A
약 120초
API 계약을 먼저 정하는 설계 습관
JAVA 백엔드 API를 설계할 때 가장 먼저 보는 것은 인터페이스 계약입니다. 호출하는 쪽이 어떤 필드를 어떤 형태로 받는지를 먼저 정하고, 구현은 그 다음입니다. 팀 프로젝트에서 프론트엔드 팀과 협업할 때 응답 스펙을 먼저 문서화하지 않아서 나중에 필드명이 달라 양쪽이 수정한 경험이 있습니다. 그 이후로 OpenAPI Specification으로 명세를 먼저 쓰고 Mock 서버를 띄운 다음 실제 구현을 진행하는 방식을 씁니다. 변경 관리도 중요하게 봅니다.
하위 호환성이 깨지는 변경은 버전 분리(/v1, /v2)로 기존 클라이언트가 영향 받지 않도록 하는 것을 원칙으로 잡았습니다. 아직 대규모 트래픽 환경은 경험해보지 못해서, 성능 최적화나 rate limiting 같은 부분은 실제 서비스를 다뤄봐야 감이 잡힐 것 같습니다.
이 결의 특징
OpenAPI 명세를 먼저 작성하고 Mock 서버를 띄운 뒤 구현하는 순서가 나온다. 프론트엔드 협업에서 필드명 불일치로 양쪽이 수정한 경험이 이 순서를 만든 자리다.
이 결이 통하는 자리
API 설계 경험을 묻는 자리에서 이 결이 통한다. 구현보다 인터페이스 계약을 먼저 정하는 흐름이 협업 경험에서 나왔다는 점이 신뢰 인상을 만드는 자리다. 이 흐름이 읽힌다.