fix(env)!: env 계약을 배포 설정 동작에 맞추고 verifyEnvKeys가 그 차이를 잡게 한다 #20

Closed
donghyeon.kang wants to merge 0 commits from claude/r9-env-keys into main
Owner

무엇을, 왜

round9 리뷰의 env 계약 발견 열(RR9-03-03·03-04·03-08·03-10, RR9-02-11, RR9-01-22, RR9-04-29~32)을 한 원인으로 묶어 고친다. docs/registries/env-keys.yaml·.env.example·배포 설정(profile 밖 application.yml, config/*.yml, 모듈 config/module-defaults/*.yml)이 서로 갈렸는데, verifyEnvKeys가 그 차이를 보지 못했다.

  • .env.example을 그대로 복사하면 기동이 실패하는 값 둘: APP_DATASOURCE_CONNECTION_TIMEOUT=5s(Hikari는 long ms), APP_SECURITY_CORS_MAX_AGE=600s(long 초).
  • 기본값과 다른 예시 값 다섯. 특히 FORWARD_HEADERS_STRATEGY=native는 프록시 없는 배포에서 호출자가 보낸 forwarded 헤더를 믿게 한다.
  • registry가 폐기로 적은 키 셋을 cache-redis 모듈 설정이 읽는다. 반대로 폐기 키 45개가 예시에 값과 함께 남았다.
  • 배포 설정이 읽는 APP_ 밖 placeholder 11개에 registry 행이 없었다.

고른 방법과 버린 대안

  • 런타임 동작은 바꾸지 않는다. registry와 예시를 배포 설정에 맞추고, verifyEnvKeys가 다섯을 더 본다: ① registry 행은 접두어와 상관없이 읽는다 ② 배포 설정 placeholder는 접두어와 상관없이 행이 있어야 한다 ③ deprecated_orphaned 행은 배포 설정이 읽지 않고 예시에 없다 ④ 예시 값은 registry default(행에 example이 있으면 그 값)와 같다 ⑤ profile 밖 placeholder 기본값은 registry default와 같다.
  • registry에 example 칸을 두었다(SMTP 587처럼 기본값이 아닌 권장값).
  • 버린 안: SECURITY_PUBLIC_PATHS·PRESENTATION_API_BASE_PATH를 APP_로 바꾸고 옛 이름을 fallback으로 두기. 공개 경로 기본값이 4중 placeholder가 되고 공개 경로 스냅숏 파서까지 바뀐다. 리뷰 README 6절 결정대로 이름은 그대로 등록했다.

위험과 영향

  • 파생 서비스가 자기 placeholder를 등록하지 않았거나 예시 값이 기본값과 다르면 verifyEnvKeys(mainCheck 안)가 새로 실패한다. 할 일은 docs/upgrade/2026-11-round9-env-keys.md.
  • 옛 예시를 복사한 .env는 그대로 남는다. 업그레이드 안내 1~4가 고칠 값을 적는다.

검증

desktop, --no-build-cache, 로그 ~/r9-be-logs/b2-*.log.

  • RED: 기준 a7e38c10 + 시험만으로 EnvContractVerifierTest 22건 중 7건 실패(새 검사 6건 + 메시지를 바꾼 기존 1건).
  • GREEN(마지막 트리 48952198): -p build-logic test, :app-bootstrap:verifyEnvKeys(314 env keys, 6 required placeholders, 370 rows), :app-bootstrap:test --tests '*Registry*' '*Env*' '*SqlLogging*', :app-bootstrap:repositoryContractTest — 231건 실패 0, skip 1, rc=0. 그 전 트리에서 registry·예시를 읽는 leaf 시험(httpclient env manifest, notification mode, redis-runtime, fileserver·notification platform, graphql registry parity, web CORS) 682건 실패 0.
  • 노트북: check-docs.py rc=0. check-work-docs.py는 main의 operate.md 151줄 때문에만 rc=1(PR #15가 고침).

리뷰어가 볼 곳

  • EnvContractVerifier의 shippedDefaults(profile 밖 배포 설정에서 placeholder 기본값을 모으는 곳)와 normalizedValue(빈 줄 = 빈 문자열).
  • registry에서 deprecated_orphaned를 지운 cache-redis 행 셋(upgrade 안내 3절).

관련

  • 리뷰 기록: PR #17 docs/reviews/2026-11-12-round9-review/.
## 무엇을, 왜 round9 리뷰의 env 계약 발견 열(RR9-03-03·03-04·03-08·03-10, RR9-02-11, RR9-01-22, RR9-04-29~32)을 한 원인으로 묶어 고친다. `docs/registries/env-keys.yaml`·`.env.example`·배포 설정(profile 밖 `application.yml`, `config/*.yml`, 모듈 `config/module-defaults/*.yml`)이 서로 갈렸는데, `verifyEnvKeys`가 그 차이를 보지 못했다. - `.env.example`을 그대로 복사하면 기동이 실패하는 값 둘: `APP_DATASOURCE_CONNECTION_TIMEOUT=5s`(Hikari는 long ms), `APP_SECURITY_CORS_MAX_AGE=600s`(long 초). - 기본값과 다른 예시 값 다섯. 특히 `FORWARD_HEADERS_STRATEGY=native`는 프록시 없는 배포에서 호출자가 보낸 forwarded 헤더를 믿게 한다. - registry가 폐기로 적은 키 셋을 cache-redis 모듈 설정이 읽는다. 반대로 폐기 키 45개가 예시에 값과 함께 남았다. - 배포 설정이 읽는 APP_ 밖 placeholder 11개에 registry 행이 없었다. ## 고른 방법과 버린 대안 - 런타임 동작은 바꾸지 않는다. registry와 예시를 배포 설정에 맞추고, `verifyEnvKeys`가 다섯을 더 본다: ① registry 행은 접두어와 상관없이 읽는다 ② 배포 설정 placeholder는 접두어와 상관없이 행이 있어야 한다 ③ `deprecated_orphaned` 행은 배포 설정이 읽지 않고 예시에 없다 ④ 예시 값은 registry `default`(행에 `example`이 있으면 그 값)와 같다 ⑤ profile 밖 placeholder 기본값은 registry `default`와 같다. - registry에 `example` 칸을 두었다(SMTP 587처럼 기본값이 아닌 권장값). - 버린 안: `SECURITY_PUBLIC_PATHS`·`PRESENTATION_API_BASE_PATH`를 APP_로 바꾸고 옛 이름을 fallback으로 두기. 공개 경로 기본값이 4중 placeholder가 되고 공개 경로 스냅숏 파서까지 바뀐다. 리뷰 README 6절 결정대로 이름은 그대로 등록했다. ## 위험과 영향 - 파생 서비스가 자기 placeholder를 등록하지 않았거나 예시 값이 기본값과 다르면 `verifyEnvKeys`(`mainCheck` 안)가 새로 실패한다. 할 일은 `docs/upgrade/2026-11-round9-env-keys.md`. - 옛 예시를 복사한 `.env`는 그대로 남는다. 업그레이드 안내 1~4가 고칠 값을 적는다. ## 검증 desktop, `--no-build-cache`, 로그 `~/r9-be-logs/b2-*.log`. - RED: 기준 `a7e38c10` + 시험만으로 `EnvContractVerifierTest` 22건 중 7건 실패(새 검사 6건 + 메시지를 바꾼 기존 1건). - GREEN(마지막 트리 `48952198`): `-p build-logic test`, `:app-bootstrap:verifyEnvKeys`(314 env keys, 6 required placeholders, 370 rows), `:app-bootstrap:test --tests '*Registry*' '*Env*' '*SqlLogging*'`, `:app-bootstrap:repositoryContractTest` — 231건 실패 0, skip 1, rc=0. 그 전 트리에서 registry·예시를 읽는 leaf 시험(httpclient env manifest, notification mode, redis-runtime, fileserver·notification platform, graphql registry parity, web CORS) 682건 실패 0. - 노트북: `check-docs.py` rc=0. `check-work-docs.py`는 main의 `operate.md` 151줄 때문에만 rc=1(PR #15가 고침). ## 리뷰어가 볼 곳 - `EnvContractVerifier`의 `shippedDefaults`(profile 밖 배포 설정에서 placeholder 기본값을 모으는 곳)와 `normalizedValue`(빈 줄 = 빈 문자열). - registry에서 `deprecated_orphaned`를 지운 cache-redis 행 셋(upgrade 안내 3절). ## 관련 - 리뷰 기록: PR #17 `docs/reviews/2026-11-12-round9-review/`.
donghyeon.kang added 2 commits 2026-11-12 16:49:46 +00:00
문제: 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.
grpc README는 "전용 APP_* 키는 registry에 없다"고 했지만 끄는 값
APP_GRPC_SERVER_ENABLED가 있고, 기동에 꼭 두라는
APP_GRPC_SERVER_ALLOW_INSECURE_LOCAL은 registry에 없었다(앞 커밋이 등록).
cache-redis README는 운영 비밀로 읽는 곳 없는 폐기 키 셋
(APP_CACHE_REDIS_PASSWORD, APP_IDEMPOTENCY_/LEASE_REDIS_KEY_HMAC_SECRET)을
넣으라고 했다. 자격 증명은 APP_REDIS_AUTHENTICATION_*의 secret 참조다.

검증: python3 scripts/check-docs.py rc=0.
donghyeon.kang added 1 commit 2026-11-12 16:55:03 +00:00
Merge branch 'main' into claude/r9-env-keys
pr / done (pull_request) Canceled after 0s
8a0b3004a4
donghyeon.kang added 1 commit 2026-11-12 17:00:31 +00:00
Merge branch 'main' into claude/r9-env-keys
pr / done (pull_request) Canceled after 0s
2958392d20
donghyeon.kang added 1 commit 2026-11-12 18:59:01 +00:00
Merge branch 'main' into claude/r9-env-keys
pr / done (pull_request) Canceled after 0s
d4ba8574d0
Author
Owner

#28로 병합됐다(main 3d31896a). 이 PR의 head d4ba8574가 #28 브랜치에 merge 커밋으로 들어 있고, #28의 runner pr / done이 그 합친 트리로 초록이었다. runner 대기를 줄이려고 이번만 쓴 방식이다(소유자 승인, 2026-11-13).

#28로 병합됐다(main `3d31896a`). 이 PR의 head `d4ba8574`가 #28 브랜치에 merge 커밋으로 들어 있고, #28의 runner `pr / done`이 그 합친 트리로 초록이었다. runner 대기를 줄이려고 이번만 쓴 방식이다(소유자 승인, 2026-11-13).
donghyeon.kang closed this pull request 2026-11-12 23:28:31 +00:00

Pull request closed

Please reopen this pull request to perform a merge.
Sign in to join this conversation.
No Reviewers
No labels
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: donghyeon.kang/clean-architecture-backend-template#20