Files
clean-architecture-backend-…/docs/upgrade/2026-11-round9-env-keys.md
T
DongHyeonka bd17bf1f00 fix(env)!: env 계약을 배포 설정 동작에 맞추고 verifyEnvKeys가 그 차이를 잡게 한다
문제: docs/registries/env-keys.yaml·.env.example·배포 설정(profile 밖의
application.yml, config/*.yml, 모듈 module-defaults)이 서로 갈렸고
verifyEnvKeys는 그 차이를 보지 못했다.
- .env.example을 복사하면 기동이 실패하는 값이 있었다:
  APP_DATASOURCE_CONNECTION_TIMEOUT=5s(Hikari long ms, registry 주석이
  "기동 실패"라고 적은 그 값), APP_SECURITY_CORS_MAX_AGE=600s(long 초).
- 기본값과 다른 예시 값: cache·rate-limit Redis command timeout(2s·1s vs
  200ms), APP_LOG_LEVEL_SQL(WARN vs INFO), FORWARD_HEADERS_STRATEGY(native
  vs none — 프록시 없는 배포에서 forwarded 헤더를 믿게 된다),
  POSITIVE_SOFT_TTL(빈 줄 — 빈 문자열이 기본값을 덮는다).
- registry가 폐기(deprecated_orphaned)로 적은 키 셋을 cache-redis 모듈 설정이
  읽는다(COMMAND_TIMEOUT, SEMANTIC_REGION, KEY_HMAC_SECRET 참조).
- 폐기 키 45개가 .env.example에 값과 함께 남아, 복사하면 아무 일도 하지 않는
  값을 켠 것으로 믿는다. 검사가 오히려 registry의 모든 APP_ 행을 예시에
  요구해 폐기 행도 넣게 했다.
- 배포 설정이 읽는 APP_ 밖 placeholder 11개(SECURITY_PUBLIC_PATHS,
  PRESENTATION_API_BASE_PATH, SPRING_JACKSON_DESER_* 등)에 registry 행이
  없었다. 검사가 APP_ 이름만 보고, registry 파서도 APP_ 행만 읽어
  MANAGEMENT_SERVER_ADDRESS 같은 행이 보이지 않았다.
- .env.example 머리말은 "빈 키는 기본값을 쓴다", "Seven values"라고 적었다.

고른 방법: 런타임 동작은 바꾸지 않고 registry와 예시를 배포 설정에 맞춘다.
그리고 verifyEnvKeys가 다섯을 더 본다.
1. registry 행은 접두어와 상관없이 읽는다.
2. 배포 설정의 placeholder는 접두어와 상관없이 행이 있어야 한다.
3. deprecated_orphaned 행은 배포 설정이 읽지 않고 .env.example에 없다.
4. .env.example 값은 registry default(행에 example이 있으면 그 값)와 같다.
   빈 줄은 빈 문자열로 본다.
5. profile 밖 배포 설정의 placeholder 기본값은 registry default와 같다.
registry에 example 칸을 두었다(SMTP 587·timeout처럼 기본값이 아닌 권장값).
APP_ 밖 이름 11개는 지금 이름 그대로 등록했다. 바꾸면 파생 서비스의 배포
env가 소리 없이 무시된다. 이름 변경은 소유자 결정이다. registry 머리말을
실제 규칙(SPRING_·MANAGEMENT_·SERVER_·OTEL_ 이름공간과 옛 이름 둘)으로
고쳤다. gRPC를 켜려면 꼭 두는 APP_GRPC_SERVER_ALLOW_INSECURE_LOCAL과
.env.example의 MANAGEMENT_SERVER_ADDRESS를 더했다.
버린 대안: SECURITY_PUBLIC_PATHS·PRESENTATION_API_BASE_PATH를 APP_로 바꾸고
옛 이름을 fallback으로 두기 — 공개 경로 기본값이 4중 placeholder가 되고
공개 경로 스냅숏 파서까지 바꿔야 한다. 이름 정리는 따로 정한다.

위험·한계: 파생 서비스가 자기 placeholder를 등록하지 않았거나 예시 값이
기본값과 다르면 이제 verifyEnvKeys(mainCheck)가 실패한다(upgrade 안내 5·6).
예시 값이 바뀌어 옛 예시를 복사한 .env는 그대로 둔다 — 안내 1~4가 고칠
값을 적는다.

검증(desktop, --no-build-cache):
- RED: 기준 a7e38c10 + 시험만으로 EnvContractVerifierTest 22건 중 7건 실패
  (새 검사 6건 + 메시지를 바꾼 기존 1건). 새 지킴 시험(example 행 통과)은
  기준에서도 통과.
- GREEN: -p build-logic test, :app-bootstrap:verifyEnvKeys(314 env keys, 6
  required placeholders, 370 rows), :app-bootstrap:test·repositoryContractTest·
  documentContractTest, registry·예시를 읽는 leaf 시험(httpclient env
  manifest, notification mode, redis-runtime required_when, support,
  fileserver·notification platform, graphql registry parity, web CORS)
  682건 실패 0, skip 5. rc=0.

BREAKING CHANGE: verifyEnvKeys가 접두어 밖 placeholder, 폐기 행의 사용,
예시·기본값 차이를 실패로 본다. .env.example에서 폐기 키가 빠지고 값 여덟이
기본값으로 바뀌었다. 할 일은 docs/upgrade/2026-11-round9-env-keys.md.
2026-11-13 01:48:48 +09:00

4.2 KiB

업그레이드 안내 — 2026-11 env 키 계약 정리

  • 범위: docs/registries/env-keys.yaml·.env.example·verifyEnvKeys를 배포 설정의 실제 동작에 맞춘 변경. 앱이 읽는 키와 그 기본값은 바뀌지 않았다. 바뀐 것은 예시 파일의 값, registry 행, 그리고 검사가 실패로 보는 범위다.
  • 근거: 2026-11-12 전체 리뷰(docs/reviews/2026-11-12-round9-review/)의 env 계약 발견

1. 누가 읽나

이 템플릿을 upstream remote로 두고 merge해 받는 파생 서비스가 읽는다. 특히 예전 .env.example을 복사해 .env나 배포 env를 만든 서비스, 자기 배포 설정에 placeholder를 더한 서비스다.

2. 할 일

# 할 일 안 하면 해당 서비스
1 옛 .env.example에서 복사한 APP_DATASOURCE_CONNECTION_TIMEOUT=5s를 5000(밀리초)으로 바꾼다 JPA를 켠 배포가 Hikari 바인딩 실패로 기동하지 않는다 persistence-jpa 선택
2 옛 예시의 APP_SECURITY_CORS_MAX_AGE=600s를 600(초)으로 바꾼다 dev·prod 기동이 app.cors.max-age-seconds 바인딩 실패로 멈춘다(local은 profile 리터럴이 덮어 안 보인다) 예시를 복사한 서비스
3 옛 예시에서 복사한 값 다섯을 확인한다: APP_CACHE_REDIS_COMMAND_TIMEOUT=2s, APP_RATE_LIMIT_REDIS_COMMAND_TIMEOUT=1s, APP_LOG_LEVEL_SQL=WARN, APP_SERVER_FORWARD_HEADERS_STRATEGY=native, APP_CACHE_REDIS_POSITIVE_SOFT_TTL=(빈 값). 새 예시는 기본값(200ms, 200ms, INFO, none, 30s)을 쓴다 그 값들이 env가 없을 때와 다르게 동작한다. 특히 native는 프록시를 거치지 않는 배포에서 호출자가 보낸 forwarded 헤더를 믿는다 예시를 복사한 서비스
4 .env·배포 env에 남은 deprecated_orphaned 키(예: APP_CACHE_REDIS_TTL_JITTER, APP_SESSION_IDLE_TIMEOUT, APP_CACHE_REDIS_L1_*)를 지운다. 무엇이 대신하는지는 registry 행 주석에 있다 아무 일도 하지 않는 값을 켠 것으로 믿는다 예시를 복사한 서비스
5 서비스가 배포 설정(profile 파일 밖의 application.yml, config/*.yml, 모듈 config/module-defaults/*.yml)에 더한 placeholder는 접두어와 상관없이 registry에 행을 더하고, 행의 default를 placeholder 기본값과 같게 둔다 :app-bootstrap:verifyEnvKeys(mainCheck 안)가 실패한다 자기 placeholder를 더한 서비스
6 .env.example의 값을 registry default(또는 행의 example)와 같게 둔다. 기본값이 있는 키를 빈 줄로 두지 않는다 같은 검사가 실패한다 자기 키를 예시에 더한 서비스

3. 다시 살린 registry 행

아래 셋은 2026-08-10 폐기로 적혀 있었지만, 2026-09-25 capability 포장 뒤로 cache-redis 모듈 설정이 다시 읽는다. deprecated_orphaned를 지우고 기본값을 모듈 설정에 맞췄다.

키 읽는 곳 기본값
APP_CACHE_REDIS_COMMAND_TIMEOUT app.capabilities.cache.command-timeout 200ms(registry가 2s라고 적었다)
APP_CACHE_REDIS_SEMANTIC_REGION app.capabilities.cache.semantic-region default
APP_CACHE_REDIS_KEY_HMAC_SECRET secret://environment/APP_CACHE_REDIS_KEY_HMAC_SECRET 참조 없음(비밀)

4. 새로 등록한 이름

배포 설정이 읽는데 registry에 없던 이름이다. 이름은 그대로이고 동작도 같다.

  • SECURITY_PUBLIC_PATHS, PRESENTATION_API_BASE_PATH — APP_ 통일 전에 퍼진 이름이다. 바꾸면 파생 서비스의 배포 env가 소리 없이 무시되어 그대로 둔다.
  • SPRING_BANNER_MODE, SPRING_JACKSON_DESER_* 넷, SPRING_JACKSON_SER_WRITE_DATES_AS_TIMESTAMPS, SPRING_MAIN_LAZY_INITIALIZATION, SPRING_MAIN_LOG_STARTUP_INFO, SPRING_THREADS_VIRTUAL_ENABLED — application.yml placeholder 이름이다. Spring relaxed 이름도 같은 속성을 덮고, 둘 다 있으면 relaxed 이름이 이긴다.
  • APP_GRPC_SERVER_ALLOW_INSECURE_LOCAL — gRPC 모듈을 켠 배포가 기동하려면 true로 명시하는 값이다.
  • .env.example에 MANAGEMENT_SERVER_ADDRESS=127.0.0.1을 더했다. Kubernetes 프로브와 Prometheus는 pod IP로 붙으므로 원격에서 읽으려면 이 값을 바꾼다.