ttipo
700a100a38
규칙과 구현이 어긋나 있던 부분을 바로잡고, 작업하며 발견한 함정을 기록한다.
- 스킬 문서의 "기본 제공 골격" 표를 실제 파일 목록과 일치시킴
- 커밋 전 체크리스트에 테스트 실행·에러 코드 동기화 절차 추가
- 커밋 규칙에 scope·브랜치 전략·PR 규칙 보강
- 새 규칙 파일(api-design, logging)을 CLAUDE.md import 목록에 등록하고,
규칙 추가 시 등록이 필수라는 메타 규칙 명시
- README 를 현재 구조에 맞게 갱신 (traceId·페이지네이션·에러 코드 SSOT·로컬 개발 명령)
작업 중 실제로 겪은 함정들을 규칙으로 남긴다:
- Windows 에서 npm install 하면 Linux 전용 optional 의존성이 lock 에서 잘려
Docker 의 npm ci 가 실패한다 → 의존성 변경은 컨테이너 안에서 수행
- --build 만으로는 node_modules 익명 볼륨이 갱신되지 않아
새 패키지가 컨테이너에 반영되지 않는다 → --renew-anon-volumes 필요
- compose 는 미정의 변수를 빈 문자열로 주입해 Number('')===0 함정이 생긴다
- dev 는 PID 1 이 npm 이라 graceful shutdown 확인은 운영 이미지로 해야 한다
- Redis 는 컨테이너만 떠 있고 사용처가 없다 — 확장 지점임을 명시
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
3.1 KiB
3.1 KiB
name, description
| name | description |
|---|---|
| env-structure | 환경변수 단일 진실 공급원(SSOT) 구조 — 루트 .env.{APP_ENV} 가 모든 설정의 SSOT, docker-compose 가 서비스에 주입. 새 설정값 추가/서비스 env 작성 규칙. |
환경변수 구조 (단일 진실 공급원: 루트 .env)
이 템플릿은 루트 .env.{APP_ENV} 가 모든 설정의 단일 진실 공급원(SSOT) 이다.
값을 한 곳에서만 관리하기 위해, 서비스(backend/frontend)는 자체 env에 값을 중복 작성하지 않고 루트 → docker-compose 가 주입한 값을 그대로 사용한다.
루트 .env.{APP_ENV}
│ (docker compose --env-file 로 로드)
├─▶ backend : env_file + environment 로 DB/Redis/CORS/포트 주입
│ (backend/.env.{APP_ENV} 는 "존재"만 하면 됨, 내용 최소)
├─▶ frontend : BACKEND_API_URL → build arg(VITE_API_BASE_URL) 로 주입
├─▶ db : DB_USER/DB_PASSWORD/DB_NAME, DB_DATA_DIR 볼륨
└─▶ redis : REDIS_PASSWORD, REDIS_DATA_DIR 볼륨
규칙:
- 새 설정값은 루트
.env.{APP_ENV}에 먼저 추가하고, 필요한 서비스에docker-compose.yml의environment/args로 전달한다. - 서비스 자체 env 파일에는 루트에서 내려주지 않는 고유 값만 작성한다. (예: 백엔드
JWT_SECRET) - compose 는 정의되지 않은 변수를 빈 문자열로 주입한다. 코드에서
??기본값만 쓰면Number('')===0같은 함정에 빠진다 — 숫자 설정값은shared/utils/env.ts의parsePositiveInt()처럼 빈 문자열까지 방어하는 파서를 거친다. (기존.env를 쓰는 사람이 새 키를 추가하지 않아도 안전해야 한다) docker-compose.yml의env_file지시자 때문에backend/.env.{APP_ENV}파일은 비어 있어도 존재해야 한다.- Flutter 는 예외 — docker-compose 대상이 아니므로
flutter/.env에서API_URL을 독립적으로 관리한다. - 모든 env 파일은 커밋 금지,
*.example만 커밋한다. (.gitignore의!*.example재포함 규칙) - 설정이 잘못되면 서버가 뜨지 않아야 한다(fail-fast). 조용히 기본값으로 굴러가다 운영에서 터지는 것이 더 위험하다.
검증은
backend/src/shared/config/env.validation.ts가 담당하며ConfigModule.forRoot({ validate })에 연결되어 있다.- 숫자 항목은 형식 검사 (모든 환경)
- 운영 환경:
DB_HOST/DB_USER/DB_PASSWORD/DB_NAME필수 - 운영 환경:
change-me·password같은 예시 값이 그대로 배포되는 것을 차단 - 문제는 하나씩이 아니라 한 번에 모아서 보여준다 (재기동 반복 방지)
- 새 필수 설정을 추가하면 이 파일의 목록과 테스트도 함께 갱신한다
루트 env의 대표 키:
PROJECT_NAME,APP_ENV,BUILD_MODE, 각종*_PORT,BACKEND_API_URL,CORS_ORIGIN,DB_*/DB_DATA_DIR,REDIS_*/REDIS_DATA_DIR,THROTTLE_TTL_MS/THROTTLE_LIMIT. 실제 목록은.env.development.example참조. 실행/배포 명령은 docker, 보안 규칙은 security 참조.