@wooojin/forgen 0.4.7 → 0.4.9

package/assets/dev-guide/be/principles/common.md

@@ -0,0 +1,433 @@
+---
+title: 공통 BE 원칙 (스택 중립)
+version: 2026-05-18
+sources:
+  - sources/12factor/
+  - sources/sre-book/
+  - sources/owasp-api/
+  - sources/otel/
+  - sources/ddia/
+  - sources/api-design/
+  - sources/postgres/
+---
+
+# 공통 BE 원칙
+
+> 모든 백엔드 코드(Node.js/Go/기타)에 적용되는 합의 원칙.
+> 스택 특화 가이드는 [`node.md`](./node.md), [`go.md`](./go.md) 참조.
+
+## 출처 우선순위 (충돌 시)
+
+충돌이 발생하면 다음 순서로 더 높은 우선순위 출처를 따른다:
+
+1. **12-Factor App** — 실행 환경 이식성·운영 합의 (config, logs, disposability)
+2. **Google SRE Book** — 가용성·SLO·에러 예산 기준
+3. **OWASP API Security Top 10** — 보안 기준선 (2023)
+4. **OpenTelemetry** — 관찰가능성 계측 표준
+5. **DDIA** (Designing Data-Intensive Applications) — 데이터 모델·분산 시스템 의사결정
+6. **프레임워크 공식 문서** — Fastify / NestJS / Go stdlib 등
+7. **벤더 권장** — AWS / GCP / Stripe 등
+
+사용자 영향 우선순위: **security > availability > correctness > performance > readability**.
+
+---
+
+## A. API 설계 4원칙
+
+> fe-guide의 코드 품질 4원칙(가독성/예측성/응집도/결합도)과 미러링.
+> 각 원칙은 트레이드오프 관계다. 동시 만족 불가능 시 위 우선순위로 판단.
+
+### A.1 명시성 (Explicitness) — 최우선
+
+**API 계약은 코드보다 먼저, 명시적으로 존재해야 한다.**
+
+- OpenAPI/Protobuf 스펙 파일이 구현보다 먼저 작성되어야 한다. 구현을 reverse로 생성한 스펙은 계약이 아니다.
+- 요청/응답 필드의 optional/required를 스펙과 검증 코드에서 동일하게 명시한다.
+  - 스펙에 optional인 필드를 서버 검증에서 required 취급하면 명세 위반.
+  - 반대로 required 필드를 서버에서 검증 없이 통과시키면 runtime error 원인.
+- **nullable vs optional은 다르다**. `"value": null`(nullable, 필드 존재) vs 필드 없음(absent, optional). 혼용 금지.
+- 에러 응답 스펙도 동일하게 정의한다. "에러 시 알아서"는 계약이 아니다.
+
+근거: `sources/api-design/`
+
+### A.2 일관성 (Consistency)
+
+**같은 개념은 API 전체에서 동일한 이름·모양을 가져야 한다.**
+
+- 리소스 이름: 복수형 명사 (`/users`, `/orders`). 동사 금지 (`/getUser` X).
+- HTTP 메서드: CRUD → GET/POST/PUT·PATCH/DELETE. 멱등성 기반으로 선택.
+  - GET: 조회, 부작용 없음
+  - POST: 생성 또는 비멱등 액션
+  - PUT: 전체 교체 (멱등)
+  - PATCH: 부분 수정 (멱등이 바람직하나 필수 아님)
+  - DELETE: 삭제 (멱등)
+- 날짜/시간: 항상 ISO 8601 UTC (`2026-05-18T07:00:00Z`). epoch int는 ms 단위 명시.
+- 페이지네이션: 커서 기반 우선 (`cursor` + `limit`). 오프셋 기반은 대용량에서 퇴화.
+  ```json
+  { "data": [...], "nextCursor": "eyJpZCI6MTIzfQ==", "hasMore": true }
+  ```
+- 에러 코드: `SNAKE_CASE` 상수 (`PAYMENT_DECLINED`, `RESOURCE_NOT_FOUND`). HTTP 상태만으로 구분 금지.
+
+근거: `sources/api-design/` (Stripe API + GitHub API + Google AIP)
+
+### A.3 예측 가능성 (Predictability)
+
+**같은 입력에는 항상 같은 출력. 부작용은 명시된 것만.**
+
+- GET 요청이 데이터를 변경해서는 안 된다. CQRS(명령/조회 분리)를 기본 마음가짐으로.
+- 같은 조건에서 동일 엔드포인트는 항상 같은 HTTP 상태 코드와 응답 구조를 반환한다.
+- 벌크 연산에서 일부 성공/일부 실패 시 응답 모양: `{ "succeeded": [...], "failed": [{"id": ..., "error": {...}}] }` 형식으로 명시. 207 Multi-Status 활용.
+- **숨은 부작용 금지**: 조회 API 내부에서 이벤트 발행, 통계 갱신 등을 몰래 수행하지 않는다. 필요하면 별도 endpoint 또는 명시적 문서화.
+
+### A.4 진화 가능성 (Evolvability)
+
+**API는 클라이언트를 깨지 않고 변경될 수 있어야 한다.**
+
+- **하위 호환 변경** (클라이언트 알림 없이 가능):
+  - 새 optional 필드 추가
+  - 새 endpoint 추가
+  - 새 enum 값 추가 (클라이언트가 unknown 처리해야 한다는 전제)
+- **파괴적 변경** (버저닝 또는 deprecation notice 필수):
+  - 필드 제거 또는 이름 변경
+  - 타입 변경 (string → int)
+  - 기존 enum 값 제거
+  - HTTP 메서드/경로 변경
+- URL 버저닝: `/v1/`, `/v2/` — 단순하고 캐시 친화적.
+  - Path 버저닝 우선. Header 버저닝은 캐시 레이어에서 문제.
+- Deprecation 정책: 최소 6개월 notice + `Deprecation` 응답 헤더 부착.
+  ```
+  Deprecation: Sun, 01 Jan 2027 00:00:00 GMT
+  Sunset: Sun, 01 Jan 2027 00:00:00 GMT
+  Link: <https://docs.example.com/migration/v2>; rel="deprecation"
+  ```
+
+근거: `sources/api-design/` (Google AIP-180)
+
+---
+
+## B. Error Model
+
+**절대 silent fail 금지. 에러는 구조화된 값으로 반환한다.**
+
+### B.1 에러 응답 구조
+
+모든 에러 응답은 다음 구조를 준수한다:
+
+```json
+{
+  "error": {
+    "code": "PAYMENT_DECLINED",
+    "message": "결제가 거절되었습니다. 카드 정보를 확인하세요.",
+    "details": [
+      {
+        "field": "card.number",
+        "reason": "INVALID_FORMAT"
+      }
+    ],
+    "requestId": "req_01HX2V3K8..."
+  }
+}
+```
+
+- `code`: 기계가 읽는 SNAKE_CASE 상수. 클라이언트 분기 처리용.
+- `message`: 사람이 읽는 설명. 필요 시 다국어화.
+- `details`: 필드별 검증 오류 배열 (optional). 빈 배열이면 생략.
+- `requestId`: 로그 추적용. 항상 포함. (correlation ID)
+
+### B.2 4xx vs 5xx 경계
+
+| 상황 | 코드 | 원칙 |
+|------|------|------|
+| 클라이언트 입력 오류 | 400 | 클라이언트가 고쳐야 함 — 재시도 의미 없음 |
+| 인증 없음 | 401 | 자격증명 제공 필요 |
+| 권한 없음 | 403 | 자격증명 있어도 불가 |
+| 리소스 없음 | 404 | 존재하지 않음 |
+| 비즈니스 규칙 위반 | 422 | 입력 형식은 맞지만 도메인 거부 |
+| 속도 제한 | 429 | `Retry-After` 헤더 필수 |
+| 서버 내부 오류 | 500 | 서버가 고쳐야 함 |
+| 외부 의존성 실패 | 502/503 | 인프라/upstream 문제 |
+
+**황금 규칙**: 4xx는 클라이언트 책임, 5xx는 서버 책임. 서버 오류를 200 + `{ "success": false }` 로 숨기지 마라.
+
+### B.3 에러 로깅 기준
+
+- 4xx: `warn` 레벨 (클라이언트 문제, 운영 알람 불필요)
+- 5xx: `error` 레벨 + stack trace + requestId (즉시 알람 대상)
+- 빈 catch 블록 절대 금지. 최소 `logger.error(err, { context: '...' })` + re-throw.
+
+---
+
+## C. Observability Triple
+
+**로그 + 메트릭 + 트레이스. 세 가지 없으면 프로덕션 불가.**
+
+### C.1 구조화 로그 (Structured Logging)
+
+근거: `sources/sre-book/`, `sources/12factor/`
+
+- **JSON 형식** 강제. 평문 로그는 파싱 불가 → 검색 불가.
+  ```json
+  {
+    "timestamp": "2026-05-18T07:00:00.123Z",
+    "level": "info",
+    "message": "Order created",
+    "service": "order-service",
+    "traceId": "4bf92f3577b34da6a3ce929d0e0e4736",
+    "spanId": "00f067aa0ba902b7",
+    "orderId": "ord_01HX2V3K8",
+    "userId": "usr_01HX2V3K8",
+    "durationMs": 142
+  }
+  ```
+- **민감 정보 금지**: 비밀번호, 카드번호, 개인식별정보를 로그에 직접 기록하지 않는다. 마스킹 또는 토큰화.
+- 12-Factor App Factor 11: 앱은 로그를 파일에 쓰지 않고 stdout으로만 출력. 수집은 인프라 책임.
+
+### C.2 메트릭 — RED Method
+
+근거: `sources/sre-book/` (4 Golden Signals의 서비스 중심 변형)
+
+모든 서비스/엔드포인트에 대해:
+
+| 메트릭 | 설명 | 예시 |
+|--------|------|------|
+| **Rate** | 요청 수 / 초 | `http_requests_total{method, path, status}` |
+| **Errors** | 에러 비율 (5xx) | `http_errors_total{method, path, status}` |
+| **Duration** | 응답 시간 분포 | `http_request_duration_seconds{quantile}` |
+
+- histogram 버킷: 5ms, 25ms, 50ms, 100ms, 250ms, 500ms, 1s, 2.5s, 5s, 10s.
+- p50/p95/p99 SLO는 코드베이스 README 또는 `docs/slo.md`에 명시 의무.
+
+### C.3 분산 트레이스 (OpenTelemetry)
+
+근거: `sources/otel/`
+
+- **자동 계측(auto-instrumentation) 먼저**: HTTP 서버, DB 클라이언트, 메시지 큐는 OTel SDK 자동 계측 사용.
+- **수동 span 추가 기준**: 비즈니스 로직 경계, 외부 API 호출, 중요한 내부 함수.
+  ```typescript
+  const span = tracer.startSpan('processPayment');
+  try {
+    span.setAttributes({ 'payment.amount': amount, 'payment.currency': currency });
+    const result = await chargeCard(cardId, amount);
+    span.setStatus({ code: SpanStatusCode.OK });
+    return result;
+  } catch (err) {
+    span.recordException(err);
+    span.setStatus({ code: SpanStatusCode.ERROR });
+    throw err;
+  } finally {
+    span.end();
+  }
+  ```
+- W3C TraceContext 헤더(`traceparent`) 전파: 모든 outbound HTTP 요청에 포함.
+- `traceId`는 에러 응답의 `requestId`와 동일하게 사용해 로그-트레이스 연결.
+
+---
+
+## D. Idempotency & Retry
+
+### D.1 멱등성 설계
+
+- GET / DELETE / PUT: 본래 멱등. 재시도 안전.
+- POST (생성 액션): **Idempotency-Key** 헤더로 멱등성 보장.
+  ```
+  POST /v1/payments
+  Idempotency-Key: a8098c1a-f86e-11da-bd1a-00112444be1e
+  ```
+  - 서버는 Key를 캐시하고 동일 Key 재요청 시 캐시된 응답 반환 (24시간~7일 TTL).
+  - 응답에 `Idempotency-Key` 반영 권장.
+- **자연스럽지 않은 멱등성 강제 금지**: 복잡한 비즈니스 로직을 억지로 멱등화하기보다 클라이언트 재시도 전략을 명확히 하는 것이 낫다.
+
+### D.2 재시도 전략 (Exponential Backoff + Jitter)
+
+클라이언트 재시도 기준:
+
+- 재시도 가능: 429, 500, 502, 503, 504, 네트워크 타임아웃
+- 재시도 불가: 400, 401, 403, 404, 422 (클라이언트 오류는 재시도 의미 없음)
+
+권장 공식:
+```
+delay = min(base * 2^attempt + random(0, base), max_delay)
+```
+- base: 1s, max_delay: 30s, max_attempts: 5
+- **Full Jitter**: `random(0, min(cap, base * 2^attempt))` — thundering herd 방지
+
+서버 측: 429 응답에 `Retry-After: 60` 헤더 필수.
+
+---
+
+## E. Security Baseline
+
+근거: `sources/owasp-api/`
+
+### E.1 입력 검증 경계
+
+**외부에서 들어오는 모든 데이터는 신뢰하지 않는다.** 신뢰 경계를 명확히 그어라.
+
+```
+[Client] → [API Gateway / Load Balancer] → [Service] → [DB/Storage]
+              ↑ TLS Termination               ↑ 여기서 검증
+              ↑ Rate Limiting                  ↑ Business rule 검증
+              ↑ Auth token 검증
+```
+
+- **경계에서 즉시 검증**: 컨트롤러/핸들러 진입 시 스키마 검증 통과 후에만 비즈니스 로직 진입.
+- Path parameter, query string, request body, headers 모두 검증 대상.
+- SQL/NoSQL Injection: ORM/parameterized query 강제. 문자열 concatenation으로 쿼리 작성 절대 금지.
+- 파일 업로드: MIME type + magic bytes 검증, 저장 경로 path traversal 방지.
+
+### E.2 인증/인가 분리
+
+- **인증(Authentication)**: "누구인가?" — JWT / OAuth 2.0 / API Key
+- **인가(Authorization)**: "무엇을 할 수 있는가?" — RBAC / ABAC
+- **OWASP API1**: Broken Object Level Authorization — 매 요청마다 리소스 소유권 확인. `userId`를 JWT에서 추출, 경로 파라미터 `userId`와 일치 검증. URL 파라미터 변조로 타인 데이터 접근하는 패턴.
+- 인가 로직은 서비스 레이어에서. 프레임워크 미들웨어에 전적으로 의존 금지.
+
+### E.3 비밀 관리
+
+- `.env` 파일 커밋 금지 (`.gitignore` + pre-commit hook).
+- 프로덕션 시크릿: AWS Secrets Manager / GCP Secret Manager / Vault.
+- 코드에 하드코딩된 시크릿 탐지: `git-secrets` 또는 CI gitleaks.
+- **환경별 분리**: dev/staging/prod 시크릿 완전 분리. dev 시크릿이 prod에 닿아서는 안 됨.
+- 12-Factor App Factor 3: Config를 환경변수에 저장.
+
+### E.4 OWASP API Security Top 10 (2023) 매핑
+
+| # | 취약점 | 핵심 대응 |
+|---|--------|-----------|
+| API1 | Broken Object Level Authorization | 모든 리소스 접근에 소유권 검증 |
+| API2 | Broken Authentication | JWT 서명 알고리즘 명시 (`RS256`), 토큰 만료 검증 |
+| API3 | Broken Object Property Level Auth | 응답에서 민감 필드 선택적 노출 (allowlist projection) |
+| API4 | Unrestricted Resource Consumption | Rate limiting + 페이로드 크기 제한 |
+| API5 | Broken Function Level Authorization | admin/user 기능 분리, HTTP 메서드 별 권한 검증 |
+| API6 | Unrestricted Access to Sensitive Flows | 로그인/OTP에 rate limit + account lockout |
+| API7 | Server Side Request Forgery | 외부 URL fetch 전 allowlist 검증 |
+| API8 | Security Misconfiguration | CORS, 불필요 HTTP 메서드, 디버그 엔드포인트 비활성화 |
+| API9 | Improper Inventory Management | API 버전 폐기 정책 + 스테이징 엔드포인트 노출 금지 |
+| API10 | Unsafe Consumption of APIs | 외부 API 응답도 검증 (신뢰하지 않음) |
+
+---
+
+## F. Performance Baseline
+
+### F.1 SLO 명시 의무
+
+**p50/p95/p99 SLO를 코드와 함께 문서화하지 않으면 "빠르다"는 주장은 의미 없다.**
+
+- `docs/slo.md` 또는 서비스 README에 명시:
+  ```
+  | Endpoint         | p50   | p95    | p99    | Error Budget |
+  |------------------|-------|--------|--------|--------------|
+  | GET /orders      | 50ms  | 200ms  | 500ms  | 99.9% / mo   |
+  | POST /payments   | 200ms | 500ms  | 1000ms | 99.95% / mo  |
+  ```
+- 신규 기능 추가 시 해당 엔드포인트 SLO 영향도 검토 의무.
+
+### F.2 N+1 쿼리 금지
+
+ORM 사용 시 N+1은 가장 흔한 성능 함정:
+
+```typescript
+// WRONG: N개 주문마다 N번 쿼리
+const orders = await Order.findAll();
+for (const order of orders) {
+  order.user = await User.findById(order.userId); // N번!
+}
+
+// RIGHT: JOIN 또는 별도 IN 쿼리로 한 번에
+const orders = await Order.findAll({ include: [User] });
+// 또는
+const userIds = orders.map(o => o.userId);
+const users = await User.findAll({ where: { id: { [Op.in]: userIds } } });
+```
+
+- Prisma: `include` / `select` 명시. `findMany` 후 루프 내 `findUnique` 패턴 금지.
+- GORM: `Preload`, `Joins` 활용.
+- DataLoader 패턴: GraphQL 또는 배치 처리 컨텍스트.
+
+### F.3 캐싱 계층 명시
+
+캐싱 전략을 코드 주석 또는 문서에 명시:
+
+```
+[요청] → [CDN / Edge Cache] → [API] → [Redis / Memcached] → [DB]
+```
+
+| 계층 | 적합한 데이터 | TTL 기준 |
+|------|---------------|----------|
+| CDN Edge | 공개 정적/준정적 API | 분~시간 |
+| Redis/Memcached | 세션, 자주 읽히는 비공개 데이터 | 초~분 |
+| Local (in-process) | 설정, enum 같은 불변 데이터 | 앱 수명 |
+
+- **캐시 무효화 전략 명시**: TTL 기반 / 이벤트 기반 중 선택. "나중에 생각"은 캐시 불일치 버그 원인.
+- **캐시 스탬피드 방지**: 만료 TTL에 jitter 추가 + lock/singleflight 패턴.
+
+---
+
+## G. DB 기본기
+
+근거: `sources/ddia/`, `sources/postgres/`
+
+### G.1 트랜잭션 경계 명시
+
+- 트랜잭션 범위를 코드 주석으로 명시:
+  ```typescript
+  // TX: order 생성 + stock 차감 원자적 처리
+  await db.transaction(async (trx) => {
+    await Order.create({ ... }, { transaction: trx });
+    await Stock.decrement('quantity', { by: 1, where: { productId }, transaction: trx });
+  });
+  ```
+- **분산 트랜잭션은 피한다**. 마이크로서비스 간 2PC 대신 Saga 패턴 또는 보상 트랜잭션.
+- 트랜잭션 내에서 외부 API 호출 금지 — 네트워크 지연이 lock 보유 시간을 늘린다.
+
+### G.2 무중단 마이그레이션 (Expand/Contract)
+
+**DB 스키마 변경은 배포와 분리해야 한다.** Breaking change를 피하는 3단계:
+
+```
+Phase 1 — Expand: 새 컬럼/테이블 추가. 기존 컬럼 유지. 앱은 둘 다 쓸 수 있게.
+Phase 2 — Migrate: 기존 데이터를 새 구조로 이전. 앱 배포.
+Phase 3 — Contract: 구 컬럼/테이블 제거. (Phase 2 완료 후 최소 1 릴리스 후)
+```
+
+- `DROP COLUMN` / `RENAME COLUMN` / 타입 변경은 반드시 Expand/Contract.
+- NOT NULL 컬럼 추가: 기본값 있는 nullable로 먼저 추가 → 데이터 채움 → NOT NULL 제약.
+- 마이그레이션 도구: Flyway / Liquibase / Alembic / golang-migrate. 파일 이름에 버전/타임스탬프.
+
+### G.3 인덱스 의도 주석
+
+```sql
+-- 주문 목록 API: WHERE user_id = ? ORDER BY created_at DESC LIMIT 20
+-- 복합 인덱스로 index scan + filesort 없이 처리
+CREATE INDEX idx_orders_user_created
+  ON orders(user_id, created_at DESC);
+```
+
+- 인덱스 추가 시 반드시 "어떤 쿼리를 위한 인덱스인가" 주석.
+- 사용되지 않는 인덱스는 제거한다 (write 부하 + vacuum 비용).
+- `EXPLAIN ANALYZE` 결과를 PR에 첨부하는 관행을 유지한다.
+
+---
+
+## H. 안티패턴 카탈로그 (리뷰에서 즉시 [HIGH] 잡아라)
+
+| 안티패턴 | 근거 | 픽스 |
+|----------|------|------|
+| 빈 catch 블록 | global rules / anti-pattern | 최소 로그 + re-throw |
+| 50줄 초과 함수 | global rules | 책임별 분리 |
+| 중첩 깊이 5+ | global rules | early return |
+| HTTP 200 + `{ "success": false }` | Error Model B.2 | 적절한 4xx/5xx 사용 |
+| 문자열 concatenation SQL | Security E.1 | parameterized query |
+| 루프 내 DB 쿼리 (N+1) | Performance F.2 | 배치 쿼리 / JOIN |
+| 하드코딩 시크릿 | Security E.3 | 환경변수 / 시크릿 매니저 |
+| 트랜잭션 내 외부 API 호출 | DB G.1 | 트랜잭션 밖으로 이동 |
+| 분산 트랜잭션 (2PC) | DB G.1 | Saga / 보상 트랜잭션 |
+| SLO 없이 "빠르다" 주장 | Performance F.1 | docs/slo.md 작성 |
+| 인덱스 의도 주석 없음 | DB G.3 | 쿼리 → 인덱스 주석 |
+| URL 파라미터로 타인 리소스 접근 | OWASP API1 | 소유권 검증 |
+| 응답에 전체 모델 그대로 반환 | OWASP API3 | allowlist projection |
+| 로그에 개인정보 | Security E.1 | 마스킹 / 토큰화 |
+| 환경별 시크릿 미분리 | Security E.3 | 환경별 완전 분리 |
+| `DROP COLUMN` 즉시 실행 | DB G.2 | Expand/Contract 패턴 |
+| 평문 로그 (비구조화) | Observability C.1 | JSON 구조화 로그 |
+| traceId 없는 에러 응답 | Observability C.3 | requestId 포함 |