82 lines
4.0 KiB
Markdown
82 lines
4.0 KiB
Markdown
---
|
|
title: blog-topic / spring-boot-serialization-contract-pins
|
|
source_type: blog-topic
|
|
status: raw
|
|
related_branches: [feature-schema-serialization-contract]
|
|
related_projects: [ca-tmpl]
|
|
tags: [blog-topic, ca-tmpl, api-design, spring-boot, json, api-contract, static-analysis]
|
|
created: 2026-07-02
|
|
status_label: ready-for-canonical
|
|
target_audience: backend-engineer
|
|
inspiration_url:
|
|
archive_url:
|
|
---
|
|
|
|
# blog-topic: spring-boot-serialization-contract-pins
|
|
|
|
> Layer: `raw/blog-topics/` — 작업 중 나온 블로그 글감 원석. 최종 블로그는 canonical 정제 후 `wiki/blog/`에서 작성한다.
|
|
|
|
## Parent / 부모
|
|
|
|
- [[raw/branch-notes/feature-schema-serialization-contract]] — Jackson/BigDecimal/datetime serialization pin과 ArchUnit guard 구현에서 나온 글감.
|
|
|
|
## 트리거 / Trigger
|
|
|
|
- 트리거 유형: `branch-work`
|
|
- 트리거 날짜: 2026-07-02
|
|
- 트리거 연결 노트: [[raw/branch-notes/feature-schema-serialization-contract]]
|
|
|
|
## 글감 / Topic seed
|
|
|
|
- 한 문장 요지: Spring Boot serialization을 framework default에 맡기지 않고 명시 pin, effective bean test, ArchUnit rule로 고정한 이유를 정리한다.
|
|
- 예상 제목 후보:
|
|
- Spring Boot serialization contract를 default 대신 pin으로 관리하기
|
|
- BigDecimal과 datetime serialization을 테스트 가능한 계약으로 만들기
|
|
|
|
## 핵심 주장 후보 / Claim candidates
|
|
|
|
- 사실 후보:
|
|
- branch가 별도 blog candidate를 직접 남겼고 serialization pin 구현 결과를 기록했다 — 근거 후보: [[raw/branch-notes/feature-schema-serialization-contract]] line `:302`, D1-D4 `:130-135`, implementation `:244-250`.
|
|
- 경험 후보:
|
|
- BigDecimal double constructor 차단과 effective ObjectMapper test는 "설정값이 있다"가 아니라 "실제로 적용된다"를 확인하기 위한 장치다.
|
|
- 의견/해석 후보:
|
|
- serialization policy는 API compatibility의 일부라서 default drift를 방치하면 client contract가 흔들릴 수 있다.
|
|
|
|
## Outline seed
|
|
|
|
1. serialization default는 API contract가 아니다 — framework upgrade와 설정 drift를 고려해야 한다.
|
|
2. pin + effective bean test 조합 — yml 값과 실제 ObjectMapper 동작을 같이 확인한다.
|
|
3. ArchUnit으로 금지 API를 막기 — `new BigDecimal(double)` 같은 실수를 compile/test 단계에서 잡는다.
|
|
|
|
## Canonical 전환 후보 / Canonical extraction candidates
|
|
|
|
- `wiki/projects/ca-tmpl/api-evolution-and-schema.md` 후보:
|
|
- ca-tmpl schema/serialization contract 구현 사실.
|
|
- `wiki/concepts/api-evolution-and-schema.md` 후보:
|
|
- serialization compatibility와 numeric precision 일반 개념.
|
|
- 필요한 추가 검증:
|
|
- ObjectMapper test, ArchUnit rule, BigDecimal/datetime sample output.
|
|
|
|
## Sources / 근거 후보
|
|
|
|
- [[raw/branch-notes/feature-schema-serialization-contract]] — serialization pin과 implementation 근거.
|
|
|
|
## 미해결 / Unknown
|
|
|
|
- 아직 확인해야 할 사실: per-API money field 직렬화 예제가 실제로 존재하는지.
|
|
- 과장하면 안 되는 부분: 모든 API serialization 문제가 해결됐다고 쓰지 않는다. branch에서 구현/검증한 pin과 guard 범위로 제한한다.
|
|
- 블로그로 쓰기 전에 필요한 canonical 정제: project 문서의 verified 항목과 needs-confirmation 항목 분리.
|
|
|
|
## Decision / 처리 결정
|
|
|
|
- 액션: `promote-to-canonical`
|
|
- 이유: `wiki/projects/ca-tmpl/api-evolution-and-schema.md` 의 schema/serialization 섹션에 output serialization pin, effective `ObjectMapper` test, BigDecimal constructor guard 범위로 반영했다.
|
|
- 다음 단계: source canonical이 `verified` 상태이므로 이후 `blogify` 대상으로 삼을 수 있다. 단 입력측 deser switch와 per-API money 직렬화 예제는 별도 owner/미구현 범위로 표시한다.
|
|
|
|
## Related / 관련
|
|
|
|
- 관련 branch: [[raw/branch-notes/feature-schema-serialization-contract]]
|
|
- 관련 error:
|
|
- 관련 interview prep:
|
|
- derived blog: 생성 전. 생성 시 `wiki/blog/spring-boot-serialization-contract-pins-YYYY-MM-DD.md` 후보
|