96 lines
5.0 KiB
Markdown
96 lines
5.0 KiB
Markdown
---
|
|
title: blog-topic / spring-conditional-on-property-optional-adapter-template-2026-06-09
|
|
source_type: blog-topic
|
|
status: raw
|
|
related_branches: [feature-integration-adapter-templates]
|
|
related_projects: [ca-tmpl]
|
|
tags: [blog-topic, ca-tmpl, spring, clean-architecture, adapter, template]
|
|
created: 2026-06-09
|
|
status_label: ready-for-canonical
|
|
target_audience: backend-engineer
|
|
inspiration_url:
|
|
archive_url:
|
|
---
|
|
|
|
# blog-topic: heavy SDK 없이 "선택형 어댑터 템플릿" 을 경량 skeleton 에 싣기
|
|
|
|
> Layer: `raw/blog-topics/` — 구현·설계·트러블슈팅 기반 글감(채용공고 아님).
|
|
|
|
## Parent / 부모
|
|
|
|
- [[raw/branch-notes/feature-integration-adapter-templates]]
|
|
|
|
## 글감 한 줄
|
|
|
|
Clean Architecture 템플릿에 Kafka/Redis/Slack/Email 같은 선택형 어댑터를 "기본 비활성 + 같은 방식으로 실패/관측" 하도록 싣되, 실 SDK 는 안 넣고 `@ConditionalOnProperty` + integration seam + disabled sentinel + ArchUnit 3계층으로 계약만 보장하는 패턴.
|
|
|
|
## 다룰 내용
|
|
|
|
1. 문제: 선택형 어댑터를 전부 기본 dependency 로 넣으면 skeleton 이 무거워지고, 빼면 "붙일 때 제각각" 실패한다.
|
|
2. 결정: optional module/template 기본 + disabled-default. 대안 비교(Java SPI=on/off 표현 불가·DI 미통합, `@Profile`=boolean 시맨틱 부재, Feature flag(FF4J/Togglz)=runtime branching 이라 startup on/off 와 시맨틱 다름)를 왜 제쳤는지.
|
|
3. 3계층 검출:
|
|
- Layer 1 `@ConditionalOnProperty(matchIfMissing=false)` 로 bean-gating + 누락=disabled 명시.
|
|
- Layer 2 ArchUnit 로 (a) application→optional adapter import 격리, (b) optional adapter `@Bean` 의 `@ConditionalOnProperty` gating 강제. 정적 검사의 한계도 함께.
|
|
- Layer 3 disabled sentinel 이 `AdapterDisabledException` 으로 fail-fast.
|
|
4. integration seam 패턴: `KafkaSender`/`RedisClient`/... interface 만 제공 → fork 프로젝트가 SDK + 구현 주입. 템플릿은 계약 owner, 소비자는 연동 owner.
|
|
5. fail-open vs fail-closed: 알림/캐시는 부수효과라 fail-open(5xx 미승격), Redis unavailable=cache-miss, 로거 시그니처에서 payload 인자를 없애 PII 누출을 구조적으로 차단.
|
|
6. 운영 계약 정합: error-codes/env-keys registry 에 row 추가, startup `REQUIRED_ADAPTER_DISABLED` 와 runtime `ADAPTER_DISABLED` 를 lifecycle 로 분리.
|
|
7. 함정: B7 같은 "outbound 패키지 public method return-type" ArchUnit rule 이 `@Configuration` `@Bean` factory 를 과탐 → rule scoping(약화 아님, 정밀화). [[raw/errors/archunit-b7-configuration-bean-factory-return-type-2026-06-09]].
|
|
|
|
## 왜 쓸 만한가
|
|
|
|
- "라이브러리를 안 넣고도 계약을 강제" 하는 구체 사례 — 면접/포트폴리오에서 설계 판단(경량성 vs 계약 강제) 을 보여줄 수 있다.
|
|
|
|
## 트리거 / Trigger
|
|
|
|
- 트리거 유형: `branch-work`
|
|
- 트리거 날짜: 2026-06-09
|
|
- 트리거 연결 노트: [[raw/branch-notes/feature-integration-adapter-templates]]
|
|
|
|
## 글감 / Topic seed
|
|
|
|
- 한 문장 요지: optional adapter를 기본 비활성 seam으로 싣고, 실제 SDK는 fork/consumer가 붙이게 하되 실패 언어와 gating은 skeleton이 제공한다.
|
|
- 예상 제목 후보:
|
|
- 선택형 어댑터 템플릿을 가볍게 싣는 방법
|
|
- `@ConditionalOnProperty`로 optional adapter 계약 만들기
|
|
|
|
## 핵심 주장 후보 / Claim candidates
|
|
|
|
- 사실 후보:
|
|
- raw branch는 optional adapter template과 disabled sentinel, ArchUnit scope를 다룬다.
|
|
- 의견/해석 후보:
|
|
- 선택형 어댑터의 핵심은 SDK 포함 여부가 아니라 disabled 상태의 실패 방식과 관측 가능성이다.
|
|
|
|
## Outline seed
|
|
|
|
1. 선택형 adapter를 모두 dependency로 넣으면 skeleton이 무거워진다.
|
|
2. `@ConditionalOnProperty`, integration seam, disabled sentinel의 역할을 나눈다.
|
|
3. ArchUnit rule은 정적 검출 범위와 한계를 함께 적어야 한다.
|
|
|
|
## Canonical 전환 후보 / Canonical extraction candidates
|
|
|
|
- `wiki/projects/ca-tmpl/config-and-adapter-templates.md` 후보:
|
|
- optional adapter template과 ConditionalOnProperty 기반 gating.
|
|
- 필요한 추가 검증:
|
|
- 실제 adapter template module, ArchUnit rule, disabled sentinel 구현 여부.
|
|
|
|
## Sources / 근거 후보
|
|
|
|
- [[raw/branch-notes/feature-integration-adapter-templates]]
|
|
- [[raw/errors/archunit-b7-configuration-bean-factory-return-type-2026-06-09]]
|
|
|
|
## 미해결 / Unknown
|
|
|
|
- 아직 확인해야 할 사실: 현재 ca-tmpl 코드에 optional adapter template이 구현됐는지.
|
|
- 과장하면 안 되는 부분: heavy SDK 없이 계약을 설계한 것과 실제 adapter 구현을 분리한다.
|
|
|
|
## Related / 관련
|
|
|
|
- 관련 branch: [[raw/branch-notes/feature-integration-adapter-templates]]
|
|
|
|
## Decision / 처리 결정
|
|
|
|
- 액션: `promote-to-canonical`
|
|
- 이유: `wiki/projects/ca-tmpl/config-and-adapter-templates.md` 에 optional adapter template / `@ConditionalOnProperty` 글감으로 반영했다.
|
|
- 다음 단계: target canonical이 아직 `draft` 이므로 `blogify` 전 실제 adapter template 구현·ArchUnit rule·disabled sentinel 존재 여부를 재검증한다.
|