FastAPI 응답 camelCase 통일로 프론트 변환 레이어 없애기

프론트 코드를 열어 보면 꼭 이런 파일이 하나 있어요. toCamel(response) 같은 이름으로, 서버가 준 monthly_payment를 monthlyPayment로 바꿔 주는 함수요. 처음엔 한 곳인데 화면이 늘수록 모델마다 하나씩 생겨요. 플랜 시리즈를 만들면서 세어 보니 응답 모델 6개에 변환 함수가 4곳이었어요. 필드 하나 추가하면 백엔드 스키마, 프론트 타입, 변환 함수까지 파일 3개를 같이 고쳐야 했고요.

이걸 백엔드에서 끊었어요. 서버가 애초에 camelCase로 내보내면 프론트는 받은 걸 그대로 쓰면 되니까요.

Pydantic 설정 2줄이면 돼요

직접 적용해 봤더니 핵심은 base 모델 하나였어요. (Pydantic 2 기준)

from pydantic import BaseModel, ConfigDict
from pydantic.alias_generators import to_camel
 
 
class CamelModel(BaseModel):
    model_config = ConfigDict(
        alias_generator=to_camel,
        populate_by_name=True,
    )
 
 
class LoanResult(CamelModel):
    monthly_payment: int
    total_interest: int
    repayment_count: int

alias_generator가 필드마다 camelCase 별칭을 만들고, FastAPI는 기본값이 별칭으로 직렬화하는 쪽이라 response_model=LoanResult만 붙이면 JSON이 monthlyPayment로 나가요. 플랜씨처럼 대출이자나 복리 계산 결과를 돌려주는 API라면 딱 이 모양이죠.

populate_by_name=True는 빼면 안 돼요. 테스트해 보면 이걸 뺀 순간 서버 안에서 LoanResult(monthly_payment=...)처럼 snake_case로 객체를 만드는 코드가 전부 검증 오류로 터져요. 별칭으로만 받겠다는 뜻이 되거든요. 켜 두면 파이썬 쪽은 snake, 바깥은 camel로 양쪽 다 살아요.

돌려 보니 요청 바디까지 따라왔어요

같은 base 모델을 요청 스키마에도 물렸더니 프론트가 보내는 { "principal": ..., "annualRate": ... }가 그대로 파싱됐어요. OpenAPI 문서도 camelCase로 찍히니까 TS 타입 생성기 출력과 프론트 코드가 처음으로 한 글자도 안 어긋났어요. 변환 함수 4개를 지우는 데 10분 정도 걸렸고, 이후엔 필드 추가 시 고칠 파일이 1개가 됐어요.

만들어 보니 걸리는 데가 3곳

• DB row를 모델로 만들 땐 from_attributes=True를 같이 켜야 ORM 객체 속성을 읽어요.
• 응답 경로 밖에서 직접 model_dump()를 부르면 기본은 snake예요. 로그나 백그라운드 작업에서 JSON을 만들 땐 by_alias=True를 명시해야 프론트와 같은 모양이 나와요.
• 이미 snake로 읽는 클라이언트가 배포돼 있으면 한 번에 못 바꿔요. 앱은 업데이트가 늦게 도니까 응답에 두 키를 잠시 같이 싣거나 API 버전을 나눠야 해요.

바꾸고 나서 제일 좋았던 건 프론트 PR에서 "변환 레이어 수정" 커밋이 사라진 거예요. 케이스 규칙은 취향 문제가 아니라, 경계에서 한 번만 정하면 끝나는 계약이더라고요.