급하게 기능을 붙이다 보면 컨트롤러가 어느새 저장소를 직접 만들어 쓰고, 중복 검사 같은 업무 규칙까지 안에 들어가 있습니다. 화면에서는 잘 돌아가니 문제가 없어 보입니다. 하지만 이 컨트롤러는 스프링을 띄우지 않고는 테스트할 수 없고, 저장 방식을 바꾸면 컨트롤러까지 고쳐야 합니다. 외부 업체의 HTTP API를 서비스에서 바로 부르면 한 걸음 더 나빠집니다. 서비스 테스트에 외부 서버가 필요해지고, 외부 응답의 필드 이름이 코드 곳곳에 퍼집니다.
이 Chapter는 두 단계로 이 문제를 풉니다. 먼저 코드를 계층으로 나누고 나눈 방향이 무너지지 않게 테스트로 고정합니다(ch23). 이어서 외부 시스템 호출을 Port(인터페이스) 뒤로 숨기고 외부의 응답과 실패를 우리 말로 번역합니다(ch24). Chapter 12에서 본 계약 개념이 이번에는 “응용이 바라는 계약”으로 나타납니다.
이 Chapter에서 만드는 것
| 만드는 것 | 설명 |
|---|---|
| 계층 구조 | web, service, repository, notification, domain 패키지 |
| 인터페이스 의존 | UserService가 UserRepository, WelcomeNotifier 인터페이스만 앎 |
| ArchUnit 규칙 | 계층 방향, 컨트롤러의 저장소 직접 사용 금지, 위반 예제로 규칙 검증 |
AddressLookupPort |
응용이 바라는 외부 조회 계약 |
HttpAddressLookupAdapter |
외부 응답 번역과 실패 변환 |
| 테스트 | ch23: 14건, ch24: 21건 |
전체 흐름
- 코드를 계층으로 나누고 의존 역전과 예외 분리를 적용한 뒤, ArchUnit으로 의존 방향을 고정합니다(ch23).
- 외부 주소 API를 Port와 Adapter로 감싸고, 외부 응답을 번역하고 외부 실패를 하나의 예외로 모읍니다(ch24).
- 마지막으로 구조와 연동에서 만나는 오류 메시지를 증상별로 정리합니다.
직접 실행해 확인한 결과
| 확인 | 결과 |
|---|---|
ch23 test |
14건 통과 |
ch24 test |
21건 통과 |
| ch23 실행: 가입 / 대소문자만 다른 이메일 / 없는 사용자 | 201 + Location, 409, 404 |
| ch24 실행: 외부 주소 서버가 없을 때 가입 / 형식이 틀린 우편번호 | 503, 400 |
사전 지식과 준비물
- Chapter 03의 DI와 Chapter 09의 서비스·저장소 구분, Chapter 12의 ArchUnit.
- 코드는
examples/ch23-layered-solid,examples/ch24-port-adapter입니다.
확인 환경
Docker 컨테이너(JDK 21.0.11), Spring Boot 4.1.1, ArchUnit 1.4.1입니다. 외부 주소 API는 테스트에서 JDK 내장 HttpServer로 흉내 냈고 실제 상용 API와는 연동하지 않았습니다. Windows는 확인하지 못했습니다.
예제 코드
| 대상 | 링크 |
|---|---|
| 계층 | ch23-layered-solid/ |
| Port/Adapter | ch24-port-adapter/ |
| 컨트롤러 | UserController.java |
| 서비스 | UserService.java |
| 서비스 테스트 | UserServiceTests.java |
| 예외 핸들러 | GlobalExceptionHandler.java |
| API 테스트 | UserApiTests.java |
| 구조 테스트 | ArchitectureTests.java |
| 위반 예제 | FatUserController.java |
| Port | AddressLookupPort.java |
| 서비스 | RegisterMemberService.java |
| HTTP 어댑터 | HttpAddressLookupAdapter.java |
| 외부 응답 타입 | ExternalAddressResponse.java |
| 설정 | AddressApiProperties.java |
| 어댑터 테스트 | HttpAddressLookupAdapterTests.java |
| 가짜 외부 서버 | FakeAddressServer.java |
| 구조 테스트 | ArchitectureTests.java |
| 응용 테스트 | RegisterMemberServiceTests.java |
| 위반 예제 | leaky/ |
계층마다 하는 일을 한 줄로 정합니다
계층을 나눈다는 것은 폴더를 나누는 것이 아니라 “이 클래스는 무엇을 알고 무엇을 몰라야 하는가”를 정하는 것입니다. 이 절에서는 사용자 등록·조회 API의 패키지를 계층별로 나누고, 각 계층의 책임을 한 줄로 적습니다.
책임 표
| 패키지 | 하는 일 | 모르는 것 |
|---|---|---|
web |
요청을 받아 서비스를 부르고 응답 모양으로 바꾼다 | 저장 방식, 업무 규칙 |
service |
업무 규칙을 지킨다(이메일 중복 금지, 가입 후 알림) | HTTP, 저장 방식 |
repository |
저장하고 읽는다 | 업무 규칙, HTTP |
notification |
알림을 보낸다 | 누가 언제 부르는지 |
domain |
사용자 값(User 레코드) |
위의 모든 계층 |
“모르는 것” 열이 핵심입니다. 서비스가 HTTP를 모르면 같은 서비스를 배치나 메시지 소비자에서도 쓸 수 있고, 저장소가 업무 규칙을 모르면 저장 방식만 바꿀 수 있습니다.
컨트롤러는 서비스만 부른다
@PostMapping
public ResponseEntity<UserResponse> register(@Valid @RequestBody UserRequest request) {
UserResponse body = UserResponse.from(service.register(request.name(), request.email()));
return ResponseEntity.created(URI.create("/api/users/" + body.id())).body(body);
}
주요 코드 설명
- 컨트롤러가 하는 일은 세 가지입니다. 요청 검증(
@Valid, Chapter 06), 서비스 호출, 응답 모양 만들기. - 중복 검사 같은 업무 규칙은 여기에 없습니다.
service.register(...)안에 있습니다. - 응답은
UserResponse.from(...)으로 도메인User를 응답 DTO로 바꿉니다. 이 변환을 MapStruct로 하는 방법은 Chapter 12에서 다뤘습니다. Location헤더로 새 자원의 주소를 알려 줍니다(Chapter 05의 201 응답).
의존 방향을 정리하면 web의 UserController는 service의 UserService를 부르고, UserService는 repository의 UserRepository와 notification의 WelcomeNotifier를 부릅니다. domain의 User는 세 계층이 모두 사용합니다.
위 계층만 아래 계층을 부릅니다. 반대 방향(저장소가 서비스를 부르는 등)은 허용하지 않습니다. 이 방향을 어기는 코드가 들어오는 순간 빌드가 멈추게 하는 방법은 아래 “계층 규칙” 절에서 봅니다.
따라 하기
./gradlew :examples:ch23-layered-solid:bootRun
curl -i -X POST http://localhost:8080/api/users -H 'Content-Type: application/json' \
-d '{"name":"kim","email":"kim@example.com"}'
201과 Location: /api/users/1이 나오면, 요청이 web → service → repository로 내려갔다가 돌아온 것입니다.
확인 문제
- 계층을 정의할 때 “하는 일”뿐 아니라 “모르는 것”을 적는 이유는 무엇인가요?
- 컨트롤러가 하는 일 세 가지는 무엇인가요?
답: 1) 모르는 것이 의존 방향의 제약이 되어 변경 범위를 좁히기 때문입니다. 2) 요청 검증, 서비스 호출, 응답 모양 만들기입니다.
직접 해 보기
- 자신의 컨트롤러 하나를 열어 “업무 규칙이 들어 있는가”를 점검해 보세요.
- 책임 표의 “모르는 것”을 자신의 프로젝트에 맞게 다시 적어 보세요.
- 서비스가 HTTP를 모르면 어떤 재사용이 가능해지는지 두 가지 적어 보세요.
서비스는 구체 클래스를 모릅니다
서비스가 new InMemoryUserRepository()를 직접 만들어 쓰면 저장 방식이 서비스에 박힙니다. 서비스가 인터페이스에만 의존하고 구현은 바깥에서 끼워 주면(의존 역전), 테스트에서 가짜를 끼울 수 있고 저장 방식도 바꿀 수 있습니다. 이 절은 의존 역전 원칙(DIP)을 코드로 확인합니다.
서비스
@Service
public class UserService {
private final UserRepository repository;
private final WelcomeNotifier notifier;
public UserService(UserRepository repository, WelcomeNotifier notifier) { ... }
public User register(String name, String email) {
if (repository.existsByEmail(email)) {
throw new DuplicateEmailException(email);
}
User saved = repository.save(name, email);
notifier.welcome(saved);
return saved;
}
}
주요 코드 설명
- 서비스가 의존하는 것은
UserRepository와WelcomeNotifier, 두 인터페이스뿐입니다. 어떤 구현이 오는지(메모리, DB, 로그, 이메일) 모릅니다. - 생성자 주입(Chapter 03)이라 구현은 스프링이 끼워 줍니다. 테스트에서는 직접 끼울 수 있습니다.
- 업무 규칙(이메일 중복 금지, 가입 후 환영 알림)은 서비스에 있고 저장·알림 방법은 모릅니다.
가짜 구현으로 스프링 없이 테스트
테스트에서는 알림을 보내는 대신 받은 사용자를 기록하는 가짜를 끼웁니다.
static class RecordingNotifier implements WelcomeNotifier {
final List<User> welcomed = new ArrayList<>();
public void welcome(User user) { welcomed.add(user); }
}
private final UserService service = new UserService(new InMemoryUserRepository(), notifier);
스프링 컨테이너 없이 서비스만 만들어 검사하므로 빠릅니다. 테스트 3건이 확인하는 것은 다음과 같습니다.
| 테스트 | 확인 |
|---|---|
| 가입하면 저장되고 알림이 한 번 간다 | welcomed의 크기 1 |
| 이메일이 중복(대소문자만 달라도)이면 예외, 알림은 가지 않는다 | DuplicateEmailException, welcomed 비어 있음 |
없는 id는 UserNotFoundException |
조회 시 예외 |
이 방식은 Chapter 19의 단위 테스트에서 Mockito로 확장됩니다.
확인한 것과 하지 않은 것
SOLID의 다섯 원칙 중 이 예제에서 확인한 것은 단일 책임(계층 분리), 의존 역전(인터페이스 의존), 인터페이스 분리(작은 인터페이스)입니다. 개방-폐쇄와 리스코프 치환은 별도 예제를 두지 않았습니다. 저장소 구현이 메모리 하나뿐이라 “구현을 바꿔 끼운다”는 장점은 테스트의 가짜 구현으로만 보였습니다.
따라 하기
./gradlew :examples:ch23-layered-solid:test --tests '*UserServiceTests*'
Spring 컨테이너 없이 서비스 테스트 3건이 실행됩니다. 서비스 클래스가 new InMemoryUserRepository()를 직접 만들지 않으므로 이런 테스트가 가능합니다.
직접 해 보기
RecordingNotifier처럼 저장소의 가짜를 만들어existsByEmail이 항상true인 상황을 테스트해 보세요.- 서비스가
new InMemoryUserRepository()를 직접 만들게 바꾸면 테스트가 어떻게 어려워지는지 적어 보세요. - 인터페이스가 하나 늘 때마다 생기는 비용이 있다면 무엇인지 생각해 보세요.
예외는 서비스가, 상태 코드는 web이 정합니다
중복 이메일일 때 409를 응답해야 합니다. 서비스에서 ResponseStatusException(CONFLICT)를 던지면 편하지만, 그러면 서비스가 HTTP를 알게 됩니다. 이 절은 서비스는 업무 의미의 예외만 던지고, 상태 코드로 바꾸는 일은 web이 맡게 나누는 방법을 봅니다.
예외 변환
서비스는 DuplicateEmailException, UserNotFoundException만 던집니다. 상태 코드는 web 패키지의 GlobalExceptionHandler가 정합니다.
@ExceptionHandler(DuplicateEmailException.class)
ResponseEntity<Map<String, String>> duplicate(DuplicateEmailException e) {
return ResponseEntity.status(HttpStatus.CONFLICT).body(Map.of("message", e.getMessage()));
}
주요 코드 설명
@ExceptionHandler(DuplicateEmailException.class): 이 예외가 컨트롤러 밖으로 나오면 이 메서드가 응답을 만듭니다. Chapter 06의 전역 예외 처리와 같은 방식입니다.- 예외는 업무 의미(
이미 사용 중인 이메일)를, 핸들러는 HTTP 표현(409, 본문)을 맡습니다. 서비스가org.springframework.http를 import하지 않습니다. - 계층 방향을 ArchUnit으로 고정하는 방법은 아래 “계층 규칙” 절에서, 응용 계층이 HTTP 패키지를 못 쓰게 하는 규칙은 아래 “의존 방향 규칙” 절에서 봅니다.
실제 응답
실제 JAR를 띄워 요청한 결과입니다.
POST /api/users {"name":"kim","email":"kim@example.com"}
-> 201 Location: /api/users/1 {"id":1,"name":"kim","email":"kim@example.com"}
POST /api/users {"name":"kim2","email":"KIM@example.com"}
-> 409 {"message":"이미 사용 중인 이메일입니다: KIM@example.com"}
GET /api/users/99
-> 404 {"message":"사용자를 찾을 수 없습니다: 99"}
두 번째 요청은 대소문자만 다른 이메일인데도 409입니다. 저장소의 existsByEmail이 이메일을 대소문자 구분 없이 비교하기 때문입니다. 검증 오류(400)는 Chapter 06의 방식으로 나옵니다.
테스트 설계에서 고친 것
API 테스트 하나가 처음에는 등록 후 /api/users/1을 조회했습니다. 같은 컨텍스트를 쓰는 다른 테스트가 먼저 가입하면 id가 1이 아닐 수 있는 가정이었습니다. 응답의 Location 헤더를 그대로 따라가도록 바꿨습니다. 테스트끼리 데이터를 공유하는 가정은 순서가 바뀌면 깨집니다. 또 처음 테스트 import 경로를 Boot 3 시절 패키지로 썼다가 컴파일 오류가 나서 org.springframework.boot.webmvc.test.autoconfigure로 바꿨습니다(Chapter 12와 같은 변화).
따라 하기
curl -i -X POST http://localhost:8080/api/users -H 'Content-Type: application/json' \
-d '{"name":"kim2","email":"KIM@example.com"}'
curl -i http://localhost:8080/api/users/99
HTTP/1.1 409 {"message":"이미 사용 중인 이메일입니다: KIM@example.com"}
HTTP/1.1 404 {"message":"사용자를 찾을 수 없습니다: 99"}
직접 해 보기
- 서비스에서
ResponseStatusException을 던지게 바꾸고 ArchUnit 규칙을 추가하면 어떻게 될지 생각해 보세요. - 새 예외 하나(예: 금지된 이름)를 만들고 핸들러를 추가해 보세요.
- 대소문자 구분 없는 이메일 비교를 저장소가 아니라 서비스가 한다면 어떤 장단점이 있을지 적어 보세요.
계층 규칙을 ArchUnit으로 고정하고 규칙 자체를 검증합니다
계층을 나눠도 누군가 컨트롤러에서 저장소를 직접 부르면 구조는 무너집니다. 코드 리뷰에서 매번 지적하는 대신 규칙을 테스트로 고정합니다. 이 절은 Chapter 12에서 익힌 ArchUnit을 계층 규칙에 적용하고, 규칙이 정말 위반을 잡는지 확인하며, 위반 메시지를 읽는 법을 정리합니다.
계층 규칙
layeredArchitecture().consideringOnlyDependenciesInLayers()
.layer("Web").definedBy("..ch23.web..")
.layer("Service").definedBy("..ch23.service..")
.layer("Repository").definedBy("..ch23.repository..")
.layer("Notification").definedBy("..ch23.notification..")
.whereLayer("Web").mayNotBeAccessedByAnyLayer()
.whereLayer("Service").mayOnlyBeAccessedByLayers("Web")
.whereLayer("Repository").mayOnlyBeAccessedByLayers("Service")
.whereLayer("Notification").mayOnlyBeAccessedByLayers("Service");
각 줄의 의미는 다음과 같습니다: Web은 아무도 호출하지 못하고, Service는 Web만, Repository와 Notification은 Service만 호출할 수 있습니다. 여기에 두 규칙을 더했습니다. 컨트롤러는 저장소를 직접 쓰지 못하고, 서비스는 저장소와 알림의 구체 클래스가 아니라 인터페이스에만 의존해야 합니다.
규칙은 어기는 코드를 만들어 봐야 믿을 수 있다
규칙을 쓰고 통과하는 것만 보면 그 규칙이 정말 위반을 잡는지 알 수 없습니다. 세 가지를 확인했습니다.
1. 위반 예제 클래스. 리팩터링 전의 모습을 흉내 낸 FatUserController를 테스트 소스에 두었습니다. 구체 저장소를 new로 만들어 쓰고 중복 검사까지 안에 있는 클래스입니다. 어디에도 등록하지 않았고, “컨트롤러는 저장소를 쓰지 못한다” 규칙을 이 클래스의 패키지에 걸었을 때 위반이 나오는지 테스트합니다.
2. 임시 클래스. web 패키지에 저장소를 주입받는 클래스를 임시로 추가하고 구조 테스트를 돌렸습니다.
ArchitectureTests > controllerDoesNotTouchRepository() FAILED
ArchitectureTests > layersOnlyDependDownward() FAILED
두 규칙이 실패했고, 임시 클래스를 지우자 다시 통과했습니다.
3. 빈 검사 방지. 패키지 이름에 오타가 나면 규칙의 대상이 비게 됩니다. ArchUnit 1.4.1 기본값은 이를 failed to check any classes로 실패시킵니다(이 저장소는 allowEmptyShould를 쓰지 않습니다). 그래도 everyLayerHasClasses 테스트를 두면 어느 계층이 비었는지 구체적으로 알려 주고, 누군가 빈 검사를 허용하도록 설정을 바꿔도 안전망이 남습니다. 기본 실패 / 빈 검사 허용 / 존재 단정 테스트의 차이는 Chapter 12의 ArchUnit에 표로 정리했습니다.
ch23-layered-solid의 테스트 14건은 서비스 3, API 4, 구조 6, 컨텍스트 1이고 모두 통과했습니다.
위반 메시지 읽기
컨트롤러가 저장소를 직접 주입받게 만들어 얻은 결과입니다.
java.lang.AssertionError: Architecture Violation [Priority: MEDIUM] - Rule 'no classes that reside in a package '..ch23.web..' should depend on classes that reside in a package '..repository..'' was violated (2 times):
Constructor <com.jqdom.curriculum.ch23.web.UserController.<init>(com.jqdom.curriculum.ch23.service.UserService, com.jqdom.curriculum.ch23.repository.UserRepository)> has parameter of type <com.jqdom.curriculum.ch23.repository.UserRepository> in (UserController.java:0)
Field <com.jqdom.curriculum.ch23.web.UserController.repo> has type <com.jqdom.curriculum.ch23.repository.UserRepository> in (UserController.java:0)
읽는 법은 세 가지입니다.
Rule '...'이 어긴 규칙의 설명입니다.was violated (2 times)는 위반 지점의 개수입니다.- 아래
Constructor/Field줄이 어느 클래스의 무엇이 어겼는지 가리킵니다. 여기서는 생성자 파라미터와 필드 두 곳입니다.
같은 변경에 계층 규칙(layersOnlyDependDownward)도 함께 실패했는데, 규칙마다 같은 위반을 자기 관점에서 다시 보고하기 때문입니다. 규칙이 여러 개 실패해도 원인은 한 곳일 수 있고, 가장 구체적인 규칙(여기서는 컨트롤러가 저장소를 쓰지 못한다)의 메시지부터 읽습니다. 줄 번호가 UserController.java:0인 것은 바이트코드 기준으로 필드와 생성자를 가리키기 때문으로 보입니다.
| 증상 | 가장 먼저 볼 것 |
|---|---|
Architecture Violation |
메시지의 Rule '...', 아래 Constructor/Field 줄 |
| 여러 규칙이 동시에 실패 | 가장 구체적인 규칙부터, 같은 위반일 수 있음 |
| 규칙은 있는데 위반이 안 잡힘 | ClassFileImporter 대상 패키지, 위반 예제로 규칙 자체 검증 |
한계
계층 규칙은 패키지 이름에 의존하므로 같은 패키지 안에서의 책임 혼합(서비스에 HTTP 코드가 섞이는 것 등)은 잡지 못합니다. 이 한 가지 실험만 했으며 ArchUnit의 다른 위반 모양은 만들지 않았습니다.
따라 하기
./gradlew :examples:ch23-layered-solid:test --tests '*ArchitectureTests*'
구조 테스트 6건이 통과해야 합니다. 재검증에서 ch23 전체 14건이 통과하는 것을 다시 확인했습니다.
직접 해 보기
- 컨트롤러에 저장소를 주입해 위반 메시지를 직접 읽고 되돌리세요.
- 계층 규칙의 패키지 이름을 틀리게 적고
everyLayerHasClasses가 실패하는지 확인하세요. - 자신의 프로젝트에 적용할 규칙 한 줄을 한국어로 먼저 적어 보세요.
Port는 응용 계층이 정한 계약입니다
여기부터는 외부 시스템을 다루는 Port/Adapter입니다(ch24).
회원 가입 때 우편번호로 주소를 확인해야 하는데, 주소는 외부 업체의 HTTP API가 알고 있습니다. 서비스 안에서 RestClient를 바로 부르면 일단 동작합니다. 하지만 그 순간부터 서비스 테스트에 외부 서버가 필요하고, 외부 응답의 필드 이름이 도메인 코드 곳곳에 퍼지고, 외부가 느려지면 우리 서버의 스레드가 묶입니다. 해결의 첫걸음은 외부가 어떻게 생겼는지보다 응용이 무엇을 원하는지를 먼저 적는 것입니다.
Port 정의
public interface AddressLookupPort {
/** 없는 우편번호면 빈 값을 돌려준다. 외부가 응답하지 못하면 AddressLookupUnavailableException. */
Optional<Address> lookup(String postalCode);
}
주요 코드 설명
- 반환 타입은 도메인의
Address입니다. 외부 API가 쓰는 응답 클래스가 아닙니다. - 없음은
Optional.empty()로, 외부 장애는AddressLookupUnavailableException으로 약속합니다. 즉 이 인터페이스의 계약에는 정상, 없음, 실패 세 가지가 모두 적혀 있습니다. 이것이 Chapter 12에서 말한 “계약”의 한 모양입니다. - HTTP 상태 코드나
RestClientException은 보이지 않습니다. 응용 계층은 HTTP를 모릅니다. - Port는 응용 계층이 소유합니다(
application.port패키지). 외부 업체가 바뀌어도 이 인터페이스는 바뀌지 않아야 하기 때문입니다.
서비스는 Port만 안다
@Service
public class RegisterMemberService implements RegisterMemberUseCase {
private final AddressLookupPort addressLookup;
private final MemberStore store;
public RegisterMemberService(AddressLookupPort addressLookup, MemberStore store) { ... }
@Override
public Member register(String name, String postalCode) {
Address address = addressLookup.lookup(postalCode)
.orElseThrow(() -> new UnknownPostalCodeException(postalCode));
return store.save(name, address);
}
}
- 두 협력(
AddressLookupPort,MemberStore)은 모두 Port로만 압니다. 앞의 “서비스” 절에서UserService가 저장소·알림 인터페이스에만 의존하던 의존 역전이 외부 시스템까지 확장된 모습입니다. - 없는 우편번호는
UnknownPostalCodeException으로 바뀝니다. 이 예외는 사용자 입력 오류로 400이 됩니다(아래 “API까지 이어서” 절). - Port에 메서드가 하나뿐이라 서비스 테스트에서는 람다로 대신할 수 있습니다.
code -> Optional.of(GANGNAM)처럼 쓰면 외부 서버 없이 응용 계층만 검사합니다.
패키지 구조
adapter.web -> application.usecase -> application.port <- adapter.address
| adapter.persistence
domain
화살표는 의존 방향입니다. 어댑터(adapter.address)가 Port(application.port)를 구현하면서 응용을 향합니다. 응용은 어댑터를 모릅니다.
계약에 적힌 것을 표로
| 상황 | Port의 약속 | 호출하는 서비스가 하는 일 |
|---|---|---|
| 우편번호가 있다 | Optional.of(Address) |
저장 |
| 우편번호가 없다 | Optional.empty() |
UnknownPostalCodeException(입력 오류) |
| 외부가 응답하지 못한다 | AddressLookupUnavailableException |
그대로 올림(web이 503) |
확인 문제
- Port를 누가 소유하나요?
- 서비스 테스트에서 Port를 람다로 대신할 수 있는 이유는 무엇인가요?
답: 1) 응용 계층입니다. 2) Port에 메서드가 하나뿐이라 함수형 인터페이스처럼 쓸 수 있기 때문입니다.
직접 해 보기
AddressLookupPort를 람다 대신 가짜 구현으로 만들어 “없는 우편번호” 테스트를 써 보세요.- 반환 타입을
ExternalAddressResponse로 바꾸면 무엇이 외부 모양에 묶일지 적어 보세요. - 실패를 계약에 적지 않고
RuntimeException만 던지게 하면 호출하는 쪽에서 무엇이 어려워지는지 생각해 보세요.
외부 응답을 우리 계약으로 번역합니다
외부 API의 응답은 필드 이름도 의미도 우리 도메인과 다릅니다. 이것이 서비스와 도메인 곳곳에 퍼지면 외부가 바뀔 때 우리 코드 전체가 흔들립니다. 어댑터의 일은 외부의 모양을 우리 계약으로 번역하고 바깥에 가두는 것입니다. 이런 번역 경계를 부패 방지 계층(Anti-Corruption Layer)이라고도 부릅니다.
번역
record ExternalAddressResponse(String zipcode, String sido, String sigungu, String road) { }
private static Address toDomain(ExternalAddressResponse r) {
return new Address(r.zipcode(), r.sido(), r.sigungu(), r.road());
}
ExternalAddressResponse는 패키지 전용 타입이라 어댑터 밖에서는 쓸 수 없습니다. 구조 테스트도 다른 패키지가 이 타입에 의존하지 못하게 막습니다(아래 “의존 방향 규칙” 절의 5번 규칙).- 외부의
sido가 도메인의city가 되는 식으로 이름이 번역됩니다. 외부 API의 필드 이름이 바뀌어도 고칠 곳은 이 어댑터 하나입니다. 이는 Chapter 12에서 내부 객체를 계약으로 변환해 내보내던 것의 반대 방향입니다.
타임아웃은 설정에서 받아 어댑터가 RestClient를 만들 때 적용합니다.
app:
address-api:
base-url: http://localhost:9090
connect-timeout: 1s
read-timeout: 2s
설정은 Chapter 02의 @ConfigurationProperties 방식이고(AddressApiProperties), 타임아웃 값 때문에 생기는 문제는 아래 “3. 타임아웃이 너무 짧으면 평소에도 실패한다” 절에서 봅니다.
404에 빈 JSON이 오면 있는 주소처럼 보였다
처음 구현은 404를 “정상 응답의 한 종류”로 처리하려고, 404일 때 아무것도 하지 않는 핸들러를 달고 본문을 읽었습니다. 없는 우편번호를 조회하는 테스트가 실패했습니다.
expected: <Optional.empty> but was: <Optional[Address[postalCode=null, city=null, district=null, street=null]]>
가짜 외부 서버가 404와 함께 빈 JSON {}를 돌려주도록 만들었는데, 본문 {}가 모든 필드가 null인 ExternalAddressResponse로 읽혔고, 그것이 다시 모든 필드가 null인 Address가 되어 “주소가 있다”는 결과로 나왔습니다. 오류 응답에 빈 본문이나 {}를 붙이는 API는 흔해서, 상태 코드를 먼저 보고 본문을 읽을지 정해야 했습니다. exchange로 바꿨습니다.
.exchange((request, response) -> {
if (response.getStatusCode().value() == 404) {
return Optional.<Address>empty();
}
if (response.getStatusCode().isError()) {
throw new AddressLookupUnavailableException(
"주소 API 오류 응답: " + response.getStatusCode().value(), null);
}
ExternalAddressResponse body = response.bodyTo(ExternalAddressResponse.class);
return Optional.ofNullable(body).map(HttpAddressLookupAdapter::toDomain);
});
주요 코드 설명
exchange는 응답을 직접 받아 상태 코드를 먼저 확인할 수 있게 합니다.- 404는 “없는 우편번호”라는 정상적인 답이므로 빈
Optional로 번역합니다. 본문은 읽지 않습니다. - 그 외 오류 상태(5xx 등)는 외부 장애이므로 약속된 예외
AddressLookupUnavailableException으로 번역합니다. - 정상 응답만 본문을 읽어 도메인으로 번역합니다.
Optional.ofNullable(body)는 본문이 비어 있을 때를 방어합니다.
이 수정 뒤 전체 21건이 통과했습니다. 이 문제는 어댑터를 서비스와 따로 테스트했기 때문에 드러났습니다. 서비스 테스트만 있었다면 놓쳤을 것입니다(아래 “세 층의 테스트” 절).
번역 규칙 한눈에 보기
| 외부 | 도메인 |
|---|---|
zipcode |
postalCode |
sido |
city |
sigungu |
district |
road |
street |
| 404 | Optional.empty() |
| 5xx, 타임아웃, 연결 거부 | AddressLookupUnavailableException |
확인 문제
- 404를 예외가 아닌
Optional.empty()로 번역하는 이유는 무엇인가요? - 외부 API의 필드 이름이 바뀌면 고칠 곳은 어디인가요?
답: 1) “없는 우편번호”는 장애가 아니라 정상적인 답이기 때문입니다. 2) 어댑터 안의 응답 타입과 번역 코드뿐입니다.
직접 해 보기
ExternalAddressResponse의 필드 이름이 바뀌었다고 가정하고 고칠 곳이 몇 군데인지 세어 보세요.- 404 분기를 제거하면 어떤 테스트가 어떻게 실패하는지 예측해 보세요(결과는 아래 “1. 없는 우편번호가 503이 된다” 절에 있습니다).
- 자신이 쓰는 외부 API가 오류 시 빈 본문이나
{}를 주는지 확인해 보세요.
외부 실패를 약속된 예외 하나로 모읍니다
외부 연동은 실패가 코드 밖에서 옵니다. 서버 오류, 느린 응답, 연결 거부는 모두 “외부가 응답하지 못했다”는 같은 사실의 다른 모습입니다. 호출하는 쪽이 이 세 가지를 따로 알 필요는 없습니다. 이 절은 어댑터가 외부 실패 다섯 가지를 진짜 HTTP로 확인하고, 응용과 웹이 어떻게 이어 받는지 봅니다.
실패 다섯 가지
어댑터 테스트는 JDK에 들어 있는 HttpServer로 가짜 외부 서버를 띄워 실제 HTTP로 주고받습니다. 별도 라이브러리가 필요 없습니다.
| 상황 | 가짜 서버의 동작 | 어댑터의 결과 |
|---|---|---|
| 정상 | 200과 JSON | 필드를 번역한 Address |
| 없는 우편번호 | 404와 {} |
빈 Optional |
| 서버 오류 | 500 | AddressLookupUnavailableException (메시지에 500 포함) |
| 느린 응답 | 1.5초 지연, 읽기 타임아웃 0.2초 | AddressLookupUnavailableException, 1.4초 안에 끝남 |
| 연결 거부 | 서버를 닫은 뒤 호출 | AddressLookupUnavailableException |
세 번째부터 다섯 번째는 모두 같은 예외로 모입니다. 호출하는 쪽은 “외부가 응답하지 못했다”는 사실만 알면 되기 때문입니다. 느린 응답 테스트는 1.5초 지연과 0.2초 제한이라는 실제 시간에 의존해서, 느린 환경에서는 여유가 줄어들 수 있습니다. CI에서는 통과했습니다.
웹 계층에서 503으로
@ExceptionHandler(AddressLookupUnavailableException.class)
ResponseEntity<Map<String, String>> unavailable(AddressLookupUnavailableException e) {
return ResponseEntity.status(HttpStatus.SERVICE_UNAVAILABLE)
.body(Map.of("message", "주소 확인 서비스를 잠시 사용할 수 없습니다"));
}
- 503은 “서버가 일시적으로 요청을 처리할 수 없다”는 뜻입니다. 외부 주소 서비스가 안 되는 상황을 우리 API의 이름으로 알립니다. 외부 업체의 오류 상세는 내보내지 않습니다.
- 사용자의 잘못된 입력(없는 우편번호)은 400, 외부 장애는 503으로 구분됩니다. 이 구분이 틀리면 아래 “1. 없는 우편번호가 503이 된다” 절의 증상이 나옵니다.
- 계층별 예외 변환은 앞의 “예외 변환” 절과 같은 방식입니다.
API까지 이어서
API 테스트는 웹, 응용, 진짜 HTTP 어댑터, 가짜 외부 서버를 모두 이어서 확인합니다.
| 요청 | 결과 |
|---|---|
| 정상 가입 | 외부의 sido가 응답의 city로 바뀌어 나옴 |
| 없는 우편번호 | 400 |
| 외부 500 | 503 |
형식이 틀린 우편번호(abc) |
외부를 부르지 않고 400 |
마지막 행처럼 외부를 부르기 전에 형식을 검증하면 불필요한 호출을 줄입니다(Chapter 06의 검증).
정리하면 외부의 500, 타임아웃, 연결 거부는 어댑터에서 AddressLookupUnavailableException이 되고 GlobalExceptionHandler가 503으로 바꿉니다. 외부의 404는 어댑터에서 Optional.empty()가 되고, 서비스가 UnknownPostalCodeException으로 바꿔 400이 됩니다.
따라 하기
외부 주소 서버를 띄우지 않고 앱만 실행했습니다(기본 설정은 http://localhost:9090이라 연결이 거부됩니다).
./gradlew :examples:ch24-port-adapter:bootRun
curl -i -X POST http://localhost:8080/api/members -H 'Content-Type: application/json' \
-d '{"name":"kim","postalCode":"06236"}'
curl -i -X POST http://localhost:8080/api/members -H 'Content-Type: application/json' \
-d '{"name":"kim","postalCode":"abc"}'
HTTP/1.1 503 {"message":"주소 확인 서비스를 잠시 사용할 수 없습니다"}
HTTP/1.1 400 {"timestamp":"...","status":400,"error":"Bad Request","path":"/api/members"}
첫 요청은 연결 거부가 AddressLookupUnavailableException을 거쳐 503이 된 것입니다. 두 번째는 형식 검증에서 걸려 외부를 부르기 전에 400이 되었습니다.
지금의 한계
재시도와 서킷 브레이커는 구현하지 않았습니다. 외부가 느릴 때 요청 스레드가 타임아웃까지 묶이는 문제는 타임아웃 값으로만 완화했습니다. 기본 설정이 가리키는 localhost:9090에 주소 API를 띄운 상태의 bootRun 실행은 하지 않았기 때문에, 정상 가입 흐름은 가짜 서버를 쓰는 테스트로만 확인했습니다.
직접 해 보기
- 가짜 서버의 지연을 0.1초로 줄이면 타임아웃 테스트가 어떻게 달라질지 예측해 보세요.
- 외부 장애를 503 대신 500으로 내보내면 클라이언트에게 어떤 오해를 줄지 적어 보세요.
- 자신의 프로젝트에서 외부 호출이 실패할 때 사용자에게 보이는 응답을 점검해 보세요.
계약을 지키는지 테스트로 확인합니다
Port/Adapter 구조는 인터페이스를 하나 더 만드는 일처럼 보이지만, 실제로 얻는 것은 테스트를 세 층으로 나눌 수 있다는 점입니다. 이 절은 계약을 지키는지 확인하는 세 가지 테스트를 정리합니다: 가짜 Port로 응용을, 진짜 HTTP로 어댑터를, ArchUnit으로 의존 방향을.
세 층의 테스트
| 층 | 방법 | 확인하는 계약 | 건수 |
|---|---|---|---|
| 응용 | 가짜 Port(람다) | 업무 규칙: 없는 우편번호는 예외, 있으면 저장 | 3 |
| 어댑터 | 진짜 HTTP(HttpServer) |
번역과 실패 변환: 정상, 404, 500, 타임아웃, 연결 거부 | 5 |
| API | 웹 + 응용 + 어댑터 + 가짜 서버 | 상태 코드와 응답 모양 | 5 |
| 구조 | ArchUnit | 의존 방향 | 7 |
| 컨텍스트 | @SpringBootTest |
설정이 뜨는지 | 1 |
합계 21건이 모두 통과했습니다. 응용 테스트는 외부 서버가 필요 없어 빠르고, 어댑터 테스트는 번역과 실패 같은 Port 구현의 약속을 진짜 통신으로 확인합니다. 하나만 있으면 다른 층의 문제를 놓칩니다. 예를 들어 앞의 “404에 빈 JSON이 오면 있는 주소처럼 보였다” 절의 문제는 서비스 테스트만으로는 보이지 않았습니다.
의존 방향 규칙
adapter.web -> application.usecase -> application.port <- adapter.address
| adapter.persistence
domain
ArchUnit 규칙은 다섯 가지입니다.
- 도메인은 응용과 어댑터와 스프링을 모릅니다.
- 응용은 어댑터를 모릅니다.
- 응용은
org.springframework.web,org.springframework.http,java.net.http를 쓰지 않습니다. - 어댑터끼리 서로 쓰지 않습니다.
- 외부 응답 타입은 자기 어댑터 안에만 있습니다.
3번이 앞의 “예외 변환” 절에서 말한 “서비스는 HTTP를 모른다”를 규칙으로 고정한 것입니다. 5번이 앞의 “번역” 절의 ExternalAddressResponse 가두기를 고정합니다. ArchUnit 사용법과 위반 메시지 읽는 법은 앞의 “계층 규칙”과 “위반 메시지 읽기” 절과 같습니다.
규칙 자체를 검증하는 위반 예제
응용 계층이 구체 어댑터를 직접 아는 LeakyService 예제를 테스트에 두어, 규칙이 위반을 잡는지(leakyFixtureIsCaughtByTheRule) 확인했습니다. ch24-port-adapter에서는 앞의 계층 규칙 때처럼 임시 클래스를 추가해 보는 실험은 하지 않았고, 위반 예제로 갈음했습니다.
이 구분은 Chapter 19(단위·슬라이스)와 Chapter 20(통합)의 테스트 전략에서 일반화됩니다.
따라 하기
./gradlew :examples:ch24-port-adapter:test
재검증에서 다시 실행해 21건이 모두 통과했습니다.
확인 문제
- 응용 테스트와 어댑터 테스트가 각각 보장하는 것은 무엇인가요?
- 위반 예제(
LeakyService)를 테스트에 두는 이유는 무엇인가요?
답: 1) 응용은 업무 규칙, 어댑터는 외부 응답의 번역과 실패 변환입니다. 2) 규칙이 실제로 위반을 잡는지 확인하기 위해서입니다.
직접 해 보기
- 응용 테스트에서 가짜 Port를 람다로 쓴 줄을 찾아 읽어 보세요.
- 규칙 3에
org.springframework.stereotype도 금지하면 어떤 문제가 생길지 생각해 보세요(@Service). - 새 어댑터를 추가한다면 어느 층의 테스트가 반드시 필요할지 적어 보세요.
구조·연동 오류 읽기
외부 API 연동은 실패가 코드 밖에서 오기 때문에, 오류가 어떤 예외로 올라오는가가 중요합니다. 아래는 이 예제의 어댑터를 한 군데씩 바꿔 얻은 결과입니다. 바꾼 코드는 되돌렸고 저장소에는 올리지 않았습니다.
1. 없는 우편번호가 503이 된다
404를 “없는 주소”라는 정상 답으로 처리하는 분기를 지우면, 404도 외부 API 오류로 취급됩니다. 21건 중 2건이 실패했습니다.
unknownCodeIsEmptyNotAnError()
AddressLookupUnavailableException: 주소 API 오류 응답: 404
unknownPostalCodeIs400()
AssertionError: Status expected:<400> but was:<503>
사용자가 잘못된 우편번호를 입력한 것인데 “외부 서비스를 쓸 수 없다”는 503이 나갑니다. 클라이언트 입력 오류가 서버 장애처럼 보이는 전형적인 모양입니다. 외부 응답의 404, 5xx, 타임아웃을 서로 다른 의미로 번역해야 합니다.
2. 외부 라이브러리 예외가 그대로 새 나온다
어댑터의 catch (RestClientException e)를 지우면 읽기 시간 초과가 Port가 약속한 예외가 아니라 Spring의 예외로 올라옵니다. 2건이 실패했습니다.
slowServerBecomesUnavailableByReadTimeout()
Unexpected exception type thrown, expected: <AddressLookupUnavailableException> but was: <org.springframework.web.client.ResourceAccessException>
Caused by: ResourceAccessException: I/O error on GET request for "http://127.0.0.1:40983/zipcodes/06236": Request cancelled
ResourceAccessException을 서비스가 알게 되면 어댑터를 바꿀 때 서비스도 바뀝니다. 어댑터의 일이 바로 이 번역이므로, 어댑터 밖으로 나가는 예외는 Port가 선언한 것만이어야 합니다. 이 테스트가 느린 서버를 흉내 내서 그 약속을 고정합니다.
3. 타임아웃이 너무 짧으면 평소에도 실패한다
read-timeout: 1ms로 두면 정상 서버에서도 요청이 실패합니다. 2건이 실패했습니다.
registerReturnsAddressTranslatedFromExternalApi()
AssertionError: Status expected:<201> but was:<503>
타임아웃 값은 코드가 아니라 설정이라 이런 실수가 배포 때야 드러나기 쉽습니다. 가입 같은 중요한 기능이 외부 API에 묶여 있을 때 타임아웃을 얼마로 둘지, 실패하면 가입을 막을지는 이 Chapter의 범위 밖입니다.
| 증상 | 가장 먼저 볼 것 |
|---|---|
| 잘못된 입력이 503 | 외부 404/4xx를 어떻게 번역하는지 |
서비스 로그에 ResourceAccessException |
어댑터의 catch와 Port 예외 |
| 정상인데 가끔 503 | connect-timeout, read-timeout |
직접 해 보기
- 위 세 가지 중 하나를 복사본에서 재현하고 Port 계약이 어떻게 깨지는지 설명해 보세요.
- 로그에서 어댑터 밖으로 나온 외부 예외 클래스 이름을 찾는 습관을 적어 보세요.
- 타임아웃을 설정하는 모든 위치를 자신의 프로젝트에서 찾아보세요.
자주 하는 실수 점검표
증상이 보이면 같은 행의 원인부터 확인합니다.
| 영역 | 증상 | 원인 | 해결 |
|---|---|---|---|
| 계층 | 업무 규칙이 컨트롤러로 퍼짐 | 컨트롤러에서 저장소를 직접 호출 | 서비스를 거침(ArchUnit으로 고정) |
| 계층 | 배치·메시지에서 재사용 불가 | 서비스가 HttpServletRequest 같은 웹 타입을 앎 |
서비스는 값(문자열 등)만 받음 |
| 계층 | 내부 필드 노출 | 도메인 객체를 그대로 응답 | 응답 DTO로 변환 |
| 의존 역전 | 테스트에서 저장소를 바꿀 수 없음 | 서비스가 구현 클래스를 new로 생성 |
생성자로 인터페이스를 주입 |
| 의존 역전 | 의존 역전이 아니라 이름만 인터페이스 | 인터페이스를 구현 한 곳에 두고 구현만 노출 | 서비스가 인터페이스만 import |
| 의존 역전 | 테스트는 통과, 실제는 실패 | 가짜 구현이 실제와 달리 동작 | 가짜는 단순하게, 실제 연동은 별도 확인 |
| 예외 변환 | 서비스가 HTTP를 앎 | 서비스에서 ResponseStatusException 던짐 |
업무 예외 + 핸들러 |
| 예외 변환 | 예외가 500으로 노출 | 핸들러가 @RestControllerAdvice 범위 밖 |
핸들러가 스캔되는지 확인 |
| 예외 변환 | 테스트 순서에 따라 실패 | 테스트가 /api/users/1을 가정 |
Location을 따라 조회 |
| ArchUnit | 기본값에서는 failed to check any classes로 실패, 빈 검사를 허용했다면 조용히 통과 |
계층 패키지 이름 오타 | everyLayerHasClasses 같은 존재 단정 테스트 |
| ArchUnit | 규칙이 정말 잡는지 모름 | 위반 예제 없이 규칙만 작성 | 위반 클래스로 규칙 검증 |
| ArchUnit | 위반 메시지가 여러 개 나옴 | 같은 위반을 규칙마다 다시 보고함 | 가장 구체적인 규칙부터 읽기 |
| Port | 외부 변경이 응용까지 전파 | Port의 반환 타입이 외부 응답 클래스 | 도메인 타입 반환 |
| Port | 호출부 NullPointerException |
없음을 null로 표현 |
Optional |
| Port | 호출부가 어떤 예외를 잡을지 모름 | 실패를 계약에 적지 않음 | 인터페이스 주석·예외로 약속 |
| Port | 응용이 어댑터를 알게 됨 | Port를 어댑터 패키지에 둠 | application.port에 둠 |
| 어댑터 번역 | 모든 필드가 null인 주소가 “있는 주소”로 보임 |
404일 때 본문 {}를 그대로 읽음 |
exchange로 상태 코드를 먼저 확인 |
| 어댑터 번역 | 다른 패키지가 외부 모양에 의존 | 외부 응답 클래스를 public으로 공개 |
패키지 전용으로 두고 구조 테스트로 고정 |
| 어댑터 번역 | 환경별 조정 불가 | 타임아웃을 코드에 고정 | @ConfigurationProperties 설정 |
| 계약 테스트 | 404/타임아웃 함정을 놓침 | 어댑터를 가짜 Port 테스트로만 검증 | 진짜 HTTP로 어댑터를 단독 테스트 |
| 계약 테스트 | 느리고 원인 파악이 어려움 | 모든 테스트를 @SpringBootTest로 작성 |
층별로 나눔 |
| 계약 테스트 | 번역·상태 코드 오류를 놓침 | 구조 규칙만 믿고 동작 테스트 생략 | 응용·어댑터·API 테스트 병행 |
용어와 참고 자료
이 절은 Chapter 15 전체에서 나온 용어와 참고한 사이트를 모았습니다. 계약과 ArchUnit의 기본은 Chapter 12 용어 정리를 참고하세요.
계층과 원칙
| 용어 | 설명 |
|---|---|
| 계층(layer) | 하는 일이 같은 클래스를 묶은 단위입니다. 위 계층만 아래 계층을 부릅니다. |
| 단일 책임 | 한 클래스가 한 가지 이유로만 바뀌게 나누는 원칙입니다. |
| 의존 역전(DIP) | 구체 클래스 대신 인터페이스에 의존해 구현을 바꿔 끼울 수 있게 하는 원칙입니다. |
| 가짜 구현(fake) | 테스트에서 실제 협력 객체 대신 끼우는 단순한 구현입니다. |
| 업무 예외 | 업무 의미를 나타내는 예외입니다. HTTP 상태 코드는 web이 정합니다. |
| 위반 예제(fixture) | 규칙이 위반을 잡는지 확인하려고 일부러 만든 잘못된 코드입니다. |
layeredArchitecture |
ArchUnit의 계층 규칙 정의 방식입니다. |
Port와 Adapter
| 용어 | 설명 |
|---|---|
| Port | 응용 계층이 바깥에 바라는 것을 적은 인터페이스입니다. 응용이 소유합니다. |
| Adapter | Port를 실제 기술(HTTP, DB 등)로 구현하고 형식을 번역하는 클래스입니다. |
| 부패 방지 계층(ACL) | 외부 시스템의 모델이 내부 도메인에 새지 않도록 번역하는 경계입니다. |
RestClient.exchange |
응답을 직접 받아 상태 코드를 먼저 확인할 수 있는 호출 방식입니다. |
| 읽기 타임아웃 | 연결 뒤 응답을 기다리는 최대 시간입니다. 넘으면 호출을 포기합니다. |
| 503 | 서버가 일시적으로 요청을 처리할 수 없음을 뜻하는 HTTP 상태 코드입니다. |
| 서킷 브레이커 | 실패가 이어지면 일정 시간 호출을 막는 보호 장치입니다. 이 Chapter에서는 다루지 않았습니다. |
참고 자료
- ArchUnit User Guide:
layeredArchitecture()의 사용법과 규칙 평가 방식을 확인했습니다. - Spring Framework - Dependency Injection: 생성자 주입을 권장하는 이유와 방식을 확인했습니다.
- Hexagonal architecture - Alistair Cockburn: Port와 Adapter라는 이름이 나온 원 설명을 확인했습니다.
- Spring Framework - REST Clients:
RestClient의exchange와 요청 팩토리 설정을 확인했습니다.
직접 해보기
./gradlew :examples:ch23-layered-solid:test와./gradlew :examples:ch24-port-adapter:test를 실행해 14건과 21건이 통과하는지 확인하세요.- 컨트롤러에 저장소를 주입하거나 응용 계층에서 어댑터를 직접 참조하게 바꿔, 어떤 ArchUnit 규칙이 어떤 메시지로 실패하는지 읽은 뒤 되돌리세요.
- 자신이 쓰는 외부 API 하나를 골라 정상, 없음, 실패를 Port 계약으로 적고, 어댑터가 각각을 어떻게 번역할지 표로 정리해 보세요.
이번 장의 정리
이 Chapter에서는 코드를 계층으로 나누고, 외부 시스템 호출을 Port 뒤로 숨겼습니다.
- 계층은 “하는 일”과 “모르는 것”으로 정의하고, 컨트롤러는 요청 검증·서비스 호출·응답 변환만 하며, 위 계층만 아래 계층을 부릅니다.
- 서비스는 인터페이스에만 의존하므로(의존 역전) 가짜 구현으로 스프링 없이 테스트할 수 있습니다.
- 서비스는 업무 예외만 던지고, HTTP 상태 코드(409, 404)는 web의 예외 핸들러가 정합니다.
- 계층 방향은 ArchUnit 규칙으로 고정하고, 위반 예제로 규칙 자체가 위반을 잡는지 확인하며, 위반 메시지는 가장 구체적인 규칙부터 읽습니다.
- Port는 응용 계층이 소유하는 계약이며 정상, 없음(
Optional.empty()), 실패(약속된 예외)를 모두 적습니다. - 어댑터는 외부 응답 타입을 안에 가두고 도메인 타입으로 번역하며, 상태 코드를 먼저 보고 404는 빈 값으로 바꿉니다.
- 5xx, 타임아웃, 연결 거부는
AddressLookupUnavailableException하나로 모아 503으로 응답하고, 없는 우편번호는 400으로 구분합니다. - 응용은 가짜 Port로, 어댑터는 진짜 HTTP로, 의존 방향은 ArchUnit으로 나눠 확인해야 404와 빈 JSON 같은 문제를 놓치지 않습니다.
예제 저장소에서 코드를 직접 실행하고 조건과 실패 상황을 바꾸어 보면 각 선택이 필요한 이유를 더 분명하게 이해할 수 있습니다.
다음 Chapter 16 Composite·Strategy와 모듈 경계에서는 서비스를 조합하는 흐름과 모듈 경계를 다룹니다.