인터페이스 코딩 규칙 정리

인터페이스에서 규칙 정의가 필요한 항목

dictionary-api 저장소가 국립국어원 표준국어대사전/한영사전 오픈API를 연동하는 방식 (interfaces 패키지, StdictClient/KrdictClient)을 기준으로 정리한다.

외부 API 호출은 Spring **RestClient**로 통일한다. RestClient.builder()를 직접 호출하지 않고, Spring Boot가 자동 구성한 RestClient.Builder를 주입받아 baseUrl만 지정하는 전용 Config 빈(StdictConfig/KrdictConfig)을 둔다.
JSON 응답은 기본 Jackson으로, XML만 지원하는 API는 클래스패스의 jackson-dataformat-xml을 Spring Boot가 자동 구성하는 JacksonXmlHttpMessageConverter를 그대로 쓴다 — 별도 컨버터를 직접 등록하지 않는다.

외부 API 연동 클라이언트는 특정 기능(feature)에 종속되지 않는 공용 레이어이므로, 각 기능 패키지가 아니라 최상위 interfaces 패키지에 둔다.
인증키는 프로퍼티(예- stdict.api-key, krdict.api-key)로 설정하고, 값은 프로파일 설정에 ENC(...)로 암호화해 저장한다.
응답 포맷이 API마다 다를 수 있음을 클라이언트가 흡수한다 — 검색 결과가 1건이면 배열이 아니라 단일 객체로 오는 등의 API별 특이사항은 클라이언트 내부에서 정규화하고, 호출부에는 일관된 형태로만 노출한다.
외부 서버(WAF 등)의 요구사항 때문에 필요한 헤더 보정 같은 우회 로직은 클라이언트 내부에 격리하고, 그 이유를 주석으로 남긴다.
신규 인터페이스는 CRUD 저장 흐름과 바로 연결하지 않고 호출/파싱까지 먼저 구현한 뒤, 실제 저장 연동은 별도 단계로 진행할 수 있다.

클라이언트 자체는 MockRestServiceServer.bindTo(RestClient.Builder)로 요청 파라미터 구성과 응답 파싱만 검증하는 순수 단위테스트로 커버한다. Spring 컨텍스트를 띄우지 않고, 실제 네트워크 호출도 하지 않는다.
실제 외부 API를 진짜로 호출해 연동을 확인하는 테스트는 @Tag("integration")으로 분리한다. 하루 호출 제한·네트워크 의존성 때문에 일반 빌드/테스트(./gradlew build/test)에는 포함하지 않고, 별도 태스크(./gradlew integrationTest)로만 수동 실행한다.
이 인터페이스를 호출하는 컨트롤러를 테스트할 때는 클라이언트를 @MockitoBean으로 대체해 실제 네트워크 호출 없이 라우팅/응답 조립만 검증한다.