project-auth-server/docs/standards/integration/serialization-deserialization.md

Integration Serialization / Deserialization 기준

1. 목적

이 문서는 외부 API / integration 호출에서 request serialization과 response deserialization 기준을 정의한다.

이 문서의 목표는 다음과 같다.

• provider 계약과 내부 모델을 분리한다
• 외부 payload 변화에 대한 내성을 높인다
• media type, 필드명, null/absent, 에러 바디, 날짜/시간 포맷을 일관되게 처리한다
• serialization concern이 application/domain으로 번지지 않게 한다

2. 근거 수준

• Official: Spring Framework / Spring Boot / Jackson 공식 문서에서 직접 확인되는 내용
• Official + Practice: 공식 기능 위에 Tolerant Reader 같은 실무 패턴을 결합한 내용
• Project Recommendation: 이 프로젝트 구조와 운영 방식에 맞춘 규칙

3. 기본 원칙

3.1 외부 serialization은 provider contract가 결정한다

Spring의 REST client는 HTTP 본문을 상위 Java 객체로 읽고 쓰며, JSON 외에도 application/x-www-form-urlencoded, multipart, byte array, XML 같은 형식을 converter로 다룹니다. 따라서 외부 연동 직렬화 기준은 우리 내부 JSON 취향이 아니라 provider가 요구하는 content type, field shape, wire format 이 먼저다.

프로젝트 규칙:

• provider가 JSON을 요구하면 JSON으로
• provider가 form-urlencoded를 요구하면 form으로
• provider가 XML/byte/binary를 요구하면 그 형식으로 보낸다
• “우리 서비스는 JSON 표준이 있으니 외부도 JSON으로 통일”을 금지한다

3.2 외부 DTO와 내부 모델은 반드시 분리한다

Spring client가 DTO 변환을 쉽게 해 준다고 해서, provider DTO를 내부 모델처럼 써도 된다는 뜻은 아니다. Tolerant Reader 관점에서도 payload를 읽는 코드는 한 경계에 모아야 나머지 시스템이 변경에 덜 민감해진다.

프로젝트 규칙:

• 외부 request DTO / response DTO는 provider 계약 전용 타입
• application/domain은 외부 DTO를 직접 모른다
• adapter 경계에서 내부 command/result/failure reason으로 변환한다

3.3 읽기는 느슨하게, 쓰기는 명시적으로 한다

Jackson의 ignoreUnknown=true는 외부 응답이 필드를 추가해도 파싱을 덜 깨뜨리게 해 준다. 반면 outbound request는 provider가 받지 않는 필드를 보내거나, null과 absent를 헷갈리게 보내면 계약 오류가 생긴다. 따라서 외부 연동에서는 response는 tolerant reader, request는 explicit writer 전략을 기본으로 둔다.

프로젝트 규칙:

• 외부 response DTO는 additive change에 관대할 수 있다
• 외부 request DTO는 보내는 필드를 명시적으로 통제한다
• 내부 객체를 그대로 직렬화해서 provider에 보내지 않는다

4. Request serialization 표준

4.1 outbound request는 provider 계약에 정확히 맞춘다

Spring REST client는 DTO를 바탕으로 본문을 직렬화하지만, 실제 field name과 media type은 adapter가 정해야 한다. Jackson의 @JsonProperty는 외부 필드명을 DTO 경계에서 맞추는 공식 수단이다.

프로젝트 규칙:

• provider field name mismatch는 외부 request DTO에서 해결한다
• 내부 필드명/도메인 용어를 provider 계약에 맞춰 바꾸지 않는다
• provider-specific enum/string/value shape를 request DTO에 국소화한다

4.2 request DTO는 allowlist 방식으로 설계한다

프로젝트 규칙:

• provider에 보낼 필드만 request DTO에 둔다
• 내부 계산값, 디버그 값, 서버 내부 상태를 request DTO에 섞지 않는다
• “언젠가 쓸 수 있으니 같이 보내자”를 금지한다

4.3 null과 absent는 provider 계약 기준으로 명시한다

프로젝트 규칙:

• provider가 null과 필드 omission을 다르게 해석하면 반드시 구분한다
• 기본 정책은 “의미가 다르면 DTO와 mapper에서 명시적으로 처리”
• 전역 NON_NULL 같은 설정으로 provider별 의미를 무심코 바꾸지 않는다

4.4 media type은 명시적으로 맞춘다

Spring converter는 JSON, form, multipart, byte array, XML 등을 지원한다. 외부 연동에서는 특히 OAuth/token 발급, webhook, 파일 업로드, binary download처럼 JSON이 아닌 형식이 흔하다.

프로젝트 규칙:

• application/json을 기본 추정값으로 두지 않는다
• provider가 요구하는 Content-Type과 Accept를 adapter에서 명시한다
• form 요청은 JSON DTO를 억지로 보내지 않는다

5. Response deserialization 표준

5.1 external response DTO는 tolerant reader를 기본 검토한다

Jackson의 @JsonIgnoreProperties(ignoreUnknown = true)는 인식하지 못한 필드를 deserialization에서 무시한다. Fowler의 Tolerant Reader도 producer가 필드를 추가해도 consumer가 덜 깨지도록 payload reading을 느슨하게 설계하라고 설명한다.

프로젝트 규칙:

• third-party response DTO는 ignoreUnknown=true를 기본 검토한다
• provider가 필드를 추가해도 우리 파싱이 즉시 깨지지 않게 한다
• 단, first-party API request DTO까지 이 정책을 일반화하지 않는다

5.2 success body와 error body를 분리한다

프로젝트 규칙:

• 성공 응답 DTO와 오류 응답 DTO를 따로 둔다
• provider error JSON을 success DTO에 억지로 파싱하지 않는다
• error body는 adapter가 읽고 내부 failure reason/exception으로 번역한다

5.3 raw Map/JsonNode는 마지막 수단이다

Spring/Jackson은 상위 객체 매핑과 custom deserializer를 지원한다. 따라서 외부 응답 구조가 완전히 동적이지 않다면 typed DTO가 기본이다. raw map/tree는 계약이 너무 불안정하거나 일부 필드만 읽을 때의 마지막 수단으로 본다.

프로젝트 규칙:

• 기본은 typed response DTO
• 정말 불안정한 payload만 JsonNode/Map 허용
• raw tree를 application/domain까지 들고 가지 않는다
• boundary에서 읽고 안정적인 내부 모델로 바꾼다

5.4 외부 enum은 바로 domain enum에 연결하지 않는다

프로젝트 규칙:

• provider enum/string 값은 외부 DTO 또는 mapper 단계에서 해석한다
• domain enum에 provider 값을 직접 박아 넣지 않는다
• provider가 새 enum 값을 추가할 수 있으면 UNKNOWN/기본 처리 전략을 둔다

6. 날짜/시간/숫자 규칙

6.1 날짜/시간 형식은 provider 계약을 따른다

Jackson의 JavaTimeModule은 java.time 타입을 지원하고, timestamps 기능이 꺼져 있으면 보통 ISO-8601 문자열을 사용한다. 하지만 외부 연동에서는 provider가 epoch millis, string, custom format 중 무엇을 쓰는지가 더 중요하다.

프로젝트 규칙:

• provider가 ISO-8601을 쓰면 Instant/OffsetDateTime 등으로 명시적으로 읽는다
• provider가 epoch number를 쓰면 그 계약을 DTO/커스텀 deserializer에서 처리한다
• 내부 표준 시간 타입을 provider wire format 때문에 오염시키지 않는다

6.2 숫자/정밀도는 domain 의미를 잃지 않게 한다

프로젝트 규칙:

• 금액, 환율, 정산 수치처럼 정밀도가 중요한 값은 double을 기본값으로 두지 않는다
• provider가 문자열 금액을 보내면 문자열 → 안전한 내부 수치 타입으로 변환한다
• 숫자 파싱 실패는 provider parsing failure로 다루고 domain 예외와 섞지 않는다

7. Jackson / mapper / module 규칙

7.1 메서드 안에서 new ObjectMapper()를 만들지 않는다

Spring Boot는 auto-configured JSON mapper와 RestClient.Builder/WebClient.Builder를 제공하고, 그 builder에는 converter/codecs와 적절한 공통 구성이 반영된다. 메서드마다 새 mapper를 만들면 그 구성을 우회하게 된다.

프로젝트 규칙:

• adapter 메서드 안 new ObjectMapper() 금지
• 공통 builder와 공통 mapper를 우선 사용한다
• provider 특수 규칙이 있으면 adapter configuration에서 분리해 구성한다

7.2 전역 @JacksonComponent / @JacksonMixin은 진짜 공통 규칙에만 쓴다

Spring Boot는 @JacksonComponent를 자동 등록하고, @JacksonMixin도 auto-configured mapper에 등록한다. 즉, 이 둘은 전역 영향 이 있다. 따라서 provider 하나만을 위한 특수 직렬화 규칙을 전역에 뿌리는 것은 신중해야 한다.

프로젝트 규칙:

• 여러 연동/여러 DTO에 공통인 serializer/deserializer만 전역 등록
• 특정 provider 전용 weird format은 adapter-local configuration 우선
• provider 하나 때문에 전체 애플리케이션 JSON 규칙을 바꾸지 않는다

7.3 imperative/reactive client가 쓰는 JSON mapper 경계를 의식한다

Boot는 imperative HTTP clients와 reactive HTTP clients에 대해 각각 pre-configured builder를 제공하고, preferred JSON mapper 설정도 분리해 둔다.

프로젝트 규칙:

• RestClient/WebClient에서 provider-specific codec/mapper를 바꿀 때 범위를 명시한다
• imperative client용 변경이 reactive client 전체에 번지지 않게 한다
• “한 군데 바꾸면 다 되겠지” 식 전역 변경을 지양한다

8. 검증 / 번역 규칙

8.1 파싱 성공과 비즈니스 성공을 같은 것으로 보지 않는다

프로젝트 규칙:

• JSON/XML/form parsing 성공은 “wire format 해석 성공”일 뿐
• provider가 business failure body를 200으로 줄 수도 있다
• adapter는 파싱 후에 success/error semantics를 다시 해석한다

8.2 deserialization 예외는 provider parsing failure로 번역한다

프로젝트 규칙:

• malformed payload, required field missing, unexpected type mismatch는 integration parsing failure로 번역한다
• application/domain이 Jackson 예외 타입을 직접 보지 않게 한다
• provider contract drift 여부를 운영에서 추적 가능하게 한다

9. 관측 가능성 규칙

9.1 payload 전문 로그를 기본 금지한다

외부 payload는 PII, 토큰, 비밀값, 내부 식별자 등을 포함할 수 있다. 이전 observability 기준과 마찬가지로, serialization/deserialization 문제를 추적한다는 이유로 request/response 전문을 기본 로그에 남기지 않는다. 이 점은 OWASP의 민감정보 로그 금지 원칙과도 맞다.

프로젝트 규칙:

• 기본 로그는 provider, operation, status, contentType, payloadBytes, parse failure type 정도만
• payload 원문은 기본 금지
• 꼭 필요하면 테스트/격리 환경에서 제한적으로 남긴다

9.2 parse failure는 contract drift 신호로 남긴다

프로젝트 규칙:

• deserialization 실패는 단순 예외로 묻지 않는다
• provider, operation, content type, failing field/shape 정도를 안전하게 남긴다
• “provider contract가 변했을 수 있음”을 운영에서 추적할 수 있어야 한다

10. 테스트 규칙

10.1 외부 DTO는 fixture 기반 계약 테스트를 둔다

프로젝트 규칙:

• 대표 성공 응답
• 대표 오류 응답
• provider가 필드를 추가한 응답
• 일부 필드 누락 응답
• 에 대한 parsing 테스트를 둔다
• provider 예시 payload나 실제 캡처 샘플을 fixture로 관리할 수 있다

10.2 request serialization도 golden sample로 확인한다

프로젝트 규칙:

• provider에 보내는 JSON/form/XML shape를 golden sample로 검증한다
• field name, null/absent, date/time format, enum value가 계약대로 직렬화되는지 확인한다
• “직렬화는 framework가 알아서 하겠지”에 기대지 않는다

11. 다른 문서와의 경계

이 문서는 외부 provider payload의 serialization/deserialization 만 다룬다. 아래 주제의 source of truth는 별도 문서다.

• external API client structure
• timeout
• retry
• outbound idempotency
• fallback
• exception translation

이 문서는 위 문서를 반복하지 않고, payload contract를 읽고 쓰는 경계 규칙 만 정의한다.

12. 금지 규칙

다음은 기본 금지다.

• 내부 domain/entity를 외부 request/response DTO로 직접 사용
• provider response DTO를 application/domain 시그니처에 그대로 전달
• 메서드 안 new ObjectMapper() 생성
• 특정 provider 응답 대응을 위해 전역 mapper 규칙을 무심코 변경
• first-party API strict 정책과 external response tolerant 정책을 혼동
• success/error body를 같은 DTO로 억지 파싱
• payload 전문 로그를 기본으로 남김
• 외부 enum/string 값을 바로 domain enum에 박아 넣음

13. 체크리스트

다음 질문에 “예”로 답할 수 있어야 한다.

• provider request/response DTO와 내부 모델이 분리되어 있는가?
• outbound request가 provider contract를 정확히 반영하는가?
• external response는 additive change에 대해 필요한 만큼 tolerant한가?
• success body와 error body DTO가 분리되어 있는가?
• null과 absent 의미를 provider 계약 기준으로 다루는가?
• provider-specific weird format이 adapter 경계 안에 갇혀 있는가?
• RestClient/WebClient의 공통 builder/mapper 구성을 우회하지 않는가?
• serialization/deserialization fixture 테스트가 있는가?