전체 메뉴

테마

Chapter 12

MapStruct와 OpenAPI 계약

MapStruct로 DTO 변환을 생성하고 springdoc OpenAPI 문서, 계약 스냅샷, ArchUnit 테스트로 API 계약과 패키지 경계를 지킵니다.

난이도
중급 심화
예상 학습
180분
Spring Boot 기준
Spring Boot 4.1.1
JDK 기준
JDK 21
최종 검토

전체 24개 Chapter 중 Chapter 12입니다. 예제 코드는 공개 저장소 spring-boot-curriculum의 examples/ch16-mapstruct 폴더에서 확인할 수 있습니다.

Learning goals

오늘 배울 내용

  • 요청·도메인·응답 객체를 분리하고 MapStruct로 변환하기
  • 매핑 누락을 컴파일 오류로 바꾸고 PATCH 갱신 규칙 설정하기
  • springdoc으로 OpenAPI 문서와 Swagger UI 제공하기
  • 운영 Profile에서 API 문서를 끄고 테스트로 확인하기
  • 계약 스냅샷과 ArchUnit으로 호환성과 의존 방향 지키기
  1. 객체 역할 분리
  2. MapStruct 변환
  3. OpenAPI 생성
  4. 계약 스냅샷 비교
  5. 의존 규칙 검증
이 Chapter의 진행 흐름

API가 커지면 세 가지 문제가 생깁니다. 첫째, 요청 객체와 도메인 객체와 응답 객체 사이에서 값을 옮겨 담는 코드가 필드마다 늘어납니다. 둘째, 클라이언트 개발자가 “필수 필드가 뭐죠?“를 계속 묻습니다. 셋째, 누군가 응답 필드를 지우면 그 필드를 쓰던 클라이언트가 배포 후에야 깨집니다.

이 Chapter는 세 문제를 차례로 풉니다. MapStruct로 변환 코드를 컴파일러가 만들게 하고, springdoc으로 코드에서 OpenAPI 문서를 만들고, 외부에 약속한 형식을 계약(Contract)으로 분리해 바뀌면 테스트가 알려 주게 합니다. 이 Chapter의 계약 개념은 이후 Chapter에서 Port, 서비스 호출, 모듈 경계로 계속 이어집니다.

이 Chapter에서 만드는 것

만드는 것 설명
MemberMapper 요청 → 도메인 → 응답 변환, 부분 수정(PATCH) 반영을 MapStruct로 구현
OpenAPI 문서와 Swagger UI 의존성 하나로 /v3/api-docs와 /swagger-ui.html, 운영에서는 끄기
contract / internal / web 패키지 외부 계약과 내부 구현을 패키지로 분리
계약 스냅샷 테스트 현재 문서를 저장본과 비교하고 깨지는 변경을 판정
ArchUnit 테스트 패키지 의존 방향을 테스트로 고정
테스트 ch16: 13건, ch17: 29건, ch18: 24건

준비물과 예제 저장소

실행 확인

세 예제 모두 Docker(JDK 21)에서 test를 실행해 통과를 확인했습니다. 이 Chapter를 정리하면서 다시 실행한 결과는 ch16 13건, ch18 24건 모두 통과(실패 0, 건너뜀 0)입니다.

사전 지식

  • Chapter 05의 DTO 계층, Chapter 06의 검증과 공통 응답.
  • 코드는 examples/ch16-mapstruct, ch17-openapi, ch18-api-contract입니다.

확인 환경

Docker 컨테이너(JDK 21.0.11)에서 실행한 값입니다. Spring Boot 4.1.1, MapStruct 1.6.3, springdoc 3.1.1, ArchUnit 1.4.1입니다. Windows는 확인하지 못했습니다. 브라우저에서 Swagger UI 화면의 렌더링과 “Try it out”은 확인하지 못했고, 주소 응답(302, 200)까지만 확인했습니다.

Contract란 무엇인가

“계약(Contract)“은 Spring의 기능이 아니라 설계 개념입니다. 서로 다른 두 쪽이 코드를 따로 바꿔도 같이 동작하려면, 둘 사이에 “무엇을 주고받는지”를 약속해 둬야 합니다. 그 약속이 계약입니다. 이 과정에서는 계약이 여러 층에 계속 나오므로, 첫 계약인 외부 API 계약으로 개념부터 잡겠습니다.

계약이 없으면 생기는 일

응답 객체 UserView에서 age 필드를 지웠다고 합시다. 서버 코드는 컴파일되고 테스트도 통과합니다. 하지만 age를 읽던 모바일 앱은 배포된 뒤에야 깨집니다. 쓰는 쪽(소비자)이 나와 다른 곳에 있기 때문입니다.

계약은 이 문제를 이렇게 다룹니다.

  1. 소비자가 보는 모양만 따로 이름 붙여 둡니다(contract 패키지).
  2. 그 밖의 구현은 숨깁니다(internal 패키지).
  3. 계약이 바뀌었는지 기계가 확인합니다(테스트).

외부 계약과 내부 구현

ch18의 패키지는 셋으로 나뉩니다.

ch18/
├── contract   # 외부에 약속한 요청/응답 (CreateUserRequest, UserView, ErrorBody, UserStatus)
├── internal   # 저장용 객체, 저장소, 서비스, 매퍼
└── web        # 컨트롤러, 예외 처리

contract의 객체만 클라이언트가 보는 모양입니다. internal의 UserEntity는 내부 메모(internalMemo)와 정지 여부(boolean suspended)를 갖지만 계약에는 나가지 않습니다. 외부에는 ACTIVE, SUSPENDED 값을 가진 열거형 UserStatus로 바뀌어 나갑니다. 그래서 내부 저장 방식이 바뀌어도 계약은 그대로입니다. 이 구조는 아래 “외부 계약을 패키지로 분리하기” 절에서 코드로 봅니다.

앞으로 만날 계약들

이 과정의 코드에서 확인되는 계약은 여섯 가지이고, Chapter 17에서 일곱 번째인 모듈 호출 계약이 더해집니다. 지금 다 이해할 필요는 없고, “이것도 계약이구나” 하고 이어 보는 것이 목적입니다.

계약 어디서 코드 근거
외부 API 계약 이 Chapter contract 패키지, 경로 버전 /api/v1, OpenAPI 저장본 비교
응용이 바라는 계약(Port) Chapter 15 AddressLookupPort, 실패 계약, 외부 응답을 도메인으로 번역
규칙 계약 Chapter 16 DiscountRule.discount() 하나로 단일 규칙과 묶음을 같은 모양으로
협력 서비스 계약 Chapter 16 PaymentService.charge/refund, 실패와 보상도 약속에 포함
모듈 공개 계약 Chapter 16 api 패키지 인터페이스 공개, internal 비공개
이벤트 계약 Chapter 16 OrderPlaced 레코드, 커밋 이후에만 전달
모듈 호출 계약 Chapter 17 다른 업무 모듈의 api로 값 목록을 넘기는 호출

여섯 가지(+모듈 호출)는 모양이 달라 보여도 같은 질문에 답합니다: “이쪽이 약속하는 것은 무엇이고, 저쪽은 무엇을 몰라도 되는가?”

계약을 다룰 때의 원칙 세 가지

원칙 의미 이 Chapter에서
작게 공개 소비자에게 필요한 것만 계약에 둔다 응답에 internalMemo 없음
깨지 않게 변경 지우거나 타입을 바꾸는 변경은 신중히 아래 “계약을 저장하고 비교하기” 절의 ContractDiff
기계로 확인 사람의 기억 대신 테스트가 지킨다 스냅샷, ArchUnit

직접 해 보기

  1. 자신이 쓰는 API 하나를 골라 “소비자는 누구인가, 그 사람이 의존하는 필드는 무엇인가”를 적어 보세요.
  2. 위 표의 계약 중 하나를 골라, 이미 Chapter 05의 DTO 분리에서 비슷한 생각을 만났는지 떠올려 보세요.
  3. 내부 객체를 그대로 응답으로 내보내면 어떤 변경이 어려워지는지 한 문장으로 써 보세요.

같은 회원인데 모양이 세 개다

회원 정보는 하나인데 코드에는 세 가지 모양이 있습니다. 가입할 때 받는 요청, 서버 내부의 도메인 객체, 클라이언트에게 돌려주는 응답입니다. 하나로 합치면 편해 보이지만, 비밀번호 같은 값이 응답에 섞여 나갈 수 있습니다. 이 절은 왜 나누는지를 보고, 나누면 따라오는 “옮겨 담는 코드”의 부담을 확인합니다.

세 모양

객체 용도 들어 있는 것
CreateMemberRequest 가입 요청 이름, 이메일, 나이, 평문 비밀번호
Member 도메인 id, 이름, 이메일, 나이, 비밀번호 해시, 상태, 가입 시각
MemberResponse 응답 id, 이름, 가려진 이메일, 나이, 상태 이름, 가입 날짜

평문 비밀번호는 요청에만 있고 도메인에는 해시로만 들어갑니다. 응답에는 비밀번호 필드가 아예 선언되어 있지 않아서 실수로도 내보낼 수 없습니다. 선언하지 않은 필드는 나갈 수 없다는 점이 DTO를 분리하는 가장 큰 이유입니다. Chapter 05의 DTO 계층 이야기와 같은 원칙입니다.

public record MemberResponse(long id, String name, String maskedEmail, int age, String statusLabel, String joinedDate) { }

이름과 값이 달라지는 곳

응답의 필드는 도메인 필드를 그대로 복사한 것이 아닙니다.

응답 필드 도메인 필드 가공
maskedEmail email 앞 한 글자만 남기고 *로 가림
statusLabel status (열거값) 한글 이름(활동)
joinedDate createdAt 날짜 부분만 문자열로
name, age 같은 이름 가공 없음

이런 가공을 손으로 쓰면 이렇게 됩니다(설명용 코드).

MemberResponse toResponse(Member m) {
    return new MemberResponse(
        m.getId(), m.getName(), maskEmail(m.getEmail()), m.getAge(),
        m.getStatus().label(), m.getCreatedAt().format(ISO_LOCAL_DATE));
}

필드가 여섯 개일 때는 견딜 만합니다. 하지만 필드가 늘고 변환 방향(요청→도메인, 도메인→응답, 부분 수정)이 세 가지가 되면, 필드를 하나 추가할 때마다 고칠 곳이 세 군데입니다. 가장 위험한 것은 빠뜨려도 컴파일이 되고, 값이 null로 조용히 나간다는 점입니다.

직접 해 보기

  1. 위의 toResponse에서 maskEmail(...) 호출을 실수로 m.getEmail()로 바꿨을 때 컴파일이 되는지, 테스트 없이 알아챌 수 있는지 생각해 보세요.
  2. MemberResponse에 nickname을 추가한다면 고칠 곳이 몇 군데인지 세어 보세요.
  3. 응답 객체를 따로 두지 않고 Member를 그대로 반환하면 어떤 값이 나갈지 적어 보세요.

MapStruct 매퍼와 생성된 코드 읽기

변환 코드를 손으로 쓰지 않고, 어떻게 옮길지만 선언하면 컴파일러가 구현을 만들어 주는 라이브러리가 MapStruct입니다. 이 절에서는 매퍼를 선언하고, 컴파일 후 만들어진 코드를 직접 열어 봅니다. 만들어진 코드가 평범한 getter/setter 호출이라는 것을 보면 마법이 아니라는 확신이 생깁니다.

의존성

implementation 'org.mapstruct:mapstruct:1.6.3'
annotationProcessor 'org.mapstruct:mapstruct-processor:1.6.3'

mapstruct는 애노테이션이고, mapstruct-processor는 컴파일할 때 실행되어 구현 클래스를 만드는 도구(애노테이션 프로세서)입니다. 실행 시점에는 필요 없습니다. 둘 다 있어야 하고, 프로세서를 빼면 아래 “3. 구현 클래스가 없다: 어노테이션 프로세서 누락” 절의 오류가 납니다.

매퍼 선언

@Mapper(componentModel = "spring")
public abstract class MemberMapper {

    @Autowired
    protected PasswordHasher passwordHasher;

    /** 요청 -> 도메인. 서버가 정하는 값(id, status, createdAt)은 여기서 채우지 않는다. */
    @Mapping(target = "id", ignore = true)
    @Mapping(target = "passwordHash", source = "password", qualifiedByName = "hash")
    @Mapping(target = "status", constant = "ACTIVE")
    @Mapping(target = "createdAt", ignore = true)
    public abstract Member toDomain(CreateMemberRequest request);

    /** 도메인 -> 응답. 이름이 다르거나 가공이 필요한 필드는 source와 qualifiedByName으로 연결한다. */
    @Mapping(target = "maskedEmail", source = "email", qualifiedByName = "maskEmail")
    @Mapping(target = "statusLabel", source = "status")
    @Mapping(target = "joinedDate", source = "createdAt", qualifiedByName = "date")
    public abstract MemberResponse toResponse(Member member);

    public abstract List<MemberResponse> toResponses(List<Member> members);

    @Named("hash")
    protected String hash(String raw) {
        return passwordHasher.hash(raw);
    }

    @Named("maskEmail")
    protected String maskEmail(String email) {
        int at = email.indexOf('@');
        if (at <= 1) {
            return "*" + email.substring(at);
        }
        return email.charAt(0) + "*".repeat(at - 1) + email.substring(at);
    }
    // statusLabel(MemberStatus), date(LocalDateTime) 등 나머지 도우미는 생략
}

주요 코드 설명

  • @Mapper(componentModel = "spring"): 구현 클래스를 Spring Bean으로 만들게 합니다. 그래서 @Autowired로 다른 Bean(PasswordHasher)을 받을 수 있고, 컨트롤러가 이 매퍼를 주입받습니다(Chapter 03의 Bean 등록).
  • 이름이 같은 필드(name, age)는 아무것도 적지 않아도 자동으로 연결됩니다.
  • ignore = true: 이 대상 필드는 매핑하지 않겠다는 선언입니다. 서버가 정하는 id, createdAt이 대표입니다.
  • constant = "ACTIVE": 고정값을 넣습니다. 가입 직후 상태는 항상 ACTIVE입니다.
  • source: 이름이 다른 소스 필드를 지정합니다. qualifiedByName: 가공이 필요할 때 @Named로 이름 붙인 내 메서드를 가리킵니다.
  • 왜 추상 클래스인가: 인터페이스와 달리 필드(passwordHasher)와 도우미 메서드를 함께 둘 수 있기 때문입니다. 도우미가 필요 없으면 인터페이스로 충분하고, 아래 “외부 계약을 패키지로 분리하기” 절의 UserContractMapper가 그 예입니다.

생성된 코드를 열어 본다

빌드하면 build/generated/sources/annotationProcessor/ 아래에 MemberMapperImpl.java가 생깁니다. 일부입니다.

@Override
public Member toDomain(CreateMemberRequest request) {
    if ( request == null ) {
        return null;
    }

    Member member = new Member();

    member.setPasswordHash( hash( request.password() ) );
    member.setName( request.name() );
    member.setEmail( request.email() );
    if ( request.age() != null ) {
        member.setAge( request.age() );
    }

    member.setStatus( MemberStatus.ACTIVE );

    return member;
}
  • 리플렉션 없이 손으로 쓴 것과 같은 호출입니다. 실행 중에 느려질 이유가 없습니다.
  • Integer age를 int age에 옮길 때 null 검사까지 넣어 주었습니다.
  • 상수 ACTIVE와 직접 만든 hash() 호출이 그대로 들어 있습니다.

매핑이 이상하다고 의심될 때는 이 파일을 열어 보면 됩니다. 테스트도 구현 클래스 이름이 MemberMapperImpl임을 확인합니다.

응답으로 확인

POST /members {"name":"kimberly","email":"kimberly@example.com","age":28,"password":"password-1"}
  -> 201 Location: /members/1 {"id":1,"name":"kimberly","maskedEmail":"k*******@example.com","age":28,"statusLabel":"활동","joinedDate":"2026-10-17"}

응답에 비밀번호와 해시가 없고 이메일은 k*******@example.com으로 가려졌습니다. 테스트는 응답 본문에 password와 원본 이메일 문자열이 없음을 직접 검사합니다. 참고로 예제의 비밀번호 해시는 솔트 없는 SHA-256이라 학습용일 뿐 실제 서비스에서는 쓰면 안 됩니다. Chapter 21 Spring Security에서 BCrypt를 다룹니다.

따라 하기: 생성된 코드를 직접 열어 보기

./gradlew :examples:ch16-mapstruct:compileJava
find examples/ch16-mapstruct/build/generated -name 'MemberMapperImpl.java'

.../annotationProcessor/java/main/com/jqdom/curriculum/ch16/MemberMapperImpl.java가 보이면 성공입니다. 이 파일은 빌드 산출물이므로 저장소에 올리지 않습니다.

직접 해 보기

  1. 프로젝트를 빌드하고 build/generated/sources/annotationProcessor 아래 MemberMapperImpl.java를 열어 toResponse가 어떻게 생겼는지 읽어 보세요.
  2. maskEmail의 규칙을 바꿔(앞 두 글자 노출) 테스트가 어떻게 달라지는지 보세요.
  3. constant = "ACTIVE"를 지우면 status가 어떻게 될지 예측하고, 아래 “매핑이 빠지면 컴파일이 실패하게” 절의 unmappedTargetPolicy와 연결해 보세요.

매핑 누락 막기와 부분 수정

MapStruct를 쓰면 필드를 빠뜨리는 실수가 줄어들 것 같지만, 기본 설정은 경고만 남기고 그 필드를 null로 둡니다. 조용한 실패를 컴파일 오류로 바꾸는 방법과, 기존 객체를 제자리에서 고치는 부분 수정(PATCH) 매핑을 다룹니다.

매핑이 빠지면 컴파일이 실패하게

응답 DTO에 필드를 하나 추가하고 매핑을 깜빡하면 기본은 경고만 남고 그 필드는 조용히 null이 됩니다. 컴파일 옵션으로 오류로 바꿨습니다.

options.compilerArgs += ['-Amapstruct.unmappedTargetPolicy=ERROR']

MemberResponse에 nickname을 추가한 복사본에서 컴파일했더니 이렇게 멈췄습니다.

MemberMapper.java:36: error: Unmapped target property: "nickname".

필드가 늘어났는데 매핑이 없다는 사실이 실행 전에 드러납니다. 손으로 쓴 변환 코드라면 응답에 null로 조용히 나갔을 실수입니다. 경고만 남기는 기본 정책에서 null로 나가는 동작은 직접 재현하지 않았고, MapStruct 문서의 기본 동작 설명에 근거합니다.

부분 수정은 기존 객체를 제자리에서 고친다

PATCH는 보낸 필드만 바꿔야 합니다(Chapter 05의 PUT과 PATCH). @MappingTarget으로 기존 객체를 받고, null인 값은 건드리지 않도록 전략을 지정했습니다.

@BeanMapping(nullValuePropertyMappingStrategy = NullValuePropertyMappingStrategy.IGNORE)
@Mapping(target = "id", ignore = true)
@Mapping(target = "passwordHash", ignore = true)
@Mapping(target = "status", ignore = true)
@Mapping(target = "createdAt", ignore = true)
public abstract void applyPatch(PatchMemberRequest request, @MappingTarget Member member);

주요 코드 설명

  • @MappingTarget Member member: 새 객체를 만들지 않고 이미 있는 객체를 대상으로 채웁니다. 반환 타입이 void인 이유입니다.
  • nullValuePropertyMappingStrategy = IGNORE: 요청의 값이 null이면 대상 필드를 건드리지 않습니다. 생성된 코드는 값이 있는 필드만 if ( request.name() != null )로 감싸 덮어씁니다.
  • ignore 네 줄: PATCH로 바꾸면 안 되는 필드(id, 비밀번호 해시, 상태, 가입 시각)를 막습니다.
  • @MappingTarget은 setter가 있어야 해서 이 예제의 Member는 record가 아니라 가변 클래스입니다.

나이만 보내면 이름, 이메일, 비밀번호 해시, 상태는 그대로 남는 것을 테스트로 확인했습니다.

PATCH /members/1 {"age":41}
  -> 200 {"id":1,"name":"kimberly","maskedEmail":"k*******@example.com","age":41,"statusLabel":"활동","joinedDate":"2026-10-17"}

POST /members {"name":"kim","email":"k@example.com","age":28,"password":"short"}
  -> 400 {"timestamp":"2026-10-17T05:01:57.433Z","status":400,"error":"Bad Request","path":"/members"}

짧은 비밀번호는 Chapter 06의 검증에 걸려 400입니다. 이 Chapter의 한계는 Chapter 05와 같습니다. “보내지 않은 값”과 “명시적인 null”을 이 방식은 구분하지 못합니다.

OS 실행 이 Chapter만 빌드
Linux / macOS ./gradlew :examples:ch16-mapstruct:bootRun ./gradlew :examples:ch16-mapstruct:build
Windows gradlew.bat :examples:ch16-mapstruct:bootRun gradlew.bat :examples:ch16-mapstruct:build

테스트 13건이 모두 통과했습니다.

생성된 PATCH 코드 확인

./gradlew :examples:ch16-mapstruct:test로 빌드한 뒤 MemberMapperImpl.applyPatch를 열면 이렇게 생겼습니다.

public void applyPatch(PatchMemberRequest request, Member member) {
    if ( request == null ) {
        return;
    }

    if ( request.name() != null ) {
        member.setName( request.name() );
    }
    if ( request.email() != null ) {
        member.setEmail( request.email() );
    }
    if ( request.age() != null ) {
        member.setAge( request.age() );
    }
}

ignore로 막은 id, passwordHash, status, createdAt은 코드에 나오지 않고, 요청 값이 null이 아닌 필드만 덮어씁니다. 그래서 앞에서 말한 한계대로 보내지 않은 값과 명시적 null이 모두 “유지”로 처리됩니다.

확인 문제

  1. 요청 {"age":41}을 PATCH로 보내면 name은 어떻게 되나요?
  2. 컴파일 옵션으로 매핑 누락을 오류로 바꾸면 어떤 점이 좋아지나요?

답: 1) 그대로 유지됩니다. 2) 필드를 추가하고 매핑을 빠뜨린 실수가 실행 전에 컴파일 오류로 드러납니다.

직접 해 보기

  1. unmappedTargetPolicy를 WARN으로 바꾸고 nickname 실험을 해서 컴파일이 통과하는 것을 확인하세요(자신의 환경에서).
  2. PATCH로 age를 null로 만들고 싶을 때 이 방식으로 가능한지 생각해 보세요.
  3. Member를 record로 바꾸면 @MappingTarget이 왜 불가능한지 적어 보세요.

MapStruct 오류 메시지 읽기

MapStruct의 오류는 대부분 컴파일 단계에서 납니다. 실행 전에 알려 주는 것이 장점인데, 처음에는 메시지가 낯설 수 있습니다. 아래는 이 예제에서 한 군데씩 같은 실수를 만들어 얻은 메시지입니다. 망가뜨린 코드는 되돌렸고 저장소에는 올리지 않았습니다(MapStruct 1.6.3 기준).

1. Unmapped target property

toDomain에서 @Mapping(target = "createdAt", ignore = true)를 지웠습니다. unmappedTargetPolicy=ERROR 때문에 경고가 아니라 오류입니다.

MemberMapper.java:29: error: Unmapped target property: "createdAt".

도메인에 필드를 추가하고 매핑을 빠뜨렸을 때도 같은 메시지가 납니다.

2. No property named “…” exists in source parameter(s)

source = "email"을 "emial"로 틀렸습니다.

MemberMapper.java:36: error: No property named "emial" exists in source parameter(s). Did you mean "email"?

문자열로 쓰는 이름이지만 컴파일 때 검사되고, 철자 제안(Did you mean)까지 줍니다.

3. 구현 클래스가 없다: 어노테이션 프로세서 누락

build.gradle에서 annotationProcessor 'org.mapstruct:mapstruct-processor'를 빼면 컴파일은 성공하고 실행할 때 실패합니다. 테스트 13건이 모두 실패했습니다.

IllegalStateException: Failed to load ApplicationContext ...
Caused by: UnsatisfiedDependencyException: Error creating bean with name 'memberController' ...

Caused by를 끝까지 내려가면 MemberMapper Bean을 만들지 못한 이유가 나옵니다. 생성되는 MemberMapperImpl이 없고 추상 클래스만 있어서 Bean으로 만들 수 없기 때문입니다. 매핑 코드가 생성되지 않았다면 build/generated/sources/annotationProcessor를 확인하세요. Chapter 01에서 배운 “Caused by는 아래부터 읽는다”가 여기서도 쓰입니다.

4. @Mapper에 componentModel이 없으면

@Mapper(componentModel = "spring")을 @Mapper로 바꾸면 구현은 생성되지만 Spring Bean이 아닙니다. 마찬가지로 13건이 모두 컨텍스트 로딩에서 실패했고, 컨트롤러가 MemberMapper를 주입받을 수 없다는 메시지가 나옵니다.

5. PATCH에서 null이 덮어쓴다

nullValuePropertyMappingStrategy = IGNORE를 지우면 보내지 않은 필드가 null로 덮어씁니다. 13건 중 2건이 실패했습니다.

patchOverwritesOnlyProvidedFields()
AssertionFailedError: expected: <kim> but was: <null>
NullPointerException: Cannot invoke "String.indexOf(int)" because "email" is null

값은 null로 바뀌고 오류는 한참 뒤 email을 쓰는 곳에서 납니다. 부분 수정이 이상하면 null 처리 전략을 먼저 확인합니다.

증상 가장 먼저 볼 것
컴파일 오류 Unmapped target property 대상 필드의 @Mapping
No property named ... source, target 철자
컨텍스트 로딩 실패(구현체 없음) annotationProcessor 의존성
주입할 Bean이 없음 componentModel = "spring"
PATCH 뒤 필드가 null nullValuePropertyMappingStrategy

지금의 한계

여러 소스 객체를 합치는 매핑, 중첩 객체와 컬렉션의 세부 옵션, 사용자 정의 애노테이션, Lombok과의 조합은 다루지 않았습니다. 도메인 객체를 JPA 엔티티나 MyBatis 결과로 쓰는 경우의 매핑도 없고 메모리 저장소만 썼습니다. MapStruct 1.7.0은 Beta라 1.6.3을 썼습니다.

직접 해 보기

  1. 위 다섯 가지 중 두 가지를 직접 재현해 보세요(복사본에서).
  2. 3번에서 build/generated/...를 확인해 파일이 없는 것을 눈으로 보세요.
  3. 다음에 MapStruct 오류를 만나면 “컴파일 오류인가, 실행 오류인가”부터 구분하는 습관을 한 줄로 적어 보세요.

springdoc으로 OpenAPI 문서 만들기

프론트엔드 개발자가 “사용자 생성 API는 어떤 필드가 필수인가요?“라고 묻습니다. 문서를 따로 써서 공유하면 코드가 바뀔 때마다 문서가 낡습니다. 코드에서 문서를 만들면 둘이 어긋날 수 없습니다. Chapter 06의 검증과 공통 응답을 갖춘 사용자 API에서 springdoc으로 OpenAPI 문서를 만들어 봅니다.

의존성 하나

implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:3.1.1'

이 한 줄을 추가하고 기존 코드를 그대로 두었는데 두 주소가 열렸습니다.

주소 용도
/v3/api-docs 기계가 읽는 OpenAPI 문서(JSON)
/swagger-ui.html 같은 문서를 사람이 읽고 직접 호출해 볼 수 있는 화면
GET /swagger-ui.html
HTTP/1.1 302
Location: /swagger-ui/index.html

OpenAPI는 REST API를 설명하는 표준 형식이고, Swagger UI는 그 형식을 보여 주는 도구입니다. 별도 애노테이션이 없어도 경로(/users, /users/{id})와 UserResponse 같은 스키마가 만들어집니다. 브라우저에서 화면이 어떻게 보이는지, “Try it out”이 동작하는지는 이 Chapter에서 확인하지 않았습니다. 주소 응답까지만 확인했습니다.

검증 애노테이션이 스키마에 그대로 반영된다

Chapter 06에서 요청 DTO에 적은 검증 규칙이 문서에도 나타났습니다.

"CreateUserRequest": {
  "type": "object",
  "description": "사용자 생성 요청",
  "properties": {
    "name":  { "type": "string", "maxLength": 20, "minLength": 2, ... },
    "email": { "type": "string", "format": "email", ... },
    "age":   { "type": "integer", "format": "int32", "maximum": 150, "minimum": 0, ... }
  },
  "required": ["age", "email", "name"]
}

실제 문서에서 줄인 형태로, ...는 example, description 등의 생략입니다.

코드의 애노테이션 문서의 표현
@Size(min = 2, max = 20) minLength, maxLength
@Email format: email
@Min, @Max minimum, maximum
@NotBlank, @NotNull required 배열

규칙을 DTO 한 곳에만 적었는데 검증과 문서가 함께 따라옵니다. PATCH 요청 스키마에는 required가 없는 것도 테스트로 확인했습니다. 보낸 필드만 검증하는 규칙이 그대로 문서에 나타난 것입니다.

문서도 테스트할 수 있다

문서가 코드와 일치하는지는 눈으로 보지 않고 테스트로 확인합니다. 예를 들어 MockMvc로 /v3/api-docs를 읽어 jsonPath("$.components.schemas.CreateUserRequest.properties.email.format")가 email인지 검사합니다(Chapter 01의 MockMvc와 jsonPath). 문서에 대한 테스트 10건이 이렇게 문서의 내용을 고정합니다.

따라 하기

./gradlew :examples:ch17-openapi:bootRun
curl -s http://localhost:8080/v3/api-docs | head -c 400
curl -i http://localhost:8080/swagger-ui.html

첫 명령은 {"openapi":"3.1.0",...로 시작하는 JSON, 두 번째는 302와 Location: /swagger-ui/index.html이면 성공입니다. 브라우저 화면은 확인하지 못했으므로 직접 열어 보세요.

직접 해 보기

  1. 의존성을 추가하고 /v3/api-docs를 curl로 받아 CreateUserRequest의 required를 찾아보세요.
  2. DTO의 @Size(max = 20)을 30으로 바꾸고 문서가 따라 바뀌는지 확인하세요.
  3. 자신의 API 중 required가 의도와 다르게 나올 만한 필드를 찾아보세요.

설명 달기, 숨기기, 운영에서 끄기

자동으로 만들어진 문서는 형식은 맞지만 사람이 읽을 설명이 없습니다. 이 절에서는 @Schema, @Operation, @ApiResponses로 설명을 더하고, produces로 응답 형식을 밝히고, @Hidden과 prod Profile로 문서 노출을 통제합니다.

설명과 예시는 애노테이션으로

필드 설명과 예시는 @Schema입니다.

@Schema(description = "사용자 생성 요청")
public record CreateUserRequest(
        @Schema(description = "이름", example = "kim") @NotBlank @Size(min = 2, max = 20) String name,
        @Schema(description = "이메일. example.com 또는 corp.com 도메인만 허용", example = "kim@example.com")
        @NotBlank @Email @AllowedEmailDomain({"example.com", "corp.com"}) String email,
        @Schema(description = "나이", example = "28") @NotNull @Min(0) @Max(150) Integer age) { }

각 엔드포인트에는 @Operation으로 요약을, @ApiResponses로 상태 코드별 의미를 적습니다.

@Operation(summary = "사용자 생성", description = "이메일은 중복될 수 없다")
@ApiResponses({
        @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "201", description = "생성됨. Location 헤더에 새 주소"),
        @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "400", description = "검증 실패 (details에 필드별 사유)",
                content = @Content(schema = @Schema(implementation = ApiResponse.class))),
        @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "409", description = "이메일 중복",
                content = @Content(schema = @Schema(implementation = ApiResponse.class)))
})
@PostMapping
public ResponseEntity<ApiResponse<UserResponse>> create(@Valid @RequestBody CreateUserRequest request) { ... }

주요 코드 설명

  • @Schema(description, example): 문서에 필드 설명과 예시 값을 넣습니다. 예시는 Swagger UI에서 요청 본문의 기본값으로 쓰입니다.
  • @Operation: 엔드포인트 한 줄 요약과 설명입니다.
  • @ApiResponses: 상태 코드별 의미와 응답 스키마입니다. 400, 409처럼 코드만으로 알 수 없는 오류 응답에 집중하세요.
  • 같은 이름 충돌: 이 프로젝트에는 직접 만든 ApiResponse 클래스가 있어서 swagger의 같은 이름 애노테이션은 패키지까지 모두 적었습니다. 모든 메서드에 이렇게 길게 적을 필요는 없습니다.

문서 맨 위의 제목과 버전은 OpenAPI Bean 하나로 정합니다.

@Bean
public OpenAPI openApi() {
    return new OpenAPI().info(new Info()
            .title("Spring Boot Curriculum - Users API")
            .version("v1")
            .description("성공은 success=true와 data, 실패는 success=false와 error로 응답한다."));
}

응답 형식이 */*로 나왔다

처음 문서를 열어 보니 응답의 콘텐츠 형식이 */*였습니다. 컨트롤러가 어떤 형식을 만드는지 선언하지 않아서 문서가 “아무 형식이나”라고 적은 것입니다. 클래스에 produces를 선언해 JSON임을 밝혔습니다.

@RequestMapping(path = "/users", produces = MediaType.APPLICATION_JSON_VALUE)

선언한 뒤 응답 콘텐츠 형식이 application/json 하나가 되었고, 테스트(responseMediaTypeIsDeclaredAsJson)가 */*가 없음을 고정합니다. 화면으로만 보면 이런 부정확함을 놓치기 쉬운데, 문서도 테스트하면 잡힙니다.

숨길 것은 숨기고, 운영에서는 끈다

내부 확인용 /demo/error는 공개 문서에 나오면 안 됩니다. @Hidden을 붙이면 문서에서만 빠지고 동작은 그대로입니다.

@Hidden
@RestController
public class DemoController { ... }

운영에서는 문서 자체를 끕니다. API의 구조를 외부에 알려 줄 필요가 없기 때문입니다. application-prod.yml입니다(Chapter 02의 Profile).

springdoc:
  api-docs:
    enabled: false
  swagger-ui:
    enabled: false

prod로 실행하면 문서 주소는 404이고 실제 API는 정상입니다.

GET /v3/api-docs
  -> 404 {"success":false,"data":null,"error":{"code":"NOT_FOUND","message":"존재하지 않는 경로입니다","details":[]}}

GET /users
  -> 200 {"success":true,"data":[],"error":null}

문서가 없다는 응답도 Chapter 06의 공통 응답 형식으로 나옵니다. 테스트는 문서 10건, prod에서 문서가 꺼지는지 3건, 기존 동작 테스트 16건을 합쳐 29건이 모두 통과했습니다. 문서화가 API 동작을 바꾸지 않았다는 것을 기존 테스트가 확인해 줍니다.

OS 실행 이 Chapter만 빌드
Linux / macOS ./gradlew :examples:ch17-openapi:bootRun ./gradlew :examples:ch17-openapi:build
Windows gradlew.bat :examples:ch17-openapi:bootRun gradlew.bat :examples:ch17-openapi:build

직접 해 보기

  1. 다른 엔드포인트 하나에 @Operation과 @ApiResponses를 추가해 보세요.
  2. produces를 지우고 응답 형식이 어떻게 보이는지 확인하세요.
  3. --spring.profiles.active=prod로 실행해 /swagger-ui.html이 404인지 확인하세요.

OpenAPI 문서가 어긋날 때

API 문서는 코드와 어긋나도 서버가 멀쩡히 떠서 오류가 늦게 드러납니다. 아래는 이 예제에서 한 군데씩 바꿔 얻은 결과입니다. 바꾼 코드는 되돌렸고 저장소에는 올리지 않았습니다.

1. 운영에서 Swagger UI가 열려 있다

application-prod.yml의 springdoc.*.enabled: false를 true로 바꿨습니다. 서버는 정상이고 테스트 두 개만 실패했습니다.

swaggerUiIsNotExposedInProd()
java.lang.AssertionError: Status expected:<404> but was:<200>

오류가 아니라 200이 나왔다는 것이 문제입니다. API 구조가 외부에 그대로 공개됩니다. 운영 Profile에서 문서가 닫혀 있는지는 사람이 확인하기 어렵기 때문에 이 예제처럼 Profile을 켠 테스트로 고정합니다.

2. 의존성이 없다: package io.swagger.v3.oas.models does not exist

springdoc-openapi-starter-webmvc-ui를 빼면 문서 애노테이션과 OpenAPI 클래스를 찾지 못합니다.

OpenApiConfig.java:3: error: package io.swagger.v3.oas.models does not exist
UpdateUserRequest.java:3: error: package io.swagger.v3.oas.annotations.media does not exist

io.swagger.v3 패키지가 없다는 메시지는 springdoc 의존성을 확인하라는 신호입니다.

3. 이전 버전 springdoc을 쓰면

Boot 4.1에 맞춘 3.1.1 대신 2.8.9로 바꿔도 서버가 뜨고 테스트 29건 중 28건이 통과했습니다. 실패한 하나는 문서 내용이었습니다.

validationAnnotationsAppearInTheSchema()
No value at JSON path "$.components.schemas.CreateUserRequest.properties.email.format"

@Email 검증이 문서에 format으로 나타나야 하는데 사라졌습니다. 시작 오류 없이 문서 내용만 달라지는 종류라서, 버전을 올리거나 내릴 때 문서 내용을 검사하는 테스트가 없으면 놓치기 쉽습니다. 어떤 원인으로 달라졌는지는 확인하지 않았습니다.

증상 가장 먼저 볼 것
운영에서 /swagger-ui.html이 200 application-prod.yml의 enabled
package io.swagger.v3... does not exist springdoc 의존성
문서의 필드 설명이나 format이 사라짐 springdoc 버전, 문서 검사 테스트

지금의 한계

Swagger UI 화면의 렌더링과 “Try it out”, 서버 주소·보안 스킴 설정, 코드 생성 도구와의 연계는 다루지 않았습니다.

직접 해 보기

  1. prod 설정을 일부러 true로 바꿔 테스트가 실패하는 것을 확인하세요(복원 필수).
  2. 문서의 한 필드를 골라 “이 필드가 문서에서 사라지면 무엇이 깨지는가”를 적어 보세요.
  3. 라이브러리를 올릴 때 확인할 항목 목록에 “문서 내용 테스트”를 추가하세요.

외부 계약을 패키지로 분리하기

OpenAPI 문서는 지금 코드가 어떻게 생겼는지를 보여 줄 뿐입니다. 누군가 응답의 age를 지우면 문서도 조용히 바뀌고, 그 필드를 쓰던 클라이언트가 배포된 뒤에야 깨집니다. 외부에 약속한 형식은 코드 안의 다른 객체보다 훨씬 무겁게 다뤄야 합니다. 이 절에서는 앞의 “Contract란 무엇인가” 절에서 말한 계약을 실제 패키지 구조로 만듭니다.

세 패키지

ch18/
├── contract   # 외부에 약속한 요청/응답 (CreateUserRequest, UserView, ErrorBody, UserStatus)
├── internal   # 저장용 객체, 저장소, 서비스, 매퍼
└── web        # 컨트롤러, 예외 처리
패키지 누가 보는가 바뀌면
contract 클라이언트(소비자) 클라이언트가 깨질 수 있음, 신중하게
internal 서버 내부만 자유롭게 바꿈
web HTTP 입구 계약과 서비스를 이어 줌

계약 객체

@Schema(description = "사용자 응답")
public record UserView(
        @Schema(description = "식별자", example = "1") long id,
        @Schema(description = "이름", example = "kim") String name,
        @Schema(description = "이메일", example = "kim@example.com") String email,
        @Schema(description = "나이", example = "28") int age,
        @Schema(description = "상태") UserStatus status) { }

오류 응답도 계약입니다. 클라이언트는 code로 분기하고 message는 사람이 읽는 용도입니다.

@Schema(description = "오류 응답. code로 분기하고 message는 사람이 읽는 용도다")
public record ErrorBody(String code, String message, List<FieldIssue> issues) { }

내부 객체는 계약으로 변환되어 나간다

record UserEntity(Long id, String name, String email, int age, String internalMemo, boolean suspended) { }

UserEntity는 public이 아니라서 패키지 밖에서는 볼 수도 없습니다. 내부 메모(internalMemo)는 계약에 없고, 정지 여부 boolean은 계약에서 열거형 UserStatus(ACTIVE, SUSPENDED)가 됩니다. 변환은 MapStruct가 맡습니다(앞의 “MapStruct 매퍼와 생성된 코드 읽기” 절).

/** 내부 객체와 외부 계약 사이의 변환. 이 경계 밖으로는 UserEntity가 나가지 않는다. */
@Mapper(componentModel = "spring")
interface UserContractMapper {

    @Mapping(target = "id", ignore = true)
    @Mapping(target = "internalMemo", ignore = true)
    @Mapping(target = "suspended", constant = "false")
    UserEntity toEntity(CreateUserRequest request);

    @Mapping(target = "status", source = "suspended")
    UserView toView(UserEntity entity);

    List<UserView> toViews(List<UserEntity> entities);

    default UserStatus status(boolean suspended) {
        return suspended ? UserStatus.SUSPENDED : UserStatus.ACTIVE;
    }
}
  • 이 매퍼는 인터페이스이고 default 메서드로 변환 규칙을 하나 가집니다. 도우미 필드가 필요 없으면 인터페이스로 충분합니다.
  • web이 호출하는 입구는 UserApplicationService 하나이고, 받고 돌려주는 타입이 모두 계약 객체입니다.
public UserView create(CreateUserRequest request) { ... }
public UserView get(long id) { ... }
public List<UserView> list() { ... }

내부 저장 방식이 boolean에서 다른 것으로 바뀌어도 UserView는 그대로입니다. 이것이 계약의 효과입니다.

계약의 버전은 경로에

/** 경로의 /api/v1이 계약의 버전이다. 호환되지 않는 변경은 /api/v2로 새로 연다. */
@Tag(name = "Users")
@RestController
@RequestMapping(path = "/api/v1/users", produces = MediaType.APPLICATION_JSON_VALUE)
public class UserController { ... }

호환되지 않는 변경이 필요해지면 /api/v2를 새로 엽니다. 이전 경로 /users는 이 예제에 없어서 404입니다. v1과 v2를 병행 운영하는 방법은 이 Chapter에서 다루지 않았습니다.

실행 결과

POST /api/v1/users {"name":"kim","email":"kim@example.com","age":28}
  -> 201 Location: /api/v1/users/1 {"id":1,"name":"kim","email":"kim@example.com","age":28,"status":"ACTIVE"}

GET /api/v1/users/999
  -> 404 {"code":"USER_NOT_FOUND","message":"사용자를 찾을 수 없습니다. id=999","issues":[]}

POST /api/v1/users {"name":"k","email":"bad","age":-1}
  -> 400 {"code":"VALIDATION_FAILED","message":"요청 값이 올바르지 않습니다","issues":[{"field":"email","reason":"must be a well-formed email address"},{"field":"age","reason":"must be greater than or equal to 0"},{"field":"name","reason":"size must be between 2 and 20"}]}

응답에 internalMemo나 suspended가 없는 것은 테스트가 직접 확인합니다.

따라 하기

./gradlew :examples:ch18-api-contract:bootRun
curl -i -X POST http://localhost:8080/api/v1/users -H 'Content-Type: application/json' \
  -d '{"name":"kim","email":"kim@example.com","age":28}'
curl -i http://localhost:8080/users/1

첫 명령은 201과 Location: /api/v1/users/1, 응답 본문에 internalMemo와 suspended가 없어야 합니다. 두 번째는 이전 경로라 404입니다.

직접 해 보기

  1. UserEntity에 필드 하나(예: lastLoginAt)를 추가하고 계약이 바뀌지 않는 것을 확인하세요.
  2. UserView에 필드를 추가하면 어떤 계약 변경이 생기는지 생각해 보세요(아래 “모든 변경이 문제는 아니다” 절에서 판정).
  3. 자신의 프로젝트에서 엔티티를 그대로 반환하는 곳을 찾아보세요.

계약을 저장하고 비교하기

계약을 지키는 가장 단순한 방법은 현재 OpenAPI 문서를 파일로 저장해 두고, 테스트가 매번 현재 코드가 만드는 문서와 비교하는 것입니다. 달라졌다면 의도한 변경인지 확인하게 됩니다. 이 절에서는 저장본 비교(스냅샷)와, 바뀐 것이 클라이언트를 깨뜨리는지 가려내는 작은 비교기를 다룹니다.

저장본과 비교

JsonNode current = current();   // GET /v3/api-docs
JsonNode saved = normalize(mapper.readTree(Files.readString(SNAPSHOT)));

assertEquals(saved, current, () -> "API 계약이 저장본과 다릅니다. 호환성 확인 결과: "
        + ContractDiff.breakingChanges(saved, current)
        + "\n의도한 변경이면 -Dcontract.update=true 로 저장본을 갱신하세요.");
  • 저장본은 src/test/resources/contract/openapi-v1.json이고 코드와 함께 버전 관리됩니다. 계약 변경이 리뷰에서 diff로 보입니다.
  • required 배열은 실행마다 순서가 다를 수 있어서 정렬한 뒤 비교합니다(normalize).
  • 의도한 변경이면 -Dcontract.update=true로 저장본을 갱신합니다.

Gradle의 -D는 테스트에 전달되지 않는다

처음 -Dcontract.update=true로 돌렸을 때 저장본이 갱신되지 않고 테스트가 실패했습니다. 명령줄의 -D는 Gradle 자신의 JVM에 주는 값이고, 테스트를 실행하는 JVM에는 전달되지 않기 때문입니다. build.gradle에서 넘겨 주도록 했습니다.

tasks.withType(Test).configureEach {
    systemProperty 'contract.update', System.getProperty('contract.update', 'false')
}

모든 변경이 문제는 아니다

문서가 달라졌다고 모두 문제는 아닙니다. 선택 필드를 추가하는 것은 괜찮고, 필드를 지우는 것은 클라이언트를 깨뜨립니다. 이 차이를 판정하는 작은 비교기 ContractDiff를 만들었습니다.

변경 판정
경로나 HTTP 메서드가 사라짐 깨짐
응답 코드가 사라짐 깨짐
응답 속성이 사라짐 깨짐
속성의 타입이 바뀜 깨짐
요청에 필수 속성이 새로 생김 깨짐
선택 속성 추가, 새 경로 추가 호환

각각을 작은 JSON으로 만들어 판정이 맞는지 테스트 8건으로 확인했습니다. 소비자 관점에서 보면 이렇게 설명됩니다.

  • 응답에서 없어지는 것은 깨짐: 소비자가 읽던 것이 사라집니다.
  • 요청에 필수가 새로 생기는 것은 깨짐: 기존 소비자는 그 값을 보내지 않습니다.
  • 응답에 추가되는 것은 호환: 모르는 필드는 무시하면 됩니다(대부분의 클라이언트).

실제로 UserView에서 age를 지운 복사본에서 돌려 보았습니다.

API 계약이 저장본과 다릅니다. 호환성 확인 결과: [삭제된 속성: UserView.age]
의도한 변경이면 -Dcontract.update=true 로 저장본을 갱신하세요.

저장본과 다르다는 사실과 함께 어떤 변경이 깨지는지가 메시지에 나옵니다.

한계

이 비교기는 위 다섯 가지만 보는 학습용입니다. 열거값 삭제, 형식 제약의 강화(최대 길이 감소) 같은 변경은 판정하지 못합니다. 실무에서는 oasdiff 같은 전용 도구가 더 안전하다고 알려져 있으나, 이 Chapter에서 직접 비교해 보지는 않았습니다. 클라이언트가 실제로 쓰는 필드만 검증하는 소비자 주도 계약 테스트(Pact), v1/v2 병행 운영도 다루지 않았습니다. 스냅샷은 MockMvc가 만든 문서 기준이라 servers의 주소가 http://localhost입니다.

따라 하기

./gradlew :examples:ch18-api-contract:test --tests '*ContractDiffTests*'
./gradlew :examples:ch18-api-contract:test --tests '*ContractSnapshotTests*'

앞 명령은 판정 규칙 8건, 뒤 명령은 스냅샷 비교 3건이 대상입니다. ch18-api-contract 전체 24건이 모두 통과하는 것도 다시 확인했습니다.

확인 문제

  1. 응답에서 필드가 사라지는 것과 새 필드가 생기는 것 중 어느 쪽이 깨짐인가요?
  2. 요청에 새 필수 필드가 생기면 왜 깨짐인가요?

답: 1) 사라지는 쪽입니다. 소비자가 읽던 것이 없어지기 때문입니다. 2) 기존 클라이언트는 그 값을 보내지 않기 때문입니다.

직접 해 보기

  1. UserView에서 필드 하나를 지우고 테스트가 어떤 메시지로 실패하는지 확인한 뒤 복원하세요.
  2. UserView에 선택 필드를 추가하면 스냅샷 테스트는 실패하지만 ContractDiff는 “깨짐 없음”으로 판정하는지 예측해 보세요.
  3. 자신의 프로젝트에서 어떤 변경을 “깨짐”으로 분류할지 목록을 만들어 보세요.

ArchUnit으로 의존 방향 고정하기

contract 패키지가 어느 날 internal의 클래스를 참조하기 시작하면 계약과 구현의 구분이 무너집니다. 코드 리뷰에서 놓치기 쉬운 이런 변화를 규칙을 코드로 적어 테스트로 막을 수 있습니다. ArchUnit은 패키지와 클래스 사이의 의존 규칙을 검사하는 라이브러리입니다.

규칙 1: 계약은 구현을 모른다

private static ArchRule contractIsIndependent(String contractPackage, String... forbiddenPackages) {
    return noClasses().that().resideInAPackage(contractPackage)
            .should().dependOnClassesThat().resideInAnyPackage(forbiddenPackages);
}
@Test
void contractDoesNotDependOnInternalOrWeb() {
    contractIsIndependent("..ch18.contract..", "..ch18.internal..", "..ch18.web..").check(production);
}
  • "..ch18.contract..": ..은 “하위 패키지 포함 아무 경로”입니다.
  • production은 ClassFileImporter로 테스트 클래스를 제외한 운영 코드만 읽어 온 것입니다.

계약 패키지에 internal의 서비스를 필드로 가진 클래스(Leak)를 넣은 복사본에서는 이렇게 실패했습니다.

Architecture Violation: Rule 'no classes that reside in a package '..ch18.contract..' should depend on classes that reside in any package ['..ch18.internal..', '..ch18.web..']' was violated (1 times):
Field <...contract.Leak.service> has type <...internal.UserApplicationService>

규칙 2: web은 서비스 입구와 예외만 쓴다

처음에는 “web이 클래스 이름이 Entity로 끝나는 것을 참조하면 안 된다”로 만들었다가 실패했습니다. 8번 위반이 나왔는데 정체는 Spring의 ResponseEntity 클래스였습니다. 이름으로 막는 방식을 버리고, web이 internal에서 쓸 수 있는 것을 허용 목록으로 한정했습니다.

private static ArchRule webDoesNotTouchPersistence(String webPackage) {
    return noClasses().that().resideInAPackage(webPackage)
            .should().dependOnClassesThat(resideInAPackage("..internal..")
                    .and(not(simpleName("UserApplicationService")))
                    .and(not(simpleNameEndingWith("Exception"))));
}

의미는 이렇습니다: web이 internal의 클래스를 참조할 때, 그것이 UserApplicationService도 아니고 이름이 Exception으로 끝나는 것도 아니면 위반입니다. 이름으로 “나쁜 것”을 막기보다 허용되는 것만 열어 두는 쪽이 예상 밖의 오탐이 적습니다.

규칙이 정말 잡는지도 검증한다

규칙이 아무것도 검사하지 않는 상태(패키지 이름 오타 등)는 위험합니다. ArchUnit 기본값은 이런 빈 검사를 실패로 처리하지만, 설정으로 허용할 수도 있습니다.

설정 검사 대상이 하나도 없을 때
기본값(ArchUnit 1.4.1, 이 저장소는 따로 바꾸지 않음) failed to check any classes로 실패합니다
ArchRule.allowEmptyShould(true) 또는 archRule.failOnEmptyShould = false 아무것도 검사하지 않고 통과합니다
클래스 존재를 직접 단정하는 테스트 어느 패키지가 비었는지 알려 주는 구체적인 메시지를 낼 수 있습니다

존재하지 않는 패키지를 고른 noClasses().that().resideInAPackage("no.such.package..") 규칙을 기본값으로 실행하면 이렇게 실패합니다(별도로 실행해 재현).

Rule 'no classes that reside in a package 'no.such.package..' should be interfaces' failed to check any classes. This means either that no classes have been passed to the rule at all, or that no classes passed to the rule matched the `that()` clause. To allow rules being evaluated without checking any classes you can either use `ArchRule.allowEmptyShould(true)` on a single rule or set the configuration property `archRule.failOnEmptyShould = false` to change the behavior globally.

따라서 오타가 있어도 조용히 통과하는 것은 위 설정을 켠 경우입니다. 그래도 존재 단정 테스트를 두면 “이 패키지에는 반드시 클래스가 있어야 한다”는 의도가 코드에 남고, 나중에 누가 빈 검사를 허용하도록 설정을 바꿔도 안전망이 유지됩니다.

그래서 규칙 자체를 시험하는 테스트를 두었습니다.

@Test
void productionCodeHasClassesInEveryLayer() {
    // 규칙이 아무것도 검사하지 않는 상태(패키지 이름 오타 등)를 막는다.
    assertTrue(production.stream().anyMatch(c -> c.getPackageName().endsWith(".contract")));
    assertTrue(production.stream().anyMatch(c -> c.getPackageName().endsWith(".internal")));
    assertTrue(production.stream().anyMatch(c -> c.getPackageName().endsWith(".web")));
}

@Test
void ruleActuallyDetectsAContractThatDependsOnInternal() {
    JavaClasses fixtures = new ClassFileImporter().importPackages(BASE + ".fixture");
    EvaluationResult result = contractIsIndependent("..fixture.contract..", "..fixture.internal..")
            .evaluate(fixtures);
    assertTrue(result.hasViolation());
}
  • fixture 패키지(BadContract, SomeEntity)는 일부러 위반하는 가짜 클래스를 테스트 소스에 둔 것입니다. 규칙이 이를 잡아야 통과합니다.
  • 규칙을 지키는 클래스에는 조용한지(ruleIsQuietForCompliantClasses)도 확인합니다.

ch18-api-contract의 테스트는 24건(contextLoads 1, API 6, 구조 6, ContractDiff 8, 스냅샷 3)이 모두 통과했습니다.

OS 실행 이 Chapter만 빌드
Linux / macOS ./gradlew :examples:ch18-api-contract:bootRun ./gradlew :examples:ch18-api-contract:build
Windows gradlew.bat :examples:ch18-api-contract:bootRun gradlew.bat :examples:ch18-api-contract:build

ArchUnit 1.4.1을 JUnit 연동 모듈 없이 코어만 사용했습니다. 이 방식은 Chapter 15의 Port/Adapter 방향 고정과 Chapter 16의 모듈 경계 검사에서 다시 쓰입니다.

따라 하기

./gradlew :examples:ch18-api-contract:test --tests '*ArchitectureTests*'

구조 테스트 6건이 통과해야 합니다. fixture 패키지의 가짜 위반 클래스는 일부러 규칙을 위반하지만 ruleActuallyDetectsAContractThatDependsOnInternal 테스트가 “위반을 잡았는지”를 확인하므로 통과합니다.

확인 문제

  1. 규칙이 한 번도 실패하지 않는다면 안전한 걸까요?
  2. 이름 기반 차단 대신 허용 목록을 쓰는 이유는 무엇인가요?

답: 1) 아닙니다. 기본값은 빈 검사를 실패로 잡아 주지만, 빈 검사를 허용한 설정이거나 대상이 너무 넓게 잡혀 있으면 아무것도 막지 못하므로 규칙이 정말 위반을 잡는지 직접 확인해야 합니다. 2) 이름이 비슷한 정상 클래스를 오탐하지 않기 위해서입니다.

직접 해 보기

  1. contract 패키지에 internal의 클래스를 참조하는 임시 클래스를 만들어 테스트가 실패하는 것을 확인하고 지우세요.
  2. 허용 목록에 클래스 하나를 더 추가하려면 어떻게 고쳐야 할지 적어 보세요.
  3. 규칙을 검증하는 테스트가 왜 필요한지 자신의 말로 설명해 보세요.

계약 테스트가 실패할 때

계약 테스트는 의도하지 않은 변경을 잡기 위한 장치라서 처음에는 “테스트가 왜 실패하지?” 하는 상황이 생깁니다. 아래는 이 예제를 한 군데씩 바꿔 테스트를 돌린 결과입니다. 바꾼 코드는 되돌렸고 저장소에는 올리지 않았습니다.

1. API 계약이 저장본과 다릅니다

UserView의 age를 int에서 long으로 바꿨습니다. 컴파일도 되고 다른 테스트도 통과했지만, 스냅샷 테스트 하나가 실패했습니다.

currentDocumentMatchesSavedContract()
AssertionFailedError: API 계약이 저장본과 다릅니다. 호환성 확인 결과: []
의도한 변경이면 -Dcontract.update=true 로 저장본을 갱신하세요. ==> expected: <{"openapi":"3.1.0", ...

호환성 확인 결과가 []라는 것은 ContractDiff가 “깨지는 변경”으로 판정한 것이 없다는 뜻이지 문서가 같다는 뜻이 아닙니다. 두 타입은 OpenAPI에서 모두 integer이고 format만 int32에서 int64로 달라지는데, format 변경은 ContractDiff의 다섯 가지 판정 대상에 없으므로 깨짐으로 세지 않습니다. 그래도 문서는 달라졌으므로 저장본 갱신을 요구합니다. 의도한 변경이라면 안내대로 갱신하고 그 diff를 리뷰에서 확인합니다.

2. 입력 검증을 바꿔도 같은 테스트가 실패한다

CreateUserRequest의 @NotBlank를 @Size(max = 100)으로 바꿨을 때도 같은 메시지가 나왔습니다. 필수였던 필드가 선택으로 바뀌면 클라이언트가 영향을 받을 수 있으므로 계약의 일부입니다. 실패 메시지가 똑같기 때문에 어느 필드가 바뀌었는지는 expected와 actual을 직접 비교해야 압니다.

3. 계약 패키지에서 내부 클래스를 참조하려 하면

contract에서 internal.UserEntity를 참조하게 만들었더니 ArchUnit에 닿기 전에 컴파일이 먼저 막았습니다.

UserView.java:12: error: UserEntity is not public in com.jqdom.curriculum.ch18.internal; cannot be accessed from outside package

접근 제어자(public이 아님)만으로 막히는 경우도 있지만, public 클래스를 참조하는 의존성은 ArchUnit 테스트가 막는 대상입니다. 두 장치가 서로 다른 구멍을 지킵니다. ArchUnit이 실제로 위반을 잡는지는 별도의 위반 예제(fixture)로 확인했습니다. 접근 제어자를 public으로 열었을 때 ArchUnit이 막는 장면은 재검증에서 다시 만들지 않았습니다.

증상 가장 먼저 볼 것
API 계약이 저장본과 다릅니다 최근 DTO, 검증 애노테이션 변경, expected와 actual 비교
의도한 변경인데 실패 -Dcontract.update=true로 갱신 후 diff 리뷰
컴파일 오류 is not public 계약 패키지가 내부 클래스를 참조하는지

이 Chapter의 계약은 어디로 이어지나

이어지는 곳 내용
Chapter 15 응용이 바라는 계약(Port), 외부 응답을 우리 계약으로 번역
Chapter 16 규칙, 서비스, 모듈, 이벤트 계약과 계약 지도
Chapter 19 MockMvc/슬라이스 테스트로 API 계약 검증

직접 해 보기

  1. age의 타입을 바꿔 보고 스냅샷 diff에서 format 변경을 눈으로 확인하세요.
  2. 검증 애노테이션을 바꾸는 것이 왜 클라이언트에 영향을 주는지 사례를 하나 들어 보세요.
  3. -Dcontract.update=true로 갱신한 뒤 PR에서 저장본 diff를 누가 확인할지 정해 보세요.

자주 하는 실수와 점검 순서

Chapter 전체에서 만날 수 있는 실수를 증상이 드러나는 시점 순서로 모았습니다. MapStruct 실수는 대부분 “빌드”에서, 문서와 계약 실수는 “실행 결과”나 “테스트”에서 드러납니다. 오류 메시지 원문은 앞의 “MapStruct 오류 메시지 읽기”, “OpenAPI 문서가 어긋날 때”, “계약 테스트가 실패할 때” 절에 있습니다.

시점 증상 원인 해결
빌드 다음 빌드에서 사라짐 생성된 Impl을 직접 수정 매퍼 선언을 고침
빌드 컴파일 오류 도우미 메서드를 @Named 없이 qualifiedByName으로 가리킴 @Named("이름")과 문자열 일치
빌드 누락이 경고로만 남음 unmappedTargetPolicy를 설정 안 함 -Amapstruct.unmappedTargetPolicy=ERROR
빌드 컴파일 오류 같은 이름의 ApiResponse 충돌 패키지를 포함해 적음
기동 컴파일은 되고 실행 때 Bean 생성 실패 annotationProcessor 줄을 빼먹음 의존성 두 줄 모두 추가
실행 결과 @Autowired 필드가 null 매퍼를 new로 만들어 사용 Spring이 주입하는 Bean 사용
실행 결과 보내지 않은 필드가 null로 덮어씀 IGNORE 전략을 빼먹음 nullValuePropertyMappingStrategy = IGNORE
실행 결과 서버는 뜨지만 문서 내용이 일부 빠짐 구버전 springdoc 사용 Boot 4.1에 맞는 3.x 사용
실행 결과 문서의 응답 형식이 */* produces를 선언하지 않음 클래스에 produces = APPLICATION_JSON_VALUE
실행 결과 내부 필드가 응답에 노출 엔티티를 컨트롤러가 그대로 반환 계약 객체로 변환 후 반환
테스트 필드 누락을 놓침 문서가 코드와 같다고 눈으로만 확인 MockMvc로 문서 내용 검사
테스트 -Dcontract.update=true를 줬는데 저장본이 갱신되지 않음 -D 값이 Gradle JVM에만 전달됨 systemProperty로 테스트 JVM에 전달
테스트 실행마다 결과가 다름 required 순서가 달라 비교 실패 정렬 후 비교(normalize)
테스트 저장본이 오래되어 다음 변경 때 혼란 호환 변경이라 스냅샷 갱신이 필요 없다고 판단 호환 변경도 저장본을 갱신
테스트 Spring의 ResponseEntity까지 위반으로 잡힘 이름이 Entity로 끝나는 클래스를 금지 허용 목록 방식으로 변경
테스트 기본값에서는 failed to check any classes로 실패, 빈 검사를 허용하도록 설정했다면 조용히 통과 패키지 이름 오타 각 계층에 클래스가 있는지 검증하는 테스트, allowEmptyShould(true)는 이유 없이 쓰지 않기
테스트 오탐 테스트 클래스까지 규칙에 포함 운영 코드만 읽어 오기
설계·운영 @MappingTarget으로 값을 바꿀 수 없음 Member를 record로 바꿈 가변 클래스 유지
설계·운영 운영에서 문서가 열려 있음 운영 설정을 로컬에서만 확인 prod Profile 테스트로 고정
설계·운영 엔드포인트는 여전히 호출됨 @Hidden을 동작이 막히는 것으로 오해 접근 제어는 별도로 구현
설계·운영 계약과 구현의 경계 붕괴 contract 패키지에 구현 클래스를 둠 internal에 두고 ArchUnit으로 고정
설계·운영 기존 클라이언트가 깨짐 호환되지 않는 변경을 v1에 그대로 적용 /api/v2로 새로 열기
설계·운영 깨지는 변경이 리뷰 없이 반영 저장본을 갱신하고 diff를 확인하지 않음 저장본 diff를 PR에서 확인

용어와 참고 자료

이 절은 이 Chapter에 나온 용어와 참고한 사이트를 모았습니다. 앞 Chapter의 용어(DTO, 검증, Profile)는 Chapter 05와 Chapter 06의 용어 정리를 참고하세요.

참고한 자료

계약(Contract)

용어 설명
계약(Contract) 서로 다른 쪽이 따로 바뀌어도 함께 동작하도록 주고받을 것을 정한 약속입니다. 설계 개념입니다.
소비자 계약을 사용하는 쪽(클라이언트, 다른 모듈)입니다.
호환성 변경 후에도 기존 소비자가 계속 동작하는 성질입니다.
깨지는 변경 기존 소비자를 깨뜨리는 변경(속성 삭제, 타입 변경, 요청의 신규 필수 등)입니다.
스냅샷 테스트 현재 결과를 저장해 두고 매번 비교하는 테스트입니다.
ArchUnit 패키지와 클래스 사이의 의존 규칙을 테스트로 검사하는 라이브러리입니다.
허용 목록 허용되는 것만 열어 두는 방식입니다. 이름으로 금지하는 방식보다 오탐이 적습니다.

변환

용어 설명
도메인 객체 업무 개념을 나타내는 내부 객체입니다. 외부에 보이면 안 되는 값을 가질 수 있습니다.
MapStruct 객체 사이의 변환 코드를 컴파일 때 생성하는 라이브러리입니다.
애노테이션 프로세서 컴파일 중에 실행되어 코드를 생성하는 도구입니다.
componentModel = "spring" 생성된 구현 클래스를 Spring Bean으로 만드는 옵션입니다.
@MappingTarget 새 객체를 만들지 않고 기존 객체에 값을 채워 넣는 대상을 표시합니다.
unmappedTargetPolicy 매핑되지 않은 대상 필드를 어떻게 다룰지(무시, 경고, 오류) 정하는 옵션입니다.
마스킹 민감한 값의 일부를 *로 가리는 처리입니다.

API 명세

용어 설명
OpenAPI REST API를 설명하는 표준 형식입니다.
Swagger UI OpenAPI 문서를 사람이 보고 호출해 볼 수 있게 만든 화면입니다.
springdoc 스프링 코드에서 OpenAPI 문서를 만드는 라이브러리입니다.
@Schema 모델과 필드의 설명·예시를 문서에 더합니다.
@Operation / @ApiResponses 엔드포인트 요약과 상태 코드별 의미를 문서에 더합니다.
@Hidden 문서에서 엔드포인트를 숨깁니다. 동작은 그대로입니다.
produces 컨트롤러가 만드는 응답 콘텐츠 형식을 선언합니다.

이 Chapter의 코드

대상 링크
MapStruct ch16-mapstruct/
OpenAPI ch17-openapi/
API 계약 ch18-api-contract/

예제 코드 파일

본문에서 다룬 파일은 예제 저장소의 다음 위치에 있습니다.

대상 링크
계약 패키지 contract/
도메인 Member.java
응답 DTO MemberResponse.java
매퍼 MemberMapper.java
빌드 설정 build.gradle
매퍼 테스트 MemberMapperTests.java
API 테스트 MemberApiTests.java
문서 테스트 OpenApiDocsTests.java
컨트롤러 UserController.java
OpenAPI 설정 OpenApiConfig.java
prod 설정 application-prod.yml
운영 노출 테스트 OpenApiDisabledInProdTests.java
서비스 입구 UserApplicationService.java
계약 변환 매퍼 UserContractMapper.java
계약 저장본 openapi-v1.json
호환성 판정 ContractDiff.java
스냅샷 테스트 ContractSnapshotTests.java
구조 테스트 ArchitectureTests.java
위반용 가짜 클래스 fixture/

직접 해보기

  1. ./gradlew :examples:ch16-mapstruct:compileJava로 빌드한 뒤 find examples/ch16-mapstruct/build/generated -name 'MemberMapperImpl.java'로 찾은 파일에서 toDomain과 applyPatch를 읽어 보세요. ignore로 막은 필드가 코드에 나오지 않는지 확인합니다.
  2. MemberResponse에 nickname을 추가한 복사본에서 컴파일해 Unmapped target property: "nickname"이 나오는지 보고, unmappedTargetPolicy를 WARN으로 바꾸면 컴파일이 통과하는지 비교해 보세요.
  3. ./gradlew :examples:ch17-openapi:bootRun 뒤 curl -s http://localhost:8080/v3/api-docs | head -c 400과 curl -i http://localhost:8080/swagger-ui.html을 실행하고, --spring.profiles.active=prod로 다시 실행해 문서 주소가 404가 되는지 확인하세요.
  4. UserView에서 age를 지운 복사본에서 ./gradlew :examples:ch18-api-contract:test --tests '*ContractSnapshotTests*'를 실행해 [삭제된 속성: UserView.age]가 나오는지 확인한 뒤 복원하세요.
  5. contract 패키지에 internal의 UserApplicationService를 필드로 가진 임시 클래스를 만들고 ./gradlew :examples:ch18-api-contract:test --tests '*ArchitectureTests*'가 실패하는지 확인한 뒤 지우세요.

이번 장의 정리

이 Chapter에서는 변환 코드, API 문서, 외부 계약이라는 세 문제를 차례로 풀었습니다.

  • 계약은 서로 다른 쪽이 따로 바뀌어도 함께 동작하게 하는 약속입니다. 소비자가 보는 모양과 내부 구현을 나누고, 변경은 테스트가 확인합니다.
  • 요청, 도메인, 응답을 나누면 선언하지 않은 필드는 나갈 수 없습니다. 그 사이의 변환은 MapStruct가 컴파일 때 평범한 getter/setter 코드로 만듭니다.
  • -Amapstruct.unmappedTargetPolicy=ERROR로 매핑 누락을 컴파일 오류로 바꾸고, PATCH는 @MappingTarget과 IGNORE 전략으로 기존 객체를 제자리에서 고칩니다.
  • springdoc 의존성 하나로 /v3/api-docs와 Swagger UI가 생기고, 검증 애노테이션이 스키마에 반영됩니다. produces를 선언하고, @Hidden으로 내부 엔드포인트를 숨기며, prod에서는 문서를 끄고 그 사실을 테스트로 고정합니다.
  • contract, internal, web 패키지로 계약과 구현을 나누고, 호환되지 않는 변경은 /api/v2로 새로 엽니다.
  • OpenAPI 저장본 비교와 ContractDiff로 깨지는 변경을 잡고, ArchUnit 허용 목록 규칙과 그 규칙을 시험하는 테스트로 의존 방향을 고정합니다.
  • MapStruct 오류는 대부분 컴파일 단계에서 나지만, 프로세서나 componentModel이 빠지면 컴파일은 되고 컨텍스트 로딩에서 실패합니다. 문서와 계약의 실수는 서버가 멀쩡히 떠서 드러나지 않으므로 테스트로 고정합니다.

다음 Chapter 13 Thymeleaf 화면과 폼 처리에서는 JSON 대신 HTML을 서버에서 만드는 Thymeleaf를 배웁니다.

FAQ

자주 묻는 질문

DTO와 도메인 객체를 꼭 나누어야 하나요?

작은 예제에서는 같아도 되지만 외부 계약과 내부 모델의 변경 이유가 달라지면 분리하는 편이 안전합니다. MapStruct가 반복 변환 코드를 줄입니다.

MapStruct 구현 코드는 언제 만들어지나요?

애노테이션 프로세서가 컴파일 시점에 생성합니다. 매핑 누락 정책을 ERROR로 두면 빠진 필드를 컴파일 오류로 발견할 수 있습니다.

OpenAPI 문서를 운영에서 공개해야 하나요?

반드시 그렇지는 않습니다. 예제는 prod Profile에서 api-docs와 Swagger UI를 끄고 테스트로 고정합니다.

스냅샷이 달라지면 모두 깨지는 변경인가요?

아닙니다. 차이를 검토해 필수 속성 추가, 경로 삭제처럼 소비자를 깨뜨리는 변경인지 판정해야 합니다.

작성·편집 ToolPado

콘텐츠 유형 Spring Boot 학습 가이드

기술 기준 Spring Boot 4.1.1 · JDK 21

마지막 검토