템플릿 repo 안에 프로젝트 계층이 아닌 라이브러리가 있었다. gRPC 플랫폼 (src/platforms/grpc, grpc-advanced)과 그것만을 위한 두 번째 Gradle 빌드 (src/platforms/optional-build)는 템플릿 어느 leaf도 쓰지 않는데, registry 9행, workflow job 넷과 단계 하나, build-logic 플러그인 둘, 카탈로그·SpotBugs 항목, 문서 열두 개를 템플릿이 함께 지고 있었다. 소유자 결정(2026-11-07, design-docs repo-structure/README.md 3.5절, 05-library-repos.md Q1~Q17 승인)대로 라이브러리마다 별도 repo로 옮긴다. gRPC는 템플릿 소비자가 없어 먼저 옮기고, 템플릿은 지우기만 한다(Q13). 코드와 이력은 grpc-library repo에 filter-repo로 옮겼다(옮긴 폴더의 트리 해시가 이 기준 커밋 22df3525와 같다). 지운 것: - src/platforms/grpc, grpc-advanced, optional-build(343파일) - registry의 "build": "optional-grpc" 9행 - ci-quality-gates.yml job optional-platforms·grpc-proto-buf와 그 needs, integration-main.yml optional 성능 단계와 job grpc-optional-platform-integration, release.yml job grpc-stable-release-gate와 이미지 job의 needs 한 줄 - build-logic ca.grpc-platform-module·ca.optional-architecture-registry, MainBuild(두 번째 빌드에서 주 빌드를 찾던 것)와 ArchitecturePlugin의 optional 분기. 도구 설정·이미지 목록·registry는 Gradle 루트에서 찾는다 - 카탈로그 protobufPlugin·protobuf-java-grpc·protoc·plugin protobuf(Q14: 채택 전이라 grpc-library 좌표도 넣지 않는다), SpotBugs 제외의 gRPC 줄 - 옮긴 문서: ADR-GRPC 7개, docs/compatibility/(폴더째), gRPC runbook 둘, gRPC 설계서. 리뷰·기록 본문은 고치지 않았다(Q15). 기록 하나의 머리 블록 「현재 정본」만 새 자리를 말하게 했다 - DeveloperExperienceContractTest의 optional 빌드 lane 계약 시험, adopter API 표면 검사의 optional-build 제외 경로 남긴 것: adapter:inbound:grpc(io.grpc를 직접 쓰고 플랫폼을 쓰지 않는다), src/platforms/messaging(다음 분리 작업), registry의 build 칸 지원 (ModuleRegistry, 일반 기능). 살아 있는 문서: README, docs 지도, capability-status, work/delegate· gates·decisions(새 행 「라이브러리 repo」)·defect-patterns· review-criteria(경계 밖 파일을 경로로 읽는 결합을 결함 후보로), manual 04, jpa migration-guide, build-logic AGENTS·README, testkit 주석. 새 docs/work/reference/related-repos.md가 라이브러리 repo 목록과 같이 고치는 법을 둔다. 파생 서비스 안내는 docs/upgrade 3.8절 B-55·B-56. 위험: 파생 서비스가 이 경로를 고쳤으면 수정 대 삭제 충돌이 난다 (tech-log-backend는 플랫폼을 받은 적이 없다, 설계 12절). 분리 직전 커밋 태그 pre-library-split(설계 12.2절)은 이 브랜치 권한 밖이라 달지 않았다. 검증: desktop 게이트 결과는 PR 본문(ci, mainCheck 계열, releaseCheck, compose smoke, 빠른 시작). 문서 검사 셋 rc=0. BREAKING CHANGE: src/platforms/grpc*·optional-build, :grpc:*·:grpc-advanced:* 프로젝트, ca.grpc-platform-module, 카탈로그 protoc·protobuf-java-grpc·plugin protobuf가 없다. 쓰던 서비스는 grpc-library 좌표 com.hyeonworks.grpc로 받는다(docs/upgrade/2026-11-maturity-review.md 3.8절). Refs: design-docs repo-structure/05-library-repos.md 13.1절 1·2단계
12 KiB
04. 영속성
핵심
저장 adapter는 생성 명령이 만들지 않는다. 이 장의 순서로 만든다. 세 가지를 지킨다.
- 엔티티 연관관계는 한쪽에서만 맵핑한다. 빌드가 막는다.
- 중복·경쟁은 코드 순서가 아니라 DB 제약이 막고, 위반은 기능의 오류로 바꾼다.
- 마이그레이션은 템플릿 운영 스트림과 번호가 겹치지 않는 자기 스트림에 둔다.
use case ── tx.inWrite ──▶ XRepository (domain 포트)
│
▼
JpaXRepository (adapter) ── CallerTransaction.require
│ 엔티티 ↔ aggregate 변환(mapper)
▼
Spring Data / EntityManager ──▶ PostgreSQL (제약·인덱스)
│
위반·장애 ──▶ PersistenceExceptionTranslator ──▶ OperationalError 또는 기능 예외
순서
- 계약 테스트부터: 생성된
XRepositoryContract(domain-core testFixtures)에 필요한 동작을 더한다. in-memory fake가 먼저 통과해야 한다. - 마이그레이션을 쓴다(아래 번호 규칙).
- 엔티티·Spring Data repository·mapper·adapter를 쓴다. adapter는 aggregate만 주고받는다
(
OUTBOUND_ADAPTER_METHOD_RETURNS_ONLY_DOMAIN_OR_PRIMITIVES). 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.- 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 생성,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가 그 이름 붙은 제약의 위반만 잡아 기능 예외로 바꾼다. 다른 제약 위반은 그대로 둔다.
순서는
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). - 수정 충돌 → 버전 열(낙관적 잠금). 예:
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 표를 복사하지 않는다.
마이그레이션 번호
템플릿 운영 스트림 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). 적용된 파일은 고치지 않는다.