280 lines
13 KiB
Markdown
280 lines
13 KiB
Markdown
# 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 테스트가 있는가?
|