API의 TypeScript 버전은 출시일에 solid하게 보였을 것입니다. 경로가 컴파일되었고, 프론트엔드가 공유 타입을 가져왔으며, 편집기가 모든 사람에게 깨끗한 녹색 느낌을 주었고, 보통은 "배포할 수 있는"이라는 뜻입니다.
__CAPGO_KEEP_0__의 TypeScript 버전 API in TypeScript 목차
__CAPGO_KEEP_0__의 TypeScript 버전이 출시된 후에 typed API가 실패하는 이유와 이를 방지하는 방법
- __CAPGO_KEEP_0__ 프로젝트를 올바르게 구축하는 방법
- API
- DTO를 설계하고 입력을 검증하는 경계에서
- API 클라이언트를 완전히 타입화된 클라이언트를 생성하고 소비하세요
- 실제로 도움이 되는 오류 처리, 테스트 및 관찰성.
- 생산에 신뢰와 통제와 함께 배송합니다.
배포 후 유형화된 API가 실패하는 이유와 이를 방지하는 방법
타입이 지정된 API은 일반 릴리스 중에 종종 깨집니다. 한 팀은 응답 필드를 이름을 바꾸고 다른 팀은 부분 마이그레이션을 위한 nullable branch를 추가합니다. 이전 페이로드를 계속 보내는 오래된 클라이언트가 있습니다. 이는 모바일 업데이트가 웹 업데이트보다 뒤쳐져 있기 때문입니다. TypeScript는 로컬 타입을 업데이트한 모든 리포지토리에서 컴파일이 가능합니다. 프로덕션에서 계약은 이미 거짓입니다.
그런 실패는 계약 드리프트라고 불립니다.
API을 사용하는 데 TypeScript가 더 즐겁게 만들었지만 약한 계약을 더 쉽게 신뢰하게 만들었습니다. 공유 인터페이스, 경로 제네릭, 타입화된 wrapper는 개발 중에 도움이 됩니다. 그러나 두 번째 또는 열 번째 릴리스 후에 JSON이 네트워크를 건너면서 여전히 그 타입과 일치하는지 증명하지는 않습니다. fetch 프로덕션에서 유지되는 규칙은 간단합니다.
제작 환경에서 유지되는 규칙은 간단합니다.
해결책은 더 똑똑한 타입 연산에 대한 재미가 아니라 진실이 어디에 존재하는지에 대한 것입니다:
유효성 검사를 경계에서 수행하세요.
- 요청 본체, 매개변수, 헤더,甚至 하위 서비스 응답을 파싱하세요. 나머지 __CAPGO_KEEP_0__이 그들을 만지기 전에. 요청 본문, 매개 변수, 헤더 및 하류 서비스 응답을 모두 파싱하여 나머지 code이 접촉하기 전에 처리합니다.
- 운송 형태와 비즈니스 객체를 분리하여 __CAPGO_KEEP_0__의 churn이 코드베이스 전체로 퍼지지 않도록 하세요. API은 타입이 지정된 API입니다.
- __CAPGO_KEEP_0__ OpenAPI, JSON Schema, 또는 schema-first 프레임워크는 클라이언트와 서버가 공유할 수 있는 진실의 근원이다.
- 파괴적인 변경을 공개 이벤트로 다루어라. 필드의 형태가 변경되면 의도적으로 버전을 관리하고 변경 사항을 다른 외부 계약 변경과 마찬가지로 통보하라.
DTO 매핑은 팀이 가장 자주 생략하는 부분이다. 처음에는 중복적 느낌이 들 수 있지만 몇 번의 릴리스 후에 매핑을 통해 서비스와 프론트엔드 화면에 걸쳐있는 모든 레거시 필드 별칭을 전파하는 것을 피할 수 있다. 경계에서 작은 변환 단계는 나중에 광범위한 리팩토링보다 저렴하다. string | null 타입화된 API도 실패한다. 오류 계약은 일반적으로 생각하지 않는다. 성공 응답은 주의를 받지만 실패 응답은 예외가 발생한 그 날에 직렬화된 형태로 변한다. 클라이언트는 설계되지 않은 형태로 재시도 로직, 사용자 메시징, 모니터링을 구축한다. 결과는 동일한 문제지만 형태가 다르다. drift.
버전 관리도 동일한 discipline를 필요로 한다. 팀은 한 번의 극적인 리팩토링으로 클라이언트를 깨지지 않는다. 그들은 호환성으로 이어지는 일련의 합리적인 지역 변경으로 클라이언트를 깨진다. 명확한 __CAPGO_KEEP_0__ 버전 관리 전략은 소비자에게 도달하기 전에 변경 사항을 표시한다.
목표는 TypeScript를 어디서나 사용하는 것이 아니다. 목표는 런칭 후에, 여러 배포, 여러 클라이언트, 실제 프로덕션 데이터가 일단의 정돈된 타입에 부딪히기 시작할 때 계약이 진실을 유지하는 것이다. 타입스크립트 API 프로젝트를 올바르게 구축하는 방법 __CAPGO_KEEP_0__
OpenAPI, JSON Schema, 또는 schema-first 프레임워크는 클라이언트와 서버가 공유할 수 있는 진실의 근원이다.
타입스크립트 API 프로젝트를 올바르게 구성하는 방법
타입스크립트에서 일반적으로 API은 첫날에는 깨끗하게 보입니다. 여섯 개월 후, 한 경로는 비검사 입력을 수용하고 다른 경로는 raw 데이터를 읽습니다. process.env프로젝트 형태를 선택하여 계약을 우회하기 어려운 형태로 만듭니다.
__CAPGO_KEEP_0__을 타이핑하는 개발자가 laptop 화면에 TypeScript 오류를 보여주는 IDE 터미널을 보는 장면입니다.
팀 형태에 맞는 프레임워크를 선택하십시오
TypeScript에서 API를 위한 첫 번째 프레임워크 결정은 구문보다 계약 규칙이 어디에 살아갈 것인지에 더關係있다.
- Express Fastify
- Fastify Nest
- Nest Express
나는 팀이 사용할 것보다 더 많은 프레임워크를 구매하는 것을 피하는 경향이 있습니다. 작은 서비스에 Fastify, 유효성 검사 라이브러리 및 생성된 계약 타입이 있는 경우, 리팩터링을 더 잘 견딜 수 있습니다. 반면에 heavier stack에 불일치한 convention이 layering된 경우, 더 많은 문제가 발생합니다.
보호된 경계를 보호하는 폴더 레이아웃을 사용하십시오.
폴더 이름이 중요하지 않습니다. import 압력이 더 중요합니다. 만약 루트가 데이터베이스 모델에 접근할 수 있다면, 또는 서비스가 클라이언트에게 ORM 엔티티를 직접 반환할 수 있다면, scaffold는 이미 drift를 초래하는 것입니다.
생산 환경에서 견딜 수 있는 레이아웃은 일반적으로 다음을 분리합니다:
src/routesHTTP wiring만src/schemas요청 및 응답 스키마src/dtotransport 유형과 매핑을 위한 codesrc/services사용 사례 및 오케스트레이션src/domain어떤 단일 엔드포인트도 살아남아야 하는 비즈니스 모델src/clients다운스트림 통합src/errors공유된 오류 타입 및 좁히는 도우미src/config시작 시간에 구성 파싱
그것 src/dto layer는 단순한 노동이 아닙니다. 그것은 외부 변경 사항을 흡수하는 데 API에게 공간을 제공하고 도메인 논리나 관련되지 않은 엔드포인트를 통해 그들을 유출하지 않도록합니다.
구성은 동일한 처리를 deserve합니다. 시작 시 환경 변수를 한 번만 파싱하고, 유효하지 않은 값에 대해 빠르게 실패하고, 앱의 나머지 부분에 유형화된 구성 객체를 내보냅니다. 팀이 핸들러 내에서 계속 읽는 경우 process.env branchy 런타임 동작이 TypeScript가 도와주지 못하는 패턴으로 끝납니다. 이 환경 구성에 대한 안내서 환경 구성 은 표준화된 패턴이 필요할 때 좋은 참고 자료입니다.
컴파일러를 강화하기 전에 기능을 추가하세요
생산 API에서 안전하지 않은 code을 작성하는 것이 불편해야 합니다.
유용한 기본값은 다음과 같습니다:
strict활성화useUnknownInCatchVariables활성화noUncheckedIndexedAccess활성화되면 팀이 추가한 제도에 대한 추가 노력을 감당할 수 있습니다.- No 경로 별칭이 Node, 테스트, 번들링 및 도구가 모두 동일한 방식으로 해결하는 경우에만 사용됩니다.
- 분리
build,typecheck, CI에서 lint 스크립트를 분리합니다.
약한 tsconfig 잠재하는 오류가 누적되지 않도록 방지합니다. 엄격한 한은 오류가 프로덕션 동작으로 변하지 전에 명확한 작업으로 변환합니다.
lint 규칙도 도움이 됩니다. 특히, any, 비동기 프롬프트, 그리고 공개 계약 모듈에서 의도치 않은 내보내기와 같은 규칙입니다. 런타임 검증을 대체하지는 않지만, 계약 오류가 숨겨질 수 있는 위치를 줄여줍니다.
또한, scaffold 선택이 초기에 중요합니다. OpenAPI 스펙의 원천을 결정하고, 그 결정이 경로层와 가깝게 유지하는 것이 중요합니다. 일부 팀은 스펙을 code-first 스키마에서 생성합니다. 다른 팀은 스펙에서 서버 스텁과 타입을 생성합니다. 두 가지 방법 모두 작동할 수 있습니다. 실패하는 것은 스펙을 첫 번째 릴리스 후에 아무도 확인하지 않는 사이드 아티팩트로 다루는 것입니다.
초기 scaffold 이후, 타입된 계약이 평범한 요청-응답 서비스 외에도 어떻게 행동하는지 비교하는 것이 도움이 됩니다. Streamkap Flink TypeScript 가이드 은 스트림이나 이벤트가 많은 시스템을 작업하는 팀에게 유용합니다. 계약 오류가 HTTP 핸들러에서만 나타나는 것이 아니라, 더 긴 pipe선에서 나타날 수 있기 때문입니다.
DTO를 설계하고 입력을 경계에서 검증하는 방법
A typed API은 일반적으로 첫날에는 정상적으로 보입니다. 여섯 개월 후, 버그는 경계에서 나타납니다. 모바일 클라이언트는 여전히 이전 필드를 전송합니다. 파트너는 프론트엔드가 항상 존재하는 것으로 가정한 속성을 생략합니다. 리팩토링은 내부 ORM 열을 공개 응답에 노출합니다. TypeScript는 코드베이스 내에서 작업을 수행했습니다. 계약은 여전히 변했습니다.
DTO 설계는 중요합니다. 그것은 요청 본체가 정돈된 것처럼 보이게 하는 것이 아닙니다. 그것은 첫 번째 릴리스 후에 공개 유형을 진실하게 유지하는 것입니다.
공개 계약과 내부 모델은 동일하지 않아야 합니다.
A DTO API는 TypeScript에서 설명합니다. DTO 설계와 유효성 검사 프로세스를 보여주는 다이어그램입니다. 안전한 시스템 경계를 유지하고 __CAPGO_KEEP_0__ 계약을 유지하기 위해. 만약에 경로가 이 것을 받았다면:
__CAPGO_KEEP_0__
type CreateOrderRequestDto = {
customerId: string
items: Array<{ sku: string; quantity: number }>
note?: string | null
}__CAPGO_KEEP_0__ OrderDraft __CAPGO_KEEP_0__
일반적으로 다음 단계가 필요합니다:
- 입력 데이터를 분석합니다.
- 데이터 형식과 필드 수준의 제약 조건을 검증합니다.
- DTO를 도메인 객체로 매핑합니다.
- 도메인 객체에 대한 비즈니스 로직을 실행합니다.
- 결과를 응답 DTO로 매핑합니다.
- 응답을 전송하기 전에 응답을 검증합니다.
6단계는 자주 생략됩니다. 또한 private 필드, nullable 값이 안정적인 응답에 유출된 경우, refactoring 중에 발생한 스키마 변경을 잡아내는 단계입니다.
비즈니스 로직이 데이터에 접근하기 전에 데이터를 검증합니다.
컴파일 타임 타입은 네트워크에서 JSON을 검증하지 않습니다. 또한 다른 서비스가 여전히 컴파일 타임 타입의 가정에 부합하는 형태를 반환할 경우에도 보호하지 않습니다. unknown runtime에서 여러분의 가정들을 깨뜨립니다.
API에서 TypeScript에서 작업할 때 Zod는 일반적으로 선택되는 라이브러리입니다. code에서 나머지 작업을 위해 타입을 추론합니다. Valibot, io-ts, 같은 라이브러리도 작동할 수 있습니다.
A refactoring에 견디는 패턴은 다음과 같습니다.
- 입력 스키마 잘못된 요청 데이터를 거부합니다.
- 의존 스키마 세계적인 API 및 내부 서비스에서 응답을 검증합니다.
- 출력 스키마 API가 곧 배포할 응답을 확인합니다.
이 중간层은 많은 타입화된 API가 런칭 후 실패하는 곳입니다. 팀은 요청을 검증하고 하류 응답에 대한 검증을 생략하고, 그 후에 왜 벤더 필드 이름 변경이 프로덕션 사고가 된 것인지를 궁금해합니다.
다음은 실용적인 규칙입니다. Raw JSON은 경로层에서 멈춥니다.
code 매핑은 낭비가 아닙니다. 이곳에서 이탈이 드러납니다.
팀은 DTO 매핑에 저항하는 경향이 있습니다. 왜냐하면 그것이 반복적이 느껴지기 때문입니다. 하지만 나는 프로덕션에서 반대의 경험이 있습니다. 얇은 매핑层은 계약 변경이 명확하고 검토할 수 있고 지역화가 된 곳입니다.
예를 들어:
- transport를 허용합니다.
note?: string | null - 도메인 모델이 저장할 수 있습니다.
note: string및""기본값으로 - 응답 DTO가 생략할 수 있습니다.
note완전히 생략할 수 있습니다. 그것이 빈 경우
그것은 세 가지 다른 진실을 세 가지 다른 청중에게 가지고 있습니다. 그것들을 하나의 공유 인터페이스로 다루면 차이점이 숨겨지지만 클라이언트가 깨트리면.
웹후크는 이것을 thậm chí 더 분명하게 만듭니다. 소비자는 몇 년 동안 페이로드 형태를 유지할 수 있습니다. 만약 팀이 그 문제를 해결하고 있다면, 이 웹후크 페이로드 디자인 예제 는 유용한 동반자입니다.
공유 타입은 진실의 원천이 명확할 때만 도움이 됩니다.
백엔드 인터페이스를 프론트엔드에 복사하는 것은 시간 지연을 가진 드리프트입니다. 공유 패키지는 의도적으로 공개된 타입만 도움이 됩니다.
대규모 코드베이스에서 더 잘 유지되는 설정은 다음과 같습니다:
- public request 및 response 스키마를 저장소 모델에서 분리하여 정의합니다.
- public 스키마에서 OpenAPI를 생성하거나 OpenAPI에서 서버 타입을 생성합니다.
- 생성된 계약 타입을 핸들러 및 클라이언트와 가까이 유지합니다.
- 도메인 타입 및 ORM 모델은 내부에 유지합니다.
- 호환성에 중요할 때 public DTO를 의도적으로 버전화합니다.
그 분리는 Azure __CAPGO_KEEP_0__ 팀의 TypeScript 디자인 가이드라인에서도 일치합니다. Azure SDK 팀의 TypeScript 설계 지침유지 관리 가능한 경계는 의도적으로 단조롭습니다.
좋은 버전은 더 똑똑하지 않습니다.
앞서, 프론트엔드는
트러스트했습니다. fetch().json() 그것은 진실로 여겨진다면, 백엔드가 ORM 객체를 직접 반환하고, 모든 층을 대표하는 하나의 공유 인터페이스를 시도한다. 그 후 각 경계는 데이터를 파싱하고, DTO는 좁고, 도메인 모델은 내부에 남아, 생성된 타입이 공개 계약을 커버하고, 매핑 code가 변경을 명확하게 한다.
이것은 의식의식의 절차를 추가한다. 또한 호출자가 그것을 찾을 때까지 리뷰를 한 곳을 제공한다.
완전히 타입화된 API 클라이언트를 생성하고 소비하는 방법
타입화된 클라이언트는 출시일에 완성된 것처럼 보인다. 세 달 후, 한 엔드포인트는 nullable 필드를 반환하기 시작하고, 다른 엔드포인트는 커서 페이징을 추가하고, 모바일 앱은 이전 버전의 계약을 고정한다. TypeScript 타입은 여전히 컴파일된다. 호출자는 여전히 깨진다.
타입화된 클라이언트의 전략을 선택하는 것
타입스크립트에서 클라이언트 선택 전략
클라이언트의 형태는 API의 실제 복잡성에 맞춰야 하며 팀의 선호도와는 관계가 없습니다.
| 최선의 선택 | 거래 | 트레이드 오프 |
|---|---|---|
| 작은 앱, 비정상적인 인증 흐름, 빠른 반복 | __CAPGO_KEEP_0__의 실제 복잡성을 반영해야 하며, 팀의 선호도와는 다르다. | 빠른 시작. 시간이 지남에 따라 호출 사이트를 통해 분할하기 쉬움 |
| OpenAPI code 생성 | 안정된 스키마와 함께 단순한 REST API | 강한 기본선. 사용자 정의 인증, 스트리밍 또는 비정상적인 페이징을 위해 도움을 필요로 함 |
| SDK-style 타입 클라이언트 | 멀티 팀 플랫폼, 공개 API, 장기적인 통합 | 가장 높은 유지 보수 비용. API이 제품인 경우 최상의 사용자 경험 |
작은 표면에 대한 손수 만든 클라이언트가 작동합니다
A custom API fetch wrapper is a reasonable choice when the API is internal, the surface area is small, or transport behavior matters more than schema generation. I still use this approach for admin tools and early-stage services.
wrapper는 __CAPGO_KEEP_0__이 내부일 때, 표면 영역이 작거나 수송 동작이 스키마 생성보다 더 중요할 때 합리적인 선택입니다. 내부 도구 및 초기 서비스에 이 접근 방식을 여전히 사용합니다. any __CAPGO_KEEP_0__가 제품인 경우 최상의 사용자 경험을 제공합니다.
이 조건이 참일 때 사용하는 손으로 만든 클라이언트를 사용하십시오:
- API이 작고 내부적일 때
- code이 자주 변경되기 때문에 다시 생성하는 것이 잡음이 될 때
- 커스텀 전송 동작이 작업의 대부분을 차지할 때
- 클라이언트에서 런타임 파싱만 아니라 TypeScript 어노테이션만으로는 충분하지 않을 때
그 마지막 점은 중요합니다. response.json() 런타임에서 알려지지 않은 데이터를 반환하기 때문에, 함수 시그니처가 그렇다고 말하더라도.
OpenAPI 생성은 실제적인 기본값입니다.
안정적인 REST API의 경우, 생성된 타입이 유지보수 비용 대비 안전성 비율이 가장 좋습니다. 중복된 타입 작성이 줄어들고, 계약 변경 사항이 Pull Request에서 보이게 됩니다.
리팩터링을 견딜 수 있는 패턴은 간단합니다. 공개 계약에서 생성하고, 생성된层을 얇게 유지하고, 소비자들이 더 좋은 사용성을 원할 때 작은 wrapper를 추가하십시오. OpenAPI TypeScript 생성 워크플로우 이 모델에 잘 맞습니다.
API TypeScript에서 유용한 분리는 다음과 같습니다.
- 생성된 code은 요청과 응답 형태를 소유합니다.
- thin한 SDK wrapper는 인증 주입, 재시도, 페이지네이션 도우미를 소유합니다.
- 런타임 검증은 서버 경계와 신뢰할 수 없는 입력이 시스템에 다시 들어올 때 발생합니다.
- DTO mapping은 내부 모델 변경이 클라이언트 계약에 유출되지 않도록 명시적으로 유지됩니다.
그 하이브리드 접근 방식은 생성된 code이 재생성, 검토 및 교체가 쉬워 좋은 것입니다. 재생성, 검토 및 교체가 쉬운 code은 좋은 것입니다.
응용 프로그램 code이 생성된 클라이언트와 접촉하기 전에 wrap하세요.
생성된 함수는 일반적으로 코드베이스 전체에서 광범위하게 사용하기에 너무 raw합니다. 그들은 전송 세부 정보를 노출하여 모든 호출자가 다시 학습해야 합니다.
thin한 wrapper는 정책을 일관되게 유지하는 한 곳을 제공합니다:
- 기본 헤더와 요청 ID를 첨부하세요.
- 오류 형태를 정규화하세요.
- 페이지네이션을 반복자 또는 도우미 메서드로 노출하세요.
- API 요청에 대한 인증을 위한 지원
- 생성된 요청 및 응답 타입을 보존하는 대신 수동으로 다시 작성하지 않습니다
예를 들어, 애플리케이션 code는 client.orders.listAll() 또는 client.orders.list({ cursor })예를 들어, __CAPGO_KEEP_0__-스타일의 클라이언트는 __CAPGO_KEEP_1__가 제품일 때 의미가 있습니다
SDK-style 클라이언트는 제품이 API일 때 의미가 있습니다.
좋은 클라이언트 사용성은 다음과 같은 형태를 보입니다:
타입이 지정된 페이지 또는 비동기 이터레이터를 반환합니다
client.orders.list()스트리밍을 처리하는 동안 낮은 수준의 fetch 설정을 모든 호출에 유출하지 않습니다client.files.stream()인증을 글로벌로 설정하고 요청 당 오버라이드할 수 있습니다- 호출자는 안정된 타입이 지정된 오류 객체를 대신하여 ad hoc로 thrown된 페이로드를 받습니다
- API 요청에 대한 인증을 위한 지원을 제공합니다.
그것은 유지 보수 비용을 추가한다. 또한 각 소비 팀이 동일한 경계 규칙을 약간 다르게 다시 구축하는 것을 방지하여, 이는 계약 이탈이 퍼지는 방식이다.
완전히 타입화된 클라이언트는 마감선이 아니다. 마감선은 API이 발전할 때까지 실제로 타입이 일치하는 클라이언트가 되는데, 이는 생성이 공개 계약에서 시작되고, 런타임 검증이 경계를 보호하며, DTO 매핑이 내부 변경이 외부로 유출되지 않도록 하는 것이다.
실제로 도움이 되는 오류 처리, 테스트 및 관찰성
대부분의 TypeScript API 예제는 너무 조용하다. 요청이 성공하고, JSON이 인터페이스와 일치하며, 실패가 throw new Error("something went wrong")생산 환경에서는 그렇게 친절하게 행동하지 않는다.
첫 번째 해결책은 기계적이다. TypeScript에서 획득된 값은 unknown로 처리되어야 하며, 읽기 전에 message, stack로 좁혀지거나, 응답 속성으로 좁혀져야 한다. 전문가 지침도 사용자 정의 오류 클래스를 추천하며, 원래 실패를 cause로 보존하고, 경계에서 유효성 검사하고, 오류가 아닌 throw를 정규화하고, 요청 컨텍스트를 첨부하여 관찰성을 제공하는 TypeScript 오류 처리 지침).
오류를 만져야 할 때는 오류를 좁혀야 한다.
안전하지 않은 catch 블록은 여전히 흔하다:
try {
await client.orders.create(input)
} catch (error) {
logger.error(error.message)
}그것은 너무 많은 것을 가정한다. error 그것이 아마도 Error 아무것도 아니다.
안전한 패턴:
try {
await client.orders.create(input)
} catch (error: unknown) {
if (error instanceof Error) {
logger.error({ message: error.message, stack: error.stack })
throw new OrderSyncError("Order sync failed", { cause: error })
}
logger.error({ error })
throw new OrderSyncError("Order sync failed", { cause: new Error("Non-Error thrown") })
}이것은 약간 더 무거워 보인다. 실패가 세 번째 SDK, JSON 파싱 실패, 또는 예상치 못한 throw에서 오는 경우, 이것은 훨씬 더 잘 살아남는다.
오류가 일시적인 경우에만 다시 시도하라.
오류 분류의 두 번째 큰 개선은 TypeScript SDK 및 API 연산에 대한 지침이 깨끗한 규칙에 수렴한다: 네트워크 오류나 HTTP 429 및 503 응답과 같은 일시적인 오류를 다시 시도하고, 초기에 유효성을 검사하고 오류 컨텍스트를 보존하고, 비즈니스 규칙 오류에 대한 다시 시도는 피하는 것이 좋다.이것은 또한 Promise.all 빠른 실패를 위한 병렬 작업에 대해 Promise.allSettled when partial success is acceptable ("SDK 오류 처리 패턴).
세 개의 바구니를 좋아합니다.
- Validation 오류 요청이 잘못된 것이므로 프로세스에서 나기 전에 오류가 있었다.
- 임시 오류 재시도 시 백오프 후 성공할 수 있습니다.
- Permanent errors 사업 규칙, 권한, 또는 누락된 리소스를 반영하고 직접 표면화해야 합니다.
그 분류는 일반적인 "실패 시 재시도" 도우미보다 더 나은 code를 제공합니다.
Field rule: transport 불안정성에 속하는 retry는 domain 불일치와는 관련이 없습니다.
실패를 설명하는 것이 관찰성이다, 그저 기록하는 것은 아니다
로그가 컨텍스트가 없으면 관찰성은 아니다. TypeScript에서 API을 위해, 모든 요청이 경계를 넘을 때 correlation ID, route 이름, 요청 메타데이터, 정규화된 오류 형태를 첨부하라.
유용한 기준점:
- 상관 ID 인바운드 요청을 다운스트림 호출과 연결한다
- 구조화된 로그 field를 저장하라, prose 블록이 아닌
- 경계 로그 사업 예외와 파싱 실패를 분리한다
- 경고 오류 클래스와 경로를 기준으로, 단순히 상태 code 볼륨을 기준으로하지 마라
모바일 또는 클라이언트 애플리케이션들이 이러한 API를 소비한다면, 관찰성 업데이트는 중요하다. 릴리스层에서 하나의 실용적인 옵션은 Capgo, Capacitor와 Electron 환경에서 실시간 업데이트 shipping 및 추적을 위한 타입화된 API를 제공합니다. 클라이언트 측 계약 수정이 제어된 롤아웃과 버전별 가시성을 위해 필요한 경우 앱 스토어의 또 다른 무책임한 기다림 대신 유용합니다. 이 안내서 앱 관찰성 구현만 테스트하는 대신 계약을 테스트하세요
단위 테스트만으로는 드리프트를 잡을 수 없습니다. 드리프트가 발생하는 곳에 테스트를 추가하세요
경계 검증 테스트:
- 잘못된 입력을 스키마에 넣고 실패 형태를 확인하세요. 계약 테스트:
- 실제 HTTP 응답이 공개된 계약과 일치하는지 확인하세요. 타입화된 오류 확인:
- 임시적이고 영구적인 실패가 올바르게 정규화되는지 확인하세요. Boundary validation tests: Feed malformed input into schemas and assert failure shape.
- Client 통합 테스트: 생성된 또는 wrapping된 클라이언트가 실제 응답을 파싱하는 것을 보장하십시오.
code 경로가 강력한 테스트套件으로 증명되는 것만이 아니라, 계약이 여전히 진실을 말하는지 증명하는 것입니다.
신뢰와 통제와 함께 프로덕션에 배송하기
품질의 릴리즈는 반복 가능한 루프에서 나옵니다. 영웅주의가 아닙니다.
TypeScript pipeline에서 신뢰할 수 있는 API 일반적으로 몇 가지 필수 요소를 포함합니다: CI에서 스키마 검사, 생성된 항목에 대한 타입 검사, 계약 차이점 검토, 그리고 클라이언트 인구가 준비되지 않은 경우 배포 경로를 늦추거나 롤백할 수 있습니다.
릴리즈 루프가 지탱하는 것
프로덕션 체크리스트를 짧게 유지하여 팀이 이를 따르도록 하십시오:
- 계약 이탈에 CI를 실패하십시오: OpenAPI가 변경되면, 생성된 타입과 클라이언트는 동일한 변경에서 업데이트되어야 합니다.
- 공개된 DTO 패키지는 릴리즈 규칙을 따르도록 하십시오: 공개된 DTO 패키지는 릴리즈 규칙을 따르도록 하십시오:
- 채널 또는 계층에 따라 배포: 한 번에 모든 소비자에게 깨진 통합 변경 사항을 노출하지 마세요.
- 롤백이 간단해야 합니다: 계약, 클라이언트 또는 웹 번들을 되돌리려면 운영적으로 지루하지 않게 해야 합니다.
이 팀은 인프라 및 배포 워크플로우를 동시에 이동하는 경우 이 안내서를 참조하세요. 정확성보다 제어가 중요합니다. API는 플랫폼 전환 시 API의 신뢰성을 보장하는 데 도움이 되는 계획 참고 자료입니다. API의 신뢰성은 단순히 code의 변경으로 인해만 저하되는 것이 아닙니다.
정확성보다 제어의 중요성
채널 기반 배포, 롤백 보호, 버전별 관찰 가능성 등이 계약 고치기를 제어할 수 있도록 하는 것이 중요합니다.
If your stack includes Capacitor or Electron, live update tooling can reduce the lag between fixing a contract bug and getting the fix into users’ hands. The important part isn’t “faster updates” in the abstract. It’s having 한 번에 모든 소비자에게 깨진 통합 변경 사항을 노출하지 마세요. contract 수정은 제어됩니다.
타입스크립트 API는 스키마, 런타임 검증, 클라이언트 생성 및 릴리즈 작업이 모두 상호 보완할 때 건강합니다. 하나의 층을 놓치면 다른 층이 나쁜 대가리를 보게 됩니다.
Capgo은 팀이 Capacitor 및 Electron 앱을 위한 타입화된 방법으로 웹 번들 수정, 롤아웃 채널 제어 및 버전별로 모니터링 및 실패를 관리할 수 있도록 해줍니다. API 계약 수정이 스토어 리뷰를 기다리지 않고 클라이언트에 신속하게 전달되어야 하는 경우에는 visit Capgo.
