Files

T

DongHyeonkaandClaude Opus 5 1099834617 chore: snapshot working tree before harness removal

미추적 파일과 미커밋 수정을 전부 담아 pre-harness-removal 태그의 복구
범위를 확보한다. .agents/skills/writing-natural-korean 9개와
korean-technical-blog-skills-bundle-v1 61개가 여기 포함된다.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

2026-08-07 14:19:24 +09:00

153 KiB

Executable File

Raw Blame History

실행 가능한 클린 아키텍처 — 선언이 아니라 빌드가 지키는 경계

ca-tmpl을 만들 때 가장 먼저 정한 기준은 “경계를 어긴 코드가 실제로 빌드를 통과하지 못해야 한다”는 것이었습니다. 클린 아키텍처라는 이름을 붙여도 컨트롤러가 리포지토리를 직접 참조하는 코드는 얼마든지 만들 수 있기 때문입니다. 그래서 책임을 패키지로 나누는 데서 멈추지 않고 19개 모듈의 소스 의존 방향을 코어 쪽으로 고정했습니다. 금지된 의존은 컴파일·Gradle 검증·아키텍처 테스트 중 알맞은 지점에서 실패하도록 만들었습니다. 이 글에서는 제가 왜 이런 구조를 택했고, 각 장치가 어떤 위반을 막도록 구현했는지 설명합니다.

그래서 무엇을 해결하는가

제가 ca-tmpl에서 해결하려 한 문제는 패키지 이름만으로는 경계를 강제할 수 없다는 점이었습니다. controller·service·repository를 잘 나눠도 컨트롤러가 JPA 리포지토리를 직접 참조할 수 있습니다. 클래스패스에 타입이 있으면 코드는 그대로 컴파일되고, 리뷰에서 놓치면 병합도 막지 못합니다. 그래서 사람이 기억하던 규칙을 javac, Gradle 검증, 아키텍처 테스트가 실행하는 실패 조건으로 옮겼습니다.

읽고 나면 다음을 할 수 있습니다.

런타임 호출 방향과 소스 의존 방향을 구분하고 DIP가 정확히 무엇을 역전하는지 설명할 수 있습니다.
멀티모듈 클래스패스 격리, Gradle 의존 화이트리스트, ArchUnit(자바 코드 구조 규칙을 테스트로 검사하는 라이브러리) 규칙이 각각 어떤 위반을 잡고 어떤 위반을 놓치는지 판별할 수 있습니다.
자신의 팀 상황에서 이 강제 장치들이 이익인지 순비용인지 판단할 수 있습니다.

설명에서는 ca-tmpl의 멀티모듈 구조, 의존 정책, 아키텍처 테스트를 중심으로 합니다. 운영 트래픽이나 장애 상황에서의 실측 효과는 다루지 않습니다.

설명은 컴파일되는 경계 위반에서 시작합니다. 이어서 런타임 호출과 소스 의존, 포트와 링을 구분하고 ca-tmpl의 모듈 구조와 요청 흐름을 보여 줍니다. 마지막에는 빌드가 실제로 막는 위반과 여전히 사람이 확인해야 하는 영역을 나눕니다.

문제가 생기는 맥락과 제약 — 경계는 왜 보이지 않게 되는가
핵심 판단 기준과 멘털 모델 — 세 가지 방향, 포트, 링, 모듈 판단 기준
해결 방식이 동작하는 과정 — 19개 모듈, 모델 분리, 세 겹 게이트
구현으로 설명하는 요청 경로 — Feed 조회와 여섯 횡단 계약
어떻게 검증할 것인가 — 테스트 4층, test-the-test, break-it, 공급망
대안, 트레이드오프, 실패 조건 — 다섯 결정의 반대편과 강제의 한계
실무 적용 체크리스트 — 상황 판별, 점진 적용, 중단·롤백 기준

문제가 생기는 맥락과 제약

경계가 무너지는 순간 — 컴파일되는 위반

제가 가장 먼저 막으려 한 것은 아래처럼 경계를 건너뛰어도 컴파일되는 코드였습니다.

@RestController
class WorkLogController {
    private final JpaWorkLogRepository repository;
}

겉으로는 필드 하나를 바로 주입한 코드지만 실제 요청은 유스케이스와 도메인을 모두 건너뜁니다. 이런 우회를 빌드에서 막으려면 다음 네 가지 질문에 답해야 했습니다.

컴파일러가 허용하는가? 타입만 맞으면 허용합니다.
기존 테스트가 잡는가? 경계 규칙이 없으면 놓칠 수 있습니다.
리뷰에서 놓치면 어떻게 되는가? 그대로 머지됩니다.
반년 뒤 이 의존은 누가 기억하는가? 아무도 기억하지 못합니다.

리뷰에서 놓친 의존이 하나씩 쌓이면 그림으로 그려 둔 아키텍처와 실제 코드가 서서히 달라집니다. 이런 변화를 아키텍처 침식(erosion)이라고 합니다. 최상위 폴더를 controller·service·repository로만 나눈 구조에서는 주문 기능 하나를 고칠 때 세 폴더를 함께 열게 됩니다. 이때 폴더 구조는 시스템이 무슨 일을 하는지보다 어떤 프레임워크 책임으로 나뉘었는지를 먼저 보여 줍니다.

질문이 하나 남습니다. 그렇다면 이 경계는 무엇이 지킬까요?

진짜 문제는 Layered가 아니라 보이지 않는 경계

저는 이 문제를 Layered 구조의 탓으로 보지 않았습니다. 같은 클래스를 Clean이라는 패키지 아래로 옮겨도 컴파일 결과는 달라지지 않기 때문입니다. 위 예시의 컨트롤러→리포지토리 직접 의존은 타입이 같은 클래스패스에 있는 한 컴파일과 테스트를 모두 통과합니다. 패키지 이름에는 사람이 정한 규칙이 담겨 있지만 컴파일러는 그 이름을 경계로 해석하지 않습니다. 그래서 문제를 Layered라는 이름이 아니라 경계가 컴파일러와 빌드 시스템에 보이지 않는 상태로 정의했습니다.

경계를 어디에 표현하느냐에 따라, 서로 다른 위반을 잡을 수 있는 강제 수단이 이렇게 갈립니다.

구조	의존 규칙 존재	빌드 강제	위반 코드
단일 모듈 Layered	약함	없음	컴파일 성공
단일 모듈 Clean	있음	약함(테스트뿐)	컴파일 성공
멀티모듈 Clean	있음	클래스패스	금지 타입컴파일 실패
실행 가능한 Clean	있음	클래스패스 + 정책 + 테스트	금지 모듈 의존빌드 실패

표의 아래쪽으로 갈수록 위반을 발견하는 곳이 리뷰에서 컴파일·빌드로 옮겨갑니다. 맨 아래의 실행 가능한(executable) 아키텍처에서는 경계를 어긴 코드가 컴파일이나 빌드를 통과하지 못합니다.

문제를 설계 요구사항으로 변환

컨트롤러가 저장소를 우회하도록 두면 DB 스키마 변경이 서비스와 API 응답까지 번집니다. 서비스가 구체 저장소에 묶이면 DB 없이 테스트하기 어렵고, 오류 코드 같은 운영 용어도 도메인 코드로 들어올 수 있습니다. 그래서 저는 “경계를 지켜야 한다”는 말로 끝내지 않고, 빌드가 확인할 수 있는 요구사항으로 하나씩 바꿨습니다. 제가 해결하려 한 문제와 이를 막을 요구사항을 짝지으면 다음과 같습니다.

문제	설계 요구사항
DB 변경이 서비스·API까지 전파	영속성 모델과 도메인 모델 분리
정책이 Spring 타입에 결합	코어의 프레임워크 클래스패스 제한
Controller가 Repository 우회	입력 포트를 통한 유스케이스 진입
테스트가 DB를 요구	애플리케이션 소유 출력 포트
패키지 경계가 침식	컴파일·빌드·테스트 수준 강제
운영 계약이 도메인에 침투	도메인 언어와 운영 언어 분리

여섯 요구는 이 글 전체의 뼈대입니다. 결론에서 각 요구를 ca-tmpl의 구체적인 설계를 설명합니다.

이 구조가 이익이 되는 조건

저는 ca-tmpl을 여러 프로젝트에서 반복해 사용할 스켈레톤으로 만들었습니다. 이런 환경에서는 최초 설계자가 모든 변경을 계속 리뷰할 수 없지만 빌드 규칙과 테스트는 담당자가 바뀌어도 같은 검사를 실행합니다. 반대로 수명이 짧고 변경하는 사람이 적은 서비스라면 19개 모듈과 여러 정책 파일을 유지하는 비용이 더 클 수 있습니다.

ca-tmpl이 여러 겹의 강제 장치를 두는 실용적인 이유는 경계 규칙을 개인이 계속 기억하지 않고 팀이 반복 실행할 수 있는 검사로 옮기기 위해서입니다. 모듈 클래스패스는 금지된 타입을 보이지 않게 하고, Gradle 정책은 금지된 모듈 의존을 거부하며, ArchUnit은 같은 모듈 안의 패키지 규칙까지 검사합니다.

settings.gradle에는 인바운드 어댑터 4개와 아웃바운드 어댑터 10개가 포함돼 있습니다. 이들을 모듈로 분리한 이유는 어댑터마다 허용할 기술 의존, 활성화 조건, 테스트 전략이 다르기 때문입니다.

여러 어댑터를 지원하도록 만들었지만 전부 항상 실행되게 하지는 않았습니다. 조립 모듈 app-bootstrap은 어댑터 11개를 main 프로젝트 의존에 넣고 나머지 3개는 클래스패스 밖의 참조 어댑터로 남깁니다. 게다가 main 의존에 포함된 모듈조차 런타임 프로퍼티가 꺼져 있으면 구체 백엔드 빈이 뜨지 않습니다. 예를 들어 Redis 캐시 설정은 matchIfMissing = false라 플래그가 없으면 기본적으로 꺼져 있습니다.

참조 코드는 프로덕션과 격리됩니다. 예제 모듈 sample-portfolio는 main 구현체가 아니라 별도 sampleFixture 설정으로만 클래스패스에 붙습니다. SampleRemovalSmokeContractTest는 지정된 열두 프로덕션 모듈이 샘플을 일반 프로덕션 configuration으로 참조하지 않는지 검사하고, sampleOffTest는 샘플을 뺀 핵심 테스트 경로를 실행합니다. 이 예제 모듈은 프로덕션 그래프를 건드리지 않고 제거할 수 있어야 하며, 위반하면 check가 실패합니다.

도메인 순수성과 운영 계약도 같은 모듈에 넣지 않았습니다. ArchUnit 규칙 DOMAIN_IS_PURE는 도메인 의존을 검사하고, 로깅·에러 코드·응답 포맷은 shared-contract에 두었습니다. 이렇게 두 종류의 코드를 다른 모듈에서 관리하지만, 이 분리만으로 운영 용어가 도메인에 들어오는 모든 경우를 자동 차단하는 것은 아닙니다. 실제 강제 범위는 뒤에서 다시 설명합니다.

핵심 판단 기준과 멘털 모델

실행 흐름과 소스 의존은 왜 반대가 되는가

ca-tmpl의 의존 방향을 설계할 때는 런타임 호출, 데이터 흐름, 소스 의존을 먼저 구분했습니다. 런타임에는 바깥의 컨트롤러가 안쪽을 호출하지만, 클린 아키텍처의 의존 화살표도 바깥에서 안쪽을 가리킵니다. 세 방향을 한 화살표로 읽으면 실행 순서와 의존 방향이 뒤섞입니다. 따로 놓으면 차이가 분명해집니다.

런타임 호출 방향: Controller → Use Case → Port 구현 → DB. 요청이 오면 호출은 바깥에서 안으로 들어갔다가, 가장자리에서 다시 바깥의 어댑터로 나가 DB를 조회하거나 갱신합니다.
데이터 흐름: 요청은 안쪽으로 들어가고 결과는 다시 바깥쪽으로 나옵니다. 방향이라기보다 왕복입니다.
소스 코드 의존 방향: Adapter → Application/Domain. 컴파일 시점에 어느 모듈이 어느 모듈을 import하고 클래스패스에 두는지를 말합니다. 여기서만은 화살표가 항상 안쪽을 향합니다.

DIP(의존성 역전 원칙, Dependency Inversion Principle)는 셋 중 딱 하나만 바꿉니다. DIP가 역전하는 대상은 런타임 호출이 아니라 소스 코드 의존 관계입니다. 런타임에 유스케이스가 포트 구현을 호출한다는 사실은 그대로 둡니다. 뒤집을 수도 없고 뒤집을 필요도 없습니다. DIP가 뒤집는 건 "그 호출을 성립시키려면 누가 누구의 타입을 알아야 하는가"입니다.

소스 의존이 호출 방향과 달라야 하는 이유도 여기에 있습니다. 자연스럽게 짜면 호출하는 쪽이 호출당하는 쪽의 타입을 압니다. 유스케이스가 DB 리포지토리를 직접 알면 소스 의존이 호출 방향을 그대로 따라 안에서 바깥으로 흘러 코어가 DB를 알게 됩니다.

DIP는 이 사이에 코어가 소유한 인터페이스를 끼웁니다. 유스케이스는 인터페이스만 알고 그 인터페이스를 바깥의 어댑터가 구현합니다. 그러면 호출은 여전히 안에서 바깥으로 나가지만 타입을 아는 방향(소스 의존)은 어댑터가 코어를 아는 쪽으로 뒤집힙니다. 호출은 그대로, 소스 의존만 역전됩니다.

ca-tmpl에서는 코어 모듈 application-core가 TransactionPort를 선언하고 JPA 어댑터의 SpringTransactionPort가 이를 구현합니다. 구현체가 코어 인터페이스를 import하므로 어댑터 소스가 코어를 향합니다. 모듈 의존도 같은 방향입니다.

implementation project(':application-core')

어댑터 빌드 파일은 한 줄로 코어에 의존을 걸지만 코어의 의존에는 이 어댑터를 가리키는 project 의존이 없습니다. application-core의 프로젝트 의존은 domain-core와 shared-contract뿐입니다.

GetFeedUseCase는 런타임에 SpringTransactionPort를 호출하지만, 소스에서는 SpringTransactionPort가 코어의 TransactionPort에 의존합니다. 이 역전이 있어야 application-core가 DB·영속 구현과 전송 프레임워크 타입을 모른 채 남습니다. 다만 application-core 자체가 framework-free라는 뜻은 아닙니다. 이 모듈은 SLF4J를 사용합니다. 코어 모듈 중 main compileClasspath에 외부 의존이 전혀 없는 곳은 domain-core와 운영 계약 모듈 shared-contract입니다.

Hexagonal — 포트는 무엇을 나누는가

포트는 웹과 DB 같은 기술 종류가 아니라 대화 방향을 기준으로 나눴습니다. HTTP 요청·스케줄러·메시지 소비처럼 바깥에서 유스케이스를 시작하는 경계는 인바운드로, DB 조회·알림 발송·파일 저장처럼 유스케이스가 바깥 기능을 요청하는 경계는 아웃바운드로 나눴습니다. Hexagonal의 육각형은 이 두 대화 방향 사이에 도메인과 유스케이스를 남깁니다.

원리 수준의 흐름은 inbound Adapter → Input Port → Application Service → Output Port → outbound Adapter입니다. 다만 ca-tmpl의 피드 조회는 이 다섯 자리를 모두 별도 타입으로 분리하지 않았습니다. 요청은 FeedController(inbound Adapter)에서 시작해 getFeed.handle(new GetFeedQuery(page, size))를 부릅니다. 컨트롤러가 주입받는 getFeed의 선언 타입은 구체 클래스 GetFeedUseCase입니다. 유스케이스별 전용 Input Port 인터페이스는 없고 대신 이 구체 서비스가 코어의 일반 계약 QueryUseCase<GetFeedQuery, List<FeedSummary>>를 구현합니다. 이런 타입 계약을 포트로 삼으면 하나의 선언이 포트의 모양과 기계적 강제를 함께 제공하면서도 유스케이스의 책임은 유지할 수 있습니다.

FeedQueryPort는 어댑터 모듈이 아니라 application-core와 같은 패키지에 선언돼 있습니다. 코어가 출력 인터페이스를 소유하므로 GetFeedUseCase는 "조회 결과를 어떻게 가져올지"가 아니라 "무엇을 받고 싶은지"만 압니다. 저장 기술을 바꾸면 직접 의존의 변경 반경은 FeedQueryPort 바깥의 어댑터와 매핑 경계로 제한됩니다. 다만 쿼리 의미나 반환 모델까지 달라지면 코어 계약도 바뀔 수 있으므로 DB를 바꿔도 코어가 항상 그대로 유지되는 것은 아닙니다.

Input Port와 Output Port를 구분하는 기준은 소유권이 아니라 방향입니다.

Driving Port(Input Port) — 바깥이 안쪽에 의도를 전달하는 창구. 코어가 받아들이는 요청의 모양(Command/Query)을 코어가 강제하고 어댑터는 그 모양을 벗어난 요청을 만들 수 없습니다.
Driven Port(Output Port) — 안쪽이 바깥에 능력을 요구하는 창구. 코어는 "이런 능력이 필요하다"까지만 선언하고 그 능력을 무엇으로 채우는지는 모릅니다.

Input Port의 Command와 Query는 어댑터가 코어에 전달할 요청의 모양을 제한합니다. 반대로 Output Port는 아웃바운드 어댑터가 코어에 제공해야 할 기능을 정합니다. 둘을 하나의 인터페이스에 합치면 받는 요청과 외부에 요구하는 기능이 섞여 한쪽의 변경이 다른 쪽까지 번집니다. ca-tmpl은 읽기와 쓰기의 의도도 타입에 남기기 위해 UseCase<I, O>를 CommandUseCase와 QueryUseCase로 나눴고, GetFeedUseCase는 후자를 구현합니다. FeedController는 구체 GetFeedUseCase를 주입받고 FeedQueryAdapter는 명시적인 FeedQueryPort를 구현합니다. 두 소스 의존 모두 코어를 향하지만 인터페이스를 실제 주입 경계로 사용하는 정도는 다릅니다.

저는 실제로 바뀔 수 있는 기술이 있거나 테스트에서 구현을 대체해야 하는 경계에만 포트를 두었습니다. 외부 기술이 끼지 않는 코어 내부의 계산·조립 클래스까지 인터페이스 하나와 구현체 하나로 나누면 동작은 그대로인데 읽는 사람만 두 파일을 오가게 됩니다.

이렇게 경계마다 타입을 나누면서 매핑 비용도 생겼습니다. 피드 항목 하나는 JPA 엔티티에서 FeedSummary로, 다시 웹 응답 FeedResponse로 옮겨집니다. 중첩 값 객체도 같은 과정을 거칩니다. FeedSummary.HighlightSummary와 FeedResponse.HighlightPart는 color, text, createdAt 세 필드가 같지만 별개 타입으로 선언되고 각각 매핑됩니다. DB 필드 하나를 응답에 추가하려면 세 클래스와 두 매핑 함수를 함께 고쳐야 합니다. AI가 반복 코드를 만들어 주더라도 변경 지점과 검토할 코드는 줄어들지 않습니다. 코어가 JPA와 HTTP를 모르는 대신 두 번의 매핑을 계속 관리해야 합니다.

Clean ↔ Spring — 네 개의 링을 모듈에 앉히기

클린 아키텍처를 설명할 때는 보통 네 개의 링을 그립니다. 저는 링의 이름을 그대로 모듈에 붙이는 대신, 코드가 바뀌는 이유를 기준으로 ca-tmpl의 모듈에 대응시켰습니다. 같은 이유로 바뀌는 코드는 한 경계에 두고 다른 이유로 바뀌는 코드는 의존 방향을 나눴습니다.

링	`ca-tmpl` 모듈	대표 책임	이곳에 두는 이유
엔터프라이즈 업무 규칙(Enterprise Business Rules)	`domain-core`	Aggregate·Value Object — 예:`FeedItem`	핵심 불변식은 HTTP·DB·Spring 교체와 무관하게 유지돼야 합니다. 그래서 JPA와 Spring 타입을 클래스패스에서 제외합니다.
애플리케이션 업무 규칙(Application Business Rules)	`application-core`	Use Case·Input/Output Port — 예:`GetFeedUseCase`, `FeedQueryPort`	유스케이스는 업무 흐름과 필요한 외부 능력을 정의하되, 그 능력을 어떤 기술로 구현하는지는 몰라야 합니다.
인터페이스 어댑터(Interface Adapters)	`adapter:inbound:`, `adapter:outbound:`	Controller·영속성 어댑터 — 예:`FeedController`, `FeedQueryAdapter`	HTTP·JPA 같은 외부 모델을 코어 계약으로 변환하는 책임을 모아 기술 변경의 직접 파급을 경계 밖에 가둡니다.
프레임워크와 드라이버(Frameworks & Drivers)	어댑터의 구체 기술 의존,`app-bootstrap`	Spring MVC·Spring Data JPA·PostgreSQL·Boot/Flyway·관측·보안 배선	구체 프레임워크 선택과 실행 시점 조립은 배포 환경에 따라 바뀌므로 가장 바깥에서 결정합니다.

domain-core를 별도 모듈로 둔 이유는 도메인 규칙을 프레임워크 변경에서 보호하기 위해서입니다. 이 모듈에는 Spring Web, JPA, Spring TX가 없으므로 도메인 코드가 해당 타입을 참조하면 컴파일 단계에서 실패합니다. application-core는 유스케이스와 포트를 소유합니다. 이렇게 해야 GetFeedUseCase가 "피드를 조회한다"는 업무 흐름만 알고, 조회를 JPA로 할지 다른 저장소로 할지는 아웃바운드 어댑터가 결정할 수 있습니다.

인바운드와 아웃바운드를 별도 어댑터 모듈로 둔 이유는 변환 방향과 기술 의존이 다르기 때문입니다. adapter:inbound:web은 HTTP 요청을 애플리케이션 입력으로 바꾸기 위해 web 의존성을 사용합니다. adapter:outbound:jpa는 애플리케이션의 출력 포트를 DB 접근으로 바꾸기 위해 jpa와 PostgreSQL 드라이버를 사용합니다. 두 기술 의존은 코어 모듈로 전파되지 않습니다.

app-bootstrap을 별도 조립 모듈로 둔 이유는 어떤 구현을 실제로 사용할지 한곳에서 고르기 위해서입니다. 이 모듈이 Boot·Validation·Flyway·Micrometer/OTel·Actuator·Security 의존과 어댑터 배선을 맡으므로 코어는 기동 방식과 운영 기술을 알 필요가 없습니다. 메시징 모듈처럼 구체 브로커 클라이언트가 아직 없는 어댑터는 확장 계약만 제공합니다. 모듈이 존재한다는 사실과 실제 연동이 완성됐다는 사실을 구분해야 합니다.

이 매핑은 유일한 정답이 아닙니다. ca-tmpl은 금지된 타입을 코어 클래스패스에서 제거해 경계 위반을 컴파일 단계에서 막기 위해 Gradle 모듈을 사용합니다. 그 대가로 모듈별 빌드 선언과 의존 정책을 계속 관리해야 합니다. 경계를 패키지 규칙만으로도 충분히 지킬 수 있는 작은 서비스라면 이 비용이 이익보다 클 수 있습니다.

Dependency Rule. 프로젝트가 소유한 모듈 사이의 소스 의존은 안쪽을 향합니다. 어댑터 모듈이 애플리케이션·도메인 계약을 참조하고 Gradle 화이트리스트는 반대 방향의 프로젝트 의존을 허용하지 않습니다. Spring MVC·JPA·PostgreSQL 같은 외부 라이브러리 간선은 어댑터 모듈에서 프레임워크 쪽으로 향합니다. Spring MVC·JPA·PostgreSQL 의존은 각 어댑터 안에서 끝나며 코어 모듈의 클래스패스로 들어가지 않습니다.

Boundary Data. 같은 피드 데이터도 경계를 넘을 때마다 사용하는 타입이 달라집니다. JPA 엔티티는 FeedSummary로 바뀌고 웹 경계에서는 다시 FeedResponse가 됩니다. 다만 모든 필드 타입을 복제하지는 않습니다. FeedItemJpaEntity는 도메인의 Visibility enum을 직접 import해 재사용합니다. 의미가 같은 단순 enum까지 따로 만들지는 않았습니다.

Entity라는 이름이 두 번 쓰입니다. Uncle Bob의 Entity(Enterprise Business Rules)와 JPA Entity는 이름이 같을 뿐 전혀 다른 개념입니다. ca-tmpl에서 이 둘은 실제로 서로 다른 모듈의 서로 다른 타입입니다.

Uncle Bob의 Entity는 domain-core의 FeedItem입니다. @AggregateRoot가 붙은 타입에 public setter를 추가하면 별도의 아키텍처 테스트가 실패합니다. 임포트는 자체 stereotype 애노테이션과 JDK 타입뿐입니다.
JPA @Entity는 adapter/outbound/jpa의 FeedItemJpaEntity입니다. JPA 의존성을 임포트하고 @Entity @Table(name = "feed_items")가 붙습니다. 영속성 프레임워크가 리플렉션으로 다루기 위한 계약입니다.

두 타입은 서로를 직접 알지 못합니다. 어댑터가 소유한 FeedItemPersistenceMapper.toDomain()은 JPA 엔티티에서 도메인으로 가는 한 방향 재구성을 제공하지만 현재 피드 조회 경로는 이를 호출하지 않고 조회 결과에서 FeedSummary를 직접 만듭니다.

Layered·Hexagonal·Clean은 경쟁하지 않는다

저는 Layered·Hexagonal·Clean을 서로 경쟁하는 구조로 보지 않았습니다. Layered는 표현·서비스·영속성 같은 기술 책임을 어디에 모을지 설명하고, Hexagonal은 외부와 대화하는 자리를 Driving/Driven 포트로 나눕니다. Clean은 정책 수준에 따라 소스 의존이 어느 쪽을 향해야 하는지 정합니다. 세 설명이 만나는 곳은 DIP였습니다. 바깥 기술이 코어가 소유한 계약에 의존하면 도메인은 구체 프레임워크를 몰라도 됩니다.

Layered에서도 서비스 계층이 포트를 소유하고 영속성 구현이 그 포트에 의존하게 만들 수 있습니다. 따라서 층의 개수만으로 의존 역전 여부가 정해지지는 않습니다. Hexagonal로는 경계를 어디에 그을지 정하고, Clean의 의존 규칙으로는 그 경계를 넘는 소스 의존의 방향을 정합니다. 이 두 규칙을 함께 적용해도 DB 교체 비용은 사라지지 않습니다. 식별자·쿼리·락·격리 수준이 달라지면 코어 계약도 바뀔 수 있습니다. ca-tmpl은 그 변경이 곧바로 컨트롤러와 다른 어댑터까지 번지지 않도록 모듈과 매핑 경계에서 멈추게 합니다.

판단 기준 — 모듈 하나를 추가하는 다섯 질문

이 원칙을 실제 Gradle 모듈로 옮기면서 “얼마나 나눠야 하는가”를 정해야 했습니다. 경계를 많이 만들수록 금지할 의존은 분명해지지만, 모듈마다 빌드 선언과 테스트, 매핑을 함께 관리해야 합니다. 그래서 저는 모듈 수를 기준으로 삼지 않고 아래 질문으로 새 경계가 필요한지 판단했습니다.

독립적으로 제한해야 하는 클래스패스, 또는 독립적으로 선택해야 하는 런타임 능력이 존재하는가?

구체적으로 다섯 질문으로 판단합니다.

금지할 의존성이 다른가? — 예: objectstorage는 도메인을 몰라야 합니다(domain-core 접근 금지).
선택적으로 켜고 끌 수 있는가? — 예: grpc는 opt-in 참조 어댑터입니다.
별도 테스트 전략이 필요한가? — 예: persistence-jpa는 Testcontainers 통합 테스트를 씁니다.
변경 주기가 다른가?
독립 배포가 아니라도 독립 컴파일이 가치 있는가?

다섯 질문에 모두 "아니오"라면 저는 모듈을 더 나누지 않습니다. 독립적인 테스트, 변경 범위의 제한, 기능의 선택적 조합이라는 기준은 여러 기업 기술 블로그에서 반복해서 확인한 모듈 분리 목적에서 가져왔습니다. ca-tmpl은 여러 프로젝트가 가져다 쓸 스켈레톤으로 만들었기 때문에, 사용하지 않는 기능 모듈을 런타임 의존에서 빼면 관련 자동 구성과 애플리케이션 컨텍스트도 등록되지 않아야 합니다. 이제 이 기준을 19개 모듈에 어떻게 적용했는지 설명합니다.

해결 방식이 동작하는 과정

전체 구조 — 19개 leaf 모듈

ca-tmpl은 19개의 leaf 모듈로 만들었습니다. 모든 기능을 잘게 나누는 것이 목적은 아니었습니다. 코어의 클래스패스를 제한할 모듈과 프로젝트마다 골라 쓸 어댑터를 따로 떼어 낸 결과입니다. 여러 프로젝트에서 오래 복제해 쓰는 스켈레톤이므로 거버넌스·품질·경계를 같은 빌드에서 검사하도록 구성했습니다. 스택은 Spring Boot 4.0.0, Gradle 9.0.0, Java 21입니다. 이 버전들은 특정 아키텍처 기능 때문에 고른 것이 아니라 메이저 버전 전환 시점에 검증하고 고정한 빌드 기준점입니다. 계속 유지해야 할 아키텍처 이유는 없으므로 호환성 테스트를 통과하는 범위에서 최신 유지보수 버전으로 갱신해야 합니다.

내부 모듈 3개 — domain-core(순수 도메인), application-core(유스케이스와 포트), shared-contract(운영 계약)
조립 루트 1개 — app-bootstrap
인바운드 4개 — web·grpc·graphql·websocket
아웃바운드 10개 — persistence-jpa·support·messaging·cache-redis·notification· objectstorage·fileserver·persistence-mongo·httpclient·identifier
참조 슬라이스 1개 — sample-portfolio

모듈 수를 19개로 늘리는 것 자체가 목적은 아니었습니다. 코어에서는 기술 의존을 막고, 어댑터마다 활성화 조건과 테스트 전략을 따로 관리하며, 조립 루트에서 실제 실행 구성을 고르게 했습니다. 프로젝트마다 필요한 기술이 다르기 때문에 19개를 모두 활성화하지 않고 선택해서 쓰는 구조로 만들었습니다. PostgreSQL, MongoDB, Redis를 초기 후보로 고를 때는 Stack Overflow Developer Survey의 사용량도 참고했습니다. Kafka를 포함해 여기에 들어 있는 기술이 모든 프로젝트에 필요하다는 뜻은 아닙니다.

19개 모듈을 설명할 때는 먼저 아웃바운드와 인바운드로 나눴습니다. 아웃바운드에는 다음 책임을 두었습니다.

persistence-jpa에는 PostgreSQL 드라이버
objectstorage에는 opt-in S3/MinIO 백엔드
fileserver에는 순수 JDK 파일시스템 구현
cache-redis·messaging·notification에는 각각 RedisClient·KafkaSender·SlackClient 구현을 프로젝트가 채워 넣을 수 있는 확장점이 있습니다.
httpclient는 외부 HTTP API 호출과 timeout-retry 같은 통신 정책을 담당합니다.

애플리케이션 코어는 PostgreSQL, Redis, Kafka, S3를 직접 알지 않습니다. 필요한 기능만 output port로 선언하고 각 outbound adapter가 이를 실제 기술로 구현합니다.

반대쪽에는 외부 요청을 애플리케이션 입력으로 변환하는 inbound 경계가 있습니다.

web은 HTTP 요청, JSON DTO, Bean Validation, 인증 인가와 HTTP 오류 응답을 담당합니다.
grpc는 protobuf 기반 요청과 gRPC 서버 lifecycle을 담당합니다.
graphql은 GraphQL schema와 query-mutation 진입점을 담당합니다.
websocket은 WebSocket.STOMP 연결과 실시간 메시지 진입점을 담당합니다.

각 inbound adapter는 자신이 사용하는 전송 기술 타입을 모듈 안에서 처리합니다. HTTP request DTO, protobuf message, GraphQL resolver, WebSocket message를 그대로 application-core에 넘기지 않습니다. 어댑터가 application command나 query로 바꾼 뒤 유스케이스를 호출합니다.

HTTP DTO ─────────┐
Protobuf message ─┤
GraphQL request ──┼─> Command / Query ─> Application use case
WebSocket message ┘

Inbound와 outbound는 테스트 전략도 다릅니다.

Inbound adapter : 역직렬화, 요청 검증, 인증 인가, transport 계약, 오류 응답
Outbound adapter : 데이터 매핑, 외부 시스템 연동, timeout-retry, 기술 예외 변환

왼쪽에서 오른쪽으로 읽습니다. web은 HTTP DTO, grpc는 protobuf message, graphql은 GraphQL request, websocket은 WebSocket message를 각 어댑터 경계에서 처리합니다. 네 어댑터는 전송 기술 타입을 application-core로 넘기지 않고 Command 또는 Query로 변환합니다. 변환된 입력만 Application use case를 호출합니다.

app-bootstrap은 프로젝트가 실제 사용할 inbound와 outbound adapter를 선택해서 application port와 연결합니다. 사용하지 않는 선택형 어댑터를 런타임 의존성에서 제외하면 해당 모듈의 빈과 설정도 애플리케이션 컨텍스트에 등록되지 않습니다. 이 실행 구성을 바탕으로 코드의 의존성이 어떤 방향으로 흐르도록 만들었는지 설명하겠습니다. 이 프로젝트의 모듈 간 의존은 inbound와 outbound 모두 바깥에서 안쪽으로 향합니다. verifyCleanArchitectureDependencies는 모듈 간 프로젝트의 의존성을 검사하고, ArchUnit의 DOMAIN_IS_TRUE는 모듈 내부 코드가 금지된 프레임워크 타입을 참조하는지 검사합니다.

가운데 Application Core를 기준으로 왼쪽에는 Inbound adapters와 Input port, 오른쪽에는 Output port와 Outbound adapters가 있습니다. 어댑터의 모듈 의존은 포트와 코어 쪽을 향합니다. 아래의 app-bootstrap은 실제 사용할 양쪽 어댑터를 선택하고 application port에 연결합니다. 별도의 두 검증 게이트 중 verifyCleanArchitectureDependencies는 모듈 간 프로젝트 의존을 검사하고 ArchUnit 규칙은 모듈 내부 코드의 금지된 프레임워크 타입 참조를 검사합니다.

프로젝트 모듈 간 의존은 adapter→application→domain으로 안쪽을 향합니다. MVC·JPA·DB 구체 의존은 해당 어댑터가 소유하고 Boot·Flyway·관측·보안 조립은 app-bootstrap이 별도로 소유합니다.

아래 그림은 allowedProjectDependencies 중 코어 접근권과 support공유의 비대칭을 보여 주는 다섯 부분만 표현합니다.

경계마다 다른 모델 — 다섯 종류

피드 항목의 같은 필드가 여러 타입에 반복되는 것은 경계마다 모델을 분리했기 때문입니다. FeedController에서 JPA 조회까지는 각 타입이 맡은 경계를 넘기지 않도록 만들었습니다. 실제 피드 조회에는 GetFeedQuery·FeedSummary·FeedItemJpaEntity·FeedResponse 네 종류가 참여합니다. FeedItem은 이 조회 경로를 지나지 않고 도메인 모델과 JPA 엔티티를 비교할 때만 등장합니다.

#	모델 종류	대표 타입	소속 모듈	경계를 넘나드는 이유
①	인바운드 DTO	`FeedResponse`(record, 중첩 `HighlightPart`)	`adapter:inbound:web`	HTTP 응답 바디 모양 — 아는 건 컨트롤러·매퍼뿐
②	애플리케이션 Command/Query	`GetFeedQuery`(record, `implements Query`)	`application-core`	코어가 강제하는 Input Port 요청 모양
③	애플리케이션 프로젝션	`FeedSummary`(record, 중첩 `HighlightSummary`)	`application-core`	`FeedQueryPort.loadFeed()`가 돌려주는 읽기 전용 투영
④	도메인 애그리게이트	`FeedItem`(`@AggregateRoot`)	`domain-core`	정책·불변식이 사는 자리 — 프레임워크 임포트 0
⑤	아웃바운드 영속 엔티티	`FeedItemJpaEntity`(`@Entity`)	`adapter:outbound:persistence-jpa`	`jakarta.persistence` 리플렉션 계약

다섯 모델은 한 객체의 생애주기 단계가 아닙니다. 조회 경로에서는 Query 마커만 사용합니다. Command 마커는 sample-portfolio의 CreateWorkLogCommand에 실제로 적용돼 있습니다.

재매핑은 두 번 일어납니다.

persistence에서 application으로 넘어갈 때입니다. FeedQueryAdapter.loadFeed()는 JPA 조회 결과를 FeedSummary로 직접 조립합니다. FeedItemJpaEntity → FeedItem → FeedSummary처럼 애그리게이트를 재구성하지 않고 조회 결과에서 곧장 애플리케이션 프로젝션으로 건너갑니다.

같은 DB 안에서 읽기 경로만 논리적으로 나누는 이 우회가 뒤에서 다룰 CQRS-lite 결정의 구체적인 모습입니다. CQRS는 명령(Command)과 조회(Query)의 코드·모델을 나누는 패턴이고 lite는 저장소 분리 없이 코드 경로와 모델만 나눈 수준을 뜻합니다.

application에서 web으로 나갈 때입니다. FeedWebMapper.toResponse()가 FeedSummary를 FeedResponse로 다시 조립합니다.

두 매핑을 모두 어댑터가 소유하므로 GetFeedUseCase와 FeedQueryPort는 웹 응답이나 JPA 엔티티의 모양을 모릅니다. GetFeedUseCase가 FeedResponse를 직접 만들었다면 HTTP 응답 변경이 코어 변경으로 번졌을 것입니다. 반대로 도메인 재구성이 필요한 경로에서는 어댑터의 FeedItemPersistenceMapper가 코어 모델 변경을 따라 바뀌는 것이 의도한 결합입니다.

패키지 축과 모듈 축 — 왜 둘 다 쓰는가

패키지와 모듈은 같은 경계를 두 번 표현하려고 함께 쓴 것이 아닙니다. 저는 패키지로 무엇이 같이 사는가를 정하고, 모듈로 무엇이 무엇을 알 수 있는가를 실제 컴파일 범위에서 제한했습니다. 기능·기술 패키지가 섞인 hybrid 배치와 19개 모듈은 서로 다른 역할을 맡습니다.

패키지 축으로 응집은 얻지만 의존 위반은 여전히 컴파일러가 막지 못합니다. 도메인의 feed는 기능 응집을 보이지만 샘플 어댑터의 controller·dto·mapper와 애플리케이션의 command·query·port는 기술 책임으로 묶입니다. 외부 사례에서 패키지를 나눈 이유도 달랐습니다. Sahibinden은 기능 패키지의 응집·캡슐화·모듈성을, arawn은 외형 복제보다 높은 응집과 느슨한 결합을 강조했습니다. 우아한형제들 사례에서는 레이어 단위로 멀티모듈을 기계적으로 나누면 output port가 많이 생길 수 있었습니다.

그런데 패키지 캡슐화가 지켜주는 범위는 좁습니다. package-private는 같은 패키지 안에서 어떤 클래스를 서로 볼 수 있는가를 컴파일러가 강제하지만 이 패키지가 어떤 외부 라이브러리에 의존해도 되는가라는 규칙은 강제하지 않습니다. 자바 문법에는 "이 패키지는 저 패키지를 import하면 안 된다"가 없습니다. 남는 방어선은 패키지 규칙 기반 ArchUnit 하나뿐인데 이건 컴파일 이후에 도는 테스트라서 끄거나 잊으면 통과하게 됩니다. 그래서 패키지만으로 그은 경계는 한계가 있습니다.

모듈 축은 컴파일과 빌드가 강제합니다. domain-core가 별도의 프레임워크 의존성을 선언하지 않으면 그런 타입은 이 모듈의 클래스패스에 없으므로, 참조하면 javac가 컴파일을 중단합니다. 모듈 그래프가 못 보는 패키지 내부는 ArchUnit이 이어서 검증합니다.

패키지 축만 있으면 관련 책임은 가까이 놓이지만 그 경계가 무너져도 컴파일러는 이를 잡지 못합니다. 모듈 축만 있으면 위반은 확실히 막히지만 같은 기능의 코드가 모듈 내부에서 서로 다른 책임들과 뒤섞이는 것까지는 막지 못합니다. 패키지가 그 응집을 담당합니다. 패키지는 경계를 사람이 읽기 쉽게 만들고 모듈은 그 경계를 빌드가 어기지 못하게 만듭니다.

내부 정책 모듈 — domain-core·application-core·shared-contract

세 코어 모듈을 모두 같은 수준의 순수성으로 정의하지는 않았습니다. domain-core와 shared-contract의 main 외부 의존은 비워 두었지만 application-core는 domain-core와 shared-contract를 알고 SLF4J도 사용합니다. “세 모듈이 모두 완전히 순수하다”고 약속하는 대신, 각 모듈이 알아도 되는 타입을 클래스패스와 ArchUnit 규칙으로 제한했습니다.

모듈	맡은 결정	허용한 지식	대표 실행 경로	경계를 고정하는 규칙
`domain-core`	애그리게이트·값·이벤트·식별자와 불변식	main compile은 JDK와 자체 타입뿐	`FeedItem`이 자체 스테레오타입·JDK 타입만 사용	`DOMAIN_IS_PURE`, `DOMAIN_HAS_NO_LOGGER`
`application-core`	유스케이스 순서와 바깥 능력의 포트	domain-core, shared-contract	`GetFeedUseCase`가 `tx.inRead(() -> feedQuery.loadFeed(...))` 호출	`APPLICATION_DOES_NOT_DEPEND_ON_ADAPTERS_OR_TRANSPORT` 외
`shared-contract`	응답·오류·추적·메트릭 같은 운영 계약	main 외부 의존 0, 허용한 운영 패키지 prefix	`Envelope(success, data, error, meta)`와 `ApiErrorCode`	`SHARED_CONTRACT_CONTAINS_ONLY_OPERATIONAL_CONTRACT_PACKAGES`

domain-core의 빈 의존 블록은 Spring·JPA·Servlet·Hibernate 같은 외부 프레임워크 타입이 들어올 직접 의존 통로를 없앱니다. JDK 자체의 파일·네트워크·SQL API까지 자동으로 금지한다는 뜻은 아닙니다. DOMAIN_IS_PURE는 금지 패키지 의존을 막고 DOMAIN_HAS_NO_LOGGER는 로깅 프레임워크까지 차단합니다. 두 규칙은 도메인이 직접 로그를 남기지 못하게 합니다. 예외를 어떤 종류로 나누고 각 예외에 구체적인 실패 사유를 담을지는 별도의 규칙으로 확인해야 합니다.

application-core의 main 의존은 domain-core와 shared-contract뿐입니다. spring-web·JPA· spring-tx는 main compileClasspath에 없습니다. 유스케이스는 TransactionPort·OutboxStorePort· FeedQueryPort 같은 인터페이스로 필요한 기능을 요청하고 어댑터가 구현합니다. @Transactional은 컴파일 의존과 ArchUnit 규칙 양쪽에서 막기 때문에 트랜잭션 의도도 TransactionPort로 표현합니다.

shared-contract에는 도메인 규칙이 아니라 응답·오류·로깅·추적 같은 운영 계약을 모아 두었습니다. response·error·logging·tracing 등 고정된 패키지 밖에 새 공유 타입을 두면 SHARED_CONTRACT_CONTAINS_ONLY_OPERATIONAL_CONTRACT_PACKAGES에서 거부합니다. 다만 이 규칙은 package prefix만 검사하기 때문에, 허용 패키지 안에 놓인 타입의 의미가 실제로 운영 계약인지까지 판별하지는 않습니다.

인바운드 어댑터 — web·grpc·graphql·websocket

REST·gRPC·GraphQL·WebSocket 네 인바운드 모듈은 같은 깊이로 구현하지 않았습니다. 기본 실행에는 web만 넣고, gRPC·GraphQL·WebSocket은 필요한 프로젝트가 따로 연결하는 opt-in 참조 구현으로 두었습니다. 구현 범위는 달라도 전송 기술을 코어 밖에 두고 아웃바운드 구현을 직접 고르지 않는 규칙은 같게 적용했습니다.

모듈	현재 제공하는 기능	결정적인 차이
`adapter:inbound:web`	`/feed` REST·health·공유 웹 인프라	`FeedController`가 `GetFeedUseCase`를 호출하고 `FeedWebMapper`로 응답 DTO를 만듭니다
`adapter:inbound:grpc`	health·reflection	피처 proto 없이 Netty 서버를 직접 수명주기 관리합니다
`adapter:inbound:graphql`	최소 헬스 스키마	피처 스키마·리졸버 추가는 소비 프로젝트의 확장 작업입니다
`adapter:inbound:websocket`	STOMP-over-SockJS 실시간 채널	인프로세스 도메인 이벤트를 토픽으로 보내는 best-effort 경로이며 내구성 있는 outbox가 아닙니다

기본 실행에 연결한 Feed 경로는 이 규칙을 가장 짧게 보여 줍니다. FeedController는 GetFeedQuery를 만들어 getFeed.handle(...)에 넘긴 뒤 FeedSummary를 웹 DTO로 매핑하며 JPA 리포지토리나 엔티티를 호출하지 않습니다. WEB_ADAPTER_DOES_NOT_DEPEND_ON_PERSISTENCE_OR_OUTBOUND_ADAPTERS가 이 우회를 금지하고 CONTROLLERS_DO_NOT_RETURN_DOMAIN_OR_ENTITY_TYPES는 공개 메서드의 raw 반환 타입이 지정된 도메인·영속 entity·repository 패키지 타입이 되는 것을 막습니다(제네릭 내부 타입까지 검사하지는 않습니다).

세 opt-in 모듈이 있다고 업무 API까지 완성된 것은 아닙니다. gRPC는 health·reflection만, GraphQL은 최소 헬스 스키마만 제공하고 WebSocket 경로의 도메인은 STOMP를 알지 못합니다. 실제 전송 기능을 추가하려면 각 모듈에 피처 계약을 더해야 합니다. 이렇게 얇은 opt-in 모듈로 남겨 두면 기본 애플리케이션에 불필요한 전송 의존을 넣지 않고도 확장 지점을 시험할 수 있습니다. 마지막 안전망은 전송 종류와 무관합니다. INBOUND_ADAPTERS_DO_NOT_DEPEND_ON_OUTBOUND_ADAPTERS가 인바운드에서 아웃바운드로 향하는 모든 직접 의존을 거부합니다.

아웃바운드 어댑터 — 유형별

아웃바운드 모듈 열 개도 같은 깊이로 구현하지 않았습니다. persistence-jpa처럼 실제 구현을 넣은 모듈이 있는 반면, cache-redis·messaging·notification에는 RedisClient·KafkaSender·SlackClient 인터페이스만 두었습니다. 프로젝트마다 외부 시스템 선택이 달라질 수 있어 “바로 실행할 기준 구현”과 “소비 프로젝트가 채울 확장점”을 구분했습니다. 구현 깊이는 달라도 인바운드나 다른 아웃바운드 구현을 직접 선택하지 않는 규칙은 같게 적용했습니다.

묶음	모듈	구현된 능력	도입 시 확인할 예외
영속성	`persistence-jpa`, `persistence-mongo`	RDBMS 구현과 opt-in NoSQL 배선	멱등성·outbox·분산 락은 JPA에 구현돼 있습니다. Mongo는 드라이버·리포지토리 스캔 배선만 있고`document`와 `repository`는 템플릿을 가져다 쓰는 프로젝트에서 추가합니다.
SDK 없는 확장점	`cache-redis`, `messaging`, `notification`	실제 Redis·Kafka·Slack 클라이언트를 연결할 인터페이스	모듈이 존재해도 벤더 연결이 완성된 것은 아닙니다
외부 시스템	`objectstorage`, `httpclient`, `fileserver`	AWS SDK S3/MinIO, 회복성 HTTP, 순수 JDK 파일 출력	클라이언트 유무와 빈 활성화 조건이 서로 다릅니다
기반 구현	`identifier`, `support`	UUIDv7 식별자와 공통 상관관계 로깅	`support`만 형제들이 공유할 수 있습니다

영속성의 기준 구현은 persistence-jpa입니다. Feed 엔티티·리포지토리·매퍼와, 나중에 확인할 트랜잭션·락·멱등성·outbox 구현이 이 모듈에 놓입니다. PostgreSQL 드라이버는 runtimeOnly라 compileClasspath에 들어오지 않습니다. .postgresql 밖의 패키지는 PERSISTENCE_RDBMS_STAYS_VENDOR_NEUTRAL 규칙 때문에 벤더 타입을 참조하지 못합니다.

cache-redis·messaging·notification 세 모듈의 빌드에는 각각 Redis SDK, Kafka SDK, Slack SDK 선언이 없습니다. ca-tmpl을 가져다 쓰는 프로젝트에서 RedisClient, KafkaSender, SlackClient의 실제 구현을 연결해야 합니다. 인터페이스가 클래스패스에 보인다고 외부 시스템 연동까지 끝난 것은 아닙니다.

의존 권한도 균일하지 않습니다. objectstorage·fileserver·persistence-mongo는 application-core·shared-contract만 볼 수 있어 도메인 어휘를 모르고 나머지는 맡은 구현에 따라 domain-core 접근이 허용됩니다. support는 화이트리스트에 명시적으로 등록된 공유 기반입니다. messaging·cache-redis·notification·httpclient 네 모듈은 support를 볼 수 있지만 support가 형제 구현을 역으로 선택할 수는 없습니다. OUTBOUND_ADAPTERS_DO_NOT_DEPEND_ON_INBOUND_ADAPTERS가 전송 계층으로 향하는 의존을 차단하고 OUTBOUND_ADAPTERS_ARE_PEERS_SHARING_ONLY_SUPPORT는 같은 아웃바운드의 직접 의존을 금지합니다.

이렇게 제한하는 이유는 아웃바운드 구현 하나가 다른 구현을 선택하기 시작하면 교체 단위가 서로 묶이기 때문입니다. 공통 로깅과 상관관계 기능만 support로 공유하고 구체 어댑터 간 의존은 금지해 각 구현을 독립적으로 바꿀 수 있게 합니다. 대신 support가 잡다한 공용 모듈로 커지지 않도록 화이트리스트와 ArchUnit 규칙을 함께 유지해야 합니다.

조립 — app-bootstrap composition root

모듈 등록과 기능 실행은 한 단계로 묶지 않았습니다. settings.gradle은 모듈의 존재만 등록하고, app-bootstrap이 런타임 클래스패스에 올릴 모듈을 고릅니다. 그다음 Spring의 조건부 설정이 실제 빈을 활성화합니다. Composition root에서 이 세 선택을 한곳에 모았습니다.

objectstorage·fileserver·persistence-mongo도 프로젝트 의존성으로 명시합니다. 따라서 이 세 모듈은 main 클래스패스에 들어오지만, 실제 빈의 활성화 여부는 런타임 프로퍼티로 결정됩니다. 셋 다 ca-skeleton.<모듈>.enabled 기본값이 꺼짐입니다. 반면 grpc·graphql·websocket은 저장소에 포함되어 있지만 app-bootstrap의 프로젝트 의존성에는 없습니다. 이는 클래스패스에 등록하고 나면 @ConditionalOnProperty로 켜고 끌 수단이 남지 않기 때문입니다.

세 모듈이 그런 상태인 근거는 각각 다릅니다. GrpcServerConfig의 게이트는 matchIfMissing = true라 플래그가 없으면 기본이 켜짐이고, HealthGraphqlController와 WebSocketConfig에는 조건 애노테이션이 아예 없습니다. CaSkeletonApplication이 dev.caskeleton.adapter를 통째로 컴포넌트 스캔하므로, 클래스패스에 올리는 순간 각각 별도 TCP 포트·/graphql 마운트·/ws STOMP 엔드포인트가 부팅마다 생깁니다. 이 셋에게는 의존성 선언을 하지 않는 것이 유일한 opt-in 수단입니다.

그런데 클래스패스에 모듈이 있다고 모든 빈이 바로 실행되는 것은 아닙니다. persistence-mongo가 그 사례입니다. 모듈 자신의 @ConditionalOnProperty는 자기 빈만 통제할 뿐, 스타터가 클래스패스에 올라오면 발동하는 Spring Boot 자체의 Mongo 자동설정까지 막지는 못합니다. 그래서 조립 루트가 나머지 절반을 맡습니다. app-bootstrap의 application.yml이 spring.autoconfigure.exclude로 Mongo 자동설정 세 개를 꺼 클래스패스를 무력화하고, 모듈이 켜질 때 MongoPersistenceConfig가 @ImportAutoConfiguration으로 같은 셋을 되살립니다. 명시적 import는 spring.autoconfigure.exclude의 영향을 받지 않으므로 모듈을 켰을 때 자동 설정을 다시 활성화할 수 있습니다. 따라서 이 opt-in 동작은 조립 루트와 모듈이 함께 구현하는 계약입니다.

아래 그림은 app-bootstrap의 main 프로젝트 의존에 포함된 어댑터 열한 개와 현재 main 의존 목록에 없는 참조 어댑터 세 개를 비교합니다. 실행 시 활성 빈 전체를 측정한 그림은 아닙니다.

Diagram description

왼쪽 비교 항목은 app-bootstrap의 main 프로젝트 의존에 포함되어 main 클래스패스에 들어오는 어댑터 11개를 나타냅니다. 클래스패스 포함과 실제 빈 활성화는 별개이며 런타임 조건이 활성화를 추가로 결정합니다. 오른쪽 비교 항목은 현재 main 의존 목록에 없는 grpc, graphql, websocket 세 참조 어댑터를 나타냅니다. 이 셋은 클래스패스에 등록되면 기본 활성화되므로 의존성 선언을 하지 않는 것이 opt-in 수단입니다. 두 수치는 main 의존 선언을 비교한 것이며 실행 시 활성 빈 전체를 측정한 값이 아닙니다.

Editable source · Grounded VizSpec

// ca-tmpl · adapter/outbound/cache-redis/.../RedisCacheAdapterConfig.java
@Bean
@ConditionalOnProperty(
    name = "app.cache.redis.enabled",
    havingValue = "true",
    matchIfMissing = false)
public CacheBackend redisCacheBackend(RedisClient redisClient) {
  return new RedisCacheStore(redisClient);
}

@ConditionalOnProperty가 외부 백엔드 빈 활성화를 한 번 더 결정합니다.

app-bootstrap이 의존하는 모듈도 모두 실행되지는 않습니다. Redis나 Kafka 같은 외부 백엔드는 런타임 프로퍼티가 켜졌을 때만 빈으로 등록됩니다. 프로퍼티는 이미 클래스패스에 들어온 모듈의 기능만 선택하며, 의존성에 없는 모듈을 자동으로 불러오지는 않습니다. sample-portfolio도 테스트용 의존으로만 연결되어 기본 애플리케이션의 main 클래스패스에는 들어가지 않습니다. 샘플을 제거한 뒤에도 핵심 테스트가 동작하는지는 별도의 빌드 테스트로 확인합니다.

// ca-tmpl · app-bootstrap/build.gradle:16-21
configurations {
    sampleFixture {
        canBeConsumed = false
        canBeResolved = false
    }
}

testCompileClasspath·testRuntimeClasspath는 sampleFixture를 확장하므로 테스트에서는 sample-portfolio와 WorkLog 같은 샘플 전용 타입이 함께 보입니다. 반대로 main의 compileClasspath·runtimeClasspath는 이 configuration을 확장하지 않습니다. 격리 주장은 테스트 클래스패스 전체가 아니라 main 프로덕션 컴파일·런타임 그래프에 한정됩니다. sampleOffTest는 샘플 없는 핵심 테스트 경로를 별도로 정의하고 SampleRemovalSmokeContractTest는 지정된 열다섯 모듈이 샘플을 일반 프로덕션 configuration으로 참조하지 않는지 검사합니다. main 클래스패스 밖의 세 어댑터까지 자동 탐색하지는 않습니다.

격리는 main 프로덕션 그래프에 한정됩니다. 테스트 클래스패스에는 샘플과 그 전이 의존이 함께 보입니다.

메인 엔트리와 두 번째 composition root. 이렇게 배선된 그래프가 부팅하는 지점은 클래스 하나입니다. CaSkeletonApplication은 bootstrap·adapter·application·domain·shared 다섯 패키지를 컴포넌트 스캔과 @ConfigurationProperties 스캔 양쪽에 명시적으로 올립니다.

// ca-tmpl · app-bootstrap/.../CaSkeletonApplication.java:7-22
@SpringBootApplication(
    scanBasePackages = {
      "dev.caskeleton.bootstrap",
      "dev.caskeleton.adapter",
      "dev.caskeleton.application",
      "dev.caskeleton.domain",
      "dev.caskeleton.shared"
    })
@ConfigurationPropertiesScan(
    basePackages = {
      "dev.caskeleton.bootstrap",
      "dev.caskeleton.adapter",
      "dev.caskeleton.application",
      "dev.caskeleton.domain",
      "dev.caskeleton.shared"
    })

sample-portfolio는 여섯 번째 최상위 패키지 dev.caskeleton.sample 아래에 있으므로 이 스캔에서도 제외됩니다. 클래스패스 격리와 패키지 스캔 격리가 같은 방향을 가리킵니다. 그렇다고 샘플이 부팅 불가능한 코드 조각은 아닙니다. sample-portfolio는 Spring Boot 플러그인을 직접 적용한 두 번째 독립 composition root입니다. 자체 SamplePortfolioApplication이 프로덕션 모듈과 샘플 패키지를 함께 스캔하되 샘플 전용 영속 구성으로 대체할 설정과 공개 데모에서 제외할 보안 구성은 필터로 제외합니다.

클래스패스가 경계를 강제하는 원리

domain-core에서는 Spring·JPA 타입을 금지 목록에만 올리지 않고 main compileClasspath에서도 제외했습니다. 패키지가 코드를 어디에 둘지 보여 준다면, 모듈은 그 코드가 볼 수 있는 타입 자체를 줄입니다. 저는 이 차이를 이용해 의존 그래프를 문서상의 약속이 아니라 컴파일러가 검사하는 규칙으로 만들었습니다.

한 가지 모델을 짚고 가겠습니다. 자바는 컴파일 시 각 모듈의 클래스패스(그 모듈이 볼 수 있는 타입의 집합)를 기준으로 타입을 해석합니다. Gradle 멀티모듈은 이 클래스패스를 모듈마다 분리하므로 직접 또는 전이 main 의존으로 도달하지 않는 라이브러리 타입은 그 모듈의 main 컴파일에서 보이지 않습니다. 뒤에서 확인할 경계 검사는 모두 이 클래스패스 분리를 전제로 합니다.

멀티모듈이면 각 모듈의 build.gradle이 자기가 필요한 것만 선언합니다. domain-core leaf는 main 의존을 선언하지 않고 shared-contract도 main compile 의존이 비어 있습니다. 두 모듈의 lockfile은 compileClasspath·runtimeClasspath를 빈 configuration으로 기록합니다. 애플리케이션 코어 lockfile에는 Spring Boot·DI 관련 main 의존이 있지만 Spring Web·WebMVC는 테스트 configuration에만 나타나고 Spring TX·JPA 항목은 없습니다. 그 결과 각 코어 모듈에서 정책상 금지한 타입이 그 모듈의 main compileClasspath에 없습니다. 도메인 클래스에 import org.springframework...를 쓰면 테스트 단계까지 갈 것도 없이 해당 모듈의 소스를 컴파일하는 모든 빌드에서 javac가 실패합니다.

여기서 configuration의 범위도 분명히 해야 합니다. Gradle의 Java Library 플러그인 맥락에서 api는 공개 계약 타입을 소비자에게 전이 노출하고 implementation은 구현 의존을 내부로 좁힙니다. 현재 ca-tmpl의 leaf subproject는 java 플러그인을 적용하고 java-library는 적용하지 않습니다. 빌드 파일은 implementation 의존을 사용하며 api 선언은 없습니다. 따라서 이 구성을 Java Library 플러그인의 api/implementation 캡슐화 선택으로 해석해서는 안 됩니다.

// ca-tmpl · adapter/inbound/web/build.gradle
implementation project(':domain-core')
implementation project(':application-core')
implementation project(':shared-contract')

실행 시점 드라이버에는 runtimeOnly, 컴파일 보조 도구에는 compileOnly 같은 별도 configuration도 씁니다. 경계 강제에 중요한 사실은 각 모듈이 컴파일에 필요한 의존을 직접 드러낸다는 점입니다. Java Library 플러그인을 도입해 공개 API를 설계한다면 api의 소비자 편의와 넓어진 전이 가시성을 함께 평가해야 합니다.

그렇다면 하나의 모듈 안에서 패키지만으로 클린 아키텍처를 표현하면 어떻게 될까요? 차이는 여기서 드러납니다.

멀티모듈의 실익은 규칙 수가 아니라 실패 시점입니다. 금지 타입이 클래스패스에서 사라져 javac가 먼저 멈추는 반면, 단일모듈은 같은 위반을 ArchUnit 실행까지 미룹니다.

단일 모듈이면 모든 클래스가 하나의 컴파일 클래스패스를 공유합니다. 어댑터 코드에는 Spring과 JPA가 필요하니 그 의존이 모듈에 들어옵니다. 그러면 도메인 패키지에서도 그 타입들이 그대로 보입니다. domain 패키지 안에서 import org.springframework...를 써도 컴파일이 멀쩡히 통과합니다. 남는 방어선은 패키지 규칙 기반의 ArchUnit 하나뿐입니다. 이건 컴파일 이후에 도는 테스트라서 끄거나 glob을 잘못 쓰거나 깜빡 잊으면 조용히 통과합니다.

이 경계를 검증하려고 위반 픽스처의 클래스패스도 분리했습니다. 프로덕션 application-core에는 spring-tx가 없어 @Transactional 타입을 해석할 수 없습니다. 그래서 ArchUnit 규칙을 시험하는 픽스처는 app-bootstrap의 테스트 소스셋에 두고, 그 소스셋에만 spring-tx를 testCompileOnly로 추가했습니다.

// ca-tmpl · app-bootstrap/build.gradle — 위반 픽스처를 "컴파일"하기 위해서만 되넣는다
testCompileOnly 'org.springframework:spring-tx'

이 한 줄이 프로덕션과 규칙 테스트의 클래스패스를 갈라 놓습니다. 프로덕션 코어에서는 금지 타입이 해석되지 않고 위반 픽스처를 평가하는 테스트 소스에서만 그 타입이 보입니다. 단일 모듈의 공유 클래스패스라면 이런 분리가 성립하지 않습니다.

세 겹 게이트 — 클래스패스·화이트리스트·ArchUnit

클래스패스 격리 하나로 모든 위반을 막을 수는 없습니다. 클래스패스는 코어에 없는 외부 타입은 막아도, 허용된 타입 사이의 잘못된 모듈 의존이나 같은 모듈 안의 패키지 위반까지 모두 알 수 없습니다. 그래서 ca-tmpl에는 컴파일 클래스패스, Gradle 화이트리스트, ArchUnit을 함께 둡니다. 세 검사는 맡은 위반이 다르며 고정된 실행 순서나 속도 순위를 뜻하지 않습니다.

세 게이트는 각기 다른 위반 유형을 맡습니다. 실행 순서나 속도 순위는 없습니다. 모듈을 합치면 클래스패스 격리와 프로젝트 의존 정책의 범위가 사라지고 ArchUnit의 별도 범위만 남습니다.

겹	무엇을 막나	언제	단일모듈이면
① 컴파일 클래스패스 격리	코어의 금지된 서드파티 import	해당 모듈을 컴파일하는 빌드의`javac`	사라짐
② Gradle 모듈 화이트리스트	금지된 모듈→모듈 의존	빌드 검증(check)	사라짐
③ ArchUnit 패키지 규칙	패키지·타입 수준 위반	테스트	유일하게 남음

Gradle 모듈 화이트리스트(②). 루트 build.gradle에 각 모듈이 의존해도 되는 모듈을 명시한 지도가 있습니다.

// ca-tmpl · build.gradle — 정책 발췌 (전체 맵의 일부)
Map<String, Set<String>> allowedProjectDependencies = [
    'domain-core'      : ['shared-contract'],
    'application-core' : ['domain-core', 'shared-contract'],
    'adapter:outbound:objectstorage' : ['application-core', 'shared-contract'],  // domain-core 없음
    //...
    'shared-contract'  : [],                                                     // 허용 project 의존 0
]

verifyCleanArchitectureDependencies 태스크는 각 모듈의 api·implementation·compileOnly· runtimeOnly 네 production configuration에 직접 선언된 project(...) 의존만 읽어 이 화이트리스트와 대조합니다. 벗어난 의존이 하나라도 있으면 GradleException이 발생해 검증이 실패합니다. 테스트·사용자 정의 configuration과 해석된 전이 의존 그래프는 검사 범위가 아닙니다. 이 태스크는 모든 모듈의 check에 걸려 있고 양방향 완전성을 검사합니다. 정책에만 있고 존재하지 않는 모듈이 있어도, 반대로 새 모듈을 추가하고 정책에 등록하지 않아도 check가 실패합니다. 규칙을 모르는 새 코드가 정책 밖에서 들어오는 것을 막습니다.

ArchUnit 바이트코드 규칙(③). 모듈 그래프가 못 보는 패키지 내부까지 잡습니다.

// ca-tmpl — 도메인이 Spring/JPA/Lombok/다른 계층을 의존하면 테스트 실패
static final ArchRule DOMAIN_IS_PURE =
    noClasses().that().resideInAPackage("..domain..")
.should().dependOnClassesThat()
.resideInAnyPackage("org.springframework..", "jakarta.persistence..", "lombok..", "..adapter..");
// 대표 4개 발췌 — 실제 규칙은 13개 금지 패키지

세는 기준. "규칙 수"는 @ArchTest가 붙은 ArchRule을 센 것입니다. CleanArchitectureTest 57개, DisabledAdapterArchitectureTest 2개, NamingConventionTest 2개, ScheduledJobOverlapPolicyTest 1개, TaskExecutorDecoratorPolicyTest 1개 — 총 63개가 5개 클래스에 분산돼 있습니다. 별도로 manual importer로 직접 평가하는 4개 규칙을 합치면 static final ArchRule은 8개 클래스의 67개입니다.

규칙의 폭이 넓습니다. 도메인 순수성뿐 아니라 읽기 전용 유스케이스가 리포지토리 쓰기 메서드를 부르지 못하게, 컨트롤러와 아웃바운드 어댑터의 raw 반환 타입이 지정된 패키지 타입이 되지 못하게까지 검사합니다. 도메인 순수성은 DOMAIN_IS_PURE 하나로 끝나지 않습니다. 도메인 로거 금지, @ValueObject의 public 무인자 생성자 금지, @AggregateRoot의 public setter 금지라는 세 모델링 가드레일이 함께 받칩니다.

세 겹에 비공허성 검증(뒤의 test-the-test 절)과 사람·운영 판단을 더하면 서로 겹치지만 대체할 수 없는 다섯 강제 범위가 됩니다.

다섯 범위는 서로 대체하거나 항상 같은 순서로 실행되는 단계가 아닙니다. 각 범위가 잡는 위반 종류와 놓치는 영역이 달라 함께 경계를 보완합니다.

구현으로 설명하는 요청 경로

Feed 조회는 제가 모듈 경계를 설명하기 위해 만든 가장 짧은 기준 경로입니다. 유스케이스, 트랜잭션 포트, 영속 어댑터를 모두 지나지만 흐름은 네 단계로 끝납니다. 이 경로를 먼저 설명한 뒤 쓰기 경로에서 사용하거나 계약만 준비해 둔 검증, 예외·오류 응답, 로깅·추적, 트랜잭션·일관성, 멱등성, outbox를 각각 나누어 설명하겠습니다.

Feed 조회 경로 — 컨트롤러에서 응답까지

GET /feed?page=0&size=20 요청은 컨트롤러에서 응답을 만들 때까지 다음 네 단계를 지나도록 구현했습니다. 포트와 어댑터 타입은 여러 개지만 실제 읽기 호출은 이 순서로 끝납니다.

FeedController가 쿼리 파라미터로 GetFeedQuery(page, size)를 만들어 getFeed.handle(...)을 호출합니다. 컨트롤러가 주입받은 선언 타입은 구체 클래스 GetFeedUseCase입니다.
GetFeedUseCase.handle()은 @UseCaseCapability(transactionMode = READ_ONLY, repositoryAccess = READ_REPOSITORY)를 선언하고 tx.inRead(() -> feedQuery.loadFeed(...))를 호출합니다. 읽기 트랜잭션 경계 안에서 출력 포트를 부릅니다.
DI가 연결한 FeedQueryAdapter가 FeedQueryPort 계약의 실체로 실행됩니다. JPA 조회 결과에서 코어의 읽기 전용 투영 FeedSummary를 직접 조립합니다. 도메인 애그리게이트 재구성은 건너뜁니다.
결과 List<FeedSummary>가 유스케이스와 트랜잭션 경계를 되돌아 나오고 FeedWebMapper.toResponse가 이를 웹 응답 FeedResponse로 다시 조립해 컨트롤러가 반환합니다.

실제 실행은 GetFeedUseCase가 TransactionPort.inRead에 들어간 뒤 콜백에서 FeedQueryAdapter를 호출하고 결과를 되돌리는 순서입니다. FeedQueryPort는 런타임 lifeline이 아니라 컴파일 시점 타입 계약입니다.

이렇게 구현했기 때문에 HTTP 응답 바디는 FeedResponse가 정하고 코어는 그 모양을 모릅니다. 피드 항목은 FeedItemJpaEntity → FeedSummary → FeedResponse 세 모델을 거치고, 두 매핑은 모두 어댑터가 맡습니다. 소스 의존도 컨트롤러와 어댑터에서 코어 쪽으로만 향합니다. Feed 조회 한 건에 포트 소유권과 모델 분리, 클래스패스 격리를 함께 담았습니다.

검증 — 3계층과 Feed 경로의 공백

현재 Feed 경로에는 page와 size의 웹 경계 검증을 연결하지 않았습니다. FeedController에는 Bean Validation도 범위 거부도 없습니다. 두 파라미터는 @RequestParam(required = false, defaultValue = "0")로만 선언돼 있고 파일 전체에 jakarta.validation import도 @Valid도 범위 제약도 없습니다. 다만 영속성 어댑터 FeedQueryAdapter.loadFeed()가 Math.max(0, page)로 음수 페이지를 0으로, size <= 0? 20 : size로 0 이하 크기를 20으로 정규화합니다. 이는 잘못된 값을 4xx로 거부하는 입력 검증이 아니라 저장소 호출 직전의 폴백입니다. 비정상적으로 큰 size에는 상한이 없습니다.

검증의 기준 구현은 sample-portfolio의 Poster·WorkLog 경로에 넣었습니다. 여기서는 "형식이 맞는가", "여러 필드가 서로 앞뒤가 맞는가", "이 상태 전이가 도메인 규칙을 지키는가"를 서로 다른 곳에서 검사합니다. 세 질문을 한 계층에 몰아넣으면 도메인이 jakarta.validation 애노테이션을 알게 되거나, 애플리케이션 계층이 웹 프레임워크의 예외 처리를 흉내 내야 하기 때문입니다.

웹 경계 — 문법. CreatePosterRequest는 record에 @NotBlank·@Size를 붙여 "필드가 있는가, 길이가 맞는가"만 검사합니다. CreateWorkLogRequest는 한 걸음 더 나가 @GroupSequence({Syntax.class, Invariant.class, CreateWorkLogRequest.class})로 검증 순서를 강제합니다. Syntax 그룹이 통과해야 Invariant 그룹의 @AssertTrue isPeriodOrdered()(종료일이 시작일보다 앞서지 않는가)가 실행됩니다. 두 DTO는 컨트롤러에서 @Valid @RequestBody로 소비됩니다.
애플리케이션 — 같은 검증을 반복하지 않습니다. 유스케이스는 커맨드를 받으며 같은 Bean Validation을 반복하지 않습니다. 이 경계는 VALIDATION_CONSTRAINTS_STAY_AT_WEB_BOUNDARY ArchUnit 규칙이 ..domain..·..application.. 패키지의 jakarta.validation.. 의존을 거부해 고정한 것입니다.
도메인 — 불변식. Poster의 제목은 반드시 requireValidTitle을 거치고 publish()는 이미지가 없으면 PosterInvariantException(IMAGE_REQUIRED)를 던집니다. 웹이 이미 걸러낸 것과 무관하게 도메인이 다시 지킵니다.

도메인 게이트에도 한계를 함께 기록합니다. rehydrate(...)는 저장된 imageKey·status를 그대로 생성자에 넘기며 생성자 검사 너머의 불변식을 재도출하지 않습니다. PUBLISHED와 빈 이미지의 조합까지 재검증하는 완전한 복원 게이트는 아닙니다. Feed 경로에서는 검증이 더 적었습니다. FeedItem의 유일한 생성 경로는 Objects.requireNonNull만 쓰므로, 클라이언트 입력과 서버 버그를 구분하는 Reason 같은 장치가 없고 null이 들어오면 그냥 NullPointerException이 납니다.

계층 규율을 고정하는 규칙과 대표 테스트는 다음과 같습니다.

검사	고정하는 경계
`VALIDATION_CONSTRAINTS_STAY_AT_WEB_BOUNDARY`	도메인·애플리케이션 패키지의`jakarta.validation..` 의존 거부
`VALID_CASCADE_DEPTH_AT_MOST_THREE`	`@Valid` 캐스케이드의 직접 raw 필드 사슬을 3단계로 제한하는 근사 가드 — 컨테이너 제네릭 원소와 수렴 그래프의 최장 경로는 정확히 추적하지 못할 수 있습니다
`PosterControllerWireTest`	빈 제목은 유스케이스 전에 400`VALIDATION_FAILED`, 이미지 없는 발행은 400 `POSTER_IMAGE_REQUIRED`
`PosterTest`	null/blank 제목이 NPE가 아닌`PosterInvariantException(TITLE_BLANK)`로 실패

예외·오류 응답 — 두 단계 처리 사슬, 하나의 Envelope

모든 예외를 하나의 핸들러에서 Envelope로 바꾸지는 않았습니다. Poster.publish()에서 발생한 예외는 분류하는 곳과 공개 메시지를 고르는 곳을 나눴습니다. sample-portfolio의 독립 실행점에서는 두 단계 @RestControllerAdvice 체인이 이 일을 맡습니다. 기본 CaSkeletonApplication에는 샘플 모듈이 없으므로 같은 도메인 핸들러 체인도 생기지 않습니다.

샘플 소유 DomainExceptionHandler는 @Order(Ordered.HIGHEST_PRECEDENCE)로 먼저 실행되어 WorkLog·Poster의 도메인 예외 다섯 종류를 포트폴리오 오류 코드로 바꿉니다. 뒤의 GlobalExceptionHandler는 운영·전송·보안·인프라 실패를 맡습니다. 17개 @ExceptionHandler와 7개 전송 오류 재정의, 도합 24개 메서드가 있으며 분류되지 않은 예외는 마지막 Exception.class 핸들러에서 500 INTERNAL_ERROR가 됩니다. 도메인 핸들러는 SQLState나 업스트림 장애를 모르고 전역 핸들러는 PosterInvariantException.Reason이나 PortfolioErrorCode를 import하지 않습니다.

오류 응답의 모양은 Envelope<T>(success, data, error, meta)입니다. 성공·실패 팩토리는 전달받은 값을 관례상 data 또는 error 한쪽에 놓습니다. 그러나 팩토리는 인자를 null 검사하지 않고 record 생성자도 이를 강제하지 않습니다. exactly-one/non-null은 타입 불변식이 아니라 호출자 사용 규율입니다. 이것이 전체 HTTP 성공 응답의 유일한 형식도 아닙니다. FeedController.feed()는 List<FeedResponse>를 직접 반환합니다. 실패 본문 ApiError(code, category, message, retryable, details)에서 code는 클라이언트의 안정된 분기 키이고 retryable은 같은 호출을 다시 시도할 가치가 있는지를 별도로 나타냅니다.

운영 분류와 도메인 분류도 서로 독립적입니다. OperationalError는 코드 54개를 13개 그룹으로 나누고 PortfolioErrorCode는 샘플 전용 6개 값을 정의합니다. 둘 다 ApiErrorCode를 구현하므로 응답 팩토리는 같은 계약을 쓰지만 한 enum의 변경이 다른 enum의 변경을 요구하지 않습니다.

실패 경로	최초 분류	HTTP 투영	공개하지 않는 것
이미지 없는`Poster.publish()`	`DomainExceptionHandler`가 `IMAGE_REQUIRED`를 `POSTER_IMAGE_REQUIRED`로 변환	400`Envelope`	내부 상태 전이 구현
SQLState`23505` 매핑 계약	`StandardSqlStateErrorMapping`이 `DB_UNIQUE_VIOLATION` 선택, 전역 핸들러 테스트는 `CONFLICT` 안전 메시지 투영	두 구성요소의 독립 계약	SQLState·제약명·원본 진단 메시지
`DependencyFailureException`	전역 핸들러가 코드별 안전 메시지 선택	코드에 따라`Retry-After` 추가	의존성 이름과 원본 진단 메시지
멱등성 충돌	전용 타입별 핸들러 — 현재 호출 엔드포인트 0	실행 중 409, 지문 불일치 422, 범위 누락 400	저장 레코드 내부 상태

특히 SQLState 행은 실제 요청 사슬을 뜻하지 않습니다. portable 매핑과 전역 핸들러는 각각 테스트되지만, PersistenceExceptionTranslator.translate(...)를 호출하는 프로덕션 소비자는 없습니다. 따라서 23505 → DB_UNIQUE_VIOLATION → HTTP 409 전체가 이미 배선됐다고 읽으면 안 됩니다.

Retry-After는 retryable=true와 동의어가 아닙니다. RetryAfterAdvisor에 등록된 8개 코드에만 값이 있고 나머지는 헤더를 만들지 않습니다. 영속성·의존성 핸들러도 원본 메시지를 잘라 쓰지 않습니다. 내부 진단 정보가 응답으로 새는 것을 막기 위해 ClientSafeErrorMessages가 코드와 카테고리에 따른 고정 문자열을 선택합니다. 원본 예외 메시지를 그대로 쓰는 방식 대신 안전한 공개 메시지를 유지하므로, 새 오류 코드를 추가할 때마다 메시지 매핑도 함께 관리해야 합니다.

// GlobalExceptionHandler.java:224-236 (persistence — 카테고리 기반 고정 메시지, 발췌)
@ExceptionHandler(PersistenceFailureException.class)
public ResponseEntity<Envelope<Void>> handlePersistenceFailure(PersistenceFailureException ex) {
  ApiErrorCode code = ex.errorCode();
  log.error(
      "persistence failure classified as {} (category={}, retryable={})",
      code.code(), code.category(), code.retryable(), ex);
  spanErrorRecorder.recordException(ex, code.code());
  return ErrorResponseFactory.envelope(
      code, ClientSafeErrorMessages.forPersistence(code.category()), null);
}

분류 코드가 있다고 웹 배선까지 생기지는 않습니다. 멱등성 예외 셋은 전용 핸들러가 있지만 LockAcquisitionTimeoutException.errorCode()는 409·retryable 분류를 반환하면서도 ApiErrorCarrier를 구현하지 않고 웹 전용 핸들러도 없습니다. 프로덕션 애플리케이션/유스케이스 범위의 tryAcquire 호출자가 0개라 현재 요청이 이 예외를 내는 경로는 없습니다. 향후 호출자만 추가하고 예외를 그대로 올리면 catch-all이 500으로 처리합니다. 현재 장애는 아니지만 락을 HTTP 경로에 도입할 때 함께 닫아야 할 배선 공백입니다.

409 분류 계약의 존재와 실제 웹 응답 배선은 별개입니다. 분류만으로 409 응답이 보장되지 않습니다.

테스트가 증명하는 범위도 나뉩니다. GlobalExceptionHandlerTest는 SQL 제약명·의존성 진단 메시지가 응답에 없음을, OperationalErrorTest는 enum 전체의 카테고리 배정과 결정적 client 오류의 retryable=false를 각각 증명하며 24개 핸들러 전체의 균일한 커버리지나 실제 HTTP caller 배선은 증명하지 않습니다. 새 오류 타입을 도입할 때는 코드 등록, 안전 메시지, 핸들러 배선, 비노출 테스트를 각각 확인해야 합니다. enum에 값 하나를 추가하는 것만으로 wire 계약이 완성되지 않습니다.

로깅·추적 — 상관관계 ID의 MDC 전파와 가명화

상관관계 ID와 사용자 가명값은 모두 MDC에 넣지만 같은 책임으로 묶지는 않았습니다. 상관관계 ID는 흩어진 로그를 한 요청으로 묶고, 가명화는 그 로그에 원본 사용자 식별자가 남지 않게 합니다. 둘은 같은 MDC(Mapped Diagnostic Context, 스레드별 로그 문맥 저장소)를 사용하지만 RequestLoggingFilter가 요청 수명을 관리하고 UserPrincipalPseudonymizerPort가 사용자 식별자를 바꿉니다. 아웃바운드 어댑터는 OutboundCorrelation으로 이미 만들어진 값을 읽습니다. 도메인은 DOMAIN_HAS_NO_LOGGER 때문에 이 계약 전체를 모릅니다.

필터·응답 메타데이터·아웃바운드 로깅의 키 이름이 달라져 추적이 끊기는 것을 막기 위해 키 이름은 docs/registries/mdc-keys.yaml에서 한 번만 관리합니다. 이 레지스트리는 19개 키를 등록하며 request_id·trace_id·span_id·correlation_id·tenant_id·user_principal을 core SSOT(single source of truth, 단일 기준)로 표시합니다. 응답에는 ResponseMetaFactory가 request_id·trace_id·correlation_id만 camelCase로 옮깁니다(응답 3키 투영). 레지스트리에서 user_principal의 헤더 매핑은 null입니다.

요청 스레드의 수명주기는 다음 순서로 한 번만 정의됩니다.

RequestLoggingFilter가 X-Request-Id·X-Correlation-Id에서 CR/LF를 포함한 U+0000–U+001F 제어문자를 제거하고 200자로 제한합니다. 값이 없으면 새로 만듭니다. 유효한 W3C traceparent는 채택하고 아니면 새 root trace와 span을 만듭니다.
네 키를 MDC에 넣고 필터 체인을 실행합니다. 같은 스레드의 아웃바운드 로깅은 OutboundCorrelation.current()로 값을 읽으며 컨텍스트가 없으면 UNKNOWN을 씁니다.
체인이 정상 반환하거나 예외를 던지면 finally에서 인증 사용자의 원본 ID를 가명화 포트에 넘깁니다. HmacUserPrincipalPseudonymizer는 HMAC-SHA-256으로 64자리 소문자 hex를 만들고 필터는 그 결과만 user_principal에 넣어 http_request를 기록합니다.
가명 처리와 로그 기록이 끝나면 5키 제거를 수행합니다.

다만 이 구현이 모든 실패에서 MDC 제거를 보장하지는 않습니다. chain.doFilter의 정상 반환과 예외는 모두 같은 정리 경로를 지나지만, 가명 처리나 log.info 자체가 제거 전에 런타임 예외를 던지면 중첩 finally가 없어 제거 호출을 건너뜁니다. 가명화 포트에도 예외 없음(no-throw) 계약은 없습니다. 현재 구현이 보장하는 것은 체인 성공·실패 뒤 정리 시도와, 정리 본문이 끝났을 때의 5키 제거까지입니다.

도식은 필터 체인의 성공·예외 뒤 같은 정리 경로가 시작되는 것과, 정리 본문 자체의 실패까지 5키 제거가 보장되지는 않는 것을 구분합니다.

비동기 경계에는 별도 조건이 붙습니다. 원시 스레드 전환은 thread-local MDC를 자동 복사하지 않습니다. 구성된 applicationTaskExecutor는 AsyncContextTaskDecorator를 설치해 제출 시점의 호출자 MDC를 스냅샷으로 잡고 worker에서 작업하는 동안만 설정한 뒤 이전 컨텍스트를 복원합니다. 이 executor를 우회한 스레드에서는 같은 전파를 기대할 수 없고 그때 OutboundCorrelation.current()는 UNKNOWN으로 떨어집니다.

전파와 실패 정책도 구분해야 합니다. 일반 OutboundMessagePublisher는 브로커 실패를 WARN으로 기록하고 삼키는 fail-open 경로입니다. OutboxMessagePublishAdapter는 같은 로거를 쓰되 예외를 다시 던지는 fail-closed 경로입니다. 로거가 정책을 정하는 게 아니라 호출자가 실패 이후의 제어 흐름을 정합니다.

공통 로거 구현에는 별도의 노출 위험이 있습니다.

// FailOpenDependencyLogger.java:37-48
public void logFailure(
    String dependencyName, String dependencyType, String operation, Throwable cause) {
  log.warn(
      "dependency_name=\"{}\" dependency_type=\"{}\" operation=\"{}\" "
          + "outcome=\"FAILURE\" correlation_id=\"{}\" error=\"{}: {}\"",
      dependencyName, dependencyType, operation,
      OutboundCorrelation.current(),
      cause.getClass().getSimpleName(),
      cause.getMessage());
}

시그니처에 payload는 없지만 cause.getMessage()는 살균하지 않습니다. 예외 메시지에 원본 요청 데이터가 들어가면 로그로 노출될 수 있습니다. "payload 파라미터를 받지 않는다"와 "민감 정보가 절대 기록되지 않는다"는 서로 다른 보장입니다. 테스트도 그 차이를 드러냅니다. FailOpenDependencyLoggerTest가 고정한 두 payload·PII 표식은 logger 입력으로 전달되지 않고 assertion literal로만 등장하므로 이 검증만으로 임의 예외 메시지의 살균을 증명하지 못합니다.

트랜잭션·일관성 — TransactionPort 3모드와 분산 락의 끊어진 사슬

TransactionPort와 DistributedLockPort는 같은 실행 흐름에 연결하지 않았습니다. TransactionPort는 애플리케이션 계층이 Spring의 @Transactional 없이 트랜잭션 의도를 선언하게 합니다. DistributedLockPort는 여러 애플리케이션 인스턴스가 같은 키를 다툴 때 사용할 상호 배제 계약입니다. 현재 프로덕션 애플리케이션과 유스케이스에는 tryAcquire(...) 호출자가 없습니다. 두 포트는 각각 계약·어댑터·테스트만 제공하며 하나의 프로덕션 흐름을 만들지는 않습니다.

TransactionPort는 inWrite/inRead/inNew 세 메서드를 노출하고 Supplier/Runnable 콜백을 받습니다. 런타임 예외가 나면 롤백한 뒤 그대로 전파합니다. inWrite는 REQUIRED 쓰기, inRead는 REQUIRED 읽기 전용, inNew는 REQUIRES_NEW이며 세 모드 모두 READ_COMMITTED를 명시합니다.

// SpringTransactionPort.java:60-71 — 세 모드 모두 격리 수준을 명시적으로 고정
private static TransactionTemplate template(
    PlatformTransactionManager transactionManager,
    TransactionMode mode,
    int propagation,
    boolean readOnly) {
  TransactionTemplate template = new TransactionTemplate(transactionManager);
  template.setName("application-" + mode.name().toLowerCase());
  template.setPropagationBehavior(propagation);
  template.setIsolationLevel(TransactionDefinition.ISOLATION_READ_COMMITTED);
  template.setReadOnly(readOnly);
  return template;
}

세 TransactionTemplate은 생성자에서 한 번만 만들어집니다. 요청마다 가변 템플릿을 재구성하지 않아 설정 경합을 피하고 벤더 기본 격리 수준 대신 READ_COMMITTED를 고정합니다. 애플리케이션의 @Transactional 사용은 컴파일 의존 부재와 APPLICATION_DOES_NOT_USE_SPRING_TRANSACTIONAL_ANNOTATION 규칙 양쪽에서 막힙니다. USE_CASE_CAPABILITY_MATCHES_TRANSACTION_PORT_BOUNDARY 규칙은 직접 호출에 한해 capability 선언과 inRead/inWrite/inNew의 대응을 검사하며 헬퍼 뒤에 숨은 호출까지 추론하지는 못합니다.

분산 락 쪽 배선은 실행 모드에 따라 달라집니다. 기본값 multi-instance-enabled=false에서는 인프로세스 LockRegistryDistributedLockAdapter가 데코레이터 없는 @Primary 구현입니다. 멀티인스턴스 모드를 켰을 때만 JDBC 기반 구현을 MeteredDistributedLockPort가 감싸 @Primary가 됩니다. 타임아웃 카운터와 리스 만료 처리는 멀티인스턴스 모드에서만 동작하며, 모든 실행 모드에 공통으로 적용되지는 않습니다. 이 락은 인터페이스 javadoc이 명시하듯 정합성 락이 아니라 효율성 락이며 데이터 정합성은 여전히 DB 제약이 지켜야 합니다.

// LockRegistryDistributedLockAdapter.java:31-55 (발췌)
if (leaseTtl.compareTo(configuredTtl) > 0) {
  throw new IllegalArgumentException(
      "leaseTtl (" + leaseTtl + ") exceeds the registry's configuredTtl ("
          + configuredTtl + ")....");
}
Lock l = registry.obtain(key);
boolean acquired;
try {
  acquired = l instanceof DistributedLock distributedLock
? distributedLock.tryLock(waitTime, leaseTtl)
      : l.tryLock(waitTime.toMillis(), TimeUnit.MILLISECONDS);
} catch (InterruptedException e) {
  Thread.currentThread().interrupt();
  throw new LockAcquisitionTimeoutException(key, waitTime);
}
if (!acquired) {
  throw new LockAcquisitionTimeoutException(key, waitTime);
}
return l::unlock;

권장 통합 순서. DistributedLock.close()의 javadoc과 README는 보호할 트랜잭션이 커밋된 뒤 락을 해제하라고 요구합니다. 코드 모양으로 옮기면 락 획득이 먼저, tx.inWrite(...)의 반환과 커밋이 그다음, close()가 마지막입니다.

// Javadoc/README가 요구하는 통합 패턴. 현재 프로덕션 애플리케이션/유스케이스 호출자는 없다.
try (DistributedLock lock = locks.tryAcquire(key, waitTime, leaseTtl)) {
  return tx.inWrite(action); // 반환 시점에는 commit 또는 rollback이 끝난다.
} // 그 뒤 close()가 락을 해제한다.

이 순서는 권장 패턴이며 현재 프로덕션 배선이 아닙니다. 계약 테스트도 try/finally 해제를 보여줄 뿐 실제 DB 커밋과 락 해제를 하나의 통합 테스트로 연결하지 않습니다. tx.inWrite 안에서 락을 획득한다고 서술하면 위 권장 순서와 반대가 되므로 그렇게 해석하면 안 됩니다.

두 포트를 한 실행 사슬로 읽으면 프로덕션 호출자 0건과 다중 인스턴스에서만 생기는 계측 배선을 숨기게 됩니다. 향후 결합하더라도 커밋 뒤 해제 순서와 DB 제약의 최종 정합성 책임은 남습니다.

테스트 경계도 나뉩니다. SpringTransactionPortTest의 5개 테스트는 세 모드의 propagation·isolation·readOnly와 런타임 예외 rollback을 단언합니다. DistributedLockPortContractTest의 5개 테스트는 작업 뒤 해제와 close() 후 재획득을 검사합니다. 두 스위트는 포트 각각의 부분 계약을 뒷받침하지만 프로덕션 호출자, 트랜잭션과 락의 통합 순서, HTTP 409 매핑까지 증명하지 않습니다.

멱등성·동시성 — IdempotencyExecutor의 네 분기, 하나의 200ms 창

IdempotencyExecutor는 구현했지만 HTTP 엔드포인트에는 아직 연결하지 않았습니다. WorkLogController는 Idempotency-Key 헤더를 받지만 바인딩만 하고 실행기를 부르지는 않습니다. 따라서 이 절에서는 현재 배선 상태와 실행기 내부 동작을 나누어 설명합니다. 실행기는 같은 요청의 재시도, 같은 키를 다른 본문에 재사용한 경우, 거의 동시에 도착한 두 요청을 구분합니다. 동시 삽입에는 분산 락 대신 uq_idempotency_scope 유니크 제약을 사용하고 늦게 온 요청은 제한된 시간만 기다립니다.

책임은 세 경계로 나뉩니다.

경계	소유하는 결정	소유하지 않는 것
`IdempotencyKeySupport`	헤더·principal로 scope 구성, 요청 직렬화, fingerprint와 JSON 코덱	경쟁·대기 정책
`IdempotencyExecutor`	`find`·`tryBegin`·replay·대기·완료 순서, 200ms 대기와 20ms 폴링, TTL 상한	HTTP·JSON·DB 제약 구현
`IdempotencyStorePort`/JPA 어댑터	`tryBegin`·`find`·`complete`·`discard`의 원자 연산	재시도 횟수와 대기 시간

scope는 (tenant, principal, idempotencyKey, useCaseName)이며 단일 테넌트 요청을 표현하기 위해 tenant만 null을 허용합니다. PostgreSQL UNIQUE 제약은 nullable column의 중복을 허용할 수 있기 때문에 영속 매퍼는 null을 빈 문자열로 바꿔 동일 scope가 여러 번 저장되지 않게 합니다. 이 방식은 빈 문자열을 영속성 센티널로 예약한다는 비용이 있습니다. fingerprint는 SHA-256 64자리 소문자 16진수지만 전송된 원시 바이트의 해시는 아닙니다. 웹 경계가 역직렬화된 객체를 다시 직렬화한 바이트를 해시합니다. TTL은 기본값과 재정의 값 모두 72시간을 넘을 수 없습니다.

실행 결과는 네 가지로 나뉩니다.

종료점	조건	동작 실행
신규(new)	살아 있는 레코드가 없고`tryBegin`이 실행권 선점에 성공	1회
저장 응답 재사용(replay-hit)	같은`fingerprint`의 `COMPLETED` 레코드 발견	0회, 저장 응답 역직렬화
실행 중(in-flight)	같은`fingerprint`가 진행 중이며 200ms 안에 완료되지 않음	0회, 409
지문 불일치(fingerprint-mismatch)	같은`scope`에 다른 `fingerprint` 존재	0회, 즉시 422

실행권 경쟁에서 진 경우와 기존 IN_FLIGHT를 읽은 경우는 같은 마감시각과 20ms 폴링을 씁니다. 기다리는 동안 승자가 완료하면 저장 응답 재사용으로 바뀌고 마감시각을 넘기면 409가 됩니다.

두 대기 진입점은 같은 200ms 마감시각으로 합쳐지고 본문 불일치는 즉시 종료됩니다. 실행권을 선점한 뒤 실패하면 discard 성공 여부에 따라 원래 예외를 다시 던질지, IN_FLIGHT를 지울지가 달라집니다.

실행권 선점 이후의 실패 경계가 정확히 한 번(exactly-once) 실행 여부를 결정합니다. runAndComplete()가 동작을 실행한 뒤 응답을 직렬화해 완료 상태로 저장합니다. 동작·코덱·complete가 런타임 예외를 던지면 catch 블록은 store.discard(scope)를 호출한 다음 원래 예외를 다시 던지려 합니다. discard가 성공할 때만 실행권이 지워지고 원래 예외가 그대로 전파됩니다.

discard에 예외 없음 계약이 없으므로 그 실패 창에서는 원래 예외가 discard 예외로 가려지고 IN_FLIGHT가 TTL까지 남을 수 있습니다. 반대로 동작의 외부 부작용은 성공했는데 코덱이나 complete가 실패하고 discard는 성공하면 재시도가 동작을 다시 실행할 수 있습니다. 어느 쪽이든 이 구현은 정확히 한 번 실행을 보장하지 않습니다.

동시에 들어온 요청 중 하나에만 실행권을 주는 핵심은 다음 짧은 어댑터 코드에 있습니다. saveAndFlush가 제약 검사를 즉시 일으키고 동일 scope 유니크 충돌이면 false를 돌려 실행기의 대기 경로로 보냅니다.

// IdempotencyStoreAdapter.java:74-77 (발췌) — DB 유니크 제약이 실제 경쟁 심판
try {
  repository.saveAndFlush(claim); // flush forces the unique-constraint check now
  return true;
} catch (DataIntegrityViolationException raceLost) {
  // Another caller inserted between the lookup and the flush — they own it.
  return false;
}

다만 catch는 constraint 이름이나 SQLState를 확인하지 않고 모든 DataIntegrityViolationException을 경쟁 패배로 분류합니다. 다른 무결성 위반도 false로 오인돼 대기 뒤 409로 끝날 수 있습니다. 안전하게 운영하려면 목표 유니크 제약 위반만 경쟁 패배로 분류하고 나머지는 원래 오류로 전파해야 합니다. 제약명이나 SQLState를 직접 확인하면 벤더 결합이 늘 수 있으므로, 그 판별은 영속성 어댑터 안에 가두는 것이 경계와 오류 정확성 사이의 현실적인 절충입니다.

계약과 구현의 불일치도 하나 있습니다. IdempotencyScope javadoc은 principal을 "pseudonymized"라고 설명하지만 IdempotencyKeySupport.currentPrincipal()은 AuthenticatedPrincipal.idpUserId()를 그대로 반환하고 가명화 포트를 호출하지 않습니다. 이 helper를 실제 엔드포인트에 배선하면 raw IdP 사용자 ID가 영속 키로 흘러갈 수 있습니다. 로깅 절의 가명화 보장은 MDC·응답 메타 경로에 한정되며 이 저장 경계까지 덮지 않습니다. 이 helper를 실제 엔드포인트에 배선한다면 principal에 가명화 포트를 먼저 적용해야 raw 사용자 ID가 영속 키로 저장되는 위험을 막을 수 있습니다.

HTTP 예외 매핑은 준비됐지만 실제 호출은 비어 있습니다. 409/422/400 전용 핸들러가 모두 존재하지만 어떤 실제 엔드포인트도 이 메커니즘을 호출하지 않습니다. WorkLogController의 두 POST는 Idempotency-Key 헤더를 바인딩만 하고 사용하지 않습니다. 이 메커니즘을 실제 쓰기 경로에 적용하려면 쓰기 유스케이스 호출을 실행기의 동작으로 감싸는 배선이 추가로 필요합니다.

IdempotencyExecutorTest의 9개 테스트 중 7개가 네 분기와 실패·만료 하위 경로를 덮습니다. 나머지 둘은 72시간 TTL 상한을 생성 시점과 호출 시점에서 검사합니다. 대기 테스트는 실제로 200ms를 재우지 않고 테스트 Sleeper가 가변 Clock을 앞당깁니다. 이 스위트는 실행기의 결정성을 증명하지만 엔드포인트 배선이나 동작의 외부 부작용까지 정확히 한 번 실행으로 만들지는 않습니다.

Outbox·메시징 — 두 실패 경로와 SKIP LOCKED 기반 선점

멱등성 실행기는 엔드포인트에 연결하지 않았지만 outbox는 샘플 쓰기 경로에 실제로 연결했습니다. CreateWorkLogUseCase에서는 DB 저장과 브로커 발행을 하나의 트랜잭션으로 묶지 않았습니다. 브로커 호출은 비즈니스 트랜잭션 밖에서 일어납니다. 아웃박스(outbox)는 먼저 발행할 이벤트 행을 도메인 변경과 같은 DB 트랜잭션에 저장합니다. 현재 샘플에서는 도메인 저장과 OutboxAppendPort.append(...)가 하나의 tx.inWrite 콜백 안에 있습니다. OutboxAppendPort는 자체 트랜잭션을 열지 않으므로 WorkLog 변경과 PENDING 행은 함께 커밋되거나 함께 롤백됩니다.

커밋 이후의 전달은 별도 계약입니다. OutboxRelayScheduler의 폴링 간격은 설정이 없으면 기본 5초입니다. 스케줄러가 호출하는 PublishPendingOutboxEventsUseCase는 짧은 쓰기 트랜잭션에서 배치를 선점하고 트랜잭션 밖에서 발행한 뒤 각 행의 결과를 다시 짧은 쓰기 트랜잭션으로 기록합니다.

시점	트랜잭션 경계	일어나는 일
T0	비즈니스`tx.inWrite`	도메인 저장 + append,`PENDING` 커밋
T1	짧은 릴레이 쓰기 트랜잭션	선점 가능한 행을 가져와`IN_FLIGHT`로 전환
T2	브로커 호출은 트랜잭션 밖, 상태 기록은 별도 쓰기 트랜잭션	발행 후`PUBLISHED`, 실패 시 `FAILED` 또는 `DEAD`

기본 fixedDelay=PT5S(설정이 없을 때의 5초)는 폴링 주기를 뜻할 뿐 다음 선점의 최소 시간 경계를 보장하지 않습니다. append는 쓰기 트랜잭션 안이고 publish는 커밋 뒤 트랜잭션 밖입니다.

OutboxBackoffPolicy는 30초 기반 지수 백오프와 최대 3회를 계산합니다. 지터를 0으로 둔 백오프 테스트의 1·2·3회차는 30/60/120초입니다. 상태 전이에서 PUBLISHED와 DEAD는 종착 상태입니다. 보존기간이 지난 PUBLISHED 행은 별도 정리 경로에서 삭제될 수 있고 DEAD에는 자동 후속 전이가 없습니다. PENDING과 FAILED는 next_attempt_at 조건으로, 고아 IN_FLIGHT는 가시성 제한 시간 조건으로 다시 선점됩니다. 재시도는 같은 호출 스택에서 반복하지 않고 상태와 다음 시각을 저장한 뒤 다음 폴에 맡깁니다.

FAILED의 재선점과 IN_FLIGHT 가시성 회수는 서로 다른 순환 경로입니다. DEAD에는 자동 후속 전이가 없으며 수동 개입 전까지 그대로 남습니다.

발행 뒤에는 두 실패 경로가 갈립니다.

실패 지점	상태	현재 폴링 회차의 제어 흐름	결과 위험
`publishPort.publish`	`markFailed` 또는 `markDead`를 별도 트랜잭션으로 기록	기록이 성공한 경우에만 다음 이벤트로 계속	최대 시도 뒤 성공 전달 0건 가능
`store.markPublished`	`IN_FLIGHT`로 남음	저장 예외가 전파되어 현재 배치를 중단할 수 있음	가시성 제한 시간 뒤 재선점되어 중복 발행 가능

발행 실패 자체는 handlePublishFailure가 잡아 시도 횟수에 따라 OUTBOX_DEAD_LETTER 또는 OUTBOX_PUBLISH_FAILED를 ERROR로 기록하며 상태 전이를 수행합니다. markFailed·markDead 저장이 실패하면 그 예외가 전파되므로 "브로커 실패를 삼키고 항상 다음 행으로 간다"고 설명하면 틀립니다. 발행은 성공했지만 markPublished가 실패한 경우에는 catch가 적용되지 않습니다. 행은 IN_FLIGHT로 남고 이미 브로커가 받은 이벤트를 다시 보낼 수 있는 창이 여기서 생깁니다.

클레임의 경쟁·순서 정책은 다음 SQL 한 문장에 있습니다.

-- PostgreSqlOutboxClaimRepository.java:16-29 — CLAIM_SQL (FIFO 게이트 + FOR UPDATE SKIP LOCKED)
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

NOT EXISTS는 같은 애그리게이트에서 엄격히 더 이른 occurred_at의 미발행 행을 게이트로 삼습니다. 더 이른 선두 행이 DEAD면 수동 개입 전까지 후속 행이 막힙니다. 같은 타임스탬프의 두 행에는 동률 정렬 키(tie-breaker)가 없어 결정적 FIFO를 보장하지 않습니다. FOR UPDATE SKIP LOCKED는 여러 릴레이가 같은 행을 동시에 클레임하지 못하게 하므로 별도 리더 락을 쓰지 않습니다. 이 동시 선점 방지 동작은 다중 인스턴스 테스트로 검증됩니다(두 Spring 컨텍스트가 1000건을 발행할 때 중복 선점 0건). 이는 선점 중복 방지의 증거이지 markPublished 실패 이후의 재발행까지 없다는 증거는 아닙니다.

테스트는 상태, DB 게이트, 다중 인스턴스 경쟁을 서로 다른 층에서 맡습니다.

테스트 파일	층위	개수	무엇을 검사하나
`PublishPendingOutboxEventsUseCaseTest`	단위	9	두 실패 경로와 PUBLISHED/FAILED/DEAD 결과
`OutboxBackoffPolicyTest`	단위	9	최대 3회, 30/60/120초와 지터 범위
`OutboxRowLifecycleContractTest`	실 PostgreSQL	9	선두 레코드 게이트, PUBLISHED 해제, 고아 회수
`OutboxPublisherLeaderElectionContractTest`	두 Spring 컨텍스트	1	SKIP LOCKED의 중복 선점 방지
`EventPayloadPiiContractTest`	ArchUnit	red/green	이벤트 필드명의 민감어 패턴만 검사

보장 범위는 여기까지입니다. 도메인 변경과 append는 한 트랜잭션이고 동시 릴레이의 선점 중복은 DB가 막습니다. 하지만 제한된 재시도가 모두 실패하면 브로커 전달은 0건일 수 있고 상태 기록이 실패하면 중복 발행할 수 있습니다. 소비자 중복 제거에는 같은 idempotencyKey를 건너뛰는 인메모리 fake 계약이 있지만 그 테스트는 영속 저장소·TTL·분산 일관성을 명시적으로 범위 밖에 둡니다. DEAD 행에는 수동 처분 runbook이 있어 원인 해소 뒤 PENDING으로 되돌리거나 승인 후 PUBLISHED로 표시합니다. 운영자가 수행하는 절차이지 자동화된 복구 전이가 아닙니다. 프로덕션 소비자의 영속 중복 제거와 수동 처분의 운영 준비도를 별도로 확인하기 전에는 자동 전달 완료나 결정적 전체 순서를 약속할 수 없습니다.

여섯 계약은 구현과 테스트의 존재만으로 완성됐다고 보지 않았습니다. 실제 요청 경로에 연결하지 않은 계약도 있기 때문입니다. 현재 배선 상태를 함께 놓으면 다음과 같습니다.

횡단 계약	구현·테스트	현재 배선 상태
검증	샘플 3계층 검증 있음	Feed 웹 경계 검증 공백, 어댑터 폴백만 존재
예외·오류 응답	두 단계 핸들러 체인·안전 메시지 있음	도메인 핸들러 체인은 샘플 실행점에만, 락 타임아웃 전용 웹 핸들러 없음
로깅·추적	필터·가명화·전파 데코레이터 있음	요청 경로 배선됨, executor 우회 시 UNKNOWN 폴백
트랜잭션	3모드 포트·구현·테스트 있음	Feed 읽기 경로 배선됨
분산 락	계약·어댑터·테스트 있음	프로덕션 애플리케이션/유스케이스 호출자 0
멱등성	실행기·저장 어댑터·핸들러 있음	엔드포인트 배선 0, 헤더 바인딩만 존재
Outbox	append·릴레이·상태기계·테스트 있음	샘플 쓰기 경로 배선됨, 소비자 영속 중복 제거는 범위 밖

어떻게 검증할 것인가

ca-tmpl의 경계는 설명만으로 끝내지 않고 테스트와 빌드로 검증하도록 만들었습니다. 테스트가 어디까지 실제 코드를 실행하는지, ArchUnit 규칙이 빈 검사로 통과하지 않는지(test-the-test), 위반 코드를 넣으면 예상한 게이트에서 멈추는지(break-it)를 각각 나눴습니다. 빌드 밖의 아티팩트와 런타임 계약도 저장소 정책으로 관리합니다.

테스트 경계 네 층 — 무엇을 실행하고 무엇을 대체하는가

테스트 이름만으로 범위를 정하지 않았습니다. unit, contract, integration이라는 이름보다 실제로 실행하는 코드와 바꿔 끼운 협력자를 기준으로 삼았습니다. 현재 테스트 트리는 실행 비용과 대체 범위에 따라 다음 네 층으로 나뉩니다.

층	무엇을 검증	진짜(real)	가짜(substituted)	도구
도메인 단위	aggregate 규칙·상태기계	도메인 POJO 전부	없음	JUnit + AssertJ
유스케이스	유스케이스 로직	유스케이스 + 도메인	아웃바운드 포트 = 손으로 만든 페이크	JUnit (Mockito 0)
어댑터	컨트롤러·매핑·DB 왕복	어댑터 본체	외부 협력자 또는 진짜 인프라	@WebMvcTest / Testcontainers
통합	outbox relay·분산 락 provider 계약	Postgres·Flyway·어댑터 배선	publisher stub·고정 Clock	Testcontainers + 최소 Spring context

안쪽 경계의 효과는 수치로도 확인됩니다. sample-portfolio의 도메인·애플리케이션 테스트 소스셋에는 단위 테스트 클래스 15개(테스트 메서드 71개)가 있고 그중 어느 하나도 org.springframework·Mockito· Testcontainers를 import하지 않습니다.

유스케이스 층에서 레이어드 구조와의 차이가 가장 분명하게 드러납니다. 유스케이스가 도메인 소유 WorkLogRepository 인터페이스에 의존하므로 테스트는 이를 ArrayList 기반 인메모리 페이크로 바꾸고 유스케이스를 그냥 new 해서 돌립니다.

// 스프링 컨텍스트도 Mockito도 없다. 진짜로 동작하는 페이크를 손으로 만든다.
static class FakeRepo implements WorkLogRepository {
    final List<WorkLog> store = new ArrayList<>();
    public WorkLog save(WorkLog w) { store.removeIf(x -> x.id().equals(w.id())); store.add(w); return w; }
    public Optional<WorkLog> findById(WorkLogId id) {... }   // 진짜 조회·페이징
}
static final TransactionPort TX = new TransactionPort() {
    public <T> T inWrite(Supplier<T> a) { return a.get(); }    // 그냥 실행
    public <T> T inRead (Supplier<T> a) { return a.get(); }
    public <T> T inNew  (Supplier<T> a) { return a.get(); }
};

WorkLog created = new CreateWorkLogUseCase(repo, IDS, STUB_EVENT_IDS, NO_OP_OUTBOX, UTC_CLOCK, TX).handle(cmd);

포트가 도메인이 소유한 인터페이스라 이게 가능합니다. 페이크는 목(mock)이 아니라 store에 진짜로 넣고 빼는 작은 구현이고 이 층 전체에서 Mockito는 한 번도 안 씁니다. 레이어드의 전형적인 단일 모듈 Spring 구현이었다면 서비스가 Spring Data 타입과 트랜잭션 프록시에 결합되기 쉬워 테스트하려면 컨텍스트를 띄우거나 프레임워크 타입을 목킹해야 합니다. 차이가 드러나는 지점은 협력자의 타입입니다. 이 대조는 결합도 차이를 설명하기 위한 것이며 저장소의 대칭 측정 결과가 아닙니다.

오른쪽은 코어 소유 포트를 익명 테스트 더블로 대체하는 실제 패턴이고 왼쪽은 결합도 차이를 설명하기 위한 대조입니다. 두 패널을 저장소의 대칭 측정 결과로 읽지 않습니다.

도메인 층에는 주목할 테스트가 하나 더 있습니다. WorkLogTest가 상태기계(OPEN→IN_PROGRESS→CLOSED)를 확인하는 데 더해 WorkLogInvariantTest는 도메인 예외가 운영용 ApiErrorCode 계약을 구현하지 않는다는 것까지 단언합니다. 운영 코드 분리가 테스트로 고정돼 있습니다. 어댑터·통합 층의 대표 테스트는 PosterControllerWireTest(@WebMvcTest 슬라이스, 유스케이스만 목킹)와 FeedPersistenceIT(@DataJpaTest + Testcontainers postgres:16-alpine, Docker 없으면 스킵)입니다. 아웃박스 통합 테스트는 전체 앱을 부팅하지 않고 Flyway를 적용한 최소 AnnotationConfigApplicationContext를 씁니다. 이 예시가 전체 테스트 트리를 빠짐없이 열거하는 것은 아닙니다.

taxonomy 자체도 일부는 규칙으로 강제됩니다. TestTaxonomyArchitectureTest는 contract·architecture 패키지의 Testcontainers 의존을 금지하고 한 클래스의 @WebMvcTest·@DataJpaTest 혼용을 거부합니다. 프로덕션 코드의 ..fixtures.. 의존은 별도 규칙으로 확인합니다. 실 서비스가 필요한 테스트를 integration 패키지로 보내는 규율은 이 제한된 게이트와 디렉터리 관례가 함께 만듭니다.

테스트 파일이 현재 어디에 놓였는지와 아키텍처 규칙이 실제로 강제하는 범위는 구분해야 합니다.

규칙을 테스트하는 테스트 — test-the-test

ArchUnit 테스트가 모두 초록색이어도 규칙이 살아 있다는 뜻은 아닙니다. glob 하나를 잘못 쓰면 검사 대상이 0개가 되고 아무것도 검사하지 않은 채 통과할 수 있기 때문입니다(vacuous pass). 그래서 저는 architecture/violations/에 규칙을 일부러 어기는 픽스처를 넣었습니다. 이곳에는 package-info.java를 제외한 Java 소스 48개가 있고, 규칙을 일부러 어기는 타입과 평가를 돕는 지원 타입이 함께 들어 있습니다. ca-tmpl은 이 코퍼스를 검사했을 때 실제 위반이 나오는지를 별도 테스트로 확인합니다.

세는 기준. 해당 트리는 .java 54개이며 그중 package-info.java 6개를 빼면 48개입니다. FixtureRepository 같은 지원 타입도 포함되므로 48을 규칙 수나 독립 위반 수로 해석하지 않습니다.

// ca-tmpl · 위반 픽스처: 읽기 전용(READ_REPOSITORY)으로 선언해 놓고 repository.save()를 부른다
@UseCaseCapability(
    transactionMode = TransactionMode.READ_ONLY,
    idempotency = Idempotency.IDEMPOTENT,
    repositoryAccess = RepositoryAccess.READ_REPOSITORY)
public final class ReadOnlyRepositoryWriteUseCase
    implements CommandUseCase<ReadOnlyRepositoryWriteUseCase.DummyCommand, Void> {
  public Void handle(DummyCommand input) {
    repository.save(new Object());                 // 위반: 읽기 전용이 쓰기 메서드를 호출
    return null;
  }
}

// ca-tmpl · ArchitectureViolationFixtureTest — "이 픽스처를 규칙에 통과시키면 정말 위반으로 걸리는가"
private static final JavaClasses READ_ONLY_REPOSITORY_WRITE_FIXTURE_ONLY =
    new ClassFileImporter().importClasses(
        ReadOnlyRepositoryWriteUseCase.class, FixtureRepository.class);

@Test
void readOnlyUseCasesDoNotCallRepositoryWriteMethodsCatchesReadToWriteUpgrade() {
    EvaluationResult result =
        CleanArchitectureTest.READ_ONLY_USE_CASES_DO_NOT_CALL_REPOSITORY_WRITE_METHODS
.evaluate(READ_ONLY_REPOSITORY_WRITE_FIXTURE_ONLY);
    assertThat(result.hasViolation()).isTrue();    // 규칙이 살아 있다는 증거
}

위반 픽스처들은 프로덕션 스캔에서 격리됩니다. ProductionClassImportOption이 규칙이 도는 대상에서 위반 코드를 빼기 때문에, 픽스처가 진짜 빌드를 깨뜨리지 않으면서 "규칙이 살아 있다"만 증명합니다. 이 클래스는 스톡 ImportOption.DoNotIncludeTests를 감싸 /sampleOffTest/까지 함께 제외합니다. 위반 코드를 프로덕션 소스에 두면 전체 빌드가 항상 실패하므로 별도 테스트 소스셋이 필요합니다. 그 대신 사용자 정의 import option을 유지하고 새 테스트 소스셋이 생길 때 제외 범위를 함께 갱신해야 합니다.

이 픽스처 테스트가 다루는 규칙은 실제 위반을 잡는다는 점까지 확인됐습니다. 그러나 63개 @ArchTest 전부에 각각 대응하는 비공허성 테스트가 있다는 뜻은 아닙니다. 커버되지 않은 규칙은 여전히 import 범위와 대상 수를 별도로 확인해야 합니다.

깨뜨리면 어디서 멈추나 — break-it

위반을 어디에 넣느냐에 따라 먼저 실패하는 검사도 달라집니다. 저는 같은 종류의 위반을 프로덕션 코어, 어댑터 빌드 파일, 테스트 픽스처에 각각 둘 수 있도록 break-it 사례를 나눴습니다. 위치별로 멈추는 곳은 다음과 같습니다.

① web이 아웃바운드(persistence)를 직접 의존 — 게이트 ②가 잡습니다.

위반    implementation project(':adapter:outbound:persistence-jpa')   ← adapter/inbound/web/build.gradle
  ↓
게이트   ② Gradle 모듈 화이트리스트 — web은 아웃바운드·형제를 의존할 수 없다
        (그 의존으로 web 코드가 outbound 타입까지 참조하면 ③ ArchUnit 규칙도 별도로 위반으로 판정)
  ↓
판정    verifyCleanArchitectureDependencies가 화이트리스트 밖 의존을 발견 → GradleException으로 check 실패

② 도메인에 @Component(Spring 의존) — 게이트 ①이 먼저 잡습니다.

위반    @Component class FeedItem { … }                ← domain-core (순수 POJO여야 함)
  ↓
게이트   ① 컴파일 격리 — org.springframework 타입이 domain-core 클래스패스에 아예 없다
         (Spring이 닿는 자리에 넣었다면 ③ ArchUnit DOMAIN_IS_PURE)
  ↓
판정    코어 소스면 javac 실패(타입 부재), 픽스처 위치면 ArchUnit 테스트 실패

③ 애플리케이션에 @Transactional — 게이트 ①이 먼저 잡습니다.

위반    @Transactional public Foo handle(...) { … }    ← application-core
  ↓
게이트   ① 컴파일 격리 — spring-tx가 application-core main compileClasspath에 없다
         (testCompileOnly로 spring-tx가 복원된 자리면 ③ ArchUnit 규칙)
  ↓
판정    코어 소스면 javac 실패(spring-tx 부재), 복원된 자리면 ArchUnit 테스트 실패

④ Class.forName(문자열) 리플렉션 우회 — 아무 게이트도 못 잡습니다.

위반    Class.forName("org.springframework.context.ApplicationContext")
  ↓
게이트   없음 — 문자열 키는 바이트코드에 타입 의존을 남기지 않는다
  ↓
판정    이를 검출하는 정적 규칙 없음 → 정적 게이트에서 차단되지 않음

정적 분석이 잡는 것은 실제 경계 위반 전체의 부분집합입니다. 작은 원 밖의 리플렉션·문자열 조회는 코드 리뷰와 런타임 검증이 맡아야 할 사각지대입니다.

②·③에서 보이듯, 어느 겹이 잡는지는 위반의 주입 위치가 정합니다. 도메인·애플리케이션 모듈엔 금지 타입 자체가 클래스패스에 없어서 프로덕션 소스에 넣으면 컴파일 격리(게이트 ①)가 ArchUnit(게이트 ③) 보다 먼저 실패합니다. javac에서 막히므로 ArchUnit은 실행조차 안 됩니다.

직접 확인하는 방법. 깨끗한 작업 트리나 일회용 브랜치에서 각 위반을 해당 위치에 한 줄씩 넣고 cd src && ./gradlew check를 실행합니다. 예상한 게이트에서 실패하는지 확인한 뒤 변경을 되돌립니다. 실행 환경은 Gradle 9.0.0, Java 21, Spring Boot 4.0.0입니다.

빌드 너머의 강제 — CI·공급망·컨테이너

세 겹 게이트의 범위는 빌드 안의 소스 경계까지입니다. 코드가 이미지가 된 뒤에는 다른 검사가 필요합니다. 그래서 .github/workflows/, 공급망 정책 파일, docker-compose.yml에 아티팩트의 출처와 컨테이너 런타임 조건을 별도 저장소 계약으로 넣었습니다.

CI와 공급망 계약. .github/workflows/에는 ci-quality-gates, dependency-vulnerability, build-release-supply-chain, supply-chain-retention-audit, link-check 다섯 워크플로가 있고 CI는 ./gradlew check를 실행합니다. 릴리스 경로는 다음 검사를 조합합니다.

재현 가능 빌드: verify-reproducible-build.sh로 같은 입력의 산출물이 재현되는지 검사합니다.
SBOM과 키리스 서명: SPDX SBOM(소프트웨어 구성 명세서)을 만들고 Cosign으로 이미지 서명과 SBOM attestation(산출물에 대한 서명된 증명)을 남깁니다.
SLSA 프로버넌스(빌드 출처 증명): generator_container_slsa3@v2.1.0을 호출해 출처를 만들고 별도 verify job에서 서명자와 소스·태그·빌더 정보를 재검사합니다.

supply-chain-policy.json은 이미지 식별을 immutable digest로, 서명을 Cosign keyless(장기 서명 키 없이 워크플로 신원으로 서명)로, 프로버넌스를 SLSA v1로 고정하고 롤백 보존 기준 minimumReleaseCount: 10·minimumAgeDays: 90을 명시합니다. 이 값은 기계 판독 가능한 정책 파일에 들어 있습니다. 다만 CI가 이 두 키를 읽어 실제 보존 상태를 판정하는 호출 경로는 없습니다. 의존성 갱신은 renovate.json이 보안 업데이트만 열고 patch·pin·digest에만 automerge: true를 설정하며 실제 병합은 저장소의 상태 검사와 브랜치 보호 설정에도 좌우됩니다. .trivyignore.yaml의 억제 항목은 사유와 만료일을 가져야 하며 verifyTrivyignore가 빌드에서 검사합니다.

컨테이너 런타임 계약. 기본 docker-compose.yml에는 다음 운영 조건이 명시돼 있습니다.

read_only: true 루트 파일시스템과 /tmp·/var/tmp/heap tmpfs
mem_limit: 512m과 -XX:MaxRAMPercentage=75가 계산할 메모리 상한
stop_grace_period: 40s — 앱 드레인 30초, preStop 5초, 안전 여유 5초의 합
관리 포트 9001의 actuator readiness probe 헬스체크

이 장치가 코드의 정확성을 증명하는 것은 아닙니다. 서명·프로버넌스의 신뢰는 CI 실행 환경과 OIDC 발급자(워크플로 신원 토큰 발급자)까지 이어지며 그 신뢰 뿌리가 침해되면 정상 절차처럼 보이는 잘못된 산출물이 만들어질 수 있습니다. 키리스 서명은 키 관리 부담을 발급자와 워크플로 신원에 대한 의존으로 옮길 뿐 없애지 않습니다. 빌드 안에서는 소스 의존을, 릴리스 파이프라인에서는 산출물의 출처를, compose에서는 프로세스의 런타임 제약을 각각 별도 계약으로 관리합니다. 세 계약은 서로 보완하지만 어느 하나도 나머지 둘을 대신하지 않습니다.

대안, 트레이드오프, 실패 조건

ca-tmpl을 만들면서 같은 목표를 더 적은 비용으로 달성할 대안도 함께 비교했습니다. 장기 재사용 템플릿에서는 유용한 장치도 작은 서비스에서는 유지비만 늘릴 수 있기 때문입니다. 외부 사례는 참고하되 제가 택한 다섯 결정과 반대 선택이 더 나은 조건을 따로 설명합니다.

참고한 외부 사례 — 무엇을 어디까지 쓰는가

외부 사례는 ca-tmpl의 선택 이유를 대신하는 근거로 사용하지 않았습니다. 같은 기술을 썼다고 해서 같은 제약과 이유로 선택한 것은 아니기 때문입니다. 외부 글은 선택 비용을 비교하는 대조군으로만 사용하고, ca-tmpl의 선택 이유는 제가 구현한 코드·Gradle 선언·테스트에서 설명할 수 있는 범위로 남겼습니다.

사례	비교할 특성	`ca-tmpl` 판단에 쓰는 범위
우아한형제들	레이어 단위 멀티모듈에서 output port가 늘어나는 비용	기능 우선 패키지를 택할 때의 반대 사례
카카오뱅크	멀티모듈·헥사고날·Spring Modulith의 결합	현재 미채택 상태를 확인하고 별도 평가 대상으로 분리
Netflix Tudum	Kafka 기반 CQRS에서 Raw Hollow 기반 CQRS로 구현 교체	CQRS 하부 구현도 운영 조건에 따라 바뀔 수 있다는 사례로만 참고
Sahibinden	package-by-feature의 응집·캡슐화·모듈성	기능 우선 패키지의 장점 비교
arawn	외형 복제보다 높은 응집과 느슨한 결합을 우선	패키지 선택의 판단 원칙으로 참고
Allegro	안쪽을 향하는 계층 의존과 추가 빌드·학습 비용	구조를 복제하지 않고 비용 대조에 사용
Buckpal·reflectoring	작은 헥사고날 웹 앱의 Input/Output Port 구성	포트 배치의 외부 대조로 참고
Arho Huttunen	도메인/JPA 모델 분리와 매핑 비용, 코어 밖 트랜잭션 선택지	모델 분리와 트랜잭션 경계의 비용 대조로 참고

Tudum 사례는 CQRS를 버린 사례가 아닙니다. Kafka에서 Raw Hollow로 구현 메커니즘을 바꿨으므로 ca-tmpl의 CQRS-lite 선택을 직접 입증하는 자료로 쓰지 않습니다. 그래서 저는 외부 사례를 선택의 근거로 대신 쓰지 않았습니다. ca-tmpl의 선택 이유는 제가 구현한 코드, Gradle 선언, 테스트 규칙으로 설명했습니다.

다섯 설계 결정과 그 반대편

제가 ca-tmpl에서 택한 선택과 더 단순한 대안을 나란히 놓으면 다음과 같습니다. ca-tmpl은 hybrid 패키지, 포트 기반 트랜잭션, 멀티모듈과 ArchUnit, CQRS-lite, 순수 POJO 도메인을 택했습니다. 장기 재사용 템플릿에서는 경계를 반복 검사할 수 있지만, 1회성 서비스에서는 같은 장치가 유지비만 늘릴 수 있었습니다. 그래서 아래 표에는 선택의 장점만 적지 않고 반대편이 더 나은 조건도 함께 남겼습니다.

결정	선택	선택으로 얻는 것	반대편이 나은 조건
① 패키지 배치	계층 소유 코어·어댑터와 수직 샘플을 함께 쓰는 hybrid	프로덕션 경계는 계층별로 통제하고, 샘플은 한 기능의 종단 구성을 보여 줍니다.	한 가지 축만으로 충분한 작은 서비스
② 트랜잭션 경계	`@Transactional` 대신 코어 소유 포트	Spring TX를 애플리케이션 클래스패스에서 빼고 트랜잭션 의도를 테스트 가능한 계약으로 만듭니다.	단일 DB를 쓰며 간접 호출 비용이 더 큰 작은 팀
③ 모듈화	멀티모듈 + ArchUnit	금지된 타입은 컴파일에서, 허용 범위 안의 패키지 위반은 테스트에서 잡습니다.	수명이 짧아 모듈·정책 유지비를 회수하기 어려운 서비스
④ CQRS	full이 아닌 lite	읽기·쓰기 코드와 모델은 분리하되 별도 저장소의 복제·복구 비용은 도입하지 않습니다.	읽기·쓰기 부하가 명확히 비대칭이고 동기화 비용을 감당할 수 있는 시스템
⑤ 도메인 순수성	Lombok·JPA 없는 순수 POJO	도메인 규칙을 ORM 생명주기와 프레임워크 타입에서 분리합니다.	매핑 비용이 격리 효과보다 큰 단순 CRUD 서비스

① 패키지 배치. ca-tmpl의 실제 패키지는 한쪽으로만 정렬되지 않습니다. 프로덕션 코어·어댑터 모듈은 계층이 소유하지만 sample-portfolio는 수직 참조 슬라이스이고 도메인은 feed처럼 기능 중심이며 애플리케이션은 기술 패키지와 기능 패키지를 함께 둡니다. 이 배치는 프로덕션의 허용 의존을 계층별로 통제하면서도 샘플에서는 기능 하나의 종단 구성을 한곳에 보여 줍니다. 기능이 2~3개로 고정된 작은 서비스라면 두 축을 병행하는 것 자체가 오버엔지니어링입니다. 그 조건에서는 한 가지 패키지 축이 더 짧습니다.

이 그림은 ca-tmpl의 hybrid 배치를 보여 주며 모든 프로젝트에 적용할 정답을 뜻하지 않습니다.

② 트랜잭션 경계. 서비스에 @Transactional을 직접 붙이면 애플리케이션 모듈에 spring-tx와 애노테이션 결합이 추가됩니다. 바깥 데코레이터는 그 결합을 유스케이스에서 치우는 대신 위임 메서드를 반복합니다. ca-tmpl은 세 번째 위치(유스케이스가 코어 소유 포트로 트랜잭션 의도를 선언하는 방식)를 택했습니다. 이 선택 덕분에 Spring 프록시 없이 유스케이스를 단위 테스트할 수 있고 허용할 정책을 계약으로 제한할 수 있습니다. 대신 콜백이 읽기 흐름을 끊고 timeout·isolation을 추가할 때는 포트 자체를 확장해야 합니다. 단일 DB를 쓰는 작은 팀이라면 직접 @Transactional이 이 간접 비용보다 나을 수 있습니다.

데코레이터는 반복되는 위임 코드와 배선 비용을, 포트는 콜백 가독성과 확장 비용을 냅니다. 어느 쪽도 application-core 전체를 framework-free로 만들지 않습니다.

③ 모듈화. 컴파일 클래스패스는 모듈마다 갈리므로 멀티모듈이어야 "금지된 타입이 이 모듈에는 없다"가 성립합니다. 단일 모듈이나 느슨한 멀티모듈은 패키지 규칙과 리뷰가 주 방어선으로 남습니다. Spring Modulith까지 더하면 논리적 package-module 경계를 테스트로 검사할 수 있습니다. 후자의 실제 대조군이 카카오뱅크 사례입니다. 현재 Gradle 스크립트에는 Spring Modulith 의존 선언이 없으므로 Modulith 기반 강제가 있다고 말할 수 없습니다. 오래 유지하지 않을 1회성 서비스라면 모듈·정책 유지 비용을 회수하기 어려워 약한 강제로도 충분합니다.

Spring Modulith를 도입할지는 현재 경계 게이트로 부족한 부분과 추가 유지비를 비교해 별도로 결정해야 합니다.

④ CQRS. CQRS 자체가 물리적 저장소 분리를 필수로 요구하지는 않습니다. 이 글에서 full 쪽 대안으로 비교하는 것은 읽기·쓰기 저장소까지 분리해 복제·동기화를 운영하는 구성입니다. WorkLogSummary의 javadoc은 현재 조회 우회 모델을 CQRS-lite라고 부르고 명령과 조회의 코드·모델을 논리적으로 나눕니다. 이 구성을 선택할 실용적 이유는 읽기 모델을 도메인 재구성에서 분리하면서도 별도 저장소의 복제·동기화·복구 비용은 도입하지 않는 데 있습니다. 읽기·쓰기 부하와 지연 요구가 실제로 갈리고 그 운영 비용을 감당할 수 있을 때 full CQRS를 별도로 평가할 수 있습니다.

⑤ 도메인 순수성. 도메인 애그리게이트에 @Entity를 붙이면 코어가 Hibernate를 알게 됩니다. ca-tmpl은 순수 POJO와 별도 JPA 타입을 두고 어댑터가 매핑하는 쪽을 택했고 DOMAIN_IS_PURE가 이 선택을 지킵니다. 이 구조가 유효한 이유는 업무 불변식을 ORM의 애노테이션·생명주기·지연 로딩에서 분리하기 때문입니다. 반면 같은 항목은 JPA 엔티티, Application 타입, Interface Adapter 타입 세 벌로 갈리고 매핑은 어댑터가 부담합니다. "도메인=엔티티" 결합을 받아들이고 세 모델을 유지할 여력이 없는 팀이라면 직접 매핑을 줄이는 편이 더 실용적일 수 있습니다.

도메인 예외 — 운영 코드와 Reason의 분리

도메인 예외에는 운영 오류 코드를 직접 넣지 않고 안전한 명사 enum Reason만 남겼습니다. 다만 이 구조만으로 운영 코드의 역류를 완전히 막지는 못합니다. 실제로 구현한 패턴도 sample-portfolio의 WorkLog·Poster 예외에 한정됩니다. 두 샘플 도메인은 Reason을 소유하고, 샘플 웹 계층의 DomainExceptionHandler가 이를 ApiErrorCode로 바꿉니다. 변환 코드는 늘지만 도메인 예외가 HTTP 상태와 운영 에러 코드를 직접 알지 않아도 됩니다.

// ca-tmpl · sample-portfolio/domain/worklog/WorkLogInvariantException.java
enum Reason { TITLE_BLANK, INVALID_STATUS_TRANSITION, CLOSED_WORKLOG_MUTATION }

이 방식은 도메인이 운영 코드를 모르게 하는 대신 사유와 API 오류 코드의 매핑 누락 가능성을 만듭니다. 실제 구현도 완전히 균일하지 않습니다. WorkLog 핸들러는 여러 사유를 WORKLOG_CONFLICT 하나로 접고 Poster 핸들러만 사유별 switch를 씁니다. 구조적 한계도 있습니다. Gradle 정책은 domain-core → shared-contract를 허용하고 DOMAIN_IS_PURE의 금지 목록에도 ..shared..는 없습니다. 이 규칙 하나로 운영 코드의 역류를 차단한다고 말할 수 없고 매핑의 완전성도 자동 보장되지 않습니다.

같은 의존 규칙, 다른 강제 수준

저는 검사를 많이 붙이는 것 자체를 목표로 삼지 않았습니다. 장치를 줄이면 초기 구성과 변경은 가벼워지지만 위반 발견이 리뷰나 런타임까지 늦어집니다. 반대로 클래스패스·빌드 정책·규칙 테스트를 늘리면 위반은 일찍 멈추지만 모듈 선언, 페이크, 매핑, 정책 파일을 계속 관리해야 했습니다. 의존을 코어 쪽으로 향하게 하는 원리는 같아도 어디까지 자동으로 막을지는 프로젝트마다 달라집니다.

ca-tmpl은 main 프로젝트 의존 그래프, implementation 의존, 세 겹 게이트, sampleOffTest, shared-contract, 레지스트리와 런북을 함께 유지하는 쪽을 택했습니다. 재사용 기간이 짧고 변경 주체가 적다면 같은 장치가 순비용이 될 수 있습니다. 따라서 "클린인가"라는 이름보다 위반을 얼마나 일찍 잡아야 하는지, 그 대신 모듈·매핑·정책 파일을 계속 관리할 수 있는지를 먼저 판단해야 합니다.

못 잡는 것 — 강제 범위의 한계

게이트를 설계하면서 정적 검사가 보지 못하는 영역도 함께 적었습니다. 빌드가 실패하지 않는다고 해서 경계와 운영이 모두 안전한 것은 아니기 때문입니다.

런타임 우회는 못 잡습니다. Class.forName(문자열)이나 getBean(문자열) 같은 문자열 키 조회는 바이트코드에 타입 의존이 남지 않아 정적 분석이 통과시킵니다. 이 영역은 코드 리뷰·런타임 검증으로 보완할 수밖에 없습니다.
잘못된 도메인 모델은 깨끗하게 분리해도 여전히 잘못된 모델입니다. 경계가 깔끔하다고 모델까지 옳아지지는 않습니다. 아키텍처는 나쁜 설계를 좋은 설계로 바꿔 주지 않습니다.
너무 많은 포트는 의미 없는 위임·매핑 코드를 만듭니다. 교체 가능성이 실제로 필요 없는 곳에 포트를 두면 남는 건 보일러플레이트뿐입니다.
모듈 경계를 잘못 그으면 되돌리는 비용이 큽니다. 19개 Gradle 모듈은 구조로 일찍 확정됩니다. 잘못 나눈 경계를 재분할·병합하려면 build.gradle 수정, 화이트리스트 갱신, ArchUnit 규칙 수정, 참조하는 쪽의 의존 선언까지 연쇄로 바뀝니다. 경계를 일찍 강제할수록 그 경계 자체를 바꿀 때 수정할 곳도 늘어납니다. 이는 정량 측정값이 아니라 변경 범위에 대한 설명입니다.
클린 아키텍처가 운영 준비성을 주진 않습니다. 경계가 깨끗해도 실패 분류·로깅·추적이 없으면 운영은 비어 있습니다. 그래서 ca-tmpl은 아키텍처 위에 별도의 운영 계약을 둡니다. 여기에는 shared-contract의 Envelope·ApiErrorCode, 레지스트리 YAML 7개, 런북 45개(실패 모드별 44개 + 템플릿 1개)가 포함됩니다. 이 문서·정책 자산은 그만큼의 유지비를 요구합니다.
공급망 계약도 신뢰 뿌리까지만 강합니다. 서명·프로버넌스는 누가 무엇을 어떤 절차로 빌드했는지를 검증하지만 CI 자격증명이 침해되면 attestation도 정상 절차처럼 위조될 수 있습니다. 출처와 무결성은 코드의 정확성과 다른 보장입니다.

실무 적용 체크리스트

사전 점검 — 어떤 상황에 어떤 구조가 맞는가

다른 프로젝트에서 ca-tmpl을 사용할 때는 19개 모듈부터 그대로 복제하도록 권하지 않습니다. 강한 게이트는 위반을 일찍 발견하지만 모듈·포트·테스트 정책을 계속 관리해야 합니다. 그래서 모듈 수보다 경계를 어겼을 때 생기는 비용과 프로젝트를 얼마나 오래 재사용할지를 먼저 비교해야 합니다.

상황	적합한 방향
짧은 시간 안에 개념을 실행해 보는 학습용 예제	단일 모듈 또는 작은 멀티모듈
여러 어댑터를 바꿔 끼우며 실험하는 랩	선택 구성을 명시한 실행형 참조 구현
수명이 짧고 변경 주체가 적은 서비스	필요한 경계만 남긴 모듈 축소형
여러 프로젝트가 복제할 조직 템플릿	`ca-tmpl`처럼 자동 게이트를 포함한 스켈레톤
경계 침식의 조기 차단이 핵심인 서비스	컴파일·Gradle·ArchUnit을 함께 쓰는 구성
공급망·운영 계약까지 저장소에서 관리해야 하는 환경	품질·릴리스 정책을 코드와 함께 버전 관리하는 구성

현재 ca-tmpl 구성은 뒤쪽 세 상황에 더 잘 맞습니다. 작은 팀이나 짧은 수명 서비스에서는 같은 장치가 순비용이 될 수 있고 반대로 여러 팀이 반복해서 복제하는 템플릿이라면 위반을 리뷰에만 맡기는 비용이 더 커질 수 있습니다.

점진적 적용 — WHY에서 HOW로

ca-tmpl의 README에는 이 판단을 실제 빌드 실패까지 확인할 수 있는 짧은 진입 경로를 두었습니다. 먼저 퀵스타트로 현재 구조를 띄우고, 그다음 샘플을 참고해 도메인 하나를 추가하는 두 걸음입니다.

띄워 봅니다. README 퀵스타트는 소스 컴파일 검사 → 로컬 PostgreSQL 기동 → 애플리케이션 이미지 빌드·기동과 Flyway 완료 확인 → sample 격리/build 검증 → /api/healthcheck 스모크의 다섯 단계를 다음 한 명령에 묶습니다.
```
cd src && ./gradlew bootstrap
```
이미지 빌드·기동 단계가 있으므로 컨테이너 런타임(Docker)이 준비돼 있어야 합니다. 저장소의 DB 왕복 테스트도 Docker가 없으면 스킵됩니다. 각 단계의 예상 출력과 기동한 컨테이너를 내리는 절차는 README를 기준으로 확인합니다.
도메인을 하나 더합니다. sample-portfolio를 참조 슬라이스 삼아 새 도메인을 안쪽에서 바깥으로 쌓아 봅니다. domain-core(순수 POJO) → application-core(유스케이스·포트) → adapter(web·persistence-jpa) 순서입니다. break-it 절의 사례처럼 금지된 의존을 추가하면 위치에 따라 javac, Gradle 의존 검사, ArchUnit 중 해당 게이트가 실패해야 합니다.

기존 프로젝트에는 강제 범위를 단계적으로 넓힙니다. 먼저 ArchUnit 패키지 규칙을 추가하고 위반 픽스처로 규칙이 실제 실패하는지 확인합니다. 경계가 안정되면 코어를 별도 모듈로 분리해 클래스패스 격리를 얻습니다. 모듈이 늘면 의존 화이트리스트를 추가하고 check에 연결합니다. 각 단계는 앞 단계의 규칙을 대체하지 않고 서로 다른 위반 유형을 맡습니다.

중단·롤백 기준 — 언제 멈추거나 되돌리는가

포트와 모듈을 계속 추가하는 쪽으로만 기준을 두면 실제 교체 요구가 사라져도 구조가 남습니다. 그래서 도입 순서와 함께 중단·롤백 기준도 정했습니다. 다음 신호가 보이면 강제 범위를 줄이거나 이미 나눈 경계를 합치는 쪽을 검토합니다.

실제로 교체할 기술도, 테스트에서 대체할 필요도 없다면 그 포트는 걷어냅니다. 이런 포트는 경계를 만들지 않고 위임 코드만 늘립니다.
모듈 추가의 다섯 질문에 모두 "아니오"라면 모듈로 나누지 않습니다. 이미 나눈 모듈이 이 기준에 걸리면 병합을 검토하되, 화이트리스트·ArchUnit·의존 선언의 연쇄 수정 비용을 함께 계산합니다.
팀이 세 벌 모델(도메인·영속·응답)의 매핑을 유지할 여력이 없다면 도메인 순수성 수준을 낮추는 것이 구조를 방치하는 것보다 낫습니다. 단, 그 완화가 어떤 검출 능력을 포기하는지 이 글의 게이트 표로 확인합니다.
강제 장치를 끄는 변경(규칙 삭제, 화이트리스트 완화)은 일반 코드 변경과 같은 리뷰를 거치지 않게 되기 쉬우므로, 정책 파일 변경에 별도 승인 경로를 두는 것을 검토합니다. ca-tmpl은 CODEOWNERS로 보안 소유자를 지정하되, 실제 강제는 브랜치 보호 설정에 달려 있음을 함께 기록합니다.

결론

제가 ca-tmpl을 만들면서 가장 중요하게 본 것은 “클린 아키텍처로 짰다”는 이름이 아니라 위반이 실제로 멈추는 지점이었습니다. 그래서 경계를 컴파일러와 빌드 시스템이 볼 수 있는 형태로 옮겼고, 금지된 의존이 자동으로 실패하도록 만들었습니다.

ca-tmpl은 세 겹의 게이트를 사용합니다. 모듈 분리는 금지된 타입을 코어 클래스패스에서 없앱니다. verifyCleanArchitectureDependencies는 네 production configuration에 직접 선언된 프로젝트 의존의 상한을 검사합니다. ArchUnit은 허용된 클래스패스 안의 패키지·애노테이션 규칙까지 확인합니다. 강제의 범위도 분명합니다. 문자열 기반 리플렉션, 도메인 모델 자체의 품질, 운영 트래픽에서 나타나는 효과는 이 게이트만으로 판단할 수 없고 포트와 모듈을 늘리는 비용 역시 사라지지 않습니다.

앞에서 정한 여섯 요구와 제가 구현한 장치를 모으면 다음과 같습니다.

문제	설계 요구	`ca-tmpl`의 구현
DB 변경이 서비스·API까지 전파	영속성 모델과 도메인 모델 분리	도메인 애그리게이트와 영속 엔티티를 구분하고 어댑터가 재매핑을 소유
정책이 Spring 타입에 결합	코어의 프레임워크 클래스패스 제한	`domain-core` main compileClasspath는 외부 의존 없이 두고 `application-core`에서 Web·JPA·Spring TX 제외
Controller가 Repository를 우회	유스케이스를 통한 진입	`FeedController`가 유스케이스를 주입하고 서비스는 코어의 일반 계약을 구현
테스트가 DB를 요구	애플리케이션 소유 출력 포트	코어가 출력 포트를 정의하고 어댑터가 구현해 안쪽 테스트를 인프라에서 분리
패키지 경계가 침식	컴파일·빌드·테스트 수준 강제	클래스패스, Gradle 의존 허용 목록, ArchUnit 규칙을 함께 적용
운영 계약이 도메인에 침투	도메인 언어와 운영 언어 분리	샘플 도메인은`Reason`을 소유하고 샘플 web 어댑터가 `ApiErrorCode`로 변환

이 장치들이 실제 팀의 변경 속도와 장애 비용에 어떤 영향을 주는지는 도입 환경에서 따로 측정해야 합니다.

제가 ca-tmpl을 만들며 내린 결론은 규칙의 개수보다 실패하는 지점이 중요하다는 것입니다. 중요한 경계 위반을 재현 가능한 검사로 옮기고, 그 검사가 놓치는 영역도 함께 기록해야 합니다. 자신의 저장소에서도 자주 발생하는 경계 위반 하나를 골라 리뷰·테스트·컴파일 중 어디에서 멈추는지 확인해 볼 수 있습니다. 아직 사람의 기억에만 기대고 있다면 그 위반부터 자동 검사로 옮기면 됩니다.

153 KiB Executable File Raw Blame History Unescape Escape