Dorong Dorong 💻😴

이번 프로젝트의 첫 글이니 배경을 간단히 적자면, 해당 프로젝트는 사료 라벨과 성분 정보를 바탕으로 보호자에게 보여줄 사료 성적표를 만든다. 성적표의 핵심 판단은 규칙 기반 파이프라인이 담당한다. LLM은 등급이나 사실을 새로 판단하지 않고 이미 계산된 결과를 보호자가 읽기 쉬운 문장으로 다듬는 역할만 맡는다.

그런데 이 문장 다듬기 한 번에 약 `$0.06`이 나왔다..

처음에는 모델 단가부터 의심했다.. 문장 몇 개를 다듬는 일인데 한 번에 `$0.06`이면 운영 비용으로 부담이 크다고 느꼈다.

다만 바로 모델을 낮추거나 프롬프트를 줄이기 전에, 먼저 실제 usage부터 확인했다. 비용이 정말 이상하게 나온 것인지, 아니면 내가 요청의 크기를 작게 착각하고 있었는지부터 분리해서 봐야 했다.

확인해보니 과금 자체는 이상하지 않았다.

input_tokens: 14,448
output_tokens: 1,034
model: claude-sonnet-4-20250514
cache_creation_input_tokens: 0
cache_read_input_tokens: 0

Anthropic 공식 가격표 기준으로 Claude Sonnet 4 계열은 입력 `$3 / 1M tokens`, 출력 `$15 / 1M tokens`다.

계산은 단순했다.

입력: 14,448 * $3 / 1,000,000 = 약 $0.043
출력: 1,034 * $15 / 1,000,000 = 약 $0.015
합계: 약 $0.058

이걸 보니.. `$0.06`은 당연한 과금이었다 🥲

(해당 문단은 읽지 않아도 괜찮아요!)

이 과정에서 하나 더 발견한 것도 있었다. 당시 프로젝트에서 쓰던 `claude-sonnet-4-20250514`는 2026년 5월 기준 Anthropic 문서에서 deprecated 상태로 표시되어 있었다. deprecated는 아직 동작하지만 더 이상 권장되지 않는 상태인데, retirement 이후에는 실패할 수 있다. 문서에 적힌 retirement 예정일은 2026년 6월 15일 이었고 바로 `claude-sonnet-4-6`으로 변경했다 😎

그래서 이 문제는 두 갈래였다.

하나는 `$0.06`이 왜 나왔는지 이해하는 것!

다른 하나는 deprecated 모델을 계속 쓰지 않도록 기본 모델을 바꾸는 것!

둘은 관련은 있지만 같은 문제는 아니었다. 모델을 바꾼다고 이 요청이 갑자기 싸지는 것이 아니었기 때문이다.. Sonnet 4와 Sonnet 4.6의 기본 입력/출력 단가는 같은 구간이었고 그렇기에 비용 문제는 요청 구조를 봐야 했다.

다만 바로 프롬프트를 줄이기엔 불안했다. 이 1.4만 토큰 안에는 무의미한 문장이 아니라, 사료 성적표의 품질을 맞추기 위한 기준 문서와 모범 예시가 들어 있었다. 과금이 정상이라는 것과, 그 프롬프트 양이 최적이라는 것은 다른 문제였기에.. 비용이 왜 발생했는지 확인하고 나서 무엇을 유지하고 무엇을 줄일 수 있는지 나눠서 봐야 했다.

여기서부터 읽기 편하게 주제를 나눠보겠다

문제는 모델이 아니라 요청 구조였다

사료 성적표를 만들 때 LLM 호출에는 사료마다 달라지는 정보만 들어가지 않았다. 예를 들어 특정 제품의 원재료, 보증성분, 칼슘/인 표기 여부, 처방식 여부처럼 제품 라벨에서 추출한 사실 데이터가 들어간다. 그런데 여기에 더해, 문장 품질을 맞추기 위한 고정 문서도 함께 들어갔다.

예를 들면 이런 것들이다.

- 2026년 사료 성적표 작성 가이드
- 보호자용 문장 톤앤매너
- 내부 채점 용어를 노출하지 말라는 규칙
- 칼슘/인 누락, 처방식 등 필수 고지 문구
- 참고를 위한 모범 성적표 예시

이 문서들은 사료가 바뀌어도 거의 동일하다. 로얄캐닌을 분석할 때도 들어가고, 다른 브랜드를 분석할 때도 들어간다. 그런데 캐싱이 없으면 매 요청마다 같은 문서를 새 입력 토큰으로 결제한다.

그렇게 정리한 요청 구조 문제는 이렇다.

사료별로 달라지는 정보는 일부인데, 사료별로 달라지지 않는 긴 기준 문서가 매번 새로 읽히고 있었다.

하지만 이 기준 문서를 얼마나 줄일 수 있는지는 별도라 생각한다. 무작정 줄이면 비용은 내려가겠지만, 성적표 문장이 모범 성적표 예시에서 멀어질 수 있다. 그래서 첫 번째 선택지는 프롬프트 축소가 아니라 캐싱이었다. 같은 기준 문서를 유지하되, 반복 입력 비용부터 줄이는 쪽이 품질 리스크가 가장 작았다.

Prompt Caching은 답변 캐시가 아니다

Prompt Caching은 완성된 성적표를 저장해두는 기능이 아니다. LLM 모델이 반복되는 프롬프트 앞부분을 다시 처리하지 않도록 재사용하는 기능이다.

이때 반복되는 앞부분을 캐시 대상이 되는 고정 프롬프트라고 부르겠다.

내가 생각하는 좋은 구조는 이렇다.

[고정 시스템 지침]
[사료 성적표 작성 가이드]
[모범 성적표 예시]
[필수 고지 규칙]
-------------------------  여기까지를 cache 대상으로 봤다
[사료별로 달라지는 원재료·성분표·급여 정보]
[룰 엔진이 이미 계산한 등급 결과]
[룰 엔진이 만든 기본 사료 등급표]
[이번 요청의 사용자 조건]

위쪽의 고정 지침과 예시는 사료가 바뀌어도 거의 같다. 그래서 cache 대상이 된다.

하지만 구분선 아래의 내용은 요청마다 달라진다. 이 값들은 cache 대상이 아니다. 특히 `룰 엔진이 이미 계산한 등급 결과`는 LLM이 새로 만드는 결과가 아니라, 룰 엔진이 계산한 결과를 LLM에게 넘겨주는 값이다. LLM은 이 값을 보고 문장을 맞출 뿐, 등급 자체를 바꾸면 안 된다.

그래서 나쁜 구조는 아래와 같다고 본다.

[사료 이름]
[사용자 조건]
[현재 시간]
[고정 가이드]
[모범 성적표]

매번 바뀌는 값이 앞에 섞이면 cache hit가 깨진다. Prompt Caching은 동일한 prefix가 다시 들어왔을 때 효과가 나기 때문이다.

Claude에서는 어떻게 확인하나

Anthropic Claude API에서는 Prompt Caching을 쓰려면 요청에 `cache_control`을 넣어야 한다.

(Anthropic은 block별 지정 없이 top-level cache_control로 breakpoint를 자동 배치하는 방식도 지원하니 이 부분 링크도 첨부해 두겠다!)

그리고 캐싱이 실제로 됐는지는 응답의 `usage`필드를 보면 된다.

top-level 또는 content block 단위의 cache_control을 넣는다.

핵심 필드는 세 개다.

{
  "usage": {
    "input_tokens": 500,
    "cache_creation_input_tokens": 12095,
    "cache_read_input_tokens": 0,
    "output_tokens": 800
  }
}

의미는 이렇다.

cache_creation_input_tokens
이번 요청에서 캐시에 새로 쓴 토큰 수

cache_read_input_tokens
이번 요청에서 이미 캐시된 prefix를 읽은 토큰 수

input_tokens
캐시되지 않은 일반 입력 토큰 수

이 부분은 실제로 두 번 연속 호출해서 확인했다. 첫 번째 요청에서는 고정 프롬프트가 cache write로 잡히는지 보고, 같은 고정 프롬프트로 두 번째 요청을 보내 cache read가 잡히는지 봤다. 비용 그래프를 눈으로 보는 것보다 응답 usage에 찍히는 숫자를 확인하는 편이 훨씬 명확했다. (usage는 API 응답 JSON body 안의 필드다)

정상적으로 캐시가 잡히면 첫 요청과 두 번째 요청의 usage가 다르게 나온다.

<첫 번째 요청>
cache_creation_input_tokens = 12095
cache_read_input_tokens = 0

<두 번째 요청>
cache_creation_input_tokens = 0
cache_read_input_tokens = 12095

이 결과는 고정 프롬프트 12,095토큰이 첫 요청에서 캐시에 쓰였고, 두 번째 요청에서 재사용됐다는 뜻이다.

반대로 아래처럼 나오면 캐싱이 안 된 것이다.

cache_creation_input_tokens = 0
cache_read_input_tokens = 0

이때는 `cache_control`이 빠졌는지, 고정 프롬프트가 요청마다 달라지는지, 제품별 데이터가 캐시 구간 안에 섞였는지, 캐시 유효시간이 지났는지 확인해야 한다.

Claude에서 전체 입력 토큰을 볼 때도 주의가 필요하다. `input_tokens`만 보면 전체 입력이 아니다.

const total_input_tokens =
    input_tokens
    + cache_creation_input_tokens
    + cache_read_input_tokens

한 번의 테스트 호출에서는 usage를 직접 보면 된다. 하지만 운영 환경에서는 요청이 계속 들어옴으로 매번 응답 JSON을 사람이 확인하긴 힘들다고 생각한다. 그래서 문장 다듬기 호출마다 최소한 아래 값은 로그나 메트릭으로 남겨두려 한다.

provider
model
input_tokens
output_tokens
cache_creation_input_tokens
cache_read_input_tokens
copy_source report_reused
estimated_cost

캐싱을 적용한 뒤에는 단순히 청구 금액이 줄었는지만 보면 부족하다. Claude 응답의 `cache_read_input_tokens`가 0보다 크게 나오는지 확인해야 한다. 이 값이 있어야 고정 프롬프트를 매번 새로 읽는 것이 아니라, 실제로 캐시에서 재사용했다는 뜻이 된다!

캐시는 얼마나 유지되나

다만 당연하게도 캐시는 영구 저장소가 아니다!

유효시간이 지나면 다음 요청은 다시 cache miss가 나고, 그 순간 입력 비용이 다시 튄다 🥲 

Anthropic 공식 문서 기준으로 Claude의 `ephemeral` cache는 기본적으로 5분 lifetime을 가진다. 1시간 TTL도 선택할 수 있지만.. write 비용이 더 비싸다..! (그러니 무작정 선택하지 말자!)

가격 구조는 이렇다.

5분 cache write: 일반 input 가격의 1.25배
1시간 cache write: 일반 input 가격의 2배
cache read: 일반 input 가격의 0.1배

따라서 트래픽이 꾸준히 들어오는 서비스라면 5분 캐시가 효율적이라 생각한다. 5분 안에 같은 고정 프롬프트가 반복해서 사용되면 cache read가 발생하고, 공식 문서 기준으로 5분 캐시는 계속 refresh될 수 있다.

반대로 요청 간격이 5분을 자주 넘는다면 첫 요청마다 다시 cache write가 발생한다. 이 경우 비용이 다시 튄다..

이런 워크로드에서는 1시간 TTL을 검토할 수 있다. 다만 1시간 cache write는 2배 가격이므로, 요청 빈도와 cache hit 가능성을 보고 결정해야 한다.

요약 정리하자면 이렇다.

짧은 시간 안에 반복 호출이 많다 → 5분 cache가 유리할 가능성이 큼
요청 간격이 5분을 자주 넘지만 1시간 안에는 반복 → 1시간 TTL 검토
요청이 하루에 몇 번 수준 → Prompt Caching보다 DB 재사용, 배치, 프롬프트 축소가 더 중요할 수 있음

그래서 캐싱을 적용했다고 끝이 아니라 cache hit 비율을 봐야 한다!

const cache_hit_ratio =
	cache_read_input_tokens / total_input_tokens

위의 코드에 아래 내용을 대입해보자.

input_tokens = 500
cache_creation_input_tokens = 0
cache_read_input_tokens = 12095

그럼 결과는 아래처럼 나온다.

total_input_tokens = 12595
cache_hit_ratio = 약 96%

이 정도면 고정 프롬프트 캐싱이 잘 먹고 있다고 본다.

반대로 트래픽이 드문 시간대마다 아래처럼 나온다면 캐시가 만료되고 있는 것이다.

cache_creation_input_tokens = 12095
cache_read_input_tokens = 0

이건 실패가 아니라 cache miss다. 다만 비용은 다시 오른다 😱

고정 프롬프트를 바꿔야 할 때

캐시 대상 고정 프롬프트는 바꿔도 될까? 당연히 된다!

작성 가이드가 개선되거나, 모범 성적표가 바뀌거나, 필수 고지 문구가 바뀌면 당연히 업데이트해야 한다!

다만 고정 프롬프트가 바뀌면 기존 캐시와 prefix가 달라진다. 그러면 첫 요청은 cache miss가 나고, 새 버전의 고정 프롬프트가 다시 cache write된다. 이후 같은 새 버전이 반복되면 다시 cache hit가 난다.

즉 배포 직후에는 비용이 잠깐 튈 수 있다.

이때 고정 프롬프트가 변경된 걸 모르는 다른 팀원 입장에선 당황스러울 수 있다.

그러니 운영에서는 고정 프롬프트를 버전으로 관리하는 편이 좋다고 생각한다.

feed_report_copy_prompt_version = 2605.1
feed_report_copy_prompt_version = 2605.2

이렇게 해두면 어떤 성적표가 어떤 기준 문서로 문장 다듬기를 거쳤는지 추적할 수 있다.

변경의 성격도 나눠야 한다고 본다.

문제가 조금 바뀐 경우
-> 기존 발행 성적표를 반드시 폐기할 필요는 없음

필수 고지, 안전 문구, 정책 판단이 바뀐 경우
-> 기존 성적표 재사용 기준을 다시 봐야 함

채점 규칙이나 사료별로 달라지는 정보들의 해석이 바뀐 경우 (사료별로 달라지는 정보들을 앞으로 facts 라고 하겠다!)
-> ruleset version 또는 report publication 기준까지 같이 봐야 함

우리 서비스에서는 이미 발행된 성적표를 재사용하는 구조가 있다. 이때 고정 프롬프트가 바뀌었다고 무조건 기존 성적표를 버릴 필요는 없다. 하지만 법적 고지, 안전 문구, 리포트 정책이 바뀐 경우라면 같은 facts여도 사용자에게 보여줄 문장이 달라질 수 있다. 그런 변경은 prompt version이나 ruleset version으로 분리해야 한다.

그리고 배포 직후 첫 사용자에게 cache miss 비용과 latency를 넘기고 싶지 않다면 pre-warming도 가능하다. Anthropic 공식 문서에서는 `max_tokens: 0`을 사용해 system prompt나 tool definition을 미리 캐시에 올리는 방식이 안내되어 있다. 다만 이 경우에도 cache write 비용은 발생한다.

A 사용자의 캐시를 B 사용자가 쓸 수 있나

가능하다! 단, 같은 Anthropic workspace 안에서 동일한 프롬프트 prefix가 다시 들어와야 한다.

Anthropic 문서 기준으로 2026년 2월 5일부터 Claude API의 prompt cache는 workspace 단위로 격리된다. 다른 조직과는 공유되지 않고, 같은 조직 안에서도 workspace가 다르면 분리된다.

즉 우리 서버가 같은 Anthropic workspace로 호출하고, 고정 사료 성적표 가이드가 100% 동일하다면 A 사용자의 요청에서 만들어진 캐시를 B 사용자의 요청이 재사용할 수 있다.

하지만 사용자 조건이나 사료 facts가 cache 대상 prefix 안에 들어가면 안 된다. 그 값들은 뒤로 빼야 한다.

OpenAI로 바꾸면 어떻게 되나

회의에서 OpenAI로 변경은 어떤가? 라는 이야기가 계속 나오고 있는 중이라 알아본 김에 적어본다 😎

결론부터 말하자면 OpenAI는 방식이 다르다.

OpenAI 공식 문서 기준으로 Prompt Caching은 지원 모델에서 자동 적용된다. Claude처럼 `cache_control`을 직접 붙이는 방식이 아니다. 확인은 `usage.prompt_tokens_details.cached_tokens`로 한다.

예시는 아래와 같은 형태다.

{
  "usage": {
    "prompt_tokens": 2006,
    "completion_tokens": 300,
    "total_tokens": 2306,
    "prompt_tokens_details": {
      "cached_tokens": 1920
    }
  }
}

OpenAI도 캐시 유지시간이 있다. 2026년 5월 기준 공식 문서에는 in-memory cache가 보통 5~10분의 비활성 시간 동안 유지되고, 최대 1시간까지 갈 수 있다고 되어 있다. 일부 모델에서는 extended retention을 통해 최대 24시간 정책을 사용할 수 있다. 특히 최신 모델들에서는 `prompt_cache_retention` 설정을 지원한다.

따라서 OpenAI로 바꾼다고 캐시가 영구적으로 알아서 유지된다고 보면 안 된다. OpenAI도 반복 prefix가 안정적으로 유지되어야 하고, cache hit 여부는 `cached_tokens` 로 확인해야 한다.

회의를 진행할수록 provider가 자주 변경될 것이 예상됐다 🤔

그래서 나는 provider별 client를 아래처럼 분리해두었다.

LLM_PROVIDER=anthropic
-> Anthropic client
-> cache_control 포함
-> cache_creation_input_tokens / cache_read_input_tokens 확인

LLM_PROVIDER=openai
-> OpenAI client
-> cache_control 없음
-> prompt_tokens_details.cached_tokens 확인

이렇게 되어 있으면 나중에 OpenAI로 바꿔도 캐싱 구조를 뜯어고칠 필요는 없다. provider별 usage 필드만 공통 로그 형식으로 정리하면 된다.

OpenAI도 캐시가 조직 간 공유되지는 않는다. 그리고 Claude와 마찬가지로 output token 생성에는 영향을 주지 않는다.

Prompt Caching은 반복 입력 비용과 지연 시간을 줄이는 기능이지, 답변 생성을 생략하는 기능이 아니다.

더 싼 호출은 호출하지 않는 것

사실 캐싱보다 더 근본적인 최적화가 있다..!

이미 같은 사료에 대해 발행된 성적표가 DB에 있다면 LLM을 다시 부르면 안 된다.

하지만 단순히 사료 이름이 같다고 재사용하면 위험하다. 재사용 기준은 명확해야 한다.

(아래는 우리 프로젝트에서 사용하는 용어가 섞여있으니 용어 이해보단 느낌만 챙기자!)

- 같은 product revision인가
- 같은 resolved facts인가
- 같은 ruleset version인가
- 같은 life stage / size / health issues context인가
- 이미 done 상태로 발행된 성적표인가

이 조건이 같다면 기존 성적표를 반환하는 게 맞다. 비용도 줄고, 결과도 더 일관적이다.

이건 단순 캐시가 아니라 제품 정책을 통한 판단이다. 이미 검증된 공식 성적표가 있다면 다시 LLM에게 문장을 맡길 이유가 없다.

그렇기에 가장 싼 LLM 호출은 호출하지 않는 것이다! 

출력 길이를 줄이다는 말

처음에는 출력 길이도 비용 최적화 후보로 봤다. 하지만 잘 생각해보니 아니었다.. 😱

사료 성적표가 원래 summary와 10개의 카드로 구성되어 있다면, 카드 수를 줄이는 것은 비용 최적화가 아니다. 제품 요구사항을 바꾸는 것이다.

만약 그럼에도 무언가를 줄인다면, 줄일 수 있는 것은 구조가 아니라 군더더기다.

- JSON 밖의 설명
- 반복되는 문장
- 불필요하게 긴 line1 / line2
- 모델이 덧붙이는 사족

성적표의 형식은 유지해야 했다. 그렇기에 나는 보호자가 기대하는 결과물은 그대로 두고, 모델이 불필요하게 길게 쓰지 않도록 제한하는 방향으로 의견을 냈다. (아직 결론이 나진 않았다!

Haiku로 바꾸면 되나

Claude Haiku 4.5는 Sonnet보다 저렴하다. Anthropic 공식 가격표 기준으로 Haiku 4.5는 입력 `$1 / 1M tokens`, 출력 `$5 / 1M tokens`다. Sonnet 4 계열의 입력 `$3`, 출력 `$15`와 비교하면 같은 토큰 수에서 약 1/3 수준이다.

하지만 상대적으로 저렴하니 Haiku로 바꾸기에는 불안했다 😐

사료 성적표의 LLM은 사실을 판단하지 않지만, 그래도 중요한 역할을 한다. 등급을 바꾸면 안 되고, 내부 채점 용어를 노출하면 안 되고, 칼슘 또는 인 누락이나 처방식 안내 같은 필수 문구를 빠뜨리면 안 된다.

그래서 저렴한 모델을 쓰려면 자동 검증이 먼저 있어야 한다.

1. 일반 케이스는 Haiku 같은 저렴한 모델로 시도한다.
2. 서버가 응답을 검증한다.
3. 통과하면 사용한다.
4. 실패하면 Sonnet으로 승격한다.
5. Sonnet도 실패하면 rule-based copy로 fallback한다.

여기서 실패는 사람이 감으로 문장이 별로네라고 판단하는 것은 아니다.

서버가 최소한 이런 기준을 봐야 한다.

- JSON 파싱 가능 여부
- summary와 카드 문장 존재 여부
- line1 / line2 길이 제한
- 내부 채점 용어 노출 여부
- 필수 고지 문구 유지 여부
- 입력에 없던 사실이나 숫자 추가 여부
- grade, rule_key, title 같은 원래 결과 변경 여부

모델이 스스로 잘 썼다고 말하는 것은 검증이 아니라고 본다. 검증은 우리의 애플리케이션이 해야 한다.

내가 정리한 최적화 순서

이번 비용 문제를 보며 정리한 순서는 이렇다.

1. deprecated 모델은 retirement 전에 교체한다.
2. 이미 발행된 동일 사료 성적표는 DB에서 재사용한다.
3. 새 성적표가 필요하면 고정 가이드와 모범 예시는 Prompt Caching을 적용한다.
4. 캐시 TTL과 cache hit 비율을 로그로 확인한다.
5. 고정 프롬프트 변경은 version으로 관리한다.
6. Claude/OpenAI별 usage 필드를 공통 메트릭으로 정리한다.
7. 검증 규칙을 통과하는 범위에서 저렴한 모델을 테스트한다.
8. 실패하거나 고위험 케이스는 상위 모델로 승격한다.
9. 그래도 실패하면 rule-based copy로 fallback한다.
10. 마지막으로 품질을 해치지 않는 범위에서 프롬프트와 출력 군더더기를 줄인다.

이때 중요한 것은 순서다.

deprecated 모델 교체는 장애 예방에 가깝고, Prompt Caching은 반복 입력 비용을 줄이는 일이다. 둘 다 필요하지만 서로 해결하는 문제가 다르다.

처음부터 가이드를 줄이면 성적표 품질이 흔들릴 수 있다. 처음부터 모델을 낮추면 필수 고지나 문장 안정성이 깨질 수 있다. 반면 Prompt Caching은 프롬프트 내용을 유지한 채 반복 입력 비용을 줄인다.

그래서 첫 번째 안전한 비용 최적화는 캐싱이었다.

다만 캐싱은 영구 보관이 아니다. 5분 TTL이면 요청 간격이 5분을 넘는 순간 cache miss가 날 수 있다. 이때 비용이 다시 튀는 것은 버그가 아니라 캐시의 수명 때문이다. 그래서 운영에서는 캐싱을 켰다가 아니라 cache_read_input_tokens가 꾸준히 잡힌다까지 확인해야 했다.

결론

`$0.06`은 비정상 과금이 아니었다.

사료 성적표의 품질을 맞추기 위해 긴 고정 문서를 매번 넣고 있었고, 그 문서가 캐시되지 않았고, 출력도 1천 토큰 정도 생성됐기 때문에 나온 정상 비용이었다.

동시에 deprecated 모델을 계속 쓰고 있다는 운영 리스크도 발견했다. 이건 비용 최적화와는 별개로 처리해야 할 문제였다. 그래서 기본 모델을 retirement 전에 `claude-sonnet-4-6`으로 바꾸는 것이 맞았다.

이번에 바로 Haiku로 낮추거나 프롬프트를 줄이지 않은 이유도 여기에 있다. 비용은 줄일 수 있어도, 성적표의 신뢰가 흔들리면 제품 입장에서는 더 큰 손해다. 먼저 같은 결과는 재사용하고, 반복되는 기준 문서는 캐시하고, cache read가 실제로 잡히는지 관찰하는 쪽이 더 안전했다.

그러니 LLM 비용 최적화는 더 싼 모델을 고르는 일로 시작하면 안된다! 먼저 무엇이 매번 다시 읽히고 있는지 봐야 한다. 그리고 모델 lifecycle처럼 곧 장애가 될 수 있는 운영 리스크도 함께 봐야 한다. 그다음에 모델 교체, 프롬프트 축소, fallback 전략을 검증 규칙 위에서 다뤄야 한다.

그 순서를 지키면 비용을 줄이면서도 제품 품질을 지킬 수 있다.

참고문서

3년간 회사에서 개발하면서 나름 경험을 쌓았다고 생각했습니다.

하지만 돌이켜보면 그 경험은 이미 잘 짜인 구조 안에서 주어진 역할만 수행했었던 것 같습니다.
디자이너와의 협업 방식은 이미 정형화되어 있었고, 디자인 시스템도 구축돼 있어서 시안을 받아 구현하는 데만 집중하면 됐거든요.

이번 프로젝트에서는 모든 걸 처음부터 만들어야 했습니다. 그 과정에서 많은 것들을 새롭게 깨달았고, 특히 디자이너와의 협업에서 여러 배움들이 있었습니다!

갑자기 보이기 시작한 것들

상태에 대한 정의

디자이너님과 같은 "상태"라는 단어를 사용하고 있었는데, 실제로는 다른 방식을 생각하고 있었습니다.

• 디자이너님이 말하는 상태는 주로 시각적인 변화 — 예를 들어 색깔, 테두리, 아이콘 같은 UI 요소들이었고,
• 제가 말하는 상태는 데이터의 상태 혹은 사용자 상호작용 — 예를 들어 에러 여부, 입력 완료 여부, 네트워크 상태 같은 것이었습니다.

아래에서 자세히 설명 하겠지만 개발했던 공통 컴포넌트로 설명해 보겠습니다.

처음 시안에는 "기본, 포커스, 에러, 비활성화" 정도만 정의돼 있었어요.

그런데 실제로 구현에 들어가면서 고민이 커졌습니다.

• 이메일 필드에서 오류 메시지가 뜨는 동시에 포커스가 가면 어떻게 보여줘야 하지?
• 네트워크 오류가 발생하면서 동시에 로딩 상태도 유지해야 한다면?
• 비밀번호 필드에서는 호버 + 에러 상태가 함께 오면 어떤 UI여야 할까?

이렇게 상태 조합 많아지기 시작했어요.
회사는 이미 디자인 시스템과 공통 컴포넌트가 잘 정리돼 있어서, 이런 조합들은 신경 쓸 필요가 거의 없었거든요.
하지만 이번 프로젝트에서는 모든 것을 직접 기획하고, 디자이너님과 논의하고, 구현까지 해보면서 "상태"를 정의한다는게 얼마나 복잡하고 섬세한 일인지 체감할 수 있었습니다.

가장 처음 시작된 소통이 시작된 화면

프로젝트 초기 디자이너님이 로그인 화면 시안을 가져왔습니다. 깔끔하고 직관적인 디자인이었습니다. 하지만 구현을 시작하면서 자연스럽게 몇 가지 궁금한 점들이 생겼어요.

"로그인 실패했을 때는 어떻게 표시할까요?"

디자이너님도 "아, 그러게요. 에러 메시지가 필요하겠네요"라고 해주셨고 함께 고민해봤습니다.

예시 코드는 실제 구현 코드와 차이가 있습니다.

type LoginErrorType = 'INVALID_CREDENTIALS' | 'NETWORK_ERROR' | 'UNKNOWN_ERROR';

interface LoginError {
  type: LoginErrorType;
  message: string;
  field?: 'email' | 'password'; // 개발 환경에서만 사용
}

interface LoginState {
  status: 'idle' | 'loading' | 'success' | 'error';
  error: LoginError | null;
}

// 에러 메시지 상수 분리
const LOGIN_ERROR_MESSAGES = {
  INVALID_CREDENTIALS: '이메일 또는 비밀번호를 확인해주세요.',
  NETWORK_ERROR: '네트워크 오류가 발생했습니다. 다시 시도해주세요.',
  UNKNOWN_ERROR: '알 수 없는 오류가 발생했습니다.',
} as const;

// 개발 환경용 상세 메시지
const DEV_ERROR_MESSAGES = {
  INVALID_EMAIL: '앗! 등록되지 않은 이메일이거나 잘못 입력했어요.',
  INVALID_PASSWORD: '앗! 비밀번호가 틀렸어요. 다시 한 번 확인해주세요.',
} as const;

const useLogin = () => {
  const [state, setState] = useState<LoginState>({
    status: 'idle',
    error: null,
  });

  // 환경별 에러 메시지 처리
  const getErrorMessage = (type: LoginErrorType, field?: 'email' | 'password'): LoginError => {
    const isDevelopment = process.env.NODE_ENV === 'development';
    
    if (isDevelopment && field) {
      return {
        type,
        message: field === 'email' ? DEV_ERROR_MESSAGES.INVALID_EMAIL : DEV_ERROR_MESSAGES.INVALID_PASSWORD,
        field,
      };
    }

    return {
      type,
      message: LOGIN_ERROR_MESSAGES[type],
    };
  };

  const login = async (email: string, password: string) => {
    setState({ status: 'loading', error: null });
    
    try {
      const user = await authService.findUserByEmail(email);
      if (!user) {
        setState({
          status: 'error',
          error: getErrorMessage('INVALID_CREDENTIALS', 'email'),
        });
        return;
      }

      const isValidPassword = await authService.validatePassword(email, password);
      if (!isValidPassword) {
        setState({
          status: 'error',
          error: getErrorMessage('INVALID_CREDENTIALS', 'password'),
        });
        return;
      }

      await authService.setSession(user);
      setState({ status: 'success', error: null });
    } catch (error) {
      setState({
        status: 'error',
        error: getErrorMessage('NETWORK_ERROR'),
      });
    }
  };

  return {
    ...state,
    login,
    isLoading: state.status === 'loading',
    isSuccess: state.status === 'success',
    isError: state.status === 'error',
  };
};

디자이너님은 로그인 화면에서 어떤 방식으로 에러 메시지를 띄울지 고민하고 계셨어요.

흔히 볼 수 있는 "아이디나 비밀번호가 일치하지 않습니다"와 같은 모호한 에러 메시지 대신, "이메일이 잘못되었습니다" 또는 "비밀번호가 잘못되었습니다"처럼 구체적으로 알려주는 게 사용자 입장에서 더 친절한 UX가 아닐까에 대해 논의하였습니다.

그리고 왜 많은 웹사이트들이 로그인 실패 시 "Incorrect username or password" 처럼 모호한 메시지를 사용하는 걸까요? 라는 의문에 도달했어요.

관련해서 찾아본 결과, tarunbatra.com 블로그에서는 보안적인 이유를 강조했습니다.

로그인 오류 메시지를 구체적으로 제공할 경우, 악의적인 사용자가 해당 정보를 기반으로 유효한 계정을 추측하거나 반복적으로 조합을 시도할 수 있게 됩니다.

예를 들어, "비밀번호가 잘못되었습니다"라는 메시지를 보면 해당 사용자명은 유효하다는 것을 알 수 있기 때문에, 공격자에게 단서를 주는 셈이죠. 반면 "아이디 또는 비밀번호가 일치하지 않습니다"처럼 모호하게 처리하면 공격자는 어떤 부분이 잘못되었는지 알 수 없기 때문에 보안상 더 안전해집니다.

하지만 그 당시엔 내부 베타 테스트를 진행할 예정이었던 동물병원 관계자분들의 요청이 있었고, 테스트 편의를 위해 로그인 오류 시 어떤 필드가 잘못되었는지를 분리해서 보여주는 UX를 채택하기로 했습니다.

사용자가 어떤 필드에서 문제가 생겼는지 직관적으로 알 수 있도록, 해당 필드 바로 아래에 에러 메시지를 띄우는 방식으로 협의했고, 실제 사용자 테스트에서도 긍정적인 반응을 얻을 수 있었습니다!

편하게 쓰던 공통 컴포넌트

알리니에서는 다양한 입력 필드가 필요했습니다.

이메일, 비밀번호, 전화번호, 사료명, 브랜드명 등등...

처음에 디자이너님이 만든 텍스트필드는 기본적이 모습이었는데, 구현하면서 함께 다양한 상태를 고민하게 되었습니다.

"비밀번호 필드에서 입력 내용을 확인할 수 있는 눈 모양 아이콘이 있으면 좋겠어요."

"맞아요! 그리고 사료 등록할 때 필수 입력 항목은 라벨에 별표(*)를 표시하면 어떨까요?"

이처럼 하나하나 기능이 추가되며 필요한 상태의 수는 기하급수적으로 늘어났습니다..

예를들어 아래처럼요. (실제 알리니 구현과 차이가 있습니다)

• 기본 상태 4가지
• 호버 상태 추가 → 4 × 2 = 8
• 읽기 전용(read-only) 고려 → 8 × 2 = 16
• 필수/선택 표시 → 16 × 2 = 총 32가지 상태 조합

그런데 가장 어려웠던 건 이런 조합들이 단순히 추가만 되는 게 아니라, 서로 충돌하거나 우선순위가 있다는 점이었어요.
예를 들어 disabled와 readOnly는 동시에 true일 수 있지만, 실제로는 disabled가 readOnly를 무시해요.

즉, disabled > readOnly인 거죠.
이런 상호 의존성과 우선순위는 처음엔 전혀 인지하지 못했고, 디자이너님과 함께 한참을 논의하면서 규칙을 정리해나갔습니다:

• disabled > readOnly (우선순위 존재)
• error와 success는 상호 배타적
• focus는 사용자의 직접적인 상호작용으로만 발생

예시 코드는 실제 구현 코드와 차이가 있습니다.

import { forwardRef, useState, useCallback, useMemo, useId } from 'react';

// 디자인 토큰
const INPUT_COLORS = {
  default: {
    border: '#e1e5e9',
    background: '#ffffff',
  },
  focused: {
    border: '#00b896', // 브랜드 컬러
    background: '#ffffff',
  },
  error: {
    border: '#ff6b6b', // 빨간색
    background: '#ffffff',
  },
  disabled: {
    border: '#f4f4f4',
    background: '#f9f9f9',
  },
} as const;

// 상태 우선순위 명시적 정의
const INPUT_STATE_PRIORITY = {
  disabled: 4,
  error: 3,
  focused: 2,
  default: 1,
} as const;

type InputState = keyof typeof INPUT_STATE_PRIORITY;

// Props 타입 분리
interface BaseInputProps {
  label?: string;
  required?: boolean;
  error?: string;
  disabled?: boolean;
  placeholder?: string;
  value?: string;
  onChange?: (value: string) => void;
  onFocus?: () => void;
  onBlur?: () => void;
}

interface TextInputProps extends BaseInputProps {
  type?: 'text' | 'email' | 'tel';
  leftIcon?: React.ReactNode;
  rightButton?: React.ReactNode;
}

interface PasswordInputProps extends BaseInputProps {
  type: 'password';
  showPasswordToggle?: boolean;
}

type InputProps = TextInputProps | PasswordInputProps;

// 상태 계산 로직 분리
const getInputState = (isFocused: boolean, error?: string, disabled?: boolean): InputState => {
  if (disabled) return 'disabled';
  if (error) return 'error';
  if (isFocused) return 'focused';
  return 'default';
};

const getInputStyles = (state: InputState) => {
  const colors = INPUT_COLORS[state];
  return {
    borderColor: colors.border,
    backgroundColor: colors.background,
  };
};

const TextInput = forwardRef<HTMLInputElement, InputProps>(({
  label,
  required = false,
  type = 'text',
  error,
  disabled = false,
  placeholder,
  value,
  onChange,
  onFocus,
  onBlur,
  ...props
}, ref) => {
  const [showPassword, setShowPassword] = useState(false);
  const [isFocused, setIsFocused] = useState(false);
  
  const inputId = useId();
  const errorId = useId();
  
  const inputType = useMemo(() => {
    if (type === 'password' && !showPassword) return 'password';
    return type === 'password' ? 'text' : type;
  }, [type, showPassword]);

  const currentState = useMemo(() => 
    getInputState(isFocused, error, disabled), 
    [isFocused, error, disabled]
  );

  const inputStyles = useMemo(() => 
    getInputStyles(currentState), 
    [currentState]
  );

  // 이벤트 핸들러들
  const handleFocus = useCallback(() => {
    if (disabled) return;
    setIsFocused(true);
    onFocus?.();
  }, [disabled, onFocus]);

  const handleBlur = useCallback(() => {
    setIsFocused(false);
    onBlur?.();
  }, [onBlur]);

  const togglePasswordVisibility = useCallback(() => {
    setShowPassword(prev => !prev);
  }, []);

  const handleChange = useCallback((e: React.ChangeEvent<HTMLInputElement>) => {
    onChange?.(e.target.value);
  }, [onChange]);

  // 패스워드 토글 버튼
  const passwordToggleButton = type === 'password' && (
    <button
      type="button"
      onClick={togglePasswordVisibility}
      className="password-toggle"
      aria-label={showPassword ? '비밀번호 숨기기' : '비밀번호 보기'}
      disabled={disabled}
      style={{ 
        opacity: disabled ? 0.5 : 1,
        cursor: disabled ? 'not-allowed' : 'pointer'
      }}
    >
      {showPassword ? '🙈' : '👁️'}
    </button>
  );

  return (
    <div className="text-input">
      {label && (
        <label htmlFor={inputId} className="input-label">
          {label}
          {required && (
            <span className="required-indicator" aria-label="필수" style={{ color: '#ff6b6b' }}>
              *
            </span>
          )}
        </label>
      )}
      
      <div 
        className={`input-container input-container--${currentState}`}
        style={{
          ...inputStyles,
          border: `1px solid ${inputStyles.borderColor}`,
          borderRadius: '8px',
          padding: '12px',
          display: 'flex',
          alignItems: 'center',
          gap: '8px',
        }}
      >
        {'leftIcon' in props && props.leftIcon && (
          <span className="input-icon" aria-hidden="true">
            {props.leftIcon}
          </span>
        )}
        
        <input
          ref={ref}
          id={inputId}
          type={inputType}
          disabled={disabled}
          placeholder={placeholder}
          value={value}
          onChange={handleChange}
          onFocus={handleFocus}
          onBlur={handleBlur}
          aria-describedby={error ? errorId : undefined}
          aria-invalid={!!error}
          style={{
            flex: 1,
            border: 'none',
            outline: 'none',
            backgroundColor: 'transparent',
            fontSize: '16px',
          }}
        />
        
        {passwordToggleButton}
        
        {'rightButton' in props && props.rightButton}
      </div>
      
      {error && (
        <span 
          id={errorId} 
          className="error-message" 
          role="alert"
          style={{
            color: '#ff6b6b',
            fontSize: '14px',
            marginTop: '4px',
            display: 'block',
          }}
        >
          {error}
        </span>
      )}
    </div>
  );
});

TextInput.displayName = 'TextInput';

// 사용 예시
const LoginForm = () => {
  const [formData, setFormData] = useState({
    email: '',
    password: '',
  });
  
  const { login, isLoading, error, status } = useLogin();
  
  const handleSubmit = async (e: React.FormEvent) => {
    e.preventDefault();
    await login(formData.email, formData.password);
  };
  
  return (
    <form onSubmit={handleSubmit} style={{ maxWidth: '400px', margin: '0 auto' }}>
      <TextInput
        label="이메일"
        type="email"
        required
        value={formData.email}
        onChange={(email) => setFormData(prev => ({ ...prev, email }))}
        error={error?.field === 'email' ? error.message : undefined}
        placeholder="이메일을 입력해주세요"
        disabled={isLoading}
      />
      
      <div style={{ marginTop: '16px' }}>
        <TextInput
          label="비밀번호"
          type="password"
          required
          value={formData.password}
          onChange={(password) => setFormData(prev => ({ ...prev, password }))}
          error={error?.field === 'password' ? error.message : undefined}
          placeholder="비밀번호를 입력해주세요"
          disabled={isLoading}
          showPasswordToggle
        />
      </div>
      
      <button 
        type="submit" 
        disabled={isLoading}
        style={{
          width: '100%',
          padding: '12px',
          marginTop: '24px',
          backgroundColor: isLoading ? '#cccccc' : '#00b896',
          color: 'white',
          border: 'none',
          borderRadius: '8px',
          fontSize: '16px',
          cursor: isLoading ? 'not-allowed' : 'pointer',
        }}
      >
        {isLoading ? '로그인 중...' : '로그인'}
      </button>
      
      {error && !error.field && (
        <div style={{ 
          marginTop: '16px', 
          padding: '12px', 
          backgroundColor: '#ffebee',
          borderRadius: '8px',
          color: '#ff6b6b'
        }}>
          {error.message}
        </div>
      )}
    </form>
  );
};

"비활성화 상태일 때는 회색으로, 에러 상태일 때는 빨간색 테두리로 평범하게 가고 포커스 상태에서는 브랜드 컬러인 초록색으로 강조하면 좋겠어요"라는 의견으로 일치했습니다.

알레르기 기록의 시각화

알리니의 핵심 기능 중 하나가 반려견의 알레르기 반응을 기록하고 분석하는 건데, 이 부분에서 정말 많은 대화가 오갔습니다.

현재 구현된 상태와는 다르지만 아래와같은 고민을 했었어요.

"알레르기 정도를 어떻게 표현하면 좋을까요?"

"색깔로 구분하면 어떨까요? 빨간색은 심함, 주황색은 보통, 초록색은 낮음?"

"색약이 있는 사용자도 고려해야 할 것 같아요. 색깔과 함께 텍스트나 아이콘도 넣으면 어떨까요?"

예시 코드는 실제 구현 코드와 차이가 있습니다.

// 디자인 토큰 정의
const COLORS = {
  success: {
    main: '#00b896',
    background: '#e6f8f5',
    light: '#b3f0e6',
  },
  warning: {
    main: '#ffa726',
    background: '#fff3e0',
    light: '#ffd699',
  },
  error: {
    main: '#ff6b6b',
    background: '#ffebee',
    light: '#ffb3b3',
  },
  gray: {
    600: '#666666',
    500: '#999999',
    100: '#f5f5f5',
  },
} as const;

// 알레르기 레벨 타입
type AllergyLevel = 'low' | 'medium' | 'high';

// 알레르기 데이터 인터페이스
interface AllergyData {
  level: AllergyLevel;
  percentage: number;
  ingredients: string[];
  timestamp?: Date;
}

// 아이콘 컴포넌트들 (실제로는 아이콘 라이브러리 사용)
const CheckCircleIcon = ({ size = 16 }: { size?: number }) => (
  <svg width={size} height={size} viewBox="0 0 24 24" fill="currentColor">
    <path d="M12 2C6.48 2 2 6.48 2 12s4.48 10 10 10 10-4.48 10-10S17.52 2 12 2zm-2 15l-5-5 1.41-1.41L10 14.17l7.59-7.59L19 8l-9 9z"/>
  </svg>
);

const AlertCircleIcon = ({ size = 16 }: { size?: number }) => (
  <svg width={size} height={size} viewBox="0 0 24 24" fill="currentColor">
    <path d="M12 2C6.48 2 2 6.48 2 12s4.48 10 10 10 10-4.48 10-10S17.52 2 12 2zm1 15h-2v-2h2v2zm0-4h-2V7h2v6z"/>
  </svg>
);

const XCircleIcon = ({ size = 16 }: { size?: number }) => (
  <svg width={size} height={size} viewBox="0 0 24 24" fill="currentColor">
    <path d="M12 2C6.48 2 2 6.48 2 12s4.48 10 10 10 10-4.48 10-10S17.52 2 12 2zm5 11H7v-2h10v2z"/>
  </svg>
);

// 알레르기 레벨 설정
interface AllergyLevelConfig {
  color: string;
  backgroundColor: string;
  text: string;
  icon: React.ReactNode;
  severity: number;
  description: string; // 접근성을 위한 설명 추가
}

const ALLERGY_LEVEL_CONFIG: Record<AllergyLevel, AllergyLevelConfig> = {
  low: {
    color: COLORS.success.main,
    backgroundColor: COLORS.success.background,
    text: '알레르기 낮음',
    icon: <CheckCircleIcon size={16} />,
    severity: 1,
    description: '알레르기 반응이 낮은 수준입니다',
  },
  medium: {
    color: COLORS.warning.main,
    backgroundColor: COLORS.warning.background,
    text: '알레르기 보통',
    icon: <AlertCircleIcon size={16} />,
    severity: 2,
    description: '알레르기 반응이 보통 수준입니다',
  },
  high: {
    color: COLORS.error.main,
    backgroundColor: COLORS.error.background,
    text: '알레르기 높음',
    icon: <XCircleIcon size={16} />,
    severity: 3,
    description: '알레르기 반응이 높은 수준입니다',
  },
} as const;

// Props 인터페이스
interface AllergyItemProps {
  level: AllergyLevel;
  percentage: number;
  ingredients?: string[];
  showDetails?: boolean;
  className?: string;
  onToggleDetails?: () => void;
}

// 퍼센티지 포맷팅 함수
const formatPercentage = (value: number): string => {
  return `${Math.round(value)}%`;
};

// 메인 컴포넌트
export const AllergyItem: React.FC<AllergyItemProps> = ({
  level,
  percentage,
  ingredients = [],
  showDetails = false,
  className = '',
  onToggleDetails,
}) => {
  const config = ALLERGY_LEVEL_CONFIG[level];
  
  return (
    <div
      className={`allergy-item ${className}`}
      style={{
        backgroundColor: config.backgroundColor,
        border: `1px solid ${config.color}20`, // 20% 투명도
        borderRadius: '12px',
        padding: '16px',
        marginBottom: '8px',
        transition: 'all 0.2s ease', // 부드러운 전환
      }}
      role="article"
      aria-label={`${config.description}, ${formatPercentage(percentage)}`}
    >
      <div 
        className="allergy-header"
        style={{
          display: 'flex',
          alignItems: 'center',
          justifyContent: 'space-between',
          marginBottom: showDetails && ingredients.length > 0 ? '12px' : '0',
        }}
      >
        <div style={{ display: 'flex', alignItems: 'center', gap: '8px' }}>
          <span 
            className="allergy-icon" 
            style={{ color: config.color, display: 'flex', alignItems: 'center' }}
            aria-hidden="true"
          >
            {config.icon}
          </span>
          <span 
            className="allergy-text" 
            style={{ 
              color: config.color, 
              fontWeight: '600',
              fontSize: '14px',
            }}
          >
            {config.text}
          </span>
        </div>
        
        <div style={{ display: 'flex', alignItems: 'center', gap: '8px' }}>
          <span 
            className="allergy-percentage"
            style={{
              fontWeight: '700',
              fontSize: '16px',
              color: config.color,
            }}
          >
            {formatPercentage(percentage)}
          </span>
          
          {ingredients.length > 0 && (
            <button
              onClick={onToggleDetails}
              style={{
                background: 'none',
                border: 'none',
                cursor: 'pointer',
                padding: '4px',
                borderRadius: '4px',
                color: config.color,
                fontSize: '12px',
                transition: 'background-color 0.2s ease',
              }}
              aria-expanded={showDetails}
              aria-label={showDetails ? '세부사항 숨기기' : '세부사항 보기'}
            >
              {showDetails ? '▲' : '▼'}
            </button>
          )}
        </div>
      </div>

      {/* 색약 사용자를 위한 추가 시각적 요소 */}
      <div 
        style={{
          width: '100%',
          height: '4px',
          backgroundColor: `${config.color}30`,
          borderRadius: '2px',
          marginBottom: showDetails && ingredients.length > 0 ? '12px' : '0',
          overflow: 'hidden',
        }}
      >
        <div
          style={{
            width: `${percentage}%`,
            height: '100%',
            backgroundColor: config.color,
            borderRadius: '2px',
            transition: 'width 0.3s ease',
          }}
          role="progressbar"
          aria-valuenow={percentage}
          aria-valuemin={0}
          aria-valuemax={100}
          aria-label={`알레르기 수준 ${formatPercentage(percentage)}`}
        />
      </div>

      {showDetails && ingredients.length > 0 && (
        <div className="allergy-details">
          <h4 
            style={{ 
              margin: '0 0 8px 0',
              fontSize: '12px',
              color: COLORS.gray[600],
              fontWeight: '600',
            }}
          >
            관련 성분 ({ingredients.length}개)
          </h4>
          <ul 
            className="allergy-ingredients"
            style={{
              margin: 0,
              padding: 0,
              listStyle: 'none',
              display: 'flex',
              flexWrap: 'wrap',
              gap: '6px',
            }}
          >
            {ingredients.map((ingredient, index) => (
              <li 
                key={`${ingredient}-${index}`}
                className="allergy-ingredient"
                style={{
                  backgroundColor: `${config.color}15`,
                  color: config.color,
                  padding: '4px 8px',
                  borderRadius: '12px',
                  fontSize: '12px',
                  fontWeight: '500',
                  border: `1px solid ${config.color}30`,
                }}
              >
                {ingredient}
              </li>
            ))}
          </ul>
        </div>
      )}
    </div>
  );
};

// 알레르기 목록 컴포넌트
interface AllergyListProps {
  allergies: AllergyData[];
  title?: string;
}

export const AllergyList: React.FC<AllergyListProps> = ({ 
  allergies, 
  title = "알레르기 분석 결과" 
}) => {
  const [expandedItems, setExpandedItems] = React.useState<Set<number>>(new Set());

  const toggleDetails = (index: number) => {
    setExpandedItems(prev => {
      const newSet = new Set(prev);
      if (newSet.has(index)) {
        newSet.delete(index);
      } else {
        newSet.add(index);
      }
      return newSet;
    });
  };

  // 데이터 정렬 (심각도 순)
  const sortedAllergies = React.useMemo(() => {
    return [...allergies].sort((a, b) => {
      const configA = ALLERGY_LEVEL_CONFIG[a.level];
      const configB = ALLERGY_LEVEL_CONFIG[b.level];
      return configB.severity - configA.severity; // 심각한 것부터
    });
  }, [allergies]);

  if (allergies.length === 0) {
    return (
      <div style={{ 
        textAlign: 'center', 
        padding: '40px 20px',
        color: COLORS.gray[500],
      }}>
        알레르기 데이터가 없습니다.
      </div>
    );
  }

  return (
    <div className="allergy-list" style={{ maxWidth: '600px', margin: '0 auto' }}>
      <h3 style={{ 
        fontSize: '18px', 
        fontWeight: '700', 
        marginBottom: '16px',
        color: COLORS.gray[600],
      }}>
        {title}
      </h3>
      
      {sortedAllergies.map((allergy, index) => (
        <AllergyItem
          key={index}
          level={allergy.level}
          percentage={allergy.percentage}
          ingredients={allergy.ingredients}
          showDetails={expandedItems.has(index)}
          onToggleDetails={() => toggleDetails(index)}
        />
      ))}
    </div>
  );
};

// 사용 예시
export const AllergyExample = () => {
  const sampleData: AllergyData[] = [
    {
      level: 'high',
      percentage: 85,
      ingredients: ['닭고기', '쌀', '옥수수'],
    },
    {
      level: 'medium',
      percentage: 45,
      ingredients: ['연어', '고구마'],
    },
    {
      level: 'low',
      percentage: 15,
      ingredients: ['당근', '브로콜리', '사과'],
    },
  ];

  return <AllergyList allergies={sampleData} title="우리 강아지 알레르기 분석" />;
};

"월별 통계를 보여줄 때 그래프로 표현하면 더 직관적일 것 같아요"라는 디자이너님의 제안에 어느정도 화면이 변경되었습니다!

마치며

진행하며 고민한 디테일들은 회사에선 이미 디자인 시스템이나 공통 컴포넌트에 반영되어 있어서, 별다른 고민 없이 가져다 쓰기만 했던 것들이었어요.

이번 프로젝트에서는 그런 요소들을 직접 기획하고, 디자인에 녹여내고, 컴포넌트로 구현하는 과정을 하나하나 경험해보니, 겉으로만 알고 있었던 UI 구성 요소들이 얼마나 많은 의도와 고민 속에서 만들어졌는지를 새삼 느낄 수 있었어요.

무엇보다 그런 과정이 생각보다 꽤 재밌었습니다!

글 초반에 이야기했던 ‘상태’에 대한 정의를 스터디원들과 함께 고민하고 찾아보던 중, 아래의 블로그 글을 접하게 되었고 큰 도움을 받았습니다. 👉 The Sorry State of States - velog.io/@tap_kim

저희가 겪고 있던 고민과 같은 내용을 보며 정말 반가웠고,
덕분에 막연했던 문제들을 조금 더 빠르게 정리하고, 명확한 기준을 세울 수 있었습니다.

오늘은 제가 Context API에서 Zustand로 상태관리 도구를 전환하게 된 과정과 2024년 현재 리액트 상태관리 라이브러리들의 현황에 대해 이야기해보려 합니다.

1. Context API의 한계와 상태관리 라이브러리의 필요성

Context API로 시작한 이유

처음 알리니 프로젝트를 시작할 때는 Context API만으로 충분하다고 생각했습니다. 사용자 인증, 테마, 언어 설정 등 전역적으로 공유되어야 하는 상태들을 관리하는 데 Context API 만으로 충분했습니다.

// 초기 Context API 사용 예시
const PetContext = React.createContext<PetContextType | undefined>(undefined);

export const PetProvider: React.FC<PropsWithChildren> = ({ children }) => {
  const [petData, setPetData] = useState<PetData>({
    allergies: [],
    symptoms: [],
    foodLog: []
  });

  return (
    <PetContext.Provider value={{ petData, setPetData }}>
      {children}
    </PetContext.Provider>
  );
};

한계점 발견

하지만 프로젝트가 커지면서 여러 가지 한계점이 드러나기 시작했습니다:

• 불필요한 리렌더링: Context의 값이 변경될 때마다 해당 Context를 구독하는 모든 컴포넌트가 리렌더링되었습니다. 
• 코드 복잡도 증가: 여러 개의 Context를 중첩해서 사용하다 보니 Provider Hell이 발생했습니다.
• 상태 업데이트 로직 관리의 어려움: 비동기 작업과 복잡한 상태 업데이트 로직을 처리하는 데 한계가 있었습니다.

2. 주요 상태관리 라이브러리 비교 분석

Redux

Redux는 오랫동안 리액트 생태계의 표준과 같은 상태관리 라이브러리 입니다.

Redux의 핵심 개념

• Action: 상태 변경을 위한 이벤트를 설명하는 객체
• Reducer: Action을 받아 상태를 변경하는 순수 함수
• Store: 애플리케이션의 전체 상태를 보관하는 객체

Redux 미들웨어 생태계

• Redux Thunk: 비동기 작업을 처리하기 위한 가장 기본적인 미들웨어
• Redux Saga: 복잡한 비동기 흐름을 제어하기 위한 미들웨어
  • Generator 함수를 사용한 선언적 비동기 처리
  • 복잡한 시나리오(API 요청 취소, 재시도 등) 처리 가능
• Redux Toolkit: 보일러플레이트 코드를 줄이기 위한 공식 도구

그러나 Redux는 다음과 같은 단점이 있습니다:

• 많은 보일러플레이트 코드
• 학습 곡선이 가파름
• 작은 상태 변화에도 많은 코드 필요

Recoil

Facebook에서 만든 상태관리 라이브러리입니다.

장점

• React와의 높은 호환성
• 간단한 API (atom, selector)
• 비동기 데이터 처리가 쉬움

단점

• 아톰으로 관리되는 전역 상태를 어떤 컴포넌트라도 바로 아톰을 구독해서 업데이트를 받기에, 의존성이 여러 방향으로 엮이면서 예측하기 힘들어집니다.

Zustand

가볍고 직관적인 API를 제공하는 현대적인 상태관리 라이브러리입니다.

주요 특징

• 최소한의 보일러플레이트
• TypeScript 지원이 훌륭함
• Redux DevTools 지원
• 미들웨어 시스템 (persist, devtools 등)

예시 코드:

import create from 'zustand'

interface PetStore {
  symptoms: Symptom[]
  addSymptom: (symptom: Symptom) => void
  foodLogs: FoodLog[]
  addFoodLog: (log: FoodLog) => void
}

const usePetStore = create<PetStore>((set) => ({
  symptoms: [],
  addSymptom: (symptom) => set((state) => ({
    symptoms: [...state.symptoms, symptom]
  })),
  foodLogs: [],
  addFoodLog: (log) => set((state) => ({
    foodLogs: [...state.foodLogs, log]
  }))
}))

3. 실제 프로젝트에서의 선택: Zustand

알리니 프로젝트에서의 요구사항

1. 실시간 데이터 업데이트
2. 복잡한 상태 관리 (알레르기 증상, 음식 기록, 분석 데이터)
3. 성능 최적화
4. TypeScript 지원

Zustand 선택 이유

1. 간단한 설정과 사용법: 별도의 Provider 설정이 필요 없고, 직관적인 API를 제공합니다.
2. 성능 최적화: 필요한 상태만 구독하여 불필요한 리렌더링을 방지합니다.
3. TypeScript 지원: 타입 추론이 잘 동작하여 개발 생산성이 향상되었습니다.
4. 미들웨어 지원: persist 미들웨어를 통해 로컬 스토리지 연동이 쉬웠습니다.

Context API와의 조화

Context API와 Zustand를 함께 사용할 수 있습니다. 저는 다음과 같이 역할을 구분했습니다:

• Context API: 테마, 인증 등 애플리케이션의 전반적인 설정과 관련된 상태 관리 (단어 그대로 특정 맥락을 씌울때 사용했습니다.)
• Zustand: 비즈니스 로직과 관련된 복잡한 상태 관리

4. 결론

2024년 현재, 저는 다음과 같은 기준으로 상태관리 라이브러리를 선택했습니다:

1. 작은 프로젝트: Context API만으로도 충분
2. 중간 규모 프로젝트: Zustand
3. 대규모 프로젝트: Redux Toolkit 또는 Zustand

알리니와 같이 실시간 데이터 처리와 복잡한 상태 관리가 필요한 프로젝트에는 Zustand가 특히 적합했습니다. 코드가 간결하면서도 강력한 기능을 제공하며, 특히 TypeScript와의 호환성이 뛰어나 개발 경험이 매우 좋았습니다.

프론트엔드 개발을 하다 보면 크로스브라우징 이슈는 피할 수 없습니다.

::-webkit-input-placeholder와 같은 브라우저별 프리픽스(-webkit-, -moz-, -ms- 등)를 일일이 추가하는 건 굉장히 번거로운 작업이예요.

사실 현업에서는 개발자가 직접 이러한 프리픽스를 추가하는 것이 매우 곤란한 일입니다.

(저도 관련된 대화를 나누다 알게됐어요!)

이러한 문제를 해결하기 위해 번들러를 통해 자동으로 프리픽스를 추가해주는 방법인 Autoprefixer를 사용할 수 있습니다.

PostCSS를 기본적으로 사용하는 라이브러리라면, 혹은 CSS로 변환한 후 postcss-loader가 처리하게 한다면 개발자가 각 브라우저 환경에 맞게 스타일을 따로 작성하지 않아도 Autoprefixer가 웹킷 프리픽스와 같은 것을 자동으로 붙여줍니다.

이번 포스트에서는 PostCSS와 Autoprefixer를 활용해 해당 ISSUE를 해결하는 방법을 실제 프로젝트 경험을 바탕으로 상세히 알아보겠습니다!

PostCSS와 Autoprefixer란?

PostCSS

• JavaScript 플러그인을 사용해 CSS를 변환하는 도구
• "Post-processor"라고도 불리는 이유는 CSS를 작성한 후에 처리하기 때문
• CSS 구문 분석에 최적화된 파서를 사용해 높은 성능을 보임
• CSS 전처리기(Sass)나 후처리기로 사용 가능 (이 부분은 제가 헷갈렸던 부분이라 아래 추가설명을 넣었어요!)
  1. CSS 전처리기(SASS):
     CSS 기능을 확장한 언어 입니다. 변수, 중첩 규칙, 믹스인 등을 지원하고, PostCSS는 Sass로 작성한 코드를 처리할 수 있지만, PostCSS 자체는 Sass 문법을 사용하진 않아요.
  2. CSS 후처리기:
     PostCSS는 CSS코드가 작성된 후에 추가적인 변환 작업을 수행하는 도구로 사용될 수 있습니다.
     예를 들어, 제가 지금 작성하는 Autoprefixer 같은 플러그인을 사용해서 자동으로 브라우저 프리픽스를 추가할 수 있는 것처럼요!
• 200개 이상의 플러그인으로 다양한 기능 제공 (생태계가 큽니다!)
• 모듈화된 구조로 필요한 기능만 플러그인으로 선택적 추가 가능

Autoprefixer

• PostCSS의 대표적인 플러그인
• 브라우저 프리픽스를 자동으로 추가해주는 도구
• Browserslist 설정을 통해 지원 브라우저 범위 지정 가능

Create React App과 Vite의 기본 지원

해당 부분은 Webpack을 직접 설정하지 않을 땐 어떻게 되는 건지, 기본 설정이 되어 있는지 등이 궁금해 찾아보게 됐습니다.

Create React App (CRA)

• PostCSS와 Autoprefixer가 기본으로 설정되어 있음
• 별도 설정 없이 바로 사용 가능
• browserslist 설정도 기본 제공

CRA의 package.json을 보시면 아래와 같은 코드를 확인하실 수 있습니다.

"browserslist": {
  "production": [
    ">0.2%",
    "not dead",
    "not op_mini all"
  ],
  "development": [
    "last 1 chrome version",
    "last 1 firefox version",
    "last 1 safari version"
  ]
}

Vite

• PostCSS는 기본 지원
• Autoprefixer는 별도 설치 필요

yarn add -D autoprefixer

// vite.config.js
import autoprefixer from 'autoprefixer'

export default {
  css: {
    postcss: {
      plugins: [
        autoprefixer()
      ]
    }
  }
}

현재 프로젝트에 Custom Webpack 설정하기

커스텀 Webpack 설정에서는 수동으로 PostCSS와 Autoprefixer를 설정해야 합니다.

필요한 패키지 설치

yarn add -D postcss postcss-loader autoprefixer

웹팩 설정 예시

module.exports = {
  module: {
    rules: [
      {
        test: /\.module\.scss$/,
        use: [
          "style-loader",
          {
            loader: "css-loader",
            options: {
              modules: {
                localIdentName: "[name]__[local]--[hash:base64:5]",
              },
              importLoaders: 2,
            },
          },
          {
            loader: "postcss-loader",
            options: {
              postcssOptions: {
                plugins: [
                  ["autoprefixer"]
                ],
              },
            },
          },
          "sass-loader",
        ],
      },
      {
        test: /\.(scss|css)$/,
        exclude: /\.module\.scss$/,
        use: [
          "style-loader",
          {
            loader: "css-loader",
            options: {
              importLoaders: 2,
            },
          },
          {
            loader: "postcss-loader",
            options: {
              postcssOptions: {
                plugins: [
                  ["autoprefixer"]
                ],
              },
            },
          },
          "sass-loader",
        ],
      },
    ],
  },
  // ... 기타 웹팩 설정
};

실수했던 부분과 해결 방법

package.json에 작성돼야 하는 json 문법을. browserslistrc 파일에 적용해 버렸어요. 공식 문서를 읽다 순간적으로 착각했습니다. 너무 간단하지만 제 기준에서 치명적인 실수란 생각이 들어 기록해두려 합니다!

Browserslist 설정 오류

Error [BrowserslistError]: Unknown browser query `{`. Maybe you are using old Browserslist or made typo in query.

.browserslistrc 파일 사용 (권장)

저는 최종적으로 아래의 코드로 수정했습니다!

# 프로덕션 환경
[production]
>0.2% # 전 세계 사용률 0.2% 이상인 브라우저
not dead # 공식 지원이 중단되지 않은 브라우저
not op_mini all # Opera Mini 브라우저 제외

# 개발 환경
[development]
last 1 chrome version # 최신 크롬 버전
last 1 firefox version # 최신 파이어폭스 버전
last 1 safari version # 최신 사파리 버전

해결방법 2: package.json에 설정

{
  "browserslist": {
    "production": [
      ">0.2%",
      "not dead",
      "not op_mini all"
    ],
    "development": [
      "last 1 chrome version",
      "last 1 firefox version",
      "last 1 safari version"
    ]
  }
}

Browserslist 설정 가이드

주요 쿼리 설명

• >0.2%: 전 세계 사용률 0.2% 이상인 브라우저
• not dead: 공식 지원이 중단되지 않은 브라우저
• not op_mini all: Opera Mini 브라우저 제외
• last 1 chrome version: 최신 크롬 버전
• last 2 versions: 각 브라우저의 최신 2개 버전
• > 1%: 전 세계 점유율 1% 이상
• IE 11: IE 11 지원

설정 테스트

• browserslist.dev에서 설정을 테스트할 수 있음
• 어떤 브라우저가 포함되는지 실시간으로 확인 가능

실제 동작 예시

변환 전 CSS

.example {
  display: flex;
  user-select: none;
}

변환 후 CSS

.example {
  display: -webkit-box;
  display: -ms-flexbox;
  display: flex;
  -webkit-user-select: none;
     -moz-user-select: none;
      -ms-user-select: none;
          user-select: none;
}

주의사항과 팁!

• 로더 순서: PostCSS 로더는 Sass 로더 이후, CSS 로더 이전에 위치해야 합니다.  
  1. sass-loader (SCSS -> CSS 변환)
  2. postcss-loader (자동 프리픽스 추가)
  3. css-loader (CSS -> JS 변환)
  4. style-loader (JS -> style 태그 삽입)
• 성능 최적화: development 환경에서는 source map을 활성화하고, production에서는 비활성화하는 것이 좋습니다.
• 브라우저 지원 범위: browserslist 설정을 통해 지원할 브라우저 범위를 적절히 조절해야 합니다.

주의사항과 팁에서의 Development 환경에서 source map 활성화하는 이유 & Production 환경에서 비활성화 하는 이유에 대해서만 좀 더 자세히 알아볼게요!

Development 환경에서 source map 활성화하는 이유:

1. 디버깅 용이성
   • 개발 중에는 원본 소스 코드와 변환된 코드를 매핑하여 쉽게 디버깅할 수 있습니다
   • 브라우저의 개발자 도구에서 실제 작성한 CSS 파일의 위치와 라인을 정확히 확인 가능
   • PostCSS로 변환된 코드가 아닌 원본 코드를 직접 확인하며 수정 가능
2. 개발 효율성
   • 코드 수정 시 즉각적인 피드백 확인 가능
   • CSS 문제 발생 시 정확한 위치 추적이 가능하여 수정 시간 단축
   • 복잡한 스타일 구조에서도 원본 코드 위치를 쉽게 파악!

Production 환경에서 source map 비활성화하는 이유:

1. 파일 크기 최적화
   • source map 파일은 원본 코드와 변환된 코드의 매핑 정보를 포함하므로 상당한 크기를 차지
   • 프로덕션 환경에서는 불필요한 데이터 전송을 줄여 로딩 속도 향상
   • 일반적으로 source map 파일은 원본 파일 크기의 절반 이상을 차지할 수 있음
2. 보안 강화
   • source map이 노출되면 원본 코드 구조가 드러날 수 있음
   • 악의적를 가진 사용자가 코드 구조를 분석하는 것을 방지
   • 기업의 proprietary 코드 보호!!
3. 성능 최적화
   • 브라우저가 source map을 처리하는 추가적인 작업 제거
   • 초기 페이지 로딩 시간 단축
   • 서버 대역폭 사용량 감소

실제 설정 예시! (프로젝트 코드보다 간략화)

// webpack.config.js
module.exports = {
  mode: process.env.NODE_ENV,
  module: {
    rules: [{
      test: /\.css$/,
      use: [
        'style-loader',
        {
          loader: 'css-loader',
          options: {
            sourceMap: process.env.NODE_ENV === 'development'
          }
        },
        {
          loader: 'postcss-loader',
          options: {
            sourceMap: process.env.NODE_ENV === 'development'
          }
        }
      ]
    }]
  }
};

결론

PostCSS와 Autoprefixer를 사용하면 크로스브라우징을 위한 수동 작업을 자동화할 수 있습니다.

CRA나 Create Vite같은 경우 이미 이러한 기능을 기본으로 제공하고 있으며, 커스텀 웹팩 설정에서도 간단한 설정만으로 동일한 기능을 사용할 수 있습니다.

특히 Browserslist 설정을 통해 프로젝트의 브라우저 지원 범위를 명확히 하고, 필요한 프리픽스만 추가함으로써 최적화된 CSS를 생성할 수 있겠죠?!

.browserslistrc 파일을 사용하면 설정 관리가 더욱 용이해지며, 다른 도구들과도 설정을 공유할 수 있습니다.

여기서 "다른 도구들"은 주로 다음과 같은 CSS 또는 JavaScript 도구들을 의미합니다!

1. Autoprefixer: CSS에 필요한 브라우저 프리픽스를 자동으로 추가해주는 도구로, Browserslist 설정을 통해 어떤 프리픽스를 추가할지 결정 (지금까지 설명드린 내용이죠?!)
2. Babel: 최신 JavaScript 코드를 구형 브라우저에서도 작동할 수 있게 변환해주는 도구로, Browserslist 설정을 통해 지원할 브라우저 정의 가능
3. ESLint: JavaScript 코드의 품질을 관리하는 도구로, Browserslist와 함께 사용해 특정 브라우저 환경에 맞는 코드 스타일 적용 가능
4. Stylelint: CSS 스타일을 검사하는 도구로, Browserslist 설정을 참고하여 브라우저 호환성 관련 규칙 적용 가능

즉, .browserslistrc 파일을 사용하면 이러한 다양한 도구들이 동일한 브라우저 지원 범위를 공유하게 되어, 개발 및 유지보수 과정에서 일관성을 유지할 수 있습니다!

안녕하세요! express-openapi-validator의 HTTP 인증 관련 이슈를 해결하기 위해 PR을 제출했던 과정을 공유드리려고 합니다.

이전 포스트에서 express-openapi-validator를 사용하면서 발견한 인증 관련 이슈를 다뤘었는데요, 간단히 요약드리면:

Express.js로 REST API를 구축하며 JWT를 http-only 쿠키로 전달하려 했는데,
Authorization 헤더와 CSRF 토큰 검증에서 문제가 발생했습니다.

특히 validateHttp() 메서드가 Authorization 헤더를 필수로 요구하는 바람에,
쿠키로 JWT를 전달하는 상황에서도 헤더가 필요한 상황이 됐죠.

코드를 분석해보니 SecuritySchemes와 AuthValidator 클래스의 validateHttp 메서드에서 이 로직을 처리하고 있었고,
type: http로 설정된 스킴에서 Authorization 헤더를 강제하고 있었습니다.

이 문제를 해결하기 위해 Pull Request를 제출했고, 여러 번의 코드 리뷰와 수정 과정을 거쳐 마침내 Merge가 되어 express-openapi-validator의 Contributor가 된 여정을 오늘 상세히 공유드리려고 합니다! 🎉

🎯 첫 번째 시도: 쿠키 지원 추가

처음에는 단순히 Authorization 헤더 외에도 쿠키를 통한 인증을 지원하도록 다음과 같이 코드를 수정했습니다:

if (!authHeader && !authCookie) {
  throw Error(`Authorization header or cookie required`);
}

if (type === 'bearer') {
  if (authHeader && !authHeader.includes('bearer')) {
    throw Error(`Authorization header with scheme 'Bearer' required`);
  }

  if (!authHeader && authCookie === undefined) {
    throw Error(`Bearer token required in authorization header or cookie`);
  }
}

💡 코드 리뷰 피드백

제가 제출한 PR에 대해 메인테이너께서 중요한 피드백을 주셨습니다:

1. OpenAPI 명세에 따르면, in: cookie로 지정된 경우와 그렇지 않은 경우를 구분해야 함
2. 에러 메시지도 각각의 상황에 맞게 다르게 처리되어야 함
   • 일반적인 경우: "Authorization header required"
   • 쿠키 인증의 경우: "Cookie authentication required"

🔨 두 번째 시도: 명세 기반 수정

피드백을 반영하여 코드를 수정했지만, 여기서 또 하나의 실수가 있었습니다. 바로 프로젝트의 기존 코드 스타일을 해치는 변경사항이 포함된 것이었죠..

예를 들어 함수 시그니처나 들여쓰기, 괄호 위치 등이 프로젝트의 기존 스타일과 달랐죠.

// 제가 수정한 코드
function extractErrorsFromResults(
  results: (SecurityHandlerResult | SecurityHandlerResult[])[],
) {
  return results
    .map((result) => {
      if (Array.isArray(result)) {
        return result.map((it) => it).filter((it) => !it.success);
      }
      return [result].filter((it) => !it.success);
    })
    .flatMap((it) => [...it]);
}

// 원래 프로젝트 스타일
function extractErrorsFromResults(results: (SecurityHandlerResult | SecurityHandlerResult[])[]) {
  return results.map(result => {
    if (Array.isArray(result)) {
      return result.map(it => it).filter(it => !it.success);
    }
    return [result].filter(it => !it.success);
  }).flatMap(it => [...it]);
}

이를 빠르게 원래 프로젝트의 스타일대로 되돌리고 커밋을 추가했습니다.

하지만 여기서 끝이 아니었죠. CI 파이프라인에서 테스트를 돌려보니 두 가지 심각한 문제가 발견되었습니다:

🐛 테스트 실패 발견

이후 CI에서 두 가지 테스트가 실패한다는 것을 발견했습니다:

1. Basic 인증에서 헤더가 없을 때 발생하는 에러
2. undefined.includes() 호출로 인한 에러

AssertionError: expected 'Cannot read properties of undefined (…' 
to equal 'Authorization header required'

결론은 authHeader가 undefined일 때 발생하는 에러 메시지 문제로 인한 테스트 실패였습니다.

✨ 최종 해결책

모든 피드백과 테스트 케이스를 고려하여 다음과 같이 코드를 최종 수정했습니다:

private validateHttp(): void {
  if (['http'].includes(scheme.type.toLowerCase())) {
    const authHeader = req.headers['authorization']?.toLowerCase();
    const authCookie = req.cookies[scheme.name] || req.signedCookies?.[scheme.name];

    const type = scheme.scheme?.toLowerCase();
    if (type === 'bearer') {
      if (authHeader && !authHeader.includes('bearer')) {
        throw Error(`Authorization header with scheme 'Bearer' required`);
      }
      
      if (!authHeader && !authCookie) {
        throw Error(scheme.in === 'cookie' 
          ? `Cookie authentication required`
          : `Authorization header required`);
      }
    }

    if (type === 'basic') {
      if (!authHeader) {
        throw Error(`Authorization header required`);
      }
      if (!authHeader.includes('basic')) {
        throw Error(`Authorization header with scheme 'Basic' required`);
      }
    }
  }
}

주요 개선사항:

1. Basic 인증과 Bearer 인증의 명확한 구분
2. 쿠키 기반 인증 지원 (OpenAPI 명세 준수)
3. 적절한 에러 메시지 처리
4. undefined 체크 강화

🎓 배운 점

1. OpenAPI 명세를 더 꼼꼼히 살펴봐야 했습니다
2. 프로젝트의 전체 테스트 실행의 중요성을 다시 한번 깨달았습니다
3. 코드 스타일 가이드를 준수하는 것의 중요성을 배웠습니다

이렇게 해서 express-openapi-validator에 작은 기여를 할 수 있었네요. 오픈소스 기여는 언제나 새로운 배움의 기회인 것 같습니다.

다음에는 또 어떤 재미있는 문제를 해결하게 될지 기대가 됩니다! 😊

들어가며

최근 Allini 프로젝트를 진행하면서 몇 가지 고민이 생겼습니다.

over-fetching, waterfall 현상으로 인한 성능 저하, 그리고 무엇보다 빠른 시장 검증을 위해 다양한 라이브러리를 활용해야 하는 상황에서 발생하는 번들 사이즈 증가 문제였죠.

좋은 개발자는 단순히 모든 것을 손수 처음부터 구현하는 것이 아니라, 적절한 라이브러리를 선택하고 조잡해 빠르게 제품을 만들어내는 능력이 중요하다고 생각합니다.

하지만 이러한 접근은 필연적으로 번들 사이즈 증가라는 문제를 동반하게 되었고, 이는 제가 React 서버 컴포넌트에 관심을 갖게 된 주된 계기가 되었습니다!

1. React 서버 컴포넌트의 현재 사용 가능 여부

현재 상태

• React 18 버전: 서버 컴포넌트 미지원
• React 19 RC(Release Candidate): 서버 컴포넌트 지원

하지만 현재 React 18.2.0을 사용중인 프로젝트에서 서버 컴포넌트를 직접 사용하기는 어렵습니다.

React 19로의 업그레이드를 고려해볼 수 있지만, RC 버전이기 때문에 프로덕션 환경에서의 사용은 신중히 결정해야 합니다.

2. SSR과 서버 컴포넌트의 관계

SSR (Server-Side Rendering)

• 목적: 초기 페이지 로드 성능 개선 및 SEO 최적화
• 동작 방식:
  • 서버에서 전체 페이지의 초기 HTML을 생성
  • 클라이언트로 HTML과 JS 번들을 전송
  • 클라이언트에서 hydration 과정을 통해 인터랙티브한 앱으로 전환

이전 React 공식 문서에 따르면, React의 서버 사이드 렌더링 메서드들은 크게 세 가지 환경으로 구분됩니다:

Node.js Streams 환경용:

• renderToPipeableStream()
• renderToNodeStream() (Deprecated)
• renderToStaticNodeStream()

Web Streams 환경용 (브라우저, Deno, modern edge runtimes):

• renderToReadableStream()

스트림을 지원하지 않는 환경용:

• renderToString()
• renderToStaticMarkup()

기존 SSR의 동작 방식은 아래와 같습니다.

// 기존 SSR의 동작 방식
// 1. 서버에서 초기 렌더링
const app = ReactDOMServer.renderToPipeableStream(<App />);
// 한번에 전체 HTML을 생성하여 클라이언트로 전송

// 2. HTML 문서에 삽입
const html = `
  <!doctype html>
  <html>
    <body>
      <div id="root">${app}</div>
      <script src="/bundle.js"></script>
    </body>
  </html>
`;

공식 문서에 따르면, renderToPipeableStream을 통해 초기 셸(shell)을 렌더링하고 전송합니다.

renderToPipeableStream의 기본 개념은 아래와 같습니다.

• Node.js 환경에서 React 트리를 HTML 스트림으로 변환하는 API입니다.
• 점진적인 로딩이 가능한 스트리밍 SSR을 구현할 수 있습니다.

예시 코드

// 발전된 SSR (스트리밍 방식)
const { pipe } = renderToPipeableStream(<App />, {
  bootstrapScripts: ['/main.js'],
  onShellReady() {
    // 1. 먼저 기본 뼈대(shell)를 보냄
    // 초기 shell(Suspense 경계 위의 콘텐츠)이 준비되면 스트리밍 시작

    pipe(response);
  },
  onAllReady() {
    // 모든 콘텐츠가 준비되면 호출 (크롤러나 정적 생성용)
  }
});

기존의 renderToString은 제한적인 기능을 제공하는 반면, renderToPipeableStream은 Suspense를 완전히 지원하고 HTML 스트리밍이 가능한 더 발전된 형태의 SSR 방식입니다.

주요 차이점:

• 기존 SSR: 모든 데이터를 다 모아서 한번에 보냄 (느림)
• 새로운 SSR:
  1. 먼저 페이지의 기본 뼈대를 보내고
  2. 나머지 내용은 준비되는 대로 조금씩 보냄 (더 빠름)

쉽게 말하면, 기존 SSR은 "식당에서 모든 요리가 완성될 때까지 기다렸다가 한번에 서빙"하는 것이고, 새로운 방식은 "준비된 메뉴부터 먼저 서빙하고, 나머지는 완성되는 대로 가져다주는" 것과 비슷합니다.

React 서버 컴포넌트 (RSC)

• 목적: 번들 사이즈 최적화 및 서버 리소스 직접 접근
• 동작 방식:
  • 특정 컴포넌트를 서버에서만 실행되도록 지정
  • 서버에서 렌더링된 결과만 클라이언트로 전송
  • JS 번들에 서버 컴포넌트 코드는 미포함

두 기술의 상호보완적 관계

SSR과 서버 컴포넌트는 서로를 대체하는 기술이 아닌, 보완하는 기술입니다:

1. 역할 분담
   • SSR: 초기 페이지 로드 시 전체 HTML 생성
   • 서버 컴포넌트: 특정 컴포넌트들의 서버 실행 및 번들 크기 최적화

3. 프레임워크들의 서버 컴포넌트 구현

Next.js의 접근

Next.js는 자체적인 서버 컴포넌트 구현을 통해 React의 실험적 기능을 안정적으로 제공합니다.

1. React 코어 팀과 Next.js 팀의 협력
   • React 코어 팀의 주요 멤버들(Joe Savona, Sebastian Markbåge 등)이 Vercel(Next.js)에 합류
   • 이를 통해 React의 실험적 기능을 Next.js에서 먼저 안정적으로 구현 가능
2. 서버 컴포넌트의 발전 과정
   • 2020년: React 팀이 서버 컴포넌트 개념 첫 발표
   • React 18: 서버 컴포넌트 기초 인프라 포함, but 완전한 구현은 아님
   • Next.js 13: App Router와 함께 서버 컴포넌트 전면 도입

기술적 구현 방식

React의 Server Components에 대한 공식문서를 보면,

문서에서는 Server Components 구현에 대해 다음과 같이 언급하고 있습니다:

"To support React Server Components as a bundler or framework, we recommend pinning to a specific React version, or using the Canary release. We will continue working with bundlers and frameworks to stabilize the APIs used to implement React Server Components in the future."

이는 Server Components 구현을 위한 번들러 API가 아직 완전히 안정화되지 않았음을 시사합니다.

Next.js는 다음과 같은 방식으로 서버 컴포넌트를 구현했습니다:

// next.config.js
{
  webpack: (config, { isServer }) => {
    if (isServer) {
      // 서버 컴포넌트 처리
      config.plugins.push(new webpack.DefinePlugin({
        // marked, sanitize-html 같은 서버 전용 라이브러리들이
        // 클라이언트 번들에 포함되지 않도록 처리
        'process.env.SERVER_ONLY': JSON.stringify(true)
      }));
      
      config.module.rules.push({
        test: /\.(js|jsx|ts|tsx)$/,
        exclude: /node_modules/,
        use: {
          loader: 'babel-loader',
          options: {
            presets: ['@babel/preset-react'],
            plugins: [
              // async 컴포넌트 지원을 위한 변환
              '@babel/plugin-syntax-top-level-await',
              // Server Component의 import 구문 처리
              ['@babel/plugin-transform-modules-commonjs', {
                importInterop: 'node'
              }]
            ]
          }
        }
      });
    } else {
      // 클라이언트 컴포넌트 처리
      config.module.rules.push({
        test: /\.(js|jsx|ts|tsx)$/,
        exclude: /node_modules/,
        use: {
          loader: 'babel-loader',
          options: {
            presets: ['@babel/preset-react'],
            plugins: [
              // "use client" 지시어가 있는 파일만 클라이언트 번들에 포함
              ['./plugins/client-directive', {}],
              // Server Component의 출력을 클라이언트에서 hydrate하기 위한 변환
              ['./plugins/server-reference', {}]
            ]
          }
        }
      });
    }
    return config;
  }
}

// Server Component 렌더링 함수
async function renderServerComponent(Component, props) {
  // 문서에 언급된 것처럼 build time 또는 request time에 실행 가능
  const stream = await ReactServerDOM.renderToReadableStream(
    <Component {...props} />,
    // 클라이언트 컴포넌트의 번들 정보를 담은 매핑
    webpackMap
  );
  
  // React의 Flight 포맷으로 직렬화
  return encodeRSCPayload(stream);
}

이 구현은 공식 문서의 다음 개념들을 반영합니다:

1. "Server Components are a new type of Component that renders ahead of time, before bundling, in an environment separate from your client app or SSR server."
   • webpack 설정에서 isServer 플래그로 환경을 분리
2. "Server Components can run once at build time on your CI server, or they can be run for each request using a web server."
   • renderServerComponent 함수가 이 두 가지 케이스를 모두 지원
3. "Async Components are a new feature of Server Components that allow you to await in render."
   • 서버 측 babel 설정에 @babel/plugin-syntax-top-level-await 포함

핵심 구현 요소

1. RSC 포맷
   • 서버 컴포넌트의 렌더링 결과를 특별한 포맷으로 직렬화
   • JSON이 아닌 특별한 바이너리 형식 사용
   • React Flight 아키텍처 활용
2. 번들링 최적화
   • 서버 전용 코드를 클라이언트 번들에서 제외
   • 클라이언트 컴포넌트만 선택적으로 번들링
3. 스트리밍 지원
   • React Suspense와 통합
   • 점진적인 페이지 로딩 구현

이해를 위해 기본적인 틀에 맞춰 간소화해 구현해 봤습니다!
혹시 틀린 부분이 있다면 편하게 댓글 주시면 감사하겠습니다!

Remix의 접근

Remix는 라우터 기반의 서버 중심 아키텍처를 채택하여 유사한 이점을 제공합니다.

// Remix의 서버 사이드 로직 예시
export async function loader({ request }) {
  const data = await getProducts();
  return json(data);
}

export default function Products() {
  const products = useLoaderData();
  return (
    <div>
      <h1>Products</h1>
      <ProductList products={products} />
    </div>
  );
}

4. Next.js 앱 라우터와 서버 컴포넌트의 관계

Next.js의 앱 라우터는 서버 컴포넌트를 기본값으로 채택했습니다.  매우 중요한 아키텍처적 결정이죠?!

기본 구조

// app/layout.jsx (서버 컴포넌트)
export default function RootLayout({ children }) {
  return (
    <html>
      <body>{children}</body>
    </html>
  );
}

// app/page.jsx (서버 컴포넌트)
async function Home() {
  const data = await getData(); // 서버에서 직접 데이터 fetch
  
  return (
    <main>
      <h1>Welcome</h1>
      <ClientComponent data={data} />
    </main>
  );
}

// components/client-component.jsx
'use client';

function ClientComponent({ data }) {
  // 클라이언트 사이드 인터랙션이 필요한 컴포넌트
  return <div>{/* 인터랙티브 UI */}</div>;
}

주요 특징

자동 코드 분할

// app/products/page.jsx
import { ProductList } from './components/product-list';

async function ProductsPage() {
  const products = await fetchProducts(); // 서버에서만 실행
  return <ProductList products={products} />;
}

// 이 컴포넌트와 관련된 서버 로직은 클라이언트 번들에 포함되지 않음

스트리밍과 Suspense 통합

// app/dashboard/page.jsx
import { Suspense } from 'react';

export default function Dashboard() {
  return (
    <div>
      <Suspense fallback={<LoadingUI />}>
        <SlowComponent />
      </Suspense>
    </div>
  );
}

마치며

현재 제가 진행 중인 프로젝트에서는 React 18.2.0을 사용하고 있어 서버 컴포넌트를 직접 사용하기는 어려운 상황입니다.

하지만 고객 피드백을 받은 후 Next.js로의 마이그레이션을 고려하고 있으며, 서버 컴포넌트의 이점을 자연스럽게 활용할 수 있는 좋은 기회가 될 것 같습니다.

프로젝트가 커지며, 번들 사이즈 최적화와 서버 리소스 활용 측면에서 큰 이점을 제공할 것으로 기대됩니다!