docs(src): src/README를 「~한다」체로 맞추고 Compose 최소 버전은 정본을 가리킨다
src/README.md가 「~합니다」체다(끝맺음 215곳, 「~한다」는 번역 묶음이 고친 두 문장뿐). docs/README.md 「문서 수명과 언어」는 살아 있는 문서의 문체를 「~한다」로 정하고 한 문서 안에서 섞지 않게 한다. 번역 묶음(D2a)이 이 문서의 영어 제목·문장만 맡아 문체는 범위 밖으로 넘겼다. - 끝맺음만 바꿨다. 낱말 111개를 하나씩 대응표로 바꾸고(합니다 → 한다, 입니다 → 이다·다, 형용사는 하다·다: 견고하다, 필요하다, 다르다, 크다, 쉽다, 같다, 「있지 않습니다」 → 「있지 않다」, 「~세요」 → 「~한다」), 바뀐 195줄을 한 줄씩 읽었다. 줄 수(577)와 다른 글자는 그대로다. - 「Docker Compose 최소 버전 `2.24.4`」가 정본 (compose-profile-contracts.json의 minimumComposeVersion)을 옆에 적고도 값을 복사했다. 값을 지우고 정본 키를 가리킨다. 버린 대안: 문체를 그대로 두고 규칙 쪽에 예외를 두기. 한 파일만 다른 문체를 허용할 근거가 없다. 이 문서를 글자 그대로 읽는 테스트는 없다(git grep 'src/README' — 링크 검사 범위 목록 테스트 하나만 경로를 적는다). 검증(노트북): check-docs.py OK, 「~니다」 끝맺음 남은 수 0(「아니다」 제외).
This commit is contained in:
+195
-195
@@ -1,24 +1,24 @@
|
||||
# src — 빌드 스크립트 / 환경 변수 참조
|
||||
|
||||
`src/` 는 Gradle 멀티모듈 루트입니다. 모듈 경계·의존 방향 규칙은 루트 [CLAUDE.md](../CLAUDE.md)
|
||||
와 [AGENTS.md](../AGENTS.md), 모듈별 규칙은 각 모듈의 `CLAUDE.md` 가 SSOT 입니다.
|
||||
`src/` 는 Gradle 멀티모듈 루트다. 모듈 경계·의존 방향 규칙은 루트 [CLAUDE.md](../CLAUDE.md)
|
||||
와 [AGENTS.md](../AGENTS.md), 모듈별 규칙은 각 모듈의 `CLAUDE.md` 가 SSOT이다.
|
||||
|
||||
이 문서는 [build.gradle](build.gradle) 과 [.env.example](.env.example)(복사해 `.env` 로 씀) 의 코드 주석에서 덜어낸 **설정 항목 설명과
|
||||
결정 근거**를 모아둔 참조용 기록입니다. 두 파일에는 짧은 기능 주석과 "자세한 내용은 README 참조"
|
||||
포인터만 남기고, "왜 이렇게 했나"는 여기서 풀어 설명합니다.
|
||||
결정 근거**를 모아둔 참조용 기록이다. 두 파일에는 짧은 기능 주석과 "자세한 내용은 README 참조"
|
||||
포인터만 남기고, "왜 이렇게 했나"는 여기서 풀어 설명한다.
|
||||
|
||||
---
|
||||
|
||||
## build.gradle — 빌드 / 검증 게이트
|
||||
|
||||
검증은 로컬 피드백과 저장소 전체 검증을 분리합니다. `:<leaf>:check`는 해당 모듈의 컴파일,
|
||||
테스트, Spotless, Checkstyle, Error Prone만 담당합니다. 저장소 전체 정책은 이름이 드러나는
|
||||
루트 task로 실행하며, CI가 이를 집계합니다.
|
||||
검증은 로컬 피드백과 저장소 전체 검증을 분리한다. `:<leaf>:check`는 해당 모듈의 컴파일,
|
||||
테스트, Spotless, Checkstyle, Error Prone만 담당한다. 저장소 전체 정책은 이름이 드러나는
|
||||
루트 task로 실행하며, CI가 이를 집계한다.
|
||||
|
||||
이 셋의 역할은 겹치지 않습니다. Spotless(google-java-format)가 포맷과 import 순서를 소유하고,
|
||||
Checkstyle은 **포매터가 표현할 수 없는 것만** — 네이밍과 몇 가지 논리/설계 규칙만 — 봅니다
|
||||
이 셋의 역할은 겹치지 않는다. Spotless(google-java-format)가 포맷과 import 순서를 소유하고,
|
||||
Checkstyle은 **포매터가 표현할 수 없는 것만** — 네이밍과 몇 가지 논리/설계 규칙만 — 본다
|
||||
(`config/checkstyle/checkstyle.xml`). 줄 길이·들여쓰기·import 순서 모듈이 여기에 없는 것은 누락이
|
||||
아니라 포매터와 싸우지 않기 위한 선택입니다. Error Prone은 컴파일 시점 버그 패턴을 담당합니다.
|
||||
아니라 포매터와 싸우지 않기 위한 선택이다. Error Prone은 컴파일 시점 버그 패턴을 담당한다.
|
||||
|
||||
| 게이트 | 하는 일 |
|
||||
| --- | --- |
|
||||
@@ -34,8 +34,8 @@ Checkstyle은 **포매터가 표현할 수 없는 것만** — 네이밍과 몇
|
||||
| `releaseCheck` | tag 전용 검사: `verifyReleaseProvenance` + `verifyPublicPathSnapshot`(`ci`를 다시 돌리지 않음) |
|
||||
|
||||
따라서 로컬에서 한 모듈만 수정했다면 `./gradlew :domain-core:check`처럼 focused task를
|
||||
먼저 사용합니다. 전체 기동 qualification은 일반 leaf `check`나 `:app-bootstrap:build`에
|
||||
매달지 않고 `qualificationCheck`/`mainCheck`에서 실행합니다.
|
||||
먼저 사용한다. 전체 기동 qualification은 일반 leaf `check`나 `:app-bootstrap:build`에
|
||||
매달지 않고 `qualificationCheck`/`mainCheck`에서 실행한다.
|
||||
|
||||
**2026-09에 삭제한 게이트.** `verifyOneTypePerFile`(Checkstyle의 `OneTopLevelClass`가 같은 규칙을
|
||||
파싱된 파일에 대해 검사한다), `verifyTrivyignore`·`verifyQuarantineSunset`(빈 레지스트리를 지키는
|
||||
@@ -47,65 +47,65 @@ Checkstyle은 **포매터가 표현할 수 없는 것만** — 네이밍과 몇
|
||||
### 로컬 첫 실행
|
||||
|
||||
`scripts/bootstrap-local.sh`(저장소 루트)은 compile → Docker 확인 → DB 기동 대기 →
|
||||
app 기동(Flyway 포함) → health smoke를 순서대로 실행합니다(예전 `./gradlew bootstrap`, 리뷰
|
||||
app 기동(Flyway 포함) → health smoke를 순서대로 실행한다(예전 `./gradlew bootstrap`, 리뷰
|
||||
BUILD-O3-5로 build-logic 플러그인에서 스크립트로 옮김).
|
||||
DB와 app lifecycle은 저장소 루트의 개발 compose 파일 `compose.yaml`(`db`는 `jpa` profile)이 소유하며, app startup Flyway가
|
||||
끝나 public health endpoint가 준비되어야 다음 단계로 넘어갑니다. `src/.env.example`은 커밋된
|
||||
env 계약이고 `src/.env`는 로컬 실행 입력입니다. `verifyEnvKeys`는 example/registry/shipped YAML을
|
||||
함께 검사합니다.
|
||||
끝나 public health endpoint가 준비되어야 다음 단계로 넘어간다. `src/.env.example`은 커밋된
|
||||
env 계약이고 `src/.env`는 로컬 실행 입력이다. `verifyEnvKeys`는 example/registry/shipped YAML을
|
||||
함께 검사한다.
|
||||
|
||||
### 추적 가능한 버전과 의존성 잠금
|
||||
|
||||
- leaf version은 release version뿐입니다(`-PreleaseVersion`/`RELEASE_VERSION`, 기본 `0.0.1`).
|
||||
revision(`-PgitRevision`/`GIT_SHA`/`GITHUB_SHA`)을 모르면 `-SNAPSHOT`이 붙습니다. revision은 jar
|
||||
- leaf version은 release version뿐이다(`-PreleaseVersion`/`RELEASE_VERSION`, 기본 `0.0.1`).
|
||||
revision(`-PgitRevision`/`GIT_SHA`/`GITHUB_SHA`)을 모르면 `-SNAPSHOT`이 붙는다. revision은 jar
|
||||
이름에 넣지 않고 각 jar manifest의 `Build-Revision`과 app-bootstrap의
|
||||
`META-INF/build-info.properties`(`build.revision`)에 남깁니다. 예전에는 version이
|
||||
`META-INF/build-info.properties`(`build.revision`)에 남긴다. 예전에는 version이
|
||||
`<MAJOR>.<MINOR>.<PATCH>+<sha>`라 커밋마다 새 jar 이름이 생겼고 그 잔여물을 `ca.archive-hygiene`이
|
||||
치웠는데, 둘 다 없앴습니다(리뷰 BUILD-O3-5).
|
||||
치웠는데, 둘 다 없앴다(리뷰 BUILD-O3-5).
|
||||
- `releaseCheck`가 실행하는 `verifyReleaseProvenance`(루트 `build.gradle`, revision 판정은
|
||||
`ca.java-conventions`와 같은 함수)는 source revision이 없으면 실패하므로 추적 불가능한 산출물을
|
||||
release로 취급할 수 없습니다. 예전 `ca.release-provenance` 플러그인은 없앴습니다(리뷰 BUILD-O3-5).
|
||||
release로 취급할 수 없다. 예전 `ca.release-provenance` 플러그인은 없앴다(리뷰 BUILD-O3-5).
|
||||
- 모든 subproject가 `lockAllConfigurations()` + `LockMode.STRICT`를 사용하고, lock state는 Gradle
|
||||
기본 `<module>/gradle.lockfile`에 둡니다. 이 경로는 Renovate Gradle manager 기본 인식 경로와
|
||||
같습니다.
|
||||
- lock 갱신은 `./gradlew resolveAndLockAll --write-locks` 한 가지 명령으로 수행합니다. 이 task는
|
||||
`--write-locks`가 없으면 실패하며, 일반 build가 lock state를 조용히 다시 쓰지 못하게 합니다.
|
||||
기본 `<module>/gradle.lockfile`에 둔다. 이 경로는 Renovate Gradle manager 기본 인식 경로와
|
||||
같다.
|
||||
- lock 갱신은 `./gradlew resolveAndLockAll --write-locks` 한 가지 명령으로 수행한다. 이 task는
|
||||
`--write-locks`가 없으면 실패하며, 일반 build가 lock state를 조용히 다시 쓰지 못하게 한다.
|
||||
|
||||
### 재현 가능한 아카이브 (D10)
|
||||
|
||||
모든 `AbstractArchiveTask`는 file timestamp 보존을 끄고, file order를 재현 가능하게 정렬하며,
|
||||
directory/file mode를 각각 `0755`/`0644`로 고정합니다. Java toolchain은 21이고 로컬·CI patch
|
||||
version은 root `.tool-versions`의 Temurin 값으로 맞춥니다.
|
||||
directory/file mode를 각각 `0755`/`0644`로 고정한다. Java toolchain은 21이고 로컬·CI patch
|
||||
version은 root `.tool-versions`의 Temurin 값으로 맞춘다.
|
||||
|
||||
archive task 자체는 timestamp 비보존·재현 가능한 file order·고정 mode를 강제합니다. 현재 저장소에는
|
||||
archive task 자체는 timestamp 비보존·재현 가능한 file order·고정 mode를 강제한다. 현재 저장소에는
|
||||
별도의 `verify-reproducible-build.sh`가 없으므로 byte-for-byte 이중-build 비교를 자동 게이트라고
|
||||
주장하지 않습니다. 릴리스 검증의 정본 진입점은 `./gradlew releaseCheck`와
|
||||
`.github/workflows/release.yml`입니다.
|
||||
주장하지 않는다. 릴리스 검증의 정본 진입점은 `./gradlew releaseCheck`와
|
||||
`.github/workflows/release.yml`이다.
|
||||
|
||||
### `-parameters` 컴파일러 플래그
|
||||
|
||||
- **결정.** 모든 subproject 의 Java 컴파일에 `-parameters` 플래그를 직접 설정합니다.
|
||||
- **결정.** 모든 subproject 의 Java 컴파일에 `-parameters` 플래그를 직접 설정한다.
|
||||
- **근거.** Spring MVC 는 `@PathVariable` / `@RequestParam` 의 이름을 reflection 의 parameter
|
||||
metadata 에서 읽습니다. 이 플래그가 없으면 파라미터 이름이 `arg0`, `arg1` 로 컴파일되어 바인딩이
|
||||
깨집니다. Spring Boot Gradle 플러그인은 이 플래그를 자동으로 켜 주지만, 이 프로젝트는 플러그인을
|
||||
`apply false` 로 두기 때문에 자동 적용이 일어나지 않습니다. 그래서 각 subproject 의 `JavaCompile`
|
||||
에 직접 설정합니다.
|
||||
metadata 에서 읽는다. 이 플래그가 없으면 파라미터 이름이 `arg0`, `arg1` 로 컴파일되어 바인딩이
|
||||
깨진다. Spring Boot Gradle 플러그인은 이 플래그를 자동으로 켜 주지만, 이 프로젝트는 플러그인을
|
||||
`apply false` 로 두기 때문에 자동 적용이 일어나지 않는다. 그래서 각 subproject 의 `JavaCompile`
|
||||
에 직접 설정한다.
|
||||
|
||||
### `verifyCleanArchitectureDependencies`
|
||||
|
||||
- **하는 일.** [config/architecture/modules.json](config/architecture/modules.json)의
|
||||
`allowed_dependencies`를 읽고, 실제 Gradle 프로젝트 의존(`api` / `implementation` /
|
||||
`compileOnly` / `runtimeOnly`)이 그 범위를 벗어나면 빌드를 실패시킵니다.
|
||||
- **JSON registry가 의존 방향의 SSOT 입니다.** 새 모듈이나 새 production 의존 edge를 추가하면
|
||||
registry와 `:app-bootstrap:architectureTest`의 관련 ArchUnit 규칙을 함께 갱신해야 합니다. settings와 gate는
|
||||
같은 registry를 읽고, 등록되지 않은 leaf나 허용되지 않은 edge를 fail-closed로 거부합니다.
|
||||
`compileOnly` / `runtimeOnly`)이 그 범위를 벗어나면 빌드를 실패시킨다.
|
||||
- **JSON registry가 의존 방향의 SSOT이다.** 새 모듈이나 새 production 의존 edge를 추가하면
|
||||
registry와 `:app-bootstrap:architectureTest`의 관련 ArchUnit 규칙을 함께 갱신해야 한다. settings와 gate는
|
||||
같은 registry를 읽고, 등록되지 않은 leaf나 허용되지 않은 edge를 fail-closed로 거부한다.
|
||||
|
||||
조립 루트가 받는 모듈의 별도 membership 검사는 없습니다. `app-bootstrap`의 `allowed_dependencies`
|
||||
조립 루트가 받는 모듈의 별도 membership 검사는 없다. `app-bootstrap`의 `allowed_dependencies`
|
||||
밖의 모듈은 방향 게이트가 막고, 무엇이 실제로 실리는지는 `app-bootstrap/build.gradle`의 의존성이
|
||||
정합니다.
|
||||
정한다.
|
||||
|
||||
세 opt-in inbound transport의 test-only composition, 실제 wire 경계, positive-count/zero-skip 증거는
|
||||
다음 release-blocking aggregate로 실행합니다.
|
||||
다음 release-blocking aggregate로 실행한다.
|
||||
|
||||
```bash
|
||||
./gradlew conditionalTransportQualification
|
||||
@@ -113,136 +113,136 @@ archive task 자체는 timestamp 비보존·재현 가능한 file order·고정
|
||||
|
||||
### 파일당 public 최상위 타입 1개 (code-conventions I6)
|
||||
|
||||
Checkstyle이 소유합니다 — `OneTopLevelClass`와 `OuterTypeFilename`(`config/checkstyle/checkstyle.xml`).
|
||||
각 leaf의 `checkstyleMain`/`checkstyleTest`가 그 leaf의 `check`에서 돕니다.
|
||||
Checkstyle이 소유한다 — `OneTopLevelClass`와 `OuterTypeFilename`(`config/checkstyle/checkstyle.xml`).
|
||||
각 leaf의 `checkstyleMain`/`checkstyleTest`가 그 leaf의 `check`에서 돈다.
|
||||
|
||||
`verifyOneTypePerFile`이라는 루트 태스크가 있었고 삭제했습니다. `src/main/java`를 줄 단위 정규식으로
|
||||
읽었고 세 가지가 틀렸습니다: package-private 최상위 타입이 보이지 않았고(126개 main 소스가 한 번도
|
||||
`verifyOneTypePerFile`이라는 루트 태스크가 있었고 삭제했다. `src/main/java`를 줄 단위 정규식으로
|
||||
읽었고 세 가지가 틀렸다: package-private 최상위 타입이 보이지 않았고(126개 main 소스가 한 번도
|
||||
매칭되지 않아, 파일 하나에 package-private 타입 다섯 개가 있어도 통과했다), `src/main/java`만 읽었고,
|
||||
`^public` 앵커 때문에 블록 주석이나 텍스트 블록의 `public`으로 시작하는 줄을 선언으로 셌습니다.
|
||||
Checkstyle은 파싱된 파일에 같은 질문을 하고, leaf 단위로 돕니다.
|
||||
`^public` 앵커 때문에 블록 주석이나 텍스트 블록의 `public`으로 시작하는 줄을 선언으로 셌다.
|
||||
Checkstyle은 파싱된 파일에 같은 질문을 하고, leaf 단위로 돈다.
|
||||
|
||||
### `:app-bootstrap:verifyEnvKeys`
|
||||
|
||||
- **소유.** app-bootstrap. 이 질문("이 애플리케이션의 배포에 무엇을 줘야 하는가")은 composition
|
||||
root의 것이고, `./gradlew :domain-core:check`가 알아야 할 사항이 아닙니다. 루트 집계 이름은
|
||||
`configContractCheck`이고 구현은 `build-logic`의 `ca.config-contract` plugin입니다(소유자 결정 4:
|
||||
root의 것이고, `./gradlew :domain-core:check`가 알아야 할 사항이 아니다. 루트 집계 이름은
|
||||
`configContractCheck`이고 구현은 `build-logic`의 `ca.config-contract` plugin이다(소유자 결정 4:
|
||||
태스크는 app-bootstrap에 유지, `build-tools` included build는 비워서 삭제).
|
||||
- **하는 일.** `docs/registries/env-keys.yaml`, app-bootstrap의 `application*.yml` + `config/*.yml`,
|
||||
capability 모듈이 싣는 `config/*.yml`·`config/module-defaults/*.yml`(기본 조립에 없어도 검사한다),
|
||||
`src/.env.example`을 lock-step(서로 어긋나지 않게) 으로 유지합니다. `env-keys.yaml` 이 `APP_` 키의 SSOT 이고, drift 가 생기면 빌드를
|
||||
실패시킵니다.
|
||||
`src/.env.example`을 lock-step(서로 어긋나지 않게) 으로 유지한다. `env-keys.yaml` 이 `APP_` 키의 SSOT 이고, drift 가 생기면 빌드를
|
||||
실패시킨다.
|
||||
- **막으려는 것 3가지.** (1) 필수 env 가 조용히 누락되는 것, (2) 더 이상 쓰지 않는 stale env 키가
|
||||
`.env.example` 에 남는 것, (3) 실제로 쓰는 `APP_` 키가 registry 에 등록되지 않고 빠져나가는 것.
|
||||
- **검사 항목.**
|
||||
- **A.** `application.yml` 의 placeholder 중 inline default(`${VAR:default}`)가 없는 **필수**
|
||||
placeholder(`${VAR}`)는 반드시 `.env.example` 에 존재해야 합니다.
|
||||
- **B.** `.env.example` 의 모든 키는 shipped configuration의 어떤 `${...}` placeholder 또는 등록된 consumer가 참조해야 합니다.
|
||||
placeholder(`${VAR}`)는 반드시 `.env.example` 에 존재해야 한다.
|
||||
- **B.** `.env.example` 의 모든 키는 shipped configuration의 어떤 `${...}` placeholder 또는 등록된 consumer가 참조해야 한다.
|
||||
(아무도 안 쓰는 키는 orphan 으로 간주해 실패)
|
||||
- **C.** `.env.example` 의 모든 `APP_` 키는 registry 에 `- name: <KEY>` 행이 있어야 합니다.
|
||||
- **C.** `.env.example` 의 모든 `APP_` 키는 registry 에 `- name: <KEY>` 행이 있어야 한다.
|
||||
- **`SPRING_*` 키는 왜 registry 추적 대상이 아닌가.** `SPRING_*` 는 Spring Boot 가 정의한 native 키라
|
||||
프로젝트가 소유한 계약이 아닙니다. 그래서 C 검사는 일부러 `APP_` prefix 로만 범위를 좁혔습니다.
|
||||
- **비고.** `src/.env.example`이 커밋된 환경 계약이고 `src/.env`는 로컬 실행용 입력입니다.
|
||||
프로젝트가 소유한 계약이 아니다. 그래서 C 검사는 일부러 `APP_` prefix 로만 범위를 좁혔다.
|
||||
- **비고.** `src/.env.example`이 커밋된 환경 계약이고 `src/.env`는 로컬 실행용 입력이다.
|
||||
|
||||
### `verifyPublicPathSnapshot`
|
||||
|
||||
- **하는 일.** deny-by-default public path 표면이 승인 없이 바뀌면 빌드를 실패시킵니다.
|
||||
- **배경.** 이 앱은 deny-by-default 입니다. 즉 `SECURITY_PUBLIC_PATHS` 가 먹이는 명시적 `permitAll()`
|
||||
경로를 **제외한** 모든 요청은 인증을 요구합니다
|
||||
- **하는 일.** deny-by-default public path 표면이 승인 없이 바뀌면 빌드를 실패시킨다.
|
||||
- **배경.** 이 앱은 deny-by-default이다. 즉 `SECURITY_PUBLIC_PATHS` 가 먹이는 명시적 `permitAll()`
|
||||
경로를 **제외한** 모든 요청은 인증을 요구한다
|
||||
(`app-bootstrap/src/main/resources/config/security.yml` → `SecuritySettings.publicPaths()` →
|
||||
`SecurityConfig`). 설정 분할 이전에는 이 SSOT 가 `src/.env` 였고 문서만 그대로 남아 있었습니다.
|
||||
스냅샷 플러그인이 실제로 읽는 파일은 `config/security.yml` 입니다
|
||||
`SecurityConfig`). 설정 분할 이전에는 이 SSOT 가 `src/.env` 였고 문서만 그대로 남아 있었다.
|
||||
스냅샷 플러그인이 실제로 읽는 파일은 `config/security.yml`이다
|
||||
(`build-logic/.../publicpath/PublicPathSnapshotPlugin.java`).
|
||||
이 public 표면이 바뀌는 순간이 곧 보호되던 엔드포인트가 조용히 공개로 노출되는 지점입니다.
|
||||
그래서 그 표면을 snapshot 으로 떠 두고, 미승인 변경에 빌드를 실패시킵니다.
|
||||
- **승인 방법.** `verifyPublicPathSnapshot` 은 항상 읽기 전용입니다. reviewer 가 변경을 승인한 뒤
|
||||
이 public 표면이 바뀌는 순간이 곧 보호되던 엔드포인트가 조용히 공개로 노출되는 지점이다.
|
||||
그래서 그 표면을 snapshot 으로 떠 두고, 미승인 변경에 빌드를 실패시킨다.
|
||||
- **승인 방법.** `verifyPublicPathSnapshot` 은 항상 읽기 전용이다. reviewer 가 변경을 승인한 뒤
|
||||
`./gradlew updatePublicPathSnapshot -PapprovePublicPathChange` 로 snapshot 을 명시적으로 다시
|
||||
생성합니다. 공개 경로 변경은 보안 리뷰 대상으로 보고 재생성된 snapshot 을 함께 커밋합니다.
|
||||
생성한다. 공개 경로 변경은 보안 리뷰 대상으로 보고 재생성된 snapshot 을 함께 커밋한다.
|
||||
- **결정 — 무엇을 snapshot 했나 (프로젝트 선택).** 초기안은 기동 시
|
||||
`SecurityFilterChain.getFilters()` 를 introspection 하는 방식이었습니다. 하지만 그 reflection
|
||||
은 Spring 버전마다 깨지기 쉽습니다(`permitAll` matcher 가
|
||||
`SecurityFilterChain.getFilters()` 를 introspection 하는 방식이었다. 하지만 그 reflection
|
||||
은 Spring 버전마다 깨지기 쉽다(`permitAll` matcher 가
|
||||
`RequestMatcherDelegatingAuthorizationManager` 의 private 필드에 숨어 있음). 그래서 `permitAll()`
|
||||
을 실제로 먹이는 결정적 SSOT 인 `SECURITY_PUBLIC_PATHS` 자체를 snapshot 합니다. 탐지 목표(공개 경로
|
||||
변경은 무조건 게이트를 실패시킨다)는 같고, 메커니즘은 더 견고합니다.
|
||||
을 실제로 먹이는 결정적 SSOT 인 `SECURITY_PUBLIC_PATHS` 자체를 snapshot 한다. 탐지 목표(공개 경로
|
||||
변경은 무조건 게이트를 실패시킨다)는 같고, 메커니즘은 더 견고하다.
|
||||
- **snapshot 위치.** `docs/security/public-paths-snapshot.txt`. 이 파일은 커밋된 필수 보안
|
||||
baseline 입니다. CI 는 Gradle 실행 전에 파일이 비어 있지 않고 Git에 추적되는지 검사하므로 fresh
|
||||
checkout 에서 누락되거나 untracked 상태면 즉시 실패합니다. 승인된 변경만 update task로 재생성한
|
||||
뒤 보안 리뷰와 함께 커밋합니다.
|
||||
baseline이다. CI 는 Gradle 실행 전에 파일이 비어 있지 않고 Git에 추적되는지 검사하므로 fresh
|
||||
checkout 에서 누락되거나 untracked 상태면 즉시 실패한다. 승인된 변경만 update task로 재생성한
|
||||
뒤 보안 리뷰와 함께 커밋한다.
|
||||
|
||||
### Trivy suppression과 플래키 격리 — 정책은 유지, 파서는 삭제
|
||||
|
||||
**Trivy suppression.** repo 루트 `.trivyignore.yaml`이 유일한 suppression 소스이고, 모든 Trivy 호출이
|
||||
`--ignorefile .trivyignore.yaml`로 명시합니다. 항목은 `id`, 비어 있지 않은 `statement`, 90일 이내의
|
||||
미래 `expired_at`을 갖춰야 합니다. 이 규칙은 그대로이고, 강제하는 주체가 `.github/CODEOWNERS` 리뷰어로
|
||||
바뀌었습니다. `verifyTrivyignore`는 105줄짜리 손으로 쓴 YAML 파서였고 — 들여쓰기 추적, 인라인 스칼라
|
||||
처리, 따옴표 제거 — 지키던 파일은 만들어진 이래 계속 비어 있었습니다. 실제 항목이 생기고 그것이
|
||||
drift하기 시작하면 그때 자동화합니다. 진짜 항목을 상대로, 진짜 YAML 라이브러리로.
|
||||
`--ignorefile .trivyignore.yaml`로 명시한다. 항목은 `id`, 비어 있지 않은 `statement`, 90일 이내의
|
||||
미래 `expired_at`을 갖춰야 한다. 이 규칙은 그대로이고, 강제하는 주체가 `.github/CODEOWNERS` 리뷰어로
|
||||
바뀌었다. `verifyTrivyignore`는 105줄짜리 손으로 쓴 YAML 파서였고 — 들여쓰기 추적, 인라인 스칼라
|
||||
처리, 따옴표 제거 — 지키던 파일은 만들어진 이래 계속 비어 있었다. 실제 항목이 생기고 그것이
|
||||
drift하기 시작하면 그때 자동화한다. 진짜 항목을 상대로, 진짜 YAML 라이브러리로.
|
||||
|
||||
**플래키 격리.** `quarantineTest` 버킷과 CI의 비차단 `quarantine` 잡은 삭제했습니다. 격리된
|
||||
테스트가 한 번도 없었습니다. 간헐 실패 테스트는 고치거나 지웁니다.
|
||||
**플래키 격리.** `quarantineTest` 버킷과 CI의 비차단 `quarantine` 잡은 삭제했다. 격리된
|
||||
테스트가 한 번도 없었다. 간헐 실패 테스트는 고치거나 지운다.
|
||||
|
||||
`flaky-quarantine.yaml` 레지스트리와 `verifyQuarantineSunset`(14일 sunset + drift 검사)은
|
||||
삭제했습니다. 250줄짜리 YAML 파서 + Java 렉서(주석과 문자열 리터럴 안의 `@Tag("quarantine")`를
|
||||
걸러내려고 인덱스 보존 렉서를 직접 구현)로 항목이 0개인 레지스트리를 지키고 있었습니다. 순서가
|
||||
반대입니다 — 실제로 격리된 테스트가 생기고, 그게 주차장이 되기 시작할 때 도입할 정책입니다.
|
||||
삭제했다. 250줄짜리 YAML 파서 + Java 렉서(주석과 문자열 리터럴 안의 `@Tag("quarantine")`를
|
||||
걸러내려고 인덱스 보존 렉서를 직접 구현)로 항목이 0개인 레지스트리를 지키고 있었다. 순서가
|
||||
반대다 — 실제로 격리된 테스트가 생기고, 그게 주차장이 되기 시작할 때 도입할 정책이다.
|
||||
|
||||
### CI 게이트 배선
|
||||
|
||||
- **소유 범위.** 이 계약은 *게이트 배선*(어떤 게이트가 CI 에서 돌고 실패 시 어떻게 릴리스를 막는가)을
|
||||
소유합니다. 개별 scanner/tool/severity *정책* 은 owner 브랜치가 소유하며, 그 20행 매핑의 in-repo
|
||||
SSOT는 Gradle task graph와 GitHub Actions job graph 그 자체입니다.
|
||||
소유한다. 개별 scanner/tool/severity *정책* 은 owner 브랜치가 소유하며, 그 20행 매핑의 in-repo
|
||||
SSOT는 Gradle task graph와 GitHub Actions job graph 그 자체다.
|
||||
|
||||
> 이력: 게이트 표 `.github/ci-gate-matrix.yml`(1,025줄, 107개 게이트 행)과 그 검사기
|
||||
> `.github/scripts/verify-gate-matrix.sh`(568줄)는 삭제했습니다. 그 표는 이미 두 그래프에 있는 정보의
|
||||
> 세 번째 사본이었고, 검사기는 세 사본을 서로 같게 유지하는 일을 했습니다. 결과적으로 체크 하나를
|
||||
> 추가하려면 Gradle · workflow · 표 · 검사기 기대값 · Java 계약 테스트 다섯 곳을 같이 고쳐야 했습니다.
|
||||
> `.github/scripts/verify-gate-matrix.sh`(568줄)는 삭제했다. 그 표는 이미 두 그래프에 있는 정보의
|
||||
> 세 번째 사본이었고, 검사기는 세 사본을 서로 같게 유지하는 일을 했다. 결과적으로 체크 하나를
|
||||
> 추가하려면 Gradle · workflow · 표 · 검사기 기대값 · Java 계약 테스트 다섯 곳을 같이 고쳐야 했다.
|
||||
- **워크플로.** `.github/workflows/ci-quality-gates.yml` 의 `release-gate` 잡이 모든 release-blocking
|
||||
게이트의 fan-in(단일 required status check)입니다. included build 테스트는 경로 필터가 걸린
|
||||
게이트의 fan-in(단일 required status check)이다. included build 테스트는 경로 필터가 걸린
|
||||
`build-logic.yml`이, main 단계(`mainCheck`)·configuration-cache·JPA candidate evidence는
|
||||
`integration-main.yml`이 돌립니다. 위임 게이트(Trivy SCA/이미지 스캔)는 `dependency-vulnerability.yml` 가 소유하며,
|
||||
`integration-main.yml`이 돌린다. 위임 게이트(Trivy SCA/이미지 스캔)는 `dependency-vulnerability.yml` 가 소유하며,
|
||||
GitHub Actions 는 워크플로 간 `needs` 를 못 쓰므로 branch protection 의 required check 합집합으로
|
||||
묶습니다.
|
||||
묶는다.
|
||||
|
||||
---
|
||||
|
||||
## .env — 환경 변수 레퍼런스
|
||||
|
||||
`spring-dotenv` 가 `src/.env` 를 읽어 외부화 설정을 주입합니다(`bootRun` 의 working dir 가 `src/` 라
|
||||
이 파일이 잡힙니다). 아래는 섹션별 키 설명입니다. 따로 표기가 없으면 `restart-only`(값 변경 시 재기동
|
||||
필요)로 간주하세요.
|
||||
`spring-dotenv` 가 `src/.env` 를 읽어 외부화 설정을 주입한다(`bootRun` 의 working dir 가 `src/` 라
|
||||
이 파일이 잡힌다). 아래는 섹션별 키 설명이다. 따로 표기가 없으면 `restart-only`(값 변경 시 재기동
|
||||
필요)로 간주한다.
|
||||
|
||||
### 앱 이름과 profile
|
||||
|
||||
- **`APP_NAME`** — `spring.application.name` 과 JSON 로그의 `app` 필드. 자유 문자열.
|
||||
- **`SPRING_PROFILES_ACTIVE`** — 활성 Spring profile. `local` | `dev` | `prod` 중 정확히 하나입니다. JSON
|
||||
로그의 `profile` 필드도 이 값을 씁니다.
|
||||
- **`SPRING_PROFILES_ACTIVE`** — 활성 Spring profile. `local` | `dev` | `prod` 중 정확히 하나다. JSON
|
||||
로그의 `profile` 필드도 이 값을 쓴다.
|
||||
|
||||
### 런타임 안전 검사 (기동할 때 바로 실패시킨다, D8)
|
||||
|
||||
- **`APP_SERVER_ERROR_INCLUDE_STACKTRACE` / `APP_SERVER_ERROR_INCLUDE_MESSAGE`** — 로컬 디버깅용.
|
||||
prod에서 `never`가 아니면 `ErrorDetailExposureSafetyValidator`가 기동을 막습니다(exit 71,
|
||||
prod에서 `never`가 아니면 `ErrorDetailExposureSafetyValidator`가 기동을 막는다(exit 71,
|
||||
`spring.web.error.include-binding-errors`·`include-exception`도 같음). request logging은 body를
|
||||
읽지 않는 계약을 검증합니다.
|
||||
읽지 않는 계약을 검증한다.
|
||||
- **`APP_MULTI_INSTANCE_ENABLED`** — `true` 면 cross-instance `DistributedLockPort`
|
||||
(`distributedLockProvider`)가 조립돼 있어야 하며, 없으면 기동이 실패합니다(exit 72,
|
||||
(`distributedLockProvider`)가 조립돼 있어야 하며, 없으면 기동이 실패한다(exit 72,
|
||||
`StartupSafetyValidator`).
|
||||
- **`APP_RATE_LIMIT_ENABLED`** — 제공자에 묶이지 않은 앞단 요청 수 제한(rate limit) interceptor를 켠다
|
||||
(429 + `Retry-After` + `X-RateLimit-*` 응답). 기본값은 `false`이며, `true`로 바꿀 때는
|
||||
`APP_RATE_LIMIT_PROVIDER=redis`와 canonical coordination role을 함께 구성해야 합니다.
|
||||
비인증 요청의 키는 `getRemoteAddr()` 입니다. 프록시 뒤라면
|
||||
`APP_RATE_LIMIT_PROVIDER=redis`와 canonical coordination role을 함께 구성해야 한다.
|
||||
비인증 요청의 키는 `getRemoteAddr()`이다. 프록시 뒤라면
|
||||
`APP_SERVER_FORWARD_HEADERS_STRATEGY=native` 와 `server.tomcat.remoteip.internal-proxies` 로 신뢰할
|
||||
프록시를 지정하세요(`framework` 면 rate limit 이 기동을 거부합니다).
|
||||
프록시를 지정한다(`framework` 면 rate limit 이 기동을 거부한다).
|
||||
- **`APP_IDEMPOTENCY_PROVIDER`** — 요청 멱등성 store. `disabled`(기본) | `redis` | `postgresql`.
|
||||
`postgresql` 은 PostgreSQL data source 가 아니면 기동을 거부하므로 `bootRunH2` 에서는
|
||||
`disabled` 나 `redis` 를 씁니다.
|
||||
`disabled` 나 `redis` 를 쓴다.
|
||||
- **`APP_IDEMPOTENCY_TTL`** — 완료 응답을 재생할 수 있는 기간(`replay-ttl`). duration(예: `24h`).
|
||||
최대 72h 이고 넘으면 기동을 거부합니다. (D6) `APP_IDEMPOTENCY_PROCESSING_LEASE`(기본 30s)보다
|
||||
짧아도, `APP_IDEMPOTENCY_FAILURE_RETENTION`(기본 24h)보다 길어도 기동을 거부합니다. 24h보다
|
||||
올리려면 `APP_IDEMPOTENCY_FAILURE_RETENTION`도 함께 올립니다.
|
||||
최대 72h 이고 넘으면 기동을 거부한다. (D6) `APP_IDEMPOTENCY_PROCESSING_LEASE`(기본 30s)보다
|
||||
짧아도, `APP_IDEMPOTENCY_FAILURE_RETENTION`(기본 24h)보다 길어도 기동을 거부한다. 24h보다
|
||||
올리려면 `APP_IDEMPOTENCY_FAILURE_RETENTION`도 함께 올린다.
|
||||
|
||||
### 비동기 executor
|
||||
|
||||
`@Async` `ThreadPoolTaskExecutor` 풀 크기 설정입니다.
|
||||
`@Async` `ThreadPoolTaskExecutor` 풀 크기 설정이다.
|
||||
|
||||
- **`APP_ASYNC_EXECUTOR_CORE_SIZE`** — 항상 살아있는 워커 수. 1 이상 정수.
|
||||
- **`APP_ASYNC_EXECUTOR_MAX_SIZE`** — 워커 수 상한. core-size 이상.
|
||||
@@ -252,17 +252,17 @@ drift하기 시작하면 그때 자동화합니다. 진짜 항목을 상대로,
|
||||
### 기능 추가 = 한 줄 + env
|
||||
|
||||
기본 조립(`bootJar`)에는 web, 관측(actuator·metrics·tracing·로그), `domain-core`·`application-core`·
|
||||
`shared-contract`, `adapter:outbound:support`·`adapter:outbound:identifier`만 들어 있습니다. DB·Redis·
|
||||
Kafka 없이 기동합니다. 나머지 기능은 `app-bootstrap/build.gradle`에 주석 처리된 `runtimeOnly` 한 줄로
|
||||
있습니다.
|
||||
`shared-contract`, `adapter:outbound:support`·`adapter:outbound:identifier`만 들어 있다. DB·Redis·
|
||||
Kafka 없이 기동한다. 나머지 기능은 `app-bootstrap/build.gradle`에 주석 처리된 `runtimeOnly` 한 줄로
|
||||
있다.
|
||||
|
||||
- **켜기:** 그 줄의 주석을 풀고, 아래 env를 `src/.env`에 넣습니다. 모듈이 classpath에 있으면 켜집니다.
|
||||
- **끄기:** 줄을 지웁니다. 모듈의 bean·설정·의존성이 함께 빠집니다. 줄은 두고 잠시 끄려면 "끄는 키"를
|
||||
`false`로 줍니다(모든 키의 기본값은 `true`).
|
||||
- **줄을 바꾼 뒤:** strict lock을 갱신합니다.
|
||||
- **켜기:** 그 줄의 주석을 풀고, 아래 env를 `src/.env`에 넣는다. 모듈이 classpath에 있으면 켜진다.
|
||||
- **끄기:** 줄을 지운다. 모듈의 bean·설정·의존성이 함께 빠진다. 줄은 두고 잠시 끄려면 "끄는 키"를
|
||||
`false`로 준다(모든 키의 기본값은 `true`).
|
||||
- **줄을 바꾼 뒤:** strict lock을 갱신한다.
|
||||
`./gradlew :app-bootstrap:resolveAndLockAll --write-locks`
|
||||
- 모든 capability를 한 번에 싣는 jar가 필요하면(compose 레인·CI) `./gradlew :app-bootstrap:qualificationBootJar`를
|
||||
씁니다. 배포용이 아닙니다.
|
||||
쓴다. 배포용이 아니다.
|
||||
|
||||
| capability | `build.gradle` 한 줄 | 켜진 뒤 필요한 env | 끄는 키 |
|
||||
|---|---|---|---|
|
||||
@@ -279,28 +279,28 @@ Kafka 없이 기동합니다. 나머지 기능은 `app-bootstrap/build.gradle`
|
||||
| 알림 (SMTP/SES, JPA 줄도 필요) | `runtimeOnly project(':composition:notification-platform')` | 키 8종과 각 `_ID`(`APP_NOTIFICATION_PLATFORM_*_KEY`, `*_KEY_ID`), 쓰는 provider 설정(`APP_NOTIFICATION_PLATFORM_SMTP_*` 또는 `_SES_*`) | `APP_NOTIFICATION_PLATFORM_ENABLED` |
|
||||
|
||||
전체 목록과 타입·기본값은 `docs/registries/env-keys.yaml`, 각 모듈이 제공하는 것은 그 모듈 README의
|
||||
"제공하는 것 · 추가할 한 줄 · env 키" 절에 있습니다. 기능 사이의 의존(알림·파일 서버 → JPA, outbox relay
|
||||
→ JPA + Kafka)은 설정 검사가 아니라 build 줄로 맞춥니다. 표에 "JPA 줄도 필요"라고 적힌 기능은 두 줄을
|
||||
함께 넣습니다.
|
||||
"제공하는 것 · 추가할 한 줄 · env 키" 절에 있다. 기능 사이의 의존(알림·파일 서버 → JPA, outbox relay
|
||||
→ JPA + Kafka)은 설정 검사가 아니라 build 줄로 맞춘다. 표에 "JPA 줄도 필요"라고 적힌 기능은 두 줄을
|
||||
함께 넣는다.
|
||||
|
||||
어떤 자동 설정이 켜졌는지는 Spring Boot의 `conditions` endpoint로 봅니다. 기본 노출 목록에는 없으므로
|
||||
필요할 때 `management.endpoints.web.exposure.include`에 추가합니다.
|
||||
어떤 자동 설정이 켜졌는지는 Spring Boot의 `conditions` endpoint로 본다. 기본 노출 목록에는 없으므로
|
||||
필요할 때 `management.endpoints.web.exposure.include`에 추가한다.
|
||||
|
||||
종속 선택자 둘:
|
||||
|
||||
- `APP_GRAPHQL_DEPLOYMENT_MODE` — GraphQL이 켜지면 **필수**이고 기본값이 없습니다. 예전의 boolean과
|
||||
enum 두 기본값이 서로 다른 말을 했기 때문에, 안전 태세는 배포가 명시적으로 고릅니다. 허용되는 값은
|
||||
런타임 환경(`local`/`dev`/`prod`)마다 다릅니다.
|
||||
- `APP_GRAPHQL_DEPLOYMENT_MODE` — GraphQL이 켜지면 **필수**이고 기본값이 없다. 예전의 boolean과
|
||||
enum 두 기본값이 서로 다른 말을 했기 때문에, 안전 태세는 배포가 명시적으로 고른다. 허용되는 값은
|
||||
런타임 환경(`local`/`dev`/`prod`)마다 다르다.
|
||||
- `APP_NOTIFICATION_PLATFORM_MODE` — `SERVING`(기본) 또는 `INGEST_ONLY`. 선택 사항이고, 허용 값은
|
||||
`NotificationModeSsotTest`가 enum에서 파생합니다.
|
||||
`NotificationModeSsotTest`가 enum에서 파생한다.
|
||||
|
||||
### Compose와 런타임 스모크
|
||||
|
||||
- **Docker Compose 최소 버전 `2.24.4`.** SSOT는 `src/app-bootstrap/compose-lanes/compose-profile-contracts.json`
|
||||
이고, 정본 스크립트가 검증합니다. lane은 저장소 루트 `compose.yaml`(개발 환경)을 바탕으로 쓰고, lane에만
|
||||
필요한 overlay·smoke client·스키마 적용은 `src/app-bootstrap/compose-lanes/`에 있습니다.
|
||||
- 진입점은 둘뿐이고, 그 둘만이 증거입니다. 워크플로에 명령 일부를 인라인하면 one-shot 없이 도는 레인이
|
||||
초록으로 보고됩니다.
|
||||
- **Docker Compose 최소 버전은 `src/app-bootstrap/compose-lanes/compose-profile-contracts.json`의
|
||||
`minimumComposeVersion`이다.** 정본 스크립트가 검증한다. lane은 저장소 루트 `compose.yaml`(개발 환경)을 바탕으로 쓰고, lane에만
|
||||
필요한 overlay·smoke client·스키마 적용은 `src/app-bootstrap/compose-lanes/`에 있다.
|
||||
- 진입점은 둘뿐이고, 그 둘만이 증거다. 워크플로에 명령 일부를 인라인하면 one-shot 없이 도는 레인이
|
||||
초록으로 보고된다.
|
||||
|
||||
```bash
|
||||
# 정적: profile별 정확한 service set, 병합된 모델 전체, mount target 유일성
|
||||
@@ -311,36 +311,36 @@ Kafka 없이 기동합니다. 나머지 기능은 `app-bootstrap/build.gradle`
|
||||
./scripts/run-compose-runtime-smoke.sh --matrix src/app-bootstrap/compose-lanes/compose-profile-contracts.json
|
||||
```
|
||||
|
||||
`--lane <id>`는 실패 재현용이고, 레인 하나가 초록인 것은 matrix가 통과했다는 증거가 아닙니다.
|
||||
`--lane <id>`는 실패 재현용이고, 레인 하나가 초록인 것은 matrix가 통과했다는 증거가 아니다.
|
||||
|
||||
### 선택형 연동 adapter
|
||||
|
||||
Kafka·Redis는 위 "기능 추가 = 한 줄 + env" 표의 한 줄로 고릅니다. 모듈이 있으면 켜지고, 없으면 그
|
||||
포트를 구현하는 bean이 아예 없습니다. 아래는 모듈을 고른 뒤 동작을 고르는 키입니다.
|
||||
Kafka·Redis는 위 "기능 추가 = 한 줄 + env" 표의 한 줄로 고른다. 모듈이 있으면 켜지고, 없으면 그
|
||||
포트를 구현하는 bean이 아예 없다. 아래는 모듈을 고른 뒤 동작을 고르는 키다.
|
||||
|
||||
- **`APP_CACHE_REDIS_ENABLED`** — deprecated(2026-11-30 제거 예정). 읽는 곳이 없고,
|
||||
기본 조립에서 Redis를 켜고 끄는 것은 `APP_REDIS_ENABLED`입니다.
|
||||
기본 조립에서 Redis를 켜고 끄는 것은 `APP_REDIS_ENABLED`이다.
|
||||
- **`APP_CACHE_CANONICAL_DEFAULT_PROVIDER`** — 기본 캐시 영역(canonical default semantic region)의 제공자를 고른다.
|
||||
`disabled`(기본) | `redis`. `redis`는 canonical Redis CACHE role binding을 함께 요구합니다.
|
||||
`disabled`(기본) | `redis`. `redis`는 canonical Redis CACHE role binding을 함께 요구한다.
|
||||
- **`APP_CACHE_REDIS_CLIENT_MODE`** — `managed`는 내장 Lettuce runtime, `external`은 프로젝트가
|
||||
제공한 `RedisClient` bean을 사용합니다.
|
||||
아래 세 키는 **활성화 스위치가 아니라 선택자**입니다. 어떤 capability가 켜지는지는 위의 build 한 줄과
|
||||
끄는 키가 정하고, 이 값들은 켜진 capability가 *무엇으로* 동작할지만 고릅니다. 예전에는 "빈 값 = 비활성"으로
|
||||
설명돼 있었고, 그 문장이 남아 있는 동안 두 개의 활성화 모델이 공존했습니다.
|
||||
제공한 `RedisClient` bean을 사용한다.
|
||||
아래 세 키는 **활성화 스위치가 아니라 선택자**이다. 어떤 capability가 켜지는지는 위의 build 한 줄과
|
||||
끄는 키가 정하고, 이 값들은 켜진 capability가 *무엇으로* 동작할지만 고른다. 예전에는 "빈 값 = 비활성"으로
|
||||
설명돼 있었고, 그 문장이 남아 있는 동안 두 개의 활성화 모델이 공존했다.
|
||||
|
||||
- **`APP_MESSAGING_BROKER`** — 활성 메시지 브로커 id. Kafka 모듈의 설정 기본값이 `kafka`(등록된 유일한
|
||||
broker)라 보통 비워 두지 않습니다. 빈 값을 주면 기동이 거부되면서 이 키 이름을 지목합니다. 이 키를 비워도 메시징이 꺼지지는
|
||||
않습니다 — 끄는 것은 `APP_MESSAGING_ENABLED=false`입니다.
|
||||
broker)라 보통 비워 두지 않는다. 빈 값을 주면 기동이 거부되면서 이 키 이름을 지목한다. 이 키를 비워도 메시징이 꺼지지는
|
||||
않는다 — 끄는 것은 `APP_MESSAGING_ENABLED=false`이다.
|
||||
- **`APP_MESSAGING_KAFKA_BROKERS`** — `host:port` CSV. Kafka 모듈을 고르면 필수. messaging
|
||||
platform의 Kafka transport(`app.messaging.brokers.kafka.bootstrap-servers`)가 이 값을 씁니다.
|
||||
`spring.kafka.bootstrap-servers`는 읽지 않습니다.
|
||||
platform의 Kafka transport(`app.messaging.brokers.kafka.bootstrap-servers`)가 이 값을 쓴다.
|
||||
`spring.kafka.bootstrap-servers`는 읽지 않는다.
|
||||
- **`APP_NOTIFICATION_SLACK_WEBHOOK_ENABLED`** — Slack webhook R0 제공자를 켜는 값. notification 플랫폼이
|
||||
켜졌을 때 어떤 provider를 쓸지 고르는 값입니다.
|
||||
- **`APP_NOTIFICATION_GOOGLE_EMAIL_ENABLED`** — Google Email R0 제공자를 켜는 값. 위와 같습니다.
|
||||
켜졌을 때 어떤 provider를 쓸지 고르는 값이다.
|
||||
- **`APP_NOTIFICATION_GOOGLE_EMAIL_ENABLED`** — Google Email R0 제공자를 켜는 값. 위와 같다.
|
||||
|
||||
### 외부 HTTP 호출 (HTTP client)
|
||||
|
||||
현재 canonical activation은 다음 두 설정 트리만 사용합니다.
|
||||
현재 canonical activation은 다음 두 설정 트리만 사용한다.
|
||||
|
||||
```yaml
|
||||
app:
|
||||
@@ -353,18 +353,18 @@ app:
|
||||
```
|
||||
|
||||
- 기본 `DISABLED`는 binding/provider definition이 모두 비어 있어야 하며
|
||||
`DISABLED_VERIFIED`만 게시하고 client, executor, pool, retry/CB registry를 만들지 않습니다.
|
||||
- `ACTIVE`는 exact destination/provider/operation-catalog binding을 요구합니다. 현재 유일한
|
||||
`DISABLED_VERIFIED`만 게시하고 client, executor, pool, retry/CB registry를 만들지 않는다.
|
||||
- `ACTIVE`는 exact destination/provider/operation-catalog binding을 요구한다. 현재 유일한
|
||||
buffered-classic readiness card가 `NOT_IMPLEMENTED`이므로 provider resource 생성 전에
|
||||
fail-closed합니다. 아직 운영 HTTP provider를 활성화할 수 있다는 뜻이 아닙니다.
|
||||
- 기존 `APP_OUTBOUND_HTTP_*`와 `app.outbound.http.*`는 canonical 설정이 아닙니다. 루트 `src/.env`,
|
||||
fail-closed한다. 아직 운영 HTTP provider를 활성화할 수 있다는 뜻이 아니다.
|
||||
- 기존 `APP_OUTBOUND_HTTP_*`와 `app.outbound.http.*`는 canonical 설정이 아니다. 루트 `src/.env`,
|
||||
`app-bootstrap`의 application YAML, env-key registry에서 제거됐으며 canonical composition에
|
||||
입력하면 상태와 무관하게 기동을 거부합니다.
|
||||
- 그 키를 시연하던 샘플 모듈의 YAML은 2026-11-07 샘플과 함께 지웠습니다. 이제 저장소 어디에도 남아 있지 않습니다.
|
||||
입력하면 상태와 무관하게 기동을 거부한다.
|
||||
- 그 키를 시연하던 샘플 모듈의 YAML은 2026-11-07 샘플과 함께 지웠다. 이제 저장소 어디에도 남아 있지 않다.
|
||||
- legacy JDK facade가 필요한 fork만 canonical composition 밖에서
|
||||
`OutboundHttpSettings.bindLegacy(Binder)`와 legacy configuration을 명시적으로 import합니다.
|
||||
`OutboundHttpSettings.bindLegacy(Binder)`와 legacy configuration을 명시적으로 import한다.
|
||||
timeout/retry/CB/response-size 설정은 그 migration API 내부 계약일 뿐 canonical provider
|
||||
readiness를 증명하지 않습니다.
|
||||
readiness를 증명하지 않는다.
|
||||
|
||||
### 로그
|
||||
|
||||
@@ -376,11 +376,11 @@ app:
|
||||
**패키지별 레벨**(root 를 덮어씀) — 동일 허용값.
|
||||
|
||||
- **`APP_LOG_LEVEL_SPRING`** / **`APP_LOG_LEVEL_WEB`** — 각 패키지 레벨.
|
||||
- **`APP_LOG_LEVEL_SQL`** — `DEBUG` 로 두면 JPA/jdbc 연결 후 SQL 문이 출력됩니다.
|
||||
- **`APP_LOG_LEVEL_SQL`** — `DEBUG` 로 두면 JPA/jdbc 연결 후 SQL 문이 출력된다.
|
||||
|
||||
**파일 출력 + rolling**
|
||||
|
||||
- **`APP_LOG_FILE_ENABLED`** — `true` 면 rolling JSON 파일 appender 를 붙입니다.
|
||||
- **`APP_LOG_FILE_ENABLED`** — `true` 면 rolling JSON 파일 appender 를 붙인다.
|
||||
- **`APP_LOG_FILE_PATH`** — `bootRun` working dir(`src/`) 기준 상대 경로 또는 절대 경로.
|
||||
- **`APP_LOG_FILE_MAX_SIZE`** — 파일 1개 최대 크기(단위 `KB` | `MB` | `GB`).
|
||||
- **`APP_LOG_FILE_MAX_HISTORY`** — 보관할 rolled archive 개수. 1 이상 정수.
|
||||
@@ -391,14 +391,14 @@ app:
|
||||
- **`APP_LOG_ASYNC_ENABLED`** — `true` 면 appender 를 `AsyncAppender` 로 감싸 non-blocking I/O.
|
||||
- **`APP_LOG_ASYNC_QUEUE_SIZE`** — back-pressure 전 in-memory 큐 깊이. 1 이상 정수.
|
||||
- **`APP_LOG_ASYNC_DISCARDING_THRESHOLD`** — 남은 큐 용량이 이 값 미만이면 `TRACE`/`DEBUG`/`INFO`
|
||||
이벤트를 버립니다(`WARN`/`ERROR` 는 항상 유지). `0` = 절대 버리지 않음. 0 이상 정수.
|
||||
이벤트를 버린다(`WARN`/`ERROR` 는 항상 유지). `0` = 절대 버리지 않음. 0 이상 정수.
|
||||
|
||||
**JSON 인코더 세부**
|
||||
|
||||
- **`APP_LOG_JSON_TIMEZONE`** — IANA timezone(예: `UTC`, `Asia/Seoul`) 또는 `default`(JVM 기본).
|
||||
- **`APP_LOG_JSON_TIMESTAMP_PATTERN`** — 타임스탬프 패턴. 보통 ISO 8601
|
||||
(`yyyy-MM-dd'T'HH:mm:ss.SSSXXX`).
|
||||
- **`APP_LOG_JSON_INCLUDE_CALLER_DATA`** — `true` 면 file/method/line 을 추가. **성능 비용이 큽니다.**
|
||||
- **`APP_LOG_JSON_INCLUDE_CALLER_DATA`** — `true` 면 file/method/line 을 추가. **성능 비용이 크다.**
|
||||
- **`APP_LOG_JSON_LOGGER_NAME_LENGTH`** — `0` = 로거 이름 전체, 양수 = 패키지 축약(예: `36` →
|
||||
`dev.caskeleton.bootstrap.Foo` 가 `d.c.bootstrap.Foo` 로).
|
||||
|
||||
@@ -410,19 +410,19 @@ app:
|
||||
### 분산 추적
|
||||
|
||||
- **`OTEL_EXPORTER_OTLP_ENDPOINT`** — OTLP exporter endpoint. 빈 값 = exporter off(스켈레톤에서 OTel
|
||||
SEAM 미활성). 값이 있으면 유효한 URL 이어야 하며 기동 시 `TracingProperties` 가 검증합니다.
|
||||
SEAM 미활성). 값이 있으면 유효한 URL 이어야 하며 기동 시 `TracingProperties` 가 검증한다.
|
||||
- **`APP_TRACING_ENABLED`** — `false` 면 tracing seam 은 꺼지지만, `meta.traceId` 는
|
||||
`WebMvcRequestIdFilter` 가 W3C `traceparent` 로 여전히 생성합니다(D4 disabled-fallback 보장).
|
||||
`WebMvcRequestIdFilter` 가 W3C `traceparent` 로 여전히 생성한다(D4 disabled-fallback 보장).
|
||||
- **`APP_TRACING_SAMPLE_RATE`** — per-profile 기본값을 덮어쓰는 샘플 비율. [0.0, 1.0] float.
|
||||
- profile별 기본값(D6): prod = `0.01`, dev/local = `1.0`.
|
||||
- **결정 — 빈 값으로 두는 이유(D-1 ISSUE-1 fix).** 빈 값이어야 per-profile resolver 의 기본값이
|
||||
실제 tracer sampler 까지 도달합니다(`TracingSampleRateResolver` 가 SSOT). 값을 박으면 프로필별
|
||||
기본값이 무시되므로, 특정 비율을 강제하고 싶을 때만 채웁니다.
|
||||
실제 tracer sampler 까지 도달한다(`TracingSampleRateResolver` 가 SSOT). 값을 박으면 프로필별
|
||||
기본값이 무시되므로, 특정 비율을 강제하고 싶을 때만 채운다.
|
||||
|
||||
### 개인정보: user_principal 가명화
|
||||
|
||||
- **`APP_PRIVACY_PSEUDONYMIZATION_SALT`** — secret 등급 HMAC-SHA-256 salt. `__LOCAL_DEV_` prefix 는 로컬 전용 sentinel 값이며,
|
||||
**prod 에서는 secret-manager 가 주입하는 실제 값**을 써야 합니다.
|
||||
**prod 에서는 secret-manager 가 주입하는 실제 값**을 써야 한다.
|
||||
|
||||
### Spring Boot 기동
|
||||
|
||||
@@ -433,34 +433,34 @@ app:
|
||||
|
||||
### Jackson — 역직렬화 정책
|
||||
|
||||
모든 request DTO 는 Jackson 경계를 지납니다. 아래 4개 스위치는 잘못된 입력을 **조용히 강제 변환하지
|
||||
않고 즉시 실패**하게 만듭니다. 개별 DTO 에 클래스 레벨 `@JsonIgnoreProperties(ignoreUnknown = true)`
|
||||
로 이 정책을 완화하는 것은 **금지**이며 ArchUnit 규칙으로 막혀 있습니다.
|
||||
모든 request DTO 는 Jackson 경계를 지난다. 아래 4개 스위치는 잘못된 입력을 **조용히 강제 변환하지
|
||||
않고 즉시 실패**하게 만든다. 개별 DTO 에 클래스 레벨 `@JsonIgnoreProperties(ignoreUnknown = true)`
|
||||
로 이 정책을 완화하는 것은 **금지**이며 ArchUnit 규칙으로 막혀 있다.
|
||||
|
||||
- **`..._FAIL_ON_UNKNOWN_PROPERTIES`** — `true`: 타입에 선언되지 않은 JSON 키를 거부(Jackson 2.13+
|
||||
기본).
|
||||
- **`..._FAIL_ON_NULL_FOR_PRIMITIVES`** — `true`: primitive 필드에 JSON `null` 이 와도 `0`/`false`
|
||||
로 강제 변환하지 않고 "필수 필드 누락" 에러로 노출. 또는 wrapper 타입(`Integer`/`Long`/`Boolean`)
|
||||
과 `Optional<T>` 를 쓰세요.
|
||||
과 `Optional<T>` 를 쓴다.
|
||||
- **`..._FAIL_ON_IGNORED_PROPERTIES`** — `true`: JSON 에 `@JsonIgnore` 처리된 필드가 들어오면 throw
|
||||
(조용히 버리는 대신 계약 drift 를 노출).
|
||||
- **`..._READ_UNKNOWN_ENUM_VALUES_AS_NULL`** — `false`(Jackson 기본 유지): 모르는 enum 값이 조용히
|
||||
`null` 이 되지 않고 throw 되어 `VALIDATION_FAILED` 로 드러나게 합니다.
|
||||
`null` 이 되지 않고 throw 되어 `VALIDATION_FAILED` 로 드러나게 한다.
|
||||
|
||||
### Jackson — 직렬화 정책
|
||||
|
||||
응답 생성 쪽 정책입니다. 현재 Jackson/Spring Boot 기본값과 같지만 **명시적으로 못박아**, 미래에 Spring
|
||||
Boot 기본값이 바뀌어도 wire 계약이 조용히 깨지지 않게 합니다(`spring.mvc.problemdetails.enabled=false`
|
||||
응답 생성 쪽 정책이다. 현재 Jackson/Spring Boot 기본값과 같지만 **명시적으로 못박아**, 미래에 Spring
|
||||
Boot 기본값이 바뀌어도 wire 계약이 조용히 깨지지 않게 한다(`spring.mvc.problemdetails.enabled=false`
|
||||
와 같은 근거). `JacksonSerializationPolicyTest` 가 강제하며, `new BigDecimal(double)` 생성자는
|
||||
`no_bigdecimal_double_constructor` ArchUnit 규칙으로 금지됩니다.
|
||||
`no_bigdecimal_double_constructor` ArchUnit 규칙으로 금지된다.
|
||||
|
||||
- **`..._WRITE_DATES_AS_TIMESTAMPS`** — `false`(D2 / RFC 3339): `java.time` 값을 ISO-8601 문자열로
|
||||
직렬화(`OffsetDateTime` → `"...Z"`, `LocalDate` → `"YYYY-MM-DD"`). `true` 면 epoch 숫자나
|
||||
`[y,m,d,...]` 배열로 나가 datetime 계약이 깨집니다.
|
||||
- **BigDecimal plain output** — Jackson 3에는 별도 `WRITE_BIGDECIMAL_AS_PLAIN` 설정 키가 없습니다.
|
||||
`[y,m,d,...]` 배열로 나가 datetime 계약이 깨진다.
|
||||
- **BigDecimal plain output** — Jackson 3에는 별도 `WRITE_BIGDECIMAL_AS_PLAIN` 설정 키가 없다.
|
||||
`JacksonSerializationPolicyTest` 가 `"12300000000.00"` plain 출력을 직접 검증하고,
|
||||
`no_bigdecimal_double_constructor` ArchUnit 규칙이 부정확한 `new BigDecimal(double)` 생성을
|
||||
금지합니다. 엔드포인트별 string vs number 선택은 그대로 명시적으로 둡니다(공개/금융 API 는 string,
|
||||
금지한다. 엔드포인트별 string vs number 선택은 그대로 명시적으로 둔다(공개/금융 API 는 string,
|
||||
내부 API 는 number+plain).
|
||||
|
||||
### 서버 / Tomcat
|
||||
@@ -493,9 +493,9 @@ Boot 기본값이 바뀌어도 wire 계약이 조용히 깨지지 않게 합니
|
||||
기동 실패. 예: `https://keycloak.example.com/realms/ca-skeleton`.
|
||||
- **`APP_SECURITY_JWT_AUDIENCE`** — 기대하는 `aud` claim(쉼표 목록 가능, 하나라도 맞으면 통과).
|
||||
JWT 모드에서 **필수** — 비어 있으면 기동 실패. 이 목록의 client 에 대한 `resource_access` role 만
|
||||
권한으로 읽습니다. 예: `ca-skeleton-api`.
|
||||
- **`SECURITY_PUBLIC_PATHS`** — 인증을 우회하는 경로 CSV. `api-base-path` 뒤의 full path 를 씁니다(예:
|
||||
`/api/healthcheck`). 이 값의 변경은 `verifyPublicPathSnapshot` 게이트가 감시합니다(위 build.gradle
|
||||
권한으로 읽는다. 예: `ca-skeleton-api`.
|
||||
- **`SECURITY_PUBLIC_PATHS`** — 인증을 우회하는 경로 CSV. `api-base-path` 뒤의 full path 를 쓴다(예:
|
||||
`/api/healthcheck`). 이 값의 변경은 `verifyPublicPathSnapshot` 게이트가 감시한다(위 build.gradle
|
||||
설명 참조).
|
||||
|
||||
### CORS
|
||||
@@ -512,7 +512,7 @@ Boot 기본값이 바뀌어도 wire 계약이 조용히 깨지지 않게 합니
|
||||
### 프로파일과 데이터베이스
|
||||
|
||||
프로파일마다 데이터스토어가 다르고, 그 차이는 `app-bootstrap/src/main/resources/application-*.yml`
|
||||
가 소유합니다.
|
||||
가 소유한다.
|
||||
|
||||
| 프로파일 | 데이터스토어 | 스키마 소유자 | 외부 인프라 |
|
||||
| --- | --- | --- | --- |
|
||||
@@ -521,45 +521,45 @@ Boot 기본값이 바뀌어도 wire 계약이 조용히 깨지지 않게 합니
|
||||
| `prod` | PostgreSQL | Flyway `db/migration/postgresql` | 필요 |
|
||||
| `bootRunH2` (명시적 opt-out) | H2 in-memory | Hibernate `ddl-auto: create-drop` | 없음 |
|
||||
|
||||
`./gradlew :app-bootstrap:bootRun` 은 기본 `local` 프로파일에서도 PostgreSQL/Flyway를 사용합니다.
|
||||
`./gradlew :app-bootstrap:bootRun` 은 기본 `local` 프로파일에서도 PostgreSQL/Flyway를 사용한다.
|
||||
로컬과 운영의 schema owner를 다르게 두면 migration-only 결함을 개발 중에 놓치기 때문에 바뀐
|
||||
계약입니다. 먼저 아래 Compose PostgreSQL을 띄운 뒤 `bootRun`을 실행하세요.
|
||||
계약이다. 먼저 아래 Compose PostgreSQL을 띄운 뒤 `bootRun`을 실행한다.
|
||||
|
||||
Docker 없이 빠르게 wiring·요청/응답·애플리케이션 로직만 확인하려면
|
||||
`./gradlew :app-bootstrap:bootRunH2`를 명시적으로 사용합니다. 이 태스크만
|
||||
`./gradlew :app-bootstrap:bootRunH2`를 명시적으로 사용한다. 이 태스크만
|
||||
`APP_PERSISTENCE_VENDOR=h2`, `APP_FLYWAY_ENABLED=false`,
|
||||
`APP_DATASOURCE_DDL_AUTO=create-drop`을 주입합니다. H2에는 PostgreSQL migration tree가 없으므로
|
||||
migration/vendor 계약의 증거로 사용하지 않습니다. 멱등성 provider(`APP_IDEMPOTENCY_PROVIDER`)는
|
||||
`disabled`(기본)나 `redis`로 둡니다. `postgresql`은 H2 data source에서 기동을 거부합니다.
|
||||
`APP_DATASOURCE_DDL_AUTO=create-drop`을 주입한다. H2에는 PostgreSQL migration tree가 없으므로
|
||||
migration/vendor 계약의 증거로 사용하지 않는다. 멱등성 provider(`APP_IDEMPOTENCY_PROVIDER`)는
|
||||
`disabled`(기본)나 `redis`로 둔다. `postgresql`은 H2 data source에서 기동을 거부한다.
|
||||
|
||||
`dev` 를 호스트에서 띄우려면(`SPRING_PROFILES_ACTIVE=dev`) PostgreSQL 이 필요합니다.
|
||||
`dev` 를 호스트에서 띄우려면(`SPRING_PROFILES_ACTIVE=dev`) PostgreSQL 이 필요하다.
|
||||
`compose.yaml` 의 `db` 서비스(`jpa` profile)가 루프백(`127.0.0.1:5433`)에만 게시하며, 이 주소가
|
||||
아래 `APP_DATASOURCE_URL` 의 커밋된 기본값입니다. 저장소 루트에서 실행합니다.
|
||||
아래 `APP_DATASOURCE_URL` 의 커밋된 기본값이다. 저장소 루트에서 실행한다.
|
||||
|
||||
```bash
|
||||
docker compose up -d --wait db
|
||||
```
|
||||
|
||||
컨테이너로 띄우는 `scripts/bootstrap-local.sh` 경로는 이 호스트 포트를 쓰지 않습니다. compose 가 app
|
||||
컨테이너의 `APP_DATASOURCE_URL` 을 내부 네트워크 주소 `jdbc:postgresql://db:5432/...` 로 덮어씁니다.
|
||||
컨테이너로 띄우는 `scripts/bootstrap-local.sh` 경로는 이 호스트 포트를 쓰지 않는다. compose 가 app
|
||||
컨테이너의 `APP_DATASOURCE_URL` 을 내부 네트워크 주소 `jdbc:postgresql://db:5432/...` 로 덮어쓴다.
|
||||
|
||||
`app.persistence.vendor`(`postgresql` | `h2`)가 어느 vendor 구성을 조립할지 고르는 단일
|
||||
스위치입니다. 값이 둘 중 하나가 아니면 기동이 실패하고, prod 에서 `h2` 이거나 datasource URL 이
|
||||
`jdbc:h2:` 이면 `PersistenceVendorProdSafetyValidator` 가 기동을 거부합니다(env 로 덮어써도 동일).
|
||||
스위치다. 값이 둘 중 하나가 아니면 기동이 실패하고, prod 에서 `h2` 이거나 datasource URL 이
|
||||
`jdbc:h2:` 이면 `PersistenceVendorProdSafetyValidator` 가 기동을 거부한다(env 로 덮어써도 동일).
|
||||
|
||||
### 데이터베이스 (PostgreSQL)
|
||||
|
||||
- **`APP_DATASOURCE_URL`** — JDBC URL(예: `jdbc:postgresql://host:5432/dbname`). `dev`·`prod` 에서
|
||||
쓰이며, 커밋된 기본값 `jdbc:postgresql://localhost:5433/ca_skeleton` 은 위 compose `db` 서비스의
|
||||
호스트 주소입니다.
|
||||
호스트 주소다.
|
||||
- **`APP_DATASOURCE_USERNAME`** / **`APP_DATASOURCE_PASSWORD`** — DB 접속 계정.
|
||||
- **`APP_DATASOURCE_DRIVER`** — Hibernate dialect 에 맞는 드라이버(예: `org.postgresql.Driver`).
|
||||
- **`APP_DATASOURCE_DDL_AUTO`** — `none` | `validate` | `update` | `create` | `create-drop`. **prod
|
||||
는 `validate` 또는 `none`**(`JpaDangerousConfigurationGuard` 가 기동 시 강제). `local` 은 이 값을 쓰지
|
||||
않습니다 — `application-local.yml` 이 `create-drop` 으로 고정합니다.
|
||||
않는다 — `application-local.yml` 이 `create-drop` 으로 고정한다.
|
||||
- **`APP_DATASOURCE_SHOW_SQL`** — `true` 면 SQL 을 로그로 echo.
|
||||
- **`APP_DATASOURCE_FORMAT_SQL`** — SQL pretty-print(`SHOW_SQL=true` 일 때만 의미 있음).
|
||||
- **`APP_DATASOURCE_OPEN_IN_VIEW`** — Hibernate OSIV. **prod 에서는 피하세요.**
|
||||
- **`APP_DATASOURCE_OPEN_IN_VIEW`** — Hibernate OSIV. **prod 에서는 피한다.**
|
||||
|
||||
**HikariCP 커넥션 풀**
|
||||
|
||||
@@ -568,10 +568,10 @@ docker compose up -d --wait db
|
||||
- **`APP_DATASOURCE_CONNECTION_TIMEOUT`** — `acquire()` 가 실패하기 전 대기 시간(ms).
|
||||
- **`APP_DATASOURCE_POOL_IDLE_TIMEOUT`** — idle 연결 회수 임계 시간(ms).
|
||||
- **`APP_DATASOURCE_POOL_MAX_LIFETIME`** — 연결의 최대 수명(ms). broker timeout 전에 rotate 하도록
|
||||
설정합니다.
|
||||
설정한다.
|
||||
|
||||
### 관리 포트 / Actuator
|
||||
|
||||
- **결정 — management 포트 분리.** actuator 엔드포인트를 앱 API 와 **같은 소켓에 노출하지 않으려고**
|
||||
별도 management 포트를 둡니다.
|
||||
- **`MANAGEMENT_SERVER_PORT`** — 1~65535 정수. **`APP_SERVER_PORT`(8080)와 달라야 합니다.**
|
||||
별도 management 포트를 둔다.
|
||||
- **`MANAGEMENT_SERVER_PORT`** — 1~65535 정수. **`APP_SERVER_PORT`(8080)와 달라야 한다.**
|
||||
|
||||
Reference in New Issue
Block a user