🤖 이 글은 Claude Code을 활용하여 작성되었습니다.

캐싱을 설정했다. 그런데 토큰이 줄지 않았다.

Anthropic 문서를 보고 cache_control: { type: 'ephemeral' }을 추가했다. 코드도 정상 동작했다. 근데 캐시가 전혀 작동하지 않고 있었다는 사실을 한참 뒤에야 알았다. 이유는 단순했다. 위치가 틀렸다.

이 글은 그 버그를 발견하면서 정리한 Claude API 토큰 효율 개선 원칙들이다. Claude 채팅 기능을 붙이는 과정에서 직접 적용한 내용을 바탕으로 썼다.

TL;DR

• body-level cache_control은 Anthropic API가 에러 없이 무시하는 잘못된 위치다
• 캐싱은 system block 또는 messages content block에 붙여야 한다
• 캐시 브레이크포인트는 요청당 최대 4개로 제한된다
• 캐시 TTL은 5분이다 — "영구 캐시"는 없다
• 캐시 레이어 설계의 핵심은 "얼마나 자주 바뀌는가"를 기준으로 나누는 것
• 보내는 데이터 자체를 줄이는 것이 캐싱만큼 중요하다
• 모델을 작업 복잡도에 맞춰 분기하면 비용을 추가로 줄일 수 있다

1️⃣ 프롬프트 캐싱 — 위치가 전부다

동작 방식

Anthropic의 프롬프트 캐싱은 요청 전체를 캐싱하는 게 아니다. 특정 지점(breakpoint)까지의 컨텍스트를 서버에 저장해두고, 동일한 prefix가 오면 그 지점부터 이어서 처리한다.

캐시 브레이크포인트를 설정할 수 있는 위치는 두 곳이다. 단, 요청당 최대 4개까지만 설정할 수 있다. 4개를 초과하면 API 에러가 발생한다.

[system block]       ← cache_control 가능 ✅ (여러 블록 가능, 4개 한도 내에서)
[messages]
  user: ...
  assistant: ...     ← content block에 cache_control 가능 ✅
  user: 새 질문      ← 캐시 이후 (매번 새로 처리)

캐시는 브레이크포인트를 설정한 지점까지의 prefix를 서버에 보관한다. 보관 시간은 5분(TTL)이다. 5분 안에 동일한 prefix로 요청이 오지 않으면 캐시가 만료되어 다음 요청에서 다시 쓰기 비용을 지불해야 한다. 요청 빈도가 낮은 기능에는 캐싱 효과가 제한적이다.

잘못된 방식 vs 올바른 방식

// ❌ body-level — Anthropic이 에러 없이 무시함
const body = {
  model,
  messages,
  cache_control: { type: 'ephemeral' },  // 무효
}

// ✅ system block에 직접 붙이기
system: [
  {
    type: 'text',
    text: '정적인 지시사항...',
    cache_control: { type: 'ephemeral' },
  }
]

// ✅ messages content block에 붙이기
messages: [
  {
    role: 'assistant',
    content: [
      {
        type: 'text',
        text: '이전 응답...',
        cache_control: { type: 'ephemeral' },
      }
    ]
  },
  { role: 'user', content: '새 질문' }
]

API가 에러를 내지 않는다는 게 더 위험하다. 조용히 실패하기 때문에 한참 동안 캐싱이 작동한다고 착각할 수 있다.

히스토리 캐싱

채팅 히스토리를 캐싱하려면 마지막 assistant turn에 브레이크포인트를 설정한다. 매 요청마다 바뀌는 새 user 메시지 직전까지를 캐시하는 것이다. user 메시지에 걸면 질문이 바뀔 때마다 캐시가 무효화되므로 assistant turn이 적합하다.

const messages = history.map(({ role, content }, i) => {
  const isLastAssistant = role === 'assistant' && i === history.length - 2
  if (isLastAssistant && history.length >= 2) {
    return {
      role,
      content: [{ type: 'text', text: content, cache_control: { type: 'ephemeral' } }],
    }
  }
  return { role, content }
})

대화가 4턴 이상 쌓이면 캐시 히트가 발생하기 시작한다. 대화가 길어질수록 절감 효과가 커진다.

2️⃣ 캐시 레이어 설계 — 변경 빈도가 기준

캐싱을 제대로 설계하려면 프롬프트 구성요소를 변경 빈도에 따라 분리해야 한다.

변경 빈도가 다른 데이터를 하나의 블록에 묶으면, 가장 빠르게 바뀌는 것이 전체 캐시를 무효화한다.

채팅 시스템을 예로 들면 이렇다.

자주 바뀜 (캐싱 의미 없음)
├── 사용자 메시지
└── 처리 결과 요약 (실행마다 업데이트)

가끔 바뀜 (5분 내 반복 요청 시 히트 기대 가능)
└── 사용 가능한 데이터 목록 (추가/삭제 시만)

거의 안 바뀜 (요청 빈도가 높으면 캐시 히트율 높음)
└── 역할 정의 + 액션 형식 지시사항

이 분석을 바탕으로 system block을 3개로 분리했다. system block 2개 + messages 1개를 사용하므로 브레이크포인트 총 3개 — 4개 한도 내에 여유가 있다.

system: [
  // block 1: 역할·지시사항 — 거의 안 바뀜 → 캐시 포인트 1
  { type: 'text', text: staticInstructions, cache_control: { type: 'ephemeral' } },

  // block 2: 데이터 목록 — 추가/삭제 시만 무효화 → 캐시 포인트 2
  { type: 'text', text: dataList, cache_control: { type: 'ephemeral' } },

  // block 3: 처리 결과 — 실행마다 바뀜 → 캐싱 안 함 (여기 걸면 쓰기 비용만 발생)
  { type: 'text', text: resultSummary },
]
// messages 내 마지막 assistant turn → 캐시 포인트 3 (총 3/4 사용)

✅ 어차피 무효화될 데이터를 캐싱하면 캐시 쓰기 비용만 추가로 발생한다.

3️⃣ 보내는 토큰 줄이기 — 컨텍스트 최소화

캐싱이 "이미 보낸 토큰을 재활용"하는 방식이라면, 이건 애초에 보내는 토큰을 줄이는 방식이다. 두 가지를 병행해야 효과가 크다.

조건부 컨텍스트

모든 요청에 모든 정보를 넣을 필요가 없다. 필요한 맥락이 무엇인지 요청마다 판단해서 선택적으로 포함한다.

예를 들어, 아이템별 상세 위치 정보를 매 채팅마다 포함하고 있었다. 그런데 "공간 활용률 높이려면?" 같은 분석 질문에는 위치 정보가 전혀 필요하지 않다.

// 마지막 user 메시지에 이동 관련 키워드가 있을 때만 위치 정보 포함
const MOVE_KEYWORDS = ['이동', '옮겨', '위치', '배치', '모서리', 'move']

const needsPos = MOVE_KEYWORDS.some((k) => lastUserMsg.includes(k))
const summary = buildSummary(result, needsPos)

아이템 10개 기준 요청당 약 150~200 토큰 절약.

히스토리에서 처리된 데이터 제거

Claude 응답에 시뮬레이션 실행을 위한 action JSON이 포함되는 경우가 있다.

분석 결과입니다. 해당 아이템을 다른 위치로 이동하는 것을 추천합니다.
<action>{"type":"move_item","moves":[{"productName":"item-a","fromBoxIndex":1,"toBoxIndex":0,"anchor":"bottom-center"}]}</action>

이미 실행된 action은 다음 요청의 히스토리로 전송할 필요가 없다. assistant 메시지를 히스토리에 추가하기 전에 제거한다.

const cleaned = role === 'assistant'
  ? content.replace(/<action>[\s\S]*?<\/action>/g, '').trimEnd()
  : content

요청당 30~100 토큰 절약. action JSON이 복잡할수록 효과가 커진다.

히스토리 크기 동적 조정

모든 대화 유형에 동일한 히스토리 크기를 유지할 필요가 없다. 맥락이 많이 필요한 요청과 그렇지 않은 요청을 구분한다.

// 맥락이 중요한 요청: 이전 대화 유지 → 8개
// 단순 분석 질문: 최근 내용만으로 충분 → 4개로 절반 축소
const historyLimit = needsContext ? 8 : 4
const trimmed = history.slice(-historyLimit)

4️⃣ 모델 분기 — 작업 복잡도에 맞는 모델 선택

모든 요청이 같은 수준의 모델을 필요로 하지 않는다. 작업 복잡도에 따라 모델을 분리하면 비용을 크게 줄일 수 있다.

작업 유형별 모델 매핑

Haiku는 3.5 → 4.5 세대로 올수록 성능이 크게 올랐지만 가격도 상승했다. 단순 텍스트 요약이라면 구버전 Haiku도 충분하다. 모델 ID는 배포 시점에 따라 달라지므로 환경변수로 분리해두는 것이 좋다.

예를 들어 즉석 분석, 통계 리포트, 패턴 분석 요청은 action JSON을 생성할 일이 없다. 순수 텍스트 분석이다. 채팅만 정확한 JSON 생성이 필요하므로 Sonnet을 유지한다.

const modelMain = process.env.ANTHROPIC_MODEL        // Sonnet
const modelFast = process.env.ANTHROPIC_MODEL_FAST   // Haiku (미설정 시 Sonnet으로 fallback)
  ?? modelMain

// 채팅: action 정확도 필요 → main 모델
// 분석 전용: 순수 텍스트 → fast 모델
const model = type === 'chat' ? modelMain : modelFast

ANTHROPIC_MODEL_FAST를 설정하지 않으면 기존처럼 동작하므로 안전하게 점진적으로 적용할 수 있다.

5️⃣ 시스템 프롬프트 압축

캐싱을 가장 효과적으로 만드는 방법 중 하나는 캐싱 대상 자체를 줄이는 것이다. 시스템 프롬프트가 짧을수록 캐시 히트 조건이 단순해지고, 신규 요청에서 처리해야 할 토큰도 줄어든다.

압축 전

4. 아이템 이동 (컨테이너 변경 또는 위치 지정):
   <action>{"type":"move_item","moves":[{"itemName":"아이템명","fromIndex":0,"toIndex":1,"anchor":"bottom-center","rotation":"flat"}]}</action>
   anchor 값(선택): "bottom-front-left","bottom-front-right","bottom-back-left","bottom-back-right","bottom-center","top-front-left","top-front-right","top-back-left","top-back-right","top-center"
   anchor와 rotation은 생략 가능. 생략 시 알고리즘이 최적 위치/방향 선택.
   fromIndex/toIndex는 0-based. 같은 컨테이너 내 이동도 가능.
   복수 아이템 동시 이동 가능.

압축 후

4. 아이템 이동: <action>{"type":"move_item","moves":[{"itemName":"아이템명","fromIndex":0,"toIndex":0,"anchor":"bottom-front-left","rotation":"flat"}]}</action>
   anchor(선택): bottom/top + front/back + left/right/center 조합. 생략 시 알고리즘 자동 선택.
   fromIndex/toIndex는 0-based. 같은 컨테이너 내 이동 가능. 복수 이동 가능.

중요한 건 압축이 의미를 훼손하지 않아야 한다는 점이다. 예시 값을 하나 남기고 패턴을 설명하는 방식으로 토큰을 줄였다.

XML 태그 활용

Claude는 XML 구조를 잘 이해한다. 긴 지시사항을 줄임표로 압축하는 것보다 <rules>, <format>, <examples> 같은 태그로 구조화하면 토큰 효율과 응답 정확도를 동시에 잡을 수 있다.

// 비구조화 (압축해도 모델이 경계를 파악하기 어려움)
규칙: A를 하라. B는 하지 마라. 형식은 C다. 예시: ...

// XML 구조화 (구조가 명확해 모델 이해도 ↑, 불필요한 설명 제거 가능)
<rules>A를 하라. B는 하지 마라.</rules>
<format>C 형식을 따른다.</format>
<examples>...</examples>

적용 결과 요약

⚠️ 캐싱 제약사항 요약

• 브레이크포인트는 요청당 최대 4개. 초과 시 API 에러 발생
• 캐시 TTL은 5분. 5분 이상 간격으로 발생하는 드문 요청에는 효과 없음
• 캐싱이 적용되려면 프롬프트 최소 토큰 기준(약 1,024 토큰)을 충족해야 함

토큰 비용은 기능이 추가될수록 선형적으로 증가한다. 채팅에 히스토리가 쌓이고, 컨텍스트가 풍부해질수록 요청당 토큰이 늘어난다. 미리 설계하지 않으면 나중에 고치기 어렵다.

이 과정에서 배운 핵심은 두 가지다.

첫째, 캐싱은 "어디에 붙이는가"보다 "무엇이 얼마나 자주 바뀌는가"를 먼저 분석해야 한다. 변경 빈도가 다른 데이터를 하나의 블록에 묶으면, 가장 빠르게 바뀌는 것이 전체 캐시를 무효화한다.

둘째, "보내지 않는 것"이 "캐시 히트"보다 확실하다. 조건부 컨텍스트, 히스토리 정리, 히스토리 크기 조정은 캐싱과 독립적으로 항상 효과가 있다.

토큰 절약은 부수 효과다. 캐시 히트가 발생하면 대형 컨텍스트의 응답 속도가 눈에 띄게 줄어든다. 진짜 목적은 사용자 경험이다.

이전 글에서 Claude API의 구조를 정리했다. 모델이 토큰을 순차적으로 생성하기 때문에 SSE가 자연스러운 선택이라는 것, REST + SSE가 gRPC보다 단순한 이유, Transformer의 Attention이 입력 전체를 한 번에 참조해 어느 위치의 토큰이든 관계를 계산할 수 있다는 것.

이번엔 그 이해를 실제 서비스에 직접 붙이면서 생긴 일들이다. AI로 알고리즘을 제어하는 패턴, SSE 파싱 구현, 토큰 절약까지.

1️⃣ AI로 알고리즘을 제어하는 패턴

이 서비스에 Claude API를 붙인 이유는 하나다. 사용자마다 요구사항이 다르기 때문이다.

"이 항목은 우선순위를 높여주세요", "특정 조건은 제외해주세요", "균형을 맞춰주세요" — 알고리즘은 이런 자연어 요청을 처리할 수 없다. 스트리밍 채팅 화면을 넣은 이유가 여기 있다. 사용자가 채팅으로 원하는 배치 방식을 전달하면, AI가 그 의도를 해석해 알고리즘에 전달하는 구조다.

전체 요청 흐름은 이렇다:

[사용자 채팅 입력]
    ↓
[프론트엔드]  POST /api/analyze  { type: "chat", messages, result }
    ↓
[서버]        system 블록 구성, 히스토리 트리밍
    ↓
[Anthropic]   POST /v1/messages  → SSE stream
    ↓
[서버]        청크 버퍼링 → <action> 태그 감지 전까지 실시간 포워딩 → 태그 추출
    ↓
[프론트엔드]  텍스트 실시간 렌더링 + 액션 버튼 노출
    ↓
[버튼 클릭]   제약 조건 → 알고리즘 재계산

여기서 AI와 알고리즘의 역할을 명확히 나눌 필요가 있었다.

초기 배치는 알고리즘이 담당한다. 여러 물리적 제약 조건을 동시에 만족해야 하는 최적화 문제는 NP-hard다. 처음부터 LLM에게 좌표를 계산하게 하면 모든 제약 조건을 동시에 만족하는 결과를 보장할 수 없다.

수정 단계에서는 AI가 제약 조건을 생성하고, 알고리즘이 재계산한다. 사용자 요청을 AI가 해석해 구조화된 액션으로 변환하면, 알고리즘이 그 조건을 반영해 다시 배치를 계산한다. 다음 단계로는 알고리즘이 계산한 실제 좌표를 AI에게 전달해, AI가 특정 요소의 위치 조정을 직접 제안하는 방식도 고려하고 있다.

[초기 배치]  알고리즘 → 유효한 좌표
[수정 단계]  사용자 요청 → LLM 해석 → 제약 조건 생성 → 알고리즘 재계산
[다음 단계]  기존 좌표 → LLM 분석 → 위치 조정 제안 → 적용

LLM이 생성할 수 있는 액션의 범위를 정의한다:

type SimAction =
  | { type: "filter_options"; names: string[] }
  | { type: "apply_constraints"; constraints: ItemConstraint[] }
  | { type: "combined"; names?: string[]; constraints?: ItemConstraint[] };

interface ItemConstraint {
  itemName: string;
  mode: "prioritize" | "restrict" | "default";
}

LLM이 선택할 수 있는 범위를 좁힐수록 엉뚱한 출력이 줄어든다. 선택지는 처리 방식의 핵심 파라미터뿐이다. 현재 좌표 계산은 알고리즘이 담당하고, AI는 제약 조건 생성에만 관여한다.

<action> 태그로 텍스트와 액션을 동시에

구조화된 출력 방식에는 선택지가 있다.

커스텀 태그를 선택했다. <action> 태그가 응답 맨 끝에만 등장하기 때문에, 태그가 감지되기 전까지는 텍스트를 실시간으로 스트리밍하고 태그가 나타나는 순간부터만 누적한다. 스트리밍이 끝나면 파싱한 액션을 별도 이벤트로 전송한다. 텍스트 실시간 노출과 액션 버튼을 하나의 SSE 스트림에서 처리할 수 있다는 점이 이 방식의 핵심이다.

시스템 프롬프트에 형식을 명시한다:

응답 맨 끝에 반드시 아래 형식을 추가하세요.

<action>{"type":"apply_constraints","constraints":[{"itemName":"항목A","mode":"prioritize"}]}</action>

액션이 없으면: <action>null</action>
항목 이름은 최적화 결과에 나온 이름 그대로 사용하세요.

스트리밍이 완료된 후 전체 텍스트에서 태그를 추출한다:

function parseAction(fullText: string): { text: string; action: unknown } {
  const match = fullText.match(/<action>([\s\S]*?)<\/action>/);
  if (!match) return { text: fullText, action: null };

  const text = fullText.replace(/<action>[\s\S]*?<\/action>/, "").trimEnd();
  try {
    return { text, action: JSON.parse(match[1].trim()) };
  } catch {
    return { text, action: null }; // 파싱 실패해도 텍스트는 정상 노출
  }
}

버튼을 누르면 제약 조건을 알고리즘에 전달해 재계산한다. AI가 판단하고 알고리즘이 실행한다.

2️⃣ SSE 파싱 구현

이전 글에서 SSE는 "토큰이 생성되는 즉시 전달되는 방식"이라고 정리했다. 이를 받으려면 요청에 stream: true를 포함해야 한다. Anthropic API 호출 코드다:

const aiRes = await fetch("https://api.anthropic.com/v1/messages", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": process.env.ANTHROPIC_API_KEY,
    "anthropic-version": "2023-06-01",
  },
  body: JSON.stringify({
    model: "claude-opus-4-6",
    max_tokens: 512,
    stream: true,
    cache_control: { type: "ephemeral" },
    system: [...],
    messages: [...],
  }),
});

API 키는 서버 환경변수로만 관리한다. 클라이언트에 노출되면 키가 탈취될 수 있기 때문에, 브라우저에서 Anthropic API를 직접 호출하는 구조는 피해야 한다.

응답은 SSE 스트림으로 온다. 실제로 파싱하면 이렇게 된다:

const reader = aiRes.body!.getReader();
const decoder = new TextDecoder();
let buffer = "";

while (true) {
  const { done, value } = await reader.read();
  if (done) break;

  buffer += decoder.decode(value, { stream: true });
  const lines = buffer.split("\n");
  buffer = lines.pop() ?? ""; // 불완전한 마지막 줄은 다음 청크와 합침

  for (const line of lines) {
    if (!line.startsWith("data: ")) continue;
    const raw = line.slice(6).trim();
    if (raw === "[DONE]") continue;

    const event = JSON.parse(raw);
    if (
      event.type === "content_block_delta" &&
      event.delta?.type === "text_delta"
    ) {
      res.write(`data: ${JSON.stringify({ text: event.delta.text })}\n\n`);
    }
  }
}

lines.pop()으로 마지막 줄을 다시 buffer에 보존하는 것이 핵심이다. 네트워크 청크는 줄 경계와 무관하게 도착한다. 불완전한 마지막 줄을 버퍼에 남겨 다음 청크와 합쳐야 파싱 오류가 없다. 이전 글에서 SSE를 이론으로 이해했다면, 이 버퍼 처리가 그 이론의 실전 구현이다.

3️⃣ 토큰 절약

동작은 됐는데 비용이 문제였다. 채팅마다 시스템 프롬프트가 통째로 전송되고, 대화가 길어질수록 히스토리가 누적된다.

프롬프트 캐싱

시스템 프롬프트란 AI의 역할과 출력 형식을 지정하는 고정된 지시문이다. 사용자 메시지와 달리 매 요청마다 동일하게 전송된다. 기존엔 이것을 첫 번째 user 메시지에 임베딩했다.

// 기존 — 캐싱 불가. 메시지 배열이 매 요청마다 달라짐
messages: [
  { role: "user", content: `${systemPrompt}\n\n사용자: ${firstMessage}` },
  ...history,
];

Anthropic Messages API의 role은 user(사람)와 assistant(모델) 두 가지뿐이다. system은 별도 파라미터로 분리되어 있어 messages 배열에 들어갈 수 없다. 그래서 시스템 프롬프트를 messages에 넣으려면 첫 번째 user 메시지에 임베딩하는 수밖에 없었다.

이 방식은 캐싱이 불가능하다. Anthropic의 프롬프트 캐싱은 prefix가 고정되어야 작동하는데, 메시지 배열이 매 요청마다 달라지기 때문이다.

시스템 프롬프트를 system 파라미터로 분리하고, 변경 빈도가 다른 내용은 블록을 나눠 각각 breakpoint를 건다:

body.system = [
  // breakpoint 1: 역할 정의 + 액션 형식 — 서비스 내내 고정
  { type: "text", text: staticInstructions, cache_control: { type: "ephemeral" } },
  // breakpoint 2: 최적화 결과 컨텍스트 — 세션 내에서 고정
  { type: "text", text: resultContext, cache_control: { type: "ephemeral" } },
];

두 블록은 독립적으로 캐싱된다. 결과 컨텍스트가 바뀌어도 정적 지시문 캐시는 유지된다.

캐시 히트 시 해당 토큰 요금이 약 10%로 줄어든다. 모델마다 캐싱 가능한 최소 토큰이 다르고(Opus 4.6 기준 4096 토큰), 최솟값 미만이면 오류 없이 조용히 스킵된다. system 블록의 총 토큰이 기준 미만이면 캐싱 자체가 작동하지 않으므로, 적용 후 cache_read_input_tokens 값으로 실제 히트 여부를 확인해야 한다.

대화 히스토리 자동 캐싱

요청 최상위에 cache_control을 추가하면 대화가 길어질수록 히스토리도 자동으로 캐싱된다:

const body = {
  model, max_tokens: maxTokens, stream: true,
  cache_control: { type: "ephemeral" }, // 마지막 캐시 가능 블록에 자동 적용
  system: [...],
  messages: trimmedMessages,
};

매 턴마다 breakpoint가 자동으로 앞으로 이동한다. 대화가 쌓일수록 캐시에서 읽히는 비율이 높아진다.

히스토리 트리밍과 max_tokens 조정

// 최근 4턴(8개 메시지)만 유지
const trimmed = messages.slice(-8);

// 응답 유형별 상한 분리
const maxTokens = type === "report" ? 1024 : 512;

대화 맥락은 대부분 최근 몇 턴에 있다. context window는 유한하고, 누적될수록 토큰 비용도 선형으로 늘어난다. 히스토리 트리밍은 오래된 맥락을 버리는 대신 비용을 줄이는 가장 단순한 방법이다.

마무리

이전 글에서 정리한 개념 — SSE가 토큰 생성 구조와 맞는 이유 — 이 실제 구현에서 그대로 나타났다. 이 글에서 새로 다룬 프롬프트 캐싱도 마찬가지다. prefix가 고정되어야 캐시가 작동한다는 원칙은, 구조를 이해하지 못하면 왜 안 되는지조차 알기 어렵다.

구조를 이해하면 디버깅이 빨라진다. "왜 이렇게 설계됐는가"를 알면 "왜 이렇게 동작하는가"가 예측 가능해진다.

🤖 이 글은 Claude Code을 활용하여 작성되었습니다.

타이핑되듯 흘러나오는 응답. 그게 구현 편의가 아니라 모델의 작동 방식에서 비롯된 것이라면?

Claude API를 처음 쓸 때 대부분 스트리밍 여부를 옵션 정도로 생각한다. 하지만 stream=True 한 줄의 근거는 HTTP 프로토콜 선택을 넘어, 모델이 텍스트를 생성하는 구조 자체에 있다. 통신 계층부터 Transformer 추론까지, 하나의 요청이 완성되는 흐름을 분해한다.

TL;DR

• Claude API는 REST + JSON. gRPC 없음
• 응답은 일반(JSON 한 번에)과 스트리밍(SSE) 두 가지
• 스트리밍이 자연스러운 이유: 모델이 토큰을 하나씩 생성하기 때문
• Transformer의 Attention → Autoregressive 생성 → SSE 전송이 하나의 흐름

1️⃣ 통신 구조 — REST + SSE

Claude API는 HTTPS REST 기반이다. 모든 요청은 단일 엔드포인트로 수렴한다.

POST https://api.anthropic.com/v1/messages
Content-Type: application/json
x-api-key: sk-ant-...
anthropic-version: 2023-06-01

{
  "model": "claude-sonnet-4-6",
  "max_tokens": 1024,
  "messages": [
    {"role": "user", "content": "JWT와 세션 인증의 차이를 설명해줘"}
  ]
}

응답 방식은 두 가지다.

일반 응답 vs 스트리밍 응답

일반 응답은 완성된 JSON을 한 방에 받는다.

{
  "id": "msg_01XFDUDYJgAACzvnptvVoYEL",
  "content": [{"type": "text", "text": "JWT는 stateless..."}],
  "usage": { "input_tokens": 20, "output_tokens": 340 }
}

스트리밍 응답은 Server-Sent Events로 토큰이 생성되는 즉시 흘러나온다.

data: {"type": "content_block_delta", "delta": {"text": "JWT"}}
data: {"type": "content_block_delta", "delta": {"text": "는"}}
data: {"type": "content_block_delta", "delta": {"text": " stateless"}}
data: {"type": "message_stop"}

with client.messages.stream(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "JWT와 세션 인증의 차이를 설명해줘"}]
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

gRPC를 선택하지 않은 이유

LLM API의 통신 패턴은 단방향 요청-응답에 서버 푸시 스트림이 전부다. gRPC의 장점이 발휘될 자리가 없다.

WebSocket 등 다른 선택지도 있지만, SSE는 HTTP 위에서 동작해 별도 인프라 없이 어디서나 호출 가능하다는 점에서 가장 단순한 선택이 된다.

2️⃣ 모델 내부 구조 — 토큰이 만들어지는 과정

토큰: 모델이 보는 언어의 단위

Claude는 텍스트를 문자가 아닌 토큰 단위로 처리한다. 자주 등장하는 문자 조합을 하나의 토큰으로 묶는 방식으로, 사용하는 토크나이저에 따라 분리 방식이 달라진다.

"Hello, world!" → ["Hello", ",", " world", "!"]  (약 4토큰)
"안녕하세요"    → ["안녕", "하세", "요"]           (약 3토큰, 토크나이저마다 다름)

영어는 평균 4글자당 1토큰, 한국어는 구조상 토큰 밀도가 더 높은 편이다. 입력과 출력 모두 토큰 단위로 비용이 계산된다. max_tokens가 출력 토큰 수를 제한하는 파라미터인 이유가 여기 있다.

Transformer: 맥락을 읽는 구조

Claude는 Transformer 기반으로 알려진 대규모 언어 모델이다 (Anthropic이 내부 아키텍처를 공식 공개하지는 않았다). 핵심은 Attention 메커니즘으로, 입력된 모든 토큰이 서로 얼마나 관련 있는지를 동시에 계산한다.

입력: "주문이 완료되면 [?]을 발송한다"
                         ↑
         Attention이 "주문", "완료", "발송"과의 관계에
         높은 가중치를 부여하고, 이를 바탕으로
         모델이 "메일"을 높은 확률로 예측

Attention은 토큰 간 관계 가중치를 계산하는 레이어이며, 실제 다음 토큰 예측은 이후 FFN(Feed-Forward Network)과 Softmax 레이어가 담당한다. 이 계산이 컨텍스트 창 전체에 걸쳐 일어나기 때문에, 수만 줄의 코드베이스도 앞뒤 맥락을 고려한 답변이 가능하다.

자동 회귀 생성: 스트리밍이 자연스러운 이유

Claude가 텍스트를 생성하는 방식은 다음 토큰을 하나씩 예측하는 반복이다.

입력:   "JWT는"
1단계:  "JWT는" → 예측 → "stateless"
2단계:  "JWT는 stateless" → 예측 → "방식으로"
3단계:  "JWT는 stateless 방식으로" → 예측 → "..."

전체 응답을 미리 완성해두고 보내는 게 아니다. 토큰을 생성하는 즉시 전송하기 때문에 SSE가 이 구조와 정확히 맞물린다.

temperature와 top_p: 확률 분포를 조절하는 파라미터

각 단계에서 다음 토큰을 고를 때 확률 분포를 참조한다. temperature와 top_p는 이 분포를 조절하는 파라미터다.

실제 사용에서는 용도에 따라 명확히 나뉜다.

import anthropic

client = anthropic.Anthropic()

# 코드 생성 — 정확성 우선, 낮은 temperature
code_response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    temperature=0.1,  # 거의 결정적. 같은 입력 → 같은 출력
    messages=[{"role": "user", "content": "Python으로 이진 탐색 구현해줘"}]
)

# 블로그 초안 작성 — 다양성 우선, 높은 temperature
creative_response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    temperature=0.9,  # 매번 다른 표현. 창의적 글쓰기에 적합
    messages=[{"role": "user", "content": "Redis를 소개하는 블로그 도입부를 써줘"}]
)

두 파라미터를 동시에 설정할 때 적용 순서가 있다. temperature가 먼저 로짓(logits)의 날카로움을 조정하고, 그 결과로 만들어진 확률 분포에서 top_p가 후보군을 좁힌 뒤 최종 샘플링이 이루어진다. 일반적으로는 하나만 조정하는 것이 결과를 예측하기 쉽다.

컨텍스트 창: Attention이 참조하는 범위

Attention은 컨텍스트 창 안의 모든 토큰을 동시에 참조한다. Claude Sonnet 4.6과 Opus 4.6 모두 최대 1M 토큰을 지원한다 (2026년 3월 GA).

[시스템 프롬프트] [이전 대화 히스토리] [현재 질문]
|←──────────────── 컨텍스트 창 (1M 토큰) ────────────────→|

창이 가득 차면 오래된 내용부터 참조 불가 상태가 된다. Compaction API는 이 한계를 서버 사이드 요약으로 우회한다.

3️⃣ 전체 흐름 — 요청에서 응답까지

[클라이언트]
    │  HTTPS POST /v1/messages (JSON)
    ▼
[api.anthropic.com]
    │  1. 인증 확인 (x-api-key)
    │  2. 입력 토크나이징
    │  3. Transformer 추론 시작
    │     ├─ 토큰 생성 → SSE 전송 → [클라이언트] 표시
    │     ├─ 다음 토큰 생성 → SSE 전송 → [클라이언트] 표시
    │     └─ (max_tokens 도달 또는 EOS 토큰까지 반복)
    │  4. message_stop 이벤트 전송
    ▼
[연결 종료]

마치며

REST냐 gRPC냐의 선택은 프로토콜 취향이 아니다. 모델이 토큰을 하나씩 생성한다는 구조적 사실이 SSE를 가장 단순한 선택으로 만들고, SSE가 HTTP 위에서 동작한다는 점이 REST와 자연스럽게 맞물린다.

max_tokens를 어떻게 설정할지, 스트리밍을 쓸지 말지, temperature를 얼마로 줄지. 이 결정들은 API 옵션이 아니라 모델이 동작하는 방식에 대한 이해에서 나온다. 인터페이스를 외우는 것과 구조를 이해하는 것의 차이가 여기서 드러난다.

책을 읽고 거래소 시스템 구조를 정리하고, 핵심 개념인 Order Book과 매칭 로직을 Rust로 간단히 정리해 보았다.

거래소 시스템 전체 구조

일반적인 증권거래소 시스템은 다음과 같은 구조를 가진다.

Client
   ↓
Order Gateway
   ↓
Matching Engine
   ↓
Market Data
   ↓
Persistence

각 구성 요소의 역할은 다음과 같다.

Order Gateway

외부 클라이언트의 진입점이다.

• 주문 검증
• 인증
• Rate limit
• 내부 서비스로 라우팅

Matching Engine

거래소의 핵심 컴포넌트다.

• 주문을 오더북에 저장
• 매수/매도 주문 매칭
• 거래 체결

Market Data

체결 결과와 호가 정보를 외부에 전달한다.

예를 들어

• 실시간 호가
• 체결 가격
• 거래량

같은 데이터가 여기서 생성된다.

Persistence

거래 기록을 저장하는 계층이다.

• 거래 로그
• 주문 상태
• 감사 로그

실제 거래소에서는 이벤트 로그 기반 저장을 많이 사용한다.

대표적인 거래소 예로는

• NASDAQ
• 한국거래소

같은 시스템이 있다.

거래소의 핵심 — Order Book

거래소의 핵심 데이터 구조는 Order Book이다.

오더북은 체결되지 않고 대기 중인 주문을 관리하는 자료구조다.

주문은 두 가지로 나뉜다.

• Bid (매수 주문) — 높은 가격 우선
• Ask (매도 주문) — 낮은 가격 우선

매수(Bid) — 높은 가격 우선        매도(Ask) — 낮은 가격 우선
─────────────────────              ─────────────────────
100,500원  x 10주                  101,000원  x 5주
100,000원  x 20주                  101,500원  x 15주
 99,500원  x 5주                   102,000원  x 8주

체결은 다음 조건이 만족되면 발생한다.

매수 최고가 ≥ 매도 최저가

Price-Time Priority

대부분의 거래소는 Price-Time Priority 규칙을 사용한다.

우선순위는 다음과 같다.

1️⃣ 가격 우선 2️⃣ 시간 우선

예를 들어 같은 가격에 두 주문이 있다면

10:01 주문
10:03 주문

먼저 들어온 주문이 먼저 체결된다.

오더북 자료구조 설계

오더북에서 가장 중요한 연산은 두 가지다.

1️⃣ 최우선 호가 조회 2️⃣ 같은 가격 내 FIFO 유지

이 두 조건을 만족하기 위해 다음 자료구조를 사용했다.

pub struct OrderBook {
    bids: BTreeMap<Reverse<u64>, VecDeque<Order>>,
    asks: BTreeMap<u64, VecDeque<Order>>,
}

구조 선택 이유는 다음과 같다.

BTreeMap

• 키가 항상 정렬된 상태 유지
• 최우선 호가 접근이 쉬움

keys().next()

Reverse

Rust의 기본 정렬은 오름차순이다.

매수 주문은 높은 가격 우선이므로 Reverse로 뒤집는다.

VecDeque

같은 가격의 주문은 FIFO를 유지해야 한다.

push_back()
pop_front()

이 구조로 Price-Time Priority 규칙을 자연스럽게 구현할 수 있다.

주문 매칭 로직

매수 주문이 들어왔을 때 매칭 흐름은 다음과 같다.

1️⃣ 매도 측 최저가 확인 2️⃣ 가격 조건 확인 3️⃣ 체결 수량 계산 4️⃣ 주문 잔량 업데이트 5️⃣ 완전 체결 주문 제거

핵심 로직은 다음과 같다.

fn match_buy(&mut self, mut taker: Order) -> Vec<Trade> {

체결 가격은 항상 maker 주문 기준이다.

즉 먼저 들어온 주문의 가격으로 거래가 체결된다.

실제 거래소도 동일한 규칙을 사용한다.

서비스 통신 — gRPC 선택

서비스 간 통신 방식으로 REST 대신 gRPC를 사용했다.

매칭엔진처럼 대량의 주문을 빠르게 처리해야 하는 서비스에서는 JSON 직렬화 비용이 부담이 될 수 있다.

Protobuf는

• 더 작은 메시지 크기
• 빠른 파싱

이라는 장점이 있다.

proto — 서비스 계약

gRPC에서는 proto 파일이 서비스 계약(contract) 역할을 한다.

service MatchingEngine {
  rpc SubmitOrder(OrderRequest) returns (OrderResponse);
  rpc CancelOrder(CancelRequest) returns (CancelResponse);
  rpc GetOrderBook(Symbol) returns (OrderBookSnapshot);
}

이 파일 하나로

• 서버 코드
• 클라이언트 코드

가 자동 생성된다.

Rust에서는 tonic을 사용했다.

fn main() -> Result<(), Box<dyn std::error::Error>> {
    tonic_build::compile_protos("../proto/matching.proto")?;
    Ok(())
}

실제 거래소와의 차이

이번 구현은 구조 이해를 위한 간단한 실험이다.

실제 거래소 시스템은 훨씬 복잡하다.

예를 들어

• lock-free 자료구조
• 멀티 스레드 매칭
• shard된 order book
• event sourcing 기반 로그
• 초저지연 네트워크

같은 기술들이 사용된다.

마치며

증권거래소 시스템에서 가장 중요한 컴포넌트는 Matching Engine이다.

핵심은 복잡한 알고리즘보다 자료구조 설계에 있다.

이번 글에서는

BTreeMap + VecDeque

조합을 사용해 Price-Time Priority 기반 오더북 구조와 매칭 로직을 Rust로 정리해 보았다.

MCP 기반 구조에서 실행 흐름과 대화 상태는 어느 계층의 책임인가?

1. 전체 시스템 구조

MCP 기반 시스템은 단순 Client–Server 모델이라기보다 다음과 같은 계층 구조로 이해하는 편이 자연스럽다.

LLM (Inference)
        ↑↓
Orchestration Layer (Claude Desktop)
        ↑↓  JSON-RPC (MCP)
MCP Server (Tool Execution)
        ↑↓
External API

각 계층의 책임은 다음과 같이 구분된다.

• LLM

  • 컨텍스트 기반 응답 생성
  • Tool 호출 여부 결정

• Claude Desktop (Client)

  • 대화 이력(messages) 관리
  • 반복 호출 제어
  • MCP 통신 처리
  • 세션 수명 관리

• MCP Server

  • Tool 실행 및 결과 반환

• External API

  • 실제 데이터 조회 및 외부 연산 수행

따라서 Claude Desktop은 단순 UI가 아니라 실행 흐름을 조정하는 Orchestration Layer로 보는 것이 타당하다.

2. 연결 과정: Handshake

await mcpClient.connect(transport);

이 호출은 내부적으로 JSON-RPC 기반 초기화 절차를 수행한다.

Client                MCP Server
  │ initialize (req)       │
  ├───────────────────────▶│
  │ initialize (res)       │
  │◀───────────────────────┤
  │ initialized (notify)   │
  ├───────────────────────▶│

이 단계에서:

• 프로토콜 버전 협상
• Capability 교환
• 초기 상태 전이

가 이루어진다.

즉, MCP 연결은 단순 소켓 연결이 아니라 명시적 초기화 단계를 포함하는 상태 기반 프로토콜 과정이다.

3. MCP의 역할 범위

MCP는 JSON-RPC 기반 요청/응답 프로토콜이다.

• Request
• Response
• Notification

중요한 점은 다음이다.

MCP는 대화 맥락을 정의하지 않는다.

초기화 상태는 존재하지만, 사용자 대화 이력이나 컨텍스트 전략은 프로토콜의 책임 범위를 벗어난다.

따라서 MCP는 다음에 가깝다.

• Tool 실행을 위한 RPC 계층
• 구조화된 요청/응답 전달 메커니즘

4. 세션의 이중 구조와 Stateless 호출 모델

구현 과정에서 확인한 핵심은 “세션(Session)”이 단일 개념이 아니라는 점이다.

① Transport Session

• MCP 서버 프로세스의 수명
• JSON-RPC 연결 단위
• initialize 이후 유지되는 상태

② Conversation Session

• messages 배열의 수명
• LLM 호출 시 전달되는 컨텍스트 범위
• /reset으로 초기화되는 영역

여기서 중요한 기술적 배경이 있다.

Claude API 호출은 요청 단위로 상태를 유지하지 않는 구조에 가깝다. 매 호출 시 전체 대화 이력이 함께 전달된다.

messages = [
  user,
  assistant(tool_use),
  tool(result),
  assistant,
  ...
]

LLM은 내부적으로 대화 상태를 저장하지 않으며, 현재 턴에 필요한 모든 맥락은 messages 배열로 제공된다.

따라서 다음은 클라이언트의 책임이 된다.

• 대화 이력 유지
• 메시지 절단(truncation)
• 요약 전략
• 컨텍스트 윈도우 관리

정리하면:

Transport는 연결의 수명이고, Conversation은 맥락의 수명이다.

이 둘을 구분하면 구조가 명확해진다.

5. Agentic Loop의 제어 흐름

Claude의 Tool 사용 흐름은 단일 요청-응답 모델이 아니라, 클라이언트가 구성하는 반복 제어 구조 위에서 동작한다.

이를 추상화하면 다음과 같다.

User Input
   ↓
LLM 호출
   ↓
stop_reason 확인
   ├─ tool_use → Tool 실행 → 결과를 messages에 추가
   └─ end_turn → 종료
   ↓
반복

각 계층의 책임은 다음과 같이 분리된다.

• LLM

  • Tool 사용 여부 결정
  • 다음 단계 의도 생성

• Client

  • stop_reason 해석
  • MCP 서버 호출
  • messages 업데이트
  • 반복 여부 제어

• MCP Server

  • 순수 Tool 실행

중요한 점은, 반복 로직은 LLM 내부가 아니라 Orchestration Layer에서 구성된다는 것이다.

정리

1편에서는 Execution Layer(MCP Server)를 분석했다. 이번 글에서는 Orchestration Layer의 구조적 책임을 살펴봤다.

핵심은 다음 세 가지다.

1. MCP는 Tool 실행을 위한 RPC 계층이다.
2. 실행 흐름은 Client가 구성하는 Agentic Loop 위에서 동작한다.
3. Conversation 상태는 LLM이 아니라 클라이언트 계층에서 관리된다.

1. LLM은 왜 외부 시스템을 모를까?

LLM은 학습 시점까지의 정적 데이터만을 기반으로 동작한다. 따라서 다음과 같은 정보에는 접근할 수 없다.

• 현재 DB 상태
• 실시간 배포 현황
• GitHub 이슈 목록
• 내부 비즈니스 데이터

기존에는 이러한 문제를 해결하기 위해 서비스별 맞춤 연동 코드를 작성해야 했다. 그러나 이 방식은 다음과 같은 한계를 가진다.

• 연동 방식이 서비스마다 상이함
• 재사용 불가능
• 클라이언트 종속적인 구현
• 표준 부재로 인한 확장성 부족

이 문제를 해결하기 위해 등장한 것이 MCP(Model Context Protocol)이다.

2. MCP의 설계 목적

MCP는 AI와 외부 시스템 간의 상호작용을 표준화하기 위한 프로토콜이다.

핵심 철학은 다음과 같다.

AI의 판단 영역과 실행 영역을 명확히 분리한다.

• AI(Claude)는 어떤 도구를 사용할지 판단한다.
• MCP 서버는 실제 실행만 담당한다.
• 프로토콜은 그 사이의 통신 규격을 정의한다.

이 설계는 확장성과 재사용성을 동시에 확보한다.

3. 프로토콜 구조: JSON-RPC 기반 설계

MCP는 JSON-RPC 2.0 위에서 동작한다.

{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { ... } }

모든 통신은 method 호출 형태로 이루어진다.

핵심 구성 요소

여기서 중요한 점은:

Tool 선택 로직은 서버에 존재하지 않는다.

Claude는 tools/list를 통해 메뉴를 받고, 각 Tool의 description과 inputSchema를 기반으로 호출을 결정한다.

즉, MCP 서버 설계에서 가장 중요한 요소는 명확한 description과 정확한 input schema 정의다.

4. Wikipedia MCP 서버 구현

실제 프로토콜 흐름을 확인하기 위해 Wikipedia API 기반 MCP 서버를 구현했다.

Tool 등록

server.registerTool(
  "search",
  {
    description: "Wikipedia에서 키워드로 문서를 검색합니다",
    inputSchema: {
      keyword: z.string(),
      lang: z.enum(["ko", "en"]).default("ko"),
    },
  },
  async ({ keyword, lang }) => {
    const url = `https://${lang}.wikipedia.org/w/api.php?action=query&list=search&srsearch=${encodeURIComponent(keyword)}&format=json&origin=*&srlimit=5`;
    const res = await fetch(url);
    const data = await res.json();
    const results = data.query.search.map((item, i) => `${i + 1}. ${item.title}`);
    return { content: [{ type: "text", text: results.join("\n") }] };
  }
);

Zod로 정의한 스키마는 JSON Schema로 변환되어 Claude에 전달된다. Claude는 이를 기반으로 arguments를 자동 구성한다.

서버는 “어떤 상황에서 search를 써야 하는지”를 판단하지 않는다. 그 판단은 전적으로 Claude의 역할이다.

5. 실제 프로토콜 흐름 분석

Inspector를 통해 확인한 호출 순서는 다음과 같다.

1. initialize
2. tools/list
3. tools/call

tools/list – 메뉴 제공

{ "method": "tools/list" }

서버는 사용 가능한 Tool 목록을 반환한다.

tools/call – 실행 요청

{
  "method": "tools/call",
  "params": {
    "name": "search",
    "arguments": { "keyword": "인공지능" }
  }
}

Claude는 inputSchema를 참고해 arguments를 자동 생성한다.

이 구조는 AI의 추론 능력을 활용하는 설계다. 서버는 로직을 최소화하고 실행 책임만 가진다.

6. Sampling: 양방향 상호작용

MCP의 흥미로운 기능 중 하나는 Sampling이다.

일반 흐름:

Claude → MCP 서버

Sampling 흐름:

MCP 서버 → Claude

서버가 데이터를 수집한 뒤, Claude에게 다시 요약·분석을 요청할 수 있다.

이는 데이터 수집 계층과 추론 계층을 분리하는 구조를 가능하게 한다.

7. Transport 계층: Stdio vs SSE

MCP 메시지 자체는 동일하지만, 전달 방식이 다르다.

중요한 점은:

Transport는 메시지 전달 방식일 뿐, 프로토콜 로직과는 무관하다.

이 설계는 프로토콜 계층과 네트워크 계층을 명확히 분리한다.

8. 설계적 인사이트

Wikipedia 서버를 구현하며 얻은 핵심 인사이트는 다음과 같다.

1. MCP는 단순 API 래퍼가 아니다.
2. AI 중심 설계를 전제로 한 프로토콜이다.
3. 서버 로직을 최소화할수록 유연성이 높아진다.
4. description 설계가 곧 UX 설계다.

즉, MCP 서버는 단순한 “백엔드 서비스”가 아니라 AI의 추론을 보조하는 실행 레이어에 가깝다.

결론

MCP는 AI와 외부 시스템 간의 상호작용을 표준화하는 프로토콜이다. JSON-RPC 기반 구조, Tool 중심 설계, Transport 분리 구조는 확장성과 재사용성을 고려한 설계다.

Wikipedia 서버 구현을 통해 확인한 것은 단순 사용법이 아니라, AI 중심 아키텍처가 어떻게 프로토콜 수준에서 설계되는지에 대한 이해였다.

1. 생태계의 변화와 이슈 분석

JPA 4.0 규격의 핵심은 관행적 코드를 표준 API로 대체하여 생산성과 성능을 개선하는 것입니다. Spring Data JPA는 이에 대응하기 위해 관련 이슈들을 생성중이었습니다.

🔍 분석한 주요 이슈 리스트

• #4141: 신규 정적 쿼리 어노테이션(@StaticQuery) 인프라 확장
• #4143: 신규 표준 API(getResultCount())를 활용한 페이징 최적화
• #4144: DTO 프로젝션 리라이팅 로직 개선 및 유연한 매핑 지원
• #4150: JPA 4.0 문법 변경에 따른 쿼리 파서 업데이트 (My Contribution)

첫 오픈소스 기여다보니, 먼저 가장 부담이 적은 #4150 부터 진행해보기로 했습니다.

2. #4150 해결 과정: CASE 문법 최신화

2.1 문제 정의 (Background)

이전 JPQL 사양에서 CASE 식은 반드시 ELSE 절을 포함해야 했으나, JPA 4.0부터는 ELSE 절이 선택 사항(Optional)으로 변경되었습니다. 생략 시 암묵적으로 NULL을 반환하도록 규격이 완화된 것입니다.

2.2 ANTLR4 문법 수정

Spring Data JPA는 쿼리 해석을 위해 ANTLR4 파서 생성기를 활용합니다. 사용자가 작성한 쿼리가 신규 사양을 준수하는지 판단하도록 Jpql.g4 및 Eql.g4 정의 파일을 수정했습니다.

[Grammar Refactoring]

// 수정 후: (ELSE scalar_expression)? 구문을 통해 ELSE 절을 Optional하게 변경
general_case_expression
    : CASE when_clause (when_clause)* (ELSE scalar_expression)? END ;

simple_case_expression
    : CASE case_operand simple_when_clause (simple_when_clause)* (ELSE scalar_expression)? END ;

ELSE 구문을 ()? 기호로 그룹화하여 처리함으로써, 파싱 단계에서의 Syntax Error를 제거하고 표준 규격을 수용했습니다.

3. Merged, Polished, and Backported

해당 Pull Request는 리뷰를 거쳐 메인 저장소에 병합(Merge)되었습니다.

그리고 메인테이너에 의해 백포트(Backport) 되었습니다.

*"Jakarta Persistence 4.0은 아직 정식 릴리즈 전인데, 이전 버전(Backport)에 들어가도 정말 괜찮은 걸까?"*

4. 표준, 구현체, 그리고 추상화의 관계

자바 데이터 접근 계층은 표준, 구현체, 추상화 라이브러리의 상호작용을 통해 발전합니다.

구현체 선행 (Running Code First): 표준 문서 확정 전이라도 Hibernate이 기능을 지원한다면, 프레임워크는 이를 수용해 생태계 정합성을 맞춥니다.

4.1 구현체(Hibernate)의 선행 지원 확인

분석 결과, 구현체인 Hibernate는 이미 2021년 6.0(Alpha) 설계 당시부터 SQL 표준 준수를 위해 CASE 문의 ELSE를 선택 사항으로 정의해 두었습니다.

[Hibernate HqlParser.g4 소스코드]

// Hibernate 6.0+ 에서는 이미 ELSE 절에 '?'(Optional)가 적용되어 있음
simpleCaseList
    : CASE expressionOrPredicate simpleCaseWhen+ caseOtherwise? END ;

4.2 기여의 가치: 기술적 단절(Mismatch) 해소

이번 기여의 핵심은 라이브러리 간의 규격 동기화에 있습니다.

• 현상: 엔진(Hibernate)은 이미 ELSE가 없는 쿼리를 실행할 수 있었으나, 상위 계층인 Spring Data JPA 파서의 구식 규격이 이를 가로막고 있었습니다.
• 해결: Spring Data JPA의 파서를 최신 표준에 맞춰 업데이트함으로써, 하부 엔진의 기능을 상위 프레임워크 수준에서 정상적으로 사용할 수 있도록 수정했습니다.

5. 정리를 마치며: 공급자의 시각을 얻다

이번 기여를 통해 얻은 핵심 수확은 라이브러리를 '공급자적 시각'에서 바라보게 된 점입니다.

• 선순환 구조의 이해: 우리가 당연시했던 기능들이 표준과 구현체의 긴밀한 상호작용 결과물임을 확인했습니다. 특히 백포트를 통해 생태계의 속도를 맞추는 오픈소스의 운영 방식을 체감했습니다.
• 기술적 공백의 보완: 익숙한 도구의 내부 구조를 파헤치며 이론적 공백을 채웠습니다. 낮은 난이도의 이슈로 시작한 점은 아쉽지만, 도구의 본질을 분석하고 기여로 연결한 경험 자체가 큰 성장이었습니다.

이번 경험을 발판 삼아, 앞으로는 프레임워크의 설계 철학까지 깊이 파고드는 기여자로 꾸준히 성장하겠습니다.

🔗 관련 Pull Request Support optional ELSE in CASE expressions (JPA 4.0) #4150

• Redis ZSET을 활용해 상품 일간 랭킹 시스템을 구현했다
• 조회수·좋아요·판매량을 10분 단위 time-bucket으로 집계해 노이즈를 줄이고 실시간성을 확보했다
• 캘린더 기준(00:00 시작) 일간 랭킹의 콜드 스타트 문제를 Carry Over 전략으로 완화했다
• 랭킹은 정확한 로그가 아니라, 상품 노출을 제어하는 시스템이라는 관점으로 설계했다

Redis의 ZSET 자료 구조를 활용해 실시간 상품 일간 랭킹 시스템을 구현하며 고민했던 설계 포인트를 정리합니다. 랭킹은 단순한 정렬 문제가 아니라, 시간 기준·집계 단위·안정성에 대한 선택의 연속이었습니다.

1️⃣ 일간 랭킹의 시간 기준

캘린더 기준 (00:00 ~ 23:59, KST)

vs Sliding Window 기준 (최근 24시간)

일간 랭킹의 기준은 크게 두 가지 방식으로 나눌 수 있습니다.

• 캘린더 기준

  • 날짜 단위로 데이터 관리가 명확
  • 일자별 랭킹 비교 및 이력 관리에 유리
  • 단점: 00시 시점에 랭킹 데이터가 거의 없는 콜드 스타트 문제 발생

• Sliding Window 기준 (최근 24시간)

  • 항상 충분한 데이터가 존재
  • 시간 경계에서의 데이터 왜곡이 적음
  • 단점: “오늘의 랭킹”이라는 개념이 모호해짐

처음에는 데이터 왜곡이 적고, 최근 24시간 기준이 더 합리적으로 보였습니다. 하지만 콜드 스타트 문제를 실제로 고민하고 일간 랭킹의 범위를 명확히 구분하기 위해, 이번 구현에서는 캘린더 기준(00:00 시작)의 일간 랭킹을 선택했습니다.

2️⃣ 시간의 양자화와 이벤트 집계 단위

랭킹 시스템에서 중요한 질문 중 하나는 다음과 같습니다.

연속적으로 발생하는 이벤트를 어떤 시간 단위로 끊어 집계할 것인가?

• 1분 단위 집계

  • 세밀한 계산 가능
  • 하지만 작은 변동이나 노이즈 이벤트까지 모두 반영되어 랭킹이 불안정해질 수 있음

• 너무 큰 단위 집계

  • 랭킹은 안정적
  • 하지만 실제 의미 있는 급등·급락이 늦게 반영됨

이 두 극단 사이에서, 노이즈는 완만하게 흡수하면서도 의미 있는 변화는 반영할 수 있는 단위로 10분 단위(time-bucket) 집계를 선택했습니다.

추후 10분 단위 데이터를 기반으로 시간 감쇠(Time Decay) 모델을 적용해 급상승 상품·브랜드 랭킹으로 확장할 수도 있습니다.

product_views:{productId}::{yyyyMMddHHmm}
product_likes:{productId}::{yyyyMMddHHmm}
product_sales:{productId}::{yyyyMMddHHmm}

• TTL: 2일
• 이벤트는 commerce-api에서 Kafka로 발행된 시각(event time) 기준으로 bucket에 귀속
• 실시간 계산에 필요한 최소한의 데이터만 Redis에 유지

3️⃣ Redis → DB 영속화 전략

이벤트는 eventTime 기준으로 처리되기 때문에,

“12:00에 배치가 실행되었다고 해서, 12:00까지 발생한 모든 이벤트가 이미 집계되었다고 보장할 수는 없다.”

이 문제를 해결하기 위해 변화량(delta) 기반 영속화 방식을 선택했습니다.

처리 흐름

1. 이벤트 발생 시

   • 조회수 / 좋아요 / 판매량을 Redis bucket에 증가

2. 배치 실행 시

   • "product_likes:*" 와 같은 패턴으로 Redis SCAN 조회

   • redisTemplate.getAndDelete(key) 사용

     • 읽기와 삭제를 동시에 처리
     • 중복 집계 방지

3. DB에는 delta update 방식으로 누적 저장

이 방식으로,

• 집계 시점과 이벤트 발생 시점의 불일치 문제를 완화하고
• 절대적인 시각 일치보다는 일관된 증가량 반영에 집중했습니다.

4️⃣ 실시간 상품별 일간 랭킹 Redis 집계

집계된 지표를 기반으로, 상품별 인기도 점수를 계산해 일자 단위 ZSET에 저장합니다.

ranking:all:{yyyyMMdd}

VIEW_WEIGHT  = 0.1
LIKE_WEIGHT  = 0.2
ORDER_WEIGHT = 0.6
TTL_DAYS     = 2

점수는 가중치 기반으로 계산되며, ZSET의 score를 증가시키는 방식으로 반영합니다.

redisTemplate.opsForZSet()
    .incrementScore(rankingKey, productId.toString(), score);

• ZSET 특성을 활용한 자동 정렬
• 날짜별 키 분리로 랭킹 범위 명확화
• TTL을 통한 자연스러운 데이터 정리

5️⃣ Ranking API 구성

• 랭킹 목록 조회

reverseRange(rankingKey, start, end)

• 상품별 랭크 조회

reverseRank(rankingKey, productId)

• 상품별 점수 조회

score(rankingKey, productId)

• 랭킹 멤버 수 조회

zCard(rankingKey)

6️⃣ 콜드 스타트 완화를 위한 Carry Over 전략

캘린더 기준 일간 랭킹의 가장 큰 문제는 00시 직후 랭킹 데이터가 거의 없다는 점입니다.

이를 완화하기 위해, 매일 23:50, 오늘의 랭킹 점수를 가중치 0.2로 감쇠하여 다음 날 랭킹 키에 미리 반영합니다.

• 전날 인기 상품의 자연스러운 노출 유지
• 00시 직후 랭킹 공백 완화
• 일간 랭킹의 연속성 확보

7️⃣ 정리하며

랭킹 시스템을 구현하다 보면, 로그처럼 모든 데이터를 정확히 기록해야 할 것 같은 유혹을 받게 됩니다.

하지만 랭킹은 로그 시스템이 아니라,

“인기 측정기”가 아닌 “노출을 제어하는 시스템”

입니다.

• 일부 누락은 허용될 수 있고
• 절대적인 정확성보다
• 일관성, 안정성, 예측 가능성이 더 중요합니다.

추가로, 10분 단위 집계 데이터를 시간 감쇠(Time Decay) 모델에 적용해 ‘지금 뜨는 상품(Trending)’ 랭킹을 계산하는 방식으로 확장하여 롱테일 문제를 해결해 볼 수 있을 것입니다.

이번 설계는 “완벽한 집계”보다는 사용자가 신뢰할 수 있는 랭킹 경험을 목표로 한 선택들의 결과였습니다.

참고 https://dan.naver.com/25/sessions/681

Kafka를 도입한다는 것은 비즈니스 로직과 후속 처리 로직을 분리하겠다는 설계 선택이다.

이 선택은 다음과 같은 변화를 만든다.

• 하나의 트랜잭션 경계가 여러 컴포넌트로 분리된다
• 처리 시점이 비동기적으로 분리된다
• 실행 순서와 재시도 타이밍을 애플리케이션이 직접 통제할 수 없게 된다

Kafka는 기본적으로 at-least-once 전달 방식을 사용한다. 이 말은 곧,

메시지 유실 가능성을 줄이는 대신 중복 처리 책임을 Consumer에게 위임한다

는 의미다.

따라서 Kafka 기반 시스템에서는 다음과 같은 상황이 정상 동작 범위로 발생할 수 있다.

• producer retry로 인한 중복 전송
• consumer 장애 후 재시작
• offset commit 이전 성공 처리
• rebalancing으로 인한 재처리

즉, Kafka를 사용하는 순간부터 시스템은 중복 이벤트를 예외가 아닌 전제 조건으로 두고 설계해야 한다.

2. Kafka에서 발생하는 두 가지 중복

Kafka 중복 이벤트는 성격이 다른 두 종류의 중복이 존재한다.

2-1. 이벤트 자체의 중복 (eventId 기준)

같은 eventId를 가진 이벤트가 여러 번 소비됨

발생 원인

• producer retry
• consumer rebalancing
• offset rollback
• 장애 후 재처리

이 경우는 기술적인 중복이다. 같은 이벤트가 여러 번 전달되었을 뿐, 비즈니스 의미는 동일하다.

2-2. 비즈니스 의미의 중복 (aggregate 기준)

같은 주문 / 같은 좋아요 / 같은 재고 차감이 두 번 반영됨

특징

• eventId는 서로 다를 수 있다
• 하지만 같은 비즈니스 행위가 두 번 처리된 결과를 만든다

이 중복은 단순 전달 문제가 아니라, 도메인 규칙이 깨지는 상황이다.

3. 핵심 원칙: Consumer는 “결과적으로” 멱등해야 한다

흔히 다음과 같은 원칙을 이야기한다.

Consumer는 항상 멱등해야 한다

이 문장은 어떤 의미를 가지고 있을까

❓ 좋아요 +1, 재고 -1 같은 로직은 멱등하지 않은데?

이 로직 자체는 본질적으로 비멱등이다.

따라서 이 원칙의 정확한 의미는 다음에 가깝다.

같은 이벤트가 여러 번 전달되더라도 최종 비즈니스 상태는 한 번만 반영되어야 한다

즉,

• 로직 자체가 멱등일 필요는 없고
• 중복 이벤트가 결과를 깨뜨리지 않도록 보호 장치가 있어야 한다

전략 1: eventId 기반 중복 제거 (Inbox / Dedup Table)

eventId는 어디서 생성해야 할까?

이벤트 발행 시점에 producer가 eventId를 생성한다.

초기에는 Auto Increment ID를 고려했지만, Outbox 패턴을 사용하면서 문제가 발생했다.

• Outbox insert 시점에는 eventId가 없음
• 이후 update 로직이 필요해짐
• 트랜잭션 흐름이 불필요하게 복잡해짐

그래서 producer에서 ID를 먼저 생성하는 방식으로 전환했다.

UUID vs ULID

Kafka + Outbox 환경에서는 다음 이유로 ULID가 특히 유리했다.

• Outbox 테이블에서 최신 이벤트 스캔 비용 감소
• DB 인덱스 locality 개선
• 이벤트 발생 흐름을 시간 기준으로 추적 가능

이벤트는 단순 식별자가 아니라, 흐름과 순서를 해석하기 위한 단서이기 때문이다.

처리 흐름

1. producer에서 eventId 생성
2. 비즈니스 트랜잭션과 함께 Outbox에 이벤트 저장
3. Kafka로 이벤트 publish
4. Consumer Inbox에 eventId 저장
5. eventId 기준 중복 여부 판단
6. 최초 이벤트만 비즈니스 로직 실행

이 방식은 다음과 같은 정합성 중심 도메인에 적합하다.

• 주문
• 결제
• 쿠폰
• 재고

전략 2: aggregateId 기반 멱등성

모든 중복 처리를 eventId 기준으로 할 필요는 없다.

경우에 따라 비즈니스 식별자 기준이 더 효율적일 수 있다.

언제 적합한가?

• 좋아요
• 팔로우
• 찜하기

예를 들어:

• 같은 userId + productId 조합의 좋아요 이벤트
• 이미 좋아요 상태라면 추가 집계를 하지 않는다

전략 선택 기준

4. Delta 이벤트 설계

추가로 좋아요, 조회수처럼 발생 빈도가 매우 높은 이벤트는 누적량만 업데이트 하는 이벤트를 설계할수 있다.

{ "delta": +1 }

Consumer는 단순 누적만 수행한다.

UPDATE product
SET like_count = like_count + :delta;

장점

• Kafka 메시지 수 감소
• DB 부하 감소

한계

• 중복 시 정확도 보장 어려움
• 보정(batch, snapshot) 전략 필요

현재 시스템에서는:

• 정확성이 더 중요하고
• 트래픽이 임계점에 도달하지 않았다고 판단하여

👉 단건 이벤트 방식을 유지했다.

5. Outbox 패턴과 중복 처리의 관계

Outbox 패턴은 종종 중복 처리까지 해결해준다고 오해된다. 실제로 초기 Producer 에서 중복을 제거하거나 변화량을 계산해 보내준다면, Customer 에서 더 빠른 처리가 가능하지 않을까 라는 생각아래, Outbox 에서도 중복을 제거를 시도하기도 했었다.

하지만 Producer에서 Outbox의 역할은 명확하다.

• 이벤트 유실 방지
• 트랜잭션 경계 보장

중복 방지는 아니다.

때문에 Outbox는 원자성 보장이 중요하다. 하나의 트랜잭션을 사용하여 주문 내역은 저장되었는데 이벤트가 누락되거나, 반대로 주문은 실패했는데 이벤트만 발행되는 모순이 발생하지 않도록 해야한다.

@Transactional
  public OrderInfo createOrder(CreateOrderCommand command) {
    // 비즈니스 로직
    Order order = Order.create(command.userId(), createOrderItems(command.orderItemRequests(), products), command.couponIssueId());
    Order savedOrder = orderService.save(order);

    // 한 트랜잭션으로 Outbox 저장
    OrderCreatedEvent orderCreatedEvent = new OrderCreatedEvent(
        savedOrder.getId(),
        command.userId(),
        command.couponIssueId(),
        command.cardType(),
        command.cardNo()
    );

    OutboxEvent savedOutboxEvent = outboxService.saveEvent(
        "Order",
        savedOrder.getId().toString(),
        "OrderCreated",
        orderCreatedEvent
    );

    return OrderInfo.from(savedOrder);
  }

Outbox + Consumer 멱등성

정리

• Kafka에서 중복은 장애가 아니라 설계 전제다
• 중복을 “막으려는 설계”보다
• 중복이 와도 안전한 설계가 중요하다

좋은 Kafka 설계란 중복 이벤트가 와도 시스템이 흔들리지 않는 설계다

Kafka 중복 처리는 기술 문제가 아니라, 도메인 성격에 맞는 멱등성 전략을 선택하는 문제다.

이 글에서는 기존에 하나의 트랜잭션 안에서 동작하던 주문 생성 로직을 Spring Application Event 기반으로 분리하며, 트랜잭션 안정성과 코드 구조 개선을 동시에 달성한 과정을 정리합니다.

⚙️ Spring Application Event란 무엇인가

Spring Application Event는 JVM 내부 메모리에서 동작하는 in-memory 이벤트 시스템입니다. 서비스 간 강한 결합을 줄이고 후속 로직을 별도의 이벤트 핸들러로 분리하는 데 효과적입니다. 단일 서버 환경에서는 구현이 간단하고 성능도 좋아 널리 사용하는 방식입니다.

다만 구조적으로 JVM 단일 인스턴스를 기반으로 하기 때문에 몇 가지 명확한 한계가 존재합니다.

🚫 Spring Application Event의 구조적 한계

Spring Event는 JVM 안에서만 처리되는 메모리 기반 이벤트이기 때문에 아래와 같은 제약을 갖습니다.

🔁 멀티 인스턴스 환경에서 이벤트가 여러 번 실행되는 문제

Spring Event는 인스턴스마다 독립적으로 존재하기 때문에 동일한 이벤트가 여러 인스턴스에서 각각 실행될 수 있습니다. “후속 처리가 단 한 번만 실행돼야 하는 로직”에는 적합하지 않습니다.

💥 장애 시 이벤트 유실

이벤트가 저장되지 않기 때문에 처리되기 전에 서버가 종료되면 해당 이벤트는 복구할 수 없습니다. 결제·정산·포인트 등 신뢰성이 중요한 영역에서 사용하기 어렵습니다. 이번 프로젝트에서는 우선 트랜잭션 분리를 목적에 두고 Spring Event를 사용했습니다.

🛠️ 주문 생성 트랜잭션 분리 과정

기존 주문 생성 로직은 다음과 같은 문제가 있었습니다.

• 주문 생성, 재고 차감, 포인트 차감, 쿠폰 처리, PG 요청이 모두 하나의 트랜잭션에 묶여 있음
• 후속 로직 오류(PG 요청 등)가 발생하면 주문 전체가 롤백됨
• 트랜잭션 시간이 불필요하게 길어짐
• 기능 확장 시 복잡도 증가

이를 해결하기 위해 주문 생성과 후속 처리(쿠폰, PG 요청)를 이벤트 기반으로 분리했습니다.

🧭 주문 처리 전략 선택 과정

모델 1 — “검증·점유 우선” (정합성 우선)

항공권/예약 시스템 등 정확성이 중요한 환경에서 사용하는 방식입니다.

모델 2 — “주문 먼저, 정합성 검증은 나중” (매출 우선)

트래픽이 높은 커머스에서 자주 사용하는 방식입니다.

🎯 선택한 방향: 모델 1 기반 + 후속 처리 이벤트 분리

서비스 특성상 아래 기준을 세웠습니다.

• 재고는 동시성 요구가 매우 강해 트랜잭션 내부에서 처리해야 합니다
• 쿠폰, 포인트, PG 요청은 후순위여도 무방합니다
• 주문 생성 자체는 PG 성공 여부와 관계없이 기록되어야 합니다

🏗️ 최종 구조

주문 생성은 본 트랜잭션에서 처리

@Transactional
public OrderInfo createOrder(CreateOrderCommand command) {
    List<Product> products = productService.getExistingProducts(
        command.orderItemRequests().stream()
            .map(CreateOrderCommand.OrderItemRequest::productId)
            .toList()
    );

    deductStock(command.orderItemRequests());

    Order order = Order.create(command.userId(), createOrderItems(command.orderItemRequests(), products));
    Order savedOrder = orderService.save(order);

    eventPublisher.publishEvent(new OrderCreatedEvent(
        savedOrder.getId(),
        command.userId(),
        command.couponId(),
        command.cardType(),
        command.cardNo()
    ));

    return OrderInfo.from(savedOrder);
}

핵심 의도

• 주문 생성과 재고 차감은 즉시 DB에 반영되어야 합니다
• 쿠폰/포인트/PG 요청은 주문 생성 이후에도 충분히 처리 가능합니다
• 후속 로직은 이벤트로 분리해 트랜잭션 영향도를 최소화했습니다

후속 로직은 별도 트랜잭션에서 처리

@TransactionalEventListener(phase = AFTER_COMMIT)
@Async
public void handleOrderCreated(OrderCreatedEvent event) {
    Order order = orderService.getOrder(event.orderId());

    Money originalPrice = order.getTotalPrice();
    Money finalPrice = couponService.useCouponById(
        event.couponId(),
        event.userId(),
        originalPrice
    );

    paymentService.requestPayment(event.orderId(), event.cardType(), event.cardNo(), finalPrice);

    eventPublisher.publishEvent(new OrderDataTransferEvent(
        event.orderId(),
        event.userId(),
        order.getStatus(),
        order.getTotalPrice().getAmount(),
        LocalDateTime.now(),
        "ORDER_CREATED"
    ));
}

왜 AFTER_COMMIT인가?

• 주문 생성 트랜잭션이 커밋된 이후 실행됩니다
• 후속 로직 실패가 주문 생성에 영향을 주지 않습니다
• 후속 작업만 자체적으로 롤백될 수 있습니다

❤️ 좋아요 집계 구조 개선 — 고빈도 이벤트 처리 최적화

좋아요 이벤트는 발생 빈도가 높아 각 요청마다 즉시 집계 테이블을 갱신하면 성능 부하가 커집니다.

이를 해결하기 위해 이벤트 기반 집계 + 디바운스 방식을 적용했습니다.

Long lastTime = lastProcessedTime.get(event.productId());
long currentTime = System.currentTimeMillis();

if (lastTime != null && (currentTime - lastTime) < debounceInterval) {
    return;
}

long actualLikeCount = likeService.getLikeCount(event.productId());
productListViewService.syncLikeCount(event.productId(), actualLikeCount);

lastProcessedTime.put(event.productId(), currentTime);

📌 정리

구조 개선을 통해 다음과 같은 효과를 얻었습니다.

• 주문 생성 트랜잭션이 짧아졌습니다
• 후속 작업 오류가 주문 생성에 영향을 주지 않습니다
• 좋아요와 같은 고빈도 이벤트의 처리 효율이 크게 향상되었습니다

다만 Spring Event는 근본적인 이벤트 플랫폼이 아니기 때문에 이벤트 유실·중복 처리 등 구조적 한계가 존재합니다. 이번 개편에서는 트랜잭션 분리와 코드 구조 개선을 주 목적에 두었으며, 추후 Kafka/RabbitMQ 등 MQ 기반 구조로 확장할 예정입니다.

PG 시뮬레이터를 로컬 PC(M1 Air)에서 실행하며, 실제 운영 환경에서 적용할 Failure Ready System을 어떻게 설계할지 수치 기반으로 정리했습니다.

PG Simulator 사양 요약

1. Timeout 설정

✔ Feign Connect/Read Timeout

connect-timeout

• 서버와 TCP 연결을 맺는 데 걸리는 시간
• PG 요청 지연 max = 500ms → 600ms로 설정

read-timeout

• 서버가 응답을 보내기까지 기다리는 시간
• PG 처리 지연 max = 5s → 6000ms 설정

✔ Resilience4j TimeLimiter

Feign timeout 외에 TimeLimiter는 전체 실행 시간을 제한한다.

특징:

• 호출 전체가 일정 시간을 넘기면 강제 취소
• fallback 가능
• CircuitBreaker 실패로 카운트됨

PG 처리 지연 max = 5s → timeout-duration = 5.5s (~6s) 설정

2. Retry 설정

✔ 요청 단계 성공률 기반 계산

PG 요청 성공률 = 60% → 즉, Retries가 너무 많으면 PG 자체 부하만 키움

Retry 성공률 증가 효과

→ 2회 → +24% → 3회 → +9.6% (효용 급감)

✔ Retry 부하 증가율

재시도는 성공률 증가보다 부하 폭증이 더 크다.

➡ 재시도 1회만 해도 부하가 40% 증가 → 실제로는 retry 를 하지 않는 것이 가장 현실적인 선택

3. CircuitBreaker 설정

PG 자체의 “정상적인 실패율”을 먼저 계산한다.

PG 성공률 =

요청 성공률 60% × 처리 성공률 70% = 42%

즉, 실패율:

100% - 42% = 58%

따라서 CircuitBreaker의 failure-rate-threshold 는 → 최소 65% 이상이 되어야 정상 실패를 차단하지 않음.

4. 로컬 PG Simulator 성능 측정 (wrk)

brew install wrk
wrk -t2 -c200 -d30s -s post.lua http://localhost:8082/api/v1/payments

post.lua

wrk.method = "POST"
wrk.body   = [[
{
  "orderId": "1351039135",
  "cardType": "SAMSUNG",
  "cardNo": "1234-5678-9814-1451",
  "amount": "5000",
  "callbackUrl": "http://localhost:8080/api/v1/payments/callback"
}
]]
wrk.headers["Content-Type"] = "application/json"
wrk.headers["X-USER-ID"]    = "135135"

✔ wrk 결과 해석 (PG 단독)

• TPS ≈ 300
• 평균 지연 ≈ 625ms
• Max latency = 2000ms
• Timeout = 202건

2초 정도의 지연은 사용자가 느끼기에 긴 시간으로 느껴지지 않아, Slow-call 기준을 다음처럼 설정:

slow-call-duration-threshold: 2000ms

PG 자체가 감당 가능한 처리량 = 약 300 TPS → 이 이상의 호출이 오면 PG가 먼저 병목됨

5. 결제 요청 API : Retry 적용 전/후 성능 비교

Retry 여부를 검증하기 위해 동일 조건에서 테스트함.

wrk -t2 -c200 -d30s -s post.lua http://localhost:8080/api/v1/payments

✔ Retry 1회 적용 시 비교

결과

• timeout·latency는 거의 변화 없음
• Non-2xx는 42% 감소 (큰 개선)
• 부하 증가는 아주 조금

➡ 따라서 retry 1회(max-attempts:2) 가 최적

최종 설정값

feign:
  client:
    config:
      pgClient:
        connect-timeout: 600 #PG 요청 지연 max = 500ms
        read-timeout: 6000 #PG 처리 지연 max = 5s
resilience4j:
  timelimiter:
    instances:
      pgTimeLimiter:
        timeout-duration: 5s #PG 처리 지연 max = 5s, read-timeout 보다 작은값
        cancel-running-future: true
  retry:
    instances:
      pgRetry:
        max-attempts: 2
        wait-duration: 1s
        retry-exceptions:
          - feign.RetryableException
        fail-after-max-attempts: true
  circuitbreaker:
    instances:
      pgCircuit:
        failure-rate-threshold: 65 # 요청 성공률 60% × 처리 성공률 70% = 42%, 실패율  58%
        slow-call-rate-threshold: 50
        slow-call-duration-threshold: 2s # Max latency = 2000ms
        permitted-number-of-calls-in-half-open-state: 30 # TPS 300 의 10~20%
        minimum-number-of-calls: 30 # 타임아웃 2s, TPS 300
        sliding-window-type: TIME_BASED # 트래픽 차이가 클경우, TIME_BASED
        sliding-window-size: 60 # 장애탐지가 중요하므로 작게
        wait-duration-in-open-state: 5s #회복하는데 걸리는 시간 기본 5s 적용
        automatic-transition-from-open-to-half-open-enabled: true
        record-exceptions:
          - feign.FeignException
          - org.springframework.web.client.HttpServerErrorException
          - java.io.IOException
          - java.util.concurrent.TimeoutException      

🔚 마무리

이번 글은 PG Simulator의 수치를 기반으로 Timeout, Retry, CircuitBreaker 값을 합리적으로 결정한 과정을 정리했습니다.

실제 운영 환경의 성능, 네트워크 품질에 따라 수치는 달라질 수 있어, 차후 실제 환경 부하 테스트를 통해 더 세밀한 수정이 필요합니다. 특히 위 방식이 로컬을 기준으로 측정된 값 + 제공된 PG 사양이 혼합되어 있지만, 수치를 기반으로 근거있는 결정을 해볼수 있었습니다.

1. 조회 목록 기능에서 고려해야 할 조건

• 브랜드별 상품 목록 조회
• 정렬 기준: 최신순, 가격순, 좋아요수
• 페이징: 페이지 단위로 결과 제공

목록 조회는 자주 발생하지만, 일부 조건(최신순, 좋아요순)에 따라 데이터 변경 빈도가 달라지므로 캐시 전략을 달리할 필요가 있었습니다.

2. 목록/상세 캐시 설계

2-1. 비정규화 테이블 생성

처음에는 상품 목록 조회 시, 상품 상세(Product) + 재고(Stock) + 좋아요수(Like)를 조회 시점에 조합하는 방식으로 개발했습니다.
조회/수정이 빈번한 좋아요 수로 인한 상품 조회/수정시 성능 이슈가 걱정 되어서 였습니다. 대신 캐시 설계시 비정규화 테이블을 생성하기로 결정했습니다.

• 문제: 매번 조회 시 조합해야 하므로 DB 부하가 발생
• 해결: 목록 조회에 최적화된 비정규화 테이블 ProductListView 생성
  • 좋아요수 포함
  • 목록 조회 시 바로 사용할 수 있음
  • 상세 캐시는 별도로 관리(ProductStock)

요약: 목록 조회는 비정규화 테이블, 상세 조회는 Product + Stock 조합

2-2. 목록/상세 캐시 분리 및 ID 기반 조합

처음 구현에서는 목록 캐시와 상세 캐시를 각각 생성되어있고, 총 좋아요 수 가 각 캐시에 저징되어 있어, 좋아요 수정시 목록/상세 캐시가 모두 업데이트 되어야만 하는방식이었습니다. 때문에 상품과 좋아요 캐시를 우선 분리하고, 목록 캐시에서 상세 캐시를 조합하는 방식으로 진행했습니다.

// 초기 캐시 구조
목록 캐시: product:list:{brandId}:{sort}:{page}:{size}
상세 캐시: product:detail:{productId}

• 문제: 좋아요수가 자주 변경될 경우, 모든 목록/상세 캐시를 삭제해야 함 → 성능 저하
• 해결: 목록 캐시는 ID 리스트만 캐싱하고, 상세 캐시는 ID 기준으로 조합하는 방식 진행

// 목록 조회 시 상세 캐시 조합 예시
List<ProductWithLikeCount> list = productIds.stream()
    .map(id -> {
        ProductStock stock = cacheRepository.get(id);
        if (stock == null) stock = getProductStock(id);
        LikeInfo like = likeCacheRepository.getLikeInfo(userId, id);
        return new ProductWithLikeCount(
            id,
            stock.product().getName(),
            stock.product().getPrice().getAmount(),
            like.likeCount()
        );
    }).toList();

* 장점:

  1. 상세 캐시 미스가 있어도 전체 목록을 DB에서 재조회하지 않음
  2. 좋아요수 변경 시 페이지별 캐시를 일일이 삭제할 필요 없음
  3. 캐시 효율과 데이터 최신성을 모두 고려 가능

3. 상세 캐시 미스 처리

• 목록 ID 리스트 캐시는 존재하지만, 일부 상세 캐시(ProductStock)가 없는 경우
• 각 ID 마다 상세 조회가 일어남
• 해결 방법: 해당 페이지의 상세 캐시가 없는 ID만 DB 조회 및 캐싱

List<Long> missIds = productIds.stream()
    .filter(id -> cacheRepository.get(id) == null)
    .toList();

if (!missIds.isEmpty()) {
    List<ProductStock> stocks = missIds.stream()
        .map(id -> getProductStock(id))
        .toList();
    stocks.forEach(stock -> cacheRepository.save(stock, DETAIL_TTL));
}

4. 페이지 단위 TTL 전략

각 목록별 특징을 고려해 페이지 마다 다른 TTL 전략을 고려했습니다.

• 최신순(latest):

  • 신규 데이터 추가 시 1페이지는 즉시 변경됨 → 1분
  • 뒤로 갈수록 변화 영향이 매우 적음 → TTL 증가 가능

• 좋아요순(likes_desc):

  • 좋아요는 실시간으로 변하지만 1페이지만 영향 큼
  • 뒤쪽 페이지는 순위 변동률이 낮음 → 2분 유지

• 가격순, 기본

  • 데이터 변경 자체가 거의 없음 → TTL 길게(10분 이상)

private Duration getListTtl(String sort, int page) {
    if ("latest".equals(sort)) {
        if (page == 0) return Duration.ofMinutes(1);
        if (page <= 4) return Duration.ofMinutes(2);
        return Duration.ofMinutes(5);
    } else if ("likes_desc".equals(sort)) {
        if (page == 0) return Duration.ofMinutes(1);
        return Duration.ofMinutes(2);
    }
    return Duration.ofMinutes(10);
}

5. 좋아요수 캐시 전략

• 좋아요수는 수정이 빈번한 데이터로 언제 DB에 저장하더라고 해당 데이터가 가장 정확한 데이터라고 보장 받을수 없습니다.
• 캐시에서 먼저 증가/감소 후, DB는 추후 배치로 저장 예정
• 배치 개발 전에는 순서를 맞추기 위해 캐시 → DB 저장 구조로 개발
• 키 구성:

사용자별 좋아요 여부: product:liked:{userId}:{productId}
상품별 좋아요 수: product:likeCount:{productId}

• 장점: 높은 읽기 트래픽에서 캐시 성능 보장, DB 부담 최소화

6. 현 구조의 문제점 및 추가 개발 사항

• 배치를 통한 DB 저장, 동기화 로직 추가 필요.
• 추가 캐시 TTL 전략 고려, 인기 상품 TTL 연장, 저빈도 브랜드 캐시 주기적 삭제 등 고려 가능
• 캐시 미스시 id 리스트 전체 조화로 수정

7. 정리

1. 비정규화 테이블로 목록 조회 최적화
2. 목록/상세 캐시 분리 → ID 리스트 기반 조합
3. 상세 캐시 미스는 해당 ID만 조회, 전체 재조회 방지
4. 페이지 단위 TTL 전략 적용
5. 좋아요수는 캐시 우선 → 배치 DB 저장

이번 설계를 통해, 읽기 최적화 + 캐시 효율 + 변경 데이터 처리 문제를 모두 고려해볼수 있었습니다.

TL;DR 이커머스 시스템에서 주문이 발생하면 재고 차감과 포인트 차감이 동시에 일어납니다. 여러 사용자가 동시에 주문을 요청할 때 데이터 정합성을 보장하기 위해 비관적 락을 적용했지만, 예상치 못한 문제가 발생했습니다. 이 문제를 분석하고 해결한 과정을 정리했습니다.

1. 배경: 동시성 제어가 필요한 이유

동시성 문제의 예시

• 재고가 1개 남았는데 10명이 동시에 주문한다면?
• 포인트가 100원 남았는데 여러 주문에서 동시에 차감한다면?

동시성 제어 없이는 재고를 초과한 주문이나 마이너스 포인트가 발생할 수 있습니다.

비관적 락을 선택한 이유

주문 시스템에서 사용할 수 있는 동시성 제어 방식은 크게 두 가지입니다.

낙관적 락(Optimistic Lock)

• 충돌이 드물 것이라 가정하고 자유롭게 작업
• 커밋 시점에 충돌 검사 후 문제가 있으면 롤백
• 충돌 시 재시도 비용 발생

비관적 락(Pessimistic Lock)

• 충돌이 발생할 것이라 가정하고 미리 락을 획득
• 다른 트랜잭션의 접근을 원천 차단
• 성능은 낮지만 데이터 정합성 보장

주문 시스템에서는 비관적 락을 선택했습니다.

선택 이유:

1. 재고와 포인트는 데이터 정합성이 매우 중요한 데이터
2. 잘못된 데이터로 인한 비즈니스 손해가 심각할 수 있음
3. 성능 문제는 재고와 포인트를 상품/유저와 분리하여 완화

2. 문제 발견: 동시성 테스트 실패

테스트 시나리오

10포인트를 가진 사용자가 4원짜리 상품(재고 10개)을 10번 동시에 주문합니다.

예상 결과

• 2건 성공 / 8건 실패 (포인트 부족)
• 총 8원 차감
• 최종 상태: 재고 8개, 남은 포인트 2원

실제 결과

실패 건수: 0
남은 재고: 0개
남은 포인트: 2원

모든 주문이 성공했습니다. 재고는 정상적으로 차감되었지만, 포인트는 10건 모두 정상 실행되었는데도 오류가 발생하지 않았습니다.

로그를 확인한 결과:

• 포인트 조회 시 10 → 6 업데이트 후에도 계속 10포인트로 조회됨
• 이후 어느 순간부터 6 → 2로만 조회되어 오류 없이 완료

쿼리문에 비관적 락은 제대로 동작하고 있지만 조회 포인트가 업데이트 되지 않고 있었습니다.

원인 분석 1: MySQL의 동시성 제어

문제를 이해하기 위해 먼저 사용하고 있는 MySQL의 동작 방식을 알아봤습니다.

Repeatable Read와 MVCC

MySQL InnoDB의 기본 격리 수준은 Repeatable Read이며, MVCC(Multi-Version Concurrency Control)로 동시성을 제어합니다.

MVCC의 핵심 개념:

• 각 레코드를 여러 버전으로 관리 (undo log 활용)
• 트랜잭션마다 읽는 데이터의 "스냅샷 버전"이 다를 수 있음
• 동시 접근 시에도 블로킹 없이 각자의 버전을 읽음

SELECT FOR UPDATE의 특별한 동작

여기서 중요한 포인트가 있습니다.

SELECT FOR UPDATE는 MVCC 스냅샷을 무시하고 항상 최신 커밋된 데이터에 락을 겁니다.

즉, Repeatable Read 격리 수준이더라도 SELECT FOR UPDATE, UPDATE, DELETE 같은 쓰기 락 작업은 마치 Read Committed처럼 동작합니다.

그렇다면 SELECT FOR UPDATE도 최신 데이터를 조회해야 정상인데, 왜 오래된 데이터가 조회되었을까요?

원인 분석 2: User findById가 문제였다

의심스러운 코드 발견

Optional<User> user = userRepository.findById(command.userId());

포인트를 조회하는 곳에서 User.getPoint()를 직접 호출하는 곳은 없었습니다. 유일하게 Point와 연관되는 곳은 주문 생성 전 해당 객체들의 존재 여부를 확인하기 위해 조회되던 userRepository.findById 밖에 없었습니다.

User 객체가 실제로 필요한 곳이 없어, 해당 구문을 주석 처리하고 테스트를 실행했습니다.

테스트가 성공했습니다!

userRepository.findById로 조회된 user를 사용하지 않고 조회 여부만으로 테스트의 결과가 달라지고 있었습니다. 조회만으로 1차 캐시가 생성되고, 이후 Point 조회 시 SELECT FOR UPDATE 값보다 1차 캐시의 값이 우선적으로 리턴되고 있는 상황이었습니다.

원인 분석 3: JPA 1차 캐시의 함정

JPA 1차 캐시와 SELECT FOR UPDATE의 충돌

JPA의 영속성 컨텍스트는 엔티티를 조회하면 1차 캐시에 저장합니다. 그리고 동일 트랜잭션 내에서 같은 엔티티를 다시 조회하면 DB를 거치지 않고 1차 캐시의 값을 반환합니다.

여기서 핵심은 "DB를 거치지 않는다"는 점입니다.

MySQL과 JPA는 서로 다른 레벨에서 동작한다

앞서 설명한 MySQL의 MVCC와 SELECT FOR UPDATE는 데이터베이스 레벨의 이야기입니다. 반면 JPA 1차 캐시는 애플리케이션 레벨의 이야기입니다.

문제의 핵심:

1. 🔄 userRepository.findById() 호출 → User 엔티티가 1차 캐시에 저장됨
2. 🚫 이후 SELECT FOR UPDATE로 Point를 조회하려 해도 → DB 쿼리가 아예 실행되지 않음
3. ⚠️ DB에서 최신 버전을 읽을 기회 자체가 없어짐
4. ❌ 결과: 1차 캐시에 있는 "오래된 값"이 그대로 반환됨

즉, MySQL의 SELECT FOR UPDATE가 아무리 최신 데이터를 가져오려 해도, JPA가 DB 조회 자체를 차단하기 때문에 무용지물이 되는 상황입니다.

주석 처리한 코드가 왜 문제를 해결했을까?

// Optional<User> user = userRepository.findById(command.userId()); // 주석 처리

이 한 줄을 주석 처리했더니 테스트가 통과했습니다. 그 이유는:

• 주석 처리 전: findById()로 User를 조회 → Point도 함께 1차 캐시에 저장 → 이후 SELECT FOR UPDATE가 DB에 가지 않음
• 주석 처리 후: User 조회를 하지 않음 → Point가 1차 캐시에 없음 → SELECT FOR UPDATE가 실제로 DB에서 최신 데이터를 가져옴

결국 불필요한 User 조회가 1차 캐시를 오염시켜, 비관적 락의 동작을 무력화시킨 것입니다.

원인 분석 4: 왜 Point까지 1차 캐시에 들어갔을까?

새로운 의문점

여기서 의문이 생깁니다. userRepository.findById()로 User만 조회했는데, 왜 Point까지 1차 캐시에 저장되었을까요?

User와 Point는 @OneToOne 관계로 연결되어 있고, fetch=LAZY로 설정되어 있습니다. LAZY 로딩이라면 Point는 실제로 사용되는 시점에만 조회되어야 합니다. 즉, user.getPoint()를 명시적으로 호출하지 않는 한 Point는 1차 캐시에 들어가지 않아야 정상입니다.

그런데 실제로는 Point도 함께 조회되어 1차 캐시에 저장되고 있었습니다. 왜 그럴까요?

LAZY로 설정했는데 EAGER로 동작하는 이유 확인

의심이 든 부분을 검증하기 위해 테스트 코드를 작성했습니다. findById(User) 시, Point 객체가 LAZY/EAGER 중 어떤 방식으로 조회되었는지 확인하는 테스트입니다.

테스트 결과: LAZY 설정이 무시되고 있었다

• SQL 로그를 확인하니 User 조회 시 Point조회도 함께 실행됨
• assert 검증으로 EAGER 조회가 일어남을 확인
• 디버그로 실행 시, User 객체 안의 Point가 Proxy가 아닌 실제 데이터를 가진 객체로 조회

분명 fetch=LAZY로 설정했는데, Hibernate가 이를 무시하고 EAGER로 동작하고 있었습니다.

@OneToOne 양방향 관계의 숨겨진 동작

@OneToOne 관계에서 LAZY 로딩을 명시하더라도, Hibernate는 EAGER 로딩을 강제하는 경우가 많습니다.

왜 이런 일이 발생할까?

프록시 생성의 난제: @OneToOne 관계에서 LAZY 로딩을 구현하려면 프록시(Proxy) 객체를 사용해야 합니다. 하지만 @OneToOne은 특별한 문제가 있습니다.

예를 들어, User를 조회할 때 Hibernate는 "이 User에게 연관된 Point가 있는가?"를 알아야 프록시를 만들지 null을 반환할지 결정할 수 있습니다. 하지만 이를 알려면 어차피 Point 테이블을 조회해야 합니다.

결과적으로:

• Point가 있는지 확인하려면 → Point 테이블을 조회해야 함
• 어차피 조회할 거면 → 그냥 데이터까지 가져오자
• Hibernate의 선택 → LAZY를 무시하고 EAGER로 동작

특히 양방향 관계에서, 그리고 연관 필드가 Not-Null인 경우 이런 현상이 자주 발생합니다.

문제의 연쇄 작용 전체 그림

이제 모든 퍼즐이 맞춰졌습니다:

1. 📝 userRepository.findById() 호출
2. 🔄 @OneToOne 양방향 관계 + Hibernate의 내부 최적화 → Point도 함께 EAGER 로딩
3. 💾 User와 Point 모두 1차 캐시에 저장됨
4. 🔒 이후 SELECT FOR UPDATE로 Point를 조회하려 시도
5. 🚫 JPA가 1차 캐시를 먼저 확인 → DB 쿼리가 실행되지 않음
6. ⏰ 1차 캐시의 "오래된 Point 값"이 반환됨
7. ❌ 비관적 락이 무력화되어 동시성 제어 실패

해결 방법 시도와 최종 결정

시도한 해결 방안들

1. @OneToOne(mappedBy = "user", cascade = CascadeType.ALL, fetch = FetchType.LAZY, optional = true)에서 optional 제거
2. Point에서 User를 참조하는 쪽도 FetchType.LAZY를 명시적으로 지정 (방어적 코딩)

결과: 두 방법 모두 실패 ❌

최종 해결: 양방향 관계 제거

현재 상태에서 가장 수정이 적은 방법들로도 해결되지 않아, 양방향 관계를 단방향으로 변경하기로 결정했습니다.

포인트를 유저 안에 넣을지, 유저와 포인트를 분리할지 설계 시점에서 정확하게 결정하지 못한 것이 근본 원인이었습니다. 중간에 방향을 바꾸려다 보니 불완전한 구조가 되었고, 이것이 예상치 못한 버그로 이어졌습니다.

최종 결정: User와 Point를 명확하게 분리하는 단방향 관계로 재설계

회고와 배운 점

1. JPA 1차 캐시의 우선순위: SELECT FOR UPDATE보다 1차 캐시가 먼저 동작한다는 것을 경험으로 배웠습니다
2. @OneToOne 양방향 관계의 함정: LAZY로 설정해도 Hibernate가 EAGER로 동작할 수 있다는 것을 알게 되었습니다
3. 트랜잭션 격리 수준: MySQL의 Repeatable Read와 MVCC에 대한 이해도가 높아졌습니다
4. 관계 설정의 중요성: 양방향 관계가 정말 필요한지, 단방향으로도 충분하지 않은지 신중하게 고려해야 합니다

발생한 문제를 해결하면서, Repeatable Read에 대해 알아보고, 각 DB별 기본 트랜잭션 격리에 대해서 학습하니 각 특성에 대해 더 잘 이해할 수 있었습니다.

주문 생성 트랜잭션을 깔끔하고 유지보수하기 쉬운 코드로 만들기 위해, 기능과 책임을 쪼개고 합치는 여정의 기록입니다. 이 과정에서 응용 서비스(Facade)와 도메인 서비스의 경계를 명확히 했습니다.

1. 🔍 초기 분석: 주문 트랜잭션의 4단계

구현해야하는 기능을 문장으로, "주문자가 / 재고가 있는 상품을 / 충분한 포인트로 결재하여 / 주문을 생성한다."

1. 문장에서 필요한 도메인(대상)은? 1) 사용자 2) 상품(주문에 필요한 자원) 3) 포인트(주문에 필요한 자원) 4) 주문

2. 어떤 순서로 진행되어야 하는가? 1) 주문에 필요한 도메인이 진짜 있는가? 2) 주문에 필요한 자원은 확보하였는가? 3) 자원을 사용한다. 4) 주문을 생성한다.

📋 주문 생성 프로세스 단계 (DDD 관점)

1.1. 확인: 도메인 정보 조회 (Read-Only)

주문 생성이 가능한 활성 상태인지 확인합니다.

• userService.getActiveUser(Long userId)
• productService.getExistProducts(List<Long> productIds)
• pointService.getAvailablePoints(Long userId) (포인트는 경우에 따라 필수X)

1.2. 검증 & 실행: 필요한 데이터 정의

가장 복잡한 재고/포인트의 검증 및 차감은 다음 데이터를 필요로 합니다.

1.3. 실행

전 단계의 이름과 특징을 적어보자

1) 확인

• 유저 정보 (DB 조회)
• 상품 정보 (DB 조회)
• 포인트 정보 (DB 조회)

userService.getActiveUser(Long `사용자ID`)
productService.getExistProducts(List <Long\> `상품IDs`)
pointService.getAvailablePoints(Long `사용자ID`)

2) 재고차감

• 필요한 재고 검증
• 재고차감(트랜잭션)

  verifyProductStock(List <Product\> `현재재고`, List<Long 상품ID ,Long 수량\> `필요한 재고`)
  deductProductStock(List<Product\> `현재재고`, List<Long 상품ID,Long 수량\> `필요한 재고`)
  

3) 포인트차감
- 충분한 포인트 검증
- 포인트 차감(트랜잭션)

verifyPointBalance(Point 현재 포인트, ? 필요한 포인트) useUserPoint(Point 현재 포인트, ? 필요한 포인트)

4) 주문서 생성(트랜잭션)

createOrder(Order)

## 2. 🧱 설계 시도와 핵심 결정

### 결정 1: DB 조회와 트랜잭션이 일어나는 기능은 Application service, 그 외는 Domain service


### 결정 2: 검증과 차감은 한번에
verify(검증) 후 deduct(차감) 을 분리하는 대신, 하나의 도메인 서비스 내에서 **검증과 상태 변경(차감)을 하나의 행위로 통합**했습니다. 입력값이 동일하며, 리스트 확인 및 데이터 수정으로 중복 조회가 일어나기 때문에 이를 방지하기 위해서 입니다.

### 결정 3: Map<Long, Long>으로 데이터 표준화

```java
public class OrderCreateV1Dto {
  public record OrderItemRequest(long productId, long quantity) {
  }
  public record OrderRequest(List<OrderItemRequest> items) {
  }
}

재고데이터 List<Product> 와 요청받은 List<OrderItemRequest> 주문내역을 비교하기 위해서, List<OrderItemRequest> 를 중복을 제거한 Map<Long,Long> 형식으로 변경하여 productId를 키값으로 수량검색이 용이하도록 했습니다.

public record CreateOrderCommand(Long userId, Map<Long, Long> orderItemInfo) {
  public record ItemCommand(Long productId, Map<Long, Long> quantity) {
  }
}

지금까지의 결정을 반환 타입까지 포함해서 적어보면,

UserService.getActiveUser(Long userId)->User
ProductService.getExistProducts(List<Long>)->List<Product>
PointService.getAvailablePoints(Long userId)->Point

verifyProductStock(List<Product> 현재재고, Map<Long 상품ID ,Long 수량> 필요한재고)-> `재고를 차감한 List<Product>`
deductProductStock(List<Product> 현재재고, Map<Long 상품ID,Long 수량> 필요한 재고)

verifyPointBalance(Point 현재 포인트, List<Product> 가격,Map<Long,Long> 수량) -> `사용 포인트를 차감한 Point`
saveUserPoint(Point 현재 포인트, `필요한 포인트`)

createOrder(Order)-> Order

결정 4: verifyPointBalance에서 차감된 포인트가 아닌 총 가격를 반환하자.

시도 1: verifyPointBalance 에서 포인트를 차감하고 잔액 Point를 반환하자?

verifyPointBalance으로( Point, List<Product>, Map<Long,Long>)을 보내고, Point 에서 총가격을 뺀 남은 Point 를 리턴하고 그대로 Point 를 저장하자.

포인트 차감후, 주문 생성에 필요한 데이터는?

• Order: 유저ID, 총 가격

• OrderItem: 상품ID, 수량, 단가

  총가격을 비교하는 verifyPointBalance에서 차감된 잔액 포인트가 리턴된다. 따라서 어디서도 총가격을 저장하고 있지 않아, 검증 이후 총 가격을 다시 구해야 한다. verifyPointBalance 에서 차감된 포인트가 아닌 총가격을 반환하자.

Order Facade에서 정리하면,

OrderFacade {
  public OrderInfo createOrder(CreateOrderCommand command) {
  User user = UserService.getActiveUser(Long userId);
  List<Product> products = ProductService.getExistProducts(List<Long> productIds);
  Point point = PointService.getAvailablePoints(Long userId);

  List<Product> deductedProducts = OrderPreparer.verifyProductStock(List<Product> products, List<Long 상품ID ,Long 수량> command.getOrderItemCommand);
  deductProductStock(deductedProducts)

  BigDecimal requestedPoints = OrderPreparer.verifyPointBalance(Point 현재 포인트, List<Product> 가격,Map<Long,Long> 수량);
  saveUserPoint(Point 현재 포인트 - requestedPoints)

  Order order = createOrder(User,List<Product>,Point)
  return OrderInfo.from(savedOrder);
  }

결정 5: 주문 생성시, 총가격 대신 Map<Long 상품ID ,Long 수량>

주문 상세 데이터 생성을 위해 상품의 단가,수량을 알려면 Map<Long 상품ID ,Long 수량> 를 넣어야 하고, List 만들면서 총가격을 계산할수 있기 때문에, 총가격 대신 Map<Long 상품ID ,Long 수량> 을 넣기로 했습니다.

결정 6: 포인트 저장 대신 포인트 차감

차감한 포인트를 저장하려다가, "포인트를 저장한다" 대신 "포인트를 차감한다" 의 의미가 행동의 의미를 잘 담고 있는것 같아서, verifyPointBalance 대신, 총가격을 조회하는 함수로 바꾸기로 했습니다.

@Transactional
  public OrderInfo createOrder(CreateOrderCommand command) {
    Map<Long, Long> quantityMap = command.orderItemInfo();
    User user = userService.getActiveUser(command.userId());
    List<Product> productList = productService.getExistingProducts(quantityMap.keySet());
    Point point = pointService.getAvailablePoints(user.getId());

    List<Product> deductedProducts = OrderPreparer.verifyProductStock(productList, quantityMap);
    productService.save(deductedProducts);

    BigDecimal totalAmt = OrderPreparer.getTotalAmt(point, productList, quantityMap);
    pointService.use(user, totalAmt);

    Order savedOrder = createOrderService.save(user, productList, quantityMap);

    return OrderInfo.from(savedOrder);
  }

결정 7:verify(검증) 후 **deduct(실행)을 합치자

같은 파라미터를 쓰고 있는 재고검증 및 차감 과 포인트검증 및 차감을 productStockService,userPointService로 합쳤습니다.

@Transactional
  public OrderInfo createOrder(CreateOrderCommand command) {
    Map<Long, Long> quantityMap = command.orderItemInfo();
    User user = userService.getActiveUser(command.userId());
    List<Product> productList = productService.getExistingProducts(quantityMap.keySet());

    productStockService.deduct(productList, quantityMap);
    userPointService.use(user, productList, quantityMap);

    Order savedOrder = createOrderService.save(user, productList, quantityMap);
    return OrderInfo.from(savedOrder);
  }

💡 정리 및 결론

처음 복잡하게 느껴졌던 주문 생성 로직이, 책임(재고, 포인트)을 기준으로 도메인 서비스(Manager)를 분석하고, 최종적으로 간결하고 이해하기 쉬운 형태의 OrderFacade를 만들어내었습니다. 추가로,초기 모델의 존재여부를 확인하는 부분도 한번 합쳐보면 더 보기좋은 코드가 될것 같은데 이렇게 계속 합쳐도 되는지, 의문이 들기도 했습니다.

간단하게 그려진 초기 클래스 다이어그램을 점검하고, 핵심 요소를 반영하며 최종 문서를 완성하는 과정을 정리합니다.

1. 🔑 접근 범위(Visibility) 및 메서드 추가

Mermaid 문법을 활용하여 클래스 멤버(필드, 메서드)의 접근 범위를 명확히 표현했습니다.

수정된 클래스 다이어그램1

2. 🧱 VO(Value Object)와 Enum 추가

도메인 설계의 완성도를 높이기 위해 식별자가 없는 VO와 상태를 정의하는 Enum을 추가했습니다.

1) Point VO (Value Object)

지난주 User 엔티티와 별도 테이블로 관리하던 Point 데이터를 VO로 전환하고 User 클래스에 포함시켰습니다. 평소 유저 테이블은 ERP에서 전송받는 데이터로 수정이 일어나지 않는 테이블이다보니 수정이 반복되는 Point가 포함되는 것이 어색해보여서 분리하게 되었었습니다. 하지만 현재 Point 테이블에 userId, pointAmount 외에 추가로 들어갈 정보들이나 요구사항이 없기 때문에 테이블로 분리하는 것은 나중 일이라는 것을 이해하게 되었습니다.

2) OrderStatus Enum

도메인 내에서 통일된 언어(유비쿼터스 언어)로 정의한 주문 상태를 Enum으로 추가했습니다.

수정된 클래스 다이어그램2

3. ➡️ 관계 및 방향 명확화 (Mermaid 화살표 사용)

Mermaid가 지원하는 UML 관계 표현을 사용하여 도메인 간의 결합도와 생명주기를 명확하게 정의했습니다.

Mermaid에서 표현할수 있는 화살표중 아래 상속,연관,집합,합성 4가지의 관계를 알아보겠습니다.

1) Inheritance(상속)

자식 --|> 부모 하나의 클래스가 다른 클래스의 특성과 동작을 물려받는 관계입니다. 예) 사과는 과일이다.

2) Association(연관)

참조하는 --> 참조되는 독립적인 객체 간의 느슨한 관계로, "has-a" 관계입니다. 객체들은 독자적인 라이프사이클을 가지며 서로 소유하지 않고 사용할 수 있습니다. 예) 선생님과 학생 관계

3) Aggregation(집합)

전체 o-- 부분 특별한 형태의 Association으로, 소유권을 가진 약한 결합 관계입니다. 포함된 객체는 독립적으로 존재할 수 있고, 부모 객체가 사라져도 자식 객체는 남습니다. 예) 부서와 직원 관계

4) Composition(합성)

전체 *-- 부분 Aggregation보다 강한 결합 관계로, 부모 객체가 소멸되면 자식 객체도 함께 소멸합니다. 예) 집과 방 관계

처음 정의한 관계코드

Order --> User  
Like --> Product  
Like --> User

Order --> OrderItem  
Product --> Brand
OrderItem --> Product  
User *--Point : has 
OrderStatus <-- Order : has

1) 강한 결합으로 Order가 사라지면 OrderItem은 독립적인 의미가 소멸하게 때문에 OrderItem 과 Order 를 "합성" 관계로 수정했습니다. 2) VO와 Class 의 관계는 "contains", Enum과 Class 의 관계는 "uses", Order Class 와 OrderItem의 합성 관계는 "owns" 로 눈에 띄도록 수정했습니다.

수정된 클래스 다이어그램3

4. ✅ 클래스 구조가 도메인 설계를 잘 표현하고 있는가?

체크리스트 중 있었던 "도메인 설계를 잘 표현하는 클래스 구조"란 무엇일까? perplexity 검색에 검색하니 핵심 요소들 5가지를 알려주었습니다.이를 보고 현재 반영하면 좋을 부분들을 찾다가 생략되었던 엔티티의 고유 식별자와 생성자를 추가하기로 했습니다.

1. 엔티티(Entity)

• 고유 식별자(ID)를 갖고 생명주기 관리
• 도메인 규칙과 상태를 가진 핵심 객체

2. 밸류 오브젝트(Value Object, VO)

• 식별자가 없으며 불변의 특성을 가짐
• 엔티티의 속성으로 포함되어 의미 부여

3. 애그리게이트(Aggregate)

• 하나 이상의 엔티티와 밸류 오브젝트 묶음
• 일관성 경계(Boundary)를 정의, 외부에서 일괄 접근
• 루트 엔티티가 존재하여 외부 참조 포인트 역할

최종 클래스 다이어그램를 완성했습니다.

5.🌟 클래스 다이어그램 학습 후기 정리

단계별 수정 과정을 통해 클래스 다이어그램의 설계를 구체화하고 객체 간 관계 표현에 대한 이해도를 심화할 수 있었습니다. 특히 클래스 다이어그램 작성 중 가장 어려움을 느꼈던 연관/집합/합성 관계간 구분과 화살표의 방향을 확인하면서 스스로 명확히 정리할수 있었습니다.

🙋‍♀️ TDD에 대한 경험과 의문점

3년 전 Spring 공부 중 테스트 코드를 접했고, 이후 사이드 프로젝트에서 PR 템플릿에 맞추어 단순 값을 대충 바꿔 넣는 정도로만 사용했습니다. 리뷰 없이 '내 맘대로' 작성했기에, TDD 방식은 알았지만 테스트 코드 작성이 단순 반복적이고 재미없는 일로 느껴졌습니다. 특히 '테스트 코드부터 개발'한다는 방식이 현실적으로 상상되지 않았습니다.

TDD 의문점과 해결

Q1. 테스트 코드를 짜는데 시간이 걸린다.

• 테스트 코드에 들이는 시간이 아예 없을수는 없다. 하지만 TDD 방식으로 검증과 개발을 동시에 진행한다면, 개발만 하다가 계획을 변경하고, 사이드 이펙트를 경험하는 것보다 빠를수밖에 없다.

Q2. 테스트 코드부터 개발하는 상황이 상상이 되지 않는다.

• 테이블 설계를 먼저 하는 것에 익숙하다 보니, 전혀 그려지지 않는 일이었다. 하지만 필요한 API요청들을 E2E로 먼저 작성하고, 세세한 로직들을 만들어 가는 과정, 객체의 특성을 녹이는 과정이 이제는 이해되기 시작했다.

Q3. 단위/통합/E2E 각각 어떤 검증을 해야하나요.

단위/통합 테스트 (주로 비즈니스 로직 및 객체 상태 검증)

//DB 저장 메서드가 호출되는지 확인
verify(repository).save(any())
//반환된 객체가 null이 아닌지
assertNotNull(result)
//반환 객체의 핵심 필드가 정확한지 
assertEquals(expectedValue, result.getField())
//특정 필드 값이 비즈니스 로직에 맞는지
assertTrue(result.isValid())
//삭제 메서드가 정확히 1번 호출되었는지 확인
verify(repository, times(1)).deleteById(id)
//삭제 후 조회 시 예외가 발생하는지 확인
assertThrows(NotFoundException.class, () -> service.read(id))

E2E 테스트 (주로 시스템 응답 및 영속성 검증)

//201 응답 확인
assertEquals(HttpStatus.CREATED, response.getStatusCode())
//DB에서 직접 조회하여 객체가 존재하는지 확인.
assertNotNull(repository.findById(id).orElse(null))
//응답 JSON 필드 값 검증
assertEquals(expectedValue, response.getBody().getFieldName())
//DB 조회 결과 Optional이 비어있는지 확인
assertTrue(repository.findById(id).isEmpty())

Q4. 운영DB에서 테스트 코드가 실행될수도 있다던데..

• 이 위험도 때문에 테스트 코드 작성이 주저되기도 했다. 사실 내가 설정을 잘 해놓으면 되는 일인데, 혹여나 하는 걱정이 있었다.

🐢 @SpringBootTest 빌드 속도 저하 트러블 슈팅

E2E 및 통합 테스트 개발 중 빌드 시간이 5분 이상 소요되는 현상이 발생했습니다. 원인을 찾기 시작했습니다.

1) @Spy와 @SpyBean 차이점 검토 (원인 아님)

@SpyBean 사용 시점과 속도 저하 시점이 비슷하여 의심했지만, 이는 근본 원인이 아님을 확인했습니다.

2) Testcontainers 환경 문제 발견 (주요 원인)

Docker와 Testcontainers가 띄워지는 로그를 통해 Docker 관련 문제임을 추정했습니다.

✅ 해결 과정

1) Docker Desktop 업데이트 2) Testcontainers 아이콘을 발견하고 실행 중인 컨테이너를 모두 삭제했습니다. 3) Containers running locally > Embedded Runtime을 desktop-linux로 변경했습니다. 4) 설정 변경 후 테스트 실행 속도가 현저히 빨라졌습니다.

🔎 Embedded Runtime vs. Desktop Linux Docker 데몬

성능 및 오버헤드 (M1/Mac 환경의 경우 더 중요) Embedded Runtime (리눅스 네이티브): Testcontainers는 도커 API를 사용하여 컨테이너를 직접 실행합니다. 파일 시스템 접근이 호스트 리눅스 커널 수준에서 이루어지기 때문에 오버헤드가 거의 없어 빌드 및 테스트 속도가 가장 빠릅니다.

Docker Desktop (Mac/Windows): Mac이나 Windows에서 Docker Desktop을 사용하면, 도커 데몬은 항상 내부 VM 내에서 실행됩니다. 특히 M1/M2/M3 Mac의 경우, 성능 개선이 이루어졌지만 여전히 네이티브 리눅스에 비하면 약간의 파일 I/O 오버헤드가 발생할 수 있습니다.

제 환경(M1)에서는 예상과 달리 Embedded Runtime에서 더 오래 걸리는 현상을 경험했습니다. 이부분은 좀더 공부해봐야 직접적인 문제를 알수 있을것 같습니다.

💡 TDD 관련 학습 내용 정리

이번 경험을 통해 알게 된 주요 개념과 도구를 정리했습니다. 추후 적합한 도구를 활용해 다양한 테스트 코드를 경험해 보려고 합니다.

🟢 테스트 더블 (Test Double)

• Dummy – 테스트에 필요하지만 실제로 사용되지 않는 더미 객체
• Stub – 특정 메서드 호출 시 미리 정의된 값 반환
• Fake – 실제 구현과 비슷하지만 단순화된 객체 (예: In-memory DB)
• Mock – 호출 여부, 인자 등을 검증할 수 있는 객체
• Spy – 실제 객체를 그대로 사용하면서 일부 동작만 감시/검증

🧪 E2E 테스트

• TestRestTemplate – Spring Boot 서버 띄워 HTTP 요청/응답 검증
• WebTestClient – WebFlux, 실제 HTTP 호출
• RestAssured – REST API E2E 테스트 🧠 통합 테스트
• @SpringBootTest – 전체 스프링 컨텍스트
• TestContainers – DB/Kafka/Redis 연동

🧱 단위 테스트

• Repository / Service / Controller
• JUnit / Kotest
• Mock / Spy (Mockito)
• @ParameterizedTest / @ValueSource

🔍 슬라이스 테스트

• @WebMvcTest – Controller만, Service/Repo Mock
• @DataJpaTest – Repository/JPA
• @RestClientTest – RestTemplate/WebClient
• @JsonTest – JSON 직렬화/역직렬화
• MockMvc – 컨트롤러 테스트

🎨 코드 포맷 / 스타일

• Spock – BDD 스타일

🗂 테스트 데이터

• Fixture Monkey – 코드 기반 픽스처 생성
• DBRider – DB 기반 픽스처 생성

이전에 Android로 구현한 React Native 앱에서 외부 앱(사진, 카메라, 갤러리 등)에서 공유되는 이미지를 받아서 처리하는 기능을 iOS으로 개발하는 작업이었습니다.

🔄 기술 스택 선택의 여정

Swift에서 Objective-C로의 전환

처음에는 Swift로 개발을 시작했습니다. 최신 언어이고 문법이 깔끔하며, iOS 개발에서 애플이 권장하는 언어이기 때문이었죠.

하지만 Native Module 개발에서는 Objective-C를 강력히 권장하고 있었습니다:

React Native가 Objective-C를 권장하는 이유

1. TurboModule 지원: React Native의 새로운 아키텍처인 TurboModule은 Objective-C 기반으로 설계
2. 코드 생성: react-native-codegen이 Objective-C 헤더 파일을 자동 생성
3. 브릿지 안정성: JavaScript와 Native 간의 브릿지가 Objective-C에서 더 안정적
4. 타입 안정성: C++ 백엔드와의 연동이 Objective-C에서 더 매끄러움

CodeGen 지원

React Native 0.68+ 버전의 New Architecture를 지원하려면 CodeGen을 사용해야 했는데, 이 도구가 생성하는 인터페이스가 순수 Objective-C였습니다. Swift에서 이를 구현하려면 복잡한 브릿징 코드가 필요했지만, Objective-C에서는 아래 코드로 바로 구현 가능했습니다.

  #import "LPShareModuleSpec.h"

  @interface LPShareModule : NativeLPShareModuleSpecBase 
  <NativeLPShareModuleSpec>
  @end

  @implementation LPShareModule
  @end

🔗 Cross-Platform 인터페이스 통일

기존 Android 모듈 활용

가장 중요했던 것은 기존 Android용으로 만들어진 TypeScript 인터페이스를 그대로 활용하는 것이었습니다. 이미 Android 개발 시 만들어진 NativeLPShareModule.ts가 있었고, iOS에서도 동일한 인터페이스로 동작하도록 구현했습니다.

기존 TypeScript 인터페이스

// src/NativeLPShareModule.ts - 이미 Android용으로 구현됨
  import type {TurboModule} from 'react-native/Libraries/TurboModule/RCTExport';
  import {TurboModuleRegistry} from 'react-native';

  export interface SharedData {
    readonly type: string | null;
    readonly uri?: string;
    readonly uriList?: ReadonlyArray<string>;
  }

  export interface Spec extends TurboModule {
    sendSharedData(eventName: string, data: string): void;
    testMethod(): Promise<string>;
    getSharedData(): Promise<SharedData>;
  }

  export default TurboModuleRegistry.getEnforcing<Spec>('LPShareModule');

이렇게 구현한 덕분에 React Native 코드에서는 플랫폼을 신경 쓰지 않고 동일하게 사용할 수 있었습니다:

통합의 이점

1. 코드 재사용성: 상위 레벨 React Native 코드는 플랫폼 구분 없이 재사용
2. 유지보수성: 인터페이스 변경 시 TypeScript 파일 하나만 수정
3. 타입 안정성: TypeScript가 두 플랫폼 모두의 타입 검사
4. 개발 효율성: 새로운 기능 추가 시 스펙 정의 후 각 플랫폼에서 구현만 하면 됨

🏗️ 아키텍처 설계

iOS에서 외부 앱 공유를 처리하는 방법은 Share Extension을 사용하는 것입니다. 전체 구조는 다음과 같습니다:

외부 앱 → Share Extension → App Group → Main App → React Native

주요 구성요소

1. Share Extension: 외부 앱에서 공유된 이미지를 받는 진입점
2. App Group: Share Extension과 Main App 간의 데이터 공유
3. Native Module: React Native Bridge를 통한 데이터 전달

🔧 구현 과정

1. Share Extension 생성

먼저 Xcode에서 새로운 Share Extension Target을 생성했습니다.

Info.plist 설정

  <key>NSExtensionActivationRule</key>
  <dict>
      <!-- 최대 10개 이미지 지원 -->
      <key>NSExtensionActivationSupportsImageWithMaxCount</key>
      <integer>10</integer>

      <!-- iOS 14+ 방식 -->
      <key>NSExtensionActivationSupportsImage</key>
      <true/>

      <!-- iOS 13 이하 호환성 -->
      <key>NSExtensionActivationSupportsAttachmentsWithMatchingUTIs</key>
      <array>
          <string>public.image</string>
      </array>
  </dict>

2. ShareViewController 구현

핵심 로직을 담은 ShareViewController:

  - (void)handleSharedContent {
      NSExtensionContext *extensionContext = self.extensionContext;
      NSArray<NSExtensionItem *> *inputItems = extensionContext.inputItems;

      // 이미지 타입 첨부파일만 필터링
      NSMutableArray<NSItemProvider *> *imageAttachments = [[NSMutableArray
  alloc] init];
      for (NSExtensionItem *item in inputItems) {
          for (NSItemProvider *attachment in item.attachments) {
              if ([attachment
  hasItemConformingToTypeIdentifier:UTTypeImage.identifier]) {
                  [imageAttachments addObject:attachment];
              }
          }
      }

      if ([imageAttachments count] == 1) {
          // 단일 이미지 처리
          [self processImageAttachment:imageAttachments[0] completion:^(NSString
   *uri) {
              [self saveSharedDataToUserDefaults:@"single" uri:uri uriList:nil];
              [self openMainApp];
          }];
      } else {
          // 다중 이미지 처리
          [self processMultipleImageAttachments:imageAttachments
  completion:^(NSArray<NSString *> *uris) {
              [self saveSharedDataToUserDefaults:@"multiple"
  uri:uris.firstObject uriList:uris];
              [self openMainApp];
          }];
      }
  }

3. App Group을 통한 데이터 공유

Share Extension과 Main App 간의 데이터 공유를 위해 App Group을 설정:

  - (void)saveSharedDataToUserDefaults:(NSString *)type uri:(NSString *)uri
  uriList:(NSArray<NSString *> *)uriList {
      NSUserDefaults *groupUserDefaults = [[NSUserDefaults alloc]
          initWithSuiteName:@"group.io.itmca.lifepuzzle"];
      NSUserDefaults *standardUserDefaults = [NSUserDefaults
  standardUserDefaults];

      // Group UserDefaults에 우선 저장
      if (groupUserDefaults) {
          [groupUserDefaults setObject:type forKey:@"SharedDataType"];
          if (uri) [groupUserDefaults setObject:uri forKey:@"SharedDataURI"];
          if (uriList) [groupUserDefaults setObject:uriList
  forKey:@"SharedDataURIList"];
          [groupUserDefaults synchronize];
      }

      // Standard UserDefaults에 백업 저장
      [standardUserDefaults setObject:type forKey:@"SharedDataType"];
      // ... 동일한 로직
  }

4. Native Module 구현

React Native와 iOS 간의 브릿지 역할을 하는 Native Module:

  - (void)getSharedData:(RCTPromiseResolveBlock)resolve
  reject:(RCTPromiseRejectBlock)reject {
      NSUserDefaults *groupUserDefaults = [[NSUserDefaults alloc]
          initWithSuiteName:@"group.io.itmca.lifepuzzle"];

      NSString *sharedType = [groupUserDefaults stringForKey:@"SharedDataType"];
      NSString *sharedURI = [groupUserDefaults stringForKey:@"SharedDataURI"];
      NSArray<NSString *> *sharedURIList = [groupUserDefaults
  arrayForKey:@"SharedDataURIList"];

      if (sharedType) {
          NSMutableDictionary *result = [[NSMutableDictionary alloc] init];
          [result setObject:sharedType forKey:@"type"];

          if ([sharedType isEqualToString:@"single"] && sharedURI) {
              [result setObject:sharedURI forKey:@"uri"];
          } else if ([sharedType isEqualToString:@"multiple"] && sharedURIList)
  {
              [result setObject:sharedURIList forKey:@"uriList"];
          }

          // 사용 후 데이터 삭제
          [groupUserDefaults removeObjectForKey:@"SharedDataType"];
          [groupUserDefaults removeObjectForKey:@"SharedDataURI"];
          [groupUserDefaults removeObjectForKey:@"SharedDataURIList"];
          [groupUserDefaults synchronize];

          resolve(result);
      } else {
          resolve(@{@"type": [NSNull null]});
      }
  }

🎯 설정 및 권한

Entitlements 설정

각 Target별로 App Groups 권한 설정:

  LifePuzzleShareRelease.entitlements:
  <key>com.apple.security.application-groups</key>
  <array>
     <string>group.io.itmca.lifepuzzle</string>
  </array>

💡 배운 점들

1. 기술 선택의 중요성

처음엔 "최신 = 최선"이라고 생각했지만, 프레임워크의 권장사항을 따르는 것이 더 중요하다는 것을 깨달았습니다.

2. React Native의 철학 이해

React Native가 왜 Objective-C를 권장하는지 이해하게 되었습니다:

• 안정성 > 모던함
• 생태계 호환성 > 개인 선호도

3. 인터페이스 통일의 중요성

Android에서 이미 만들어진 TypeScript 인터페이스를 그대로 사용함으로써:

• 개발 시간 단축
• 버그 위험 감소
• 코드 일관성 확보
• 유지보수성 향상

🎉 결과

ios (카카오톡 이미지 공유, iPhone)

• ✅ 외부 앱에서 단일/다중 이미지 공유 지원
• ✅ iOS 13+ 호환성 확보
• ✅ 메모리 누수 방지 및 자동 정리
• ✅ 안정적인 데이터 전달 메커니즘
• ✅ TypeScript 타입 안정성
• ✅ React Native New Architecture 완벽 지원
• ✅ Android와 동일한 인터페이스로 Cross-Platform 코드 재사용

이제 iOS 사용자들도 갤러리, 카메라, 다른 앱에서 이미지를 LifePuzzle 앱으로 직접 공유할 수 있게 되었습니다! 🎊

React Native 0.68부터 도입된 New Architecture는 기존의 Bridge 방식에서 TurboModule과 Fabric으로 전환하면서 성능상의 많은 이점을 가져다주었습니다. 하지만 기존 Legacy 모듈들과의 호환성 문제로 인해 많은 개발자들이 마이그레이션에 어려움을 겪고 있습니다.

이번 글에서는 React Native New Architecture 환경에서 외부 앱에서 이미지를 공유받아 처리하는 시스템을 구현하면서 마주했던 7가지 핵심 문제들과 그 해결 과정을 상세히 공유하겠습니다.

프로젝트 개요

목표: 갤러리나 카메라 앱에서 "공유" 버튼을 통해 우리 React Native 앱으로 이미지를 전송받아 처리하는 시스템 구현

기술 스택:

• React Native 0.74+ (New Architecture 활성화)
• TurboModule (Kotlin/Java)
• Recoil (상태 관리)
• TypeScript

문제 1: React Native New Architecture 호환성 문제

🚨 문제 상황

기존의 Legacy ReactModule로 구현된 네이티브 모듈이 New Architecture의 Bridgeless 모드와 호환되지 않았습니다.

// ❌ Legacy 방식 - New Architecture 비호환
class ShareModule(reactContext: ReactApplicationContext) : ReactContextBaseJavaModule(reactContext) {
    // Legacy implementation
}

🔍 원인 분석

• React Native New Architecture는 2025년 8월 현재 안정화 단계
• TurboModule로 전환 시 Bridgeless 모드에서 런타임 오류 발생
• Codegen 관련 설정 누락으로 인한 빌드 실패

✅ 해결 방법

1단계: Codegen 아티팩트 생성

./gradlew generateCodegenArtifactsFromSchema

2단계: TurboModule 스펙 정의

// NativeLPShareModule.ts
import type { TurboModule } from 'react-native';
import { TurboModuleRegistry } from 'react-native';

export interface Spec extends TurboModule {
  getSharedData(): Promise<string | null>;
  clearSharedData(): Promise<void>;
}

export default TurboModuleRegistry.getEnforcing<Spec>('LPShareModule');

3단계: Kotlin TurboModule 구현

// LPShareModule.kt
class LPShareModule(reactContext: ReactApplicationContext) : NativeLPShareModuleSpec(reactContext) {

    companion object {
        const val NAME = "LPShareModule"
        private var pendingSingleImageUri: String? = null
        private var pendingMultipleImageUris: List<String>? = null
    }

    override fun getName(): String = NAME

    ...
}

문제 2: NativeShareModuleSpecJSI 중복 정의 오류

🚨 문제 상황

Duplicate symbol: facebook::react::NativeShareModuleSpecJSI::NativeShareModuleSpecJSI

React Native core의 내장 Share API와 모듈명이 충돌하면서 빌드 오류가 발생했습니다.

🔍 원인 분석

React Native는 이미 Share라는 이름의 TurboModule을 내장하고 있었고, 동일한 이름으로 커스텀 모듈을 만들면서 C++ 레벨에서 심볼 충돌이 발생했습니다.

✅ 해결 방법

모듈명을 고유한 이름으로 변경하여 충돌을 회피했습니다.

// ❌ 충돌 발생
export default TurboModuleRegistry.getEnforcing<Spec>('ShareModule');

// ✅ 충돌 해결
export default TurboModuleRegistry.getEnforcing<Spec>('LPShareModule');

문제 3: Event Emitter 방식의 한계

🚨 문제 상황

초기에는 Event Emitter 방식으로 네이티브에서 JavaScript로 데이터를 전송하려 했지만, 앱이 완전히 초기화되기 전에는 이벤트 리스너가 설정되지 않아 데이터 손실이 발생했습니다.

// ❌ 데이터 손실 가능성이 있는 방식
useEffect(() => {
  const subscription = shareEventEmitter.addListener('imageShared', handleImageData);
  return () => subscription?.remove();
}, []);

✅ 해결 방법

Event 방식 대신 Polling + Static 저장소 패턴을 도입했습니다.

// JavaScript에서 데이터 확인
const checkForSharedData = useCallback(async () => {
  try {
    const sharedData = await LPShareModule.getSharedData();
    if (sharedData) {
      // 공유된 데이터 처리
      handleSharedData(sharedData);
    }
  } catch (error) {
    console.log('공유 데이터 확인 실패:', error);
  }
}, []);

문제 4: React Context 타이밍 문제

🚨 문제 상황

앱이 완전히 시작되기 전에 외부에서 이미지 공유가 발생하면, React Native 컨텍스트가 준비되지 않아 모듈을 찾을 수 없는 오류가 발생했습니다.

🔍 원인 분석

MainActivity에서 ShareModule을 호출하는 시점과 React Native가 초기화되는 시점 사이의 레이스 컨디션이 문제였습니다.

✅ 해결 방법: Pending Data 패턴

MainActivity에서 임시 저장

// MainActivity.kt
override fun onCreate(savedInstanceState: Bundle?) {
    SplashView.showSplashView(this)
    super.onCreate(savedInstanceState)
    handleShareIntent(intent)
}

override fun onNewIntent(intent: Intent) {
    super.onNewIntent(intent)
    intent?.let { handleShareIntent(it) }
}

private fun handleShareIntent(intent: Intent?) {
    if (intent == null) return

    val action = intent.action
    val type = intent.type

    if (Intent.ACTION_SEND == action && type != null && type.startsWith("image/")) {
        // 단일 이미지 처리
        val imageUri: Uri? = intent.getParcelableExtra(Intent.EXTRA_STREAM)
        imageUri?.let {
            val module = (application as MainApplication).reactNativeHost.reactInstanceManager
                        .currentReactContext?.getNativeModule(LPShareModule::class.java)
            if (module != null) {
                module.setSharedImageUri(it.toString())
            } else {
                // React Native 초기화 전이면 pending 저장소에 저장
                pendingSingleImageUri = it.toString()
                pendingMultipleImageUris = null
            }
        }
    } else if (Intent.ACTION_SEND_MULTIPLE == action && type != null && type.startsWith("image/")) {
        // 다중 이미지 처리
        val imageUris: ArrayList<Uri>? = intent.getParcelableArrayListExtra(Intent.EXTRA_STREAM)
        imageUris?.let { uris ->
            val uriStrings = uris.map { it.toString() }
            val module = (application as MainApplication).reactNativeHost.reactInstanceManager
                        .currentReactContext?.getNativeModule(LPShareModule::class.java)
            if (module != null) {
                module.setSharedImageUris(uriStrings)
            } else {
                // React Native 초기화 전이면 pending 저장소에 저장
                pendingMultipleImageUris = uriStrings
                pendingSingleImageUri = null
            }
        }
    }
}

companion object {
    private var pendingSingleImageUri: String? = null
    private var pendingMultipleImageUris: List<String>? = null

    fun hasPendingShareData(): Boolean {
        return pendingSingleImageUri != null || pendingMultipleImageUris != null
    }

    fun processPendingShareData(): Pair<String?, List<String>?> {
        val result = Pair(pendingSingleImageUri, pendingMultipleImageUris)
        pendingSingleImageUri = null
        pendingMultipleImageUris = null
        return result
    }
}

문제 5: ShareModule 인스턴스 격리 문제

🚨 문제 상황

setSharedImageUri()와 getSharedData()가 서로 다른 TurboModule 인스턴스에서 실행되어 데이터 공유가 되지 않았습니다.

🔍 원인 분석

TurboModule 시스템에서는 메서드 호출마다 새로운 인스턴스가 생성될 수 있어, 인스턴스 변수로는 데이터 공유가 불가능했습니다.

✅ 해결 방법: Companion Object 활용

class LPShareModule(reactContext: ReactApplicationContext) : NativeLPShareModuleSpec(reactContext) {

    companion object {
        // 단일/다중 이미지를 모두 처리할 수 있는 Static 변수
        private var pendingSingleImageUri: String? = null
        private var pendingMultipleImageUris: List<String>? = null

        fun setSharedImageUri(uri: String) {
            pendingSingleImageUri = uri
            pendingMultipleImageUris = null
        }

        fun setSharedImageUris(uris: List<String>) {
            pendingMultipleImageUris = uris
            pendingSingleImageUri = null
        }
    }

    override fun getSharedData(promise: Promise) {
        try {
            // MainActivity의 pending 데이터도 함께 확인
            val mainActivity = currentActivity as? MainActivity
            if (mainActivity?.hasPendingShareData() == true) {
                val (singleUri, multipleUris) = mainActivity.processPendingShareData()
                if (singleUri != null) {
                    pendingSingleImageUri = singleUri
                } else if (multipleUris != null) {
                    pendingMultipleImageUris = multipleUris
                }
            }

            // 데이터 반환 및 초기화
            val sharedData = pendingSingleImageUri ?: pendingMultipleImageUris?.firstOrNull()
            pendingSingleImageUri = null
            pendingMultipleImageUris = null

            promise.resolve(sharedData)
        } catch (e: Exception) {
            promise.reject("GET_SHARED_DATA_ERROR", e.message, e)
        }
    }
}

문제 6: 순환 참조 문제

🚨 문제 상황

getSharedData() → processPendingShareData() → setSharedImageUri() → 무한 루프 발생

🔍 원인 분석

ShareModule에서 MainActivity의 메서드를 호출할 때, 다시 ShareModule을 찾으려 해서 순환 참조가 발생했습니다.

✅ 해결 방법: 단순화된 직접 처리

// ❌ 순환 참조 발생 가능한 복잡한 구조
fun getSharedData() {
    val mainActivity = getCurrentActivity() as? MainActivity
    mainActivity?.processPendingShareData() // 위험!
}

// ✅ 이중 저장소로 순환 참조 방지
class LPShareModule {
    companion object {
        private var pendingSingleImageUri: String? = null
        private var pendingMultipleImageUris: List<String>? = null
    }

    override fun getSharedData(promise: Promise) {
        try {
            // 1. MainActivity의 pending 데이터 확인
            val mainActivity = currentActivity as? MainActivity
            if (mainActivity?.hasPendingShareData() == true) {
                val (singleUri, multipleUris) = mainActivity.processPendingShareData()
                // 2. TurboModule의 저장소로 이동
                if (singleUri != null) {
                    pendingSingleImageUri = singleUri
                } else if (multipleUris != null) {
                    pendingMultipleImageUris = multipleUris
                }
            }

            // 3. 데이터 반환 및 초기화 (순환 참조 없음)
            val sharedData = pendingSingleImageUri ?: pendingMultipleImageUris?.firstOrNull()
            pendingSingleImageUri = null
            pendingMultipleImageUris = null

            promise.resolve(sharedData)
        } catch (e: Exception) {
            promise.reject("GET_SHARED_DATA_ERROR", e.message, e)
        }
    }
}

// MainActivity는 단순히 pending 데이터만 관리
class MainActivity {
    companion object {
        fun processPendingShareData(): Pair<String?, List<String>?> {
            val result = Pair(pendingSingleImageUri, pendingMultipleImageUris)
            pendingSingleImageUri = null
            pendingMultipleImageUris = null
            return result
        }
    }
}

문제 7: 다른 화면에서 공유 데이터 미처리 문제

🚨 문제 상황

사용자가 HomePage가 아닌 다른 화면에 있을 때 외부에서 이미지를 공유하면, 해당 이미지가 처리되지 않았습니다.

🔍 원인 분석

checkSharedData() 함수가 HomePage에서만 실행되어, 다른 화면에서는 공유 데이터를 감지할 수 없었습니다.

✅ 해결 방법: 전역 공유 데이터 감지 시스템

1단계: Recoil 전역 상태 관리

// atoms/sharedImageAtom.ts
import { atom } from 'recoil';

export interface SharedImageData {
  uri: string;
  timestamp: number;
}

export const sharedImageDataState = atom<SharedImageData | null>({
  key: 'sharedImageDataState',
  default: null,
});

2단계: App.tsx에서 전역 감지

// App.tsx
const App = () => {
  const [, setSharedImageData] = useRecoilState(sharedImageDataState);
  const navigation = useNavigation();

  const checkForSharedData = useCallback(async () => {
    try {
      const sharedData = await LPShareModule.getSharedData();
      if (sharedData) {
        console.log('공유된 데이터 감지:', sharedData);

        // 전역 상태 업데이트
        setSharedImageData({
          uri: sharedData,
          timestamp: Date.now(),
        });

        // HomePage로 자동 네비게이션
        navigation.navigate('Home' as never);
      }
    } catch (error) {
      console.log('공유 데이터 확인 실패:', error);
    }
  }, [setSharedImageData, navigation]);

  // 앱 상태 변화 감지 (앱이 열리거나 포커스될 때만 체크)
  useEffect(() => {
    // 앱 시작할 때 한 번 체크
    checkForSharedData();

    // AppState 변화 리스너
    const handleAppStateChange = (nextAppState: string) => {
      if (nextAppState === 'active') {
        // 앱이 활성화될 때마다 체크
        checkForSharedData();
      }
    };

    const subscription = AppState.addEventListener('change', handleAppStateChange);

    return () => subscription?.remove();
  }, [checkForSharedData]);

  return <NavigationContainer>{/* ... */}</NavigationContainer>;
};

3단계: HomePage에서 상태 감지 및 처리

// HomePage.tsx
const HomePage = () => {
  const [sharedImageData, setSharedImageData] = useRecoilState(sharedImageDataState);
  const [isBottomSheetOpen, setIsBottomSheetOpen] = useState(false);

  useEffect(() => {
    if (sharedImageData) {
      console.log('HomePage에서 공유 이미지 감지:', sharedImageData);

      // BottomSheet 자동 열기
      setIsBottomSheetOpen(true);

      // 처리 완료 후 상태 초기화
      // setSharedImageData(null); // 필요에 따라 즉시 또는 나중에 초기화
    }
  }, [sharedImageData]);

  const handleImageUpload = async () => {
    if (sharedImageData) {
      try {
        // 이미지 업로드 로직
        await uploadImage(sharedImageData.uri);

        // 성공 후 상태 초기화
        setSharedImageData(null);
        setIsBottomSheetOpen(false);
      } catch (error) {
        console.error('이미지 업로드 실패:', error);
      }
    }
  };

  return (
    <View style={{ flex: 1 }}>
      {/* 기존 HomePage 컴포넌트들 */}

      <BottomSheet
        isOpen={isBottomSheetOpen}
        onClose={() => {
          setIsBottomSheetOpen(false);
          setSharedImageData(null);
        }}
      >
        {sharedImageData && (
          <SharedImagePreview
            imageUri={sharedImageData.uri}
            onUpload={handleImageUpload}
            onCancel={() => {
              setIsBottomSheetOpen(false);
              setSharedImageData(null);
            }}
          />
        )}
      </BottomSheet>
    </View>
  );
};

최종 아키텍처 및 데이터 흐름

🏗️ 시스템 아키텍처

📱 외부 앱 (갤러리)
    ↓ Intent.ACTION_SEND / ACTION_SEND_MULTIPLE
🏠 MainActivity (이중 저장 시스템)
    ↓ setSharedImageUri(s)
💾 LPShareModule + MainActivity Pending 저장소
    ↓ 앱 상태 변화 감지
🌐 App.tsx (전역 감지)
    ↓ Recoil 상태 업데이트
⚛️ HomePage (상태 구독)
    ↓ BottomSheet 자동 열기
👤 사용자 확인 및 업로드

🔄 완벽한 데이터 흐름

1. 📱 갤러리 앱에서 "공유" 버튼 클릭 (단일 또는 다중 이미지)
2. 🏠 MainActivity에서 Intent 수신 및 이중 저장 시스템 활용
3. 💾 LPShareModule과 MainActivity 양쪽에 URI 보관
4. 🌐 App.tsx에서 앱 상태 변화 시점에 감지 수행
5. ⚛️ Recoil 상태로 앱 전체에 데이터 전파
6. 🧭 HomePage로 자동 네비게이션
7. 📋 BottomSheet 자동 열기 및 이미지 미리보기
8. 👤 사용자 확인 후 이미지 업로드

🎯 핵심 기술적 결정사항

마무리

React Native New Architecture 환경에서 외부 앱 이미지 공유 시스템을 구현하면서 다음과 같은 핵심 인사이트를 얻었습니다:

🎓 주요 학습 포인트

1. TurboModule의 중요성: New Architecture에서는 TurboModule 구현이 필수
2. Static 데이터 공유: 인스턴스 간 데이터 공유를 위해서는 Static 변수 활용
3. 전역 상태 관리: 앱 전체에서 공유 데이터를 감지하려면 전역 상태 관리가 필요
4. 타이밍 문제 해결: 이중 저장소 패턴으로 초기화 타이밍 문제 해결
5. 효율적인 감지 시스템: 주기적 폴링보다 AppState 기반 감지가 더 효율적
6. 다중 이미지 처리: ACTION_SEND_MULTIPLE 지원으로 확장성 확보

🚀 프로덕션 준비 완료

현재 시스템은 다음과 같은 특징으로 프로덕션 환경에서 안정적으로 작동합니다:

• ✅ New Architecture 완전 호환
• ✅ 단일/다중 이미지 모두 지원
• ✅ 모든 화면에서 공유 데이터 감지
• ✅ 자동 네비게이션 및 UI 표시
• ✅ 이중 저장소로 데이터 안정성 확보
• ✅ 오류 처리 및 복구
• ✅ 사용자 친화적 UX

💡 향후 개선 방향

1. 푸시 알림 통합: 공유 데이터 수신 시 알림 표시
2. 멀티미디어 지원: 비디오 및 기타 파일 형식 지원 확장
3. 배치 처리: 여러 이미지 동시 공유 처리
4. 캐싱 시스템: 반복적인 공유 작업 최적화

이번 구현을 통해 React Native New Architecture의 강력함과 동시에 기존 시스템과의 호환성 문제를 해결하는 과정을 경험할 수 있었습니다. 앞으로 New Architecture가 더욱 안정화되면서 이런 구현들이 더욱 간편해질 것으로 기대됩니다.

🎉 결과

android (사진앱 이미지 공유, Android Emulator)

💬 궁금한 점이나 개선 아이디어가 있다면 댓글로 공유해주세요!
React Native New Architecture 관련 다른 문제들도 함께 논의해보면 좋겠습니다. 🚀

1. 설정

   kubectl create namespace jenkins
   kubectl apply -f jenkins.yaml //Jenkins 배포
   minikube service jenkins-service -n jenkins //Jenkins 접속

2. 초기 비밀번호 확인

   kubectl exec -n jenkins -it deployment/jenkins -- cat /var/jenkins_home/secrets/initialAdminPassword
   

3. secret 생성

kubectl apply -f jenkins-serviceaccount.yaml kubectl create secret generic jenkins-sa-token
--namespace jenkins
--type kubernetes.io/service-account-token
--from-literal=extra=dummy
--dry-run=client -o yaml |
sed '/extra:/d' |
tee jenkins-sa-token.yaml kubectl apply -f jenkins-sa-token.yaml kubectl get secret jenkins-sa-token -n jenkins -o jsonpath="{.data.token}" | base64 --decode

### minicube 고정 포트 사용

minikube service zion-web curl http://[minikube ip]:32209

#### 고정 URL 연결 실패시,
##### 1) port-forward 방식

kubectl port-forward svc/zion-web 8080:80

##### 2) LoadBalancer 방식

kubectl delete svc zion-web kubectl expose deployment zion-web --type=LoadBalancer --port=80 minikube tunnel

##### EXTERNAL-IP 생성확인

kubectl get svc

### Jenkins 빌드 실패
1. No credentials specified
**checkout scm** :Jenkins가 브랜치와 자격증명 다 관리

2. npm: command not found v18.20.2

curl -O https://nodejs.org/dist/v18.20.2/node-v18.20.2-darwin-x64.tar.xz tar -xf node-v18.20.2-darwin-x64.tar.xz mv node-v18.20.2-darwin-x64 ~/node echo 'export PATH=$HOME/node/bin:$PATH' >> ~/.zshrc source ~/.zshrc

```

[GitHub Push] ↓ (Webhook) [Jenkins Git Pull] ↓ [Docker Build (Minikube Docker)] ↓ [kubectl로 배포] ↓ [Minikube 앱 서비스]

: openssl 설정후, Let’s Encrypt 로 변경하려고 했으나, brew install certbot 설치 실패가 발생해, openssl 까지만 진행. cloudflare ssl : full 설정일 경우 자체서명 사용가능

1. OpenSSL 설정파일 생성

nano ~/openssl-san.cnf

[req]
default_bits       = 2048
prompt             = no
default_md         = sha256
req_extensions     = req_ext
distinguished_name = dn

[dn]
C  = KR
ST = Seoul
L  = Seoul
O  = ZionDev
OU = Dev
CN = localhost

[req_ext]
subjectAltName = @alt_names

[alt_names]
DNS.1 = localhost
IP.1  = 127.0.0.1

2. 인증서 및 키 생성

openssl req -x509 -nodes -days 365 \
  -newkey rsa:2048 \
  -keyout ~/localhost.key \
  -out ~/localhost.crt \
  -config ~/openssl-san.cnf \
  -extensions req_ext

3. nginx 설정 수정

:기존 8080, 443 포워딩 설정은 cloudflare 기능으로 대제 된다.

listen 443 ssl;
server_name  [도메인 이름];
ssl_certificate     [localhost.crt 주소];
ssl_certificate_key [localhost.key 주소];

openssl x509 -in [파일 주소].crt -text -noout | grep -A1 "Subject Alternative Name"

4. nginx 재시작

sudo nginx -s reload

도메인 설정

1. 도메인구매 및 cloudflare 설정

www.namecheap.com https://dash.cloudflare.com

brew install cloudflared
cloudflared tunnel login
cloudflared tunnel create zionlee-website-tunnel 
cloudflared tunnel run zionlee-website-tunnel 

2. cloudflare cname 설정

: 초기 A, CNAME 레코드 삭제후 실행

cloudflared tunnel route dns zionlee-website-tunnel zionlee.website

연결확인

1. nginx 443 포트 LISTEN 실행확인

: 오류 확인시, nginx 실행 여부 및 설정 확인

sudo lsof -i :443
curl -vk https://localhost

2. nginx 연결 오류시

1) PID 확인

ps aux | grep nginx
cat /usr/local/var/run/nginx.pid

2) PID 파일 수동 삭제 후 nginx 재시작

sudo rm -f /usr/local/var/run/nginx.pid
sudo nginx
sudo nginx -s reload

3. 외부 접근 확인

: 실패시, cloudflare 설정, 방화벽 확인

curl -vk [도메인 주소]

4. URL 확인