fix: 하네스 제거 및 keycloak 문서 보강
This commit is contained in:
DongHyeonka
@@ -1 +0,0 @@
|
||||
../../vault/40-publish/blog/ca-tmpl-api-error-envelope-design-2026-07-02.md
|
||||
@@ -0,0 +1,239 @@
|
||||
---
|
||||
title: API Error Envelope을 프로젝트 계약으로 고정하기
|
||||
source_type: blog
|
||||
status: verified
|
||||
confidence: high
|
||||
tags: [blog, ca-tmpl, api-design, error-handling]
|
||||
related_projects: [ca-tmpl]
|
||||
last_reviewed: 2026-07-02
|
||||
canonical_sources:
|
||||
- wiki/projects/ca-tmpl/api-error-envelope-design
|
||||
- wiki/concepts/api-error-envelope-design
|
||||
audience: backend-engineer
|
||||
target_publish:
|
||||
status_label: ready
|
||||
---
|
||||
|
||||
# API Error Envelope을 프로젝트 계약으로 고정하기
|
||||
|
||||
## Parent / 부모 (필수)
|
||||
|
||||
- Canonical source: [[wiki/projects/ca-tmpl/api-error-envelope-design]]
|
||||
- Supporting concept: [[wiki/concepts/api-error-envelope-design]]
|
||||
|
||||
## 타깃 독자 / Target reader
|
||||
|
||||
- Spring Boot 기반 REST API에서 error response contract를 정해야 하는 백엔드 엔지니어.
|
||||
- 이미 HTTP status, Spring MVC exception handling, validation error mapping의 기본은 알고 있다고 가정한다.
|
||||
- 이 글에서 처음 보게 될 포인트: `ProblemDetail`을 거부하는 이유가 "표준이 싫어서"가 아니라, 프로젝트가 요구한 success/error 대칭 envelope과 운영 메타데이터 계약 때문이라는 점.
|
||||
|
||||
## 도입 / Hook
|
||||
|
||||
API 실패 응답은 보통 나중에 정리하려고 미루기 쉽다. 그런데 validation, security, transport failure, business rule violation이 각자 다른 JSON shape을 반환하기 시작하면 client는 실패 원인을 안정적으로 분기할 수 없고, 운영자는 응답과 로그/트레이스를 한 번에 이어 보기 어렵다.
|
||||
|
||||
ca-tmpl에서는 Spring 6+의 `ProblemDetail`을 그대로 쓰지 않고, `{ success, data, error, meta }` 형태의 custom envelope을 프로젝트 계약으로 고정했다. 이 글은 그 결정이 어떤 요구에서 나왔고, 어디까지 코드로 구현되고 로컬 검증됐으며, 아직 구현됐다고 말하면 안 되는 부분이 무엇인지 정리한다.
|
||||
|
||||
## 본문 outline / Body outline
|
||||
|
||||
1. 실패 응답 shape이 흩어질 때 생기는 문제
|
||||
- validation, security, transport failure가 서로 다른 응답 구조를 만들면 client 분기와 테스트가 어려워진다.
|
||||
- ca-tmpl의 목표는 모든 실패를 같은 원인으로 섞는 것이 아니라, 같은 envelope 안에서 status/code/category 의미를 보존하는 것이다.
|
||||
|
||||
2. 왜 `ProblemDetail`을 그대로 쓰지 않았나
|
||||
- `ProblemDetail`은 실패 전용 평면 shape이다.
|
||||
- ca-tmpl은 성공과 실패를 같은 top-level envelope으로 감싸고, `error.code`, `error.category`, `error.retryable`, `error.details`, `meta`를 1급 계약으로 두고 싶었다.
|
||||
- 따라서 표준 위에 다시 custom 확장층을 얹기보다 프로젝트 전용 envelope을 명시적으로 선택했다.
|
||||
|
||||
3. ca-tmpl envelope의 핵심 필드
|
||||
- `success`: client의 1차 분기 기준.
|
||||
- `data`: 성공 응답 payload.
|
||||
- `error.code`: machine-readable error identifier.
|
||||
- `error.category`: 운영 분류.
|
||||
- `error.retryable`: client retry 판단의 최소 힌트.
|
||||
- `error.details`: validation field error 같은 항목별 오류.
|
||||
- `meta`: `requestId`, `traceId`, `correlationId`로 응답과 로그/트레이스를 연결하는 영역.
|
||||
|
||||
4. 구현으로 고정한 계약
|
||||
- `Envelope`, `ApiError`, `ResponseMeta`, `Category`, `OperationalError`, `ApiErrorCode`.
|
||||
- `GlobalExceptionHandler`, `ErrorResponseFactory`, `EnvelopeBodyAdvice`.
|
||||
- `ProblemDetail` import 금지 ArchUnit rule.
|
||||
- `spring.mvc.problemdetails.enabled: false` pin과 config regression test.
|
||||
|
||||
5. transport failure까지 같은 shape으로 태우기
|
||||
- 413, 406, 415, 405(+`Allow`), 412는 envelope shape으로 반환되도록 테스트됐다.
|
||||
- Spring MVC `ResponseEntityExceptionHandler`가 이미 다루는 umbrella exception은 중복 `@ExceptionHandler`가 아니라 protected override로 다룬다.
|
||||
- 이 범위는 검증된 transport row에 한정한다.
|
||||
|
||||
6. 아직 말하면 안 되는 부분
|
||||
- 운영 배포와 prod metric 검증은 없다.
|
||||
- `Retry-After` header 발행은 planned/stub이다.
|
||||
- 5xx span ERROR 기록도 planned/stub이다.
|
||||
- business rule violation의 세부 category/details mapping은 별도 owner branch 책임이다.
|
||||
|
||||
## 본문 / Body
|
||||
|
||||
API error response는 처음에는 작아 보입니다. 실패하면 적당한 HTTP status와 message만 내려주면 될 것처럼 보입니다. 그런데 프로젝트가 커지면 이야기가 달라집니다. validation 실패는 field 목록을 내려주고, 인증 실패는 Spring Security가 다른 shape을 만들고, 잘못된 `Content-Type`이나 큰 request body는 Spring MVC transport layer에서 또 다른 응답을 만들 수 있습니다.
|
||||
|
||||
이 상태가 오래가면 client 입장에서는 "실패했다"는 사실보다 "이번 실패는 어떤 모양으로 오지?"를 먼저 걱정해야 합니다. 운영하는 사람 입장에서도 비슷합니다. 응답에 trace id가 있는지, 재시도해도 되는 오류인지, validation 문제인지 인증 문제인지가 매번 다른 위치에 있으면 로그와 응답을 이어서 보기 어렵습니다.
|
||||
|
||||
ca-tmpl에서 API Error Envelope을 먼저 계약으로 잡은 이유는 여기에 있습니다. 목표는 모든 실패를 똑같은 원인으로 뭉개는 것이 아니었습니다. HTTP status와 error code의 의미는 유지하되, client가 읽는 바깥 구조를 하나로 맞추는 것이었습니다.
|
||||
|
||||
쉽게 말하면 실패 응답에도 "봉투"를 하나 씌운 셈입니다. 봉투 바깥에는 `success`, `data`, `error`, `meta`가 있고, 실패일 때는 `success=false`, `data=null`, `error`에 실제 오류 정보가 들어갑니다. `meta`에는 요청과 로그, trace를 이어 볼 수 있는 id들이 들어갑니다.
|
||||
|
||||
```json
|
||||
{
|
||||
"success": false,
|
||||
"data": null,
|
||||
"error": {
|
||||
"code": "VALIDATION_FAILED",
|
||||
"category": "VALIDATION",
|
||||
"message": "Request body failed validation",
|
||||
"retryable": false,
|
||||
"details": []
|
||||
},
|
||||
"meta": {
|
||||
"requestId": "...",
|
||||
"traceId": "...",
|
||||
"correlationId": "..."
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
여기서 중요한 점은 이 구조가 단순히 보기 좋은 JSON이 아니라는 것입니다. `error.code`는 client가 분기할 수 있는 machine-readable identifier입니다. `message`는 사람이 읽는 문장이므로 client 로직이 여기에 의존하면 안 됩니다. `error.category`는 운영 분류입니다. validation 문제인지, auth 문제인지, dependency 문제인지 같은 큰 묶음을 나타냅니다. `retryable`은 client가 재시도를 검토할 수 있게 해 주는 최소 힌트입니다. `details`는 validation field error처럼 항목별 정보가 필요한 경우에만 채웁니다.
|
||||
|
||||
그럼 Spring 6+에서 제공하는 `ProblemDetail`을 쓰면 되지 않을까요? 이 질문이 자연스럽습니다. `ProblemDetail`은 RFC 7807 계열의 실패 응답 모델이고, Spring에서도 기본 지원합니다. 하지만 ca-tmpl의 요구와는 결이 달랐습니다.
|
||||
|
||||
`ProblemDetail`은 실패 전용 평면 shape입니다. 반면 ca-tmpl은 성공과 실패를 모두 같은 top-level envelope으로 감싸고 싶었습니다. 성공 응답도 `success=true`, 실패 응답도 `success=false`로 읽히게 만들고 싶었던 것입니다. 또한 ca-tmpl은 `code`, `category`, `retryable`, `meta`를 프로젝트 계약의 1급 필드로 두고 싶었습니다. `ProblemDetail` 위에 확장 필드를 계속 얹으면 결국 표준을 쓰는 척하면서 실제로는 custom envelope을 하나 더 만든 셈이 됩니다.
|
||||
|
||||
그래서 ca-tmpl의 선택은 "ProblemDetail이 나쁜 설계라서 버린다"가 아니었습니다. 실패 전용 표준 모델보다, 이 skeleton이 원하는 success/error 대칭 구조와 운영 메타데이터가 더 중요했기 때문에 custom envelope을 명시적으로 선택한 것입니다.
|
||||
|
||||
이 결정은 문서에만 남아 있지 않습니다. `shared-contract` 모듈에는 `Envelope`, `ApiError`, `ResponseMeta`가 있고, web adapter에는 예외를 envelope으로 바꾸는 `GlobalExceptionHandler`와 `ErrorResponseFactory`가 있습니다. 즉 "우리 프로젝트는 이런 실패 응답을 쓴다"가 README 문장에 머문 것이 아니라, 컴파일되는 타입과 테스트 가능한 경로로 내려왔습니다.
|
||||
|
||||
`Envelope`는 성공과 실패가 같은 바깥 구조를 공유한다는 결정을 담습니다. 성공이면 `data`가 있고 `error`가 없습니다. 실패이면 `error`가 있고 `data`가 없습니다. `ApiError`는 실패 안쪽의 구조를 고정합니다. 특히 `category`와 `retryable`을 field로 올려 둔 점이 중요합니다. 이 둘을 message 안에 섞어 두면 client와 운영 도구가 안정적으로 읽기 어렵습니다.
|
||||
|
||||
`ErrorResponseFactory`는 이 결정을 Spring MVC 응답으로 바꾸는 관문입니다. `ApiErrorCode`가 가진 HTTP status, code, category, retryable 값을 읽고 `Envelope.failure(...)`를 만들어 냅니다. 이 관문이 있으면 handler마다 JSON을 직접 조립하지 않아도 됩니다. 실패 응답을 만드는 길을 하나로 좁혀 두는 효과가 있습니다.
|
||||
|
||||
또 하나 중요한 장치는 `ProblemDetail`을 다시 들여오지 못하게 막는 것입니다. ca-tmpl은 `spring.mvc.problemdetails.enabled=false`를 application.yml에 명시하고, 그 값이 유지되는지 테스트합니다. 여기에 더해 ArchUnit rule로 production code가 `org.springframework.http.ProblemDetail`에 의존하지 못하게 막습니다. 이것은 "개발자가 조심하자" 수준의 약속이 아니라, build가 깨지는 계약입니다.
|
||||
|
||||
transport failure를 같은 envelope에 태운 것도 이 글의 핵심입니다. 예를 들어 request body가 너무 크면 413, 지원하지 않는 `Content-Type`이면 415, 지원하지 않는 HTTP method면 405가 됩니다. 이때 status의 의미는 그대로 보존해야 합니다. ca-tmpl은 이런 실패들을 모두 `VALIDATION_FAILED` 같은 하나의 오류로 뭉개지 않고, `PAYLOAD_TOO_LARGE`, `UNSUPPORTED_MEDIA_TYPE`, `METHOD_NOT_ALLOWED`처럼 구분된 code/status로 envelope에 담습니다.
|
||||
|
||||
특히 Spring MVC의 `ResponseEntityExceptionHandler`가 이미 처리하는 계열은 주의가 필요합니다. 같은 예외를 `@ExceptionHandler`로 다시 등록하면 framework가 가진 처리 흐름과 충돌할 수 있습니다. ca-tmpl은 이런 경우 protected override를 사용해서 Spring MVC의 흐름 위에서 body만 envelope shape으로 바꿉니다. 예를 들어 405에서는 `Allow` header도 함께 보존합니다. 실패 응답의 바깥 shape은 통일하지만, HTTP가 가진 의미까지 지워 버리지는 않는다는 뜻입니다.
|
||||
|
||||
다만 이 글에서 말할 수 있는 범위는 분명히 제한해야 합니다. 현재 근거는 코드 구현과 로컬 검증입니다. canonical 문서 기준으로 `./gradlew check`가 통과했고, 413/406/415/405(+`Allow`)/412 같은 transport failure row가 테스트됐다고 말할 수 있습니다. 하지만 운영 배포에서 검증했다거나, 실제 production metric으로 개선을 확인했다고 말할 수는 없습니다.
|
||||
|
||||
아직 planned/stub으로 남은 것도 있습니다. `Retry-After` header 발행은 rate-limit owner branch의 책임으로 남아 있습니다. 5xx span ERROR 기록도 tracer-neutral seam은 있지만, 이 글에서 운영 추적이 완성됐다고 말하면 안 됩니다. business rule violation을 어떤 `category`와 `details`로 세분화할지도 foundation이 아니라 별도 owner branch의 범위입니다.
|
||||
|
||||
정리하면 ca-tmpl의 API Error Envelope은 "표준을 몰라서 만든 custom JSON"이 아닙니다. `ProblemDetail`, JSON:API errors, Google `rpc.Status` 같은 선택지를 비교한 뒤, 이 skeleton이 더 중요하게 본 요구를 코드 계약으로 고정한 결과입니다. 그 요구는 성공/실패 응답의 대칭성, client가 읽을 수 있는 안정적인 error code, 운영자가 볼 수 있는 category와 meta, 그리고 exception leak을 막는 일관된 실패 응답 경로였습니다.
|
||||
|
||||
좋은 error response 설계는 예쁜 JSON을 만드는 일이 아니라, 실패를 다루는 책임을 어디에 둘지 정하는 일에 가깝습니다. ca-tmpl의 선택은 그 책임을 프로젝트 초기에 명시하고, 테스트와 ArchUnit rule로 회귀하지 않게 붙잡아 둔 사례입니다.
|
||||
|
||||
## 코드 예제 / Code samples (있다면)
|
||||
|
||||
```java
|
||||
// 출처: [[wiki/projects/ca-tmpl/api-error-envelope-design]]
|
||||
// 실제 파일: shared-contract/src/main/java/dev/caskeleton/shared/response/Envelope.java
|
||||
public record Envelope<T>(boolean success, T data, ApiError error, ResponseMeta meta) {
|
||||
|
||||
public static <T> Envelope<T> ok(T data, ResponseMeta meta) {
|
||||
return new Envelope<>(true, data, null, meta);
|
||||
}
|
||||
|
||||
public static <T> Envelope<T> failure(ApiError error, ResponseMeta meta) {
|
||||
return new Envelope<>(false, null, error, meta);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```java
|
||||
// 출처: [[wiki/projects/ca-tmpl/api-error-envelope-design]]
|
||||
// 실제 파일: shared-contract/src/main/java/dev/caskeleton/shared/response/ApiError.java
|
||||
public record ApiError(
|
||||
String code, String category, String message, boolean retryable, Object details) {
|
||||
|
||||
public static ApiError of(String code, String category, String message, boolean retryable) {
|
||||
return new ApiError(code, category, message, retryable, null);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```java
|
||||
// 출처: [[wiki/projects/ca-tmpl/api-error-envelope-design]]
|
||||
// 실제 파일: adapter-web/src/main/java/dev/caskeleton/adapter/web/error/ErrorResponseFactory.java
|
||||
public static Envelope<Void> body(ApiErrorCode code, String message, Object details) {
|
||||
ApiError err =
|
||||
details == null
|
||||
? ApiError.of(code.code(), code.category().name(), message, code.retryable())
|
||||
: ApiError.withDetails(
|
||||
code.code(), code.category().name(), message, code.retryable(), details);
|
||||
return Envelope.failure(err, ResponseMetaFactory.fromMdc());
|
||||
}
|
||||
```
|
||||
|
||||
```java
|
||||
// 출처: [[wiki/projects/ca-tmpl/api-error-envelope-design]]
|
||||
// 실제 파일: app-bootstrap/src/test/java/.../CleanArchitectureTest.java
|
||||
@ArchTest
|
||||
static final ArchRule NO_PROBLEM_DETAIL_USAGE =
|
||||
noClasses()
|
||||
.that()
|
||||
.resideInAPackage("dev.caskeleton..")
|
||||
.should()
|
||||
.dependOnClassesThat()
|
||||
.haveFullyQualifiedName("org.springframework.http.ProblemDetail");
|
||||
```
|
||||
|
||||
```yaml
|
||||
# 출처: [[wiki/projects/ca-tmpl/api-error-envelope-design]]
|
||||
# 실제 파일: app-bootstrap/src/main/resources/application.yml
|
||||
spring:
|
||||
mvc:
|
||||
problemdetails:
|
||||
enabled: false
|
||||
```
|
||||
|
||||
## Sources / 근거 (canonical 인용 필수, derived layer 의무)
|
||||
|
||||
- [[wiki/projects/ca-tmpl/api-error-envelope-design]] - 이 글의 1차 canonical. `verified`, `actually-implemented`, `locally-verified` 범위와 과장 금지 항목을 따른다.
|
||||
- [[wiki/concepts/api-error-envelope-design]] - `ProblemDetail`, Google `rpc.Status`, JSON:API errors, GraphQL errors, custom envelope trade-off를 정리한 개념 canonical.
|
||||
- [[raw/project-notes/ca-skeleton-operational-contract]] - Structured API Response Contract, Exception Ownership Contract, Operational Error Category, Topic 4 envelope 대안 검토.
|
||||
- [[raw/branch-notes/feature-operational-error-observability-foundation]] - envelope schema SSOT와 exception leak 금지 catalog.
|
||||
- [[raw/branch-notes/feature-api-contract-baseline]] - 413/406/415/405(+`Allow`)/412 transport failure envelope mapping 검증.
|
||||
- [[raw/blog-topics/spring-responseentityexceptionhandler-transport-failure-envelope-2026-07-02]] - Spring MVC transport failure envelope 글감.
|
||||
- [[raw/blog-topics/operational-error-envelope-meta-category-migration-2026-06-01]] - `error.category`와 `meta` migration 글감.
|
||||
- [[raw/blog-topics/spring-security-filter-layer-error-envelope-2026-06-08]] - Spring Security filter-layer envelope 후속 글감.
|
||||
|
||||
## 사실 vs 의견 / Fact vs opinion 구분
|
||||
|
||||
- 사실: ca-tmpl에는 `Envelope`, `ApiError`, `ResponseMeta`, `Category`, `OperationalError`, `GlobalExceptionHandler`, `ErrorResponseFactory`, `EnvelopeBodyAdvice`가 코드로 존재한다.
|
||||
- 사실: `ProblemDetail`은 ArchUnit rule과 `spring.mvc.problemdetails.enabled: false` 설정으로 금지/비활성화되어 있다.
|
||||
- 사실: `./gradlew check`가 2026-06-01에 통과했고, 413/406/415/405(+`Allow`)/412 transport failure mapping이 테스트로 검증됐다.
|
||||
- 사실: 운영 배포와 prod 검증은 없다.
|
||||
- 의견: ca-tmpl의 요구 조합에서는 `ProblemDetail` 위에 확장을 쌓는 것보다 custom envelope을 명시적으로 고정하는 편이 더 설명 가능하다.
|
||||
- 의견: `retryable`과 `category`를 1급 필드로 두면 client/retry/observability 설계가 단순해진다. 다만 `RetryInfo.retry_delay` 같은 더 구체적인 표준 정보를 잃는 trade-off가 있다.
|
||||
|
||||
## 답할 수 있는 범위 / Answer boundary
|
||||
|
||||
- 자신 있게 답할 수 있음: ca-tmpl이 왜 `ProblemDetail`을 채택하지 않았는지.
|
||||
- 자신 있게 답할 수 있음: envelope field shape과 각 필드의 책임.
|
||||
- 자신 있게 답할 수 있음: 어떤 클래스와 테스트로 계약을 고정했는지.
|
||||
- 자신 있게 답할 수 있음: 어떤 transport failure row가 envelope으로 검증됐는지.
|
||||
- 제한해서 답해야 함: 운영에서의 동작. 현재는 local/dev verification까지만 말한다.
|
||||
- 제한해서 답해야 함: `Retry-After`, 5xx span ERROR, business rule details mapping. 현재 문서 기준으로는 planned/stub 또는 별도 owner branch 범위다.
|
||||
|
||||
## 게시 체크리스트 / Publish checklist
|
||||
|
||||
- [x] 원천 canonical이 `reviewed | verified | published-ready` 상태인지 확인
|
||||
- [x] derived 문서가 raw를 1차 근거처럼 사용하지 않는지 확인
|
||||
- [x] 코드 발췌가 실제 ca-tmpl 코드와 일치하는지 확인
|
||||
- [x] `actually-implemented`, `locally-verified`, `prod-verified` 범위를 분리했는지 확인
|
||||
- [x] 금지 마케팅 표현을 쓰지 않았는지 확인
|
||||
- [x] `canonical_sources`를 실제 인용 canonical로 채웠는지 확인
|
||||
- [x] 본문 작성 후 `status_label`을 `ready`로 갱신했는지 확인
|
||||
|
||||
## Related / 관련
|
||||
|
||||
- 관련 project 문서: [[wiki/projects/ca-tmpl/api-error-envelope-design]]
|
||||
- 관련 concept 문서: [[wiki/concepts/api-error-envelope-design]]
|
||||
- 후속 글 후보: [[raw/blog-topics/spring-responseentityexceptionhandler-transport-failure-envelope-2026-07-02]]
|
||||
- 후속 글 후보: [[raw/blog-topics/spring-security-filter-layer-error-envelope-2026-06-08]]
|
||||
- 후속 글 후보: [[raw/blog-topics/operational-error-envelope-meta-category-migration-2026-06-01]]
|
||||
@@ -1 +0,0 @@
|
||||
../../vault/40-publish/blog/ca-tmpl-api-evolution-and-schema-2026-07-02.md
|
||||
@@ -0,0 +1,257 @@
|
||||
---
|
||||
title: API Evolution은 버전 번호가 아니라 계약의 문제다
|
||||
source_type: blog
|
||||
status: verified
|
||||
confidence: high
|
||||
tags: [blog, ca-tmpl, api-design, versioning, schema]
|
||||
related_projects: [ca-tmpl]
|
||||
last_reviewed: 2026-07-02
|
||||
canonical_sources:
|
||||
- wiki/projects/ca-tmpl/api-evolution-and-schema
|
||||
- wiki/concepts/api-evolution-and-schema
|
||||
audience: backend-engineer
|
||||
target_publish:
|
||||
status_label: ready
|
||||
---
|
||||
|
||||
# API Evolution은 버전 번호가 아니라 계약의 문제다
|
||||
|
||||
> Layer: `wiki/blog/` — **외부 공개용 블로그 글 초안·완성본**. canonical (`wiki/concepts/` + `wiki/projects/`) 에서 파생된 산출물.
|
||||
> 상태: draft → reviewed → verified → **published-ready** (외부 게시 가능)
|
||||
> `status_label`: `outline` | `drafting` | `review` | `ready` | `published` | `retired`
|
||||
> `audience`: `backend-engineer` | `senior-engineer` | `tech-lead` | `general` — 깊이·전문용어 사용량이 달라짐.
|
||||
|
||||
## Parent / 부모 (필수)
|
||||
|
||||
> wiki/blog/ 는 derived layer. **반드시 canonical wiki/concepts/ 또는 wiki/projects/ 에서 파생.** raw 또는 branch에서 직접 파생 금지.
|
||||
|
||||
- 핵심 canonical:
|
||||
- [[wiki/projects/ca-tmpl/api-evolution-and-schema]] — ca-tmpl API contract baseline, compatibility/deprecation, schema/serialization 결정과 검증 범위.
|
||||
- [[wiki/concepts/api-evolution-and-schema]] — API versioning, deprecation, schema compatibility, serialization policy 일반 개념.
|
||||
- 영감 출처:
|
||||
- [[raw/blog-topics/api-deprecation-sunset-header-migration-window-2026-07-02]] — Sunset/Deprecation header와 migration window 글감.
|
||||
- [[raw/blog-topics/spring-boot-serialization-contract-pins-2026-07-02]] — Jackson serialization pin과 BigDecimal constructor guard 글감.
|
||||
|
||||
## 타깃 독자 / Target reader
|
||||
|
||||
> 이 글을 누가 읽을 것인지. 톤·전문용어·깊이가 결정됨.
|
||||
|
||||
- 독자 profile: Spring Boot 기반 REST API를 만들면서 versioning, pagination, deprecation, serialization contract를 어디까지 정해야 하는지 고민하는 백엔드 엔지니어.
|
||||
- 독자가 이미 알고 있을 것이라 가정하는 것: HTTP status, REST endpoint, OpenAPI, Jackson, Spring MVC의 기본 역할.
|
||||
- 독자가 처음 듣는다고 가정하는 것: API evolution을 단순히 `/v1` prefix가 아니라 migration window, compatibility catalog, conditional request, serialization pin까지 포함하는 계약으로 보는 관점.
|
||||
|
||||
## 도입 / Hook
|
||||
|
||||
> 왜 이 글을 쓰는가. 독자에게 이 글의 가치를 1~2문장으로.
|
||||
|
||||
- 문제 / 궁금증: API versioning을 `/v1`만 붙이면 끝난다고 생각하기 쉽지만, 실제로는 pagination cap, ETag, cache header, deprecation signal, serialization default drift까지 모두 contract surface가 된다.
|
||||
- 이 글이 답하는 것: ca-tmpl이 API evolution을 어떤 하위 계약으로 쪼갰고, 그중 무엇은 코드로 구현·로컬 검증됐으며, 무엇은 아직 documented-only인지 구분한다.
|
||||
- 이 글이 답하지 않는 것 (스코프): 실제 외부 client migration 운영 경험, production cutover, 410 응답 전환 실측, Avro Schema Registry 운영 경험.
|
||||
|
||||
## 본문 outline / Body outline
|
||||
|
||||
> 글의 흐름. 초안 단계에서는 outline 만, drafting 단계부터 본문.
|
||||
|
||||
1. API evolution은 `/v1` prefix 하나가 아니다 — versioning, pagination, cache, conditional request, OpenAPI, batch/LRO, serialization policy까지 surface로 본다.
|
||||
2. ca-tmpl에서 실제 구현된 contract baseline — `/v1`, pagination/sort, ETag/If-Match/304/412, `no-store`/`Vary`, OpenAPI producer, LRO, batch endpoint.
|
||||
3. compatibility/deprecation은 아직 문서 계약이다 — 90d/30d window, 7행 breaking change catalog, `Sunset` + `Deprecation`, OpenAPI `deprecated: true`는 구현됐다고 말하지 않는다.
|
||||
4. serialization은 출력측만 로컬 검증됐다 — datetime/BigDecimal pin, effective `ObjectMapper` test, `new BigDecimal(double/float)` ArchUnit ban.
|
||||
5. 표준과 project-local trade-off를 분리하기 — RFC 8594, RFC 9110, RFC 3339, OpenAPI 같은 source-backed 사실과 90d/30d·size cap 100·weak ETag 같은 project decision을 구분한다.
|
||||
6. 블로그에서 과장하면 안 되는 경계 — 운영 deprecation 경험, strong ETag, idempotency replay, OpenAPI drift release gate, money string serialization은 아직 말하면 안 된다.
|
||||
|
||||
## 본문 / Body
|
||||
|
||||
API evolution을 처음 생각할 때 가장 먼저 떠오르는 것은 보통 version number입니다. `/v1`을 붙일지, header로 받을지, 날짜 기반으로 갈지 같은 질문입니다. 그런데 실제로 API가 오래 살아남으려면 version number만으로는 부족합니다.
|
||||
|
||||
API는 한 번 배포되면 client와 약속이 됩니다. 응답 field를 없애는 일, enum 값을 줄이는 일, pagination limit을 바꾸는 일, datetime을 숫자로 보내던 것을 문자열로 바꾸는 일도 모두 client에게는 변화입니다. 그래서 API evolution은 "버전을 어떻게 붙일까"보다 넓은 문제입니다. 더 정확히는 API surface 전체가 어떻게 변할 수 있고, 그 변화가 client를 언제 깨뜨리는지 정하는 계약입니다.
|
||||
|
||||
ca-tmpl의 API Evolution & Schema 문서는 이 문제를 세 갈래로 나눕니다. 첫 번째는 실제 HTTP API의 기본 계약입니다. `/v1` prefix, pagination/sort, ETag와 conditional request, cache header, OpenAPI producer, long-running operation, batch endpoint 같은 것들입니다. 두 번째는 compatibility와 deprecation입니다. 어떤 변경을 breaking으로 볼지, deprecated API를 얼마나 오래 살릴지, `Sunset`과 `Deprecation` header를 어떻게 보낼지에 대한 정책입니다. 세 번째는 schema와 serialization입니다. 날짜와 decimal이 어떤 JSON 모양으로 나가야 하는지, Jackson default가 바뀌어도 계약이 흔들리지 않게 어떻게 고정할지에 대한 문제입니다.
|
||||
|
||||
중요한 점은 이 세 갈래의 검증 수준이 서로 다르다는 것입니다. ca-tmpl에서 API contract baseline은 상당 부분 코드로 구현되고 로컬 테스트로 검증됐습니다. 반면 compatibility/deprecation 정책은 아직 문서 계약입니다. serialization은 출력측 일부가 구현·검증됐지만, 모든 schema evolution 도구가 구현된 것은 아닙니다. 이 구분을 흐리면 블로그 글은 읽기 좋아져도 사실 경계가 무너집니다.
|
||||
|
||||
먼저 구현된 API contract baseline부터 보겠습니다. ca-tmpl은 public endpoint에 `/v1` prefix를 사용합니다. 이것은 단지 URL을 예쁘게 만드는 선택이 아니라, API major version을 route surface에 드러내는 결정입니다. `PresentationSettings`는 `ca-skeleton.presentation.api-base-path`를 읽고, 값이 빠졌거나 `/`로 시작하지 않을 때 보정합니다. canonical 문서 기준으로 운영 default는 `/v1`이고, `VersioningPrefixTest`가 `/v1/probe`는 열리고 `/probe`는 열리지 않는다는 것을 검증합니다.
|
||||
|
||||
pagination도 계약입니다. client가 `size=100000`을 던질 수 있게 두면 서버 resource를 쉽게 압박할 수 있습니다. ca-tmpl의 `PageParams`는 기본 size를 20으로 두고, 1 이상 100 이하만 허용합니다. `page`는 0-indexed이며, deep offset은 `page > 10000`일 때 표시합니다. 여기서 숫자 100과 10000은 표준이 정한 값이 아닙니다. DoS 방어와 cursor pagination 유도라는 project-local trade-off입니다. 따라서 글에서는 "표준이라서 100"이라고 말하면 안 되고, "ca-tmpl이 skeleton 기본값으로 선택한 제한"이라고 말해야 합니다.
|
||||
|
||||
conditional request도 흥미로운 부분입니다. conditional request는 client가 "내가 알고 있는 이전 상태와 같을 때만 처리해 달라" 또는 "내가 가진 버전과 같으면 body를 다시 보내지 않아도 된다"고 말하는 HTTP 메커니즘입니다. ca-tmpl은 entity의 optimistic lock version에서 `W/"<version>"` 형태의 ETag를 만들고, read에서는 `If-None-Match`로 304를, write에서는 `If-Match` mismatch로 412를 냅니다. 이 흐름은 `ETags`와 `PreconditionFailedException`, controller wire test로 검증됩니다.
|
||||
|
||||
다만 여기에도 경계가 있습니다. ca-tmpl의 ETag 비교는 RFC 9110의 strict한 strong comparison 구현이 아닙니다. `ETags.matches`는 `W/` marker와 따옴표를 벗겨 opaque value를 비교하는 lenient 구현입니다. skeleton에서 이해하기 쉬운 optimistic lock bridge를 택한 것이지, production-grade strong ETag semantics를 모두 구현했다고 말하면 안 됩니다.
|
||||
|
||||
cache policy는 더 보수적입니다. 인증된 API에서 cache default를 열어 두면 proxy나 browser cache가 민감한 응답을 붙잡을 수 있습니다. ca-tmpl의 `CacheControlFilter`는 모든 응답에 `Cache-Control: no-store`와 `Vary: Accept, Accept-Encoding, Authorization`을 먼저 박습니다. cacheable endpoint가 필요하면 명시적으로 opt-in해야 합니다. 기본값을 닫고 예외를 열게 만든 셈입니다.
|
||||
|
||||
OpenAPI producer, long-running operation, batch endpoint도 baseline에 들어갑니다. OpenAPI는 `/v3/api-docs`가 열리는지 확인하는 producer 수준까지 구현됐습니다. long-running operation은 `POST /worklogs:export`가 202 Accepted와 `Location` header, polling URL을 돌려주는 sample fixture로 구현됐습니다. batch endpoint는 `POST /worklogs:batchCreate`에서 단일 transaction atomic 처리와 size cap을 검증합니다. 여기까지는 "코드로 구현했고 로컬 검증했다"고 말할 수 있는 범위입니다.
|
||||
|
||||
반대로 compatibility/deprecation은 조심해야 합니다. ca-tmpl은 90일 public, 30일 internal migration window를 문서 계약으로 정했습니다. 응답 field 제거, 응답 field 의미 변화, required request field 추가, enum value 제거, enum value 의미 변화, narrow enum, 기본값 변경을 breaking change catalog로 분류했습니다. 또한 `Sunset` header와 `Deprecation` header를 함께 보내기로 결정했습니다.
|
||||
|
||||
하지만 이것들은 아직 response interceptor나 release gate로 구현된 것이 아닙니다. 실제 API를 deprecated 상태로 운영해 본 것도 아니고, 외부 client가 90일 안에 migration을 끝냈는지 검증한 경험도 없습니다. 따라서 이 부분은 "설계했다", "문서 계약으로 잡았다", "표준과 사례를 비교해 이런 정책을 택했다"까지만 말해야 합니다. "운영에서 검증했다"는 표현은 쓰면 안 됩니다.
|
||||
|
||||
`Sunset`과 `Deprecation`의 차이는 글에서 꼭 풀어야 합니다. `Sunset`은 언제 사라질지를 알려주는 날짜 신호입니다. `Deprecation`은 지금 이미 deprecated 상태인지를 알려주는 신호입니다. 하나만 보내면 정보가 반쪽이 됩니다. ca-tmpl은 그래서 둘을 함께 보내기로 결정했습니다. 여기에 `Link rel="deprecation"`이나 `Link rel="sunset"`을 붙여 사람이 읽을 migration guide로 연결하는 방향도 문서에 잡혀 있습니다. 다시 말하지만, 현재는 결정과 설계이지 구현은 아닙니다.
|
||||
|
||||
schema/serialization 축은 조금 다릅니다. 여기서는 출력측 일부가 실제로 구현됐습니다. ca-tmpl은 Jackson 설정에서 `WRITE_DATES_AS_TIMESTAMPS=false`를 명시해 `OffsetDateTime`과 `LocalDate`가 숫자나 배열이 아니라 ISO-8601 문자열로 나가도록 고정합니다. `WRITE_BIGDECIMAL_AS_PLAIN=true`도 명시해 큰 `BigDecimal`이 scientific notation으로 나가지 않게 합니다.
|
||||
|
||||
흥미로운 점은 이 설정들이 현재 Spring Boot 기본값과 크게 어긋나지 않는다는 것입니다. 그런데도 ca-tmpl은 명시적으로 pin을 둡니다. 이유는 default에 기대면 future default drift를 잡기 어렵기 때문입니다. 그래서 `JacksonSerializationPolicyTest`는 설정 binding만 보는 것이 아니라 실제 wired `ObjectMapper`로 `OffsetDateTime`, `LocalDate`, `BigDecimal`을 직렬화해 봅니다. `JavaTimeModule`이 빠져서 날짜가 배열로 나가는 회귀도 이 테스트가 잡을 수 있습니다.
|
||||
|
||||
`BigDecimal`은 정적 차단까지 들어갑니다. Java에서 `new BigDecimal(0.1)`은 사람이 기대하는 0.1이 아니라 binary floating-point 오차를 품은 값을 만들 수 있습니다. ca-tmpl은 production code에서 `new BigDecimal(double)`과 `new BigDecimal(float)` 생성자를 호출하지 못하도록 ArchUnit rule을 둡니다. 이건 "조심하자"가 아니라 build에서 깨지는 계약입니다.
|
||||
|
||||
하지만 serialization도 모든 것이 끝난 것은 아닙니다. 입력측 strict deserialization, null/empty/missing 3-state 처리, per-API money string-vs-number 선택, OpenAPI drift release gate, 제거 field 재사용 방지 도구, Avro compatibility 자동검사는 각각 다른 owner나 planned 범위에 있습니다. 특히 sample domain에 money field가 없기 때문에 `@JsonSerialize(ToStringSerializer)` 같은 money string serialization 코드 시연은 없습니다.
|
||||
|
||||
이 글의 핵심은 API evolution을 넓게 보되, 구현 등급을 섞지 않는 데 있습니다. `/v1`, pagination, ETag, cache header, OpenAPI producer, LRO, batch endpoint는 로컬 검증된 구현으로 말할 수 있습니다. deprecation policy는 문서 계약으로 말해야 합니다. serialization output pin과 BigDecimal guard는 로컬 검증으로 말할 수 있습니다. strong ETag, idempotency replay, OpenAPI release gate, production deprecation 운영은 아직 말하면 안 됩니다.
|
||||
|
||||
좋은 skeleton은 단지 "예제 endpoint가 동작한다"에서 끝나지 않습니다. 나중에 API가 변할 때 어떤 변화가 안전하고, 어떤 변화가 client를 깨뜨리며, 어떤 값은 default에 기대지 않고 명시적으로 고정해야 하는지까지 알려 줘야 합니다. ca-tmpl의 API Evolution & Schema 결정은 그 방향을 잡은 문서입니다. 일부는 이미 코드와 테스트로 내려왔고, 일부는 앞으로 구현해야 할 계약으로 남아 있습니다. 이 둘을 구분해서 설명할 수 있을 때, 비로소 이 주제를 내 프로젝트 경험으로 말할 수 있습니다.
|
||||
|
||||
## 코드 예제 / Code samples (있다면)
|
||||
|
||||
> 가능한 실제 프로젝트 코드 인용. 가짜 예제 금지. 추출 시 출처 PR·커밋 명시.
|
||||
|
||||
```java
|
||||
// 출처: [[wiki/projects/ca-tmpl/api-evolution-and-schema]]
|
||||
// 실제 파일: adapter-web/src/main/java/dev/caskeleton/adapter/web/settings/PresentationSettings.java
|
||||
@ConfigurationProperties(prefix = "ca-skeleton.presentation")
|
||||
public record PresentationSettings(String apiBasePath) {
|
||||
|
||||
public PresentationSettings {
|
||||
if (apiBasePath == null) {
|
||||
apiBasePath = "";
|
||||
} else if (!apiBasePath.isEmpty() && !apiBasePath.startsWith("/")) {
|
||||
apiBasePath = "/" + apiBasePath;
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```java
|
||||
// 출처: [[wiki/projects/ca-tmpl/api-evolution-and-schema]]
|
||||
// 실제 파일: adapter-web/src/main/java/dev/caskeleton/adapter/web/pagination/PageParams.java
|
||||
public record PageParams(int page, int size) {
|
||||
|
||||
public static final int DEFAULT_SIZE = 20;
|
||||
public static final int MIN_SIZE = 1;
|
||||
public static final int MAX_SIZE = 100;
|
||||
public static final int DEEP_OFFSET_THRESHOLD = 10000;
|
||||
|
||||
public boolean isDeepOffset() {
|
||||
return page > DEEP_OFFSET_THRESHOLD;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```java
|
||||
// 출처: [[wiki/projects/ca-tmpl/api-evolution-and-schema]]
|
||||
// 실제 파일: adapter-web/src/main/java/dev/caskeleton/adapter/web/conditional/ETags.java
|
||||
public static String weakFromVersion(long version) {
|
||||
return "W/\"" + version + "\"";
|
||||
}
|
||||
```
|
||||
|
||||
```java
|
||||
// 출처: [[wiki/projects/ca-tmpl/api-evolution-and-schema]]
|
||||
// 실제 파일: adapter-web/src/main/java/dev/caskeleton/adapter/web/filter/CacheControlFilter.java
|
||||
@Override
|
||||
protected void doFilterInternal(
|
||||
HttpServletRequest request, HttpServletResponse response, FilterChain chain)
|
||||
throws ServletException, IOException {
|
||||
response.setHeader(ApiHeaders.CACHE_CONTROL, "no-store");
|
||||
response.setHeader(ApiHeaders.VARY, "Accept, Accept-Encoding, Authorization");
|
||||
chain.doFilter(request, response);
|
||||
}
|
||||
```
|
||||
|
||||
```java
|
||||
// 출처: [[wiki/projects/ca-tmpl/api-evolution-and-schema]]
|
||||
// 실제 파일: sample-portfolio/src/main/java/.../OperationsController.java
|
||||
@PostMapping("/worklogs:export")
|
||||
public ResponseEntity<Operation<WorkLogExportResult>> export() {
|
||||
Operation<WorkLogExportResult> accepted =
|
||||
operations.startExport(presentationSettings.apiBasePath(), 0L);
|
||||
return ResponseEntity.accepted().location(URI.create(accepted.statusUrl())).body(accepted);
|
||||
}
|
||||
```
|
||||
|
||||
```java
|
||||
// 출처: [[wiki/projects/ca-tmpl/api-evolution-and-schema]]
|
||||
// 실제 파일: app-bootstrap/src/test/java/.../JacksonSerializationPolicyTest.java
|
||||
String dateTimeJson = mapper.writeValueAsString(utc);
|
||||
assertThat(dateTimeJson).isEqualTo("\"1985-04-12T23:20:50.52Z\"");
|
||||
|
||||
String scaledJson = mapper.writeValueAsString(new BigDecimal("1.10"));
|
||||
assertThat(scaledJson).isEqualTo("1.10");
|
||||
```
|
||||
|
||||
```java
|
||||
// 출처: [[wiki/projects/ca-tmpl/api-evolution-and-schema]]
|
||||
// 실제 파일: app-bootstrap/src/test/java/.../CleanArchitectureTest.java
|
||||
@ArchTest
|
||||
static final ArchRule NO_BIGDECIMAL_DOUBLE_CONSTRUCTOR =
|
||||
noClasses()
|
||||
.that()
|
||||
.resideInAPackage("dev.caskeleton..")
|
||||
.should()
|
||||
.callConstructor(BigDecimal.class, double.class)
|
||||
.orShould()
|
||||
.callConstructor(BigDecimal.class, float.class);
|
||||
```
|
||||
|
||||
## Sources / 근거 (canonical 인용 필수, derived layer 의무)
|
||||
|
||||
> 모든 사실 주장은 canonical 또는 raw 인용으로 뒷받침. 자기 추론은 명시적으로 "내 해석" 으로 분리.
|
||||
|
||||
- [[wiki/projects/ca-tmpl/api-evolution-and-schema]] — 이 글의 1차 canonical. API contract baseline과 schema/serialization 출력측은 구현·로컬 검증 범위, compatibility/deprecation은 documented-only 범위로 구분한다.
|
||||
- [[wiki/concepts/api-evolution-and-schema]] — API versioning/deprecation/schema compatibility의 일반 개념과 표준·사례 비교.
|
||||
- [[raw/branch-notes/feature-api-contract-baseline]] — `/v1`, pagination/sort, conditional request, cache header, OpenAPI producer, LRO, batch endpoint 구현·검증 근거.
|
||||
- [[raw/branch-notes/feature-api-compatibility-deprecation-contract]] — 90d/30d migration window, breaking change catalog, Sunset+Deprecation decision. 현재 documented-only.
|
||||
- [[raw/branch-notes/feature-schema-serialization-contract]] — Jackson serialization output pin, BigDecimal constructor guard, serialization policy test.
|
||||
- [[raw/blog-topics/api-deprecation-sunset-header-migration-window-2026-07-02]] — deprecation/migration window 블로그 글감 raw seed.
|
||||
- [[raw/blog-topics/spring-boot-serialization-contract-pins-2026-07-02]] — Spring Boot serialization contract pin 블로그 글감 raw seed.
|
||||
- [[raw/official-docs/sunset-deprecation-headers-paired-usage]] — `Sunset` + `Deprecation` header paired usage 근거.
|
||||
- [[raw/official-docs/rfc9110-http-semantics]] — conditional request, 304/412, transport status 의미.
|
||||
- [[raw/official-docs/rfc3339-datetime-utc]] — datetime serialization 표현 근거.
|
||||
|
||||
## 사실 vs 의견 / Fact vs opinion 구분
|
||||
|
||||
> 독자가 자신 있게 인용할 수 있도록.
|
||||
|
||||
- **사실 (검증됨)**:
|
||||
- ca-tmpl의 API contract baseline 일부는 코드로 구현되어 있고 `./gradlew check`/테스트로 로컬 검증됐다. 근거: [[wiki/projects/ca-tmpl/api-evolution-and-schema]]
|
||||
- `/v1` prefix, pagination/sort, ETag/If-Match/304/412, cache header, OpenAPI producer, LRO, batch endpoint는 구현 범위에 포함된다. 근거: [[wiki/projects/ca-tmpl/api-evolution-and-schema]]
|
||||
- Jackson serialization 출력측 pin과 `new BigDecimal(double/float)` 정적 차단은 로컬 검증됐다. 근거: [[wiki/projects/ca-tmpl/api-evolution-and-schema]]
|
||||
- **내 해석·의견 (검증 안 된 추론)**:
|
||||
- API evolution을 versioning 하나가 아니라 "API surface 전체의 변화 관리"로 보면 skeleton 단계에서 정해야 할 계약이 더 선명해진다.
|
||||
- default 값을 그대로 믿는 것보다 명시 pin과 effective-bean test를 두는 편이 skeleton template에는 설명 가능하다.
|
||||
- **알지 못하는 것**:
|
||||
- 실제 external client migration이 90d/30d window로 충분했는지 알 수 없다. 운영 배포가 없다.
|
||||
- compatibility/deprecation header를 실제 response interceptor로 구현하고 cutover까지 운영해 본 경험은 없다.
|
||||
- OpenAPI drift release gate, Avro compatibility, money string-vs-number per-API serialization은 아직 구현·검증 범위가 아니다.
|
||||
|
||||
## 답할 수 있는 범위 / Answer boundary
|
||||
|
||||
> 이 글을 읽은 사람에게 후속 질문을 받았을 때 자신 있게 답할 수 있는 범위.
|
||||
|
||||
- 자신 있게 답할 수 있는 후속 질문:
|
||||
- ca-tmpl에서 API contract baseline을 어떤 항목으로 나눴는가?
|
||||
- `/v1` path prefix와 ETag/If-Match/304/412를 어떤 테스트로 검증했는가?
|
||||
- `Sunset`과 `Deprecation` header는 어떤 차이가 있고 왜 함께 보내기로 했는가?
|
||||
- Jackson serialization pin과 BigDecimal constructor guard는 왜 두었는가?
|
||||
- "그건 다음 글에서 다루겠다" 라고 해야 하는 부분:
|
||||
- 실제 deprecation 운영과 client migration coordination.
|
||||
- release-blocking OpenAPI drift gate 구현.
|
||||
- idempotency replay semantics.
|
||||
- strong ETag 전환.
|
||||
- per-API money string serialization code sample.
|
||||
|
||||
## 게시 체크리스트 / Publish checklist
|
||||
|
||||
`ready` → `published` 로 올리기 전 확인.
|
||||
|
||||
- [x] 모든 사실 주장에 canonical 링크 있음
|
||||
- [x] 사실 vs 의견 분리 명시됨
|
||||
- [x] 금지 마케팅 표현 없음
|
||||
- [x] 코드 예제 출처 명시
|
||||
- [x] 타깃 독자 가정과 톤 일치
|
||||
- [x] `/lint` 통과
|
||||
- [ ] 게시 URL 기록 (게시 후):
|
||||
|
||||
## Related / 관련
|
||||
|
||||
- 후속 글 후보: [[wiki/blog/ca-tmpl-api-error-envelope-design-2026-07-02]]
|
||||
- 관련 포트폴리오 항목: `[[wiki/portfolio/<...>]]`
|
||||
- 영감을 받은 raw 자료: [[raw/blog-topics/api-deprecation-sunset-header-migration-window-2026-07-02]], [[raw/blog-topics/spring-boot-serialization-contract-pins-2026-07-02]]
|
||||
@@ -1 +0,0 @@
|
||||
../../vault/40-publish/blog/ca-tmpl-boundary-validation-mapping-2026-07-02.md
|
||||
@@ -0,0 +1,255 @@
|
||||
---
|
||||
title: 입력 경계에서 검증과 매핑 책임을 분리하기
|
||||
source_type: blog
|
||||
status: verified
|
||||
confidence: high
|
||||
tags: [blog, ca-tmpl, validation, mapper, archunit]
|
||||
related_projects: [ca-tmpl]
|
||||
last_reviewed: 2026-07-02
|
||||
canonical_sources:
|
||||
- wiki/projects/ca-tmpl/boundary-validation-mapping
|
||||
audience: backend-engineer
|
||||
target_publish:
|
||||
status_label: ready
|
||||
---
|
||||
|
||||
# 입력 경계에서 검증과 매핑 책임을 분리하기
|
||||
|
||||
> Layer: `wiki/blog/` — **외부 공개용 블로그 글 초안·완성본**. canonical (`wiki/concepts/` + `wiki/projects/`) 에서 파생된 산출물.
|
||||
> 상태: draft → reviewed → verified → **published-ready** (외부 게시 가능)
|
||||
> `status_label`: `outline` | `drafting` | `review` | `ready` | `published` | `retired`
|
||||
> `audience`: `backend-engineer` | `senior-engineer` | `tech-lead` | `general` — 깊이·전문용어 사용량이 달라짐.
|
||||
|
||||
## Parent / 부모 (필수)
|
||||
|
||||
> wiki/blog/ 는 derived layer. **반드시 canonical wiki/concepts/ 또는 wiki/projects/ 에서 파생.** raw 또는 branch에서 직접 파생 금지.
|
||||
|
||||
- 핵심 canonical:
|
||||
- [[wiki/projects/ca-tmpl/boundary-validation-mapping]] — ca-tmpl 입력 경계 검증, DTO↔도메인 매핑, ArchUnit 정적 강제 구현·검증 범위.
|
||||
- 관련 개념 문서:
|
||||
- [[wiki/concepts/boundary-validation-and-dto-mapping]] — boundary validation과 DTO/domain mapping 일반 개념. 현재 concept 문서는 `draft`이므로 이 글의 구현 사실 근거는 verified project canonical에 둔다.
|
||||
- 영감 출처:
|
||||
- [[raw/blog-topics/boundary-validation-mapper-responsibility-map-2026-07-02]] — validation/mapper 책임 분리 글감.
|
||||
- [[raw/blog-topics/archunit-jackson-default-typing-cve-2019-14379-block-2026-05-29]] — Jackson default typing 위험 API 정적 차단 글감.
|
||||
|
||||
## 타깃 독자 / Target reader
|
||||
|
||||
> 이 글을 누가 읽을 것인지. 톤·전문용어·깊이가 결정됨.
|
||||
|
||||
- 독자 profile: Spring Boot API에서 request DTO, validation, mapper, domain model 경계를 어디에 둘지 고민하는 백엔드 엔지니어.
|
||||
- 독자가 이미 알고 있을 것이라 가정하는 것: Bean Validation, DTO, controller/service 계층, Jackson, 기본적인 Clean Architecture 용어.
|
||||
- 독자가 처음 듣는다고 가정하는 것: PATCH 3-state, mapper 실패와 validation 실패의 분리, ArchUnit으로 boundary rule을 build-time contract로 만드는 방식.
|
||||
|
||||
## 도입 / Hook
|
||||
|
||||
> 왜 이 글을 쓰는가. 독자에게 이 글의 가치를 1~2문장으로.
|
||||
|
||||
- 문제 / 궁금증: 입력 검증과 DTO↔domain mapping을 한 계층에 몰아두면 request DTO가 application layer까지 새거나, domain/entity가 response로 silent 직렬화되거나, PATCH가 기존 값을 조용히 덮어쓰는 회귀가 생긴다.
|
||||
- 이 글이 답하는 것: ca-tmpl이 입력 syntax, mapper, response shaping, outbound ACL, polymorphic deserialization, envelope error mapping을 어떻게 나누고 어떤 것은 ArchUnit으로 강제했는지 정리한다.
|
||||
- 이 글이 답하지 않는 것 (스코프): 운영 트래픽 검증, 실 DB/Testcontainers 통합 검증, 실 외부 HTTP/WireMock 통합, OpenAPI `oneOf` response shape 명세.
|
||||
|
||||
## 본문 outline / Body outline
|
||||
|
||||
> 글의 흐름. 초안 단계에서는 outline 만, drafting 단계부터 본문.
|
||||
|
||||
1. 경계가 흐려질 때 생기는 문제 — request DTO leak, domain/entity response leak, PATCH silent overwrite, raw external response leak.
|
||||
2. validation 실패와 mapping 실패를 분리하기 — Spring이 다루는 request parsing/validation은 `VALIDATION_FAILED`, mapper 내부 의미 실패는 `MappingException`→`MAPPING_FAILED`.
|
||||
3. PATCH 3-state를 `JsonNullable<T>`에서 `Patch<T>`로 옮기기 — web adapter의 Jackson-aware 타입을 application-core 밖으로 가두고 absent/null/value를 보존한다.
|
||||
4. polymorphic deserialization을 allowlist로 제한하기 — Jackson default typing 위험 API를 ArchUnit rule로 막고, `@JsonTypeInfo` + subtype allowlist만 허용한다.
|
||||
5. DTO/domain/persistence 경계를 ArchUnit fitness function으로 고정하기 — controller 반환 타입, application method parameter, ProblemDetail import, merge-patch media type, `@Valid` cascade depth, outbound ACL return type을 build-time으로 검증한다.
|
||||
6. 검증된 범위와 아직 아닌 범위 — WorkLog wire/unit test, ArchitectureViolationFixtureTest, virtual-thread MDC e2e는 검증됐지만 운영, 실 DB 통합, 실 외부 HTTP 통합, OpenAPI shape 명세는 아니다.
|
||||
|
||||
## 본문 / Body
|
||||
|
||||
입력 경계는 처음에는 controller의 `@Valid` 정도로 끝나는 문제처럼 보입니다. request body를 DTO로 받고, Bean Validation으로 검사하고, service에 넘기면 충분해 보입니다. 그런데 프로젝트가 커질수록 이 경계는 생각보다 쉽게 흐려집니다.
|
||||
|
||||
예를 들어 request DTO가 application layer까지 들어가면 application core가 web framework의 모양을 알게 됩니다. 반대로 domain entity나 JPA entity가 controller response로 바로 나가면, 내부 모델이 외부 API contract가 되어 버립니다. PATCH에서는 더 미묘한 문제가 생깁니다. field가 아예 빠진 것인지, 명시적으로 `null`을 보낸 것인지, 새 값을 보낸 것인지 구분하지 못하면 기존 값을 조용히 덮어쓰는 버그가 생깁니다.
|
||||
|
||||
ca-tmpl의 boundary validation/mapping 계약은 이 문제를 “입력 검증을 어디서 하느냐” 하나로 보지 않습니다. request parsing, syntax validation, mapper, domain/application command, response shaping, outbound ACL을 서로 다른 책임으로 나눕니다. 그리고 중요한 경계는 ArchUnit rule과 wire-level test로 고정합니다. 컨벤션 문서에만 적어두는 것이 아니라, 누군가 실수로 깨면 build가 실패하게 만드는 방식입니다.
|
||||
|
||||
먼저 validation 실패와 mapping 실패를 분리합니다. Spring MVC가 request body를 읽지 못하거나 Bean Validation을 통과하지 못한 경우는 `VALIDATION_FAILED`입니다. 예를 들어 `MethodArgumentNotValidException`, `HttpMessageNotReadableException`, `ConstraintViolationException` 계열입니다. 반면 payload는 구조적으로 들어왔지만 mapper가 의미상 domain command로 바꿀 수 없는 경우는 `MappingException`입니다. ca-tmpl은 이것을 `MAPPING_FAILED`로 분류합니다.
|
||||
|
||||
이 분리가 중요한 이유는 실패의 원인이 다르기 때문입니다. validation failure는 보통 client가 입력 형식을 잘못 보냈다는 뜻입니다. mapping failure는 한 단계 더 안쪽입니다. 예를 들어 link URI가 형식은 문자열이지만 project가 받아들일 수 없는 형태라면, mapper가 그것을 domain command로 바꾸지 못합니다. 둘을 모두 “bad request”로만 뭉개면 운영 분류와 client 디버깅이 어려워집니다.
|
||||
|
||||
PATCH 3-state도 이 글의 핵심입니다. 일반 update에서는 `null`을 “값을 지운다”로 볼 수 있지만, PATCH에서는 field가 빠진 상태와 field가 `null`인 상태가 다릅니다. 빠졌다는 것은 변경하지 말라는 뜻이고, 명시적 `null`은 비우라는 뜻일 수 있습니다. ca-tmpl은 web adapter에서 `JsonNullable<T>`를 받고, application으로 넘기기 전에 Jackson-free 타입인 `Patch<T>`로 변환합니다.
|
||||
|
||||
이렇게 하면 application-core는 Jackson을 모릅니다. application은 `Patch.absent()`, `Patch.ofNull()`, `Patch.of(value)`만 보고 의도를 판단합니다. web adapter는 wire 표현을 domain/application이 이해할 수 있는 작은 값 객체로 번역하는 역할만 맡습니다. 이것이 DTO와 command 사이의 mapper 책임입니다.
|
||||
|
||||
polymorphic deserialization도 경계 문제입니다. Jackson default typing은 임의 subtype을 열어 둘 수 있고, 과거 CVE-2019-14379 같은 gadget chain 위험과 연결됩니다. ca-tmpl은 `ObjectMapper.enableDefaultTyping()` 호출과 `LaissezFaireSubTypeValidator` 의존을 ArchUnit으로 막습니다. 대신 `@JsonTypeInfo(use = NAME)`과 명시적인 `@JsonSubTypes` allowlist를 사용합니다. 즉 “다형성을 쓰지 않는다”가 아니라, 허용된 이름과 타입만 받게 하는 것입니다.
|
||||
|
||||
DTO/domain/persistence 경계는 정적 rule로 고정합니다. controller public method가 domain entity, JPA entity, repository type을 반환하지 못하게 막습니다. application public method가 web DTO를 parameter로 받지 못하게 막습니다. RFC 7807 `ProblemDetail` import도 막고, `application/merge-patch+json` media type 문자열도 막습니다. outbound adapter public method가 raw external response type을 밖으로 흘리지 못하게 하는 ACL rule도 있습니다.
|
||||
|
||||
여기서 ArchUnit은 “아키텍처 다이어그램 검사기”가 아닙니다. 사람이 리뷰에서 놓치기 쉬운 carrier를 build-time에 잡는 fitness function에 가깝습니다. 특히 ca-tmpl은 violations-as-data 방식을 씁니다. 의도적으로 잘못된 fixture를 만들어 rule이 실제 위반을 잡는지 테스트합니다. 이것은 rule이 아무 것도 검사하지 않는데 green이 되는 vacuous pass를 줄이는 장치입니다.
|
||||
|
||||
물론 이 계약이 모든 것을 해결한 것은 아닙니다. 현재 검증 범위는 local/dev입니다. `WorkLogControllerWireTest`, unit/contract test, virtual-thread MDC test, `CleanArchitectureTest`와 violation fixture가 있습니다. 하지만 운영 배포는 없고, 실 DB 통합 테스트도 없습니다. outbound ACL도 실 `WebClient`/`RestClient`와 WireMock 왕복으로 검증된 것은 아닙니다. OpenAPI `oneOf` response shape 명세도 아직 planned입니다.
|
||||
|
||||
정리하면 ca-tmpl의 boundary validation/mapping 결정은 “controller에 `@Valid` 붙였다”보다 훨씬 넓은 계약입니다. request DTO가 어디까지 들어갈 수 있는지, mapper 실패는 어떤 error code가 되는지, PATCH의 세 상태를 어떻게 보존하는지, 외부 응답 raw type이 domain으로 어떻게 정리되는지, 그리고 그 규칙을 어떤 ArchUnit rule로 고정하는지를 함께 다룹니다. 좋은 경계 설계는 한 번의 아름다운 mapper가 아니라, 다음 사람이 무심코 깨뜨려도 build가 알려주는 구조에 가깝습니다.
|
||||
|
||||
## 코드 예제 / Code samples (있다면)
|
||||
|
||||
> 가능한 실제 프로젝트 코드 인용. 가짜 예제 금지. 추출 시 출처 PR·커밋 명시.
|
||||
|
||||
```java
|
||||
// 출처: [[wiki/projects/ca-tmpl/boundary-validation-mapping]]
|
||||
// 실제 파일: shared-contract/src/main/java/dev/caskeleton/shared/request/Patch.java
|
||||
public final class Patch<T> {
|
||||
public static <T> Patch<T> absent() { ... }
|
||||
public static <T> Patch<T> ofNull() { ... }
|
||||
public static <T> Patch<T> of(T value) { ... }
|
||||
|
||||
public boolean isAbsent() { return !present; }
|
||||
public boolean isExplicitNull() { return present && value == null; }
|
||||
public boolean hasValue() { return present && value != null; }
|
||||
}
|
||||
```
|
||||
|
||||
```java
|
||||
// 출처: [[wiki/projects/ca-tmpl/boundary-validation-mapping]]
|
||||
// 실제 파일: sample-portfolio/.../CreateWorkLogRequest.java
|
||||
@GroupSequence({Syntax.class, Invariant.class, CreateWorkLogRequest.class})
|
||||
public record CreateWorkLogRequest(
|
||||
@NotBlank(groups = Syntax.class) @Size(max = 200, groups = Syntax.class) String title,
|
||||
@NotNull(groups = Syntax.class) WorkCategory category,
|
||||
@NotNull(groups = Syntax.class) LocalDate periodStart,
|
||||
LocalDate periodEnd) {
|
||||
|
||||
@AssertTrue(message = "periodEnd must not be before periodStart", groups = Invariant.class)
|
||||
public boolean isPeriodOrdered() { ... }
|
||||
}
|
||||
```
|
||||
|
||||
```java
|
||||
// 출처: [[wiki/projects/ca-tmpl/boundary-validation-mapping]]
|
||||
// 실제 파일: sample-portfolio/.../UpdateWorkLogRequest.java
|
||||
private static <T> Patch<T> toPatch(JsonNullable<T> field) {
|
||||
if (field == null || !field.isPresent()) {
|
||||
return Patch.absent();
|
||||
}
|
||||
return field.get() == null ? Patch.ofNull() : Patch.of(field.get());
|
||||
}
|
||||
```
|
||||
|
||||
```java
|
||||
// 출처: [[wiki/projects/ca-tmpl/boundary-validation-mapping]]
|
||||
// 실제 파일: sample-portfolio/.../SamplePolymorphicRequest.java
|
||||
@JsonTypeInfo(use = JsonTypeInfo.Id.NAME, property = "kind")
|
||||
@JsonSubTypes({
|
||||
@JsonSubTypes.Type(value = SamplePolymorphicRequest.Text.class, name = "text"),
|
||||
@JsonSubTypes.Type(value = SamplePolymorphicRequest.Image.class, name = "image")
|
||||
})
|
||||
public sealed interface SamplePolymorphicRequest
|
||||
permits SamplePolymorphicRequest.Text, SamplePolymorphicRequest.Image {}
|
||||
```
|
||||
|
||||
```java
|
||||
// 출처: [[wiki/projects/ca-tmpl/boundary-validation-mapping]]
|
||||
// 실제 파일: shared-contract/src/main/java/dev/caskeleton/shared/error/MappingException.java
|
||||
public class MappingException extends RuntimeException {
|
||||
public MappingException(String message) {
|
||||
super(message);
|
||||
}
|
||||
|
||||
public MappingException(String message, Throwable cause) {
|
||||
super(message, cause);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```java
|
||||
// 출처: [[wiki/projects/ca-tmpl/boundary-validation-mapping]]
|
||||
// 실제 파일: adapter-web/src/main/java/dev/caskeleton/adapter/web/error/GlobalExceptionHandler.java
|
||||
@ExceptionHandler(MappingException.class)
|
||||
public ResponseEntity<Envelope<Void>> handleMapping(MappingException ex) {
|
||||
return ErrorResponseFactory.envelope(OperationalError.MAPPING_FAILED, ex.getMessage(), null);
|
||||
}
|
||||
```
|
||||
|
||||
```java
|
||||
// 출처: [[wiki/projects/ca-tmpl/boundary-validation-mapping]]
|
||||
// 실제 파일: sample-portfolio/.../RepoStatsAclMapper.java
|
||||
static RepoStats toDomain(RawRepoStatsResponse raw) {
|
||||
if (raw == null || raw.fullName() == null || raw.fullName().isBlank()) {
|
||||
throw new MappingException("repo provider: missing 'fullName'");
|
||||
}
|
||||
return new RepoStats(
|
||||
raw.fullName().toLowerCase(), Math.max(0, raw.stargazers()), raw.pushedAt());
|
||||
}
|
||||
```
|
||||
|
||||
```java
|
||||
// 출처: [[wiki/projects/ca-tmpl/boundary-validation-mapping]]
|
||||
// 실제 파일: app-bootstrap/src/test/java/.../CleanArchitectureTest.java
|
||||
@ArchTest
|
||||
static final ArchRule APPLICATION_METHODS_DO_NOT_ACCEPT_WEB_DTOS =
|
||||
methods()
|
||||
.that()
|
||||
.areDeclaredInClassesThat()
|
||||
.resideInAPackage("..application..")
|
||||
.and()
|
||||
.arePublic()
|
||||
.should()
|
||||
.notHaveRawParameterTypes(...);
|
||||
```
|
||||
|
||||
## Sources / 근거 (canonical 인용 필수, derived layer 의무)
|
||||
|
||||
> 모든 사실 주장은 canonical 또는 raw 인용으로 뒷받침. 자기 추론은 명시적으로 "내 해석" 으로 분리.
|
||||
|
||||
- [[wiki/projects/ca-tmpl/boundary-validation-mapping]] — 이 글의 1차 canonical. `verified`, `actually-implemented`, `locally-verified` 범위와 planned 항목을 따른다.
|
||||
- [[wiki/concepts/boundary-validation-and-dto-mapping]] — boundary validation, DTO/domain mapping, mapper responsibility의 관련 개념 문서. 현재 `draft`이므로 project 구현 사실의 출처로 쓰지 않는다.
|
||||
- [[raw/branch-notes/feature-boundary-validation-mapping-contract]] — feature branch 결정, Decision Evidence Map, 구현 결과.
|
||||
- [[raw/blog-topics/boundary-validation-mapper-responsibility-map-2026-07-02]] — validation/mapper responsibility map 블로그 글감 raw seed.
|
||||
- [[raw/blog-topics/archunit-jackson-default-typing-cve-2019-14379-block-2026-05-29]] — Jackson default typing 위험 API static block 블로그 글감 raw seed.
|
||||
- [[raw/official-docs/validation-jakarta-bean-validation-3.0-spec]] — `@GroupSequence`, `@Valid` cascade 근거.
|
||||
- [[raw/official-docs/spring-mvc-rest-exception-handling]] — Spring MVC validation/deserialization exception 처리 근거.
|
||||
- [[raw/official-docs/patch-json-merge-rfc7396]] — JSON Merge Patch null semantics와 미채택 근거.
|
||||
- [[raw/official-docs/schema-jackson-polymorphic-deserialization]] — Jackson polymorphic deserialization 위험과 allowlist API 근거.
|
||||
|
||||
## 사실 vs 의견 / Fact vs opinion 구분
|
||||
|
||||
> 독자가 자신 있게 인용할 수 있도록.
|
||||
|
||||
- **사실 (검증됨)**:
|
||||
- `Patch<T>`, `MappingException`, `GlobalExceptionHandler`, `EnvelopeBodyAdvice`, WorkLog request/mapper, outbound ACL mapper, boundary ArchUnit rules는 ca-tmpl 코드에 존재한다. 근거: [[wiki/projects/ca-tmpl/boundary-validation-mapping]]
|
||||
- `WorkLogControllerWireTest`, unit/contract tests, virtual-thread MDC tests, `CleanArchitectureTest` + violation fixtures가 로컬 검증 범위에 포함된다. 근거: [[wiki/projects/ca-tmpl/boundary-validation-mapping]]
|
||||
- 운영 배포와 prod 검증은 없다. 근거: [[wiki/projects/ca-tmpl/boundary-validation-mapping]]
|
||||
- **내 해석·의견 (검증 안 된 추론)**:
|
||||
- validation/mapping 책임을 하나의 mapper나 controller에 몰지 않고 boundary rule로 쪼개면, skeleton 사용자가 깨뜨리기 쉬운 회귀를 더 빨리 발견할 수 있다.
|
||||
- violations-as-data 방식은 ArchUnit rule이 실제 위반을 잡는지 확인하는 데 좋은 학습 소재다.
|
||||
- **알지 못하는 것**:
|
||||
- 실 DB 통합에서 PATCH/mapper 정책이 어떻게 동작하는지는 아직 검증되지 않았다.
|
||||
- 실 외부 HTTP + WireMock 기반 outbound ACL 검증은 아직 없다.
|
||||
- OpenAPI `oneOf` response shape 명세는 아직 planned다.
|
||||
|
||||
## 답할 수 있는 범위 / Answer boundary
|
||||
|
||||
> 이 글을 읽은 사람에게 후속 질문을 받았을 때 자신 있게 답할 수 있는 범위.
|
||||
|
||||
- 자신 있게 답할 수 있는 후속 질문:
|
||||
- validation 실패와 mapping 실패를 왜 다른 error category로 나눴는가?
|
||||
- PATCH absent/null/value를 왜 구분해야 하는가?
|
||||
- Jackson default typing 위험 API를 어떤 ArchUnit rule로 막았는가?
|
||||
- controller/application/outbound boundary를 어떤 정적 rule로 강제했는가?
|
||||
- violations-as-data fixture가 왜 필요한가?
|
||||
- "그건 다음 글에서 다루겠다" 라고 해야 하는 부분:
|
||||
- 실 DB/Testcontainers 통합 검증.
|
||||
- 실 외부 HTTP/WireMock 기반 ACL 검증.
|
||||
- OpenAPI response shape `oneOf` 명세.
|
||||
- 운영 트래픽에서 이 계약이 인시던트를 줄였는지에 대한 측정.
|
||||
|
||||
## 게시 체크리스트 / Publish checklist
|
||||
|
||||
`ready` → `published` 로 올리기 전 확인.
|
||||
|
||||
- [x] 모든 사실 주장에 canonical 링크 있음
|
||||
- [x] 사실 vs 의견 분리 명시됨
|
||||
- [x] 금지 마케팅 표현 없음
|
||||
- [x] 코드 예제 출처 명시
|
||||
- [x] 타깃 독자 가정과 톤 일치
|
||||
- [x] `/lint` 통과
|
||||
- [ ] 게시 URL 기록 (게시 후):
|
||||
|
||||
## Related / 관련
|
||||
|
||||
- 후속 글 후보: [[wiki/blog/ca-tmpl-api-error-envelope-design-2026-07-02]]
|
||||
- 영감을 받은 raw 자료: [[raw/blog-topics/boundary-validation-mapper-responsibility-map-2026-07-02]], [[raw/blog-topics/archunit-jackson-default-typing-cve-2019-14379-block-2026-05-29]]
|
||||
@@ -1 +0,0 @@
|
||||
../../vault/40-publish/blog/ca-tmpl-clean-architecture-package-layout-2026-07-02.md
|
||||
@@ -0,0 +1,199 @@
|
||||
---
|
||||
title: Clean Architecture를 패키지 구조로 강제하기
|
||||
source_type: blog
|
||||
status: verified
|
||||
confidence: high
|
||||
tags: [blog, ca-tmpl, clean-architecture, package-layout]
|
||||
related_projects: [ca-tmpl]
|
||||
last_reviewed: 2026-07-02
|
||||
canonical_sources:
|
||||
- wiki/projects/ca-tmpl/clean-architecture-package-layout
|
||||
audience: backend-engineer
|
||||
target_publish:
|
||||
status_label: ready
|
||||
---
|
||||
|
||||
# Clean Architecture를 패키지 구조로 강제하기
|
||||
|
||||
## Parent / 부모 (필수)
|
||||
|
||||
- 핵심 canonical: [[wiki/projects/ca-tmpl/clean-architecture-package-layout]] — ca-tmpl module/package blueprint, Gradle dependency matrix, ArchUnit boundary rule, negative fixture 검증 범위.
|
||||
- 관련 개념 문서: [[wiki/concepts/clean-architecture-package-layout]] — Clean Architecture package layout 일반 비교. 현재 concept 문서는 `draft`이므로 이 글의 구현 사실 근거는 verified project canonical에 둔다.
|
||||
|
||||
## 타깃 독자 / Target reader
|
||||
|
||||
- 독자 profile: Clean Architecture를 Java/Spring 멀티모듈 skeleton에 적용하려는 백엔드 엔지니어.
|
||||
- 이미 안다고 가정하는 것: controller, application service, domain, adapter 계층.
|
||||
- 처음 듣는다고 가정하는 것: package layout 자체를 ArchUnit fitness function으로 고정하는 방식.
|
||||
|
||||
## 도입 / Hook
|
||||
|
||||
- 문제 / 궁금증: Clean Architecture는 그림으로는 쉽지만, package가 흐트러지면 금방 관례가 된다.
|
||||
- 이 글이 답하는 것: ca-tmpl이 package/module layout과 dependency rule을 어떻게 구현·검증했는지.
|
||||
- 이 글이 답하지 않는 것: 모든 도메인에 맞는 universal package 구조.
|
||||
|
||||
## 본문 outline / Body outline
|
||||
|
||||
1. 계층 그림만으로는 부족하다 — import 방향이 깨지면 architecture도 깨진다.
|
||||
2. ca-tmpl의 module/package layout — domain, application, adapters, shared contract의 책임.
|
||||
3. ArchUnit rule로 강제하기 — 금지 import와 boundary violation을 build에서 잡는다.
|
||||
4. sample-portfolio 격리 — 예제 코드는 template core와 분리한다.
|
||||
5. 말할 수 있는 범위 — local verification과 planned/open risk를 구분한다.
|
||||
|
||||
## 본문 / Body
|
||||
|
||||
Clean Architecture는 그림으로 보면 단순합니다. domain은 안쪽에 있고, application은 use case를 담고, adapter는 바깥쪽 기술을 맡습니다. 문제는 그림이 아니라 시간이 지난 뒤의 코드입니다. controller가 repository를 직접 부르거나, application이 web DTO를 parameter로 받거나, shared package가 business common dumping ground가 되기 시작하면 구조는 이름만 남습니다.
|
||||
|
||||
ca-tmpl은 이 문제를 package naming convention만으로 해결하지 않았습니다. Gradle multi-module을 1차 경계로 두고, ArchUnit을 2차 경계로 둡니다. build graph에서는 어떤 module이 어떤 module을 의존할 수 있는지 검사하고, source import graph에서는 domain/application/adapter/shared-contract가 금지된 타입을 가져오는지 검사합니다. 즉 “Clean Architecture로 짰다”가 아니라, 깨졌을 때 build가 알려주는 skeleton을 만들려는 결정입니다.
|
||||
|
||||
현재 ca-tmpl의 production root는 `dev.caskeleton`입니다. bootstrap은 `dev.caskeleton.bootstrap`에 있고, domain/application/adapter/shared package를 component scan 대상으로 명시합니다. module은 `domain-core`, `application-core`, `adapter-web`, `adapter-persistence-rdbms`, `adapter-persistence-postgresql`, `adapter-outbound`, `adapter-identifier`, `shared-contract`, `app-bootstrap`, `sample-portfolio`로 나뉘어 있습니다. project canonical의 최초 slice는 8개 module blueprint였고, 이후 다른 slice에서 identifier와 persistence 세분화가 추가됐습니다. 그래서 이 글에서는 “현재 HEAD의 module 수”와 “그 slice가 검증한 결정”을 섞어 말하지 않습니다.
|
||||
|
||||
Gradle 쪽 핵심은 `verifyCleanArchitectureDependencies`입니다. 이 task는 module별 허용 dependency를 whitelist로 들고 있다가, 허용되지 않은 `project()` dependency가 들어오면 실패합니다. 예를 들어 web adapter가 persistence adapter나 outbound adapter를 직접 의존하면 안 됩니다. app-bootstrap은 composition root라 여러 module을 조립할 수 있지만, production code가 `sample-portfolio`에 의존하는 것은 금지됩니다. sample은 학습과 fixture 역할을 하는 소비자 module이지 production core가 기대는 기반 module이 아니기 때문입니다.
|
||||
|
||||
ArchUnit 쪽 핵심은 import 방향입니다. `domain_is_pure` rule은 domain package가 Spring, JPA, Hibernate, Lombok, application, adapter, bootstrap에 의존하지 못하게 합니다. application package도 adapter, bootstrap, persistence, Spring Web, Hibernate에 의존하지 못합니다. application에서 Spring `@Transactional`을 직접 쓰지 못하게 막는 rule도 여기에 놓여 있습니다. transaction 자체를 다루지 않는다는 뜻이 아니라, 그 책임을 `TransactionPort` 같은 application port로 드러내겠다는 뜻입니다.
|
||||
|
||||
adapter 간 직접 의존도 막습니다. web adapter가 persistence/outbound adapter를 직접 알면, controller가 DB나 외부 client 세부 구현을 우회할 수 있습니다. persistence adapter가 web adapter를 알면, 저장소 계층이 transport 모양을 알게 됩니다. outbound adapter가 persistence adapter를 직접 알면, 외부 호출과 저장소 구현이 서로 엮입니다. ca-tmpl은 이런 adapter 간 연결을 application/domain/shared contract를 통해서만 흐르게 하려 합니다.
|
||||
|
||||
`shared-contract`도 별도 경계가 있습니다. 이름이 shared라고 해서 아무 공통 코드를 넣는 곳이 아닙니다. ca-tmpl에서는 response, request, error, headers, logging, tracing, metrics, registry, annotation 같은 operational contract package만 허용합니다. business concept가 shared로 들어오면 여러 domain이 같은 이름의 공통 모델에 묶이기 쉽습니다. 그래서 shared는 편의 package가 아니라 운영 계약의 제한된 통로로 둡니다.
|
||||
|
||||
또 하나 중요한 장치는 violations-as-data입니다. ArchUnit rule은 매칭 대상이 비어 있으면 의미 없이 green이 될 수 있습니다. ca-tmpl은 의도적으로 잘못된 fixture class를 test tree에 두고, rule이 그 위반을 실제로 잡는지 확인합니다. 이렇게 하면 rule 이름만 있고 아무 것도 검사하지 않는 상태를 줄일 수 있습니다. 이것은 architecture test 자체를 테스트하는 장치입니다.
|
||||
|
||||
다만 이 구조도 만능은 아닙니다. ArchUnit은 bytecode에 남는 import, call, annotation을 잘 잡지만, string-key `ApplicationContext.getBean(String)`, `Class.forName(String)` 같은 reflection-style 우회는 정적으로 잡기 어렵습니다. 또한 운영 배포나 장기 유지보수 효과 측정은 없습니다. 이 글에서 말할 수 있는 범위는 ca-tmpl repository에서 구현됐고, 로컬/dev 검증으로 확인된 module/package boundary까지입니다.
|
||||
|
||||
정리하면 ca-tmpl의 Clean Architecture package layout은 “도메인, 애플리케이션, 어댑터로 나눴다”가 핵심이 아닙니다. 핵심은 그 나눔을 Gradle dependency matrix와 ArchUnit fitness function으로 계속 확인한다는 점입니다. skeleton은 한 번 예쁘게 만든 구조보다, 새 도메인을 추가하는 사람이 실수했을 때 어디서 잘못됐는지 알려주는 구조여야 합니다.
|
||||
|
||||
## 코드 예제 / Code samples (있다면)
|
||||
|
||||
```groovy
|
||||
// 출처: [[wiki/projects/ca-tmpl/clean-architecture-package-layout]]
|
||||
// 실제 파일: settings.gradle, ca-tmpl @f6fbd4e196b4
|
||||
include 'app-bootstrap'
|
||||
include 'domain-core'
|
||||
include 'application-core'
|
||||
include 'adapter-web'
|
||||
include 'adapter-persistence-rdbms'
|
||||
include 'adapter-persistence-postgresql'
|
||||
include 'adapter-outbound'
|
||||
include 'adapter-identifier'
|
||||
include 'shared-contract'
|
||||
include 'sample-portfolio'
|
||||
```
|
||||
|
||||
```java
|
||||
// 출처: [[wiki/projects/ca-tmpl/clean-architecture-package-layout]]
|
||||
// 실제 파일: app-bootstrap/.../CaSkeletonApplication.java, ca-tmpl @f6fbd4e196b4
|
||||
@SpringBootApplication(
|
||||
scanBasePackages = {
|
||||
"dev.caskeleton.bootstrap",
|
||||
"dev.caskeleton.adapter",
|
||||
"dev.caskeleton.application",
|
||||
"dev.caskeleton.domain",
|
||||
"dev.caskeleton.shared"
|
||||
})
|
||||
public class CaSkeletonApplication {
|
||||
public static void main(String[] args) {
|
||||
SpringApplication.run(CaSkeletonApplication.class, args);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```groovy
|
||||
// 출처: [[wiki/projects/ca-tmpl/clean-architecture-package-layout]]
|
||||
// 실제 파일: build.gradle, ca-tmpl @f6fbd4e196b4
|
||||
tasks.register('verifyCleanArchitectureDependencies') {
|
||||
doLast {
|
||||
Map<String, Set<String>> allowedProjectDependencies = [
|
||||
'domain-core' : ['shared-contract'] as Set,
|
||||
'application-core' : ['domain-core', 'shared-contract'] as Set,
|
||||
'adapter-web' : ['application-core', 'domain-core', 'shared-contract'] as Set,
|
||||
'adapter-outbound' : ['application-core', 'domain-core', 'shared-contract'] as Set,
|
||||
'shared-contract' : [] as Set
|
||||
]
|
||||
// 허용되지 않은 ProjectDependency가 있으면 GradleException을 던진다.
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```java
|
||||
// 출처: [[wiki/projects/ca-tmpl/clean-architecture-package-layout]]
|
||||
// 실제 파일: app-bootstrap/.../CleanArchitectureTest.java, ca-tmpl @f6fbd4e196b4
|
||||
@ArchTest
|
||||
static final ArchRule DOMAIN_IS_PURE =
|
||||
noClasses()
|
||||
.that()
|
||||
.resideInAPackage("..domain..")
|
||||
.should()
|
||||
.dependOnClassesThat()
|
||||
.resideInAnyPackage(
|
||||
"org.springframework..",
|
||||
"jakarta.persistence..",
|
||||
"org.hibernate..",
|
||||
"lombok..",
|
||||
"..application..",
|
||||
"..adapter..",
|
||||
"..bootstrap..")
|
||||
.allowEmptyShould(true);
|
||||
```
|
||||
|
||||
```java
|
||||
// 출처: [[wiki/projects/ca-tmpl/clean-architecture-package-layout]]
|
||||
// 실제 파일: app-bootstrap/.../CleanArchitectureTest.java, ca-tmpl @f6fbd4e196b4
|
||||
@ArchTest
|
||||
static final ArchRule PRODUCTION_CODE_DOES_NOT_DEPEND_ON_SAMPLE_PORTFOLIO =
|
||||
noClasses()
|
||||
.that()
|
||||
.resideOutsideOfPackage("..sample.portfolio..")
|
||||
.should()
|
||||
.dependOnClassesThat()
|
||||
.resideInAPackage("..sample.portfolio..");
|
||||
```
|
||||
|
||||
```java
|
||||
// 출처: [[wiki/projects/ca-tmpl/clean-architecture-package-layout]]
|
||||
// 실제 파일: app-bootstrap/.../ArchitectureViolationFixtureTest.java, ca-tmpl @f6fbd4e196b4
|
||||
class ArchitectureViolationFixtureTest {
|
||||
private static final JavaClasses VIOLATION_CLASSES =
|
||||
new ClassFileImporter().importPackages("dev.caskeleton.bootstrap.architecture.violations");
|
||||
|
||||
// intentional fixture classes를 읽어 각 ArchUnit rule이 실제 위반을 잡는지 확인한다.
|
||||
}
|
||||
```
|
||||
|
||||
## Sources / 근거 (canonical 인용 필수, derived layer 의무)
|
||||
|
||||
- [[wiki/projects/ca-tmpl/clean-architecture-package-layout]] — 이 글의 1차 canonical. module/package blueprint, Gradle dependency guard, ArchUnit enforcement, negative fixture, 검증 범위와 과장 금지 항목을 따른다.
|
||||
- [[wiki/concepts/clean-architecture-package-layout]] — 관련 개념 문서. 현재 `draft`이므로 구현 사실의 출처로 쓰지 않는다.
|
||||
|
||||
## 사실 vs 의견 / Fact vs opinion 구분
|
||||
|
||||
- 사실: ca-tmpl에는 Gradle module dependency matrix, `CleanArchitectureTest`, `ArchitectureViolationFixtureTest`, production → sample dependency ban, `shared-contract` package scope rule이 존재한다. 근거: [[wiki/projects/ca-tmpl/clean-architecture-package-layout]]
|
||||
- 사실: 검증 범위는 local/dev이며, 운영 배포나 운영 metric 검증은 없다. 근거: [[wiki/projects/ca-tmpl/clean-architecture-package-layout]]
|
||||
- 의견: package layout은 문서보다 build-time guardrail과 함께 있을 때 skeleton 학습 효과가 커진다.
|
||||
- 알지 못하는 것: 운영 조직에서 이 구조가 장기 유지보수 비용을 얼마나 줄였는지는 측정하지 않았다.
|
||||
|
||||
## 답할 수 있는 범위 / Answer boundary
|
||||
|
||||
- 자신 있게 답할 수 있는 후속 질문:
|
||||
- 왜 Gradle multi-module을 1차 boundary로 두었는가?
|
||||
- Gradle dependency matrix와 ArchUnit rule은 각각 무엇을 막는가?
|
||||
- `sample-portfolio`를 production code가 의존하지 못하게 한 이유는 무엇인가?
|
||||
- violations-as-data fixture가 왜 필요한가?
|
||||
- 다음 글로 넘길 부분:
|
||||
- Spring Modulith 도입 여부.
|
||||
- 대규모 도메인에서 feature module을 더 쪼개는 전략.
|
||||
- runtime lookup/reflection 우회를 자동으로 잡는 방법.
|
||||
|
||||
## 게시 체크리스트 / Publish checklist
|
||||
|
||||
- [x] 모든 사실 주장에 canonical 링크 있음
|
||||
- [x] 사실 vs 의견 분리 명시됨
|
||||
- [x] 금지 마케팅 표현 없음
|
||||
- [x] 코드 예제 출처 명시
|
||||
- [x] 타깃 독자 가정과 톤 일치
|
||||
- [x] `/lint` 통과
|
||||
- [ ] 게시 URL 기록 (게시 후):
|
||||
|
||||
## Related / 관련
|
||||
|
||||
- 후속 글 후보: [[wiki/blog/ca-tmpl-skeleton-governance-registry-verification-test-scorecard-2026-07-02]]
|
||||
- 관련 개념 문서: [[wiki/concepts/clean-architecture-package-layout]]
|
||||
@@ -1 +0,0 @@
|
||||
../../vault/40-publish/blog/ca-tmpl-config-and-adapter-templates-2026-07-02.md
|
||||
@@ -0,0 +1,154 @@
|
||||
---
|
||||
title: Optional Adapter를 설정 계약으로 다루기
|
||||
source_type: blog
|
||||
status: verified
|
||||
confidence: high
|
||||
tags: [blog, ca-tmpl, config, adapter, conditional-on-property]
|
||||
related_projects: [ca-tmpl]
|
||||
last_reviewed: 2026-07-03
|
||||
canonical_sources:
|
||||
- wiki/projects/ca-tmpl/config-and-adapter-templates
|
||||
audience: backend-engineer
|
||||
target_publish:
|
||||
status_label: ready
|
||||
---
|
||||
|
||||
# Optional Adapter를 설정 계약으로 다루기
|
||||
|
||||
## Parent / 부모 (필수)
|
||||
|
||||
- 핵심 canonical: [[wiki/projects/ca-tmpl/config-and-adapter-templates]]
|
||||
- 관련 개념 문서: [[wiki/concepts/config-and-adapter-templates]] - 일반 config/adapter template 비교. 현재 이 글의 구현 사실 근거는 verified project canonical에 둔다.
|
||||
|
||||
## 타깃 독자 / Target reader
|
||||
|
||||
- 독자 profile: Spring Boot optional adapter와 env-driven 설정을 skeleton에 넣으려는 백엔드 엔지니어.
|
||||
- 이미 안다고 가정하는 것: `@ConfigurationProperties`, `@ConditionalOnProperty`, env var.
|
||||
- 처음 듣는다고 가정하는 것: adapter 추가를 설정값 하나가 아니라 registry, bean gating, static rule, startup fail-fast가 맞물린 계약으로 보는 방식.
|
||||
|
||||
## 도입 / Hook
|
||||
|
||||
Optional adapter는 처음에는 편해 보입니다. Redis가 있으면 cache adapter를 켜고, Kafka가 있으면 message broker adapter를 켜고, Slack이나 email provider는 필요할 때만 붙이면 됩니다. 문제는 “꺼져 있어도 안전한가”입니다. env key가 `.env`에는 있는데 `application.yml`에서 안 쓰이거나, optional adapter bean이 조건 없이 등록되거나, disabled 상태인데 application layer가 adapter package를 직접 import하면 설정은 계약이 아니라 분위기가 됩니다.
|
||||
|
||||
ca-tmpl은 이 문제를 `@ConditionalOnProperty` 하나로 끝내지 않았습니다. `APP_` env registry와 `.env` drift gate, `@ConfigurationProperties` settings, optional adapter package isolation, `@ConditionalOnProperty` annotation rule, startup failure exception을 나눠 두었습니다. 이 글은 optional adapter를 “있으면 쓰고 없으면 말고”가 아니라 “켜지는 조건과 실패 방식이 검증되는 계약”으로 만든 이유를 정리합니다.
|
||||
|
||||
## 본문 outline / Body outline
|
||||
|
||||
1. optional adapter의 흔한 실패 - env drift, ungated bean, hidden direct import.
|
||||
2. 설정은 runtime contract다 - `.env`, `application.yml`, env registry를 같이 검증한다.
|
||||
3. `@ConditionalOnProperty`의 역할과 한계 - bean 등록 조건은 보지만 runtime activation 전체를 증명하지는 않는다.
|
||||
4. static isolation과 startup fail-fast - disabled adapter가 조용히 섞이지 않게 한다.
|
||||
5. 구현된 것과 provider-specific template의 남은 범위를 분리한다.
|
||||
|
||||
## 본문 / Body
|
||||
|
||||
설정값은 코드 밖에 있지만, 실제로는 코드의 실행 경로를 바꿉니다. `APP_CACHE_REDIS_ENABLED=true`가 들어오면 Redis cache backend가 생기고, `app.messaging.broker=kafka`가 들어오면 Kafka broker bean이 등록됩니다. 이런 설정을 문서로만 관리하면 drift가 생깁니다. `.env`에만 남은 key, `application.yml`에만 있는 placeholder, registry에 등록되지 않은 `APP_` key가 조금씩 쌓입니다.
|
||||
|
||||
ca-tmpl은 이 drift를 Gradle task로 막습니다. `verifyEnvKeys`는 `src/.env`, `application.yml`, `docs/registries/env-keys.yaml`을 함께 읽습니다. `application.yml`의 required placeholder가 `.env`에 없으면 실패하고, `.env` key가 어떤 placeholder에도 쓰이지 않으면 실패합니다. 또 `APP_` key는 env registry에 등록되어 있어야 합니다. 즉 설정 문서와 실제 boot 설정이 따로 움직이지 않게 빌드 단계에서 묶습니다.
|
||||
|
||||
adapter activation은 Layer 1에서 Spring bean 조건으로 표현합니다. Redis cache backend는 `app.cache.redis.enabled=true`일 때만 `CacheBackend` bean을 제공합니다. Kafka broker도 `app.messaging.broker=kafka`일 때만 `MessageBroker` bean을 등록합니다. 이 방식의 장점은 adapter 구현이 중앙 router나 use case를 직접 수정하지 않아도 “내가 활성화되는 조건”을 자기 config에 선언할 수 있다는 점입니다.
|
||||
|
||||
하지만 `@ConditionalOnProperty`만으로는 충분하지 않습니다. ArchUnit은 런타임 property evaluation을 실행하지 않습니다. 대신 ca-tmpl은 정적 분석으로 두 가지를 봅니다. application layer가 optional adapter package를 import하지 않는지, optional adapter package 안의 `@Bean` method가 `@ConditionalOnProperty`를 갖고 있는지입니다. 이건 “현재 어떤 profile에서 bean이 켜졌는가”를 증명하는 것이 아니라, disabled-default를 우회할 수 있는 코드 구조를 막는 쪽입니다.
|
||||
|
||||
Layer 3는 startup fail-fast입니다. required capability adapter가 꺼져 있거나 coordination bean이 없으면 `RequiredAdapterDisabledException` 계열 startup failure로 드러납니다. cache router나 messaging config처럼 중앙 binding 지점에서도 disabled backend binding이 조용한 no-op으로 흘러가지 않도록 설계합니다. skeleton에서 중요한 것은 “꺼져 있으면 아무 일도 하지 않는다”가 아니라, “꺼져 있는데 필요한 경로라면 빨리 실패한다”입니다.
|
||||
|
||||
이 결정을 그림으로 보면 세 층입니다.
|
||||
|
||||
| 층 | 잡는 문제 | ca-tmpl 구현 범위 |
|
||||
|---|---|---|
|
||||
| Env registry gate | `.env` / `application.yml` / registry drift | `verifyEnvKeys` |
|
||||
| Bean gating | optional adapter bean이 조건 없이 등록되는 문제 | `@ConditionalOnProperty`, `DisabledAdapterArchitectureTest` |
|
||||
| Startup/runtime fail-fast | required adapter가 disabled인데 조용히 진행되는 문제 | startup failure exception, router/config guard |
|
||||
|
||||
이 글에서 조심해야 할 경계도 있습니다. ca-tmpl에는 env registry/gate와 optional adapter guard가 구현되어 있고 `./gradlew check`로 로컬 검증됐습니다. 반면 모든 provider-specific adapter template가 완성됐다고 말하면 안 됩니다. Kafka, Redis, Slack, Google Email 같은 표면이 일부 존재하더라도, “모든 외부 provider 전환을 검증했다”는 주장은 project canonical 범위를 넘습니다. 이 글의 결론은 “optional adapter를 완성했다”가 아니라 “optional adapter가 켜지고 꺼지는 실패 모드를 설정 계약으로 드러내기 시작했다”입니다.
|
||||
|
||||
## 코드 예제 / Code samples (있다면)
|
||||
|
||||
```groovy
|
||||
// 출처: [[wiki/projects/ca-tmpl/config-and-adapter-templates]]
|
||||
// 실제 파일: src/build.gradle, ca-tmpl @f6fbd4e196b4
|
||||
tasks.register('verifyEnvKeys') {
|
||||
description = 'Verifies src/.env covers application.yml placeholders and every APP_ key is registered.'
|
||||
|
||||
File envFile = file("${rootProject.projectDir}/.env")
|
||||
File appYml = file("${rootProject.projectDir}/app-bootstrap/src/main/resources/application.yml")
|
||||
File registryFile = file("${rootProject.projectDir}/../docs/registries/env-keys.yaml")
|
||||
}
|
||||
```
|
||||
|
||||
```java
|
||||
// 출처: [[wiki/projects/ca-tmpl/config-and-adapter-templates]]
|
||||
// 실제 파일: adapter-outbound/.../RedisCacheAdapterConfig.java, ca-tmpl @f6fbd4e196b4
|
||||
@Bean
|
||||
@ConditionalOnProperty(
|
||||
name = "app.cache.redis.enabled",
|
||||
havingValue = "true",
|
||||
matchIfMissing = false)
|
||||
public CacheBackend redisCacheBackend(RedisClient redisClient) {
|
||||
return new RedisCacheStore(redisClient);
|
||||
}
|
||||
```
|
||||
|
||||
```java
|
||||
// 출처: [[wiki/projects/ca-tmpl/config-and-adapter-templates]]
|
||||
// 실제 파일: adapter-outbound/.../KafkaAdapterConfig.java, ca-tmpl @f6fbd4e196b4
|
||||
@Bean
|
||||
@ConditionalOnProperty(name = "app.messaging.broker", havingValue = "kafka")
|
||||
public MessageBroker kafkaMessageBroker(KafkaSender sender, KafkaAdapterSettings settings) {
|
||||
if (settings.brokers().isEmpty()) {
|
||||
throw new IllegalStateException("app.messaging.broker=kafka requires a non-empty broker list");
|
||||
}
|
||||
return new KafkaMessageBroker(sender);
|
||||
}
|
||||
```
|
||||
|
||||
```java
|
||||
// 출처: [[wiki/projects/ca-tmpl/config-and-adapter-templates]]
|
||||
// 실제 파일: app-bootstrap/.../DisabledAdapterArchitectureTest.java, ca-tmpl @f6fbd4e196b4
|
||||
static final ArchRule APPLICATION_DOES_NOT_DEPEND_ON_OPTIONAL_ADAPTERS =
|
||||
noClasses()
|
||||
.that()
|
||||
.resideInAPackage("..application..")
|
||||
.should()
|
||||
.dependOnClassesThat()
|
||||
.resideInAnyPackage(OPTIONAL_ADAPTER_PACKAGES);
|
||||
```
|
||||
|
||||
## Sources / 근거 (canonical 인용 필수, derived layer 의무)
|
||||
|
||||
- [[wiki/projects/ca-tmpl/config-and-adapter-templates]] - 이 글의 1차 canonical. env registry/gate, `@ConfigurationProperties`, optional adapter `@ConditionalOnProperty`, ArchUnit static guard, startup fail-fast, local verification, provider별 미완성 범위를 따른다.
|
||||
- [[wiki/concepts/config-and-adapter-templates]] - 관련 개념 문서. Spring Cloud Config, ConfigMap reload, Consul, Parameter Store, feature flag SaaS 같은 대안 비교 배경으로만 둔다.
|
||||
|
||||
## 사실 vs 의견 / Fact vs opinion 구분
|
||||
|
||||
- 사실: ca-tmpl에는 `verifyEnvKeys`, `docs/registries/env-keys.yaml`, 여러 `@ConfigurationProperties` settings, optional adapter `@ConditionalOnProperty` config, `DisabledAdapterArchitectureTest`, startup failure exception이 존재한다. 근거: [[wiki/projects/ca-tmpl/config-and-adapter-templates]]
|
||||
- 사실: `./gradlew check`가 2026-07-02 기준 통과했고, `verifyEnvKeys`와 optional adapter 관련 검증이 local/dev 범위에 포함된다. 근거: [[wiki/projects/ca-tmpl/config-and-adapter-templates]]
|
||||
- 사실: 모든 provider-specific adapter template와 모든 disabled runtime path가 완성됐다고 말하지 않는다. 근거: [[wiki/projects/ca-tmpl/config-and-adapter-templates]]
|
||||
- 의견: optional adapter는 silent noop보다 fail-fast 계약으로 두는 편이 skeleton 학습과 장애 분석에 더 유리하다.
|
||||
- 알지 못하는 것: 실제 환경에서 adapter on/off를 전환한 운영 경험, provider SDK별 production tuning.
|
||||
|
||||
## 답할 수 있는 범위 / Answer boundary
|
||||
|
||||
- 자신 있게 답할 수 있는 후속 질문:
|
||||
- env key drift를 왜 build gate로 잡는가?
|
||||
- `@ConditionalOnProperty`는 어떤 문제를 해결하고 어떤 문제를 해결하지 못하는가?
|
||||
- optional adapter static isolation과 startup fail-fast가 왜 둘 다 필요한가?
|
||||
- 다음 글로 넘길 부분:
|
||||
- 특정 provider SDK별 timeout/retry/auth 설정.
|
||||
- runtime reload나 feature flag SaaS가 필요한 제품 단계.
|
||||
- 실제 환경에서 adapter toggle을 운영한 경험.
|
||||
|
||||
## 게시 체크리스트 / Publish checklist
|
||||
|
||||
- [x] 모든 사실 주장에 canonical 링크 있음
|
||||
- [x] 사실 vs 의견 분리 명시됨
|
||||
- [x] 금지 마케팅 표현 없음
|
||||
- [x] 코드 예제 출처 명시
|
||||
- [x] 타깃 독자 가정과 톤 일치
|
||||
- [x] `/lint` 통과
|
||||
- [ ] 게시 URL 기록 (게시 후):
|
||||
|
||||
## Related / 관련
|
||||
|
||||
- 후속 글 후보: [[wiki/blog/ca-tmpl-runtime-container-health-migration-2026-07-02]]
|
||||
- 후속 글 후보: [[wiki/blog/ca-tmpl-data-layer-persistence-cache-outbound-2026-07-02]]
|
||||
@@ -1 +0,0 @@
|
||||
../../vault/40-publish/blog/ca-tmpl-data-layer-persistence-cache-outbound-2026-07-02.md
|
||||
@@ -0,0 +1,184 @@
|
||||
---
|
||||
title: Persistence와 Cache, Outbound 경계를 한 문서에서 분리하기
|
||||
source_type: blog
|
||||
status: verified
|
||||
confidence: high
|
||||
tags: [blog, ca-tmpl, persistence, cache, outbound]
|
||||
related_projects: [ca-tmpl]
|
||||
last_reviewed: 2026-07-02
|
||||
canonical_sources:
|
||||
- wiki/projects/ca-tmpl/data-layer-persistence-cache-outbound
|
||||
audience: backend-engineer
|
||||
target_publish:
|
||||
status_label: ready
|
||||
---
|
||||
|
||||
# Persistence와 Cache, Outbound 경계를 한 문서에서 분리하기
|
||||
|
||||
## Parent / 부모 (필수)
|
||||
|
||||
- 핵심 canonical: [[wiki/projects/ca-tmpl/data-layer-persistence-cache-outbound]]
|
||||
- 관련 개념 문서: [[wiki/concepts/data-layer-persistence-cache-outbound]] — data layer 일반 개념. 현재 이 글의 구현 사실 근거는 verified project canonical에 둔다.
|
||||
|
||||
## 타깃 독자 / Target reader
|
||||
|
||||
- 독자 profile: data layer baseline을 skeleton 수준에서 정하려는 백엔드 엔지니어.
|
||||
- 이미 안다고 가정하는 것: JPA, cache-aside, outbound HTTP, connection pool.
|
||||
- 처음 듣는다고 가정하는 것: persistence/cache/outbound를 한데 묶되 증거 등급을 분리하는 방식.
|
||||
|
||||
## 도입 / Hook
|
||||
|
||||
- 문제 / 궁금증: data layer는 persistence, cache, outbound가 섞여 보여도 실패 모드와 검증 범위가 다르다.
|
||||
- 이 글이 답하는 것: ca-tmpl에서 구현된 항목과 문서/계획만 있는 항목을 구분한다.
|
||||
- 이 글이 답하지 않는 것: 실제 운영 DB latency와 cache hit ratio 개선 측정.
|
||||
|
||||
## 본문 outline / Body outline
|
||||
|
||||
1. data layer baseline을 쪼개서 보기 — persistence, cache, outbound.
|
||||
2. 실제 구현된 범위 — idempotency/outbox adapter, migration, OSIV/Hikari guard, lower-layer cache SPI.
|
||||
3. cache와 outbound의 실패 계약 — fail-open/fail-closed를 구분한다.
|
||||
4. Hikari/startup guard와 slow query 논의 — 구현/계획/needs-confirmation을 분리한다.
|
||||
5. 운영 검증 없음 — metric과 incident 경험처럼 말하지 않는다.
|
||||
|
||||
## 본문 / Body
|
||||
|
||||
data layer라고 부르면 하나로 보이지만, 실제로는 서로 다른 실패 모드가 섞여 있습니다. persistence는 DB transaction과 constraint, connection pool 문제가 중심입니다. cache는 빠른 조회와 stale data, backend 장애 시 degrade 정책이 중심입니다. outbound HTTP는 외부 dependency의 timeout, retry, circuit breaker, shutdown 처리 문제가 중심입니다. ca-tmpl의 data layer 문서는 이 셋을 한 문서에 두되, 구현된 범위와 계획만 있는 범위를 분리합니다.
|
||||
|
||||
이 분리가 중요한 이유는 과장하기 쉽기 때문입니다. “data layer baseline을 구현했다”고 말하면 persistence classifier, cache consistency, outbound resilience가 모두 같은 수준으로 끝난 것처럼 들립니다. 하지만 ca-tmpl 기준으로는 구현된 slice가 서로 다릅니다. idempotency/outbox RDBMS adapter, PostgreSQL migration, OSIV/Hikari startup guard, lower-layer cache SPI/router/fail-open, outbound HTTP client는 구현·로컬 검증됐습니다. 반면 SQLState classifier 전체, read replica lag metric, cache-aside + Redisson distributed mutex + after-commit invalidation 전체 contract, 운영 tuning은 아직 planned 또는 부분 구현입니다.
|
||||
|
||||
persistence 쪽에서 구현된 대표 guard는 OSIV off입니다. OSIV(Open Session In View)는 web response 렌더링 시점까지 Hibernate session을 열어두는 방식입니다. 편리하지만 presentation layer에서 lazy association을 만지는 순간 DB query가 나갈 수 있습니다. ca-tmpl은 `spring.jpa.open-in-view=true`가 명시되면 startup에서 실패시키는 validator를 둡니다. 즉 layer boundary를 runtime configuration에서도 깨지 않게 합니다.
|
||||
|
||||
HikariCP 설정도 startup guard로 다룹니다. connection-timeout은 최소 250ms 이상이어야 하고, validation-timeout은 connection-timeout보다 작아야 하며, keepalive-time은 max-lifetime보다 작아야 합니다. leak-detection-threshold도 켤 거면 2000ms 이상이어야 합니다. 이것은 pool sizing을 운영에서 측정했다는 뜻이 아닙니다. 잘못 조합된 knob를 애플리케이션 시작 시점에 빨리 실패시키는 guard입니다.
|
||||
|
||||
cache 쪽은 fail-open 경계를 구현했습니다. ca-tmpl의 `CacheStoreRouter`는 logical cache name을 backend id로 라우팅합니다. binding이 없는 logical cache를 호출하면 조용히 no-op 하지 않고 `AdapterDisabledException`을 던집니다. 반대로 backend가 구성된 뒤 실제 cache backend 호출이 실패하면 `FailOpenCacheStore`가 get은 miss로, put은 관찰된 실패로 낮춥니다. cache는 성능 보조 장치이므로 backend 장애가 곧 5xx가 되지 않게 하는 쪽입니다.
|
||||
|
||||
이 차이가 outbox와 다릅니다. outbox publish는 fail-open이면 안 됩니다. 메시지 발행 실패를 조용히 삼키면 downstream이 영원히 변경 사실을 모를 수 있습니다. 그래서 outbox는 `FAILED`/`DEAD` state machine과 error log를 갖습니다. cache는 장애 시 miss로 degrade할 수 있지만, outbox는 실패를 상태로 남기고 다시 처리해야 합니다. 같은 “adapter failure”라도 업무 의미가 다릅니다.
|
||||
|
||||
outbound HTTP는 또 다른 경계입니다. ca-tmpl의 `OutboundHttpClient`는 dependency name별 baseline client를 만들고, shutdown 중이면 네트워크를 맺기 전에 fail-fast합니다. buffered 호출은 retry/circuit breaker decorator를 거치고, streaming 호출은 retry하지 않습니다. 이미 일부 bytes를 소비한 stream은 안전하게 재시도하기 어렵기 때문입니다. retry policy도 GET/HEAD/PUT/DELETE 같은 idempotent method만 재시도 대상으로 둡니다. POST/PATCH는 기본적으로 제외됩니다.
|
||||
|
||||
outbound HTTP에서 중요한 것은 timeout 3축입니다. connect timeout, read timeout, global call timeout을 분리해서 생각합니다. connect timeout은 TCP 연결 단계, read timeout은 socket read 단계, global call timeout은 retry를 포함한 전체 예산입니다. ca-tmpl의 현재 구현은 이 값을 기본값으로 박아두기보다 필수 설정으로 요구하고, 누락 또는 잘못된 raw RestClient 등록을 startup에서 막는 방향입니다.
|
||||
|
||||
정리하면 ca-tmpl의 data layer baseline은 “DB, cache, HTTP를 다 구현했다”는 단순한 문장이 아닙니다. 구현된 것은 구현됐다고 말하고, planned인 것은 planned라고 남기는 문서입니다. 이 글에서 가장 중요한 학습 포인트도 여기에 있습니다. data layer의 경계는 기술 이름으로 나뉘는 것이 아니라, 실패했을 때 무엇을 보존해야 하는지로 나뉩니다. DB transaction은 정합성을 보존해야 하고, cache는 miss로 degrade할 수 있으며, outbound HTTP는 retry/timeout 예산 안에서 실패를 분류해야 합니다.
|
||||
|
||||
## 코드 예제 / Code samples (있다면)
|
||||
|
||||
```java
|
||||
// 출처: [[wiki/projects/ca-tmpl/data-layer-persistence-cache-outbound]]
|
||||
// 실제 파일: app-bootstrap/.../OpenInViewSafetyValidator.java, ca-tmpl @f6fbd4e196b4
|
||||
public void afterSingletonsInstantiated() {
|
||||
Boolean openInView = environment.getProperty("spring.jpa.open-in-view", Boolean.class);
|
||||
if (Boolean.TRUE.equals(openInView)) {
|
||||
throw new IllegalStateException("APP_DATASOURCE_OPEN_IN_VIEW must be false");
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```java
|
||||
// 출처: [[wiki/projects/ca-tmpl/data-layer-persistence-cache-outbound]]
|
||||
// 실제 파일: app-bootstrap/.../HikariPoolConstraintValidator.java
|
||||
if (validationTimeout != null
|
||||
&& connectionTimeout != null
|
||||
&& validationTimeout >= connectionTimeout) {
|
||||
violations.add("validation-timeout must be < connection-timeout");
|
||||
}
|
||||
if (keepaliveTime != null && maxLifetime != null && keepaliveTime >= maxLifetime) {
|
||||
violations.add("keepalive-time must be < max-lifetime");
|
||||
}
|
||||
```
|
||||
|
||||
```java
|
||||
// 출처: [[wiki/projects/ca-tmpl/data-layer-persistence-cache-outbound]]
|
||||
// 실제 파일: adapter-outbound/.../CacheStoreRouter.java
|
||||
public Optional<String> get(String logicalName, String key) {
|
||||
return resolve(logicalName).get(key);
|
||||
}
|
||||
|
||||
private CacheStore resolve(String logicalName) {
|
||||
String backendId = bindings.get(logicalName);
|
||||
if (backendId == null) {
|
||||
throw new AdapterDisabledException("cache", "no cache backend bound");
|
||||
}
|
||||
return backends.get(backendId);
|
||||
}
|
||||
```
|
||||
|
||||
```java
|
||||
// 출처: [[wiki/projects/ca-tmpl/data-layer-persistence-cache-outbound]]
|
||||
// 실제 파일: adapter-outbound/.../FailOpenCacheStore.java
|
||||
public Optional<String> get(String key) {
|
||||
try {
|
||||
return delegate.get(key);
|
||||
} catch (Exception ex) {
|
||||
dependencyLogger.logFailure(delegate.backendId(), "cache", "get", ex);
|
||||
return Optional.empty();
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```java
|
||||
// 출처: [[wiki/projects/ca-tmpl/data-layer-persistence-cache-outbound]]
|
||||
// 실제 파일: adapter-outbound/.../OutboundHttpClient.java
|
||||
if (shutdownGuard.isShuttingDown()) {
|
||||
throw observer.rejectShutdown("shutdown in progress — outbound call rejected fail-fast");
|
||||
}
|
||||
|
||||
retryPolicy.beginCall(method, deadline);
|
||||
try {
|
||||
Supplier<T> decorated = countingSupplier;
|
||||
if (retry.isPresent()) decorated = Retry.decorateSupplier(retry.get(), decorated);
|
||||
if (cb.isPresent()) decorated = CircuitBreaker.decorateSupplier(cb.get(), decorated);
|
||||
return decorated.get();
|
||||
} finally {
|
||||
retryPolicy.endCall();
|
||||
}
|
||||
```
|
||||
|
||||
```java
|
||||
// 출처: [[wiki/projects/ca-tmpl/data-layer-persistence-cache-outbound]]
|
||||
// 실제 파일: adapter-outbound/.../OutboundRetryPolicy.java
|
||||
private static final Set<HttpMethod> IDEMPOTENT_METHODS =
|
||||
Set.of(HttpMethod.GET, HttpMethod.HEAD, HttpMethod.PUT, HttpMethod.DELETE);
|
||||
|
||||
if (!IDEMPOTENT_METHODS.contains(ctx.method())) {
|
||||
return false;
|
||||
}
|
||||
```
|
||||
|
||||
## Sources / 근거 (canonical 인용 필수, derived layer 의무)
|
||||
|
||||
- [[wiki/projects/ca-tmpl/data-layer-persistence-cache-outbound]] — 이 글의 1차 canonical. persistence/cache/outbound 각각의 구현·부분 구현·planned 경계를 따른다.
|
||||
- [[wiki/concepts/data-layer-persistence-cache-outbound]] — 관련 개념 문서. 구현 사실 출처로 쓰지 않는다.
|
||||
|
||||
## 사실 vs 의견 / Fact vs opinion 구분
|
||||
|
||||
- 사실: ca-tmpl에는 idempotency/outbox RDBMS adapter와 migration, OSIV-off startup guard, Hikari inter-knob startup guard, lower-layer cache SPI/router/fail-open, outbound HTTP baseline이 존재한다. 근거: [[wiki/projects/ca-tmpl/data-layer-persistence-cache-outbound]]
|
||||
- 사실: SQLState classifier 전체, read replica lag metric/alert, cache-aside + Redisson distributed mutex + after-commit invalidation 전체 contract, 운영 tuning은 구현 완료로 말하지 않는다. 근거: [[wiki/projects/ca-tmpl/data-layer-persistence-cache-outbound]]
|
||||
- 사실: 운영 배포, pool wait p99, cache hit ratio, circuit breaker 운영 경험은 없다. 근거: [[wiki/projects/ca-tmpl/data-layer-persistence-cache-outbound]]
|
||||
- 의견: persistence/cache/outbound를 함께 다루더라도 실패 계약은 분리해서 설명해야 한다.
|
||||
- 알지 못하는 것: production pool wait, slow query, cache hit rate, outbound dependency 장애율.
|
||||
|
||||
## 답할 수 있는 범위 / Answer boundary
|
||||
|
||||
- 자신 있게 답할 수 있는 후속 질문:
|
||||
- fail-open cache와 fail-closed outbox의 차이는 무엇인가?
|
||||
- OSIV off startup guard가 layer boundary와 어떤 관련이 있는가?
|
||||
- Hikari knob guard는 운영 tuning과 어떻게 다른가?
|
||||
- outbound HTTP retry에서 POST/PATCH를 제외한 이유는 무엇인가?
|
||||
- 다음 글로 넘길 부분:
|
||||
- 실제 DB/cache 운영 metric.
|
||||
- SQLState classifier 전체 구현과 운영 alert.
|
||||
- cache-aside after-commit invalidation의 full contract.
|
||||
|
||||
## 게시 체크리스트 / Publish checklist
|
||||
|
||||
- [x] 모든 사실 주장에 canonical 링크 있음
|
||||
- [x] 사실 vs 의견 분리 명시됨
|
||||
- [x] 금지 마케팅 표현 없음
|
||||
- [x] 코드 예제 출처 명시
|
||||
- [x] 타깃 독자 가정과 톤 일치
|
||||
- [x] `/lint` 통과
|
||||
- [ ] 게시 URL 기록 (게시 후):
|
||||
|
||||
## Related / 관련
|
||||
|
||||
- 후속 글 후보: [[wiki/blog/ca-tmpl-transactional-outbox-pattern-2026-07-02]]
|
||||
@@ -1 +0,0 @@
|
||||
../../vault/40-publish/blog/ca-tmpl-devops-ci-supply-chain-dx-2026-07-02.md
|
||||
@@ -0,0 +1,143 @@
|
||||
---
|
||||
title: CI와 Supply Chain을 Skeleton 계약으로 묶기
|
||||
source_type: blog
|
||||
status: verified
|
||||
confidence: high
|
||||
tags: [blog, ca-tmpl, devops, ci-cd, supply-chain]
|
||||
related_projects: [ca-tmpl]
|
||||
last_reviewed: 2026-07-03
|
||||
canonical_sources:
|
||||
- wiki/projects/ca-tmpl/devops-ci-supply-chain-dx
|
||||
audience: backend-engineer
|
||||
target_publish:
|
||||
status_label: ready
|
||||
---
|
||||
|
||||
# CI와 Supply Chain을 Skeleton 계약으로 묶기
|
||||
|
||||
## Parent / 부모 (필수)
|
||||
|
||||
- 핵심 canonical: [[wiki/projects/ca-tmpl/devops-ci-supply-chain-dx]]
|
||||
- 관련 개념 문서: [[wiki/concepts/devops-ci-supply-chain-dx]] - 일반 CI/supply-chain/DX 개념. 현재 이 글의 구현 사실 근거는 verified project canonical에 둔다.
|
||||
|
||||
## 타깃 독자 / Target reader
|
||||
|
||||
- 독자 profile: template repo의 CI, static analysis, release/supply-chain baseline을 설계하려는 엔지니어.
|
||||
- 이미 안다고 가정하는 것: Gradle, GitHub Actions, dependency lock, SBOM, static analysis.
|
||||
- 처음 듣는다고 가정하는 것: CI를 도구 목록이 아니라 gate ownership, drift check, release evidence의 계약으로 보는 방식.
|
||||
|
||||
## 도입 / Hook
|
||||
|
||||
CI에 도구를 많이 붙이는 것은 어렵지 않습니다. formatter, linter, unit test, integration test, vulnerability scanner, SBOM, signing, provenance를 순서대로 추가하면 화면은 그럴듯해집니다. 그런데 어떤 gate가 release를 막는지, 실패하면 어느 branch contract가 책임지는지, 문서의 gate matrix가 실제 workflow와 어긋나면 누가 잡는지 정하지 않으면 CI는 금방 장식이 됩니다.
|
||||
|
||||
ca-tmpl은 DevOps baseline을 “workflow 파일 몇 개”가 아니라 skeleton contract로 보려 했습니다. gate ownership matrix를 repo 안에 두고, Gradle custom task와 workflow job이 실제로 존재하는지 검사하며, dependency lock과 reproducible archive 설정, Cosign/SLSA 관련 workflow와 검증 스크립트를 둡니다. 단, hosted GitHub Actions에서 release를 실제 발행하고 Rekor/GHCR evidence까지 확인한 것은 아닙니다. 이 글은 구현된 local/repo-level gate와 live release 검증의 경계를 분리합니다.
|
||||
|
||||
## 본문 outline / Body outline
|
||||
|
||||
1. CI gate는 tool list가 아니라 release contract다.
|
||||
2. gate matrix와 owner branch - 무엇이 실패하면 누가 고쳐야 하는가.
|
||||
3. Gradle baseline - static analysis, dependency locking, reproducible archive.
|
||||
4. supply-chain workflow - SBOM, Cosign, SLSA, Trivy를 증거 체인으로 묶는다.
|
||||
5. local/dev portability와 hosted release 검증의 차이를 분리한다.
|
||||
|
||||
## 본문 / Body
|
||||
|
||||
CI를 설계할 때 흔한 실수는 “무엇을 실행할지”만 정하는 것입니다. 실제로 더 중요한 질문은 “이 검사가 실패하면 release가 막히는가”, “누가 policy를 소유하는가”, “문서에 적힌 gate가 실제 workflow에 남아 있는가”입니다. ca-tmpl의 `.github/ci-gate-matrix.yml`은 이 질문에 답하기 위한 파일입니다. 각 gate에는 id, release blocking 여부, owner branch, mechanism, ref, workflow가 붙습니다.
|
||||
|
||||
이 matrix는 문서가 아니라 검사 대상입니다. `verify-gate-matrix.sh`는 matrix row를 읽고, mechanism별로 실제 존재 여부를 확인합니다. `gradle-custom-task`라면 `tasks.register('<ref>')`가 있어야 하고, `contract-test`라면 test class 파일이 있어야 하며, `workflow-job`이라면 workflow 안에 job id가 있어야 합니다. 이렇게 하면 “문서에는 gate가 있는데 CI에서는 빠진 상태”를 줄일 수 있습니다.
|
||||
|
||||
Gradle baseline도 여러 층으로 나뉩니다. `src/build.gradle`은 Spotless, Checkstyle, SpotBugs, ErrorProne을 subproject에 적용하고, dependency locking을 strict mode로 켭니다. archive task는 timestamp, file order, permission을 고정해 build artifact가 host 환경에 덜 흔들리도록 합니다. 이것은 production artifact reproducibility를 완전히 증명한다는 뜻이 아니라, skeleton에서 entropy source를 줄이는 baseline입니다.
|
||||
|
||||
Supply chain 쪽은 release evidence를 digest 중심으로 묶으려는 방향입니다. `.github/workflows/build-release-supply-chain.yml`에는 SBOM generation, Trivy image scan, Cosign sign/attest, SLSA provenance, verification, promotion step이 있습니다. `.github/scripts/verify-supply-chain-contract.sh`는 workflow와 policy file에 필요한 문자열과 job wiring이 남아 있는지 확인합니다. 예를 들어 `cosign sign --yes`, `cosign attest --yes`, `--certificate-identity`, `--certificate-oidc-issuer`, SLSA v1 predicate, exact builder identity 같은 조건을 검사합니다.
|
||||
|
||||
여기서 중요한 경계가 있습니다. ca-tmpl에 workflow와 검증 스크립트가 존재한다는 사실과, 실제 release artifact가 public registry에 올라갔고 Rekor/GHCR evidence로 검증됐다는 사실은 다릅니다. project canonical은 후자를 확인하지 않았다고 명시합니다. 따라서 이 글은 “supply-chain release를 운영했다”가 아니라 “supply-chain release contract를 repo-level workflow와 script로 고정했다”까지만 말합니다.
|
||||
|
||||
DX도 같은 관점입니다. `./gradlew bootstrap`은 compile, Docker preflight, dependency/migration/startup, sample contract, HTTP smoke를 하나의 진입점으로 묶습니다. 이 명령이 모든 OS와 CI 환경을 보장한다는 뜻은 아닙니다. 대신 새 프로젝트를 받은 사람이 “무엇부터 실행해야 하는가”를 덜 고민하게 만들고, 실패 지점을 단계로 나누려는 목적입니다.
|
||||
|
||||
결국 ca-tmpl의 DevOps baseline은 “이 도구를 썼다”보다 “어떤 증거가 release를 통과시키는가”에 가깝습니다. gate matrix가 workflow와 drift 나지 않아야 하고, dependency lock이 조용히 풀리면 안 되며, vulnerability suppression은 사유와 만료일 없이 남으면 안 됩니다. 이 정도가 local/repo-level에서 검증된 범위입니다. 실제 hosted CI run, release publication, live Cosign/Rekor 검증은 별도의 근거가 생긴 뒤에만 말할 수 있습니다.
|
||||
|
||||
## 코드 예제 / Code samples (있다면)
|
||||
|
||||
```yaml
|
||||
# 출처: [[wiki/projects/ca-tmpl/devops-ci-supply-chain-dx]]
|
||||
# 실제 파일: .github/ci-gate-matrix.yml, ca-tmpl @f6fbd4e196b4
|
||||
gates:
|
||||
- id: architecture-test
|
||||
release_blocking: true
|
||||
owner_branch: feature-architecture-enforcement-rules
|
||||
mechanism: contract-test
|
||||
ref: app-bootstrap/src/test/java/dev/caskeleton/bootstrap/architecture/CleanArchitectureTest.java
|
||||
runs_in: ci-quality-gates
|
||||
```
|
||||
|
||||
```bash
|
||||
# 출처: [[wiki/projects/ca-tmpl/devops-ci-supply-chain-dx]]
|
||||
# 실제 파일: .github/scripts/verify-gate-matrix.sh, ca-tmpl @f6fbd4e196b4
|
||||
# Cross-checks every row of .github/ci-gate-matrix.yml against reality:
|
||||
# gradle-custom-task -> a tasks.register('<ref>') exists
|
||||
# contract-test -> the <ref> test-class file exists under src/
|
||||
# workflow-job -> the <ref> job id exists in .github/workflows/<runs_in>.yml
|
||||
```
|
||||
|
||||
```groovy
|
||||
// 출처: [[wiki/projects/ca-tmpl/devops-ci-supply-chain-dx]]
|
||||
// 실제 파일: src/build.gradle, ca-tmpl @f6fbd4e196b4
|
||||
dependencyLocking {
|
||||
lockAllConfigurations()
|
||||
lockMode = LockMode.STRICT
|
||||
}
|
||||
|
||||
tasks.withType(AbstractArchiveTask).configureEach {
|
||||
preserveFileTimestamps = false
|
||||
reproducibleFileOrder = true
|
||||
}
|
||||
```
|
||||
|
||||
```bash
|
||||
# 출처: [[wiki/projects/ca-tmpl/devops-ci-supply-chain-dx]]
|
||||
# 실제 파일: .github/scripts/verify-supply-chain-contract.sh, ca-tmpl @f6fbd4e196b4
|
||||
require_fixed "${workflow}" 'cosign sign --yes' 'D6 keyless image signature'
|
||||
require_fixed "${workflow}" 'cosign attest --yes' 'D4 digest-bound SBOM attestation'
|
||||
require_fixed "${workflow}" '--certificate-identity' 'D12 signer identity verification'
|
||||
require_fixed "${workflow}" '--certificate-oidc-issuer' 'D12 OIDC issuer verification'
|
||||
require_fixed "${workflow}" 'generator_container_slsa3.yml@v2.1.0' 'D7 isolated SLSA generator'
|
||||
```
|
||||
|
||||
## Sources / 근거 (canonical 인용 필수, derived layer 의무)
|
||||
|
||||
- [[wiki/projects/ca-tmpl/devops-ci-supply-chain-dx]] - 이 글의 1차 canonical. CI gate matrix, Gradle gates, supply-chain workflow/script, local verification, live release 미검증 경계를 따른다.
|
||||
- [[wiki/concepts/devops-ci-supply-chain-dx]] - 관련 개념 문서. CI provider, signing, provenance, dependency lock, dev environment 대안 비교 배경으로만 둔다.
|
||||
|
||||
## 사실 vs 의견 / Fact vs opinion 구분
|
||||
|
||||
- 사실: ca-tmpl에는 CI workflow, `.github/ci-gate-matrix.yml`, gate matrix 검증 스크립트, supply-chain policy/script, Gradle dependency lock/reproducible archive 설정, 여러 custom verification task가 존재한다. 근거: [[wiki/projects/ca-tmpl/devops-ci-supply-chain-dx]]
|
||||
- 사실: `./gradlew check`가 2026-07-02 기준 통과했고, local gate 검증이 project canonical에 기록되어 있다. 근거: [[wiki/projects/ca-tmpl/devops-ci-supply-chain-dx]]
|
||||
- 사실: hosted GitHub Actions run, 실제 release publication, live Rekor/GHCR/Cosign 검증은 확인하지 않았다. 근거: [[wiki/projects/ca-tmpl/devops-ci-supply-chain-dx]]
|
||||
- 의견: skeleton에서는 CI tool list보다 gate ownership matrix가 더 오래 남는 설계 자산이다.
|
||||
- 알지 못하는 것: public artifact 소비자, 실제 release incident, live registry rollback 경험.
|
||||
|
||||
## 답할 수 있는 범위 / Answer boundary
|
||||
|
||||
- 자신 있게 답할 수 있는 후속 질문:
|
||||
- gate matrix가 왜 필요한가?
|
||||
- Gradle dependency locking과 reproducible archive 설정이 어떤 drift를 줄이는가?
|
||||
- Cosign/SLSA/Trivy workflow와 검증 스크립트가 repo-level에서 무엇을 고정하는가?
|
||||
- 다음 글로 넘길 부분:
|
||||
- 실제 release signing 운영.
|
||||
- public artifact distribution과 rollback manifest 운영.
|
||||
- SLSA level 달성 여부와 live provenance 검증.
|
||||
|
||||
## 게시 체크리스트 / Publish checklist
|
||||
|
||||
- [x] 모든 사실 주장에 canonical 링크 있음
|
||||
- [x] 사실 vs 의견 분리 명시됨
|
||||
- [x] 금지 마케팅 표현 없음
|
||||
- [x] 코드 예제 출처 명시
|
||||
- [x] 타깃 독자 가정과 톤 일치
|
||||
- [x] `/lint` 통과
|
||||
- [ ] 게시 URL 기록 (게시 후):
|
||||
|
||||
## Related / 관련
|
||||
|
||||
- 후속 글 후보: [[wiki/blog/ca-tmpl-skeleton-governance-registry-verification-test-scorecard-2026-07-02]]
|
||||
- 후속 글 후보: [[wiki/blog/ca-tmpl-sample-fixture-and-adoption-2026-07-02]]
|
||||
@@ -1 +0,0 @@
|
||||
../../vault/40-publish/blog/ca-tmpl-idempotency-key-design-2026-07-02.md
|
||||
@@ -0,0 +1,160 @@
|
||||
---
|
||||
title: Idempotency Key를 API 표면이 아니라 실행 계약으로 보기
|
||||
source_type: blog
|
||||
status: verified
|
||||
confidence: high
|
||||
tags: [blog, ca-tmpl, idempotency, api-design]
|
||||
related_projects: [ca-tmpl]
|
||||
last_reviewed: 2026-07-02
|
||||
canonical_sources:
|
||||
- wiki/projects/ca-tmpl/idempotency-key-design
|
||||
audience: backend-engineer
|
||||
target_publish:
|
||||
status_label: ready
|
||||
---
|
||||
|
||||
# Idempotency Key를 API 표면이 아니라 실행 계약으로 보기
|
||||
|
||||
## Parent / 부모 (필수)
|
||||
|
||||
- 핵심 canonical: [[wiki/projects/ca-tmpl/idempotency-key-design]]
|
||||
- 관련 개념 문서: [[wiki/concepts/idempotency-key-design]] — 일반 idempotency key 개념. 현재 이 글의 구현 사실 근거는 verified project canonical에 둔다.
|
||||
|
||||
## 타깃 독자 / Target reader
|
||||
|
||||
- 독자 profile: POST 중복 요청과 retry를 안전하게 처리하려는 백엔드 엔지니어.
|
||||
- 이미 안다고 가정하는 것: HTTP retry, unique key, transaction.
|
||||
- 처음 듣는다고 가정하는 것: scope, body digest, replay/in-flight/mismatch 분류를 API 계약으로 고정하는 방식.
|
||||
|
||||
## 도입 / Hook
|
||||
|
||||
- 문제 / 궁금증: `Idempotency-Key` header만 받는다고 idempotency가 구현되는 것은 아니다.
|
||||
- 이 글이 답하는 것: ca-tmpl이 key scope, request digest, status classification, persistence/executor 경계를 어떻게 나눴는지.
|
||||
- 이 글이 답하지 않는 것: production retry traffic과 duplicate suppression metric.
|
||||
|
||||
## 본문 outline / Body outline
|
||||
|
||||
1. header surface와 실제 executor의 차이.
|
||||
2. triple scope와 request digest — 같은 key가 무엇을 의미하는지 고정한다.
|
||||
3. in-flight/replay/mismatch 분류 — client가 무엇을 해야 하는지 알려준다.
|
||||
4. transaction boundary와 persistence adapter — local verification 범위.
|
||||
5. 아직 운영 검증은 없다.
|
||||
|
||||
## 본문 / Body
|
||||
|
||||
`Idempotency-Key` header를 받는 것만으로 idempotency가 구현되지는 않습니다. header는 단지 client가 “이 요청은 같은 의도로 다시 보낼 수 있다”고 알려주는 표면입니다. 서버가 실제로 해야 할 일은 더 많습니다. 같은 요청인지 판단해야 하고, 이미 처리 중인지 구분해야 하며, 완료된 결과를 replay할 수 있어야 하고, 같은 key로 다른 body가 들어오면 client bug로 돌려줘야 합니다.
|
||||
|
||||
ca-tmpl은 이 문제를 web filter 하나로 처리하지 않았습니다. 핵심 실행 계약은 application layer의 `IdempotencyExecutor`에 둡니다. web adapter는 header, principal, use case name, request fingerprint를 모아 context를 만들고, executor는 store port를 통해 claim/replay/mismatch/in-flight를 판정합니다. persistence adapter는 DB table과 unique constraint로 scope 충돌을 실제로 막습니다.
|
||||
|
||||
scope는 `(authenticatedPrincipal, idempotencyKey, useCaseName)` triple입니다. tenant isolation이 활성화되면 tenant가 앞에 붙어 4-tuple이 됩니다. 여기서 `useCaseName`을 넣는 이유가 중요합니다. 같은 principal이 같은 idempotency key를 두 다른 use case에 보냈을 때 충돌하면 안 됩니다. URL path를 scope에 넣지 않는 것도 의도입니다. path version이 바뀌어도 같은 application use case의 실행 의미가 유지될 수 있기 때문입니다.
|
||||
|
||||
request fingerprint는 같은 key가 같은 body를 뜻하는지 확인하는 장치입니다. ca-tmpl의 executor는 live record를 찾으면 fingerprint를 먼저 비교합니다. 같으면 상태에 따라 replay 또는 in-flight 처리로 갑니다. 다르면 `IdempotencyRequestMismatchException`을 던지고, web boundary에서 `422`로 매핑합니다. 같은 key를 재사용했지만 body가 다르다는 것은 보통 client가 idempotency key를 잘못 관리한다는 신호입니다.
|
||||
|
||||
동시 도착은 `409`로 분리합니다. executor는 record가 `IN_FLIGHT`이면 바로 실패시키지 않고 최대 200ms 동안 짧게 기다립니다. 그 안에 선행 요청이 완료되면 저장된 response를 replay할 수 있습니다. 그래도 완료되지 않으면 `IdempotencyInFlightException`이 나고 `409`로 응답합니다. 이 200ms는 부하 테스트로 튜닝된 수치가 아니라 ca-tmpl 기본 정책값입니다.
|
||||
|
||||
완료된 요청은 저장된 response를 replay합니다. action이 성공하면 codec이 response를 직렬화해 store에 저장하고, 같은 scope의 후속 요청은 action을 다시 실행하지 않고 그 payload를 역직렬화합니다. action이 예외를 던지면 executor는 record를 discard합니다. 실패한 실행을 영구적으로 replay하지 않기 위해서입니다. 즉 idempotency는 성공 응답 replay와 실행 중 충돌 제어를 다루며, 모든 실패를 캐시하는 장치가 아닙니다.
|
||||
|
||||
저장소는 DB table입니다. Redis나 in-memory cache만으로 두지 않은 이유는 skeleton에서 transaction boundary와 운영 복구 가능성을 우선했기 때문입니다. PostgreSQL migration에는 `tenant`, `principal`, `idempotency_key`, `use_case_name` unique constraint가 있습니다. TTL은 기본 24h이고, executor는 per-use-case override가 있더라도 72h cap을 넘지 못하게 합니다.
|
||||
|
||||
응답 코드도 의도적으로 나뉩니다. in-flight 충돌은 `409 Conflict`, 같은 key와 다른 body fingerprint는 `422 Unprocessable Entity`입니다. 두 상황은 client가 해야 할 일이 다릅니다. `409`은 조금 뒤 다시 시도할 수 있지만, `422`는 key/body 조합을 고쳐야 합니다. ca-tmpl은 이 차이를 error envelope mapping까지 이어갑니다.
|
||||
|
||||
검증 범위는 local/dev입니다. `IdempotencyExecutor`, web helper/codec, RDBMS store, PostgreSQL unique scope contract가 존재하고 `./gradlew check`로 검증됐습니다. 하지만 운영 duplicate suppression metric, 실제 retry traffic 비율, 200ms wait의 부하 기반 튜닝은 없습니다. 따라서 이 글에서 말할 수 있는 것은 구현과 로컬 검증이지 운영 효과 측정이 아닙니다.
|
||||
|
||||
## 코드 예제 / Code samples (있다면)
|
||||
|
||||
```java
|
||||
// 출처: [[wiki/projects/ca-tmpl/idempotency-key-design]]
|
||||
// 실제 파일: application-core/.../IdempotencyScope.java, ca-tmpl @f6fbd4e196b4
|
||||
public record IdempotencyScope(
|
||||
String tenant, String principal, String idempotencyKey, String useCaseName) {
|
||||
|
||||
public static IdempotencyScope of(String principal, String idempotencyKey, String useCaseName) {
|
||||
return of(null, principal, idempotencyKey, useCaseName);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```java
|
||||
// 출처: [[wiki/projects/ca-tmpl/idempotency-key-design]]
|
||||
// 실제 파일: application-core/.../IdempotencyExecutor.java, ca-tmpl @f6fbd4e196b4
|
||||
public final class IdempotencyExecutor {
|
||||
public static final Duration IN_FLIGHT_WAIT = Duration.ofMillis(200);
|
||||
public static final Duration MAX_TTL = Duration.ofHours(72);
|
||||
|
||||
public <R> R execute(
|
||||
IdempotencyContext context, Supplier<R> action, IdempotentResponseCodec<R> codec) {
|
||||
// claim -> fingerprint mismatch -> replay -> in-flight wait -> 409
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```java
|
||||
// 출처: [[wiki/projects/ca-tmpl/idempotency-key-design]]
|
||||
// 실제 파일: application-core/.../IdempotencyExecutor.java
|
||||
if (!record.fingerprint().equals(fingerprint)) {
|
||||
throw new IdempotencyRequestMismatchException(scope);
|
||||
}
|
||||
if (record.status() == IdempotencyStatus.COMPLETED) {
|
||||
return codec.deserialize(record.response().payload());
|
||||
}
|
||||
if (!now.isBefore(deadline)) {
|
||||
throw new IdempotencyInFlightException(scope);
|
||||
}
|
||||
```
|
||||
|
||||
```sql
|
||||
-- 출처: [[wiki/projects/ca-tmpl/idempotency-key-design]]
|
||||
-- 실제 파일: adapter-persistence-postgresql/.../V1__idempotency_record.sql
|
||||
CREATE TABLE idempotency_record (
|
||||
id uuid NOT NULL,
|
||||
tenant varchar(128) NOT NULL DEFAULT '',
|
||||
principal varchar(256) NOT NULL,
|
||||
idempotency_key varchar(256) NOT NULL,
|
||||
use_case_name varchar(256) NOT NULL,
|
||||
request_hash char(64) NOT NULL,
|
||||
status varchar(16) NOT NULL,
|
||||
response_payload text NULL,
|
||||
expires_at timestamptz NOT NULL,
|
||||
CONSTRAINT uq_idempotency_scope
|
||||
UNIQUE (tenant, principal, idempotency_key, use_case_name)
|
||||
);
|
||||
```
|
||||
|
||||
## Sources / 근거 (canonical 인용 필수, derived layer 의무)
|
||||
|
||||
- [[wiki/projects/ca-tmpl/idempotency-key-design]] — 이 글의 1차 canonical. triple scope, 24h TTL, 200ms wait, 409/422 mapping, 구현/로컬 검증 범위와 과장 금지 경계를 따른다.
|
||||
- [[wiki/concepts/idempotency-key-design]] — 관련 개념 문서. 구현 사실 출처로 쓰지 않는다.
|
||||
|
||||
## 사실 vs 의견 / Fact vs opinion 구분
|
||||
|
||||
- 사실: ca-tmpl에는 `IdempotencyExecutor`, `IdempotencyStorePort`, `IdempotencyScope`, `RequestFingerprint`, web helper/codec, RDBMS store, PostgreSQL unique scope migration이 존재한다. 근거: [[wiki/projects/ca-tmpl/idempotency-key-design]]
|
||||
- 사실: `./gradlew check`, executor/store/web mapping/unique scope contract test가 로컬 검증 범위에 포함된다. 근거: [[wiki/projects/ca-tmpl/idempotency-key-design]]
|
||||
- 사실: 운영 배포, duplicate suppression metric, 200ms wait 부하 튜닝은 없다. 근거: [[wiki/projects/ca-tmpl/idempotency-key-design]]
|
||||
- 의견: idempotency는 API header보다 application execution contract로 설명할 때 설계가 더 잘 보인다.
|
||||
- 알지 못하는 것: 운영 retry traffic에서 replay/in-flight/mismatch 비율이 어떻게 나오는지.
|
||||
|
||||
## 답할 수 있는 범위 / Answer boundary
|
||||
|
||||
- 자신 있게 답할 수 있는 후속 질문:
|
||||
- replay, in-flight, mismatch를 왜 나눴는가?
|
||||
- triple scope에 `useCaseName`을 넣은 이유는 무엇인가?
|
||||
- 같은 key + 다른 body를 왜 `422`로 보는가?
|
||||
- DB table unique constraint가 idempotency executor와 어떻게 맞물리는가?
|
||||
- 다음 글로 넘길 부분:
|
||||
- 운영 duplicate suppression metric.
|
||||
- multi-node production race 부하 테스트.
|
||||
- long-term retention policy와 비용 모델.
|
||||
|
||||
## 게시 체크리스트 / Publish checklist
|
||||
|
||||
- [x] 모든 사실 주장에 canonical 링크 있음
|
||||
- [x] 사실 vs 의견 분리 명시됨
|
||||
- [x] 금지 마케팅 표현 없음
|
||||
- [x] 코드 예제 출처 명시
|
||||
- [x] 타깃 독자 가정과 톤 일치
|
||||
- [x] `/lint` 통과
|
||||
- [ ] 게시 URL 기록 (게시 후):
|
||||
|
||||
## Related / 관련
|
||||
|
||||
- 후속 글 후보: [[wiki/blog/ca-tmpl-api-evolution-and-schema-2026-07-02]]
|
||||
@@ -1 +0,0 @@
|
||||
../../vault/40-publish/blog/ca-tmpl-knowledge-capture-workflow-2026-07-02.md
|
||||
@@ -0,0 +1,121 @@
|
||||
---
|
||||
title: 구현 후 지식을 다시 Wiki로 회수하기
|
||||
source_type: blog
|
||||
status: verified
|
||||
confidence: medium
|
||||
tags: [blog, ca-tmpl, workflow, documentation]
|
||||
related_projects: [ca-tmpl]
|
||||
last_reviewed: 2026-07-03
|
||||
canonical_sources:
|
||||
- wiki/projects/ca-tmpl/knowledge-capture-workflow
|
||||
audience: backend-engineer
|
||||
target_publish:
|
||||
status_label: ready
|
||||
---
|
||||
|
||||
# 구현 후 지식을 다시 Wiki로 회수하기
|
||||
|
||||
## Parent / 부모 (필수)
|
||||
|
||||
- 핵심 canonical: [[wiki/projects/ca-tmpl/knowledge-capture-workflow]]
|
||||
- 관련 개념 문서: [[wiki/concepts/clean-architecture-package-layout]] - ca-tmpl 문서 구조와 project/concept 분리의 배경으로만 참고한다.
|
||||
|
||||
## 타깃 독자 / Target reader
|
||||
|
||||
- 독자 profile: 구현 과정에서 생긴 결정을 branch note, wiki, blog로 회수하고 싶은 개발자.
|
||||
- 이미 안다고 가정하는 것: branch note, project note, blog draft, wiki 문서화.
|
||||
- 처음 듣는다고 가정하는 것: raw 증거, canonical 문서, derived 산출물을 분리해서 학습 루프를 만드는 방식.
|
||||
|
||||
## 도입 / Hook
|
||||
|
||||
구현이 끝난 뒤 가장 빨리 사라지는 것은 코드가 아닙니다. 코드는 repository에 남습니다. 사라지는 것은 “왜 이 선택을 했는가”, “어떤 대안을 버렸는가”, “어디까지 검증했고 어디부터는 추측인가” 같은 맥락입니다. 이 맥락은 채팅 로그, branch note, 테스트 실패, 작은 TODO 사이에 흩어지기 쉽습니다.
|
||||
|
||||
ca-tmpl의 knowledge capture workflow는 이 문제를 줄이기 위한 문서화 규칙입니다. raw 자료를 증거로 보관하고, `wiki/projects`와 `wiki/concepts`를 canonical로 정리한 뒤, blog/interview/portfolio 같은 derived 산출물을 canonical에서만 만듭니다. 이 글은 애플리케이션 기능이 아니라 작업 종료 조건으로서의 지식 회수 구조를 설명합니다.
|
||||
|
||||
## 본문 outline / Body outline
|
||||
|
||||
1. 구현 후 사라지는 것은 코드가 아니라 결정 맥락이다.
|
||||
2. raw, canonical, derived를 섞지 않는다.
|
||||
3. branch-note와 blog-topic은 증거이고 project 문서는 설명 가능한 결정이다.
|
||||
4. blogify는 raw가 아니라 verified canonical에서 시작한다.
|
||||
5. 이 workflow는 자동화가 아니라 documentation rule이다.
|
||||
|
||||
## 본문 / Body
|
||||
|
||||
개발자가 나중에 다시 공부하기 어려운 이유는 “기록이 없어서”만은 아닙니다. 기록은 많습니다. branch note도 있고, daily note도 있고, 테스트 로그도 있고, raw blog-topic도 있습니다. 문제는 그 기록들이 서로 다른 신뢰도를 갖는다는 점입니다. 구현 중 적은 메모와 코드 대조를 마친 project canonical, 그리고 외부에 내보낼 블로그 초안은 같은 레이어가 아닙니다.
|
||||
|
||||
ca-tmpl workflow의 첫 원칙은 raw를 증거로 두는 것입니다. branch-note, daily-note, error note, blog-topic은 생각의 흔적과 구현 증거를 보관합니다. 여기에는 미확정 판단, 실패한 시도, 나중에 다듬을 글감이 들어갈 수 있습니다. raw는 귀중하지만 그대로 블로그가 되지는 않습니다.
|
||||
|
||||
두 번째 레이어는 canonical입니다. `wiki/projects/`는 내 프로젝트에서 실제로 구현됐거나 로컬 검증된 결정을 정리합니다. `wiki/concepts/`는 특정 프로젝트를 떠난 일반 개념과 trade-off를 정리합니다. ca-tmpl의 20개 project 문서가 중요한 이유도 여기에 있습니다. 여러 branch-note에 흩어진 결정을 주제별로 합치고, 구현 범위와 미검증 범위를 분리해서 “내가 설명할 수 있는 지식”으로 바꾸기 때문입니다.
|
||||
|
||||
세 번째 레이어가 derived 산출물입니다. blog, interview, portfolio는 canonical에서 파생됩니다. raw branch-note에서 바로 blog를 만들지 않는 이유는 간단합니다. raw에는 사실, 추측, 계획, 감정, 작업 중간 판단이 섞입니다. canonical을 거치면 “실제로 코드가 있는가”, “로컬에서 검증됐는가”, “prod 검증은 없는가”, “planned를 구현처럼 말하고 있지 않은가”를 먼저 정리할 수 있습니다.
|
||||
|
||||
이번 ca-tmpl 블로그 작업도 같은 흐름입니다. raw/blog-topics 59개는 글감 원석이었고, ingest를 통해 project canonical에 반영됐습니다. 그 뒤 `blogify`는 `wiki/projects/ca-tmpl/*.md`에서 시작했습니다. 그래서 블로그 20개는 branch-note 50여 개를 1:1로 그대로 옮긴 것이 아니라, 프로젝트 결정 주제 20개로 녹인 뒤 다시 읽을 수 있는 글로 풀어내는 구조입니다.
|
||||
|
||||
이 workflow의 장점은 학습 경로가 보인다는 점입니다. 어떤 글을 쓰다가 근거가 약하면 raw로 돌아가는 것이 아니라 canonical을 먼저 고칩니다. canonical이 draft라면 verified로 올릴 근거를 대조합니다. blog에 쓸 수 없는 planned 항목은 planned라고 표시합니다. 이렇게 하면 글쓰기 자체가 복습이 됩니다. 단순히 문장을 만드는 것이 아니라, 내가 어디까지 알고 어디부터 모르는지 나누는 과정이기 때문입니다.
|
||||
|
||||
다만 이 글은 높은 자동화를 주장하지 않습니다. canonical에 따르면 이 workflow는 runtime 기능이 아니고, git hook이나 CI로 강제되는 구조도 아닙니다. 일부 branch에서 branch-note 갱신과 derived raw note 생성이 실제로 수행됐고, raw/blog-topics 59개 ingest batch가 적용 사례로 남아 있을 뿐입니다. 따라서 confidence도 `medium`으로 둡니다. 문서화 규칙으로는 검증됐지만, 자동 강제 장치가 있는 것은 아닙니다.
|
||||
|
||||
결론적으로 knowledge capture는 ca-tmpl의 코드 기능이 아니라 학습과 설명을 위한 작업 방식입니다. 구현이 끝난 뒤 branch-note를 닫고, raw 글감을 canonical에 반영하고, verified project 문서에서 blog를 파생합니다. 이 구조를 따르면 “왜 그렇게 결정했는지”를 나중에 다시 따라갈 수 있습니다. 그게 이 블로그 묶음의 진짜 목적입니다.
|
||||
|
||||
## 코드 예제 / Code samples (있다면)
|
||||
|
||||
이 글은 runtime code를 설명하는 글이 아니므로 애플리케이션 코드 예제는 두지 않는다. 대신 실제 workflow는 아래 흐름으로 읽는다.
|
||||
|
||||
```text
|
||||
# 출처: [[wiki/projects/ca-tmpl/knowledge-capture-workflow]]
|
||||
raw/branch-notes + raw/blog-topics
|
||||
-> wiki/projects 또는 wiki/concepts canonical
|
||||
-> wiki/blog, wiki/interview, wiki/portfolio derived output
|
||||
```
|
||||
|
||||
```text
|
||||
# 출처: [[wiki/projects/ca-tmpl/knowledge-capture-workflow]]
|
||||
blogify 입력으로 적합한 것:
|
||||
wiki/projects/ca-tmpl/<verified-project-canonical>.md
|
||||
wiki/concepts/<reviewed-or-verified-concept>.md
|
||||
|
||||
blogify 입력으로 피해야 하는 것:
|
||||
raw/branch-notes/<branch-note>.md
|
||||
raw/blog-topics/<topic-seed>.md
|
||||
```
|
||||
|
||||
## Sources / 근거 (canonical 인용 필수, derived layer 의무)
|
||||
|
||||
- [[wiki/projects/ca-tmpl/knowledge-capture-workflow]] - 이 글의 1차 canonical. runtime 구현 없음, documentation workflow, partial local 사례, 자동 강제 부재, confidence medium 경계를 따른다.
|
||||
- [[wiki/concepts/clean-architecture-package-layout]] - 관련 개념 문서. ca-tmpl 문서 구조와 project/concept 분리 배경으로만 둔다.
|
||||
|
||||
## 사실 vs 의견 / Fact vs opinion 구분
|
||||
|
||||
- 사실: 이 문서가 다루는 것은 runtime 기능이나 애플리케이션 코드가 아니라 workflow rule과 문서화 결정이다. 근거: [[wiki/projects/ca-tmpl/knowledge-capture-workflow]]
|
||||
- 사실: 일부 branch에서 branch-note 갱신과 derived raw note 생성이 수행됐고, raw/blog-topics 59개 ingest batch가 raw에서 canonical로 승격된 사례로 기록되어 있다. 근거: [[wiki/projects/ca-tmpl/knowledge-capture-workflow]]
|
||||
- 사실: git hook/CI enforcement는 없고 agent workflow rule에 의존한다. 근거: [[wiki/projects/ca-tmpl/knowledge-capture-workflow]]
|
||||
- 의견: 블로그 작성은 문장 생산보다 canonical을 다시 검증하는 학습 루프로 볼 때 더 효과적이다.
|
||||
- 알지 못하는 것: 장기적으로 회고 품질, 면접 성과, 외부 글 반응이 얼마나 좋아지는지.
|
||||
|
||||
## 답할 수 있는 범위 / Answer boundary
|
||||
|
||||
- 자신 있게 답할 수 있는 후속 질문:
|
||||
- 왜 raw에서 바로 blog를 만들지 않는가?
|
||||
- branch-note와 project canonical의 역할은 어떻게 다른가?
|
||||
- ca-tmpl 20개 project blog가 branch-note 묶음을 어떻게 학습 가능한 구조로 바꾸는가?
|
||||
- 다음 글로 넘길 부분:
|
||||
- git hook/CI 기반 documentation gate.
|
||||
- 자동 품질 검사 확장.
|
||||
- 블로그 게시 후 독자 반응이나 회고 효과 측정.
|
||||
|
||||
## 게시 체크리스트 / Publish checklist
|
||||
|
||||
- [x] 모든 사실 주장에 canonical 링크 있음
|
||||
- [x] 사실 vs 의견 분리 명시됨
|
||||
- [x] 금지 마케팅 표현 없음
|
||||
- [x] 코드 예제 출처 명시
|
||||
- [x] 타깃 독자 가정과 톤 일치
|
||||
- [x] `/lint` 통과
|
||||
- [ ] 게시 URL 기록 (게시 후):
|
||||
|
||||
## Related / 관련
|
||||
|
||||
- 후속 글 후보: [[wiki/blog/ca-tmpl-skeleton-governance-registry-verification-test-scorecard-2026-07-02]]
|
||||
- 후속 글 후보: [[wiki/blog/ca-tmpl-api-error-envelope-design-2026-07-02]]
|
||||
- 후속 글 후보: [[wiki/blog/ca-tmpl-api-evolution-and-schema-2026-07-02]]
|
||||
@@ -1 +0,0 @@
|
||||
../../vault/40-publish/blog/ca-tmpl-multi-tenancy-isolation-patterns-2026-07-02.md
|
||||
@@ -0,0 +1,146 @@
|
||||
---
|
||||
title: Multi-tenancy를 기본값이 아니라 Opt-in 계약으로 두기
|
||||
source_type: blog
|
||||
status: verified
|
||||
confidence: high
|
||||
tags: [blog, ca-tmpl, multi-tenancy, saas]
|
||||
related_projects: [ca-tmpl]
|
||||
last_reviewed: 2026-07-03
|
||||
canonical_sources:
|
||||
- wiki/projects/ca-tmpl/multi-tenancy-isolation-patterns
|
||||
audience: backend-engineer
|
||||
target_publish:
|
||||
status_label: ready
|
||||
---
|
||||
|
||||
# Multi-tenancy를 기본값이 아니라 Opt-in 계약으로 두기
|
||||
|
||||
## Parent / 부모 (필수)
|
||||
|
||||
- 핵심 canonical: [[wiki/projects/ca-tmpl/multi-tenancy-isolation-patterns]]
|
||||
- 관련 개념 문서: [[wiki/concepts/multi-tenancy-isolation-patterns]] - Pool/Silo/Bridge와 Hibernate multi-tenancy 전략의 일반 배경. 현재 이 글의 구현 사실 근거는 verified project canonical에 둔다.
|
||||
|
||||
## 타깃 독자 / Target reader
|
||||
|
||||
- 독자 profile: SaaS skeleton에서 tenant isolation을 어디까지 기본 제공할지 고민하는 백엔드 엔지니어.
|
||||
- 이미 안다고 가정하는 것: `tenant_id`, shared DB, schema-per-tenant.
|
||||
- 처음 듣는다고 가정하는 것: multi-tenancy를 default feature가 아니라 opt-in guardrail과 migration trigger로 다루는 방식.
|
||||
|
||||
## 도입 / Hook
|
||||
|
||||
Multi-tenancy는 SaaS에서 중요하지만, skeleton에 처음부터 강하게 박아 넣기 어렵습니다. 모든 query에 tenant predicate를 강제하고, tenant resolver filter를 만들고, admin tenant switching을 열고, schema-per-tenant까지 고려하면 single-tenant 서비스에도 비용이 따라옵니다. 반대로 아무 계약도 없으면 나중에 tenant를 얹을 때 권한, idempotency, logging, repository 경계가 한꺼번에 흔들립니다.
|
||||
|
||||
ca-tmpl은 이 사이에서 opt-in 방향을 택했습니다. 기본은 `APP_TENANT_ENABLED=false`이고, shared DB + `tenant_id` 방향을 문서화하되 현재 구현은 registry, capability, idempotency scope, runbook stub 같은 foundation에 머뭅니다. repository-level tenant filter와 cross-tenant E2E isolation은 아직 planned입니다. 이 글은 multi-tenancy를 “완성했다”고 말하지 않고, 어디까지 foundation을 깔았는지 정리합니다.
|
||||
|
||||
## 본문 outline / Body outline
|
||||
|
||||
1. multi-tenancy를 skeleton 기본값으로 강제하지 않는 이유.
|
||||
2. shared DB + `tenant_id`와 schema/db-per-tenant의 trade-off.
|
||||
3. 현재 구현된 registry/capability/idempotency foundation.
|
||||
4. 아직 없는 tenant resolver와 repository filter.
|
||||
5. migration trigger와 운영 검증 없음.
|
||||
|
||||
## 본문 / Body
|
||||
|
||||
Multi-tenancy의 첫 갈림길은 격리 수준입니다. 모든 tenant를 같은 DB와 table에 두고 `tenant_id` column으로 나누는 방식은 운영이 단순합니다. 반면 schema-per-tenant나 db-per-tenant는 isolation은 강하지만 migration, backup, connection pool, monitoring 비용이 빠르게 늘어납니다. ca-tmpl은 B2B 초기 단계, tenant 수 수십에서 수백 정도의 가정을 두고 shared DB + `tenant_id`를 baseline 후보로 잡았습니다.
|
||||
|
||||
하지만 이 선택은 “항상 shared DB가 낫다”는 뜻이 아닙니다. 규제 산업, data residency 요구, enterprise tier처럼 격리를 상품 가치로 팔아야 하는 경우에는 schema나 DB를 나누는 쪽이 맞을 수 있습니다. 그래서 ca-tmpl canonical은 migration trigger도 함께 기록합니다. 규제 요구, tenant 수와 row 수 증가, enterprise tier 등장 같은 조건이 생기면 Pool 모델에서 더 강한 isolation으로 넘어갈 수 있다는 판단입니다.
|
||||
|
||||
현재 코드로 구현된 것은 storage isolation 전체가 아니라 foundation입니다. env registry에는 `APP_TENANT_ENABLED`가 있고, header registry에는 `X-Tenant-Id`가 있습니다. capability registry에는 `CROSS_TENANT_ADMIN`이 존재합니다. error-code registry에는 tenant 미지원 상태에서 tenant header가 들어왔을 때의 `TENANT_NOT_SUPPORTED`가 정의되어 있고, cross-tenant mismatch runbook stub도 있습니다.
|
||||
|
||||
application layer에도 일부 표현이 있습니다. `UseCaseCapability`에는 `crossTenantAdmin` flag가 있습니다. 이것은 tenant 경계를 넘는 admin use case가 명시적으로 선언해야 하는 capability입니다. idempotency 쪽에는 `IdempotencyScope`가 single-tenant triple뿐 아니라 tenant를 앞에 둔 4-tuple을 표현할 수 있습니다. tenant가 활성화되면 idempotency key 충돌도 tenant boundary 안에서 해석되어야 하기 때문입니다.
|
||||
|
||||
다만 중요한 enforcement가 아직 없습니다. request에서 tenant를 해석하는 tenant resolver filter는 구현됐다고 말할 수 없습니다. repository 진입점에서 `tenant_id` predicate를 강제하는 rule도 아직 planned입니다. `CROSS_TENANT_ADMIN`을 가진 admin만 `X-Tenant-Id` header로 tenant switching을 할 수 있다는 정책은 문서/registry 수준에 가깝고, E2E isolation으로 검증된 상태는 아닙니다.
|
||||
|
||||
이 경계가 이 글의 핵심입니다. ca-tmpl은 multi-tenancy를 처음부터 모든 서비스에 강제하지 않습니다. 대신 나중에 tenant를 열 때 필요한 vocabulary와 일부 cross-cutting surface를 미리 잡아 둡니다. header, env key, capability, idempotency scope, runbook link가 그 foundation입니다. 반면 실제 data isolation은 repository filter와 E2E test가 들어와야 닫힙니다.
|
||||
|
||||
따라서 면접이나 블로그에서 말할 때도 “multi-tenancy를 구현했다”보다 “multi-tenancy를 opt-in으로 열 수 있게 foundation을 만들었고, storage isolation enforcement는 planned로 남겼다”가 정확합니다. 이 차이를 숨기지 않는 것이 오히려 설계 이해를 더 잘 보여줍니다.
|
||||
|
||||
## 코드 예제 / Code samples (있다면)
|
||||
|
||||
```yaml
|
||||
# 출처: [[wiki/projects/ca-tmpl/multi-tenancy-isolation-patterns]]
|
||||
# 실제 파일: docs/registries/env-keys.yaml, ca-tmpl @f6fbd4e196b4
|
||||
- name: APP_TENANT_ENABLED
|
||||
type: boolean
|
||||
default: false
|
||||
allowed_values: [true, false]
|
||||
reload_policy: restart-only
|
||||
owner_branch: feature-tenant-context-policy
|
||||
```
|
||||
|
||||
```yaml
|
||||
# 출처: [[wiki/projects/ca-tmpl/multi-tenancy-isolation-patterns]]
|
||||
# 실제 파일: docs/registries/capabilities.yaml, ca-tmpl @f6fbd4e196b4
|
||||
- name: CROSS_TENANT_ADMIN
|
||||
scope: use_case_method
|
||||
enforcement: archunit
|
||||
annotation: "@UseCaseCapability(crossTenantAdmin = true)"
|
||||
```
|
||||
|
||||
```java
|
||||
// 출처: [[wiki/projects/ca-tmpl/multi-tenancy-isolation-patterns]]
|
||||
// 실제 파일: application-core/.../UseCaseCapability.java, ca-tmpl @f6fbd4e196b4
|
||||
public @interface UseCaseCapability {
|
||||
TransactionMode transactionMode();
|
||||
Idempotency idempotency();
|
||||
RepositoryAccess repositoryAccess();
|
||||
boolean crossTenantAdmin() default false;
|
||||
}
|
||||
```
|
||||
|
||||
```java
|
||||
// 출처: [[wiki/projects/ca-tmpl/multi-tenancy-isolation-patterns]]
|
||||
// 실제 파일: application-core/.../IdempotencyScope.java, ca-tmpl @f6fbd4e196b4
|
||||
public record IdempotencyScope(
|
||||
String tenant, String principal, String idempotencyKey, String useCaseName) {
|
||||
|
||||
public static IdempotencyScope of(
|
||||
String tenant, String principal, String idempotencyKey, String useCaseName) {
|
||||
requirePresent("principal", principal);
|
||||
requirePresent("idempotencyKey", idempotencyKey);
|
||||
requirePresent("useCaseName", useCaseName);
|
||||
String normalizedTenant = (tenant == null || tenant.isBlank()) ? null : tenant;
|
||||
return new IdempotencyScope(normalizedTenant, principal, idempotencyKey, useCaseName);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Sources / 근거 (canonical 인용 필수, derived layer 의무)
|
||||
|
||||
- [[wiki/projects/ca-tmpl/multi-tenancy-isolation-patterns]] - 이 글의 1차 canonical. opt-in policy, shared DB + `tenant_id`, registry/capability/idempotency foundation, planned repository filter, 운영 미검증 경계를 따른다.
|
||||
- [[wiki/concepts/multi-tenancy-isolation-patterns]] - 관련 개념 문서. Pool/Silo/Bridge와 Hibernate strategy의 일반 비교 배경으로만 둔다.
|
||||
|
||||
## 사실 vs 의견 / Fact vs opinion 구분
|
||||
|
||||
- 사실: ca-tmpl에는 `APP_TENANT_ENABLED`, `X-Tenant-Id`, `CROSS_TENANT_ADMIN`, tenant 관련 error code/runbook stub, `UseCaseCapability.crossTenantAdmin`, tenant-aware `IdempotencyScope`가 존재한다. 근거: [[wiki/projects/ca-tmpl/multi-tenancy-isolation-patterns]]
|
||||
- 사실: repository-level tenant predicate 강제, tenant resolver filter, cross-tenant E2E isolation은 구현/검증됐다고 말하지 않는다. 근거: [[wiki/projects/ca-tmpl/multi-tenancy-isolation-patterns]]
|
||||
- 사실: 운영 배포, tenant isolation audit, penetration test 결과는 없다. 근거: [[wiki/projects/ca-tmpl/multi-tenancy-isolation-patterns]]
|
||||
- 의견: ca-tmpl 같은 skeleton에서는 multi-tenancy를 default feature가 아니라 opt-in foundation으로 두는 편이 적용 범위를 넓힌다.
|
||||
- 알지 못하는 것: 실제 tenant 수, row 수, noisy neighbor metric, schema/db-per-tenant migration 경험.
|
||||
|
||||
## 답할 수 있는 범위 / Answer boundary
|
||||
|
||||
- 자신 있게 답할 수 있는 후속 질문:
|
||||
- 왜 schema-per-tenant를 skeleton 기본값으로 두지 않았는가?
|
||||
- `X-Tenant-Id` header를 왜 admin only로 제한해야 하는가?
|
||||
- idempotency scope에 tenant dimension이 왜 필요한가?
|
||||
- 다음 글로 넘길 부분:
|
||||
- tenant resolver filter 구현.
|
||||
- repository-level `tenant_id` predicate 강제.
|
||||
- cross-tenant E2E isolation과 audit evidence.
|
||||
|
||||
## 게시 체크리스트 / Publish checklist
|
||||
|
||||
- [x] 모든 사실 주장에 canonical 링크 있음
|
||||
- [x] 사실 vs 의견 분리 명시됨
|
||||
- [x] 금지 마케팅 표현 없음
|
||||
- [x] 코드 예제 출처 명시
|
||||
- [x] 타깃 독자 가정과 톤 일치
|
||||
- [x] `/lint` 통과
|
||||
- [ ] 게시 URL 기록 (게시 후):
|
||||
|
||||
## Related / 관련
|
||||
|
||||
- 후속 글 후보: [[wiki/blog/ca-tmpl-security-baseline-jwt-actuator-secrets-2026-07-02]]
|
||||
- 후속 글 후보: [[wiki/blog/ca-tmpl-idempotency-key-design-2026-07-02]]
|
||||
@@ -1 +0,0 @@
|
||||
../../vault/40-publish/blog/ca-tmpl-observability-log-metric-trace-runbook-2026-07-02.md
|
||||
@@ -0,0 +1,165 @@
|
||||
---
|
||||
title: Observability를 로그 한 줄이 아니라 운영 계약으로 보기
|
||||
source_type: blog
|
||||
status: verified
|
||||
confidence: high
|
||||
tags: [blog, ca-tmpl, observability, logging, metrics, tracing]
|
||||
related_projects: [ca-tmpl]
|
||||
last_reviewed: 2026-07-03
|
||||
canonical_sources:
|
||||
- wiki/projects/ca-tmpl/observability-log-metric-trace-runbook
|
||||
audience: backend-engineer
|
||||
target_publish:
|
||||
status_label: ready
|
||||
---
|
||||
|
||||
# Observability를 로그 한 줄이 아니라 운영 계약으로 보기
|
||||
|
||||
## Parent / 부모 (필수)
|
||||
|
||||
- 핵심 canonical: [[wiki/projects/ca-tmpl/observability-log-metric-trace-runbook]]
|
||||
- 관련 개념 문서: [[wiki/concepts/observability-log-metric-trace-runbook]] - 일반 observability 개념. 현재 이 글의 구현 사실 근거는 verified project canonical에 둔다.
|
||||
|
||||
## 타깃 독자 / Target reader
|
||||
|
||||
- 독자 profile: skeleton에 log/metric/trace/runbook baseline을 넣고 싶은 백엔드 엔지니어.
|
||||
- 이미 안다고 가정하는 것: MDC, Micrometer, trace id, runbook.
|
||||
- 처음 듣는다고 가정하는 것: 관측 가능성을 응답 `meta`, 로그 MDC, trace context, runbook의 연결 계약으로 보는 관점.
|
||||
|
||||
## 도입 / Hook
|
||||
|
||||
로그가 많다고 장애 대응이 쉬워지는 것은 아닙니다. 요청 id가 응답에는 있는데 로그에는 없거나, 로그에는 trace id가 있는데 client가 받은 error envelope에는 없거나, metric alert는 울렸는데 어떤 runbook을 봐야 하는지 연결되지 않으면 관측 데이터는 흩어진 조각이 됩니다.
|
||||
|
||||
ca-tmpl은 observability를 “로그 한 줄 찍기”가 아니라 연결 가능한 계약으로 다루려 했습니다. request id, trace id, correlation id를 MDC에 올리고, 응답 envelope의 `meta`에도 투영하며, inbound header는 sanitize하고, user principal은 pseudonymize해서 로그에 싣는 식입니다. 다만 project canonical 기준으로 전체 log/metric/trace/runbook 체계가 모두 구현된 것은 아닙니다. 이 글은 구현된 foundation slice와 아직 planned/documented-only인 부분을 나눠서 정리합니다.
|
||||
|
||||
## 본문 outline / Body outline
|
||||
|
||||
1. observability는 출력 포맷이 아니라 join 가능성이다.
|
||||
2. requestId/traceId/correlationId와 envelope meta.
|
||||
3. MDC key, header sanitizer, request logging filter.
|
||||
4. logback JSON/MDC include와 masking/sampling의 구현 범위.
|
||||
5. metric/trace/runbook 중 구현된 범위와 planned 범위.
|
||||
6. 운영 장애 대응 효과와 alert tuning 검증은 없음.
|
||||
|
||||
## 본문 / Body
|
||||
|
||||
장애 상황에서 가장 먼저 필요한 것은 “이 응답이 어떤 로그와 이어지는가”입니다. client가 받은 실패 응답에 `requestId`와 `traceId`가 있어도, 서버 로그에 같은 key가 없으면 검색이 끊깁니다. 반대로 로그에만 trace id가 있고 응답에는 없으면 client 문의에서 출발해 서버 이벤트로 들어가기 어렵습니다. ca-tmpl의 observability foundation은 이 연결을 기본 계약으로 둡니다.
|
||||
|
||||
구현의 중심에는 MDC key가 있습니다. `MdcKeys`는 `request_id`, `trace_id`, `span_id`, `correlation_id`, `user_principal`을 snake_case로 정의합니다. `RequestLoggingFilter`는 inbound `X-Request-Id`, `X-Correlation-Id`, `traceparent`를 읽고, 없거나 유효하지 않으면 서버에서 생성합니다. 값은 MDC에 들어가고 response header에도 다시 설정됩니다. 그래서 request 처리 중 남는 로그와 client가 받은 header가 같은 id로 이어질 수 있습니다.
|
||||
|
||||
`ResponseMetaFactory`는 이 MDC 값을 API envelope의 `meta`로 투영합니다. 로그에서는 snake_case key를 쓰지만, JSON wire format은 `requestId`, `traceId`, `correlationId` camelCase record입니다. 이 작은 변환이 중요합니다. 로그의 key naming과 API contract naming을 억지로 같게 만들지 않고, 각 영역의 규칙을 유지한 채 mapping 지점을 명확히 둔 것입니다.
|
||||
|
||||
header는 그대로 믿지 않습니다. `HeaderSanitizer`는 inbound header value에서 `\r`, `\n`, ASCII control char를 제거하고 길이를 제한합니다. request id나 correlation id는 로그/MDC에 들어가므로 log injection을 피해야 합니다. `RequestLoggingFilter`는 user principal도 raw id를 MDC에 넣지 않고 `UserPrincipalPseudonymizerPort`를 거쳐 pseudonymized value만 싣습니다. 즉 “관측 가능하게 남긴다”와 “민감 정보를 그대로 남긴다”를 구분합니다.
|
||||
|
||||
logback 설정도 이 계약을 받쳐줍니다. local/dev는 사람이 읽기 쉬운 pattern layout을 쓰고, 그 외 profile은 structured JSON encoder에 MDC key를 포함합니다. 설정에는 `trace_id`, `span_id`, `request_id`, `correlation_id`, `user_principal` include가 명시되어 있습니다. 또한 masking converter/decorator와 sampling turbo filter, async appender 설정도 존재합니다. 다만 이 글에서 말할 수 있는 것은 코드와 local verification 범위입니다. production log pipeline에서의 실제 누락률이나 비용 절감 효과는 검증된 주장이 아닙니다.
|
||||
|
||||
traceparent 처리도 선을 분명히 해야 합니다. 현재 `RequestLoggingFilter`는 inbound W3C `traceparent`가 유효하면 채택하고, 없으면 fresh ROOT traceparent를 생성합니다. 이것은 trace id를 응답/log에 연결하기 위한 foundation입니다. 하지만 실제 distributed tracer가 붙어 span tree를 export하고, 5xx span을 ERROR로 기록하고, trace backend에서 검색된다는 주장까지는 별도 구현/운영 검증이 필요합니다.
|
||||
|
||||
metric과 runbook도 마찬가지입니다. project canonical에는 log/metric/trace/runbook을 하나의 운영 계약으로 보는 방향이 있지만, 모든 항목이 같은 증거 등급은 아닙니다. 구현된 foundation은 MDC/header/meta/logback 중심입니다. Prometheus alert, alert tuning, runbook link-check와 실제 incident response 효과는 documented-only 또는 planned 범위로 남아 있습니다. 따라서 이 글의 결론은 “운영 관측성이 완성됐다”가 아니라 “ca-tmpl은 응답 meta와 로그 context를 연결하는 관측성 foundation을 구현했다”입니다.
|
||||
|
||||
## 코드 예제 / Code samples (있다면)
|
||||
|
||||
```java
|
||||
// 출처: [[wiki/projects/ca-tmpl/observability-log-metric-trace-runbook]]
|
||||
// 실제 파일: adapter-web/.../MdcKeys.java, ca-tmpl @f6fbd4e196b4
|
||||
public final class MdcKeys {
|
||||
public static final String REQUEST_ID = "request_id";
|
||||
public static final String TRACE_ID = "trace_id";
|
||||
public static final String SPAN_ID = "span_id";
|
||||
public static final String CORRELATION_ID = "correlation_id";
|
||||
public static final String USER_PRINCIPAL = "user_principal";
|
||||
}
|
||||
```
|
||||
|
||||
```java
|
||||
// 출처: [[wiki/projects/ca-tmpl/observability-log-metric-trace-runbook]]
|
||||
// 실제 파일: adapter-web/.../RequestLoggingFilter.java, ca-tmpl @f6fbd4e196b4
|
||||
String requestId = resolveOrGenerate(req.getHeader("X-Request-Id"));
|
||||
String correlationId = resolveOrGenerate(req.getHeader("X-Correlation-Id"));
|
||||
res.setHeader("X-Request-Id", requestId);
|
||||
res.setHeader("X-Correlation-Id", correlationId);
|
||||
|
||||
MDC.put(MdcKeys.REQUEST_ID, requestId);
|
||||
MDC.put(MdcKeys.CORRELATION_ID, correlationId);
|
||||
|
||||
TraceParent traceParent = resolveOrGenerateTraceParent(req.getHeader("traceparent"));
|
||||
MDC.put(MdcKeys.TRACE_ID, traceParent.traceId());
|
||||
MDC.put(MdcKeys.SPAN_ID, traceParent.spanId());
|
||||
res.setHeader("traceparent", traceParent.toHeader());
|
||||
```
|
||||
|
||||
```java
|
||||
// 출처: [[wiki/projects/ca-tmpl/observability-log-metric-trace-runbook]]
|
||||
// 실제 파일: adapter-web/.../HeaderSanitizer.java, ca-tmpl @f6fbd4e196b4
|
||||
public static String sanitize(String raw, int maxLength) {
|
||||
if (raw == null) {
|
||||
return null;
|
||||
}
|
||||
StringBuilder sb = new StringBuilder(Math.min(raw.length(), maxLength));
|
||||
for (int i = 0; i < raw.length() && sb.length() < maxLength; i++) {
|
||||
char c = raw.charAt(i);
|
||||
if (c >= 0x20) {
|
||||
sb.append(c);
|
||||
}
|
||||
}
|
||||
return sb.toString();
|
||||
}
|
||||
```
|
||||
|
||||
```java
|
||||
// 출처: [[wiki/projects/ca-tmpl/observability-log-metric-trace-runbook]]
|
||||
// 실제 파일: adapter-web/.../ResponseMetaFactory.java, ca-tmpl @f6fbd4e196b4
|
||||
public static ResponseMeta fromMdc() {
|
||||
return new ResponseMeta(
|
||||
MDC.get(MdcKeys.REQUEST_ID), MDC.get(MdcKeys.TRACE_ID), MDC.get(MdcKeys.CORRELATION_ID));
|
||||
}
|
||||
```
|
||||
|
||||
```xml
|
||||
<!-- 출처: [[wiki/projects/ca-tmpl/observability-log-metric-trace-runbook]] -->
|
||||
<!-- 실제 파일: app-bootstrap/src/main/resources/logback-spring.xml, ca-tmpl @f6fbd4e196b4 -->
|
||||
<includeMdcKeyName>trace_id</includeMdcKeyName>
|
||||
<includeMdcKeyName>span_id</includeMdcKeyName>
|
||||
<includeMdcKeyName>request_id</includeMdcKeyName>
|
||||
<includeMdcKeyName>correlation_id</includeMdcKeyName>
|
||||
<includeMdcKeyName>user_principal</includeMdcKeyName>
|
||||
```
|
||||
|
||||
## Sources / 근거 (canonical 인용 필수, derived layer 의무)
|
||||
|
||||
- [[wiki/projects/ca-tmpl/observability-log-metric-trace-runbook]] - 이 글의 1차 canonical. MDC/header/meta/logback foundation, local verification, planned/documented-only 항목 경계를 따른다.
|
||||
- [[wiki/concepts/observability-log-metric-trace-runbook]] - 관련 개념 문서. 로그, metric, trace, runbook의 일반 개념 배경으로만 둔다.
|
||||
|
||||
## 사실 vs 의견 / Fact vs opinion 구분
|
||||
|
||||
- 사실: ca-tmpl에는 `MdcKeys`, `HeaderSanitizer`, `RequestLoggingFilter`, `ResponseMetaFactory`, `ResponseMeta`, `logback-spring.xml` MDC include 설정이 존재한다. 근거: [[wiki/projects/ca-tmpl/observability-log-metric-trace-runbook]]
|
||||
- 사실: inbound request/correlation id sanitize, traceparent 채택/생성, response header 설정, envelope meta projection은 구현된 foundation 범위다. 근거: [[wiki/projects/ca-tmpl/observability-log-metric-trace-runbook]]
|
||||
- 사실: production alert tuning, 실제 incident response 효과, trace backend export 검증, runbook 운영 검증은 project canonical 기준으로 구현/운영 검증 범위가 아니다. 근거: [[wiki/projects/ca-tmpl/observability-log-metric-trace-runbook]]
|
||||
- 의견: observability를 “데이터 출력”보다 “서로 join 가능한 운영 계약”으로 설명하면 skeleton 설계 의도가 더 잘 드러난다.
|
||||
- 알지 못하는 것: 실제 alert fatigue, log volume/cost 변화, production trace 검색 성공률.
|
||||
|
||||
## 답할 수 있는 범위 / Answer boundary
|
||||
|
||||
- 자신 있게 답할 수 있는 후속 질문:
|
||||
- response meta와 log context를 왜 연결하는가?
|
||||
- snake_case MDC와 camelCase JSON meta를 왜 분리하는가?
|
||||
- inbound header sanitize와 principal pseudonymization은 어떤 위험을 줄이는가?
|
||||
- 다음 글로 넘길 부분:
|
||||
- production alert threshold.
|
||||
- OpenTelemetry exporter와 trace backend 운영.
|
||||
- runbook link-check와 incident review 결과.
|
||||
|
||||
## 게시 체크리스트 / Publish checklist
|
||||
|
||||
- [x] 모든 사실 주장에 canonical 링크 있음
|
||||
- [x] 사실 vs 의견 분리 명시됨
|
||||
- [x] 금지 마케팅 표현 없음
|
||||
- [x] 코드 예제 출처 명시
|
||||
- [x] 타깃 독자 가정과 톤 일치
|
||||
- [x] `/lint` 통과
|
||||
- [ ] 게시 URL 기록 (게시 후):
|
||||
|
||||
## Related / 관련
|
||||
|
||||
- 후속 글 후보: [[wiki/blog/ca-tmpl-api-error-envelope-design-2026-07-02]]
|
||||
- 후속 글 후보: [[wiki/blog/ca-tmpl-security-baseline-jwt-actuator-secrets-2026-07-02]]
|
||||
@@ -1 +0,0 @@
|
||||
../../vault/40-publish/blog/ca-tmpl-privacy-file-domain-modeling-2026-07-02.md
|
||||
@@ -0,0 +1,152 @@
|
||||
---
|
||||
title: Privacy와 File Handling을 Domain Modeling과 함께 보기
|
||||
source_type: blog
|
||||
status: verified
|
||||
confidence: high
|
||||
tags: [blog, ca-tmpl, privacy, file-upload, domain-modeling]
|
||||
related_projects: [ca-tmpl]
|
||||
last_reviewed: 2026-07-03
|
||||
canonical_sources:
|
||||
- wiki/projects/ca-tmpl/privacy-file-domain-modeling
|
||||
audience: backend-engineer
|
||||
target_publish:
|
||||
status_label: ready
|
||||
---
|
||||
|
||||
# Privacy와 File Handling을 Domain Modeling과 함께 보기
|
||||
|
||||
## Parent / 부모 (필수)
|
||||
|
||||
- 핵심 canonical: [[wiki/projects/ca-tmpl/privacy-file-domain-modeling]]
|
||||
- 관련 개념 문서: [[wiki/concepts/privacy-file-domain-modeling]] - privacy, file upload, DDD guardrail의 일반 배경. 현재 이 글의 구현 사실 근거는 verified project canonical에 둔다.
|
||||
|
||||
## 타깃 독자 / Target reader
|
||||
|
||||
- 독자 profile: skeleton에서 privacy, file upload, domain modeling guardrail을 함께 고민하는 백엔드 엔지니어.
|
||||
- 이미 안다고 가정하는 것: PII, file upload, DDD aggregate.
|
||||
- 처음 듣는다고 가정하는 것: privacy/file/domain을 각각 따로 구현하지 않고 “어떤 값이 어디에 남으면 안 되는가”라는 모델링 경계로 연결하는 관점.
|
||||
|
||||
## 도입 / Hook
|
||||
|
||||
Privacy는 보안팀 문서처럼 보이고, file upload는 adapter 이슈처럼 보이며, domain modeling은 DDD 문법처럼 보입니다. 그런데 실제 프로젝트에서는 세 가지가 자주 엮입니다. 사용자의 원본 식별자가 로그에 남으면 안 되고, upload payload는 app/proxy/gateway 어디에서 막을지 정해야 하며, domain model은 ORM이나 logger에 오염되지 않아야 합니다.
|
||||
|
||||
ca-tmpl은 이 세 축을 한 문서에 묶었지만, 구현 범위는 균등하지 않습니다. HMAC 기반 principal pseudonymization, MDC logging path, domain purity/aggregate/value object guardrail은 코드와 테스트가 있습니다. 반면 file upload handler, DSR workflow, backup cryptographic erasure, ICAP integration은 아직 문서/계획 범위입니다. 이 글은 이 차이를 숨기지 않고, privacy와 modeling을 함께 보는 이유를 정리합니다.
|
||||
|
||||
## 본문 outline / Body outline
|
||||
|
||||
1. privacy/file/domain modeling을 같은 문서에서 보는 이유.
|
||||
2. 구현된 privacy foundation - principal pseudonymization과 MDC logging.
|
||||
3. 구현된 domain guardrail - pure domain, logger ban, value object, aggregate setter rule.
|
||||
4. file handling과 DSR은 아직 planned 범위다.
|
||||
5. compliance/운영 검증은 없다.
|
||||
|
||||
## 본문 / Body
|
||||
|
||||
Privacy의 첫 번째 실수는 “민감 정보를 나중에 마스킹하면 된다”고 생각하는 것입니다. 하지만 로그에 raw principal이 들어가면, 이후 retention이나 DSR을 논의하기 전에 이미 추적 가능한 식별자가 퍼져 있습니다. ca-tmpl은 request logging path에서 raw principal을 바로 MDC에 넣지 않고, `UserPrincipalPseudonymizerPort`를 거친 pseudonymized value만 `user_principal` key에 넣습니다.
|
||||
|
||||
구현체는 `HmacUserPrincipalPseudonymizer`입니다. 입력 principal을 HMAC-SHA-256으로 64자 lowercase hex token으로 바꿉니다. `PseudonymizationConfig`는 이 구현체를 `UserPrincipalPseudonymizerPort` bean으로 제공합니다. `PrivacySettings`는 `ca-skeleton.privacy.*` 설정에서 salt를 읽고, local/test에서 blank salt면 dev sentinel을 사용합니다. 이 흐름은 “raw subject를 로그에 그대로 쓰지 않는다”는 최소 foundation입니다.
|
||||
|
||||
다만 이것을 anonymization이라고 부르면 안 됩니다. HMAC token은 같은 salt에서 같은 입력을 안정적으로 같은 token으로 만들기 때문에, 추적 가능성을 줄이는 pseudonymization에 가깝습니다. input space가 작으면 brute-force 위험도 남습니다. 또한 backup 안에 이미 남은 값을 단건 삭제하는 GDPR Art.17 문제까지 해결하지 않습니다. project canonical도 per-principal envelope key 구조는 미결정이라고 명시합니다.
|
||||
|
||||
Domain modeling guardrail은 privacy와 다른 문제처럼 보이지만, 같은 방향을 봅니다. domain layer가 logger를 직접 잡으면 domain invariant violation이 곧바로 log payload가 될 수 있습니다. domain class가 JPA annotation이나 framework type에 묶이면 persistence detail이 domain boundary로 들어옵니다. ca-tmpl의 `CleanArchitectureTest`는 domain package가 Spring/JPA/Hibernate/Lombok/application/adapter/bootstrap에 의존하지 못하게 하고, domain logger dependency도 별도 rule로 금지합니다.
|
||||
|
||||
Value Object와 Aggregate Root rule도 있습니다. `@ValueObject`는 public no-arg constructor를 금지합니다. 값 객체가 빈 생성자로 만들어지고 나중에 setter로 채워지면 invariant를 우회할 수 있기 때문입니다. `@AggregateRoot`에는 public `set*` mutator를 금지합니다. aggregate state는 의도가 드러나는 method를 통해 바뀌어야 하고, 그 method가 invariant를 확인해야 합니다.
|
||||
|
||||
File handling 쪽은 아직 구현됐다고 말하면 안 됩니다. app 10MB, proxy 12MB, gateway 20MB 같은 size limit, content-type allowlist, temp orphan cleanup, ICAP antivirus gateway는 project canonical에 문서화되어 있지만 file upload handler나 scan integration으로 닫힌 상태가 아닙니다. DSR SLA, backup cryptographic erasure도 마찬가지입니다. 설계 방향은 있지만, 실제 요청 처리 workflow나 법무/compliance review가 있는 것은 아닙니다.
|
||||
|
||||
그래서 이 글의 결론은 조심스럽습니다. ca-tmpl은 privacy/file/domain 전체를 완성한 것이 아닙니다. 구현된 것은 pseudonymized principal logging foundation과 domain modeling guardrail 일부입니다. file upload, DSR, backup erasure는 후속 구현이 필요합니다. 하지만 세 축을 함께 보는 관점은 유효합니다. 어떤 값이 어디에 남는지, 어떤 계층이 어떤 타입을 알 수 있는지, 어떤 construction path가 invariant를 우회하는지 모두 결국 boundary 문제이기 때문입니다.
|
||||
|
||||
## 코드 예제 / Code samples (있다면)
|
||||
|
||||
```java
|
||||
// 출처: [[wiki/projects/ca-tmpl/privacy-file-domain-modeling]]
|
||||
// 실제 파일: adapter-identifier/.../HmacUserPrincipalPseudonymizer.java, ca-tmpl @f6fbd4e196b4
|
||||
public String pseudonymize(String rawPrincipal) {
|
||||
if (rawPrincipal == null || rawPrincipal.isBlank()) {
|
||||
return null;
|
||||
}
|
||||
Mac mac = Mac.getInstance("HmacSHA256");
|
||||
mac.init(key);
|
||||
byte[] digest = mac.doFinal(rawPrincipal.getBytes(StandardCharsets.UTF_8));
|
||||
return HexFormat.of().formatHex(digest);
|
||||
}
|
||||
```
|
||||
|
||||
```java
|
||||
// 출처: [[wiki/projects/ca-tmpl/privacy-file-domain-modeling]]
|
||||
// 실제 파일: adapter-web/.../RequestLoggingFilter.java, ca-tmpl @f6fbd4e196b4
|
||||
private void putUserPrincipalIfAvailable() {
|
||||
Authentication auth = SecurityContextHolder.getContext().getAuthentication();
|
||||
if (auth != null && auth.getPrincipal() instanceof AuthenticatedPrincipal user) {
|
||||
String pseudo = pseudonymizer.pseudonymize(user.idpUserId());
|
||||
if (pseudo != null) {
|
||||
MDC.put(MdcKeys.USER_PRINCIPAL, pseudo);
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```java
|
||||
// 출처: [[wiki/projects/ca-tmpl/privacy-file-domain-modeling]]
|
||||
// 실제 파일: app-bootstrap/.../CleanArchitectureTest.java, ca-tmpl @f6fbd4e196b4
|
||||
static final ArchRule DOMAIN_IS_PURE =
|
||||
noClasses()
|
||||
.that()
|
||||
.resideInAPackage("..domain..")
|
||||
.should()
|
||||
.dependOnClassesThat()
|
||||
.resideInAnyPackage("org.springframework..", "jakarta.persistence..", "org.hibernate..");
|
||||
```
|
||||
|
||||
```java
|
||||
// 출처: [[wiki/projects/ca-tmpl/privacy-file-domain-modeling]]
|
||||
// 실제 파일: app-bootstrap/.../CleanArchitectureTest.java, ca-tmpl @f6fbd4e196b4
|
||||
static final ArchRule AGGREGATE_ROOT_SETTERS_ARE_NOT_PUBLIC =
|
||||
methods()
|
||||
.that()
|
||||
.haveNameMatching("set.*")
|
||||
.and()
|
||||
.areDeclaredInClassesThat()
|
||||
.areAnnotatedWith(AggregateRoot.class)
|
||||
.should()
|
||||
.notBePublic();
|
||||
```
|
||||
|
||||
## Sources / 근거 (canonical 인용 필수, derived layer 의무)
|
||||
|
||||
- [[wiki/projects/ca-tmpl/privacy-file-domain-modeling]] - 이 글의 1차 canonical. pseudonymization/logging path, domain guardrail, file/DSR/backup planned 범위, 운영/법무 미검증 경계를 따른다.
|
||||
- [[wiki/concepts/privacy-file-domain-modeling]] - 관련 개념 문서. GDPR, cryptographic erase, file upload, DDD guardrail의 일반 배경으로만 둔다.
|
||||
|
||||
## 사실 vs 의견 / Fact vs opinion 구분
|
||||
|
||||
- 사실: ca-tmpl에는 `HmacUserPrincipalPseudonymizer`, `PseudonymizationConfig`, `PrivacySettings`, `RequestLoggingFilter`의 pseudonymized principal logging path가 존재한다. 근거: [[wiki/projects/ca-tmpl/privacy-file-domain-modeling]]
|
||||
- 사실: domain purity, domain logger ban, value object no public no-arg constructor, aggregate setter visibility rule이 `CleanArchitectureTest` 계열에 존재한다. 근거: [[wiki/projects/ca-tmpl/privacy-file-domain-modeling]]
|
||||
- 사실: file upload handler, DSR workflow, backup cryptographic erasure, ICAP integration은 구현/로컬 검증 범위가 아니다. 근거: [[wiki/projects/ca-tmpl/privacy-file-domain-modeling]]
|
||||
- 의견: privacy와 domain modeling은 서로 다른 주제처럼 보여도 “값이 어디에 남고 어떤 경계가 우회되는가”라는 같은 질문으로 연결된다.
|
||||
- 알지 못하는 것: 실제 GDPR DSR 처리, legal review, antivirus gateway 운영, backup erasure 검증.
|
||||
|
||||
## 답할 수 있는 범위 / Answer boundary
|
||||
|
||||
- 자신 있게 답할 수 있는 후속 질문:
|
||||
- HMAC pseudonymization이 anonymization이 아닌 이유.
|
||||
- raw principal을 MDC에 직접 쓰지 않는 이유.
|
||||
- domain layer logger ban과 aggregate/value object guardrail이 어떤 우회를 막는가.
|
||||
- 다음 글로 넘길 부분:
|
||||
- file upload handler와 antivirus integration.
|
||||
- DSR workflow와 backup cryptographic erasure.
|
||||
- compliance review와 production privacy workflow.
|
||||
|
||||
## 게시 체크리스트 / Publish checklist
|
||||
|
||||
- [x] 모든 사실 주장에 canonical 링크 있음
|
||||
- [x] 사실 vs 의견 분리 명시됨
|
||||
- [x] 금지 마케팅 표현 없음
|
||||
- [x] 코드 예제 출처 명시
|
||||
- [x] 타깃 독자 가정과 톤 일치
|
||||
- [x] `/lint` 통과
|
||||
- [ ] 게시 URL 기록 (게시 후):
|
||||
|
||||
## Related / 관련
|
||||
|
||||
- 후속 글 후보: [[wiki/blog/ca-tmpl-clean-architecture-package-layout-2026-07-02]]
|
||||
- 후속 글 후보: [[wiki/blog/ca-tmpl-observability-log-metric-trace-runbook-2026-07-02]]
|
||||
@@ -1 +0,0 @@
|
||||
../../vault/40-publish/blog/ca-tmpl-resource-identifier-format-2026-07-02.md
|
||||
@@ -0,0 +1,160 @@
|
||||
---
|
||||
title: Resource Identifier를 UUID 대신 ULID로 고정한 이유
|
||||
source_type: blog
|
||||
status: verified
|
||||
confidence: high
|
||||
tags: [blog, ca-tmpl, resource-identifier, ulid]
|
||||
related_projects: [ca-tmpl]
|
||||
last_reviewed: 2026-07-03
|
||||
canonical_sources:
|
||||
- wiki/projects/ca-tmpl/resource-identifier-format
|
||||
audience: backend-engineer
|
||||
target_publish:
|
||||
status_label: ready
|
||||
---
|
||||
|
||||
# Resource Identifier를 UUID 대신 ULID로 고정한 이유
|
||||
|
||||
## Parent / 부모 (필수)
|
||||
|
||||
- 핵심 canonical: [[wiki/projects/ca-tmpl/resource-identifier-format]]
|
||||
- 관련 개념 문서: [[wiki/concepts/resource-identifier-format]] - 일반 identifier format 비교. 현재 이 글의 구현 사실 근거는 verified project canonical에 둔다.
|
||||
|
||||
## 타깃 독자 / Target reader
|
||||
|
||||
- 독자 profile: API resource id 규칙을 skeleton 수준에서 정하려는 백엔드 엔지니어.
|
||||
- 이미 안다고 가정하는 것: UUID, database primary key, API id.
|
||||
- 처음 듣는다고 가정하는 것: ULID의 표기 규칙, 생성 위치, id-kind governance를 architecture rule로 고정하는 방식.
|
||||
|
||||
## 도입 / Hook
|
||||
|
||||
API의 id는 처음에는 단순한 문자열처럼 보입니다. 하지만 id가 어디에서 생성되는지, 어떤 형태로 외부에 노출되는지, DB에는 어떤 타입으로 저장되는지, 어떤 계층이 id를 만들 수 있는지까지 정하지 않으면 나중에 작은 균열이 생깁니다. controller에서 `UUID.randomUUID()`를 부르고, 다른 use case에서는 DB sequence를 쓰고, 또 다른 API는 문자열 id를 그대로 반환하는 식입니다.
|
||||
|
||||
ca-tmpl은 이 문제를 “UUID냐 ULID냐”의 취향 싸움으로만 보지 않았습니다. 외부 API에는 26자 대문자 Crockford base32 ULID를 노출하고, domain은 id를 value object로 다루며, 생성은 adapter port 뒤로 숨기고, persistence는 PostgreSQL `uuid` column으로 저장하는 계약으로 묶었습니다. 이 글은 그 결정이 왜 필요했는지, 어떤 코드로 고정됐는지, 그리고 아직 검증했다고 말하면 안 되는 부분이 무엇인지 정리합니다.
|
||||
|
||||
## 본문 outline / Body outline
|
||||
|
||||
1. identifier를 나중에 정하면 생기는 문제.
|
||||
2. ULID를 API 표기 규칙으로 선택한 이유와 trade-off.
|
||||
3. domain value object, generation port, adapter module의 역할 분리.
|
||||
4. persistence와 wire format의 분리.
|
||||
5. ArchUnit rule로 id governance를 고정한 범위.
|
||||
6. 운영 규모에서의 index/locality 검증은 없음.
|
||||
|
||||
## 본문 / Body
|
||||
|
||||
Resource id 설계에서 먼저 정해야 하는 것은 “id 값이 무엇인가”보다 “누가 id를 만들 수 있는가”입니다. controller가 직접 `UUID.randomUUID()`를 호출하면 use case마다 생성 방식이 갈라질 수 있습니다. application service가 라이브러리에 직접 의존하면 domain model은 순수해 보여도 use case가 infrastructure detail을 알고 있게 됩니다. DB가 id 생성을 전담하면 API에 노출되는 id format과 persistence type이 묶입니다.
|
||||
|
||||
ca-tmpl은 이 지점을 domain port로 끊었습니다. domain-core에는 `ResourceId` marker와 `IdFactory<T>` port가 있고, sample domain에는 `WorkLogId`와 `WorkLogIdFactory`가 있습니다. `WorkLogId`는 26자 대문자 Crockford base32 ULID 문자열만 받는 value object입니다. domain은 ULID library를 직접 알지 않습니다. 실제 생성은 `adapter-identifier` module의 `UlidWorkLogIdFactory`가 맡습니다. 이렇게 하면 domain은 “id shape”만 알고, “id를 어떻게 mint하는가”는 adapter가 책임집니다.
|
||||
|
||||
ULID를 고른 이유는 API 표기와 정렬성의 균형입니다. ULID는 26자 문자열이라 URL path에 넣기 쉽고, 시간 성분이 앞에 있어 생성 시점 기준 정렬 가능성이 있습니다. ca-tmpl에서는 이를 외부 wire format으로 삼았습니다. 다만 이 말이 곧 “모든 DB에서 insert 성능이 검증됐다”는 뜻은 아닙니다. project canonical은 PostgreSQL index locality benchmark가 없다고 명시합니다. 이 글도 그 선을 넘지 않습니다.
|
||||
|
||||
재미있는 부분은 DB 저장 방식입니다. API와 domain에서는 ULID 문자열을 쓰지만, JPA entity는 `UUID` field를 PostgreSQL native `uuid` column에 저장합니다. `UlidCodec`이 ULID 문자열과 UUID 사이 변환을 맡고, persistence mapper가 domain `WorkLogId`와 entity `UUID` 사이를 변환합니다. 즉 외부 계약은 “대문자 ULID 문자열”이고, DB 저장 계약은 “native uuid type”입니다. 두 계약을 같은 문자열 column으로 합쳐버리지 않은 셈입니다.
|
||||
|
||||
wire format도 별도로 고정했습니다. Java record인 `WorkLogId`를 그대로 Jackson이 직렬화하면 `{ "value": "..." }` 형태가 될 수 있습니다. ca-tmpl은 `WorkLogIdSerializer`를 두어 응답에서는 bare ULID string이 나가도록 했습니다. 이 결정 덕분에 API 소비자는 id field를 객체가 아니라 문자열로 다룹니다. 내부 value object와 외부 JSON shape를 분리한 것입니다.
|
||||
|
||||
id governance는 ArchUnit rule로도 고정되어 있습니다. domain entity의 `id` field는 `ResourceId`여야 하고, controller/application layer는 resource id 생성을 위해 `UUID.randomUUID()`나 `UlidCreator`에 직접 닿지 않아야 합니다. `Math.random()`도 id seed로 쓰지 못하게 막습니다. JPA `@Column`으로 매핑된 id field가 기본 `varchar(255)`로 떨어지는 것도 금지합니다. 또 `adapter-identifier`는 sibling adapter나 bootstrap에 의존하지 못합니다.
|
||||
|
||||
여기까지가 ca-tmpl이 실제로 구현하고 로컬 검증한 범위입니다. `adapter-identifier` module, `WorkLogId`, `UlidCodec`, persistence mapper, JSON serializer, architecture rule과 테스트가 존재합니다. 반면 CUID2 override, multi-tenancy까지 포함한 id scoping, log scrubber, PostgreSQL index benchmark는 구현됐다고 말하면 안 됩니다. 이 글의 결론은 “ULID가 어디서나 이긴다”가 아니라, “ca-tmpl은 id format을 API/Domain/Persistence/Architecture rule까지 이어지는 계약으로 만들었다”입니다.
|
||||
|
||||
## 코드 예제 / Code samples (있다면)
|
||||
|
||||
```java
|
||||
// 출처: [[wiki/projects/ca-tmpl/resource-identifier-format]]
|
||||
// 실제 파일: domain-core/.../ResourceId.java, ca-tmpl @f6fbd4e196b4
|
||||
public interface ResourceId<SELF extends ResourceId<SELF>> {
|
||||
/** The canonical 26-character uppercase Crockford base32 ULID string. */
|
||||
String value();
|
||||
}
|
||||
```
|
||||
|
||||
```java
|
||||
// 출처: [[wiki/projects/ca-tmpl/resource-identifier-format]]
|
||||
// 실제 파일: sample-portfolio/.../WorkLogId.java, ca-tmpl @f6fbd4e196b4
|
||||
public record WorkLogId(String value) implements ResourceId<WorkLogId> {
|
||||
private static final Pattern PATTERN = Pattern.compile("^[0-9A-HJKMNP-TV-Z]{26}$");
|
||||
|
||||
public WorkLogId {
|
||||
if (value == null || !PATTERN.matcher(value).matches()) {
|
||||
throw new IllegalArgumentException("Invalid WorkLogId format: " + value);
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```java
|
||||
// 출처: [[wiki/projects/ca-tmpl/resource-identifier-format]]
|
||||
// 실제 파일: adapter-identifier/.../UlidCodec.java, ca-tmpl @f6fbd4e196b4
|
||||
public static String normalize(String input) {
|
||||
if (input == null) {
|
||||
return null;
|
||||
}
|
||||
return Ulid.from(input.toUpperCase(Locale.ROOT)).toString();
|
||||
}
|
||||
|
||||
public static UUID toUuid(String ulidString) {
|
||||
return Ulid.from(ulidString).toUuid();
|
||||
}
|
||||
```
|
||||
|
||||
```java
|
||||
// 출처: [[wiki/projects/ca-tmpl/resource-identifier-format]]
|
||||
// 실제 파일: sample-portfolio/.../WorkLogEntity.java, ca-tmpl @f6fbd4e196b4
|
||||
@Id
|
||||
@Column(name = "id", columnDefinition = "uuid", nullable = false, updatable = false)
|
||||
@JdbcTypeCode(SqlTypes.UUID)
|
||||
private UUID id;
|
||||
```
|
||||
|
||||
```java
|
||||
// 출처: [[wiki/projects/ca-tmpl/resource-identifier-format]]
|
||||
// 실제 파일: app-bootstrap/.../CleanArchitectureTest.java, ca-tmpl @f6fbd4e196b4
|
||||
static final ArchRule NO_UUID_RANDOM_IN_CONTROLLER =
|
||||
noClasses()
|
||||
.that()
|
||||
.resideInAnyPackage("..adapter.web..controller..", "..application..")
|
||||
.should()
|
||||
.callMethod(UUID.class, "randomUUID")
|
||||
.orShould()
|
||||
.dependOnClassesThat()
|
||||
.haveFullyQualifiedName("com.github.f4b6a3.ulid.UlidCreator");
|
||||
```
|
||||
|
||||
## Sources / 근거 (canonical 인용 필수, derived layer 의무)
|
||||
|
||||
- [[wiki/projects/ca-tmpl/resource-identifier-format]] - 이 글의 1차 canonical. ULID wire format, `ResourceId`, `IdFactory`, `adapter-identifier`, persistence UUID column, ArchUnit rule, local verification, 미구현 항목 경계를 따른다.
|
||||
- [[wiki/concepts/resource-identifier-format]] - 관련 개념 문서. UUIDv7/ULID/Snowflake/NanoID/CUID2 등 일반 비교를 위한 배경으로만 둔다.
|
||||
|
||||
## 사실 vs 의견 / Fact vs opinion 구분
|
||||
|
||||
- 사실: ca-tmpl에는 `ResourceId`, `IdFactory`, `WorkLogId`, `WorkLogIdFactory`, `UlidWorkLogIdFactory`, `UlidCodec`, `WorkLogEntity`, `WorkLogPersistenceMapper`, `WorkLogIdSerializer`가 존재한다. 근거: [[wiki/projects/ca-tmpl/resource-identifier-format]]
|
||||
- 사실: `adapter-identifier` module과 identifier 관련 ArchUnit rule이 존재하고, project canonical은 이를 local verification 범위로 기록한다. 근거: [[wiki/projects/ca-tmpl/resource-identifier-format]]
|
||||
- 사실: PostgreSQL uuid index locality benchmark, CUID2 override, multi-tenancy id scoping, `UlidLogScrubber`는 구현/운영 검증으로 말하지 않는다. 근거: [[wiki/projects/ca-tmpl/resource-identifier-format]]
|
||||
- 의견: ca-tmpl 같은 skeleton에서는 id를 단순 primitive로 두는 것보다 value object와 generation port로 고정하는 편이 이후 boundary rule을 설명하기 쉽다.
|
||||
- 알지 못하는 것: production insert/index metric, tenant별 id collision/lookup 운영 결과.
|
||||
|
||||
## 답할 수 있는 범위 / Answer boundary
|
||||
|
||||
- 자신 있게 답할 수 있는 후속 질문:
|
||||
- ca-tmpl에서 resource id 생성이 왜 adapter port 뒤에 있는가?
|
||||
- API에는 ULID string을 노출하면서 DB에는 왜 native `uuid` column을 쓰는가?
|
||||
- 어떤 ArchUnit rule이 id 생성 위치와 id column mapping을 막는가?
|
||||
- 다음 글로 넘길 부분:
|
||||
- sharding/partitioning 환경의 id 전략.
|
||||
- PostgreSQL index locality benchmark.
|
||||
- multi-tenant id scoping과 tenant-aware repository rule.
|
||||
|
||||
## 게시 체크리스트 / Publish checklist
|
||||
|
||||
- [x] 모든 사실 주장에 canonical 링크 있음
|
||||
- [x] 사실 vs 의견 분리 명시됨
|
||||
- [x] 금지 마케팅 표현 없음
|
||||
- [x] 코드 예제 출처 명시
|
||||
- [x] 타깃 독자 가정과 톤 일치
|
||||
- [x] `/lint` 통과
|
||||
- [ ] 게시 URL 기록 (게시 후):
|
||||
|
||||
## Related / 관련
|
||||
|
||||
- 후속 글 후보: [[wiki/blog/ca-tmpl-api-evolution-and-schema-2026-07-02]]
|
||||
- 후속 글 후보: [[wiki/blog/ca-tmpl-multi-tenancy-isolation-patterns-2026-07-02]]
|
||||
@@ -1 +0,0 @@
|
||||
../../vault/40-publish/blog/ca-tmpl-runtime-container-health-migration-2026-07-02.md
|
||||
@@ -0,0 +1,166 @@
|
||||
---
|
||||
title: Runtime 설정 오류를 Startup에서 실패시키기
|
||||
source_type: blog
|
||||
status: verified
|
||||
confidence: high
|
||||
tags: [blog, ca-tmpl, runtime, container, health, migration]
|
||||
related_projects: [ca-tmpl]
|
||||
last_reviewed: 2026-07-03
|
||||
canonical_sources:
|
||||
- wiki/projects/ca-tmpl/runtime-container-health-migration
|
||||
audience: backend-engineer
|
||||
target_publish:
|
||||
status_label: ready
|
||||
---
|
||||
|
||||
# Runtime 설정 오류를 Startup에서 실패시키기
|
||||
|
||||
## Parent / 부모 (필수)
|
||||
|
||||
- 핵심 canonical: [[wiki/projects/ca-tmpl/runtime-container-health-migration]]
|
||||
- 관련 개념 문서: [[wiki/concepts/runtime-container-health-migration]] - 일반 runtime/container/health/migration 개념. 현재 이 글의 구현 사실 근거는 verified project canonical에 둔다.
|
||||
|
||||
## 타깃 독자 / Target reader
|
||||
|
||||
- 독자 profile: container readiness, health check, migration, runtime config guard를 skeleton에 넣고 싶은 엔지니어.
|
||||
- 이미 안다고 가정하는 것: Docker/Kubernetes probe, Flyway, env config, Spring Boot Actuator.
|
||||
- 처음 듣는다고 가정하는 것: runtime safety를 startup validator, health group, migration strategy, exit code로 묶는 방식.
|
||||
|
||||
## 도입 / Hook
|
||||
|
||||
운영 설정 오류는 배포 뒤에 늦게 발견될수록 비쌉니다. pool size가 음수로 들어가거나, `open-in-view`가 켜지거나, prod profile에서 Flyway safety option이 풀린 상태로 애플리케이션이 올라오면, 문제는 요청을 받기 시작한 뒤에 드러날 수 있습니다.
|
||||
|
||||
ca-tmpl은 이런 오류를 startup 단계에서 실패시키는 방향으로 runtime contract를 잡았습니다. env-driven configuration을 쓰되 잘못된 값은 lenient default로 숨기지 않고, health group은 liveness/readiness/startup 역할을 나누며, Flyway migration 실패는 startup failure와 exit code로 드러냅니다. 이 글은 ca-tmpl에 실제로 구현된 runtime/container/health/migration baseline과 아직 운영 검증으로 말하면 안 되는 범위를 정리합니다.
|
||||
|
||||
## 본문 outline / Body outline
|
||||
|
||||
1. startup fail-fast의 가치.
|
||||
2. runtime numeric bounds와 OSIV/Hikari guard.
|
||||
3. health probe group split과 readiness gate.
|
||||
4. Flyway migration startup contract와 exit code.
|
||||
5. container image/runtime baseline.
|
||||
6. Kubernetes cluster rollout 검증은 없음.
|
||||
|
||||
## 본문 / Body
|
||||
|
||||
runtime 설정은 코드보다 덜 중요해 보이지만, 실제로는 애플리케이션의 동작 경계를 바꿉니다. DB pool max size, Tomcat thread count, shutdown timeout, Flyway option, Actuator exposure는 모두 장애 양상을 바꿀 수 있습니다. 그래서 ca-tmpl은 “값이 이상하면 프레임워크 기본값으로 알아서 흘러가게 둔다”보다 “startup에서 실패한다”는 쪽을 택했습니다.
|
||||
|
||||
`RuntimeNumericBoundsValidator`는 대표적인 예입니다. `spring.datasource.hikari.maximum-pool-size`, `server.tomcat.threads.max`, `server.tomcat.max-connections` 같은 값은 1 이상이어야 하고, minimum idle이나 accept count처럼 0을 허용하는 값은 0 이상이어야 합니다. key가 없으면 framework default에 맡기지만, key가 있는데 범위를 벗어나면 `IllegalStateException`으로 startup을 막습니다. env-driven 설정을 쓰면서도 잘못된 env 값을 조용히 묻지 않는 장치입니다.
|
||||
|
||||
OSIV와 Hikari 설정도 별도 guard로 다룹니다. `OpenInViewSafetyValidator`는 `spring.jpa.open-in-view=true`를 거부합니다. Hikari validator는 `connection-timeout`, `validation-timeout`, `keepalive-time`, `max-lifetime`, `leak-detection-threshold`의 상호 관계를 검사합니다. 예를 들어 validation timeout이 connection timeout보다 길면 pool 동작을 예측하기 어려워집니다. ca-tmpl은 이런 값을 요청 처리 뒤의 증상으로 발견하기보다 startup에서 configuration error로 드러내려 합니다.
|
||||
|
||||
health check는 endpoint 하나로 뭉개지 않습니다. `application.yml`에는 Actuator health group이 `liveness`, `readiness`, `startup`으로 나뉘어 있습니다. liveness는 JVM이 계속 살아갈 수 있는지를 보며 dependency health를 포함하지 않습니다. DB가 잠깐 내려갔다고 pod를 재시작하는 것은 보통 원하는 동작이 아니기 때문입니다. readiness는 traffic을 받아도 되는지를 판단하므로 `readinessState,db`를 포함합니다. startup은 context initialization과 migration 완료 후 준비 상태를 드러내는 gate로 둡니다.
|
||||
|
||||
Flyway도 startup contract의 일부입니다. `MigrationStartupRunner`는 context refresh 중 Flyway migration을 수행하고, 실패하면 `MigrationFailedException` 계열로 바꿔 exit code 70에 연결합니다. `StartupErrorCode`에는 startup validation, migration failure, profile mismatch, required adapter disabled가 각각 다른 exit code와 phase로 정의되어 있습니다. 실패 원인을 process exit status와 structured startup log에서 분리해 보려는 설계입니다.
|
||||
|
||||
prod profile의 Flyway safety guard도 들어 있습니다. `FlywayProdSafetyValidator`는 prod에서 `baseline-on-migrate=true`, `out-of-order=true`, `clean-disabled=false` 같은 위험한 override를 막습니다. 여기서 중요한 것은 “Flyway를 쓰면 안전하다”가 아닙니다. migration 도구를 쓰더라도 prod에서 안전망을 푸는 설정이 들어오면 애플리케이션이 올라오지 않게 만드는 것입니다.
|
||||
|
||||
container/runtime baseline도 project canonical에 포함되어 있습니다. `src/Dockerfile`, graceful shutdown 설정, Actuator health group, startup validator, migration strategy가 묶여 있습니다. 그러나 실제 Kubernetes manifest, rolling update, probe tuning, cluster에서의 rollout incident 검증은 없습니다. 따라서 이 글은 “Kubernetes 운영에서 검증된 lifecycle 설계”가 아니라 “ca-tmpl이 startup fail-fast와 health/migration baseline을 코드와 설정으로 고정하고 로컬 검증했다”까지 말합니다.
|
||||
|
||||
## 코드 예제 / Code samples (있다면)
|
||||
|
||||
```java
|
||||
// 출처: [[wiki/projects/ca-tmpl/runtime-container-health-migration]]
|
||||
// 실제 파일: app-bootstrap/.../RuntimeNumericBoundsValidator.java, ca-tmpl @f6fbd4e196b4
|
||||
static final List<Bound> BOUNDS =
|
||||
List.of(
|
||||
new Bound("spring.datasource.hikari.maximum-pool-size", "APP_DATASOURCE_POOL_MAX_SIZE", 1),
|
||||
new Bound("server.tomcat.threads.max", "APP_SERVER_TOMCAT_MAX_THREADS", 1),
|
||||
new Bound("server.tomcat.max-connections", "APP_SERVER_TOMCAT_MAX_CONNECTIONS", 1),
|
||||
new Bound("spring.datasource.hikari.minimum-idle", "APP_DATASOURCE_POOL_MIN_IDLE", 0),
|
||||
new Bound("server.tomcat.accept-count", "APP_SERVER_TOMCAT_ACCEPT_COUNT", 0));
|
||||
```
|
||||
|
||||
```java
|
||||
// 출처: [[wiki/projects/ca-tmpl/runtime-container-health-migration]]
|
||||
// 실제 파일: app-bootstrap/.../StartupErrorCode.java, ca-tmpl @f6fbd4e196b4
|
||||
public enum StartupErrorCode {
|
||||
STARTUP_VALIDATION_FAILED(78, StartupPhase.ENV_VALIDATION),
|
||||
MIGRATION_FAILED(70, StartupPhase.MIGRATION),
|
||||
PROFILE_MISMATCH(71, StartupPhase.PROFILE_CHECK),
|
||||
REQUIRED_ADAPTER_DISABLED(72, StartupPhase.ADAPTER_ENABLEMENT);
|
||||
}
|
||||
```
|
||||
|
||||
```java
|
||||
// 출처: [[wiki/projects/ca-tmpl/runtime-container-health-migration]]
|
||||
// 실제 파일: app-bootstrap/.../FlywayProdSafetyValidator.java, ca-tmpl @f6fbd4e196b4
|
||||
if (isTrue(BASELINE_ON_MIGRATE_KEY)) {
|
||||
violations.add(BASELINE_ON_MIGRATE_KEY + "=true (removes the missing-migration safety net)");
|
||||
}
|
||||
if (isTrue(OUT_OF_ORDER_KEY)) {
|
||||
violations.add(OUT_OF_ORDER_KEY + "=true (breaks migration ordering consistency)");
|
||||
}
|
||||
if (isFalse(CLEAN_DISABLED_KEY)) {
|
||||
violations.add(CLEAN_DISABLED_KEY + "=false (re-arms destructive Flyway clean)");
|
||||
}
|
||||
```
|
||||
|
||||
```java
|
||||
// 출처: [[wiki/projects/ca-tmpl/runtime-container-health-migration]]
|
||||
// 실제 파일: app-bootstrap/.../MigrationStartupRunner.java, ca-tmpl @f6fbd4e196b4
|
||||
try {
|
||||
MigrateResult result = flyway.migrate();
|
||||
int executed = (result != null) ? result.migrationsExecuted : 0;
|
||||
log.info("startup phase {}: migration complete, {} migration(s) applied",
|
||||
kv("startup.phase", StartupPhase.MIGRATION.wireName()), executed);
|
||||
} catch (FlywayException e) {
|
||||
throw StartupFailures.migrationFailed("Flyway forward-only migration failed during startup", e);
|
||||
}
|
||||
```
|
||||
|
||||
```yaml
|
||||
# 출처: [[wiki/projects/ca-tmpl/runtime-container-health-migration]]
|
||||
# 실제 파일: app-bootstrap/src/main/resources/application.yml, ca-tmpl @f6fbd4e196b4
|
||||
management:
|
||||
endpoint:
|
||||
health:
|
||||
probes:
|
||||
enabled: true
|
||||
group:
|
||||
liveness:
|
||||
include: livenessState
|
||||
readiness:
|
||||
include: readinessState,db
|
||||
startup:
|
||||
include: readinessState
|
||||
```
|
||||
|
||||
## Sources / 근거 (canonical 인용 필수, derived layer 의무)
|
||||
|
||||
- [[wiki/projects/ca-tmpl/runtime-container-health-migration]] - 이 글의 1차 canonical. startup validators, Actuator health group, Flyway startup migration/safety guard, exit code mapping, local verification, 운영 미검증 경계를 따른다.
|
||||
- [[wiki/concepts/runtime-container-health-migration]] - 관련 개념 문서. container lifecycle, health probe, migration strategy 일반 배경으로만 둔다.
|
||||
|
||||
## 사실 vs 의견 / Fact vs opinion 구분
|
||||
|
||||
- 사실: ca-tmpl에는 runtime numeric bounds validator, OSIV/Hikari safety validator, Actuator health group 설정, Flyway startup migration strategy, prod safety validator, startup exit code mapping이 존재한다. 근거: [[wiki/projects/ca-tmpl/runtime-container-health-migration]]
|
||||
- 사실: startup validation과 migration failure는 local/dev verification 범위로 기록되어 있다. 근거: [[wiki/projects/ca-tmpl/runtime-container-health-migration]]
|
||||
- 사실: Kubernetes manifest, rolling update, production probe tuning, cluster-level incident 검증은 없다. 근거: [[wiki/projects/ca-tmpl/runtime-container-health-migration]]
|
||||
- 의견: skeleton에서는 잘못된 runtime env를 lenient default로 흘리는 것보다 startup에서 실패시키는 쪽이 학습과 운영 설명에 유리하다.
|
||||
- 알지 못하는 것: 실제 orchestrator rollout behavior, migration lock contention, production shutdown latency.
|
||||
|
||||
## 답할 수 있는 범위 / Answer boundary
|
||||
|
||||
- 자신 있게 답할 수 있는 후속 질문:
|
||||
- ca-tmpl은 어떤 runtime config 오류를 startup에서 막는가?
|
||||
- liveness와 readiness health group을 왜 나누는가?
|
||||
- Flyway migration 실패가 어떻게 startup failure와 exit code로 연결되는가?
|
||||
- 다음 글로 넘길 부분:
|
||||
- Kubernetes production probe tuning.
|
||||
- rolling update와 graceful shutdown 실측.
|
||||
- DB migration 운영 runbook과 장애 복구 사례.
|
||||
|
||||
## 게시 체크리스트 / Publish checklist
|
||||
|
||||
- [x] 모든 사실 주장에 canonical 링크 있음
|
||||
- [x] 사실 vs 의견 분리 명시됨
|
||||
- [x] 금지 마케팅 표현 없음
|
||||
- [x] 코드 예제 출처 명시
|
||||
- [x] 타깃 독자 가정과 톤 일치
|
||||
- [x] `/lint` 통과
|
||||
- [ ] 게시 URL 기록 (게시 후):
|
||||
|
||||
## Related / 관련
|
||||
|
||||
- 후속 글 후보: [[wiki/blog/ca-tmpl-config-and-adapter-templates-2026-07-02]]
|
||||
- 후속 글 후보: [[wiki/blog/ca-tmpl-devops-ci-supply-chain-dx-2026-07-02]]
|
||||
@@ -1 +0,0 @@
|
||||
../../vault/40-publish/blog/ca-tmpl-sample-fixture-and-adoption-2026-07-02.md
|
||||
@@ -0,0 +1,158 @@
|
||||
---
|
||||
title: Sample Fixture를 버리는 예제가 아니라 Adoption 계약으로 만들기
|
||||
source_type: blog
|
||||
status: verified
|
||||
confidence: high
|
||||
tags: [blog, ca-tmpl, sample-fixture, adoption]
|
||||
related_projects: [ca-tmpl]
|
||||
last_reviewed: 2026-07-03
|
||||
canonical_sources:
|
||||
- wiki/projects/ca-tmpl/sample-fixture-and-adoption
|
||||
audience: backend-engineer
|
||||
target_publish:
|
||||
status_label: ready
|
||||
---
|
||||
|
||||
# Sample Fixture를 버리는 예제가 아니라 Adoption 계약으로 만들기
|
||||
|
||||
## Parent / 부모 (필수)
|
||||
|
||||
- 핵심 canonical: [[wiki/projects/ca-tmpl/sample-fixture-and-adoption]]
|
||||
- 관련 개념 문서: [[wiki/concepts/sample-fixture-and-adoption]] - sample fixture/adoption의 일반 배경. 현재 이 글의 구현 사실 근거는 verified project canonical에 둔다.
|
||||
|
||||
## 타깃 독자 / Target reader
|
||||
|
||||
- 독자 profile: template project의 sample domain을 어떻게 유지/제거할지 고민하는 개발자.
|
||||
- 이미 안다고 가정하는 것: sample app, fixture, template adoption.
|
||||
- 처음 듣는다고 가정하는 것: sample을 데모가 아니라 architecture rule과 operational contract를 검증하는 corpus로 사용하는 방식.
|
||||
|
||||
## 도입 / Hook
|
||||
|
||||
Template repository의 sample code는 애매합니다. 남겨두면 실제 서비스 코드처럼 오해받고, 지우면 skeleton이 정말 동작하는지 보여줄 corpus가 사라집니다. 특히 Clean Architecture skeleton에서는 sample이 단순 CRUD 데모를 넘어 envelope, authorization, transaction, idempotency, outbox, OpenAPI snapshot 같은 계약을 실제 흐름으로 건드리는 역할을 합니다.
|
||||
|
||||
ca-tmpl은 sample을 “나중에 지울 예제”로만 보지 않았습니다. `sample-portfolio` module을 fixture로 유지하고, 동시에 `sampleOffTest`로 sample이 빠진 classpath에서도 core test suite가 컴파일/실행되는지 확인합니다. sample-on과 sample-off를 둘 다 검증하는 구조입니다. 이 글은 sample fixture를 adoption 계약으로 다루는 이유와, 아직 실제 외부 프로젝트 adoption 경험으로 말하면 안 되는 부분을 정리합니다.
|
||||
|
||||
## 본문 outline / Body outline
|
||||
|
||||
1. sample domain의 목적 - 데모가 아니라 contract proof.
|
||||
2. sample-on과 sample-off를 둘 다 검증하는 이유.
|
||||
3. `sampleFixture` configuration과 `sampleOffTest` source set.
|
||||
4. `SampleRemovalSmokeContractTest`가 막는 회귀.
|
||||
5. 외부 adoption 사례는 없음.
|
||||
|
||||
## 본문 / Body
|
||||
|
||||
좋은 skeleton에는 작동하는 예제가 필요합니다. 문서만 보고 architecture rule을 이해하기는 어렵습니다. ca-tmpl의 `sample-portfolio`는 WorkLog 도메인을 통해 use case, controller, persistence adapter, id generation, validation, idempotency, outbox, OpenAPI snapshot 같은 표면을 실제로 건드립니다. 그래서 sample은 “보여주기 화면”이 아니라 contract를 깨뜨렸을 때 테스트가 반응하는 corpus입니다.
|
||||
|
||||
하지만 sample이 production runtime에 섞이면 다른 문제가 생깁니다. downstream project가 template을 가져간 뒤에도 sample package가 core module의 production dependency에 남아 있으면, sample을 지우는 순간 build가 깨질 수 있습니다. 더 나쁘게는 production app이 sample route나 sample bean을 몰래 품은 채 출발할 수 있습니다. 그래서 ca-tmpl은 sample 제거를 runtime toggle이 아니라 build/test classpath 문제로 다룹니다.
|
||||
|
||||
핵심은 `sampleFixture` configuration과 `sampleOffTest`입니다. ordinary test는 sample fixture를 볼 수 있습니다. sample-on axis에서 sample이 contract corpus로 작동해야 하기 때문입니다. 반면 `sampleOffTest`는 같은 app-bootstrap core test source를 sample-portfolio 없이 컴파일하고 실행합니다. 즉 sample이 빠져도 core skeleton이 sample type에 의존하지 않는지 확인합니다.
|
||||
|
||||
`SampleRemovalSmokeContractTest`는 이 경계를 여러 방식으로 확인합니다. production module의 build.gradle에서 `sample-portfolio`가 test 또는 sampleFixture scope 밖으로 들어오지 않는지 봅니다. app-bootstrap core test가 `dev.caskeleton.sample.portfolio.*`를 import하지 않는지도 확인합니다. `sampleOffTest` source set과 task가 선언되어 있는지, CI workflow에 `sample-off` job과 `./gradlew :app-bootstrap:sampleOffTest`가 있는지도 검사합니다.
|
||||
|
||||
GitHub Actions에도 sample-off axis가 있습니다. ordinary quality-gates job은 sample-on axis이고, `sample-off` job은 sample-portfolio가 compile/runtime classpath에 없는 상태에서 `:app-bootstrap:sampleOffTest`와 architecture dependency matrix를 돌립니다. 이것은 실제 외부 프로젝트 adoption을 검증했다는 뜻은 아닙니다. 하지만 template 내부에서는 “sample을 지워도 core가 sample에 기대지 않는다”는 방향을 테스트로 표현합니다.
|
||||
|
||||
이 방식은 sample을 무조건 오래 남기자는 뜻도 아닙니다. downstream project에서는 sample을 지울 수 있습니다. 다만 지우기 전에 sample-off build가 green이어야 합니다. sample을 먼저 지워서 어떤 계약이 깨졌는지 모르게 만드는 것보다, sample-on으로 reference behavior를 보고 sample-off로 제거 가능성을 확인하는 편이 안전합니다.
|
||||
|
||||
주의할 점도 있습니다. canonical에는 예전 `sample-ticket` 12 scenario matrix 같은 계획성 문장과 현재 `sample-portfolio` 구현이 함께 남아 있습니다. 이 글에서 구현 사실로 말할 수 있는 것은 `sample-portfolio`, `sampleFixture`, `sampleOffTest`, `SampleRemovalSmokeContractTest`, CI sample-off job, 로컬 `./gradlew check` 범위입니다. 외부 프로젝트가 ca-tmpl을 adoption했고 도입 시간이 줄었다는 식의 주장은 아직 없습니다.
|
||||
|
||||
## 코드 예제 / Code samples (있다면)
|
||||
|
||||
```groovy
|
||||
// 출처: [[wiki/projects/ca-tmpl/sample-fixture-and-adoption]]
|
||||
// 실제 파일: app-bootstrap/build.gradle, ca-tmpl @f6fbd4e196b4
|
||||
configurations {
|
||||
sampleFixture {
|
||||
canBeConsumed = false
|
||||
canBeResolved = false
|
||||
}
|
||||
}
|
||||
|
||||
sourceSets {
|
||||
sampleOffTest {
|
||||
java.srcDirs = sourceSets.test.java.srcDirs
|
||||
resources.srcDirs = sourceSets.test.resources.srcDirs
|
||||
compileClasspath += sourceSets.main.output
|
||||
runtimeClasspath += sourceSets.main.output
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```groovy
|
||||
// 출처: [[wiki/projects/ca-tmpl/sample-fixture-and-adoption]]
|
||||
// 실제 파일: app-bootstrap/build.gradle, ca-tmpl @f6fbd4e196b4
|
||||
dependencies {
|
||||
sampleFixture project(':sample-portfolio')
|
||||
}
|
||||
|
||||
tasks.register('sampleOffTest', Test) {
|
||||
description = 'Compiles and runs the core test suite without sample-portfolio on the classpath.'
|
||||
testClassesDirs = sourceSets.sampleOffTest.output.classesDirs
|
||||
classpath = sourceSets.sampleOffTest.runtimeClasspath
|
||||
systemProperty 'ca.sample.mode', 'off'
|
||||
}
|
||||
```
|
||||
|
||||
```java
|
||||
// 출처: [[wiki/projects/ca-tmpl/sample-fixture-and-adoption]]
|
||||
// 실제 파일: app-bootstrap/.../SampleRemovalSmokeContractTest.java, ca-tmpl @f6fbd4e196b4
|
||||
void sampleClassIsAbsentFromTheSampleOffTestClasspath() {
|
||||
Assumptions.assumeTrue(
|
||||
"off".equals(System.getProperty("ca.sample.mode")),
|
||||
"sample classpath absence is verified only by sampleOffTest");
|
||||
|
||||
assertThat(isClassPresent("dev.caskeleton.sample.portfolio.SamplePortfolioApplication"))
|
||||
.as("sampleOffTest must not contain the sample-portfolio jar")
|
||||
.isFalse();
|
||||
}
|
||||
```
|
||||
|
||||
```yaml
|
||||
# 출처: [[wiki/projects/ca-tmpl/sample-fixture-and-adoption]]
|
||||
# 실제 파일: .github/workflows/ci-quality-gates.yml, ca-tmpl @f6fbd4e196b4
|
||||
sample-off:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- name: sampleOffTest + clean architecture dependency matrix
|
||||
working-directory: src
|
||||
run: ./gradlew :app-bootstrap:sampleOffTest verifyCleanArchitectureDependencies --no-daemon --stacktrace
|
||||
```
|
||||
|
||||
## Sources / 근거 (canonical 인용 필수, derived layer 의무)
|
||||
|
||||
- [[wiki/projects/ca-tmpl/sample-fixture-and-adoption]] - 이 글의 1차 canonical. `sample-portfolio`, sample fixture/adoption decision, `sampleFixture`, `sampleOffTest`, `SampleRemovalSmokeContractTest`, CI sample-off job, 외부 adoption 미검증 경계를 따른다.
|
||||
- [[wiki/concepts/sample-fixture-and-adoption]] - 관련 개념 문서. template sample과 adoption strategy의 일반 배경으로만 둔다.
|
||||
|
||||
## 사실 vs 의견 / Fact vs opinion 구분
|
||||
|
||||
- 사실: ca-tmpl에는 `sample-portfolio` module, `sampleFixture` configuration, `sampleOffTest` task, `SampleRemovalSmokeContractTest`, CI `sample-off` job이 존재한다. 근거: [[wiki/projects/ca-tmpl/sample-fixture-and-adoption]]
|
||||
- 사실: `./gradlew check`가 2026-07-02 기준 통과했고, sample-off 관련 task가 check graph에 포함되어 실행된 것으로 기록되어 있다. 근거: [[wiki/projects/ca-tmpl/sample-fixture-and-adoption]]
|
||||
- 사실: 외부 프로젝트 adoption 사례, hosted release 차단 사례, adoption 시간 측정값은 없다. 근거: [[wiki/projects/ca-tmpl/sample-fixture-and-adoption]]
|
||||
- 의견: sample은 빨리 지울 데모보다 architecture contract를 증명하는 corpus로 남기는 편이 skeleton 학습에 유리하다.
|
||||
- 알지 못하는 것: 실제 template consumer의 migration friction, sample 제거에 걸린 시간, 조직별 adoption pattern.
|
||||
|
||||
## 답할 수 있는 범위 / Answer boundary
|
||||
|
||||
- 자신 있게 답할 수 있는 후속 질문:
|
||||
- sample domain이 어떤 contract를 검증하는 corpus인가?
|
||||
- sample-on과 sample-off를 둘 다 검증하는 이유는 무엇인가?
|
||||
- `sampleOffTest`가 runtime toggle이 아니라 classpath contract인 이유는 무엇인가?
|
||||
- 다음 글로 넘길 부분:
|
||||
- 실제 외부 프로젝트 adoption report.
|
||||
- sample 제거 자동화 script.
|
||||
- Backstage나 Cookiecutter 같은 generator형 adoption과의 비교.
|
||||
|
||||
## 게시 체크리스트 / Publish checklist
|
||||
|
||||
- [x] 모든 사실 주장에 canonical 링크 있음
|
||||
- [x] 사실 vs 의견 분리 명시됨
|
||||
- [x] 금지 마케팅 표현 없음
|
||||
- [x] 코드 예제 출처 명시
|
||||
- [x] 타깃 독자 가정과 톤 일치
|
||||
- [x] `/lint` 통과
|
||||
- [ ] 게시 URL 기록 (게시 후):
|
||||
|
||||
## Related / 관련
|
||||
|
||||
- 후속 글 후보: [[wiki/blog/ca-tmpl-clean-architecture-package-layout-2026-07-02]]
|
||||
- 후속 글 후보: [[wiki/blog/ca-tmpl-devops-ci-supply-chain-dx-2026-07-02]]
|
||||
@@ -1 +0,0 @@
|
||||
../../vault/40-publish/blog/ca-tmpl-security-baseline-jwt-actuator-secrets-2026-07-02.md
|
||||
@@ -0,0 +1,164 @@
|
||||
---
|
||||
title: Security Baseline을 JWT, Actuator, Secrets로 나누기
|
||||
source_type: blog
|
||||
status: verified
|
||||
confidence: high
|
||||
tags: [blog, ca-tmpl, security, jwt, actuator, secrets]
|
||||
related_projects: [ca-tmpl]
|
||||
last_reviewed: 2026-07-03
|
||||
canonical_sources:
|
||||
- wiki/projects/ca-tmpl/security-baseline-jwt-actuator-secrets
|
||||
audience: backend-engineer
|
||||
target_publish:
|
||||
status_label: ready
|
||||
---
|
||||
|
||||
# Security Baseline을 JWT, Actuator, Secrets로 나누기
|
||||
|
||||
## Parent / 부모 (필수)
|
||||
|
||||
- 핵심 canonical: [[wiki/projects/ca-tmpl/security-baseline-jwt-actuator-secrets]]
|
||||
- 관련 개념 문서: [[wiki/concepts/security-baseline-jwt-actuator-secrets]] - JWT Resource Server, actuator 노출, secret source/rotation의 일반 배경. 현재 이 글의 구현 사실 근거는 verified project canonical에 둔다.
|
||||
|
||||
## 타깃 독자 / Target reader
|
||||
|
||||
- 독자 profile: Spring Boot skeleton에 보안 baseline을 넣으려는 백엔드 엔지니어.
|
||||
- 이미 안다고 가정하는 것: JWT, OAuth2 Resource Server, Spring Security filter chain, actuator, 환경 변수 기반 secret 주입.
|
||||
- 처음 듣는다고 가정하는 것: security baseline을 인증 설정 하나가 아니라 데이터면 인증/인가, 제어면 actuator, secret lifecycle의 세 계약으로 나누는 방식.
|
||||
|
||||
## 도입 / Hook
|
||||
|
||||
Spring Boot 프로젝트에 보안을 붙인다고 하면 보통 `SecurityFilterChain`부터 떠올립니다. JWT를 검증하고, public path를 열고, 나머지는 인증을 요구하면 일단 그림은 그려집니다. 그런데 운영 관점에서 보면 그 정도로는 baseline이라고 부르기 어렵습니다. 인증 실패가 어떤 JSON shape으로 내려가는지, actuator endpoint가 앱 트래픽과 같은 경계에 놓이는지, secret rotation을 runtime reload로 볼지 restart-only로 볼지까지 같이 정해야 합니다.
|
||||
|
||||
ca-tmpl은 이 문제를 세 표면으로 나눴습니다. 데이터면은 JWT Resource Server와 AuthN/AuthZ 실패 envelope으로, 제어면은 management actuator chain으로, secret은 `SecretSource`와 restart-only guard로 다룹니다. 이 글은 ca-tmpl에 실제로 구현되고 로컬 검증된 범위와, 아직 IdP/secret manager 운영 경험처럼 말하면 안 되는 범위를 분리합니다.
|
||||
|
||||
## 본문 outline / Body outline
|
||||
|
||||
1. security baseline은 인증 설정 하나가 아니다.
|
||||
2. 데이터면: JWT Resource Server와 filter-layer error envelope.
|
||||
3. 제어면: actuator를 별도 security chain으로 본다.
|
||||
4. secret: source abstraction과 restart-only rotation guard.
|
||||
5. 구현된 baseline과 운영 미검증 범위를 분리한다.
|
||||
|
||||
## 본문 / Body
|
||||
|
||||
보안 baseline을 좁게 잡으면 “JWT를 검증한다”가 전부가 됩니다. 하지만 skeleton/template에서는 다음 프로젝트가 무엇을 가져가야 하는지까지 보여줘야 합니다. ca-tmpl의 기준은 세 가지였습니다. 첫째, 사용자 요청이 들어오는 데이터면 인증/인가를 stateless JWT Resource Server로 고정합니다. 둘째, actuator 같은 제어면은 일반 API와 다른 노출 정책을 갖게 합니다. 셋째, secret은 문자열 설정값이 아니라 source와 reload 정책이 있는 runtime 계약으로 봅니다.
|
||||
|
||||
데이터면의 핵심은 `adapter-web`의 `SecurityConfig`와 `JwtDecoderConfig`입니다. `SecurityConfig`는 `exceptionHandling`과 `oauth2ResourceServer` 양쪽에 같은 entry point와 access denied handler를 연결합니다. Spring Security filter layer에서 발생한 401/403은 `@ControllerAdvice`까지 내려오지 않는 경우가 많습니다. 그래서 filter layer 자체가 ca-tmpl의 API error envelope을 쓰도록 entry point/denied handler를 맞춘 것입니다.
|
||||
|
||||
JWT decoder도 framework 기본값에만 맡기지 않습니다. `JwtDecoderConfig`는 `SupplierJwtDecoder`를 사용해 JWKS discovery를 기동 시점이 아니라 첫 decode 시점으로 미룹니다. validator chain에는 60초 clock skew, issuer validation, 선택적 audience validation이 명시됩니다. 여기서 구현된 것은 “JWT 검증 baseline”입니다. 외부 IdP 운영, JWKS rotation latency, unknown `kid` 상황의 실측값은 아직 없습니다.
|
||||
|
||||
제어면은 actuator입니다. ca-tmpl의 `ManagementSecurityConfig`는 actuator endpoint용 `SecurityFilterChain`을 `@Order(0)`으로 별도 구성합니다. `health`, `info`, `prometheus`는 allowlist로 열고, `POST/DELETE /actuator/loggers/**`는 deny합니다. 이 결정의 요지는 “actuator도 Spring Security가 보호한다”가 아니라, application API와 다른 security matcher, 다른 노출 정책, 다른 ingress/network boundary를 가져야 한다는 점입니다.
|
||||
|
||||
secret 쪽에서는 `SecretSource` abstraction과 restart-only 원칙이 중요합니다. ca-tmpl은 local `.env`와 prod secret source를 같은 소비자 코드가 보게 하되, runtime reload를 기본 경로로 만들지 않습니다. `SecretReloadContractTest`는 context refresh 이후 property source를 바꿔도 이미 바인딩된 configuration property 값이 바뀌지 않는다는 것을 확인합니다. 또한 Spring Cloud refresh scope machinery가 runtime classpath에 없다는 점도 검증합니다. 이것은 secret manager 연동을 구현했다는 뜻이 아니라, ca-tmpl의 secret 소비 계약이 restart-only라는 뜻입니다.
|
||||
|
||||
이 세 영역을 묶으면 security baseline의 의미가 달라집니다. JWT는 데이터면 인증을 담당하고, actuator는 제어면 노출을 담당하며, secret source는 runtime config lifecycle을 담당합니다. 세 영역은 모두 Spring Boot 설정처럼 보이지만 실패 형태, 네트워크 경계, lifecycle 위험이 다릅니다. ca-tmpl은 그 차이를 문서에만 남기지 않고 `SecurityErrorClassifierTest`, `JwtDecoderConfigTest`, `ActuatorSecurityHttpTest`, `SecretReloadContractTest` 같은 테스트로 일부 고정했습니다.
|
||||
|
||||
주의할 점도 분명합니다. 이 글에서 “구현됐다”고 말할 수 있는 것은 ca-tmpl repo 안의 filter chain, lazy decoder, actuator policy, secret source/reload guard, 로컬 `./gradlew check` 통과 범위입니다. 실제 Keycloak이나 외부 IdP를 붙여 token lifecycle을 검증한 것이 아니고, Vault/AWS Secrets Manager/GCP Secret Manager 통합도 없습니다. actuator endpoint에 대한 침투 테스트나 production metric도 없습니다. security baseline을 설명할 때는 이 경계를 같이 말해야 합니다.
|
||||
|
||||
## 코드 예제 / Code samples (있다면)
|
||||
|
||||
```java
|
||||
// 출처: [[wiki/projects/ca-tmpl/security-baseline-jwt-actuator-secrets]]
|
||||
// 실제 파일: adapter-web/.../auth/SecurityConfig.java, ca-tmpl @f6fbd4e196b4
|
||||
.exceptionHandling(
|
||||
ex ->
|
||||
ex.authenticationEntryPoint(authenticationEntryPoint)
|
||||
.accessDeniedHandler(accessDeniedHandler))
|
||||
.oauth2ResourceServer(
|
||||
oauth ->
|
||||
oauth
|
||||
.authenticationEntryPoint(authenticationEntryPoint)
|
||||
.accessDeniedHandler(accessDeniedHandler)
|
||||
.jwt(jwt -> jwt.jwtAuthenticationConverter(jwtConverter)));
|
||||
```
|
||||
|
||||
```java
|
||||
// 출처: [[wiki/projects/ca-tmpl/security-baseline-jwt-actuator-secrets]]
|
||||
// 실제 파일: adapter-web/.../auth/JwtDecoderConfig.java, ca-tmpl @f6fbd4e196b4
|
||||
return new SupplierJwtDecoder(
|
||||
() -> {
|
||||
NimbusJwtDecoder decoder =
|
||||
NimbusJwtDecoder.withIssuerLocation(settings.issuerUri()).build();
|
||||
decoder.setJwtValidator(jwtValidator(settings.issuerUri(), settings.audience()));
|
||||
return decoder;
|
||||
});
|
||||
|
||||
validators.add(new JwtTimestampValidator(Duration.ofSeconds(60)));
|
||||
validators.add(new JwtIssuerValidator(issuerUri));
|
||||
```
|
||||
|
||||
```java
|
||||
// 출처: [[wiki/projects/ca-tmpl/security-baseline-jwt-actuator-secrets]]
|
||||
// 실제 파일: app-bootstrap/.../management/security/ManagementSecurityConfig.java, ca-tmpl @f6fbd4e196b4
|
||||
http.securityMatcher(EndpointRequest.toAnyEndpoint())
|
||||
.sessionManagement(s -> s.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
|
||||
.authorizeHttpRequests(
|
||||
auth ->
|
||||
auth
|
||||
.requestMatchers(EndpointRequest.to("health", "info", "prometheus"))
|
||||
.permitAll()
|
||||
.requestMatchers(HttpMethod.POST, "/actuator/loggers/**")
|
||||
.denyAll()
|
||||
.requestMatchers(HttpMethod.DELETE, "/actuator/loggers/**")
|
||||
.denyAll()
|
||||
.anyRequest()
|
||||
.authenticated());
|
||||
```
|
||||
|
||||
```java
|
||||
// 출처: [[wiki/projects/ca-tmpl/security-baseline-jwt-actuator-secrets]]
|
||||
// 실제 파일: app-bootstrap/.../contract/SecretReloadContractTest.java, ca-tmpl @f6fbd4e196b4
|
||||
sources.addFirst(
|
||||
new MapPropertySource(
|
||||
"rotated-secret-source",
|
||||
Map.of("secret-reload-probe.value", "rotated-secret")));
|
||||
|
||||
SecretHolder afterRotation = context.getBean(SecretHolder.class);
|
||||
assertThat(afterRotation.value()).isEqualTo("initial-secret");
|
||||
|
||||
assertThatThrownBy(
|
||||
() -> Class.forName("org.springframework.cloud.context.scope.refresh.RefreshScope"))
|
||||
.isInstanceOf(ClassNotFoundException.class);
|
||||
```
|
||||
|
||||
## Sources / 근거 (canonical 인용 필수, derived layer 의무)
|
||||
|
||||
- [[wiki/projects/ca-tmpl/security-baseline-jwt-actuator-secrets]] - 이 글의 1차 canonical. JWT Resource Server, filter-layer envelope, actuator security chain, secret source/reload guard, local verification, IdP/secret manager/prod 미검증 경계를 따른다.
|
||||
- [[wiki/concepts/security-baseline-jwt-actuator-secrets]] - 관련 개념 문서. JWT, actuator, secret rotation의 일반 배경으로만 둔다.
|
||||
|
||||
## 사실 vs 의견 / Fact vs opinion 구분
|
||||
|
||||
- 사실: ca-tmpl에는 `SecurityConfig`, `JwtDecoderConfig`, `SecurityErrorClassifier`, envelope entry point/denied handler, `ManagementSecurityConfig`, `SecretSource*`, `SecretReloadContractTest`가 존재한다. 근거: [[wiki/projects/ca-tmpl/security-baseline-jwt-actuator-secrets]]
|
||||
- 사실: `./gradlew check`가 2026-07-02 기준 통과했고, security/error path, actuator policy, secret source/reload guard 관련 테스트가 canonical에 기록되어 있다. 근거: [[wiki/projects/ca-tmpl/security-baseline-jwt-actuator-secrets]]
|
||||
- 사실: 외부 IdP 운영, JWKS rotation latency, secret manager integration, real secret rotation automation, pentest, prod metric 검증은 없다. 근거: [[wiki/projects/ca-tmpl/security-baseline-jwt-actuator-secrets]]
|
||||
- 의견: skeleton의 security baseline은 JWT 검증 코드보다 실패 계약, control plane 노출, secret lifecycle을 함께 묶을 때 설명력이 높아진다.
|
||||
- 알지 못하는 것: 실제 IdP 장애 상황, secret manager rotation window, actuator 노출 사고 대응 경험.
|
||||
|
||||
## 답할 수 있는 범위 / Answer boundary
|
||||
|
||||
- 자신 있게 답할 수 있는 후속 질문:
|
||||
- filter-layer 401/403을 error envelope으로 맞춘 이유는 무엇인가?
|
||||
- `SupplierJwtDecoder`와 60초 clock skew를 명시한 이유는 무엇인가?
|
||||
- actuator를 일반 API security chain과 분리해서 보는 이유는 무엇인가?
|
||||
- secret runtime reload를 기본 경로로 두지 않은 이유는 무엇인가?
|
||||
- 다음 글로 넘길 부분:
|
||||
- real IdP integration과 token lifecycle.
|
||||
- Vault/Secrets Manager/KMS 통합.
|
||||
- actuator endpoint penetration test나 prod metric 기반 검증.
|
||||
|
||||
## 게시 체크리스트 / Publish checklist
|
||||
|
||||
- [x] 모든 사실 주장에 canonical 링크 있음
|
||||
- [x] 사실 vs 의견 분리 명시됨
|
||||
- [x] 금지 마케팅 표현 없음
|
||||
- [x] 코드 예제 출처 명시
|
||||
- [x] 타깃 독자 가정과 톤 일치
|
||||
- [x] `/lint` 통과
|
||||
- [ ] 게시 URL 기록 (게시 후):
|
||||
|
||||
## Related / 관련
|
||||
|
||||
- 후속 글 후보: [[wiki/blog/ca-tmpl-api-error-envelope-design-2026-07-02]]
|
||||
- 후속 글 후보: [[wiki/blog/ca-tmpl-runtime-container-health-migration-2026-07-02]]
|
||||
- 후속 글 후보: [[wiki/blog/ca-tmpl-config-and-adapter-templates-2026-07-02]]
|
||||
-1
@@ -1 +0,0 @@
|
||||
../../vault/40-publish/blog/ca-tmpl-skeleton-governance-registry-verification-test-scorecard-2026-07-02.md
|
||||
+148
@@ -0,0 +1,148 @@
|
||||
---
|
||||
title: Skeleton Governance를 Registry와 Verification으로 닫기
|
||||
source_type: blog
|
||||
status: verified
|
||||
confidence: high
|
||||
tags: [blog, ca-tmpl, governance, archunit, testing]
|
||||
related_projects: [ca-tmpl]
|
||||
last_reviewed: 2026-07-03
|
||||
canonical_sources:
|
||||
- wiki/projects/ca-tmpl/skeleton-governance-registry-verification-test-scorecard
|
||||
audience: backend-engineer
|
||||
target_publish:
|
||||
status_label: ready
|
||||
---
|
||||
|
||||
# Skeleton Governance를 Registry와 Verification으로 닫기
|
||||
|
||||
## Parent / 부모 (필수)
|
||||
|
||||
- 핵심 canonical: [[wiki/projects/ca-tmpl/skeleton-governance-registry-verification-test-scorecard]]
|
||||
- 관련 개념 문서: [[wiki/concepts/skeleton-governance-registry-verification-test-scorecard]] - registry, verification, test taxonomy, scorecard의 일반 배경. 현재 이 글의 구현 사실 근거는 verified project canonical에 둔다.
|
||||
|
||||
## 타깃 독자 / Target reader
|
||||
|
||||
- 독자 profile: template skeleton의 품질 기준을 registry, test, gate로 유지하려는 백엔드/플랫폼 엔지니어.
|
||||
- 이미 안다고 가정하는 것: Gradle test, ArchUnit, YAML registry, CI gate.
|
||||
- 처음 듣는다고 가정하는 것: governance를 규칙 문서가 아니라 owner, registry row, verification mechanism, test taxonomy로 연결하는 방식.
|
||||
|
||||
## 도입 / Hook
|
||||
|
||||
Skeleton 프로젝트에서 좋은 규칙을 많이 쓰는 것은 어렵지 않습니다. “application layer는 framework에 의존하지 않는다”, “환경 변수는 registry에 등록한다”, “quarantine test는 만료일을 가진다” 같은 문장을 README에 적으면 됩니다. 문제는 시간이 지난 뒤입니다. 규칙은 남아 있는데 owner가 사라지고, gate matrix는 workflow와 어긋나고, registry row는 코드와 다른 이름을 가리키기 시작합니다.
|
||||
|
||||
ca-tmpl은 이 문제를 governance 계약으로 다뤘습니다. registry family를 두고, 각 row가 owner와 required test를 갖게 하며, gate matrix가 실제 Gradle task/test/workflow job과 맞는지 검사합니다. 다만 scorecard badge, 11 gate 전체 hosted release-blocking history, 5분 budget 강제 같은 항목은 아직 구현됐다고 말하면 안 됩니다. 이 글은 구현된 registry/verification slice와 계획으로 남은 governance slice를 분리합니다.
|
||||
|
||||
## 본문 outline / Body outline
|
||||
|
||||
1. governance는 규칙 목록이 아니라 drift를 줄이는 구조다.
|
||||
2. registry는 row owner와 required test를 연결한다.
|
||||
3. verification은 matrix와 실제 task/test/job을 대조한다.
|
||||
4. test taxonomy는 classpath와 boundary를 지킨다.
|
||||
5. scorecard는 아이디어와 자동화 범위를 나눠 말한다.
|
||||
|
||||
## 본문 / Body
|
||||
|
||||
governance라는 단어는 무겁지만, skeleton에서 필요한 질문은 단순합니다. “이 규칙을 누가 소유하는가?”, “이 규칙이 깨지면 어떤 테스트가 실패하는가?”, “문서에 적힌 gate가 실제 CI에 남아 있는가?” ca-tmpl은 이 질문에 답하기 위해 registry, verification, test taxonomy, scorecard를 한 묶음으로 기록했습니다.
|
||||
|
||||
registry 축은 `docs/registries/` 아래의 7개 YAML family에서 시작합니다. `error-codes.yaml`, `env-keys.yaml`, `secrets-classification.yaml`, `headers.yaml`, `mdc-keys.yaml`, `metrics.yaml`, `capabilities.yaml`가 있고, `ContractRegistrySchemaGovernanceTest`가 각 family의 schema owner header, identity column, `owner_branch`, `compatibility_impact`, `required_test` 같은 필드를 확인합니다. 핵심은 registry row가 단순 목록이 아니라 “누가 책임지고 어떤 test가 지키는가”를 담는다는 점입니다.
|
||||
|
||||
이 registry는 모든 것을 해결하지 않습니다. canonical은 markdown SSOT와 YAML registry의 관계, generated constants/code generator, markdown과 YAML의 full drift gate가 아직 남았다고 구분합니다. 따라서 이 글에서 말할 수 있는 것은 7개 registry artifact와 schema governance test가 존재한다는 사실입니다. registry YAML이 모든 계약의 최종 SSOT라고 말하면 범위를 넘습니다.
|
||||
|
||||
verification 축은 `.github/ci-gate-matrix.yml`와 `verify-gate-matrix.sh`에서 잘 드러납니다. matrix row에는 gate id, release blocking 여부, owner branch, mechanism, ref, workflow가 들어갑니다. script는 mechanism별로 실제 존재를 확인합니다. `gradle-custom-task`라면 `tasks.register('<ref>')`가 있어야 하고, `contract-test`라면 test class 파일이 있어야 하며, `workflow-job`이라면 workflow에 job id가 있어야 합니다. 문서와 실행 경로가 벌어지는 것을 줄이려는 구조입니다.
|
||||
|
||||
Gradle 쪽 custom gate도 같은 방향입니다. `verifyEnvKeys`는 `.env`, `application.yml`, `docs/registries/env-keys.yaml` 사이를 맞춥니다. required placeholder가 `.env`에 없거나, `.env`의 `APP_` key가 registry에 없으면 실패합니다. `verifyTrivyignore`, `verifyQuarantineSunset`, `verifyCleanArchitectureDependencies` 같은 task도 같은 계열입니다. 규칙은 글로만 남지 않고 build graph에 들어가야 회귀를 잡습니다.
|
||||
|
||||
test taxonomy는 boundary를 강제하는 쪽에 가깝습니다. `CleanArchitectureTest`, `DisabledAdapterArchitectureTest`, `NamingConventionTest`, `ProductionClassImportOption`, sample-off source set은 production classpath와 test fixture boundary가 섞이는 것을 줄입니다. Testcontainers integration test도 outbox/idempotency 같은 runtime contract를 검증하는 데 쓰입니다. 다만 canonical은 6 level 전체의 budget 측정과 강제 mechanism이 아직 없다고 명시합니다.
|
||||
|
||||
scorecard는 더 조심해서 말해야 합니다. ca-tmpl은 binary pass/fail readiness scorecard를 설계했지만, 별도 CI badge나 자동 산출물까지 구현한 것은 아닙니다. 그래서 이 글에서는 scorecard를 “좋은 방향의 governance 모델”로 설명할 수는 있어도, 자동화된 release readiness dashboard가 존재한다고 쓰면 안 됩니다. 현재 구현의 중심은 registry와 verification, 그리고 일부 Gradle/test gate입니다.
|
||||
|
||||
결국 ca-tmpl의 skeleton governance는 개발자의 선의에만 기대지 않으려는 시도입니다. registry row에 owner와 required test를 붙이고, gate matrix와 실제 task/test/job을 대조하며, architecture boundary를 ArchUnit으로 고정합니다. 구현된 것은 이 정도입니다. 조직 전체 rollout, 장기적 defect 감소, hosted release gate 차단 이력은 아직 별도의 근거가 필요합니다.
|
||||
|
||||
## 코드 예제 / Code samples (있다면)
|
||||
|
||||
```yaml
|
||||
# 출처: [[wiki/projects/ca-tmpl/skeleton-governance-registry-verification-test-scorecard]]
|
||||
# 실제 파일: .github/ci-gate-matrix.yml, ca-tmpl @f6fbd4e196b4
|
||||
gates:
|
||||
- id: architecture-test
|
||||
release_blocking: true
|
||||
owner_branch: feature-architecture-enforcement-rules
|
||||
mechanism: contract-test
|
||||
ref: app-bootstrap/src/test/java/dev/caskeleton/bootstrap/architecture/CleanArchitectureTest.java
|
||||
runs_in: ci-quality-gates
|
||||
```
|
||||
|
||||
```java
|
||||
// 출처: [[wiki/projects/ca-tmpl/skeleton-governance-registry-verification-test-scorecard]]
|
||||
// 실제 파일: app-bootstrap/.../contract/ContractRegistrySchemaGovernanceTest.java, ca-tmpl @f6fbd4e196b4
|
||||
private static final List<Registry> REGISTRIES =
|
||||
List.of(
|
||||
new Registry("error-codes.yaml", "errors", "code"),
|
||||
new Registry("env-keys.yaml", "env_keys", "name"),
|
||||
new Registry("secrets-classification.yaml", "secrets", "name"),
|
||||
new Registry("headers.yaml", "headers", "name"),
|
||||
new Registry("mdc-keys.yaml", "mdc_keys", "key"),
|
||||
new Registry("metrics.yaml", "metrics", "name"),
|
||||
new Registry("capabilities.yaml", "capabilities", "name"));
|
||||
```
|
||||
|
||||
```groovy
|
||||
// 출처: [[wiki/projects/ca-tmpl/skeleton-governance-registry-verification-test-scorecard]]
|
||||
// 실제 파일: src/build.gradle, ca-tmpl @f6fbd4e196b4
|
||||
tasks.register('verifyEnvKeys') {
|
||||
description = 'Verifies src/.env covers application.yml placeholders and every APP_ key is registered.'
|
||||
|
||||
File envFile = file("${rootProject.projectDir}/.env")
|
||||
File appYml = file("${rootProject.projectDir}/app-bootstrap/src/main/resources/application.yml")
|
||||
File registryFile = file("${rootProject.projectDir}/../docs/registries/env-keys.yaml")
|
||||
}
|
||||
```
|
||||
|
||||
```bash
|
||||
# 출처: [[wiki/projects/ca-tmpl/skeleton-governance-registry-verification-test-scorecard]]
|
||||
# 실제 파일: .github/scripts/verify-gate-matrix.sh, ca-tmpl @f6fbd4e196b4
|
||||
# Cross-checks every row of .github/ci-gate-matrix.yml against reality:
|
||||
# gradle-custom-task -> a tasks.register('<ref>') exists
|
||||
# contract-test -> the <ref> test-class file exists under src/
|
||||
# workflow-job -> the <ref> job id exists in .github/workflows/<runs_in>.yml
|
||||
```
|
||||
|
||||
## Sources / 근거 (canonical 인용 필수, derived layer 의무)
|
||||
|
||||
- [[wiki/projects/ca-tmpl/skeleton-governance-registry-verification-test-scorecard]] - 이 글의 1차 canonical. registry files, schema governance test, gate matrix, Gradle verification tasks, test taxonomy, scorecard 미자동화 경계를 따른다.
|
||||
- [[wiki/concepts/skeleton-governance-registry-verification-test-scorecard]] - 관련 개념 문서. governance/test taxonomy/scorecard의 일반 배경으로만 둔다.
|
||||
|
||||
## 사실 vs 의견 / Fact vs opinion 구분
|
||||
|
||||
- 사실: ca-tmpl에는 7개 registry family, `.github/ci-gate-matrix.yml`, `ContractRegistrySchemaGovernanceTest`, registry/gate 관련 contract tests, 여러 Gradle verification task가 존재한다. 근거: [[wiki/projects/ca-tmpl/skeleton-governance-registry-verification-test-scorecard]]
|
||||
- 사실: `./gradlew check`가 2026-07-02 기준 통과했고, `verifyCleanArchitectureDependencies`, `verifyEnvKeys`, `verifyQuarantineSunset`, `verifyReadmeCommands`, `verifyTrivyignore`가 canonical에 기록되어 있다. 근거: [[wiki/projects/ca-tmpl/skeleton-governance-registry-verification-test-scorecard]]
|
||||
- 사실: scorecard CI badge/auto artifact, 11 gate 전체 hosted release-blocking history, generated constants/code generator 전체, 5분 budget 강제는 구현됐다고 말할 수 없다. 근거: [[wiki/projects/ca-tmpl/skeleton-governance-registry-verification-test-scorecard]]
|
||||
- 의견: skeleton governance는 규칙 문서보다 owner와 verification mechanism을 같이 남길 때 오래 유지된다.
|
||||
- 알지 못하는 것: 팀 단위 rollout 효과, 장기 defect 감소율, 실제 release 차단 사례.
|
||||
|
||||
## 답할 수 있는 범위 / Answer boundary
|
||||
|
||||
- 자신 있게 답할 수 있는 후속 질문:
|
||||
- registry row에 owner와 required test를 두는 이유는 무엇인가?
|
||||
- gate matrix와 실제 Gradle/test/workflow를 대조하는 이유는 무엇인가?
|
||||
- ArchUnit/test taxonomy가 skeleton governance에서 맡는 역할은 무엇인가?
|
||||
- 다음 글로 넘길 부분:
|
||||
- scorecard badge와 자동 산출물.
|
||||
- multi-team governance process.
|
||||
- hosted release gate 차단 이력.
|
||||
|
||||
## 게시 체크리스트 / Publish checklist
|
||||
|
||||
- [x] 모든 사실 주장에 canonical 링크 있음
|
||||
- [x] 사실 vs 의견 분리 명시됨
|
||||
- [x] 금지 마케팅 표현 없음
|
||||
- [x] 코드 예제 출처 명시
|
||||
- [x] 타깃 독자 가정과 톤 일치
|
||||
- [x] `/lint` 통과
|
||||
- [ ] 게시 URL 기록 (게시 후):
|
||||
|
||||
## Related / 관련
|
||||
|
||||
- 후속 글 후보: [[wiki/blog/ca-tmpl-devops-ci-supply-chain-dx-2026-07-02]]
|
||||
- 후속 글 후보: [[wiki/blog/ca-tmpl-sample-fixture-and-adoption-2026-07-02]]
|
||||
- 후속 글 후보: [[wiki/blog/ca-tmpl-knowledge-capture-workflow-2026-07-02]]
|
||||
@@ -1 +0,0 @@
|
||||
../../vault/40-publish/blog/ca-tmpl-streaming-response-support-2026-07-02.md
|
||||
@@ -0,0 +1,144 @@
|
||||
---
|
||||
title: Streaming Response를 지원하지 않는 결정도 계약이다
|
||||
source_type: blog
|
||||
status: verified
|
||||
confidence: high
|
||||
tags: [blog, ca-tmpl, streaming, archunit, api-design]
|
||||
related_projects: [ca-tmpl]
|
||||
last_reviewed: 2026-07-03
|
||||
canonical_sources:
|
||||
- wiki/projects/ca-tmpl/streaming-response-support
|
||||
audience: backend-engineer
|
||||
target_publish:
|
||||
status_label: ready
|
||||
---
|
||||
|
||||
# Streaming Response를 지원하지 않는 결정도 계약이다
|
||||
|
||||
## Parent / 부모 (필수)
|
||||
|
||||
- 핵심 canonical: [[wiki/projects/ca-tmpl/streaming-response-support]]
|
||||
- 관련 개념 문서: [[wiki/concepts/streaming-response-patterns]] - SSE/WebSocket/long-polling/chunked transfer의 일반 trade-off. 현재 이 글의 구현 사실 근거는 verified project canonical에 둔다.
|
||||
|
||||
## 타깃 독자 / Target reader
|
||||
|
||||
- 독자 profile: template skeleton에서 streaming/SSE/WebSocket response를 언제 열지 고민하는 백엔드 엔지니어.
|
||||
- 이미 안다고 가정하는 것: `SseEmitter`, `ResponseBodyEmitter`, WebSocket, `StreamingResponseBody`.
|
||||
- 처음 듣는다고 가정하는 것: “지원하지 않음”도 문서 문장이 아니라 build-time rule로 고정할 수 있다는 관점.
|
||||
|
||||
## 도입 / Hook
|
||||
|
||||
기술 선택은 보통 “무엇을 지원할 것인가”로 기록됩니다. 그런데 skeleton에서는 “지금은 열지 않을 것”도 중요한 결정입니다. SSE나 WebSocket을 한 번 열면 응답 envelope, timeout, heartbeat, reconnect, observability, connection cap, reverse proxy 설정까지 같이 따라옵니다. use case가 없는데 surface만 열면 템플릿은 빨리 무거워집니다.
|
||||
|
||||
ca-tmpl은 streaming response를 지원하지 않는다는 결정을 그냥 README에 쓰지 않았습니다. production code가 `SseEmitter`, `ResponseBodyEmitter`, Spring/Jakarta WebSocket surface를 import하면 ArchUnit rule이 잡도록 했습니다. 단, 대용량 다운로드용 `StreamingResponseBody`는 차단하지 않았습니다. 이 글은 “미지원도 계약이 될 수 있다”는 관점과, 어디까지가 실제 구현인지 정리합니다.
|
||||
|
||||
## 본문 outline / Body outline
|
||||
|
||||
1. 미지원도 설계 결정이다.
|
||||
2. streaming이 깨뜨리는 기존 request-response baseline.
|
||||
3. 차단 대상과 제외 대상 - `SseEmitter`/WebSocket은 막고 `StreamingResponseBody`는 막지 않는다.
|
||||
4. ArchUnit rule과 violations-as-data fixture로 검증한다.
|
||||
5. 나중에 streaming을 열려면 필요한 선행 계약.
|
||||
|
||||
## 본문 / Body
|
||||
|
||||
Streaming은 매력적인 기능입니다. LLM token streaming, 실시간 알림, export 진행률처럼 server가 client에게 계속 event를 보내야 하는 use case가 생기면 request-response만으로는 답답합니다. 하지만 skeleton의 default surface로 넣기에는 비용이 큽니다. event envelope을 어떻게 만들지, error를 mid-stream에서 어떻게 표현할지, trace id는 connection 단위인지 event 단위인지, proxy timeout과 heartbeat는 어떻게 둘지 정해야 합니다.
|
||||
|
||||
ca-tmpl은 현재 sample fixture에 server-push use case가 없기 때문에 streaming을 기본 지원하지 않기로 했습니다. 여기서 핵심은 “아직 안 만들었다”가 아니라 “지금은 열지 않는다는 결정을 build-time rule로 고정했다”입니다. production code가 `SseEmitter`를 import하거나, `ResponseBodyEmitter`를 쓰거나, Spring/Jakarta WebSocket package에 의존하면 ArchUnit rule이 실패합니다.
|
||||
|
||||
차단 대상은 이벤트/server-push streaming입니다. `SseEmitter`는 Server-Sent Events surface이고, `ResponseBodyEmitter`는 incremental object emit surface이며, WebSocket은 full-duplex connection model입니다. 이 셋은 request-response API baseline과 다른 운영 계약을 요구합니다. ca-tmpl은 이 표면을 기본 skeleton에 열지 않았습니다.
|
||||
|
||||
반대로 `StreamingResponseBody`는 차단하지 않습니다. 이름은 비슷하지만, ca-tmpl project canonical은 이를 대용량 파일 다운로드나 chunked body처럼 request-response 모델을 유지하는 관심사로 봅니다. 이벤트를 계속 push하는 계약과, 하나의 요청에 대해 body를 stream으로 쓰는 계약은 다릅니다. 그래서 over-block guard fixture가 있습니다. `StreamingResponseBodyAllowedFixture`는 streaming ban rule이 이 허용 케이스를 잡지 않아야 통과합니다.
|
||||
|
||||
이 구조가 좋은 이유는 “금지 rule이 진짜로 작동하는가”까지 테스트한다는 점입니다. `ArchitectureViolationFixtureTest`는 `SseEmitterUsingFixture`, `ResponseBodyEmitterUsingFixture`, Spring WebSocket fixture, Jakarta WebSocket fixture를 의도적 위반 데이터로 둡니다. 각 rule이 이 fixture를 잡는지 확인하고, WebSocket은 Spring glob과 Jakarta glob을 따로 가져와 vacuous pass를 줄입니다. 동시에 `StreamingResponseBody`는 잡지 않는지 확인합니다.
|
||||
|
||||
나중에 streaming을 열 수 없는 것은 아닙니다. 다만 그때는 단순히 controller return type을 바꾸는 일이 아닙니다. SSE인지 WebSocket인지, event envelope을 기존 `{ success, data, meta }`와 어떻게 맞출지, per-event trace를 만들지, reconnect와 timeout, connection cap, reverse proxy 설정을 어떻게 둘지 결정해야 합니다. ca-tmpl 문서는 이 지원 계약을 planned/open 범위로 남겨 두고 있습니다.
|
||||
|
||||
따라서 이 글의 결론은 “streaming은 나쁘다”가 아닙니다. ca-tmpl의 결론은 더 좁습니다. 현재 skeleton의 sync request-response baseline에서는 server-push streaming을 기본 surface로 열지 않고, 그 미지원 상태가 우연히 깨지지 않도록 ArchUnit으로 막습니다. 운영 streaming endpoint, connection load, SSE/WebSocket 장애 대응은 이 글에서 말할 수 있는 범위가 아닙니다.
|
||||
|
||||
## 코드 예제 / Code samples (있다면)
|
||||
|
||||
```java
|
||||
// 출처: [[wiki/projects/ca-tmpl/streaming-response-support]]
|
||||
// 실제 파일: app-bootstrap/.../CleanArchitectureTest.java, ca-tmpl @f6fbd4e196b4
|
||||
static final ArchRule NO_SSE_EMITTER =
|
||||
noClasses()
|
||||
.that()
|
||||
.resideInAPackage("dev.caskeleton..")
|
||||
.should()
|
||||
.dependOnClassesThat()
|
||||
.haveFullyQualifiedName("org.springframework.web.servlet.mvc.method.annotation.SseEmitter");
|
||||
```
|
||||
|
||||
```java
|
||||
// 출처: [[wiki/projects/ca-tmpl/streaming-response-support]]
|
||||
// 실제 파일: app-bootstrap/.../CleanArchitectureTest.java, ca-tmpl @f6fbd4e196b4
|
||||
static final ArchRule NO_WEBSOCKET_HANDLER =
|
||||
noClasses()
|
||||
.that()
|
||||
.resideInAPackage("dev.caskeleton..")
|
||||
.should()
|
||||
.dependOnClassesThat()
|
||||
.resideInAnyPackage("org.springframework.web.socket..", "jakarta.websocket..");
|
||||
```
|
||||
|
||||
```java
|
||||
// 출처: [[wiki/projects/ca-tmpl/streaming-response-support]]
|
||||
// 실제 파일: app-bootstrap/.../ArchitectureViolationFixtureTest.java, ca-tmpl @f6fbd4e196b4
|
||||
void noWebsocketHandlerCatchesJakartaWebsocketFixture() {
|
||||
EvaluationResult result =
|
||||
CleanArchitectureTest.NO_WEBSOCKET_HANDLER.evaluate(JAKARTA_WEBSOCKET_FIXTURE_ONLY);
|
||||
|
||||
assertThat(result.hasViolation()).isTrue();
|
||||
}
|
||||
```
|
||||
|
||||
```java
|
||||
// 출처: [[wiki/projects/ca-tmpl/streaming-response-support]]
|
||||
// 실제 파일: app-bootstrap/.../StreamingResponseBodyAllowedFixture.java, ca-tmpl @f6fbd4e196b4
|
||||
public class StreamingResponseBodyAllowedFixture {
|
||||
public StreamingResponseBody allowed() {
|
||||
return outputStream -> outputStream.write("data".getBytes());
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Sources / 근거 (canonical 인용 필수, derived layer 의무)
|
||||
|
||||
- [[wiki/projects/ca-tmpl/streaming-response-support]] - 이 글의 1차 canonical. streaming 미지원 결정, ArchUnit import-ban rule, violations-as-data fixture, `StreamingResponseBody` 제외 경계, local verification, 운영 미검증 범위를 따른다.
|
||||
- [[wiki/concepts/streaming-response-patterns]] - 관련 개념 문서. SSE/WebSocket/long-polling/chunked transfer의 일반 trade-off 배경으로만 둔다.
|
||||
|
||||
## 사실 vs 의견 / Fact vs opinion 구분
|
||||
|
||||
- 사실: ca-tmpl에는 `NO_SSE_EMITTER`, `NO_RESPONSE_BODY_EMITTER`, `NO_WEBSOCKET_HANDLER` ArchUnit rule과 streaming violation fixtures, `StreamingResponseBody` over-block guard fixture가 존재한다. 근거: [[wiki/projects/ca-tmpl/streaming-response-support]]
|
||||
- 사실: 구현된 것은 streaming 지원이 아니라 streaming 미지원을 강제하는 build-time guard다. 근거: [[wiki/projects/ca-tmpl/streaming-response-support]]
|
||||
- 사실: 실제 SSE/WebSocket endpoint, connection load test, production streaming metric은 없다. 근거: [[wiki/projects/ca-tmpl/streaming-response-support]]
|
||||
- 의견: skeleton 초기 surface에서는 real-time use case가 나타나기 전까지 server-push streaming을 닫아두는 편이 계약을 단순하게 유지한다.
|
||||
- 알지 못하는 것: 실제 streaming workload 요구사항, proxy timeout tuning, per-event tracing 운영 효과.
|
||||
|
||||
## 답할 수 있는 범위 / Answer boundary
|
||||
|
||||
- 자신 있게 답할 수 있는 후속 질문:
|
||||
- 왜 streaming을 지금 열지 않았는가?
|
||||
- 어떤 Spring/Jakarta streaming surface를 ArchUnit으로 막았는가?
|
||||
- 왜 `StreamingResponseBody`는 차단하지 않았는가?
|
||||
- violations-as-data fixture가 vacuous pass를 어떻게 줄이는가?
|
||||
- 다음 글로 넘길 부분:
|
||||
- SSE/WebSocket을 실제로 열 때 필요한 API envelope와 observability 계약.
|
||||
- connection cap, heartbeat, reconnect, proxy timeout 설계.
|
||||
- production streaming endpoint 검증.
|
||||
|
||||
## 게시 체크리스트 / Publish checklist
|
||||
|
||||
- [x] 모든 사실 주장에 canonical 링크 있음
|
||||
- [x] 사실 vs 의견 분리 명시됨
|
||||
- [x] 금지 마케팅 표현 없음
|
||||
- [x] 코드 예제 출처 명시
|
||||
- [x] 타깃 독자 가정과 톤 일치
|
||||
- [x] `/lint` 통과
|
||||
- [ ] 게시 URL 기록 (게시 후):
|
||||
|
||||
## Related / 관련
|
||||
|
||||
- 후속 글 후보: [[wiki/blog/ca-tmpl-api-error-envelope-design-2026-07-02]]
|
||||
- 후속 글 후보: [[wiki/blog/ca-tmpl-runtime-container-health-migration-2026-07-02]]
|
||||
@@ -1 +0,0 @@
|
||||
../../vault/40-publish/blog/ca-tmpl-transaction-boundary-abstraction-2026-07-02.md
|
||||
@@ -0,0 +1,201 @@
|
||||
---
|
||||
title: Transaction을 Annotation이 아니라 Application Port로 다루기
|
||||
source_type: blog
|
||||
status: verified
|
||||
confidence: high
|
||||
tags: [blog, ca-tmpl, transaction, clean-architecture]
|
||||
related_projects: [ca-tmpl]
|
||||
last_reviewed: 2026-07-02
|
||||
canonical_sources:
|
||||
- wiki/projects/ca-tmpl/transaction-boundary-abstraction
|
||||
audience: backend-engineer
|
||||
target_publish:
|
||||
status_label: ready
|
||||
---
|
||||
|
||||
# Transaction을 Annotation이 아니라 Application Port로 다루기
|
||||
|
||||
## Parent / 부모 (필수)
|
||||
|
||||
- 핵심 canonical: [[wiki/projects/ca-tmpl/transaction-boundary-abstraction]] — ca-tmpl `TransactionPort`, Spring adapter, ArchUnit rule, local verification 범위.
|
||||
- 관련 개념 문서: [[wiki/concepts/transaction-boundary-abstraction]] — Spring transaction boundary 대안 비교. 현재 concept 문서는 `draft`이므로 이 글의 구현 사실 근거는 verified project canonical에 둔다.
|
||||
|
||||
## 타깃 독자 / Target reader
|
||||
|
||||
- 독자 profile: Clean Architecture에서 transaction boundary를 application layer에 어떻게 둘지 고민하는 백엔드 엔지니어.
|
||||
- 이미 안다고 가정하는 것: `@Transactional`, propagation, read/write transaction.
|
||||
- 처음 듣는다고 가정하는 것: `TransactionPort`로 framework 의존을 adapter에 밀어내는 방식.
|
||||
|
||||
## 도입 / Hook
|
||||
|
||||
- 문제 / 궁금증: `@Transactional`은 편하지만 application core가 Spring에 묶일 수 있다.
|
||||
- 이 글이 답하는 것: ca-tmpl이 transaction boundary를 port로 추상화하고 어떤 범위를 검증했는지.
|
||||
- 이 글이 답하지 않는 것: 모든 DB vendor isolation tuning.
|
||||
|
||||
## 본문 outline / Body outline
|
||||
|
||||
1. transaction boundary는 use case 책임이다.
|
||||
2. Spring annotation을 core에 두지 않는 이유.
|
||||
3. `TransactionPort.inRead`/`inWrite` 류의 모델.
|
||||
4. propagation/isolation의 owner 분리.
|
||||
5. local verification과 운영 DB 검증 경계.
|
||||
|
||||
## 본문 / Body
|
||||
|
||||
Spring Boot에서 transaction을 다루는 가장 익숙한 방법은 `@Transactional`입니다. service method에 annotation을 붙이면 Spring AOP proxy가 method 호출을 감싸고, commit과 rollback을 처리합니다. 실무에서 널리 쓰이고, 단순 CRUD에서는 이 방식이 가장 읽기 쉽습니다.
|
||||
|
||||
그런데 Clean Architecture 관점에서는 질문이 하나 생깁니다. application layer가 Spring transaction annotation을 직접 import해도 괜찮은가? ca-tmpl은 이 질문에 대해 보수적인 답을 택했습니다. application core가 Spring transaction API를 직접 알지 않도록 `TransactionPort`를 두고, 실제 Spring transaction 실행은 persistence adapter의 `SpringTransactionPort`가 맡게 했습니다.
|
||||
|
||||
여기서 핵심은 `@Transactional`이 나쁘다는 주장이 아닙니다. Spring의 declarative transaction은 표준적이고 좋은 도구입니다. 다만 ca-tmpl은 skeleton template입니다. skeleton은 새 프로젝트가 어떤 adapter와 운영 계약을 붙이더라도 application core의 dependency direction이 유지되어야 합니다. 그래서 transaction도 repository나 HTTP client처럼 port 뒤로 밀어내는 쪽을 선택했습니다.
|
||||
|
||||
`TransactionPort`의 표면은 작습니다. write use case는 `inWrite`, read use case는 `inRead`, 독립 commit이 필요한 outbox/audit/compensation 흐름은 `inNew`를 사용합니다. callback은 `Supplier<T>` 또는 `Runnable`입니다. checked exception을 port signature에 노출하지 않고, runtime exception은 Spring transaction template을 통해 rollback되고 다시 전파됩니다. 이 API만 보면 application은 Spring의 propagation enum이나 `TransactionTemplate`을 알 필요가 없습니다.
|
||||
|
||||
Spring 구현체는 adapter-persistence 쪽에 있습니다. 현재 코드에서는 `SpringTransactionPort`가 `PlatformTransactionManager`를 주입받고, write/read/requires-new용 `TransactionTemplate`을 미리 만들어 둡니다. write는 `PROPAGATION_REQUIRED` + readOnly false, read는 `PROPAGATION_REQUIRED` + readOnly true, requires-new는 `PROPAGATION_REQUIRES_NEW` + readOnly false입니다. 모두 `ISOLATION_READ_COMMITTED`를 명시합니다.
|
||||
|
||||
미리 만들어 둔 template을 쓰는 이유도 중요합니다. `TransactionTemplate`은 설정을 가진 객체입니다. 호출할 때마다 같은 template의 propagation/readOnly/isolation을 바꾸는 방식은 동시성 상황에서 읽기 어려운 race를 만들 수 있습니다. ca-tmpl은 mode별 template을 분리해서 “이 method는 어떤 transaction mode로 실행되는가”를 코드 구조로 고정합니다.
|
||||
|
||||
use case 쪽에서는 `@UseCaseCapability`가 같이 등장합니다. 이 annotation은 use case의 transaction mode, idempotency, repository access, 외부 outbound 허용 여부를 드러냅니다. 그러면 class 이름이나 body를 끝까지 읽지 않아도 이 use case가 read인지 write인지, repository를 쓰는지, 외부 호출을 하는지 볼 수 있습니다. 그리고 ArchUnit은 이 선언과 실제 `TransactionPort` 호출이 맞는지 검사합니다.
|
||||
|
||||
예를 들어 `CreateWorkLogUseCase`는 `transactionMode = WRITE`, `repositoryAccess = WRITE_REPOSITORY`를 선언하고 `tx.inWrite(...)` 안에서 aggregate 저장과 outbox append를 함께 수행합니다. 반대로 query use case는 `tx.inRead(...)`를 사용합니다. ca-tmpl은 application package에서 `org.springframework.transaction.annotation.Transactional`에 의존하는 것도 ArchUnit으로 막습니다. 즉 annotation을 몰래 붙여서 port를 우회하는 경로를 build-time에 차단합니다.
|
||||
|
||||
하지만 `TransactionPort`가 항상 더 좋은 선택이라는 뜻은 아닙니다. framework 교체 가능성이 낮고, 팀이 Spring transaction에 익숙하며, 대부분이 단순 CRUD라면 `@Transactional`을 직접 쓰는 편이 더 단순합니다. `TransactionPort`는 interface, adapter 구현, rule, test를 추가합니다. 이 비용은 skeleton처럼 경계를 학습하고 재사용해야 하는 프로젝트에서는 설명 가능하지만, 모든 팀의 기본값이 될 필요는 없습니다.
|
||||
|
||||
검증 범위도 분명히 나눠야 합니다. ca-tmpl에는 `TransactionPort`, `SpringTransactionPort`, capability annotation, ArchUnit rule, unit test가 존재하고 로컬/dev 수준으로 검증됐습니다. 하지만 운영 배포는 없고, 실 DB connection에서 `readOnly`가 flush mode를 어떻게 바꾸는지 측정한 자료도 없습니다. `REQUIRES_NEW`가 outbox/audit에서 실제 connection pool을 얼마나 쓰는지도 별도 통합 검증 대상입니다.
|
||||
|
||||
정리하면 ca-tmpl의 transaction boundary 결정은 “Spring을 쓰지 않겠다”가 아닙니다. Spring transaction은 adapter에서 사용합니다. 대신 application core는 “나는 read transaction이 필요하다”, “나는 write transaction이 필요하다”라는 의도만 port로 말합니다. 이 작은 우회 덕분에 application layer의 dependency rule, use case capability, ArchUnit fitness function이 한 줄로 이어집니다.
|
||||
|
||||
## 코드 예제 / Code samples (있다면)
|
||||
|
||||
```java
|
||||
// 출처: [[wiki/projects/ca-tmpl/transaction-boundary-abstraction]]
|
||||
// 실제 파일: application-core/.../TransactionPort.java, ca-tmpl @f6fbd4e196b4
|
||||
public interface TransactionPort {
|
||||
<T> T inWrite(Supplier<T> action);
|
||||
<T> T inRead(Supplier<T> action);
|
||||
<T> T inNew(Supplier<T> action);
|
||||
|
||||
default void inWrite(Runnable action) { ... }
|
||||
default void inRead(Runnable action) { ... }
|
||||
default void inNew(Runnable action) { ... }
|
||||
}
|
||||
```
|
||||
|
||||
```java
|
||||
// 출처: [[wiki/projects/ca-tmpl/transaction-boundary-abstraction]]
|
||||
// 실제 파일: adapter-persistence-rdbms/.../SpringTransactionPort.java, ca-tmpl @f6fbd4e196b4
|
||||
@Component
|
||||
public class SpringTransactionPort implements TransactionPort {
|
||||
private final TransactionTemplate writeTemplate;
|
||||
private final TransactionTemplate readTemplate;
|
||||
private final TransactionTemplate requiresNewTemplate;
|
||||
|
||||
public SpringTransactionPort(PlatformTransactionManager transactionManager) {
|
||||
this.writeTemplate = template(transactionManager, TransactionMode.WRITE,
|
||||
TransactionDefinition.PROPAGATION_REQUIRED, false);
|
||||
this.readTemplate = template(transactionManager, TransactionMode.READ_ONLY,
|
||||
TransactionDefinition.PROPAGATION_REQUIRED, true);
|
||||
this.requiresNewTemplate = template(transactionManager, TransactionMode.REQUIRES_NEW,
|
||||
TransactionDefinition.PROPAGATION_REQUIRES_NEW, false);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```java
|
||||
// 출처: [[wiki/projects/ca-tmpl/transaction-boundary-abstraction]]
|
||||
// 실제 파일: application-core/.../UseCaseCapability.java, ca-tmpl @f6fbd4e196b4
|
||||
@Retention(RetentionPolicy.RUNTIME)
|
||||
@Target(ElementType.TYPE)
|
||||
public @interface UseCaseCapability {
|
||||
TransactionMode transactionMode();
|
||||
Idempotency idempotency();
|
||||
RepositoryAccess repositoryAccess();
|
||||
boolean externalOutboundAllowed() default false;
|
||||
}
|
||||
```
|
||||
|
||||
```java
|
||||
// 출처: [[wiki/projects/ca-tmpl/transaction-boundary-abstraction]]
|
||||
// 실제 파일: sample-portfolio/.../CreateWorkLogUseCase.java, ca-tmpl @f6fbd4e196b4
|
||||
@UseCaseCapability(
|
||||
transactionMode = TransactionMode.WRITE,
|
||||
idempotency = Idempotency.NOT_IDEMPOTENT,
|
||||
repositoryAccess = RepositoryAccess.WRITE_REPOSITORY)
|
||||
public class CreateWorkLogUseCase implements CommandUseCase<CreateWorkLogCommand, WorkLog> {
|
||||
@Override
|
||||
public WorkLog handle(CreateWorkLogCommand cmd) {
|
||||
return tx.inWrite(
|
||||
() -> {
|
||||
WorkLog saved = repository.save(...);
|
||||
appendReservedEvent(saved);
|
||||
return saved;
|
||||
});
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```java
|
||||
// 출처: [[wiki/projects/ca-tmpl/transaction-boundary-abstraction]]
|
||||
// 실제 파일: app-bootstrap/.../CleanArchitectureTest.java, ca-tmpl @f6fbd4e196b4
|
||||
@ArchTest
|
||||
static final ArchRule APPLICATION_DOES_NOT_USE_SPRING_TRANSACTIONAL_ANNOTATION =
|
||||
noClasses()
|
||||
.that()
|
||||
.resideInAPackage("..application..")
|
||||
.should()
|
||||
.dependOnClassesThat()
|
||||
.haveFullyQualifiedName("org.springframework.transaction.annotation.Transactional")
|
||||
.as("application package must use TransactionPort instead of @Transactional")
|
||||
.allowEmptyShould(true);
|
||||
```
|
||||
|
||||
```java
|
||||
// 출처: [[wiki/projects/ca-tmpl/transaction-boundary-abstraction]]
|
||||
// 실제 파일: app-bootstrap/.../CleanArchitectureTest.java, ca-tmpl @f6fbd4e196b4
|
||||
@ArchTest
|
||||
static final ArchRule USE_CASE_CAPABILITY_MATCHES_TRANSACTION_PORT_BOUNDARY =
|
||||
classes()
|
||||
.that()
|
||||
.areAnnotatedWith(UseCaseCapability.class)
|
||||
.should(callTransactionPortMethodRequiredByCapability())
|
||||
.as("READ_REPOSITORY+READ_ONLY -> inRead, WRITE_REPOSITORY+WRITE -> inWrite");
|
||||
```
|
||||
|
||||
## Sources / 근거 (canonical 인용 필수, derived layer 의무)
|
||||
|
||||
- [[wiki/projects/ca-tmpl/transaction-boundary-abstraction]] — 이 글의 1차 canonical. `TransactionPort`, Spring 구현체, ArchUnit rule, unit/local verification, planned 항목과 과장 금지 경계를 따른다.
|
||||
- [[wiki/concepts/transaction-boundary-abstraction]] — 관련 개념 문서. 현재 `draft`이므로 구현 사실의 출처로 쓰지 않는다.
|
||||
|
||||
## 사실 vs 의견 / Fact vs opinion 구분
|
||||
|
||||
- 사실: ca-tmpl에는 `TransactionPort`, `TransactionMode`, `Isolation`, `UseCaseCapability`, `SpringTransactionPort`, transaction 관련 ArchUnit rule과 unit test가 존재한다. 근거: [[wiki/projects/ca-tmpl/transaction-boundary-abstraction]]
|
||||
- 사실: application package에서 Spring `@Transactional` 의존을 금지하는 ArchUnit rule이 존재한다. 근거: [[wiki/projects/ca-tmpl/transaction-boundary-abstraction]]
|
||||
- 사실: 운영 배포, 실 DB 통합 검증, `readOnly` flush-mode 측정, `inNew` connection pool 실측은 없다. 근거: [[wiki/projects/ca-tmpl/transaction-boundary-abstraction]]
|
||||
- 의견: skeleton template에서는 `@Transactional` 직접 부착보다 port 기반 경계가 학습과 검증에 유리할 수 있다.
|
||||
- 알지 못하는 것: production lock/contention behavior, 실제 DB vendor별 성능 차이.
|
||||
|
||||
## 답할 수 있는 범위 / Answer boundary
|
||||
|
||||
- 자신 있게 답할 수 있는 후속 질문:
|
||||
- 왜 application core에 `@Transactional`을 직접 두지 않았는가?
|
||||
- `TransactionPort.inWrite`/`inRead`/`inNew`는 각각 어떤 의도를 표현하는가?
|
||||
- `SpringTransactionPort`가 mode별 `TransactionTemplate`을 미리 만드는 이유는 무엇인가?
|
||||
- ArchUnit은 transaction boundary를 어디까지 강제하는가?
|
||||
- 다음 글로 넘길 부분:
|
||||
- vendor-specific isolation tuning.
|
||||
- 실 DB/Testcontainers 기반 `readOnly`/`REQUIRES_NEW` 동작 검증.
|
||||
- outbox와 transaction boundary의 통합 검증.
|
||||
|
||||
## 게시 체크리스트 / Publish checklist
|
||||
|
||||
- [x] 모든 사실 주장에 canonical 링크 있음
|
||||
- [x] 사실 vs 의견 분리 명시됨
|
||||
- [x] 금지 마케팅 표현 없음
|
||||
- [x] 코드 예제 출처 명시
|
||||
- [x] 타깃 독자 가정과 톤 일치
|
||||
- [x] `/lint` 통과
|
||||
- [ ] 게시 URL 기록 (게시 후):
|
||||
|
||||
## Related / 관련
|
||||
|
||||
- 후속 글 후보: [[wiki/blog/ca-tmpl-transactional-outbox-pattern-2026-07-02]]
|
||||
- 관련 개념 문서: [[wiki/concepts/transaction-boundary-abstraction]]
|
||||
@@ -1 +0,0 @@
|
||||
../../vault/40-publish/blog/ca-tmpl-transactional-outbox-pattern-2026-07-02.md
|
||||
@@ -0,0 +1,177 @@
|
||||
---
|
||||
title: Transactional Outbox를 Polling 계약으로 구현하기
|
||||
source_type: blog
|
||||
status: verified
|
||||
confidence: high
|
||||
tags: [blog, ca-tmpl, outbox, event-driven, transaction]
|
||||
related_projects: [ca-tmpl]
|
||||
last_reviewed: 2026-07-02
|
||||
canonical_sources:
|
||||
- wiki/projects/ca-tmpl/transactional-outbox-pattern
|
||||
audience: backend-engineer
|
||||
target_publish:
|
||||
status_label: ready
|
||||
---
|
||||
|
||||
# Transactional Outbox를 Polling 계약으로 구현하기
|
||||
|
||||
## Parent / 부모 (필수)
|
||||
|
||||
- 핵심 canonical: [[wiki/projects/ca-tmpl/transactional-outbox-pattern]]
|
||||
- 관련 개념 문서: [[wiki/concepts/transactional-outbox-pattern]] — 일반 outbox 개념. 현재 이 글의 구현 사실 근거는 verified project canonical에 둔다.
|
||||
|
||||
## 타깃 독자 / Target reader
|
||||
|
||||
- 독자 profile: DB transaction과 message publish 사이의 원자성 문제를 skeleton에서 다루려는 백엔드 엔지니어.
|
||||
- 이미 안다고 가정하는 것: transaction, message broker, retry.
|
||||
- 처음 듣는다고 가정하는 것: SKIP LOCKED polling과 per-aggregate FIFO gate를 계약으로 다루는 방식.
|
||||
|
||||
## 도입 / Hook
|
||||
|
||||
- 문제 / 궁금증: DB commit과 broker publish를 한 번에 성공시키는 것은 생각보다 어렵다.
|
||||
- 이 글이 답하는 것: ca-tmpl이 transactional outbox를 어떤 구현과 검증 범위로 잡았는지.
|
||||
- 이 글이 답하지 않는 것: production broker throughput과 장애 복구 실측.
|
||||
|
||||
## 본문 outline / Body outline
|
||||
|
||||
1. dual write 문제와 outbox의 목적.
|
||||
2. outbox table과 polling worker.
|
||||
3. SKIP LOCKED와 per-aggregate FIFO gate.
|
||||
4. idempotency/retry/DLQ와의 경계.
|
||||
5. local verification과 운영 검증 없음.
|
||||
|
||||
## 본문 / Body
|
||||
|
||||
DB 저장과 message publish를 한 use case에서 함께 처리하면 dual-write 문제가 생깁니다. 예를 들어 주문을 DB에 저장한 직후 broker로 이벤트를 보내야 한다고 해보겠습니다. DB commit은 성공했는데 publish 직전에 프로세스가 죽으면, DB에는 상태가 남지만 외부 시스템은 그 사실을 모릅니다. 반대로 publish는 성공했는데 DB transaction이 rollback되면, 외부 시스템은 존재하지 않는 변경을 본 셈이 됩니다.
|
||||
|
||||
Transactional outbox는 이 틈을 줄이는 패턴입니다. business table을 수정하는 같은 DB transaction 안에서 outbox table에도 이벤트 row를 저장합니다. 그리고 별도의 relay가 outbox row를 읽어 broker로 publish합니다. 여기서 중요한 점은 “DB와 broker를 한 transaction으로 묶는다”가 아닙니다. broker publish는 여전히 바깥 작업입니다. 대신 DB 안에 “나중에 반드시 publish해야 할 사실”을 남겨서, 프로세스 실패 후에도 다시 이어갈 수 있게 만듭니다.
|
||||
|
||||
ca-tmpl은 outbox를 문서상의 패턴으로만 두지 않고, application port와 persistence adapter, PostgreSQL migration, relay use case, scheduler/metrics까지 구현했습니다. `OutboxAppendPort`는 business operation이 여는 `TransactionPort.inWrite(...)` 안에서 호출되어야 합니다. 구현체가 자기 transaction을 새로 열지 않는다는 계약도 중요합니다. 같은 write transaction에 aggregate save와 event append가 함께 있어야 dual-write를 줄이는 의미가 생기기 때문입니다.
|
||||
|
||||
outbox row는 상태 머신을 가집니다. 처음에는 `PENDING`이고 relay가 claim하면 `IN_FLIGHT`가 됩니다. publish가 성공하면 `PUBLISHED`, 일시 실패하면 `FAILED`, retry를 모두 소진하면 `DEAD`가 됩니다. `DEAD`는 단순한 로그가 아니라 운영자가 봐야 하는 terminal failure입니다. ca-tmpl 문서와 코드 모두 이 상태를 manual intervention이 필요한 상태로 둡니다.
|
||||
|
||||
claim 단계는 PostgreSQL의 `FOR UPDATE SKIP LOCKED`를 사용합니다. 여러 relay가 동시에 row를 읽을 때, 이미 다른 transaction이 잠근 row를 기다리지 않고 건너뛰게 하는 방식입니다. 이것은 multi-instance relay에서 같은 row를 동시에 claim하는 경합을 줄입니다. 다만 `SKIP LOCKED`가 순서 보존까지 해결하지는 않습니다. 그래서 ca-tmpl query에는 같은 aggregate의 더 이른 미게시 row가 있으면 뒤 row를 claim하지 않는 `NOT EXISTS` gate가 같이 들어갑니다.
|
||||
|
||||
relay use case의 흐름도 의도적으로 짧은 transaction과 바깥 publish를 나눕니다. 먼저 짧은 write transaction에서 batch를 claim합니다. 그다음 publish는 transaction 밖에서 수행합니다. 성공한 row는 다시 짧은 write transaction으로 `PUBLISHED` 처리합니다. publish 실패는 잡아서 `FAILED` 또는 `DEAD`로 바꾸고 error log를 남깁니다. 반대로 publish 성공 후 `markPublished`가 실패하면 예외를 삼키지 않습니다. row가 `IN_FLIGHT`로 남고 timeout 이후 재claim될 수 있기 때문입니다.
|
||||
|
||||
이 구조는 exactly-once delivery를 약속하지 않습니다. outbox relay가 publish 성공 후 상태 갱신에 실패하면 같은 event가 다시 publish될 수 있습니다. 따라서 consumer는 `eventId`나 `idempotencyKey`로 dedupe해야 합니다. ca-tmpl project canonical도 이 지점을 명확히 나눕니다. outbox는 at-least-once delivery를 제공하고, 최종 정합성은 idempotent consumer와 함께 닫힙니다.
|
||||
|
||||
Debezium CDC나 Kafka Connect Outbox SMT도 대안입니다. 하지만 ca-tmpl은 skeleton baseline에서 Kafka Connect cluster, connector, WAL slot 운영을 기본 요구로 두지 않았습니다. 수 초 수준 lag를 허용하는 전제에서는 DB table + polling이 더 작은 운영 단위입니다. 대신 lag SLO가 sub-second로 내려가거나 polling query가 DB load를 만들면 CDC 전환을 검토하는 migration trigger를 문서에 남겼습니다.
|
||||
|
||||
검증 범위는 local/dev입니다. `./gradlew check`가 통과했고, application relay logic, RDBMS adapter, PostgreSQL Testcontainers 기반 row lifecycle과 SKIP LOCKED claim, publish adapter가 테스트되었습니다. 운영 배포, production lag 측정, DLQ 재처리 운영 경험은 없습니다. 따라서 이 글은 “outbox를 운영에서 검증했다”가 아니라 “ca-tmpl skeleton에 outbox polling 계약을 구현하고 로컬 검증했다”까지 말합니다.
|
||||
|
||||
## 코드 예제 / Code samples (있다면)
|
||||
|
||||
```java
|
||||
// 출처: [[wiki/projects/ca-tmpl/transactional-outbox-pattern]]
|
||||
// 실제 파일: application-core/.../OutboxAppendPort.java, ca-tmpl @f6fbd4e196b4
|
||||
public interface OutboxAppendPort {
|
||||
/**
|
||||
* Appends event to the outbox table, participating in the caller's existing
|
||||
* write transaction. Calling outside TransactionPort.inWrite(...) is a
|
||||
* contract violation.
|
||||
*/
|
||||
void append(NewOutboxEvent event);
|
||||
}
|
||||
```
|
||||
|
||||
```java
|
||||
// 출처: [[wiki/projects/ca-tmpl/transactional-outbox-pattern]]
|
||||
// 실제 파일: application-core/.../OutboxEventStatus.java, ca-tmpl @f6fbd4e196b4
|
||||
public enum OutboxEventStatus {
|
||||
PENDING,
|
||||
IN_FLIGHT,
|
||||
PUBLISHED,
|
||||
FAILED,
|
||||
DEAD
|
||||
}
|
||||
```
|
||||
|
||||
```java
|
||||
// 출처: [[wiki/projects/ca-tmpl/transactional-outbox-pattern]]
|
||||
// 실제 파일: adapter-persistence-postgresql/.../PostgreSqlOutboxClaimRepository.java
|
||||
private static final String CLAIM_SQL =
|
||||
"""
|
||||
SELECT * FROM outbox_event o
|
||||
WHERE o.next_attempt_at <= :now
|
||||
AND o.status IN ('PENDING', 'FAILED', 'IN_FLIGHT')
|
||||
AND NOT EXISTS (
|
||||
SELECT 1 FROM outbox_event p
|
||||
WHERE p.aggregate_id = o.aggregate_id
|
||||
AND p.occurred_at < o.occurred_at
|
||||
AND p.status <> 'PUBLISHED'
|
||||
)
|
||||
ORDER BY o.occurred_at ASC
|
||||
LIMIT :limit
|
||||
FOR UPDATE SKIP LOCKED
|
||||
""";
|
||||
```
|
||||
|
||||
```java
|
||||
// 출처: [[wiki/projects/ca-tmpl/transactional-outbox-pattern]]
|
||||
// 실제 파일: application-core/.../PublishPendingOutboxEventsUseCase.java
|
||||
List<OutboxEvent> claimed =
|
||||
tx.inWrite(() -> store.claimBatch(batchSize, now, inFlightTimeout));
|
||||
|
||||
for (OutboxEvent event : sorted) {
|
||||
publishPort.publish(event); // outside transaction
|
||||
tx.inWrite(() -> store.markPublished(event.eventId()));
|
||||
}
|
||||
```
|
||||
|
||||
```sql
|
||||
-- 출처: [[wiki/projects/ca-tmpl/transactional-outbox-pattern]]
|
||||
-- 실제 파일: adapter-persistence-postgresql/.../V3__outbox_event.sql
|
||||
CREATE TABLE outbox_event (
|
||||
event_id varchar(64) NOT NULL,
|
||||
aggregate_id varchar(256) NOT NULL,
|
||||
event_type varchar(256) NOT NULL,
|
||||
payload text NOT NULL,
|
||||
occurred_at timestamptz NOT NULL,
|
||||
status varchar(16) NOT NULL,
|
||||
attempt_count integer NOT NULL DEFAULT 0,
|
||||
next_attempt_at timestamptz NOT NULL,
|
||||
correlation_id varchar(64) NOT NULL,
|
||||
idempotency_key varchar(256) NOT NULL,
|
||||
CONSTRAINT pk_outbox_event PRIMARY KEY (event_id)
|
||||
);
|
||||
```
|
||||
|
||||
## Sources / 근거 (canonical 인용 필수, derived layer 의무)
|
||||
|
||||
- [[wiki/projects/ca-tmpl/transactional-outbox-pattern]] — 이 글의 1차 canonical. outbox 구현, SKIP LOCKED polling, Testcontainers/local verification, prod 미검증 경계를 따른다.
|
||||
- [[wiki/concepts/transactional-outbox-pattern]] — 관련 개념 문서. 구현 사실 출처로 쓰지 않는다.
|
||||
|
||||
## 사실 vs 의견 / Fact vs opinion 구분
|
||||
|
||||
- 사실: ca-tmpl에는 `OutboxAppendPort`, `OutboxStorePort`, `OutboxEventStatus`, `PublishPendingOutboxEventsUseCase`, PostgreSQL `FOR UPDATE SKIP LOCKED` claim repository, outbox migration, publish adapter가 존재한다. 근거: [[wiki/projects/ca-tmpl/transactional-outbox-pattern]]
|
||||
- 사실: `./gradlew check`, application unit test, RDBMS adapter test, PostgreSQL Testcontainers 기반 row lifecycle/claim 검증이 로컬 범위에 포함된다. 근거: [[wiki/projects/ca-tmpl/transactional-outbox-pattern]]
|
||||
- 사실: 운영 배포, production lag 측정, DLQ 재처리 운영 경험은 없다. 근거: [[wiki/projects/ca-tmpl/transactional-outbox-pattern]]
|
||||
- 의견: ca-tmpl 같은 skeleton에서는 Debezium CDC보다 polling outbox가 더 작은 baseline일 수 있다.
|
||||
- 알지 못하는 것: production lag, throughput, broker 장애 상황의 DLQ 운영 결과.
|
||||
|
||||
## 답할 수 있는 범위 / Answer boundary
|
||||
|
||||
- 자신 있게 답할 수 있는 후속 질문:
|
||||
- transactional outbox가 dual-write 문제를 어떻게 줄이는가?
|
||||
- `FOR UPDATE SKIP LOCKED`는 claim 경합에서 무엇을 해결하는가?
|
||||
- per-aggregate FIFO gate가 왜 별도로 필요한가?
|
||||
- 왜 outbox가 exactly-once가 아니라 at-least-once + consumer dedupe인가?
|
||||
- 다음 글로 넘길 부분:
|
||||
- broker-specific scaling.
|
||||
- Debezium CDC/Kafka Connect Outbox SMT 전환.
|
||||
- production lag/DLQ 운영 측정.
|
||||
|
||||
## 게시 체크리스트 / Publish checklist
|
||||
|
||||
- [x] 모든 사실 주장에 canonical 링크 있음
|
||||
- [x] 사실 vs 의견 분리 명시됨
|
||||
- [x] 금지 마케팅 표현 없음
|
||||
- [x] 코드 예제 출처 명시
|
||||
- [x] 타깃 독자 가정과 톤 일치
|
||||
- [x] `/lint` 통과
|
||||
- [ ] 게시 URL 기록 (게시 후):
|
||||
|
||||
## Related / 관련
|
||||
|
||||
- 후속 글 후보: [[wiki/blog/ca-tmpl-idempotency-key-design-2026-07-02]]
|
||||
@@ -1 +0,0 @@
|
||||
../../vault/30-knowledge/concepts/api-error-envelope-design.md
|
||||
@@ -0,0 +1,151 @@
|
||||
---
|
||||
title: API Error Envelope 설계 (custom vs ProblemDetail vs rpc.Status)
|
||||
source_type: llm-generated
|
||||
status: draft
|
||||
confidence: medium
|
||||
tags: [api-design, error-handling, http]
|
||||
related_projects: [ca-skeleton]
|
||||
last_reviewed: 2026-05-22
|
||||
---
|
||||
|
||||
# API Error Envelope 설계 (custom vs ProblemDetail vs rpc.Status)
|
||||
|
||||
> Layer: `wiki/concepts/` — 일반 개념. 특정 프로젝트의 결정/구현 사실은 `wiki/projects/`에서 다룬다.
|
||||
|
||||
## Summary
|
||||
|
||||
API error envelope은 실패 응답의 구조 계약이다. 표준 후보는 RFC 7807 ProblemDetail, Google `rpc.Status`, JSON:API errors, GraphQL errors가 있고, 그 외 대형 서비스의 custom envelope (Stripe / GitHub / 토스페이먼츠 등)이 사실상 진영별 컨벤션으로 자리잡았다. 설계 결정의 핵심 축은 (a) 성공/실패 응답의 대칭 여부, (b) `code` · `category` · `retryable` 같은 운영 메타데이터의 1급 필드 승격 여부, (c) 표준 lock-in과 client SDK 호환성의 trade-off다.
|
||||
|
||||
## Standard (공식 정의)
|
||||
|
||||
### RFC 7807 ProblemDetail (실패 전용 평면)
|
||||
|
||||
IETF 표준. `application/problem+json` media type. 필드: `type` (URI), `title`, `status`, `detail`, `instance`. 모든 필드 optional이고 확장은 top-level에 임의 필드 추가로 한다. RFC 9457로 obsolete되었지만 의미상 호환이며, Spring 6+는 `ProblemDetail` 클래스로 기본 지원한다. 성공 응답에는 적용되지 않고 실패 전용 평면 shape이다.
|
||||
|
||||
### Google `rpc.Status` (gRPC, typed details)
|
||||
|
||||
Google AIP-193. `code` (정수, `google.rpc.Code` enum), `message`, `details: Any[]`. `details`는 `google.protobuf.Any`로 packing되며 표준 detail 타입(`ErrorInfo`, `LocalizedMessage`, `Help`, `RetryInfo`, `QuotaFailure`, `BadRequest`)을 포함한다. `RetryInfo`로 retryable + delay까지 표준화되어 있다. REST/gRPC 양쪽에 동일 모델로 매핑된다.
|
||||
|
||||
### JSON:API errors (배열)
|
||||
|
||||
JSON:API v1.1 spec. top-level에 `errors: []` array 필수. 각 error 객체는 `id`, `links`, `status`, `code`, `title`, `detail`, `source.pointer` (JSON Pointer), `meta` 중 하나 이상을 가진다. `source.pointer`로 form 필드 단위 오류를 가리킨다.
|
||||
|
||||
### GraphQL errors (HTTP 200 + errors field)
|
||||
|
||||
GraphQL Specification (October 2021) §7.1.2. 응답은 `data`와 `errors`를 모두 가질 수 있고, error 객체는 `message` (required), `locations`, `path`, `extensions`를 가진다. transport는 보통 HTTP 200이고 4xx/5xx는 transport-level 실패에만 사용한다.
|
||||
|
||||
### 진영별 custom envelope (표준 아님)
|
||||
|
||||
- **Stripe**: `{ error.{ type, code, decline_code, message, param, doc_url, ... } }`. `type` enum이 사실상 category 역할.
|
||||
- **GitHub**: `{ message, documentation_url, errors[].{ resource, field, code } }`. validation 항목별 풀이가 명시적.
|
||||
- **토스페이먼츠**: `{ code, message }`. 가장 얇은 envelope. retryable/category는 `code` semantic으로 추론.
|
||||
|
||||
이 세 사례는 어떤 IETF/W3C 표준도 따르지 않으며, 각 회사 SDK가 envelope을 흡수하는 전제로 동작한다.
|
||||
|
||||
## 한계 / 주의점
|
||||
|
||||
### Custom envelope
|
||||
|
||||
- 외부 표준이 존재하지 않으므로 client SDK를 직접 작성하거나 envelope 처리 규칙을 client에게 명시적으로 전달해야 한다.
|
||||
- 성공/실패 대칭, `retryable` 1급 같은 운영 친화 결정을 자유롭게 둘 수 있지만 그 비용은 "표준 client 라이브러리 0개"다.
|
||||
|
||||
### RFC 7807 ProblemDetail
|
||||
|
||||
- 실패 전용 평면 shape이므로 "성공도 envelope으로 감싸 `success: true/false`로 분기하고 싶다"는 요구와 구조적으로 충돌한다.
|
||||
- `code` 필드가 표준에 없다 — `type` URI가 식별자다. 짧은 머신리더블 코드를 원하면 확장 필드를 강제해야 하고, 결국 "표준 위에 사실상 custom 레이어"가 된다.
|
||||
- Spring 6+는 기본 활성이므로, custom envelope을 채택한다는 것은 의식적으로 표준 인프라를 비활성화하는 선택이다.
|
||||
- `application/problem+json`을 content-negotiation으로 처리하는 client는 흔하지 않다 — 실질 호환성 이득은 명목 수준에 가깝다.
|
||||
|
||||
### Google `rpc.Status`
|
||||
|
||||
- 본질적으로 gRPC/protobuf 생태계 결합이다. HTTP REST 전용 서비스에 강제하면 `Any` 디코딩 부담이 client에 mismatch로 전가된다.
|
||||
- 표준 detail 타입 카탈로그를 알아야 효용이 발휘되어 학습 곡선이 높다.
|
||||
- 가벼운 CRUD API에는 과한 표현력이다.
|
||||
|
||||
### JSON:API errors
|
||||
|
||||
- `errors[]` array와 `source.pointer`는 항목 단위 오류 표현에 강하지만, `category`/`retryable`이 1급 필드가 아니라 `meta`로 빠진다.
|
||||
- 부분 채택 시 표준성이 사라진다. 완전 채택 시 success response 리소스 객체 구조, sparse fieldsets 등 spec 전체에 lock-in된다.
|
||||
|
||||
### GraphQL errors
|
||||
|
||||
- HTTP 200 + `errors` field가 transport 규약이라 CDN / proxy / observability 도구의 4xx/5xx 기반 알람·캐시·라우팅과 부조화한다.
|
||||
- partial success가 1급 개념이라 REST envelope과 패러다임 자체가 다르다 — REST 컨텍스트에서 직접 비교해 "GraphQL이 옳다/그르다"라고 말할 수 없다.
|
||||
|
||||
### 흔한 오해
|
||||
|
||||
- "Stripe / GitHub / 토스페이먼츠가 그렇게 하니까 industry standard다" — 표준이 아니라 진영별 컨벤션이다. SDK 없이 직접 다루는 client는 거의 없다는 전제 위에서 동작한다.
|
||||
- "ProblemDetail은 잘못된 설계다" — 실패 전용 use case (예: 외부 노출 API, RFC 9457 client 생태계 활용)에서는 유효한 선택이다.
|
||||
|
||||
## Project Application
|
||||
|
||||
- [[wiki/projects/ca-tmpl/api-error-envelope-design]] — ca-tmpl 의사결정 기록 (`verified` — envelope record/handler 코드 구현 + `./gradlew check` 로컬 통과). 실제 구현 범위·검증 수준은 project 문서 참조.
|
||||
- [[raw/project-notes/ca-skeleton-operational-contract]] — §3 Structured API Response Contract / §5 Exception Ownership Contract / §6 Operational Error Category / §29 Topic 4 (custom envelope 결정 라인업)
|
||||
- [[raw/branch-notes/feature-operational-error-observability-foundation]] — envelope schema SSOT
|
||||
- [[raw/branch-notes/feature-boundary-validation-mapping-contract]] — validation error → `error.details` 매핑
|
||||
- [[raw/branch-notes/feature-business-rule-validation-contract]] — business invariant → category 매핑
|
||||
|
||||
위 branch-note들은 success / error 대칭, `error.code` · `error.category` · `error.retryable` · `error.details` 분리, `meta.requestId` / `meta.traceId` / `meta.correlationId` 1급 노출, raw exception / SQL / token / body의 응답 leak 금지를 계약으로 둔다.
|
||||
|
||||
## Claim-backed Knowledge
|
||||
|
||||
> 이 개념 문서의 핵심 설명은 raw source claim 으로 뒷받침되어야 한다.
|
||||
> 공식 문서 claim, 회사 사례 claim, 내 프로젝트 decision 을 분리한다.
|
||||
|
||||
| Knowledge Point | Supporting Claims | Confidence | Notes |
|
||||
|---|---|---|---|
|
||||
| RFC 7807 ProblemDetail은 `application/problem+json` 기반 실패 전용 평면 shape이며 `type` URI가 식별자다 (`code` 필드 없음) | [[raw/official-docs/problem-detail-rfc-7807]], [[raw/official-docs/spring-problem-detail]] | `high` | 공식 표준 (IETF / Spring) — success/error 대칭·머신리더블 `code` 요구와 구조적으로 충돌 |
|
||||
| Google `rpc.Status`는 `RetryInfo` 등 typed detail로 retryable + delay까지 표준화 (REST/gRPC 공통 모델) | [[raw/official-docs/google-api-error-format]] | `high` | 공식 vendor 문서(AIP-193) — 단 protobuf/`Any` 결합이라 HTTP REST 전용에는 과한 표현력 |
|
||||
| JSON:API는 `errors[]` + `source.pointer`(JSON Pointer)로 항목 단위 오류를 가리키지만 `category`/`retryable`이 1급 필드가 아니다 | [[raw/official-docs/json-api-errors-spec]] | `high` | 공식 표준 — 부분 채택 시 표준성 상실, 완전 채택 시 spec 전체 lock-in |
|
||||
| Stripe/GitHub/토스페이먼츠 envelope은 IETF/W3C 표준이 아니라 진영별 컨벤션이며 각 사 SDK가 envelope을 흡수하는 전제로 동작한다 | [[raw/company-tech-blogs/stripe-error-format]], [[raw/company-tech-blogs/github-api-error-format]], [[raw/company-tech-blogs/toss-payments-error-format]] | `medium` | company-case-study — 공식 best practice로 일반화 금지. SDK 부재 client는 거의 없다는 전제 |
|
||||
|
||||
## 내가 설명할 수 있어야 하는 것
|
||||
|
||||
- API error envelope의 후보 표준(RFC 7807 / Google `rpc.Status` / JSON:API / GraphQL errors)의 공식 정의와 각자의 식별자 표현 방식은?
|
||||
- 어떤 문제를 해결하는가 — client가 실패를 어떻게 분기·재시도·관측 가능하게 만드는 구조 계약인가?
|
||||
- 어떤 상황에서는 custom envelope을 쓰면 안 되는가(표준 client 생태계 활용이 우선인 외부 노출 API 등)?
|
||||
- 공식 표준이 말하지 않는 부분(success/error 대칭, `retryable`·`category` 1급화)은 무엇이고 그 비용("표준 client 라이브러리 0개")은 무엇인가?
|
||||
- Stripe/GitHub/토스 사례를 industry standard처럼 일반화하면 안 되는 지점은?
|
||||
- 내 프로젝트에서는 어떤 branch decision(custom envelope 채택 + ProblemDetail 거부)으로 연결됐는가?
|
||||
- 이 개념을 코드/운영에서 검증하려면 무엇을 확인해야 하는가(envelope 직렬화, leak 금지, ProblemDetail 비활성 build-time 강제 등)?
|
||||
|
||||
## Interview Questions
|
||||
|
||||
- 왜 RFC 7807 ProblemDetail을 채택하지 않았는지? 표준을 우회한 비용은 무엇이고, 그 대신 무엇을 얻는지?
|
||||
- `retryable`을 1급 필드로 둔 이유는? client는 `retryable: true`를 받았을 때 어떻게 다르게 동작해야 하는지?
|
||||
- validation error를 `error.details`에 담을 때 GitHub `errors[].{resource, field, code}` 또는 JSON:API `source.pointer`와 비교하면 어떤 형식을 택했고, 왜 그렇게 택했는지?
|
||||
- `error.code`와 `error.category`를 분리한 이유는? client 분기는 어느 쪽으로 하라고 가이드하는지?
|
||||
- 응답에 절대 leak하면 안 되는 항목은? exception class name, stack trace, SQL, token, raw body, upstream raw error body 각각이 왜 금지인지 설명할 수 있는지?
|
||||
|
||||
## Do Not Overclaim
|
||||
|
||||
- "내 envelope이 표준이다" / "ca-tmpl envelope이 IETF 표준 envelope이다"라고 말하면 안 된다. 어떤 표준도 success/error 대칭 + `retryable` 1급 + `category` 1급을 동시에 강제하지 않는다 — 자체 결정일 뿐이다.
|
||||
- "ProblemDetail은 잘못된 설계다"라고 단정하면 안 된다. 실패 전용 평면이라는 그 자체가 결함이 아니며, 외부 표준 client 호환을 우선하는 use case에서는 합리적이다.
|
||||
- "Stripe / GitHub / 토스가 다 custom이니까 표준은 의미 없다"라고 말하면 안 된다. 그들은 SDK가 envelope을 흡수하는 전제 위에 동작하며, 표준 미준수가 정당화되는 것이 아니라 trade-off가 다른 것뿐이다.
|
||||
- Google `rpc.Status`의 `RetryInfo.retry_delay`보다 `retryable: boolean`이 우월하다고 주장하면 안 된다 — 후자는 단순하지만 actionable한 delay 정보를 잃는다.
|
||||
|
||||
## Sources
|
||||
|
||||
### 공식 표준
|
||||
|
||||
- [[raw/official-docs/problem-detail-rfc-7807]] — RFC 7807 (Problem Details for HTTP APIs)
|
||||
- [[raw/official-docs/spring-problem-detail]] — Spring Framework `ProblemDetail` (RFC 9457 기본 지원)
|
||||
- [[raw/official-docs/google-api-error-format]] — Google AIP-193, `google.rpc.Status`
|
||||
- [[raw/official-docs/json-api-errors-spec]] — JSON:API v1.1 Errors
|
||||
- [[raw/official-docs/graphql-errors-spec]] — GraphQL Specification (October 2021) Errors
|
||||
|
||||
### 진영별 사례 (표준 아님)
|
||||
|
||||
- [[raw/company-tech-blogs/stripe-error-format]] — Stripe custom envelope
|
||||
- [[raw/company-tech-blogs/github-api-error-format]] — GitHub REST API error format
|
||||
- [[raw/company-tech-blogs/toss-payments-error-format]] — 토스페이먼츠 `{code, message}`
|
||||
|
||||
### Canonical (프로젝트 결정 사실)
|
||||
|
||||
- [[raw/project-notes/ca-skeleton-operational-contract]] §3 / §5 / §6 / §29 Topic 4
|
||||
|
||||
## Cluster / 묶음
|
||||
|
||||
<!-- GENERATED: derived-blogs:start -->
|
||||
- [[wiki/blog/ca-tmpl-api-error-envelope-design-2026-07-02]]
|
||||
<!-- GENERATED: derived-blogs:end -->
|
||||
@@ -1 +0,0 @@
|
||||
../../vault/30-knowledge/concepts/api-evolution-and-schema.md
|
||||
@@ -0,0 +1,177 @@
|
||||
---
|
||||
title: API Evolution & Schema (compatibility + serialization + HTTP contract surface)
|
||||
source_type: llm-generated
|
||||
status: reviewed
|
||||
confidence: medium
|
||||
tags: [api-design, versioning, schema, deprecation, pagination, conditional-request, http-cache]
|
||||
related_projects: [ca-skeleton]
|
||||
last_reviewed: 2026-06-04
|
||||
---
|
||||
|
||||
# API Evolution & Schema (compatibility + serialization)
|
||||
|
||||
> Layer: `wiki/concepts/` — 일반 개념. 특정 프로젝트의 결정/구현 사실은 `wiki/projects/`에서 다룬다.
|
||||
|
||||
## Summary
|
||||
|
||||
API evolution은 두 축으로 나뉜다. (1) **compatibility / deprecation** — 응답 필드 제거나 의미 변화를 막기 위해 breaking change를 분류하고 migration window 동안 deprecated marker와 Sunset 헤더로 client에게 신호를 보낸다. (2) **schema / serialization** — date·money·enum·null·unknown field의 의미를 framework default에 맡기지 않고 명시 계약으로 고정한다. 대표 결정 라인업은 `90d public + 30d internal migration window`, RFC 8594 `Sunset` 헤더, ISO-8601 offset datetime (UTC default), `BigDecimal` scale 2 + `HALF_UP`, **strict inbound / tolerant outbound** 정책이다.
|
||||
|
||||
## Standard (공식 정의)
|
||||
|
||||
### Compatibility / deprecation 표준 후보
|
||||
|
||||
- **RFC 8594 Sunset header (IETF)**: 응답 헤더로 자원이 응답 불가가 될 시점을 HTTP-date로 알린다. `Sunset` 단독은 *언제* 사라지는지 신호일 뿐이고, deprecation 자체는 별도 `Deprecation` 헤더(IETF draft)로 표시하는 것이 표준 의도다.
|
||||
- **Microsoft REST API versioning policy**: `api-version` query/header를 정식 권고. major version 단위 breaking change 허용, minor/preview는 additive only. preview API는 별도 lifecycle.
|
||||
- **GitHub REST API**: 2022년부터 `X-GitHub-Api-Version: YYYY-MM-DD` 날짜 헤더. 새 버전 release 후 **24개월 EOL** 정책, EOL된 버전 호출은 `410 Gone` 응답. preview API는 `Accept` 헤더 `application/vnd.github.<name>-preview+json`로 옵트인.
|
||||
- **Stripe date-based versioning**: account마다 첫 호출 시 version pin. 이후 새 version이 나와도 client가 명시적으로 upgrade하지 않으면 **freeze forever** (Stripe가 영구적으로 구버전 응답을 유지). 외부 컨슈머 규모가 큰 결제 도메인 특화.
|
||||
- **Google AIP-180 (Backwards compatibility)**: enum value 제거 / 의미 변경 / 응답 필드 제거 / 기본값 변경 / required request field 추가 모두 breaking으로 분류. additive (optional response field 추가)만 minor에 허용.
|
||||
- **Twitter tier-based**: legacy / current / beta 트랙 병렬 운영.
|
||||
- **Spring HATEOAS**: 응답에 `_links`로 다음 자원 URI를 동봉해 client가 version이 아닌 link relation에 결합하게 한다.
|
||||
|
||||
### Schema / serialization 표준 후보
|
||||
|
||||
- **ISO-8601**: date·time·datetime·duration의 wire 표현 표준. offset datetime(`2026-05-22T11:30:00+09:00` 또는 `Z`)이 timezone ambiguity 회피의 정석.
|
||||
- **JSON Schema** (draft 2020-12): JSON payload의 shape 검증 spec. `additionalProperties: false`로 unknown field strict, `nullable` / `required` / `enum`으로 의미 분리.
|
||||
- **OpenAPI 3.1**: JSON Schema 2020-12 정합. response shape SSOT 후보. `deprecated: true` 플래그를 schema/operation 양쪽에 둘 수 있어 deprecation marker 표준 위치가 된다.
|
||||
- **Avro schema evolution**: backward / forward / full compatibility를 schema registry가 자동 검사. 필드 추가/삭제 시 default 의무, alias로 rename. event/outbox 환경에 우위.
|
||||
- **Protobuf**: `reserved` 키워드로 field number와 name 재사용을 영구 차단. wire-format 기반 strict typing.
|
||||
- **Jackson** (Java): `DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES`는 default `true`. 단, `FAIL_ON_NULL_FOR_PRIMITIVES`는 default `false`라 null/missing primitive가 묵시적으로 0이 된다. 출력측은 `SerializationFeature.WRITE_DATES_AS_TIMESTAMPS`(default `false` → `JavaTimeModule` 경유 ISO-8601 문자열, `true` 면 epoch/배열)와 `JsonGenerator.Feature.WRITE_BIGDECIMAL_AS_PLAIN`(default `false` → 큰 값이 지수 표기 `1.23E+10`)이 wire 형식을 좌우한다. 이 둘은 *프레임워크 기본값*이라 버전 업그레이드로 flip 될 수 있으므로 계약을 명시 핀하고 effective bean 동작 테스트로 회귀를 잡는 것이 안전하다.
|
||||
- **Property naming strategy**: Jackson `PropertyNamingStrategies`(camelCase default / `SNAKE_CASE` / `KEBAB_CASE`)는 wire 의 field 이름 컨벤션을 결정한다. 한 번 정하면 client 가 그 이름에 결합하므로 *변경 자체가 breaking* — 전역 strategy 변경은 모든 응답 field rename 과 동치다.
|
||||
- **Null vs absent (`@JsonInclude`)**: `JsonInclude.Include.NON_NULL`/`NON_ABSENT`/`NON_EMPTY` 는 null 또는 빈 값을 출력에서 *생략* 한다. 생략(absent)과 명시적 `null` 은 client 에게 다른 의미(부재 vs 값이 null) 일 수 있어, JSON Merge Patch 같은 부분 갱신 의미가 필요하면 `JsonNullable<T>` 로 3-상태(present-null / present-value / absent)를 구분한다.
|
||||
- **Java BigDecimal**: 금액 계산 표준. `new BigDecimal(double)` 함정 (`0.1` → `0.1000000000000000055511151231257827021181583404541015625`), `setScale(2, RoundingMode.HALF_UP)` 패턴, JSON에서는 string 직렬화로 client 부동소수 손실 회피가 표준 권고.
|
||||
- **Smithy**: AWS의 API modeling DSL. SDK 코드 생성 친화적, 단 외부 ecosystem에서는 OpenAPI보다 미성숙.
|
||||
|
||||
### HTTP contract surface 표준 (conditional request / cache / pagination)
|
||||
|
||||
versioning·schema 와 별개로, HTTP API surface 자체의 일반 계약 표준. (RFC 9110/9111 은 IETF official-standard, AIP 는 Google community guideline)
|
||||
|
||||
- **Conditional request (RFC 9110 §13)**: `ETag` 는 representation 의 opaque validator (weak `W/"..."` 또는 strong). write 는 `If-Match` 로 optimistic concurrency 검증 — condition 이 false 면 **412 Precondition Failed**. read 는 `If-None-Match` 로 cache validation — match 면 **304 Not Modified** (body 없음, client 저장본 사용). RFC 9110 은 `If-Match` 에 *strong comparison* 을 MUST 로 요구한다.
|
||||
- **HTTP caching (RFC 9111 §5.2)**: `Cache-Control` directive — `no-store` (저장 금지, 인증 API 안전 default), `private` (shared cache 저장 금지), `public` (Authorization 있어도 shared cache 허용), `max-age=N` (stale 판정 초). 협상/인증 응답은 `Vary` (RFC 9110 §12.5.5) 로 어떤 request 부분이 content 선택에 영향을 줬는지 명시해 proxy/CDN cache poisoning 을 막는다.
|
||||
- **Pagination (Google AIP-158, JSON:API)**: offset (`page`/`size`) vs cursor (opaque token). AIP-158 은 page token 이 opaque + URL-safe MUST, server-side size cap SHOULD coerce, empty next-token = end-of-collection 을 규정. JSON:API 는 `links` object 안의 `first`/`last`/`prev`/`next` key 위치를 정의. 구체 숫자(size cap, TTL)는 표준이 아닌 구현 trade-off.
|
||||
- **Transport error 의미 구분 (RFC 9110 §15)**: 413 Content Too Large, 406 Not Acceptable (응답 표현 협상 실패) vs 415 Unsupported Media Type (요청 본문 format), 405 Method Not Allowed (+ `Allow` header MUST). 같은 code 로 뭉개면 표준 의미가 손실된다.
|
||||
- **Long-running operation (Google AIP-151 + RFC 9110)**: 비동기 처리는 **202 Accepted** + `Location` polling URL + Operation 객체(`done`/`response`/`error`). `Retry-After` 로 polling interval 권고.
|
||||
|
||||
## 한계 / 주의점
|
||||
|
||||
### Compatibility / deprecation 측
|
||||
|
||||
- **Stripe freeze-forever**: 무기한 구버전 유지 비용이 외부 결제 컨슈머 규모에서만 정당화된다. internal API에 그대로 차용하면 server 코드에 N개 버전 분기를 영구 운반하게 된다.
|
||||
- **GitHub 24개월 EOL + `410 Gone`**: 길어 보이는 EOL window지만 catalog에 EOL 응답 코드(410)를 명시하지 않으면 client 입장에서 *어느 날 갑자기 410*과 다를 바 없다. EOL 응답 코드 자체를 contract에 박는 것이 필요하다.
|
||||
- **Twitter tier-based (legacy/current/beta)**: 트랙별 행위 분기가 server-side 복잡도와 운영 비용을 곱한다. 단일 팀 / internal-first 환경에 과하다.
|
||||
- **Spring HATEOAS (links over versions)**: 이론적으로 우아하지만 실제 client가 `_links`를 dynamic하게 따라가는 경우는 드물고, 학습 곡선과 client 구현 강제 비용이 크다.
|
||||
- **Google AIP-180 `enum value 제거 = breaking`**: client switch/case 누락을 유발하므로 strict 분류가 맞지만, enum value 추가 또한 client 입장에서 unknown enum 처리 정책이 없으면 깨진다 — server-side enum addition을 "additive"로만 분류하는 단순화는 위험하다.
|
||||
- **`Sunset` 단독 사용**: RFC 8594는 *언제 사라지는지*만 알린다. 같은 자원이 *이미 deprecated인지*는 `Deprecation` 헤더로 함께 보내야 정합이다. Sunset만 보내면 "사라질 날짜는 알지만 지금 권장 여부는 모름" 상태가 된다.
|
||||
- **`Sunset` 헤더 단독 사용 금지 — `Deprecation` draft와 paired**: IETF httpapi WG 권고에 따르면 `Sunset` 헤더는 `Deprecation` 헤더(draft-ietf-httpapi-deprecation-header, RFC 9745 진행)와 paired로 송신해야 client tooling이 deprecation 상태를 감지할 수 있다. paired invariant는 "Sunset 시점 ≥ Deprecation 시점". 추가로 `Link: <url>; rel="deprecation"` / `rel="sunset"`을 함께 보내 사람-가독 가이드를 연결한다. ca-tmpl처럼 marker만 OpenAPI에 박고 응답 헤더 paired 송신을 누락하면 외부 client interceptor가 deprecation을 자동 인지하지 못한다.
|
||||
|
||||
### Schema / serialization 측
|
||||
|
||||
- **Avro / Protobuf strict typing**: schema registry가 backward/forward 자동 검사로 강력하나, 외부 REST API가 JSON인 환경에서는 outbox / event 한정 도입이 현실적이다.
|
||||
- **Smithy**: AWS SDK 친화적이지만 외부 ecosystem(예: third-party tooling, doc generator) 성숙도가 OpenAPI 대비 낮다.
|
||||
- **Jackson default**: `FAIL_ON_UNKNOWN_PROPERTIES=true`는 strict inbound와 정합하나, `FAIL_ON_NULL_FOR_PRIMITIVES=false`는 null/empty/missing 분리 정책과 **불일치**다 — 명시적으로 override하지 않으면 contract가 깨진 줄도 모르고 0이 흘러간다.
|
||||
- **"Jackson은 unknown field tolerant가 default"라는 오해**: 보안/계약 측면에서 unknown inbound를 silently 허용하면 typo로 인한 데이터 손실 + payload smuggling 모두 위험. strict inbound가 안전 default.
|
||||
- **JSON 환경의 Protobuf `reserved` 흉내**: Protobuf는 field number / name 재사용을 wire-format 수준에서 영구 차단한다(`reserved 3, 5;` / `reserved "foo";`). OpenAPI 3.1 / JSON Schema 2020-12에는 동등 시맨틱이 없다 — `deprecated: true`는 *비권장* 신호일 뿐 재사용 차단이 아니고, field가 사라지면 schema에서도 사라져 미래 재사용 방지 불가. 현실적 대안은 두 가지: (1) **OpenAPI `x-removed-fields` 같은 Specification Extension**으로 schema SSOT에 catalog를 통합하고 자체 lint로 재사용 검출, (2) **별도 markdown catalog**(예: `docs/removed-fields-catalog.md`)에 제거된 이름/번호/일자 기록 후 CI에서 OpenAPI diff와 cross-check. 둘 다 표준 검증 도구가 없어 자체 도구 작성이 따라온다. (needs-confirmation)
|
||||
- **`new BigDecimal(double)` 함정**: 같은 `0.1`이 `BigDecimal.valueOf(0.1)` (정확)과 `new BigDecimal(0.1)` (부동소수 잔차)으로 갈린다. 코드 review 규칙으로 차단하지 않으면 unit test 통과 + 운영에서 1원 차이 인시던트가 흔하다.
|
||||
- **ISO-8601 offset 없는 datetime**: `2026-05-22T11:30:00`는 표준상 valid이지만 timezone이 누락된다. 서버 timezone에 따라 의미가 달라지므로 contract에서는 offset 필수로 강제해야 한다. 직렬화 형식을 `WRITE_DATES_AS_TIMESTAMPS=false`로만 핀해도 `JavaTimeModule`(`jackson-datatype-jsr310`)이 등록되지 않으면 `LocalDateTime`이 `[2026,5,22,...]` 배열로 직렬화되므로, module 등록 + effective 직렬화 동작 테스트가 함께 필요하다.
|
||||
- **naming strategy 변경 = 전역 breaking change**: snake_case ↔ camelCase 같은 `PropertyNamingStrategy` 전역 변경은 모든 응답 field 이름이 바뀌는 것과 같아 deprecation window 없이 적용하면 client 가 일제히 깨진다. naming 은 초기에 고정하고 이후 변경을 breaking change catalog 대상으로 다뤄야 한다.
|
||||
- **`@JsonInclude(NON_NULL)` 의 의미 손실**: null 생략은 payload 를 줄이지만 "값이 null" 과 "field 부재" 를 구분 불가하게 만든다. 부분 갱신(PATCH/merge-patch) contract 에서는 이 구분이 의미를 가지므로 3-상태(`JsonNullable`/`Optional`) 표현을 별도로 둬야 하고, 무분별한 NON_NULL 전역 적용은 이 의미 분리를 무너뜨린다.
|
||||
|
||||
### 흔한 오해
|
||||
|
||||
- "Stripe 방식이 표준이다" — IETF/W3C 표준이 아니고 진영별 사례다. 외부 결제 컨슈머 규모를 가정한 trade-off의 결과다.
|
||||
- "`Sunset` 헤더만 보내면 deprecation은 끝이다" — 잘못. `Deprecation` 헤더(현재 진행 중인지)와 `Sunset` 헤더(언제 사라지는지)는 함께 사용해야 정합이다.
|
||||
- "Jackson은 unknown field tolerant가 안전한 default다" — 잘못. inbound strict가 보안/계약 안전 default이고, outbound는 schema에 없는 field가 노출되지 않도록 controlled해야 한다(소위 **strict inbound / tolerant outbound**가 아니라 "strict inbound / schema-controlled outbound"가 정확).
|
||||
- "enum 값 추가는 무조건 additive다" — server-side 입장에서는 additive지만 client 입장에서는 unknown enum 처리 정책이 없으면 깨진다. client side에 unknown enum fallback이 contract로 명시되어야 비로소 additive다.
|
||||
|
||||
## Project Application
|
||||
|
||||
- [[wiki/projects/ca-tmpl/api-evolution-and-schema]] — ca-tmpl 의사결정 기록 (현재 `documented-only`, Phase C2 미진입). 실제 구현 여부는 project 문서 참조.
|
||||
- [[raw/project-notes/ca-skeleton-operational-contract]] §13 API Contract Surface / §16 Schema / Serialization Contract / §18 API Compatibility / Deprecation / §29 G-F (외부 근거 인덱스)
|
||||
- [[raw/branch-notes/feature-api-compatibility-deprecation-contract]] — breaking change catalog(7행), 90d/30d migration window, OpenAPI `deprecated: true` marker, Sunset 헤더 채택
|
||||
- [[raw/branch-notes/feature-schema-serialization-contract]] — ISO-8601 offset/UTC, BigDecimal scale 2 + HALF_UP, unknown field strict inbound, null/empty/missing 의미 분리
|
||||
|
||||
위 branch-note들이 (a) breaking change 7 분류 + migration window + deprecation marker 위치, (b) serialization producer 책임(date/time/money/enum/null/unknown)을 계약으로 둔다. canonical 승급 여부와 검증 등급은 해당 project 문서가 판정한다.
|
||||
|
||||
ca-tmpl 의 **HTTP contract surface (versioning/pagination/conditional/cache/OpenAPI)** 는 위 두 축과 달리 실제 코드로 구현·로컬 검증됐다 — 구현 사실과 검증 등급은 [[wiki/projects/ca-tmpl/api-evolution-and-schema]] 의 "API contract baseline 구현" 절 참조.
|
||||
|
||||
## Claim-backed Knowledge
|
||||
|
||||
> 각 Knowledge Point 는 이미 §Sources 에 인용된 자료로만 뒷받침된다. company-tech-blog 출처는 사례일 뿐 official best practice 로 격상하지 않는다.
|
||||
|
||||
| Knowledge Point | Supporting Claims | Confidence | Notes |
|
||||
|---|---|---|---|
|
||||
| `Sunset` 헤더는 자원이 응답 불가가 될 시점을 HTTP-date 로 알리며 `Deprecation` 헤더와 paired 송신해야 client tooling 이 deprecation 상태를 감지 | [[raw/official-docs/compat-rfc-8594-sunset-header]], [[raw/official-docs/sunset-deprecation-headers-paired-usage]] | high | `official-standard`(RFC 8594) + IETF httpapi draft. "Sunset 단독 충분" 금지. invariant: Sunset 시점 ≥ Deprecation 시점 |
|
||||
| Google AIP-180 은 enum 제거/의미변경, 응답 필드 제거, 기본값 변경, required request field 추가를 breaking 으로 분류 | [[raw/official-docs/api-versioning-google-aip-180]] | high | `official-reference` (Google community guideline, IETF/W3C 표준 아님). additive 만 minor 허용 |
|
||||
| Jackson `FAIL_ON_UNKNOWN_PROPERTIES` default `true` (strict inbound) 이나 `FAIL_ON_NULL_FOR_PRIMITIVES` default `false` (null/missing primitive → 묵시적 0) | [[raw/official-docs/schema-jackson-unknown-field-handling]] | high | `official-vendor-doc`. "Jackson default 가 안전" 금지 — 후자는 명시 override 필요 |
|
||||
| `new BigDecimal(double)` 은 부동소수 잔차를 남기므로 `BigDecimal.valueOf` + `setScale(2, HALF_UP)` + JSON string 직렬화 권고 | [[raw/official-docs/schema-bigdecimal-money-serialization-java]] | high | `official-vendor-doc`. client 부동소수 손실 회피 |
|
||||
| ISO-8601 offset datetime 이 timezone ambiguity 회피의 정석, offset 없는 표현은 서버 timezone 의존 | [[raw/official-docs/schema-jackson-unknown-field-handling]] | medium | wire 계약에서 offset 강제 근거 (ISO-8601 일반 상식 + Jackson 직렬화 자료) |
|
||||
| OpenAPI 3.1 은 JSON Schema 2020-12 정합의 machine-readable HTTP API contract 이며 `deprecated: true` marker 를 schema/operation 양쪽에 둘 수 있음 | [[raw/official-docs/openapi-spec-3-1-0]] | high | `official-standard`(OAS/Linux Foundation). "marker 만으로 client 가 알아서 migrate" 금지 |
|
||||
| Protobuf `reserved` 는 field number/name 재사용을 wire-format 수준에서 영구 차단하나 OpenAPI/JSON Schema 에는 동등 시맨틱이 없음 | [[raw/official-docs/schema-protobuf-vs-json-evolution]], [[raw/official-docs/protobuf-reserved-vs-json-openapi-extension]] | medium | `official-reference`. "JSON 에서 완벽 흉내" 금지 — `x-` extension + 자체 lint 필요, needs-confirmation |
|
||||
| RFC 9110 conditional request: `ETag` validator + `If-Match`(write, strong comparison MUST)→412 + `If-None-Match`(read)→304; RFC 9111 cache directive(`no-store`/`private`/`public`/`max-age`) + `Vary` 로 cache poisoning 방지 | [[raw/official-docs/rfc9110-http-semantics]], [[raw/official-docs/rfc9111-http-caching]] | high | `official-standard`(IETF). ca-tmpl 의 weak/lenient `If-Match` 비교는 skeleton 단순화 — project 문서 참조 |
|
||||
| Pagination: AIP-158 은 page token opaque+URL-safe MUST, server-side size cap SHOULD coerce, empty next-token = EoC. JSON:API 는 `links` 의 first/last/prev/next 위치 정의 | [[raw/official-docs/spring-data-pageable-defaults]] (offset/zero-indexed) | medium | `official-vendor-doc`(Spring). size cap 숫자/TTL 은 표준 아닌 구현 trade-off |
|
||||
|
||||
## 내가 설명할 수 있어야 하는 것
|
||||
|
||||
- **API evolution 의 세 영역 분리**: compatibility/deprecation vs schema/serialization vs HTTP contract surface (versioning/pagination/conditional/cache). 세 영역이 framework default 가 아니라 명시 계약이어야 하는 이유.
|
||||
- **`Sunset` vs `Deprecation` 헤더의 역할 분리**와 paired 송신 이유, paired invariant.
|
||||
- **breaking change 분류 기준** (enum 축소/제거, 응답 필드 제거, 기본값 변경, required request field 추가) 과 "internal API 니까 그냥 한다" 가 위험한 이유 (client deploy lag).
|
||||
- **strict inbound / schema-controlled outbound** 의 정확한 의미와 Jackson 의 두 feature default 차이.
|
||||
- **money 직렬화**에서 `double` 위험 / `BigDecimal.valueOf` / HALF_UP / JSON string 직렬화 근거.
|
||||
- **conditional request** 가 DB optimistic lock 과 같은 충돌의 HTTP 표현이라는 점 (ETag → If-Match → 412, If-None-Match → 304), strong vs weak comparison 차이.
|
||||
- **인증 API 의 안전한 cache default = `no-store`** + `Vary` 가 cache poisoning 을 막는 원리.
|
||||
- **offset vs cursor pagination** trade-off, size cap 이 DoS 방어인 이유, page token opacity 의 의미.
|
||||
- **transport error 의미 구분** (406 vs 415, 405 + `Allow`, 413/414) 을 같은 code 로 뭉개면 안 되는 이유.
|
||||
|
||||
## Interview Questions
|
||||
|
||||
- **90d public + 30d internal migration window**의 근거는? 더 짧게/길게 잡으면 어떤 비용이 생기는지? Stripe(freeze forever)나 GitHub(24mo EOL)와 비교했을 때 internal-first 환경에서 90d가 합리적인 이유는?
|
||||
- **`Sunset` 헤더와 `Deprecation` 헤더의 차이**는? 둘 중 하나만 보내면 client 입장에서 어떤 정보가 빠지는지?
|
||||
- **enum value 추가/제거가 breaking change**가 되는 이유는? client side에 unknown enum fallback이 있을 때와 없을 때 분류가 어떻게 달라지는지?
|
||||
- **strict inbound / tolerant outbound**가 무슨 의미인지? Jackson `FAIL_ON_UNKNOWN_PROPERTIES`와 `FAIL_ON_NULL_FOR_PRIMITIVES`는 default가 어떻게 잡혀 있고, 어느 쪽을 override해야 하는지?
|
||||
- **money 직렬화에서 `BigDecimal` scale 2 + HALF_UP**을 택한 이유는? `double`이 위험한 이유, `new BigDecimal(double)` 함정, JSON string 직렬화로 client 부동소수 손실을 회피하는 이유를 설명할 수 있는지?
|
||||
|
||||
## Do Not Overclaim
|
||||
|
||||
- "Stripe 방식이 API versioning의 표준이다"라고 말하면 안 된다 — 진영별 사례이며 외부 결제 컨슈머 규모에 특화된 trade-off다.
|
||||
- "`Sunset` 헤더만 보내면 deprecation 정책으로 충분하다"라고 말하면 안 된다 — `Deprecation` 헤더와 함께 사용해야 정합이다.
|
||||
- "OpenAPI `deprecated: true`로 표시했으니 client가 알아서 migration한다"라고 단정하면 안 된다 — schema marker는 신호일 뿐이고 실제 cutover는 migration window + contract test + compatibility fixture가 함께 강제해야 한다.
|
||||
- "Jackson default가 안전하다"고 단정하면 안 된다 — `FAIL_ON_UNKNOWN_PROPERTIES`는 strict default이지만 `FAIL_ON_NULL_FOR_PRIMITIVES`는 lenient라 null/missing primitive가 묵시적으로 0이 된다.
|
||||
- "Avro / Protobuf로 가면 schema evolution이 자동 검사된다"라고 일반화하면 안 된다 — registry 인프라(예: Confluent Schema Registry)와 wire format 변경 비용이 따라온다. 외부 REST가 JSON인 환경에서는 outbox/event 한정 도입이 현실적이다.
|
||||
- "narrow enum / 응답 필드 제거 / 필드 rename"을 "internal API니까 그냥 한다"라고 정당화하면 안 된다 — client가 deploy lag을 가지면 internal에서도 breaking이다.
|
||||
|
||||
## Sources
|
||||
|
||||
### 공식 표준 / 표준 후보
|
||||
|
||||
- [[raw/official-docs/compat-rfc-8594-sunset-header]] — IETF RFC 8594 (HTTP `Sunset` header)
|
||||
- [[raw/official-docs/sunset-deprecation-headers-paired-usage]] — IETF RFC 8594 + Deprecation draft paired 사용 권고 (Sunset 단독 금지)
|
||||
- [[raw/official-docs/api-versioning-google-aip-180]] — Google AIP-180 (Backwards compatibility 분류)
|
||||
- [[raw/official-docs/schema-jackson-unknown-field-handling]] — Jackson DeserializationFeature default
|
||||
- [[raw/official-docs/schema-bigdecimal-money-serialization-java]] — Java BigDecimal scale/HALF_UP + JSON string 직렬화
|
||||
- [[raw/official-docs/schema-avro-evolution-rules]] — Avro backward/forward/full compatibility
|
||||
- [[raw/official-docs/schema-protobuf-vs-json-evolution]] — Protobuf `reserved` field semantics
|
||||
- [[raw/official-docs/protobuf-reserved-vs-json-openapi-extension]] — Protobuf `reserved` 시맨틱의 JSON/OpenAPI 환경 흉내 대안 비교 (G-F follow-up, needs-confirmation)
|
||||
- [[raw/official-docs/rfc9110-http-semantics]] — IETF RFC 9110 (HTTP Semantics): conditional request(ETag/If-Match/If-None-Match/304/412), transport error(406/413/414/415/405+Allow), HEAD/OPTIONS, 202+Retry-After, Vary
|
||||
- [[raw/official-docs/rfc9111-http-caching]] — IETF RFC 9111 (HTTP Caching): `no-store`/`private`/`public`/`max-age` directive
|
||||
- [[raw/official-docs/openapi-spec-3-1-0]] — OpenAPI 3.1.0 (machine-readable HTTP API contract, JSON Schema 2020-12 정합)
|
||||
- [[raw/official-docs/google-aip-185-resource-versioning]] — Google AIP-185 (major-only `/v1` path versioning)
|
||||
- [[raw/official-docs/google-aip-158-pagination]] — Google AIP-158 (page token opacity + size cap + EoC)
|
||||
- [[raw/official-docs/jsonapi-pagination-format]] — JSON:API pagination link key/위치
|
||||
- [[raw/official-docs/google-aip-151-long-running-operations]] — Google AIP-151 (LRO Operation shape + polling)
|
||||
- [[raw/official-docs/spring-data-pageable-defaults]] — Spring Data `Pageable` zero-indexed + size default + `DEFAULT_MAX_PAGE_SIZE` 2000
|
||||
|
||||
### 진영별 사례 (표준 아님)
|
||||
|
||||
- [[raw/company-tech-blogs/api-versioning-stripe-date-based]] — Stripe date-based versioning (account pin + freeze)
|
||||
- [[raw/company-tech-blogs/api-versioning-github-rest-date-header]] — GitHub `X-GitHub-Api-Version` + 24mo EOL + `410 Gone`
|
||||
|
||||
### Canonical (프로젝트 결정 사실)
|
||||
|
||||
- [[raw/project-notes/ca-skeleton-operational-contract]] §13 / §16 / §18 API Compatibility / Deprecation / §29 G-F
|
||||
- [[raw/branch-notes/feature-api-compatibility-deprecation-contract]]
|
||||
- [[raw/branch-notes/feature-schema-serialization-contract]]
|
||||
|
||||
## Cluster / 묶음
|
||||
|
||||
<!-- GENERATED: derived-blogs:start -->
|
||||
- [[wiki/blog/ca-tmpl-api-evolution-and-schema-2026-07-02]]
|
||||
<!-- GENERATED: derived-blogs:end -->
|
||||
@@ -1 +0,0 @@
|
||||
../../vault/30-knowledge/concepts/archunit-scope-classpath-vs-package-filter.md
|
||||
@@ -0,0 +1,81 @@
|
||||
---
|
||||
title: ArchUnit 분석 scope — import scope(어떤 클래스가 검사되는가) vs classpath 의존성(어떻게 검사하는가)
|
||||
source_type: llm-generated
|
||||
status: draft
|
||||
confidence: medium
|
||||
tags: [archunit, clean-architecture, testing, static-analysis, jvm]
|
||||
related_projects: [ca-skeleton]
|
||||
last_reviewed: 2026-06-04
|
||||
---
|
||||
|
||||
# ArchUnit 분석 scope — import scope(어떤 클래스가 검사되는가) vs classpath 의존성(어떻게 검사하는가)
|
||||
|
||||
> Layer: `wiki/concepts/` — 일반 개념. 내 프로젝트 사실(`wiki/projects/`)은 `wiki-project-template` 사용.
|
||||
|
||||
## Summary
|
||||
|
||||
ArchUnit rule의 결과는 두 개의 독립적인 축에 의해 결정된다. (1) **import scope** — `ClassFileImporter`/`@AnalyzeClasses`가 어떤 class를 분석 대상 집합(`JavaClasses`)으로 끌어왔는가. (2) **classpath 의존성** — 그 class를 분석할 때 ArchUnit이 JVM classpath(reflection)에 의존하는가, 아니면 bytecode만 읽는가. 첫 번째 축을 잘못 잡으면 검사하려던 class가 아예 집합에 없어 rule이 *vacuous하게* 통과한다(false-negative). 두 번째 축은 대부분의 default rule에서 무관하지만 strongly-typed annotation 접근 같은 일부 ergonomics에만 영향을 준다.
|
||||
|
||||
## Standard (공식 정의)
|
||||
|
||||
- **Import 진입점**: class import의 표준 진입점은 `new ClassFileImporter().importPackages("<base-package>")`이며, JUnit 통합에서는 `@AnalyzeClasses(packages = ...)`가 같은 역할을 한다. `importPackages(...)`는 varargs라 다중 package를 받을 수 있고, "단일 root package만 가능"하다는 의미가 아니다. 출처: [[raw/official-docs/archunit-user-guide]] (ARCHUNIT-UG-C2).
|
||||
- **import은 classpath와 무관**: ArchUnit은 classpath/JAR/folder 어디서 import했는지와 무관하게 `JavaClasses`를 구성할 수 있다. 즉 import scope는 "어떤 `.class` 파일을 읽었는가"의 문제이지 "그 class가 현재 test의 classpath에 있는가"와 자동으로 같지 않다. 출처: [[raw/official-docs/archunit-conditional-on-property-3-layer-pattern]] (AUCP-C4).
|
||||
- **rule 평가는 classpath에 의존하지 않음**: ArchUnit 자체의 rule API와 default rule + syntax 조합 평가는 classpath에 의존하지 않는다. 출처: [[raw/official-docs/archunit-conditional-on-property-3-layer-pattern]] (AUCP-C4).
|
||||
- **classpath가 영향을 주는 곳**: classpath가 있으면 annotation을 `javaClass.getAnnotationOfType(CustomAnnotation.class).value()`처럼 strongly-typed로 접근할 수 있고, 없으면 `JavaAnnotation<?>` + `Object value = annotation.get("value")` 같은 untyped 접근을 써야 한다. 출처: [[raw/official-docs/archunit-conditional-on-property-3-layer-pattern]] (AUCP-C2, AUCP-C3).
|
||||
- **rule 평가 흐름**: rule은 `ArchRule` 객체로 표현되고 `myRule.check(importedClasses)` 또는 `@ArchTest`로 평가된다. `@ArchTest`가 붙은 rule은 지정된 class를 자동 import(또는 재사용)해 평가한다. 출처: [[raw/official-docs/archunit-user-guide]] (ARCHUNIT-UG-C3, ARCHUNIT-UG-C6).
|
||||
|
||||
## 한계 / 주의점
|
||||
|
||||
- **package filter가 import scope를 보장하지 않는다**: rule의 `that().resideInAPackage("..application..")`는 *이미 import된 집합 안에서* 필터링할 뿐이다. 해당 package의 class가 import scope(`@AnalyzeClasses(packages=...)` 또는 test classpath)에 애초에 없으면, 위반 코드가 존재해도 매칭 대상이 0개가 되어 rule이 통과한다. 즉 "package glob을 썼으니 그 package를 다 본다"는 착각이 가장 흔한 실패 모드다.
|
||||
- **두 가지 빈-집합 동작이 다르다**: (a) `that()` 결과가 비면 ArchUnit은 기본적으로 `failed to check any classes` 에러를 낸다 — 이때는 *눈에 보이는* 실패다. 빈 anchor module이 의도된 상태라면 `allowEmptyShould(true)`로 명시적으로 허용해야 한다. (b) 그러나 검사 대상 class가 *import scope 자체에 빠져* 있으면 ArchUnit은 그것을 "정상 평가했고 위반 0건"으로 인식해 `failed to check any classes` 에러조차 내지 않고 `BUILD SUCCESSFUL`로 통과한다 — 이 vacuous pass가 더 위험하다(에러 신호가 없으므로).
|
||||
- **`allowEmptyShould(true)`는 양날의 검**: 빈 anchor를 합법화하지만, 동시에 import scope 누락으로 인한 vacuous pass도 똑같이 통과시켜 버린다. 따라서 빈-집합 허용 정책만으로는 rule이 *실제로* 위반을 잡는지 보증할 수 없다.
|
||||
- **권장 보완**: (1) 검사 대상이 될 수 있는 module/package(예: sample·fixture)를 test의 import scope에 명시적으로 포함시킨다(예: Gradle `testImplementation project(':<sample>')`). (2) "위반을 데이터로 보는(violations-as-data)" negative fixture를 두고, 의도된 위반 class에 대해 `rule.evaluate(fixtureClasses).hasViolation() == true`를 별도 test로 assert해 rule이 진짜 catch하는지 commit으로 보증한다.
|
||||
- **classpath 의존성과 import scope를 혼동하지 말 것**: "classpath에 없어서 못 잡았다"와 "import scope에 안 넣어서 못 잡았다"는 다른 문제다. 전자는 주로 annotation ergonomics(typed accessor)에만 영향을 주고, false-negative의 실제 원인은 거의 항상 후자(import scope 누락)다. 두 축을 섞어 진단하면 엉뚱한 곳을 고친다. (이 구분의 정밀한 경계는 ArchUnit 버전·import 옵션에 따라 달라질 수 있어 `needs-confirmation`)
|
||||
|
||||
## Project Application
|
||||
|
||||
이 개념과 관련된 내 프로젝트 사실·검증 등급은 아래 project 문서에서 판정한다(concept 문서는 등급을 직접 매기지 않는다).
|
||||
|
||||
- [[wiki/projects/ca-tmpl/clean-architecture-package-layout]] — ca-tmpl의 `CleanArchitectureTest`가 `@AnalyzeClasses(packages = "dev.caskeleton", importOptions = DoNotIncludeTests.class)`로 import scope를 잡고, `allowEmptyShould(true)`로 빈 anchor를 허용하며, `ArchitectureViolationFixtureTest`(violations-as-data)로 각 rule의 catch 동작을 보증하는 실제 적용.
|
||||
- [[wiki/concepts/clean-architecture-package-layout]] — 경계 강제(enforcement)의 두 축(build-graph 검사 vs source/bytecode import 검사) 일반 지식.
|
||||
|
||||
## Claim-backed Knowledge
|
||||
|
||||
> 이 개념 문서의 핵심 설명은 raw source claim으로 뒷받침되어야 한다. 공식 문서 claim과 내 프로젝트 트러블슈팅 사실을 분리한다.
|
||||
|
||||
| Knowledge Point | Supporting Claims | Confidence | Notes |
|
||||
|---|---|---|---|
|
||||
| import 진입점은 `ClassFileImporter().importPackages(...)`이며 varargs로 다중 package 가능(단일 root 강제 아님) | `raw/official-docs/archunit-user-guide.md#ARCHUNIT-UG-C2` | high | 공식 vendor doc |
|
||||
| ArchUnit rule API/default rule 평가는 classpath(reflection)에 의존하지 않으며, classpath/JAR/folder 어디서 import했는지와 무관 | `raw/official-docs/archunit-conditional-on-property-3-layer-pattern.md#AUCP-C4` | high | 공식 vendor doc. "import scope ≠ classpath presence"의 근거 |
|
||||
| annotation 접근 ergonomics만 classpath에 의존(있으면 typed `.value()`, 없으면 untyped `JavaAnnotation.get("value")`) | `raw/official-docs/archunit-conditional-on-property-3-layer-pattern.md#AUCP-C2`, `#AUCP-C3` | high | classpath가 영향을 주는 *유일한* 좁은 지점 |
|
||||
| rule은 `ArchRule.check(classes)` / `@ArchTest`로 평가되고, `@ArchTest`는 지정 class를 자동 import해 평가 | `raw/official-docs/archunit-user-guide.md#ARCHUNIT-UG-C3`, `#ARCHUNIT-UG-C6` | high | 공식 vendor doc |
|
||||
| `that()` 매칭 결과가 비면 기본적으로 `failed to check any classes` 실패 — 빈 anchor가 의도면 `allowEmptyShould(true)` 필요 | `raw/errors/archunit-empty-should-anchor-2026-05-27.md` | medium | 프로젝트 트러블슈팅 사실(`error-note`). 빈 *should* 동작 |
|
||||
| 검사 대상 class가 import scope에 빠지면 위반이 있어도 vacuous pass(`BUILD SUCCESSFUL`, 에러 신호 없음) — sample/fixture를 test import scope에 포함 + negative fixture로 보완 | `raw/errors/archunit-test-scope-sample-ticket-inclusion-2026-05-28.md` | medium | 프로젝트 트러블슈팅 사실(`error-note`). 빈 *that* / import-scope 누락 동작 |
|
||||
|
||||
## 내가 설명할 수 있어야 하는 것
|
||||
|
||||
- ArchUnit의 import scope와 classpath 의존성은 각각 무엇을 결정하는가?
|
||||
- package glob(`..application..`)을 썼는데도 위반을 놓치는 경우는 왜 생기는가?
|
||||
- `failed to check any classes` 에러가 *나는* 경우와 *나지 않고 통과해 버리는* 경우의 차이는 무엇인가?
|
||||
- `allowEmptyShould(true)`는 무엇을 허용하고, 무엇을 *못* 막는가?
|
||||
- vacuous pass를 어떻게 commit 수준에서 막는가(violations-as-data)?
|
||||
|
||||
## Interview Questions
|
||||
|
||||
- ArchUnit rule이 통과했는데도 실제로는 boundary가 깨져 있을 수 있는 시나리오는? 어떻게 방지하는가?
|
||||
- ArchUnit의 분석이 JVM classpath에 의존하는 부분과 의존하지 않는 부분은 각각 무엇인가?
|
||||
- 빈 anchor package가 많은 skeleton에서 architecture test를 신뢰 가능하게 유지하려면 무엇이 필요한가?
|
||||
|
||||
## Do Not Overclaim
|
||||
|
||||
- "package glob을 쓰면 그 package의 모든 class를 검사한다"는 단정 금지. 검사 대상은 *import scope ∩ glob*이며, scope에 없으면 검사되지 않는다.
|
||||
- "ArchUnit은 classpath가 필요하다/필요 없다"는 단정 금지. default rule 평가는 classpath 독립이지만 typed annotation 접근 같은 ergonomics는 classpath에 의존한다 — 부분적이다.
|
||||
- "`allowEmptyShould(true)`를 켜면 안전하다"는 단정 금지. 빈 should를 허용할 뿐, import scope 누락으로 인한 vacuous pass는 막지 못한다.
|
||||
- 위 빈-집합/scope 동작의 정밀한 경계는 ArchUnit 버전·import 옵션에 따라 달라질 수 있어 일부는 `needs-confirmation`이다.
|
||||
|
||||
## Sources
|
||||
|
||||
- [[raw/official-docs/archunit-user-guide]] — ArchUnit User Guide (import 진입점, rule 평가, JUnit 통합)
|
||||
- [[raw/official-docs/archunit-conditional-on-property-3-layer-pattern]] — classpath 유무에 따른 annotation 접근 + rule API의 classpath 독립성
|
||||
- [[raw/errors/archunit-empty-should-anchor-2026-05-27]] — 빈 anchor에서의 `failed to check any classes` + `allowEmptyShould` 해결(프로젝트 사실)
|
||||
- [[raw/errors/archunit-test-scope-sample-ticket-inclusion-2026-05-28]] — import scope 누락으로 인한 vacuous pass + sample module을 test scope에 포함해 해결(프로젝트 사실)
|
||||
@@ -1 +0,0 @@
|
||||
../../vault/30-knowledge/concepts/boundary-validation-and-dto-mapping.md
|
||||
@@ -0,0 +1,86 @@
|
||||
---
|
||||
title: 경계 검증과 DTO↔도메인 매핑 (Bean Validation · MapStruct vs 수기 mapper · Patch partial-update)
|
||||
source_type: llm-generated
|
||||
status: draft
|
||||
confidence: medium
|
||||
tags: [backend, validation, mapper, dto, bean-validation, boundary]
|
||||
related_projects: [ca-skeleton, ca-tmpl]
|
||||
last_reviewed: 2026-06-04
|
||||
---
|
||||
|
||||
# 경계 검증과 DTO↔도메인 매핑
|
||||
|
||||
> Layer: `wiki/concepts/` — 일반 개념. 내 프로젝트 사실은 [[wiki/projects/ca-tmpl/boundary-validation-mapping]] 참조.
|
||||
|
||||
## Summary
|
||||
|
||||
웹 애플리케이션의 **입력 경계**(request boundary)에서는 두 가지 책임이 동시에 생긴다: (1) 들어온 데이터가 형식적으로 올바른지 **검증**하고, (2) 외부 표현(DTO)을 내부 모델(domain / command)로 **변환(mapping)** 하는 것이다.
|
||||
|
||||
- **Bean Validation (Jakarta Validation, JSR 380 / 3.0)**: `@NotNull`, `@Size`, `@Valid` 같은 선언적 제약을 DTO 필드/메서드에 붙여 프레임워크가 자동 검증하게 하는 표준. Spring MVC 는 컨트롤러 파라미터에 `@Valid`/`@Validated` 가 붙으면 본문 바인딩 직후 검증을 수행하고, 실패 시 `MethodArgumentNotValidException` 을 던진다.
|
||||
- **validation-at-boundary 원칙**: 검증은 가능한 한 *입력 경계 한 곳* 에서 fail-fast 로 끝내고, 안쪽 레이어(application/domain)는 이미 검증된 값만 받는다는 설계. 단, 형식(syntax) 검증과 도메인 불변식(invariant) 검증은 책임이 다르므로 같은 어노테이션 한 줄로 뭉뚱그리지 않는다.
|
||||
- **DTO↔domain mapping**: 외부에 노출되는 DTO 와 내부 도메인 객체를 분리하고 그 사이를 변환하는 코드. 변환 도구는 **수기(manual) mapper** 와 **MapStruct 같은 코드 생성기(generator)** 두 갈래가 있다.
|
||||
- **partial-update (PATCH) semantics**: PATCH 요청에서 "필드 없음(absent) / 명시적 null / 값 있음" 세 상태를 구분해야 silent overwrite 를 막을 수 있다.
|
||||
|
||||
## Standard (공식 정의)
|
||||
|
||||
- **Jakarta Bean Validation 3.0** (official-standard): class-level constraint 는 "한 클래스의 여러 property 를 동시에 보는 상태 검증"을 위한 것이고(JBV-3.0-C1), `ConstraintValidator` 는 클래스 인스턴스를 받아 여러 필드에 동시 접근할 수 있다(JBV-3.0-C2). `@GroupSequence` 를 쓰면 group 을 순서대로 실행하다 한 group 이 실패하면 **다음 group 을 건너뛴다(short-circuit)** — syntax 검증을 먼저 통과해야 invariant 검증이 돈다는 패턴의 normative 근거(JBV-3.0-C3). `@Valid` 는 중첩 객체로 검증을 **cascade(전파)** 시킨다(JBV-3.0-C4). 단, Bean Validation 자체는 syntax/invariant 라는 **레이어 이름을 정의하지 않는다** — 그 분류는 애플리케이션 설계 결정이다.
|
||||
- **Spring MVC REST exception handling** (official-vendor-doc): `HttpMessageNotReadableException`(JSON 파싱 실패) 과 `MethodArgumentNotValidException`(Bean Validation 실패) 은 모두 Spring 내장 `ErrorResponse` 구현체이고 `ResponseEntityExceptionHandler` 가 normative 하게 처리한다(SPRING-MVC-EXC-C1/C2/C4/C5). 즉 이 두 예외는 표준적으로 검증 실패(400) 카테고리로 분류된다.
|
||||
- **RFC 7396 (JSON Merge Patch)** (official-standard): merge patch 에서 `null` 값은 "해당 필드 삭제"를 의미한다(RFC7396-C2). 따라서 "명시적 null" 을 다른 의미로 쓰려는 API 는 RFC 7396 merge patch 를 그대로 채택하면 충돌한다(RFC7396-C3). 배열 부분 수정도 불가하다(RFC7396-C4).
|
||||
- **MapStruct** (도구): 컴파일 타임에 mapper 구현 코드를 생성하는 어노테이션 프로세서. 리플렉션 없이 동작하지만, 생성된 코드가 architecture 규칙(예: 도메인 직접 접근 금지)을 우회할 수 있어 별도 exemption 관리가 필요하다. (※ MapStruct 도구 선택 자체는 공식 표준이 권고하는 사항이 아니라 프로젝트 trade-off 결정이다.)
|
||||
|
||||
## 한계 / 주의점
|
||||
|
||||
- **4-layer validation 분류(syntax / policy / invariant / persistence integrity)는 표준이 아니다.** Bean Validation spec 은 이런 taxonomy 를 정의하지 않는다. 레이어를 나누는 것은 설계 결정이며, 잘못 나누면 같은 검증이 두 곳에서 중복되거나 빠진다.
|
||||
- **MapStruct vs 수기 mapper 는 정답이 없는 trade-off.** 수기 mapper 는 boilerplate 가 많지만 동작이 투명하다. MapStruct 는 코드량을 줄이지만 generated code 가 architecture 경계를 silent 하게 leak 할 수 있고, 매핑 누락이 컴파일 시점에 드러나지 않을 수 있다.
|
||||
- **PATCH 의 null/absent 혼동**은 흔한 버그다. Java record 의 기본 매핑으로 PATCH 를 구현하면 요청에 없던 필드가 `null` 로 들어와 기존 값을 덮어쓰는 silent overwrite 가 발생한다. `Optional<T>` 또는 `JsonNullable<T>`(openapi-generator) 같은 3-state wrapper 가 필요하다.
|
||||
- **검증을 경계에서만 한다고 도메인 불변식이 보장되지는 않는다.** 형식 검증(DTO)과 도메인 불변식(application/domain)은 별개다. DTO 검증만으로 "도메인이 안전하다"고 말하면 안 된다.
|
||||
- **`@Valid` cascade 의 무한/깊은 재귀**는 DoS 표면이 될 수 있다. 중첩 깊이에 상한을 두는 것은 spec 이 아니라 운영적 방어 결정이다.
|
||||
|
||||
## Project Application
|
||||
|
||||
- ca-tmpl 은 입력 경계의 검증/매핑 책임을 명시적으로 고정하고, 일부 정책을 ArchUnit fitness function 으로 정적 강제했다. 구체적 구현 사실·검증 등급은 [[wiki/projects/ca-tmpl/boundary-validation-mapping]] 참조.
|
||||
- 관련 트랜잭션 경계 추상화는 [[wiki/concepts/transaction-boundary-abstraction]] / [[wiki/projects/ca-tmpl/transaction-boundary-abstraction]].
|
||||
|
||||
## Claim-backed Knowledge
|
||||
|
||||
> 아래는 본 개념을 뒷받침하는 raw official-doc claim 인용. company-tech-blog 는 사례일 뿐 공식 best practice 로 격상하지 않는다.
|
||||
|
||||
| Knowledge Point | Supporting Claims | Confidence | Notes |
|
||||
|---|---|---|---|
|
||||
| class-level constraint 는 한 클래스의 여러 property 상태를 함께 검증한다 | [[raw/official-docs/validation-jakarta-bean-validation-3.0-spec]] JBV-3.0-C1 | high | constraint 의 *목적* 근거. syntax/invariant 레이어 이름은 spec 미규정 |
|
||||
| `@GroupSequence` 는 group 을 순차 실행하다 실패 시 후속 group 을 short-circuit 한다 | [[raw/official-docs/validation-jakarta-bean-validation-3.0-spec]] JBV-3.0-C3 | high | syntax→invariant 단계 분리 패턴의 normative 근거 |
|
||||
| `@Valid` 는 중첩 객체로 검증을 cascade 한다 | [[raw/official-docs/validation-jakarta-bean-validation-3.0-spec]] JBV-3.0-C4 | high | cascade *메커니즘* 근거. depth 상한은 설계 결정 (spec 미규정) |
|
||||
| `HttpMessageNotReadableException` 은 Spring 이 normative 하게 처리하는 내장 예외 | [[raw/official-docs/spring-mvc-rest-exception-handling]] SPRING-MVC-EXC-C4 | high | JSON 파싱 실패 → 검증(400) 분류 근거 |
|
||||
| `MethodArgumentNotValidException` 은 field error 를 담아 normative 처리된다 | [[raw/official-docs/spring-mvc-rest-exception-handling]] SPRING-MVC-EXC-C5 | high | Bean Validation 실패 → 검증(400) + field error shape 근거 |
|
||||
| JSON Merge Patch 의 `null` 은 필드 삭제를 의미한다 | [[raw/official-docs/patch-json-merge-rfc7396]] RFC7396-C2 | high | PATCH 에서 null/absent 구분이 필요한 이유. ca-tmpl 은 merge patch *미채택* |
|
||||
|
||||
## 내가 설명할 수 있어야 하는 것
|
||||
|
||||
- Bean Validation 의 `@Valid`/`@Validated`/`@GroupSequence` 가 각각 무엇이고, syntax 검증과 도메인 invariant 검증을 왜 분리하는가.
|
||||
- `MethodArgumentNotValidException` 과 `HttpMessageNotReadableException` 이 왜 둘 다 "검증 실패(400)" 로 분류되는가, mapper 내부 예외는 왜 별도 카테고리가 필요한가.
|
||||
- DTO↔domain mapping 에서 MapStruct 와 수기 mapper 의 trade-off (boilerplate vs architecture leak / 컴파일 안전성).
|
||||
- PATCH 의 absent / explicit-null / value 3-state 를 구분하지 않으면 어떤 버그(silent overwrite)가 생기는가, `Optional`/`JsonNullable` 로 어떻게 구분하는가.
|
||||
- RFC 7396 merge patch 의 null=deletion semantics 와, 이를 채택하지 않는 API 가 왜 `application/merge-patch+json` content type 을 쓰면 안 되는가.
|
||||
|
||||
## Interview Questions
|
||||
|
||||
- "request 검증을 어디서 하나요? 컨트롤러? 서비스? 도메인?" → 형식 검증은 경계(DTO), 도메인 불변식은 application/domain. 한 줄 어노테이션으로 다 끝낸다는 답은 위험.
|
||||
- "`@Valid` 와 `@Validated` 차이는?" → `@Validated` 는 Spring 의 group 지원 + 메서드 레벨 검증, `@Valid` 는 표준 cascade.
|
||||
- "PATCH 에서 어떤 필드만 바꾸고 싶을 때 null 을 어떻게 처리하나요?" → absent vs explicit-null 구분, 3-state wrapper.
|
||||
- "DTO 와 도메인 객체를 왜 분리하나요? MapStruct 와 수기 매핑 중 무엇을 쓰나요?" → 노출 경계 분리 + 도구 trade-off.
|
||||
|
||||
## Do Not Overclaim
|
||||
|
||||
- **"Bean Validation 이 syntax/invariant 를 알아서 나눠준다" → 금지.** spec 은 레이어를 정의하지 않는다. `@GroupSequence` 로 *순서* 는 줄 수 있지만 분류는 설계자가 한다.
|
||||
- **"MapStruct 가 수기 mapper 보다 우월하다" → 금지.** generated code 의 architecture leak / 매핑 누락 trade-off 가 있다.
|
||||
- **"DTO 검증을 했으니 도메인이 안전하다" → 금지.** 형식 검증과 도메인 불변식은 별개.
|
||||
- **"PATCH 의 null 은 항상 삭제다(RFC 7396)" → 단정 금지.** RFC 7396 의 정의일 뿐, 이를 채택하지 않는 API 도 많다.
|
||||
|
||||
## Sources
|
||||
|
||||
- [[raw/official-docs/validation-jakarta-bean-validation-3.0-spec]] — Jakarta Bean Validation 3.0 normative (class-level constraint, group sequence, `@Valid` cascade)
|
||||
- [[raw/official-docs/spring-mvc-rest-exception-handling]] — Spring MVC `ResponseEntityExceptionHandler` 처리 예외 목록 (`HttpMessageNotReadableException` / `MethodArgumentNotValidException`)
|
||||
- [[raw/official-docs/patch-json-merge-rfc7396]] — RFC 7396 JSON Merge Patch (null=deletion semantics)
|
||||
- [[raw/official-docs/schema-jackson-polymorphic-deserialization]] — Jackson polymorphic deserialization 보안 지침 (allowlist, CVE-2019-14379) — 경계 역직렬화 보안 맥락
|
||||
- [[raw/branch-notes/feature-boundary-validation-mapping-contract]] — 본 개념을 도출한 ca-tmpl 경계 검증/매핑 계약 branch
|
||||
- [[wiki/projects/ca-tmpl/boundary-validation-mapping]] — 내 프로젝트 적용 사실
|
||||
@@ -1 +0,0 @@
|
||||
../../vault/30-knowledge/concepts/circuit-breaker.md
|
||||
@@ -0,0 +1,64 @@
|
||||
---
|
||||
title: concept / Circuit Breaker
|
||||
source_type: llm-generated
|
||||
status: reviewed
|
||||
confidence: high
|
||||
tags: [concept, ca-tmpl, architecture, spring-boot, circuit-breaker]
|
||||
related_projects: [ca-tmpl]
|
||||
last_reviewed: 2026-06-15
|
||||
---
|
||||
|
||||
# concept / Circuit Breaker
|
||||
|
||||
## Summary
|
||||
|
||||
외부 서비스(의존성) 호출의 실패율을 감시하여, 실패율이 임계치를 초과하면 연동을 즉시 차단(OPEN)함으로써 시스템 전체로 장애가 전파되는 것을 차단하고 빠른 실패(Fail-Fast)를 유도하는 리질리언스 패턴.
|
||||
|
||||
## Standard (공식 정의)
|
||||
|
||||
서킷 브레이커는 크게 세 가지 상태를 가지며, 유한 상태 머신(FSM)으로 동작한다.
|
||||
- **CLOSED**: 정상 상태. 모든 요청을 외부 서비스로 통과시킨다. 최근 N개 호출(Count-Based) 또는 T초간 호출(Time-Based)의 실패율을 측정한다.
|
||||
- **OPEN**: 차단 상태. 외부 서비스로 요청을 보내지 않고 즉시 예외(CallNotPermittedException)를 던져 빠른 실패를 유도한다. 특정 대기 시간(Wait Duration)이 지나면 HALF_OPEN 상태로 전이한다.
|
||||
- **HALF_OPEN**: 감시 통과 상태. 설정된 횟수만큼 제한된 요청을 외부로 전송하여 성공 여부를 측정한다. 만약 재발한 실패율이 임계치 이하면 CLOSED로 복귀하고, 또다시 임계치를 초과하면 OPEN으로 회귀한다.
|
||||
|
||||
## 한계 / 주의점
|
||||
|
||||
- **지표 누수(Metric Cardinality Explosion)**: Resilience4j 등 라이브러리는 기본적으로 매우 세부적인 게이지와 카운터 지표(예: slow call rate, buffered calls 등)를 대량 방출한다. 이를 모니터링 시스템(Prometheus 등)에 그대로 전송하면 시계열 데이터 개수가 급증하여 저장소 과부하를 초래한다. 실무에서는 엄격히 합의된 저카디널리티(low-cardinality) 필수 지표만 필터링하여 통과시켜야 한다.
|
||||
- **Retry와의 충돌**: 서킷 브레이커와 리트라이를 무작정 함께 배치하면, 하나의 외부 요청 실패가 리트라이 3회로 증폭되어 서킷 브레이커가 오작동하거나 윈도우 슬라이딩의 실패율이 왜곡될 수 있다.
|
||||
|
||||
## Project Application
|
||||
|
||||
- [[wiki/explainer/adapter-outbound.md]]
|
||||
- `OutboundHttpResilience`에서 각 의존성별로 독립된 `CircuitBreaker`와 `Retry`를 구성함.
|
||||
- `OutboundHttpResilienceConfig`에서 D3/D4 가이드라인을 강제하여:
|
||||
- 리질리언스를 켤 때 지표 수집기(`MeterRegistry`)가 없으면 애플리케이션 기동을 에러로 즉시 차단(Activation Guard).
|
||||
- Prometheus 지표 수집을 위해 `resilience4j.retry.calls`, `resilience4j.circuitbreaker.calls`, `resilience4j.circuitbreaker.state` 딱 3가지 필수 지표만 허용하고 나머지는 강제 차단(Deny Filter)함.
|
||||
- 가시성을 높이기 위해 벤더 사양의 태그를 `outcome` (SUCCESS/FAILURE) 및 대문자 `state` (CLOSED, OPEN, HALF_OPEN)로 정형화(Metric Normalisation)하여 바인딩함.
|
||||
|
||||
## Claim-backed Knowledge
|
||||
|
||||
| Knowledge Point | Supporting Claims | Confidence | Notes |
|
||||
|---|---|---|---|
|
||||
| 서킷 브레이커의 표준 구조 및 Resilience4j 사양 | `raw/official-docs/outbound-resilience4j-vs-spring-retry.md` | `high` | Resilience4j 공식 사양 |
|
||||
| 지표 카디널리티 폭발 문제 및 모니터링 필터링 규칙 | `raw/official-docs/resilience4j-micrometer-module.md` | `high` | Micrometer 통합 모범 사례 |
|
||||
|
||||
## 내가 설명할 수 있어야 하는 것
|
||||
|
||||
- 서킷 브레이커의 세 가지 상태와 그 전이 조건은 무엇인가?
|
||||
- 왜 리트라이와 서킷 브레이커를 결합할 때 데코레이팅 순서가 중요한가? (CB가 Retry의 바깥쪽에 위치해야 각 재시도 실패가 개별적으로 서킷 실패율에 반영되지 않고 전체 실패로 깔끔하게 묶이거나, 혹은 구조에 따라 왜곡이 발생할 수 있음을 알아야 한다.)
|
||||
- 카디널리티 폭발(Metric Cardinality Explosion)이란 무엇이며, 우리 프로젝트는 이를 어떻게 대처했는가?
|
||||
|
||||
## Interview Questions
|
||||
|
||||
- 마이크로서비스 환경에서 서킷 브레이커의 필요성과 작동 방식(FSM)을 설명하십시오.
|
||||
- 서킷 브레이커를 적용한 후 모니터링 시스템의 시계열 부하(Cardinality)가 급증하는 문제를 해결하기 위해 구체적으로 어떤 조치를 취할 수 있습니까?
|
||||
|
||||
## Do Not Overclaim
|
||||
|
||||
- "서킷 브레이커가 동작하면 분산 시스템의 네트워크 순단에 대비해 무조건 가용성이 높아진다"고 단정하면 안 된다. 서킷이 열려 있는(OPEN) 동안은 정상 요청조차 즉시 거절되므로, 가용성은 일시적으로 0이 된다. 서킷 브레이커의 목표는 가용성 향상뿐 아니라 **호출 측의 스레드 고갈 방지 및 업스트림 서버 보호**임을 명시해야 한다.
|
||||
|
||||
## Sources
|
||||
|
||||
- [Resilience4j CircuitBreaker Core Guide](https://resilience4j.readme.io/docs/circuitbreaker)
|
||||
- [[raw/official-docs/outbound-resilience4j-vs-spring-retry.md]]
|
||||
- [[raw/official-docs/resilience4j-micrometer-module.md]]
|
||||
@@ -1 +0,0 @@
|
||||
../../vault/30-knowledge/concepts/clean-architecture-package-layout.md
|
||||
@@ -0,0 +1,124 @@
|
||||
---
|
||||
title: Clean Architecture 패키지 레이아웃 (feature-first vs layer-first vs hexagonal vs modulith vs onion)
|
||||
source_type: llm-generated
|
||||
status: draft
|
||||
confidence: medium
|
||||
tags: [clean-architecture, package-layout, hexagonal, modulith]
|
||||
related_projects: [ca-skeleton]
|
||||
last_reviewed: 2026-05-22
|
||||
---
|
||||
|
||||
# Clean Architecture 패키지 레이아웃 (feature-first vs layer-first vs hexagonal vs modulith vs onion)
|
||||
|
||||
> Layer: `wiki/concepts/` — 일반 개념. 내 프로젝트 사실은 `project-template` 사용.
|
||||
|
||||
## Summary
|
||||
|
||||
feature-first 패키지 레이아웃은 최상위를 도메인 feature(`features/{name}/`)로 자르고 그 내부에 `presentation/application/domain/infrastructure`를 두는 구조로, 각 feature가 자체 inbound/outbound adapter와 application core를 갖는다는 점에서 본질적으로 "feature 단위로 잘린 mini-Hexagonal"과 동형이다. layer-first는 최상위가 기술 계층이고 도메인이 그 안에 흩어지는 점에서 응집도 축이 정반대다.
|
||||
|
||||
## Standard (공식 정의)
|
||||
|
||||
- **Uncle Bob, Screaming Architecture (2011)**: 시스템의 최상위 디렉터리는 사용된 framework이 아니라 시스템이 "외치는" use case / business 영역이어야 한다고 주장. controller/service/repository로 자르는 layer-first는 framework가 외치는 구조라는 점을 비판한다. 출처: [[raw/official-docs/feature-first-uncle-bob-screaming-architecture-2011]].
|
||||
- **Cockburn, Hexagonal (Ports and Adapters)**: 응용 코어(application + domain)를 inbound adapter(driving)와 outbound adapter(driven)로부터 port interface로 격리. driving/driven adapter 분리가 본질이며 패키지 형태 자체는 비강제. 출처: [[raw/official-docs/hexagonal-cockburn-wikipedia-summary]].
|
||||
- **Thombergs, BuckPal reference**: Cockburn Hexagonal을 자바/스프링 부트로 구현한 reference. 최상위가 feature이고 내부에 `domain/application/adapter(in|out)` 3-tier로 잘려 feature-first + Hexagonal이 같은 구조에서 만난다는 점을 보여줌. 출처: [[raw/official-docs/hexagonal-thombergs-buckpal-github]].
|
||||
- **Palermo, Onion Architecture (2008)**: 의존성은 외부 layer(infrastructure/UI)에서 내부 layer(domain model)로만 향하며, 안쪽이 바깥쪽 interface를 알지 않는다는 의존성 역전 규칙. layer를 동심원으로 표현. 출처: [[raw/official-docs/onion-palermo-original-2008]].
|
||||
- **Spring Modulith (공식 문서)**: Spring Boot 위에서 패키지 자체가 모듈 경계가 되며 `@ApplicationModule`/named-interface로 cross-module 접근을 강제. JPA event SPI 위에서 transactional event publication 등 운영 contract를 framework가 제공. 출처: [[raw/official-docs/modulith-spring-official-doc]].
|
||||
|
||||
## 한계 / 주의점
|
||||
|
||||
각 레이아웃은 다른 트레이드오프를 가진다.
|
||||
|
||||
- **feature-first**
|
||||
- cross-feature shared kernel(공통 value object, 공통 정책)을 어디에 둘지가 모호. `common/`을 두되 business concept가 새지 않도록 별도 규칙이 필요.
|
||||
- 도메인 인접성이 강한 feature 사이에서 model 중복 위험(같은 개념을 두 feature가 따로 정의).
|
||||
- feature 사이 호출은 직접 import보다는 port 또는 명시적 application API를 통해 통제해야 함 (그렇지 않으면 사실상 layer-first로 회귀).
|
||||
|
||||
- **layer-first**
|
||||
- 도메인 수가 늘어나면 같은 도메인의 코드가 `controller/`, `service/`, `repository/`에 흩어져 응집도가 폭락. 한 도메인을 수정할 때 패키지 3~4곳을 동시에 건드림. Sahibinden 기술블로그는 이를 "패키지가 도메인을 외치지 않는다"로 비판함. 출처: [[raw/company-tech-blogs/feature-first-sahibinden-package-by-layer-vs-feature]].
|
||||
- Baeldung식 Clean Architecture Spring Boot 가이드는 입문 학습 비용이 가장 낮지만 결과적으로 도메인 응집을 보장하지 않음. 출처: [[raw/official-docs/layer-first-baeldung-clean-architecture-spring-boot]], [[raw/company-tech-blogs/layer-first-kamilmazurek-github-template]].
|
||||
|
||||
- **hexagonal pure (feature 슬라이스 없음)**
|
||||
- 최상위가 `application/domain/adapter`로만 잘리고 feature 슬라이스가 없으면 도메인이 늘어날수록 `application`과 `domain` 패키지가 비대해짐.
|
||||
- inbound/outbound 분리는 명확하지만 도메인 간 boundary가 약함. 우아한형제들 기술블로그의 Hexagonal 적용도 결국 도메인별 module로 분리하는 방향으로 진화. 출처: [[raw/company-tech-blogs/hexagonal-woowahan-techblog-2023]].
|
||||
|
||||
- **Spring Modulith**
|
||||
- Spring Framework / Spring Boot 종속. framework-neutral 도메인을 외부 강제로 보호하기 어려움 (도메인까지 Spring scan에 들어옴).
|
||||
- transactional event publication은 JPA event SPI에 의존하는 구현체가 다수라 persistence 선택에 영향. 카카오뱅크 수신상품 사례는 Modulith가 "느슨한 modular monolith"의 좋은 진화 경로임을 보여주지만 framework lock-in 비용을 수반. 출처: [[raw/company-tech-blogs/modulith-kakaobank-techblog-2025]], [[raw/company-tech-blogs/modulith-arawn-github-modular-monoliths-spring]].
|
||||
- Spring Modulith 공식 문서는 module boundary 위반을 verification API로 잡지만 빌드 실패 강제 여부는 적용 프로젝트의 CI 설정에 의존. 출처: [[raw/official-docs/modulith-spring-official-doc]].
|
||||
|
||||
- **onion**
|
||||
- 의존성 방향 규칙은 Hexagonal과 동등 (안쪽으로만 의존).
|
||||
- 그러나 boundary verification 도구가 framework 자체로는 제공되지 않음. ArchUnit 같은 별도 정적 분석 없이는 layer 우회를 build-time에 잡기 어려움. Allegro 기술블로그도 onion의 이상은 인정하면서 실제 강제는 별도 도구가 필요하다고 명시. 출처: [[raw/company-tech-blogs/onion-allegro-tech-blog-2023]].
|
||||
|
||||
5종 모두 "의존성은 안쪽으로만"이라는 동일한 핵심 원칙을 공유하며, 차이는 (a) 최상위 자름의 기준(feature vs layer) (b) framework가 boundary를 강제하는지 (c) inbound/outbound adapter 명시 여부에 있다.
|
||||
|
||||
### 경계를 *강제*하는 방법 (enforcement)
|
||||
|
||||
레이아웃을 고른 것만으로 경계가 지켜지지 않는다. 어느 레이아웃이든 boundary drift를 막으려면 별도의 강제 수단이 필요하며, 일반적으로 두 축으로 나뉜다.
|
||||
|
||||
- **Build-graph 검사**: multi-module 빌드에서 module 간 허용 dependency를 화이트리스트로 두고, 허용 외 module dependency 선언 시 빌드를 실패시킨다(예: Gradle custom verification task). module 경계 자체가 1차 방어선이 된다.
|
||||
- **Source/bytecode import 검사**: ArchUnit 같은 정적 분석 도구로 package/class 레벨 import·call·annotation을 검사한다. "`..domain..`은 `org.springframework..`에 의존 금지", "특정 class(예: `ApplicationContext`) 의존 금지(banned-class)", "특정 annotation 사용 금지", "DTO는 web adapter 안에서만 접근" 같은 fitness function을 test로 강제한다.
|
||||
|
||||
정적 분석의 한계는 분명하다. import/call/annotation은 bytecode에 남지만, runtime container lookup(`ApplicationContext.getBean(String)` 같은 string-key 조회), `Class.forName(String)` reflection, classloader 우회는 bytecode가 *문자열 내용*을 노출하지 않으므로 catch할 수 없다. class-literal `getBean(Class<T>)`까지는 method-call target으로 잡히지만 string-key 변종은 false-negative가 되며, 이 영역은 code review·runtime 검증(Actuator `/beans`, Modulith verifier 등)으로만 보완 가능하다. 또 ArchUnit의 `should()` 조건이 매칭 대상이 0개인 빈 module에서 vacuous하게 통과하는 empty-anchor 함정이 있어, `allowEmptyShould` 정책과 "위반을 데이터로 보는(violations-as-data)" negative fixture로 rule이 실제로 catch하는지 별도 보증하는 패턴이 쓰인다. ArchUnit 분석 scope(classpath import vs package filter)와 empty-should 함정의 일반 지식은 [[wiki/concepts/archunit-scope-classpath-vs-package-filter]] 참조.
|
||||
|
||||
## Claim-backed Knowledge
|
||||
|
||||
> 인용 가능한 출처가 직접 뒷받침하는 일반 지식만 둔다. "어느 레이아웃이 옳다"는 추론·취향은 §한계 / 주의점과 §Do Not Overclaim에서 다룬다.
|
||||
|
||||
| Knowledge Point | Supporting Claims | Confidence | Notes |
|
||||
|---|---|---|---|
|
||||
| 최상위 디렉터리는 framework가 아니라 use case / business 영역을 드러내야 한다(layer-first 비판) | [[raw/official-docs/feature-first-uncle-bob-screaming-architecture-2011]] | medium | Uncle Bob Screaming Architecture (2011), `engineering-blog` — 공식 표준이 아닌 영향력 있는 블로그 주장 |
|
||||
| Hexagonal의 본질은 응용 코어를 inbound(driving)/outbound(driven) adapter로부터 port interface로 격리하는 것이며 package 형태 자체는 비강제 | [[raw/official-docs/hexagonal-cockburn-wikipedia-summary]] | medium | Cockburn Ports & Adapters, `engineering-blog` |
|
||||
| 의존성은 외부 layer(infra/UI)→내부 layer(domain model) 방향으로만 향하고 안쪽은 바깥쪽 interface를 알지 않는다 | [[raw/official-docs/onion-palermo-original-2008]] | medium | Palermo Onion (2008), `engineering-blog` |
|
||||
| Spring Modulith는 package를 module 경계로 삼고 `@ApplicationModule`/named-interface로 접근을 강제하나, 위반의 build 실패 강제 여부는 적용 프로젝트 CI 설정에 의존(framework는 verification API만 제공) | [[raw/official-docs/modulith-spring-official-doc]] | high | 공식 문서. build 실패는 자동이 아님 |
|
||||
| onion/hexagonal 의존성 방향 규칙은 framework 자체로 build-time 강제되지 않으며, ArchUnit 등 별도 정적 분석 없이는 layer 우회를 빌드 시점에 잡기 어렵다 | [[raw/company-tech-blogs/onion-allegro-tech-blog-2023]] | medium | `company-tech-blog` 관점 — 공식 best practice로 승격 금지 |
|
||||
| 도메인 수가 늘면 layer-first에서 한 도메인 코드가 controller/·service/·repository/에 흩어져 응집도가 떨어진다 | [[raw/company-tech-blogs/feature-first-sahibinden-package-by-layer-vs-feature]] | medium | `company-tech-blog` 사례 |
|
||||
|
||||
## Project Application
|
||||
|
||||
- [[wiki/projects/ca-tmpl/clean-architecture-package-layout]] — ca-tmpl package/module blueprint + enforcement-rules 적용 기록. Gradle multi-module boundary(8 module, production root `dev.caskeleton`)와 ArchUnit/Gradle guardrail은 `locally-verified`(2026-06-04 ground-truth 대조). enforcement dimension: `domain_is_pure`(Lombok ban 포함), application↔adapter 격리, `ApplicationContext` banned-class rule(D11, string-key bypass는 한계), `verifyCleanArchitectureDependencies` build-graph 검사, violations-as-data negative fixture를 기록. `sample-portfolio` fixture business flow와 Spring Modulith verifier는 범위 밖.
|
||||
- [[raw/branch-notes/feature-architecture-enforcement-rules]] — 경계 의존성 규칙과 forbidden annotation/import의 ArchUnit 강제 기준.
|
||||
- [[raw/branch-notes/feature-skeleton-package-blueprint-contract]] — Gradle multi-module Clean Architecture / Hexagonal module blueprint SSOT.
|
||||
- [[raw/branch-notes/feature-domain-feature-onboarding-contract]] — 새 도메인 추가 시 New Domain Module Slice + Read/Write Difference Table 기준.
|
||||
- [[raw/project-notes/ca-skeleton-operational-contract]] §20 Skeleton Blueprint Contract — 위 3개 branch-note를 통합한 canonical SSOT.
|
||||
|
||||
## 내가 설명할 수 있어야 하는 것
|
||||
|
||||
- feature-first / layer-first / hexagonal / onion / modulith 5종의 공식 정의와 공통 핵심 원칙("의존성은 안쪽으로만")은 무엇인가?
|
||||
- 각 레이아웃이 어떤 문제를 해결하고, 어떤 상황에서는 무너지는가(특히 layer-first의 응집도 붕괴 시점)?
|
||||
- 레이아웃 선택만으로 경계가 지켜지지 않는 이유와, build-graph 검사 / 정적 분석(ArchUnit) 두 축의 enforcement가 각각 무엇을 막는가?
|
||||
- 공식 문서가 말하지 않는 부분(예: Spring Modulith가 위반의 build 실패를 자동 강제하지 않음)은 무엇인가?
|
||||
- 회사 기술 블로그 사례(우아한형제들·카카오뱅크·Allegro 등)를 일반 법칙처럼 말하면 안 되는 지점은?
|
||||
- 내 프로젝트(ca-tmpl)에서는 어떤 branch decision과 ArchUnit/Gradle rule로 연결됐는가?
|
||||
- 정적 분석으로 잡히지 않는 우회(runtime lookup, reflection)는 코드/운영에서 어떻게 검증·보완하는가?
|
||||
|
||||
## Interview Questions
|
||||
|
||||
- feature-first 패키지 레이아웃과 layer-first(controller/service/repository) 레이아웃의 차이는 무엇인가? 어느 시점에 후자가 무너지는가?
|
||||
- feature-first 레이아웃이 Hexagonal Architecture와 "동형"이라는 표현은 무슨 뜻인가? buckpal 예시로 설명하라.
|
||||
- 도메인 수가 늘어났을 때 layer-first가 응집도 면에서 무너지는 이유는 무엇인가? 어떤 운영 신호로 그것을 감지하는가?
|
||||
- Spring Modulith를 즉시 도입하지 않고 Gradle multi-module + ArchUnit/Gradle guardrail로 시작하는 트레이드오프는 무엇인가? 향후 Modulith로 이행할 수 있는 조건은?
|
||||
- 패키지 규약을 문서로만 두지 않고 ArchUnit 같은 architecture test로 boundary를 강제하는 이유는 무엇인가? 정적 분석으로 잡히지 않는 우회(runtime lookup 등)는 어떻게 보완하는가?
|
||||
|
||||
## Do Not Overclaim
|
||||
|
||||
- "feature-first가 항상 layer-first보다 우월하다"는 금지. 학습 비용은 layer-first가 가장 낮고, 도메인 수가 적은 초기 단계에서는 layer-first도 합리적인 선택이다.
|
||||
- "ca-tmpl이 Hexagonal Architecture다"는 단정 금지. ca-tmpl은 Gradle module boundary로 application/domain과 adapter를 물리 분리한 Clean Architecture / Hexagonal-inspired template이다. 현재 구현 어휘는 inbound = `adapter-web`, outbound = `adapter-persistence` / `adapter-outbound`이며, Cockburn 원전의 모든 어휘를 그대로 차용한 구현은 아님.
|
||||
- "Spring Modulith를 곧 도입할 것"이라는 단정 금지. Modulith는 framework가 boundary를 강제하는 자연스러운 진화 경로이지만, 도입은 framework lock-in과 JPA 의존 비용을 수반하며 ca-tmpl의 framework-neutral 도메인 원칙과 일부 충돌한다. 향후 검토 대안 중 하나일 뿐 도입 결정이 아니다.
|
||||
- "ArchUnit이 모든 경계 위반을 잡아낸다"는 단정 금지. 정적 분석은 ApplicationContext lookup, `@Lazy` reflection, runtime classloader 우회를 감지할 수 없으며 별도 코드 리뷰/SonarQube 보완이 필요하다.
|
||||
|
||||
## Sources
|
||||
|
||||
- [[raw/official-docs/feature-first-uncle-bob-screaming-architecture-2011]] — Uncle Bob Screaming Architecture (2011)
|
||||
- [[raw/official-docs/hexagonal-cockburn-wikipedia-summary]] — Cockburn Hexagonal Architecture (Ports & Adapters)
|
||||
- [[raw/official-docs/hexagonal-thombergs-buckpal-github]] — Thombergs BuckPal reference (feature 단위로 잘린 Hexagonal)
|
||||
- [[raw/official-docs/layer-first-baeldung-clean-architecture-spring-boot]] — Baeldung Clean Architecture Spring Boot
|
||||
- [[raw/official-docs/onion-palermo-original-2008]] — Palermo Onion Architecture (2008)
|
||||
- [[raw/official-docs/modulith-spring-official-doc]] — Spring Modulith 공식 문서
|
||||
- [[raw/company-tech-blogs/feature-first-sahibinden-package-by-layer-vs-feature]] — Sahibinden: feature vs layer 응집도 비교
|
||||
- [[raw/company-tech-blogs/layer-first-kamilmazurek-github-template]] — layer-first Spring Boot template
|
||||
- [[raw/company-tech-blogs/hexagonal-woowahan-techblog-2023]] — 우아한형제들 Hexagonal 적용 사례
|
||||
- [[raw/company-tech-blogs/modulith-kakaobank-techblog-2025]] — 카카오뱅크 수신상품 Modulith 적용
|
||||
- [[raw/company-tech-blogs/modulith-arawn-github-modular-monoliths-spring]] — Modular Monoliths with Spring 참조 구현
|
||||
- [[raw/company-tech-blogs/onion-allegro-tech-blog-2023]] — Allegro Onion Architecture 적용기
|
||||
- [[raw/project-notes/ca-skeleton-operational-contract]] — canonical operational contract (§20 Skeleton Blueprint Contract, §29 Topic 1)
|
||||
@@ -1 +0,0 @@
|
||||
../../vault/30-knowledge/concepts/config-and-adapter-templates.md
|
||||
@@ -0,0 +1,96 @@
|
||||
---
|
||||
title: Config & Adapter Templates (env-driven + optional module)
|
||||
source_type: llm-generated
|
||||
status: draft
|
||||
confidence: medium
|
||||
tags: [12-factor, config, spring-boot, adapter, conditional-on-property]
|
||||
related_projects: [ca-skeleton]
|
||||
last_reviewed: 2026-05-22
|
||||
---
|
||||
|
||||
# Config & Adapter Templates (env-driven + optional module)
|
||||
|
||||
> Layer: `wiki/concepts/` — env 기반 runtime configuration과 optional adapter template를 동시에 다루는 일반 개념 문서. 구체적인 프로젝트 결정은 [[raw/project-notes/ca-skeleton-operational-contract]] §9 및 [[raw/branch-notes/feature-env-driven-runtime-configuration]], [[raw/branch-notes/feature-integration-adapter-templates]] 참조.
|
||||
|
||||
## Summary
|
||||
|
||||
**Env config**: 12-factor §III. Config 원칙을 따라 application-owned env에 `APP_` prefix, Duration은 `30s` 형식 1택, boolean은 `true/false` only, runtime reload는 기본 금지, `.env.example` drift 검증 도구로 누락 감지를 강제하는 설계.
|
||||
|
||||
**Adapter templates**: 선택형 adapter(Kafka/Redis/Slack/Email)는 기본 dependency가 아닌 optional module로 두고, `@ConditionalOnProperty` 3-layer(Layer 1 Spring bean 등록 조건, Layer 2 ArchUnit static dependency 검사, Layer 3 runtime `AdapterDisabledException` fail-fast)로 disabled adapter가 use case path에 새지 않게 막는 설계.
|
||||
|
||||
## Standard (공식 정의)
|
||||
|
||||
### Env-driven runtime configuration
|
||||
|
||||
- **12-factor §III. Config** — config는 코드와 분리된 환경 변수에 두고, 배포 환경별로 달라지는 값(자격 증명, hostname, profile)은 모두 env로 주입. config dump가 가능하면 안 됨.
|
||||
- **Spring Boot externalized configuration** — `@ConfigurationProperties + @Validated`로 env 바인딩, `application.yml` profile-specific override, Spring `Duration` (`30s`/`PT30S`) / `DataSize` (`10MB`) 타입 지원.
|
||||
- **검토된 대안**:
|
||||
- **Spring Cloud Config Server** — 중앙 git-backed config + `@RefreshScope`로 runtime reload. config server 자체가 인프라 SPOF가 되고 bootstrap에 의존.
|
||||
- **k8s ConfigMap + Spring Cloud Kubernetes auto-reload** — 3-level reload (`refresh` / `restart_context` / `shutdown`).
|
||||
- **HashiCorp Consul KV** — KV store + watch.
|
||||
- **AWS Parameter Store / AppConfig** — managed validator + CloudWatch auto-rollback + deployment strategy.
|
||||
- **LaunchDarkly / Unleash** — feature flag SaaS. A/B/canary, user-targeting, percentage rollout 등 product-grade 기능 제공.
|
||||
|
||||
### Adapter templates (optional module)
|
||||
|
||||
- **Spring `@ConditionalOnProperty`** — `name`/`havingValue` 조건이 일치할 때만 bean 등록. Spring Boot 3.5.0+에서 `@ConditionalOnBooleanProperty` 도입.
|
||||
- **Spring Boot AutoConfiguration** — `META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports`에 등록된 `@AutoConfiguration` 클래스가 조건부 bean을 제공. custom starter의 표준 방식.
|
||||
- **검토된 대안**:
|
||||
- **Java SPI / `ServiceLoader`** — `META-INF/services/<interface>`에 구현체 등록, classpath에서 발견된 모든 provider를 load.
|
||||
- **Spring `@Profile` 기반** — profile 활성화로 bean 선택.
|
||||
- **OSGi plugin architecture** — runtime module 동적 load/unload.
|
||||
- **Feature flag library (FF4J / Togglz)** — runtime flag로 코드 path 분기.
|
||||
|
||||
## 한계 / 주의점
|
||||
|
||||
### Env config
|
||||
|
||||
- **12-factor env (process env 노출)** — secret이 process env에 남아 `/proc/<pid>/environ`, container metadata API, `env` actuator endpoint로 leak 가능. secret manager 별도 필요.
|
||||
- **Spring Cloud Config Server** — 인프라 SPOF. config server 장애 시 client startup 차단 (bootstrap 의존).
|
||||
- **k8s ConfigMap auto-reload** — pod별로 reload 타이밍이 다르면 partial-state가 생겨 디버깅 어려움. k8s lock-in 발생.
|
||||
- **AWS AppConfig** — AWS lock-in + per-call billing.
|
||||
- **LaunchDarkly / Unleash** — 외부 SaaS 의존, flag debt(제거되지 않은 flag 누적), cost. product-grade A/B/canary 요구가 발생하기 전에는 over-engineering.
|
||||
|
||||
### Adapter templates
|
||||
|
||||
- **Spring `@ConditionalOnProperty` Layer 1** — Spring 공식이 cover하는 영역은 bean 등록 조건뿐. application code가 disabled adapter package를 import해도 Spring 자체는 막지 못함.
|
||||
- **ArchUnit Layer 2** — 별도 source가 필요한 미흡 영역. `noClasses().that().resideInAPackage("..application..").should().dependOnClassesThat().resideInAPackage("..adapters.{disabled}..")` 같은 정적 rule을 작성해야 하며, ca-tmpl 자체 contract로 G-I 후속 보강 대상.
|
||||
- **ArchUnit Layer 2 정적 검사 한계** (2026-05-22 보강) — ArchUnit User Guide의 `DescribedPredicate` / `ArchCondition` API와 `JavaClass.getAnnotationOfType(...)`로 정적 추출 가능한 것은 (a) adapter 후보 class가 `@ConditionalOnProperty`를 부착했는지, (b) `name`/`havingValue` parameter 값이 `app.adapter.<name>.enabled` 패턴을 따르는지, (c) application layer가 adapter package를 직접 import하지 않는지(CA 경계)까지. **"현재 빌드/배포 환경에서 어떤 adapter가 실제 disabled인지"는 runtime config 평가이므로 ArchUnit 능력 밖**이며, Layer 3 (`AdapterDisabledException` runtime fail-fast)에 위임해야 함. 즉 Layer 2는 "annotation 존재 + naming pattern 강제" fitness function까지가 실효 범위. 자세한 평가는 [[raw/official-docs/archunit-conditional-on-property-3-layer-pattern]] 참조. status `needs-confirmation`.
|
||||
- **`AdapterDisabledException` Layer 3** — branch 자체 contract. 표준 라이브러리가 제공하지 않으며 직접 구현.
|
||||
- **Java SPI** — on/off boolean 표현 불가(classpath 존재 = enable), default constructor 강제, Spring DI 미통합. ca-tmpl의 `APP_ADAPTER_*_ENABLED` 결정과 정면 충돌.
|
||||
- **Togglz / FF4J** — runtime branching tool로, startup-time adapter on/off와 시맨틱이 다름. ca-tmpl `@ConditionalOnProperty`(startup 결정)와 feature flag service(runtime 결정)는 분리 영역으로 취급해야 함.
|
||||
|
||||
## Project Application
|
||||
|
||||
- [[wiki/projects/ca-tmpl/config-and-adapter-templates]] — ca-tmpl 의사결정 기록 (현재 `documented-only`, Phase C2 미진입). 실제 구현 여부는 project 문서 참조.
|
||||
- [[raw/branch-notes/feature-env-driven-runtime-configuration]] — `APP_` prefix, Duration `30s`, boolean `true/false`, no-runtime-reload, `.env.example` drift 검증 결정.
|
||||
- [[raw/branch-notes/feature-integration-adapter-templates]] — optional module + `@ConditionalOnProperty` 3-layer detection + `AdapterDisabledException` fail-fast 결정.
|
||||
- [[raw/project-notes/ca-skeleton-operational-contract]] — §9 Env-driven Runtime Configuration, §11 Adapter Failure Contract, §29 Group G-I.
|
||||
|
||||
## Interview Questions
|
||||
|
||||
- 12-factor §III. Config가 의미하는 "config와 코드 분리"는 구체적으로 무엇을 강제하는지 설명해 주세요.
|
||||
- runtime config reload를 기본 금지(no-runtime-reload)로 결정한 근거와, 그 결정이 운영에서 갖는 trade-off는 무엇인가요?
|
||||
- `@ConditionalOnProperty` 3-layer 검출(Spring bean 조건 + ArchUnit static + runtime fail-fast)이 각각 어떤 실패 시나리오를 잡아내려는 것인지 설명해 주세요.
|
||||
- Java SPI `ServiceLoader`와 Spring `@ConditionalOnProperty`는 adapter on/off 표현에서 어떤 차이가 있나요?
|
||||
- LaunchDarkly 같은 feature flag SaaS와 `@ConditionalOnProperty` 기반 startup toggle은 어떤 운영 요구가 생겼을 때 갈라지는지 설명해 주세요.
|
||||
|
||||
## Do Not Overclaim
|
||||
|
||||
- "`@RefreshScope`만 도입하면 dynamic config가 된다" 같은 단정은 피해야 함. ca-tmpl은 runtime reload를 기본 금지로 두며, reload가 필요한 경우는 secret manager + startup validation을 별도 branch로 분리하는 것이 결정 사항.
|
||||
- "`@ConditionalOnProperty` 3-layer가 disabled adapter 호출을 완전 검증한다"고 단정하면 안 됨. Layer 1만 Spring 공식 cover이고, Layer 2(ArchUnit)는 source 부재로 G-I 후속 보강 대상, Layer 3(`AdapterDisabledException`)는 branch 자체 contract.
|
||||
- "12-factor env가 secret 관리까지 책임진다"는 표현은 과장. process env 노출 위험은 12-factor 자체가 해결하지 않으며 secret manager가 별도 책임.
|
||||
- "ca-tmpl이 LaunchDarkly/Togglz를 거부했다"가 아니라 "ca-tmpl scope에서 위임한 영역"이라는 표현이 정확.
|
||||
|
||||
## Sources
|
||||
|
||||
- [The Twelve-Factor App — III. Config](https://12factor.net/config) — [[raw/official-docs/config-12-factor-app-config]]
|
||||
- [Spring Cloud Config (official)](https://docs.spring.io/spring-cloud-config/reference/) — [[raw/official-docs/config-spring-cloud-config-server-official]]
|
||||
- [Spring Cloud Kubernetes — ConfigMap auto-reload](https://docs.spring.io/spring-cloud-kubernetes/reference/) — [[raw/official-docs/config-spring-cloud-kubernetes-configmap-reload]]
|
||||
- [AWS AppConfig — Feature flag & deployment strategy](https://docs.aws.amazon.com/appconfig/) — [[raw/official-docs/config-aws-appconfig-feature-flag-deployment]]
|
||||
- [LaunchDarkly — Feature flag best practice](https://launchdarkly.com/) — [[raw/company-tech-blogs/config-launchdarkly-feature-flag-best-practice]]
|
||||
- [Spring Boot — Custom AutoConfiguration / starter](https://docs.spring.io/spring-boot/reference/features/developing-auto-configuration.html) — [[raw/official-docs/adapter-spring-boot-autoconfig-custom-starter]]
|
||||
- [Java SPI — `java.util.ServiceLoader`](https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/util/ServiceLoader.html) — [[raw/official-docs/adapter-java-spi-serviceloader]]
|
||||
- [Togglz / FF4J — Feature toggle library](https://www.togglz.org/) — [[raw/company-tech-blogs/adapter-togglz-ff4j-feature-toggle-library]]
|
||||
- [ArchUnit — Writing Custom Rules / Accessing Annotation](https://www.archunit.org/userguide/html/000_Index.html) — [[raw/official-docs/archunit-conditional-on-property-3-layer-pattern]] (Layer 2 정적 검사 가능 범위 평가, needs-confirmation)
|
||||
- Canonical: [[raw/project-notes/ca-skeleton-operational-contract]] (§9, §11, §29 Group G-I)
|
||||
@@ -1 +0,0 @@
|
||||
../../vault/30-knowledge/concepts/data-layer-persistence-cache-outbound.md
|
||||
@@ -0,0 +1,128 @@
|
||||
---
|
||||
title: Data Layer Baseline (Persistence + Cache + Outbound HTTP)
|
||||
source_type: llm-generated
|
||||
status: draft
|
||||
confidence: medium
|
||||
tags: [persistence, jpa, cache, http-client, resilience]
|
||||
related_projects: [ca-skeleton]
|
||||
last_reviewed: 2026-05-22
|
||||
---
|
||||
|
||||
# Data Layer Baseline (Persistence + Cache + Outbound HTTP)
|
||||
|
||||
> Layer: `wiki/concepts/` — Phase E Group G-C 합성. 3개 sub-topic(Persistence failure / Cache consistency / Outbound HTTP)을 하나의 baseline canonical로 묶음. 프로젝트 적용 사실은 `wiki/projects/`에 별도 작성하고 본 문서에서는 링크만 둠.
|
||||
|
||||
## Summary
|
||||
|
||||
Data layer baseline은 세 가지 축으로 구성된다.
|
||||
|
||||
- **Persistence**: SQLState 매트릭스로 DB 실패를 분류하고, Spring `DataAccessException` 계층 위에 매핑하여 `PERSISTENCE / CONFLICT / TRANSIENT_DEPENDENCY` 카테고리를 만든다. OSIV는 off가 기본.
|
||||
- **Cache**: cache-aside default + Caffeine local lock(single-instance) + Redisson `RLock` distributed mutex(multi-instance HPA) + after-commit invalidation + eventual consistency window 5초.
|
||||
- **Outbound HTTP**: Spring RestClient를 baseline으로 두고, retry/circuit breaker는 Resilience4j로 일원화. timeout default = connect 2s / read 5s / global 10s.
|
||||
|
||||
## Standard (공식 정의)
|
||||
|
||||
### Persistence — SQLState + Spring DAO hierarchy
|
||||
|
||||
- **SQLState** (ISO/IEC 9075): 5-char code로 DB 오류를 표준 분류. `08*` = connection exception, `40001` = serialization failure, `40P01` = deadlock(Postgres), `23xxx` = integrity constraint, `57014` = query canceled.
|
||||
- **Spring `DataAccessException` hierarchy**: `TransientDataAccessException` / `NonTransientDataAccessException` / `RecoverableDataAccessException`로 retryable/non-retryable 1차 분리. JPA `PersistenceException`은 `JpaSystemException`으로 흡수.
|
||||
- **OSIV (Open Session In View)**: Hibernate session을 view rendering까지 열어두는 패턴. Vlad Mihalcea가 anti-pattern으로 명시했고 Spring Boot는 활성화 시 startup WARN 로그를 출력. 운영 baseline은 off.
|
||||
- **HikariCP pool sizing**: 공식 wiki는 `connections = ((core_count * 2) + effective_spindle_count)` 공식과 단일 small pool 권장. pool wait p99 / pool exhaustion이 1차 alert 지표.
|
||||
|
||||
### Cache — cache-aside + stampede control
|
||||
|
||||
- **Cache-aside** (Microsoft Cloud Design Patterns / AWS ElastiCache): application이 cache miss 시 DB 조회 → cache 채움. invalidation도 application 책임. write-through는 cache layer가 sync 책임, write-behind는 async, read-through는 cache layer가 loader를 안다. 책임 위치가 다름.
|
||||
- **Caffeine `AsyncLoadingCache` / `@Cacheable(sync = true)`**: 동일 key 동시 miss를 단일 loader 호출로 직렬화 (in-process stampede 방지).
|
||||
- **Redisson `RLock`**: Redis 기반 reentrant lock + watchdog lease extension. Kleppmann의 Redlock 비판을 회피하기 위해 단일 master 기반 RLock + fence token 사용.
|
||||
- **after-commit invalidation**: Spring `TransactionSynchronizationManager.registerSynchronization`의 `afterCommit()` hook에서만 cache mutation 수행. tx rollback 시 stale write 차단.
|
||||
|
||||
### Outbound HTTP — RestClient + Resilience4j
|
||||
|
||||
- **Spring RestClient** (6.1+): `RestTemplate`의 fluent 후속 API. RestTemplate은 Spring 공식 maintenance-only 상태로 신규 기능 추가 없음.
|
||||
- **Resilience4j**: Netflix Hystrix의 사실상 후속. Hystrix는 2018년 maintenance mode 진입. Retry / CircuitBreaker / TimeLimiter / Bulkhead / RateLimiter를 functional decorator로 제공.
|
||||
- **Circuit breaker 상태**: `CLOSED` → `OPEN` (failure rate threshold 초과) → `HALF_OPEN` (probe) → `CLOSED` 복귀. Micrometer로 state transition을 metric으로 노출.
|
||||
- **Timeout 계층**: connect timeout(소켓 연결) < read timeout(응답 첫 바이트 대기) < global call timeout(전체 호출). 셋 중 하나라도 미설정이면 무한 대기 위험.
|
||||
|
||||
## 한계 / 주의점
|
||||
|
||||
### Persistence
|
||||
|
||||
- SQLState 9-row matrix의 vendor-specific row(PostgreSQL `23505`, `40P01` 등)는 DB 변경 시 재검증 필요. MySQL은 `40001`만 공유하고 `40P01` 대신 다른 코드를 사용.
|
||||
- OSIV off는 lazy loading exception을 presentation까지 새지 않게 막아주지만, application 경계에서 명시적 fetch 전략(`@EntityGraph`, fetch join, DTO projection)을 강제한다. 익숙하지 않은 팀은 운영 부담이 늘 수 있음.
|
||||
- R2DBC reactive는 throughput 우위가 있으나 JPA tooling을 포기해야 한다. baseline은 JPA blocking으로 고정한 trade-off의 반대편.
|
||||
|
||||
### Cache
|
||||
|
||||
- cache-aside의 eventual consistency window가 5초로 잡혀 있어 **strict consistency가 요구되는 use case(잔액, 인증, idempotency 검증)에는 부적합**. 해당 use case는 cache bypass를 명시.
|
||||
- Caffeine local cache + Redisson 분산 mutex 조합은 노드 간 sync lag이 존재. 한 노드가 invalidation을 발행한 뒤 다른 노드의 local cache가 비워질 때까지 lag 발생.
|
||||
- Redisson `RLock`도 Kleppmann의 분산 lock 비판에서 완전히 자유롭지 않다. 정확한 fencing을 요구하는 경우 token + DB-level optimistic lock 병행이 필요.
|
||||
- negative cache(존재하지 않는 row, TTL 60s)는 invalidation 채널 적용 대상에서 제외 — 의도된 분리이지만 row가 실제로 생성된 직후 60초간 stale empty 응답이 나갈 수 있음.
|
||||
|
||||
### Outbound HTTP
|
||||
|
||||
- RestClient는 Spring 6.1+ 한정. 기존 RestTemplate 코드는 마이그레이션 비용이 따른다.
|
||||
- WebClient는 reactor event-loop 위에서 동작하므로 MVC(servlet) baseline에 강제 도입하면 blocking risk가 있다. baseline에서는 extension 문서로 분리.
|
||||
- OpenFeign은 declarative interface로 편리하지만 Spring Cloud 의존이 붙는다. Spring 6.1+ `@HttpExchange`가 framework-level 대안.
|
||||
- Stripe engineering blog는 retry default-on을 옹호하지만 **이는 idempotency-key 헤더 보장이 전제**. 일반 API에 default-on retry를 적용하면 비-idempotent endpoint의 중복 write 위험이 생긴다.
|
||||
- Resilience4j는 Spring Boot starter 통합이 매끄럽지만, Spring 외 환경(plain Java, Vert.x 등)에서는 verbose한 functional decorator 작성이 필요. "vendor-neutral"로 단언하기에는 일부 마찰이 있음.
|
||||
|
||||
## Project Application
|
||||
|
||||
- [[wiki/projects/ca-tmpl/data-layer-persistence-cache-outbound]] — ca-tmpl 의사결정 기록 (현재 `documented-only`, Phase C2 미진입). 실제 구현 여부는 project 문서 참조.
|
||||
ca-skeleton operational contract와 owning branch-notes:
|
||||
|
||||
- [[raw/branch-notes/feature-persistence-failure-baseline]] — SQLState 9-row matrix, Hikari alert threshold, OSIV off 결정
|
||||
- [[raw/branch-notes/feature-cache-consistency-contract]] — cache-aside default, Caffeine + Redisson, after-commit invalidation, 5s window
|
||||
- [[raw/branch-notes/feature-outbound-http-client-baseline]] — RestClient baseline, Resilience4j, timeout 2s/5s/10s, shutdown retry suppression
|
||||
- [[raw/project-notes/ca-skeleton-operational-contract]] — §6 Operational Error Category, §11 Adapter Failure Contract, §29 G-C 외부 근거
|
||||
|
||||
## Interview Questions
|
||||
|
||||
- SQLState 코드를 어떻게 retryable / non-retryable로 매핑했고 그 분류가 Spring `DataAccessException` hierarchy와 어떻게 정합한가?
|
||||
- OSIV가 anti-pattern으로 평가되는 이유는 무엇이고 off로 두었을 때 lazy loading은 어떻게 해결하는가?
|
||||
- cache-aside의 eventual consistency window 5초가 의미하는 바와, 그 안에서 stale read가 허용되지 않는 use case는 어떻게 분리하는가?
|
||||
- Resilience4j를 Hystrix 대신 선택한 이유와 두 라이브러리의 차이는?
|
||||
- outbound HTTP timeout을 connect 2s / read 5s / global 10s로 둔 의도와 셋 중 어떤 게 빠지면 어떤 위험이 생기는가?
|
||||
- after-commit invalidation을 강제하는 이유와, transaction rollback 시 cache 일관성이 어떻게 보장되는가?
|
||||
|
||||
## Do Not Overclaim
|
||||
|
||||
- "cache-aside면 항상 안전하다" — strict consistency가 요구되는 use case에서는 cache bypass가 필요하다. cache-aside는 eventual consistency 모델이다.
|
||||
- "Resilience4j는 vendor-neutral이라 어디서나 동일하게 동작" — Spring Boot starter 통합 외 환경에서는 functional decorator를 직접 조립해야 하고 boilerplate가 늘어난다.
|
||||
- "RestClient가 RestTemplate를 완전히 대체했다" — Spring 6.1+ 한정이고 기존 코드 마이그레이션 비용이 있다.
|
||||
- "Redisson RLock이면 분산 lock 문제 해결" — Kleppmann 비판은 완화되었지만 fencing token / DB optimistic lock 병행이 필요한 경우가 있다.
|
||||
- "Stripe처럼 retry default-on이 좋은 패턴이다" — Stripe는 idempotency-key 보장이 전제. 일반 API에 그대로 적용하면 위험하다.
|
||||
|
||||
## Sources
|
||||
|
||||
### 공식 근거 (Persistence)
|
||||
|
||||
- [[raw/official-docs/persistence-spring-dataaccessexception-hierarchy]] — Spring `DataAccessException` 계층 (SQLState 분류의 framework-level anchor)
|
||||
- [[raw/official-docs/persistence-osiv-antipattern-hibernate-vladmihalcea]] — Hibernate 권위자의 OSIV anti-pattern 명시 + Spring Boot WARN
|
||||
- [[raw/official-docs/persistence-hikaricp-pool-sizing-wiki]] — pool sizing 공식과 alert threshold 출처
|
||||
- [[raw/official-docs/persistence-r2dbc-reactive-spring]] — JPA blocking baseline의 trade-off 반대편(R2DBC reactive)
|
||||
|
||||
### 공식 근거 (Cache)
|
||||
|
||||
- [[raw/official-docs/cache-aside-vs-write-through-aws]] — cache-aside / write-through / write-behind / read-through trade-off 공식 분류
|
||||
- [[raw/official-docs/cache-caffeine-asyncloadingcache-readme]] — single-instance stampede 방지(`@Cacheable(sync = true)`, `AsyncLoadingCache`) 공식 매핑
|
||||
- [[raw/official-docs/cache-redisson-rlock-vs-setnx]] — multi-instance HPA에서 RLock 채택 + SETNX/Redlock 배제 (Kleppmann 비판 포함)
|
||||
|
||||
### 사례 (Cache)
|
||||
|
||||
- [[raw/company-tech-blogs/cache-woowahan-after-commit-invalidation]] — after-commit invalidation의 한국 사례 + Spring `TransactionSynchronizationManager` 강제 근거 (회사 기술블로그 — 사례 취급)
|
||||
|
||||
### 공식 근거 (Outbound HTTP)
|
||||
|
||||
- [[raw/official-docs/outbound-spring-restclient-baseline]] — RestClient baseline + RestTemplate maintenance-only 명시
|
||||
- [[raw/official-docs/outbound-resilience4j-vs-spring-retry]] — Resilience4j 채택 + Spring Retry 좁은 예외 허용 + Hystrix 배제
|
||||
- [[raw/official-docs/outbound-webclient-vs-restclient-spring]] — WebClient baseline 배제 이유(reactor event-loop blocking risk)
|
||||
- [[raw/official-docs/outbound-openfeign-declarative-client]] — Feign declarative 대안 + maintenance status + Spring 6.1+ `@HttpExchange`
|
||||
|
||||
### 사례 (Outbound HTTP)
|
||||
|
||||
- [[raw/company-tech-blogs/outbound-stripe-rate-limit-retry-engineering]] — retry + idempotency-key 결합, full-jitter backoff. ca-tmpl default-disabled의 보수성 대비 (회사 기술블로그 — 사례 취급)
|
||||
|
||||
### Canonical contract
|
||||
|
||||
- [[raw/project-notes/ca-skeleton-operational-contract]] — §6 Operational Error Category, §11 Adapter Failure Contract, §29 Group G-C 외부 근거 인덱스
|
||||
@@ -1 +0,0 @@
|
||||
../../vault/30-knowledge/concepts/devops-ci-supply-chain-dx.md
|
||||
@@ -0,0 +1,130 @@
|
||||
---
|
||||
title: DevOps Baseline (CI + Supply chain + DX)
|
||||
source_type: llm-generated
|
||||
status: draft
|
||||
confidence: medium
|
||||
tags: [devops, ci-cd, supply-chain, sigstore, developer-experience]
|
||||
related_projects: [ca-skeleton]
|
||||
last_reviewed: 2026-05-22
|
||||
---
|
||||
|
||||
# DevOps Baseline (CI + Supply chain + DX)
|
||||
|
||||
> Layer: `wiki/concepts/` — 일반 개념. 내 프로젝트 사실은 `project-template` / project 문서 사용.
|
||||
|
||||
## Summary
|
||||
|
||||
운영 가능한 백엔드 skeleton의 DevOps baseline은 세 축으로 구성된다.
|
||||
**(1) CI quality gate** — GitHub Actions `needs:` + `if: success()`로 contract test ↔ release-blocking 의존성을 단일 yaml에서 강제하고, flaky test는 14일 sunset 기한이 붙은 quarantine bucket으로 분리한다.
|
||||
**(2) Build / release supply chain** — Cosign keyless signing (Sigstore Fulcio + Rekor transparency log)으로 artifact를 서명하고, SLSA provenance attestation으로 build 출처를 검증하며, Gradle dependency-locking으로 transitive 버전 drift를 차단한다.
|
||||
**(3) Developer experience** — `./gradlew bootstrap` 같은 단일 진입점 + Testcontainers `@ServiceConnection` 기반 integration test + `.tool-versions`로 핀된 JDK LTS로 새 개발자가 clean clone 직후 smoke까지 5단계로 도달한다.
|
||||
|
||||
## Standard (공식 정의)
|
||||
|
||||
### CI quality gate
|
||||
|
||||
- **GitHub Actions** (`docs.github.com/en/actions/`): YAML workflow의 `jobs.<id>.needs` 의존성과 `if: success() | failure()` 조건으로 단계별 gate를 표현. job status가 `failure`이면 workflow status도 `failure`.
|
||||
- **GitLab CI/CD** (`docs.gitlab.com/ee/ci/pipelines/`): `stages` + `jobs` + `needs:` + `rules:` 키워드로 같은 모델을 구성. `parallel: matrix:` 키워드로 matrix job.
|
||||
- **Jenkins Declarative Pipeline** (`jenkins.io/doc/book/pipeline/syntax/`): `agent` 디렉티브 + `post { failure { ... } }` block으로 실패 처리.
|
||||
- **CircleCI configuration reference** (`circleci.com/docs/configuration-reference/`): orbs + workflow + job 모델.
|
||||
- **Tekton Pipelines** (`tekton.dev/docs/pipelines/`): `Pipeline` = `Tasks`의 모음, 각 `Task`는 Kubernetes Pod로 실행.
|
||||
|
||||
### Supply chain
|
||||
|
||||
- **Sigstore Cosign** (`docs.sigstore.dev/cosign/signing/overview/`): OIDC identity token으로 Fulcio가 단명(10분) 서명 cert 발급, 서명 직후 private key 파기. 서명 이벤트는 **Rekor transparency log**에 immutable 기록. 검증 측은 `cosign verify --certificate-identity=... --certificate-oidc-issuer=...`로 issuer와 identity를 함께 강제.
|
||||
- **SLSA v1.0 spec** (`slsa.dev/spec/v1.0/`): "Supply-chain Levels for Software Artifacts". provenance는 build platform, top-level build invocation, materials(sources + dependencies)를 최소 식별. Build L1 = provenance 존재, L2 = hosted build platform, L3 = hardened/hermetic build.
|
||||
- **in-toto attestation** (`github.com/in-toto/attestation`): 인증된 statement = subject(artifact digest 목록) + predicate(예: SLSA Provenance). DSSE envelope으로 서명되며 Cosign이 같은 envelope을 서명한다.
|
||||
- **Gradle dependency locking** (`docs.gradle.org/current/userguide/dependency_locking.html`): `dependencyLocking { lockAllConfigurations() }` + `--write-locks`로 lockfile 생성. `lockMode = STRICT`일 때 lock state와 다른 해석은 build fail.
|
||||
- **Maven Enforcer Plugin** `dependencyConvergence` 룰: transitive lockfile은 부재. 부분 대응만 가능.
|
||||
|
||||
### Developer experience
|
||||
|
||||
- **Testcontainers for Java** (`java.testcontainers.org/`): Docker container 기반 throwaway dependency. Spring Boot 3.1+ `@ServiceConnection` annotation으로 JDBC URL, credentials, host, port가 ApplicationContext에 자동 주입. reuse 옵션은 CI 금지, 로컬만.
|
||||
- **Devcontainer spec** (`containers.dev/implementors/spec/`): `.devcontainer/devcontainer.json`이 VSCode/Codespaces용 dev container 정의. tool version과 OS-level dep을 통일하지만 첫 진입점/smoke/migration 순서는 별도 필요.
|
||||
- **mise / asdf** (`mise.jdx.dev/`, `asdf-vm.com/`) — `.tool-versions` 형식이 사실상 표준. **SDKMAN!** (`sdkman.io/`)은 별도 `.sdkmanrc` 사용.
|
||||
- **Eclipse Temurin 21 LTS** (`adoptium.net/temurin/releases/?version=21`): 2028-09까지 무료 LTS 보안 패치.
|
||||
|
||||
## 한계 / 주의점
|
||||
|
||||
### CI
|
||||
|
||||
- **GitHub Actions**는 vendor lock-in(workflow yaml 문법, OIDC issuer URL, marketplace action 등)과 hosted runner 비용 모델이 다른 provider와 다르다. provider-agnostic하게 gate를 정의하지 않으면 이식 비용이 크다.
|
||||
- **Jenkins / Tekton**은 인프라(k8s cluster, plugin ecosystem)에 대한 의존도가 커서 skeleton 단계에서는 과한 선택일 수 있다.
|
||||
- **Flaky test quarantine**은 Spotify/Google/Microsoft가 운영 도구로 인정한 반면 Martin Fowler는 *"Eradicating Non-Determinism in Tests"*에서 quarantine 자체를 anti-pattern으로 본다. "Spotify가 한다 = 공식 best practice"로 표현 금지. 14일 sunset 같은 절충은 *어느 한쪽도 공식이 아니라는 인정*이다.
|
||||
- **OpenAPI snapshot diff** (springdoc + openapi-diff/oasdiff)는 controller annotation을 정적 추출하므로 dynamic routing(예: webflux functional routes)이 있으면 누락된다. "ground truth"는 이 범위 안에서만 참.
|
||||
|
||||
### Supply chain
|
||||
|
||||
- **Cosign keyless**의 "signature 누락 시 deploy block"만으로는 부족하다. `--certificate-identity` + `--certificate-oidc-issuer`로 **identity 매칭 정책**을 별도로 명시해야 임의의 OIDC identity가 만든 서명도 통과되는 사고를 막을 수 있다. Sigstore 공식은 키리스 모드에서 두 flag를 **검증 진입 전제 조건**으로 강제하며(`--certificate-identity ... is required for verification in keyless mode`), GitHub Actions OIDC 환경의 expected identity는 `https://github.com/<ORG>/<REPO>/.github/workflows/<file>@refs/heads/<branch>` 형식, issuer는 `https://token.actions.githubusercontent.com`이다. 클러스터 측 강제는 policy-controller / Kyverno `verifyImages` 등 admission controller에서 expected identity/issuer를 정책으로 선언. — `needs-confirmation`: 정책 표현 형식은 조직별로 다름.
|
||||
- **SLSA v1.0 spec**의 실제 필드명은 두 최상위 객체로 구성된다. `buildDefinition.{buildType, externalParameters, internalParameters, resolvedDependencies}` + `runDetails.{builder.id, builder.version, builder.builderDependencies, metadata.invocationId, metadata.startedOn, metadata.finishedOn, byproducts}`. in-toto Statement 래퍼는 `_type`(`https://in-toto.io/Statement/v1`) + `subject[*].digest` + `predicateType`(`https://slsa.dev/provenance/v1`) + `predicate`. 약식 표현(`build.config.source`, `build.invocation`, `materials`)은 spec 필드명과 다르므로 slsa-verifier가 `--builder-id` ↔ `runDetails.builder.id` 등의 필드를 찾지 못해 검증이 실패한다. provenance 생성 단계에서 spec 필드명을 그대로 사용해야 한다. — 출처: [[raw/official-docs/slsa-v1-provenance-schema]].
|
||||
- **SLSA Build L3** (hardened build, hermetic, tamper-resistant builder)는 GitHub Actions hosted runner만으로는 도달 불가. 실무적으로는 L2(hosted build platform)가 현실적 목표지점.
|
||||
- **Gradle dependency-locking**이 있어도 plugin 버전과 toolchain(JDK)은 별도 핀이 필요. `.tool-versions` / `gradle/wrapper/gradle-wrapper.properties` 핀과 함께 봐야 reproducible build가 완성된다.
|
||||
- **Maven**에는 transitive lockfile이 1급 시민으로 존재하지 않는다. Maven 기반 프로젝트에서 같은 수준의 reproducibility를 요구하면 추가 도구가 필요.
|
||||
|
||||
### Developer experience
|
||||
|
||||
- **`.tool-versions`(asdf/mise) vs `.sdkmanrc`(SDKMAN)** 포맷 차이. 두 파일을 동시에 두면 drift 위험. 단일 source로 좁히는 편이 안전하다.
|
||||
- **Devcontainer**는 VSCode/Codespaces에 의존한다. IntelliJ + 로컬 JDK 사용자에게는 중복 환경이 되며 bootstrap 단일 진입점/smoke는 devcontainer 안에서도 별도로 정의되어야 한다.
|
||||
- **Testcontainers**는 Apple Silicon(arm64) 환경에서 일부 image가 emulation(amd64) 위에서 동작해 bootstrap 시간이 늘어날 수 있다.
|
||||
- **Testcontainers reuse 옵션**은 CI에서는 반드시 비활성화. test 간 isolation을 깬다.
|
||||
- **Bootstrap 한 줄 명령**은 ergonomic 강점이 있으나 단계가 합쳐져 있어 *어느 단계에서 실패했는지* 추적이 어려울 수 있다. 실패 단계별 exit code 또는 step 출력 분리가 필요.
|
||||
|
||||
## Project Application
|
||||
|
||||
- [[wiki/projects/ca-tmpl/devops-ci-supply-chain-dx]] — ca-tmpl 의사결정 기록 (현재 `documented-only`, Phase C2 미진입). 실제 구현 여부는 project 문서 참조.
|
||||
내 프로젝트(ca-skeleton)에서 이 개념과 관련된 문서로 **링크**. 실제 구현 여부·검증 등급은 해당 project / branch 문서에서 판정 (concept 문서는 등급을 직접 매기지 않음).
|
||||
|
||||
- [[raw/project-notes/ca-skeleton-operational-contract]] — §29 G-E (외부 근거 / 대안 조사 인덱스, DevOps / CI).
|
||||
- [[raw/branch-notes/feature-ci-quality-gates-contract]] — Gate ↔ Branch Contract Test 소유권 매트릭스 20행, flaky quarantine 14d sunset SSOT, OpenAPI snapshot diff.
|
||||
- [[raw/branch-notes/feature-build-release-supply-chain-contract]] — Cosign keyless 의무, SLSA provenance attestation 의무, Gradle dependency-locking, SemVer + git sha suffix, reproducibility.
|
||||
- [[raw/branch-notes/feature-developer-experience-contract]] — `./gradlew bootstrap` 5단계, Temurin 21 LTS, Testcontainers integration, markdown-link-check.
|
||||
|
||||
## Interview Questions
|
||||
|
||||
- "CI에서 Gate ↔ Branch Contract Test 소유권 매트릭스란 무엇이고 왜 필요한가? 누가 어떤 gate를 깨질 때 책임지는지 어떻게 표현하는가?"
|
||||
- "Flaky test quarantine bucket에 sunset deadline을 14일로 두는 근거는 무엇인가? quarantine 자체를 반대하는 입장(Fowler)과 어떻게 절충하는가?"
|
||||
- "Cosign keyless signing이 GPG signing과 비교해 어떤 운영 비용을 제거하고, 어떤 새 의존성(OIDC IdP, Rekor 가용성)을 추가하는가?"
|
||||
- "SLSA build level L1/L2/L3가 각각 무엇을 보장하는가? skeleton 단계에서 현실적으로 도달 가능한 level은 어디까지인가?"
|
||||
- "Gradle dependency-locking이 필요한 이유는 무엇이고, Maven에는 왜 같은 수준의 lockfile이 없으며 어떻게 대체하는가?"
|
||||
- "Integration test backend로 Testcontainers를 H2 같은 in-memory DB 대신 선택하는 이유는 무엇인가? 그 비용은 무엇인가?"
|
||||
|
||||
## Do Not Overclaim
|
||||
|
||||
- "Cosign signature 누락만 차단하면 supply chain이 안전하다"고 단정 금지. **identity 매칭 정책**(`--certificate-identity` + `--certificate-oidc-issuer`)이 없으면 임의 OIDC identity가 만든 서명도 통과될 수 있다.
|
||||
- "SLSA Build L3를 달성했다"고 단정 금지. ca-skeleton 단계에서 L3는 hermetic build / tamper-resistant builder를 요구하며 GitHub Actions hosted runner만으로는 도달 어렵다. branch note의 약식 매핑(`build.config.source` 등)은 spec 실제 필드명(`buildDefinition.externalParameters`)과 다르므로 정정 필요.
|
||||
- "Google/Spotify/Microsoft가 flaky test quarantine을 운영하므로 공식 best practice다"라고 표현 금지. 이들은 *company-tech-blog* 등급이며 Fowler의 반대 입장이 함께 존재한다.
|
||||
- "GitHub Actions가 CI provider의 정답이다"로 단정 금지. ca-skeleton은 `needs:` + `if: success()` 모델이 contract gate에 맞물려 채택된 것이며, gate 정의 자체는 provider-agnostic하게 작성되어야 이식 가능하다.
|
||||
- "`./gradlew bootstrap` 한 줄이 끝났다 = 모든 게 정상이다"로 표현 금지. 5단계(compileTestJava → docker compose up → Flyway migrate → sample profile seed → smoke) 중 어디서 실패했는지 step 단위 검증이 필요.
|
||||
- "Devcontainer가 있으면 bootstrap이 필요 없다"로 표현 금지. devcontainer는 tool version과 OS-level dep만 통일하며, 진입점/smoke/migration 순서는 별도로 정의되어야 한다.
|
||||
- LLM 생성 문서이므로 본 concept 문서의 모든 진술은 `confidence: medium`. 검증 전 high confidence로 분류 금지.
|
||||
|
||||
## Sources
|
||||
|
||||
### 공식 문서 / spec
|
||||
|
||||
- [GitHub Actions — Migrating from GitLab CI/CD](https://docs.github.com/en/actions/learn-github-actions/migrating-from-gitlab-cicd-to-github-actions) / [GitLab CI/CD pipelines](https://docs.gitlab.com/ee/ci/pipelines/) / [Jenkins Declarative Pipeline](https://www.jenkins.io/doc/book/pipeline/syntax/) / [CircleCI configuration reference](https://circleci.com/docs/configuration-reference/) / [Tekton Pipelines overview](https://tekton.dev/docs/pipelines/) — CI provider 모델 비교.
|
||||
- [Sigstore Cosign overview](https://docs.sigstore.dev/cosign/signing/overview/) + [Fulcio](https://docs.sigstore.dev/certificate_authority/overview/) + [Rekor](https://docs.sigstore.dev/logging/overview/) — keyless signing 체인.
|
||||
- [SLSA v1.0 spec](https://slsa.dev/spec/v1.0/) + [Build levels](https://slsa.dev/spec/v1.0/levels) + [Provenance schema](https://slsa.dev/spec/v1.0/provenance) + [in-toto attestation](https://github.com/in-toto/attestation) — supply chain provenance.
|
||||
- [Gradle dependency locking](https://docs.gradle.org/current/userguide/dependency_locking.html) + [Maven Enforcer dependencyConvergence](https://maven.apache.org/enforcer/enforcer-rules/dependencyConvergence.html) — dependency lockfile 정책.
|
||||
- [Testcontainers for Java](https://java.testcontainers.org/) + [reuse](https://java.testcontainers.org/features/reuse/) + [Spring Boot Testcontainers support](https://docs.spring.io/spring-boot/docs/current/reference/htmlsingle/#features.testing.testcontainers) — integration test backend.
|
||||
- [Devcontainer spec](https://containers.dev/implementors/spec/) + [VS Code Dev Containers](https://code.visualstudio.com/docs/devcontainers/containers) + [GitHub Codespaces](https://docs.github.com/en/codespaces/overview) — dev environment 통일.
|
||||
- [mise](https://mise.jdx.dev/) + [asdf](https://asdf-vm.com/) + [SDKMAN!](https://sdkman.io/usage#env) + [Adoptium Temurin 21](https://adoptium.net/temurin/releases/?version=21) — tool versioning + JDK LTS.
|
||||
- [springdoc-openapi](https://springdoc.org/) + [OpenAPITools/openapi-diff](https://github.com/OpenAPITools/openapi-diff) + [Tufin/oasdiff](https://github.com/Tufin/oasdiff) + [OpenAPI 3.1](https://spec.openapis.org/oas/v3.1.0) — OpenAPI snapshot diff.
|
||||
|
||||
### Raw 원본 (저장소 내 발췌)
|
||||
|
||||
- [[raw/official-docs/ci-github-actions-vs-gitlab-comparison]] — GitHub Actions `needs:` + `if: success()`가 contract gate 매트릭스에 맞물리는 근거, Jenkins/Tekton의 k8s 인프라 부담.
|
||||
- [[raw/official-docs/ci-openapi-snapshot-diff-tooling]] — springdoc 런타임 추출 + openapi-diff/oasdiff CI 실패 조건, dynamic routing 함정.
|
||||
- [[raw/company-tech-blogs/ci-flaky-test-quarantine-spotify-google]] — Spotify/Google/MS quarantine 인정 vs Fowler 반대 양립, 14d sunset은 절충.
|
||||
- [[raw/official-docs/supply-chain-cosign-keyless-sigstore]] — Fulcio 단명 cert + Rekor transparency log + identity 매칭 정책 필요성.
|
||||
- [[raw/official-docs/cosign-keyless-identity-verification-policy]] — `--certificate-identity` + `--certificate-oidc-issuer` 키리스 검증 강제 (Sigstore docs / cosign issue #3671), GitHub Actions OIDC identity 포맷.
|
||||
- [[raw/official-docs/supply-chain-slsa-provenance-framework]] — SLSA v1.0 build levels, provenance 최소 필드, in-toto attestation, 약식 매핑 정정 필요.
|
||||
- [[raw/official-docs/slsa-v1-provenance-schema]] — SLSA v1.0 provenance 실제 필드명 표(`buildDefinition.*` / `runDetails.*`) + in-toto Statement v1 래퍼 + slsa-verifier 검사 동작. ca-tmpl 약식 명명 정정 근거.
|
||||
- [[raw/official-docs/supply-chain-gradle-vs-maven-dependency-locking]] — Gradle `lockMode = STRICT`, Maven transitive lockfile 부재.
|
||||
- [[raw/official-docs/dx-testcontainers-java-best-practices]] — Spring Boot 3.1+ `@ServiceConnection`, singleton 패턴, CI에서 reuse 금지.
|
||||
- [[raw/official-docs/dx-mise-asdf-tool-versioning]] — `.tool-versions` 사실상 표준, `.sdkmanrc`와의 drift 위험, Temurin 21 LTS.
|
||||
- [[raw/official-docs/dx-devcontainer-spring-boot]] — devcontainer가 보장하는 것/보장하지 않는 것, IDE 종속성.
|
||||
|
||||
### Canonical 참조
|
||||
|
||||
- [[raw/project-notes/ca-skeleton-operational-contract]] §29 Group G-E — DevOps / CI / Supply chain / DX 대안 조사 인덱스.
|
||||
@@ -1 +0,0 @@
|
||||
../../vault/30-knowledge/concepts/distributed-tracing-baggage.md
|
||||
@@ -0,0 +1,64 @@
|
||||
---
|
||||
title: concept / Distributed Tracing & Baggage
|
||||
source_type: llm-generated
|
||||
status: reviewed
|
||||
confidence: high
|
||||
tags: [concept, ca-tmpl, observability, mdc, span-event]
|
||||
related_projects: [ca-tmpl]
|
||||
last_reviewed: 2026-06-15
|
||||
---
|
||||
|
||||
# concept / Distributed Tracing & Baggage
|
||||
|
||||
## Summary
|
||||
|
||||
여러 마이크로서비스를 거쳐 흐르는 단일 요청의 실행 흐름을 시각화하고 진단할 수 있도록 트레이스 ID와 스팬 ID 등의 메타데이터(TraceContext)를 전파하고, 전체 트레이스 수명 주기 동안 요청 전반에 걸쳐 데이터를 전달(Baggage)하는 기술.
|
||||
|
||||
## Standard (공식 정의)
|
||||
|
||||
W3C Distributed Tracing 및 OpenTelemetry 표준 명세에 따른 정의는 다음과 같다.
|
||||
- **traceparent**: 실행 중인 분산 요청의 컨텍스트를 규격화한 W3C 공식 헤더.
|
||||
- 형식: `version-traceId-parentId-traceFlags` (예: `00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01`)
|
||||
- `traceFlags`의 마지막 비트가 `01`이면 샘플링됨(Sampled), `00`이면 샘플링되지 않음(Not-Sampled)을 나타낸다.
|
||||
- **baggage**: 분산 트레이스 경계 전반에 걸쳐 임의의 키-값 쌍 메타데이터를 전파하기 위한 W3C 헤더 규격. 클라이언트 요청 처리 중 하위 모든 마이크로서비스 호출 시에 함께 흘러간다.
|
||||
- 형식: `key1=value1,key2=value2`
|
||||
|
||||
## 한계 / 주의점
|
||||
|
||||
- **보안 경계 허점 (Security Boundary Risk)**: Baggage는 하위 시스템과 외부 네트워크 경계까지 쉽게 유실/전파될 수 있으므로, 민감 정보(자격증명, 개인정보(PII), 비밀 토큰)가 포함될 경우 데이터 유출의 주요 통로가 된다. 따라서 반드시 어댑터 송출 단계에서 엄격한 허용 목록(Allowlist) 필터링을 거치거나 원천 차단해야 한다.
|
||||
- **샘플링 불일치 (Sampling Mismatch)**: 마이크로서비스 상위 계층에서 샘플링되지 않은(`00`) 트레이스 헤더가 다운스트림으로 내려가면 하위 서비스들은 해당 요청에 대한 상세 스팬 지표를 수집하지 않고 드랍할 수 있어, 트레이스 경로가 끊어지는 현상이 발생할 수 있다.
|
||||
|
||||
## Project Application
|
||||
|
||||
- [[wiki/explainer/adapter-outbound.md]]
|
||||
- `TraceContextPropagationInterceptor`가 RestClient 요청 송출 시 MDC(Mapped Diagnostic Context)에 저장된 트레이스 및 배기지 컨텍스트를 가로채 전파함.
|
||||
- `traceparent`는 MDC `trace_id`와 `span_id`를 기반으로 동적으로 조립되어 전송됨 (현재는 추적 서버로 전송하지 않는 기본 뼈대이므로 샘플 플래그는 `00`으로 고정함).
|
||||
- `baggage`의 경우 보안 누출 방지를 위해 오직 **`request_id`**와 **`tenant_id`** 두 가지만 통과시키는 허용 목록 필터링(`BaggageAllowlist.filter`)을 적용함.
|
||||
|
||||
## Claim-backed Knowledge
|
||||
|
||||
| Knowledge Point | Supporting Claims | Confidence | Notes |
|
||||
|---|---|---|---|
|
||||
| W3C traceparent 헤더 포맷 및 전파 규격 | `raw/official-docs/trace-context-w3c-recommendation.md` | `high` | W3C 공식 권고안 |
|
||||
| Baggage API 스펙 및 데이터 필터링 필요성 | `raw/official-docs/baggage-w3c-baggage-spec.md` | `high` | W3C Baggage 사양 |
|
||||
|
||||
## 내가 설명할 수 있어야 하는 것
|
||||
|
||||
- `traceparent` 헤더의 구성 요소와 샘플링 플래그(`01`/`00`)의 역할은 무엇인가?
|
||||
- 왜 Baggage 전파 시 Allowlist 기반의 보안 필터링이 필수적으로 수반되어야 하는가?
|
||||
- 우리 아웃바운드 HTTP 클라이언트의 트레이싱 전파 시 뼈대 코드(Skeleton)의 한계는 무엇이며, 향후 실무 OTel SDK 연동 시 어떻게 대응해야 하는가? (하드코딩된 `00` 샘플링 해제 및 OTel RestClient Interceptor로의 전환)
|
||||
|
||||
## Interview Questions
|
||||
|
||||
- 마이크로서비스 간 분산 트레이싱을 구현할 때 HTTP 헤더 전파(Propagation) 과정과 Baggage 활용 시 주의해야 할 보안 위협에 대해 설명해 주세요.
|
||||
- MDC 기반 트레이싱 컨텍스트와 실제 OpenTelemetry / Micrometer Tracing API의 생명 주기를 멀티스레드 환경에서 어떻게 안전하게 바인딩할 수 있습니까?
|
||||
|
||||
## Do Not Overclaim
|
||||
|
||||
- "MDC 정보가 자동으로 헤더로 전파되므로 어떤 환경에서든 분산 트레이싱이 정상 작동한다"고 과장해서는 안 된다. 멀티스레드 비동기 작업(TaskExecutor 사용 시)이나 리액티브 환경에서는 MDC가 유실되므로 별도의 Context Propagator를 직접 정의하여 스레드 경계를 가로지르는 전파 설계를 갖춰야만 보장된다.
|
||||
|
||||
## Sources
|
||||
|
||||
- [W3C Recommendation for Trace Context](https://www.w3c.org/TR/trace-context/)
|
||||
- [[raw/official-docs/trace-context-w3c-recommendation.md]]
|
||||
- [[raw/official-docs/baggage-w3c-baggage-spec.md]]
|
||||
@@ -1 +0,0 @@
|
||||
../../vault/30-knowledge/concepts/fail-open-fail-closed.md
|
||||
@@ -0,0 +1,61 @@
|
||||
---
|
||||
title: concept / Fail-Open & Fail-Closed
|
||||
source_type: llm-generated
|
||||
status: reviewed
|
||||
confidence: high
|
||||
tags: [concept, ca-tmpl, architecture, spring-boot, circuit-breaker]
|
||||
related_projects: [ca-tmpl]
|
||||
last_reviewed: 2026-06-15
|
||||
---
|
||||
|
||||
# concept / Fail-Open & Fail-Closed
|
||||
|
||||
## Summary
|
||||
|
||||
장애가 발생했을 때 시스템이 취하는 두 가지 상반된 처리 모델.
|
||||
- **Fail-Open (실패 개방)**: 외부 시스템/인프라 장애 시 요청을 통과시키거나 대체 수단(Cache-Miss 등)으로 우회하여 핵심 비즈니스 기능을 계속 수행한다.
|
||||
- **Fail-Closed (실패 폐쇄)**: 외부 시스템/인프라 장애 발생 시 즉시 시스템 전체 또는 해당 기능을 중단하고 예외를 전파하여 불완전한 상태에서의 처리를 강력히 차단한다.
|
||||
|
||||
## Standard (공식 정의)
|
||||
|
||||
공식적인 소프트웨어 및 인프라 설계 기법(SRE 및 분산 아키텍처)에 따르면 두 모델의 정의는 다음과 같다.
|
||||
- **Fail-Open**: 보안 게이트웨이나 캐시 계층 같은 비핵심 인프라가 먹통이 되었을 때, 인프라 부재 상태를 '허용'하여 전체 서비스 가용성을 최대화하는 모델. 예컨대 캐시 서버가 죽으면 DB를 조회(Cache-miss로 취급)하도록 하여 기능 정지를 막는다.
|
||||
- **Fail-Closed**: 원격 트랜잭션, 아웃박스 발행기 등 데이터 정합성이 극도로 중요한 구간에서 하위 시스템이 오류를 뱉으면 호출자에게 오류를 전파하고 전체 처리를 롤백하는 모델.
|
||||
|
||||
## 한계 / 주의점
|
||||
|
||||
- **Fail-Open의 함정**: 가용성은 유지되나 백엔드 DB에 트래픽이 폭증(Cache Stampede)하거나, 장애가 전파되어 전체 시스템이 도미노처럼 무너질 위험이 있다. 따라서 반드시 서킷 브레이커, Rate Limiter 같은 보호막이 함께 작동해야 한다.
|
||||
- **Fail-Closed의 함정**: 가용성이 급격히 떨어진다. 단 하나의 마이크로서비스나 인프라 장애로 인해 전체 서비스가 5xx 에러를 뿜으며 중단될 수 있다.
|
||||
|
||||
## Project Application
|
||||
|
||||
- [[wiki/explainer/adapter-outbound.md]]
|
||||
- `FailOpenCacheStore`에서는 캐시 인프라 장애 시 예외를 삼키고 캐시 미스로 처리하는 Fail-Open을 적용함.
|
||||
- `KafkaOutboxMessagePublishAdapter`는 아웃박스 이벤트 유실 방지를 위해 Fail-Closed를 적용하여 예외를 반드시 상위로 전파함.
|
||||
|
||||
## Claim-backed Knowledge
|
||||
|
||||
| Knowledge Point | Supporting Claims | Confidence | Notes |
|
||||
|---|---|---|---|
|
||||
| 캐시 붕괴 시 DB 조회 등으로 가용성을 지키는 것 | `raw/official-docs/cache-aside-vs-write-through-aws.md` | `high` | AWS 캐시 아키텍처 가이드라인 |
|
||||
| Fail-Open 구조에서 유실되지 않아야 할 이벤트 처리 | `raw/official-docs/event-sourcing-vs-outbox-microservices-io.md` | `high` | 마이크로서비스 트랜잭션 보장 기법 |
|
||||
|
||||
## 내가 설명할 수 있어야 하는 것
|
||||
|
||||
- Fail-Open과 Fail-Closed의 극명한 결정 기준은 무엇인가? (가용성 우선 vs 정합성/안전성 우선)
|
||||
- 우리 프로젝트의 캐시 스토어와 아웃박스 발행기는 각각 어떤 모델을 따르며 그 이유는 무엇인가?
|
||||
- Fail-Open 적용 시 백엔드 DB 보호를 위해 어떤 추가 장치가 필요한가?
|
||||
|
||||
## Interview Questions
|
||||
|
||||
- Redis 캐시 서버가 갑자기 중단되었을 때, 귀하의 시스템은 어떻게 동작하며 이를 위해 어떤 resilience 패턴을 적용했습니까?
|
||||
- 메시지 발행 실패 시 예외를 상위로 전파하는 구조(Fail-Closed)와 삼켜버리는 구조(Fail-Open)의 아키텍처적 트레이드오프를 설명하십시오.
|
||||
|
||||
## Do Not Overclaim
|
||||
|
||||
- "Fail-Open을 적용했으므로 인프라가 죽어도 시스템에 아무런 영향이 없다"고 과장해서는 안 된다. 캐시가 없으면 DB 부하가 치솟으므로 성능 저하와 2차 장애 위험이 상존함을 인정해야 한다.
|
||||
|
||||
## Sources
|
||||
|
||||
- [AWS Cache-Aside caching strategy](https://aws.amazon.com/caching/)
|
||||
- [[raw/official-docs/cache-aside-vs-write-through-aws.md]]
|
||||
@@ -1 +0,0 @@
|
||||
../../vault/30-knowledge/concepts/idempotency-key-design.md
|
||||
@@ -0,0 +1,141 @@
|
||||
---
|
||||
title: Idempotency Key 설계 (triple scope vs Stripe/Square/Toss)
|
||||
source_type: llm-generated
|
||||
status: draft
|
||||
confidence: medium
|
||||
tags: [idempotency, api-design, distributed-systems]
|
||||
related_projects: [ca-skeleton]
|
||||
last_reviewed: 2026-05-22
|
||||
---
|
||||
|
||||
# Idempotency Key 설계 (triple scope vs Stripe/Square/Toss)
|
||||
|
||||
> Layer: `wiki/concepts/` — 일반 개념. 내 프로젝트 사실은 [[raw/branch-notes/feature-rate-limit-idempotency-contract]] / [[raw/project-notes/ca-skeleton-operational-contract]] §29 Topic 5 참조.
|
||||
|
||||
## Summary
|
||||
|
||||
Idempotency key는 동일한 mutating request의 재시도를 서버가 인식하도록 클라이언트가 생성하는 고유 값입니다. ca-tmpl은 key shape를 `(authenticatedPrincipal, idempotencyKey, useCaseName)` triple + DB table + 24h TTL + 200ms in-flight wait + fingerprint mismatch 시 HTTP 422로 정의합니다. 이 설계는 (a) triple scope로 endpoint dimension을 명시해 cross-use-case 충돌을 방지하고, (b) 24h TTL로 스토리지·키 추측 공격면을 최소화하며, (c) 200ms wait로 IETF draft의 즉시 409보다 retry 친화적인 hybrid를 채택하고, (d) body fingerprint mismatch를 409(in-flight)와 분리해 422로 표현한 점이 특징입니다.
|
||||
|
||||
## Standard (공식 정의)
|
||||
|
||||
### IETF draft (`draft-ietf-httpapi-idempotency-key-header`, draft-07, 2025-10)
|
||||
|
||||
- `Idempotency-Key` HTTP request header를 정의 — Stripe / PayPal / Square / Adyen이 공통 참조하는 사실상의 헤더 표준 초안 (정식 RFC 아님).
|
||||
- 인용: *"Uniqueness of the key MUST be defined by the resource owner and MUST be implemented by the clients."* — key scope 정의는 **resource owner의 책임**으로 위임.
|
||||
- 인용: *"If there is an attempt to reuse an idempotency key with a different request payload, the resource SHOULD reply with a HTTP `422` status code."*
|
||||
- 인용: *"The request was retried before the original request completed. The resource SHOULD respond with a resource conflict error"* (HTTP `409`).
|
||||
- TTL은 시간을 명시하지 않고 "정책을 정해 문서화하라"만 강제.
|
||||
|
||||
### Stripe v1 pair → v2 triple
|
||||
|
||||
- v1: `(account, Idempotency-Key)` pair. TTL 24h minimum. 5xx 응답까지 그대로 replay됨(결정적 응답).
|
||||
- v2: *"idempotent request replay occurs when requests use the same idempotency key, are made to the same API, occur within the scope of the same account or sandbox, and occur within 30 days of each other."* → `(account/sandbox, API, key)` triple. TTL 30일.
|
||||
- fingerprint mismatch: *"The idempotency layer compares incoming parameters to those of the original request and errors if they're not the same."* (status code는 명시 안 함).
|
||||
|
||||
### Square (Common API patterns)
|
||||
|
||||
- `idempotency_key`를 **body 필드**로 받음 (header 표준 미준수). endpoint별 dedup → `(merchant_account, endpoint, idempotency_key)` 사실상 triple.
|
||||
- fingerprint mismatch: *"If you use the same idempotency key but change the `CreatePayment` request ... you get an error indicating that you used the idempotency key previously."*
|
||||
- TTL 미공개, in-flight 동작 미정의.
|
||||
- 특수 디자인: `cancel-payment-by-idempotency-key` — 키 자체를 resource handle로 사용.
|
||||
|
||||
### PayPal (Idempotency-Replay / `PayPal-Request-Id`)
|
||||
|
||||
- header 이름이 `Idempotency-Key`가 아닌 `PayPal-Request-Id` (Stripe·IETF와 다름).
|
||||
- scope: `(request-id, API call type)`. TTL **45일** — 조사된 reference 중 최장.
|
||||
|
||||
### Toss Payments (기술블로그)
|
||||
|
||||
- 4-tuple `(account, key, URL, method)` + TTL **15일**. ca-tmpl보다 dimension 1개 많고 TTL 더 김.
|
||||
- header 이름은 `Idempotency-Key`로 IETF/Stripe와 동일.
|
||||
|
||||
### AWS Lambda Powertools (idempotency utility)
|
||||
|
||||
- key를 **server-derived content-hash** `(function_name, payload_hash)`로 도출 → 클라이언트가 header를 보낼 필요 없음.
|
||||
- 동일 payload면 동일 hash → 자동 dedup. body 변경 = 서로 다른 operation으로 취급.
|
||||
|
||||
### GitHub REST API
|
||||
|
||||
- API-level idempotency dedup을 제공하지 않음. 클라이언트 측 retry 정책에만 의존.
|
||||
|
||||
### Brandur (Stripe 엔지니어 글) — Postgres locked_at lock
|
||||
|
||||
- Postgres 테이블 + atomic phase 모델 + `locked_at` column으로 in-flight를 표현. abandoned key 회수는 별도 정책 필요.
|
||||
- Stripe 내부 구현의 가장 자세한 reference 문서.
|
||||
|
||||
## 한계 / 주의점
|
||||
|
||||
| 옵션 | 한계 / 주의점 |
|
||||
|------|-----------|
|
||||
| **Stripe v1 pair `(account, key)`** | endpoint dimension 부재 → API 추가 시 같은 키가 의도하지 않은 use case에 재사용될 위험. v2에서 API dimension 추가로 직접 보강. |
|
||||
| **Stripe v2 triple `(account, API, key)`** | IETF "resource owner가 정의" 범위 내에서 가장 엄격한 reference. TTL 30일은 보안 surface와 비용에 부담. |
|
||||
| **Square endpoint-scoped (body field)** | header 표준 미준수 → 미들웨어/게이트웨이 레벨에서 dedup 불가. URL path 변경 시 endpoint dimension 매핑이 깨질 수 있음. TTL 미공개로 클라이언트가 retry window를 가늠 못 함. |
|
||||
| **PayPal 45일 TTL** | 스토리지 비용 크고 키 추측 공격면이 가장 넓음. header 이름이 표준과 달라 멀티 PG 통합 비용 발생. |
|
||||
| **Toss 4-tuple `(account, key, URL, method)`** | URL/method가 scope에 들어가 HTTP path 변경(예: `/v1/payments` → `/v2/payments`) 시 같은 의미의 재시도가 다른 키로 인식. version migration에 취약. |
|
||||
| **AWS Powertools content-hash** | 클라이언트가 키를 누락해도 동작하는 장점이 있으나, body의 사소한 변경(여백/필드 순서)이 다른 operation으로 분류 — JSON canonicalization 정책 필수. |
|
||||
| **Brandur Postgres lock (`locked_at`)** | `locked_at`만으로는 process crash 후 stale lock이 남을 수 있음 → abandoned key 회수(timeout-based release) 정책이 별도로 필요. |
|
||||
| **IETF draft 자체** | draft 단계로 정식 RFC 아님. TTL / 저장 layer / lock 정책 등 운영 핵심을 표준이 다루지 않아 구현체별 동작이 제각각. |
|
||||
| **No API-level dedup (GitHub)** | 인프라/미들웨어 부담은 없으나 클라이언트가 모든 중복 위험을 책임 → 결제·금융 도메인에는 부적합. |
|
||||
|
||||
### 흔한 오해
|
||||
|
||||
- "Stripe pair보다 ca-tmpl이 무조건 안전" — **v1 한정** 비교. Stripe v2 triple과는 사실상 동등.
|
||||
- "IETF draft 422는 fingerprint mismatch의 표준" — draft는 `SHOULD`이지 `MUST` 아님. 구현체별로 400/409/422가 혼재.
|
||||
- "TTL은 길수록 안전하다" — 길수록 클라이언트 retry window는 늘지만 스토리지 비용과 키 추측 공격면도 함께 증가.
|
||||
|
||||
## Project Application
|
||||
|
||||
- [[wiki/projects/ca-tmpl/idempotency-key-design]] — ca-tmpl 의사결정 기록 (현재 `documented-only`, Phase C2 미진입). 실제 구현 여부는 project 문서 참조.
|
||||
- [[raw/branch-notes/feature-rate-limit-idempotency-contract]] — key shape / TTL / 저장소 SSOT (triple scope + DB table + 24h TTL + 200ms wait + 422 fingerprint mismatch + 409 in-flight 결정의 owning branch).
|
||||
- [[raw/branch-notes/feature-api-contract-baseline]] — `Idempotency-Key` HTTP header 표준 (consume only, shape은 위 branch가 owns).
|
||||
- [[raw/project-notes/ca-skeleton-operational-contract]] §29 Topic 5 — 비교표·결정 라인.
|
||||
|
||||
## Interview Questions
|
||||
|
||||
- **Q1.** `useCaseName` (또는 endpoint) dimension을 scope에 포함시키는 이유는? Stripe v1 pair에서 어떤 충돌이 발생할 수 있는가?
|
||||
- **Q2.** TTL을 24h로 잡은 trade-off는? PayPal 45일·Stripe v2 30일과 비교했을 때 어떤 비용·위험을 줄이고, 어떤 use case(예: 결제·송금 long-running)에서는 부족한가?
|
||||
- **Q3.** 동시 도착 요청에 대해 200ms wait를 둔 의미는? IETF draft의 즉시 409와 비교했을 때 client retry 동작이 어떻게 달라지는가?
|
||||
- **Q4.** 같은 key + 다른 body를 422로, in-flight 충돌을 409로 분리한 이유는? 두 상황을 같은 코드로 합치면 어떤 클라이언트 버그가 가려지는가?
|
||||
- **Q5.** key가 클라이언트 생성 unique value라면 추측 공격면은 어떻게 평가해야 하는가? TTL이 길수록 공격면이 어떻게 변하고, AWS Powertools content-hash 방식은 이 문제를 어떻게 우회하는가?
|
||||
|
||||
## Do Not Overclaim
|
||||
|
||||
- "ca-tmpl triple이 Stripe pair보다 무조건 안전하다"고 말하지 않습니다. **v1 pair 한정** 비교이며, Stripe v2 triple과는 사실상 동급.
|
||||
- "ca-tmpl이 IETF Idempotency-Key spec을 완전히 준수한다"고 단정하지 않습니다. **draft 단계**이고, 422 fingerprint mismatch는 `SHOULD`이며, ca-tmpl의 200ms wait는 draft의 "즉시 409" 권고와 다른 선택입니다.
|
||||
- "Square가 표준 미준수라서 열등하다"고 단정하지 않습니다. body 필드 방식은 `cancel-by-idempotency-key`처럼 키를 resource handle로 쓰는 API 디자인의 장점이 있습니다.
|
||||
- "AWS Powertools content-hash가 header 방식의 상위 호환"이라고 말하지 않습니다. body의 사소한 변경(여백/필드 순서/timestamp)이 다른 operation으로 분류되므로 canonicalization 정책이 함께 가야 동작합니다.
|
||||
- "Brandur lock 패턴을 그대로 채택했다"고 말하지 않습니다. ca-tmpl은 200ms wait + unique constraint hybrid이며 Brandur `locked_at` lock의 변형입니다.
|
||||
- ca-tmpl 24h TTL이 "업계 표준"이라고 표현하지 않습니다. Stripe v1 최소값과 일치할 뿐이고, 다른 도메인 reference는 모두 더 길게 잡습니다.
|
||||
|
||||
## Sources
|
||||
|
||||
### 공식 / 표준
|
||||
|
||||
- [IETF draft — The Idempotency-Key HTTP Header Field](https://datatracker.ietf.org/doc/draft-ietf-httpapi-idempotency-key-header/) — 422/409 status code 근거, "resource owner가 scope 정의" 권한 위임.
|
||||
- [Stripe API Reference — Idempotent requests](https://docs.stripe.com/api/idempotent_requests) — v1 pair / v2 triple scope, 24h–30d TTL, 5xx replay.
|
||||
- [Square API — Idempotency (Common API patterns)](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency) — body 필드 방식, fingerprint mismatch error.
|
||||
- [PayPal — Idempotency](https://developer.paypal.com/api/rest/reference/idempotency/) — `PayPal-Request-Id`, 45일 TTL.
|
||||
- [AWS Lambda Powertools — Idempotency utility](https://docs.powertools.aws.dev/lambda/python/latest/utilities/idempotency/) — content-hash 기반.
|
||||
- [GitHub REST API](https://docs.github.com/en/rest) — API-level dedup 없음.
|
||||
|
||||
### 구현 reference
|
||||
|
||||
- [Brandur Leach — Implementing Stripe-like Idempotency Keys in Postgres](https://brandur.org/idempotency-keys) — atomic phase + `locked_at` lock.
|
||||
|
||||
### raw 보존본
|
||||
|
||||
- [[raw/official-docs/idempotency-ietf-draft]]
|
||||
- [[raw/official-docs/idempotency-stripe-api-ref]]
|
||||
- [[raw/official-docs/idempotency-square-api]]
|
||||
- [[raw/official-docs/idempotency-paypal-docs]]
|
||||
- [[raw/official-docs/idempotency-aws-lambda-powertools]]
|
||||
- [[raw/official-docs/idempotency-no-api-level-github-rest]]
|
||||
- [[raw/company-tech-blogs/idempotency-brandur-stripe-postgres]]
|
||||
- [[raw/company-tech-blogs/idempotency-toss-payments-techblog]]
|
||||
- [[raw/company-tech-blogs/idempotency-redis-vs-db-storage]]
|
||||
|
||||
### canonical 참조
|
||||
|
||||
- [[raw/project-notes/ca-skeleton-operational-contract]] §29 Topic 5
|
||||
- [[raw/branch-notes/feature-rate-limit-idempotency-contract]]
|
||||
- [[raw/branch-notes/feature-api-contract-baseline]]
|
||||
@@ -1 +0,0 @@
|
||||
../../vault/30-knowledge/concepts/idempotency.md
|
||||
@@ -0,0 +1,60 @@
|
||||
---
|
||||
title: concept / Idempotency
|
||||
source_type: llm-generated
|
||||
status: reviewed
|
||||
confidence: high
|
||||
tags: [concept, ca-tmpl, api-design, spring-boot, idempotency]
|
||||
related_projects: [ca-tmpl]
|
||||
last_reviewed: 2026-06-15
|
||||
---
|
||||
|
||||
# concept / Idempotency
|
||||
|
||||
## Summary
|
||||
|
||||
동일한 요청을 한 번 보내는 것과 여러 번 연속해서 보내는 것이 서버의 상태에 미치는 영향이 동일한 성질.
|
||||
- 안전한 메서드(Safe Methods) 및 멱등한 메서드(Idempotent Methods)를 구분하여 HTTP 클라이언트의 재시도 안전성을 보장하는 기반이 된다.
|
||||
|
||||
## Standard (공식 정의)
|
||||
|
||||
RFC 9110 HTTP Semantics 규격에 따른 정의는 다음과 같다.
|
||||
- **Idempotent Methods**: `GET`, `HEAD`, `PUT`, `DELETE`, `OPTIONS`, `TRACE`는 여러 번 수행해도 리소스의 최종 상태가 동일하다. 따라서 transient network failure 발생 시 클라이언트가 안전하게 재시도할 수 있다.
|
||||
- **Non-Idempotent Methods**: `POST`와 `PATCH`는 호출할 때마다 새로운 리소스가 생성되거나 상태 변경이 누적될 수 있어, 재시도가 안전하지 않다. 중복 처리를 방지하려면 별도의 `Idempotency-Key` 헤더와 같은 고유 분산 락/식별 메커니즘이 합의되어야 한다.
|
||||
|
||||
## 한계 / 주의점
|
||||
|
||||
- **멱등성은 서버가 보장해야 하는 계약이다**: 클라이언트 입장에서 단순히 `GET`을 보낸다고 해서 서버가 내부적으로 멱등하게 처리하지 않고 사이드 이펙트(예: 조회수 1 증가 등)를 누적한다면 엄격한 의미의 멱등성은 깨질 수 있다. 그러나 HTTP 명세상 클라이언트는 RFC 규격을 신뢰하고 재시도를 감행하게 된다.
|
||||
- **Idempotency-Key 계약의 부재**: 아웃바운드 연동 시 상대방 서버가 `Idempotency-Key` 사양을 구현하지 않았다면, `POST`나 `PATCH` 호출 실패 시 클라이언트는 네트워크 지연 등의 원인으로 인해 요청이 이미 처리되었는지 알 수 없어 재시도가 불가능하다.
|
||||
|
||||
## Project Application
|
||||
|
||||
- [[wiki/explainer/adapter-outbound.md]]
|
||||
- `OutboundRetryPolicy`는 RFC 9110 규격에 정의된 멱등한 메서드(`GET`, `HEAD`, `PUT`, `DELETE`)에 대해서만 `shouldRetry`가 `true`를 반환하도록 설계되어 있음. `POST`/`PATCH`는 부작용 방지를 위해 즉시 `false`를 뱉고 재시도를 전면 금지함.
|
||||
|
||||
## Claim-backed Knowledge
|
||||
|
||||
| Knowledge Point | Supporting Claims | Confidence | Notes |
|
||||
|---|---|---|---|
|
||||
| RFC 9110 기반 멱등 메서드 리스트 및 재시도 타당성 | `raw/official-docs/rfc9110-http-semantics.md` | `high` | RFC 9110 표준 명세 |
|
||||
| non-idempotent API 재시도를 위한 Idempotency-Key 계약 | `raw/official-docs/idempotency-stripe-api-ref.md` | `high` | Stripe의 실무 멱등 키 처리 패턴 |
|
||||
|
||||
## 내가 설명할 수 있어야 하는 것
|
||||
|
||||
- `GET`과 `PUT`은 왜 멱등하고 `POST`와 `PATCH`는 왜 비멱등한가?
|
||||
- 왜 우리 아웃바운드 HTTP 클라이언트는 `POST`/`PATCH` 요청에 대해 재시도를 원천 차단하는가? (Idempotency-Key 계약 미정의에 따른 사이드 이펙트 방지)
|
||||
- 비멱등 메서드를 꼭 재시도해야 할 경우, 인프라 및 애플리케이션 계층에서 어떤 설계를 보완해야 하는가?
|
||||
|
||||
## Interview Questions
|
||||
|
||||
- HTTP 메서드 중 멱등성을 보장하는 메서드와 그렇지 않은 메서드를 구분하고, 네트워크 타임아웃 발생 시 각각에 대한 재시도 전략을 설명해 주세요.
|
||||
- 아웃바운드 호출 시 POST 요청의 재시도를 제한하는 시스템에서, 일시적인 네트워크 순단 상황을 어떻게 극복할 수 있겠습니까?
|
||||
|
||||
## Do Not Overclaim
|
||||
|
||||
- "멱등한 메서드만 재시도하므로 어떠한 데이터 정합성 문제도 발생하지 않는다"고 확언해서는 안 된다. 업스트림(상대방 서버)이 표준을 무시하고 내부 구현을 비멱등하게 작성했을 경우 여전히 사이드 이펙트가 발생할 수 있음을 인지해야 한다.
|
||||
|
||||
## Sources
|
||||
|
||||
- [RFC 9110 Section 9.3: Idempotent Methods](https://www.rfc-editor.org/rfc/rfc9110.html)
|
||||
- [[raw/official-docs/rfc9110-http-semantics.md]]
|
||||
- [[raw/official-docs/idempotency-stripe-api-ref.md]]
|
||||
@@ -1 +0,0 @@
|
||||
../../vault/30-knowledge/concepts/multi-tenancy-isolation-patterns.md
|
||||
@@ -0,0 +1,142 @@
|
||||
---
|
||||
title: Multi-tenancy Isolation 패턴 (Pool vs Silo vs Bridge)
|
||||
source_type: llm-generated
|
||||
status: draft
|
||||
confidence: medium
|
||||
tags: [multi-tenancy, saas, isolation]
|
||||
related_projects: [ca-skeleton]
|
||||
last_reviewed: 2026-05-22
|
||||
---
|
||||
|
||||
# Multi-tenancy Isolation 패턴 (Pool vs Silo vs Bridge)
|
||||
|
||||
> Layer: `wiki/concepts/` — 일반 개념. 실제 적용은 `wiki/projects/` 또는 raw 브랜치 노트 참조.
|
||||
|
||||
## Summary
|
||||
|
||||
Multi-tenancy isolation은 "여러 tenant가 같은 소프트웨어 인스턴스를 어느 수준까지 공유하는가"의 스펙트럼이다. AWS SaaS Lens는 이를 **Silo / Pool / Bridge** 3분류로 정리하고, Hibernate는 ORM 레벨에서 **DATABASE / SCHEMA / DISCRIMINATOR** 3 strategy로 공식 지원하며, Azure는 **Deployment Stamps** 패턴으로 hybrid를 다룬다. ca-tmpl은 **opt-in(`APP_TENANT_ENABLED=true` 시만 활성) + shared DB + `tenant_id` column(ULID) + JWT claim 우선 resolution** 조합을 baseline으로 채택한다. 이는 AWS Pool 모델 + Hibernate DISCRIMINATOR 전략에 해당하며, B2B 초기 단계(tenant 수 수십~수백 단위)에 isolation 비용 대비 운영 단순성을 우선한 의도적 선택이다. opt-in 설계의 의의는 single-tenant deployment에서는 tenant 로직 자체를 비활성화하여 skeleton의 적용 범위를 넓힌 점에 있다. **Migration trigger 3가지**는 (a) 규제(금융·의료) isolation 강제, (b) tenant 수 수백~수천 + 단일 row 수 수억 도달, (c) enterprise tier 등장으로 isolation을 가격에 반영해야 할 때다.
|
||||
|
||||
## Standard (공식 정의)
|
||||
|
||||
### AWS SaaS Tenant Isolation Strategies (Whitepaper) — Silo / Pool / Bridge
|
||||
|
||||
- **Silo**: tenant마다 별도 stack(compute/DB/network까지 분리). isolation 최강, 비용 최대.
|
||||
- **Pool**: 모든 tenant가 동일 infra와 schema를 공유, `tenant_id` 컬럼으로 row-level 구분.
|
||||
- **Bridge**: 일부 리소스는 silo, 일부는 pool. 예) DB는 silo, app server는 pool.
|
||||
- AWS는 "Authentication is not isolation. You must enforce isolation at the resource layer"라고 명시한다.
|
||||
|
||||
### Hibernate ORM Multi-tenancy — DATABASE / SCHEMA / DISCRIMINATOR
|
||||
|
||||
- **DATABASE**: tenant별 별도 데이터베이스.
|
||||
- **SCHEMA**: 동일 DB, tenant별 별도 schema.
|
||||
- **DISCRIMINATOR**: 동일 schema, `tenant_id` 컬럼. Hibernate 6부터 native 지원(이전엔 Filter로 우회).
|
||||
- 활성화는 `hibernate.tenant_identifier_resolver` + `hibernate.multi_tenant_connection_provider` 설정으로 수행. `CurrentTenantIdentifierResolver`가 ThreadLocal/SecurityContext에서 tenant를 결정.
|
||||
|
||||
### Azure Architecture Center — Deployment Stamps (Hybrid)
|
||||
|
||||
- Tenancy를 "fully shared → shared compute, isolated DB → isolated stamp → isolated subscription" **스펙트럼**으로 정의.
|
||||
- **Deployment Stamps**: 동일한 스택을 단위(stamp)로 복제하고, stamp 안에 N개 tenant를 pool. tier별로 stamp 크기와 isolation 수준을 다르게 둘 수 있음.
|
||||
- Microsoft는 "There's no single right approach to multitenancy"라고 명시 — 비즈니스 모델·규제·확장성·비용에 따라 모델이 달라진다.
|
||||
|
||||
### Tenant Resolution 방식 (isolation과 직교)
|
||||
|
||||
- **JWT claim**: token 서명 검증으로 위변조 방지. 가장 안전.
|
||||
- **Subdomain (`{tenant}.app.com`)**: UX 친화적, 단 wildcard DNS/TLS 필요.
|
||||
- **Custom header (`X-Tenant-Id`)**: 단순하나 외부 trust boundary에서 단독 신뢰 금지.
|
||||
- **Path (`/t/{tenant}/...`)**: routing 자연스럽지만 모든 client URL 변경.
|
||||
|
||||
## 한계 / 주의점
|
||||
|
||||
각 대안의 한계는 다음과 같다.
|
||||
|
||||
### shared DB + tenant_id (Pool / Hibernate DISCRIMINATOR)
|
||||
|
||||
- **Noisy neighbor**: hot tenant가 같은 인스턴스 전체에 영향.
|
||||
- **규제 isolation 불가**: application bug 한 줄로 cross-tenant leak 가능. HIPAA·FedRAMP·금융권은 storage 레벨 분리를 요구하는 경우가 있어 Pool로 충족 어려움.
|
||||
- **Index 비용**: tenant로 filter하는 모든 index에 `tenant_id`를 leading column으로 포함해야 plan이 효율적.
|
||||
- **Native query/JDBC bypass 위험**: JPQL 경로 외에서 tenant filter 누락 시 leak.
|
||||
|
||||
### Subdomain-based resolution
|
||||
|
||||
- **Wildcard DNS와 wildcard TLS 인증서** 필요. custom domain 지원 시 per-domain 인증서 자동화 추가.
|
||||
- Let's Encrypt rate limit은 "registered domain당 주 50개 인증서"로 보고되나 — 정확 수치와 적용 범위는 `needs-confirmation` (raw 발췌 기준).
|
||||
- **DNS propagation 지연**, **subdomain takeover 위험**(tenant 삭제 후 DNS record 미정리), **CORS/cookie domain 설정 복잡성**.
|
||||
- Local dev는 `lvh.me`/`nip.io`/hosts 수정 필요.
|
||||
|
||||
### JWT claim only
|
||||
|
||||
- claim 검증을 한 곳이라도 빠뜨리면 cross-tenant 위험.
|
||||
- token 재발급 없이 tenant 전환 불가 → admin/support 운영 동선 제약.
|
||||
- IdP와 강결합 → tenant 정보 변경 시 token rotation 정책 필요.
|
||||
|
||||
### Schema-per-tenant (Hibernate SCHEMA)
|
||||
|
||||
- Postgres metadata(`pg_class`, `pg_attribute`) overhead가 tenant 수 증가에 따라 누적.
|
||||
- Stripe/Citus 자료에 따르면 "수백~수천 tenant"에서 catalog bloat·autovacuum·plan cache miss가 문제로 보고됨 — 다만 정확한 임계 수치 인용은 `needs-confirmation`.
|
||||
- **Connection pooling 난이도**: `search_path` 전환이 plan cache를 무효화. HikariCP per tenant vs single pool 설계 선택 필요.
|
||||
- 마이그레이션이 tenant 수만큼 반복(Flyway `schemas` 옵션으로 일괄 처리 가능하나 추가/삭제 자동화 필요).
|
||||
|
||||
### Database-per-tenant (Silo)
|
||||
|
||||
- Isolation 가장 강함, **운영 비용 폭증**: 마이그레이션·백업·모니터링이 모두 tenant 수에 비례.
|
||||
- Connection pool이 (tenant 수 × pool size)로 폭발 → connection multiplexing(예: PgBouncer) 필수.
|
||||
- AWS 계정·서비스 limit에 부딪힐 수 있음.
|
||||
- 비용은 silo > bridge > pool 순.
|
||||
|
||||
### Hybrid (Azure Deployment Stamps / AWS Bridge)
|
||||
|
||||
- 두 가지 이상 모델을 동시 운영 → **운영 복잡도 최고**.
|
||||
- Tier 승급(pool → silo) 시 **데이터 이동 절차** 필요.
|
||||
- Routing layer + tenant catalog가 사실상 control plane이 되어, 가용성 single point가 되지 않도록 분산 필요.
|
||||
- 작은 팀에서 도입하면 ROI 부정. 일반적으로 product-market fit 이후 단계에서 검토.
|
||||
|
||||
### 공통 오해
|
||||
|
||||
- "Pool이면 무조건 싸다"는 거짓 — 노이즈/검증 비용이 일정 규모 이상에선 silo와 역전될 수 있음.
|
||||
- "Subdomain이면 자동 isolation" 거짓 — resolution과 isolation은 직교. subdomain은 routing일 뿐 storage 분리를 보장하지 않음.
|
||||
- "JWT claim만 있으면 안전" 거짓 — repository·query 레이어에서 tenant filter를 강제하지 않으면 claim의 의미가 없음.
|
||||
|
||||
## Project Application
|
||||
|
||||
- [[wiki/projects/ca-tmpl/multi-tenancy-isolation-patterns]] — ca-tmpl 의사결정 기록 (현재 `documented-only`, Phase C2 미진입). 실제 구현 여부는 project 문서 참조.
|
||||
ca-tmpl은 본 개념을 다음 위치에서 적용·문서화한다. concept 문서는 등급을 매기지 않으며, 검증 수준은 각 프로젝트/브랜치 노트에서 판정한다.
|
||||
|
||||
- [[raw/branch-notes/feature-tenant-context-policy]] — tenant resolution(JWT > header admin only > subdomain fallback) + isolation SSOT
|
||||
- [[raw/branch-notes/feature-repository-access-permission-contract]] — `CROSS_TENANT_ADMIN` capability, repository 레벨 tenant filter 강제 contract
|
||||
- [[raw/project-notes/ca-skeleton-operational-contract]] — §10 Repository Access Permission Contract, §29 Topic 6 Multi-tenancy Isolation
|
||||
|
||||
## Interview Questions
|
||||
|
||||
- AWS SaaS Lens의 Pool/Silo/Bridge는 무엇이 다르고, 어떤 상황에서 어떤 모델을 선택하나?
|
||||
- Tenant ID를 JWT claim과 HTTP header 중 어디서 읽어야 하며, 둘을 동시에 허용한다면 어떤 trust 기준을 두는가?
|
||||
- shared DB + tenant_id에서 schema-per-tenant 또는 db-per-tenant로 마이그레이션을 트리거하는 조건은 무엇인가?
|
||||
- Cross-tenant 침해를 막기 위해 어느 레이어(JWT 검증 / SecurityContext / repository / DB)에 어떤 방어가 필요한가?
|
||||
- Tenant 식별자에 ULID와 UUID 중 어느 쪽을 쓰는 게 적합하며, 각 선택의 trade-off는 무엇인가?
|
||||
|
||||
## Do Not Overclaim
|
||||
|
||||
- "shared DB + tenant_id가 항상 우월하다"고 말하지 말 것 — 규제 산업·data residency 요구가 있는 도메인에서는 Silo가 필수 또는 사실상 강제다.
|
||||
- Stripe/Citus의 schema-per-tenant 한계치(예: "정확히 N tenant에서 한계")는 **정확 인용 wording이 미완**이며 raw 자료는 `needs-confirmation` 상태다. 면접/이력서에서는 "수백~수천 단위에서 catalog overhead가 보고된다" 정도로 출처(Citus blog)와 함께만 언급할 것.
|
||||
- "Atlassian이 그렇게 하니까 best practice"라고 말하지 말 것 — company-tech-blog 사례는 관점·증거이지 공식 기준이 아니다.
|
||||
- "JWT claim만 검증하면 multi-tenant가 안전하다"는 단정 금지 — claim은 입구일 뿐 storage layer 강제가 별도로 필요하다.
|
||||
- ca-tmpl 적용 사실(예: ULID 채택 이유, capability 설계)은 본 concept 문서가 아니라 `wiki/projects/` 또는 branch-notes에서 검증 등급과 함께 진술할 것. "내가 했다"는 표현은 concept 레이어에 두지 않는다.
|
||||
|
||||
## Sources
|
||||
|
||||
- [AWS Whitepaper — SaaS Tenant Isolation Strategies](https://docs.aws.amazon.com/whitepapers/latest/saas-tenant-isolation-strategies/saas-tenant-isolation-strategies.html) — Silo/Pool/Bridge 분류 baseline
|
||||
- [Hibernate ORM User Guide — Multi-tenancy](https://docs.jboss.org/hibernate/orm/current/userguide/html_single/Hibernate_User_Guide.html#multitenacy) — DATABASE/SCHEMA/DISCRIMINATOR 공식 strategy
|
||||
- [Azure Architecture Center — Multitenant SaaS](https://learn.microsoft.com/en-us/azure/architecture/guide/multitenant/overview) — Deployment Stamps / hybrid spectrum
|
||||
- [Citus — Designing your SaaS DB for High Scalability](https://www.citusdata.com/blog/2016/10/03/designing-your-saas-database-for-high-scalability/) — schema vs shared schema 한계치 (company-tech-blog, needs-confirmation)
|
||||
- [Auth0 — Multi-tenant applications](https://auth0.com/docs/get-started/auth0-overview/create-tenants/multiple-tenants) — tenant resolution(subdomain/JWT/header) 비교
|
||||
- [Vercel — Multi-tenant Next.js Guide](https://vercel.com/guides/nextjs-multi-tenant-application) — subdomain routing 실무
|
||||
- [AWS APN Blog — Hybrid Tenant Isolation](https://aws.amazon.com/blogs/apn/) — tier-based hybrid 사례
|
||||
- [Atlassian Engineering — Cloud Architecture Guidelines](https://www.atlassian.com/engineering/cloud-architecture-and-guidelines) — shard 단위 isolation + tenant context propagation 사례
|
||||
- [[raw/official-docs/multitenancy-aws-saas-tenant-isolation-whitepaper]]
|
||||
- [[raw/official-docs/multitenancy-hibernate-user-guide]]
|
||||
- [[raw/official-docs/multitenancy-azure-architecture-patterns]]
|
||||
- [[raw/company-tech-blogs/multitenancy-stripe-citus-schema-per-tenant]]
|
||||
- [[raw/company-tech-blogs/multitenancy-auth0-tenant-resolution]]
|
||||
- [[raw/company-tech-blogs/multitenancy-subdomain-resolution-patterns]]
|
||||
- [[raw/company-tech-blogs/multitenancy-hybrid-pooled-siloed-mix]]
|
||||
- [[raw/company-tech-blogs/multitenancy-atlassian-tenant-context]]
|
||||
- [[raw/project-notes/ca-skeleton-operational-contract]] — §10, §29 Topic 6
|
||||
@@ -1 +0,0 @@
|
||||
../../vault/30-knowledge/concepts/observability-log-metric-trace-runbook.md
|
||||
@@ -0,0 +1,155 @@
|
||||
---
|
||||
title: Observability Baseline (Log + Metric + Trace + Runbook)
|
||||
source_type: llm-generated
|
||||
status: draft
|
||||
confidence: medium
|
||||
tags: [observability, logging, metrics, tracing, runbook, sre]
|
||||
related_projects: [ca-skeleton]
|
||||
last_reviewed: 2026-05-22
|
||||
---
|
||||
|
||||
# Observability Baseline (Log + Metric + Trace + Runbook)
|
||||
|
||||
> Layer: `wiki/concepts/` — 일반 개념. 내 프로젝트 사실은 project 문서에서 다룬다.
|
||||
|
||||
## Summary
|
||||
|
||||
Observability는 세 가지 신호(structured log, metric, distributed trace)와 이를 운영 행위로 잇는 runbook이 결합될 때 성립한다. ca-tmpl은 **JSON Logback + Micrometer dot.case 이름 규칙 + W3C tracecontext 전파 + `runbook://` URI 스킴**을 기본선으로 잡아 네 축을 하나의 운영 계약으로 묶는다. 어느 한 축만 갖추면 인시던트 시 "왜·어디서·어떻게 대응할지"를 답할 수 없다.
|
||||
|
||||
## Standard (공식 정의)
|
||||
|
||||
### Log
|
||||
|
||||
- **ECS (Elastic Common Schema)**: `@timestamp`, `log.level`, `service.name`, `trace.id`, `event.dataset` 등 필드명을 표준화. Elastic이 정의한 공개 스키마지만 OTel·Loki·Datadog도 부분 호환.
|
||||
- **OpenTelemetry Log Data Model**: log record를 trace/metric과 동일 SDK로 다루는 신호. `SeverityNumber`, `Body`, `Attributes`, `TraceId`/`SpanId` correlation을 정의.
|
||||
- **Structured logging best practice**: 자유 텍스트가 아닌 key-value JSON. PII는 발신 측에서 마스킹 (Logback `ch.qos.logback.classic.pattern` 또는 `MaskingPatternLayout`).
|
||||
|
||||
### Metric
|
||||
|
||||
- **Micrometer**: JVM 표준 facade. 이름은 `dot.case` (`http.server.requests`), `meterRegistry`가 backend별 변환을 담당.
|
||||
- **Prometheus**: pull-based, label cardinality bound 권장. exporter가 dot을 `_`로 변환 (`http_server_requests_seconds_count`).
|
||||
- **OpenTelemetry Metrics Data Model**: counter / gauge / histogram / exponential histogram을 정의. instrument 종류와 aggregation을 분리.
|
||||
- **RED method (Tom Wilkie)**: Request rate / Error rate / Duration. request-driven 서비스 표준.
|
||||
- **USE method (Brendan Gregg)**: Utilization / Saturation / Errors. 리소스 관점.
|
||||
- **SLO burn-rate alert (Google SRE Workbook)**: error budget 소진 속도를 multi-window multi-burn-rate로 측정 (예: 1h 14.4× burn AND 5m 14.4× burn).
|
||||
|
||||
### Trace
|
||||
|
||||
- **W3C Trace Context (W3C TR)**: `traceparent` 헤더 — `version-trace-id-parent-id-trace-flags`. 128-bit trace-id, 64-bit span-id, vendor-neutral.
|
||||
- **Micrometer Tracing**: Spring 진영의 facade. Brave(Zipkin) 또는 OpenTelemetry bridge로 backend 교체 가능.
|
||||
- **B3 propagation (Zipkin legacy)**: `X-B3-TraceId`(64 or 128-bit), `X-B3-SpanId`, `X-B3-Sampled`. 일부 레거시 서비스 호환용.
|
||||
- **Sampling**: head-based (요청 시점 결정, 저비용) vs tail-based (span 완료 후 결정, 고비용·고정밀). OTel Collector가 tail processor 제공.
|
||||
|
||||
### Runbook
|
||||
|
||||
- **Google SRE Workbook**: incident response·postmortem·error budget을 한 묶음으로 본다. runbook은 "on-call이 새벽 3시에 따라할 수 있어야" 한다.
|
||||
- **PagerDuty Incident Response**: severity(SEV-1~5), incident commander, scribe, communication template을 표준화.
|
||||
- **PagerDuty Runbook Automation (구 Rundeck)**: runbook을 코드/스크립트로 실행. drift 감소.
|
||||
- **ITIL**: 광의의 service operation 프로세스 (incident / problem / change). runbook은 ITIL의 procedure에 해당.
|
||||
- **Runbook-as-code (GitOps)**: markdown runbook을 git에 두고 alert payload에 URL을 박는다. `runbook://` 같은 내부 스킴은 ca-tmpl 관례.
|
||||
|
||||
## 한계 / 주의점
|
||||
|
||||
### Log
|
||||
|
||||
| 항목 | 한계 |
|
||||
|------|------|
|
||||
| ECS schema | Elastic이 사실상 owner — Loki/Datadog 채택은 부분적, **vendor lock-in 위험**. |
|
||||
| OTel log signal | 2024년 기준 GA 진입했지만 ecosystem maturity는 metric/trace 대비 낮음. SDK·Collector 버전 호환에 주의. |
|
||||
| SaaS 백엔드 (Loki/Datadog/Splunk) | 필드 매핑·인덱싱 정책이 제품마다 달라 schema drift 발생. 마이그레이션 비용 큼. |
|
||||
| Masking | Logback `MaskingPatternLayout`은 정규식 기반 — false negative (놓침)·false positive (과다 마스킹) 모두 가능. 정책은 발신지에서. |
|
||||
|
||||
### Metric
|
||||
|
||||
| 항목 | 한계 |
|
||||
|------|------|
|
||||
| Naming drift | Micrometer dot.case → Prometheus exporter underscore 변환은 자동이지만, 대시보드·alert rule은 backend 표기를 직접 참조 → 코드와 alert 사이 표기 분리. |
|
||||
| Cardinality | `userId`·`requestId`처럼 unbounded label을 metric에 박으면 시계열 폭증. trace/log로 보내야 함. |
|
||||
| SLO burn-rate | 식이 직관적이지 않음. SLO 자체가 없는 단계에선 traffic-based threshold가 더 합리적. |
|
||||
| Histogram | exponential histogram은 OTel·Prometheus 양쪽에서 채택 중이나 client/server 호환 매트릭스 확인 필요. |
|
||||
|
||||
### Trace
|
||||
|
||||
| 항목 | 한계 |
|
||||
|------|------|
|
||||
| Sampling | head-based 1% sampling은 rare-error 누락 위험. tail-based는 Collector 메모리·CPU 비용 큼. |
|
||||
| Adaptive sampling | "에러는 100%, 정상은 N%" 같은 정책 — 검증·재현이 어렵고 비교 분석을 깨뜨릴 수 있음. |
|
||||
| B3 non-호환 | B3 64-bit trace-id는 W3C 128-bit와 1:1 호환 안 됨. 게이트웨이에서 변환 정책 필요. |
|
||||
| Backend lock-in | Datadog APM·New Relic의 auto-instrumentation은 강력하지만 OTel exporter로 동등하게 옮기기 어려움. |
|
||||
| 비용 | full-trace 보관은 비싸다. 보존 기간·sampling rate가 곧 비용. |
|
||||
|
||||
### Runbook
|
||||
|
||||
| 항목 | 한계 |
|
||||
|------|------|
|
||||
| Drift | Confluence·Notion runbook은 코드와 따로 움직여 stale 되기 쉽다. |
|
||||
| Automation lock-in | PagerDuty Runbook Automation·Rundeck 같은 도구는 ops 표면을 그 제품에 묶는다. |
|
||||
| `runbook://` scheme | git markdown 링크는 repo 이동·이름 변경 시 link rot. CI에서 link check 필요. |
|
||||
| 적용 한계 | runbook은 "이미 알려진 장애"에 강하다. novel incident에는 framework(SEV·comm·IC)만 도움이 되고 절차 자체는 비워둬야 한다. |
|
||||
|
||||
## Project Application
|
||||
|
||||
- [[wiki/projects/ca-tmpl/observability-log-metric-trace-runbook]] — ca-tmpl 의사결정 기록 (`verified` — foundation observability 토대 slice는 MDC snake_case 표준 + 응답-로그 상관 + 헤더 sanitization으로 코드 구현·로컬 검증됨; 4축 full 기능은 여전히 `documented-only`). 실제 구현 범위·검증 수준은 project 문서 참조.
|
||||
- [[raw/project-notes/ca-skeleton-operational-contract]] — ca-tmpl 운영 계약 SSOT (§8 Structured Log, §6 Operational Error, §29 G-A).
|
||||
- [[raw/branch-notes/feature-log-management-contract]] — JSON Logback + masking + trace 상관관계 계약.
|
||||
- [[raw/branch-notes/feature-metrics-alerting-contract]] — Micrometer dot.case + SLO burn-rate alert 계약.
|
||||
- [[raw/branch-notes/feature-distributed-tracing-contract]] — W3C tracecontext 전파 + sampling 계약.
|
||||
- [[raw/branch-notes/feature-operational-runbook-contract]] — `runbook://` scheme · alert payload 연동 계약.
|
||||
- [[raw/branch-notes/feature-operational-error-observability-foundation]] — error code · severity · 3 pillars 연계 토대.
|
||||
|
||||
## Claim-backed Knowledge
|
||||
|
||||
> 이 개념 문서의 핵심 설명은 raw source claim 으로 뒷받침되어야 한다.
|
||||
> 공식 문서 claim, 회사 사례 claim, 내 프로젝트 decision 을 분리한다.
|
||||
|
||||
| Knowledge Point | Supporting Claims | Confidence | Notes |
|
||||
|---|---|---|---|
|
||||
| ECS는 `@timestamp`/`log.level`/`service.name`/`trace.id` 등 로그 필드명을 표준화한 공개 스키마다 | [[raw/official-docs/log-ecs-schema-elastic-official]] | `high` | 공식(Elastic) — 사실상 Elastic이 owner라 Loki/Datadog 채택은 부분적, vendor lock-in 위험 |
|
||||
| OpenTelemetry는 log를 trace/metric과 동일 SDK 신호로 다루며 `TraceId`/`SpanId` correlation을 정의한다 | [[raw/official-docs/log-otel-log-data-model-spec]], [[raw/official-docs/metric-otel-metrics-data-model-spec]] | `high` | 공식 spec — log signal은 metric/trace 대비 ecosystem maturity 낮음 |
|
||||
| Micrometer는 `dot.case` 이름 규칙을 쓰고 Prometheus exporter가 `_`로 변환한다 (`http.server.requests` → `http_server_requests_seconds_count`) | [[raw/official-docs/metric-micrometer-naming-convention-official]] | `high` | 공식 — 대시보드·alert rule은 backend 표기를 직접 참조해 코드/alert 표기 분리 발생 |
|
||||
| W3C Trace Context `traceparent`는 128-bit trace-id·64-bit span-id의 vendor-neutral 표준이며 B3(64-bit)와 1:1 lossless 변환이 안 된다 | [[raw/official-docs/tracing-w3c-trace-context-spec]], [[raw/official-docs/tracing-b3-propagation-zipkin-spec]] | `high` | 공식 — hybrid 환경에서 게이트웨이 변환 정책 필요 |
|
||||
| trace sampling은 head-based(저비용, rare-error 누락 위험) vs tail-based(고정밀, Collector 메모리/CPU 비용)의 trade-off다 | [[raw/official-docs/tracing-otel-sampling-tail-vs-head-spec]] | `high` | 공식 — full-trace 보관 비용이 곧 보존기간·sampling rate |
|
||||
| SLO burn-rate alert는 error budget 소진 속도를 multi-window multi-burn-rate로 측정한다 | [[raw/official-docs/metric-google-sre-slo-burn-rate]] | `high` | 공식(Google SRE Workbook) — SLO 미합의 단계에선 traffic-based threshold가 더 운영 가능 |
|
||||
| PagerDuty는 severity·incident commander·comm template로 incident response를 표준화하며 runbook은 "on-call이 새벽 3시에 따라할 수 있어야" 한다 | [[raw/official-docs/runbook-pagerduty-incident-response-doc]] | `high` | 공식 — runbook은 알려진 장애에 강하고 novel incident엔 framework만 유효 |
|
||||
|
||||
## 내가 설명할 수 있어야 하는 것
|
||||
|
||||
- Observability 3 pillars(log/metric/trace)의 공식 정의와 각 신호가 서로 대체 불가능한 이유는?
|
||||
- 각 축의 공개 표준(ECS / OTel data model / Micrometer / W3C Trace Context / SLO burn-rate)은 무엇을 규정하는가?
|
||||
- 어떤 상황에서는 특정 선택을 쓰면 안 되는가(SLO 미합의 시 burn-rate alert, unbounded label을 metric에 박기 등)?
|
||||
- 공식 표준이 말하지 않는 부분(backend lock-in, schema drift, masking false negative/positive)은 무엇인가?
|
||||
- Datadog APM vs OTel 같은 tech-blog 비교를 공식 best practice처럼 일반화하면 안 되는 지점은?
|
||||
- 내 프로젝트에서는 어떤 branch decision(MDC snake_case 표준, W3C traceparent 채택, `runbook://` scheme 등)으로 연결됐는가?
|
||||
- 이 개념을 코드/운영에서 검증하려면 무엇을 확인해야 하는가(MDC 키 일관성, 응답-로그 상관, 헤더 sanitization, alert 발화 등)?
|
||||
|
||||
## Interview Questions
|
||||
|
||||
- Observability **3 pillars**(log/metric/trace)를 정의하고, 각각이 다른 신호로 대체될 수 없는 이유는?
|
||||
- **SLO burn-rate alert**의 원리와 단순 threshold alert 대비 장점은?
|
||||
- **W3C tracecontext와 B3 propagation**의 차이, 그리고 hybrid 환경에서 변환 전략은?
|
||||
- **trace sampling rate 1%**를 선택할 때의 근거와 rare-error 누락 위험을 어떻게 보완하는가?
|
||||
- **log masking**은 어디서(발신/수신) 수행해야 하며, false negative를 어떻게 줄이는가?
|
||||
- **runbook drift**(코드와 문서 불일치)를 방지하는 운영적 장치는?
|
||||
|
||||
## Do Not Overclaim
|
||||
|
||||
- "OpenTelemetry만 쓰면 vendor-neutral이다"라고 단정하지 말 것. instrument 표준은 중립이지만 **backend (Datadog/New Relic/Tempo/Jaeger)** 선택 시점에 다시 lock-in이 발생한다.
|
||||
- "SLO burn-rate alert가 정답이다"라고 단정하지 말 것. SLO·error budget이 합의되지 않은 단계에선 traffic-based threshold (RPS·5xx rate)가 더 운영 가능하다.
|
||||
- "structured logging만 하면 PII는 안전하다"고 단정하지 말 것. 필드 단위 마스킹 정책과 sink(Elastic/Loki/Datadog)별 접근 통제가 함께 있어야 한다.
|
||||
- "B3과 W3C는 호환된다"고 단정하지 말 것. 64-bit B3 trace-id는 128-bit W3C로 lossless 변환되지 않는다.
|
||||
- "runbook이 있으면 incident가 빨라진다"고 단정하지 말 것. drift된 runbook은 오히려 잘못된 행동을 유도한다.
|
||||
|
||||
## Sources
|
||||
|
||||
- [[raw/official-docs/log-ecs-schema-elastic-official]] — ECS schema 공식 정의.
|
||||
- [[raw/official-docs/log-otel-log-data-model-spec]] — OpenTelemetry log data model spec.
|
||||
- [[raw/official-docs/log-logback-mask-pattern-converter-official]] — Logback masking pattern 공식.
|
||||
- [[raw/official-docs/metric-micrometer-naming-convention-official]] — Micrometer dot.case 이름 규칙.
|
||||
- [[raw/official-docs/metric-otel-metrics-data-model-spec]] — OTel metrics data model spec.
|
||||
- [[raw/official-docs/metric-google-sre-slo-burn-rate]] — Google SRE Workbook burn-rate alert.
|
||||
- [[raw/official-docs/tracing-w3c-trace-context-spec]] — W3C Trace Context spec.
|
||||
- [[raw/official-docs/tracing-b3-propagation-zipkin-spec]] — Zipkin B3 propagation spec.
|
||||
- [[raw/official-docs/tracing-otel-sampling-tail-vs-head-spec]] — OTel sampling head/tail 비교.
|
||||
- [[raw/official-docs/runbook-pagerduty-incident-response-doc]] — PagerDuty incident response 공식 문서.
|
||||
- [[raw/company-tech-blogs/tracing-datadog-apm-vs-opentelemetry]] — Datadog APM vs OTel 비교 (tech blog 관점).
|
||||
- [[raw/project-notes/ca-skeleton-operational-contract]] — ca-tmpl 운영 계약 canonical SSOT.
|
||||
@@ -1 +0,0 @@
|
||||
../../vault/30-knowledge/concepts/outbox-pattern.md
|
||||
@@ -0,0 +1,65 @@
|
||||
---
|
||||
title: concept / Transactional Outbox Pattern
|
||||
source_type: llm-generated
|
||||
status: reviewed
|
||||
confidence: high
|
||||
tags: [concept, ca-tmpl, messaging, kafka, outbox-pattern]
|
||||
related_projects: [ca-tmpl]
|
||||
last_reviewed: 2026-06-15
|
||||
---
|
||||
|
||||
# concept / Transactional Outbox Pattern
|
||||
|
||||
## Summary
|
||||
|
||||
로컬 트랜잭션의 일부로 비즈니스 상태 변경과 이벤트를 동일한 데이터베이스(Outbox 테이블)에 저장한 후, 독립적인 프로세스(Outbox Relay)가 이 이벤트를 비동기적으로 메시지 브로커(Kafka 등)로 발행하는 디자인 패턴.
|
||||
- 이를 통해 분산 환경에서 비즈니스 로직 성공과 메시지 발행 간의 원자성(Atomicity)을 보장하고, 이중 쓰기(Dual-Write) 안티패턴을 방지한다.
|
||||
|
||||
## Standard (공식 정의)
|
||||
|
||||
- **Dual-Write Anti-Pattern**: 하나의 비즈니스 유스케이스 내에서 데이터베이스 업데이트와 외부 메시지 발행을 동시에 시도하는 방식. 데이터베이스 트랜잭션은 커밋되었으나 브로커 연결 실패로 메시지가 유실되거나, 반대로 메시지는 발행되었으나 데이터베이스 커밋이 롤백되는 불일치 문제가 상존한다.
|
||||
- **Transactional Outbox**:
|
||||
1. 비즈니스 원장 데이터 수정과 함께, 발행할 메시지를 동일 트랜잭션 하에서 `Outbox` 테이블에 인서트한다. (DB 로컬 트랜잭션의 원자성으로 인해 메시지 저장도 100% 보장된다.)
|
||||
2. 별도의 백그라운드 워커(Outbox Relay)가 Outbox 테이블을 주기적으로 폴링(또는 CDC를 활용)하여 `PENDING` 상태의 이벤트를 읽어온다.
|
||||
3. 릴레이 워커가 메시지를 브로커로 발행(Publish)한 뒤, 데이터베이스에 해당 Outbox 레코드를 `COMPLETED` 등으로 상태를 업데이트하거나 삭제한다.
|
||||
|
||||
## 한계 / 주의점
|
||||
|
||||
- **중복 메시지 발행 (At-Least-Once Delivery)**: 릴레이가 브로커에 메시지를 정상적으로 보냈으나, DB에 상태를 `COMPLETED`로 업데이트하기 직전에 시스템이 다운되면 동일한 메시지가 재전송될 수 있다. 따라서 소비처(Consumer)는 반드시 **멱등적 메시지 처리(Idempotent Consumer)** 구조를 갖춰야 한다.
|
||||
- **순서 보장 (Ordering)**: 멀티 스레드로 릴레이를 돌릴 때 동일 Aggregate의 이벤트가 뒤집혀서 발행되지 않도록 Aggregate ID 기반의 분산 락이나 시퀀스 제어가 필요할 수 있다.
|
||||
|
||||
## Project Application
|
||||
|
||||
- [[wiki/explainer/adapter-outbound.md]]
|
||||
- 우리 프로젝트에서는 메시지 발행 시 직접 발행과 아웃복스 릴레이 발행의 결합을 지원함.
|
||||
- **직접 발행 (`KafkaMessagePublisher`)**: 비즈니스 트랜잭션 흐름 중 메시지를 즉시 발행함. 이미 로컬 DB 트랜잭션에 아웃복스가 커밋되므로, 실시간 발행은 **Fail-Open** 계약을 맺어 예외가 발생하더라도 사용자 API를 중단시키지 않고 백그라운드 릴레이에 유실 복구를 위임함.
|
||||
- **릴레이 발행 (`KafkaOutboxMessagePublishAdapter`)**: 백그라운드에서 Outbox 레코드를 전달받아 브로커에 실제 전달하는 역할. 브로커가 장애를 내면 반드시 예외를 다시 던지는 **Fail-Closed** 계약을 가짐. 예외가 전파되어야 릴레이 트랜잭션이 롤백되어 해당 레코드가 `IN_FLIGHT`에 고립되지 않고 재시도(Retry) 루프를 타거나 운영 경보(Runbook)가 정상 작동하기 때문임.
|
||||
|
||||
## Claim-backed Knowledge
|
||||
|
||||
| Knowledge Point | Supporting Claims | Confidence | Notes |
|
||||
|---|---|---|---|
|
||||
| 이중 쓰기(Dual-write)의 근본적 문제점과 일관성 결여 | `raw/official-docs/dual-write-antipattern-microservices-io.md` | `high` | 마이크로서비스 데이터 패턴 |
|
||||
| 트랜잭셔널 아웃복스 패턴의 기본 구성 요소 | `raw/official-docs/transactional-outbox-aws-prescriptive-guidance.md` | `high` | AWS 마이크로서비스 설계 패턴 |
|
||||
| Outbox 데이터 상태 변경 및 중복 처리 주의점 | `raw/official-docs/microservices-io-transactional-outbox.md` | `high` | Microservices.io 패턴 정의 |
|
||||
|
||||
## 내가 설명할 수 있어야 하는 것
|
||||
|
||||
- 이중 쓰기(Dual-Write)의 위험성과 이를 아웃복스 패턴이 어떻게 해결하는지 메커니즘을 상세히 설명할 수 있어야 함.
|
||||
- 실시간 API 단의 메시지 발행기와 백그라운드 릴레이 단의 메시지 발행기가 예외 처리 정책(Fail-Open vs Fail-Closed)을 다르게 맺는 이유는 무엇인가?
|
||||
- 카프카 외에 다른 메시징 시스템(RabbitMQ, AWS SQS)으로 아웃복스 발행기를 대체하려면 어떻게 설계해야 하는가? (Port-Adapter 인터페이스 구현을 통해 어댑터만 교체)
|
||||
|
||||
## Interview Questions
|
||||
|
||||
- 메시지 큐와 RDB를 동시에 업데이트할 때 발생할 수 있는 데이터 정합성 문제와 이를 해결하기 위한 Transactional Outbox Pattern에 대해 설명해 주세요.
|
||||
- 아웃복스 릴레이 컴포넌트의 실패 상황 시 가용성과 정합성 설계 관점에서 어떻게 실패 복구를 처리해야 하는지 설명하십시오.
|
||||
|
||||
## Do Not Overclaim
|
||||
|
||||
- "아웃복스 패턴을 도입했으므로 분산 트레이싱 환경에서 완벽한 1회성 전송(Exactly-Once)을 달성할 수 있다"고 장담하면 안 된다. 분산 네트워크 상에서 릴레이 DB 업데이트 실패 시 중복 메시지가 무조건 나갈 수 있으므로, 최종 소비자의 멱등 수신 설계가 반드시 동반되어야 보장된다.
|
||||
|
||||
## Sources
|
||||
|
||||
- [Microservices.io - Transactional Outbox](https://microservices.io/patterns/data/transactional-outbox.html)
|
||||
- [[raw/official-docs/dual-write-antipattern-microservices-io.md]]
|
||||
- [[raw/official-docs/transactional-outbox-aws-prescriptive-guidance.md]]
|
||||
@@ -1 +0,0 @@
|
||||
../../vault/30-knowledge/concepts/privacy-file-domain-modeling.md
|
||||
@@ -0,0 +1,116 @@
|
||||
---
|
||||
title: Privacy / File / Domain Modeling (GDPR + ICAP + Vernon)
|
||||
source_type: llm-generated
|
||||
status: draft
|
||||
confidence: medium
|
||||
tags: [privacy, gdpr, file-upload, ddd, domain-modeling]
|
||||
related_projects: [ca-skeleton]
|
||||
last_reviewed: 2026-05-22
|
||||
---
|
||||
|
||||
# Privacy / File / Domain Modeling (GDPR + ICAP + Vernon)
|
||||
|
||||
> Layer: `wiki/concepts/` — 일반 개념. Phase E Group G-J(3 branch / 10 raw) 통합. 내 프로젝트 사실 판정은 [[raw/project-notes/ca-skeleton-operational-contract]] §19, §29 G-J 와 각 branch-note에서 별도로 다룸.
|
||||
|
||||
## Summary
|
||||
|
||||
서비스가 도메인을 얹기 전에도 (1) **개인정보·로그의 보존/삭제 계약**, (2) **파일 업로드/다운로드의 안전성 계약**, (3) **도메인 모델의 프레임워크 격리 계약** 세 축이 사전에 정의되어야 한다. 본 문서는 이 세 축의 공식 기준과 그 한계를 묶어서 다룬다. 대표 결정값(예: 30/180/365일 retention, HMAC-SHA-256 + 90일 salt rotation, DSR SLA 30/14일, 3-layer file size limit, content-type allowlist 6종, VO private constructor, aggregate root mutator non-public)은 모두 개별 branch-note의 결정 사항을 따른다.
|
||||
|
||||
## Standard (공식 정의)
|
||||
|
||||
### Privacy / Retention
|
||||
|
||||
- **GDPR Art.25 — Data protection by design and by default**: 처리 시작 시점부터 "최소한의 데이터, 가능한 짧은 보존, 가능한 적은 노출"이 기본값이어야 한다. Art.17(Right to erasure)은 controller가 합리적 조치로 backup·복제본을 포함해 삭제하도록 요구한다.
|
||||
- **NIST SP 800-88 Rev.1 — Cryptographic Erase (CE)**: 키를 안전하게 폐기함으로써 데이터 자체를 sanitize한 것으로 인정하는 공식 방법. backup·offline media의 GDPR Art.17 대응 수단으로 사용 가능.
|
||||
- **ENISA / IAPP — Pseudonymization techniques**: HMAC-with-secret-key, tokenization, encryption 등을 pseudonymization 기법으로 분류. salt rotation, lookup table 분리 보관, brute-force input space 등을 비교 기준으로 제시.
|
||||
- **DSR (Data Subject Request) 운영 패턴**: intake → identity verification → scope classification(export/delete) → execution → audit evidence. GDPR Art.12는 응답을 "원칙적으로 1개월(연장 시 +2개월)" 내로 요구.
|
||||
|
||||
### File / Resource Handling
|
||||
|
||||
- **ICAP / RFC 3507 — Internet Content Adaptation Protocol**: HTTP proxy/gateway가 antivirus engine(예: ClamAV)에 payload를 위임 검사하는 표준 프로토콜. 업로드 단의 외부 콘텐츠 검사를 app 외부에서 수행하는 정석.
|
||||
- **AWS S3 — Presigned URL upload**: 서버가 서명된 PUT URL을 발급하면 클라이언트가 직접 S3에 업로드. app/gateway의 대역폭/CPU 부담 없이 large object 처리 가능.
|
||||
- **tus.io — Resumable upload protocol (v1.0.0)**: HTTP `PATCH` 기반 resumable upload. 대용량/장시간 업로드를 chunk 단위 재개 가능하도록 표준화.
|
||||
- **multipart/form-data + size limit**: Spring `spring.servlet.multipart.max-file-size` 등 framework 단의 1차 enforcement는 envelope error 변환의 책임을 진다. gateway/WAF는 raw 차단 보조.
|
||||
|
||||
### Domain Modeling
|
||||
|
||||
- **Vaughn Vernon — Effective Aggregate Design (IDDD)**: 4 rules — (1) protect true invariants in consistency boundary, (2) design small aggregates, (3) reference other aggregates by identity, (4) update other aggregates eventually. ORM-friendly constructor / package-private setter를 통해 ORM과 도메인 모델의 분리를 권장(이하 "Option A: ORM 외부 매핑").
|
||||
- **Martin Fowler — Anemic Domain Model**: 데이터만 있는 entity + 모든 로직이 service에 모이는 구조를 anti-pattern으로 정의. rich model(state + behavior + invariant 동소화)을 기본으로 제시.
|
||||
- **Greg Young — CQRS / Event Sourcing**: domain event는 transport-free fact, command와 query 모델 분리, event stream을 source of truth로 두는 패턴. event sourcing과 CQRS는 동일 개념이 아님(Young 본인이 구분).
|
||||
|
||||
## 한계 / 주의점
|
||||
|
||||
### Privacy
|
||||
|
||||
- **HMAC + salt rotation을 anonymization으로 단정 금지**: ENISA·IAPP 기준으로도 HMAC은 pseudonymization이지 anonymization이 아니다. brute-force 가능한 input space(예: 한국 휴대폰 11자리, 주민번호 일부 자리)에서는 attacker가 가능한 모든 입력을 미리 HMAC 계산할 수 있으므로 tokenization(랜덤 토큰 + 별도 lookup table)이 우위인 구간이 존재한다. 또한 HMAC + salt rotation은 **forward security만** 제공한다 — 새로 기록되는 식별자에 한해 rotation 이전 hash가 무효화될 뿐, 이미 작성된 backup 안의 hash는 그대로 잔존한다. 따라서 HMAC을 backup erasure 수단으로 오해하면 안 된다.
|
||||
- **salt rotation interval (예: 90일)** 자체로 안전성이 증명되지 않음. 회전 주기 동안의 collision/lookup 정책, 옛 salt 보관 기간(예: 90일 retain), 키 저장소의 안전성이 별도로 요구된다.
|
||||
- **GDPR Art.17 + backup → envelope key 필요**: backup·snapshot에서의 erasure는 단건 삭제가 어렵다. NIST SP 800-88 Rev.1 § 2.5 Cryptographic Erase (CE)는 인정되는 방법이나, **per-principal envelope key** 구조(주체별 DEK를 master CMK로 wrap, 삭제 요청 시 해당 principal의 DEK 폐기 → 모든 backup ciphertext가 동시에 unreadable)가 사전에 설계되어 있어야 한다. HMAC + salt rotation은 이 단건 erasure를 제공하지 **못한다**. 비용 trade-off에 따라 (a) per-principal CMK / (b) per-principal DEK + master CMK envelope (AWS KMS·GCP KMS 권장) / (c) tenant-level CMK (Stripe·Twilio·Shopify 류 SaaS 일반 패턴) 중 선택이 필요하다. 일반적 대량 KEK 폐기로는 Art.17 단건 요청을 만족하기 어렵다.
|
||||
- **PII detection SaaS(AWS Macie / OneTrust / TrustArc)** 채택은 vendor 종속을 만든다. skeleton 단계의 기본값으로 두는 것은 부적절.
|
||||
|
||||
### File / Resource
|
||||
|
||||
- **ICAP gateway가 모든 위협을 막는다고 단정 금지**: HTTPS end-to-end TLS 환경에서는 gateway가 payload를 평문으로 보지 못해 ICAP 검사가 어려운 구간이 있다. 그 경우 post-upload async scan(예: quarantine bucket + worker)이 대안.
|
||||
- **Direct S3 presigned URL**: 앱이 payload를 보지 못하므로 in-app validation(예: content-type 재검증, watermark, business rule)이 부재한다. content-type/size 검증은 S3 측 정책 + 후행 worker로 분산되어야 한다.
|
||||
- **tus resumable upload**: session 식별자와 orphan temp file이 충돌한다. ca-tmpl 류의 "temp file > 1h not closed = orphan, sweeper가 삭제" 정책은 tus의 정상 long session을 잘못 삭제할 수 있어 threshold 분리가 필요하다.
|
||||
- **in-app ClamAV daemon**: 앱 인스턴스마다 daemon dependency가 늘고, scaling/CPU 비용이 함께 증가한다. skeleton 단계의 기본값으로는 부적절.
|
||||
- **content-type "sniffing 금지" vs "allowlist"**: client-supplied Content-Type 신뢰는 위험하나, 동시에 서버측 sniffing(magic byte 추론)도 우회 가능. allowlist + endpoint별 검증이 현실적 절충.
|
||||
- **size limit 3-layer (예: app 10MB / global 12MB / gateway 20MB)**: 의도된 defense-in-depth지만, gateway 단의 raw 413은 envelope을 우회한다는 점이 trade-off다. 어느 layer에서 어떤 응답 형태를 보장할지 사전에 정해야 한다.
|
||||
|
||||
### Domain Modeling
|
||||
|
||||
- **Functional domain modeling (Scala / F#)**: 패러다임은 매력적이나 JVM Java 중심 팀의 학습 비용이 크다. skeleton 기본 채택은 부적절.
|
||||
- **Anemic model**: 로직이 service로 흩어져 invariant 위치가 불명확해진다. Fowler가 anti-pattern으로 명시.
|
||||
- **Pure DDD aggregates**: 작은 도메인에 과한 학습 비용 / 코드량을 강제할 수 있다. Vernon 본인도 "small aggregate"를 강조.
|
||||
- **Event sourcing**: event store, snapshot, projection 등 운영 비용이 크다. 도메인 event = transport-free fact라는 정의만 차용하고 event sourcing은 채택하지 않는 절충이 일반적.
|
||||
- **JPA direct annotation in domain (Vernon Option B / 우아한형제들 초기 글 스타일)**: `@Entity` / `@Column` 등을 domain class에 직접 두는 방식. 도메인이 persistence를 "안다"는 점에서 framework 격리 규칙과 충돌. forbidden import 규칙을 둔 코드베이스에서는 채택 불가.
|
||||
- **`@Entity` / `@Service` / Logger / HTTP type을 도메인이 import**: 도메인의 framework neutrality가 깨진다. ArchUnit 등의 forbidden-import 테스트로 강제할 수 있다.
|
||||
|
||||
## Project Application
|
||||
|
||||
- [[wiki/projects/ca-tmpl/privacy-file-domain-modeling]] — ca-tmpl 의사결정 기록 (현재 `documented-only`, Phase C2 미진입). 실제 구현 여부는 project 문서 참조.
|
||||
- [[raw/branch-notes/feature-data-retention-privacy-contract]] — log retention by profile, HMAC pseudonymization, DSR SLA, backup retention 결정
|
||||
- [[raw/branch-notes/feature-file-resource-handling-contract]] — upload size 3-layer, content-type allowlist, temp file cleanup, antivirus position 결정
|
||||
- [[raw/branch-notes/feature-domain-modeling-guardrails]] — VO private constructor, aggregate mutator non-public, domain forbidden import 결정
|
||||
- [[raw/project-notes/ca-skeleton-operational-contract]] §19 Domain Application Readiness Contract, §29 G-J 외부 근거 / 대안 조사
|
||||
|
||||
## Interview Questions
|
||||
|
||||
- GDPR Art.17 erasure 요청이 들어왔을 때, backup·snapshot까지 어떻게 처리하는가? Cryptographic erase와 per-principal envelope key 구조가 왜 필요한가?
|
||||
- HMAC + salt rotation을 pseudonymization으로 채택할 때 salt rotation 주기(예: 90일)는 어떤 의미를 갖는가? brute-force 가능한 input space에서는 왜 tokenization이 더 안전할 수 있는가?
|
||||
- 파일 업로드 size limit을 app(예: 10MB) / global(예: 12MB) / gateway(예: 20MB) 3-layer로 두는 이유는? 각 layer가 어떤 실패 모드를 책임지는가?
|
||||
- ICAP / RFC 3507 기반 gateway antivirus의 한계는? HTTPS end-to-end TLS 환경과 in-app ClamAV daemon은 각각 어떤 trade-off를 만드는가?
|
||||
- Value Object의 생성자를 private/factory only로 두는 이유는? aggregate root의 mutator를 package-private/protected로 강제하는 이유는?
|
||||
- ORM 매핑을 도메인 외부에서 수행(Vernon Option A)하는 방식과, JPA annotation을 도메인에 직접 다는 방식(Option B / 우아한형제들 초기 글 스타일)의 trade-off는?
|
||||
|
||||
## Do Not Overclaim
|
||||
|
||||
- **"HMAC + salt = anonymization"으로 단정 금지**. ENISA·IAPP 기준 pseudonymization. brute-force 가능 input(휴대폰·주민번호 일부 등)에서는 tokenization이 우위인 구간이 존재.
|
||||
- **"backup도 GDPR Art.17로 완전 삭제했다"고 단정 금지**. cryptographic erase + per-principal envelope key 구조가 실제로 설계되어 있어야 가능한 진술이다. 단순 backup 보존만으로는 단건 삭제 불가.
|
||||
- **"DSR SLA 30/14일은 GDPR 요구치"라고 단정 금지**. GDPR Art.12는 "원칙적으로 1개월(연장 시 +2개월)"이며, 30/14일은 내부 운영 결정값이다.
|
||||
- **"ICAP gateway antivirus가 모든 위협을 막는다"고 단정 금지**. HTTPS E2E TLS 환경 한계와 post-upload async scan 필요성이 있다.
|
||||
- **"Direct S3 presigned URL이 가장 안전하다"고 단정 금지**. in-app validation 부재 → quarantine bucket + 후행 worker 분리가 추가로 필요.
|
||||
- **"우리는 pure DDD 기반"이라고 단정 금지**. Vernon Option A(ORM 외부 매핑) 차용이며, CQRS / event sourcing은 채택하지 않은 절충이다. "transport-free domain event 정의만 차용했다"가 더 정확한 표현.
|
||||
- **"Vernon Option B(JPA direct annotation)도 DDD이니 동일하다"고 단정 금지**. domain의 framework 격리 규칙을 두는 코드베이스에서는 양립 불가.
|
||||
- **"functional domain modeling(Scala/F#) 도입했다"고 단정 금지**(JVM Java 기준 코드베이스에서). 패러다임 학습 비용과 팀 적합성이 별도로 필요.
|
||||
|
||||
## Sources
|
||||
|
||||
### Privacy
|
||||
- [GDPR Article 25 — Data protection by design and by default](https://gdpr-info.eu/art-25-gdpr/) — [[raw/official-docs/privacy-gdpr-article-25-design]]
|
||||
- [NIST SP 800-88 Rev.1 — Cryptographic Erase](https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-88r1.pdf) — [[raw/official-docs/privacy-cryptographic-erasure-nist-sp800-88]]
|
||||
- [Per-Principal Envelope Key for GDPR Art.17 (NIST SP 800-88 + AWS/GCP KMS envelope)](https://csrc.nist.gov/publications/detail/sp/800-88/rev-1/final) — [[raw/official-docs/gdpr-cryptographic-erasure-envelope-key-pattern]]
|
||||
- [ENISA / IAPP — Pseudonymization techniques](https://www.enisa.europa.eu/publications/pseudonymisation-techniques-and-best-practices) — [[raw/company-tech-blogs/privacy-pseudonymization-hmac-vs-tokenization-iapp]]
|
||||
|
||||
### File / Resource
|
||||
- [ClamAV / ICAP — Gateway antivirus scan](https://docs.clamav.net/manual/Usage/Scanning.html) — [[raw/company-tech-blogs/file-clamav-icap-gateway-scan]]
|
||||
- [AWS S3 — Presigned URL upload](https://docs.aws.amazon.com/AmazonS3/latest/userguide/PresignedUrlUploadObject.html) — [[raw/official-docs/file-s3-presigned-url-upload]]
|
||||
- [tus.io — Resumable upload protocol v1.0.0](https://tus.io/protocols/resumable-upload) — [[raw/official-docs/file-tus-resumable-upload-protocol]]
|
||||
|
||||
### Domain Modeling
|
||||
- [Vaughn Vernon — Aggregate root rules (IDDD)](https://www.dddcommunity.org/library/vernon_2011/) — [[raw/official-docs/domain-vaughn-vernon-aggregate-root]]
|
||||
- [Martin Fowler — Anemic Domain Model](https://martinfowler.com/bliki/AnemicDomainModel.html) — [[raw/official-docs/domain-fowler-anemic-vs-rich-model]]
|
||||
- [우아한형제들 — DDD Aggregate 구현](https://techblog.woowahan.com/2711/) — [[raw/company-tech-blogs/domain-woowahan-ddd-aggregate-techblog]]
|
||||
- [Greg Young — CQRS Documents (Event sourcing vs CQRS 구분)](https://cqrs.files.wordpress.com/2010/11/cqrs_documents.pdf) — [[raw/company-tech-blogs/domain-event-sourcing-vs-cqrs-greg-young]]
|
||||
|
||||
### Canonical
|
||||
- [[raw/project-notes/ca-skeleton-operational-contract]] §19, §29 G-J
|
||||
@@ -1 +0,0 @@
|
||||
../../vault/30-knowledge/concepts/resource-identifier-format.md
|
||||
@@ -0,0 +1,135 @@
|
||||
---
|
||||
title: Resource Identifier Format (ULID vs UUIDv7 vs UUIDv4 vs Snowflake)
|
||||
source_type: llm-generated
|
||||
status: draft
|
||||
confidence: medium
|
||||
tags: [resource-identifier, ulid, uuid, backend]
|
||||
related_projects: [ca-skeleton]
|
||||
last_reviewed: 2026-06-04
|
||||
---
|
||||
|
||||
# Resource Identifier Format (ULID vs UUIDv7 vs UUIDv4 vs Snowflake)
|
||||
|
||||
> Layer: `wiki/concepts/` — 일반 개념. 특정 프로젝트(ca-tmpl)의 적용 사실은 [[wiki/projects/ca-tmpl/resource-identifier-format]] 로 분리.
|
||||
|
||||
## Summary
|
||||
|
||||
Resource identifier format 결정은 API resource 를 가리키는 public ID 의 *형식*(random vs time-ordered, charset, 길이, prefix)을 고르는 일이다. 후보는 크게 random 계열(UUID v4, NanoID)과 time-ordered 계열(UUID v7, ULID, KSUID, Snowflake, TSID)로 갈린다. 핵심 trade-off 축은 **(1) 정렬성/DB index locality, (2) timestamp leak(privacy), (3) URL 길이/charset, (4) 조율 부담, (5) 표준 여부**다. ID 는 URL·log·DB PK·cache key·FK 에 한 번 박히면 변경이 breaking 이므로, 형식 선택은 되돌리기 어려운 결정이다.
|
||||
|
||||
## Standard (공식 정의)
|
||||
|
||||
### UUID (RFC 9562, 2024)
|
||||
|
||||
IETF RFC 9562 는 UUID 의 128-bit 구조와 버전을 정의한다. v4 는 순수 random, v7 은 48-bit Unix millisecond timestamp 를 앞에 두는 **time-ordered** 변형이며, 같은 timestamp 내 단조성을 위한 monotonicity 메커니즘을 규정한다. RFC 는 새 ID 가 필요할 때 time-ordered 변형(v6/v7)을 SHOULD 로 권고한다. §8 은 timestamp 노출의 attack surface 를 "very small" 로 기술한다.
|
||||
|
||||
출처: [[raw/official-docs/rfc9562-uuid]] (RFC9562-C1~C5).
|
||||
|
||||
### ULID (공식 spec)
|
||||
|
||||
ULID 는 128-bit 를 **26-char Crockford base32** 로 인코딩한 형식이다. 앞 48-bit 가 millisecond timestamp(정렬 가능), 뒤 80-bit 가 random. `getMonotonicUlid()` 류의 monotonic factory 는 동일 ms 내 단조 증가를 보장한다. 128-bit 이므로 UUID 와 binary 호환(상호 변환 가능)이다.
|
||||
|
||||
출처: [[raw/official-docs/ulid-spec.md]] (ULID-C1~C6).
|
||||
|
||||
### Crockford base32 / RFC 3986
|
||||
|
||||
- **Crockford base32**: 32-char alphabet 에서 사람이 혼동하는 **I / L / O / U 를 제외**한다. 디코딩 시 `I`/`L` → `1`, `O` → `0` 으로 정규화하고 대소문자를 구분하지 않는다(case-insensitive). 출처: [[raw/official-docs/crockford-base32-spec.md]] (CROCKFORD-C1~C4).
|
||||
- **RFC 3986 (URI generic syntax)**: `unreserved` charset 은 `ALPHA / DIGIT / "-" / "." / "_" / "~"`. path component 는 case-sensitive 로 취급되며 §6.2.2.1 의 case normalization 규칙은 scheme/host 에만 적용된다. ULID 의 `0-9A-Z` 는 `unreserved` 의 진부분집합이라 percent-encoding 없이 URL path 에 안전하다. 출처: [[raw/official-docs/rfc3986-uri-generic-syntax]] (RFC3986-C1/C3/C4).
|
||||
|
||||
### 식별자 관례 (벤더 표준 — best practice 아님)
|
||||
|
||||
- **Google AIP-148**: `name`(server-assigned), `uid`(system-assigned opaque, non-PII), `display_name`(mutable), `parent`(계층 resource name) 표준 필드. 출처: [[raw/official-docs/google-aip-148-standard-fields]] (AIP148-C1~C5).
|
||||
- **Stripe**: typed prefix opaque ID(`ch_`, `cus_`, `pi_`). 단 Stripe 스스로 prefix 변경을 *backward-compatible* 로 분류 → prefix 영구 불변 보장이 아니므로 prefix 의존 코드는 lock-in 위험. Idempotency-Key 는 client-generated 로 resource ID 와 별개. 출처: [[raw/official-docs/stripe-resource-id-convention]] (STRIPE-C1~C5).
|
||||
|
||||
> AIP-148·Stripe 는 `official-vendor-doc`/벤더 관례다. RFC 9562·RFC 3986·ULID spec 같은 `official-standard` 와 달리 "공식 best practice" 로 일반화하면 안 된다.
|
||||
|
||||
## 한계 / 주의점
|
||||
|
||||
후보별 trade-off:
|
||||
|
||||
| 형식 | 정렬성(DB index) | timestamp leak | URL 길이 | 조율 부담 | 표준 |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| Sequential integer | 최상 | 없음(but enumeration/count leak) | 짧음 | 없음 | — |
|
||||
| UUID v4 | 나쁨(random → B-tree 단편화) | 없음 | 36자(dashed) | 없음 | RFC 9562 |
|
||||
| UUID v7 | 좋음(time-ordered) | **48-bit ms 노출** | 36자 | 없음 | RFC 9562 |
|
||||
| ULID | 좋음(time-ordered) | **48-bit ms 노출** | 26자 | 없음 | ULID spec(비-IETF) |
|
||||
| NanoID | 나쁨(random) | 없음 | 21자(default) | 없음 | 라이브러리 |
|
||||
| KSUID | 좋음 | 초 단위 노출 | 27자(base62) | 없음 | 라이브러리 |
|
||||
| Snowflake | 좋음(k-sorted) | ms 노출 + machine ID | ~19자(64-bit) | **worker/datacenter id 조율** | 라이브러리 |
|
||||
| TSID | 좋음 | ms 노출 | BIGINT fit | 일부 | 라이브러리 |
|
||||
| CUID2 | 없음(보안 우선) | **없음(저자 주장)** | 24자(base36) | 없음 | 라이브러리 |
|
||||
|
||||
주요 함정:
|
||||
|
||||
- **Sequential ID**: enumeration attack + count leak + tenant 격리 위반. public ID 로 부적합.
|
||||
- **random UUID v4 의 DB 비용**: time-ordered 가 아니라 B-tree index 에 random insert → page split + WAL/디스크 증가. Percona 의 MySQL InnoDB 25M-row 벤치마크에서 random UUID PK 가 ordered UUID 대비 +50% 디스크, ordered UUID ≈ BIGINT 성능. 단 이는 MySQL InnoDB clustered index 기준 — PostgreSQL HEAP/MVCC 등 다른 엔진에는 *parallel evidence* 로만 적용된다. 출처: [[raw/company-tech-blogs/percona-uuid-storage-mysql]] (PERCONA-UUID-C2~C5).
|
||||
- **timestamp leak**: UUID v7 / ULID 는 48-bit ms timestamp 가 평문 노출 → 작성 시각·가입 순서·활동 패턴 추론 가능. *user-facing* ID 에서 실질 문제. 완화책은 수용 / random scramble / CUID2 채택. CUID2 의 timestamp 비노출은 *저자 주장*이며 독립 감사로 확인된 것은 아니다. 출처: [[raw/official-docs/cuid2-spec.md]] (CUID2-C1).
|
||||
- **Snowflake 의 조율 부담**: worker_id / datacenter_id 를 노드마다 사전 할당해야 함 → 단일 generator 환경에는 과한 운영 부담. 출처: [[raw/company-tech-blogs/snowflake-twitter-id]] (SNOWFLAKE-C1~C5).
|
||||
- **case-insensitive charset 의 함정**: Crockford base32(ULID)는 입력이 case-insensitive 라 서버가 URL boundary 에서 canonical uppercase 로 normalize 하지 않으면 cache key miss 가 발생한다.
|
||||
- **typed prefix lock-in**: Stripe 자신이 prefix 변경을 backward-compatible 로 본다 → prefix 를 파싱·의존하는 코드는 깨질 수 있다.
|
||||
- **public ID vs internal sequence**: external-only(ULID 하나가 public ID = PK, Stripe)는 단순하지만, dual column(internal BIGINT + external ULID, Shopify/Linear/PlanetScale)은 audit/JOIN 성능을 회수한다. 후자는 cache key/FK 를 어느 쪽으로 둘지 추가 결정을 부른다. 출처: [[raw/company-tech-blogs/planetscale-nanoid-api]] (PLANETSCALE-NANOID-C4).
|
||||
|
||||
## Project Application
|
||||
|
||||
- ca-tmpl(Clean Architecture skeleton)에서의 실제 ULID 채택 + `adapter-identifier` 모듈 구현 사실은 [[wiki/projects/ca-tmpl/resource-identifier-format]] 참조. (본 개념 문서는 일반론만 다룬다.)
|
||||
|
||||
## Claim-backed Knowledge
|
||||
|
||||
> 인용된 raw source 의 claim 만. 출처 없는 일반화 금지.
|
||||
|
||||
| Knowledge Point | Supporting Claims | Confidence | Notes |
|
||||
| --- | --- | --- | --- |
|
||||
| RFC 9562 가 UUID v7 = time-ordered(48-bit Unix ms) 를 정의하고 새 ID 에 time-ordered 를 SHOULD 권고 | [[raw/official-docs/rfc9562-uuid]] RFC9562-C1/C3 | high | `official-standard` |
|
||||
| RFC 9562 §8 이 timestamp 노출 attack surface 를 "very small" 로 기술 | [[raw/official-docs/rfc9562-uuid]] RFC9562-C5 | high | `official-standard` |
|
||||
| ULID = 26-char Crockford base32, 48-bit ms timestamp + 80-bit random, monotonic 정렬 | [[raw/official-docs/ulid-spec.md]] ULID-C1~C5 | high | `official-reference`(비-IETF spec) |
|
||||
| Crockford base32 가 I/L/O/U 제외 + 디코딩 시 정규화(case-insensitive) | [[raw/official-docs/crockford-base32-spec.md]] CROCKFORD-C1~C3 | high | `official-reference` |
|
||||
| RFC 3986 `unreserved` = `ALPHA / DIGIT / "-" / "." / "_" / "~"`, path case-sensitive | [[raw/official-docs/rfc3986-uri-generic-syntax]] RFC3986-C1/C3 | high | `official-standard` |
|
||||
| Google AIP-148 의 uid = system-assigned opaque(non-PII), display_name 과 분리 | [[raw/official-docs/google-aip-148-standard-fields]] AIP148-C2/C3 | medium | `official-vendor-doc` (벤더 관례, 공식 표준 아님) |
|
||||
| Stripe 가 typed prefix 변경을 backward-compatible 로 분류(영구 불변 보장 아님) | [[raw/official-docs/stripe-resource-id-convention]] STRIPE-C2 | medium | `official-vendor-doc` |
|
||||
| Percona: MySQL InnoDB 에서 random UUID PK 가 ordered UUID 대비 +50% 디스크, ordered UUID ≈ BIGINT (25M-row) | [[raw/company-tech-blogs/percona-uuid-storage-mysql]] PERCONA-UUID-C2/C5 | medium | `company-case-study` (MySQL 5.x, 타 엔진엔 parallel evidence) |
|
||||
| CUID2 가 timestamp leak 없음 | [[raw/official-docs/cuid2-spec.md]] CUID2-C1 | low | `official-reference` (저자 주장, 독립 감사 미확인) |
|
||||
| Snowflake 가 worker/datacenter id 사전 조율을 요구 | [[raw/company-tech-blogs/snowflake-twitter-id]] SNOWFLAKE-C1 | medium | `company-case-study` |
|
||||
| NanoID 21자 default + URL-safe alphabet `A-Za-z0-9_-` + crypto-strong random | [[raw/official-docs/nanoid-spec]] NANOID-C1/C2/C4 | high | `official-reference` |
|
||||
| Brandur(전 Stripe): Idempotency-Key 는 client-generated, ~24h TTL, request fingerprint 비교 | [[raw/company-tech-blogs/brandur-stripe-idempotency-keys]] BRANDUR-IDEMP-C8~C12 | medium | `engineering-blog` |
|
||||
|
||||
## 내가 설명할 수 있어야 하는 것
|
||||
|
||||
- time-ordered ID(UUID v7 / ULID)가 random UUID v4 대비 DB index locality 에 유리한 *원리*(B-tree 에 정렬된 키가 append 우세).
|
||||
- timestamp leak 가 왜 *user-facing* ID 에서만 실질 문제인지, 완화책(수용 / scramble / CUID2)의 trade-off.
|
||||
- Crockford base32 가 I/L/O/U 를 제외하는 이유 + 그래서 생기는 canonical uppercase 출력 + case-insensitive 입력 정규화 의무.
|
||||
- public ID vs internal sequence(external-only vs dual column)의 trade-off.
|
||||
- Idempotency-Key(client-generated, ephemeral) 와 resource ID(server-assigned, persistent)가 왜 별개 형식인지.
|
||||
- "Netflix/Stripe 가 X 를 쓰니까 공식이다" 가 아니라, RFC(official-standard) 와 벤더 관례(vendor-doc)·사례(case-study)를 구분해 말하는 것.
|
||||
|
||||
## Interview Questions
|
||||
|
||||
- ULID 와 UUID v7 은 둘 다 time-ordered 인데 왜 ULID 를 고를 수 있는가? (URL 길이 26 vs 36, Crockford base32 의 human-friendliness, Java 21 `java.util.UUID` 의 v7 native 미지원.)
|
||||
- random UUID v4 를 DB PK 로 쓰면 어떤 비용이 있는가? 어느 엔진 기준 벤치마크인가?
|
||||
- ULID/UUID v7 의 timestamp leak 가 실제로 어떤 정보를 노출하는가? 언제 문제이고 어떻게 완화하나?
|
||||
- typed prefix(`tk_`)를 쓰는 것의 장단점은? Stripe 가 prefix 변경을 어떻게 분류하는가?
|
||||
- public ID 와 internal sequence 를 분리(dual column)하는 동기와 비용은?
|
||||
|
||||
## Do Not Overclaim
|
||||
|
||||
- **"ULID 가 UUID 보다 항상 우월하다" → 금지.** timestamp leak(privacy), 비-IETF 표준, 라이브러리 의존이라는 trade-off 존재.
|
||||
- **"random UUID 는 PostgreSQL 에서도 느리다" → 단정 금지.** 인용 벤치마크는 MySQL InnoDB clustered index 기준 — 다른 엔진에는 parallel evidence 일 뿐.
|
||||
- **"CUID2 는 timestamp 가 절대 안 샌다" → 단정 금지.** spec 저자 주장이며 독립 감사로 확인된 것은 아니다.
|
||||
- **"Google AIP / Stripe 관례 = 업계 공식 표준" → 금지.** 벤더 관례·사례이지 RFC 같은 official-standard 가 아니다.
|
||||
- **"sequential ID 는 무조건 나쁘다" → 맥락 의존.** internal-only(외부 비노출) 라면 합리적일 수 있고, dual column 의 internal PK 가 그 예다.
|
||||
|
||||
## Sources
|
||||
|
||||
- [[raw/official-docs/rfc9562-uuid]] — IETF RFC 9562 (UUID v4/v6/v7/v8, monotonicity, §8 attack surface).
|
||||
- [[raw/official-docs/ulid-spec.md]] — ULID 공식 spec (26-char Crockford base32, monotonic).
|
||||
- [[raw/official-docs/crockford-base32-spec.md]] — Crockford base32 (I/L/O/U 제외, case-insensitive 디코딩).
|
||||
- [[raw/official-docs/rfc3986-uri-generic-syntax]] — URI generic syntax (`unreserved` charset, case normalization).
|
||||
- [[raw/official-docs/cuid2-spec.md]] — CUID2 (timestamp-leak-free 저자 주장).
|
||||
- [[raw/official-docs/nanoid-spec]] — NanoID (21자 URL-safe, crypto random).
|
||||
- [[raw/official-docs/google-aip-148-standard-fields]] — Google AIP-148 standard fields.
|
||||
- [[raw/official-docs/stripe-resource-id-convention]] — Stripe typed prefix opaque ID 관례.
|
||||
- [[raw/company-tech-blogs/percona-uuid-storage-mysql]] — Percona MySQL InnoDB UUID PK 벤치마크.
|
||||
- [[raw/company-tech-blogs/snowflake-twitter-id]] — Twitter Snowflake (조율 부담).
|
||||
- [[raw/company-tech-blogs/planetscale-nanoid-api]] — PlanetScale NanoID + dual column 사례.
|
||||
- [[raw/company-tech-blogs/brandur-stripe-idempotency-keys]] — Brandur: Idempotency-Key vs resource ID.
|
||||
- [[raw/company-tech-blogs/segment-ksuid]] — Segment KSUID (base62, 초 단위 timestamp).
|
||||
- [[raw/company-tech-blogs/github-graphql-global-node-id]] — GitHub global node ID (base64 type-encoded).
|
||||
- [[raw/company-tech-blogs/aws-iam-arn-format]] — AWS ARN 계층 prefix.
|
||||
@@ -1 +0,0 @@
|
||||
../../vault/30-knowledge/concepts/runtime-container-health-migration.md
|
||||
@@ -0,0 +1,158 @@
|
||||
---
|
||||
title: Runtime / Container / Health / Migration Baseline
|
||||
source_type: llm-generated
|
||||
status: draft
|
||||
confidence: medium
|
||||
tags: [runtime, container, kubernetes, health, migration, flyway]
|
||||
related_projects: [ca-skeleton]
|
||||
last_reviewed: 2026-05-22
|
||||
---
|
||||
|
||||
# Runtime / Container / Health / Migration Baseline
|
||||
|
||||
> Layer: `wiki/concepts/` — JVM 서비스의 container runtime · runtime health · migration startup 세 sub-topic을 한 문서로 통합한 baseline. 내 프로젝트 사실은 `project-template` 사용.
|
||||
|
||||
## Summary
|
||||
|
||||
JVM 서비스의 **runtime baseline**은 세 축으로 구성된다.
|
||||
|
||||
1. **Container**: Eclipse Temurin (Adoptium) JRE slim + JVM ergonomics (`-XX:MaxRAMPercentage=75`, `-XX:+UseContainerSupport`).
|
||||
2. **Health**: Kubernetes Probes (liveness/readiness/startup)를 **세 endpoint로 분리** + Spring Boot Actuator Health Groups로 dependency 범위를 명시.
|
||||
3. **Migration**: Flyway forward-only migration을 **readiness gated**로 실행 + 표준 startup exit code (sysexits 계열 78/70/71/72).
|
||||
|
||||
세 축은 **graceful shutdown 35s budget** (app 20s + preStop 5s + grace 10s margin)으로 묶인다.
|
||||
|
||||
## Standard (공식 정의)
|
||||
|
||||
### Container
|
||||
|
||||
- **Eclipse Temurin (Adoptium)** — JEP/JCK 인증 OpenJDK 빌드. JRE slim 이미지는 JDK 대비 footprint 작고 production runtime에 권장.
|
||||
- **OCI Image spec** — base image, layer, label 표준. Dockerfile은 OCI 호환 image를 산출.
|
||||
- **JVM container ergonomics**:
|
||||
- `-XX:+UseContainerSupport` — JDK 10+ default. cgroup memory/cpu limit을 JVM이 인식.
|
||||
- `-XX:MaxRAMPercentage=<N>` — container memory limit의 N%를 max heap으로 사용. 절대값 `-Xmx`보다 container 환경에서 안전.
|
||||
- `-XX:+ExitOnOutOfMemoryError` — JVM `OutOfMemoryError` 발생 시 즉시 process exit (137).
|
||||
- `-XX:HeapDumpPath=...` — OOM 진단용 heap dump.
|
||||
|
||||
### Health
|
||||
|
||||
- **Kubernetes Probes** (kubelet 공식 모델):
|
||||
- **liveness** — process가 살아있는가. 실패 시 container restart.
|
||||
- **readiness** — traffic을 받을 수 있는가. 실패 시 Service endpoint 제거 (drain).
|
||||
- **startup** — startup이 끝났는가. startup probe가 success할 때까지 liveness/readiness 비활성. 긴 migration/warmup 시 liveness 오판 방지.
|
||||
- probe 분리는 K8s 공식 권장. single `/health`로 묶지 않는다.
|
||||
- **Spring Boot Actuator Health Groups** — `management.endpoint.health.group.liveness.include`, `.readiness.include`로 endpoint별 HealthIndicator set을 분리.
|
||||
- Spring default readiness는 외부 dependency 미포함이므로 DB/broker 등 required dependency는 명시적 group 등록 필요.
|
||||
|
||||
### Migration
|
||||
|
||||
- **Flyway 공식**:
|
||||
- forward-only versioned migration이 기본 model.
|
||||
- `flyway.repair` — checksum/state 수정 도구. **prod 사용은 공식이 직접 위험성 경고** (실제 schema 변경 없이 metadata만 수정).
|
||||
- `flyway.baselineOnMigrate` — 기존 DB에 처음 Flyway 적용 시. 잘못 켜면 누락 migration이 skip된 채 baseline.
|
||||
- `flyway.outOfOrder` — version 순서 외 migration 허용. 협업 환경에서 일관성 깨짐.
|
||||
- **sysexits.h** (BSD `sysexits.h`, 1990s) — Unix 관례적 exit code 의미.
|
||||
- `64` — usage error
|
||||
- `70` — internal software error
|
||||
- `71` — OS error
|
||||
- `72` — critical OS file missing
|
||||
- `78` — config error
|
||||
- 표준이 강제하는 enum은 아니지만 ops/CI 진단에 관례적으로 사용.
|
||||
|
||||
## 한계 / 주의점
|
||||
|
||||
### Container 선택 트레이드오프
|
||||
|
||||
- **Temurin JRE slim (base)**:
|
||||
- 운영/디버깅 친숙도 우위 (shell, JDK tools 가용).
|
||||
- security surface는 distroless보다 크다 (apt, libc 등 OS 패키지 포함).
|
||||
- **Distroless (Google)**:
|
||||
- OS 패키지 제거 → 보안 surface 축소 + image 크기 감소.
|
||||
- shell·debug tool 없음 → in-container 디버깅 손실. 별도 sidecar/ephemeral container 필요.
|
||||
- **Alpine + musl libc**:
|
||||
- image 크기 작음.
|
||||
- musl libc는 glibc 호환성 risk (DNS resolver 차이, native lib 미지원 등). Java 일부 native lib는 alpine에서 동작 미보장.
|
||||
- **GraalVM Native Image / Spring Boot Native**:
|
||||
- cold start/메모리 우위 (수십 MB heap, ms 단위 startup).
|
||||
- reflection·dynamic proxy는 build-time metadata 필요. peak throughput은 HotSpot JIT보다 손실.
|
||||
- Spring Boot Native는 Spring 6+ + Spring Boot 3+ AOT compile 의존.
|
||||
- 우아한형제들 도입기는 전체 native 전환이 아닌 **hybrid 채택** 결론.
|
||||
|
||||
### Health 분리의 한계
|
||||
|
||||
- **Single `/health` endpoint (legacy)**:
|
||||
- liveness/readiness 구분 불가.
|
||||
- K8s rolling update 시 dependency 일시 outage가 container restart loop 유발 가능. traffic 유실 risk.
|
||||
- **Custom HealthIndicator만 사용**:
|
||||
- Spring default readiness는 외부 dependency 미포함. DB/broker 등은 명시적으로 readiness group에 묶지 않으면 readiness가 traffic 가능 여부를 반영하지 않음.
|
||||
- **Service mesh-based health (Istio sidecar)**:
|
||||
- mTLS 환경에서 편의성. 단 sidecar 살아있음 / app 살아있음 구분이 mesh layer에서 불명확.
|
||||
- 추가 infra 의존 (sidecar 주입, mesh control plane).
|
||||
|
||||
### Migration tool 트레이드오프
|
||||
|
||||
- **Liquibase (XML/YAML changelog)**:
|
||||
- DB-agnostic + rollback 기능.
|
||||
- XML/YAML 기반은 SQL 대비 verbose. migration speed Flyway 대비 느림 (changelog parser 오버헤드).
|
||||
- rollback 안전 보장 없음 (rollback script 사람이 작성).
|
||||
- **Hibernate `hbm2ddl=update` 등**:
|
||||
- 공식 anti-pattern. prod 사용 금지가 일반 권고. schema drift 추적 불가.
|
||||
- **Atlas / Tern (schema-as-code)**:
|
||||
- declarative + integrity hash 강점.
|
||||
- Java/Spring 생태계 성숙도 부족. JVM 외부 CLI tool.
|
||||
- **K8s Init Container 패턴**:
|
||||
- replica마다 init container 실행 → multi-instance migration race.
|
||||
- **K8s Job + migration lock**이 race 회피에 구조적 우월.
|
||||
- **Flyway 자체 한계**:
|
||||
- `repair` / `baselineOnMigrate` / `outOfOrder`는 잘못 쓰면 schema state corruption. 공식이 직접 위험 경고.
|
||||
- forward-only 모델이라 rollback은 별도 forward migration으로 처리.
|
||||
|
||||
### Exit code 한계
|
||||
|
||||
- sysexits.h는 관례. POSIX 강제 표준 아님. 조직 표준으로 명시적 enum 필요.
|
||||
|
||||
## Project Application
|
||||
|
||||
- [[wiki/projects/ca-tmpl/runtime-container-health-migration]] — ca-tmpl 의사결정 기록 (현재 `documented-only`, Phase C2 미진입). 실제 구현 여부는 project 문서 참조.
|
||||
- [[raw/branch-notes/feature-container-runtime-contract]] — container runtime 결정 (Temurin JRE slim, `MaxRAMPercentage=75`, UTC/UTF-8, graceful shutdown 35s).
|
||||
- [[raw/branch-notes/feature-runtime-health-lifecycle-contract]] — liveness/readiness/startup 3-endpoint 분리, Required vs Optional Dependency Matrix.
|
||||
- [[raw/branch-notes/feature-migration-startup-contract]] — Flyway baseline + readiness gated + exit code 78/70/71/72.
|
||||
- [[raw/project-notes/ca-skeleton-operational-contract]] (§15 Runtime / Lifecycle Contract).
|
||||
|
||||
## Interview Questions
|
||||
|
||||
- JRE slim과 distroless 중 어떤 base image를 선택하고, 그 근거는 무엇인가?
|
||||
- `-XX:MaxRAMPercentage=75`로 설정한 이유는 무엇이고, 절대값 `-Xmx`와 어떤 차이가 있는가?
|
||||
- liveness / readiness / startup 세 probe를 분리하는 이유는 무엇인가? single `/health`로 묶으면 어떤 운영 문제가 생기는가?
|
||||
- graceful shutdown을 app 20s + preStop 5s + terminationGracePeriodSeconds 35s로 잡았다면 각 단계가 어떤 의미를 가지는가?
|
||||
- Flyway `repair`가 prod에서 위험하다고 보는 근거는? 어떤 대안 경로가 있는가?
|
||||
- startup exit code 78 / 70 / 71 / 72로 분리하면 어떤 진단상 이점이 생기는가? (config error / internal error / OS error / critical OS file missing)
|
||||
|
||||
## Do Not Overclaim
|
||||
|
||||
- "GraalVM native-image가 곧 standard"라고 단정하지 말 것. reflection-heavy 코드와 peak throughput 손실은 실측 trade-off. 우아한형제들 사례도 hybrid 채택.
|
||||
- "Flyway가 항상 우월"이라고 단정하지 말 것. 조직이 XML/YAML 기반 schema-as-doc을 요구하거나 DB-agnostic이 강제일 때는 Liquibase가 합리.
|
||||
- "distroless가 보안상 무조건 정답"이라고 단정하지 말 것. in-container 디버깅 손실은 incident 대응 시간을 늘릴 수 있다.
|
||||
- "K8s probe만 있으면 graceful shutdown은 자동"이라고 말하지 말 것. app shutdown timeout과 manifest grace period가 sync되지 않으면 SIGKILL로 inflight 요청 유실.
|
||||
- "exit code 70/78은 표준"이라고 말하지 말 것. sysexits.h는 관례이고 조직 enum 명시가 필요.
|
||||
|
||||
## Sources
|
||||
|
||||
- [Eclipse Temurin / Adoptium project](https://adoptium.net/) — 공식 OpenJDK 배포.
|
||||
- [Kubernetes — Configure Liveness, Readiness and Startup Probes (공식)](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/)
|
||||
- [Spring Boot Actuator — Health (공식)](https://docs.spring.io/spring-boot/docs/current/reference/html/actuator.html#actuator.endpoints.health)
|
||||
- [Flyway — Concepts / Repair (공식)](https://documentation.red-gate.com/flyway/) — repair / baseline_on_migrate / out_of_order 위험성 경고 명시.
|
||||
- [sysexits.h — BSD man page](https://man.freebsd.org/cgi/man.cgi?sysexits) — 64/70/71/72/78 등 관례적 exit code.
|
||||
- [[raw/official-docs/container-distroless-google-github]] — Distroless 보안 surface vs 디버깅 손실.
|
||||
- [[raw/official-docs/container-alpine-java-musl-tradeoffs]] — Alpine + musl libc 호환성 risk.
|
||||
- [[raw/official-docs/container-graalvm-native-image-spring-boot]] — GraalVM native-image / Spring Boot Native AOT 비용·이득.
|
||||
- [[raw/company-tech-blogs/container-woowahan-spring-native-tradeoffs]] — 우아한형제들 Spring Native 도입기 (hybrid 채택).
|
||||
- [[raw/official-docs/runtime-health-k8s-probes-official]] — K8s liveness/readiness/startup 공식.
|
||||
- [[raw/official-docs/runtime-health-spring-actuator-groups]] — Spring Boot Actuator Health Groups.
|
||||
- [[raw/official-docs/runtime-health-istio-mesh-health-check]] — Istio mesh health 대안과 한계.
|
||||
- [[raw/company-tech-blogs/runtime-health-datadog-engineering-graceful-shutdown]] — Datadog graceful shutdown preStop/drain/grace 비율 사례.
|
||||
- [[raw/official-docs/migration-flyway-official-concepts-and-repair]] — Flyway 공식 repair/baseline_on_migrate/out_of_order 위험성.
|
||||
- [[raw/official-docs/migration-liquibase-official-changelog-xml-yaml]] — Liquibase XML/YAML changelog.
|
||||
- [[raw/official-docs/migration-atlas-schema-as-code]] — Atlas schema-as-code 대안.
|
||||
- [[raw/official-docs/migration-k8s-init-container-job-pattern]] — K8s Init Container vs Job 패턴 비교.
|
||||
- [[raw/project-notes/ca-skeleton-operational-contract]] — §15 Runtime / Lifecycle Contract.
|
||||
@@ -1 +0,0 @@
|
||||
../../vault/30-knowledge/concepts/sample-fixture-and-adoption.md
|
||||
@@ -0,0 +1,83 @@
|
||||
---
|
||||
title: Sample Fixture & Adoption (skeleton template lifecycle)
|
||||
source_type: llm-generated
|
||||
status: draft
|
||||
confidence: medium
|
||||
tags: [skeleton, sample-fixture, template, adoption]
|
||||
related_projects: [ca-skeleton]
|
||||
last_reviewed: 2026-05-22
|
||||
---
|
||||
|
||||
# Sample Fixture & Adoption (skeleton template lifecycle)
|
||||
|
||||
> Layer: `wiki/concepts/` — skeleton/template lifecycle 일반 개념. 구체 결정과 검증 등급은 `wiki/projects/` 또는 `raw/branch-notes/`에서 판정.
|
||||
|
||||
## Summary
|
||||
|
||||
skeleton/template repository 라이프사이클은 두 축으로 분해된다. 첫째, **sample fixture**는 비즈니스 기능이 아니라 skeleton 계약(envelope/error/capability/transaction/idempotency)을 트리거하는 contract 검증 도구이다. 둘째, **sample-off/adoption**은 실제 도메인을 얹을 때 sample을 production runtime에서 비활성화하면서도 운영 계약이 함께 사라지지 않도록 보장하는 절차이다. 두 영역의 대표 안: sample-ticket 12 scenario matrix + 6-field minimum model + `OPEN→IN_PROGRESS→CLOSED` state machine + optimistic lock + idempotency key, 그리고 sample-off profile + production dependency 차단 + dual-mode CI matrix(sample-on / sample-off 둘 다 release-blocking) + multi-module adoption checklist.
|
||||
|
||||
## Standard (공식 정의 / 업계 사례)
|
||||
|
||||
### Sample fixture 계열
|
||||
|
||||
- **Spring Petclinic**: Spring Framework 공식 데모. README에 "demo지 best-practice 아님" 본인 선언. 학습/시연 목적, contract 검증 매트릭스는 부재.
|
||||
- **RealWorld (gothinkster Conduit)**: cross-stack spec (Article/Comment/User/Follow/Favorite). 백엔드 언어/프레임워크 호환성을 검증하는 reference. spec은 풍부하지만 minimum이 아니고, envelope/idempotency/optimistic lock 같은 contract scenario는 정의 범위 밖.
|
||||
- **Spring Cloud Microservices sample**: microservices 변형 (config server, eureka, gateway). fixture 수준을 초과해 인프라 다수 component를 함께 보여줌.
|
||||
- **Stripe testmode**: SaaS sandbox. payment 도메인에 한정된 sandbox key/카드 번호.
|
||||
|
||||
### Removal / adoption 계열 (template scaffolding)
|
||||
|
||||
- **Yeoman / Maven archetype**: generator 시점에 sample 제외 옵션을 노출하는 전통적 generator 모델. 생성 후에는 sample 자취가 남지 않음.
|
||||
- **Cookiecutter (Python)**: `{{cookiecutter.*}}` 변수 치환 기반 generator. 생성 시점 sample-off가 기본.
|
||||
- **degit (Svelte)**: git history 없이 repo를 clone하는 경량 도구. 생성 후에도 원본 sample 그대로 존재.
|
||||
- **Spring Initializr**: Spring Boot 공식 generator. dependency / build tool / language / Java version 선택 기반이며 contract sample은 포함되지 않음.
|
||||
- **GitHub Template Repository**: GitHub 공식 기능. 한 번의 클릭으로 코드뿐 아니라 CI/Actions workflow 파일까지 그대로 복제됨. friction이 가장 낮은 reference scaffolding 모델.
|
||||
- **Backstage golden path (Spotify IDP)**: Spotify가 발표한 internal developer platform. service template / scorecard / catalog를 묶어 조직 차원에서 표준 stack 진입점을 제공.
|
||||
|
||||
## 한계 / 주의점
|
||||
|
||||
- **Spring Petclinic**: README가 "demo"라고 자기 부정. best-practice baseline으로 사용하기에는 contract enforcement test/registry/profile isolation이 없어 부족.
|
||||
- **RealWorld**: domain spec은 풍부하나 "minimum"이 아니며, validation/conflict/optimistic lock/idempotency를 trigger하는 contract 시나리오 매트릭스는 정의되지 않음. backend cross-stack 호환성 reference로는 적합.
|
||||
- **Stripe testmode**: SaaS-side sandbox. OSS skeleton repo가 채택할 수 있는 모델은 아니며 payment 도메인에 한정.
|
||||
- **No fixture (unit test only)**: contract test를 트리거할 도메인 흐름 자체가 없어 envelope/capability/transaction 일관성을 행위로 검증할 수단이 없음.
|
||||
- **Yeoman / Maven archetype**: generator 시점에 sample을 제거하므로, "sample-on / sample-off 두 mode를 CI에서 동시에 green으로 유지"하는 운영 모델과는 시맨틱이 다름.
|
||||
- **Cookiecutter**: Python ecosystem에 정착. JVM/Spring 환경에서는 직접 도구로 들이기 어렵고, 동일하게 generator 시점 sample-off 모델.
|
||||
- **degit**: 단일 repo 단순 clone에 최적화. monorepo / multi-module 구조나 CI/Actions 동반 복제에는 친화적이지 않음.
|
||||
- **Spring Initializr**: dependency-only generator. operational contract / sample fixture / contract test 같은 운영 계약 묶음은 제공하지 않음.
|
||||
- **GitHub Template Repository**: CI/Actions 파일까지 그대로 복제되어 friction이 낮다. skeleton repo 모델의 reference 1순위로 평가되지만, 그 자체로 sample-off profile이나 adoption 절차를 보장하지는 않음. 별도 sample-off/adoption 절차가 함께 정의되어야 함.
|
||||
- **Backstage**: 조직 규모가 service template / scorecard / catalog를 따로 운영할 수준에 도달한 이후 적합. 1인 / 소규모 단계에서는 IDP 도입 자체가 과투자.
|
||||
|
||||
## Project Application
|
||||
|
||||
- [[wiki/projects/ca-tmpl/sample-fixture-and-adoption]] — ca-tmpl 의사결정 기록 (현재 `documented-only`, Phase C2 미진입). 실제 구현 여부는 project 문서 참조.
|
||||
- [[raw/branch-notes/feature-sample-domain-contract-fixture]] — sample-ticket 12 scenario matrix + 6-field minimum model + state machine + optimistic lock + idempotency key 결정 SSOT branch.
|
||||
- [[raw/branch-notes/feature-sample-removal-adoption-contract]] — `sample-ticket` fixture module 유지 + sample-off runtime isolation + dual-mode CI matrix 결정 SSOT branch.
|
||||
- [[raw/project-notes/ca-skeleton-operational-contract]] — canonical operational contract (§17 Sample Domain Fixture, §22 Sample-ticket Contract Matrix, §29 G-H Sample / adoption).
|
||||
|
||||
## Interview Questions
|
||||
|
||||
- sample-ticket 12 scenario matrix는 어떤 의미를 갖나요? 왜 단순한 CRUD 예제가 아니어야 하나요?
|
||||
- sample-ticket이 6개 필드(`TicketId`, `TicketTitle`, `TicketStatus`, `TicketVersion`, `TicketOwner`, `IdempotencyKey`)만 가지는 근거는 무엇인가요?
|
||||
- "dual-mode CI matrix(sample-on / sample-off 둘 다 release-blocking)"는 어떤 문제를 막기 위한 장치인가요?
|
||||
- sample-off first adoption이 즉시 코드 삭제보다 좋은 이유는 무엇인가요?
|
||||
- Spring Petclinic이나 RealWorld 같은 기존 sample 대신 자체 fixture(sample-ticket)를 둔 이유는 무엇인가요?
|
||||
|
||||
## Do Not Overclaim
|
||||
|
||||
- sample-ticket을 "도메인 모델"로 단정하면 안 된다. sample은 skeleton 계약을 트리거하기 위한 **contract 검증 도구(fixture)**이며 production feature가 아니다.
|
||||
- Spring Initializr / Cookiecutter를 "ca-tmpl과 동급 alternative"로 단정하면 안 된다. 두 도구 모두 **generator 시점에 sample을 빼는 모델**이라 sample-on / sample-off 두 mode를 동시에 release-blocking으로 검증하는 운영 모델과 시맨틱이 다르다.
|
||||
- "GitHub Template Repository가 reference 1순위"라는 평가는 friction(=초기 복제 단계의 마찰) 기준일 뿐이다. sample-off 절차, adoption checklist, operational contract 보존은 별도로 정의되어야 한다.
|
||||
- Backstage는 조직 규모 임계점 이후의 IDP 진입점이며, 일반적인 skeleton repo와 동일 레이어가 아니다.
|
||||
- 위 비교는 외부 raw 자료 발췌와 ca-skeleton operational contract canonical을 기반으로 한 정리이며, 본 문서는 status `draft` / confidence `medium`이다. 실제 채택 / 검증 등급은 관련 `wiki/projects/` 문서에서 판정한다.
|
||||
|
||||
## Sources
|
||||
|
||||
- [[raw/official-docs/sample-spring-petclinic-github]] — Spring Petclinic README (demo 선언)
|
||||
- [[raw/official-docs/sample-realworld-gothinkster-github]] — RealWorld (Conduit) spec
|
||||
- [[raw/official-docs/sample-microservices-spring-cloud-github]] — Spring Cloud microservices sample
|
||||
- [[raw/official-docs/scaffolding-spring-initializr]] — Spring Initializr generator
|
||||
- [[raw/official-docs/scaffolding-cookiecutter-official]] — Cookiecutter (Python)
|
||||
- [[raw/official-docs/scaffolding-degit-svelte-github]] — degit (Svelte)
|
||||
- [[raw/official-docs/scaffolding-github-template-repository]] — GitHub Template Repository
|
||||
- [[raw/company-tech-blogs/scaffolding-backstage-golden-path-spotify]] — Backstage golden path (Spotify IDP)
|
||||
- [[raw/project-notes/ca-skeleton-operational-contract]] — §17 Sample Domain Fixture, §22 Sample-ticket Contract Matrix, §29 Group G-H
|
||||
@@ -1 +0,0 @@
|
||||
../../vault/30-knowledge/concepts/security-baseline-jwt-actuator-secrets.md
|
||||
@@ -0,0 +1,138 @@
|
||||
---
|
||||
title: Security Baseline (JWT Resource Server + Actuator + Secrets)
|
||||
source_type: llm-generated
|
||||
status: draft
|
||||
confidence: medium
|
||||
tags: [security, jwt, oauth2, actuator, secrets]
|
||||
related_projects: [ca-skeleton]
|
||||
last_reviewed: 2026-05-22
|
||||
---
|
||||
|
||||
# Security Baseline (JWT Resource Server + Actuator + Secrets)
|
||||
|
||||
> Layer: `wiki/concepts/` — JWT Resource Server 기반 인증/인가, Actuator 관리면 보안, secret 소스/rotation 세 가지를 한 묶음으로 다루는 백엔드 보안 baseline 개념 문서. 실무 적용은 `wiki/projects/` 문서로 분리.
|
||||
|
||||
## Summary
|
||||
|
||||
운영 가능한 백엔드 보안 baseline은 **세 축**으로 구성된다. ① 데이터면 인증/인가는 **JWT Resource Server**(RFC 7519/8725, OAuth2 Resource Server) 기준으로 표준화하고, 토큰 실패를 `missing / malformed / expired / invalid signature / issuer / audience / unknown kid / claim mapping` 등으로 분류한다. JWKS는 주기 refresh(예: 10분 + unknown kid 시 on-demand)로 키 회전을 흡수하고, JWT 시간 검증은 **clock skew tolerance 60s** 정도를 둔다. ② 제어면(Actuator)은 **management port 분리**(예: 9001) + prod allowlist(health / prometheus / info) + heapdump/threaddump/env/configprops/shutdown forbidden을 default로 한다. ③ Secret은 **prod = secret manager 또는 mounted secret**, local만 `.env` 허용, runtime reload 금지, rotation은 restart 또는 명시적 dual-bind/overlap window로만 한다.
|
||||
|
||||
## Standard (공식 정의)
|
||||
|
||||
### JWT / OAuth2 / 인가
|
||||
|
||||
- **RFC 7519 (JSON Web Token)**: JWT 구조와 `iss`, `aud`, `exp`, `nbf`, `iat`, `jti`, `sub` 등 표준 claim, 서명/검증 의무를 규정. `exp`/`nbf` 검증 시 "a few minutes leeway"가 일반적이며 구현은 명시된 허용치를 설정해야 한다.
|
||||
- **RFC 8725 (JWT Best Current Practices)**: algorithm confusion 회피(`alg: none` 금지, `HS256`↔`RS256` 혼용 금지), `kid` 사용, audience/issuer 명시 검증, `typ: JWT` 검증 등 운영상 함정 정리.
|
||||
- **RFC 6749/6750 + OAuth2 Resource Server**: bearer token으로 보호된 리소스에서 token validation 책임을 resource server에 두는 모델. Spring Security 6의 `spring-boot-starter-oauth2-resource-server`가 표준 구현 경로.
|
||||
- **RFC 8252 (OAuth 2.0 for Native Apps) + PKCE**: public client(SPA, mobile)의 authorization code flow에서 code interception 방어. **issuance flow** 영역으로 resource server JWT 검증과는 보완재.
|
||||
- **RFC 8705 (Mutual-TLS Client Authentication and Certificate-Bound Access Tokens)**: mTLS 또는 sender-constrained token. JWT보다 강한 보장이나 PKI 운영 비용이 큼.
|
||||
- **OWASP Authorization Cheatsheet**: deny-by-default, least privilege, server-side enforcement, ABAC/RBAC 혼합, audit logging 등 인가 설계 원칙.
|
||||
|
||||
### Actuator / 관리면
|
||||
|
||||
- **Spring Boot Actuator 공식 문서**: 기본적으로 `health`, `info`만 web exposure, 그 외(`env`, `configprops`, `heapdump`, `threaddump`, `loggers`, `shutdown`)는 default disabled. `management.endpoints.web.exposure.include`로 명시 허용 + `SecurityFilterChain`으로 별도 보호 권고.
|
||||
- **`management.server.port`**: app port(8080)와 별도의 management port(예: 9001)로 분리 가능. 네트워크 ACL/Ingress에서 외부 노출 차단을 단순화하는 것이 분리 권고의 핵심.
|
||||
- **Istio sidecar / service mesh**: mTLS, AuthorizationPolicy로 management endpoint 보호 가능. mesh 가정이 강하므로 framework-neutral skeleton에서는 대안.
|
||||
|
||||
### Secrets / Config
|
||||
|
||||
- **12-factor App §III. Config**: 환경 사이에서 변하는 값은 **환경변수**로 외부화, 코드와 분리. config dump 금지의 이론 근거.
|
||||
- **AWS Secrets Manager (auto-rotation)**: Lambda 기반 rotation function 표준. dual-binding window 동안 old/new credential을 둘 다 유효하게 두어 connection pool/검증자 캐시가 흡수하도록 설계.
|
||||
- **HashiCorp Vault (dynamic secrets)**: lease 기반 짧은 수명 credential 발급. lease renewal 책임을 클라이언트가 짊.
|
||||
- **K8s Secret + External Secrets Operator (ESO)**: 외부 secret manager → K8s Secret → 컨테이너 mount/env 경로. etcd 암호화 미설정 시 평문 저장 한계.
|
||||
- **NIST SP 800-57 (Recommendation for Key Management)**: cryptoperiod, key rotation, key destruction의 표준. HMAC salt/JWT signing key rotation 주기 결정의 reference.
|
||||
|
||||
## 한계 / 주의점
|
||||
|
||||
### JWT Resource Server
|
||||
|
||||
- **Revocation 한계**: 표준 JWT는 stateless 검증이므로 발급 후 강제 무효화가 어렵다. 회수 수단은 ① short expiry + refresh token, ② JWKS rotation + 작은 key overlap, ③ deny-list cache(상태 부활), ④ token introspection(stateless 포기) 중 trade-off. "JWT라 안전하다"는 단정 금지.
|
||||
- **algorithm confusion**: RFC 8725가 명시적으로 경고. 구현 단에서 server-side로 허용 알고리즘을 fix해야 함(`alg: none`/HS↔RS 혼용 금지).
|
||||
- **clock skew**: 너무 작게 잡으면 서버 시계 drift로 false negative, 너무 크면 expired token 수용 창 확대. 일반적으로 30~60s 권고.
|
||||
- **JWKS endpoint outage**: cache miss + IdP 장애 시 모든 인증이 막힘. 캐시 TTL + on-demand refresh + 명시적 outage status 분류가 필요.
|
||||
|
||||
### Session + Cookie
|
||||
|
||||
- stateless 확장성 손실(서버 측 session store 필요).
|
||||
- CSRF 방어, SameSite/HttpOnly/Secure cookie 운영 복잡도.
|
||||
- revocation은 session 삭제로 즉시 가능 — 보안상 강점이지만 비용은 분산 session store.
|
||||
|
||||
### mTLS
|
||||
|
||||
- sender-constrained로 token theft 위협에 강함.
|
||||
- 단점: PKI(발급/갱신/폐기) 운영 비용, public client(브라우저 SPA, 모바일 일반 사용자) 사용 어려움.
|
||||
|
||||
### OPA (Open Policy Engine)
|
||||
|
||||
- 정책-코드 분리, 외부에서 정책 변경/감사 가능.
|
||||
- 단점: 외부 호출 latency, sidecar/agent 운영, in-process 인가 2~3종에는 과한 인프라.
|
||||
|
||||
### Actuator
|
||||
|
||||
- **single-port + path ACL**: cloud ingress가 path 기반 차단을 강하게 보장할 때만 안전. 잘못된 filter ordering, regex 매칭 우회 risk.
|
||||
- **mTLS for management**: 강하지만 cert 운영 부담.
|
||||
- **mesh sidecar (Istio)**: mesh 도입을 전제 → skeleton/framework-neutral 가정과 충돌.
|
||||
- **info endpoint**: build info 외에 commit hash/branch만 노출해도 attack surface가 될 수 있음 — 무엇이 들어가는지 명시 필요.
|
||||
- **한국 사례 (토스/우아한형제들 등) 일부 참조 가능 (G-B 후속 보강 결과).** Actuator 노출 보안에 대한 한국 도메인 사례가 존재하며, JWT/secret 관리 직접 사례는 follow-up 후보로 남음.
|
||||
|
||||
### Secrets
|
||||
|
||||
- **Vault dynamic secrets**: 짧은 lease가 보안 우위이나, **Spring `@RefreshScope` + bean 재생성** 흐름을 강제 → connection pool/캐시 lifecycle과 충돌. ca-tmpl처럼 `@RefreshScope` 금지 환경에서는 정면 충돌.
|
||||
- **AWS Secrets Manager auto-rotation**: dual-binding window 60s 패턴과 정합하지만, rotation Lambda 자체가 운영/감사 대상.
|
||||
- **ESO**: K8s native이지만 etcd 평문 저장은 cluster operator의 별도 책임.
|
||||
- **Doppler / 1Password SDK**: dev 머신까지 reference 보호 강점이지만 SaaS 외부 의존.
|
||||
- **plain env**: prod에서 ps/dump/log 노출 가능성 — 단독 baseline으로는 거부 대상.
|
||||
|
||||
## Project Application
|
||||
|
||||
- [[wiki/projects/ca-tmpl/security-baseline-jwt-actuator-secrets]] — ca-tmpl 의사결정 기록 (현재 `documented-only`, Phase C2 미진입). 실제 구현 여부는 project 문서 참조.
|
||||
이 baseline은 ca-skeleton 운영 계약과 세 개의 branch-note 결정에 적용된다(검증 등급은 각 branch/project 문서가 판정한다 — 이 concept 문서는 등급을 매기지 않는다).
|
||||
|
||||
- [[raw/project-notes/ca-skeleton-operational-contract]] — §18 Control Plane Contract (Secrets / Config Source, Management / Actuator Security)
|
||||
- [[raw/branch-notes/feature-security-operational-baseline]] — JWT Resource Server + AuthN/AuthZ Matrix 12행 + JWKS 10min refresh + clock skew 60s + rotation overlap 24h + public path snapshot diff
|
||||
- [[raw/branch-notes/feature-management-actuator-security-contract]] — management port 9001 + prod allowlist + heapdump/threaddump prod forbidden + loggers prod read-only + metrics network ACL default
|
||||
- [[raw/branch-notes/feature-secrets-config-source-contract]] — prod = secret manager OR mounted env + `no-runtime-reload` default + `__LOCAL_DEV_` sentinel + JWT key 24h overlap / DB credential dual-bind 60s / API key restart-reload
|
||||
|
||||
## Interview Questions
|
||||
|
||||
- JWT vs Session 기반 인증을 어떤 기준으로 선택하는가? (stateless 확장성 / revocation 용이성 / cookie 운영 비용 / 클라이언트 타입)
|
||||
- JWKS rotation 주기와 unknown `kid` 처리 정책을 어떻게 설계하는가? (refresh 주기, on-demand refresh, overlap window)
|
||||
- Spring Boot Actuator를 운영에서 노출할 때 management port를 분리하는 이유는? (network 경계 단순화, ingress 정책, single-port + path ACL 위험)
|
||||
- secret rotation을 zero-downtime으로 만들 때 어떤 패턴을 쓰는가? (dual-bind window, JWT key overlap, restart-only vs runtime reload)
|
||||
- HMAC salt rotation을 90일 등으로 두는 근거는? (NIST cryptoperiod 권고, 누적 노출량 한도, downstream re-hash 비용)
|
||||
- JWT 검증의 `clock skew tolerance`를 어떻게 정하는가? (NTP drift 가정, 발급자/검증자 분산도, expired vs replay trade-off)
|
||||
|
||||
## Do Not Overclaim
|
||||
|
||||
- **"JWT는 안전하다"는 단정 금지.** 토큰 탈취 시 revocation이 어렵다는 한계가 있다. JWT의 보안성은 발급/저장/전송/회수 전 과정 설계에 좌우된다.
|
||||
- **"HashiCorp Vault가 secret 관리의 표준"이라는 단정 금지.** dynamic secrets는 강력하지만 `@RefreshScope`/bean refresh 패턴을 전제로 하며, 이를 금지하는 운영 계약(예: ca-skeleton)과는 충돌한다. AWS Secrets Manager, K8s + ESO, 1Password 등은 각자 다른 운영 상충점을 갖는다.
|
||||
- **"actuator를 켜두는 것은 항상 안전하다"는 단정 금지.** default exposure가 `health`/`info`로 좁아도 `env`, `configprops`, `heapdump`, `threaddump`, `shutdown`이 잘못 열리면 그대로 공격 표면이 된다. allowlist + 네트워크 경계 + 인증의 다층 방어가 필요하다.
|
||||
- **"company tech blog가 JWT/secret를 이렇게 쓴다 = 공식 best practice"** 로 격상 금지. 사례는 참고일 뿐 RFC/OWASP/공식 문서 기준과 구분해야 한다.
|
||||
|
||||
## Sources
|
||||
|
||||
### Canonical project SSOT
|
||||
|
||||
- [[raw/project-notes/ca-skeleton-operational-contract]] — §18 Control Plane Contract, §29 Group G-B 외부 근거 인덱스
|
||||
|
||||
### JWT / OAuth2 / 인가 (raw)
|
||||
|
||||
- [[raw/official-docs/security-jwt-rfc-7519-validation]] — RFC 7519 JWT claim 검증 표준
|
||||
- [[raw/official-docs/security-oauth2-pkce-rfc-8252]] — OAuth2 PKCE (RFC 8252) issuance flow 표준
|
||||
- [[raw/official-docs/security-mtls-rfc-8705]] — mTLS sender-constrained token (RFC 8705)
|
||||
- [[raw/official-docs/security-aws-sigv4-hmac-signing]] — AWS SigV4 HMAC signing (webhook/외부 호출 인증 영역)
|
||||
- [[raw/official-docs/security-authorization-cheatsheet-owasp]] — OWASP Authorization Cheatsheet (deny-by-default)
|
||||
|
||||
### Actuator / 관리면 (raw)
|
||||
|
||||
- [[raw/official-docs/actuator-endpoint-exposure-spring-official]] — Spring 공식 actuator default exposure 정책
|
||||
- [[raw/official-docs/actuator-management-port-spring-official]] — Spring 공식 separate management port 권고
|
||||
- [[raw/official-docs/actuator-istio-sidecar-management-alt]] — Istio sidecar 기반 management 보호 (대안)
|
||||
- [[raw/company-tech-blogs/security-woowahan-actuator-safe-usage]] — 우아한형제들 SOC팀 Actuator 안전 사용 사례 (한국 도메인)
|
||||
- [[raw/company-tech-blogs/security-toss-actuator-healthcheck]] — 토스 Spring Boot Actuator 헬스체크 (health detail 민감성, 한국 도메인)
|
||||
|
||||
### Secrets / Config (raw)
|
||||
|
||||
- [[raw/official-docs/secrets-aws-secrets-manager-rotation]] — AWS Secrets Manager + auto-rotation (dual-bind 패턴 정합)
|
||||
- [[raw/official-docs/secrets-vault-dynamic-secrets-hashicorp]] — HashiCorp Vault dynamic secrets (short lease)
|
||||
- [[raw/official-docs/secrets-k8s-secret-external-secrets-operator]] — K8s Secret + External Secrets Operator
|
||||
- [[raw/company-tech-blogs/secrets-1password-developer-secret-references]] — 1Password developer secret references (dev 머신 보호 사례)
|
||||
@@ -1 +0,0 @@
|
||||
../../vault/30-knowledge/concepts/skeleton-governance-registry-verification-test-scorecard.md
|
||||
@@ -0,0 +1,153 @@
|
||||
---
|
||||
title: Skeleton Governance (Registry + Verification + Test taxonomy + Scorecard)
|
||||
source_type: llm-generated
|
||||
status: draft
|
||||
confidence: medium
|
||||
tags: [skeleton, governance, archunit, testcontainers, scorecard]
|
||||
related_projects: [ca-skeleton]
|
||||
last_reviewed: 2026-05-22
|
||||
---
|
||||
|
||||
# Skeleton Governance (Registry + Verification + Test taxonomy + Scorecard)
|
||||
|
||||
> Layer: `wiki/concepts/` — 일반 개념. 내 프로젝트 사실은 `project-template` 사용.
|
||||
|
||||
## Summary
|
||||
|
||||
스켈레톤 거버넌스는 네 축으로 구성된다. (1) **Contract registry** — markdown SSOT(canonical 운영 계약) + YAML 파생을 단일 진실 원천으로 두고 ADR/스키마 레지스트리 같은 외부 대안을 트레이드오프 관점에서 선택, (2) **Verification suite** — Pact CDC · Spring Cloud Contract · Spring REST Docs · WireMock/Hoverfly 등으로 계약-구현 일치를 자동 검증, (3) **Test taxonomy** — 단위/얇은 슬라이스/통합/E2E/계약/성능의 6 레벨로 피라미드와 트로피의 절충을 명시, (4) **Readiness scorecard** — 11개 릴리즈 차단 게이트의 binary pass/fail로 채택 가능 여부를 판정. 네 축은 서로 참조 관계이며 어느 하나가 빠지면 거버넌스가 깨진다.
|
||||
|
||||
## Standard (공식 정의)
|
||||
|
||||
### Contract registry
|
||||
|
||||
- **Architecture Decision Records (ADR)**: Michael Nygard이 제안한 결정 단위 markdown 문서. 컨텍스트·결정·결과를 명시하며 한번 채택된 ADR은 변경 대신 새 ADR로 교체. branch-note의 "결정/근거/측정값" 패턴과 구조가 유사하다.
|
||||
- **Schema/Protobuf/Smithy registry**: 데이터/인터페이스 계약을 IDL로 선언하고 빌드 산출물(jar, 코드)로 분배. 멀티 언어·멀티 팀에서 단일 출처를 강제하는 방식.
|
||||
- **Markdown SSOT + YAML 파생**: 운영 계약을 사람이 읽는 markdown 한 곳에만 두고, machine-readable 형식은 빌드 시점에 파생. drift는 빌드 스크립트가 검사.
|
||||
- **Code-only registry (enum/annotation)**: ArchUnit·custom annotation에 메타정보를 박는 방식. verifier 가깝지만 사람이 읽기 어려움.
|
||||
|
||||
### Verification suite
|
||||
|
||||
- **Pact (Consumer-Driven Contract)**: consumer가 기대를 pact 파일로 선언 → provider가 pact broker에서 받아 검증. 외부 consumer가 많을 때 효과.
|
||||
- **Spring Cloud Contract**: provider 쪽 DSL/YAML로 계약 정의 → consumer stub 자동 생성. JVM 단일 생태계에 최적.
|
||||
- **Spring REST Docs**: 테스트 통과 시점에 asciidoc 스니펫을 자동 추출. 문서-구현 일치 보장 강하지만 "계약 위반 시 빌드 실패" 강제력은 약함.
|
||||
- **ApprovalTests / JSON snapshot**: 출력 스냅샷을 파일로 저장, diff로 회귀 감지. 단일 팀에서 가장 가볍다.
|
||||
- **WireMock / Hoverfly**: 외부 의존성 mock/record-replay. 통합 테스트에서 외부 시스템을 격리.
|
||||
- **ArchUnit**: 패키지 의존 방향·네이밍·어노테이션 규칙을 JUnit 테스트로 표현해 빌드 차단.
|
||||
|
||||
### Test taxonomy
|
||||
|
||||
- **Test pyramid (Mike Cohn, *Succeeding with Agile*)**: 단위 다수 → 서비스 일부 → UI 소수. 비용/속도 기반.
|
||||
- **Test trophy (Kent C. Dodds)**: 정적 분석 + 단위 + 통합(가장 두꺼움) + E2E. 통합이 ROI가 높다는 주장.
|
||||
- **Honeycomb (Spotify)**: 마이크로서비스에서는 통합 중심이 현실적이라는 변형.
|
||||
- **Fitness functions (*Building Evolutionary Architectures*, Ford et al.)**: 아키텍처 특성(레이어 의존성, 성능 SLO, 보안 룰)을 실행 가능한 테스트로 표현.
|
||||
- **Testcontainers**: real DB/Kafka/Redis를 Docker로 띄워 통합 테스트. mock의 false confidence를 줄인다는 입장.
|
||||
|
||||
### Readiness scorecard
|
||||
|
||||
- **AWS Well-Architected Framework**: 6 pillar(운영·보안·신뢰성·성능·비용·지속가능성)에 대한 review 질문. 점진적 maturity.
|
||||
- **CIS Benchmark**: 구성 항목별 pass/fail. 보안 baseline에 가까움.
|
||||
- **SLSA (Supply-chain Levels for Software Artifacts)**: build 단계의 무결성을 1~4 레벨로 나눔.
|
||||
- **CMMI**: 조직 프로세스 성숙도 1~5.
|
||||
- **OpenTelemetry Maturity Model**: observability 도입 단계.
|
||||
|
||||
스켈레톤은 이 중 **CIS/Well-Architected의 binary pass/fail** 접근에 가깝다. "릴리즈 가능한가"만 판정.
|
||||
|
||||
## 한계 / 주의점
|
||||
|
||||
### Registry 축
|
||||
|
||||
- **Markdown SSOT + YAML 파생**: drift 검증 도구를 **자체 작성**해야 함. CI에 통합되지 않으면 SSOT가 깨져도 모름.
|
||||
- **Code-only enum/annotation**: SSOT가 코드 곳곳에 분산. 사람이 한눈에 보기 어렵고 외부 리뷰어가 접근 못 함.
|
||||
- **Protobuf/Smithy registry**: IDL 학습·빌드 파이프라인 추가·breaking change 정책까지 필요. 단일 팀 스켈레톤에는 도입 비용이 효익을 초과할 수 있음.
|
||||
- **ArchUnit annotations as registry**: verifier 한정. "왜 이 규칙인지"를 표현하지 못함 — registry라기보다 enforcement. (2026-05-22 후속 평가: framework-neutral 부재 / git diff review 약함 / 외부 도구 호환 불가로 ca-tmpl에서 채택 보류, markdown SSOT 유지. [[raw/official-docs/archunit-annotation-as-registry-evaluation]])
|
||||
- **DB-stored registry (config service)**: 런타임 의존성·운영 부담. 빌드 타임 결정에는 부적합.
|
||||
|
||||
### Verification 축
|
||||
|
||||
- **Pact CDC**: 외부 consumer가 다수일 때 강점. **single-team / single-repo 환경에선 JSON snapshot이 우위** — broker 운영 비용, consumer-provider 협업 오버헤드가 효익을 초과.
|
||||
- **Spring Cloud Contract**: JVM 외 consumer가 있으면 stub 활용도 떨어짐.
|
||||
- **Spring REST Docs**: 문서 자동 생성에는 좋지만 "계약을 깨면 빌드가 실패"하는 강제력은 약함 — 문서가 코드와 같이 갱신될 뿐, 변경 자체는 막지 않음.
|
||||
- **WireMock/Hoverfly**: real system과 mock의 차이로 false green 가능. Testcontainers와 병행 필요.
|
||||
- **ArchUnit**: 규칙이 많아지면 테스트 시간·유지보수 부담. annotation 기반 규칙은 어노테이션 누락 시 silently pass.
|
||||
|
||||
### Test taxonomy 축
|
||||
|
||||
- **6 level (unit / slice / integration / e2e / contract / performance)**: 전체 budget 5분 등 시간 제약을 두면 레벨이 늘수록 budget 준수가 어려움. **레벨 분리 + 병렬화 + nightly 분리**가 필요.
|
||||
- **Testcontainers integration**: real DB/Redis로 mock보다 정확하지만 CI 시간 증가. cache layer warm-up 비용 큼.
|
||||
- **Trophy/Honeycomb 모델**: "통합이 ROI 높다"는 주장은 도메인 의존적. 순수 라이브러리·CLI에는 과한 권고.
|
||||
- **Fitness functions**: 빌드 차단력은 강하지만 룰을 잘못 짜면 false positive로 개발 흐름을 막음.
|
||||
|
||||
### Scorecard 축
|
||||
|
||||
- **Binary pass/fail**: **adoption gate 판단에 적합**. "이 스켈레톤으로 신규 프로젝트를 시작해도 되는가" 같은 컷오프 결정에 단순·명확.
|
||||
- 그러나 **점진적 개선이 필요한 기존 시스템 평가**에는 부적합 — "50% 만족"을 표현 못 함. 한 게이트를 못 넘으면 전체가 not-ready로 표시되어, 개선 우선순위를 가리기 어려움.
|
||||
- **AWS Well-Architected / CIS**: 운영 중 시스템의 점진적 개선·우선순위 매기기에 적합. 새 스켈레톤 평가엔 항목이 너무 많아 noise.
|
||||
- **SLSA**: 공급망에 한정. registry/test 영역은 다루지 않음.
|
||||
- **CMMI / OpenTelemetry maturity**: 조직·도메인 단위 평가. 단일 skeleton repo 단위에는 과대.
|
||||
|
||||
### 4축의 결합 한계
|
||||
|
||||
- 네 축이 서로 참조되도록 강제하지 않으면 거버넌스가 깨짐. 예: scorecard가 verification suite를 "통과" 표시했는데 실제로는 일부 contract만 검증된 경우. **메타 검증(scorecard ↔ verification ↔ registry 교차 확인)이 별도로 필요**.
|
||||
- branch-note ≈ mini-ADR로 운용하면 결정 이력은 보존되나, 시간이 지나며 ADR이 누락된 결정이 코드에 생길 수 있음 — registry 정기 audit 필요.
|
||||
|
||||
## Project Application
|
||||
|
||||
- [[wiki/projects/ca-tmpl/skeleton-governance-registry-verification-test-scorecard]] — ca-tmpl 의사결정 기록 (현재 `documented-only`, Phase C2 미진입). 실제 구현 여부는 project 문서 참조.
|
||||
- [[raw/project-notes/ca-skeleton-operational-contract]] — §12 Test Contract, §21 Contract Registry, §27 Readiness Scorecard, §29 Group G-G
|
||||
- [[raw/branch-notes/feature-contract-registry-governance]]
|
||||
- [[raw/branch-notes/feature-contract-verification-test-suite]]
|
||||
- [[raw/branch-notes/feature-test-taxonomy-fixture-contract]]
|
||||
- [[raw/branch-notes/feature-implementation-readiness-scorecard]]
|
||||
|
||||
(실제 구현 여부·검증 등급은 위 project / branch 문서에서 판정. 본 concept 문서는 등급을 직접 매기지 않음.)
|
||||
|
||||
## Interview Questions
|
||||
|
||||
- Contract registry의 SSOT 위치를 markdown SSOT vs code-only(enum/annotation) vs IDL(Protobuf/Smithy) 중 어떻게 선택했고, 각 선택의 트레이드오프는 무엇인가?
|
||||
- Consumer-Driven Contract(Pact)와 단순 JSON snapshot(ApprovalTests) 중 single-team skeleton에 어느 쪽을 택해야 하고 이유는?
|
||||
- Testcontainers를 통합 테스트에 강제하는 이유와, 대신 mock으로 갈 때 잃는 보장은 무엇인가?
|
||||
- 단위/슬라이스/통합/E2E/계약/성능의 6 test level이 각각 무엇을 보장하며, budget 5분을 어떻게 지키는가?
|
||||
- Readiness scorecard에서 binary pass/fail vs maturity score(AWS WAF·CMMI 류) 중 binary를 택하는 상황은 언제인가?
|
||||
- branch-note를 mini-ADR처럼 사용한다는 것은 구체적으로 무엇을 의미하며, ADR과 어떤 부분이 같고 어떤 부분이 다른가?
|
||||
|
||||
## Do Not Overclaim
|
||||
|
||||
- "Pact CDC가 항상 우월하다"고 말하지 말 것. **외부 consumer가 다수일 때만 효익이 비용을 넘는다**. single-team 환경에서는 over-engineering이 되며, JSON snapshot이 더 적합할 수 있다.
|
||||
- "Binary pass/fail이 절대적 기준"이라고 말하지 말 것. **adoption gate(채택 가능 여부) 한정**이다. 운영 중 시스템의 점진적 개선 평가에는 AWS Well-Architected / CIS 형태가 적합하다.
|
||||
- "ArchUnit으로 모든 거버넌스를 강제할 수 있다"고 말하지 말 것. 어노테이션 누락 시 silently pass하는 등 enforcement 한계가 있다.
|
||||
- "Spring REST Docs가 계약을 강제한다"고 말하지 말 것. 문서-구현 일치를 자동화할 뿐, 계약 위반 자체를 막는 강제력은 약하다.
|
||||
- "Markdown SSOT + YAML 파생이 다른 registry보다 우월하다"고 말하지 말 것. **drift 검증 도구를 자체 작성·CI 통합**해야 비로소 신뢰 가능하다.
|
||||
- "Test taxonomy 6 level이면 항상 5분 budget을 지킬 수 있다"고 말하지 말 것. 병렬화·nightly 분리·캐시 전략이 같이 가야 한다.
|
||||
|
||||
## Sources
|
||||
|
||||
### Canonical (내 프로젝트 운영 계약)
|
||||
|
||||
- [[raw/project-notes/ca-skeleton-operational-contract]] — §12 Test Contract, §21 Contract Registry, §27 Readiness Scorecard, §29 Group G-G
|
||||
|
||||
### Registry
|
||||
|
||||
- [[raw/official-docs/registry-adr-official]] — Architecture Decision Records
|
||||
- [[raw/official-docs/schema-protobuf-vs-json-evolution]] — IDL registry / 호환성
|
||||
- [[raw/official-docs/governance-archunit-official]] — code-only enforcement registry
|
||||
- [[raw/official-docs/archunit-annotation-as-registry-evaluation]] — annotation-as-registry 대안 평가 (2026-05-22, ca-tmpl 채택 보류)
|
||||
|
||||
### Verification
|
||||
|
||||
- [[raw/official-docs/verification-pact-cdc-official]] — Consumer-Driven Contract
|
||||
- [[raw/official-docs/verification-spring-cloud-contract-official]] — provider-side contract
|
||||
- [[raw/official-docs/verification-spring-restdocs-official]] — 문서-구현 일치
|
||||
- [[raw/official-docs/verification-approvaltests-snapshot-official]] — JSON snapshot 대안
|
||||
|
||||
### Test taxonomy
|
||||
|
||||
- [[raw/official-docs/test-taxonomy-practical-pyramid-fowler]] — Practical Test Pyramid
|
||||
- [[raw/official-docs/test-taxonomy-testcontainers-official]] — Testcontainers
|
||||
- [[raw/official-docs/dx-testcontainers-java-best-practices]] — Testcontainers Java DX
|
||||
- [[raw/company-tech-blogs/test-pyramid-vs-trophy-kent-dodds]] — Trophy 모델 (회사 블로그 — 공식 기준 아님)
|
||||
|
||||
### Scorecard
|
||||
|
||||
- [[raw/official-docs/scorecard-aws-well-architected]] — Well-Architected Framework
|
||||
- [[raw/official-docs/scorecard-cis-benchmarks-slsa]] — CIS / SLSA
|
||||
- [[raw/official-docs/scorecard-opentelemetry-maturity]] — OTel Maturity Model
|
||||
@@ -1 +0,0 @@
|
||||
../../vault/30-knowledge/concepts/spring-smart-lifecycle.md
|
||||
@@ -0,0 +1,66 @@
|
||||
---
|
||||
title: concept / Spring SmartLifecycle
|
||||
source_type: llm-generated
|
||||
status: reviewed
|
||||
confidence: high
|
||||
tags: [concept, ca-tmpl, runtime, spring-framework, graceful-shutdown]
|
||||
related_projects: [ca-tmpl]
|
||||
last_reviewed: 2026-06-15
|
||||
---
|
||||
|
||||
# concept / Spring SmartLifecycle
|
||||
|
||||
## Summary
|
||||
|
||||
Spring 컨텍스트의 생명 주기(start / stop)에 통합되어, 빈의 시작 및 종료 순서를 결정론적으로(Deterministic) 제어할 수 있게 해주는 인터페이스.
|
||||
- 애플리케이션 종료 시점에 리소스 반납 및 진행 중인 트랜잭션/재시도의 중단을 순서대로 조율하여 우아한 종료(Graceful Shutdown)를 돕는다.
|
||||
|
||||
## Standard (공식 정의)
|
||||
|
||||
Spring Framework 공식 명세에 따른 정의는 다음과 같다.
|
||||
- **SmartLifecycle**: `Lifecycle` 및 `Phased` 인터페이스의 확장판.
|
||||
- **isAutoStartup()**: 컨텍스트 리프레시 시점에 `start()`가 자동으로 실행될지 여부를 결정한다.
|
||||
- **getPhase()**: 생명 주기 상의 실행 단계를 나타낸다.
|
||||
- **시작(Start) 순서**: `getPhase()`가 **작은 순**에서 **큰 순**으로 기동된다.
|
||||
- **종료(Stop) 순서**: `getPhase()`가 **큰 순**에서 **작은 순**(내림차순)으로 정지된다.
|
||||
- 따라서, phase가 `Integer.MAX_VALUE`인 빈은 가장 마지막에 기동되고, **종료 시점에는 가장 먼저** 멈춘다.
|
||||
|
||||
## 한계 / 주의점
|
||||
|
||||
- **ContextClosedEvent 와의 차이**: Spring의 `ContextClosedEvent` 리스너는 애플리케이션 컨텍스트가 닫히기 시작했다는 신호만 전달할 뿐, 빈의 소멸(destroy) 순서와 비결정론적으로 얽혀 있다. 예컨대 어떤 DB 소스 빈이 이미 소멸된 후에 커넥션을 수립하려는 리스너 코드가 호출되면 NPE나 의존성 부재 예외가 터진다.
|
||||
- **SmartLifecycle은 비동기 셧다운을 차단할 수 있다**: `stop(Runnable callback)` 메서드가 호출되면 종료 작업을 수행하고 반드시 callback을 호출해 주어야 한다. 그렇지 않으면 Spring이 설정된 셧다운 타임아웃까지 대기하여 기동 종료 과정이 지연될 수 있다.
|
||||
|
||||
## Project Application
|
||||
|
||||
- [[wiki/explainer/adapter-outbound.md]]
|
||||
- `OutboundHttpShutdownGuard`가 `SmartLifecycle`을 구현하고 `getPhase()`에서 `Integer.MAX_VALUE`를 반환함.
|
||||
- 이로 인해 Spring 컨텍스트가 종료 과정을 개시할 때, 다른 어떤 데이터베이스 빈이나 아웃바운드 의존성 어댑터가 종료되기 전에 **가장 먼저** 셧다운 가드의 `stop()`이 실행되어 `shuttingDown` 플래그를 세우게 됨.
|
||||
- 리트라이 정책(`OutboundRetryPolicy`)은 루프 도중 이 플래그를 관찰하여 즉시 중단(short-circuit)하며, 신규 요청 또한 `OutboundHttpClient` 단에서 즉시 거부(`DEPENDENCY_CIRCUIT_OPEN` 예외)함으로써, 애플리케이션 종료 시 불필요한 HTTP 커넥션 맺기나 타임아웃 예산 낭비를 미연에 방지함.
|
||||
|
||||
## Claim-backed Knowledge
|
||||
|
||||
| Knowledge Point | Supporting Claims | Confidence | Notes |
|
||||
|---|---|---|---|
|
||||
| Spring SmartLifecycle 생명 주기 제어 및 phase 결정 규칙 | `raw/official-docs/spring-smartlifecycle-reference.md` | `high` | Spring Framework 공식 참조 |
|
||||
| Spring Boot Graceful Shutdown 시그널 수신 및 정리 과정 | `raw/official-docs/spring-boot-graceful-shutdown-reference.md` | `high` | Spring Boot Reference Guide |
|
||||
|
||||
## 내가 설명할 수 있어야 하는 것
|
||||
|
||||
- `Lifecycle`과 `SmartLifecycle` 인터페이스의 근본적인 차이는 무엇인가?
|
||||
- 왜 Graceful Shutdown 구현 시 `ContextClosedEvent` 리스너를 사용하는 대신 `SmartLifecycle` phase를 활용하는 것이 안전한가?
|
||||
- `getPhase()` 반환값이 `Integer.MAX_VALUE`일 때, 종료 시점의 제어 순서는 어떻게 보장되는가?
|
||||
|
||||
## Interview Questions
|
||||
|
||||
- Spring Framework에서 애플리케이션이 안전하게 종료(Graceful Shutdown)되도록 빈의 소멸 순서를 조율하는 방법에 대해 설명하고, `SmartLifecycle` 인터페이스의 동작 방식을 설명하십시오.
|
||||
- Kubernetes 환경에서 Pod가 종료 신호(SIGTERM)를 받았을 때 Spring Boot 애플리케이션이 수신 중인 API 및 아웃바운드 재시도 요청을 처리하는 우아한 종료 흐름을 설계해 보십시오.
|
||||
|
||||
## Do Not Overclaim
|
||||
|
||||
- "SmartLifecycle을 적용했기 때문에 종료 과정에서 어떠한 데이터 유실도 물리적으로 발생하지 않는다"고 보장해서는 안 된다. 컨테이너 셧다운 유예 기간(Kubernetes `terminationGracePeriodSeconds`)을 넘어가면 강제 종료(SIGKILL)가 발생하므로, 애플리케이션의 우아한 정리 시간이 유예 기간보다 짧도록 세심히 설정해야만 보장된다.
|
||||
|
||||
## Sources
|
||||
|
||||
- [Spring Framework Reference - SmartLifecycle](https://docs.spring.org/spring-framework/reference/core/beans/factory-nature.html#beans-factory-lifecycle)
|
||||
- [[raw/official-docs/spring-smartlifecycle-reference.md]]
|
||||
- [[raw/official-docs/spring-boot-graceful-shutdown-reference.md]]
|
||||
@@ -1 +0,0 @@
|
||||
../../vault/30-knowledge/concepts/streaming-response-patterns.md
|
||||
@@ -0,0 +1,86 @@
|
||||
---
|
||||
title: Streaming Response Patterns (SSE vs WebSocket vs Long-Polling vs Chunked)
|
||||
source_type: llm-generated
|
||||
status: draft
|
||||
confidence: medium
|
||||
tags: [streaming, sse, websocket, http, backend]
|
||||
related_projects: [ca-skeleton]
|
||||
last_reviewed: 2026-06-04
|
||||
---
|
||||
|
||||
# Streaming Response Patterns (SSE vs WebSocket vs Long-Polling vs Chunked)
|
||||
|
||||
> Layer: `wiki/concepts/` — 일반 개념. ca-skeleton 이 이 개념을 *미지원으로 결정하고 ArchUnit 으로 차단한* 사실은 [[wiki/projects/ca-tmpl/streaming-response-support]] 참조.
|
||||
|
||||
## Summary
|
||||
|
||||
HTTP 의 기본 통신 모델은 *request-response*(클라이언트가 묻고 서버가 한 번 답함)다. 이를 넘어 서버가 클라이언트로 데이터를 *지속적으로/능동적으로* 보내려면 별도 메커니즘이 필요하다 — 대표적으로 **SSE**(서버→클라이언트 단방향 push), **WebSocket**(양방향 full-duplex), **long-polling**(요청을 응답 없이 오래 붙잡아 둠), **chunked transfer encoding**(크기 미상 응답을 조각으로 흘려보냄)이 있다. 핵심 구분 축은 *통신 방향(단/양방향)* 과 *통신 모델이 request-response 를 유지하는가, server-push 로 바뀌는가* 다.
|
||||
|
||||
## Standard (공식 정의)
|
||||
|
||||
- **SSE (Server-Sent Events)**: MIME type `text/event-stream`, UTF-8 인코딩 필수. `data:` / `event:` / `id:` / `retry:` 필드를 가진 line-based text protocol. 클라이언트 측 API 는 `EventSource`(브라우저 `Window`/`Worker` context 전용 — 서버는 직접 `text/event-stream` 응답을 구현해야 함). 재연결 시 `Last-Event-ID` 헤더로 마지막 수신 event 를 서버에 전달. (WHATWG HTML §9.2)
|
||||
- **WebSocket**: 단일 TCP 연결 위의 *full-duplex*(양방향) 통신 — 각 side 가 독립적으로 언제든 송신 가능. HTTP Upgrade handshake(`GET` + `Upgrade: websocket` → `101 Switching Protocols`)로 연결을 수립하고, handshake 이후 TCP 는 HTTP 가 아닌 WebSocket 프레임 전송에 쓰인다. HTTP 와의 *유일한* 관계는 handshake 가 HTTP Upgrade 로 해석되는 것뿐인 독립 프로토콜. (IETF RFC 6455 §1.2, §1.7)
|
||||
- **Chunked transfer encoding**: *크기를 알 수 없는* content stream 을 length-delimited buffer 의 연속으로 전송 — 전체 크기 없이 connection 을 유지하며 메시지 완료를 수신자가 알 수 있게 함(`Transfer-Encoding: chunked`, last-chunk = size 0). HTTP/1.1 한정 (HTTP/2 는 DATA frame 으로 별도 framing, `Transfer-Encoding` 자체 금지). (IETF RFC 9112 §7.1)
|
||||
- **Long-polling**: 클라이언트가 요청을 보내고 서버가 *이벤트가 생길 때까지* 응답을 지연시키는 패턴 — RFC 6455 는 WebSocket 의 탄생 배경으로 "HTTP polling/long-polling 은 HTTP 의 남용(abuse)이며 서버가 클라이언트마다 여러 TCP 연결을 유지해야 했다"고 기술한다. (RFC 6455 §1.1)
|
||||
- **Spring MVC(servlet) 매핑**: `request.startAsync()` 로 Servlet/filter 는 exit 하고 response 만 열어 둠. 응답 타입별로 — `StreamingResponseBody`(message conversion 우회, `OutputStream` 직접 write, *파일 다운로드* 용), `ResponseBodyEmitter`(객체 stream emit, 각 객체를 `HttpMessageConverter` 로 직렬화), `SseEmitter`(`ResponseBodyEmitter` 의 subclass, W3C SSE 포맷). (Spring MVC vendor doc)
|
||||
|
||||
## 한계 / 주의점
|
||||
|
||||
- **"streaming" 이라는 단어가 두 개의 다른 것을 가리킨다**: ① *통신 모델 자체* 가 server-push 로 바뀌는 것(SSE/WebSocket) ② request-response 모델을 유지한 채 *응답 body 만 조각 전송* 하는 것(`StreamingResponseBody` / chunked 다운로드). 둘은 운영 부담·계약이 전혀 다르므로 묶어서 다루면 안 된다.
|
||||
- **SSE 는 단방향**: 서버→클라이언트만. 클라이언트→서버 메시지는 별도 일반 HTTP 요청으로. 양방향이 필요하면 WebSocket.
|
||||
- **WebSocket 은 기존 HTTP 인프라와 자동 호환되지 않는다**: HTTP 와 독립 프로토콜이라 reverse proxy(Nginx 등)에 Upgrade 처리 설정이 별도로 필요. envelope/필터/미들웨어 같은 기존 request-response 자산도 그대로 못 씀.
|
||||
- **server-push 는 운영 비용을 키운다**: connection 수 관리, 서버 재시작 시 동시 재연결(thundering herd), 멀티 서버 fan-out, timeout/heartbeat/reconnect, load balancer sticky session 등. 단발 request-response 에는 없던 부담.
|
||||
- **chunked 는 HTTP/1.1 전용**: HTTP/2·HTTP/3 에서 `Transfer-Encoding: chunked` 는 금지(별도 framing). 브라우저의 trailer section 지원도 일반화 보장 안 됨.
|
||||
- **YAGNI 경계**: 실제 server-push use case 가 없으면 스트리밍 도입은 speculative generality — request-response + 비동기 우회(LRO polling, webhook)로 대부분 충분.
|
||||
|
||||
## Project Application
|
||||
|
||||
- [[wiki/projects/ca-tmpl/streaming-response-support]] — ca-skeleton 이 이벤트/server-push 스트리밍을 *미지원으로 결정* 하고 ArchUnit import-ban 3개(`no_sse_emitter` / `no_response_body_emitter` / `no_websocket_handler`)로 강제. `StreamingResponseBody`(다운로드)는 차단 제외.
|
||||
|
||||
## Claim-backed Knowledge
|
||||
|
||||
> 이 개념 문서의 핵심 설명은 raw source claim 으로 뒷받침된다. 공식 standard / vendor doc / 회사 사례를 분리한다.
|
||||
|
||||
| Knowledge Point | Supporting Claims | Confidence | Notes |
|
||||
|---|---|---|---|
|
||||
| SSE 는 `text/event-stream`(UTF-8) line-based protocol, `data:/event:/id:/retry:` 필드 | `raw/official-docs/whatwg-html-server-sent-events.md#WHATWG-SSE-C1`, `#WHATWG-SSE-C2` | `high` | WHATWG HTML (official-standard) |
|
||||
| SSE 재연결은 `Last-Event-ID` 헤더로 마지막 event 전달, `retry:` 로 대기시간 설정 | `#WHATWG-SSE-C3`, `#WHATWG-SSE-C4` | `high` | 서버 활용은 구현 책임 (MAY 수준) |
|
||||
| `EventSource` 는 브라우저 클라이언트 API — 서버는 `text/event-stream` 을 직접 구현 | `#WHATWG-SSE-C5` | `high` | Spring 서버 측에 EventSource 직접 적용 불가 |
|
||||
| WebSocket 은 단일 TCP 위 full-duplex, 양 side 독립 송신 | `raw/official-docs/rfc6455-websocket.md#RFC6455-C1` | `high` | RFC 6455 (official-standard) |
|
||||
| WebSocket 은 HTTP Upgrade handshake(101) 이후 HTTP 와 독립 프로토콜 | `#RFC6455-C3`, `#RFC6455-C5` | `high` | reverse proxy 자동 호환 아님 — 별도 설정 필요 |
|
||||
| WebSocket 탄생 배경 = HTTP polling/long-polling 의 "HTTP 남용" + 클라이언트당 다중 TCP | `#RFC6455-C2` | `high` | "항상 polling 보다 우수" 는 아님 — 희소 업데이트엔 SSE/polling 적합 |
|
||||
| chunked = 크기 미상 stream 을 length-delimited buffer 로, HTTP/1.1 한정 | `raw/official-docs/rfc9112-http-1-1-chunked-transfer.md#RFC9112-CHUNK-C1` | `high` | HTTP/2 에선 `Transfer-Encoding` 금지 |
|
||||
| `SseEmitter` = `ResponseBodyEmitter` subclass, W3C SSE 포맷 / `StreamingResponseBody` = 파일 다운로드용 | `raw/official-docs/spring-mvc-async-streaming.md#SPRING-ASYNC-C4`, `#SPRING-ASYNC-C2`, `#SPRING-ASYNC-C3` | `high` | Spring vendor doc — server-push(SSE) vs 다운로드(StreamingResponseBody) 구분 |
|
||||
| SSE 멀티서버 운영 시 thundering herd(재시작 시 동시 재연결 CPU spike), 해결로 random jitter | `raw/company-tech-blogs/sse-realtime-notification-woowahan.md#WOOWA-SSE-C2`, `#WOOWA-SSE-C3` | `medium` | 우아한형제들 사례 (company-case-study) — 공식 best practice 아님, 규모별 심각도 다름 |
|
||||
|
||||
## 내가 설명할 수 있어야 하는 것
|
||||
|
||||
- SSE / WebSocket / long-polling / chunked 각각의 공식 정의와 통신 방향(단/양방향).
|
||||
- "streaming" 이 *통신 모델 변경(server-push)* 과 *응답 body 청크 전송(다운로드)* 두 개를 가리킨다는 점, 그리고 왜 둘을 구분해야 하는지.
|
||||
- WebSocket 이 왜 기존 HTTP 인프라(envelope, proxy)와 자동 호환되지 않는가.
|
||||
- 언제 스트리밍이 가치 있고(실시간 push, LLM token streaming), 언제 request-response + 비동기 우회(LRO polling, webhook)로 충분한가.
|
||||
- 우아한형제들 SSE/WebSocket 운영 부담 사례를 *일반 법칙처럼* 말하면 안 되는 지점.
|
||||
|
||||
## Interview Questions
|
||||
|
||||
- SSE 와 WebSocket 의 차이는? 어떤 상황에 각각을 고르나?
|
||||
- 서버가 클라이언트에 능동적으로 데이터를 보내야 할 때, 스트리밍 없이 해결하는 방법은? (LRO polling, webhook)
|
||||
- `StreamingResponseBody` 와 `SseEmitter` 는 둘 다 "스트리밍" 인데 무엇이 다른가?
|
||||
- WebSocket 을 도입하면 reverse proxy/load balancer 설정이 왜 달라지나?
|
||||
- 스트리밍을 *도입하지 않기로* 결정한다면, 그 결정을 코드 레벨에서 어떻게 강제할 수 있나?
|
||||
|
||||
## Do Not Overclaim
|
||||
|
||||
- **회사 기술 블로그(우아한형제들) 사례 = 공식 best practice 아님.** thundering herd / jitter / fan-out 은 *그 회사 규모·스택*(WebFlux + Coroutine + Kafka 등) 특화이며 일반 법칙으로 단정 금지.
|
||||
- **"WebSocket 이 polling 보다 항상 우월" → 금지.** RFC 6455 자체가 희소 업데이트엔 다른 선택이 적합할 수 있다고 시사.
|
||||
- **"SseEmitter 가 Last-Event-ID replay 를 자동 지원" → 금지.** 서버 측 event store 를 별도 구현해야 함 (vendor doc 주의).
|
||||
- **개념 문서는 구현 등급을 매기지 않는다.** 실제 구현/검증 여부는 [[wiki/projects/ca-tmpl/streaming-response-support]] 에서 판정.
|
||||
|
||||
## Sources
|
||||
|
||||
- [[raw/official-docs/whatwg-html-server-sent-events]] — WHATWG HTML SSE spec (`text/event-stream`, EventSource, Last-Event-ID, retry). official-standard.
|
||||
- [[raw/official-docs/rfc6455-websocket]] — IETF RFC 6455 WebSocket (full-duplex, HTTP Upgrade handshake, masking). official-standard.
|
||||
- [[raw/official-docs/rfc9112-http-1-1-chunked-transfer]] — HTTP/1.1 chunked transfer encoding (§7.1 framing). official-standard.
|
||||
- [[raw/official-docs/spring-mvc-async-streaming]] — Spring MVC `SseEmitter` / `ResponseBodyEmitter` / `StreamingResponseBody`. official-vendor-doc.
|
||||
- [[raw/company-tech-blogs/sse-realtime-notification-woowahan]] — 우아한형제들 SSE 운영 사례 (thundering herd, jitter, Kafka fan-out). company-case-study — 공식 best practice 아님.
|
||||
- [[raw/company-tech-blogs/realtime-service-experience-woowahan-websocket]] — 우아한형제들 WebSocket 운영 사례 (이벤트 유실, 모바일 네트워크, 클러스터링). company-case-study.
|
||||
@@ -1 +0,0 @@
|
||||
../../vault/30-knowledge/concepts/transaction-boundary-abstraction.md
|
||||
@@ -0,0 +1,172 @@
|
||||
---
|
||||
title: Transaction Boundary Abstraction (TransactionPort vs @Transactional)
|
||||
source_type: llm-generated
|
||||
status: draft
|
||||
confidence: medium
|
||||
tags: [transaction, clean-architecture, spring]
|
||||
related_projects: [ca-skeleton]
|
||||
last_reviewed: 2026-05-22
|
||||
---
|
||||
|
||||
# Transaction Boundary Abstraction (TransactionPort vs @Transactional)
|
||||
|
||||
> Layer: `wiki/concepts/` — 일반 개념. 특정 프로젝트의 적용 사실은 `wiki/projects/`로 분리.
|
||||
|
||||
## Summary
|
||||
|
||||
Transaction boundary abstraction은 application layer가 Spring transaction API(`@Transactional`, `PlatformTransactionManager`)를 직접 의존하지 않고, `TransactionPort` 또는 `TransactionalUseCaseRunner` 같은 port abstraction을 통해 트랜잭션 경계를 선언하는 패턴이다. Clean Architecture / Hexagonal에서 "application은 framework를 모른다"는 원칙을 트랜잭션 경계까지 일관되게 적용하기 위한 선택지 중 하나이며, 다수파인 `@Transactional` 직접 부착의 대안으로 testability와 framework lock-in 완화를 노린다.
|
||||
|
||||
## Standard (공식 정의)
|
||||
|
||||
Spring Framework는 트랜잭션 경계 선언을 위해 세 가지 표준 메커니즘을 제공한다.
|
||||
|
||||
- **`PlatformTransactionManager`**: 모든 트랜잭션 추상화의 SPI. JDBC, JPA, JTA 구현체가 존재.
|
||||
- **선언적 트랜잭션 (`@Transactional`)**: AOP proxy 기반. method/class 단위 attribute로 propagation, isolation, timeout, rollbackFor, readOnly 등을 선언.
|
||||
- **프로그래매틱 트랜잭션 (`TransactionTemplate`, `TransactionManager`)**: 명시적 코드로 트랜잭션 범위를 둘러쌈.
|
||||
|
||||
### Propagation 7종 (Spring `Propagation` enum)
|
||||
|
||||
| 값 | 의미 |
|
||||
| --- | --- |
|
||||
| `REQUIRED` (default) | 기존 트랜잭션 참여, 없으면 새로 생성 |
|
||||
| `SUPPORTS` | 있으면 참여, 없으면 non-transactional |
|
||||
| `MANDATORY` | 반드시 존재해야 함, 없으면 예외 |
|
||||
| `REQUIRES_NEW` | 항상 새 물리 트랜잭션 (기존은 suspend) |
|
||||
| `NOT_SUPPORTED` | non-transactional로 실행 (기존은 suspend) |
|
||||
| `NEVER` | 트랜잭션 존재 시 예외 |
|
||||
| `NESTED` | savepoint 기반 nested 트랜잭션 (JDBC 한정, JPA는 일반적으로 미지원) |
|
||||
|
||||
### Isolation 5종 (Spring `Isolation` enum)
|
||||
|
||||
`DEFAULT`, `READ_UNCOMMITTED`, `READ_COMMITTED`, `REPEATABLE_READ`, `SERIALIZABLE`. PostgreSQL은 `READ_COMMITTED`가 default, MySQL InnoDB는 `REPEATABLE_READ`가 default라서 vendor default 묵시 사용은 의미 차이를 만든다.
|
||||
|
||||
출처: [[raw/official-docs/at-transactional-spring-official]], [[raw/official-docs/transaction-template-spring-official]].
|
||||
|
||||
## 한계 / 주의점
|
||||
|
||||
트랜잭션 경계를 어떻게 선언할지에 대한 5가지 대안과 그 한계.
|
||||
|
||||
### 대안 1: `@Transactional` direct (다수파)
|
||||
|
||||
- **장점**: boilerplate 최저, Spring/Hexagonal 표준 다수파, IDE 가시성 좋음.
|
||||
- **한계**:
|
||||
- **AOP self-invocation 문제**: 같은 클래스 내부 메서드 호출은 proxy를 거치지 않아 `@Transactional`이 무시됨. self-injection이나 별도 bean 분리 같은 우회가 필요.
|
||||
- **Testability 낮음**: application use case 단위 테스트에서 트랜잭션 경계를 검증하려면 Spring context 또는 `@DataJpaTest` 등 통합 환경이 필요.
|
||||
- **Framework lock-in**: application package가 `org.springframework.transaction.annotation.Transactional`을 직접 import → Clean Architecture 의존성 규칙 위반 (application은 framework를 모른다).
|
||||
- **선언과 실행 분리**: annotation은 attribute 선언일 뿐 실제 실행은 proxy/interceptor가 담당. 디버깅 시 호출 경로 추적이 간접적.
|
||||
- 출처: [[raw/official-docs/at-transactional-spring-official]], [[raw/company-tech-blogs/hexagonal-reflectoring-transactional-placement]].
|
||||
|
||||
### 대안 2: `TransactionTemplate` programmatic
|
||||
|
||||
- **장점**: 명시적 코드, self-invocation 문제 없음, propagation/isolation을 객체로 다룸.
|
||||
- **한계**:
|
||||
- Boilerplate 증가 — 매 use case마다 `template.execute(status -> { ... })` 작성.
|
||||
- 여전히 `org.springframework.transaction.support.TransactionTemplate`를 application이 직접 import → framework lock-in은 그대로.
|
||||
- 출처: [[raw/official-docs/transaction-template-spring-official]].
|
||||
|
||||
### 대안 3: Functional Resource monad (예: Arrow Kt `Resource`, `transaction { }`)
|
||||
|
||||
- **장점**: testability 최고 (순수 함수 합성으로 검증 가능), 명시적 effect, type-level 보장.
|
||||
- **한계**:
|
||||
- 팀 학습 비용 큼 — Kotlin/함수형 코드 스타일에 익숙하지 않은 팀에선 채택 장벽이 높다.
|
||||
- Java 위주 Spring 팀에선 패턴 매칭 / monad 사용이 자연스럽지 않음.
|
||||
- Spring의 propagation/isolation 기본 의미를 monad 위에 재구현해야 하는 경우 있음.
|
||||
- 출처: [[raw/official-docs/functional-tx-arrow-kt-resource-docs]].
|
||||
|
||||
### 대안 4: Custom `TransactionInterceptor` (AOP)
|
||||
|
||||
- **장점**: 자체 annotation 정의 가능, 커스텀 정책 주입(예: capability 검증과 결합) 가능.
|
||||
- **한계**:
|
||||
- AOP 자체의 self-invocation 문제 동일하게 잔존.
|
||||
- interceptor 구현 자체가 Spring AOP 의존을 가짐.
|
||||
- 표준 `@Transactional` 도구(`@TransactionalEventListener` 등) 호환성 추가 검증 필요.
|
||||
- 출처: [[raw/company-tech-blogs/custom-transaction-interceptor-catnipcoder]].
|
||||
|
||||
### 대안 5: TransactionPort / TransactionalUseCaseRunner abstraction (소수파)
|
||||
|
||||
- **장점**:
|
||||
- Application package가 Spring transaction import 없이 트랜잭션 경계를 선언.
|
||||
- Test에서는 in-memory fake port로 트랜잭션 경계 검증 가능 → use case 단위 테스트가 Spring context 없이 성립.
|
||||
- Framework 교체(예: Spring → Micronaut) 시 application 코드 변경 최소화.
|
||||
- **한계**:
|
||||
- 소수파 — 일반적 hexagonal 사례에서도 `@Transactional`을 application service에 부착하는 경우가 다수.
|
||||
- Port interface 추가, infrastructure 구현체 추가, propagation/isolation을 port 시그니처로 어떻게 표현할지 결정 비용.
|
||||
- Spring 도구(`@TransactionalEventListener`, JPA OSIV, AOP 기반 audit 등)와의 호환을 직접 챙겨야 함.
|
||||
- 단순 CRUD 위주 프로젝트에서는 over-engineering이 될 수 있음.
|
||||
- 출처: [[raw/company-tech-blogs/transaction-port-clean-ddd-spring-medium]], [[raw/company-tech-blogs/transaction-port-vassilis-soum-github-readme]].
|
||||
|
||||
### 공통 주의점
|
||||
|
||||
- **묵시적 vendor default isolation**: `Isolation.DEFAULT`로 두면 PostgreSQL은 `READ_COMMITTED`, MySQL InnoDB는 `REPEATABLE_READ`로 달라진다. multi-vendor 환경에서는 명시 선언이 안전.
|
||||
- **`NESTED`는 JDBC savepoint 기반**: JPA EntityManager는 일반적으로 nested 트랜잭션을 지원하지 않음 (provider 의존).
|
||||
- **`REQUIRES_NEW`는 비싸다**: 기존 트랜잭션을 suspend하고 새 connection을 잡는 비용이 있음. outbox/audit 같은 명시적 케이스에만 사용.
|
||||
|
||||
## Claim-backed Knowledge
|
||||
|
||||
> 이 표는 일반 개념 지식이 어떤 raw 근거로 뒷받침되는지 명시한다. 프로젝트 구현 주장은 여기에 넣지 않는다 (project 문서 참조).
|
||||
|
||||
| Knowledge Point | Supporting Claims | Confidence | Notes |
|
||||
|---|---|---|---|
|
||||
| Spring 은 트랜잭션 경계 선언에 declarative(`@Transactional`) / programmatic(`TransactionTemplate`) / SPI(`PlatformTransactionManager`) 메커니즘을 제공 | [[raw/official-docs/at-transactional-spring-official]], [[raw/official-docs/transaction-template-spring-official]] | high | `official-vendor-doc` (Spring 공식) |
|
||||
| `@Transactional` 은 AOP proxy 기반이라 self-invocation 시 무시될 수 있음 | [[raw/official-docs/at-transactional-spring-official]]#AT-TX-C5 | high | 표준 우회(self-injection 등) 존재 — 치명적 결함 아님 |
|
||||
| Propagation 기본값은 `REQUIRED`, `readOnly` 는 REQUIRED/REQUIRES_NEW 한정 적용 | [[raw/official-docs/spring-tx-management-reference]]#SPRING-TX-MGR-C3, #SPRING-TX-MGR-C6 | high | `official-vendor-doc` |
|
||||
| `REQUIRES_NEW` 는 독립 physical transaction + 새 connection → pool 소모, exhaustion/deadlock 위험 | [[raw/official-docs/spring-tx-propagation-required-new-nested-official]]#SPRING-PROP-C1~C4 | high | `official-vendor-doc` |
|
||||
| closure-based transaction abstraction 은 enterprise OSS 선례 존재(Axon `executeInTransaction`/`fetchInTransaction`) | [[raw/company-tech-blogs/axonframework-transactionmanager-spring-adapter]]#AXON-TX-C1~C3 | medium | `company-case-study` — 공식 best practice 아님 |
|
||||
| 다수파 hexagonal 사례는 오히려 application service 에 `@Transactional` 직접 부착(abstraction 없음) | [[raw/company-tech-blogs/buckpal-archunit-lombok-allowlist-direct-transactional]]#BUCKPAL-TX-C1~C2, [[raw/company-tech-blogs/hexagonal-reflectoring-transactional-placement]]#HEX-REFL-C1 | medium | `engineering-blog`/`company-case-study` — TransactionPort 가 소수파임을 보여주는 contrary evidence |
|
||||
| Spring 공식 incubator(Modulith)는 `@ApplicationModuleListener` 로 `@Transactional(REQUIRES_NEW)` 를 meta-annotation 재노출 | [[raw/company-tech-blogs/spring-modulith-archunit-generated-exemption-and-violations-as-data]]#SPRING-MOD-TX-C1 | medium | abstraction-only forbidden 정책과 반대 방향 |
|
||||
|
||||
## Project Application
|
||||
|
||||
- [[wiki/projects/ca-tmpl/transaction-boundary-abstraction]] — ca-tmpl 의사결정 + 구현 기록 (`TransactionPort` + `SpringTransactionPort` + ArchUnit 강제, 로컬 검증까지 완료). 실제 구현·검증 범위는 project 문서 참조 — 이 개념 문서에는 프로젝트 구현 주장을 넣지 않는다.
|
||||
|
||||
- [[raw/project-notes/ca-skeleton-operational-contract]] (§14 Transaction/Concurrency, §19 Domain Application Readiness, §29 Topic 2)
|
||||
- [[raw/branch-notes/feature-application-port-usecase-contract]] — TransactionPort interface spec, forbidden import 규칙
|
||||
- [[raw/branch-notes/feature-transaction-concurrency-contract]] — isolation default, propagation default, idempotency / lock 분류
|
||||
|
||||
## 내가 설명할 수 있어야 하는 것
|
||||
|
||||
- transaction boundary abstraction 의 공식 정의 — Spring 의 declarative / programmatic / SPI 메커니즘과의 관계.
|
||||
- 어떤 문제를 해결하는가 — application 패키지의 framework lock-in 차단 + use case 단위 테스트의 Spring context 분리(testability).
|
||||
- 어떤 상황에서는 쓰면 안 되는가 — 단순 CRUD 위주 + framework 교체 계획 없음 + Spring 숙련 팀이면 `@Transactional` 직접 부착이 합리적. abstraction 은 over-engineering 이 될 수 있다.
|
||||
- 공식 문서가 말하지 않는 부분 — Spring 공식은 `@Transactional`/`TransactionTemplate` 을 권장하지 abstraction port 를 권장하지 않는다. port 화는 자체 taste.
|
||||
- 회사 기술 블로그 사례를 일반 법칙처럼 말하면 안 되는 지점 — UNIL / Axon / Buckpal / Modulith 는 case-study/engineering-blog 등급. 특히 Buckpal·Modulith 는 오히려 `@Transactional` 직접/meta 부착이라 abstraction-only 가 다수파라고 말하면 안 된다.
|
||||
- 내 프로젝트에서는 어떤 branch decision 으로 연결됐는가 — [[raw/branch-notes/feature-application-port-usecase-contract]] D3(TransactionPort 채택) / D11(callback 시그니처) / D12(`inNew` pool 비용). 구현 사실은 [[wiki/projects/ca-tmpl/transaction-boundary-abstraction]].
|
||||
- 코드/운영에서 검증하려면 — ArchUnit 으로 application 패키지의 `@Transactional` import 차단을 확인, `readOnly` flush-mode 는 Hibernate session statistics 로 측정, `REQUIRES_NEW` 는 connection pool 사용량을 통합 테스트로 확인.
|
||||
|
||||
## Interview Questions
|
||||
|
||||
- 왜 application layer에서 Spring `@Transactional` 직접 import를 금지할 수 있는가? 어떤 trade-off가 있는가?
|
||||
- AOP self-invocation 문제는 무엇이고, TransactionPort abstraction은 이 문제를 어떻게 회피하는가?
|
||||
- `REQUIRES_NEW`와 `NESTED`의 차이는 무엇이며, 왜 `NESTED`는 JPA에서 일반적으로 권장되지 않는가?
|
||||
- Isolation level 4단계(READ_UNCOMMITTED, READ_COMMITTED, REPEATABLE_READ, SERIALIZABLE)와 phantom read / non-repeatable read / dirty read의 관계를 설명할 수 있는가?
|
||||
- TransactionPort 도입의 trade-off를 단순 CRUD 프로젝트와 도메인 복잡도가 큰 프로젝트로 나눠 어떻게 다르게 평가하는가?
|
||||
|
||||
## Do Not Overclaim
|
||||
|
||||
- **"TransactionPort가 무조건 우월하다"고 말하지 않는다.** 단순 CRUD가 대부분이고 framework 교체 계획이 없으며 팀이 Spring에 익숙하다면, `@Transactional` 직접 부착이 boilerplate / 가시성 / 표준 도구 호환성 측면에서 합리적인 선택이다. Hexagonal/Clean Architecture 사례 다수도 application service에 `@Transactional`을 부착한다.
|
||||
- **UNIL 팀 사례를 "ca-tmpl이 영감을 받았다"고 단정하지 않는다.** [[raw/company-tech-blogs/transaction-port-clean-ddd-spring-medium]](UNIL, 2024-05)와 ca-tmpl은 동일한 evolution path(@Transactional → AOP → TransactionPort)를 거친 별개 사례로 다루며, 인용은 "동일한 결론에 도달한 외부 사례" 수준에서만 한다.
|
||||
- **"AOP 기반 transaction은 항상 self-invocation 문제 때문에 깨진다"고 말하지 않는다.** self-injection, public method 분리, 별도 bean 분리 같은 표준 우회가 존재하며, 다수 프로덕션에서 잘 동작한다. self-invocation은 "주의해야 할 함정"이지 "치명적 결함"이 아니다.
|
||||
- **"Functional monad가 testability에서 항상 우월하다"고 말하지 않는다.** test 친화성은 높지만 팀 역량 / 언어 / 기존 코드베이스에 따라 실제 도입 비용이 매우 크다.
|
||||
- 본 문서의 5종 비교는 **외부 source를 기반으로 정리한 trade-off 표**이며, 모든 항목이 자체 측정 결과는 아니다. status `draft` / confidence `medium`로 둔다.
|
||||
|
||||
## Sources
|
||||
|
||||
### 공식 문서
|
||||
|
||||
- [[raw/official-docs/at-transactional-spring-official]] — Spring `@Transactional` 선언적 트랜잭션 공식 정의
|
||||
- [[raw/official-docs/transaction-template-spring-official]] — Spring `TransactionTemplate` 프로그래매틱 API
|
||||
- [[raw/official-docs/functional-tx-arrow-kt-resource-docs]] — Arrow Kt Resource / Functional transaction
|
||||
|
||||
### 사례 / 블로그 (공식 best practice 아님)
|
||||
|
||||
- [[raw/company-tech-blogs/transaction-port-clean-ddd-spring-medium]] — UNIL (2024-05), 동일 진화 경로 사례
|
||||
- [[raw/company-tech-blogs/transaction-port-vassilis-soum-github-readme]] — TransactionPort 참고 구현
|
||||
- [[raw/company-tech-blogs/hexagonal-reflectoring-transactional-placement]] — Hexagonal에서 `@Transactional` 부착 위치 (다수파)
|
||||
- [[raw/company-tech-blogs/custom-transaction-interceptor-catnipcoder]] — Custom TransactionInterceptor (AOP) 사례
|
||||
- [[raw/company-tech-blogs/woowahan-hexagonal-multimodule]] — 보완(대체 아님): hexagonal multi-module 분리
|
||||
|
||||
### 프로젝트 canonical / branch-notes
|
||||
|
||||
- [[raw/project-notes/ca-skeleton-operational-contract]] — §14, §19, §29
|
||||
- [[raw/branch-notes/feature-application-port-usecase-contract]]
|
||||
- [[raw/branch-notes/feature-transaction-concurrency-contract]]
|
||||
@@ -1 +0,0 @@
|
||||
../../vault/30-knowledge/concepts/transactional-outbox-pattern.md
|
||||
@@ -0,0 +1,112 @@
|
||||
---
|
||||
title: Transactional Outbox Pattern (SKIP LOCKED polling vs CDC)
|
||||
source_type: llm-generated
|
||||
status: draft
|
||||
confidence: medium
|
||||
tags: [outbox, event-driven, distributed-systems]
|
||||
related_projects: [ca-skeleton]
|
||||
last_reviewed: 2026-05-22
|
||||
---
|
||||
|
||||
# Transactional Outbox Pattern (SKIP LOCKED polling vs CDC)
|
||||
|
||||
> Layer: `wiki/concepts/` — 일반 개념. 프로젝트 적용 사실은 [[raw/project-notes/ca-skeleton-operational-contract]] 등 project 문서 참조.
|
||||
|
||||
## Summary
|
||||
|
||||
Transactional outbox는 "DB write + 외부 메시지 publish"라는 두 시스템에 걸친 원자성 요구를 **단일 RDB 트랜잭션 + 비동기 publisher**로 우회하는 패턴입니다. 도메인 변경과 같은 트랜잭션에서 `outbox` 테이블에 이벤트 row를 INSERT하고, 별도 publisher가 그 row를 polling(또는 CDC)으로 읽어 broker에 발행함으로써 dual-write 문제(두 시스템 중 하나만 성공)를 제거합니다. polling 구현체에서는 PostgreSQL/MySQL의 `FOR UPDATE SKIP LOCKED`로 다중 publisher 간 row 경합을 해소합니다.
|
||||
|
||||
## Standard (공식 정의)
|
||||
|
||||
- **microservices.io / Chris Richardson**: outbox 패턴의 원형 정의. 서비스가 DB 트랜잭션 내에 `OUTBOX` 테이블에 이벤트를 기록하고, 별도 message relay가 이 테이블을 읽어 broker로 publish. dual-write를 명시적 anti-pattern으로 두고 outbox/event sourcing을 두 정식 대안으로 제시.
|
||||
- **PostgreSQL `FOR UPDATE SKIP LOCKED`**: 9.5+. `SELECT ... FOR UPDATE` 대상 row 중 다른 트랜잭션이 이미 잠근 row를 **차단 없이 skip**. queue 형태의 워크로드(outbox claim, job queue)에 사용 권장. 잠금은 row 단위, 트랜잭션 종료 시 해제.
|
||||
- **MySQL 8.0+ `SKIP LOCKED`**: PostgreSQL과 동일한 의미. 8.0 이전 버전은 미지원 — advisory lock으로 fallback.
|
||||
- **Debezium**: 오픈소스 CDC 플랫폼. DB write-ahead log(Postgres logical replication / MySQL binlog)을 읽어 변경 이벤트를 Kafka 등 broker로 전달. outbox 테이블도 다른 테이블과 동일하게 WAL/binlog로 캡처.
|
||||
- **Kafka Connect Outbox Event Router (Debezium SMT)**: Debezium이 캡처한 outbox row를 Single Message Transform 단계에서 Kafka topic/key/headers로 라우팅. outbox row schema 규약(`aggregatetype`, `aggregateid`, `type`, `payload`)을 요구.
|
||||
- **delivery semantic**: outbox + 비동기 publish는 **at-least-once**가 기본이며 exactly-once가 아님. consumer 측에서 `eventId` 또는 `idempotencyKey` 기반 dedupe가 필수.
|
||||
|
||||
## 한계 / 주의점
|
||||
|
||||
각 구현 옵션별 trade-off.
|
||||
|
||||
### SKIP LOCKED polling
|
||||
|
||||
- publish lag = polling interval + claim transaction + broker publish. 일반적으로 **수 초~수 분** 수준이며 sub-second lag 요구에는 부적합.
|
||||
- outbox 테이블이 단조 증가 → archived/published row cleanup 정책 필수 (TTL 삭제 또는 partition rotation). 누락 시 인덱스 비대 및 vacuum 비용 증가.
|
||||
- 단일 DB가 SSOT여야 함. 멀티 DB에 도메인 write가 분산되면 outbox 1개로 해소 불가.
|
||||
- multi-instance publisher 운영 시 동일 row 중복 claim 방지는 SKIP LOCKED 자체가 보장하지만, publish 후 commit 실패 시 재시도로 인한 중복 publish 가능 → consumer dedupe가 정합성의 일부.
|
||||
|
||||
### Debezium CDC
|
||||
|
||||
- WAL/binlog 기반이므로 publish lag이 polling보다 짧음(밀리초~초 단위).
|
||||
- 단, Kafka Connect 클러스터, connector 설정/스키마, replica slot 관리, snapshot 운영 인력이 추가로 필요. **인프라 비용·운영 학습 비용이 폴링 대비 크게 큼**.
|
||||
- Postgres에서는 logical replication slot이 누적되면 WAL 디스크가 증가하는 운영 risk가 있음(slot lag 모니터링 필수).
|
||||
- 마이그레이션 트리거는 보통 "polling lag SLO 위반" 또는 "DB load가 polling 쿼리로 포화"이며, 그 가정이 깨지지 않으면 도입 정당화 어려움.
|
||||
|
||||
### Kafka Connect Outbox SMT (Debezium event router)
|
||||
|
||||
- payload 변환·라우팅 로직이 connector 설정 + SMT 규약에 묶임. 복잡한 payload 가공이나 multi-topic fan-out은 SMT 표현력의 한계가 있음.
|
||||
- outbox row schema가 Debezium event router 규약에 종속 → 자유로운 컬럼 설계가 어려움.
|
||||
|
||||
### Dual-write (anti-pattern, negative reference)
|
||||
|
||||
- 애플리케이션 코드에서 DB commit과 broker publish를 **순차로 직접 호출**하는 형태. 둘 사이에 프로세스 종료/장애가 끼면 정합성이 깨짐.
|
||||
- outbox 도입의 근거 그 자체이므로, "왜 outbox인가"의 답은 항상 dual-write 실패 시나리오에서 출발.
|
||||
- 외부 publish 없이 in-process consumer만 있는 경우라면 트랜잭션 commit 후 in-process dispatch도 허용 가능 — 하지만 외부 transport가 끼는 순간 outbox가 기본값.
|
||||
|
||||
### Event sourcing
|
||||
|
||||
- 흔히 "outbox 대안"으로 묶이지만 실제로는 **도메인 모델 자체를 이벤트 스트림으로 교체**하는 결정이며, 단순 publish 정합성 문제 해결이 아님.
|
||||
- 도메인 재설계, 스냅샷·재구성 운영, 쿼리 모델(CQRS) 분리 비용 동반. 단지 "이벤트 발행이 필요해서" event sourcing으로 가는 것은 trade-off 오판.
|
||||
|
||||
### Spring `@TransactionalEventListener`
|
||||
|
||||
- `AFTER_COMMIT` phase에서 in-process bean으로 이벤트 dispatch. **JVM 프로세스 내부에서만 동작**.
|
||||
- commit 직후 publish 실패(예: 외부 broker 호출 예외, 프로세스 강제 종료)에 대한 영속 큐가 없음 → **재시작 시 유실**. 외부 broker로 가는 integration event 발행에는 부적합.
|
||||
- 도메인 이벤트의 in-process side effect 트리거 용도로만 안전.
|
||||
|
||||
### Netflix DBLog 류 자체 CDC
|
||||
|
||||
- Debezium보다 더 큰 자체 인프라 투자. 일반 백엔드 팀이 도입할 baseline 아님. 비교 시 "왜 Debezium도 부담이라 polling을 골랐는가"의 대조군으로만 사용.
|
||||
|
||||
## Project Application
|
||||
|
||||
- [[wiki/projects/ca-tmpl/transactional-outbox-pattern]] — ca-tmpl 의사결정 기록 (현재 `documented-only`, Phase C2 미진입). 실제 구현 여부는 project 문서 참조.
|
||||
- [[raw/branch-notes/feature-domain-event-outbox-contract]] — outbox publisher SSOT, row status(`PENDING/IN_FLIGHT/PUBLISHED/FAILED/DEAD`), per-aggregate FIFO, claim transaction(`READ_COMMITTED` + `FOR UPDATE SKIP LOCKED`), at-least-once + consumer dedupe 결정.
|
||||
- [[raw/branch-notes/feature-background-job-async-contract]] — outbox publisher가 consume하는 retry/DLQ vocabulary(exp backoff with jitter, max 3, DLQ exhausted) SSOT.
|
||||
- [[raw/project-notes/ca-skeleton-operational-contract]] (§11 Adapter Failure, §14 Transaction/Concurrency, §29 Topic 3) — outbox 패턴이 어떤 운영 계약 안에서 어떤 위치를 차지하는지의 canonical map.
|
||||
|
||||
## Interview Questions
|
||||
|
||||
- 왜 dual-write는 안 되는가? outbox는 dual-write의 어떤 실패 모드를 어떻게 제거하는가?
|
||||
- SKIP LOCKED polling은 publish lag과 어떤 trade-off를 가지는가? lag을 줄이려면 polling interval만 줄이면 되는가?
|
||||
- Debezium CDC로 마이그레이션을 결정하는 트리거는 무엇인가? (어떤 가정이 깨졌을 때?)
|
||||
- outbox 테이블 cleanup(archived row 삭제/파티셔닝)을 누락하면 어떤 문제가 생기는가?
|
||||
- outbox가 exactly-once를 보장하지 않는 이유와, 그 위에서 consumer가 정합성을 유지하는 메커니즘(idempotency key)을 설명할 수 있는가?
|
||||
|
||||
## Do Not Overclaim
|
||||
|
||||
- "outbox = exactly-once delivery"라고 말하지 않기. 정확한 표현은 **at-least-once delivery + idempotent consumer**.
|
||||
- "Debezium을 곧 도입할 것"이라고 말하지 않기. CDC migration은 polling lag SLO나 DB 부하 가정이 깨질 때만 정당화되며, 현 시점에는 가정이 유지된다고만 말할 것.
|
||||
- "outbox만 있으면 정합성이 보장된다"고 말하지 않기. publisher 측의 retry/DLQ, consumer 측의 dedupe, outbox row cleanup 정책이 함께 있어야 운영 가능.
|
||||
- "SKIP LOCKED가 race condition을 다 막아준다"고 말하지 않기. SKIP LOCKED는 **claim 단계의 row 경합**만 해소하며, publish 후 commit 실패로 인한 재발행은 별개의 문제.
|
||||
- "event sourcing이 outbox의 상위 호환이다"라고 말하지 않기. 둘은 해결하려는 문제의 층위가 다름(전달 정합성 vs 도메인 모델링).
|
||||
- 본인이 polling publisher를 운영해 본 측정값이 없다면 lag 수치를 단정적으로 말하지 않기.
|
||||
|
||||
## Sources
|
||||
|
||||
- [Pattern: Transactional outbox (microservices.io)](https://microservices.io/patterns/data/transactional-outbox.html) — outbox 원형 정의 / Chris Richardson
|
||||
- [PostgreSQL: SELECT — The Locking Clause](https://www.postgresql.org/docs/current/sql-select.html#SQL-FOR-UPDATE-SHARE) — `FOR UPDATE SKIP LOCKED` 의미론
|
||||
- [Debezium documentation — Outbox Event Router](https://debezium.io/documentation/reference/stable/transformations/outbox-event-router.html) — Kafka Connect SMT
|
||||
- [Spring Framework — `@TransactionalEventListener`](https://docs.spring.io/spring-framework/reference/data-access/transaction/event.html) — in-process only 한계
|
||||
- [[raw/official-docs/outbox-skip-locked-microservices-io]] — outbox 원형 raw 발췌
|
||||
- [[raw/official-docs/skip-locked-postgres-docs]] — Postgres SKIP LOCKED 원리
|
||||
- [[raw/official-docs/outbox-debezium-official-docs]] — Debezium 공식 문서
|
||||
- [[raw/official-docs/spring-transactional-event-listener]] — Spring 공식 문서
|
||||
- [[raw/official-docs/event-sourcing-vs-outbox-microservices-io]] — outbox vs event sourcing
|
||||
- [[raw/official-docs/dual-write-antipattern-microservices-io]] — dual-write negative reference
|
||||
- [[raw/company-tech-blogs/outbox-woowahan-techblog-pattern]] — 우아한형제들 polling 사례
|
||||
- [[raw/company-tech-blogs/outbox-wix-engineering-debezium]] — Wix Debezium migration 사례
|
||||
- [[raw/company-tech-blogs/outbox-confluent-kafka-connect-smt]] — Confluent Kafka Connect outbox SMT
|
||||
- [[raw/company-tech-blogs/outbox-netflix-domain-events-cdc]] — Netflix DBLog 자체 CDC
|
||||
- [[raw/project-notes/ca-skeleton-operational-contract]] — §11 / §14 / §29 Topic 3 canonical map
|
||||
@@ -1 +0,0 @@
|
||||
../../vault/30-knowledge/explainer/adapter-identifier.md
|
||||
@@ -0,0 +1,18 @@
|
||||
---
|
||||
title: (강사 설명) adapter-identifier 모듈
|
||||
source_type: explainer
|
||||
status: raw
|
||||
confidence: unknown
|
||||
tags: [explainer, ca-tmpl, resource-identifier]
|
||||
related_projects: [ca-tmpl]
|
||||
last_reviewed:
|
||||
---
|
||||
|
||||
# (강사 설명) adapter-identifier 모듈
|
||||
|
||||
> Layer: `wiki/explainer/` — **derived(파생) 교육 문서.** 개인 이해용이며 외부 공개 대상이 아니다.
|
||||
> 사실·근거·검증 등급은 여기서 만들지 않고 canonical 에서 가져온다.
|
||||
|
||||
**아직 작성되지 않은 스텁입니다.** `[[wiki/explainer/adapter-outbound]]` 와 같은 ca-tmpl 모듈별
|
||||
설명 시리즈의 자리만 잡아둔 상태이며, 본문은 canonical(`[[wiki/projects/ca-tmpl/resource-identifier-format]]`)을
|
||||
경유해 작성해야 합니다.
|
||||
@@ -1 +0,0 @@
|
||||
../../vault/30-knowledge/explainer/adapter-outbound.md
|
||||
@@ -0,0 +1,923 @@
|
||||
---
|
||||
title: (강사 설명) adapter-outbound 모듈의 아웃바운드 연동 및 리질리언스 설계 구조
|
||||
source_type: explainer
|
||||
status: reviewed
|
||||
confidence: high
|
||||
tags: [explainer, ca-tmpl, architecture, spring-boot, integration]
|
||||
related_projects: [ca-tmpl]
|
||||
last_reviewed: 2026-06-15
|
||||
---
|
||||
|
||||
# (강사 설명) adapter-outbound — Outbound HTTP 클라이언트 완전 정복
|
||||
|
||||
> Layer: `wiki/explainer/` — **derived(파생) 교육 문서.** "나의 진짜 이해" 를 위한 1타강사 칠판이다.
|
||||
> 정확한 사실·근거·검증 등급은 여기서 만들지 않는다. 전부 canonical 에서 가져온다:
|
||||
> - 개념·대안·근거: [[wiki/concepts/fail-open-fail-closed.md]], [[wiki/concepts/idempotency.md]], [[wiki/concepts/circuit-breaker.md]], [[wiki/concepts/outbox-pattern.md]], [[wiki/concepts/distributed-tracing-baggage.md]], [[wiki/concepts/spring-smart-lifecycle.md]]
|
||||
> - 내 프로젝트 실제 구현·검증 범위: [[wiki/projects/ca-tmpl/data-layer-persistence-cache-outbound.md]] (§Outbound HTTP Client — 코드 사실 SSOT, `locally-verified`), [[wiki/projects/ca-tmpl/config-and-adapter-templates.md]] (adapter on/off 게이팅)
|
||||
>
|
||||
> 이 문서의 **비유는 의도적으로 부정확**하다 (이해를 위한 단순화). 비유를 사실로 인용하지 마라. 면접에서 말할 땐 canonical 의 표현을 써라.
|
||||
>
|
||||
> 📁 코드 경로 기준(본문 캡션은 파일명만 표기): `ca-tmpl/src/adapter-outbound/src/main/java/dev/caskeleton/adapter/outbound/httpclient/`
|
||||
> 📌 본문의 `D5`·`D8`·`I5`·`B7` 같은 코드는 ca-tmpl 의 **설계 결정/규칙 번호**다. 흐름 이해엔 무시해도 된다(추적용 꼬리표).
|
||||
|
||||
---
|
||||
|
||||
## §0. 학습 계약 — 시작 전에 꼭 읽기
|
||||
|
||||
🟢 **[신입 필수]** — 이 섹션은 먼저 읽는다.
|
||||
|
||||
이 수업은 **하나의 클래스(`OutboundHttpClient`)가 외부 API 호출의 위험을 어떻게 가두는가**를 *코드 레벨*로 가르친다. 다 읽으면 면접에서 이 주제로 "깊이 있게" 답할 수 있는 게 목표다.
|
||||
|
||||
### 이 수업을 마치면 — 수료 역량 (이 질문들에 이 깊이로 답하게 된다)
|
||||
|
||||
| # | 질문 | 답에 *반드시* 들어가야 할 키워드 |
|
||||
|---|---|---|
|
||||
| E1 | 외부 API 를 그냥 `RestClient` 한 줄로 부르면 뭐가 문제인가? | 타임아웃 부재→스레드 고갈 / 무지성 재시도→이중결제 / 무한버퍼→OOM / 종료 중 호출 (4개 중 3개 + 인과) |
|
||||
| E2 | POST 는 왜 재시도 안 하나? | 비멱등 → 중복 부작용. RFC 9110 멱등 메서드(GET/HEAD/PUT/DELETE)만. Idempotency-Key 미보장 |
|
||||
| E3 | 서킷 브레이커 상태와 전이를 설명하라 | CLOSED/OPEN/HALF_OPEN + 각 전이 트리거 + 설정값(임계 50%·대기 60s·시험 10건) |
|
||||
| E4 | "서킷 쓰면 가용성 올라가?" (함정) | **틀림** → OPEN 동안 정상 요청도 거부(가용성 일시 0). 목적 = 내 스레드·업스트림 보호 |
|
||||
| E5 | 외부가 5xx + 본문에 토큰을 줬다. 클라이언트는 뭘 받나? | `{"error":{"code":"DEPENDENCY_5XX_SERVER"}}`만. 진단메시지=status+클래스명, body 비유출(2중 방어) |
|
||||
| E6 | CB 와 Retry 의 감싸는 순서가 왜 중요한가? | CB 바깥 → 재시도 전체가 CB 에 **1건**으로 집계(트레이드오프 설명) |
|
||||
| E7 | 100MB 응답은 어떻게 받나? | `exchange()`(buffered, 10MB 초과 예외) 대신 `stream()`(raw stream, 재시도 없음 — 스트림은 되감기 불가) |
|
||||
| E8 | 배포 종료 중 새 호출이 오면? | `SmartLifecycle` phase=MAX_VALUE → 가드가 먼저 stop → 플래그 → `exchange()` Step1 fail-fast |
|
||||
|
||||
### 시작 전 알아야 할 것 — 선행 지식 (self-check 통과하면 OK)
|
||||
|
||||
| 알아야 할 것 | self-check (한 줄로 답되면 통과) | 모르면 |
|
||||
|---|---|---|
|
||||
| HTTP 메서드·상태코드 | "GET·POST 의 부작용 차이? 404 와 503 중 '내 잘못'은?" | MDN HTTP |
|
||||
| 스레드 / 스레드 풀 | "요청 1개가 스레드 1개를 점유한다는 게 무슨 뜻?" | (§1 #1 에서 직관 보충) |
|
||||
| 자바 제네릭 `<T>` / `Class<T>` | "`get(uri, User.class)` 가 어떻게 `User` 를 돌려주나?" | Oracle Generics |
|
||||
| 자바 람다 / `Supplier<T>` | "`() -> x` 는 *언제* 실행되나(즉시? 나중?)" | Oracle Lambda |
|
||||
| 예외 / cause chain | "`new RuntimeException(e)` 에서 `e` 는 어디로?" | Throwable.getCause() |
|
||||
| Spring Bean / `@Bean` / DI | "'빈을 등록한다'가 무슨 뜻?" | Spring IoC Container |
|
||||
|
||||
> 람다·제네릭이 약하면 §5 의 "코드 읽기 전 5단어" 박스를 먼저 봐라.
|
||||
|
||||
### 난이도 레인 & 최소 완주 경로
|
||||
|
||||
각 섹션 제목에 라벨이 있다: **[신입 필수]** / **[심화]** / **[참조]**.
|
||||
- **신입은 §1~§11(필수)까지만 읽어도** E1~E5·E7·E8 을 답할 수 있다.
|
||||
- **[심화]**(§12~§14)는 E6 + 면접 압박 질문(라이브러리 내부)을 위한 것. 1회독 후 와도 된다.
|
||||
- **[참조]**(§15~§16)는 학습용이 아니라 *복습/치트시트*다.
|
||||
|
||||
### 이 수업을 관통하는 한 줄기 🧵
|
||||
|
||||
처음부터 끝까지 **"결제 호출 1건(`POST /v1/payments`, 주문 `ord-1001`)의 생애"** 를 따라간다. 이 한 건이 정상일 때 어떻게 흐르고, 각 안전장치를 만날 때 어떻게 갈리는지를 *순서대로* 본다. (결제 도메인은 이해를 위한 **가상 예시** — ca-tmpl skeleton 엔 결제 코드가 없다.)
|
||||
|
||||
---
|
||||
|
||||
## §1. 한 장면 — 5초 만에 고통 느끼기
|
||||
|
||||
🟢 **[신입 필수]**
|
||||
|
||||
외부 결제사에 `POST /payments` 를 보내다 네트워크가 순간 튀었다. 개발자가 재시도를 걸었다 → **고객에게 이중 결제**가 청구돼 민원 폭탄.
|
||||
또는 Redis 캐시가 죽자 그 여파로 홈 화면 API 전체가 500 으로 마비.
|
||||
또는 배포 종료(SIGTERM) 신호가 왔는데 진행 중 재시도가 커넥션을 안 놓고 버티다 강제 종료(SIGKILL), 데이터가 반쯤 처리된 채 꼬임.
|
||||
또는 외부에서 수 GB 응답을 무작정 버퍼에 담다 JVM 힙이 가득 차 **OOM** 사망.
|
||||
|
||||
> 💡 **왜 타임아웃이 "생사 문제"인가(스레드 풀 보충):** 톰캣 같은 서버는 요청 하나당 스레드 하나를 배정한다. 스레드 수는 유한(풀, 예: 200개). 외부가 응답을 안 주는데 타임아웃이 없으면 그 스레드는 *영원히* 그 요청에 묶인다. 이런 요청이 200개 쌓이면 *새 요청을 받을 스레드가 없어* 서버 전체가 멈춘다. 이게 "스레드 고갈"이다.
|
||||
|
||||
**그래서 진짜 고민 한 줄: 외부 인프라·네트워크 장애로부터 우리 시스템 리소스를 어떻게 격리하고, 사이드 이펙트 없이 우아하게 방어할 것인가?**
|
||||
|
||||
---
|
||||
|
||||
## §2. 단 하나의 축
|
||||
|
||||
🟢 **[신입 필수] — 이 주제의 축: 정합성(Consistency) ↔ 가용성(Availability)**
|
||||
|
||||
아웃바운드 설계의 모든 결정은 **데이터 정합성(Consistency) ↔ 시스템 가용성(Availability)** 이라는 하나의 축 위에서 갈린다.
|
||||
|
||||
```text
|
||||
[안전제일 / Fail-Closed (정합성 최우선)] ◄──────────────────────► [가용성 / Fail-Open (가용성 최우선)]
|
||||
- Outbox Relay (Kafka) 연동 - 캐시 스토어 (Redis) 연동
|
||||
- 비멱등(POST/PATCH) HTTP 재시도 차단 - 멱등(GET/PUT/DELETE) HTTP 재시도 허용
|
||||
- 셧다운 가드 (즉시 신규 요청 거절) - 직접 알림 발행 (Slack/Email)
|
||||
```
|
||||
|
||||
어떤 의존성은 장애 시 즉각 멈춰야 정합성을 지키고(Fail-Closed), 어떤 의존성은 장애를 삼키고 우회해야 가용성을 지킨다(Fail-Open). HTTP 클라이언트는 이 축 위에서 "**장애를 분류해 예외로 전달**"하는 중간 전략을 쓴다 — 무엇을 재시도/차단할지 메서드와 예외 종류로 가른다.
|
||||
|
||||
---
|
||||
|
||||
## §3. 큰 그림
|
||||
|
||||
🟢 **[신입 필수] — 관통 줄기: 결제 호출 1건(`ord-1001`)의 정상 항해**
|
||||
|
||||
### 레이어 경계 — Port & Adapter
|
||||
|
||||
> **새 용어 — Port & Adapter(육각형/클린 아키텍처):** Port = application(비즈니스 로직)이 "이런 기능이 필요해"라고 선언한 **인터페이스(구멍)**. Adapter = 그 구멍을 실제 기술(HTTP/Redis/Kafka)로 **메우는 구현체**. 비즈니스 로직이 "외부가 HTTP 인지 Redis 인지" 몰라도 되게 분리하는 게 목적. 의존성 화살표는 항상 바깥(adapter)에서 안쪽(core)을 향한다.
|
||||
|
||||
|
||||
|
||||
`OutboundHttpClient` 는 그 그림에서 **HTTP adapter 가 외부 세계로 나가는 출구**다. 사용자의 "결제하기" 클릭 한 번이 이렇게 흐른다:
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
autonumber
|
||||
participant Web as 🌫️ web (미지의 영역)<br>Controller
|
||||
participant App as 🌫️ application (미지의 영역)<br>PayUseCase
|
||||
participant Port as PaymentPort<br>(인터페이스)
|
||||
participant Adapter as PaymentHttpAdapter<br>(outbound adapter)
|
||||
participant Client as OutboundHttpClient
|
||||
participant Ext as 외부 결제사 서버
|
||||
|
||||
Web->>App: PaymentCommand(orderId, amount, currency)
|
||||
App->>Port: pay(command)
|
||||
Note over Port,Adapter: Port 는 application 이 정의한 "구멍",<br>Adapter 가 그 구멍을 HTTP 로 메운다
|
||||
Adapter->>Client: exchange(POST, "/v1/payments", reqObj, PaymentResult.class)
|
||||
Client->>Ext: POST /v1/payments (객체 → JSON 직렬화)
|
||||
Ext-->>Client: 200 OK (JSON 본문)
|
||||
Client-->>Adapter: PaymentResult (JSON → 객체 역직렬화)
|
||||
Adapter-->>App: 도메인 결과
|
||||
```
|
||||
|
||||
### 경계를 넘는 실제 값 (JSON 입·출력)
|
||||
|
||||
> **새 용어 — 직렬화/역직렬화:** 자바 객체 ↔ JSON 문자열 변환. 나갈 때 객체→JSON(직렬화), 들어올 때 JSON→객체(역직렬화). 내가 짜지 않고 RestClient 가 한다(자세히는 §13).
|
||||
|
||||
1. **application → adapter (자바 객체):** application 은 외부가 HTTP 인지 모른다. 객체만 넘긴다.
|
||||
`PaymentCommand(orderId="ord-1001", amount=15000, currency="KRW")`
|
||||
2. **adapter → `exchange()` 호출:**
|
||||
```java
|
||||
PaymentResult result = paymentClient.exchange(
|
||||
HttpMethod.POST, "/v1/payments",
|
||||
new PaymentRequest("ord-1001", 15000, "KRW"), // ← requestBody (자바 객체)
|
||||
PaymentResult.class); // ← 응답을 이 타입으로 받겠다
|
||||
```
|
||||
3. **`exchange()` 가 실제로 내보내는 HTTP (객체 → JSON):**
|
||||
```http
|
||||
POST /v1/payments HTTP/1.1
|
||||
Host: payment
|
||||
traceparent: 00-4bf9...-00f0...-00 ← 인터셉터가 자동 주입 (§11)
|
||||
Content-Type: application/json
|
||||
|
||||
{"orderId":"ord-1001","amount":15000,"currency":"KRW"}
|
||||
```
|
||||
4. **외부 성공 응답(JSON):** `{"paymentId":"pay_abc","status":"APPROVED","approvedAt":"2026-06-15T09:00:00Z"}`
|
||||
5. **반환값:** RestClient 가 JSON 을 `PaymentResult` 로 역직렬화 → adapter 는 `PaymentResult(paymentId="pay_abc", status=APPROVED, …)` 객체를 받음.
|
||||
6. **실패(500)면?** `exchange()` 는 `DependencyFailureException`(코드 `DEPENDENCY_5XX_SERVER`)를 **던진다** → §10 에서 추적.
|
||||
|
||||
➡️ 한 줄 요약: `exchange()` 입력 = **(메서드 + 경로 + 요청객체 + 응답타입)**, 출력 = **역직렬화된 응답객체** 또는 **던져진 `DependencyFailureException`**.
|
||||
|
||||
---
|
||||
|
||||
## §4. 클래스의 모양 — 공개 메서드 4개 [신입 필수]
|
||||
|
||||
> **새 용어 — 정적 팩토리(static factory):** `new` 대신 `static` 메서드로 객체를 만드는 방식. 여기선 아키텍처 규칙(ArchUnit "B7": 어댑터 타입을 반환하는 *일반* 메서드 금지)을 `static` 으로 우회하는 합법 통로(seam). · **제네릭 `<T>`:** "호출자가 정한 타입". `get(uri, PaymentResult.class)` 면 `T=PaymentResult`.
|
||||
|
||||
진입 클래스 `OutboundHttpClient` 는 **외부 의존성 1개당 인스턴스 1개**(결제용 1개, 재고용 1개 …). 공개 메서드 4개:
|
||||
|
||||
| 부르는 법 | 코드 위치 | 넣는 것 | 나오는 것 |
|
||||
|---|---|---|---|
|
||||
| `baseline(name, baseUrl, …협력자 8개)` | `OutboundHttpClient.java:140` | 의존성 이름 + 협력 빈 | 그 의존성 전용 클라이언트 |
|
||||
| `get(uri, Class<T>)` | `:166` | URI + 응답 타입 | 역직렬화된 `T` |
|
||||
| `exchange(method, uri, body, Class<T>)` | `:184` | 메서드 + URI + 요청 바디 + 응답 타입 | 역직렬화된 `T` |
|
||||
| `stream(method, uri, reader)` | `:281` | 메서드 + URI + 스트림 리더(함수) | 리더가 만든 `T` (대용량 전용, 재시도 X) |
|
||||
|
||||
```java
|
||||
// 📄 OutboundHttpClient.java:166-168 — get 은 exchange 의 GET 단축
|
||||
public <T> T get(String uri, Class<T> responseType) {
|
||||
return exchange(HttpMethod.GET, uri, null, responseType);
|
||||
}
|
||||
```
|
||||
|
||||
<details><summary>✅ 이해 점검 (펼쳐서 스스로 답해보기)</summary>
|
||||
|
||||
1. `exchange()` 와 `stream()` 의 *출력 형태* 차이는? (정답: exchange=역직렬화된 객체 / stream=리더 함수가 만든 값. stream 은 재시도 없음)
|
||||
2. `baseline(...)` 이 `static` 인 이유 한 줄? (ArchUnit B7 우회 seam)
|
||||
</details>
|
||||
|
||||
---
|
||||
|
||||
## §5. `exchange()` 한 줄씩 — 정상 골격 [신입 필수]
|
||||
|
||||
> 🔑 **이 코드 읽기 전 5단어** (이거만 알면 아래가 읽힌다):
|
||||
> - **supplier** = "값을 주는 함수"(`Supplier<T>`). *호출(`.get()`)해야* 실제로 실행된다(준비 ≠ 실행).
|
||||
> - **람다 `() -> {...}`** = 이름 없는 함수 한 덩어리. `() ->` 는 "인자 없이 {…} 를 실행".
|
||||
> - **`<T>`** = 호출자가 받고 싶은 응답 타입(예: `PaymentResult`).
|
||||
> - **ThreadLocal** = "스레드 전용 변수칸"(다른 스레드와 안 섞임).
|
||||
> - **데코레이션(decorate)** = 함수를 *한 겹 감싸* 새 능력(재시도·차단)을 입히는 것.
|
||||
|
||||
```java
|
||||
// 📄 OutboundHttpClient.java:184-258 — exchange() (주석 축약)
|
||||
public <T> T exchange(HttpMethod method, String uri, Object requestBody, Class<T> responseType) {
|
||||
// ── Step 1. 셧다운 fail-fast: 종료 중이면 네트워크를 맺지도 않고 즉시 거부 (§6)
|
||||
if (shutdownGuard.isShuttingDown()) {
|
||||
DependencyFailureException rejected = new DependencyFailureException(
|
||||
OperationalError.DEPENDENCY_CIRCUIT_OPEN, // ← 나가는 예외 "값"
|
||||
dependencyName,
|
||||
"shutdown in progress — outbound call rejected fail-fast (D8)", null);
|
||||
logger.logFailure(dependencyName, "REJECTED", 0L, 0, rejected);
|
||||
throw rejected; // ← 여기서 나간다
|
||||
}
|
||||
|
||||
// ── Step 2. 마감시한 산정 + 스레드에 적재 (재시도 루프가 이 시각을 본다) (§7)
|
||||
Instant deadline = Instant.now().plus(settings.globalCallTimeout());
|
||||
retryPolicy.beginCall(method, deadline);
|
||||
|
||||
int[] attemptCount = {0}; // 시도 횟수(람다가 고치려고 1칸 배열 — §14)
|
||||
long startNs = System.nanoTime();
|
||||
try {
|
||||
// ── Step 3. 실제 호출(buffered)을 supplier 로 "준비"만 한다 (아직 실행 X)
|
||||
Supplier<T> supplier = buildSupplier(method, uri, requestBody, responseType);
|
||||
|
||||
// ── Step 4. CB·Retry 로 감싼다 (감싸는 순서의 의미는 §12 [심화])
|
||||
Optional<CircuitBreaker> cb = resilience.circuitBreakerFor(dependencyName);
|
||||
Optional<Retry> retry = resilience.retryFor(dependencyName);
|
||||
Supplier<T> countingSupplier = () -> { attemptCount[0]++; return supplier.get(); };
|
||||
Supplier<T> decorated = countingSupplier;
|
||||
if (retry.isPresent()) decorated = Retry.decorateSupplier(retry.get(), decorated);
|
||||
if (cb.isPresent()) decorated = CircuitBreaker.decorateSupplier(cb.get(), decorated);
|
||||
|
||||
T result = decorated.get(); // ← 여기서 비로소 실제 네트워크 호출이 일어난다
|
||||
|
||||
// ── Step 5. 성공 로그 (소요시간 + 재시도 횟수)
|
||||
long durationMs = (System.nanoTime() - startNs) / 1_000_000;
|
||||
logger.logSuccess(dependencyName, durationMs, Math.max(0, attemptCount[0] - 1));
|
||||
return result;
|
||||
|
||||
} catch (OutboundResponseSizeExceededException sizeEx) {
|
||||
throw sizeEx; // ── Step 6a. 응답 과대 = "API 오용" → 분류 없이 그대로 (§9)
|
||||
|
||||
} catch (Throwable t) { // Throwable = 자바 모든 예외의 최상위 = 사실상 전부
|
||||
// ── Step 6b. 그 외 모든 실패 → 하나의 DependencyFailureException 으로 "번역" (§10)
|
||||
long durationMs = (System.nanoTime() - startNs) / 1_000_000;
|
||||
DependencyFailureException dfe = errorMapper.classify(dependencyName, t);
|
||||
logger.logFailure(dependencyName, outcomeFor(dfe), durationMs,
|
||||
Math.max(0, attemptCount[0] - 1), dfe);
|
||||
throw dfe; // ← 호출자는 항상 이 분류된 예외만 본다
|
||||
|
||||
} finally {
|
||||
retryPolicy.endCall(); // 성공·예외 무관 *반드시* 실행 → ThreadLocal 정리(누수 방지 §14)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
골격 5줄 요약: ① 종료 중이면 즉시 거부 → ② 마감시한 적재 → ③ 호출을 *준비* → ④ 감싸서 `decorated.get()` 으로 *실행* → ⑤/⑥ 성공 로그 또는 예외 번역. **`supplier` 는 레시피일 뿐, `.get()` 을 불러야 요리된다**(지연 실행). 각 안전장치의 *내부*는 §6~§11 에서 하나씩 연다.
|
||||
|
||||
<details><summary>✅ 이해 점검</summary>
|
||||
|
||||
1. *네트워크가 실제로 일어나는* 코드 한 줄은? (정답: `decorated.get()`)
|
||||
2. `finally` 의 `endCall()` 을 빼면? (ThreadLocal 누수 → 풀 스레드 재사용 시 이전 요청 컨텍스트 오염 — §14)
|
||||
3. 응답 과대(Step 6a)만 분류 없이 그대로 던지는 이유? (업스트림 장애가 아니라 "버퍼 API 오용")
|
||||
</details>
|
||||
|
||||
---
|
||||
|
||||
## §5.5. 안전장치 ⓪ 타임아웃 3종 — connect·read·global [신입 필수]
|
||||
|
||||
> **새 용어:** **connect timeout** = TCP 연결(핸드셰이크) 맺기까지의 제한. **read timeout** = 연결 후 *한 번의* 응답 바이트를 기다리는 제한. **global-call timeout** = 재시도까지 포함한 *전체* 마감(= §7 의 deadline 예산).
|
||||
|
||||
타임아웃은 가장 기본 안전장치다 — 셧다운·재시도·서킷보다 먼저, **모든 호출에 무조건** 적용된다. 하나라도 빠지면 §1 #1 의 "무한 대기 → 스레드 고갈"이 그 구멍으로 샌다. 세 개가 *서로 다른 단계*를 끊는다:
|
||||
|
||||
```text
|
||||
[연결 시도] ──connect timeout(예 2s)──▶ [연결됨] ──read timeout(예 5s)──▶ [응답 한 번 도착]
|
||||
└──────────────── global-call timeout(예 10s): 재시도 다 합쳐 여기까지 ────────────────┘
|
||||
```
|
||||
|
||||
설정/배선 (생성자에서):
|
||||
|
||||
```java
|
||||
// 📄 OutboundHttpClient.java:95-99 — 타임아웃 2원화
|
||||
HttpClient httpClient = HttpClient.newBuilder()
|
||||
.connectTimeout(settings.connectTimeout()).build(); // ← connect 는 JDK HttpClient 가
|
||||
JdkClientHttpRequestFactory requestFactory = new JdkClientHttpRequestFactory(httpClient);
|
||||
requestFactory.setReadTimeout(settings.readTimeout()); // ← read 는 factory 가
|
||||
// global 은 타임아웃 객체가 아니라 exchange() 의 deadline 예산으로 강제 (§7)
|
||||
```
|
||||
|
||||
> 🤔 **왜 connect 와 read 가 다른 객체에?** JDK `HttpClient.Builder` 엔 connectTimeout API 만 있고 *per-request read timeout 이 없다*. 그래서 Spring 의 `JdkClientHttpRequestFactory.setReadTimeout` 이 그 공백을 메운다(라이브러리 API 한계). global 은 라이브러리가 안 주니 우리가 deadline 으로 직접 만든다.
|
||||
|
||||
#### 타임아웃 설정값과 역할 (`app.outbound.http.*`)
|
||||
|
||||
| 설정 | 역할 (무엇을 끊나) | 기본 | 없거나 0/음수면 |
|
||||
|---|---|---|---|
|
||||
| `connect-timeout` | TCP 연결(핸드셰이크)까지 | **필수(기본 없음)** | 죽은/방화벽 막힌 호스트에 무한 대기 |
|
||||
| `read-timeout` | 연결 후 응답 한 번까지 | **필수** | 응답을 질질 끄는 서버에 스레드 묶임 |
|
||||
| `global-call-timeout` | 재시도 포함 전체 마감(=deadline) | **필수** | 재시도 루프가 끝없이 늘어짐 |
|
||||
|
||||
셋 다 **필수 입력**이라, 하나라도 비거나 잘못되면 §13① 의 `@ConfigurationProperties` 검증이 `IllegalArgumentException` 으로 **앱 기동을 막는다** — 무한 대기 구멍을 *기동 시점에* 봉쇄한다.
|
||||
|
||||
> 🧑🏫 **한마디:** connect/read 는 *한 단계*를, global 은 *전체*를 끊는다. 보통 connect ≤ read ≤ global 로 잡아 어느 단계에서 멈춰도 새는 곳이 없게 한다. 단 §7 에서 봤듯 global(deadline)은 *진행 중 read 를 강제로 못 끊어* 하드컷이 아니다 — 진행 중 호출의 상한은 결국 read timeout 이 책임진다.
|
||||
|
||||
<details><summary>✅ 이해 점검</summary>
|
||||
|
||||
1. 상대가 TCP 연결은 받아주는데 응답 바이트를 영영 안 주면, 어느 타임아웃이 끊나? (read)
|
||||
2. connect/read 가 왜 두 객체(JDK HttpClient / factory)에 나뉘나? (JDK 에 per-request read API 부재)
|
||||
</details>
|
||||
|
||||
---
|
||||
|
||||
## §6. 안전장치 ① 셧다운 fail-fast — `SmartLifecycle` [신입 필수]
|
||||
|
||||
배포로 서버가 종료 중일 때 새 외부 호출이 들어오면, 반쯤 죽은 빈을 건드려 NPE·자원 누수가 난다. 그래서 **종료가 시작되면 가장 먼저 깃발을 올려** 신규 호출을 즉시 끊는다.
|
||||
|
||||
```java
|
||||
// 📄 OutboundHttpShutdownGuard.java:41-77 (발췌) — SmartLifecycle 구현
|
||||
@Override public void stop() { shuttingDown.set(true); running.set(false); } // 종료 시 호출됨
|
||||
@Override public int getPhase(){ return Integer.MAX_VALUE; } // ← phase 최대 = 내림차순에서 1순위로 stop
|
||||
public boolean isShuttingDown() { return shuttingDown.get(); } // exchange Step1 / shouldRetry 가 조회
|
||||
```
|
||||
|
||||
**어떻게 동작하나:** Spring 컨테이너는 종료 시 `SmartLifecycle` 빈들의 `stop()` 을 **phase 큰 것부터(내림차순)** 호출한다. phase 를 `Integer.MAX_VALUE` 로 둬서 이 가드의 `stop()` 이 *맨 먼저* 불리고 `shuttingDown` 깃발이 켜진다 → 외부 호출하는 다른 빈이 아직 살아있을 때 이미 신규 호출을 막는다.
|
||||
|
||||
> 🤔 **왜 `ContextClosedEvent` 가 아니라 `SmartLifecycle`?** (자가점검 단골) `ContextClosedEvent` 리스너는 *컨테이너가 이미 닫히기 시작한 뒤* + 리스너 간 순서 보장 없이 불린다 → 그 사이 다른 빈이 먼저 죽어버릴 수 있다. `SmartLifecycle` 의 phase 순서는 *결정론적*이라 "내가 1순위"를 보장한다.
|
||||
|
||||
이 깃발은 두 곳이 읽는다: `exchange()` Step 1(신규 호출 즉시 `DEPENDENCY_CIRCUIT_OPEN`) + `shouldRetry()` 관문1(진행 중 재시도 중단).
|
||||
|
||||
---
|
||||
|
||||
## §7. 안전장치 ② 재시도 — *할지*(4-관문) + *어떻게*(루프·백오프) [신입 필수]
|
||||
|
||||
> **새 용어 — 멱등(idempotent):** 같은 요청을 여러 번 보내도 결과가 한 번과 같음. GET/PUT/DELETE 는 멱등(안전하게 재시도 가능), **POST 는 비멱등**(보낼 때마다 새 결제가 생김 → 재시도 금지). · **데드라인 예산:** "늦어도 이 시각까지"라는 전체 마감. · **백오프/지터:** 재시도 간 대기를 점점 늘리고(backoff) 거기에 무작위를 섞어(jitter) 모두가 동시에 재시도(thundering herd)하는 걸 막음.
|
||||
|
||||
#### A. 재시도를 *할지* 결정 — 4-관문 (`shouldRetry`)
|
||||
|
||||
재시도는 무조건 하면 위험하다(이중 결제). 그래서 **4-관문을 전부 통과해야만** 재시도한다:
|
||||
|
||||
```java
|
||||
// 📄 OutboundRetryPolicy.java:103-133 — shouldRetry() (반환문 압축)
|
||||
public boolean shouldRetry(Throwable failure) {
|
||||
if (guard.isShuttingDown()) return false; // 관문1: 종료 중이면 끝
|
||||
CallContext ctx = callContextHolder.get();
|
||||
if (ctx == null) return false; // beginCall 안 됐으면 끝
|
||||
if (!IDEMPOTENT_METHODS.contains(ctx.method())) return false; // 관문2: POST/PATCH 차단
|
||||
boolean retryable;
|
||||
if (failure instanceof DependencyFailureException dfe)
|
||||
retryable = dfe.errorCode().retryable(); // 이미 번역됨 → 그 코드의 플래그
|
||||
else
|
||||
retryable = mapper.classify("_retry-check_", failure).errorCode().retryable();
|
||||
if (!retryable) return false; // 관문3: 재시도 가능 코드만 (§10 표)
|
||||
return Instant.now().isBefore(ctx.deadline()); // 관문4: 마감시한 예산 남았나
|
||||
}
|
||||
// IDEMPOTENT_METHODS = Set.of(GET, HEAD, PUT, DELETE) ← :52-53 (POST/PATCH 의도적 제외)
|
||||
```
|
||||
|
||||
순서대로: ① **종료 중 아님** → ② **멱등 메서드** → ③ **재시도 가능 코드**(§10 의 "재시도?" 칸) → ④ **마감시한 남음**. (코드상으론 `ctx==null` 까지 5개의 조기 반환이지만, 논리적으론 4-관문.)
|
||||
|
||||
> ⚠️ **[심화] deadline 은 "하드 데드라인"이 아니다.** 관문4 는 *재시도를 시작하기 전*에만 검사한다(`shouldRetry` 안). 즉 **이미 시작된 read 는 강제로 못 끊는다** → 마지막 시도가 read-timeout 만큼 deadline 을 *초과*해 끝날 수 있다. "deadline=다음 재시도 차단선"이지 "30s 면 무조건 30s 에 끊김"이 아니다. 진짜 하드 컷이 필요하면 Resilience4j `TimeLimiter`(+별도 스레드)가 필요한데, 동기 클라이언트엔 스레드 낭비라 *의도적으로* deadline 예산만 택했다(결정 I3).
|
||||
|
||||
#### B. 재시도가 *어떻게* 도나 — 루프·횟수·백오프·지터
|
||||
|
||||
게이트(A)가 "해도 된다"고 하면, Resilience4j `Retry` 가 *실제 루프*를 돈다. 그 설정을 만드는 코드:
|
||||
|
||||
```java
|
||||
// 📄 OutboundHttpResilience.java:82-90 — retryFor(): 재시도 설정 빌드
|
||||
RetryConfig config = RetryConfig.custom()
|
||||
.maxAttempts(r.maxAttempts()) // 총 시도 횟수 (기본 3)
|
||||
.intervalFunction(IntervalFunction.ofExponentialRandomBackoff( // 지수 백오프 + 지터
|
||||
r.initialBackoff(), r.backoffMultiplier())) // 기본 100ms, ×2.0
|
||||
.retryOnException(retryPolicy::shouldRetry) // ← 4-관문(A)이 여기 꽂힌다
|
||||
.build();
|
||||
```
|
||||
|
||||
- **`retryOnException(shouldRetry)`** — 매 실패마다 Retry 가 4-관문을 *다시* 물어본다. true 면 한 번 더, false 면 즉시 포기. 즉 **게이트(A)는 루프 안에서 매 회 호출**된다.
|
||||
- **`maxAttempts=3`** — 첫 시도 1 + 재시도 2 = **총 3번**. (재시도 켠 채 매번 500 주는 GET 은 서버를 *정확히 3번* 친다 — 테스트 검증.)
|
||||
- **백오프 = 지수 + 지터** — 시도 사이 *대기 시간*. nominal = `initial-backoff × multiplier^(n-1)` → 기본값이면 100ms, 200ms … 거기에 **±50% 무작위(지터)** 를 섞는다(Resilience4j 기본 randomizationFactor 0.5).
|
||||
|
||||
타임라인 (기본값, GET 이 매번 timeout):
|
||||
|
||||
```text
|
||||
시도1 ─실패→ 대기 ~100ms(지터 [50,150]) → 시도2 ─실패→ 대기 ~200ms(지터 [100,300]) → 시도3 ─실패→ 포기(예외 전파)
|
||||
└─────────────────── 매 대기 직전 4-관문④(deadline)을 다시 확인 ───────────────────┘
|
||||
```
|
||||
|
||||
> **왜 지터?** 장애 순간 수백 개 요청이 *똑같이* 100ms 뒤 동시에 재시도하면 회복 중인 상대를 또 무너뜨린다(thundering herd). ±무작위로 시점을 흩뜨려 막는다.
|
||||
|
||||
#### 재시도 설정값과 역할 (`app.outbound.http.retry.*`)
|
||||
|
||||
| 설정 | 역할 | 기본 | 바꾸면 |
|
||||
|---|---|---|---|
|
||||
| `retry-enabled` | 재시도 기능 on/off (off 면 `retryFor`→`Optional.empty()` = 데코 안 함) | `false` | `true` 라야 위 루프가 생김 |
|
||||
| `retry.max-attempts` | **총** 시도 횟수(첫 시도 포함) | `3` | `5` → 최대 4번 재시도 |
|
||||
| `retry.initial-backoff` | 첫 재시도 전 nominal 대기 | `100ms` | 키우면 첫 대기 ↑ |
|
||||
| `retry.backoff-multiplier` | 매 재시도마다 대기 ×배수 | `2.0` | `3.0` → 100→300→900ms |
|
||||
|
||||
> 🧑🏫 **한마디:** 게이트(A)=*할지*, 루프(B)=*어떻게*. 재시도가 실제로 일어나려면 **`retry-enabled=true`** + **4-관문 통과** 둘 다 필요하다. (서킷 §8 과 합쳐지는 순서·집계는 §12 [심화].)
|
||||
|
||||
<details><summary>✅ 이해 점검</summary>
|
||||
|
||||
1. `POST /orders` 가 `SocketTimeoutException` → 재시도되나? 어느 관문에서 탈락? (관문2)
|
||||
2. `GET /products/1` 가 404 → 재시도되나? 왜? (관문3 — 4xx 는 retryable=false, §10)
|
||||
3. `max-attempts=3` 이고 매번 실패면 서버를 몇 번 치고, 대기는 몇 번 하나? (정답: 3번 호출 / 2번 대기)
|
||||
4. `initial-backoff=100ms`, `backoff-multiplier=2.0` 면 *두 번째* 재시도 전 nominal 대기는? (200ms)
|
||||
</details>
|
||||
|
||||
---
|
||||
|
||||
## §8. 안전장치 ③ 서킷 브레이커 — 0부터 [신입 필수]
|
||||
|
||||
> 근거: 개념 [[wiki/concepts/circuit-breaker.md]], 설정 수치는 canonical project 문서. 라이브러리는 Resilience4j.
|
||||
|
||||
**서킷 브레이커가 뭔데?** 집 누전차단기(두꺼비집)다. 과부하/누전 시 차단기가 *탁* 내려가 집 전체 화재를 막고, 잠시 뒤 다시 올려본다. **단 — 차단기가 내려간 동안은 멀쩡한 가전도 못 쓴다.** 소프트웨어도 똑같다: 어떤 외부 의존성이 계속 실패하면 그쪽 호출을 한동안 *아예 끊는다*. 죽은 서버를 계속 두들겨봐야 ① 내 스레드만 묶이고 ② 아픈 상대를 더 괴롭히기 때문.
|
||||
|
||||
**무엇을 감시?** 그 의존성으로 나간 **최근 100건의 실패 비율**(= 슬라이딩 윈도우).
|
||||
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
[*] --> CLOSED
|
||||
CLOSED --> OPEN: 최근 100건 실패율 ≥ 50%
|
||||
OPEN --> HALF_OPEN: 60초 경과
|
||||
HALF_OPEN --> CLOSED: 시험 10건 실패율 < 50% (복구)
|
||||
HALF_OPEN --> OPEN: 시험 10건 실패율 ≥ 50% (아직 아픔)
|
||||
note right of CLOSED
|
||||
정상. 통과시키며 실패율만 측정
|
||||
end note
|
||||
note right of OPEN
|
||||
차단. 네트워크 안 감.
|
||||
즉시 CallNotPermittedException
|
||||
end note
|
||||
note right of HALF_OPEN
|
||||
간 보기. 동시 10건만 통과
|
||||
end note
|
||||
```
|
||||
|
||||
- **CLOSED(정상):** 다 통과시키며 실패율을 잰다.
|
||||
- **OPEN(차단):** 외부로 **안 보내고** 즉시 `CallNotPermittedException` 을 던진다(= §10 표의 `DEPENDENCY_CIRCUIT_OPEN`). ms 단위로 빠르게 실패(fail-fast).
|
||||
- **HALF_OPEN(간 보기):** 대기 후 "살아났나?" 확인하려 **동시 10건만** 통과시키고 나머진 거부. 그 10건 결과가 다 모이면 CLOSED 복귀냐 OPEN 회귀냐 결정.
|
||||
|
||||
**각 전이를 어떤 설정값이 정하나:**
|
||||
|
||||
| 전이 | 트리거 | 설정 (`app.outbound.http.circuit-breaker.*`) | 기본 |
|
||||
|---|---|---|---|
|
||||
| CLOSED → OPEN | 윈도우가 차고 실패율 임계 이상 | `sliding-window-size` / `minimum-number-of-calls` / `failure-rate-threshold` | 100 / 100 / 50% |
|
||||
| OPEN → HALF_OPEN | 대기시간 경과 | `wait-duration-in-open-state` | 60s |
|
||||
| HALF_OPEN → CLOSED/OPEN | 시험 호출 실패율 < / ≥ 임계 | `permitted-calls-in-half-open` (+ 임계) | 10 |
|
||||
|
||||
> 🧩 **두 설정이 헷갈린다 — `sliding-window-size` vs `minimum-number-of-calls`:** 우연히 둘 다 100이지만 *다른 손잡이*다. 윈도우 크기 = "실패율을 *재는 표본 범위*", min-calls = "실패율을 *계산하기 시작하는 최소 건수*". 100건이 안 모이면 한두 번 실패해도 서킷을 안 연다(통계 노이즈 방지).
|
||||
>
|
||||
> 🔬 **[심화] HALF_OPEN 의 윈도우는 따로다.** HALF_OPEN 에 들어가면 100짜리 윈도우를 비우고 `permitted-calls-in-half-open`(10) 크기의 *별도 시험 윈도우*로 평가한다. 그 10건의 실패율로 CLOSED/OPEN 을 가른다. (이 윈도우는 시간이 아니라 *건수* 기준 = `slidingWindowType` 이 COUNT_BASED. 코드엔 노출 안 됨 = Resilience4j 기본값. TIME_BASED 로 바꾸려면 코드 수정 필요.)
|
||||
|
||||
**타임라인(기본값):** ① payment 가 100건 중 60건 실패 → 실패율 60% → **OPEN.** ② 60초간 모든 payment 호출 즉시 거절(내 스레드 보호, 상대 숨 돌림). ③ 60초 후 **HALF_OPEN**, 10건 떠봄 → 1건만 실패(10%) → **CLOSED 복귀.** ④ 만약 6건 실패면 → **다시 OPEN.**
|
||||
|
||||
**코드에서 어디?** `OutboundHttpResilience.circuitBreakerFor("payment")` 가 의존성 이름별 인스턴스를 캐시 → payment 와 inventory 는 *독립된* 두꺼비집(한쪽이 열려도 다른 쪽 멀쩡).
|
||||
|
||||
> ⚠️ **과장 금지(면접용):** "서킷 쓰면 가용성 올라간다"는 **틀린 말**이다. OPEN 동안은 멀쩡한 요청도 거절돼 *그 의존성 가용성은 일시적으로 0*. 서킷의 진짜 목적은 가용성이 아니라 **내 스레드 보호 + 아픈 업스트림 보호**다.
|
||||
|
||||
<details><summary>✅ 이해 점검</summary>
|
||||
|
||||
1. 빈 종이에 3상태 + 전이 4개 + 트리거를 직접 그려보라. (E3)
|
||||
2. `minimum-number-of-calls=100` 이 없으면 서버 켜자마자 무슨 일? (1~2건 실패로 서킷 오픈 — 노이즈)
|
||||
3. "서킷 쓰면 가용성 ↑?" O/X + 한 줄 교정. (E4)
|
||||
</details>
|
||||
|
||||
---
|
||||
|
||||
## §9. 안전장치 ④ 응답 크기 & 스트리밍 [신입 필수]
|
||||
|
||||
상대가 2GB 응답을 주는데 버퍼에 다 담으면 OOM. 그래서 **buffered 경로엔 크기 상한(기본 10MB)**, 대용량은 **streaming 경로**로 분리한다.
|
||||
|
||||
`ResponseSizeBoundingInterceptor` 는 **2단 방어**다:
|
||||
1. **Content-Length 빠른 차단:** 응답 헤더의 선언 크기가 상한을 넘으면 본문을 *한 바이트도 안 읽고* `OutboundResponseSizeExceededException`.
|
||||
2. **스트림 카운팅:** 헤더가 없거나 *거짓말*하면, `BoundedInputStream` 이 읽는 바이트를 세다 상한 초과 시 throw.
|
||||
|
||||
대용량은 buffered 가 아니라 streaming:
|
||||
|
||||
```java
|
||||
// 📄 OutboundHttpClient.java:295-298 — 버퍼 없이 raw InputStream 을 reader 에게 직접
|
||||
T result = streamingClient.method(method).uri(uri)
|
||||
.exchange((req, res) -> reader.apply(res.getBody()));
|
||||
```
|
||||
|
||||
`exchange()` 콜백은 응답을 메모리에 다 담지 않고 `InputStream` 을 그대로 넘긴다 → 100MB CSV OK. 단 **재시도 없음** — 한 번 흘려보낸 스트림은 (수도꼭지에서 이미 흘러간 물처럼) 되감을 수 없어 다시 보낼 수 없다(자가점검 Q5 답).
|
||||
|
||||
---
|
||||
|
||||
## §10. 실패의 번역 — `classify()` + 예외 운반 [신입 필수]
|
||||
|
||||
> **새 용어 — cause chain(원인 사슬):** 예외 A 가 예외 B 때문에 났을 때 `A.getCause()==B` 로 줄줄이 연결된 것. 진짜 원인은 사슬 아래에 숨어 있곤 한다.
|
||||
|
||||
`exchange()` 가 잡은 raw 예외(`Throwable`)는 **하나의 `DependencyFailureException` 으로 번역**된다. `classify()` 가 cause chain 을 훑어 첫 매치를 채택:
|
||||
|
||||
```java
|
||||
// 📄 OutboundHttpErrorMapper.java:63-169 — classify() (메시지 인자 …로 생략)
|
||||
public DependencyFailureException classify(String dependencyName, Throwable failure) {
|
||||
Throwable current = failure;
|
||||
while (current != null) { // 원인 사슬을 위에서부터 한 칸씩
|
||||
if (current instanceof CallNotPermittedException) // 규칙1: 서킷 OPEN (§8)
|
||||
return new DependencyFailureException(OperationalError.DEPENDENCY_CIRCUIT_OPEN, …);
|
||||
if (current instanceof UnknownHostException || current instanceof UnresolvedAddressException)
|
||||
return new DependencyFailureException(OperationalError.DEPENDENCY_DNS_FAILED, …); // 규칙2: DNS
|
||||
if (current instanceof HttpConnectTimeoutException) // 규칙3: 연결 (먼저!)
|
||||
return new DependencyFailureException(OperationalError.DEPENDENCY_CONNECT_FAILED, …);
|
||||
if (current instanceof ConnectException) {
|
||||
if (hasDnsCauseInChain(current.getCause())) // 연결예외가 사실 DNS 를 감쌌으면 DNS 로
|
||||
return new DependencyFailureException(OperationalError.DEPENDENCY_DNS_FAILED, …);
|
||||
return new DependencyFailureException(OperationalError.DEPENDENCY_CONNECT_FAILED, …);
|
||||
}
|
||||
if (current instanceof HttpTimeoutException || current instanceof SocketTimeoutException
|
||||
|| current instanceof TimeoutException) // 규칙4: 시간 초과
|
||||
return new DependencyFailureException(OperationalError.DEPENDENCY_TIMEOUT, …);
|
||||
if (current instanceof RestClientResponseException responseEx) { // 규칙5/6: HTTP 상태
|
||||
int status = responseEx.getStatusCode().value();
|
||||
if (status >= 400 && status < 500) // I5: 모든 4xx = 비재시도
|
||||
return new DependencyFailureException(OperationalError.DEPENDENCY_4XX_CLIENT, …);
|
||||
if (status >= 500)
|
||||
return new DependencyFailureException(OperationalError.DEPENDENCY_5XX_SERVER, …);
|
||||
}
|
||||
current = current.getCause(); // 다음 원인으로
|
||||
}
|
||||
return new DependencyFailureException(OperationalError.DEPENDENCY_CONNECT_FAILED, …); // 규칙7: fallback
|
||||
}
|
||||
```
|
||||
|
||||
> 🤔 **왜 `HttpConnectTimeoutException` 을 먼저 검사하나?** 자바는 부모 타입으로 `instanceof` 하면 자식도 다 걸린다. `HttpConnectTimeoutException` 은 `HttpTimeoutException`(규칙4)의 *자식*이라, 규칙4 를 먼저 두면 connect-timeout 이 일반 timeout 으로 *오분류*된다 → 그래서 규칙3(connect)이 위. · **ConnectException 의 DNS 재탐색:** JDK 가 DNS 실패를 `ConnectException(cause=UnresolvedAddressException)` 로 감싸는 패턴이 있어, 그 *하위 사슬*을 한 번 더 훑어 DNS 면 `DNS_FAILED` 로 승격한다(분류 충실도).
|
||||
|
||||
번역 결과(코드·HTTP·재시도 여부)는 `OperationalError` enum 에 못박혀 있다:
|
||||
|
||||
| 실제로 터진 예외 | 번역된 코드 | HTTP / 재시도? |
|
||||
|---|---|---|
|
||||
| `CallNotPermittedException`(서킷 OPEN) | `DEPENDENCY_CIRCUIT_OPEN` | 503 / ✅ |
|
||||
| `UnknownHostException`(DNS) | `DEPENDENCY_DNS_FAILED` | 503 / ✅ |
|
||||
| `ConnectException`(연결) | `DEPENDENCY_CONNECT_FAILED` | 503 / ✅ |
|
||||
| `SocketTimeoutException` 등(시간초과) | `DEPENDENCY_TIMEOUT` | 504 / ✅ |
|
||||
| 상대 4xx | `DEPENDENCY_4XX_CLIENT` | 502 / ❌ (401→자격증명, 403→권한 힌트) |
|
||||
| 상대 5xx | `DEPENDENCY_5XX_SERVER` | 502 / ✅ |
|
||||
|
||||
> 4xx 가 ❌ 인 이유: 잘못 보낸 요청을 똑같이 다시 보내봐야 또 거절. **알려진 한계:** 408(타임아웃)·429(과다요청)는 원래 재시도 가치가 있는데 "모든 4xx=비재시도"라 함께 막힌다.
|
||||
|
||||
### 예외 객체는 어떻게 "담겨서" 위로 가나
|
||||
|
||||
```java
|
||||
// 📄 shared/error/DependencyFailureException.java (발췌) — 분류된 실패 운반체
|
||||
public class DependencyFailureException extends RuntimeException {
|
||||
private final ApiErrorCode errorCode; // ① 클라이언트에 줄 코드 (DEPENDENCY_5XX_SERVER)
|
||||
private final String dependencyName; // ② 누가 실패했나 ("payment")
|
||||
public DependencyFailureException(ApiErrorCode errorCode, String dependencyName,
|
||||
String diagnosticMessage, Throwable cause) {
|
||||
super(diagnosticMessage, cause); // ③ diagnosticMessage = 서버 로그 전용, ④ cause = 원본 예외
|
||||
...
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
5xx 메시지 조립(`:151-154`): `"Upstream 5xx from dependency: payment status=500 (HttpServerErrorException)"` — **status + 예외 클래스명만.**
|
||||
|
||||
> 🔒 **비밀(토큰/PII)이 안 새는 2중 방어:** (1) `classify()` 가 메시지에 `getResponseBodyAsString()`(외부 응답 본문)을 *안 넣는다* + (2) 구조화 로거(`OutboundHttpDependencyLogger`)는 애초에 **응답 body·URI 를 받는 파라미터가 없다**(시그니처 차원 봉쇄, "by construction"). 그래서 외부가 `{"token":"sk_live_secret"}` 를 줘도:
|
||||
> - 서버 로그 메시지: `…status=500 (HttpServerErrorException)` (secret 없음)
|
||||
> - 클라이언트 응답: `{"error":{"code":"DEPENDENCY_5XX_SERVER"}}` (코드만)
|
||||
> - 원본 예외는 `cause` 로 서버 스택트레이스에만. (이 비유출을 단위 테스트가 검증.)
|
||||
|
||||
**전달 경로:** `exchange()` 가 throw → adapter·application 은 안 잡음 → 🌫️ web 의 `GlobalExceptionHandler` 가 잡아 `errorCode()` 만 읽어 클라이언트용 봉투로 변환(이 계약은 `DependencyFailureException` javadoc 에 명시). web 변환부 *세부*는 미지의 영역.
|
||||
|
||||
<details><summary>✅ 이해 점검</summary>
|
||||
|
||||
1. 외부 500 + body `{"token":"…"}` → ① 서버 로그 메시지 ② 클라이언트 응답을 각각 써보라. (E5)
|
||||
2. `HttpConnectTimeoutException` 을 `HttpTimeoutException` 보다 먼저 검사하는 이유? (상속 + instanceof 순서)
|
||||
</details>
|
||||
|
||||
---
|
||||
|
||||
## §11. 횡단 관심사 — trace / baggage 인터셉터 [신입 필수]
|
||||
|
||||
> **새 용어 — MDC:** 로그·추적용 "스레드별 메모장". **traceparent:** W3C 표준 분산추적 헤더(`00-traceid-spanid-flag`). **baggage:** 서비스 간 따라다니는 키-값. **allowlist:** 허용 목록(나머지는 차단).
|
||||
|
||||
외부로 나가는 모든 요청에 `TraceContextPropagationInterceptor` 가 *먼저* 끼어들어 MDC 의 추적 정보를 헤더로 붙인다 — 여러 서버를 관통하는 한 요청을 추적하려고. 단 **baggage 는 allowlist(`tenant_id`·`request_id`)만** 통과시키고 나머지(이메일·토큰 등)는 전송 전 박멸한다(보안 경계).
|
||||
|
||||
```text
|
||||
입력 MDC: trace_id, span_id, tenant_id, user_email(민감)
|
||||
출력 헤더: traceparent: 00-<trace_id>-<span_id>-00
|
||||
baggage: tenant_id=... (user_email 은 자동 탈락)
|
||||
```
|
||||
|
||||
> ⚠️ **[한계]** 현재 traceparent 의 샘플링 비트가 `00`(Not-Sampled)으로 하드코딩이다. 실제 운영 분산추적엔 OpenTelemetry SDK / Micrometer Tracing 연동으로 교체해야 한다(스켈레톤 한계).
|
||||
|
||||
---
|
||||
|
||||
## §12. [심화] 데코레이션 순서의 진실 — CB 는 retry 의 *바깥*
|
||||
|
||||
§5 Step 4 에서 `Retry.decorateSupplier` 로 감싼 뒤 `CircuitBreaker.decorateSupplier` 로 또 감쌌다. **마지막에 감싼 게 가장 바깥 껍질**이므로 최종 구조는:
|
||||
|
||||
```text
|
||||
CircuitBreaker( Retry( countingSupplier → 실제 호출 ) )
|
||||
└ 바깥 ─────────┘ └ 안쪽 ┘
|
||||
실행: cb.executeSupplier( () -> retry.executeSupplier( counting ) )
|
||||
```
|
||||
|
||||
**이게 무슨 뜻인가(★중요):** CB 가 가장 바깥이라, **한 논리적 호출(재시도 N번 포함)이 CB 에는 단 1건으로 기록된다.**
|
||||
- 일시 실패가 재시도로 복구되면 → CB 는 그 흔들림을 *안 보고* 성공 1건만 기록(블립 흡수).
|
||||
- 재시도까지 다 실패하면 → CB 에 실패 1건.
|
||||
- 즉 **재시도 각각이 따로 카운트되지 않는다.**
|
||||
|
||||
트레이드오프:
|
||||
- **CB-바깥(현재 코드):** CB 가 "이 논리적 호출이 최종 실패했나"만 본다. 재시도로 흡수된 일시 장애가 윈도우를 오염시키지 않음(장점). 대신 시도별 실패 *빈도*는 CB 가 못 봄.
|
||||
- **CB-안쪽(반대 배치):** 시도마다 CB 에 기록 → 한 번 실패한 호출이 윈도우를 재시도 횟수만큼 부풀림 + CB 가 OPEN 되면 남은 재시도가 `CallNotPermitted` 로 즉시 끊김.
|
||||
|
||||
> 🐞 **반드시 알아야 할 코드 모순(내 코드의 결함):** 실제 코드 주석(`OutboundHttpClient.java:212-216`)은 "Retry is OUTSIDE the CB so each retry attempt is independently CB-counted"(재시도가 따로 카운트됨)라고 적었지만, 바로 아래 `:225-231` 의 데코 순서는 **CB 를 바깥**에 둔다 → 주석의 주장과 정반대로 동작한다(재시도는 1건으로 묶임). 이 문서의 *이전 버전도 그 틀린 주석을 베껴* "재시도가 따로 잡힌다"고 잘못 썼었다. **➡️ 코드 소유 브랜치(`feature-outbound-http-client-baseline`)에서 주석을 고치거나, 의도가 "시도별 집계"였다면 데코 순서를 바꿔야 한다.** (면접에서 "CB 바깥이라 재시도가 따로 잡힌다"고 말하면 Resilience4j 아는 면접관이 바로 반박한다 — 1순위 위험.)
|
||||
|
||||
<details><summary>✅ 이해 점검 (E6)</summary>
|
||||
|
||||
같은 호출이 3번 재시도 끝에 실패했다. CB 슬라이딩 윈도우엔 실패가 몇 건 기록되나? (정답: 1건 — CB 가 바깥이라.)
|
||||
</details>
|
||||
|
||||
---
|
||||
|
||||
## §13. [심화] 배선 & Spring 메커니즘 — "그게 어떻게 가능한가"
|
||||
|
||||
**① `@ConfigurationProperties` + `@ConstructorBinding`** (`OutboundHttpSettings.java:36, 60`)
|
||||
|
||||
```java
|
||||
@ConfigurationProperties(prefix = "app.outbound.http") // 이 prefix 설정만 모음
|
||||
public record OutboundHttpSettings(
|
||||
@ConstructorBinding // setter 없이 "생성자로만" 주입
|
||||
Duration connectTimeout, Duration readTimeout, Duration globalCallTimeout, ...) {
|
||||
public OutboundHttpSettings { // compact 생성자 = 값이 들어오는 길목에서 검증
|
||||
if (connectTimeout == null || connectTimeout.isZero() || connectTimeout.isNegative())
|
||||
throw new IllegalArgumentException("APP_OUTBOUND_HTTP_CONNECT_TIMEOUT ... (D5)");
|
||||
}
|
||||
}
|
||||
```
|
||||
어떻게 가능한가: ① Spring Boot 의 **`Binder`** 가 `Environment`(env+yaml+프로퍼티)에서 prefix 키를 긁고 → ② **느슨한 바인딩**(`connect-timeout` ≡ `APP_OUTBOUND_HTTP_CONNECT_TIMEOUT` ≡ `connectTimeout`) → ③ 타입 변환(`"30s"`→`Duration`, `"10MB"`→`DataSize`) → ④ `@ConstructorBinding` 이라 생성자로만 주입 → 불변 → ⑤ compact 생성자 검증에서 `throw` 하면 빈 생성 실패 → `BeanCreationException` → **앱이 아예 안 뜸**(런타임 아님). 핵심: Binder 가 리플렉션으로 record 파라미터↔키를 자동 매칭하므로 내가 파싱 코드를 안 짠다.
|
||||
|
||||
**② `BeanPostProcessor` 타임아웃 강제기** (`OutboundHttpTimeoutEnforcer.java:39`) — 모든 빈 생성 직후 끼어드는 콜백. raw `RestClient`/`Builder` 빈을 발견하면 `BeanCreationException` 으로 기동 차단(타임아웃 없는 클라 봉쇄). `static @Bean` 인 이유: 다른 빈보다 먼저 만들어져야 검사 가능. **잔여 위험:** 메서드 *본문 안*의 인라인 `RestClient.create()` 는 빈이 아니라 못 잡는다 → 코드리뷰/import 게이트가 그 방어선. (그래서 §1 의 "원천 차단"은 정확히는 *빈으로 등록된* raw 클라 차단.)
|
||||
|
||||
**③ 타임아웃 2원화** (`OutboundHttpClient.java:95-99`) — connect timeout 은 JDK `HttpClient` 가, read timeout 은 `JdkClientHttpRequestFactory` 가 맡는다. *왜 두 군데?* JDK `HttpClient.Builder` 엔 connectTimeout 만 있고 *per-request read timeout API 가 없어서*, Spring factory 가 그 공백을 메운다(라이브러리 API 한계).
|
||||
|
||||
**④ RestClient 의 객체↔JSON 은 Jackson "만"이 아니다** — `.body(obj)` / `.body(responseType)` 는 RestClient 의 **`HttpMessageConverter` 체인**을 돌며 타입 + `Content-Type` 협상으로 컨버터를 고른다. JSON 이면 `MappingJackson2HttpMessageConverter` 가 담당할 뿐, XML/폼/String 도 같은 메커니즘. "RestClient=무조건 Jackson"으로 일반화하면 안 된다.
|
||||
|
||||
**⑤ Resilience4j `decorateSupplier`** — `Supplier` 를 감싸 능력 부여(§12). 의존성 이름별 인스턴스를 Registry 가 캐시.
|
||||
**⑥ Micrometer `MeterFilter`** (`OutboundHttpResilienceConfig.java`) — 지표 등록 *전*에 끼어들어 핵심 3종만 남기고 `DENY` + 태그 정규화(§16 "카디널리티").
|
||||
|
||||
---
|
||||
|
||||
## §14. [심화] 자료구조 & 배선 함정
|
||||
|
||||
| 쓴 것 | 코드 위치 | 왜 (한 겹 더) |
|
||||
|---|---|---|
|
||||
| `AtomicBoolean` | `OutboundHttpShutdownGuard.java:28-29` | 종료 스레드의 write 를 요청 스레드가 *즉시* 보게(가시성). JMM 상 plain boolean 은 다른 스레드가 캐시된 옛 값을 영원히 볼 수 있다 → `AtomicBoolean` 은 내부가 `volatile`+CAS 라 **happens-before** 로 가시화. (여기선 CAS 안 쓰니 `volatile boolean` 으로도 충분 — 표현 명시성 때문에 Atomic 선택) |
|
||||
| `ThreadLocal<CallContext>` | `OutboundRetryPolicy.java:59` | 호출이 한 스레드를 타고 가니 마감시한·메서드를 스레드별 격리. **누수 위험:** 톰캣 풀 스레드는 재사용되므로 `endCall()`(`remove()`)을 안 하면 다음 요청이 *이전 컨텍스트*를 봄(오판) + GC 안 됨 → `exchange()` `finally` 가 필수 |
|
||||
| `Set.of(GET,HEAD,PUT,DELETE)` | `:52-53` | 불변 + O(1) 멱등 판정 |
|
||||
| `int[] attemptCount = {0}` | `OutboundHttpClient.java:206` | 람다는 바깥 지역변수를 못 바꿈 → 1칸 배열의 *안*을 고침 |
|
||||
| `record CallContext` | `:136` | per-call 불변 컨텍스트 |
|
||||
| `Optional<Retry>/<CircuitBreaker>` | `:217-218` | "기능 off → 데코 없음"을 호출자가 반드시 처리하게 |
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class OutboundHttpClient {
|
||||
+baseline(...)$ OutboundHttpClient
|
||||
+exchange(method, uri, body, type) T
|
||||
+stream(method, uri, reader) T
|
||||
}
|
||||
class OutboundHttpShutdownGuard { +isShuttingDown() boolean }
|
||||
class OutboundRetryPolicy { +beginCall() +shouldRetry() boolean +endCall() }
|
||||
class OutboundHttpResilience { +circuitBreakerFor(name) Optional +retryFor(name) Optional }
|
||||
class OutboundHttpErrorMapper { +classify(name, failure) DependencyFailureException }
|
||||
class OutboundHttpSettings
|
||||
class SmartLifecycle { <<interface>> }
|
||||
|
||||
OutboundHttpClient --> OutboundHttpSettings : 설정
|
||||
OutboundHttpClient --> OutboundHttpShutdownGuard : 종료 검문
|
||||
OutboundHttpClient --> OutboundRetryPolicy : beginCall/endCall
|
||||
OutboundHttpClient --> OutboundHttpResilience : CB·Retry 공급
|
||||
OutboundHttpClient --> OutboundHttpErrorMapper : 예외 번역
|
||||
OutboundHttpResilience --> OutboundRetryPolicy : shouldRetry 를 재시도 조건으로
|
||||
OutboundRetryPolicy --> OutboundHttpShutdownGuard : 종료 시 중단
|
||||
OutboundHttpShutdownGuard ..|> SmartLifecycle : 구현
|
||||
```
|
||||
|
||||
생성/배선: `OutboundHttpClientConfig` 가 협력 빈들을 `@Bean` 등록(단 `OutboundHttpClient` 자체는 의존성마다 `baseline(...)` 으로 직접 생성), `OutboundHttpResilienceConfig` 가 `OutboundHttpResilience` 빈 + MeterFilter.
|
||||
|
||||
> ⚠️ **함정:** `OutboundRetryPolicy` 를 `OutboundHttpResilience`(판정)와 `OutboundHttpClient`(`beginCall` 적재)가 *다른 객체*로 들면, 판정 측 `callContextHolder.get()` 이 항상 `null` → **영영 재시도 안 함**(관문2 탈락). 반드시 **같은 빈 공유**.
|
||||
|
||||
---
|
||||
|
||||
## §15. [참조] 설정값 레퍼런스 (전부 `OutboundHttpSettings.java`)
|
||||
|
||||
| 키 (`app.outbound.http.*`) | 기본값 | 효과 |
|
||||
|---|---|---|
|
||||
| `connect-timeout` / `read-timeout` / `global-call-timeout` | **없음(필수)** | TCP 연결 / 한 번 읽기 / 재시도 포함 전체. 누락 시 기동 실패 |
|
||||
| `retry-enabled` / `circuit-breaker-enabled` | `false` / `false` | 재시도 / 서킷 활성. 하나라도 켜면 `MeterRegistry` 필수 |
|
||||
| `response-size-limit` | `10MB` | buffered 응답 메모리 상한 |
|
||||
| `retry.max-attempts` / `initial-backoff` / `backoff-multiplier` | `3` / `100ms` / `2.0` | 시도 횟수 / 첫 대기 / 지수 배수 |
|
||||
| `circuit-breaker.failure-rate-threshold` | `50%` | 이 실패율 넘으면 OPEN |
|
||||
| `…sliding-window-size` / `…minimum-number-of-calls` | `100` / `100` | 표본 범위 / 계산 최소 건수 |
|
||||
| `…wait-duration-in-open-state` / `…permitted-calls-in-half-open` | `60s` / `10` | OPEN 유지 / HALF_OPEN 시험 호출 수 |
|
||||
|
||||
---
|
||||
|
||||
## §16. [참조] 용어집 — 치트시트 (복습용)
|
||||
|
||||
> 학습용이 아니라 *남 앞에서 설명하기 직전* 빠르게 훑는 카드. 각 항목: 정의 → 한 줄로 말하면.
|
||||
|
||||
- **Port & Adapter** — application 이 선언한 인터페이스(Port)를 어댑터가 실제 기술로 구현. → *"핵심 로직은 인터페이스에만 의존하고 외부 기술은 어댑터가 갈아끼웁니다."*
|
||||
- **직렬화/역직렬화** — 객체 ↔ JSON. RestClient 가 메시지 컨버터로 처리. → *"객체를 넣으면 JSON 으로 바꿔 보내고 응답 JSON 을 객체로 돌려줍니다."*
|
||||
- **타임아웃 3종** — connect/read/global. → *"어디서 멈춰도 스레드가 안 묶이게 셋 다 끊습니다."*
|
||||
- **데드라인 예산** — 재시도 누적 시간의 절대 마감. *재시도 차단선*이지 하드컷 아님(§7). → *"재시도가 전체 마감을 못 넘게 하는 예산입니다."*
|
||||
- **멱등(idempotent)** — 여러 번 = 한 번(GET/PUT/DELETE). POST 는 비멱등. → *"멱등 메서드만 재시도해 이중 결제를 막습니다."*
|
||||
- **재시도/백오프/지터** — 다시 시도 / 대기 점증 / 무작위 섞기. → *"지수 백오프에 지터를 섞어 재시도 쏠림(thundering herd)을 막습니다."*
|
||||
- **서킷 브레이커 / CLOSED·OPEN·HALF_OPEN / 슬라이딩 윈도우** — 실패 잦은 의존성을 잠시 끊는 두꺼비집. → *"세 상태 FSM 으로 아픈 서버를 잠시 끊어 내 스레드·상대를 보호(가용성 목적 아님)."*
|
||||
- **fail-fast / fail-open / fail-closed** — 즉시 실패 / 삼키고 통과 / 막고 멈춤. → *"의존성 성격에 따라 정합성↔가용성 중 무엇을 지킬지 고릅니다."*
|
||||
- **`@ConfigurationProperties`+`@ConstructorBinding`** — 설정→불변 record + 생성자 검증 → *"값이 틀리면 앱이 아예 안 뜨게 합니다."*
|
||||
- **`SmartLifecycle`/phase** — 순서 보장 시작/종료. → *"가드를 phase 최대로 둬 가장 먼저 멈춰 신규 호출을 선차단합니다."*
|
||||
- **`BeanPostProcessor`** — 빈 생성 직후 후크. raw 클라 적발에 사용.
|
||||
- **데코레이터/`decorateSupplier`** — 함수를 감싸 능력 추가. CB 는 retry 의 *바깥*(§12).
|
||||
- **`ThreadLocal`** — 스레드 전용 칸. 풀 스레드면 `remove()` 안 하면 누수.
|
||||
- **`AtomicBoolean` / 가시성** — 스레드 간 즉시 보이는 boolean(volatile+CAS).
|
||||
- **MDC / traceparent / baggage / allowlist** — 추적 메모장 / W3C 추적 헤더 / 따라다니는 키값 / 허용 목록.
|
||||
- **시계열 DB / 카디널리티** — 시각별 측정값 수열 저장소 / 라벨 조합 가짓수. 무한값 라벨은 폭발 → 핵심 지표만(저카디널리티).
|
||||
- **cause chain** — `getCause()` 로 줄줄이 연결된 원인. → *"래퍼에 가려진 진짜 원인을 따라가며 분류합니다."*
|
||||
|
||||
---
|
||||
|
||||
## §17. 캐시 모듈 — Fail-Open 데코레이터 + 라우터 [신입 필수]
|
||||
|
||||
> §2 축의 *가용성 끝*. "캐시가 죽어도 본점은 정상 영업." HTTP 와 달리 캐시는 장애를 **삼켜서 미스인 척** 한다. 근거: [[wiki/concepts/fail-open-fail-closed.md]]
|
||||
|
||||
**한 줄 그림:** `CacheStore`(Port: get/put) ← `CacheBackend`(+backendId) ← {`RedisCacheStore`→`RedisClient`(프로젝트 구현), `FailOpenCacheStore`(데코레이터)}. `CacheStoreRouter` 가 logicalName→backendId→backend 로 라우팅.
|
||||
|
||||
> ⚠️ **HTTP 와 타입이 다르다:** 캐시 값은 전부 `String`. `get(key)` → `Optional<String>`, `put(key, value)`. **`Class<T>`·TTL·직렬화가 이 모듈엔 없다**(있다면 프로젝트의 `RedisClient` 구현 쪽). 흔한 오해: `get(key, Class)` 형태가 *아니다*.
|
||||
|
||||
**① Fail-Open 데코레이터 — 장애를 미스로 바꾸는 곳:**
|
||||
|
||||
```java
|
||||
// 📄 cache/FailOpenCacheStore.java:42-64 — 모든 백엔드를 감싸는 데코레이터
|
||||
@Override public Optional<String> get(String key) {
|
||||
try {
|
||||
Optional<String> value = delegate.get(key);
|
||||
dependencyLogger.logSuccess(delegate.backendId(), "cache", "get");
|
||||
return value;
|
||||
} catch (Exception ex) { // ← 백엔드가 던지는 모든 예외를 잡아
|
||||
dependencyLogger.logFailure(delegate.backendId(), "cache", "get", ex); // WARN(+correlation_id)
|
||||
return Optional.empty(); // ← 미스인 척 → 호출자는 DB 로 fallback
|
||||
}
|
||||
}
|
||||
@Override public void put(String key, String value) {
|
||||
try { delegate.put(key, value); /* logSuccess */ }
|
||||
catch (Exception ex) { dependencyLogger.logFailure(...); } // ← put 실패는 조용히 삼킴(no-op)
|
||||
}
|
||||
```
|
||||
→ Redis 가 죽어도 컨트롤러는 **예외를 안 받는다.** `get` 은 빈 Optional(미스), `put` 은 무시. 실패는 WARN 로그로만 *관측*된다(5xx 아님). 단 대량 동시 미스 → DB 쏠림(캐시 스탬피드) 위험은 서킷 병행으로 보완.
|
||||
|
||||
**② 백엔드는 안 삼킨다 — "장애"를 "미스"로 오인하지 않게:**
|
||||
|
||||
```java
|
||||
// 📄 cache/redis/RedisCacheStore.java:34-40 — 얇은 Redis 바인딩
|
||||
@Override public Optional<String> get(String key) {
|
||||
try { return client.read(key); } // RedisClient = 프로젝트가 구현하는 seam
|
||||
catch (Exception ex) { throw new CacheBackendException(BACKEND_ID, ex); } // 감싸서 *전파*
|
||||
}
|
||||
```
|
||||
`CacheBackendException` 메시지 = `"cache backend 'redis' access failed"`. **백엔드는 전파, 데코레이터(①)는 삼킴** — 이 2단 분리 덕에 "진짜 장애"와 "그냥 미스(키 없음)"가 안 섞인다.
|
||||
|
||||
**③ 라우터 = 설정 오류엔 fail-fast (fail-open 과 정반대 층):**
|
||||
|
||||
```java
|
||||
// 📄 cache/CacheStoreRouter.java:77-87 — 바인딩 안 된 logical 이름 접근
|
||||
private CacheStore resolve(String logicalName) {
|
||||
String backendId = bindings.get(logicalName);
|
||||
if (backendId == null)
|
||||
throw new AdapterDisabledException("cache",
|
||||
"no cache backend bound for logical cache '" + logicalName + "' — set app.cache.bindings...");
|
||||
return backends.get(backendId);
|
||||
}
|
||||
```
|
||||
생성 시엔 **중복 backendId / 없는 backend 바인딩 → `IllegalStateException`**(기동 차단). 즉 *런타임 장애*는 fail-open(①), *설정 실수*는 fail-fast(③) — 같은 모듈 안 두 정책.
|
||||
|
||||
**설정값과 역할:**
|
||||
|
||||
| 설정 | 역할 | 기본 |
|
||||
|---|---|---|
|
||||
| `app.cache.redis.enabled` | Redis 백엔드 빈 등록 여부(`@ConditionalOnProperty`) | `false` |
|
||||
| `app.cache.bindings.<논리명>=<backendId>` | 논리 캐시명 → 실제 백엔드 매핑 | 빈 맵 |
|
||||
|
||||
<details><summary>✅ 이해 점검</summary>
|
||||
|
||||
1. Redis 가 완전히 죽었다. `Router.get("worklog","k")` 의 반환과 컨트롤러가 받는 예외는? (Optional.empty / 예외 없음 → DB fallback)
|
||||
2. `RedisCacheStore` 는 왜 예외를 안 삼키고 `CacheBackendException` 으로 던지나? (장애를 "미스"로 오인 못 하게 — 삼킴은 데코레이터 책임)
|
||||
3. `app.cache.bindings.worklog=redis` 인데 `redis.enabled=false` 면? (기동 시 IllegalStateException — fail-fast)
|
||||
</details>
|
||||
|
||||
---
|
||||
|
||||
## §18. 메시징·아웃박스 모듈 — Fail-Open vs Fail-Closed (한 줄 차이) [신입 필수]
|
||||
|
||||
> §2 축의 *양쪽을 한 모듈에서 동시에* 보여주는 곳. 같은 Kafka 인데 **실시간 발행은 fail-open, 백그라운드 릴레이는 fail-closed**. 차이는 catch 블록이 `throw` 로 끝나느냐뿐. 근거: [[wiki/concepts/outbox-pattern.md]]
|
||||
|
||||
**① 실시간 발행 — Fail-Open (삼킴):**
|
||||
|
||||
```java
|
||||
// 📄 messaging/kafka/KafkaMessagePublisher.java:39-48
|
||||
@Override public void publish(OutboundMessage message) {
|
||||
try { sender.send(message); dependencyLogger.logSuccess("kafka","messaging","publish"); }
|
||||
catch (Exception ex) {
|
||||
dependencyLogger.logFailure("kafka","messaging","publish", ex); // 로깅만
|
||||
// ← throw 없음. 브로커가 죽어도 사용자 API 는 200.
|
||||
}
|
||||
}
|
||||
```
|
||||
왜 삼켜도 되나? 이미 같은 트랜잭션에서 **Outbox 테이블에 메시지가 영속화**됐기 때문(전달은 릴레이가 책임). 브로커 장애가 사용자 응답을 5xx 로 만들지 않는다.
|
||||
|
||||
**② 백그라운드 릴레이 — Fail-Closed (전파):**
|
||||
|
||||
```java
|
||||
// 📄 messaging/outbox/KafkaOutboxMessagePublishAdapter.java:56-71
|
||||
@Override public void publish(OutboxEvent event) {
|
||||
String envelope = OutboxEnvelopeJson.toJson(event);
|
||||
OutboundMessage message = new OutboundMessage(event.eventType(), event.aggregateId(), envelope);
|
||||
try { sender.send(message); dependencyLogger.logSuccess(...); }
|
||||
catch (RuntimeException ex) { dependencyLogger.logFailure(...); throw ex; } // ← 그대로 던짐
|
||||
catch (Exception ex) { dependencyLogger.logFailure(...);
|
||||
throw new RuntimeException("Kafka outbox publish failed", ex); } // checked 는 감싸 던짐
|
||||
}
|
||||
```
|
||||
왜 던져야 하나? 릴레이가 예외를 **봐야** 그 Outbox 레코드를 `FAILED`/`DEAD` 로 전이하고 트랜잭션을 롤백해 *재시도 루프*에 남긴다. 삼키면 레코드가 `IN_FLIGHT` 로 영영 박혀 큐가 조용히 막힌다(지표 이상도 없음).
|
||||
|
||||
> 🎯 **단 한 줄의 차이:** 둘 다 `logFailure` 를 부른다. 실시간(①)의 catch 는 *그냥 끝*나고, 릴레이(②)의 catch 는 *`throw` 로 끝*난다. 이게 fail-open ↔ fail-closed 의 전부다.
|
||||
|
||||
**③ 봉투 직렬화 — Jackson 없이 손으로:**
|
||||
|
||||
```java
|
||||
// 📄 messaging/outbox/OutboxEnvelopeJson.java:49-58 — D12 wire format
|
||||
public static String toJson(OutboxEvent event) {
|
||||
return "{"
|
||||
+ "\"eventId\":\"" + escape(event.eventId()) + "\","
|
||||
+ /* eventType, aggregateId, occurredAt, correlationId, idempotencyKey — 모두 escape */
|
||||
+ "\"payload\":" + event.payload() // ← payload 는 *이미 JSON* 이라 escape 없이 raw 삽입
|
||||
+ "}";
|
||||
}
|
||||
```
|
||||
`payload` 는 이미 직렬화된 JSON 이라 그대로(이중 인코딩 방지), 나머지 문자열은 `escape()`(RFC 8259 제어문자). 스켈레톤은 `jackson-databind` 를 안 싣는다.
|
||||
|
||||
**④ on/off 게이팅 — 같은 플래그가 real ↔ Disabled 빈을 교체:**
|
||||
|
||||
```java
|
||||
// 📄 messaging/kafka/KafkaAdapterConfig.java:30-41 — @ConditionalOnProperty 한 쌍
|
||||
@Bean @ConditionalOnProperty(name="app.messaging.kafka.enabled", havingValue="true", matchIfMissing=false)
|
||||
public MessagePublisher kafkaMessagePublisher(...) { return new KafkaMessagePublisher(...); }
|
||||
|
||||
@Bean @ConditionalOnProperty(name="app.messaging.kafka.enabled", havingValue="false", matchIfMissing=true)
|
||||
public MessagePublisher disabledMessagePublisher() { return new DisabledMessagePublisher(); }
|
||||
```
|
||||
플래그 하나로 *정확히 하나*의 빈만 등록된다. 꺼지면(기본) `DisabledMessagePublisher` 가 올라가, 누가 실수로 호출하면 `AdapterDisabledException("kafka")` 를 던진다(Layer 3 — Layer 1 게이팅이 뚫렸을 때의 최후 방어선).
|
||||
|
||||
**설정값:** `app.messaging.kafka.enabled`(false) — 실시간/릴레이 두 포트를 *한 플래그*로 동시 제어. `app.messaging.kafka.brokers`(켜면 CSV `host:port` 필수, regex 검증).
|
||||
|
||||
> 🧑🏫 **한마디:** "같은 Kafka 인데 왜 한쪽은 삼키고 한쪽은 던지나?"는 단골 질문. 답: **누가 그 실패를 책임지느냐**. 실시간은 Outbox 가 책임지니 삼켜도 되고, 릴레이는 *자기가* 마지막 책임자라 던져 재시도/경보로 이어가야 한다.
|
||||
|
||||
<details><summary>✅ 이해 점검</summary>
|
||||
|
||||
1. 브로커 순단 시 두 발행자의 동작 차이를 *코드 한 줄*로? (catch 가 `throw` 로 끝나는가)
|
||||
2. `app.messaging.kafka.enabled` 미설정 시 어떤 빈이 등록되고 호출하면? (Disabled* → AdapterDisabledException)
|
||||
3. `OutboxEnvelopeJson` 이 `payload` 만 escape 안 하는 이유? (이미 JSON → 이중 인코딩 방지)
|
||||
</details>
|
||||
|
||||
---
|
||||
|
||||
## §19. [심화] 더 깊이 — 이 코드 *밖*의 5가지 (면접 천장 뚫기)
|
||||
|
||||
> 여기부터는 ca-tmpl 에 **구현되어 있지 않은** 주제다(skeleton 범위 밖). 면접에서 "그 다음은?"으로 꼬리를 물 때 막히지 않도록 *왜 이 코드엔 없고, 있으면 어떻게 되는지*만 정리한다. (canonical 프로젝트 사실 아님 — 일반 지식 + 이 설계와의 연결.)
|
||||
|
||||
**1. Bulkhead(동시성 격리) — 지금 빠진 가장 큰 구멍.** 서킷·타임아웃은 있지만 *동시 호출 수 제한*이 없다. 동기 RestClient 는 호출당 스레드를 점유하므로, 한 의존성이 느려지면 서킷이 *열리기 전까지* 호출 스레드가 무더기로 묶인다. Resilience4j `Bulkhead`(세마포어/스레드풀)로 "이 의존성엔 동시 N개까지"를 막아야 완전하다. → *"타임아웃+서킷은 '오래 걸리는 것'을, Bulkhead 는 '한꺼번에 많은 것'을 막습니다."*
|
||||
|
||||
**2. Idempotency-Key 프로토콜 — POST 재시도의 진짜 해법.** 지금은 "POST 재시도 전면 금지"로 *회피*한다(§7 관문2). 진짜는: 클라이언트가 요청마다 고유 키(UUID)를 만들어 *재전송 시 동일 키 유지* → 서버가 그 키로 중복을 제거. 그러면 POST 도 안전하게 재시도 가능. → *"멱등 키 계약이 서면 비멱등 메서드도 재시도할 수 있습니다. 지금은 그 계약이 없어 보수적으로 막은 겁니다."*
|
||||
|
||||
**3. 재시도 예산(retry budget) — retry storm 방지.** per-call deadline(§7)은 *한 요청*의 재시도만 제한한다. *서비스 전역*으로 "전체 요청의 N%만 재시도 허용"하는 상한(Google SRE retry budget)은 없다. 장애 시 모두가 재시도하면 트래픽이 증폭돼 상대를 더 무너뜨린다(retry storm). → *"deadline 은 한 건을, retry budget 은 전체를 지킵니다."*
|
||||
|
||||
**4. 분산추적 샘플링 — traceparent `00` 의 실체.** §11 에서 샘플링 비트가 `00`(not-sampled) 하드코딩이라 했다. 실무는 head-based(시작 시 결정) vs tail-based(끝나고 느린 것만) 샘플링 + 부모 결정 전파(ParentBased)가 일관돼야 한다. 지금은 그게 없어 *수집이 안 된다.* OpenTelemetry SDK 로 교체 필요. → *"추적 헤더는 붙지만 샘플링 결정이 죽어 있어, 실제 백엔드 연동 전엔 트레이스가 안 모입니다."*
|
||||
|
||||
**5. 커넥션 풀 / HTTP/2 멀티플렉싱.** JDK `HttpClient` 의 connection pool·executor 를 *명시 설정하지 않아* 기본값에 의존한다(skeleton 한계). HTTP/2 면 한 커넥션에 다중 스트림이 흐르는데, 이때 head-of-line blocking 과 read-timeout 의 상호작용이 미묘하다. 동시성 상한은 결국 timeout+서킷으로 *간접* 보호될 뿐 명시적 풀 튜닝은 없다. → *"커넥션 재사용·풀 사이즈는 아직 기본값이라 고부하에선 별도 튜닝이 필요합니다."*
|
||||
|
||||
> 🧑🏫 **한마디:** 1~3 은 "구현된 것의 *다음 단계*", 4~5 는 "스켈레톤이라 *기본값에 맡긴* 부분". 면접에서 이걸 *먼저* "여기까진 했고, 다음은 Bulkhead/멱등키/재시도예산입니다"로 말하면 천장이 아니라 로드맵이 된다.
|
||||
|
||||
---
|
||||
|
||||
## 그래서 어떤 문제로 "정의" 했나
|
||||
|
||||
`ca-tmpl` 은 연동 문제를 **"외부 시스템의 장애·지연이 우리 서버의 스레드 잠식이나 데이터 정합성 훼손으로 전이되지 않도록 강력한 완충 경계(Isolation Boundary)를 강제"** 로 정의했다. 그래서:
|
||||
|
||||
- **물리 리소스 제약:** `bufferedClient`/`streamingClient` 격리 + `ResponseSizeBoundingInterceptor` 로 힙 통제.
|
||||
- **시간 예산:** connect/read 외에 deadline 예산으로 재시도 무한 대기 차단.
|
||||
- **Optional 빈 게이팅 & 센티넬:** 비활성 의존성 호출 시 `AdapterDisabledException` 으로 기동 거부(Layer 3).
|
||||
|
||||
### 실제 구현·검증 범위 (`locally-verified`)
|
||||
|
||||
`adapter-outbound` 모듈에 구현되어 있고 단위 테스트로 검증됨(prod 배포·측정 없음): `OutboundHttpClientTest`(재시도/CB/셧다운/사이즈), `OutboundHttpErrorMapperTest`(예외 매핑), `OutboundHttpResilienceTest/ConfigTest`, `OutboundRetryPolicyTest`, `OutboundHttpShutdownGuardTest`, `OutboundHttpSettingsTest`, `TraceContextPropagationInterceptorTest` 등.
|
||||
(상세는 canonical [[wiki/projects/ca-tmpl/data-layer-persistence-cache-outbound.md]] §Outbound HTTP Client.)
|
||||
|
||||
> [!WARNING]
|
||||
> traceparent 샘플링 비트 `00` 하드코딩(§11). 실제 분산추적은 OpenTelemetry/Micrometer Tracing 으로 교체 필요.
|
||||
> §12 의 CB 데코 주석 모순은 *코드* 결함 — 소유 브랜치에서 정정 필요.
|
||||
|
||||
---
|
||||
|
||||
## 자가 점검 — 다시 처음 장면으로
|
||||
|
||||
1. **[멱등성]** `Idempotency-Key` 명세가 없는 `POST /payments` 에 재시도를 켜두면, 어느 안전장치(어느 관문)가 거부하나? (§7 관문2)
|
||||
2. **[캐시 Fail-Open]** Redis 완전 다운 시 홈 API 호출 → `FailOpenCacheStore` 내부에서 무슨 일이? 컨트롤러가 받는 최종 예외는? (예외 없음 → DB fallback, §17)
|
||||
3. **[우아한 종료]** SIGTERM 시 `SmartLifecycle` 대신 `ContextClosedEvent` 로 깃발을 세우면 어떤 비결정 순서 오류가? (§6)
|
||||
4. **[아웃박스]** 브로커 순단 시 `KafkaMessagePublisher`(실시간) vs `KafkaOutboxMessagePublishAdapter`(릴레이) 가 각각 왜 삼킴/전파를 택하나? (§18)
|
||||
5. **[대용량]** 100MB CSV 를 `get(uri, Class)` 로 받으면 무슨 에러? 우회 API 는? (size 예외 → `stream()`, §9)
|
||||
6. **[서킷-재시도]** 한 호출이 3번 재시도 끝에 실패했다. CB 윈도우엔 실패 몇 건? (1건 — §12)
|
||||
|
||||
---
|
||||
|
||||
## Sources (이 설명의 출처 — 모두 canonical)
|
||||
|
||||
- [[wiki/concepts/fail-open-fail-closed.md]] — 실패 처리 설계 철학 및 트레이드오프
|
||||
- [[wiki/concepts/idempotency.md]] — RFC 9110 HTTP 멱등성 및 재시도 게이트
|
||||
- [[wiki/concepts/circuit-breaker.md]] — 서킷 브레이커 FSM 상태 전이 및 저카디널리티 지표 필터링
|
||||
- [[wiki/concepts/outbox-pattern.md]] — 트랜잭셔널 아웃복스 및 릴레이의 정합성 보장
|
||||
- [[wiki/concepts/distributed-tracing-baggage.md]] — MDC 트레이싱 전파와 배기지 보안 필터
|
||||
- [[wiki/concepts/spring-smart-lifecycle.md]] — SmartLifecycle 을 통한 Graceful Shutdown
|
||||
- [[wiki/projects/ca-tmpl/data-layer-persistence-cache-outbound.md]] — **§Outbound HTTP Client: 코드 사실 SSOT** (입출력·예외 매핑·자료구조·Spring 메커니즘·설정·검증, `locally-verified`)
|
||||
- [[wiki/projects/ca-tmpl/config-and-adapter-templates.md]] — adapter on/off 게이팅 결정
|
||||
@@ -1 +0,0 @@
|
||||
../../vault/30-knowledge/explainer/adapter-persistence.md
|
||||
@@ -0,0 +1,18 @@
|
||||
---
|
||||
title: (강사 설명) adapter-persistence 모듈
|
||||
source_type: explainer
|
||||
status: raw
|
||||
confidence: unknown
|
||||
tags: [explainer, ca-tmpl, persistence]
|
||||
related_projects: [ca-tmpl]
|
||||
last_reviewed:
|
||||
---
|
||||
|
||||
# (강사 설명) adapter-persistence 모듈
|
||||
|
||||
> Layer: `wiki/explainer/` — **derived(파생) 교육 문서.** 개인 이해용이며 외부 공개 대상이 아니다.
|
||||
> 사실·근거·검증 등급은 여기서 만들지 않고 canonical 에서 가져온다.
|
||||
|
||||
**아직 작성되지 않은 스텁입니다.** `[[wiki/explainer/adapter-outbound]]` 와 같은 ca-tmpl 모듈별
|
||||
설명 시리즈의 자리만 잡아둔 상태이며, 본문은 canonical(`[[wiki/projects/ca-tmpl]]`)을 경유해
|
||||
작성해야 합니다.
|
||||
@@ -1 +0,0 @@
|
||||
../../vault/30-knowledge/explainer/adapter-web.md
|
||||
@@ -0,0 +1,18 @@
|
||||
---
|
||||
title: (강사 설명) adapter-web 모듈
|
||||
source_type: explainer
|
||||
status: raw
|
||||
confidence: unknown
|
||||
tags: [explainer, ca-tmpl, api-design]
|
||||
related_projects: [ca-tmpl]
|
||||
last_reviewed:
|
||||
---
|
||||
|
||||
# (강사 설명) adapter-web 모듈
|
||||
|
||||
> Layer: `wiki/explainer/` — **derived(파생) 교육 문서.** 개인 이해용이며 외부 공개 대상이 아니다.
|
||||
> 사실·근거·검증 등급은 여기서 만들지 않고 canonical 에서 가져온다.
|
||||
|
||||
**아직 작성되지 않은 스텁입니다.** `[[wiki/explainer/adapter-outbound]]` 와 같은 ca-tmpl 모듈별
|
||||
설명 시리즈의 자리만 잡아둔 상태이며, 본문은 canonical(`[[wiki/projects/ca-tmpl]]`)을 경유해
|
||||
작성해야 합니다.
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user