FastAPI 응답을 camelCase로: Pydantic alias_generator 실전

백엔드 코드에서는 monthly_payment 같은 snake_case가 편해요. 그런데 프론트에서는 monthlyPayment가 자연스럽죠. 이 둘이 어긋나면 프론트에서 매번 키를 바꿔 받거나, 백엔드 변수 이름을 억지로 camelCase로 쓰게 돼요. 혹시 응답 하나 받을 때마다 res.monthly_payment인지 monthlyPayment인지 헷갈렸던 적 없나요?

혼자 API랑 앱을 같이 만들다 보면 이 경계에서 시간을 은근히 많이 까먹어요. 저도 처음엔 프론트에서 매핑 함수를 하나 두고 손으로 바꿨는데, 필드가 20개쯤 되니까 관리가 안 되더라고요.

왜 굳이 응답 쪽에서 바꿀까

규칙은 하나만 정하는 게 편해요. "백엔드 내부는 snake_case, 밖으로 나가는 JSON은 camelCase" 이렇게요. 그러면 파이썬 코드는 파이썬답게 두고, 프론트 계약만 camelCase로 맞춰줄 수 있어요. 변환 위치를 응답 직렬화 한 곳으로 몰아두는 거예요.

alias_generator 3줄이면 끝

Pydantic v2에는 pydantic.alias_generators.to_camel 함수가 들어 있어요. 이걸 model_config에 물려주면 필드 이름을 알아서 camelCase 별칭으로 만들어줘요. 공용 베이스 모델 하나만 만들어두면 돼요.

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_months: int

FastAPI는 response_model을 직렬화할 때 기본으로 별칭을 써요. 그래서 라우터에서 response_model=LoanResult만 걸어두면 클라이언트가 받는 JSON은 이렇게 나가요.

{
  "monthlyPayment": 512000,
  "totalInterest": 2300000,
  "repaymentMonths": 36
}

직접 붙여 보니 설정 3줄에 함수 하나로 프로젝트 전체 응답이 정리됐어요. 10분이면 기존 모델을 베이스 교체로 갈아끼울 수 있었고요.

요청도 camelCase로 받고 싶다면

위 설정에서 populate_by_name=True가 핵심이에요. 이게 없으면 별칭을 붙이는 순간, 파이썬 코드에서 모델을 만들 때도 monthlyPayment로만 넣어야 해서 내부 코드가 지저분해져요. 이 옵션을 켜두면 필드 이름(snake_case)으로도, 별칭(camelCase)으로도 값을 채울 수 있어요.

요청 바디를 받을 때도 같은 베이스를 쓰면 프론트가 보낸 camelCase JSON을 그대로 파싱해줘요. 들어올 때도 나갈 때도 계약이 한 벌로 맞춰지는 거죠.

적용하면서 걸렸던 한 가지

라우터에서 모델을 반환하지 않고 dict를 손으로 만들어 반환하면 별칭이 안 붙어요. 이때 응답은 snake_case로 새어 나가요. 테스트해 보면 이런 곳이 꼭 한두 군데 남아 있더라고요.

모델 인스턴스를 직접 직렬화할 일이 있으면 model_dump()는 기본이 by_alias=False라 model_dump(by_alias=True)로 명시해야 camelCase가 나와요. 돌려 보니 이 두 지점만 정리하면 응답 키가 튀는 일이 없었어요. 겪어 보니 자동 변환을 켰다고 방심하지 말고, 계약 테스트로 대표 응답 몇 개의 키를 한 번씩 확인해두는 게 마음 편해요.

플랜씨(plan-c)의 금융계산기 API처럼 프론트가 바로 화면에 꽂아 쓰는 응답일수록 이 경계가 깔끔해야 손이 덜 가요. 규칙을 코드가 아니라 설정으로 강제해두면, 나중에 필드를 추가해도 계약이 저절로 맞춰지는 게 제일 큰 이점이었어요.