83 lines
4.4 KiB
Markdown
83 lines
4.4 KiB
Markdown
---
|
|
title: blog-topic / spring-responseentityexceptionhandler-transport-failure-envelope
|
|
source_type: blog-topic
|
|
status: raw
|
|
related_branches: [feature-api-contract-baseline]
|
|
related_projects: [ca-tmpl]
|
|
tags: [blog-topic, ca-tmpl, api-design, error-handling, spring-mvc, api-contract]
|
|
created: 2026-07-02
|
|
status_label: ready-for-canonical
|
|
target_audience: backend-engineer
|
|
inspiration_url:
|
|
archive_url:
|
|
---
|
|
|
|
# blog-topic: spring-responseentityexceptionhandler-transport-failure-envelope
|
|
|
|
> Layer: `raw/blog-topics/` — 작업 중 나온 블로그 글감 원석. 최종 블로그는 canonical 정제 후 `wiki/blog/`에서 작성한다.
|
|
|
|
## Parent / 부모
|
|
|
|
- [[raw/branch-notes/feature-api-contract-baseline]] — HTTP API baseline에서 transport failure를 error envelope로 분류한 구현/검증 경험에서 나온 글감.
|
|
|
|
## 트리거 / Trigger
|
|
|
|
- 트리거 유형: `branch-work`
|
|
- 트리거 날짜: 2026-07-02
|
|
- 트리거 연결 노트: [[raw/branch-notes/feature-api-contract-baseline]]
|
|
|
|
## 글감 / Topic seed
|
|
|
|
- 한 문장 요지: Spring MVC의 `ResponseEntityExceptionHandler` 기본 흐름을 깨지 않으면서 405/406/413/415 같은 transport failure를 공통 envelope로 정리한 경험을 쓴다.
|
|
- 예상 제목 후보:
|
|
- Spring transport failure도 같은 error envelope로 다루기
|
|
- 405와 415를 domain error처럼 보이게 만들지 않기
|
|
|
|
## 핵심 주장 후보 / Claim candidates
|
|
|
|
- 사실 후보:
|
|
- branch가 transport failure envelope 글감 후보를 직접 남겼다 — 근거 후보: [[raw/branch-notes/feature-api-contract-baseline]] section+line `:479-481`.
|
|
- 405/406/413/415 handler와 테스트가 verified item으로 언급된다 — 근거 후보: [[raw/branch-notes/feature-api-contract-baseline]] section+line `:145-156`.
|
|
- 경험 후보:
|
|
- transport failure를 공통 envelope에 넣되, domain validation/error와 같은 의미로 섞지 않는 설계가 필요했다.
|
|
- 의견/해석 후보:
|
|
- API error envelope는 "모든 실패를 같은 원인으로 보이게 하는 것"이 아니라, 원인 category를 잃지 않고 client가 일관된 shape을 받게 하는 장치다.
|
|
|
|
## Outline seed
|
|
|
|
1. transport failure와 domain failure는 다르다 — 같은 JSON shape이어도 원인 category와 복구 방식은 다르다.
|
|
2. Spring MVC 기본 exception handler를 대체할 때 생기는 위험 — framework가 이미 분류한 실패를 덮어쓰지 않아야 한다.
|
|
3. envelope의 목적은 균질화가 아니라 관측 가능한 분류다 — status, category, retryability를 잃지 않는다.
|
|
|
|
## Canonical 전환 후보 / Canonical extraction candidates
|
|
|
|
- `wiki/projects/ca-tmpl/api-evolution-and-schema.md` 후보:
|
|
- ca-tmpl HTTP API baseline의 transport failure envelope 구현 사실.
|
|
- `wiki/concepts/api-error-envelope-design.md` 후보:
|
|
- transport/framework-layer failure와 application/domain failure를 envelope에서 구분하는 일반 설계.
|
|
- 필요한 추가 검증:
|
|
- handler 클래스/테스트 이름, category 값, 실제 응답 shape 확인.
|
|
|
|
## Sources / 근거 후보
|
|
|
|
- [[raw/branch-notes/feature-api-contract-baseline]] — transport failure envelope 후보와 verified item 근거.
|
|
|
|
## 미해결 / Unknown
|
|
|
|
- 아직 확인해야 할 사실: 실제 handler method별 status/category mapping.
|
|
- 과장하면 안 되는 부분: Spring의 모든 예외를 ca-tmpl envelope가 포괄한다고 단정하지 않는다. branch에서 검증된 transport failure 범위로 제한한다.
|
|
- 블로그로 쓰기 전에 필요한 canonical 정제: `wiki/projects/ca-tmpl/api-evolution-and-schema.md`의 verified 범위 재확인.
|
|
|
|
## Decision / 처리 결정
|
|
|
|
- 액션: `promote-to-canonical`
|
|
- 이유: `wiki/projects/ca-tmpl/api-error-envelope-design.md` 에 verified transport failure row와 Spring MVC override 경계를 반영했다. HTTP API baseline 쪽 구현 anchor는 `wiki/projects/ca-tmpl/api-evolution-and-schema.md` 의 D8/D9/D12 transport errors와 연결된다.
|
|
- 다음 단계: source canonical이 `verified` 상태이므로 이후 `blogify` 대상으로 삼을 수 있다. 단 Spring MVC의 모든 예외를 포괄한다고 쓰지 않고 검증된 413/406/415/405/412 범위로 제한한다.
|
|
|
|
## Related / 관련
|
|
|
|
- 관련 branch: [[raw/branch-notes/feature-api-contract-baseline]]
|
|
- 관련 error:
|
|
- 관련 interview prep:
|
|
- derived blog: 생성 전. 생성 시 `wiki/blog/spring-responseentityexceptionhandler-transport-failure-envelope-YYYY-MM-DD.md` 후보
|