ttipo
c5d165275c
세 클라이언트가 공유하는 계약 중 정의가 빠져 있던 부분을 채운다.
- 목록 응답 형태를 {items, pageInfo} 로 고정하고 커서/오프셋 쿼리 DTO 제공
- @SkipTransform() 으로 스트림·204 등 래핑하면 안 되는 응답을 제외
- ApiStandardResponse/ApiErrorResponse 로 Swagger 문서를 실응답과 일치시킴
(컨트롤러는 raw 를 반환하지만 실제 응답은 래핑되어 문서가 어긋나 있었다)
- RequestIdMiddleware 로 모든 요청에 x-request-id 부여
- API 설계 규약(api-design.md) 신설 — REST 경로·쿼리·날짜/ID 표현·버전 관리
또한 .gitignore 의 data/ 패턴이 모든 depth 에 매칭되어
flutter/lib/features/user/data/ 의 소스가 커밋되지 않던 문제를 함께 고친다.
(user_provider.dart 가 import 하는 파일이 저장소에 없어 flutter analyze 가 깨져 있었다)
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
3.3 KiB
3.3 KiB
API 설계 규약
세 클라이언트가 공유하는 계약이므로, 아래 규약은 백엔드 단독으로 바꾸지 않는다.
경로 · 메서드
- 모든 라우트는 글로벌 prefix
/api아래에 놓인다 (main.ts). 클라이언트 baseURL 도/api를 포함한다. - 리소스는 복수형 명사, 소문자 kebab-case:
/users,/order-items - 동사를 경로에 넣지 않는다. 상태 변경이 필요하면 하위 리소스로 표현한다.
- ❌
POST /users/1/doDeactivate - ✅
POST /users/1/deactivation
- ❌
| 메서드 | 용도 | 성공 상태 |
|---|---|---|
| GET | 조회 (부수효과 없음) | 200 |
| POST | 생성 · 비멱등 작업 | 201 (생성) / 200 |
| PATCH | 부분 수정 | 200 |
| PUT | 전체 교체 | 200 |
| DELETE | 삭제 | 204 (@SkipTransform()) 또는 200 |
쿼리 파라미터
| 용도 | 파라미터 | 비고 |
|---|---|---|
| 커서 페이지네이션 | cursor, limit |
기본 20 / 최대 100 (response-format) |
| 오프셋 페이지네이션 | page, limit |
전체 페이지 수가 UI 에 필요할 때만 |
| 정렬 | sort=createdAt:desc |
필드:방향, 콤마로 다중 지정 |
| 검색 | q |
자유 텍스트 검색 |
| 필터 | 필드명 그대로 (status=active) |
화이트리스트 DTO 로만 수용 |
- 모든 쿼리는 DTO(
class-validator)로 검증한다.forbidNonWhitelisted때문에 미정의 파라미터는 400(VAL_001)이 된다.
데이터 표현
- 날짜/시각: ISO 8601 UTC 문자열 (
2026-09-16T13:22:16.000Z). 타임존 변환은 클라이언트 책임. - ID: 노출용 식별자는 문자열로 직렬화해도 되지만 타입을 도메인 내에서 일관되게 유지한다.
- 금액: 소수 오차를 피해 최소 단위 정수(원 단위)로 주고받는다.
- 불리언 필드:
is/has접두어 (isActive,hasNext). - 필드명: JSON 은 camelCase. DB 컬럼명이 snake_case 여도 응답에서 변환한다.
null과 필드 생략을 혼용하지 않는다 — "값 없음"은null로 통일한다.
버전 관리
- 호환성을 깨는 변경(필드 삭제, 타입 변경, 의미 변경)이 필요하면 경로 버전을 올린다:
/api/v2/users - 필드 추가는 호환 변경이므로 버전을 올리지 않는다. 클라이언트는 모르는 필드를 무시해야 한다.
- 제거 예정 필드는 먼저 문서에
deprecated로 표시하고, 클라이언트 전환 후 삭제한다.
문서화 (Swagger)
- 모든 컨트롤러에
@ApiTags(), 모든 엔드포인트에@ApiOperation(). - 성공 응답은
@ApiStandardResponse(), 실패 응답은@ApiErrorResponse('CODE')로 문서화한다 — 래퍼 구조와 에러 레지스트리가 자동 반영되어 문서와 구현이 어긋나지 않는다 (response-format). - 모든 DTO 필드에
@ApiProperty()+ 한국어description.
신규 엔드포인트 체크
- 경로가 복수형 리소스 + 동사 없음
- 입력은 DTO 검증, 출력은 응답 DTO 정의
- 목록이면 페이지네이션 적용
- 실패 경로마다 에러 코드 지정 (error-codes)
- Swagger 데코레이터 작성
- 세 클라이언트 중 사용하는 쪽의 타입/모델 갱신
응답 구조는 response-format, 에러는 error-codes, 구현 규칙은 nestjs 참조.