전체 메뉴

테마

Chapter 23

종합 프로젝트 1: 설계와 백엔드

게시판 종합 프로젝트의 범위와 모듈 규칙, H2·Oracle 스키마 계약을 먼저 고정하고, MyBatis-Plus와 XML Mapper를 나눠 검색·태그 필터·서비스·MapStruct 백엔드를 구현합니다.

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

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

아침 햇살이 드는 서재에서 화이트보드에 모듈 구조를 그리며 설계를 정하는 아빠와 아들 개발자
종합 프로젝트는 코드를 쓰기 전에 범위와 모듈 규칙을 먼저 고정합니다.

Learning goals

오늘 배울 내용

  • 기능·비기능·범위 밖 요구사항으로 프로젝트 범위 정하기
  • ArchUnit으로 모듈 의존 규칙 고정하기
  • H2와 Oracle의 스키마 차이를 한곳에 모으고 계약 테스트 작성하기
  • MyBatis-Plus와 XML Mapper를 작업 모양에 맞게 나눠 쓰기
  • 검색·태그 필터·MapStruct·서비스 오류를 두 DB 시나리오로 확인하기
  1. 요구사항 범위
  2. 모듈 구조 테스트
  3. H2·Oracle 스키마
  4. 검색 SQL
  5. 두 DB 시나리오
  6. 서비스와 오류
이 Chapter의 진행 흐름

지금까지 배운 것을 한 프로젝트에 모아 쓰는 종합 프로젝트입니다. 두 Chapter에 걸쳐 게시판 하나를 만듭니다. 이 Chapter(23)는 코드를 쓰기 전에 못 박아 둔 것들(설계)과 백엔드(검색 SQL, 두 DB)를, 다음 Chapter(Chapter 24)는 화면, 보안, 배포를 다룹니다.

만들 것

“회원이 가입하고, 글을 쓰고, 검색하며, 본인 글(관리자는 모든 글)을 수정·삭제하는 게시판”입니다. 프로젝트는 저장소의 projects/final-project에 있습니다.

이 Chapter에서 다루는 것

단계 내용
설계(f01) 요구사항과 범위 밖, 모듈 경계 구조 테스트, 같은 테이블의 H2/Oracle 두 SQL, API 계약과 검증 규칙
백엔드(f02) MyBatis-Plus와 XML Mapper 나눠 쓰기, 검색 SQL 한 쿼리, DB별 태그 필터, 같은 시나리오를 두 DB에서 실행, MapStruct

저녁 식탁에서 두 노트북에 나온 검색 결과가 조금 다른 이유를 함께 비교하는 아빠와 아들 개발자

직접 실행해 확인한 결과

예제는 projects/final-project이며, 이 Chapter(설계·백엔드 단계)의 임시 인증(X-User-Id)은 최종 상태에서 HTTP Basic으로 교체되어 있습니다(Chapter 24). 아래 호출 결과는 최종 상태의 코드로 실행한 것입니다.

확인 결과
전체 test 88건 중 75건 통과, 13건 SKIPPED(Oracle 테스트: OracleSchemaTests 2, PostSearchOracleTests 11), 실패 0
가입 / 중복 가입 201 / 409 DUPLICATE_USERNAME
검증 오류 400 VALIDATION_FAILED, issues에 필드별 사유
글 등록(인증 없음 / Basic) 401 / 201 + Location
검색 고정 글 먼저, 태그 sq는 0건, sql은 1건, 키워드 %는 100%가 들어간 글 1건, size=0은 400

Oracle에서 11+2건이 통과했다는 기록은 원고 작성 시 확인한 것이고, 재검증에서는 Oracle 컨테이너를 띄우지 않았습니다.

사전 지식

  • Chapter 16의 모듈 경계, Chapter 08~12의 MyBatis·동적 SQL·MyBatis-Plus·MapStruct, Chapter 11의 Oracle JSON.
  • Docker를 쓸 수 있으면 Oracle 테스트도 돌려 볼 수 있습니다(필수는 아닙니다).

확인 환경

Docker 컨테이너(JDK 21.0.11, Gradle 9.8.1), GitHub Actions입니다. 종합 프로젝트 전체 테스트 88건(Oracle 포함, 건너뜀 0건)이 최종 상태에서 모두 통과했다는 것은 CI oracle 잡의 원고 작성 시 기록이고, 재검증 환경에서는 75건 통과·Oracle 13건 SKIPPED였습니다. Oracle은 Free 23 컨테이너 하나에서만 확인했고, 다른 DB는 확인하지 않았습니다. Windows는 확인하지 못했습니다.

예제 코드

대상 링크
프로젝트 final-project/
설계 문서 docs/
H2 스키마 schema-h2.sql
Oracle 스키마 schema-oracle.sql
글 모듈 post/
검색 XML PostMapper.xml
검색 시나리오 PostSearchScenarios.java
Chapter 문서(f01) README.md
Chapter 문서(f02) README.md

범위를 정하고 모듈 규칙을 테스트로 고정하기

종합 프로젝트는 코드부터 쓰지 않고 설계 문서 네 장과 테스트 몇 개로 시작했습니다. 설계를 문서로만 남기면 코드가 쌓이면서 조용히 어긋나기 때문에, 지킬 수 있는 것은 테스트로 만들어 두었습니다.

만들 것을 한 문장으로 줄이면 범위가 보인다

구분 내용
기능 가입, 글 작성·수정·삭제, 글 검색(키워드, 작성자, 태그, 페이징), 작성자별 글 수(관리자)
비기능 HTTP Basic 인증(세션 없음), 비밀번호 bcrypt 해시, H2 기본·Oracle 선택
범위 밖 파일 첨부, 댓글, 이메일 인증, 비밀번호 찾기, 소셜 로그인, 글 임시 저장

범위 밖을 먼저 적어 두면 “이것도 있으면 좋겠다”가 나왔을 때 거절할 근거가 문서에 있습니다. 요구사항 문서는 한 사람이 정리했고 실제 사용자 의견은 받지 않았습니다.

모듈 구조

Chapter 16의 모듈 구조를 그대로 가져왔습니다. user와 post가 각각 공개 입구(api)와 비공개 구현(internal)을 갖고, 요청·응답 타입은 어디에도 의존하지 않는 contract 패키지에 둡니다.

contract/   외부에 약속하는 요청/응답 타입 (어떤 패키지도 참조하지 않는다)
common/     오류 처리 같은 공통 코드
user/       api/ (공개)  internal/ (비공개)
post/       api/ (공개)  internal/ (비공개)
web/        컨트롤러. 모듈의 api만 사용한다
security/   인증·인가 설정

post는 user의 api만 알고, user는 post를 모릅니다. 의존이 한 방향으로만 흐릅니다.

첫 규칙: 계약은 아무것도 참조하지 않는다

문서에 적은 그림은 시간이 지나면 코드와 달라집니다. 그래서 첫 규칙을 ArchUnit으로 만들었습니다.

noClasses().that().resideInAPackage("..finalproject.contract..")
        .should().dependOnClassesThat().resideInAnyPackage(
                "..finalproject.user..", "..finalproject.post..",
                "..finalproject.web..", "..finalproject.common..")
        .check(production);

이 규칙은 나중 단계(Chapter 24까지)에서 코드가 크게 늘어나는 동안 한 번도 고치지 않았고 계속 통과했습니다. 규칙이 하나뿐일 때도 가치가 있었던 이유는, 계약 타입이 서비스 내부 클래스를 가져다 쓰는 순간 바로 테스트가 실패하기 때문입니다. 구조 테스트의 이전 모습은 Chapter 17의 호출 방향 고정에서 봤습니다.

확인 문제

  1. “범위 밖” 목록을 먼저 적는 이유는 무엇인가요?
  2. contract 패키지가 아무 패키지도 참조하지 않게 한 이유는 무엇인가요?

답: 1) 나중에 기능 추가 요청이 왔을 때 거절할 근거가 문서에 남기 때문입니다. 2) 외부에 약속하는 타입이 내부 구현에 묶이지 않게 하기 위해서입니다.

직접 해 보기

  1. 자신의 프로젝트에서 “범위 밖” 목록을 먼저 써 보세요.
  2. 계약 패키지(contract)에 web 클래스를 참조하는 줄을 넣어 규칙이 실패하는지 확인하세요.
  3. 지키고 싶은 의존 방향 하나를 문장으로 쓰고 ArchUnit 규칙으로 옮겨 보세요.

자주 하는 실수

실수 증상 해결
설계 그림만 문서에 둠 시간이 지나면 코드와 달라짐 ArchUnit 규칙으로 고정
user가 post를 참조 모듈 순환 의존을 한 방향으로
범위 밖을 적지 않음 요구사항이 계속 늘어남 범위 밖 목록 작성

같은 테이블, 두 가지 SQL

개발과 테스트는 H2로, 운영은 Oracle로 쓸 수 있게 만들려면 같은 테이블을 DB마다 다른 SQL로 만들어야 합니다. 차이는 한곳에 모아 두는 것이 핵심입니다. (Chapter 11에서 본 H2와 Oracle의 차이를 설계에 반영합니다.)

접두사로 충돌을 피한다

테이블은 두 개(fp_users, fp_posts)입니다. 같은 Oracle 스키마를 쓰는 다른 Chapter의 테이블과 이름이 겹치지 않게 fp_ 접두사를 붙였습니다. 이름이 겹치면 CI에서 모듈끼리 서로의 테이블을 지우는 일이 실제로 있었기 때문입니다(Chapter 22의 ORA-00955 사례).

차이는 fp_posts 한 곳에

컬럼 H2 (schema-h2.sql) Oracle (oracle/schema-oracle.sql)
id BIGINT GENERATED BY DEFAULT AS IDENTITY NUMBER(19) GENERATED BY DEFAULT AS IDENTITY
title VARCHAR(100) VARCHAR2(100)
pinned BOOLEAN NUMBER(1)
meta CLOB JSON

meta가 CLOB인 이유는 Chapter 11에서 확인한 H2의 동작 때문입니다. H2의 JSON 타입에 문자열을 넣으면 따옴표로 한 번 더 감싸 저장해서, 읽어 오면 JSON 객체가 아니라 JSON 문자열이 됩니다. Oracle에서는 진짜 JSON 타입을 써서 나중에 JSON 조건(JSON_EXISTS)으로 검색할 수 있게 했습니다.

정렬에 쓰는 값은 JSON 안에 두지 않는다

글의 태그는 개수가 일정하지 않아 meta 컬럼에 JSON으로 넣었습니다. 반면 “고정 글을 먼저 보여 준다”는 정렬 기준인 pinned는 별도 컬럼입니다. JSON 안의 값을 꺼내 정렬하는 문법은 DB마다 달라서 H2와 Oracle 모두에서 같은 ORDER BY를 쓰려면 별도 컬럼이어야 했습니다. 이 결정을 코드를 쓰기 전에 내렸기 때문에 바꾸는 비용이 거의 없었습니다.

자주 하는 실수

실수 증상 해결
테이블 이름 접두사 없이 같은 스키마 사용 다른 Chapter 테이블과 충돌(ORA-00955) fp_ 접두사
정렬 기준을 JSON 안에 넣음 DB마다 ORDER BY 방식이 달라짐 별도 컬럼
H2에서 meta를 JSON 타입으로 선언 문자열이 따옴표로 감싸져 저장됨(Chapter 11) CLOB

확인 문제

  1. H2의 meta가 CLOB인 이유는 무엇인가요?
  2. pinned가 JSON이 아니라 컬럼인 이유는 무엇인가요?

답: 1) H2의 JSON 컬럼에 문자열을 넣으면 따옴표로 감싼 문자열로 저장되는 함정이 있기 때문입니다. 2) 정렬에 쓰는 값은 DB가 일관되게 다룰 수 있는 컬럼에 두기 위해서입니다.

직접 해 보기

  1. 두 스키마 파일을 열어 차이를 표와 대조해 보세요.
  2. pinned를 meta 안에 넣으면 H2와 Oracle의 ORDER BY가 어떻게 달라질지 예측해 보세요(이 프로젝트는 시도하지 않았습니다).
  3. 자신의 스키마에서 DB마다 다른 부분을 한 파일에 모을 수 있는지 점검하세요.

스키마와 계약을 테스트로 고정하기

스키마와 API 계약도 문서가 아니라 테스트로 고정합니다. 제약 조건(UNIQUE, CHECK, FOREIGN KEY)이 정말 동작하는지, 입력 검증이 정말 걸리는지 확인합니다.

스키마 테스트 (H2 5건, Oracle 2건)

테스트 확인하는 것
usernameMustBeUnique 같은 아이디를 두 번 넣으면 제약 위반
roleIsLimitedToUserAndAdmin USER, ADMIN 외의 역할은 CHECK 제약으로 거부
postNeedsAnExistingAuthor 없는 작성자의 글은 외래 키로 거부
metaIsStoredAsTheJsonTextItWasGiven meta가 넣은 문자열 그대로 저장됨
createdAtIsFilledByTheDatabase 값을 안 주면 DB 기본값이 채움

Oracle 테스트는 ORACLE_URL이 있을 때만 실행하고(없으면 SKIPPED), JSON_EXISTS로 태그를 찾는 쿼리까지 실제 Oracle에서 확인합니다. 제약 조건이 두 DB에서 동일하다는 것은 원고 작성 시 Oracle에서 확인한 기록이며, 재검증에서는 Oracle 컨테이너를 띄우지 못해 다시 실행하지 않았습니다. 재검증에서 확인한 것은 아래 H2 결과입니다.

API 계약은 타입과 검증 규칙으로

요청·응답을 contract 패키지의 record로 정의했습니다. 입력 검증은 어노테이션으로 계약 안에 적습니다.

public record SignupRequest(
        @NotBlank @Size(min = 3, max = 30)
        @Pattern(regexp = "[a-z0-9_]+", message = "영문 소문자, 숫자, 밑줄만 쓸 수 있습니다") String username,
        @NotBlank @Size(min = 8, max = 72) String password,
        @NotBlank @Size(max = 30) String displayName) {
}
  • 정규식 [a-z0-9_]+는 아이디 형식을 한정합니다.
  • 비밀번호의 상한 72는 bcrypt가 72바이트까지만 받기 때문에 정했습니다. 이 숫자에는 문제가 있었고(어노테이션은 글자 수를 센다는 점), 그 이야기는 Chapter 24의 “500 오류의 원인: 글자 수와 바이트 수” 절에서 다룹니다.

검증 규칙도 테스트합니다. 정상 입력, 나쁜 입력(아이디 형식·짧은 비밀번호·빈 이름이 각각 걸리는지), 태그 개수와 길이 제한이 걸리는지 등 4건입니다. 구조 테스트 2건, 컨텍스트 로딩 1건을 합쳐 이 단계의 테스트는 H2 기준 12건, Oracle 환경에서는 14건입니다. 이 12건은 설계 단계 커밋 기준 로컬 실행 값입니다.

따라 하기

./gradlew :projects:final-project:test --tests '*SchemaTests*' --tests '*ContractValidationTests*'

재검증에서 SchemaTests 5건과 ContractValidationTests 5건이 통과했습니다(Oracle 쪽 OracleSchemaTests 2건은 ORACLE_URL이 없어 SKIPPED).

curl -s -X POST http://localhost:8080/api/v1/users -H 'Content-Type: application/json' \
  -d '{"username":"Bad Name","password":"short","displayName":""}'
{"code":"VALIDATION_FAILED","message":"입력값이 올바르지 않습니다","issues":[
 {"field":"username","reason":"영문 소문자, 숫자, 밑줄만 쓸 수 있습니다"},
 {"field":"password","reason":"size must be between 8 and 72"},
 {"field":"displayName","reason":"must not be blank"}]}

자주 하는 실수

실수 증상 해결
스키마 제약을 문서에만 적음 제약이 풀려도 모름 제약 위반을 테스트로 확인
비밀번호 상한을 글자 수로 이해 한글 등 다바이트 문자에서 72바이트 초과 가능 바이트 기준임을 문서화(이 프로젝트의 한계)
정상 입력만 테스트 나쁜 입력이 통과해도 모름 필드마다 나쁜 입력 테스트

확인 문제

  1. 비밀번호 상한이 72인 이유는 무엇인가요?
  2. 스키마 제약을 테스트하는 이유는 무엇인가요?

답: 1) bcrypt가 72바이트까지만 받기 때문입니다. 2) 제약이 지워지거나 DB마다 달라져도 바로 알 수 있게 하기 위해서입니다.

직접 해 보기

  1. SignupRequest에 아이디 대문자를 넣어 어떤 메시지가 나오는지 보세요.
  2. 스키마의 CHECK 제약을 지우고 roleIsLimitedToUserAndAdmin이 실패하는지 확인하세요.
  3. 비밀번호 상한 72가 글자 수 기준이라 생길 수 있는 문제를 예측해 보세요.

구조 테스트가 실패하는 모양

설계 규칙은 어겨도 컴파일되고 서버도 뜹니다. 그래서 구조 테스트가 언제, 어떤 모양으로 실패하는지 알아 두면 좋습니다. 아래는 종합 프로젝트에서 규칙을 일부러 어겨 얻은 메시지입니다(테스트 88건 중 해당 규칙의 1건이 실패했습니다). 바꾼 코드는 되돌렸고 저장소에는 올리지 않았습니다.

1. 모듈이 다른 모듈을 알게 됐다

user 모듈의 공개 입구 UserApi에 post 모듈의 클래스를 참조하는 메서드를 넣었습니다.

Architecture Violation [Priority: MEDIUM] - Rule 'no classes that reside in a package '..finalproject.user..' should depend on classes that reside in a package '..finalproject.post..''
Method <...finalproject.user.api.UserApi.leak()> references class object <...finalproject.post.api.PostNotFoundException> in (UserApi.java:11)

위반한 규칙의 설명이 첫 줄에, 누가 무엇을 참조했는지가 둘째 줄에 나옵니다. 둘째 줄의 UserApi.leak()과 (UserApi.java:11)만 보면 어디를 고칠지 알 수 있습니다. user가 post를 몰라야 한다는 규칙은 의존 방향이 한쪽(post가 user를 아는 쪽)으로만 흐르게 합니다. 실패한 테스트는 userModuleDoesNotKnowPostModule입니다.

2. 웹 계층이 모듈의 내부를 건드렸다

web의 PageController가 post.internal.PostMeta를 참조하게 만들었습니다.

Architecture Violation [Priority: MEDIUM] - Rule 'no classes that reside outside of package '..finalproject.post..' should depend on classes that reside in a package '..finalproject.po...
Static Initializer <...finalproject.web.PageController.<clinit>()> references class object <...finalproject.post.internal.PostMeta> in (PageController.java:22)

internal 패키지의 클래스 대부분은 접근 제어자(패키지 전용)로도 막히지만, 이 예제의 PostMeta처럼 public인 클래스는 컴파일러가 막지 못합니다. 그 빈틈을 ArchUnit이 맡습니다. 실패한 테스트는 modulesAreOnlyReachedThroughTheirApiPackage입니다. 메시지의 Static Initializer, Method, Field, Constructor는 위반한 코드가 어디에 있는지 알려 줍니다.

3. 규칙이 조용히 비어 있지는 않은가

구조 규칙에서 가장 조심할 것은 검사할 클래스가 하나도 없는데 통과하는 경우입니다. 패키지 이름을 잘못 적으면 규칙의 대상이 비게 됩니다. ArchUnit 1.4.1 기본값은 이를 failed to check any classes로 실패시키지만, allowEmptyShould(true) 같은 설정을 켜면 조용히 통과합니다(이 프로젝트는 켜지 않았습니다). 이 프로젝트는 contractHasClasses 같은 테스트로 “검사 대상이 실제로 있다”는 것을 확인하고, 위의 두 위반처럼 규칙을 한 번씩 어겨서 정말 실패하는지도 직접 해 봤습니다. 이 세 번째 위험은 일반적인 주의사항이며, 규칙 대상을 일부러 비워 재현해 보지는 않았습니다. 구조 테스트는 패키지 이름 기준이라 같은 패키지 안의 잘못된 의존은 잡지 못합니다.

증상 가장 먼저 볼 것
Architecture Violation 둘째 줄의 Method/Field/Constructor와 (파일:줄)
public 클래스를 가져다 썼는데 컴파일은 통과 그 클래스가 api 패키지에 있는지
규칙이 통과하는데 믿기 어려움 검사 대상이 비어 있지 않은지, 규칙을 어겨서 실패해 보기

따라 하기

./gradlew :projects:final-project:test --tests '*ArchitectureTests*'

재검증에서 구조 테스트 8건이 통과했습니다(이 Chapter 시점에는 5건이었고 이후 단계에서 규칙이 늘어났습니다).

자주 하는 실수

실수 증상 해결
internal 클래스가 public 컴파일러가 못 막음 ArchUnit 규칙
패키지 이름 오타로 규칙 대상이 비어 있음 기본값에서는 failed to check any classes로 실패, 빈 검사를 허용했다면 아무것도 검사하지 않고 통과 대상 클래스 존재 확인 테스트
위반 메시지의 첫 줄만 읽음 원인 위치를 모름 둘째 줄의 참조 주체 확인

직접 해 보기

  1. 위 두 위반을 직접 만들고 어떤 테스트가 실패하는지 확인하세요.
  2. 패키지 이름을 일부러 틀리게 적은 규칙을 실행해 어떤 메시지로 실패하는지 읽고, 어느 패키지가 비었는지 알려 주는 존재 단정 테스트를 써 보세요.
  3. 같은 패키지 안의 잘못된 의존을 잡으려면 어떤 규칙이 필요할지 생각해 보세요.

도구는 일의 모양으로 고른다

게시판의 글 목록 검색은 겉보기에는 단순합니다. 키워드, 작성자, 태그를 골라 넣으면 맞는 글이 나오는 화면입니다. 그런데 이 한 쿼리 안에 JOIN, 동적 조건, JSON 필터, 페이징이 모두 들어 있습니다. 이 절은 어떤 일은 MyBatis-Plus에 맡기고 어떤 일은 XML로 직접 쓰는지 기준을 봅니다. (동적 SQL, MyBatis-Plus 선택 기준의 연장입니다.)

일에 따라 도구를 나눴다

작업 도구 이유
회원 저장·조회, 글 저장·수정·삭제 MyBatis-Plus BaseMapper 조건이 단순해서 SQL을 쓸 필요가 없습니다
글 목록 검색과 건수 XML Mapper JOIN, 동적 조건, JSON 필터, 페이징이 한 쿼리에 모입니다
작성자별 글 수 XML Mapper LEFT JOIN과 GROUP BY

BaseMapper는 인터페이스 한 줄로 끝납니다.

@Mapper
interface UserMapper extends BaseMapper<UserEntity> {
}

글 쪽은 같은 BaseMapper를 상속하면서 XML에 쓴 쿼리 메서드(search, count, authorStats)를 함께 선언했습니다. 한 매퍼에서 두 방식을 섞어도 충돌하지 않았습니다.

기준을 한 줄로

“SQL을 읽을 필요가 없는 일은 BaseMapper, SQL의 모양 자체가 요구사항인 일은 XML”입니다. 후자는 DB마다 다를 수 있고 튜닝 대상이 되기 때문에 눈에 보이는 SQL로 남겨 둡니다.

자주 하는 실수

실수 증상 해결
단순 CRUD까지 XML로 작성 코드가 늘어남 BaseMapper
복잡한 검색을 BaseMapper 조건 빌더로 억지 구현 읽기 어려움 XML Mapper
한 매퍼에 두 방식을 못 섞는다고 생각 매퍼가 불필요하게 늘어남 한 매퍼에서 함께 사용 가능

확인 문제

  1. 단순 CRUD와, JOIN·동적 조건·DB별 분기는 각각 어느 쪽으로 쓰나요?
  2. 한 매퍼 안에서 두 방식을 함께 써도 되나요?

답: 1) 단순 CRUD는 BaseMapper, JOIN·동적 조건·DB별 분기는 XML Mapper입니다. 2) 됩니다. 한 매퍼에 두 방식을 함께 둘 수 있습니다.

직접 해 보기

  1. PostMapper에서 BaseMapper가 만든 메서드와 XML로 쓴 메서드를 구분해 보세요.
  2. 글 삭제를 XML로 직접 쓰면 무엇이 더 늘어나는지 적어 보세요.
  3. 자신의 프로젝트에서 XML이 필요한 쿼리와 BaseMapper로 충분한 쿼리를 나눠 보세요.

검색 쿼리: 조건 조각과 정렬

목록과 전체 건수를 따로 쿼리하면 조건이 어긋나기 쉽습니다. 목록은 키워드로 거르는데 건수는 거르지 않으면, 화면의 “총 N건”이 틀립니다. 그래서 조건을 한 곳에 두고 두 쿼리가 함께 씁니다.

조건 조각

<sql id="searchConditions">
    <where>
        <if test="c.keywordPattern != null">
            AND (LOWER(p.title) LIKE #{c.keywordPattern} ESCAPE '\'
                 OR LOWER(p.content) LIKE #{c.keywordPattern} ESCAPE '\')
        </if>
        <if test="c.authorId != null">
            AND p.author_id = #{c.authorId}
        </if>
        <if test="c.tag != null">
            <!-- 이어지는 절에서 설명하는 DB별 분기 -->
        </if>
    </where>
</sql>

코드 읽기

  • <where>: 안의 조건이 하나도 없으면 WHERE 자체를 만들지 않고, 첫 조건 앞의 AND를 자동으로 지웁니다(Chapter 09).
  • 조건은 값이 있을 때만 붙는 <if>입니다. 키워드, 작성자, 태그를 조합할 수 있습니다.
  • LOWER(...) LIKE: 대소문자를 무시한 검색입니다. ESCAPE '\'는 아래 “DB별 태그 필터와 LIKE 이스케이프” 절의 특수문자 이스케이프와 짝입니다.
  • #{c.keywordPattern}: 바인드 변수라 SQL 인젝션 걱정이 없습니다.

목록과 건수 쿼리가 <include refid="searchConditions"/>로 같은 조각을 씁니다. 조건을 한 군데만 고치면 둘 다 바뀝니다.

정렬과 페이징

정렬과 페이징은 두 DB가 같은 문법을 받아서 분기하지 않았습니다.

ORDER BY p.pinned DESC, p.created_at DESC, p.id DESC
OFFSET #{c.offset} ROWS FETCH NEXT #{c.size} ROWS ONLY
  • p.pinned DESC: 고정 글 먼저(별도 컬럼으로 둔 이유는 앞의 “같은 테이블, 두 가지 SQL” 절).
  • p.created_at DESC: 최신순.
  • p.id DESC: 같은 시각에 쓴 글의 순서를 고정하는 마지막 기준입니다. 정렬 기준에 동점이 있으면 페이지를 넘길 때 같은 글이 겹치거나 빠질 수 있습니다.
  • OFFSET ... FETCH NEXT는 표준 SQL 문법으로 H2와 Oracle 모두에서 같은 결과를 냈습니다. keyset 방식과 달리 읽는 도중 행이 바뀌면 페이지가 어긋날 수 있는 방식입니다.

한계

키워드 검색은 LIKE '%...%'라 데이터가 많아지면 인덱스를 타지 못하며, 이 규모에서의 성능은 측정하지 않았습니다. 큰 데이터에서는 Oracle Text나 별도 검색 엔진이 필요할 수 있습니다.

따라 하기

글 두 개(첫 글: 고정 아님, 둘째: 고정)를 등록한 뒤 검색합니다.

curl -s 'http://localhost:8080/api/v1/posts'
curl -s -i 'http://localhost:8080/api/v1/posts?size=0'
{"items":[{"id":2,"title":"둘째",...,"pinned":true,...},{"id":1,"title":"첫 글",...,"pinned":false,...}],"page":0,"size":10,"total":2}
HTTP/1.1 400   {"code":"VALIDATION_FAILED",...,"issues":[{"field":"size","reason":"1 이상 50 이하여야 합니다"}]}

나중에 쓴 둘째가 고정 글이라 먼저 나옵니다(pinned DESC가 created_at DESC보다 앞).

자주 하는 실수

실수 증상 해결
목록과 건수 쿼리에 조건을 각각 작성 건수와 목록이 어긋남 <sql> + <include>
정렬에 동점 기준이 없음 같은 시각의 글 순서가 흔들림 마지막 기준 id DESC
size 상한이 없음 한 번에 너무 많은 행 입구에서 1~50 검증

확인 문제

  1. <where> 태그가 해 주는 일은 무엇인가요?
  2. p.id DESC를 마지막에 두는 이유는 무엇인가요?

답: 1) 조건이 없으면 WHERE를 만들지 않고, 첫 조건 앞의 AND를 자동으로 정리합니다. 2) 같은 시각에 쓴 글의 순서를 고정하기 위해서입니다.

직접 해 보기

  1. ORDER BY에서 p.id DESC를 빼고 같은 시각의 글이 있을 때 순서가 흔들리는지 시험해 보세요.
  2. 목록 쿼리의 조건만 바꾸고 건수 쿼리를 두고 보면 어떤 불일치가 생기는지 확인해 보세요.
  3. LIKE '%키워드%'가 인덱스를 못 타는 이유를 설명해 보세요.

DB별 태그 필터와 LIKE 이스케이프

검색 조건 중 태그는 H2와 Oracle에서 SQL 자체가 달라집니다. 그리고 LIKE를 쓰는 곳에서는 사용자가 넣은 %, _가 와일드카드로 해석되는 문제가 있습니다. 이 절은 둘을 다룹니다.

DB별 분기

<if test="c.tag != null">
    <choose>
        <when test="_databaseId == 'oracle'">
            AND JSON_EXISTS(p.meta, '$.tags[*]?(@ == $t)' PASSING #{c.tag} AS "t")
        </when>
        <otherwise>
            AND p.meta LIKE #{c.tagPattern} ESCAPE '\'
        </otherwise>
    </choose>
</if>
  • Oracle의 meta는 진짜 JSON 컬럼이라 JSON_EXISTS로 태그 배열의 원소를 정확히 비교합니다. PASSING으로 값을 바인드하므로 문자열을 이어 붙이지 않습니다.
  • H2의 meta는 CLOB이라 JSON 함수가 없어서, 따옴표까지 포함한 "태그" 모양을 LIKE로 찾습니다.

_databaseId로 나누려면 접속한 DB의 이름을 MyBatis에 알려 주는 설정이 필요합니다.

@Bean
DatabaseIdProvider databaseIdProvider() {
    Properties vendors = new Properties();
    vendors.setProperty("H2", "h2");
    vendors.setProperty("Oracle", "oracle");
    VendorDatabaseIdProvider provider = new VendorDatabaseIdProvider();
    provider.setProperties(vendors);
    return provider;
}

DatabaseIdProvider 설정 없이 _databaseId가 어떻게 동작하는지는 직접 돌려 보지 않았습니다.

LIKE 특수문자 이스케이프

H2의 LIKE 방식에서 태그에 따옴표나 %가 들어 있으면 쿼리가 깨질 수 있습니다. 그래서 서비스에서 태그를 JSON 문자열로 먼저 바꾼 뒤(따옴표는 \"가 됩니다) LIKE의 특수문자를 이스케이프해서 넘깁니다. 검색어도 같은 방식입니다.

private static String escapeLike(String value) {
    return value.replace("\\", "\\\\").replace("%", "\\%").replace("_", "\\_");
}

이 부분은 눈으로 보고 믿지 않고 테스트로 확인했습니다.

입력 기대
키워드 100% 100%가 들어간 글 1건만 (%가 와일드카드로 해석되지 않음)
키워드 %, _ 글자 그대로 들어 있는 글만 각각 1건
태그 sq (실제 태그는 sql) 0건 (정확히 일치해야 함)
태그 a"b, % 0건, 쿼리 오류 없음

모두 쿼리 오류 없이 기대한 건수가 나왔습니다.

한계

H2 쪽의 LIKE 방식은 meta에 태그 외의 값이 들어가면(예: 태그 이름과 같은 문자열을 가진 다른 항목) 오탐할 수 있습니다. 지금은 meta가 태그만 담기 때문에 문제가 없지만 항목을 늘릴 때 고쳐야 합니다. 태그 검색은 한 번에 태그 하나만 받습니다.

따라 하기(H2)

curl -s 'http://localhost:8080/api/v1/posts?tag=sq'
curl -s 'http://localhost:8080/api/v1/posts?tag=sql'
curl -s 'http://localhost:8080/api/v1/posts?keyword=%25'
{"items":[],"page":0,"size":10,"total":0}                                  (tag=sq: 정확히 일치해야 함)
{"items":[{"id":1,"title":"첫 글",...,"tags":["sql","java"],...}],...,"total":1}
{"items":[{"id":1,"title":"첫 글",...}],...,"total":1}                      (keyword=%: 본문에 100%가 있는 글만)

keyword=%25는 URL 인코딩된 %입니다. 이스케이프가 없었다면 %가 와일드카드로 해석되어 모든 글이 나왔을 것입니다(재검증에서는 이스케이프를 뺀 상태를 직접 시험하지 않았습니다).

자주 하는 실수

실수 증상 해결
LIKE 패턴에 사용자 입력을 그대로 사용 %, _가 와일드카드로 동작 escapeLike + ESCAPE '\'
DatabaseIdProvider 설정 누락 _databaseId가 비어 분기 불가 벤더 이름을 매핑하는 Bean 등록
H2의 LIKE 방식을 JSON 전체 일치로 오해 meta에 태그 외 값이 있으면 오탐 가능 이 프로젝트는 meta가 태그만 담는 전제

확인 문제

  1. 태그 sq가 sql 글을 찾지 못하는 이유는 무엇인가요?
  2. Oracle에서는 태그를 어떻게 찾나요?

답: 1) H2는 따옴표까지 포함한 "sq" 모양을 찾기 때문에 "sql"과 일치하지 않습니다. 2) JSON_EXISTS로 $.tags 배열의 원소를 비교합니다.

직접 해 보기

  1. escapeLike를 빼고 키워드 %로 검색해 모든 글이 나오는지 확인하세요.
  2. 태그 sq가 sql 글을 찾지 못하는 이유를 H2의 LIKE 패턴으로 설명해 보세요.
  3. Oracle의 JSON_EXISTS 쿼리를 SQL 클라이언트에서 직접 실행해 보세요.

같은 시나리오를 두 DB에서 돌린다

SQL이 DB마다 다르면 “H2에서 통과했다”가 “Oracle에서도 통과한다”를 보장하지 않습니다. 이 프로젝트는 검색 시나리오를 한 번 쓰고 H2와 Oracle에서 모두 실행하게 만들었습니다.

구조

@SpringBootTest
@Transactional
abstract class PostSearchScenarios { /* 11개 시나리오 */ }

class PostSearchH2Tests extends PostSearchScenarios { }

@EnabledIfEnvironmentVariable(named = "ORACLE_URL", matches = ".+")
@ActiveProfiles("oracle")
class PostSearchOracleTests extends PostSearchScenarios {
    @Override
    void prepareSchema() throws Exception { /* 테이블을 새로 만든다 */ }
}
  • 시나리오는 추상 클래스에 한 번만 쓰고, H2용 하위 클래스는 비워 둡니다.
  • Oracle용 하위 클래스는 ORACLE_URL 환경 변수가 있을 때만 실행됩니다. 없으면 건너뜁니다(SKIPPED, 통과가 아닙니다).
  • @Transactional로 각 시나리오가 롤백되어 서로 독립입니다.

시나리오 11개

조건 없이 전체(고정 글이 먼저), 키워드(대소문자 무시), 작성자, 태그, 조건 조합, 페이징(총 건수 유지), 태그 목록 확인, 잘못된 페이징 거부, 작성자별 통계(글이 없는 작성자도 0건으로 나옴) 등입니다. 원고 작성 시에는 같은 11건이 H2와 Oracle에서 모두 통과했습니다. 재검증에서는 H2 11건만 통과했고 Oracle 11건은 SKIPPED였습니다(아래 “따라 하기”의 표).

같은 시나리오 구조의 가치

SQL을 고칠 때마다 두 곳을 한 번에 확인할 수 있습니다. 기능을 만드는 시간보다 “두 DB에서 같은 결과”를 확인하는 시간이 더 걸렸지만, 이 구조를 먼저 만들어 두니 이후가 빨랐습니다.

따라 하기

./gradlew :projects:final-project:test --tests '*PostSearchH2Tests*' --tests '*PostSearchOracleTests*'

ORACLE_URL이 없는 재검증 환경에서는 H2 시나리오 11건이 통과하고 Oracle 시나리오 11건은 SKIPPED입니다. SKIPPED는 통과가 아닙니다.

환경 재검증 원고 작성 시 기록
H2 11건 통과 11건 통과
Oracle 11건 SKIPPED(OracleSchemaTests 2건도 SKIPPED) ORACLE_URL 지정 시 11 + 2건 통과

자주 하는 실수

실수 증상 해결
H2만 통과하고 Oracle은 확인하지 않음 운영 DB에서 SQL 실패 같은 시나리오를 두 DB에서 실행
SKIPPED를 통과로 집계 실행되지 않은 경로를 검증된 것으로 오해 CI에서 PASSED 건수 확인
시나리오를 DB마다 복사 한쪽만 수정되어 어긋남 추상 클래스에 한 번만 작성

확인 문제

  1. 같은 시나리오를 두 DB에서 돌리는 구조는 클래스를 어떻게 나누나요?
  2. Oracle 환경이 없는 CI에서 테스트 통과를 확인하려면 무엇을 세어야 하나요?

답: 1) 시나리오는 추상 클래스에 한 번 쓰고, 하위 클래스가 DB만 바꿉니다. 2) Oracle 환경이 없으면 건너뛰므로 PASSED 건수를 직접 세어야 합니다.

직접 해 보기

  1. ORACLE_URL 없이 실행해 Oracle 테스트가 SKIPPED로 나오는지 확인하세요.
  2. 시나리오를 하나 추가하고 하위 클래스를 고치지 않아도 양쪽에 적용되는지 확인하세요.
  3. 한 DB에서만 통과하는 SQL을 일부러 만들어 이 구조가 잡아 내는지 보세요.

변환과 부딪친 문제

저장하는 객체와 내보내는 객체는 다릅니다. 저장용 객체(UserEntity)를 그대로 응답으로 쓰면 비밀번호 해시가 나갈 수 있습니다. 이 절은 MapStruct 설정과 개발 중에 실제로 부딪친 세 가지 문제를 정리합니다.

누락을 컴파일 오류로

대상에 채우지 못하는 필드가 있으면 컴파일이 실패하도록 설정했습니다.

tasks.withType(JavaCompile).configureEach {
    options.compilerArgs += ['-Amapstruct.unmappedTargetPolicy=ERROR']
}

Chapter 12에서 본 정책입니다. 새 필드를 추가하고 매핑을 잊으면 빌드가 막아 줍니다.

부딪친 문제 세 가지

증상 원인 해결
NoSuchMethodException: PostRow.<init>(Long, String, ..., Boolean, ...) resultMap 생성자 인자의 javaType="long"이 박싱 타입 Long으로 해석돼, 기본 타입을 받는 record 생성자를 못 찾음 javaType="_long", "_boolean"
MapStruct The type of parameter "entity" has no property named "id" 엔티티의 getter가 package-private getter와 setter를 public으로
(예방) meta 조회 시 JSON 문자열이 객체로 안 바뀜 MyBatis-Plus는 결과 매핑에 TypeHandler를 기본 적용하지 않음 @TableName(autoResultMap = true)

앞의 둘은 실제로 겪고 해결했습니다. 세 번째는 이 프로젝트에서 실제로 실패해 보지 않았고, 처음부터 켜 둔 설정입니다. 끈 상태에서의 실패는 재현하지 않았습니다.

읽는 법

  • NoSuchMethodException의 생성자 인자 목록에 Long(대문자)이 보이면 박싱 타입을 찾고 있다는 뜻입니다. record가 long을 받는다면 MyBatis의 _long(기본 타입)을 써야 합니다.
  • MapStruct의 has no property named "id"는 접근자를 못 찾는다는 뜻이고, getter가 public이 아닌 경우를 먼저 의심합니다.
  • MyBatis-Plus의 meta 변환은 TypeHandler가 결과 매핑에도 적용되어야 동작합니다.

확인 문제

  1. 변환 누락을 런타임이 아니라 컴파일 시점에 알리려고 이 프로젝트는 무엇을 쓰나요?
  2. 이 절에서 “확인하지 않은 것”을 대하는 원칙은 무엇인가요?

답: 1) MapStruct로 변환하고 누락을 컴파일 오류로 만듭니다. 2) 실패해 보지 않았거나 확인하지 않은 설정은 확인하지 않았다고 밝힙니다.

직접 해 보기

  1. unmappedTargetPolicy=ERROR를 빼고 필드를 하나 누락시켜 보세요. 오류가 나는지 확인하세요.
  2. javaType="long"으로 되돌려 첫 번째 오류를 재현해 보세요.
  3. autoResultMap = true를 빼면 어떻게 되는지 직접 시험해 보세요(이 프로젝트는 하지 않았습니다).

서비스와 임시 인증, 오류 응답

검색 SQL이 준비되었으니 그 위의 서비스 계층을 봅니다. 이 단계의 서비스는 HTTP도 보안 설정도 모르고, “누가 요청했는가”(Actor)만 받습니다. 인증은 임시로 처리하고, Chapter 24에서 실제 방식으로 바꿉니다.

모듈 사이의 호출

post 모듈은 글을 쓸 때 user의 공개 입구(UserApi)로 작성자를 확인할 뿐 user의 구현을 모릅니다(앞의 “범위를 정하고 모듈 규칙을 테스트로 고정하기” 절에서 정한 구조). 서비스는 Actor만 받습니다.

public PostView update(Actor actor, long id, PostRequest request) {
    PostEntity entity = find(id);
    requireOwnerOrAdmin(actor, entity);
    ...
}
  • requireOwnerOrAdmin: 본인 글이거나 관리자인지 서비스에서 판단합니다. 이 규칙은 Chapter 21의 데이터별 권한과 같은 종류인데, 이 프로젝트는 메서드 보안 대신 서비스 코드에서 직접 판단합니다.
  • 서비스가 HTTP를 모르므로 서비스 테스트에서 요청을 만들 필요가 없습니다.

임시 인증은 한곳에

이 단계의 인증은 X-User-Id 헤더로 임시로 처리했습니다. 누구나 위조할 수 있는 방식이라 개발용입니다. 컨트롤러가 이 헤더를 직접 읽지 않고 CurrentActor 한 클래스만 거치게 해서, 나중에 바꿀 곳을 하나로 모았습니다. Chapter 24에서 HTTP Basic으로 바꿀 때 컨트롤러는 그대로 두고 이 클래스만 고칠 수 있었는지가 설계의 시험이었습니다.

가입의 중복 처리

가입은 아이디 중복을 먼저 확인하고, 확인과 INSERT 사이에 같은 아이디가 들어오는 경우는 UNIQUE 제약 위반(DuplicateKeyException)을 잡아 같은 오류(409)로 돌려줍니다. 확인만 하면 동시 가입에서 빈틈이 생기고, 제약만 믿으면 친절한 메시지를 만들기 어렵습니다. 두 방어를 함께 둡니다(통합 테스트에서 본 409와 이어집니다).

오류 응답은 한 곳에서

오류 응답은 @RestControllerAdvice 한 곳에서 모두 같은 모양(code, message, issues)으로 만듭니다. 호출하는 쪽(화면)이 오류마다 다른 모양을 처리하지 않아도 됩니다.

이 단계의 테스트

영역 건수
회원 API (가입, 비밀번호 해시, 중복, 검증 오류, 잘못된 JSON, 임시 로그인) 7
글 API (권한, 검증, 404, 잘못된 질의 매개변수, 통계 권한) 10
검색 시나리오 H2 11 + Oracle 11
JSON TypeHandler (저장 형태, null 태그, 수정) 3
구조 테스트(누적) 5

비밀번호 해시 테스트는 저장된 값이 평문 비밀번호와 다르고 {bcrypt}로 시작하며(Chapter 21), PasswordEncoder가 맞는 비밀번호만 통과시키는 것까지 확인합니다.

따라 하기(최종 상태)

curl -i -X POST http://localhost:8080/api/v1/users -H 'Content-Type: application/json' \
  -d '{"username":"alice","password":"password-1","displayName":"앨리스"}'

같은 요청을 두 번 보냅니다.

HTTP/1.1 201   {"id":1,"username":"alice","displayName":"앨리스","role":"USER"}
HTTP/1.1 409   {"code":"DUPLICATE_USERNAME","message":"이미 사용 중인 아이디입니다: alice","issues":[]}

모든 오류가 code, message, issues 한 가지 모양입니다. 글 등록 요청에 인증이 없으면 401이고, -u alice:password-1(HTTP Basic)을 붙이면 201과 Location: /api/v1/posts/1이 나옵니다.

자주 하는 실수

실수 증상 해결
서비스가 HttpServletRequest를 앎 서비스 단위 테스트가 어려움 Actor 같은 값만 받음
가입 중복을 확인만 하고 UNIQUE 제약이 없음 동시 가입 시 중복 확인 + UNIQUE 제약
오류 응답이 컨트롤러마다 다름 화면이 처리하기 어려움 @RestControllerAdvice 한 곳
임시 인증(X-User-Id)을 운영에 사용 누구나 위조 가능 이후 단계에서 HTTP Basic 등으로 교체

확인 문제

  1. 서비스가 Actor만 받으면 무엇이 좋아지나요?
  2. 가입 중복을 확인과 UNIQUE 제약으로 이중으로 막는 이유는 무엇인가요?

답: 1) HTTP와 보안 설정을 몰라도 되어 서비스 테스트가 단순해집니다. 2) 확인과 INSERT 사이에 같은 아이디가 들어오는 경우를 제약이 막아 주기 때문입니다.

직접 해 보기

  1. X-User-Id를 다른 사용자의 값으로 보내면 무슨 일이 생기는지 확인해 보세요(위조 가능성).
  2. 동시에 같은 아이디로 가입하는 두 요청을 보내 하나만 성공하는지 확인해 보세요(이 프로젝트는 동시성 테스트를 하지 않았습니다).
  3. 오류 응답 모양(code, message, issues)을 화면에서 어떻게 쓸지 설계해 보세요.

한계와 다음 단계

Chapter를 마무리하며 만든 것과 확인하지 않은 것을 정리합니다.

만든 것

  • 요구사항 3분류와 모듈 구조, 구조 테스트(ArchUnit).
  • fp_users, fp_posts의 H2/Oracle 스키마와 스키마·계약 테스트.
  • BaseMapper와 XML Mapper를 나눠 쓴 백엔드, 조건 조각을 공유하는 검색 쿼리.
  • 같은 검색 시나리오 11건이 H2에서 통과했고, Oracle 통과는 원고 작성 시 기록입니다. 재검증에서는 Oracle이 없어 다시 실행하지 못했습니다.
  • 종합 프로젝트 전체 88건 중 재검증 환경에서는 75건 통과·Oracle 13건 SKIPPED입니다. “Oracle 포함 88건 통과”는 CI의 oracle 잡 기록입니다.

한계와 확인하지 않은 것

항목 상태
실제 사용자 의견 받지 않음. 요구사항은 한 사람이 정리
인덱스(author_id, created_at) 효과 대량 데이터로 측정하지 않음
키워드 검색(LIKE '%..%') 대량 성능 측정하지 않음
같은 글 동시 수정 충돌(낙관적 락) 다루지 않음
구조 테스트 패키지 이름 기준이라 같은 패키지 안의 잘못된 의존은 못 잡음
Oracle 외 DB(PostgreSQL 등) 확인하지 않음. Oracle은 Free 23 컨테이너 하나
DatabaseIdProvider 없이 _databaseId 동작 실행해 보지 않음
H2 태그 LIKE 방식 meta가 태그만 담는 동안만 안전
@TableName(autoResultMap = true) 끈 상태 실패를 재현하지 않음
임시 인증 위조 가능. Chapter 24에서 대체

이 Chapter의 일관된 교훈

  • 지킬 수 있는 것은 테스트로 만듭니다(구조 규칙, 스키마 제약, 검증 규칙).
  • DB마다 다른 것은 한곳에 모으고, 같은 시나리오를 두 DB에서 돌립니다.
  • 확인하지 않은 것은 확인하지 않았다고 씁니다.

확인 범위 요약

구분 재검증에서 직접 실행 원고 작성 시 기록에만 의존
H2 기반 테스트 75건, API 호출 예 -
Oracle 테스트 13건 아니오(SKIPPED) 예
인덱스·성능, 동시 수정, 다른 DB 아니오 원고 작성 시에도 확인하지 않음

직접 해 보기

  1. 위 표에서 가장 걸리는 항목 하나를 골라 보완 계획을 세워 보세요.
  2. 자신의 프로젝트에서 테스트로 고정되지 않은 “문서에만 있는 규칙”을 찾아 보세요.
  3. 같은 시나리오를 두 환경에서 돌릴 수 있도록 자신의 테스트를 재구성해 보세요.

용어와 참고 자료

Chapter 23의 용어를 모았습니다. 모듈과 계약은 Chapter 16 용어 정리, MyBatis·MapStruct는 Chapter 12 용어 정리, Oracle JSON은 Chapter 11 용어 정리를 참고하세요.

용어

용어 설명 나온 곳
범위 밖 이번에 만들지 않기로 한 기능의 목록입니다. 거절의 근거가 됩니다. 범위를 정하고 모듈 규칙을 테스트로 고정하기
구조 테스트 패키지 의존 방향 같은 코드 구조의 규칙을 테스트로 검사하는 것입니다. 범위를 정하고 모듈 규칙을 테스트로 고정하기
계약(Contract) 외부와 주고받는 요청·응답의 모양과 검증 규칙을 정의한 것입니다. 스키마와 계약을 테스트로 고정하기
제약 조건 테이블이 스스로 지키는 규칙입니다. UNIQUE, CHECK, FOREIGN KEY가 있습니다. 스키마와 계약을 테스트로 고정하기
IDENTITY 행을 넣을 때 번호를 자동으로 붙이는 컬럼 방식입니다. 같은 테이블, 두 가지 SQL
JSON 컬럼 구조가 일정하지 않은 값을 JSON 문서로 한 컬럼에 담는 방식입니다. 같은 테이블, 두 가지 SQL
BaseMapper MyBatis-Plus가 제공하는 기본 CRUD 메서드 모음 인터페이스입니다. 도구는 일의 모양으로 고른다
XML Mapper SQL을 XML 파일에 직접 쓰고 메서드와 연결하는 방식입니다. 도구는 일의 모양으로 고른다
<sql>/<include> SQL 조각을 정의하고 여러 쿼리에서 재사용하는 MyBatis 태그입니다. 검색 쿼리: 조건 조각과 정렬
_databaseId 접속한 DB의 종류를 나타내는 MyBatis 내장 값으로, SQL을 DB별로 나눌 때 씁니다. DB별 태그 필터와 LIKE 이스케이프
JSON_EXISTS Oracle에서 JSON 문서가 경로 조건을 만족하는지 검사하는 조건식입니다. DB별 태그 필터와 LIKE 이스케이프
이스케이프 %, _처럼 특별한 뜻이 있는 문자를 글자 그대로 쓰도록 표시하는 것입니다. DB별 태그 필터와 LIKE 이스케이프
TypeHandler Java 값과 JDBC 값 사이의 변환을 맡는 MyBatis 구성 요소입니다. 변환과 부딪친 문제
Actor 서비스가 받는 요청자 정보(사용자 ID와 역할)입니다. 서비스와 임시 인증, 오류 응답

참고 자료

직접 해보기

  1. UserApi에 post 모듈의 클래스를 참조하는 메서드를 하나 넣고 ./gradlew :projects:final-project:test --tests '*ArchitectureTests*'를 실행해 보세요. Architecture Violation 메시지의 둘째 줄에서 위반한 메서드와 (파일:줄)을 찾은 뒤 되돌립니다.
  2. ./gradlew :projects:final-project:test --tests '*SchemaTests*' --tests '*ContractValidationTests*'를 실행하고, 스키마의 CHECK 제약을 지운 뒤 다시 실행해 roleIsLimitedToUserAndAdmin이 실패하는지 확인하세요. 아이디에 대문자를 넣은 가입 요청을 보내 VALIDATION_FAILED의 issues에 어떤 사유가 나오는지도 봅니다.
  3. 글을 두 개 등록한 뒤 curl -s 'http://localhost:8080/api/v1/posts?tag=sq', ?tag=sql, ?keyword=%25의 결과를 비교해 보세요. 태그 sq가 sql 글을 찾지 못하는 이유를 H2의 LIKE 패턴으로 설명하고, ORDER BY에서 p.id DESC를 빼면 같은 시각의 글 순서가 어떻게 되는지도 생각해 봅니다.
  4. ORACLE_URL 없이 ./gradlew :projects:final-project:test --tests '*PostSearchH2Tests*' --tests '*PostSearchOracleTests*'를 실행해 통과와 SKIPPED 건수를 따로 세어 보세요. PostSearchScenarios에 시나리오를 하나 추가하면 하위 클래스를 고치지 않아도 양쪽에 적용되는지 확인합니다.
  5. resultMap의 javaType="_long"을 "long"으로 되돌려 NoSuchMethodException을 재현해 보세요. 같은 가입 요청을 두 번 보내 201과 409 DUPLICATE_USERNAME이 오는지도 확인합니다.

이번 장의 정리

  • 코드를 쓰기 전에 요구사항을 기능, 비기능, 범위 밖으로 나눕니다. 범위 밖 목록은 나중에 기능 추가 요청을 거절하는 근거가 됩니다.
  • user와 post 모듈은 공개 입구(api)와 비공개 구현(internal)으로 나누고, contract 패키지는 아무것도 참조하지 않게 ArchUnit 규칙으로 고정합니다. 위반 메시지는 둘째 줄의 참조 주체와 (파일:줄)부터 읽고, 검사 대상이 비어 있지 않은지도 확인합니다.
  • 테이블에는 fp_ 접두사를 붙이고, H2와 Oracle의 차이는 fp_posts 한 곳(H2 meta는 CLOB, Oracle은 JSON)에 모읍니다. 정렬에 쓰는 pinned는 JSON 안이 아니라 별도 컬럼에 둡니다.
  • 스키마 제약과 입력 검증 규칙은 테스트로 고정합니다. 비밀번호 상한 72는 bcrypt의 바이트 기준에서 나왔고, 글자 수와의 차이는 Chapter 24에서 다룹니다.
  • 단순 CRUD는 MyBatis-Plus BaseMapper, JOIN·동적 조건·JSON 필터·페이징이 한 쿼리에 모이는 검색은 XML Mapper로 씁니다. 목록과 건수 쿼리는 <sql>/<include>로 같은 조건 조각을 쓰고, 정렬은 pinned DESC, created_at DESC, id DESC로 순서를 고정합니다.
  • 태그 필터는 _databaseId로 나눠 Oracle은 JSON_EXISTS, H2는 따옴표까지 포함한 LIKE로 찾습니다. 사용자가 넣은 %, _는 escapeLike와 ESCAPE '\'로 글자 그대로 검색합니다.
  • 검색 시나리오 11건은 추상 클래스에 한 번만 쓰고 H2와 Oracle 하위 클래스가 함께 실행합니다. ORACLE_URL이 없을 때의 SKIPPED는 통과가 아닙니다.
  • MapStruct는 unmappedTargetPolicy=ERROR로 변환 누락을 컴파일 오류로 만들고, 서비스는 HTTP를 모른 채 Actor만 받습니다. 가입 중복은 사전 확인과 UNIQUE 제약으로 이중으로 막아 409를 돌려주고, 오류 응답은 @RestControllerAdvice 한 곳에서 code, message, issues 모양으로 만듭니다.

다음 Chapter 24 종합 프로젝트 2: 화면·보안·배포에서는 이 백엔드 위에 화면을 올리고, 임시 인증을 HTTP Basic으로 바꾸고, 한 이미지로 묶어 띄웁니다.

FAQ

자주 묻는 질문

왜 코드를 쓰기 전에 범위 밖을 정하나요?

완료 기준과 검증 범위를 분명히 하고 프로젝트 중간에 요구가 끝없이 늘어나는 것을 막기 위해서입니다.

BaseMapper와 XML Mapper를 함께 써도 되나요?

가능합니다. 단순 CRUD는 BaseMapper로 줄이고 조건 조각·정렬·DB별 분기가 필요한 검색은 XML Mapper에 명시합니다.

정렬 값 pinned를 JSON 안에 넣지 않는 이유는 무엇인가요?

정렬과 인덱스에 자주 쓰는 값은 DB가 직접 비교할 수 있는 열로 두는 편이 명확하고 효율적이기 때문입니다.

Oracle 테스트가 로컬에서 건너뛰어졌는데 결과를 믿어도 되나요?

본문은 재검증 환경의 75건 통과·Oracle 13건 SKIPPED와 원고 작성 당시 CI의 Oracle 통과 기록을 구분합니다. 직접 확인한 범위를 넘겨 단정하지 않습니다.

작성·편집 ToolPado

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

기술 기준 Spring Boot 4.1.1 · JDK 21

마지막 검토