Files
clean-architecture-backend-…/src/adapter/outbound/cache-redis/CLAUDE.md
T
DongHyeonka 8813b02e54 docs(adapter-outbound): outbound 어댑터 모듈 문서를 한국어로 옮긴다
문제: outbound 어댑터 leaf의 CLAUDE.md 열세 개와 README 아홉 개가
영어이거나 영어 절이 섞여 있다. 열 CLAUDE.md는 Spring Boot 버전
(4.0.0, 4.0.8)을 복사해 두었고 실제 버전(libs.versions.toml)과 다르다.

방법: 뜻을 그대로 옮기고 코드·명령·경로·식별자·설정 키·로그 문자열·
표 구조는 원문으로 둔다. 버전은 `src/gradle/libs.versions.toml`을
가리키게 고친다. 번역하며 본 코드와 어긋난 주장은 코드에 맞춘다:
identifier CLAUDE.md의 `.claude/hooks/ca_import_gate.py`(저장소에 없는
hook)를 registry 방향 게이트로, cache-redis README의 「app-bootstrap
`IdempotencySettings`」를 실제 위치 `composition:idempotency`로,
redis-sdk compose README의 ACL 파일 위치 `acl/`을 lane이 실제로
mount하는 `compose/redis/acl/`로 고친다. persistence-mongo 문서에는
지운 namespace(`spring.data.mongodb.`)를 쓰지 않는다
(MongoNamespaceContractTest가 본다). 다른 영역 문서의 절 제목을 인용한
곳(`docs/jpa/migration-guide.md` "Bound the lock wait" 등)은 그 문서가
아직 영어라 원문 제목으로 둔다.

위험: 인용한 docs/jpa 절 제목은 그 문서를 번역하는 쪽이 제목을 바꾸면
낡는다. 통합 단계에서 맞춰야 한다. ArchUnit 규칙 이름의 대소문자는 다음
커밋에서 맞춘다.

검증: python3 scripts/check-docs.py rc=0(language 줄 19개, number 줄
10개 지움, src/** number 줄 0), check-work-docs.py rc=0,
--links(gates.md 범위) 깨진 링크 0.
2026-11-07 17:24:33 +09:00

16 KiB

adapter:outbound:cache-redis — cache와 Redis 어댑터

등록 정보

  • 모듈 ID: adapter-outbound-cache-redis
  • Gradle 경로: :adapter:outbound:cache-redis
  • 이 모듈만 시험(Gradle 경로에서 나온 명령): ./gradlew :adapter:outbound:cache-redis:test --console=plain
  • 실행 기준: Java 21. 프레임워크 기준인 Spring Boot 버전은 src/gradle/libs.versions.toml이 정한다.
  • registry 정본: src/config/architecture/modules.json.

패키지 루트: dev.caskeleton.adapter.outbound.cache.

책임

  • application-core의 semantic cache 포트를 구현하고, Redis 개념을 core에 드러내지 않는다.
  • 정해진 물리 키, digest, codec·envelope, program catalog, 타입 있는 Redis 원자 창구, runtime client 연결, capability별 실패 뜻을 가진다.
  • semantic cache 포트(CacheRegionPort) 뒤에서 절대 soft·hard 만료, 쓰기 조건, 키 무효화 표지를 구현한다. TTL jitter도 stampede 보호도 없다. single-flight는 호출자의 몫이다. revision 순서는 포트의 CacheSourceRevisionOrder다. Lua 사본은 CacheRegionContract(application-core testFixtures)가 그 순서에 맞추고, RedisCacheRegionContractTest와 LiveRedisCacheRegionContractTest가 그 계약을 상속한다.
  • provider 중립 EdgeRateLimitPort를 전용 조율 Redis 설정, 연결·admission, 전용 키, 버전 있는 원자 program으로 구현한다.
  • 쓰는 쪽이 semantic 포트로 옮기는 동안 옛 cache router를 떼어 둔다.
  • 공용 outbound 관심사는 adapter:outbound:support를 다시 쓴다.
  • semantic 어댑터가 쓰는 공용 topology client, 연결 lifecycle, SemanticRedisCommands 여덟 개, 조건부 Redis runtime 조립은 :adapter:outbound:redis-runtime에 의존한다.
  • 범용 typed SDK는 따로 둔 라이브러리 leaf :adapter:outbound:redis-sdk에 둔다(그 README.md를 본다). 이 leaf는 시험을 포함해 어떤 설정에서도 그것에 의존하지 않는다. SDK의 시험과 lane은 그 leaf에 있다.

Redis 런타임과 골라 쓰는 typed SDK (…cache.redis.runtime, …cache.redis.sdk)

등록된 leaf 둘, 패키지 둘, 방향 하나: SDK는 runtime 위에 서고, runtime은 SDK를 모른다(runtime 안의 RedisRuntimePackageBoundaryTest가 그 방향을 지킨다).

  • :adapter:outbound:redis-runtime은 운영 기반이다: RedisRuntimeSettings 바인딩, credential 해석, topology client, runtime 자신의 lane(RedisConnectionKind.REGULAR, SCRIPT)을 가진 RedisRuntimeOwner, SemanticRedisCommands(이 leaf와 health contributor가 보내는 명령 여덟 개), health. cache-redis가 이 leaf에 의존한다.
  • :adapter:outbound:redis-sdk는 골라 쓰는 범용 typed API를 가진다: RedisCommandGateway(SemanticRedisCommands를 상속), 명령 catalog·정책, operation 예산, 명령 guard, raw·admin surface, programmability, extension — 그리고 자기 lane(RedisSdkLane: blocking, transaction, admin)과 admin 계정. 서비스가 그것을 RedisLaneContribution/RedisAccountContribution bean으로 runtime에 기여한다(RedisSdkComposition). cache-redis는 운영에서도 시험에서도 그것에 의존하지 않는다.
  • 이 leaf의 semantic cache·멱등성·rate-limit·lease 어댑터는 runtime의 SemanticRedisCommands를 자기의 닫힌 semantic program(RegisteredLuaScript)으로 보낸다. CommandPolicyGuard를 지나지 않고, redis-command-policy.yml이 그것을 다루지 않는다.
  • 정확성을 위해 어떤 role에 Redis가 필요한지는 이 leaf의 RedisCorrectnessRoleSelectors가 정하고, META-INF/spring.factories에 runtime의 RedisCorrectnessRequirement로 등록한다.

docs/design/2026-08-07-redis-wrapper-typed-api-design.md가 설명하는 typed SDK는 출하하는 semantic Redis 어댑터의 일부가 아니라 골라 쓰는 라이브러리로 남는다. 전달 상태와 맞춘 이력은 docs/history/plans/2026-08-07-redis-wrapper-typed-api-status.md에 있다.

  • sdk.api..는 공개 계약이다. Spring, Lettuce, Micrometer, SDK 구현 패키지를 import하지 않는다. Reactor는 sdk.api.reactive 안에만 둔다.
  • sdk.lettuce..가 계약을 구현한다. sdk.config는 속성, capability probe, 허가 정본을 가진다.
  • :adapter:outbound:redis-sdk/src/main/resources/redis-sdk/redis-command-policy.yml이 골라 쓰는 typed SDK의 명령 정책 정본이다. 거기 분류되지 않은 typed SDK 명령은 거절한다. 이 leaf의 semantic capability 어댑터를 위한 정책 파일이 아니다.
  • sdk.lettuce.operations가 타입 있는 operation을 구현한다. 거기 있는 모든 것은 Lettuce에 닿는 유일한 이음매인 RedisCommandGateway를 거치고, 모든 호출은 돌기 전에 CommandPolicyGuard의 허가를 받는다. operation에서 driver를 직접 부르지 않는다.
  • sdk.cluster는 client 쪽 slot 계산과 cluster 관찰을 가진다. sdk.api에만 의존하고 Lettuce를 import하지 않는다: slot을 명령을 만들기 전에 계산하므로 CommandPolicyGuard가 서버 redirect로 알게 되기 전에 cross-slot 요청을 거절할 수 있다.
  • sdk.programmability는 트랜잭션, 등록된 Lua script, 배포된 function 호출을 가진다. 호출 때 script 본문을 받지 않는다: catalog가 EVAL을 막고 RedisScriptRegistry digest의 EVALSHA만 닿을 수 있다. FUNCTION LOAD는 애플리케이션이 아니라 admin plane이다.
  • 트랜잭션은 WATCH/MULTI/EXEC이고 절대 롤백하지 않는다. TransactionResult는 「실행됨」이나 「감시한 키가 바뀌어서 아무것도 돌지 않음」만 알리고, 이 패키지의 어떤 타입도 다른 뜻을 비치는 말을 주지 않는다. 줄 세운 명령은 QueuedReply를 돌려주고, 커밋 전에 읽으면 던진다. 그 창 안에서 서버는 +QUEUED만 답했기 때문이다. 줄 세운 명령도 보통 명령과 같은 CommandPolicyGuard 허가를 지난다 — 트랜잭션은 guard를 피하는 길이 아니다 — 그리고 창은 던진 callback을 포함해 모든 출구에서 닫는다. MULTI 상태로 버려진 연결은 다음 호출자의 명령을 소리 없이 줄 세우기 때문이다. queue는 일부러 쓰기 전용이다: 창 안의 읽기로는 분기할 수 없으니, 트랜잭션이 기대는 읽기는 그 앞에서 WATCH 아래에 둔다.
  • sdk.raw는 승인된 raw 명령 gateway다. catalog가 RAW_ONLY로 표시했고 그리고 배포가 그 명령에 ApprovedRawCommand를 등록했을 때만 닿을 수 있다. 보내기 전에 인자에서 키를 다시 파싱해 namespace를 검사한다. 명령 이름을 문자열로 받는 메서드를 여기 더하지 않는다.
  • sdk.admin은 읽기 전용 진단 plane이다. 자기 gateway(admin ACL 계정, 자기 연결)를 받고, catalog가 ADMIN_ONLY이자 읽기 전용으로 분류하지 않은 명령은 모두 거절하며, slow log나 client 목록이 인자·상대 주소·연결 이름을 싣지 않게 응답을 걸러 낸다.
  • sdk.extensions.*는 Redis 8 모듈(JSON, Search, Time Series, Probabilistic)을 담는다. 모든 bean은 ifSupported(...)로 만든다 — capability probe가 정하고, catalog 최소값은 앞 걸러내기일 뿐이다 — 그리고 모두 ExtensionCommandRunner로 명령을 만들어 guard가 그 키를 본다. Search는 이것을 보여 주는 예외다: index는 키가 아니라서 그 이름은 LettuceRedisSearchOperations가 직접 namespace를 붙인다.
  • RedisSdkModuleBoundaryTest(redis-sdk 안)가 redis-sdk 소스 루트를 scan해 내부 패키지 그래프, driver 가두기, 아무 문자열 명령 surface 없음, 설계한 모듈 목록을 강제한다.
  • 설계를 다시 보지 않고 바꾸면 안 되는 결정: 한계 없는 entries, members, rangeAll, keys 없음. 선택 사항인 R2 허가·예산 없음. 아무 명령 문자열을 받는 overload 없음. timeout 뒤 멱등이 아닌 쓰기의 자동 재시도 없음. metric이나 trace tag에 실제 키 없음.

경계

  • 허용 의존 edge는 이 모듈의 src/config/architecture/modules.json 항목에서만 온다.
  • inbound 전송, 영속 엔티티·repository, bootstrap, 샘플 의존이 없다.
  • cache 어댑터는 업무상 신선도, 자격, 도메인 대체 규칙을 정하지 않는다.
  • Redis 물리 TTL은 인코딩한 hard 만료와 같아야 한다. 미래·손상 schema가 보통 miss로 뭉개지면 안 된다.
  • application·domain 코드는 raw Redis 키, 명령, Lua·Function 이름, SDK 객체, topology, 연결 타입을 받으면 안 된다.
  • cache의 fail-open 동작을 session, 멱등성, 엄격한 quota, lease, fencing에 다시 쓰면 안 된다.
  • rate-limit 조립은 app.cache.redis, 그 연결, 외부 client 모드, 실패하면 열리는 뜻을 다시 쓰면 안 된다. v1은 조율 role이고 실패하면 닫히는 것뿐이다.
  • standalone runtime·cache 서비스 lane은 R1 증거일 뿐이다. Sentinel·Cluster, TLS·ACL, 영속·재시작, eviction, 장애 증거는 R2를 위해 따로 필요하다.

테스트

이 모듈만 보는 시험은 semantic 어댑터를 testFixtures(project(':adapter:outbound:redis-runtime'))의 InMemorySemanticRedisCommands에 대고 돌린다. SemanticRedisCommands의 유일한 fake이고, StubRedisRuntimeClient를 거쳐 쓴다. R1·R2 승격에는 따로 실제 Redis 서비스 lane이 필요하다. 그 lane을 골랐으면 소리 없이 건너뛰면 안 된다.

실제 서버 lane이 둘 있다. redisContainerContractTest(integration category, integrationCheck에만 있다 — 이 leaf의 mainCheck에도 있었을 때는 main push마다 두 번 돌았다)는 Testcontainers로 자기 Redis를 띄운다 — config/testing/container-images.properties의 redis image이고 compose/redis/acl/lane-fixture-accounts.acl을 읽어 들인다 — 그리고 LiveRedisCacheRegionContractTest, LiveRedisDistributedLeaseContractTest, LiveRedisIdempotencyStoreContractTest(메모리 fake도 통과하는 application-core 포트 계약), LiveRedisSemanticPortsTest, LiveRedisSemanticScriptAclProbeTest를 돌린다. 건너뛰기가 있으면 실패한다 (2026-11-01부터). 멱등성 계약은 2026-11-03까지 명시할 때만 도는 topology lane에만 있었다. 그래서 Lua 상태 기계의 낡은 handle, 갱신 거절, 재시도 경우가 어느 게이트에서도 실제 서버에 닿지 않았다. RedisTestContainer는 그 lane이 ACL 파일을 이름으로 댈 때만 서버를 띄운다.

redisTopologyTest는 외부 topology lane이고 ca.redis-topology-lane으로 선언한다. 이 leaf는 standalone과 cluster(LiveRedisSemanticPortsTest, LiveRedisSemanticScriptAclProbeTest)를 선언한다. redis-runtime과 redis-sdk는 자기 클래스에 대해 자기 lane을 선언한다. 고를 때만 돌고 실패하면 닫힌다: 모드는 standalone, sentinel, cluster, tls 중 이 leaf가 선언한 것이어야 하고, endpoint 속성이 있어야 하며(sentinel은 redis.topology.master가, tls는 redis.topology.trust-material이 더 필요하다), 시험을 하나도 찾지 못하거나 돌리지 않은 실행은 실패하고(그것은 이 leaf가 아니라 규약이 가진다), leaf가 redisTopologyLane에 적은 클래스가 실제로 돌았어야 하며, 건너뛴 시험은 실행한 것으로 세지 않고 실행을 실패시킨다. tls는 배포 모드가 아니라 lane이다 — 모양은 standalone이고 태스크가 그렇게 대응시킨다. 검증하는 것이 전송이기 때문이다.

예전 검사 둘은 없어졌다. 시험 소스에서 글자 그대로 @Tag("redis-topology")를 찾는 scan은 failOnNoDiscoveredTests가 이미 내는 실패의 메시지를 낫게 할 뿐이었고, 같은 글을 담은 주석으로도 만족됐다. 손으로 관리하던 모드별 실행 수 하한(20/20/24/4)은 경우를 더하거나 뺄 때마다 고쳐야 했고, 그것이 잡는 「덮는 범위가 줄었다」는 런타임·배포·데이터·보안·컴파일 실패가 아니다.

조립

RedisRuntimeAutoConfiguration은 이제 :adapter:outbound:redis-runtime의 것이다. Redis 설정과 공용 runtime 기반이 생기는 유일한 곳이고, app.redis.enabled(env APP_REDIS_ENABLED, 기본 true — 모듈이 있으면 켜진다)가 true인 동안에만 있다. topology client, 연결 owner, health contributor를 만든다. 이 leaf의 RedisCapabilityConfig(자기 AutoConfiguration.imports)가 그 runtime 위에 semantic 포트를 조립한다.

골라 쓰는 :adapter:outbound:redis-sdk는 출하하는 애플리케이션이 자동으로 조립하지 않는다. 그 RedisStartupProbe는 라이브러리 API이고 숨은 운영 guard가 아니다. 특히 APP_REDIS_ACKNOWLEDGED_WRITE_LOSS_ACCEPTED 스위치는 없다: 그 거래를 받아들이는 것은 운영 호출자가 없는 공개 설정이 아니라 probe를 부르는 곳의 명시한 인자여야 한다.

모든 capability는 CapabilityKeyspace를 거쳐 app.redis.namespace의 namespace 하나 — {environment}:{service}:{domain} — 아래에 키를 만든다. capability에 자기 접두어 token을 주지 않는다: capability 넷이 각자 자유 문자열 둘을 이어 붙였더니 키 모양이 넷이 됐고, 배포의 ACL pattern은 그중 어느 것과도 맞지 않았다.

lane은 서로 다른 계정으로 인증한다. RedisLane.account()가 lane의 RedisAccount를 이름으로 대고, topology factory는 설정한 계정마다 client를 하나 만든다 — 그래서 계정이 하나인 배포는 여전히 client 하나와 event loop 하나만 가진다. SCRIPT lane이 그것이 있는 이유다: SCRIPT LOAD와 EVALSHA는 advanced 계정의 것이라서, cache 항목을 읽는 계정은 script를 실행할 수 없다.

cache의 조건부 쓰기는 같은 계정이지만 자기 lane CacheScriptLane.CACHE_SCRIPT에서 돈다 (app.capabilities.cache.maximum-script-connections, RedisCacheConfig가 RedisLaneContribution으로 기여한다). SCRIPT로 되돌리지 않는다: 그 lane은 멱등성·rate-limit·lease의 예산이고, 부하를 받는 cache가 그것을 가져가면 안 된다(2026-11-03에 정함). lane마다 기다림, 거절, 재연결은 redis-runtime의 meter(RedisLaneMetrics, redis.lane.*, tag lane)이다. 그래서 cache가 SCRIPT를 쓰지 않는지는 짐작이 아니라 조회로 안다. DEGRADED health 순서는 redis-runtime과 함께 나가고, 그 leaf가 상태를 알린다(config/module-defaults/redis-runtime.yml).

Cluster 트랜잭션은 노드 하나에서 돈다. 그래서 SDK의 RedisTransactionRunner는 감시한 키(또는 명시한 RedisSlotTag)에서 routing 키를 끌어내고, 그 slot을 가진 노드에서 키의 주인에 고정된 RedisSdkLane.TRANSACTION을 빌린다. route된 lease는 pool에 두지 않는다: pool에 둔 연결은 앞 호출자의 노드에 고정되어 있다.

설정 바인딩은 capability 기준 4(접두어 하나, StrictSettingsBinder)의 기록된 예외다(2026-11-03에 정함): app.redis.*는 redis-runtime이 setter와 validate()로 바인딩한다. 그 leaf는 프로젝트 의존이 없어서 StrictSettingsBinder(support)에 닿을 수 없기 때문이다. app.capabilities.*(cache, lease, rate-limit provider)는 이 leaf가 공용 capability 선택 루트 아래에서 엄격하게 바인딩한다. app.rate-limit.*은 이 leaf가 읽기만 하는 HTTP 경계의 스위치다. 키 이름을 바꾸면 동작 이득 없이 모든 배포의 환경이 깨지니 세 트리를 그대로 둔다. 새 Redis 설정은 그중 하나에 넣고, 네 번째 트리를 만들지 않는다.

RedisRuntimeSettings에는 클래스 수준 @ConfigurationProperties를 달면 안 된다: RedisRuntimeAutoConfiguration이 그것을 바인딩하므로 APP_REDIS_ENABLED=false이면 Redis 설정을 하나도 바인딩하지 않는다. 이 패키지에 닿는 properties scan은 그래도 그것을 바인딩하게 된다(bootstrap의 @ConfigurationPropertiesScan은 dev.caskeleton.bootstrap.* 패키지만 적는다). role 선택자(cache 바인딩, session 인증 모드, 멱등성·lease·rate-limit provider)는 어떤 capability를 조립할지 고른다. 그중 어느 것도 Redis를 켜지 않고, 전역 스위치가 꺼져 있으면 이 모듈은 bean을 하나도 기여하지 않는다.