donghyeon.kang/document-haness

Fork 0

Files

T

DongHyeonka 41501b5d06 chore: 문서를 작성할 때 한국어의 표현 작성 스킬 추가 및 1인칭 관점의 글 작성 검증 테스트 추가

2026-07-29 16:48:03 +09:00

146 KiB

Executable File

Raw Blame History

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

이 글은 경계 위반을 코드 리뷰나 계속 인지해야되는 상황이 아닌 컴파일·빌드·테스트 단계에서 자동으로 거부하는 방법을 설명한다.

핵심은 책임을 분리한 뒤 소스 의존 방향을 코어 쪽으로 고정하고, 그 규칙을 빌드가 검사하게 만드는 것이다.

그래서 무엇을 해결하는가

"우리는 클린 아키텍처로 짰다"는 선언만으로는 협업 과정에서 생기는 경계 위반을 막을 수 없다. 예를 들면 컨트롤러가 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	있음	약함(테스트뿐)	컴파일 성공
멀티모듈 Clean	있음	클래스패스	금지 타입컴파일 실패
실행 가능한 Clean	있음	클래스패스 + 정책 + 테스트	금지 모듈 의존빌드 실패

아래로 내려갈수록 "경계가 무너지는 순간"은 리뷰어에서 컴파일·검증 실패로 옮겨간다. 이것이 핵심이다. 실행 가능한(executable) 아키텍처는 맨 아래 줄처럼 경계가 깨지면 컴파일이나 빌드가 실패하는 구조다.

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

경계 침식을 막으려면 앞의 문제를 구현 가능한 요구사항으로 바꿔야 한다. 경계가 보이지 않으면 DB 스키마 변경이 서비스와 API 응답 모양까지 번지고 서비스가 구체 저장소에 묶여 테스트가 DB 없이 돌 수 없게 된다. 오류 코드 같은 운영 어휘도 도메인 코드에 스며들게 되고 이렇게 드러난 원인과 대응을 짝지으면 다음과 같다.

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

여섯 요구는 이 글 전체의 뼈대다. 결론에서 각 요구를 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 모듈에 있다. 둘을 하나의 모듈로 합치지 않고 갈라놓은 것 자체가 제약이다. "운영 계약이 도메인에 침투하지 않아야 한다"는 위 요구사항 표의 마지막 행이 여기서 드러난다.

핵심 판단 기준과 멘털 모델

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

클린 아키텍처 그림을 처음 보면 걸리는 게 하나 있다. 화살표가 실행 순서와 반대로 그려져 있다. 런타임에는 바깥의 컨트롤러가 안쪽을 호출하는데, 의존 화살표는 바깥이 안쪽을 가리킨다. 이 원인은 서로 다른 세 방향을 한 화살표로 뭉뚱그리는 데 있다. 먼저 셋을 갈라놓자.

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

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

왜 반대가 되나. 자연스럽게 짜면 호출하는 쪽이 호출당하는 쪽의 타입을 안다. 유스케이스가 DB 리포지토리를 직접 알면 소스 의존이 호출 방향을 그대로 따라 안에서 바깥으로 흘러 코어가 DB를 알게 된다.

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

ca-tmpl에서도 코어 모듈 application-core가 TransactionPort라는 인터페이스를 소유하고 있고 실제 구현체인 SpringTransactionPort는 바깥의 JPA 어댑터에 있다. 구현이 인터페이스를 알아야 하니 어댑터 소스가 코어를 향하게 된다. 모듈 수준도 같다.

implementation project(':application-core')

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

같은 한 쌍에서 호출은 나가고 의존은 들어온다. 이게 바로 역전이며 이 역전이 있어야 application-core가 DB·영속 구현과 전송 프레임워크 타입을 모른 채 남는다. 다만 application-core 자체가 framework-free라는 뜻은 아니다. 이 모듈은 SLF4J를 사용한다. 코어 셋 중 외부 의존이 전혀 없는 main 컴파일 표면은 domain-core와 운영 계약 모듈 shared-contract이다.

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

Hexagonal이 그리는 육각형에서 안과 밖을 가르는 기준은 기술 종류가 아니다. 웹이든 메시지 큐든 파일시스템이든 전부 "바깥"이고 안쪽에는 도메인과 유스케이스만 남는다. 진짜 기준은 누가 대화를 거는가다. 바깥이 안쪽에 말을 걸면(HTTP 요청, 스케줄러, 메시지 소비) 그 통로는 인바운드 쪽이다. 안쪽이 바깥에 말을 걸면(DB 조회, 알림 발송, 파일 저장) 그 통로는 outbound 쪽이다.

원리 수준의 흐름은 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) — 안쪽이 바깥에 능력을 요구하는 창구. 코어는 "이런 능력이 필요하다"까지만 선언하고 그 능력을 무엇으로 채우는지는 모른다.

강제하는 주체는 늘 코어지만 강제받는 대상이 반대다. 이 반대 방향을 하나의 인터페이스로 합치면 "받는 계약"과 "요구하는 계약"이 뒤섞여 어느 한쪽이 바뀌어도 나머지 관계자 전부가 흔들린다. ca-tmpl은 읽기와 쓰기의 의도를 타입에 드러내기 위해 Input Port 쪽에 세분을 하나 더 둔다. UseCase<I, O>를 CommandUseCase와 QueryUseCase로 가르고 GetFeedUseCase는 후자를 구현한다. FeedController는 일반 계약이 아니라 구체 GetFeedUseCase에 의존하고 FeedQueryAdapter는 명시적인 FeedQueryPort를 구현한다. 두 소스 의존 모두 코어를 향하지만 인터페이스를 실제 주입 경계로 쓰는 정도는 같지 않다.

포트를 통해서 계약과 구현체를 구분하는 이유는 그 경계 너머에 실제로 바뀔 수 있는 기술이 있고 테스트에서 실제로 대체할 필요가 있기 때문이다. 외부 기술이 전혀 끼지 않는 코어 내부의 계산·조립 클래스까지 인터페이스 하나에 구현체 하나로 감싸기 시작하면 바뀌는 건 아무것도 없이 읽는 사람이 두 파일을 오가는 간접 비용만 남는다. 포트는 "이 자리는 기술이 바뀔 수 있다"라는 내용을 기억하고 포트를 설계하면 된다.

두 번째로 들어가는 비용 매핑에 대해서 얘기를 해보려고 한다. 같은 피드 항목 하나가 흐름을 지나며 최소 세 벌의 모델을 거친다. 실제로 liner의 feed를 구현하면서 FeedQueryAdapter가 JPA 엔티티 필드를 코어의 FeedSummary로 손수 조립하고 FeedWebMapper.toResponse가 그 FeedSummary를 웹 응답 FeedResponse로 다시 조립한다. 중첩 값 객체도 같은 일을 두 번 겪는다. FeedSummary.HighlightSummary와 FeedResponse.HighlightPart는 필드 세 개(color, text, createdAt)가 완전히 같은데도 별개 타입으로 두 번 선언되고 두 번 매핑된다. DB가 공급하는 필드 하나를 응답까지 전달하려면 세 클래스와 두 매핑 함수를 함께 고쳐야 한다. 격리에서 오는 코어가 JPA도 HTTP도 모른다는 장점도 있지만 이처럼 2번의 매핑을 해야된다는 단점 또한 존재한다. 요즘은 ai시대라 이런 단점이 와닿지 않을 수 있지만 직접 계속 손으로 쳐보면서 겪어보면 왜 단점이라고 말하는지 와닿을 수 있다.

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

클린 아키텍처를 보통 표현을 할 때 4개의 링을 두고 설명을 하는데 ca-tmpl에서는 이 4개의 링을 적용 시킨 것도 중요하지만 변경 이유가 제일 중요하다. 같은 이유로 바뀐 코드는 한 경계에 두고, 다른 이유로 바뀌는 코드는 의존 방향을 분리해야 한다.

링	`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 같은 외부 라이브러리 간선은 어댑터 모듈에서 프레임워크 쪽으로 향한다. 지키는 규칙은 그 외부 의존을 어댑터 경계 안에 가두어 코어 모듈의 클래스패스로 퍼지지 않게 하는 것이다.

Boundary Data. ca-tmpl은 경계마다 복합 객체의 소유권과 모양을 다시 정한다. JPA 엔티티 → FeedSummary(Application) → FeedResponse(Interface Adapter)로 애그리게이트·조회·HTTP 응답의 모양이 갈라진다. 다만 모든 필드 타입까지 복제하는 완전 격리는 아니다. FeedItemJpaEntity는 도메인의 Visibility enum을 직접 import해 재사용한다. 의미가 동일한 단순 enum까진 중복해서 정의하지 않는다.

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

Uncle Bob의 Entity는 domain-core의 FeedItem이다. @AggregateRoot 어노테이션을 명시함으로써 public set이 들어오게 되면 별도의 테스트를 통해서 실패를 하게 된다. 임포트는 자체 stereotype 애노테이션과 JDK 타입뿐이다.
JPA @Entity는 adapter/outbound/jpa의 FeedItemJpaEntity다. jpa의 의존성을 임포트하고 @Entity @Table(name = "feed_items")가 붙는다. 영속성 프레임워크가 리플렉션으로 다루기 위한 계약이다.

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

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

세 이름은 같은 답을 반복하지 않는다. Layered는 표현·서비스·영속성처럼 기술적 책임을 층으로 묶는다. Hexagonal은 외부와 대화하는 자리를 Driving/Driven 포트로 가른다. Clean은 정책 수준에 따라 소스 의존이 향할 방향을 정한다. 셋이 겹치는 지점은 DIP다. 바깥 기술이 코어가 소유한 계약에 의존하게 만들면 도메인은 구체 프레임워크를 모른 채 남는다.

Layered도 서비스 계층이 소유한 포트에 영속성 구현이 의존하도록 만들 수 있다. 층의 개수와 의존 역전은 별개의 결정이다. Hexagonal의 질문이 "경계를 어디에 그을까"라면 Clean의 질문은 "그 경계를 넘는 소스 의존은 어느 쪽을 향할까"다. 이 결합은 DB 교체 비용을 없애지 않는다. 식별자·쿼리·락·격리 수준이 달라지면 코어 계약도 영향을 받을 수 있다. 여기서 얻는 것은 변경의 파급을 어댑터와 매핑 경계에 가둘 수 있다는 것이다. ca-tmpl의 멀티모듈 구성은 컴파일·빌드 강제를 함으로써 변경의 파급을 최소화 할 수 있도록 하였다.

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

멘털 모델의 마지막 조각은 "그래서 모듈을 얼마나 쪼개야 하는가"라는 판단 기준이다. 모듈은 많을수록 좋은 게 아니다. 모듈 하나를 추가할 이유는 하나뿐이다.

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

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

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

이 질문에 모두 "아니오"라면 모듈을 분리해서 얻는 이점보다 관리 복잡성이 더 클 수 있기 때문에 모듈로 나누지 않는 편이 낫다고 생각한다. 이 기준은 여러 기업 기술 블로그에서 반복적으로 띄고 나타난 모듈 분리 목적, 즉 독립적인 테스트, 변경 영향 범위의 제한, 기능의 선택적 조합을 바탕으로 정하게 되었다. ca-tmpl을 처음 만들 때 스켈레폰이라고 생각하고 만들었기에 사용하지 않는 기능 모듈을 런타임 의존성에서 제외하면 해당 모듈과 관련된 자동 구성 및 어플리케이션 컨텍스트가 등록되지 않아야 한다. 이 기준이 실제로 어떻게 적용되었는지 살펴보자.

해결 방식이 동작하는 과정

전체 구조 — 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개의 모듈이 구성되게 되었다. 이 보편적이다라는 말이 postgresql, mongodb, redis, kafka 등등의 기술들이 모든 프로젝트 별로 주로 사용한다고 일반화할 순 없지만 Stack Overflow Developer에 따르면 rdb같은 경우는 postgresql nosql 같은 경우는 mongodb, redis의 사용량이 제일 높았고 이를 반영하여 모듈을 구성하게 되었다.

전체 구조는 서로 다른 관점으로 나눠 볼 수 있다. 먼저 outbound이다.

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공유의 비대칭을 보여 주는 다섯 부분만 표현한다.

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

예시로 같은 피드 항목과 관련된 타입은 경계마다 다른 모델로 구분된다. 아래 표는 실제 피드 조회 흐름에는 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` 리플렉션 계약

다섯 모델은 한 객체의 생애주기 단계가 아니다. 마커 Command와 Query는 조회 경로에는 읽기 마커만 쓰이지만 쓰기 마커는 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가 코어 모델 변경을 따라 바뀌는 것이 의도한 결합이다.

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

ca-tmpl프로젝트에선 기능·기술 패키지가 섞인 hybrid 배치와 19개 leaf 모듈을 함께 쓴다. 패키지 축과 모듈 축은 겹쳐 보이지만 같은 문제를 풀지 않는다. 패키지는 무엇이 같이 사는가라는 응집을 정하고 모듈은 무엇이 무엇을 알 수 있는가라는 강제를 정한다.

패키지 축으로 응집은 얻지만 컴파일러는 여전히 못 막는다. 도메인의 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

세 코어 모듈은 모두 안쪽에 있지만 같은 종류의 순수성을 약속하지 않는다. 공통되는 건 각 모듈이 알아도 되는 지식을 컴파일 클래스패스와 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에서도 별도의 외부 의존성을 갖지 않는다 여기서는 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은 프로토콜이 다르지만 같은 불변식을 따른다. 전송 기술을 코어 밖에 두고 아웃바운드 구현을 직접 고르지 않는다. app-bootstrap main 프로젝트 의존에는 web만 들어가며 나머지 세 모듈은 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 모듈은 "프로토콜 지원"의 범위를 과장하지 않는다. gRPC는 health·reflection만, GraphQL은 최소 헬스 스키마만 제공하고 WebSocket 경로의 도메인은 STOMP를 알지 못한다. 전송을 추가하려면 이 표면 위에 피처 계약을 얹어야 하며 존재만으로 업무 API가 완성되지는 않는다. 이렇게 얇은 opt-in 모듈로 남겨 두면 기본 애플리케이션에 불필요한 전송 의존을 넣지 않고도 확장 지점을 시험할 수 있다. 마지막 안전망은 전송 종류와 무관하다. INBOUND_ADAPTERS_DO_NOT_DEPEND_ON_OUTBOUND_ADAPTERS가 인바운드에서 아웃바운드로 향하는 모든 직접 의존을 거부한다.

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

아웃바운드 모듈 열 개는 외부 기술이 달라도 인바운드나 형제 구현을 직접 선택하지 않는다. 모듈 수보다 중요한 차이는 "무엇을 실제로 연결했는가"와 "어떤 확장점만 남겼는가"다.

묶음	모듈	구현된 능력	도입 시 확인할 예외
영속성	`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라 컴파일 표면에 노출되지 않고 .postgresql 밖의 패키지는 PERSISTENCE_RDBMS_STAYS_VENDOR_NEUTRAL 규칙으로 벤더 타입을 참조하지 못한다.

cache-redis·messaging·notification세 모듈의 빌드에는 각각 Redis SDK, Kafka SDK, Slack SDK 선언이 없다. 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이 프로덕션 모듈과 샘플 패키지를 함께 스캔하되 샘플 전용 영속 구성으로 대체할 설정과 공개 데모에서 제외할 보안 구성을 필터로 뺀다.

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

여기서 자연스러운 질문이 나온다. 클린 아키텍처는 패키지만 잘 나눠도 그릴 수 있다. 그런데 ca-tmpl은 왜 굳이 19개 모듈로 쪼갰나. 답은 앞의 그래프가 말이 아니라 컴파일러가 강제하는 사실이 되기 때문이다.

한 가지 모델을 짚고 간다. 자바는 컴파일 시 각 모듈의 클래스패스(그 모듈이 볼 수 있는 타입의 집합)를 기준으로 타입을 해석한다. 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은 앞의 동기를 세 겹의 실행 가능한 게이트로 옮겼다. 세 범위에는 고정된 실행 순서나 속도 순위를 부여하지 않는다.

세 게이트는 각기 다른 위반 표면을 맡는다. 실행 순서나 속도 순위는 없다. 모듈을 합치면 클래스패스 격리와 프로젝트 의존 정책의 범위가 사라지고 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 HTTP 요청이다. 코드가 정의한 순서는 다음과 같다.

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 세 벌의 모델을 거치고 두 매핑 모두 어댑터가 소유한다. 셋째, 소스 의존은 실행 내내 안쪽만 향한다. 컨트롤러와 어댑터가 코어 타입을 import하고 코어는 그 반대를 하지 않는다. 이 하나의 요청이 앞 절의 구조 전체(포트 소유권, 모델 분리, 클래스패스 격리)를 실증한다.

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

입력 검증은 서로 다른 세 질문을 뒤섞기 쉽다. "형식이 맞는가", "여러 필드가 서로 앞뒤가 맞는가", "이 상태 전이가 도메인 규칙을 지키는가". 세 질문을 한 계층에서 처리하면 둘 중 하나가 깨진다. 도메인이 jakarta.validation 애노테이션을 알게 되거나(순수성 상실), 애플리케이션 계층이 웹 프레임워크의 예외 처리를 흉내 내야 한다.

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

3계층 검증의 실물은 sample-portfolio의 Poster·WorkLog 경로에 있다. 질문마다 게이트가 다르다.

웹 경계 — 문법. 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

오류 계약은 "누가 분류하는가"와 "클라이언트에 무엇을 공개하는가"를 분리해야 한다. 이 분리는 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(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키 제거를 수행한다.

보장 범위를 정확히 긋는다. 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는 애플리케이션 계층이 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는 이 셋을 하나의 결정 흐름에서 구분한다. 정상적인 동시 삽입 경로에서는 명시적 분산 락 대신 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 심판

DB 변경과 브로커 발행을 한 트랜잭션으로 묶을 수 없으면 어느 쪽을 먼저 해도 실패 창이 생긴다. 아웃박스(outbox)는 브로커 호출을 비즈니스 트랜잭션에서 빼고 대신 발행할 이벤트 행을 같은 DB 트랜잭션에 저장한다. 현재 샘플에서는 CreateWorkLogUseCase가 도메인 저장과 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·릴레이·상태기계·테스트 실재	샘플 쓰기 경로 배선됨, 소비자 영속 중복 제거는 범위 밖

어떻게 검증할 것인가

앞의 구조와 흐름이 실제로 지켜지는지는 네 방향에서 본다. 테스트 경계가 실행·대체 범위를 드러내는지, 규칙 자체가 살아 있는지(test-the-test), 위반을 주입하면 예측된 게이트에서 멈추는지 (break-it), 그리고 빌드 밖의 아티팩트·런타임 계약이 저장소에서 검증되는지를 확인한다.

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

테스트 경계는 어떤 도구를 쓰는지보다 무엇을 실제로 실행하고 어디를 대체하는지에서 드러난다. 현재 테스트 트리를 실행 비용과 대체 범위에 따라 네 층으로 정리한다.

층	무엇을 검증	진짜(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). ca-tmpl은 여기에 한 겹을 더 뒀다. architecture/violations/에는 package-info.java를 제외한 Java 소스 48개가 있다. 규칙을 일부러 어기는 타입과 그 평가를 돕는 지원 타입이 함께 있다. 이 코퍼스를 넣었을 때 규칙이 실제로 실패하는지를 별도 테스트로 단언한다.

세는 기준. 해당 트리는 .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

위반을 프로덕션 코드에 넣었을 때의 예상 실패 지점은 클래스패스와 규칙 정의에 따라 달라진다.

① 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·공급망·컨테이너

세 겹 게이트는 빌드 안의 경계를 다룬다. 장기 재사용 템플릿은 코드가 아티팩트가 된 뒤의 공급망과 컨테이너 런타임도 저장소 계약으로 다룰 수 있다.

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` 판단에 쓰는 범위
우아한형제들	레이어 단위 멀티모듈에서 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 선언, 테스트 규칙으로 판단해야 한다.

다섯 설계 결정과 그 반대편

현재 구성은 다섯 축에서 서로 다른 위치를 차지한다. 선택의 이유와 비용을 함께 보면 장기 재사용 템플릿에는 적합하지만, 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의 분리

도메인 예외가 HTTP 상태나 운영 에러 코드를 직접 알면 변환 코드는 줄지만 도메인 언어와 전송 계약이 결합한다. 이 패턴은 전체 도메인이 아니라 sample-portfolio의 WorkLog·Poster 예외에서 확인된다. 두 샘플 도메인은 안전한 명사 enum Reason을 남기고 Reason에서 ApiErrorCode로의 변환을 샘플 웹 계층의 DomainExceptionHandler가 소유한다.

// 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`처럼 자동 게이트를 포함한 스켈레톤
경계 침식의 조기 차단이 핵심인 서비스	컴파일·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은 세 겹의 게이트를 사용한다. 모듈 분리는 금지된 타입을 코어 클래스패스에서 없앤다. 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`로 변환

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

기억할 판단은 하나다. 실행 가능한 아키텍처의 가치는 규칙을 많이 두는 데 있지 않고 중요한 실패를 재현 가능한 검사로 바꾸고 그 한계를 함께 공개하는 데 있다. 다음 행동은 자신의 저장소에서 가장 아픈 경계 위반 하나를 골라, 그 위반이 지금 리뷰·테스트·컴파일 중 어디에서 멈추는지 확인하는 것이다. 멈추는 곳이 사람의 기억이라면 그 자리가 첫 번째 게이트를 세울 자리다.

146 KiB Executable File Raw Blame History Unescape Escape