Files
clean-architecture-backend-…/docs/manual/04-persistence.md
T
DongHyeonka 1400dc1506 feat!: 남은 리뷰 발견을 고치고 개발 매뉴얼과 기능 생성 명령을 더한다
문제: High·P1을 고친 뒤에도 P2·P3 약 90건이 남았다. 연결·구독·메시지
크기 상한이 없는 전송(WebSocket·gRPC·GraphQL deadline), 낙관적 충돌의
500, upsert 경쟁, Mongo 무제한 timeout, 샘플 목록 N+1, 갈라진 복사본
(TenantId 3벌, 이벤트 ID 문법 5곳, SQLState 표 2벌), 문서를 읽는 PR
테스트와 캐시를 막는 lane 설정 등이다. 새 기능을 어디에 어떤 순서로
만드는지 알려 주는 문서와 도구가 없었다. MinIO 공식 이미지가 사라져
객체 저장소 lane이 돌지 않았다.

방법: 영역별 묶음으로 실패 테스트를 먼저 쓰고 고쳤다. 고치는 중에 찾은
결함도 함께 고쳤다(durable operation id가 UUIDv4라 이벤트가 전부 DEAD,
S3 어댑터 생성·작은 chunk 읽기 실패, Redis 조건부 기록의 EVALSHA 권한).
MinIO는 pgsty/minio를 digest로 고정했다(Chainguard는 태그·실행 사용자·
mc 이미지 문제로 버림). docs/manual/에 작업 순서와 판단 지점을 쓰고,
scripts/new-feature.sh가 5개 leaf에 뼈대를 만든다. 생성→빌드→통과
왕복을 verifyFeatureScaffold가 mainCheck에서 본다. 묶음별 결과와
결정은 리뷰 README 14절에 있다.

위험·한계: 파생 서비스 동작이 바뀐다. JDBC batch 50 기본, 운영 jar에서
H2 제거, 트랜잭션 30초 제한, 격리 수준을 Hikari에서 고정, gRPC·
WebSocket·GraphQL 새 한도, correlation ID 규칙 밖이면 서버가 교체,
샘플 키 오류 코드 IDEMPOTENCY_KEY_INVALID. 새 leaf 두 개
(composition:durable-operation, adapter:inbound:messaging)와 새
마이그레이션(postgresql V20·V21, notification V11·V12, sample V8_1,
grpc-ledger V002)이 생긴다. V21 유일 인덱스는 기존 중복이 있으면
실패한다(runbook에 확인 쿼리).

검증: ci, mainCheck(생성 명령 왕복 포함), integrationCheck(MinIO 포함
전 컨테이너 lane), -p optional-platforms ci integrationCheck 통과.

Refs: docs/reviews/2026-11-01-maturity-review/README.md 14절
BREAKING CHANGE: JDBC batch 기본 켜짐, H2 운영 의존 제거, 트랜잭션
기본 제한 30초, gRPC·WebSocket·GraphQL 서버 한도 기본값 추가,
샘플 Idempotency-Key 오류 코드 변경.
2026-11-03 19:52:06 +09:00

9.0 KiB

04. 영속성

핵심

저장 adapter는 생성 명령이 만들지 않는다. 이 장의 순서로 만든다. 세 가지를 지킨다.

  1. 엔티티 연관관계는 한쪽에서만 맵핑한다. 빌드가 막는다.
  2. 중복·경쟁은 코드 순서가 아니라 DB 제약이 막고, 위반은 기능의 오류로 바꾼다.
  3. 마이그레이션은 템플릿 운영 스트림과 번호가 겹치지 않는 자기 스트림에 둔다.
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). 예: 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.
    • 여러 인스턴스가 집는 작업 → 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 표를 복사하지 않는다.

마이그레이션 번호

템플릿 운영 스트림      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부터 쓴다.
  • 예외: 템플릿 운영 스트림(db/migration/postgresql)에 직접 넣으면 upstream이 다음에 쓸 번호와 겹친다. 어쩔 수 없으면 upstream이 쓰지 않을 큰 번호대를 정해 문서에 적는다.
  • 이미 적용된 파일은 고치지 않는다. 고치면 체크섬 불일치로 기동이 멈추고, repair는 쓰지 않는다 (docs/jpa/migration-guide.md).
  • 같은 스트림 안에서 기존 두 버전 사이에 끼워야 하면 소수 버전(V8_1)을 쓴다. 샘플 테스트 일부가 운영 스트림과 샘플 스트림을 한 목록으로 합치는데, 정수 V9 이상은 운영이 이미 쓰고 있어서 V8_1을 골랐다 (리뷰 README 13.2, 09-02).
  • 기존 데이터가 새 제약을 어기면 마이그레이션이 이유를 남기고 멈추게 쓴다(V8_1의 DO $$ 블록). 조용히 지우지 않는다.

지금 이해하면 되는 것

  • 저장 adapter는 서비스 전용 persistence leaf에. persistence-jpa에 업무 코드를 넣지 않는다.
  • 중복은 유일성 제약, 경쟁은 트랜잭션 안 claim + lease, 수정 충돌은 버전 열.
  • 마이그레이션은 자기 스트림(자기 history table). 적용된 파일은 고치지 않는다.