lease를 넘겨받는 저장소 다섯 곳이 앞 실행의 쓰기를 막지 못한다. durable operation은 owner만 보고 써서 같은 worker id가 다시 claim하면 앞 실행의 결과가 남는다. 알림 lease 회복은 상태를 다시 읽은 뒤 조건 없이 되돌려 끝난 delivery를 다시 보낸다. 만료 sweep·전체 읽음은 기다린 행의 상태를 다시 보지 않는다. 멱등성 reaper는 앱 시계로 비교하고 한 번에 다 지우며, 같은 키 요청이 되살린 기록까지 지운다. fileserver recovery enqueue는 동시 삽입에서 25P02로 실패하고, cleanup은 claim lease가 끝난 뒤에도 항목을 시작한다. 저장소가 행에서 만드는 claim·lease record는 잘못된 값을 IllegalArgumentException으로 거절해 web이 400으로 바꾼다. 고른 방법: 모든 쓰기를 owner·fence(·상태·만료) 조건을 단 한 문장으로 바꾼다. durable operation은 V23 lease_fence를 더하고 DurableOperationClaim 을 돌려준다. 알림 회복은 requeueAbandoned 한 문장이다. 만료 sweep은 subquery가 SKIP LOCKED로 쥔 행을 건너뛰고 바깥 UPDATE가 상태·만료를 다시 본다. 전체 읽음은 바깥 UPDATE가 상태를 다시 본다. reaper는 DB now()로 1000행씩, 트랜잭션마다 30초(SpringTransaction.DEFAULT_TIMEOUT_SECONDS)이고 바깥 DELETE에도 만료를 둔다. recovery는 INSERT … ON CONFLICT, cleanup은 lease 마지막 2분에 시작하지 않고 시도를 세지 않는 release로 돌려준다. 알림 provider timeout은 lease보다 짧아야 기동한다(호출이 lease를 넘으면 lease 복구가 아직 도는 호출을 맞추기로 넘긴다). 저장소가 만드는 record 일곱은 IllegalStateException으로 거절한다. 버린 대안: 읽고 비교한 뒤 쓰기(경합이 그대로 남음), 앱 쪽 락(인스턴스 사이에서 무의미). 위험·한계: 포트 시그니처가 바뀐다(DurableOperationStorePort, RecipientLeaseStorePort.expiredDispatching, RecipientDeliveryStorePort .requeueAbandoned, CleanupQueuePort.release). owner가 없거나 fence가 0인 V4 전 DISPATCHING 행은 회복이 고르지 않는다(안내 4행에 고치는 SQL). provider timeout 검사는 필요조건일 뿐이고, 호출 전체를 묶는 것은 SES다. 검증: desktop RED(고치기 전 트리 + 새 시험, pr1-red3) 새 시험 13건 실패. GREEN은 PR 본문의 verify.sh pr·PostgreSQL lane 결과. Refs: RR9-01-02, RR9-01-04, RR9-01-06, RR9-01-12, RR9-01-13, RR9-01-23, RR9-01-24, RR9-01-29, R1 넘김 DurableOperationStoreContractTest BREAKING CHANGE: DurableOperationStorePort의 heartbeat·reportProgress·succeed·fail이 DurableOperationClaim을 받고 claimNext가 그것을 돌려준다. RecipientLeaseStorePort.expiredDispatching이 List<RecipientLease>를 돌려주고 RecipientDeliveryStorePort.requeueAbandoned, CleanupQueuePort.release가 새로 생긴다. IdempotencyReaper 생성자에서 Clock이 빠진다. 알림 provider timeout이 lease 이상이면 기동이 실패한다. 저장소가 만드는 claim·lease record가 IllegalStateException을 던진다. docs/upgrade/2026-11-round9-claim-fence.md
158 lines
13 KiB
Markdown
158 lines
13 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/adapter/outbound/persistence-jpa/src/postgresqlIntegrationTest/java/dev/caskeleton/adapter/outbound/persistence/operation/JpaDurableOperationStoreContractTest.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 병합 충돌 면이 넓어진다.
|
|
- 새 leaf는 `modules.json` 등록, lockfile 생성, `src/bootstrap/app/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가 그 **이름 붙은 제약**의 위반만 잡아 기능 예외로 바꾼다. 다른 제약 위반은 그대로 둔다.
|
|
순서는 `DataIntegrityViolationException`을 잡는다 → 원인의 제약 이름이 그 제약인지 본다 → 맞으면
|
|
기능 예외(예: `TitleAlreadyExistsException`, 409)를 던지고, 아니면 다시 던진다. 템플릿 코드에는 이
|
|
모양의 예가 없다. 확인은 아래 공유 계약 테스트와 동시성 테스트로 한다.
|
|
- **충돌을 바꾸는 곳은 하나다.** 업무 규칙 충돌(같은 제목)은 포트 옆 domain 패키지의 예외 타입이고,
|
|
포트가 `@throws`로 선언하고 adapter가 던진다. 유스케이스의 사전 조회도 같은 타입을 던져 두 경로가 같은
|
|
409가 된다. application 예외를 domain 포트가 Javadoc으로만 가리키면 fake·mock은 그 약속을 지킬 수 없다.
|
|
기술 충돌(버전 불일치·교착)은 adapter가 프레임워크 예외 그대로 두고 아래 `PersistenceExceptionTranslator`가
|
|
`DB_*` 코드로 바꾼다(`ObjectOptimisticLockingFailureException` → `DB_OPTIMISTIC_CONFLICT`).
|
|
- 그 약속은 포트 소유자 testFixtures의 공유 계약 테스트로 고정한다. fake와 adapter가 같은 계약을 상속한다.
|
|
예: `DurableOperationStoreContract`(`InMemoryDurableOperationStore`, `JpaDurableOperationStoreContractTest`).
|
|
- 여러 인스턴스가 집는 작업 → `FOR UPDATE SKIP LOCKED`는 **트랜잭션 안에서**, 그리고 lease(만료 시각)와
|
|
fence 값을 함께 저장한다. 예: `ReconciliationJobStorePort.claimDue`(application-notification).
|
|
- 연장·완료·되돌리기는 그 claim의 owner와 fence를 `WHERE`에 넣은 조건부 UPDATE 하나다. fence는 claim마다
|
|
오르므로 같은 worker id가 다시 claim해도 앞 실행의 쓰기는 0행이다(예: `DurableOperationClaim`).
|
|
- `WHERE id IN (SELECT … LIMIT n)`으로 고른 행을 바꿀 때는 subquery를 `FOR UPDATE SKIP LOCKED`로 잠가 남이 쥔 행을
|
|
고르지 않는다. 상태 조건도 바깥 `UPDATE … WHERE`에 한 번 더 둔다. 잠금 절이 빠지면 READ COMMITTED는 잠금을 기다린
|
|
행에 바깥 조건만 다시 보고 subquery 안 조건은 보지 않기 때문이다(예: `RecipientClaimSql.EXPIRE_OVERDUE`). 잠그지 않는
|
|
subquery라면 바깥 조건이 유일한 방어다(예: inbox `markAllRead`).
|
|
- 만료는 그 시각을 쓴 시계로 본다. row lease(outbox, 알림 수신자, durable operation, fileserver cleanup,
|
|
Mongo migration lock)는 앱 `Clock`으로 쓰고 앱 `Clock`으로 비교한다. 시험이 시계를 옮길 수 있게 하려는
|
|
것이고, 대신 인스턴스 사이 시계 차이가 가장 짧은 lease보다 훨씬 작아야 한다(NTP 동기화가 배포 조건이다).
|
|
DB가 쓴 시각은 DB 시계로(멱등성 `expires_at`은 `clock_timestamp()`로 쓰고 `now()`로 지운다), Redis가 쓴
|
|
시각은 Redis `TIME`으로 본다. 한 저장소 안에서 두 시계를 섞지 않는다.
|
|
- 수정 충돌 → 버전 열(낙관적 잠금). 예: `DurableOperationEntity`(persistence-jpa)의 `@Version` 열 `row_version`.
|
|
- **예외**: DB가 볼 수 없는 규칙(외부 시스템 상태)은 분산 락(`DistributedLockPort`)이나 멱등성 키(05장).
|
|
- 동시성 테스트는 실 DB lane에서 동시 요청 N개 → 행 1개를 단언한다.
|
|
|
|
## 기술 실패는 공통 코드로 나간다
|
|
|
|
어떤 기능 예외로도 바꾸지 않은 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/migration/<service> flyway_<service>_schema_history
|
|
```
|
|
|
|
- **고르는 기준**: upstream 템플릿을 계속 받을 것인가.
|
|
- **기본값**: 서비스 마이그레이션은 **자기 위치 + 자기 history table** 스트림에 둔다. 모양은
|
|
`NotificationSchemaStream`(persistence-notification). 그러면 번호가 템플릿 스트림과 독립이라 V1부터 쓴다.
|
|
자기 스트림의 Flyway는 `Flyway.configure()`가 아니라 `FlywaySchemaPolicy.configure()`(persistence-jpa)로
|
|
만든다. Flyway의 PostgreSQL 잠금을 세션에 두어야 `CREATE INDEX CONCURRENTLY` 마이그레이션이 끝난다.
|
|
`Flyway.configure()`를 직접 부르거나 설정 객체를 직접 만들면(`new FluentConfiguration()`,
|
|
`new ClassicConfiguration()`, 그 하위 클래스) `: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`)을 쓴다. 두 스트림을 한 목록으로
|
|
합쳐 검사하는 테스트가 있으면, 다른 스트림이 이미 쓴 정수 번호를 피하려고 이렇게 끼운다.
|
|
- 기존 데이터가 새 제약을 어기면 마이그레이션이 이유를 남기고 멈추게 쓴다(`DO $$` 블록의 `RAISE EXCEPTION`). 조용히
|
|
지우지 않는다.
|
|
- 운영 중인 테이블을 잠그는 문장(`ALTER TABLE`, `CONCURRENTLY` 없는 `CREATE INDEX`, `UPDATE`·`DELETE`, 기존
|
|
테이블을 가리키는 `REFERENCES`, trigger 만들기·지우기 등 — 전체 목록은 `docs/jpa/migration-guide.md`)이 있으면
|
|
그 앞에 `SET LOCAL lock_timeout = '5s';`를 둔다(`V22`). 값은 0이 아니어야 하고,
|
|
`executeInTransaction=false` 마이그레이션에서는 `SET LOCAL`이 효과가 없으니 잠그는 문장을 거기 두지 않는다. Flyway가
|
|
스스로 트랜잭션 밖에서 돌리는 문장(`VACUUM`, `CREATE INDEX CONCURRENTLY` 등 — 목록은 같은 가이드)이 하나라도 있는 파일도
|
|
트랜잭션 밖에서 돌므로, 그런 문장은 따로 한 파일에 둔다. `VACUUM FULL`처럼 트랜잭션 안에서 돌 수 없는 잠금 문장은
|
|
상한을 걸 수 없으니 마이그레이션에 두지 않고 운영 절차로 돌린다. 상한이 없으면 그 테이블을 건드린 열린
|
|
트랜잭션 하나(`ALTER TABLE`이면 읽기만 한 것도) 뒤에서 마이그레이션이 끝없이 기다리고, 그동안 뒤에 온 그
|
|
테이블의 쓰기(`ALTER TABLE`이면 읽기까지)가 모두 마이그레이션 뒤에 줄을 선다. 상한이 있으면 5초 뒤 실패·롤백되고 새 버전이 뜨지 않을 뿐이다. 자기 스트림에도
|
|
`MigrationLockWaitTest`(persistence-jpa)처럼 `LockWaitMigrationInspector`(persistence-jpa testkit) 검사를 둔다
|
|
(`docs/jpa/migration-guide.md` "Bound the lock wait").
|
|
|
|
## 지금 이해하면 되는 것
|
|
|
|
- 저장 adapter는 서비스 전용 persistence leaf에. persistence-jpa에 업무 코드를 넣지 않는다.
|
|
- 중복은 유일성 제약, 경쟁은 트랜잭션 안 claim + lease, 수정 충돌은 버전 열.
|
|
- 마이그레이션은 자기 스트림(자기 history table). 적용된 파일은 고치지 않는다.
|