[Spring] 직접 개발한 라이브러리 Fortune Cookie : API 응답에 재미 더하기

안녕하세요. 개발자 Stark입니다!

저는 개발자가 된 후 지금까지 꾸준히 나만의 오픈소스 라이브러리를 만들고자 생각해 왔습니다. 이렇게 생각만 하던 중 갑자기 이런 생각이 들었습니다. "이렇게 오픈소스 만든다는 생각만 하다가 늙어 죽을 때까지 시도도 못해보고 똥 되겠다!"

 

 

시작하며

---

위의 서론에서 이어집니다.

 

그래서 저는 바로 집에 가서 GPT를 켜고 이렇게 물어봤습니다. "내가 정말 멋진 오픈소스 프로젝트를 만들고 싶은데 어떻게 하면 될까?"

이 질문에 대한 답변을 받은 순간 이런 생각이 들었습니다. 이제 최고의 두뇌이자 선생님인 AI가 있으니 Google에서도 원할만한 최고의 개발자가 되기 위해서는 '무언가를 만들고자 하는 본인의 강한 의지와 실행력'만 있으면 되는 게 아닐까?

 

왜냐하면 gpt에게 너무 완벽하게 답변을 받았기 때문입니다. 참.. 매번 생각만 하지 말고 빨리 행동으로 옮길걸 그랬습니다. 이후에 gpt에게 제가 생각했던 아이디어를 몇 개 던져주었습니다. 그리고 비슷하거나 새로운 아이디어를 여러 개 받았는데 특히 제가 집중한 점은 아이디어가 재미를 가지고 있는지에 대해서였습니다.

 

이렇게 재미요소를 따져서 1가지의 아이디어가 정해졌습니다. 바로 "API 호출 시 Json 응답에 '포춘 쿠키'처럼 재미있는 말을 응답해 주는 것"입니다. 왜 이걸로 정했냐면 저는 백엔드 개발자로서 API 호출을 하루에도 수없이 많이 합니다. 근데 응답 json만 보다 보면 굉장히 질린다는 생각이 들 때가 있습니다. 근데 백엔드인 저도 이런 생각이 드는데 매번 응답을 받아서 적용해 주시는 front 개발자분들께서는 얼마나 노잼일까 이렇게 생각되어 저는 "게임처럼 api를 요청할 때마다 뭔가 이벤트성 응답이 있거나 특별한 아이템(선물) 같은 게 주어진다면 api를 호출하면서도 모두가 힘이 나고 협업하기도 즐겁지 않을까?"라고 생각했습니다.

 

이 생각을 반영하여 저는 fortune-cookie라는 스프링에서 사용 가능한 라이브러리를 개발하였습니다. 지금부터는 README에 열심히 적은 내용을 기반으로 라이브러리에 대해 소개드리겠습니다. Let's go!!

 

 

🥠 Fortune Cookie Library 소개

---

웹 API에 랜덤 한 "포춘 메시지"를 추가해서 사용자 경험에 재미를 더하고 싶으신가요? Fortune Cookie Library는 Spring Boot 3 이상 환경에서 간단한 설정만으로 HTTP 응답(헤더 및 JSON 바디)에 랜덤 운세 메시지를 자동으로 추가해 주는 라이브러리입니다.

 

주요 특징은 다음과 같습니다.

1. 간단한 설정: Spring Boot Auto-Configuration으로 의존성 추가 후 바로 사용 가능합니다.
2. 다국어 지원: i18n을 통해 다양한 언어의 메시지를 제공합니다.
3. 커스터마이징 옵션: URL 필터링, 상태 코드 조건부 삽입, 에러 응답 포함 여부 등을 세부적으로 조정할 수 있습니다.
4. 모드 전환 기능: 운세 외에도 농담, 명언 등 다양한 메시지 모드를 지원합니다.
5. 미니 게임: 숫자 맞히기와 같은 재미 요소를 추가할 수 있습니다.

참고사항: 이 라이브러리는 Spring Framework/Spring Boot와 공식적으로 연관된 프로젝트가 아닙니다. 독립적으로 설계 및 개발되었습니다.

 

 

🎯 왜 Fortune Cookie Library인가?

---

API의 기본적인 역할은 데이터를 전달하는 것이지만, 사용자와의 상호작용을 더 유쾌하게 만드는 것도 중요하다고 생각합니다. Fortune Cookie Library는 api 사용자 경험(UX)을 고려한 다음과 같은 장점을 제공합니다.

• 재미 요소 추가: API를 호출하는 사용자에게 신선한 경험 제공.
• 손쉬운 설정: 복잡한 코딩 없이 application.yml 설정만으로 자동화.
• 확장 가능성: 커스텀 메시지 추가 및 외부 데이터 연동 가능.
• 미니 게임 기능: 숫자 맞히기와 같은 게임 기능을 통해 사용자와 상호작용하며, 당첨 시 쿠폰 같은 보상을 제공하는 등 부가적인 가치를 창출할 수 있습니다.

 

특히 저는 미니 게임 기능을 추가한걸 신의 한 수로 생각하고 있는데요. api를 호출하는 front 개발자분들께서 이 게임에서 당첨된다면 커피쿠폰 같은 것들을 받아서 힘을 내셨으면 하는 생각을 했습니다.

 

 

🚀 설치 및 시작하기

---

1. 의존성 추가

• Fortune Cookie Library는 Maven Central에서 다운로드할 수 있습니다. (이것도 나중에 포스팅을 할까 고민 중입니다.)

아래의 링크에서 확인하실 수 있습니다.

Maven Central: io.github.wlsdks:fortune-cookie

Maven

<dependency>
    <groupId>io.github.wlsdks</groupId>
    <artifactId>fortune-cookie</artifactId>
    <version>0.3.1</version>
</dependency>

Gradle

dependencies {
    implementation 'io.github.wlsdks:fortune-cookie:0.3.1'
}

중요사항: 라이브러리 사용 시 spring-boot-starter-web 의존성을 반드시 추가해야 웹 관련 기능이 정상 작동합니다.

2. 기본 설정 (application.yml)

fortune-cookie:
  enabled: true                   # 라이브러리 활성화 여부
  include-header: true            # 헤더에 포춘 메시지 추가 여부
  header-name: X-Fortune-Cookie   # 포춘 메시지를 포함할 헤더 이름
  include-in-response: true       # JSON 바디에 메시지 추가 여부
  response-fortune-name: fortune  # JSON 응답에 포함될 필드 이름
  fortunes-count: 50              # 포춘 메시지 총 개수 (기본 50)
  debug: false                    # 디버그 모드 (true 시 상세 로그)

  # 추가된 설정들
  mode: joke                       # fortune, joke, quote 중 하나 선택 가능
  game-enabled: true               # 미니 게임 기능 활성화
  game-range: 20                   # 숫자 추측 범위를 1~20으로 설정
  placeholder-enabled: true        # 플레이스홀더 사용 여부
  placeholder-mapping:
    userName: "header:X-User-Name"
    userEmail: "header:X-User-Email"

 

 

 

✨ 주요 기능

---

1. 자동 포춘 메시지 삽입

• HTTP 응답의 헤더와 JSON 바디에 랜덤 메시지를 추가합니다. 기본 설정만으로도 모든 API 응답에 메시지가 삽입됩니다.

응답 예시

{
  "message": "Hello World!",
  "fortune": "오늘은 행운이 가득한 날입니다!"
}

헤더 예시

X-Fortune-Cookie: Today is a day full of luck!

2. 다국어(i18n) 지원

• 다양한 언어의 메시지 파일(fortunes_ko.properties, fortunes_en.properties)을 통해 다국어를 지원합니다.

3. 모드 전환 기능

• 운세 메시지 외에도 농담(joke), 명언(quote) 모드를 사용할 수 있습니다. 예를 들어:

fortune-cookie:
  mode: joke

메시지 예시

fortune.joke.1=Why don’t programmers like nature? Because it has too many bugs.
fortune.joke.2=I told my computer I needed a break, and it said: 'No problem, I’ll go on a byte!'

4. 미니 게임 기능

• 숫자 맞히기 게임을 통해 사용자와의 상호작용을 강화할 수 있습니다.

fortune-cookie:
  game-enabled: true
  game-range: 20

요청 헤더 예시

X-Guess: 7

응답 예시 (틀린 경우)

{
  "message": "Hello World!",
  "fortune": "Wrong guess! Try again!"
}

 

 

🛠️ 커스터마이징

---

1. 사용자 정의 메시지 파일

• 프로젝트의 resources 디렉토리에 메시지 파일을 추가하면 커스텀 메시지를 사용할 수 있습니다.

fortune.1=우리 회사만의 특별한 메시지1
fortune.default=기본 메시지입니다.

2. 커스텀 FortuneProvider

• 외부 데이터베이스나 API를 통해 메시지를 제공하려면 FortuneProvider를 구현하면 됩니다.

@Component
public class DatabaseFortuneProvider implements FortuneProvider {

    @Override
    public String generateFortuneKey() {
        return "fortune.123"; // DB 조회 후 키 반환
    }

    @Override
    public String getFortune(String fortuneKey, Locale locale) {
        return "DB 기반 메시지!";
    }
}

 

 

Fortune Cookie에 기여하는 법

---

Fortune Cookie Library에 기여하고 싶으신가요? 다음 절차에 따라 작업해 주시면 됩니다.

 

1. 저장소 Fork 하기

• 먼저 이 프로젝트를 자신의 GitHub 계정으로 Fork 합니다.
• Fork 한 저장소를 로컬에 클론 합니다. (아래 코드는 예시일 뿐이니 이대로 사용하시면 안 됩니다!)

git clone https://github.com/your-username/fortune-cookie.git
cd fortune-cookie

2. 새 브랜치 생성

• 작업을 시작하기 전에 브랜치를 만드세요. 브랜치 이름은 다음 규칙을 따릅니다.
  • 기능 개발: feature/기능명
  • 버그 수정: bugfix/버그명
• 브랜치 생성 명령어

git checkout -b feature/my-new-feature

3. 코드 작성 및 커밋

• 작업한 내용을 로컬에서 저장하고 커밋합니다.

git add .
git commit -m "Add new feature: 설명"

4. 브랜치 Push

• 변경 사항을 자신의 Fork 저장소로 푸시합니다.

git push origin feature/my-new-feature

5. 작업완료 후 Pull Request(PR) 생성

1. GitHub로 이동하여 본 프로젝트(Fortune Cookie Library)의 main 브랜치를 기준으로 PR을 생성합니다.
2. PR 작성 시 다음 사항을 포함하세요.
   • 변경한 내용 설명.
   • 관련된 이슈 번호(있다면).
   • 추가적인 설명이나 작업 히스토리.
     
     

6. PR 승인 및 병합

1. PR이 제출되면, 프로젝트 주인(Owner)인 제가 내용을 검토하고 승인 여부를 결정합니다.
2. PR이 승인되면, main 브랜치에 병합됩니다.

 

7. 작업 완료 후 브랜치 삭제

• PR이 병합되면, 사용이 끝난 브랜치는 삭제하세요.

git branch -d feature/my-new-feature

중요한 규칙

• 모든 작업은 반드시 새 브랜치에서 진행되어야 합니다.
• PR 없이 main 브랜치에 직접 Push 할 수 없습니다.
• PR은 주인(저)의 승인을 받은 후에만 병합됩니다.

 

 

🏁 마무리하며

---

제가 만든 Fortune Cookie Library는 간단한 설정만으로 API 응답에 재미와 상호작용을 더해주는 라이브러리입니다. 다양한 옵션과 확장성을 제공하므로 여러분의 프로젝트에 손쉽게 통합할 수 있습니다.

 

GitHub에서 이 라이브러리를 확인하시고, 사용 후기를 남겨주세요! 또는 직접 contribute를 해주셔도 됩니다. (함께 만들어가요!)

GitHub - wlsdks/fortune-cookie: "Fortune Cookie" - Spring 라이브러리로서 HTTP 응답에 랜덤한 격언이나 조언을

 

사용해 보시고 개선 아이디어나 질문이 있다면 언제든 공유해 주세요. ⭐을 잊지 말아 주세요!

긴 글 읽어주셔서 감사합니다 :)