保存した形と外へ出す形は違う

한 줄 요약

저장한 모양과 내보내는 모양은 다르다. 이 한 줄을 지키지 않아서 생기는 사고가 백엔드 사고의 큰 몫이다.

왜 필요한가 — 사고는 조용히 일어난다

주문 표에 internal_memo 컬럼을 하나 더했다고 하자. 핸들러는 그대로다. return order 한 줄이 그대로 있고, 테스트도 다 통과한다. 그런데 그 순간부터 API 응답에 내부 메모가 실려 나간다.

아무도 에러를 못 본다. 로그도 정상이다. 컬럼을 하나 더한 것이 곧 API 변경 이었다는 사실을 아무도 인지하지 못한다.

한곳에서 정한다

고칠 곳은 핸들러가 아니다. 내보낼 필드를 한곳에 두고 그것만 통과시킨다.

const publicItem = ({ id, name, qty }) => ({ id, name, qty });

허용 목록이라는 점이 중요하다. delete item.secret 처럼 빼는 방식으로 쓰면, 다음에 컬럼이 하나 더 생길 때 또 새어 나간다. 뺄 것을 세는 대신 내보낼 것을 세야 한다.

현장에서

Nest 의 ClassSerializerInterceptor, FastAPI 의 response_model 이 하는 일이 정확히 이것이다. 이름은 다르지만 판단은 같다 — 핸들러 코드를 안 고쳐도 필드가 걸러지게 만든다.

코드 리뷰에서 볼 것도 하나다. 새 컬럼이 추가된 PR 에서 출력 모양이 함께 바뀌었는지, 아니면 자동으로 흘러 나가게 두었는지. 후자면 그 PR 은 API 변경인데 아무도 그렇게 부르지 않은 것이다.