Files
clean-architecture-backend-…/docs/manual/10-capabilities.md
T
DongHyeonka 1400dc1506 feat!: 남은 리뷰 발견을 고치고 개발 매뉴얼과 기능 생성 명령을 더한다
문제: High·P1을 고친 뒤에도 P2·P3 약 90건이 남았다. 연결·구독·메시지
크기 상한이 없는 전송(WebSocket·gRPC·GraphQL deadline), 낙관적 충돌의
500, upsert 경쟁, Mongo 무제한 timeout, 샘플 목록 N+1, 갈라진 복사본
(TenantId 3벌, 이벤트 ID 문법 5곳, SQLState 표 2벌), 문서를 읽는 PR
테스트와 캐시를 막는 lane 설정 등이다. 새 기능을 어디에 어떤 순서로
만드는지 알려 주는 문서와 도구가 없었다. MinIO 공식 이미지가 사라져
객체 저장소 lane이 돌지 않았다.

방법: 영역별 묶음으로 실패 테스트를 먼저 쓰고 고쳤다. 고치는 중에 찾은
결함도 함께 고쳤다(durable operation id가 UUIDv4라 이벤트가 전부 DEAD,
S3 어댑터 생성·작은 chunk 읽기 실패, Redis 조건부 기록의 EVALSHA 권한).
MinIO는 pgsty/minio를 digest로 고정했다(Chainguard는 태그·실행 사용자·
mc 이미지 문제로 버림). docs/manual/에 작업 순서와 판단 지점을 쓰고,
scripts/new-feature.sh가 5개 leaf에 뼈대를 만든다. 생성→빌드→통과
왕복을 verifyFeatureScaffold가 mainCheck에서 본다. 묶음별 결과와
결정은 리뷰 README 14절에 있다.

위험·한계: 파생 서비스 동작이 바뀐다. JDBC batch 50 기본, 운영 jar에서
H2 제거, 트랜잭션 30초 제한, 격리 수준을 Hikari에서 고정, gRPC·
WebSocket·GraphQL 새 한도, correlation ID 규칙 밖이면 서버가 교체,
샘플 키 오류 코드 IDEMPOTENCY_KEY_INVALID. 새 leaf 두 개
(composition:durable-operation, adapter:inbound:messaging)와 새
마이그레이션(postgresql V20·V21, notification V11·V12, sample V8_1,
grpc-ledger V002)이 생긴다. V21 유일 인덱스는 기존 중복이 있으면
실패한다(runbook에 확인 쿼리).

검증: ci, mainCheck(생성 명령 왕복 포함), integrationCheck(MinIO 포함
전 컨테이너 lane), -p optional-platforms ci integrationCheck 통과.

Refs: docs/reviews/2026-11-01-maturity-review/README.md 14절
BREAKING CHANGE: JDBC batch 기본 켜짐, H2 운영 의존 제거, 트랜잭션
기본 제한 30초, gRPC·WebSocket·GraphQL 서버 한도 기본값 추가,
샘플 Idempotency-Key 오류 코드 변경.
2026-11-03 19:52:06 +09:00

3.6 KiB

10. capability 추가·제거

핵심

JPA·Redis·Kafka·알림·파일 서버 같은 부가 기능은 의존성 한 줄로 켜지고, 그 줄을 지우면 사라지는 모듈이다. 서비스는 src/app-bootstrap/build.gradle에서 필요한 모듈만 runtimeOnly로 고른다. 기본 조립은 web, 운영 관측, cores, support/identifier뿐이다. JPA도 한 줄로 켠다.

app-bootstrap/build.gradle
  runtimeOnly project(':adapter:outbound:persistence-jpa')   ← 이 한 줄
        │
        ▼
  모듈의 META-INF/spring/...AutoConfiguration.imports  →  자동 설정  →  포트 구현 bean
        │
        ▼
  기능 XConfig의 @ConditionalOnBean(포트)  →  유스케이스·엔드포인트가 켜진다

정본: AGENTS.md 「부가 기능(capability) 모듈 규칙」(완료 기준 7개), docs/superpowers/specs/2026-09-25-capability-module-packaging-design.md, 현황은 docs/capability-status.md.

켜기

  1. src/app-bootstrap/build.gradle의 해당 runtimeOnly 줄 주석을 푼다.
  2. lockfile 갱신: ./gradlew :app-bootstrap:resolveAndLockAll --write-locks, 확인 ./gradlew verifyDependencyLocks.
  3. 모듈 README의 env 키를 채운다. 키 목록 정본은 docs/registries/env-keys.yaml.
  4. 기본값은 config/module-defaults/<모듈>.yml에 이미 있다. 서비스 값만 덮어쓴다.
  5. ./gradlew :app-bootstrap:check architectureCheck. 공개 경로가 생기면 verifyPublicPathSnapshot.

끄기

줄을 지우고 lockfile을 갱신한다. 그 모듈의 포트에 기대던 기능(@ConditionalOnBean)은 함께 꺼진다. 기능이 꺼지면 안 되는데 꺼졌다면, 그 기능이 다른 구현을 가져야 한다는 신호다.

판단: 서비스 코드가 모듈 타입을 직접 불러도 되나

  • 기본값: 안 된다. 서비스 코드는 application-core 포트만 부른다. 그래야 runtimeOnly로 받을 수 있다.
  • 예외: 라이브러리형 기능(모듈 타입을 상속·호출해야 하는 것)은 서비스의 adapter leaf에서만 implementation으로 받는다. 예: 서비스 persistence leaf가 persistence-jpa의 감사 base 타입을 상속.

새 capability 모듈을 만들 때

03장에서 ②(기능 leaf)를 골랐을 때만 해당한다. 완료 기준 7개를 모두 지킨다.

# 기준 확인
1 서비스는 포트만 호출 runtimeOnly로 컴파일되는가
2 자기 AutoConfiguration.imports, 필요하면 enabled 스위치, 순서는 afterName 모듈 자동 설정 테스트
3 켜면 완전히 동작. 동작하지 않는 설정 키는 두지 않는다 설정 바인딩 테스트
4 설정 prefix 하나(app.<모듈>), StrictSettingsBinder, 검증은 record compact constructor
5 포트 계약 테스트를 fake와 실제 adapter가 모두 통과, 실 벤더(Testcontainers) 1개 이상 strict lane(08장)
6 README: 제공하는 것, 추가할 한 줄, env 키
7 이 모듈을 아는 곳은 모듈 자신뿐. bootstrap scan·스위치 목록에 등록하지 않는다 줄을 지우면 기능이 완전히 사라지는가

등록할 공용 파일: src/config/architecture/modules.json(leaf와 허용 edge), src/settings.gradle이 읽는 디렉터리 매핑, app-bootstrap의 허용 edge, 새 leaf lockfile. registry가 허용하지 않은 edge는 architectureCheck(의존 방향)가 막는다.

지금 이해하면 되는 것

  • 켜기 = runtimeOnly 한 줄 + lockfile + env 키.
  • 서비스 코드는 포트만 부른다.
  • 새 capability는 완료 기준 7개. 업무 기능은 capability로 만들지 않는다(03장).