Controller·DTO·Zod schema·응답 매퍼·페이지네이션·Swagger·요청 헤더를 바꿀 때 읽는다. 공유 계약 패키지는 packages/api, 응답·오류 envelope는 오류 규칙, 출시 앱 호환 범위는 호환이다.
| 경계 | 소유 |
|---|---|
@aido/api/contracts/<resource>/v<n> |
요청·응답 Zod schema, inferred type |
@aido/api/common |
성공 envelope, 공용 pagination·날짜·id schema |
@aido/api/errors |
안정된 오류 code·HTTP 오류 계약·공개 details |
@aido/api/vocabulary |
Zod·HTTP·ORM 없는 순수 상수·튜플 |
| presentation | DTO 검증, DTO → Command 변환(문자열 → Temporal 포함), 응답 매핑·문구 |
| Application·Domain | 계약 타입을 모른다(lint로 막는다) |
- Controller는 guard·Swagger·DTO 검증, 원시값의 Command 변환, 결과의 HTTP 매핑만 한다. Repository·SDK·트랜잭션·업무 판단을 두지 않는다. UseCase를 직접 주입한다.
@Controller({ path, version: API_VERSION.V1 })처럼 v1도 명시한다. v2는 계약이 갈라질 때만http/v2/에 둔다. 버전은 폴더로만 나누고 클래스·Swagger 태그·상수 이름에 넣지 않으며, 버전 폴더끼리 import하지 않는다. 사례: MemoController.- 공용 데코레이터는
platform/http/decorators(@Timezone·@Locale·@IdempotencyKey·@RawResponse·@RedirectResponse·@ClientAbortSignal)와platform/http/request-client(@AppVersion·@CurrentRequestClient)에 있다. 인증(@CurrentUser·@Public·@Admin)은 identity sessions가identity-sessions.public.ts로 연다. - redirect는
@RedirectResponse()(Nest@Redirect(), 302)를 붙이고 handler가{ url }을 돌려준다.@Res()로 응답을 직접 보내지 않는다. - guard·interceptor·decorator가 읽는 요청·응답 타입은
platform/http/http-request.ts의HttpRequest·HttpResponse다. HTTP 어댑터(@nestjs/platform-node) API(trustProxy·maxParamLength, route별 본문 한도)는platform/http안에만 둔다(lint:deps의http-adapter-only-in-platform-http). - HTTP 어댑터는
NodeAdapter(node:http)이고 운영·테스트 앱이createHttpAdapter()하나로 만든다. 경로는 대소문자를 구분하고 등록 순서가 아니라 특이성(리터럴 >:param)으로 고른다. 응답에 ETag가 없어 304를 주지 않는다.__proto__·constructor.prototype키가 있는 JSON 본문과 퍼센트 인코딩이 깨진 경로는 400, 100KB(녹음 정리 256KB)를 넘는 본문은 413, 디코딩해 256자를 넘는 경로 파라미터는 414이고 모두 전역 필터의SYS_0002envelope다.
앱 헤더는 요청마다 한 번 RequestClient(platform/http/request-client)로 정규화한다. Controller에서 @Headers("x-…")를 쓰지 않는다. 새 헤더는 RequestClient에 정규화 규칙과 함께 더한다.
| 필요한 값 | 사용 |
|---|---|
| 앱 버전(SemVer, 없으면 구 앱) | @AppVersion(). 비교는 isSemanticVersionAtLeast |
| 플랫폼·빌드·OS·기기명·언어 | @CurrentRequestClient(), @Locale()(다국어) |
| 시간대 | @Timezone()(날짜 규칙) |
| Controller 밖(guard 등) | RequestClientReader.current() |
X-Request-Id는 UUID면 그대로, 아니면 새 UUID를 쓰고 응답 헤더로 돌려준다(관측).- 헤더 Swagger 문서는
platform/http/swagger/decorators/api-header.decorator.ts의@ApiAppVersionHeader()·@ApiIdempotencyKeyHeader()를 쓴다. query·path는@Query/@Param({ schema })가 문서를 만든다.@ApiQuery·@ApiParam을 겹쳐 쓰면 그쪽이 이겨 문서가 검증과 달라지므로 새로 쓰지 않는다(남은 곳은 출시 지문을 갱신하며 옮긴다). - throttle은 전역
UserAwareThrottlerGuard다. 인증한 요청은 사용자 id, 인증 전은 IP로 센다. 한도는 slicepresentation/http/<slice>.rate-limits.ts의defineRateLimits({ <행동>: { limitPerMinute 또는 limitPerHour, limitPerDay? } })한 곳이고 라우트는@RateLimit(<Slice>RateLimits.<행동>)하나를 붙인다. 출시된 endpoint의 새 한도는@ApiDocdescription 문장으로 적는다.
packages/api/src/contracts/<resource>/v<n>/의*.request.ts·*.response.ts·*.common.ts가 schema를 소유한다. 타입은z.infer로만 얻는다.- 서버 DTO는
http/v1/<noun>.dto.ts한 파일에 그 컨트롤러의X = schema.meta({ id: "XDto" })와 타입을 모은다(memo.dto.ts). Swagger component id는 바꾸지 않는다. 파일을 합칠 때 옛 파일을 같은 커밋에서 지운다(같은 id가 두 번 등록되면toJSONSchema가 실패한다). - Zod 4 문법: 조합은
.pick/.omit/.extend/.partial만(.merge금지). 외부 원문은z.looseObject, 내부 계약은z.object, 닫힌 내부 payload는z.strictObject. 오류 옵션은{ error }다. .describe()·.meta()는 공개 Swagger 계약이다. 새 필드는 단위·시점·nullable 의미를 적는다.- required/optional/nullable/default와 검증 메시지는 계약이다. 리팩터링 중 바꾸지 않는다. 기존 한국어 검증 문구도 유지한다(앱은
SYS_0002로 현지화).
- 응답 envelope(
{ success, data, timestamp },ResponseTransformInterceptor)와 오류 envelope는 그대로다. - 서버가 계산한 값을 싣는다. AI 응답과 한도 오류는
featureQuota를 준다. 앱이 읽지 않는 값은 새 응답에 넣지 않는다(출시 뒤에는 뺄 수 없다). 그런 값은 서버 로그에 남긴다. - 날짜는
YYYY-MM-DD, 순간은 ISO datetime(ms 3자리,toIsoString), 벽시계는HH:mm이다. 변환은 응답 매퍼 한 곳이다. - 변경 응답의
message는 출시 계약이라 유지하되 문구는 presentation 매퍼 상수(MEMO_RESPONSE_MESSAGES)에 둔다. 새 응답에는 넣지 않는다. - 운영 응답에 실을 details는
PUBLIC_ERROR_DETAILS에 코드별 Zod로 등록하고, 그 코드의 오류는 slice*.errors.ts생성 함수 하나가 같은 모양으로 만든다(verificationResendCooldown(remainingSeconds)). 앱이 details를 읽는 코드는 앱 계약 테스트(apps/mobile/src/shared/errors/error-details-contract.test.ts)가 등록을 확인한다. 등록이 빠지면 개발·테스트에서는 보이던 값이 운영에서만 사라진다.
배포 환경이 운영이 아니면(로컬 실행·테스트·개발서버·staging, appConfig의 responseContractCheck) configureApplication이 ResponseContractInterceptor를 전역으로 더한다. 운영에는 요청마다 parse하는 비용을 피하려고 등록하지 않는다(설정).
@ApiSuccessResponse·@ApiCreatedSuccessResponse가 Swagger에 등록한 바로 그 Zod schema로, 실제 상태 코드의 body를 JSON으로 바꾼 뒤(@RawResponse가 아니면 envelope 포함)safeParse한다. 응답 값은 바꾸지 않는다.- 다르거나 선언한 성공 상태와 다른 상태로 응답하면
http.response-contract.violated로그(handler·path·Zod issues)를 남기고 500(SYS_0001)으로 실패한다. 그래서 E2E가 선언과 다른 응답을 바로 잡는다. - Zod가 아닌 선언(class
type, OpenAPIschema객체)과@Res()로 직접 보낸 응답은 검사하지 않는다. 친구·카테고리 한도 응답의 class DTO는 Zod로 옮기면 제약 없는 nullable 숫자가nullable: true대신type: ["number", "null"]이 되어 released 지문이 달라지므로 그대로 둔다. - 실패는 서버 응답을 출시 계약에 맞추거나, 선언이 틀렸으면 선언을 고쳐서 없앤다. 출시 계약과 released fixture는 바꾸지 않는다.
- 새 목록은
cursorPageSchema(item, cursor)(@aido/api/common)가 만드는{ items, pagination: { nextCursor, hasNext, size } }만 쓴다. 페이지 크기 이름은size다. 할 일·친구 할 일·메모·주간 성취 목록이 이 helper를 쓴다. - 출시 계약을 helper로 옮길 때는 그 계약의 설명 문구를 세 번째 인자로 넘겨 생성된 JSON Schema를 바이트 단위로 같게 두고, OpenAPI 지문으로 확인한다.
- 다른 모양의 출시 계약(알림·친구·응원·찌르기·초대·댓글)은 그대로 두고, 서버 내부는
CursorPage로 통일한 뒤 매퍼가 옛 모양을 만든다. - 서버가 발급한 문자열 ID는
entityIdSchema로 검증한다(z.cuid()금지). 모양 규칙은@aido/api/vocabulary의ENTITY_ID_PATTERN하나이고 서버 도메인은isEntityId로 같은 규칙을 쓴다. - 문자열 커서는 서명한다. 댓글 커서는 HmacTodoCommentCursorCodecAdapter가
CURSOR_SIGNING_KEYSkey ring으로 서명한다(보안). 숫자 커서 계약은 숫자를 유지한다.
| 경계 | 보장 |
|---|---|
| HTTP 입력 | 공유 Zod + 전역 StandardSchemaValidationPipe. 인자 타입은 z.infer |
| HTTP 출력 | 반환 타입이 계약 DTO 타입. 운영 밖에서는 응답 계약 검사, E2E도 .parse |
| 외부 API | *.wire.ts Zod parse(외부 호출) |
| 큐·이벤트 payload | defineQueue·이벤트 schema(작업과 이벤트) |
| 환경변수 | defineConfig·config schema Zod(설정) |
| DB 행 | $inferSelect/$inferInsert + Temporal customType, 행 → 도메인은 매퍼 한 곳 |
| DI | abstract class 토큰 + provideUseCase |
| 분기 | 유니온은 ts-pattern .exhaustive() |
| 금지 | as(as const 제외)·any·!·@ts-*. 예외는 provideUseCase 내부 1곳(사유 주석) |
출시된 operation의 상태 코드·필수 입력·기존 필드는 바꾸지 않는다. released OpenAPI fixture(test/e2e/fixtures/released-*-openapi-contract.ts)와 OpenAPI 계약 테스트(test:contract)가 막는다. 필드·파라미터를 더해야 하면:
- 생략했을 때 동작이 지금과 정확히 같은 optional만 더한다.
- fixture에 이전 지문을
pre<변경>SchemasFingerprint·pre<변경>PathsFingerprint로 사유 주석과 함께 남기고 현재 지문을 갱신한다. - 출시 앱 요청 모양으로 보낸 E2E로 동작을 증명한다.
고정된 released fixture를 현재 schema로 재생성하지 않는다. 서버는 @aido/api의 dist 타입을 읽으므로 packages/api를 바꾸면 서버 타입 검사 전에 pnpm --filter @aido/api build를 돌린다. Swagger 설명은 지문에서 빠지므로 코드와 다른 설명(정렬 방향 등)은 바로 고친다.