Files
clean-architecture-backend-…/docs/manual/04-persistence.md
T
DongHyeonka 6e992970ca fix!: r9 확인 리뷰가 찾은 결함 25건을 고친다
문제: r9 커밋(45d2a478)을 영역 4개로 다시 리뷰해 결함 25건을 찾았다
(Important 2, Minor 23, round6/01~04). Important 둘: r9가 @Configuration을
사용자 전송에서 통째로 빼서 설정 안의 RouterFunction·DataFetcher가
@SystemCaller를 불러도 잡히지 않는 회귀, 그리고 가이드대로 만든
CREATE INDEX CONCURRENTLY 마이그레이션이 Flyway 기본 트랜잭션 잠금과 서로
기다려 끝나지 않는 것(이전부터). 그 밖에 시작을 거절당한 같은 attempt가
기록 만료까지 503을 받는 것, gRPC 취소 판정과 raw status 설명의 로그 유출,
STOMP의 IAE ERROR 기록, 아무것도 잡지 못하던 shared-contract 패키지 규칙,
workflow 판독기의 거짓 통과 모양(-v·조건부 exit·Windows 기본 셸·요청형
trigger 등).

방법: 영역별 4묶음이 실패 테스트를 먼저 확인하고 고쳤다(재리뷰 README 17절).
- 설정과 그 중첩 클래스는 요청 처리기 타입에 의존하면 사용자 전송으로 센다.
- Flyway PostgreSQL 잠금을 세션 수준으로(transactional-lock=false), 직접
  만드는 Flyway는 FlywaySchemaPolicy 하나로. 버린 대안: CIC를 마이그레이션에서
  금지하고 운영 절차로.
- 같은 attempt로 다시 claim하면 lease가 지난 claim을 넘겨받는다. 옛 revision의
  늦은 시작이 ALREADY를 받아 이중 실행되던 것도 막았다.
- 네 전송이 IAE를 ServerFailureLog의 같은 WARN 한 줄로 남긴다.
- workflow 판독기가 세지 않는 이유를 셋으로 나누고 문서 5곳을 같은 말로.

위험·한계: Flyway 세션 잠금은 transaction-mode PgBouncer 뒤에서 깨진다
(Hikari 직접 연결 전제, 가이드에 적음). 배포 마이그레이션 도구도 같은 값을
써야 한다(업그레이드 안내). 같은 attempt를 두 호출이 동시에 쓰는 것은
저장소가 가려내지 않는다(호출자 계약으로 문서화).

검증: 묶음별 RED·GREEN은 로컬(노트북 빌드 금지 지시 전)에서, 지시 뒤에
바뀐 01 A5 fixture의 RED와 02 늦은 시작 revision 검사의 RED, 03 동시 인덱스
검사기 GREEN은 desktop에서 확인했다. 합친 트리를 desktop에서 돌려 모두 첫
실행 통과: :ci :verifyDependencyLocks --warning-mode=fail, sample check,
두 빌드 verifyStrictLaneStages --dry-run, :mainCheck, :integrationCheck,
-p optional-platforms ci integrationCheck performanceCheck, :performanceCheck,
:releaseCheck, compose 18 lane, -p build-logic check javadoc(README 17.2절).

Refs: docs/reviews/2026-11-03-rereview/README.md 17절
BREAKING CHANGE: Flyway PostgreSQL 잠금이 세션 수준이 되어 배포 도구에도
flyway.postgresql.transactional.lock=false가 필요하다. GraphQL·gRPC가 IAE를
WARN 한 줄로 남긴다. shared-contract 패키지 규칙이 실제로 검사한다.
2026-11-05 21:26:50 +09:00

151 lines
12 KiB
Markdown

# 04. 영속성
## 핵심
저장 adapter는 생성 명령이 만들지 않는다. 이 장의 순서로 만든다. 세 가지를 지킨다.
1. 엔티티 연관관계는 한쪽에서만 맵핑한다. 빌드가 막는다.
2. 중복·경쟁은 코드 순서가 아니라 **DB 제약**이 막고, 위반은 기능의 오류로 바꾼다.
3. 마이그레이션은 템플릿 운영 스트림과 **번호가 겹치지 않는 자기 스트림**에 둔다.
```text
use case ── tx.inWrite ──▶ XRepository (domain 포트)
│
▼
JpaXRepository (adapter) ── CallerTransaction.require
│ 엔티티 ↔ aggregate 변환(mapper)
▼
Spring Data / EntityManager ──▶ PostgreSQL (제약·인덱스)
│
위반·장애 ──▶ PersistenceExceptionTranslator ──▶ OperationalError 또는 기능 예외
```
## 순서
1. 계약 테스트부터: 생성된 `XRepositoryContract`(domain-core testFixtures)에 필요한 동작을 더한다.
in-memory fake가 먼저 통과해야 한다.
2. 마이그레이션을 쓴다(아래 번호 규칙).
3. 엔티티·Spring Data repository·mapper·adapter를 쓴다. adapter는 aggregate만 주고받는다
(`OUTBOUND_ADAPTER_METHOD_RETURNS_ONLY_DOMAIN_OR_PRIMITIVES`).
4. `JpaXRepositoryContractTest extends XRepositoryContract`를 실 PostgreSQL lane에 둔다(08장 lane).
adapter는 호출자 트랜잭션 밖의 호출을 거부하므로(아래 「트랜잭션 안에서만 쓴다」), 계약의
`inTransaction(Supplier)`을 재정의해 거기서 트랜잭션을 열고 커밋한다. 계약은 모든 저장소 호출을 그
hook으로 부른다. fake는 기본값(그냥 실행)을 쓴다.
예: `src/sample-portfolio/src/integrationTest/java/dev/caskeleton/sample/portfolio/adapter/outbound/persistence/repository/WorkLogRepositoryAdapterContractTest.java`.
5. adapter를 bean으로 등록하는 자동 설정을 쓰고, 기능의 `XConfig`에 `afterName`으로 그 순서를 적는다.
## 판단: 저장 adapter를 둘 leaf
- **고르는 기준**: upstream 템플릿 leaf에 서비스 코드가 섞이는가.
- **기본값**: 서비스 전용 persistence leaf 하나(`adapter:outbound:persistence-<service>`)를 registry에
등록하고 업무 기능의 adapter를 모두 거기 둔다. 모양은 `src/adapter/outbound/persistence-notification`
(`persistence-jpa`에 의존, 자기 엔티티 scan·자기 Flyway 스트림·자기 자동 설정).
- **예외**: 하나도 없다고 보는 편이 낫다. `persistence-jpa`에 업무 패키지를 넣으면 ① capability 규칙 7
("모듈을 아는 곳은 모듈 자신뿐")을 어기고, ② 그 leaf의 공개 API 기준선
(`docs/architecture/jpa-api-surface.txt`)과 엔티티 scan 목록(`PersistenceJpaConfig`,
`PersistenceEntityScanCoverageTest`)을 고쳐야 하며, ③ upstream 병합 충돌 면이 넓어진다.
sample은 자기 leaf 안에 adapter를 둔다(③ 수직 슬라이스라서).
- 새 leaf는 `modules.json` 등록, lockfile 생성, `app-bootstrap/build.gradle` 한 줄이 필요하다(10장).
## 엔티티 매핑
정본: `docs/jpa/entity-mapping-guide.md`.
| 규칙 | 막는 곳 |
| --- | --- |
| 연관관계는 한쪽만. aggregate 사이는 id 참조, 같은 aggregate 안은 단방향 `@ManyToOne(LAZY)`, 컬렉션은 쿼리 | `JpaArchitectureRules.associationsAreMappedFromOneSideOnly()`(`src/adapter/outbound/persistence-jpa/src/testFixtures/java/dev/caskeleton/adapter/outbound/persistence/testkit/arch/JpaArchitectureRules.java`) — `JpaProductionArchitectureTest`가 운영 그래프 전체에 건다 |
| 엔티티는 adapter 밖으로 나가지 않는다 | `PERSISTENCE_ENTITIES_STAY_INSIDE_A_PERSISTENCE_ADAPTER`, `noEntityFromWeb` |
| `Long` id 금지, id 컬럼 `varchar(255)` 금지 | `NO_LONG_ID_PK`, `NO_VARCHAR_255_FOR_ID_COLUMN` |
| 벤더 전용 `columnDefinition` 금지 | `PERSISTENCE_RDBMS_ENTITIES_DO_NOT_PIN_VENDOR_COLUMN_DEFINITIONS` |
| 감사 필드는 엔티티에만, 도메인에는 없다 | `DOMAIN_ENTITIES_DO_NOT_CARRY_AUDIT_FIELDS` |
### 판단: 단방향 `@OneToMany(@JoinColumn)`을 써도 되나
- **기본값**: 쓰지 않는다. 자식 목록은 repository 쿼리(`findByParentId`, 페이지는 SQL에서).
- **예외**: 루트만 바꾸는 자식(루트를 통해서만 생기고 지워짐). 규칙은 `mappedBy`만 막으므로 허용되지만
nullable join column이면 자식마다 UPDATE가 한 번 더 나간다(가이드 「Associations」).
## 트랜잭션 안에서만 쓴다
store는 자기 트랜잭션을 열지 않는다. 유스케이스가 연 트랜잭션에 합류해야 하는 쓰기는 시작 전에
`CallerTransaction.require("<무엇>")`
(`src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/transaction/CallerTransaction.java`)를
부른다. 없으면 트랜잭션 밖 호출이 문장마다 따로 커밋되어, 같이 커밋돼야 할 행(업무 행 + outbox 행)이
갈라진다.
## 중복·경쟁은 DB가 막는다
- **고르는 기준**: "같은 X가 둘 있으면 안 된다", "한 작업을 두 인스턴스가 집으면 안 된다" 같은 규칙인가.
- **기본값**: DB 제약.
- 중복 금지 → 유일성 제약/인덱스. 유스케이스의 사전 조회(`existsBy…`)는 빠른 거절일 뿐이다.
READ COMMITTED에서 두 요청이 모두 "없음"을 보고 둘 다 insert한다.
- adapter가 그 **이름 붙은 제약**의 위반만 잡아 기능 예외로 바꾼다. 다른 제약 위반은 그대로 둔다.
예: `src/sample-portfolio/src/main/java/dev/caskeleton/sample/portfolio/adapter/outbound/persistence/repository/PosterRepositoryAdapter.java`
(`DataIntegrityViolationException` → 제약 이름 확인 → `PosterTitleAlreadyExistsException` 409),
제약은 `src/sample-portfolio/src/main/resources/db/sample-migration/V8_1__poster_title_unique.sql`.
- **충돌을 바꾸는 곳은 하나다.** 업무 규칙 충돌(같은 제목)은 포트 옆 domain 패키지의 예외 타입이고,
포트가 `@throws`로 선언하고 adapter가 던진다. 유스케이스의 사전 조회도 같은 타입을 던져 두 경로가 같은
409가 된다. application 예외를 domain 포트가 Javadoc으로만 가리키면 fake·mock은 그 약속을 지킬 수 없다.
기술 충돌(버전 불일치·교착)은 adapter가 프레임워크 예외 그대로 두고 아래 `PersistenceExceptionTranslator`가
`DB_*` 코드로 바꾼다(WorkLog의 `ObjectOptimisticLockingFailureException` → `DB_OPTIMISTIC_CONFLICT`).
- 그 약속은 포트 소유자 testFixtures의 공유 계약 테스트로 고정한다. fake와 adapter가 같은 계약을 상속한다.
예: `PosterRepositoryContract`(`InMemoryPosterRepository`, `PosterRepositoryAdapterContractTest`).
- 여러 인스턴스가 집는 작업 → `FOR UPDATE SKIP LOCKED`는 **트랜잭션 안에서**, 그리고 lease(만료 시각)와
fence 값을 함께 저장한다. 예: `ReconciliationJobStorePort.claimDue`(application-notification),
gRPC operation ledger의 claim.
- 수정 충돌 → 버전 열(낙관적 잠금). 예: `UpdateWorkLogUseCase`의 version 비교와 `@Version`.
- **예외**: DB가 볼 수 없는 규칙(외부 시스템 상태)은 분산 락(`DistributedLockPort`)이나 멱등성 키(05장).
- 동시성 테스트는 실 DB lane에서 동시 요청 N개 → 행 1개를 단언한다(sample `integrationTest` 참고).
## 기술 실패는 공통 코드로 나간다
어떤 기능 예외로도 바꾸지 않은 DB 실패는 `PersistenceExceptionTranslator`
(`src/adapter/outbound/persistence-jpa/src/main/java/dev/caskeleton/adapter/outbound/persistence/failure/PersistenceExceptionTranslator.java`)가
SQLState로 `OperationalError`를 고른다. `DB_UNIQUE_VIOLATION` 409, `DB_SERIALIZATION_FAILURE`·`DB_DEADLOCK`
409(retryable), 커밋 중 연결 끊김은 `DB_COMPLETION_UNKNOWN` 500(05장). 분류표는 이 한 곳이다. adapter가
SQLState 표를 복사하지 않는다.
## 마이그레이션 번호
```text
템플릿 운영 스트림 classpath:db/migration/postgresql V1 … V19 … (upstream이 계속 늘린다)
capability 스트림 db/migration/jpa/<capability> 각자 history table
샘플 스트림 db/sample-migration flyway_sample_schema_history
서비스 스트림(권장) db/migration/<service> flyway_<service>_schema_history
```
- **고르는 기준**: upstream 템플릿을 계속 받을 것인가.
- **기본값**: 서비스 마이그레이션은 **자기 위치 + 자기 history table** 스트림에 둔다. 모양은
`SamplePostgreSqlPersistenceConfig.sampleMigrationStrategy`
(`src/sample-portfolio/src/main/java/dev/caskeleton/sample/portfolio/bootstrap/persistence/SamplePostgreSqlPersistenceConfig.java`)와
`NotificationSchemaStream`(persistence-notification). 그러면 번호가 템플릿 스트림과 독립이라 V1부터 쓴다.
자기 스트림의 Flyway는 `Flyway.configure()`가 아니라 `FlywaySchemaPolicy.configure()`(persistence-jpa)로
만든다. Flyway의 PostgreSQL 잠금을 세션에 두어야 `CREATE INDEX CONCURRENTLY` 마이그레이션이 끝나고,
직접 부르면 `:app-bootstrap:architectureTest`가 실패한다(`docs/jpa/migration-guide.md` "Who may change the schema").
- **예외**: 템플릿 운영 스트림(`db/migration/postgresql`)에 직접 넣으면 upstream이 다음에 쓸 번호와
겹친다. 어쩔 수 없으면 upstream이 쓰지 않을 큰 번호대를 정해 문서에 적는다.
- 이미 적용된 파일은 고치지 않는다. 고치면 체크섬 불일치로 기동이 멈추고, `repair`는 쓰지 않는다
(`docs/jpa/migration-guide.md`).
- 같은 스트림 안에서 기존 두 버전 사이에 끼워야 하면 소수 버전(`V8_1`)을 쓴다. 샘플 테스트 일부가 운영
스트림과 샘플 스트림을 한 목록으로 합치는데, 정수 V9 이상은 운영이 이미 쓰고 있어서 `V8_1`을 골랐다
(리뷰 README 13.2, 09-02).
- 기존 데이터가 새 제약을 어기면 마이그레이션이 이유를 남기고 멈추게 쓴다(`V8_1`의 `DO $$` 블록). 조용히
지우지 않는다.
- 운영 중인 테이블을 잠그는 문장(`ALTER TABLE`, `CONCURRENTLY` 없는 `CREATE INDEX`, `UPDATE`·`DELETE`, 기존
테이블을 가리키는 `REFERENCES`, trigger 만들기·지우기 등 — 전체 목록은 `docs/jpa/migration-guide.md`)이 있으면
그 앞에 `SET LOCAL lock_timeout = '5s';`를 둔다(`V8_1`, `V22`). 값은 0이 아니어야 하고,
`executeInTransaction=false` 마이그레이션에서는 `SET LOCAL`이 효과가 없으니 잠그는 문장을 거기 두지 않는다. Flyway가
스스로 트랜잭션 밖에서 돌리는 문장(`VACUUM`, `CREATE INDEX CONCURRENTLY` 등 — 목록은 같은 가이드)이 하나라도 있는 파일도
트랜잭션 밖에서 돌므로, 그런 문장은 따로 한 파일에 둔다. `VACUUM FULL`처럼 트랜잭션 안에서 돌 수 없는 잠금 문장은
상한을 걸 수 없으니 마이그레이션에 두지 않고 운영 절차로 돌린다. 상한이 없으면 그 테이블을 건드린 열린
트랜잭션 하나(`ALTER TABLE`이면 읽기만 한 것도) 뒤에서 마이그레이션이 끝없이 기다리고, 그동안 뒤에 온 그
테이블의 쓰기(`ALTER TABLE`이면 읽기까지)가 모두 마이그레이션 뒤에 줄을 선다. 상한이 있으면 5초 뒤 실패·롤백되고 새 버전이 뜨지 않을 뿐이다. 자기 스트림에도
`SampleMigrationLockWaitTest`처럼 `LockWaitMigrationInspector`(persistence-jpa testkit) 검사를 둔다
(`docs/jpa/migration-guide.md` "Bound the lock wait").
## 지금 이해하면 되는 것
- 저장 adapter는 서비스 전용 persistence leaf에. persistence-jpa에 업무 코드를 넣지 않는다.
- 중복은 유일성 제약, 경쟁은 트랜잭션 안 claim + lease, 수정 충돌은 버전 열.
- 마이그레이션은 자기 스트림(자기 history table). 적용된 파일은 고치지 않는다.