API
팀에 거짓말을 시작하는 __CAPGO_KEEP_0__ pipeline을 일반적으로 발견할 수 있습니다. 스키마가 변경되면, 생성된 타입이 불평하지 않고 업데이트되고, PR이 초록색으로 가고, somebody는 frontend에서 오래된 응답 형태를 계속 읽고 있지만 wrapper가 오류를 숨겼습니다. 그게 OpenAPI TypeScript 문제, 그것이 생성기 whether가 인터페이스를 내뱉을 수 있는지 여부가 아니라. 어떤 계약을 원하는지, 스키마, 전송, 검증 사이에 어떤 부분이 빌드 타임에 빠지지 않고 런타임에 유출되는지, 그리고 어떤 부분이 빠르게 실패해야 하는지 더 어려운 질문입니다. 한 번 프레임을 OpenAPI TypeScript
pipeline 선택으로 프레임을 하면, 트레이드 오프가 훨씬 rõ해지고, 도구가 전체 해결책으로 속이는 것을 멈추게 됩니다.
- 왜 생성된 타입은 안전한 API과 다르다.
- 실패가 숨겨진 곳
- 실제로 중요한 플래그
- Fetch 또는 Axios를 둘러싼 얇은 타입 클라이언트를 연결하는 방법
- zod, ajv, 또는 io-ts를 사용하여 런타임 검증을 추가하는 방법
- 생성, 검증 및 계약 테스트를 CI에 넣는 방법
- 유지 관리 가능한 PIPELINES, 성능 및 최종 체크리스트
제네레이트된 타입은 안전한 API과 동일하지 않습니다.
팀원 중 한 명이 옵션 응답 필드를 추가하는 PR을 병합합니다. 생성된 파일은 깨끗하게 업데이트되고 diff는 흥미롭지 않으며 모든 팀원은 다음으로 넘어갑니다. 그런 다음 프론트 엔드에서는 "영구적으로" cast된 "임시" wrapper를 통해 더 오래된 형태를 계속 읽고 있습니다. as any생성된 타입에 대한 함정입니다.
생성된 타입에 대한 함정입니다. TypeScript는 생성된 타입을 소비하는 code만 보호할 수 있습니다., 그리고 전송層이 계약을 다시 지우지 않는 한. discussion around understanding API connections __CAPGO_KEEP_0__ 연결에 대한 이해를 위한 토론은
__CAPGO_KEEP_0__ 연결에 대한 이해를 위한 토론은
실패하는 부분을 숨기고 있습니다. 가장 일반적인 브레이크 포인트는 재미가 없으며, 독특하지 않습니다. 스키마 드리프트는 OpenAPI 스펙과 구현된 서비스가 일치하지 않아 발생하는 현상입니다. 부분적 커버지는 스펙이 행복한 경로만 모델링하는 반면, 앱은 문서화되지 않은 에지 케이스를 의존하는 경우에 발생합니다. 수동으로 작성된 wrapper는 일반적으로 타입이 약화되는 경우가 많으며, 특히 alguien이 "빠르게 움직이고" 싶어 "move fast"를 사용할 때 발생합니다. any 또는 느슨한 응답 cast.
실용적인 규칙: Wrapper가 거짓말 할 수 있다면, 생성기가 당신을 구할 수 없다.
There’s also a runtime gap. TypeScript types disappear after compilation, so they can’t reject malformed JSON coming over the wire. The network does not care what your editor inferred, and that’s why a generated client is only one layer in a safer API pipeline.
보다 광범위한 운영 문제는 보안 및 계약 규율이며, 개발자 편의성만을 고려하는 것이 아닙니다. API 계약이 더 큰 앱 라이프 사이클에 어떻게 통합되는지 구조화된 시각을 원한다면, 앱 스토어 준수에 대한 API 보안 표준에 대한 내부 가이드 애플리케이션 스토어 준수성을 위한 API 보안 표준 __CAPGO_KEEP_0__
__CAPGO_KEEP_0__ typescript OpenAPI 는 다음과 같이 생각하는 것이 성숙한 방식입니다. strict schema-to-types bridge를 제공하여 좋지만, 요청을 검증하지 않으며, 런타임 페이로드 형태를 강제하지도 않고, 느슨한 wrapper가 모든 것을 무너뜨리도록 하지도 않습니다. 생성기는 쉬운 20%입니다. 나머지 부분은 pipeline 설계이며, 팀이 신뢰를 얻거나 거짓된 자신감을 쌓는 것을 선택합니다.
OpenAPI Spec에서 TypeScript 타입을 생성하는 방법
실제 저장소 churn을 견딜 수 있는 가장 가벼운 유용한 설정은 일반적으로 살아남습니다. OpenAPI 스펙을 동일한 저장소에 유지하고, 커밋된 타입 파일을 생성하고 CI에서 드리프트를 표시하는 대신, someone이 refresh 단계를 기억하도록 의존하지 말고, npx openapi-typescript ./openapi.yaml -o ./src/types/api.d.ts 리뷰어는 일반 소스 코드 변경과 같이 출력 파일을 검토할 수 있는 정해진 출력 파일을 제공합니다.
실제로 중요하는 flag
The -o 생성된 아티팩트가 명확해지도록 하기 위해 출력 플래그는 중요합니다. --immutable 생성된 타입이 readonly 의 의도도 유지되도록 하려면 readonly intent 를 유지하는 것이 유용합니다. --alphabetize 스키마 순서 변경이 의미 없는 경우 diff가 안정적입니다. --enum generated surface에서 팀이 열거형을 선호하는 대신联合을 사용하는 것이 중요합니다.
프로젝트의 자체 문서는 범위에 대해 명확하게 설명하고 있습니다. 그것은 typescript 생성기, client runtime 또는 request layer가 아닌 tool입니다. 그 제한이 lightweight, type-first 설정을 원할 때 도움이 됩니다. 오픈 소스 유지 보수의 필요성. GitHub 저장소와 CLI 문서.
__CAPGO_KEEP_0__ package.json __CAPGO_KEEP_1__ git diff Wire
이 명령어는 다른 빌드 스크립트와 함께 존재하고, 스펙이 변경될 때마다 실행됩니다. CI에서 파일을 재생성하고, compilerOptions.noUncheckedIndexedAccess drift additionalProperties become T | undefined스키마 측면도 명령줄과 마찬가지로 중요합니다. 프로젝트에서는 oneOf 를 추천합니다. $defs 가 openapi-typescript 가 되도록 강제합니다. 또한 혼합된 추가 구성과 함께 사용하지 않고, 명시적 위치가 불확실할 때 루트에 위치시키는 것을 추천합니다. 이는 잘못된 정의가 생성된 출력에서 사라질 수 있기 때문입니다. 한 가지 더 자세한 정보가 나중에 시간을 절약할 수 있습니다. any이러한 스키마 세부 사항이 누락된 경우, 더 유연한 타입으로 숨겨지기 전에 조기 노출되도록 하세요.
스펙을 명확하게 유지하거나, 생성기는 다시 노출할 수 있도록 신뢰할 수 있는 타입을 노출합니다.
지속적인 워크플로는 간단합니다. 스펙을 버전 관리 하여, 빌드 시 재생성하고, 생성된 파일을 커밋하고, 타입 체커가 불일치로 인한 오류를 신고하기 전에, pipeline의 나머지 부분에서 안정적인 계약 경계를 제공합니다.
Pure 타입, Full 클라이언트 및 No 코드 생성 간 선택
| 패턴 | 빌드 시 | 출력 파일 | 배포 중량 | 최적 |
|---|---|---|---|---|
| Pure 타입에 얇은 래퍼 | 빠르다 | 적다 | 낮음 | 제어와 작은 런타임 표면을 원하는 팀 |
| 전체 클라이언트 코드 생성 | 느린 | 많은 | 높은 | 빠른 전달과 자동화된 연산을 원하는 팀 |
| 코드 생성 요청 빌더가 없음 | 빠름 | 없음 또는 최소 | 낮음 | 단일 코드베이스 앱이 수동으로 전송 논리를 선호하는 팀 |
The choice isn’t really “which tool wins”. It’s which pipeline shape fits your repo, your team, and how much churn the API sees. In a 2025 benchmark around a large OpenAPI spec of about 75,000줄, 2MB, 약 1,200개의 연산을 가진 대형 OpenAPI 스펙에 대한 벤치마크에서 , openapi-typescript 생성된 출력에 대해 평균 1.5초 대조적으로 평균 8.0초 평균 5.5초 @hey-api/openapi-ts, 평균 18.1초 평균 5.5초 Orval, and 18.1 초 평균 5.5초 Kubb또한 단일 출력 파일을 생성하는 반면 16 위하여 hey-api, 2,719 위하여 Orval, 그리고 3,877 위하여 Kubb (성능 비교 세부 정보).
순수 타입은 제어를 선호합니다
순수 타입 설정은 수동으로 요청 레이어와 잘 어울립니다. 런타임이 작고 API 표면이 단순하고 검토할 수 있기 때문입니다. 이게 번들러에 민감한 프론트 엔드와, 하나의 팀이 스펙과 소비자 모두를 소유하는 앱에서 중요합니다. 개발자 경험은 단순한 구문으로만 구성된 것이 아니라는 것을 잊지 마세요. 개발자 경험 관점 개발자 경험 관점은 클라이언트 code가 짧고 명확하며 검토할 수 있을 때 더 쉽게 판단할 수 있습니다.
전체 클라이언트는 전달 속도에 주목합니다
openapi-generator, hey-api, Orval, 그리고 Kubb 모든 시도는 유형보다 더 많은 것을 하려는 것입니다. 요청 메서드, 모델 및 플러밍을 함께 생성할 때 유용할 수 있습니다. 특히 백엔드와 프론트엔드 팀 간의 큰 전환 시점에.
코드 생성이 없는 것은
타입화된 요청 빌더 및 fetch wrappers는 한 코드베이스가 양쪽 끝을 소유하고 API 변경이 밀접하게 조정되는 경우 잘 작동합니다. 단점은 유지 보수 규율입니다. 프로듀서와 컨슈머 사이에 팀과 저장소가 많을수록, 수동으로 작성된 요청层가 드리프트하지 않도록 강력하게 계약 테스트를 강제하는 경우가 많습니다.
핵심 결정 지점은 이념적이지 않습니다. Bundle 비용이 제한적일 경우, 순수한 타입이 매력적입니다. 팀이 최대 scaffold를 원하고 출력을 흡수할 수 있다면, 전체 클라이언트는 설정 시간을 줄입니다. 계약이 가까운 경우, 최소한의 이동 부분과 함께 코드 생성이 없는 요청 빌더가 올바른 내부 거래일 수 있습니다.
Fetch 또는 Axios를 사용하여 얇은 타입화된 클라이언트를 연결하는 방법
생성기가 멈추고 애플리케이션 code이 시작되는 곳입니다. wrapper는 하나의 함수를 노출하고, 타입화된 매개 변수 및 쿼리 객체를 수용하고, 호출을 code 또는 주입된 인스턴스로 전달하지 말고, 지혜롭지 않게 행동하지 말아야 합니다. 대부분의 프로덕션 설정에서, 그 층은 30-60 줄 정도로 남아 있습니다. fetch 타입화된 클라이언트 빌더와 axios production 환경에서 대부분의 설정에서 그 layer는 남아있게 됩니다. 30–60 라인 생성된 타입이 이미 대부분의 형태를 가지고 있기 때문에.
다음은 유지되는 정신 모델입니다:
- 경로 매개 변수는 타입이 유지됩니다. 따라서
/users/{id}호출할 수 없습니다.id. - 쿼리 객체는 타입이 유지됩니다. 따라서 필터가 선택적이면 문자열로 변하지 않습니다.
- 응답 본문은 타입이 유지됩니다. 따라서 code를 파싱할 때는 narrow shape을 기대할 수 있습니다.
그런 wrapper는 의도적으로 재미없습니다. 그것은 재시도, 변환, 또는 인증 정책을 만드는 것이 아니라, 그것이 다른 곳에 속하는지 여부를 판단해야 합니다. 그것은 타입이 지정된 연산에서 요청을 transport layer로 옮기고, 그 다음에 타입이 지정된 결과를 다시 올려줍니다.
wrapper를 재미없게 유지하고 의존성이 적다면, 모든 미래의 코드 생성 변경이 앱에 영향을 미치지 않습니다.
공통적인 실패는 불일치점을 패치하는 것입니다. as any 생성된 타입이 옛 wrapper 서명과 일치하지 않으면 그만큼의 녹색 빌드와 약한 앱이 생깁니다. 또한 generator가 노출하고 싶었던 계약 위반을 숨기기도 합니다.
Axios를 선호하는 팀의 경우 패턴은 동일하지만 전송 구현만 변경됩니다. 더 단순한 브라우저 측 code fetch 요청 함수가 생성된 경로 타입을 받아들이고 타입화된 응답을 반환하는 것이 중요합니다. 나중에 형태를 조정하는 느슨한 객체가 반환되지 않습니다.
이 접합부를 잘 사용하면 OpenAPI TypeScript 스키마는 스펙에, 전송은 wrapper에, 앱은 타입화된 연산을 보게 됩니다. ad hoc 요청 code
Runtime Validation with zod, ajv, or io-ts
TypeScript 타입은 런타임에 사라지며 네트워크는 편집기의 자신감에 관심이 없습니다. 따라서 안전한 패턴은 "생성된 타입을 기대하며"가 아니라 "생성된 타입을 생성하고 edge에서 유효성 검사를 수행하는" 것입니다. 생성된 스키마는 진실의 근원이며, 유효성 검사 라이브러리인 zod, ajv, io-ts 은 컴파일 타임 타입이 처리할 수 없는 경계 검사를 처리합니다.
유효성 검증을 어디서 수행해야 하나요?
React 앱의 경우, 요청이 해결되고 payload가 상태에 들어가기 전에 일반적으로 경계입니다. 서버의 경우, payload가 데이터베이스에 기록되기 전에 또는 비즈니스 규칙에 전달되기 전에 경계입니다. 규칙은 간단합니다. 유효성 검사를 경계 근처에 유지하고 기능 code
A zod A shape can mirror the generated response shape without replacing it:
import { z } from "zod";
const WeatherForecastSchema = z.object({
date: z.string(),
temperatureC: z.number(),
summary: z.string().nullable(),
temperatureF: z.number().optional(),
});그 예는 schema에서 optional로 표시된 field를 검증하고, 생성기에서 생성한 런타임 체크와 일치시킵니다. ajv 이는 서버에서 높은 처리량 JSON Schema 검증을 원할 때 강력한 선택입니다. io-ts still fits teams that already live in the fp-ts composition의 스타일로 살고 있는 팀이 이미 존재하는 경우에도 적합합니다.
composition의 스타일로 살고 있는 팀이 이미 존재하는 경우에도 적합합니다. composition의 스타일로 살고 있는 팀이 이미 존재하는 경우에도 적합합니다. composition의 스타일로 살고 있는 팀이 이미 존재하는 경우에도 적합합니다.
정확한 layering은 예측할 수 있습니다. composition의 스타일로 살고 있는 팀이 이미 존재하는 경우에도 적합합니다. generates the contract, the validator checks the runtime payload, and your app code only sees data that survived both steps. That’s a much better boundary than trusting a static type to police an untrusted response.
CI에서 생성, 유효성 검사 및 계약 테스트를 넣습니다.
contract 기간 동안 유지되는 pipe line은 contract를 gate로, 제안이 아닌 것으로 바꾸며, types를 재생성하고 drift 시 실패하고, run합니다. tsc --noEmit간단한 API Actions 형태 package.json실제 워크플로우는 다음과 같습니다:
A simple GitHub 액션 형태
타입을 다시 생성합니다.
- 변경이 있는 경우 실패합니다.
- 변경이 있는 경우
- 실행합니다.
git diffcontext: HTML 텍스트 프래그먼트. 페이지/영역: Capgo 마케팅 웹사이트. 역할: 장문의 마케팅 또는 법률 문장. 보이는 곳: alternatives/codepush.astro 페이지. Capgo 제품/브랜드 및 개발자 용어를 정확히 유지합니다. 메시지 키: compare_codepush_step2_text (Compare Codepush Step2 Text). - Run
tsc --noEmit. - Mock 서버인 Prism 또는 Spectral-backed 체크와 같은 계약 테스트를 실행합니다.
계약 테스트와 스냅샷 테스트의 주요 차이점은 범위입니다. 스냅샷은 파일이 변경되었는지 알려주지만 계약 테스트는 스펙에 따라 shape이 어떻게 동작해야 하는지 여부를 알려줍니다.
A mock server is especially useful when backend and frontend work are separated by time or team boundaries. It gives consumer code a predictable API surface while still checking the actual contract rather than a hard-coded fixture. The CI 설정 가이드 팀이 깨끗하고 반복 가능한 CI 기준선을 필요로 하는 경우 CI 설정 가이드는 유용한 참고 자료입니다.
제네레이터 버전을 고정하면 코드 생성 PIPELINE의 가장 끔찍한 실패 중 하나인 불시적 출력 왜곡을 피할 수 있습니다. 개발자가 제네레이터를 지역적으로 업그레이드하고 다른 개발자가 업그레이드하지 않으면 생성된 파일은 신호 대신 랜덤 소음이 됩니다. CI는 그럴 수 없습니다.
결과적으로 스키마 변경, 타입 생성, 컴파일러 확인 및 계약 테스트가 모두 서로를 강화하는 PIPELINE이 생성됩니다. 그게 workflow가 진실되게 만드는 것입니다.
유지보수 가능한 PIPELINE, 성능, 최종 체크리스트
생존하는 pipe는 governance가 단조로운 pipe들이다. spec 버전을 관리하고 schema 변경을 code처럼 검토하고 generator를 고정하고 breaking changes가 승인되는 방법을 문서화한다. process가 불분명하면 사람들은 이를 회피하고 generated types는 enforcement가 아닌 decoration이 된다.
몇 가지 성능 조절자가 실제로 중요하다
incremental generation은 monorepos에서 spec이 자주 변경되지만 한 package만이 이를 소비하는 경우에 도움이 된다. tsc --incremental 중복된 컴파일러 작업을 제거하고 production builds에서 필요하지 않은 출력 플래그를 비활성화하면 generated surface가 더 작아진다. 실제로 가장 큰 이익은 여전히 사회적이지 않은 기술적이기 때문에 predictable pipeline이 더 자주 실행된다.
아래의 체크리스트는 기억해야 할 것이다:
- 버전 고정: Lock the file
openapi-typescript스키마 검토:package.json기계 간에 출력이 비틀리지 않습니다. - 드리프트 감지: 드리프트 감지:
- 드리프트 감지: CI에서 재생성하고 diff가 다르면 실패합니다.
- Edge 검증: 미신뢰할 수 있는 데이터를 앱 상태나 영속성에 도달하기 전에 해석합니다.
- 계약 테스트: Mock 백업을 사용하여 소비자가 code이 스키마와 일치하는지 증명하는 체크를 실행합니다.
- 변경 사항 정책: 형태 변경을 승인하고 클라이언트에게 알리는 방법을 기록합니다.
그게 게이트를 포함하는 pipeline이 생성하는 타입만이 아니라 계약을 보이게 만드는 것입니다. 계약의 가시성이야말로 팀이 안전해 보이는 파일만 믿지 않도록 하는 것입니다.
Capacitor 또는 Electron 앱을 배포하고자 하시고 업데이트 PIPELINE이 앱 스토어 리뷰를 기다리지 않고도 자바스크립트, CSS, 복사본, 설정, 자산 수정을 빠르게 적용하고 싶으시다면 Capgo은 JavaScript, CSS, 복사본, 설정, 자산 수정을 빠르게 적용할 수 있는 실용적인 방법을 제공합니다. 자세한 내용은 Capgo 속도와 제어를 잃지 않고 배포 프로세스에 속도가 필요하다면 signed bundles, rollback 보호, 및 릴리스 제어를 포함한 __CAPGO_KEEP_0__의 signed bundles, rollback 보호, 및 릴리스 제어를 확인하세요.
