특히 Claude, Gemini, Codex 등 AI 도구들을 연계해 작업을 구성하다 보면
여러 브랜치를 병렬로 다루고 싶거나, 모듈별로 컨텍스트를 나눠 관리하고 싶은 상황이 많아지죠.

이 글에서는 Git Worktree 개념을 정리하고,
AI 기반 워크플로에서의 활용법과 실무 전략을 함께 살펴봅니다.

1. Git Worktree란?

_{출처: blog.invidelabs.com}

Git Worktree는 하나의 Git 저장소에서 여러 작업 디렉토리(branch)를 동시에 체크아웃할 수 있게 해주는 기능입니다.

# 새 워크트리 생성 예시
git worktree add ../exp-agent feature/agent-flow

2. AI 워크플로와 Git Worktree, 왜 잘 맞을까?

AI를 활용한 개발 환경에선 종종 이런 고민이 생깁니다:

• 한쪽에서는 프롬프트 체인/모델 설정 작업,
• 다른 한쪽에서는 도메인별 테스트나 실험 브랜치 작업
  → 작업 흐름은 연결되지만, 파일과 컨텍스트는 분리하고 싶음

이럴 때 Worktree가 쓸만하죠 !

3. 실전 Worktree 적용 예시

예를 들어, 메인 에이전트가 있고, 거기서 다양한 워크플로(모델/프롬프트 흐름)를 실험하는 경우:

/my-agent-repo
├── main/               ← 기본 브랜치
├── .git/
├── worktrees/
│   ├── agent-v1-test/   ← Claude 기반 흐름 실험
│   ├── agent-v2-openai/ ← GPT 기반 흐름 분기
│   └── prompt-playground/

각 worktree 디렉토리는 Git 브랜치와 연결되며,
충돌 없이 동시에 여러 흐름을 설계하고 테스트할 수 있게 해줍니다.

4. 운영 전략 팁

• main (혹은 develop)브랜치는 공유 기준점으로 두고,
• 워크트리는 실험, 시나리오 분리, 프롬프트 구조 테스트 등에 적극 활용
• GitHub Actions나 CI 설정도 워크트리마다 조건 분기로 관리 가능

🔍 Worktree가 잘 맞는 경우

• AI Agent를 다양한 프롬프트 설계 구조로 실험 중일 때
• “Prompt A vs B” A/B 테스트처럼 모델 설정을 비교하고 싶은 경우
• Git 충돌 없이 여러 버전의 워크플로를 병렬 관리하고 싶은 경우
• 메인 브랜치 변경 없이 테스트 기반 브랜치만 따로 진행하고 싶은 경우

마무리 정리

AI 개발에서도 여전히 협업과 유지보수는 중요합니다.
Git Worktree는 프롬프트 설계, 워크플로 테스트, 모델 흐름 실험을 브랜치 단위가 아닌 디렉토리 단위로 분리하고 동시 작업할 수 있게 해줍니다.

따라서?! AI + Git 워크플로를 더 체계적으로 다루고 싶다면,
Worktree는 꼭 알아두면 좋은 Git 기능입니다.

"PR 보냈는데 This branch has conflicts 메시지가 떠요..."
"merge 하다가 CONFLICT 터졌는데 어떻게 해야 하죠?"

이건 실력 부족이 아니라, 협업이 잘 이루어지고 있다는 신호입니다.
이번 글에서는 Fork → PR → 충돌 구간에서 Git Merge Conflict를 해결하는 전 과정을 정리합니다.

1. Merge Conflict 상황 먼저 이해하기

협업 흐름 시각 설명

_{출처: Medium / Bhavya Rawal}

원본 레포 (Main Repo)
        ↑
        | PR
        |
내 포크 레포 (Fork)

• 내가 fork한 레포에서 작업하는 동안
• 다른 팀원이 main 브랜치에 코드를 먼저 머지함
• 나의 브랜치와 같은 파일의 다른 부분이 수정됨
• Git: "둘 중 어떤 코드가 맞는지 결정해줘" → Merge Conflict 발생

2. Merge Conflict란?

Merge Conflict란?

충돌 예시 구조

_{출처:Nova Kim}

내가 포크한 레포에서 작업을 하고 있는 사이,
원본 레포(main)에 다른 팀원이 코드를 먼저 반영한 경우가 많아요.

그 사이에 같은 파일의 같은 부분이 서로 다르게 수정되었다면,
Git은 "어떤 코드를 기준으로 병합해야 할지 모르겠는데;" 하며
Merge Conflict(충돌) 상태가 됩니다.

즉, 충돌은 Fork 기반 협업에서 자연스럽게 생기는 현상이에요.

3. Git 용어 정리

4. 메인 레포 최신 코드 가져오기

💡 처음 한 번만 upstream 등록

git remote add upstream https://github.com/원본유저/메인레포.git
git remote -v

💡 최신 코드 가져오기

git fetch upstream

5. 내 작업 브랜치로 이동

git switch feature/내브랜치

6. 최신 main 병합하기 → 여기서 충돌 발생

git merge upstream/main

예시 메시지:
CONFLICT (content): Merge conflict in xxx.java

정상입니다. 이제 시작입니다😎😎

7. 충돌 구간 확인 및 수정

👀 충돌난 파일에는 이렇게 표시됩니다

<<<<<<< HEAD
내 코드
=======
메인 레포 코드
>>>>>>> upstream/main

충돌 표시 의미

8. 충돌 해결 방법

앞에서 본 충돌 구간을 보고, 다음과 같은 순서로 해결하면 됩니다:

1. 내 코드, 원본 코드 중 무엇을 남길지 결정
   (또는 두 코드를 적절히 섞어서 새로운 코드로 만들 수도 있어요)
2. <<<<<<<, =======, >>>>>>> 같은 충돌 마커 기호들을 전부 삭제
3. 수정이 끝났으면 저장 후 git add ., git commit 으로 마무리

💡 팁:
Intellij, VS Cod 등 IDE에서는 충돌 지점을 시각적으로 보여주고,
버튼 클릭으로 해결할 수도 있어서 훨씬 편해요!

9. 충돌 해결 후 커밋 & 푸시

git add .
git commit
git push origin feature/내브랜치

→ GitHub PR 화면에서
“This branch has no conflicts” 메시지를 확인할 수 있습니다 🎉

10. 머지를 중단하고 싶을 때

✅ 일반 머지 중단

git merge --abort

❗ 에러: 작업 디렉토리가 깨끗하지 않을 때

방법 1️⃣ 변경사항 버리고 중단

git reset --hard HEAD
git merge --abort

방법 2️⃣ 작업 내용 살리고 중단

git stash
git merge --abort

11. ✨ 실무 꿀팁: merge vs rebase

Rebase 방식

git fetch upstream
git rebase upstream/main

충돌 났을 때:

git add .
git rebase --continue

완료 후 강제 푸시:

git push origin feature/내브랜치 --force-with-lease

🎁 실수에서 배우는 Git 강의도 있어요!

혹시 Git 충돌, 되돌리기, 협업 브랜치 전략 등
이런 문제들을 실습 중심으로 차근차근 배우고 싶다면, 제가 실무 경험을 바탕으로 만든 강의도 참고해보세요!

• 되돌리는 감각: reflog, reset, revert, 안전한 push
• 협업 루틴: 브랜치 전략, PR 체크리스트, 보호 규칙
• 실습 레포 기반 시나리오 6종으로 직접 몸으로 익히는 흐름

🎬 강의 소개 영상: https://lnkd.in/gMWTUSf3
📌 수강 링크: https://lnkd.in/gVVBhJ4g
💸 오픈 기념 할인 중입니다!

에이전트가 코드는 잘 짜줘도,
버전 관리 습관은 우리가 만들어야 우리가 편해집니다.
이번 기회에 Git과 좀 더 친해져보세요. 🙂

정신없이 MVP 만들고,
회사에 도움이 되는 제품을 빠르게 출시하다 보면 배포 환경이 이중화되지 않은 채로 운영되는 경우가 많습니다.
(저만 그런 건 아니겠죠…?)

그땐 괜찮다고 생각했어요.
“어차피 우리 아직 작은 서비스잖아. 배포 한 번 멈췄다고 누가 뭐라 하겠어?”

하지만 시간이 지나고 배포 횟수가 늘어나면서,
조금씩 “이게 괜찮지 않았던 거구나” 를 체감하게 됩니다.
테스트 브랜치가 프로덕션으로 들어가기도 하고,
잠깐의 실수가 다운타임으로 이어지기도 하죠.

그리고 어느 날, 라는 생각이 들었습니다.

그래서 이번에 production 환경과 개발 환경을 완전히 분리하고,
각 환경에서 독립적인 GitHub Actions runner를 운영하도록 구성했습니다.
이 글에서는 그 과정을 정리했습니다.

🧩 전체 아키텍처 개요

이 구조를 통해 develop 브랜치 배포는 개발 서버로, main 브랜치 배포는 프로덕션 서버로 각각 독립적으로 처리됩니다.

1. EC2 복제 (via AMI)

1-1. AMI 생성

AWS 콘솔에서 기존 프로덕션 인스턴스를 선택 후:

Actions → Image → Create Image

이미지 이름은 crm-replica-prod-ami 정도로 명명.

1-2. 새 인스턴스 실행

• 위 AMI를 기반으로 새 인스턴스를 실행
• 인스턴스 타입, 키 페어, 보안 그룹은 동일하게 설정
• Elastic IP는 새로 할당해도 되고, 기존 IP를 재연결해도 됩니다
• 태그 예시: crm-dev

✅ 기존 Elastic IP를 붙일 예정이라면, 새 EC2가 완전히 준비된 뒤 재연결해 주세요.

2. 환경 설정 (Nginx, 경로, 로그)

새 EC2가 올라왔으면 바로 접속해서 아래 항목을 수정합니다.

• Nginx 설정 (/etc/nginx/sites-enabled/crm.conf)

  • 도메인명을 dev용으로 변경
  • 포트는 그대로 유지
  • 필요 없다면 access_log, error_log 끄기 (비용 절감)

• 프론트엔드 경로 변경

  mv /var/www/frontend-prod /var/www/frontend-dev

3. GitHub Actions 워크플로 추가

개발용 배포 전용 워크플로를 새로 추가합니다.
예: .github/workflows/deploy-dev.yml

runs-on: [self-hosted, dev]  # "dev" 라벨을 가진 러너에서만 실행

테스트 커밋으로 트리거 확인:

git commit --allow-empty -m "test: trigger dev deploy"
git push origin develop

4. Self-Hosted Runner 설정 (organization-level)

복제된 EC2에는 프로덕션 러너 설정이 그대로 남아 있어서,
먼저 초기화를 해줘야 합니다.

(1) 기존 Runner 제거

sudo ./svc.sh stop
sudo ./svc.sh uninstall
./config.sh remove

새 토큰은 아래에서 발급받을 수 있습니다:
GitHub → Organization → Settings → Actions → Runners → New self-hosted runner → Linux

(2) 폴더 초기화 (선택)

cd ~
rm -rf actions-runner
mkdir actions-runner && cd actions-runner

(3) Runner 재등록

repository-level이 아닌 organization-level로 등록합니다.

./config.sh --url https://github.com/Allies-Tax-Relief --token <TOKEN>

등록 과정 예시:

? Name: ec2-dev-runner
? Labels: self-hosted, dev
? Work folder: [Enter]

⚠️ repo URL로 등록하면 GitHub API가 거절해요!

(4) 서비스 등록 (systemd)

SSH 종료 후에도 러너가 계속 살아 있도록 설정합니다.

sudo ./svc.sh install
sudo ./svc.sh start
sudo ./svc.sh status

✅ active (running) 이면 정상 작동 중입니다.

나중에 중지/삭제할 때는:

sudo ./svc.sh stop
sudo ./svc.sh uninstall

5. Runner 등록 확인

이제 GitHub에서 runner가 정상적으로 등록됐는지 확인해봅니다.

GitHub → Organization → Settings → Actions → Runners

아래처럼 두 개의 runner가 보이면 성공 👇

두 runner 모두 “Shared with this repository” 상태여야 합니다.
상태가 idle로 표시되면 runner가 정상적으로 대기 중인 것입니다.(Offline이면 무언가 잘못된 것,,⭐️)

6. 배포 테스트

이제 develop 브랜치에 커밋을 하나 푸시하면
dev 러너가 잡아서 배포를 실행합니다.

√ Connected to GitHub
Current runner version: '2.329.0'
2025-11-03 08:19:19Z: Listening for Jobs
2025-11-03 08:22:41Z: Running job: Deploy (EC2 self-hosted runner)
2025-11-03 08:22:50Z: Job Deploy (EC2 self-hosted runner) completed with result: Succeeded

깔끔하게 “Succeeded” 뜨면 완성 🎉

7. 구조 요약 다이어그램

💡 실무 팁

• organization-level runner를 사용하세요.
• ./run.sh는 수동 테스트용으로만 쓰세요.
  딸깍 배포 실행을 원하신다면 반드시 svc.sh start로 관리해야 합니다.
• 러너 로그 확인:

  journalctl -u actions.runner.*

🧭 마무리

드디어 기다리던 배포환경 분리가 되었어요. 저는 사실 아직 하는 중이긴 해요 세상의 모든 개발자 화이팅,,💪🏻💪🏻

백엔드 시스템에서 각종 작업(Job), 메시지, 트랜잭션 등을 식별하기 위한 고유 ID 생성은 굉장히 기본적인 기능이지만, 동시에 많은 문제가 숨어 있는 지점이기도 합니다. 특히 부하가 큰 상황에서는 "시간 기반 ID" 하나만으로는 유니크함을 보장하기 어렵지요.

이번 글에서는 실제 서비스 배포 이전 새로운 기능 구현에서 jobId를 밀리초 타임스탬프 기반으로 만들었다가 Cursor AI의 버그 봇한테 혼나고(!) 이를 계기로 더 안전한 방식으로 고친 이야기를 풀어보려 합니다. 실무에서도 유사한 이슈는 충분히 발생할 수 있으니, 참고가 되셨으면 좋겠습니다.

1. 문제 상황 : jobId가 중복되는 이유

저같은 경우에는, 스케줄링 시스템에서 메시지 배치 작업의 식별을 위해 jobId를 다음과 같이 생성하고 있었습니다:

const jobId = DateTime.utc().toMillis();

UTC 기준 밀리초 단위의 타임스탬프를 사용하는 이 방식은 겉보기에 유니크한 값을 보장할 것처럼 보입니다. 그러나 동일한 밀리초 내에 여러 요청이 들어오는 경우, 똑같은 jobId가 생성되는 심각한 문제가 발생할 수 있습니다.

실제 문제 사례 (거의 발생할 뻔한 문제)

풀리퀘를 열고 Cursor Bug Bot으로 코드 리뷰를 받았는데, (아니 마침 코드래빗 프리티어 끝난 시점에 이녀석들이 시용기간을 주지 뭡니까?! 개꿀)

바로 이 부분이 지적됐습니다:

"타임스탬프 기반 ID는 충돌 가능성이 있어요. 부하가 큰 상황에선 동일한 밀리초 안에 여러 job이 생성될 수 있습니다."

처음엔 "그렇게까지 동시 요청이 많을까...?" 싶었지만, 정말 중요한 포인트를 짚어준 리뷰였기에, 더 안전한 방식으로 바꾸기로 했습니다.

2. 흔히 저지르는 실수: 왜 타임스탬프만 썼을까?

단순한 타임스탬프 기반 ID 생성 방식은 다음과 같은 장점 때문에 널리 사용됩니다:

• 구현이 간단하고,
• 시간 순서에 따라 정렬이 가능하며,
• 외부 라이브러리 없이 숫자형 ID를 쉽게 만들 수 있기 때문이죠.

그치만 이 방식의 근본적인 한계는 다음과 같습니다:

• 단일 서버 또는 싱글스레드 상황에서는 괜찮지만,
• 부하가 큰, 혹은 멀티스레드 환경에서는 동시성 문제가 발생하기 쉽습니다.

3. 해결 방법 : 진짜 유니크한 jobId 만들기

이 문제를 해결하기 위해 timestamp + counter + random 조합 방식을 도입했습니다.

개선된 코드 예시

private static jobIdCounter = 0;

private generateUniqueJobId(): number {
  const timestamp = DateTime.utc().toMillis();
  SchedulingService.jobIdCounter = (SchedulingService.jobIdCounter + 1) % 1000;
  const randomComponent = Math.floor(Math.random() * 1000);
  return timestamp * 1000000 + SchedulingService.jobIdCounter * 1000 + randomComponent;
}

개선 포인트 요약

4. 다른 ID 생성 방식과 비교

5. 이렇게 하면 이런 장점이 있답니다?

• 충돌 없음 : 동일 밀리초에도 counter와 random이 보완
• 정렬 가능 : 시간순 정렬 유지
• 숫자 포맷 유지 : 기존 시스템과 호환성 유지
• 부하가 클 때 대응 가능 : 1ms 내 최대 1,000건까지 안전 처리 가능

예시 Job ID

• 1672531200000000123456 → (timestamp: 1672531200000, counter: 123, random: 456)
• 1672531200000001234567 → 같은 timestamp라도 counter와 random 값으로 구분

6. (잠깐만) 그런데 JavaScript에서 이 방식 써도 괜찮은 걸까?

Cursor 리뷰를 반영해서 개선한 이 방식, 얼핏 보면 완벽해 보입니다. (저도 그런 줄 알았는데 말이죠?) 그런데 한 가지 치명적인 문제가 더 있었으니...

바로 JavaScript의 (그리고 TypeScript의 number 타입의) Number.MAX_SAFE_INTEGER 한계 초과 이슈입니다.

현재 방식은 timestamp * 1_000_000 계산을 기반으로 합니다. 그런데 이때 timestamp는 보통 1.7e12 수준 (밀리초)이기 때문에, 전체 값은 1.7e18 근처가 됩니다. 문제는 이게 JS의 안전한 정수 표현 범위(~9e15)를 야무지게 넘는다는 점입니다.

🤯 왜 이게 문제일까요?

• TypeScript의 number는 JavaScript와 동일한 Number 타입을 따릅니다. 이 타입은 정밀도를 보장할 수 있는 최대 정수가 약 9조(2^53 - 1)까지예요.
• 이 범위를 넘는 숫자는 계산이나 비교, 정렬 등의 연산에서 정밀도가 깨지거나 이상한 결과를 만들 수 있습니다.
• 즉, jobId가 유일하더라도 정렬이 깨지거나, 숫자끼리 비교 시 서로 다른 값인데도 같다고 인식될 수도 있는 거죠.

해결책: 밀리초 → 초 단위로 바꾸자!💡

다행히도 해결책은 단순합니다:

const timestamp = Math.floor(DateTime.utc().toSeconds());

즉, 초 단위로 timestamp를 줄이면:

• timestamp ≈ 1.7e9
• 최종 jobId ≈ 1.7e15 수준 → Number.MAX_SAFE_INTEGER 이내!

나머지 구조(counter, random)는 그대로 유지할 수 있어 안정성 + 정렬성 + 유니크함까지 모두 잡을 수 있습니다.

7. 결론 : 절대 (과거의 저처럼ㅎ) 타임스탬프에만 의존하지 마세요

밀리초 단위의 타임스탬프만으로 유니크 ID를 생성하는 것은 부하가 큰 시스템에서 너무 위험해버리는 전략입니다.

복합 요소를 조합하고, 정수 범위도 체크하는 신중한 ID 설계가 더더욱 필요합니다. (그리고 가능하다면... Cursor bugbot 리뷰 한 번 받아보는 것도 추천드려요 😎)

⚠️ 이 글은 Twilio 공식 문서 Best Practices for Scaling with Messaging Services 를 번역한 내용입니다.

Twilio 메시징 서비스를 본격적으로 확장할 준비가 되셨나요? 확장을 고려할 때에는 몇 가지 핵심 질문과 함께, 구축 방식과 설정에 있어 꼭 알아두셔야 할 팁들이 있습니다. 이 가이드는 대표적인 메시징 사용 사례와 국가별 특수 상황을 정리해두었으며, Twilio와 함께 메시징을 운영하면서 놓치기 쉬운 부분을 미리 방지할 수 있도록 돕습니다.

1. 메시지를 보낼 땐 메시징 서비스를 활용하세요

PoC(Proof of Concept) 단계에서는 단일 전화번호(롱코드)를 통해 메시지를 보내는 방식으로도 충분할 수 있습니다. 하지만 서비스가 성장함에 따라 숏코드, 알파벳 발신 ID, WhatsApp 발신 번호 등 다양한 유형의 발신자를 고려해야 할 수 있습니다. 또한 Advanced Opt-Out 같은 기능을 활용하여 수신자 동의/거부 관리를 자동화하거나, Smart Encoding으로 유니코드 문자로 인한 세그먼트 초과를 방지하는 기능도 중요해집니다.

메시징 서비스는 발신자 ID를 묶고 메시지 전송 설정을 통합적으로 관리할 수 있는 컨테이너 역할을 합니다. 예를 들어, 하나의 메시징 서비스에 숏코드와 지역 번호들을 등록하고, 동일한 Webhook으로 연결하여 수신 메시지에 응답하거나, 국가별 수신 거부(Stop) 키워드를 통일적으로 설정하는 것이 가능합니다.

메시지를 전송할 때는 From 필드 대신 messagingServiceSid를 사용하여 메시징 서비스를 통해 전송할 수 있습니다. 이 방식은 자동 라우팅 및 다양한 Twilio 메시징 기능들을 함께 사용할 수 있도록 해줍니다.

2. 어떤 발신자가 적절할지 결정해보세요

✔️ 1) 단방향 메시지인가요? 아니면 양방향 메시지인가요?

• 사용자가 메시지에 답장할 수 있는 구조라면 **양방향 메시지(two-way messaging)**입니다.
• WhatsApp은 기본적으로 양방향을 지원하지만, SMS는 발신 번호 유형에 따라 양방향 여부가 달라질 수 있습니다.
• 단방향만 필요하다면 선택할 수 있는 번호 유형의 폭은 넓어지지만, 국가별 규정을 함께 고려해야 합니다.

✔️ 2) 어느 국가로 메시지를 보내시나요?

• 각 국가마다 메시징 관련 규제가 다르므로, Twilio에서 제공하는 국가별 가이드라인을 꼭 확인하셔야 합니다.

미국/캐나다:

• 사용 가능한 발신 번호 유형: 10DLC 롱코드, 숏코드, Toll-Free 번호, WhatsApp
• 캐나다는 롱코드를 통한 A2P 메시징을 금지하고 있으므로 Toll-Free 또는 숏코드를 사용해야 합니다.

그 외 국가:

• 사용 가능한 발신 번호 유형: 알파벳 발신 ID, 롱코드, 숏코드, Toll-Free, WhatsApp
• 일부 국가에서는 인바운드 응답을 받기 위해 반드시 현지 번호 사용이 요구될 수 있습니다.

✔️ 3) 어떤 종류의 메시지를 보내시나요?

단방향 메시지:

• 마케팅, 배송 알림, 정보성 메시지 등
• 예: 프랑스에서는 P2P가 아닌 A2P 트래픽에 대해 지역 롱코드를 금지하고 있으므로, 알파벳 발신 ID나 숏코드만 사용할 수 있습니다.

양방향 메시지:

• 챗봇, 리마인더, 고객 대화 등
• 인바운드 수신이 가능한 번호 유형(예: 현지 롱코드, 숏코드, WhatsApp)을 사용해야 합니다.

3. 메시징 처리량(MPS)을 계산해보세요

• MPS는 초당 메시지 세그먼트(Message Segments Per Second)로 측정되며, 발신자 유형과 국가에 따라 다릅니다.

미국 기준:

• 롱코드: A2P 등록 결과에 따라 MPS가 달라짐
• Toll-Free: 기본 3 MPS (증설 요청 가능)
• 숏코드: 기본 100 MPS 이상

기타 국가:

• 알파벳 ID 및 롱코드: 기본 10 MPS

Twilio는 메시지를 수신한 순서대로 큐에 넣어 전송하므로, API 요청은 빠르게 보내더라도 실제 발송은 MPS에 맞춰 이루어집니다. 안정성을 위해 메시징 서비스를 통해 큐 관리를 맡기는 것이 권장됩니다.

4. 높은 처리량이 필요하다면 숏코드 또는 Toll-Free 번호를 고려하세요

• 롱코드를 여러 개 추가해서 처리량을 분산시키는 "스노우슈잉(snowshoeing)" 방식은 필터링 위험이 커지므로 비권장됩니다.
• Twilio는 미국, 캐나다, 브라질 등 14개국에서 숏코드를 제공합니다. 숏코드는 사전 심사된 번호이기 때문에 필터링 위험이 낮고 고속 처리에 적합합니다.
• 한 국가에만 적용되는 것이기 때문에 국제 발송이 필요하다면 알파벳 발신 ID 또는 Toll-Free를 함께 고려해야 합니다.

알파벳 발신 ID는 Sender Pool 내 다른 번호보다 우선 적용되며, 메시지가 큐에 있어도 대체 발신으로 넘어가지 않습니다. MPS 증설이 필요한 경우 Twilio에 요청할 수 있습니다.

마무리하며

Twilio Programmable Messaging을 통해 확장을 고려하고 있다면, 우선 메시징 서비스를 활용하여 구성하는 것을 강력히 권장합니다. 이렇게 하면 하나의 Sender Pool 내에서 다양한 번호와 기능을 통합 관리하면서 글로벌 메시징 확장에도 유연하게 대응할 수 있습니다.

처음부터 다음 사항을 명확히 해두시면 확장 시 큰 도움이 됩니다:

• 메시지를 보낼 국가
• 메시지 내용 유형 (마케팅/정보성/인증 등)
• 응답이 필요한지 여부 (양방향 메시징)
• 처리량 요구 사항

▶⃣ 함께 읽으면 좋은 자료:

• Twilio Messaging Services 개요
• 국가별 SMS 가이드라인
• Rate Limit 및 Message Queue 이해하기
• 통신사 필터링은 어떻게 작동할까요?

원문 링크: Customize Users’ Opt-in and Opt-out Experience

✨ Advanced Opt-Out란?

Advanced Opt-Out 기능을 사용하면, 고객이 SMS 수신을 동의하거나 거부하는 키워드와 응답 메시지를 전 세계 언어와 국가별로 맞춤 설정할 수 있습니다. 이 기능은 Messaging Service에 포함된 발신번호 전체에 적용됩니다.

✅ 기본 제공되는 키워드

Twilio는 다음의 기본 키워드를 인식합니다:

• 수신 거부 (Opt-Out): STOP, UNSUBSCRIBE, END, QUIT, STOPALL, CANCEL
• 수신 동의 (Opt-In): START, UNSTOP
• 도움말 (Help): HELP

2025년 4월 29일부터는 REVOKE, OPTOUT도 기본 Opt-Out 키워드로 포함됩니다.

🛠 설정 순서

1. Messaging Service 생성

const service = await client.messaging.v1.services.create({
  friendlyName: "My First Messaging Service",
});

2. SMS 발신 가능한 번호 구매 및 연결

• Twilio Console에서 구매
• 번호의 SID (PNxxx)를 Messaging Service에 연결

await client.messaging.v1.services("MGxxx").phoneNumbers.create({
  phoneNumberSid: "PNxxx"
});

3. Advanced Opt-Out 활성화

• Twilio Console > Messaging > Services > Opt-Out Management 섹션
• "Enable Advanced Opt-Out" 클릭

⚠ 활성화 이후 비활성화는 Support 요청 필요

🔤 키워드 커스터마이징 방식

▪ 표준 키워드(Standard Keywords)

• 모든 국가에 공통 적용되는 키워드와 응답 메시지

▪ 언어별 키워드(Language-specific)

• 예: 스페인어 사용자에게는 SALIR 입력 시 스페인어 응답 전송

▪ 국가 코드별 키워드(Country-specific)

• 특정 국가 번호(예: +82)에만 다른 키워드와 메시지 지정
• 언어별 중복 키워드는 허용되지 않음

📌 Toll-Free 번호 주의사항

• Toll-Free 번호는 항상 STOP으로 수신 거부 처리됨 (커스텀 메시지 무시)
• START 또는 UNSTOP으로만 차단 해제 가능

🧾 사용자 상태 추적하기

• 사용자 메시지가 키워드와 일치하면 Twilio는 webhook으로 OptOutType 포함하여 알림
• OptOutType 값: START, STOP, HELP
• Twilio가 이미 응답했기 때문에, 별도 메시지를 다시 보내는 것은 권장되지 않음

📚 다음 단계

• Messaging Service Overview
• How to send messages with Messaging Services

원본 문서: Traffic Shaping | Twilio Docs

🌍 개요

Traffic Shaping은 Twilio의 Programmable Messaging 제품 중 하나로, 대량 메시징 환경에서 메시지의 우선순위에 따라 처리 속도(MPS)를 조절할 수 있게 해주는 기능입니다. 주로 OTP(일회용 비밀번호), 보안 알림, 계정 알림처럼 시간에 민감한 메시지를 다른 마케팅 메시지보다 빠르게 보내고자 할 때 유용합니다.

🚫 미국 및 캐나다의 A2P 10DLC 메시지는 지원되지 않습니다.

⚙️ 서비스 레벨 (Service Levels)

Traffic Shaping은 총 **3개의 Service Level(우선순위 큐)**을 제공합니다.

원한다면 Level 1과 Level 3만 사용하는 것도 가능합니다.

📨 메시지에 서비스 레벨 지정하기

메시지를 보낼 때 MessageIntent 파라미터를 설정하여 어느 Service Level에 들어갈지 지정할 수 있습니다. 지정하지 않으면 기본값인 Level 3으로 처리됩니다.

✅ 예시 (curl 명령어)

curl -X POST "https://api.twilio.com/2010-04-01/Accounts/$TWILIO_ACCOUNT_SID/Messages.json" \
--data-urlencode "From=+15557122661" \
--data-urlencode "Body=Your one-time passcode is: 8458881" \
--data-urlencode "To=+15558675310" \
--data-urlencode "MessageIntent=otp" \
-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

♻️ 동적 처리량 재분배

어떤 Service Level 큐에 메시지가 없으면, 그 큐에 할당된 처리량(MPS)은 다른 큐로 자동 재분배됩니다. 즉, 전체 계정 처리량은 100% 다 활용됩니다.

🎯 장점

• 메시지 우선순위에 따라 처리량(MPS)을 유연하게 분배 가능
• 하나의 번호에서 여러 우선순위 메시지를 보낼 경우에도 큐 간 간섭 없이 독립적으로 처리
• Multi-Tenancy와 동시에 사용 가능 (서브 계정 간 처리량 분배 + 메시지 레벨 처리 분배)

⚠️ 제약 사항

• 미국/캐나다의 A2P 10DLC 메시지에는 적용되지 않음
• 메시지 우선순위 설정을 위해 MessageIntent 파라미터 필수 사용

🚀 시작하기 (Onboarding 절차)

1. Twilio 지원팀에 연락 → Traffic Shaping 데모/적용 요청
2. 트래픽 예측 및 서비스 구성 협의
3. 설정 리뷰 및 승인
4. 비혼잡 시간대에 설정 반영 및 트래픽 마이그레이션

🔚 마무리

Traffic Shaping을 사용하면 대량 메시지 처리 중에도 긴급한 메시지를 빠르게 보낼 수 있고, 전체 처리 효율도 높일 수 있습니다. 특히 OTP나 보안 경고처럼 시간 민감한 메시지에 최적화된 설계로, 기존의 Market Throughput보다 훨씬 정밀한 제어가 가능합니다.

Twilio에서 제공 중인 Public Beta 기능입니다. 요금 및 사용 관련 자세한 내용은 Twilio 계정 매니저나 고객지원팀에 문의하세요.

원문 링크: Twilio Docs - Bulk Upsert Consents

📢 소개

Bulk Upsert Consents API는 여러 연락처의 동의 상태를 한 번에 등록하거나 갱신할 수 있는 기능입니다. 현재는 SMS 채널만 지원하며, Pilot 단계에 있습니다. 즉, Twilio는 현재 초기 사용자들의 피드백을 받고 있으며, 이 기능을 미리 사용해보고 의견을 줄 수 있는 기회가 있다는 뜻입니다.

⚠️ 주의: 이 API는 HIPAA 인증 서비스가 아닙니다. 의료 정보를 다루는 시스템에서는 사용하지 마세요.

✅ 기능 개요

• 최대 25개의 consents 객체를 한 요청으로 생성하거나 업데이트 가능
• 각 요청은 고유한 correlation_id로 구분되어, 개별 응답 확인 가능
• 실패한 요청은 개별 correlation_id에 에러 메시지와 함께 응답됨

🔐 제한 사항

🔄 요청 포맷

POST https://accounts.twilio.com/v1/Consents/Bulk

Content-Type: application/x-www-form-urlencoded

요청 파라미터

• items (필수): 연락처의 동의 정보를 담은 객체 배열

  • contact_id: E.164 포맷의 전화번호 (예: +19999999991)
  • correlation_id: 32자리 UUID 문자열
  • sender_id: 메시징 서비스 SID 또는 전화번호
  • status: opt-in 또는 opt-out
  • source: website, offline, opt-in-message, opt-out-message, others
  • date_of_consent: ISO 8601 날짜 문자열 (선택)

예시 (Node.js)

const twilio = require("twilio");
const accountSid = process.env.TWILIO_ACCOUNT_SID;
const authToken = process.env.TWILIO_AUTH_TOKEN;
const client = twilio(accountSid, authToken);

async function createBulkConsents() {
  const bulkConsent = await client.accounts.v1.bulkConsents.create({
    items: [
      {
        contact_id: "+19999999991",
        correlation_id: "ad388b5a46b33b874b0d41f7226db2ef",
        sender_id: "MG00000000000000000000000000000000",
        date_of_consent: "2025-02-28T10:05:27Z",
        status: "opt-in",
        source: "website",
      },
      {
        contact_id: "+19",
        correlation_id: "02520cfa6c432f0e3ec3a38c122d428d",
        sender_id: "12345",
        date_of_consent: "2025-02-25T10:05:27Z",
        status: "opt-out",
        source: "opt-out-message",
      },
    ],
  });

  console.log(bulkConsent.items);
}

createBulkConsents();

📥 응답 구조

{
  "items": [
    {
      "correlation_id": "ad388b5a46b33b874b0d41f7226db2ef",
      "error_code": 0,
      "error_messages": []
    },
    {
      "correlation_id": "02520cfa6c432f0e3ec3a38c122d428d",
      "error_code": 30646,
      "error_messages": [
        "INVALID_CONTACT_ID"
      ]
    }
  ]
}

• error_code: 0이면 성공, 그 외에는 실패 코드
• error_messages: 유효성 검사 실패 시 메시지 포함

🧾 참고: 주요 에러 코드

• 30646: 잘못된 contact_id, 누락된 필드 등 유효성 검사 실패

🔗 원본 문서: Build to scale: queueing and latency on Twilio

🧨 시나리오: 블랙 프라이데이 대란 대비하기

11시에 1000개의 상품이 할인 오픈! 이 소식을 오전 10시에 100만 명에게 한꺼번에 문자로 알려야 한다면?

• 10시: 프로모션 문자 (링크 포함)
• 로그인/회원가입 후: OTP 문자 인증

이렇게 두 종류의 메시지가 필요하다면, 각 유스케이스마다 별도의 메시징 서비스(Messaging Service) 를 설정해야 해요.

📦 메시징 서비스(Messaging Service)란?

메시징 서비스는 여러 발신번호(발신자 풀) 와 설정값을 하나의 목적에 맞게 묶은 단위예요. 이를 사용하면:

• 발신자 관리 자동화
• Opt-Out 처리
• 다국가 대응 설정

등을 손쉽게 할 수 있어요.

⚠️ 단, 여러 번호를 동시에 사용하는 건 지역 규제에 따라 제한될 수 있어요. 특히 미국에서는 "스노우슈잉(snowshoeing)"으로 간주될 수 있으니 Twilio 정책 확인 필수!

💡 메시지 발송 흐름 (요청 → 발송)

1. 메시징 서비스로 API 요청 전송
2. 서비스가 큐에 저장하고 적절한 발신자 선택
3. 통신사(Carrier)로 전달
4. 최종 수신자에게 도착

✅ 유스케이스에 맞게 설계하기

📈 큐 사이즈와 MPS 계산법

• 기본 큐 가능 시간: 10시간 (36,000초)
• MPS (Messages Per Second) = 메시지 수 ÷ 큐 시간
• Twilio 권장: 안전하게 2배 버퍼 적용

예시 계산

프로모션

• 1M ÷ 36,000초 = 27.7 → 버퍼 적용 시 60 MPS 필요

OTP

• 20,000 ÷ 180초 = 111 → 버퍼 적용 시 220 MPS 필요

🛠 메시징 서비스 생성 예시 (OTP용)

const service = await client.messaging.v1.services.create({
  friendlyName: "My OTP Messaging Service",
  validityPeriod: 120
});

🔢 발신자(Pool) 구성 예시

프로모션용

OTP용

⏱ 캠페인 타이밍 전략

• 프로모션 메시지: 오전 중 미리 큐에 올려두기
• OTP: 사용자 행동 발생 시 실시간 발송

const message = await client.messages.create({
  body: "세일 1시간 전! 로그인하세요!",
  messagingServiceSid: "MGxxx",
  to: "+821012345678"
});

📊 성능 모니터링: Messaging Insights

• Latency Report: 메시지가 Twilio에서 처리되는 시간
• Delivery & Errors Report: 전송 성공률, 실패 원인 파악
• 각 발신자/서비스/계정 단위로 확인 가능

⚠️ 오류 예시: Queue Overflow, 30001 등 → 백오프 + 재시도 로직 필요

🚨 긴급 상황 대응

대규모 장애나 공지 필요 시, 기존 한도 초과될 수 있어요. 이럴 땐 Twilio 지원팀에 한도 상향 요청할 수 있어요.

📎 참고 리소스

• Messaging Insights 사용법
• Messaging Service 기능 전체 보기
• Messaging Service 생성 가이드

본 문서는 Twilio 공식 문서(원문 링크)를 기반으로 자연스럽고 실무에 맞게 번역한 자료입니다.

Twilio Messaging Services로 메시지 보내기

Messaging Service를 사용하면 고객에게 더 나은 SMS 또는 WhatsApp 경험을 제공할 수 있어요. Twilio Console을 통해 발신 번호를 지역화하거나, 여러 발신자에 걸쳐 메시지를 분산하고, 고객과 고정된 번호로 소통할 수도 있죠. 이 가이드는 Messaging Service의 기능과 실제 메시지 전송 방법을 소개합니다.

✅ Messaging Service를 왜 써야 할까?

고객에게 전 세계적으로 많은 메시지를 보내는 상황이라면 복잡도가 확 올라갑니다. Twilio는 이런 복잡도를 줄이기 위해 Messaging Service라는 개념을 도입했어요. 발신자 관리, 규제 준수, 사용자 경험 일관성까지 모두 커버할 수 있죠.

주요 기능은 다음과 같아요:

• Sticky Sender: 동일한 고객에게 항상 같은 발신 번호 사용
• Smart Encoding: Unicode 문자 자동 변환으로 메시지 분할 방지 (비용 절감!)
• MMS Converter: MMS 미지원 국가에 링크 형태로 변환 발송
• Advanced Opt-Out: 고객의 수신 거부 키워드 설정 및 응답 메시지 지정
• Sender ID 사전 등록 알림: 사전 등록이 필요한 국가에서 메시지 발송 시 알림

👉 더 많은 기능은 Messaging Service Overview 문서 참고!

🏗️ Messaging Service 생성 & 구성하기

1. 서비스 생성

const twilio = require("twilio");
const accountSid = process.env.TWILIO_ACCOUNT_SID;
const authToken = process.env.TWILIO_AUTH_TOKEN;
const client = twilio(accountSid, authToken);

async function createService() {
  const service = await client.messaging.v1.services.create({
    friendlyName: "My First Messaging Service",
  });
  console.log(service.sid);
}

createService();

서비스 SID(MG로 시작하는 값)를 꼭 기억하세요. 이걸로 나중에 메시지 전송합니다!

2. SMS 가능한 번호 구매

Twilio Console > Phone Numbers 메뉴에서 SMS 전송이 가능한 번호를 구매하세요. Trial 계정의 경우 미국에 보내려면 Toll-Free 번호가 필요합니다.

3. Sender Pool에 번호 추가

const phoneNumber = await client.messaging.v1
  .services("MGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX")
  .phoneNumbers.create({
    phoneNumberSid: "PNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  });

Sender Pool에 번호를 등록해야 메시지 전송이 가능해요!

📤 Messaging Service로 메시지 전송하기

const message = await client.messages.create({
  body: "Hello from your Messaging Service!",
  messagingServiceSid: "MG9752274e9e519418a7406176694466fa",
  to: "+15553332222",
});

발신 번호 대신 messagingServiceSid만 넣으면 Twilio가 자동으로 적절한 번호를 골라줘요.

🔎 메시지 상태와 로그 확인

• Twilio Console의 Messaging Insights 및 로그 메뉴에서 상태 확인 가능
• 메시지가 실패한 경우 status = failed로 표시되며 오류 코드 확인 가능

※ MessagingServiceSid를 명시하지 않으면 Service 정보가 로그에 남지 않으니 주의!

📈 다음 단계로!

이제 메시지 하나 보내봤다면, 그 다음은?

• Advanced Opt-Out 설정하기
• WhatsApp 연동 시작하기
• Messaging Service REST API 살펴보기

👉 시리즈 전체 보러가기: Twilio Messaging 가이드 시리즈

📄 원문 링크: Twilio Multi-Tenancy (Public Beta)

Twilio의 Multi-Tenancy는 현재 퍼블릭 베타(Public Beta)로 제공 중인 기능으로, Traffic Optimization Engine의 하위 기능입니다. 이 기능을 통해 메시지 처리량을 세부적으로 제어하고, 여러 서브 계정(Subaccount) 간에 트래픽 용량을 공정하게 분배할 수 있습니다.

🧩 Multi-Tenancy란?

Multi-Tenancy를 사용하면 어떤 서브 계정이나 발신자가 전체 트래픽 처리량(throughput)을 독점하는 것을 방지하고, 계층 구조 내에서 다른 계정들도 충분한 처리량을 보장받을 수 있도록 합니다.

Twilio가 서브 계정 간 트래픽을 자동으로 분배하여 수동으로 처리량 설정을 하지 않아도 되며, 각 국가 및 채널(예: SMS, MMS)의 설정에 맞춰 알고리즘적으로 공정하게 처리량이 할당됩니다.

❗ A2P 10DLC(미국/캐나다) 트래픽에는 적용되지 않습니다.

⚙️ 동작 방식

1. 필요할 때 각 서브 계정에 최소 처리량을 자동 할당합니다.
2. 메시지 처리가 끝나면, 사용된 처리량은 다시 큐에 있는 다른 서브 계정에 재분배됩니다.

🔧 구성 옵션 (국가별 적용)

1. None (미적용)

• 서브 계정별 보장 처리량 없음
• 메시지는 하나의 큐에 들어가며, 부모 계정의 최대 처리량만큼 순차적으로 전송됨

2. Even (균등 분배)

• 모든 서브 계정에 동일한 처리량 할당
• 예: 총 100 MPS → 서브 계정 3개 → 각 33.33 MPS
• 어느 한 큐가 비어 있으면 나머지 큐에 그 처리량이 자동 공유됨

3. Weighted (가중치 분배)

• 특정 서브 계정에 더 높은 처리량 할당 가능
• 예: 서브 계정 3번에 80%, 나머지 2개에 10%씩 분배
• 비어 있는 큐의 처리량은 동일한 Tier 내에서만 공유됨

🚀 시작하기

• 현재 모든 Programmable Messaging 고객에게 Public Beta로 제공됨
• 사용을 원하면 계정 소유자 또는 Twilio Support에 문의

✅ 사전 준비사항

Multi-Tenancy를 활성화하려면, Market Throughput 기능이 계정에 먼저 적용되어 있어야 합니다.

Market Throughput 가이드 보기

🛠️ 온보딩 단계

1. 요청 접수: Twilio 계정 소유자 또는 Support 팀에 데모 또는 적용 요청
2. 처리량 예측/설정: 어떤 국가/채널에 어떤 옵션을 적용할지 결정
3. 리뷰: Twilio가 설정 요청 검토
4. 적용 및 마이그레이션: 설정 적용 및 오프피크 시간에 트래픽 이관

기존 Twilio 연동에는 별도의 변경이 필요하지 않습니다.

🧠 정리

필요에 따라 처리량을 효율적으로 제어하고 싶은 경우, Multi-Tenancy는 훌륭한 선택이 될 수 있어요. 특히 여러 서비스나 브랜드를 하나의 Twilio 계정으로 운영하는 환경에서 유용합니다.

📌 다음 포스트에서는 Market Throughput이나 Traffic Shaping에 대해 다뤄볼게요. 궁금한 거 있음 댓글이나 DM 주세요!

📎 본 글은 Twilio 공식 문서 - Messaging Services를 참고해 작성된 한글 번역 및 해설입니다.

Messaging Services란?

미국이든 전 세계든, 대량의 메시지를 보내기 시작하면 시스템은 금방 복잡해지죠. 이때 Twilio의 Messaging Services 기능을 이용하면 발신 번호 관리, 메시지 로그, 기능 설정 등을 깔끔하게 구성할 수 있어요.

Messaging Service는 일종의 메시지 발신자(번호) 그룹을 만들고, 이 그룹에 공통된 기능이나 설정을 적용할 수 있도록 도와주는 상위 개념이에요. 예를 들어 여러 개의 전화번호, 숏코드(short code), 톨프리 번호를 하나의 서비스에 묶고, 해당 서비스 단위로 기능을 설정하는 식이죠.

메시지 전송: Messaging Service를 통해 보내기

Twilio REST API를 이용해 메시지를 보낼 때, from에 직접 전화번호를 넣는 대신 MessagingServiceSid를 넣으면 Twilio가 해당 서비스에 연결된 발신 번호 중 적절한 번호를 골라 메시지를 보내줍니다.

const twilio = require("twilio");

const accountSid = process.env.TWILIO_ACCOUNT_SID;
const authToken = process.env.TWILIO_AUTH_TOKEN;
const client = twilio(accountSid, authToken);

async function createMessage() {
  const message = await client.messages.create({
    body: "Revenge of the Sith was clearly the best of the prequel trilogy.",
    messagingServiceSid: "MG9752274e9e519418a7406176694466fa",
    to: "+441632960675",
  });
  console.log(message.body);
}

createMessage();

이렇게 하면 Twilio가 자동으로 최적의 발신 번호를 선택해서 메시지를 보내요.

상태 콜백 (Status Callback URL)

메시지 전송 성공 여부나 에러 등은 Twilio가 비동기적으로 전달해줘요. 이때 콜백 받을 URL은 콘솔에서 설정할 수 있고, API로도 지정 가능해요.

Console 경로: Messaging Services > Integration > Delivery Status Callback

WhatsApp, RCS 발신 번호도 추가 가능해요!

Twilio에서 발급받은 WhatsApp 번호나 RCS Sender도 Messaging Service에 추가해서 사용할 수 있어요. 덕분에 WhatsApp 메시지도 동일한 설정과 기능으로 통합 관리할 수 있죠.

예를 들어 SMS, WhatsApp, Toll-free 번호가 모두 하나의 서비스에 묶이면, 발신자 선택 로직이나 유효기간 설정 등이 한 번에 적용됩니다.

Messaging Service의 기본 제공 기능

서비스를 생성하자마자 자동으로 적용되는 주요 기능들이 있어요:

✅ Alphanumeric Sender ID (브랜드 이름으로 발송)

• SMS O / WhatsApp X
• 예: "YourBrand" 이름으로 메시지 발송 (단, 국가 제한 있음)

✅ Short Code Reroute

• SMS O / WhatsApp X
• 숏코드가 막힌 경우엔 Twilio가 자동으로 다른 번호로 대체 발송

✅ Country Code Geomatch

• SMS O / WhatsApp O
• 수신자의 국가와 동일한 Twilio 번호로 자동 매핑

✅ Scaler (자동 부하 분산)

• SMS O / WhatsApp O
• 서비스에 묶인 여러 발신 번호에 트래픽을 자동 분산시켜줘요

⚠️ 톨프리 번호는 하나만 사용하는 게 좋아요. 여러 개 넣으면 블록될 수 있음!

선택적으로 설정 가능한 고급 기능들

🌟 Sticky Sender

• 항상 같은 수신자에겐 같은 발신 번호로 전송 (신뢰도 증가)

🌟 Area Code Geomatch (미국/캐나다 한정)

• 수신자의 지역 번호와 동일한 번호를 우선 사용

🌟 Validity Period

• 메시지가 Twilio 플랫폼 내에서 유효한 시간 설정 (1~36,000초)

🌟 Smart Encoding

• 보이지 않는 유니코드 문자 자동 치환 → 메시지 분할 방지

🌟 MMS Converter

• MMS가 안 되는 캐리어엔 링크 포함된 SMS로 자동 변환

🌟 Sender ID Pre-registration Alert

• 사전 등록 필수 국가로 발신 시 경고 알림 제공

🌟 Advanced Opt-Out

• STOP, HELP 같은 키워드 커스터마이징 + 다국어 설정 가능

마무리

Twilio Messaging Services는 단순히 메시지를 보내는 수준을 넘어서, 대규모 메시징 환경을 스마트하게 확장할 수 있도록 도와주는 툴이에요.

• 발신자 관리 자동화
• 수신자 경험 통일
• 지역 기반 발신 번호 자동 선택
• 메시지 유효성/형식 자동 조정 등

이 모든 걸 하나의 서비스 단위로 묶어서 사용할 수 있는 게 진짜 매력입니다. 이제 메시지 하나도 똑똑하게 보내봅시다!

📎 원문 링크: Twilio Messaging Services 공식 문서

📘 본 문서는 Twilio 공식 문서인 Message Scheduling를 한국어로 번역/정리한 글입니다. 최신 정보 및 자세한 기능은 반드시 공식 문서를 참고해주세요.

Twilio의 Message Scheduling 기능은 미래의 특정 시점에 SMS, MMS, WhatsApp 메시지를 예약 전송할 수 있는 기능입니다. 이 기능은 Messaging Service를 통해서만 사용할 수 있으며, Engagement Suite에 포함되어 있습니다.

✅ 사전 조건

• 이미 메시지를 일반적으로 Twilio Messaging Service를 통해 전송할 수 있어야 함
• WhatsApp 메시지를 예약하려면 WhatsApp 발신 번호가 Messaging Service의 Sender Pool에 등록되어 있어야 하며, 사전 승인된 템플릿을 사용해야 함

✉️ 메시지 예약 전송 방식

Twilio에서 예약 메시지를 생성할 땐, 일반 메시지와 동일하게 Message 리소스를 생성하되, 두 가지 추가 파라미터를 포함해야 합니다:

그 외에도 아래 값들이 필요합니다:

• messagingServiceSid: 메시지를 전송할 Messaging Service의 SID
• body 또는 mediaUrl 또는 contentSid
• to: 수신자 번호 (예: +821012345678) 또는 WhatsApp 주소 (예: whatsapp:+821012345678)

🔒 제한사항

• 메시지는 전송 5분 전까지는 예약되어야 함
• 예약은 최대 35일 후까지 가능함

💻 예제 코드 (Node.js)

const twilio = require("twilio");
const accountSid = process.env.TWILIO_ACCOUNT_SID;
const authToken = process.env.TWILIO_AUTH_TOKEN;
const client = twilio(accountSid, authToken);

async function createMessage() {
  const message = await client.messages.create({
    body: "이건 예약된 메시지입니다.",
    messagingServiceSid: "MGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    scheduleType: "fixed",
    sendAt: new Date("2025-06-10T15:00:00Z"),
    to: "+821012345678",
  });
  console.log(message.sid);
}

createMessage();

📩 Twilio 응답 예시

{
  "status": "scheduled",
  "sid": "SMxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "to": "+821012345678",
  "messaging_service_sid": "MGxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

• 메시지가 정상 예약되면 HTTP 응답 코드 201과 함께 status: scheduled로 표시됨
• 메시지가 실패하면 400 오류 발생 (시간 형식 오류 등)

⚠️ 전송 시 실패할 수 있는 경우

1. 수신자가 Opt-Out 한 경우

예약 당시에는 생성되지만, 전송 시점에 해당 사용자가 차단(Opt-Out)했을 경우 메시지는 실패 처리됨 (21610)

→ 메시지 취소 API를 사용해 사전에 취소 가능

2. WhatsApp 템플릿 유효성 실패

템플릿은 메시지 생성 시가 아닌, 실제 전송 시점에 유효성 검사를 거침. 허용되지 않은 템플릿이면 전송 실패

🛑 예약 메시지 취소

async function cancelMessage() {
  const message = await client
    .messages("SMxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx")
    .update({ status: "canceled" });
  console.log(message.status); // canceled
}

• status: "canceled" 로 업데이트하면 예약이 취소됨
• 이때 status callback에는 canceled 이벤트가 전송됨

💡 유의사항

• 하나의 Twilio 계정(서브계정 포함) 당 최대 1,000,000개의 예약 메시지 생성 가능
• 예약 메시지는 예약된 순간부터 카운트됨

🏷️ 관련 문서

• Twilio Message Scheduling (공식 문서)
• Message Resource API 문서

예를 들어 리뷰가 등록되면 Book의 reviewCount를,
댓글이 달리면 Review의 commentCount를 함께 갱신해야 하는 식이죠.

이번 글은 코드잇 스프링 부트캠프에서 실제로 멘토링 중 나왔던 이와 같은 고민에서 출발해,
JPQL UPDATE와 락 전략, 그리고 동시성 문제에 대해 정리해보았습니다.

🤔 고민의 시작은 이랬습니다

• Book 엔티티의 reviewCount는 리뷰가 생성될 때마다 어떻게 갱신할까?
• Review 엔티티의 commentCount는 댓글이 생성될 때마다 어떻게 관리해야 할까?

네모님은 다음 세 가지 방식 사이에서 동시성과 정합성 측면에서 어떤 전략이 최선일지 깊이 고민하셨습니다:

1. 리뷰 생성 시, 단순히 book.reviewCount++
2. 리뷰 생성 시, SELECT COUNT(*) FROM Review WHERE book_id = ?로 매번 다시 세기
3. JPQL UPDATE를 통해 DB에서 직접 집계 + 갱신

그중 네모님은 3번 방식, 즉 JPQL UPDATE 쿼리로 reviewCount와 rating을 함께 갱신하는 방식을 선택하셨어요.

구체적으로 락이나 JPQL의 동작 방식에 대해 언급하시진 않았지만,
그 선택만으로도 실무적인 고민이 엿보였기 때문에

👉 이 글에서는 그 흐름을 따라
락(Lock), JPQL UPDATE의 특성, 그리고 비관적 락과 낙관적 락 중 어떤 전략을 선택할 수 있는지까지 함께 정리해보고자 합니다.

💡 선택한 구현 방식

@Modifying
@Query("""
  UPDATE Book b
  SET 
    b.reviewCount = (SELECT COUNT(r) FROM Review r WHERE r.book.id = :bookId),
    b.rating = (SELECT COALESCE(AVG(r.rating), 0) FROM Review r WHERE r.book.id = :bookId)
  WHERE b.id = :bookId
""")
void recalcStats(@Param("bookId") UUID bookId);

• @Modifying과 함께 JPQL UPDATE 사용
• 리뷰 수와 평점을 한 번의 쿼리로 동시 갱신
• 이때 발생하는 락(lock) 동작을 이해하는 것이 핵심 포인트입니다.

JPQL UPDATE 사용할 때 꼭 알아야 할 점 ⚠️: clearAutomatically

그치만 ..!!! JPQL UPDATE는 JPA의 영속성 컨텍스트를 무시하고 DB에 바로 반영되기 때문에,
같은 트랜잭션 내에서 조회 결과가 최신 값과 불일치할 수 있습니다.

이 문제를 방지하려면 @Modifying(clearAutomatically = true) 옵션을 반드시 사용하는 것이 좋아요.

@Modifying(clearAutomatically = true)
@Query("UPDATE Book b SET b.reviewCount = :count WHERE b.id = :bookId")
void updateCount(@Param("count") long count, @Param("bookId") UUID bookId);

→ 관련 설명 자세히 보기

JPQL UPDATE는 락🔒을 건다? Yes, 비관적 락🔒입니다

JPQL로 직접 UPDATE를 수행하면, JPA는 해당 row에 대해 쓰기 락(write lock)을 요청해요.
이는 DB 차원에서 다른 트랜잭션의 접근을 차단하는 비관적 락(Pessimistic Lock)의 대표적인 예시입니다.

락 전략 비교

락 전략 시각화 (Mermaid)

graph TD
    A[리뷰 생성 요청] --> B{락 전략 선택}
    B -->|비관적 락| C[JPQL UPDATE → row 잠금]
    B -->|낙관적 락| D[@Version 기반 충돌 검사]
    C --> E[동시 수정 방지, 성능 부담]
    D --> F[충돌 시 예외 발생, 성능 우위]

네모님의 선택, 실무에서도 충분히 고려할 수 있는 접근이었습니다

리뷰 생성 시 book.reviewCount와 rating을 어떻게 갱신할지 고민하던 네모님은,
JPQL UPDATE 쿼리를 통해 두 값을 한 번에 갱신하는 방법을 선택하셨어요.

이 방식이 야무졌던 이유는 다음과 같아요:

• 리뷰는 자주 생성되고,
• Book은 여러 사용자가 동시에 접근할 가능성이 높으며,
• 단순 ++ 연산은 동시성 이슈에 쉽게 노출될 수 있기 때문이죠.

복잡한 조건을 고려한 결정이라기보단, 현실적인 상황에서 자연스럽게 나온 선택이었지만,
결과적으로는 실무에서도 자주 사용하는 안전한 방식과 맞닿아 있었습니다.

이 선택에 대해서는 9팀 멘토링 시간에 직접 들을 수 있었고,
그때 떠올랐던 기술적 배경과 함께 알아두면 좋을 내용을
큐레이션 형식으로 정리해보면 좋겠다는 생각에 이 글을 작성하게 되었습니다.

💬 꼭 JPQL UPDATE를 써야 할까? 비관적 락은 JPA에서도 가능해요

한편, 꼭 JPQL UPDATE를 쓰지 않아도 JPA에서 비관적 락을 명시적으로 걸 수 있는 방법이 있습니다.

예를 들어 findById와 함께 PESSIMISTIC_WRITE를 사용하면,
JPQL 없이도 아래처럼 트랜잭션 레벨에서 락을 적용할 수 있어요:

Book book = em.find(Book.class, bookId, LockModeType.PESSIMISTIC_WRITE);
// 이후 book.reviewCount = ... 로직 수행

이 방식은 DB 락을 안전하게 걸면서도 엔티티를 수정하는 흐름을 그대로 유지할 수 있어,
JPQL UPDATE보다 더 유연하고 타입 안전한 구조로 이어질 수 있습니다.
→ 관련 예제 보기

🔗 참고 자료

• 공식 Hibernate User Guide - Locking
• Spring Data JPA - Modifying Queries
• rudaks 블로그 - JPQL @Modifying의 clearAutomatically가 필요한 이유
• Baeldung - Optimistic Locking in JPA
• Baeldung - JPA에서 비관적 락 적용하기
• pixx 블로그 - JPA에서의 비관적 락 사용 예제

마무리하며

• JPQL UPDATE는 비관적 락을 유발합니다
• reviewCount++처럼 단순히 값을 증가시키는 방식은
  여러 트랜잭션이 동시에 접근할 경우, 마지막 값만 반영되는 문제가 발생할 수 있습니다
  → 즉, 중복 업데이트나 값 손실로 이어질 수 있어 동시성 충돌에 매우 취약합니다
• 동시성이 중요한 필드라면 쿼리 기반 갱신과 락 전략 고려가 필요합니다
• 실무에서는 데이터 특성과 트래픽 패턴을 고려해 적절한 락을 선택해야 합니다

4주차는 항해 시네마 프로젝트의 마지막 주차였습니다.

이번 주의 주제는 바로 —
"RateLimit 기능 구현"

실제 서비스에 가까운 환경에서 다음과 같은 제한 정책을 Redis로 구현하는 것이 핵심이었어요:

• API 호출 수 제한
• 예약 중복 제한
• 분산 환경에서의 요청 제어

🧱 과부하 트래픽에도 무너지지 않는 구조,
우리가 직접 설계해 본 시간입니다.

또한 이번 주는 단순한 기능 구현을 넘어,
항해라는 브랜드와 함께한 성장 여정을 되돌아보는 시간이기도 했습니다.

1. RateLimit은 왜 필요할까?

• 실제 서비스에서 무제한 호출은 곧 서버 리소스 고갈, 시스템 장애로 이어질 수 있겠죠.
• 인증 여부와 관계없이, 우리는 클라이언트의 과도한 요청을 제어해줘야만 해요.
• 특히 분산 환경에서의 RateLimit은 원자성과 TTL 관리, 일관성 보장이라는 도전과제를 동반합니다.

🎯 이번 주의 기술 목표

• IP 기반의 RateLimit 정책을 Redis로 구현
• API 호출 및 예약에 각각 다른 제한 적용
• 테스트와 AOP 적용을 통해 선언적이고 검증 가능한 구조로 설계

2. 어떻게 구현할까? 설계 방향부터 고민하기

RateLimit 기능은 단순히 요청을 막는 로직이 아닙니다.
서비스의 안정성을 유지하면서도, 개발자가 관리하기 쉬운 구조로 설계되어야 하죠.

그래서 이번 구현에서는 아래 세 가지 원칙을 기준 삼아 설계했어요:

• 선언적 구조 : 요청 제한을 각 컨트롤러 메서드 위에서 바로 볼 수 있어야 햇!
• 관심사의 분리 : 비즈니스 로직과 RateLimit 로직을 철저히 분리하자!
• 확장 가능한 구조 : 추후 다양한 타입의 제한이나 정책 변경에도 유연하게 대응 가능하게!

이를 위해 사용한 방법은 바로 @RateLimit 애노테이션 + AOP 기반의 분리였습니다.

3. 기술 구현

3-1. @RateLimit 애노테이션과 AOP 기반 제어

RateLimit을 적용할 메서드에 애노테이션만 붙이면, 자동으로 제한 로직이 적용되는 구조를 설계했습니다. 이런 선언적인 방식은 컨트롤러의 가독성을 높이고, 로직 재사용에도 큰 장점이 있죠.

@Target(AnnotationTarget.FUNCTION)
@Retention(AnnotationRetention.RUNTIME)
annotation class RateLimit(
    val type: RateLimitType
)

enum class RateLimitType {
    API_CALL,    // 분당 50회 제한
    BOOKING      // 5분당 1회 제한
}

그리고 AOP를 활용해 실제 실행 흐름에서 제한 여부를 체크하도록 구성했습니다. 이 방식은 실제 API 동작 흐름을 해치지 않으면서도, 일관된 방식으로 제한 로직을 삽입할 수 있다는 장점이 있어요.

@Around("@annotation(rateLimit)")
fun rateLimitCheck(joinPoint: ProceedingJoinPoint, rateLimit: RateLimit): Any {
    val clientIp = request.remoteAddr
    ... // 제한 확인 후 예외 발생 또는 proceed()
}

이처럼 관심사 분리(SOC) 원칙을 잘 살린 구조는 리뷰에서도 긍정적인 평가를 받을 수 있었습니다.

💬 리뷰 피드백

• AOP 기반 구조와 IP 차단 방식이 잘 설계되었다는 리뷰를 받았습니다.☺️
• 예외 메시지는 상수로 분리하면 유지보수에 더 유리하다는 피드백도 함께 받았습니다.

3-2. Redis 기반 RateLimiter 구현 - Lua Script 방식

처음에는 Redis의 AtomicLong을 활용해 간단한 방식으로 RateLimit을 구현했어요. 하지만 테스트 과정에서 Race Condition 문제와 제한 정확성 이슈가 발생했고, 결국 더 안정적이고 원자적인 방식을 고민하게 되었습니다.

그 대안으로 선택한 방식이 바로 Lua Script 기반 구현입니다.

local key = KEYS[1]
local limit = tonumber(ARGV[1])
...
local current = redis.call('incr', key)
if current == 1 then
  redis.call('expire', key, 60)
end
...

이 방식은 Redis 내부에서 스크립트를 단일 트랜잭션처럼 처리하기 때문에, 동시성 문제 없이 안전하게 요청 횟수를 제어할 수 있어요. 또한 TTL(만료 시간)을 명확하게 설정할 수 있어 자동화된 리셋도 가능했습니다.

💬 리뷰 피드백

• Lua Script를 통한 원자성 확보, TTL 처리 방식 모두 잘 설계되었다는 긍정적인 피드백을 받았습니다.

3-3. Controller 적용 예시

RateLimit 로직을 설계하고 검증한 이후, 이제 실제 서비스 흐름에 적용할 차례입니다.

@RateLimit 애노테이션을 컨트롤러 메서드에 붙이기만 하면 유형별 제한 정책이 자동 적용되는 구조가 완성돼요.

API 유형에 따라 API 호출 제한(API_CALL), 예약 중복 제한(BOOKING) 으로 나눠 선언적으로 적용했습니다.

@RateLimit(type = RateLimitType.API_CALL)
@GetMapping("/api/v1/movies")
fun getMovies() = ...

@RateLimit(type = RateLimitType.BOOKING)
@PostMapping("/api/v1/movies/{scheduleId}/reservations")
fun reserve(...) = ...

3-4. 테스트 구성과 시나리오 검증

로직을 구현했다면, 검증은 필수겠죠.

RateLimit 기능의 정확한 동작을 검증하기 위해,
AOP 레벨의 흐름 테스트부터 Controller 단위의 통합 테스트까지 다층적으로 테스트를 구성했습니다.

✅ 단위 테스트 : RateLimitAspect 내부 흐름 검증

AOP 로직이 잘 작동하는지, 제한 조건에 따라 예외가 발생하는지를 검증합니다.

@Test
fun `1분 내 API 호출이 50회를 초과하면 1시간 동안 차단된다`() {
    // given
    whenever(rateLimit.type).thenReturn(RateLimitType.API_CALL)
    whenever(guavaRateLimiter.isBlocked(testIp)).thenReturn(false)
    whenever(guavaRateLimiter.checkApiRateLimit(testIp))
        .thenReturn(true)  // 50회까지는 허용
        .thenReturn(false) // 51번째는 차단

    // when
    repeat(50) { rateLimitAspect.rateLimitCheck(joinPoint, rateLimit) }

    // then - 51번째 요청에서 예외 발생
    assertThrows<RateLimitExceededException> {
        rateLimitAspect.rateLimitCheck(joinPoint, rateLimit)
    }
}

💬 리뷰 피드백

• 핵심 흐름(정상 요청 → 제한 초과 → 예외 발생)이 명확히 드러난 테스트 설계라는 평가를 받았어요.
• 다만 mock 기반 테스트만으로는 Redis 동작을 완전히 검증할 수 없으므로,
  실제 환경 기반 테스트의 보완이 필요하다는 코멘트도 함께 받았습니다.

✅ 통합 테스트 : API 호출 흐름 검증

Spring의 MockMvc를 사용해, 실제 API 호출을 반복하며 RateLimit 정책이 정확히 반영되는지 검증했습니다.

@Test
fun `영화 목록 API를 51회 호출하면 마지막 요청은 차단된다`() {
    repeat(50) {
        mockMvc.perform(get("/api/v1/movies"))
            .andExpect(status().isOk)
    }

    mockMvc.perform(get("/api/v1/movies"))
        .andExpect(status().isTooManyRequests)
        .andExpect(jsonPath("$.message").value("분당 최대 50회 요청 가능합니다."))
}

이 테스트는 정책상 허용된 50회까지는 OK 응답을 받고, 51번째 요청부터는 429 Too Many Requests 응답을 받도록 검증합니다.

💬 리뷰 피드백
Presentation Layer에서의 흐름 테스트가 잘 구성되어 있다는 피드백을 받았습니다.

✍️ 개인 회고 실제 호출 흐름을 따라가는 테스트는 단순한 단위 검증보다 “제한 정책이 진짜로 적용되고 있는지”를 입증하는 데에 더 도움이 된다고 느꼈어요. 특히 이와 같은 흐름 검증은 사용자 경험 측면에서도 중요한 포인트라고 생각합니다.

4. 이번 주를 정리하며 — 실전 피드백과 회고

🎉 Best Practice 선정 소식! 이번 주 구현 내용은 항해 단기 스킬업 Slack에서 Best Practice 사례로도 선정되었어요. (Guava와 Redis를 활용한 RateLimit 설계 및 테스트 구성이 특히 좋은 평가를 받았습니다.)

🔍 리뷰어 코멘트 요약

이번 피드백을 통해 실무에서도 중요시되는 “구조의 명확함”과 테스트의 실용적 가치에 대해 다시금 체감할 수 있었습니다.

특히 “예외 메시지의 상수화”나 “제한 정책의 표현 방식 개선”처럼, 사소해보이지만 유지보수성과 직결되는 포인트들을 직접 느낄 수 있었어요.

📎 자세한 구현 및 리뷰 코멘트는 4주차 PR - RateLimit 기능 구현에서 확인해보실 수 있어요.

시리즈 돌아보기

👉 지난 글 보기: 항해 시네마 개발 Log📄 #3 : 락을 썼지만, 테스트는 나락...
👉 첫 글 보기: 멀티 모듈 설계, 이렇게 고민하고 이렇게 풀었다

마무리하며

항해 플러스 백엔드 과정에 이어
이번 단기 스킬업 과정까지 —
저는 두 번의 항해를 무사히 완주했습니다.

항해는 언제나 단순한 구현을 넘어, 더 나은 방향을 제시해주는 공간이었어요.
이번 과정에서도 멋쟁이 코치님들의 깊이 있는 리뷰 덕분에
기술뿐 아니라 설계, 테스트, 구조적인 시야까지 함께 성장할 수 있었습니다.

그리고 무엇보다 —
제가 항해를 진심으로 애정하게 된 이유는
개발을 바라보는 시야가 정말 넓어졌다는 점이에요.

이제는 "어떻게 만들까"를 넘어서,
"어디로 가볼까?", "무엇을 시도해볼까?"
더 많은 가능성을 열어두고 고민할 수 있게 되었어요.

그게 저는 정말, 너무 좋습니다. 😊

다음엔 번외편으로,
Optimistic Lock 재도전, Redis 설정 후 AOP 기반 Distributed Lock 적용, 테스트 커버리지 개선과 같은 이야기들도 기록해보려 합니다.

그럼, 진짜 마지막 여정에서 또 만나요 ⛵️

3주차는 동시성 제어와 락 구현이라는 무게감 있는 주제를 마주한 주차였습니다.

하지만 현실은 언제나 시련을 동반하죠. 요구사항은 Pessimistic → Optimistic → Distributed → 함수형 락까지 구현하는 것이었지만, 결국 비관적 락에서 멈춰버렸습니다. 😇

그럼에도 불구하고, 동시성 제어의 핵심 원리와 Pessimistic Lock의 실전 적용 경험, 테스트 설계와 삽질 기록까지 모두 정리해보겠어요.

3주차 핵심 목표 및 달성 현황

📌 과정이 끝난 시점인 5주차에서는 미완료 항목들을 중심으로 구현을 마무리할 계획입니다.

1. 예약 API 구현과 동시성 문제의 본질

1-1. 왜 동시성 제어가 필요한가?

• 예매 시스템에서 좌석은 공유 자원입니다.
• 다수의 사용자가 동시에 특정 좌석을 예매하려는 경우 데이터 무결성 문제가 발생할 수 있죠.
• 실무 사례 참고: T-money Go 앱도 클라이언트 단 선점 처리로 동시성 이슈를 방지한다고 합니다.

🎯 목표: 서버 사이드에서 이러한 동시성 이슈를 트랜잭션과 락을 활용해 제어할 수 있을지 직접 구현해봅니다.

트랜잭션 경계 안에서 데이터 정합성을 보장하기 위해, 가장 먼저 적용한 방법은 Pessimistic Lock이었습니다.

1-2. Pessimistic Lock으로 해결한 첫 단계

@Lock(LockModeType.PESSIMISTIC_WRITE)
@Query("""
    SELECT r FROM Reservation r
    WHERE r.schedule.id = :scheduleId
    AND r.seat.id IN :seatIds
""")
fun findAllByScheduleIdAndSeatIdInWithPessimisticLock(...)

• Critical Section에 대해 락을 설정하여 경쟁 조건을 방지했어요.
• 데이터 정합성 보장에 강력하지만, 동시성 성능 저하 우려가 돼요🤔

1-2. 테스트 코드 설계

@Test
    fun `동시 예약 시도시 하나만 성공하고 나머지는 실패해야 한다`() {
        // given
        val threadCount = 5
        val executorService = Executors.newFixedThreadPool(threadCount)
        val latch = CountDownLatch(threadCount)
        val results = mutableMapOf<String, Throwable?>()

        // when
        repeat(threadCount) { index ->
            executorService.submit {
                try {
                    val userId = "user-$index"
                    val request = ReservationRequest(
                        scheduleId = schedule.id!!,
                        seatIds = listOf(seats.first().id!!)
                    )
                    reservationFacade.reserve(request, userId)
                    results[userId] = null // 성공
                } catch (e: Exception) {
                    results["user-$index"] = e
                } finally {
                    latch.countDown()
                }
            }
        }

        // then
        latch.await(10, TimeUnit.SECONDS)
        executorService.shutdown()

        val successCount = results.count { it.value == null }
        val lockFailureCount = results.count { it.value is PessimisticLockingFailureException }

        assertEquals(1, successCount, "하나의 예약만 성공해야 합니다")
        assertEquals(threadCount - 1, lockFailureCount, "나머지는 락 획득 실패로 실패해야 합니다")
    }

• 동시성 상황을 시뮬레이션하는 구조화된 테스트 코드 구성
• 하지만 문제 발생…

2. 테스트는 나락으로… 실패의 기록🏳️

2-1. TestContainers, 네가 문제인거니…

처음에는 테스트가 전혀 실행되지 않아 의아했지만, 로그를 꼼꼼히 들여다본 끝에 다음과 같은 에러 메시지를 발견할 수 있었습니다.

처음엔 테이블 자체가 없다는 뜻인가 싶었지만, 에러를 하나씩 없애보다보니 진짜 문제는 바로…

💣 엔티티 - DDL(sql) 간 컬럼 불일치였습니다.

문제가 발생한 구조

해결 방법

언제나 해결 방법은 삽질을 아무리 오래 했어도^^,,, 간단하죠.

1. Entity 정의 기준으로 schema.sql을 다시 정리

   • Hibernate DDL 로그를 참고해 컬럼명, 제약 조건, 타입 등 모두 일치시킴

2. data.sql도 이에 맞춰 INSERT문 다시 작성

   • 모든 컬럼에 값이 들어가도록 하고, 외래 키 제약도 맞춤

3. application-test.yml에 다음 설정을 추가

   spring:
     jpa:
       hibernate:
         ddl-auto: none
       properties:
         hibernate:
           dialect: org.hibernate.dialect.MySQLDialect
           format_sql: true
       show-sql: true
       defer-datasource-initialization: true
   
     sql:
       init:
         mode: always
         schema-locations: schema.sql
         data-locations: data.sql

4. 테스트 클래스에서 withInitScript("init.sql") → 제거하고, DynamicProperty 설정 단순화

   @JvmStatic
   @DynamicPropertySource
   fun properties(registry: DynamicPropertyRegistry) {
       registry.add("spring.datasource.url") { "jdbc:tc:mysql:8.0.32:///${mysqlContainer.databaseName}" }
       registry.add("spring.datasource.driver-class-name") { "org.testcontainers.jdbc.ContainerDatabaseDriver" }
       registry.add("spring.datasource.username") { mysqlContainer.username }
       registry.add("spring.datasource.password") { mysqlContainer.password }
   }

✅ 최종 정리
schema.sql, data.sql을 Entity 기준으로 재작성하고,
Spring Boot 설정과 TestContainers를 분리 구성함으로써 문제를 해결했습니다.

그 결과, 테스트가 정상적으로 실행되었고 드디어 본격적인 동시성 테스트 코드 실행까지 진입할 수 있었습니다!

2-2. 테스트는 돌아갔지만… 성공한 예약은 0건?

Testcontainers + schema.sql + data.sql 조합으로 환경을 잘 구성한 덕분에, 테스트는 드디어 정상 실행되기 시작했습니다.

하지만 기대와는 다르게 결과는...

❌ Expected :1, Actual :0
🤯 하나의 예약도 성공하지 못하고 모두 실패!

테스트 메서드는 동시성 상황에서 5명의 유저가 동시에 같은 좌석을 예약하려고 시도하고,
하나는 성공하고 나머지는 Pessimistic Lock 실패로 예외가 나야 정상이죠.

그런데 지금은 아예 모두 실패(PessimisticLockingFailureException) 하고 있습니다.

val successCount = results.count { it.value == null }   // 성공한 쓰레드 수
val lockFailureCount = results.count { it.value is PessimisticLockingFailureException }

org.opentest4j.AssertionFailedError: 하나의 예약만 성공해야 합니다
Expected :1
Actual   :0

즉, 락이 작동은 했지만... 처음 시도한 쓰레드조차 락을 못 잡고 실패한 셈입니다.

2-3. 왜 전부 실패했을까? 😰

현재 예상되는 원인은 다음과 같아요.

✅ 시도 예정 해결 방향 다음과 같은 시도를 통해 테스트 정확도를 높일 예정입니다:

• Executors.newCachedThreadPool()로 병렬성 높이기
• 락이 정확히 @Transactional 경계 안에서 작동하는지 재확인
• 초기화된 seat가 실제로 DB에 존재하고 예약 가능한 상태인지 검증

2-4. 로그로 확인한 쿼리 흐름

실제로 테스트 중 쿼리 로그를 확인해보면, for update 쿼리가 발생하고 있는 걸 확인할 수 있습니다:

select r1_0.id, ... from reservations r1_0 
where r1_0.schedule_id=? and r1_0.seat_id in (?) for update

하지만 그 뒤에 insert가 발생하지 않거나, 전부 롤백된 정황입니다.

🤔 결론적으로 락 자체는 시도되었지만, 테스트 환경의 트랜잭션/실행 타이밍/예외 흐름 등이 성공까지 이어지지 못한 상태로 보입니다.

2-5. 다음 시도 방향

• Thread.sleep을 삽입해 락 점유 시간을 늘려 race condition 유도해본다!
• @Transactional(propagation = Propagation.REQUIRES_NEW) 등 트랜잭션을 세밀하게 조정해본다!
• TestMessageService에 예약 시점 로깅 추가하여 첫 번째 요청 시도 기록 추적^^..

3. 이번 주를 정리하며 — 실전 피드백과 회고

이번 주차는 단순 락 구현을 넘어서, 트랜잭션 경계 설정과 테스트 환경 구성의 중요성까지 체감할 수 있었던 시기였습니다. 락을 통해 동시성 문제를 해결하는 것이 목표였지만, 나락 속에서 몇 가지 과제는 다음 주차로 넘기게 되었어요.

잘한 점

• TestContainers 환경 구성과 DDL/data.sql 싱크 맞춤
• Pessimistic Lock을 적용해 실제로 동시성 이슈를 잡아본 경험

아쉬운 점

• "하나의 예약만 성공해야 한다" 테스트는 여전히 실패 상태
• Pessimistic Lock까지만 구현하고, Optimistic/Distributed Lock은 미완료

리뷰 피드백 & 다음에 꼭 챙길 것

이번 주 주제와 직접 연관되진 않지만, 리뷰 과정에서 아래와 같은 피드백도 받았습니다:

• Exception 분리: IllegalArgumentException 대신 도메인 예외 클래스로 세분화
• URL 프리픽스(v1): REST API 버전 관리 도입 필요
• 도메인 Validation 분리: 도메인 내부의 유효성 검사를 명확히 함수로 추출

급하게 기능 구현에 집중하느라 놓쳤던 부분들이지만,
다음 주차 리팩토링과 분산락 구현 타이밍에 맞춰 반드시 반영할 예정이에요.

📎 3주차 Pessimistic Lock 적용 PR: #45 - 예약 API 및 Pessimistic Lock 적용 PR

시리즈 돌아보기

👉 지난 글 보기: 항해 시네마 개발 Log #2 - 인덱스보다 캐시? 성능 최적화 실전 기록
👉 첫 글 보기: 멀티 모듈 설계, 이렇게 고민하고 이렇게 풀었다

그럼 다음 글에서는 RateLimit 구현기와 테스트 커버리지 개선 여정으로 다시 찾아뵐게요!

이 글은 항해 플러스 스킬업 과정에서 진행한 실전 프로젝트 경험을 바탕으로 작성되었습니다.

2주차의 핵심은 실제 트래픽을 고려한 성능 최적화 실험이었습니다. 지난 주차에 설계한 구조 위에 기능을 추가하면서 발생한 성능 저하 문제를 진단하고, 이를 해결하기 위해 다양한 전략을 직접 테스트하며 비교 분석했습니다.

2주차 핵심 목표

• 검색 기능 추가로 인한 성능 변화 분석
• 인덱스 기반 쿼리 최적화 실험
• 로컬 캐시(Caffeine) 및 분산 캐시(Redis) 적용 비교
• 성능 테스트 자동화 및 수치 기반 개선 검증

1. 성능 테스트, 제대로 하는 법부터 시작하자

1-1. 성능 테스트 시나리오 설계: DAU 기반 접근

• 하루 사용자 수(DAU) 1,000명, 사용자당 2회 접속을 가정
• 피크 시간대는 일반 트래픽 대비 10배 증가 시나리오 설정
• 실전처럼 현실적인 조건을 시뮬레이션하며 성능 테스트 전제를 정리

📸 테스트 보고서 내 전제 조건 설명: 리뷰어 피드백에서 “테스트 가정이 매우 논리적이다”는 평가를 받았습니다.

1-2. 단계적 성능 측정의 중요성

• 성능은 한 번의 테스트로 끝나지 않지요. 변화 과정을 기록하며 개선 방향을 잡는 것이 중요합니다.

• 1주차 기본 API → 검색 기능 추가 → 인덱스 적용 → 캐시 적용 → Redis 적용 흐름으로 테스트를 진행했고, 아래는 그 결과를 정리한 성능 비교표입니다.

  구분	평균 응답 시간	p95 응답 시간	처리량(RPS)	실패율
  1주차 API	17.18ms	21.62ms	52.80	10.27%
  인덱스 적용 전	9.42s	14.14s	7.42	10.24%
  인덱스 적용 후	9.59s	15.08s	7.34	10.29%
  로컬 캐시 적용	4.38ms	6.78ms	53.33	9.75%
  Redis 캐시 적용	10.08s	14.77s	7.02	100%

📊 위 데이터를 통해 어떤 전략이 실질적으로 성능에 가장 큰 영향을 주었는지 직관적으로 파악할 수 있어요.

특히, 인덱스보다 로컬 캐시 적용의 효과가 가장 극적이었고, Redis 캐시는 설정 이슈로 인해 실패율 100%라는 슬픈 결과를 보였습니다.

2. 인덱스 적용, 기대와 다른 실전 결과

2-1. 작은 데이터셋에서는 오히려 역효과?

• Full Scan은 단순 작업이라 소규모 DB에선 빠를 수 있음
• 인덱스를 타는 쿼리는 오히려 오버헤드가 생길 수 있음
• 실제 테스트 결과, 인덱스 적용 전후 성능 차이는 미미함

📸리뷰 코멘트:
“작은 테이블에서는 인덱스가 성능에 도움이 안 될 수도 있습니다.”

위 피드백은 실제로 인덱스를 적용했을 때 성능 차이가 미미했던 실험 결과와도 잘 맞아떨어지지요. 소규모 데이터셋에서 인덱스는 오히려 불필요한 오버헤드가 될 수 있다는 걸 직접 체감한 사례입니다.

2-2. 복합 인덱스 vs 단일 인덱스, 무엇이 더 나을까?

• 카디널리티(중복도) 기반으로 인덱스 설계 고려
• 복합 인덱스(title, genre, releaseAt DESC) 대신 단일 인덱스 선택
• 쿼리 실행 계획을 통해 인덱스가 실제로 사용되는지 확인

📸 리뷰 질문: "복합 인덱스를 선택하지 않은 이유가 궁금합니다."

이 리뷰를 통해 인덱스 선택의 기준이 단순히 필드 수가 아니라, 쿼리 특성과 데이터 분포(카디널리티)임을 다시금 실감했습니다. 실무에서도 복합 인덱스를 무조건적으로 적용하기보다는, 상황에 맞는 전략적 선택이 중요하니까요😅

3. 캐시 전략의 진화: Caffeine → Redis

3-1. 로컬 캐시(Caffeine)로 얻은 성능 개선 효과

• 평균 응답 시간 4.38ms, 처리량 53.33 RPS로 비약적 개선
• 기존 API 대비 약 2,150배 빠르고 7배 이상 처리량 향상

3-2. 분산 캐시(Redis) 도입 후 마주친 도전들

• Redis 연결 문제로 실패율 100% 기록
• 캐시 미스 시 fallback 미비, 장애 발생 시 전체 실패
• 분산 환경에서는 예외 처리 및 장애 설계가 매우 중요함을 실감

📸 리뷰 피드백: "Redis 장애가 발생해도 응답이 아예 실패하면 안 됩니다."

이 피드백을 통해 단순히 캐시를 적용하는 데 그치지 않고,
장애 상황에서도 서비스가 무너지지 않도록 설계하는 것이 얼마나 중요한지 다시금 깨달았습니다.
실제 운영 환경에서는 성능보다 안정성이 더 중요한 순간이 많기 때문에,
“실패했을 때 어떻게 복구할 것인가”에 대한 고민은 반드시 선행되어야 한다고 느꼈습니다.

3-3. 캐시 키 설계의 함정

• title + genre 조합은 캐시 효율이 낮을 수 있음
• 캐시 효율을 위해서는 인기 장르 중심 캐싱이 더 나은 전략

📸 리뷰 인사이트: "캐시 히트율 높은 장르만 선택적으로 캐싱해보는 것을 고려해보세요."

이 피드백을 통해 단순히 키를 조합하는 방식만으로는 캐시 효율을 끌어올리기 어렵다는 점을 알 수 있었습니다.
실제로는 사용 패턴이나 자주 조회되는 데이터를 분석해, “무엇을 캐싱할 것인가”를 전략적으로 결정하는 것이 훨씬 더 중요하다는 걸 배웠죠.

4. 실전에서 배운 진짜 교훈

4-1. 테스트 데이터가 성능을 왜곡할 수도 있다

• 랜덤으로 4개 타이틀만 사용하는 경우, 캐싱 효과가 과대하게 나타남
• 다양한 타이틀 데이터로 테스트해야 실제 환경과 유사

📸 리뷰 피드백: "데이터 다양성이 부족하면 캐시 히트율이 왜곡될 수 있습니다."

이 피드백 덕분에 성능 테스트에서 데이터 샘플의 다양성과 현실성이 얼마나 중요한지 느낄 수 있었습니다.
제대로 된 검증을 위해서는 단순히 많은 데이터를 넣는 것이 아니라, 실제 사용 시나리오와 유사한 분포와 구조를 설계해야 한다는 것을 배웠습니다.

4-2. 실패에 강한 시스템을 설계하라

• Redis 장애 시 fallback 응답 설계 필요
• 캐시 미스, 캐시 삭제 등 예외 상황 고려한 로직 필요
• 장애 대응, 재시도, 타임아웃 등 전체 흐름을 고려한 설계가 필요함

5. 종합 비교 분석

성능 지표 비교

표로 비교해보니 더욱 분명해졌습니다. 가장 극적인 개선은 인덱스가 아닌 로컬 캐시(Caffeine) 적용에서 나타났으며, 반대로 가장 큰 실패는 Redis 설정 미비^^..로 인해 발생했습니다. 단순히 기술을 사용하는 것을 넘어서, 그것을 운영 가능한 구조로 만드는 것이 실전 개발에서 훨씬 더 중요한 과제라는 사실을 다시금 느꼈습니다.

결론 요약

• 인덱스는 소규모 데이터셋에서는 성능 향상이 미미할 수 있음
• 로컬 캐시(Caffeine)는 가장 큰 성능 개선을 가져왔으며, 응답 시간과 처리량 모두 크게 향상
• Redis는 설정 오류로 실패율 100%, 분산 캐시에서는 예외 처리 및 장애 대비가 중요함
• 향후 확장성과 안정성을 고려한 캐시 전략, 장애 대응 설계가 필요함

시리즈 돌아보기

👉 지난 글 보기: 항해 시네마 개발 Log #1 - 멀티 모듈 설계, 이렇게 고민하고 이렇게 풀었다

위 글에서는 멀티 모듈 아키텍처를 어떻게 설계하고, 각 계층을 어떻게 분리했는지에 대한 고민과 그 과정을 담았습니다. 이어지는 이번 글에서는 이 구조 위에 실제 성능을 어떻게 쌓아올릴 수 있을지 실험하고 분석한 기록을 담았습니다.

마무리하며

이번 주는 단순한 튜닝이 아닌 왜 성능이 안 나오는가?🤦🏻‍♀️를 깊이 파고드는 시간이었습니다. 단순한 수치 개선을 넘어서, 데이터 설계와 장애 대응까지 고려하는 아키텍처 고민이 얼마나 중요한지를 실감했습니다.

👉 관련 PR 보기: 김인후 - 2주차 성능 최적화 PR

👉 다음 글에서는 예약 API 구현과 함께,
Pessimistic Lock → Optimistic Lock → Distributed Lock 순으로 어떻게 동시성 문제를 해결해 나갔는지,
그리고 Redisson의 내부 동작과 Lua Script, 함수형 락 전환 경험까지 실전 사례를 정리해볼 예정입니다.

이 글은 항해 플러스 스킬업 과정에서 진행한 '항해 시네마 프로젝트' 경험을 바탕으로 작성되었습니다. 실전 프로젝트를 통해 설계, 성능 최적화, 장애 대응까지 전방위적으로 경험하고 있습니다.

지난 주차의 가장 큰 목표는 프로젝트의 골격을 잡는 것이었습니다. 단순히 기능 구현을 넘어, 앞으로 수주간 쌓아갈 개발 과정의 기반이 되는 설계 말이지요. 그래서 더더욱 신중하게, 그리고 고민하며 진행했죠.

• Multi Module Design 설계 및 ERD 작성
• 메인 페이지용 '상영 중인 영화 조회 API' 개발
• Docker 기반 DB 환경 및 초기 데이터 세팅

🤔 "김인후"가 가장 고민했던 지점

1. 멀티 모듈 경계는 어디까지?

처음에는 ‘domain, application, api’만으로 충분하지 않을까 싶었는데, 인프라 계층을 별도로 두지 않으면 점점 도메인이 더러워질 위험이 보였습니다. 결국 cinema-infrastructure 모듈을 따로 두는 것으로 결정 했지요!

2. 도메인은 얼마나 순수해야 할까?

‘정말 비즈니스 로직 외의 어떤 것도 들어가면 안 된다.’ 이 말을 지키려니 인터페이스 하나 작성할 때도 “이게 진짜 도메인의 책임인가?” 재귀적으로 스스로 질문하며 진행했습니다.

3. Facade는 필수일까?

처음에는 단순한 서비스만 있어도 충분할 줄 알았는데, 여러 도메인을 조합하는 순간 코드가 난잡해지더군요. Facade 패턴의 필요성을 온몸으로 느꼈습니다.

ERD 설계 — 그림으로 먼저 그려봤어요

• 느낀 점: 관계는 간단해 보이지만, 실제 API 응답 설계 시 join과 fetch 전략을 잘못 잡으면 바로 N+1 지옥이 열린다는 걸 알았습니다.

모듈 구조 — 내가 선택한 이유와 구성

상영 중인 영화 조회 API 설계 및 응답 예시

GET /api/movies/now-playing

[
  {
    "id": 1,
    "title": "범죄도시4",
    "rating": "15세 이상",
    "releaseDate": "2023-12-01",
    "thumbnailUrl": "https://example.com/thumbnail1.jpg",
    "runningTime": 120,
    "genre": "액션",
    "schedules": [
      {
        "id": 1,
        "theaterName": "1관",
        "startTime": "2023-12-10T10:00:00",
        "endTime": "2023-12-10T12:00:00"
      }
    ]
  }
]

• "김인후" 생각: ‘조회 API’ 하나지만, 페이징 없이 500건 이상 조회 조건 때문에 최적화가 필수였고, DB-서비스 계층의 설계가 진짜 중요하다는 걸 뼈저리게 느꼈습니다.

시행착오와 해결 과정 (진짜 있었던 일들)

• N+1 문제 발생: 영화마다 스케줄 가져오는데 총 쿼리가 501개 나오는 거 보고 식은땀이...
  • 해결: @EntityGraph와 JPQL fetch join으로 갈아타려고요^_^
• 순환 참조 문제: 인프라 계층이 잘못 application 계층을 참조하도록 설정해서 빌드 실패.
  • 해결: Configuration class에서 @Bean 주입과 모듈 의존 방향을 철저히 점검.
• 초기 데이터 문제: 500개 스케줄 데이터 생성 중 실수로 인덱스 걸어서 MySQL 인서트 속도 지옥...
  • 해결: 1주차 조건에 맞게 인덱스 제거 후 삽입.

"김인후"가 준비한 테스트 환경

• Docker로 PostgreSQL 환경을 구성했습니다.
• 개발 및 테스트는 모두 test 프로필로 분리해서 진행했고, TestContainers를 사용해 로컬 환경에서도 최대한 프로덕션과 유사한 DB 구성을 유지하려고 했습니다.
• API 테스트는 IntelliJ HTTP Client를 적극 활용했고, PR 리뷰에서도 .http 파일을 제공해 리뷰어가 쉽게 실행 가능하도록 준비했습니다.

코치님의 피드백 & "김인후"가 느낀 점

지난 1주차 과제에서 감사하게도 코치님께 Best Practice로 선정되었고,
구조와 책임 분리, 리드미 작성이 협업에 도움이 되었다는 좋은 피드백을 받았습니다.

"프로젝트 구조가 잘 설계되어 있고, 각 모듈 별 책임도 명확해서 좋았습니다.
리드미와 기타 문서를 통해 소통 장치를 잘 만들어서 협업하기 좋은 사람이라는 인상이 들었습니다."

"김인후"가 느낀 점:
리드미 작성과 모듈 설계는 단순한 형식이 아니라,
결국 협업과 커뮤니케이션의 시작이라는 걸 새삼 깨달았습니다.
내가 뭘 고민했고, 어떻게 풀었는지를 미리 잘 담아두는 것만으로도 팀원과 리뷰어에게 신뢰를 줄 수 있다는 걸 배운 주차였어요.

👉 김인후 PR 링크

마무리하며

지난 주는 설계와 구조를 고민하느라 손이 느렸지만, 머리가 정말 야무지게 돌아갔던 시간이었습니다. ‘잘 짠 설계는 코드보다 오래 간다'는 말을 몸소 느꼈고,이번 주에는 성능 튜닝과 인덱스 적용이라는 새로운 도전이 기다리고 있다는 생각에 벌써 기대가 됩니다.

다음 글 예고

다음 글에서는 실제로 쿼리를 어떻게 튜닝했는지, 인덱스를 적용하며 어떤 시행착오를 겪었는지 그리고 성능 개선 전후의 변화를 자세히 정리해보려고 합니다.

잘 정리된 설계 위에서 성능까지 챙기는 야무진 과정을 함께 해보시렵니까?

이 글은 항해 플러스 스킬업 과정에서 진행한 '항해 시네마 프로젝트' 경험을 바탕으로 작성되었습니다.
실전 프로젝트를 통해 배우고 성장하는 경험이 궁금하다면, 꼭 한 번 확인해 보세요!

생각보다 많은 개발자들이 아직 MCP와 Cursor IDE의 역할을 잘 모르는 것 같아 이 시리즈 '스낵AI🤖'를 시작하게 되었습니다.
복잡한 설명 대신, 짧고 간결하지만 실전에 바로 적용할 수 있는 핵심 내용만 전해드릴게요.

MCP란 무엇인가?

MCP (Model Context Protocol)는 AI 모델과 코드 편집기(IDE), 브라우저 간에 정보를 실시간으로 주고받을 수 있도록 만들어진 표준 프로토콜입니다.

✅ MCP가 제공하는 핵심 기능

• 콘솔 로그 실시간 공유
• 네트워크 요청/응답 모니터링
• 현재 선택된 DOM 요소 전송
• 스크린샷 캡처 및 자동 전달
• SEO 및 퍼포먼스 점검 (Lighthouse 연동)
• Debugger Mode, Audit Mode 등 AI 주도의 자동화 기능

MCP를 지원하는 에디터에선, 이제 이렇게 요청할 수 있습니다:

"이거 왜 안돼? 디버깅 모드로 들어가 줘."
"선택한 버튼 요소 색상 바꿔줘."
"지금 SEO 점검 리포트 생성해줘."

👉 즉, MCP는 '말하는 디버깅'과 '말하는 코드 수정'을 가능하게 해주는 기술 표준이에요.

Cursor IDE란 무엇인가?

Cursor는 MCP를 완벽하게 지원하는 AI 기반 코드 에디터입니다.

• Claude 3.5 Sonnet 등 강력한 AI 엔진 지원
• MCP 서버 통합 기능 내장
• 실시간 디버깅 및 코드 자동 수정 지원
• GitHub Copilot 같은 추천 기능과 Chat 기능 내장
• AI Prompt로 ‘코드 생성 → 테스트 → 수정’까지 대화형 가능

특히 Cursor는 vibe coding의 대표 주자로,

"코드 설명해줘"
"이 함수 최적화 해줘"
"테스트 코드 자동 생성해줘"
와 같은 요청을 자연어로 할 수 있는 개발자 필수 툴입니다.

MCP + Cursor = vibe coding

MCP 프로토콜이 정보 교환 표준이라면,
Cursor는 그것을 실제로 구동시키는 도구입니다.
두 가지가 결합되면 여러분은 이제 마우스를 거의 쓰지 않고, 대화만으로 코드를 디버깅하고, 수정하고, 점검할 수 있는 환경을 만들 수 있습니다.

다음 편 예고 🎯

스낵AI🤖 - MCP 편 #1
👉 AgentDesk browser-tools 설치 및 Cursor MCP 연동 가이드에서 직접 설치 과정을 차근차근 알려드립니다!

한 프로젝트에서 여러 개의 저장소를 함께 관리해야 하는 순간, Git Submodule을 고려하게 되는데요.

하지만 정말 Submodule이 최선일까요? 🤔

독립적인 프로젝트를 유지하면서 특정 버전 상태를 고정해야 한다면 Submodule이 적절할 수 있습니다.

하지만 코드 변경이 잦고, 최신 버전을 자주 반영해야 한다면 Subtree나 패키지 매니저(npm, pip 등)가 더 나을 수도 있습니다.

이제 Git Submodule의 개념과 활용법, 그리고 실제 MSA(Microservices Architecture)에서 어떻게 활용할 수 있는지 알아보겠습니다.

⸻

MSA에서 Git Submodule을 활용하는 방법

✅ Submodule이 적절한 경우

MSA 환경에서는 여러 개의 독립적인 서비스가 협력하여 하나의 시스템을 구성하는데요. 각 서비스가 공통된 코드를 유지하면서도 독립적으로 운영되길 원할 때, Git Submodule이 유용할 수 있습니다.

📌 예제: 공통 유틸리티를 여러 마이크로서비스에서 공유하는 경우

** 상황**

• MSA에서는 여러 개의 마이크로서비스(예: user-service, order-service, payment-service)가 존재합니다.
• 모든 서비스에서 공통된 유틸리티 코드(common-utils)를 사용해야 합니다.
• 각 서비스가 이 공통 유틸리티를 특정 버전으로 유지해야 합니다.

해결 방법

• 각 마이크로서비스에서 공통 유틸리티를 Git Submodule로 추가하면, 각 서비스는 독립적으로 개발되면서도 특정 버전의 common-utils를 유지할 수 있습니다.

  각 마이크로서비스에서 공통 유틸리티를 서브모듈로 추가

  cd user-service
  git submodule add https://github.com/company/common-utils.git libs/common-utils
  git commit -m "Add common-utils submodule"

  cd ../order-service
  git submodule add https://github.com/company/common-utils.git libs/common-utils
  git commit -m "Add common-utils submodule"

• 이렇게 하면 common-utils는 각 마이크로서비스의 독립적인 폴더로 존재하지만, 변경이 필요하면 한 번의 업데이트로 모든 서비스에 반영할 수 있습니다.

  • 각 서비스는 특정 버전의 common-utils를 유지하면서 필요할 때만 업데이트할 수 있습니다.

  공통 유틸리티 업데이트 (필요할 때만)

  cd libs/common-utils
  git pull origin main
  cd ../..
  git add .
  git commit -m "Update common-utils to latest version"

⸻

❌ Git Submodule이 적절하지 않은 경우

MSA에서 Git Submodule을 사용하는 것이 비효율적인 경우도 있습니다.

• 공통 코드가 너무 자주 변경되어 모든 서비스에서 항상 최신 버전을 유지해야 할 때
• 공통 모듈이 아니라 단순 라이브러리라면, 패키지 매니저(npm, pip, maven)로 관리하는 것이 더 효율적
• 모든 마이크로서비스가 같은 저장소에 있는 모놀리식(monolithic) 프로젝트일 때

📌 예제: API 요청을 처리하는 공통 라이브러리가 있는 경우

상황

• api-client라는 공통 라이브러리가 있고, 모든 마이크로서비스(user-service, order-service, payment-service)에서 이 라이브러리를 사용해야 합니다.
• 이 라이브러리는 자주 변경되며, 모든 서비스에서 최신 버전으로 유지해야 합니다.

해결 방법

• 이 경우 api-client를 Git Submodule로 추가하는 것보다, 패키지 매니저(npm, pip, maven 등)를 활용하는 것이 더 적절합니다.

  패키지 매니저로 공통 라이브러리 관리 (예: npm)

  npm install @company/api-client@latest

  • 이렇게 하면 모든 마이크로서비스에서 최신 버전의 api-client를 자동으로 가져올 수 있어, Git Submodule을 사용하는 것보다 훨씬 편리합니다.

⸻

Git Submodule vs Git Subtree vs 패키지 매니저 비교

Git Submodule을 도입하기 전에, 비슷한 기능을 제공하는 다른 방법들과 비교해볼게요.

즉,

• Git Submodule은 독립적인 프로젝트를 포함해야 하지만, 코드 변경이 자주 일어나지 않는 경우 적절합니다.
• 코드 변경이 자주 일어난다면 Git Subtree나 패키지 매니저가 더 유용할 수 있습니다.

⸻

Git Submodule 사용법 요약

Submodule 추가

git submodule add <서브모듈_레포_URL> <서브모듈_디렉토리_경로>
git commit -m "Add submodule"

서브모듈이 포함된 프로젝트를 클론할 때

git clone --recurse-submodules <레포_URL>

or

git submodule update --init --recursive

서브모듈 업데이트

git submodule update --remote

서브모듈 삭제

git submodule deinit -f <서브모듈_디렉토리>
rm -rf .git/modules/<서브모듈_디렉토리>
git rm -f <서브모듈_디렉토리>
git commit -m "Remove submodule"

⸻

📌 결론: Git Submodule을 써야 할까?

Git Submodule을 쓰기 좋은 경우🤭

• 독립적인 프로젝트를 유지하면서도, 내 프로젝트에 포함해야 할 때
• 특정 외부 라이브러리를 고정된 버전으로 유지해야 할 때
• 변경이 자주 일어나지 않는 서브 프로젝트를 관리할 때

Git Submodule이 비효율적인 경우😵

• 코드 변경이 자주 발생하고, 최신 버전을 계속 유지해야 하는 경우
• 패키지 매니저(npm, pip, maven)로 쉽게 관리할 수 있는 라이브러리인 경우

⸻

Git Submodule, 여러분은 어떻게 생각하시나요?

Git Submodule을 써야 할까요? 아니면 Git Subtree나 패키지 매니저가 더 나을까요?

🎁 실수에서 배우는 Git 강의도 있어요!

혹시 Git 충돌, 되돌리기, 협업 브랜치 전략 등
이런 문제들을 실습 중심으로 차근차근 배우고 싶다면, 제가 실무 경험을 바탕으로 만든 강의도 참고해보세요!

• 되돌리는 감각: reflog, reset, revert, 안전한 push
• 협업 루틴: 브랜치 전략, PR 체크리스트, 보호 규칙
• 실습 레포 기반 시나리오 6종으로 직접 몸으로 익히는 흐름

🎬 강의 소개 영상: https://lnkd.in/gMWTUSf3
📌 수강 링크: https://lnkd.in/gVVBhJ4g
💸 오픈 기념 할인 중입니다!

에이전트가 코드는 잘 짜줘도,
버전 관리 습관은 우리가 만들어야 우리가 편해집니다.
이번 기회에 Git과 좀 더 친해져보세요. 🙂