リリース時は、TypeScript API はきちんと動作していました。ルートがコンパイルされ、フロントエンドは共有型をインポートし、エディターは全員にクリーンな緑色の感覚を与え、通常は “安全に配信” と意味します。
しかし、バックエンドがレスポンスフィールドを変更したり、予想外の場所でnullable値が現れたり、モバイルクライアントが古いペイロードシェイプを呼び続けたりすると、ほとんどの __CAPGO_KEEP_0__ の作業が途中で止まります。シンタックスではありません。ドリフトです。 API in TypeScript リリース後、型付きAPIが失敗する理由とそれを防ぐ方法
TypeScript __CAPGO_KEEP_0__ のプロジェクトを正しく構築する方法
- チームの形状に合ったフレームワークを選択する
- Scaffolding Your TypeScript API Project the Right Way
- __CAPGO_KEEP_0__
- 完全に型付きの API クライアントを生成して消費する
- 実際に役立つエラー処理、テスト、観察性
- 信頼と制御のあるプロダクションへの配信
リリース後に型付きAPIが失敗する理由とそれを防ぐ方法
通常のリリース中に型付きAPIが通常破壊される。チームはレスポンスフィールドをリネームする。チームは部分的なマイグレーション用に可NullのBranchを追加する。古いクライアントは、モバイルのアップデートがウェブのアップデートより遅れているため、前のペイロードを送信し続ける。TypeScriptは、ローカルタイプを更新したすべてのリポジトリでコンパイルされる。プロダクション環境の契約はすでに間違っている。
その失敗には名前があります: 契約のずれ
TypeScriptはAPIをより快適に使えるようにしたが、弱い契約を過信することを容易にした。共有インターフェイス、ルートジェネリック、型付き fetch ネットワーク上のJSONが2回目、10回目などのリリース後でも、型が一致していることを証明するものではありません。
実稼働環境では、ルールは簡単です。
未検証のJSONが直接アプリケーションロジックに流れ込む場合、TypeScriptの型は意図を表すのではなく、現実を表すものです。
対処方法は、巧妙な型の演算ではなく、真実が存在する場所に関係しています:
- 境界で検証することです。 リクエストボディ、パラメータ、ヘッダー、そして下流サービスレスポンスをパースし、残りのcodeが触れる前に検証することです。
- DTOをドメインモデルにマップすることです。 運輸形状とビジネスオブジェクトを分離して、APIの変更がコードベース全体に漏れ出さないようにすることです。
- 契約から型を生成することです。 OpenAPI、JSONスキーマ、またはスキーマファーストフレームワークは、クライアントとサーバーに共有される真実の源です。
- 破壊的な変更を公開イベントとして扱うことです。 フィールドの形状が変化した場合、意図的にバージョンを管理し、外部契約の変更と同様にコミュニケーションを取ります。
DTOのマッピングは、チームが最も省略する部分です。最初は冗長に思われます。数回のリリース後、DTOマッピングは、サービスとフロントエンド画面にわたる古いフィールドのエイリアスを拡散するのを防ぐためのレイヤーになります。境界での小さな翻訳ステップは、後で広範なリファクタリングよりも安価です。 string | null APIは型付きでも失敗します。エラー契約は通常後思われています。成功のペイロードは注目されますが、失敗のペイロードはその日、例外がシリアライズされた形で何が起こったかによって変わります。クライアントは、設計されていない形にリトライロジック、ユーザーメッセージング、モニタリングを構築します。結果は同じ問題が形を変えています。ドリフト。
バージョニングには同じ規律が必要です。チームは、1つの大きなリライトでクライアントを破壊することは滅多にありません。彼らは、互換性のないものに加算される一連の合理的なローカル変更でクライアントを破壊します。明確な__CAPGO_KEEP_0__バージョニング戦略で、契約が進化する際に、変更が消費者に到達する前に可視化されます。
目標は、TypeScriptを全ての場所に持つことではありません。目標は、リリース後、複数のデプロイ、複数のクライアント、実際の生産データが、最初の日にはきれいなタイプに圧力をかけるのを防ぐことです。 TypeScriptのAPIプロジェクトを正しく構築する方法 型付きの__CAPGO_KEEP_0__は、最初はきれいな状態です。6か月後、一つのルートは未検証の入力を受け付け、もう一つのルートは未加工の
__CAPGO_KEEP_0__
API
API process.env、そして3番目は、クライアントが設計されていない形を返します。サーバーはほとんどの場合、すべての部分が同時に壊れないように設計されています。契約の変化が通常の機能開発に混入するための十分なスペースを提供します。
プロジェクトの形を選択して、契約を回避することが難しくなるようにしてください。
チームの形に合ったフレームワークを選択してください。
TypeScriptのAPIの場合、最初のフレームワークの決定は、契約の規範を維持する場所についてではなく、シンタックスについてはあまり関係ありません。
- Express チームがミドルウェアモデルを既に知っている場合、最小限の抽象化を必要とするチームに適しています。フレームワークは手から離れますが、ルートごとに独自の検証、エラー形状、レスポンスの規範を設定するようになると、問題が生じます。
- Fastify 小規模から中規模のバックエンドチームにとって、強力なデフォルトです。プラグインシステムはきれいであり、スキーマの作業をルート層に近づけることで、実行時ビヘイビアと型を同期するのに役立ちます。
- Nest 多くのコントリビューター、共有モジュール、明示的な所有権境界を持つ大規模なコードベースに適しています。コストは典礼であり、サービス自体が小さくてあれば、重いスタックに不一致な規範を重ねることのコストは実際に実際です。
私は通常、チームが使用するよりも多くのフレームワークを購入するのを避けます。小規模なサービスにFastify、検証ライブラリ、生成された契約型を使用する場合、より重いスタックに不一致な規範を重ねた場合よりも、再構築に耐えられることがよくあります。
フォルダレイアウトは境界を保護する
フォルダ名はインポート圧力よりも重要ではない。ルートがデータベースモデルにアクセスできる場合、またはサービスがクライアントにORMエンティティを直接返す場合、スケルトンはすでに漂流を誘う
生産環境で持続するレイアウトは、次のことを分離することが多い
src/routesHTTPワイヤリングのみsrc/schemas要求とレスポンスのスキーマsrc/dtoトランスポートタイプとマッピングcodesrc/servicesユースケースとオーケストレーションsrc/domainビジネスモデルは、単一のエンドポイントを超えて生き残るべきsrc/clientsダウンストリーム統合src/errors共有エラー種類と狭め方のヘルパーsrc/config起動時構成パーシング
それ src/dto 層はただの無駄ではない。APIは外部の変更を吸収する場所を与え、ドメインロジックや無関係なエンドポイントを通じて漏れさせないようにする。
構成には同じ扱いを与える価値がある。起動時に環境変数を1度だけ解釈し、無効な値の場合に速やかに失敗し、型付きの構成オブジェクトをアプリの残りの部分にエクスポートする。チームが読み続けている process.env ハンドラの中に常にブランチの実行時動作が生じ、TypeScriptが助けることができないパターンに陥ることが多い。環境構成に関する このガイドは、標準化する必要がある場合の参考になります。 コンパイラを緊密にする前に機能を追加する
生産的な__CAPGO_KEEP_0__では、安全でない__CAPGO_KEEP_1__を書くのは面倒になるようにする。
A production API should make unsafe code annoying to write.
有効
strictenableduseUnknownInCatchVariablesenablednoUncheckedIndexedAccessパスエイリアスは、Node、テスト、バンドリング、ツールのすべてが同じ方法で解決する場合にのみ使用する- __CAPGO_KEEP_0__は外部の変更を吸収する場所を与え、ドメインロジックや無関係なエンドポイントを通じて漏れさせないようにする。
- 分離
build,typecheck, CI内でlintスクリプトを分離する
弱い tsconfig 無視されながら蓄積する。厳格なものは、ミスマッチを生産動作になる前に、可視化された作業に変える。
Lint rules help too, especially rules against unused imports. anyルーティング層近くにOpenAPI仕様の生成元を決めることは早い段階で重要な選択肢です。チームによっては、__CAPGO_KEEP_0__から最初のスキーマを生成するものがあります。別のチームは、仕様からサーバースタブとタイプを生成するものがあります。どちらのアプローチも機能します。失敗するのは、最初のリリース後も誰もチェックしないように仕様を扱うことです。
One more scaffolding choice matters early. Decide where your OpenAPI spec will come from and keep that decision close to the route layer. Some teams generate it from code-first schemas. Others generate server stubs and types from the spec first. Either approach can work. What fails is treating the spec as a side artifact that no one checks after the first release.
Streamkap Flink TypeScriptガイド は、ストリームやイベント重視のシステムで、契約ドリフトがHTTPハンドラーではなく、長いパイプライン全体で現れる場合に役立ちます。 DTOの設計と入力の検証
バウンダリでDTOの設計と入力の検証
A typed API usually looks correct on day one. Six months later, the bugs show up at the boundary. A mobile client still sends an old field. A partner omits a property your frontend assumed was always present. A refactor exposes an internal ORM column in a public response. TypeScript did its job inside the codebase. The contract still drifted.
DTOの設計はなぜ重要か。リクエストボディをきれいに見せることだけではない。最初のリリース後もパブリックタイプを正直に保つことだ。
パブリック契約と内部モデルは同じでならない
A DTO APIは通信で送信されるデータを表します。 DTOの設計と検証プロセスを示す図。 __CAPGO_KEEP_0__ コントラクトを維持するために安全なシステム境界を確保する ルートがこのようなものを受け取った場合
境界は通常、以下のステップが必要だ
type CreateOrderRequestDto = {
customerId: string
items: Array<{ sku: string; quantity: number }>
note?: string | null
}translations OrderDraft translations
translations
- 受信データを解析する
- 受信データの形状とフィールドレベルの制約を検証する
- DTOをドメインオブジェクトにマップする
- ドメインオブジェクトにビジネスロジックを実行する
- 結果をレスポンスDTOにマップする
- 送信する前に出発するレスポンスを検証する
ステップ6はよくスキップされるステップでもある。プライベートフィールド、nullable値が安定したレスポンスにリークした値、そしてリファクタリング中のアクシデントによるスキーマの変更もここでキャッチされる。
データにビジネスロジックが触れる前に検証する
コンパイル時型はネットワークからJSONを検証しない。別のサービスが返す形状がコンパイル時型の制約を満たしているときでも、実行時にはアサーションを破る。 unknown 実行時にはあなたの仮定を破壊します。
For API work in TypeScript, Zod is a common choice because it parses at runtime and infers types for the rest of the code. Valibot, io-ts, and similar libraries can work too. The library matters less than the rule. Untrusted data gets parsed before anything else uses it.
__CAPGO_KEEP_0__
- Inbound schema 不正なリクエストデータを拒否する
- 依存性スキーマ 第三者APIや内部サービスからのレスポンスを検証する
- アウトバウンドスキーマ APIが即座に公開することになるレスポンスを検証する
実装後、多くの型付きAPIがここで失敗する。チームはリクエストを検証し、下流のレスポンスの検証をスキップし、次にプロダクションインシデントが発生する理由を理解するのを忘れる。
実用的なルールは次のとおりです。ルート層でJSONが止まる。
マッピングはcodeの無駄ではありません。漂流が見える場所です。
DTOマッピングに抵抗するチームはよく見られます。繰り返し感じるからです。私は実際にその逆を実行しました。薄いマッピング層は契約変更が明らかで、レビュー可能で、ローカルです。
例えば:
- transportを許可する
note?: string | null - ドメインモデルは、
note: stringとともに""デフォルトの - レスポンスDTOは、
note全てを省略することができます。空の場合
それぞれ異なる真実が3つあります。3つの異なるアウディエンスに対して。1つの共有インターフェイスとして扱うことで、差異はクライアントが破棄するまで隠されます。
ウェブフックは、さらに明確にこのことを示しています。消費者は、ペイロードの形状を数年間保持する可能性があります。チームがこの問題を解決している場合、この ウェブフックペイロード設計の例 は、有用な相棒です。
共有されたタイプは、明示的な真実の源がある場合にのみ役立ちます。
バックエンドのインターフェイスをフロントエンドにコピーすることは、時間の遅延を伴う漂流です。共有パッケージは、意図的に公開されたタイプのみに役立ちます。
より大きなコードベースで持続するセットアップは、以下のようになります。
- public リクエストとレスポンスのスキーマを、永続化モデルから分離する
- 生成された OpenAPI からそれらの public スキーマを生成する、または OpenAPI からサーバータイプを生成する
- 生成された契約型をハンドラーやクライアントの近くに保つ
- ドメイン型と ORM モデルを内部に保つ
- 互換性が重要な場合に、DTO を意図的にバージョンアップする
その分離は、Azure __CAPGO_KEEP_0__ チームの TypeScrip 設計ガイドラインと一致している TypeScript design guidelines from the Azure SDK team境界が維持可能なものであることは、意図的に面白くない
良いバージョンは、もっと賢くない
前は、フロントエンドは
バックエンドは ORM オブジェクトを直接返し、すべてのレイヤーを表現する共有インターフェイスを信頼していた fetch().json() 後は、各境界はデータをパースし、DTO は狭く、ドメインモデルは内部に保たれ、生成された型は public 契約をカバーし、マッピング code は変更を明示的にする
APIをTypeScriptで使用する
完全に型付きのAPIクライアントの生成と消費
型付きのクライアントはリリース日には完成したように見えます。3か月後、1つのエンドポイントはnullableフィールドを返し始め、もう1つはカーソルページネーションを追加し、モバイルアプリでは古いバージョンの契約を固定します。TypeScriptの型はまだコンパイルされます。呼び出し元はまだ破棄されます。
クライアント層の仕事は、最初のリリース後も公開された契約を真実に保つことです。エディターのオートコンプリートが見栄えがいいだけではありません。
型付きクライアントの戦略を選択する
クライアントの形状は、APIの実際の複雑さに合致するべきであり、チームの好みに合致するべきではありません。
| アプローチ | ベストフォー | トレードオフ |
|---|---|---|
| ハンドロールされたフェッチラッパー | 小規模なアプリ、不慣れな認証フロー、高速なイテレーション | すぐに始められます。時間の経過とともに呼び出し元間で分散する可能性があります |
| OpenAPI code generation | REST APIの実装が簡単で、定義されたスキーマが安定している | 強力なベースライン。カスタム認証、ストリーミング、または不慣れなページネーションに必要な支援が必要 |
| SDK-styleの型付きクライアント | 複数のチームが使用するプラットフォーム、公開API、長期間の統合 | 最高のメンテナンスコスト。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.
次の条件が真である場合に手作りのクライアントを使用することをお勧めします: any __CAPGO_KEEP_0__
__CAPGO_KEEP_0__
- APIは小さく内部です。
- codeの契約が頻繁に変更されるため、再生成がノイズになる
- カスタムトランスポートの動作が仕事を支配しています。
- クライアント側でランタイムパーシングを維持する意欲があります。TypeScriptの注釈だけではありません。
その最後の点は重要です。 response.json() 実行時には未知のデータを返します。関数シグネチャがそうではありません。
OpenAPIの生成は実用的デフォルトです。
安定したREST APIの場合、生成された型が最もメンテナンス対安全性比率が高いです。重複した型の書き込みを削減し、契約変更がプルリクエストで可視化されます。
リファクタリングが生き残るパターンは単純です。公開契約から生成し、生成された層を薄くし、消費者がより便利なエコノミクスを必要とする場合は、小さなラッパーを追加してください。 OpenAPIのTypeScript生成ワークフローはそのモデルに合っています。 そのような分割が役立ちます。
__CAPGO_KEEP_0__の生成フローは、生成された層を薄くし、生成された層の変更がプルリクエストで可視化されるようにします。
- code が生成されると、要求と応答の形状を所有します。
- SDK wrapper が薄く作られると、認証の挿入、リトライ、ページネーションのヘルパーが所有されます。
- 実行時検証は、サーバー境界と、不信頼の入力がシステムに再入る場所で行われます。
- DTO のマッピングは明示的で、内部モデルが変更されてもクライアント契約に影響を与えません。
ハイブリッドアプローチは、生成された code が面白くないことを保ちます。面白くない code は、再生成、レビュー、置き換えが容易です。
生成されたクライアントをアプリケーション code が触れる前に Wrap してください。
生成された関数は、コードベース全体で広く使用するには、通常、太くて使いづらいです。トランスポートの詳細を露出すると、呼び出し元がそれを再度学習する必要があります。
薄いラッパーは、ポリシーを一貫して保つ 1 つの場所を与えます:
- デフォルトヘッダーと要求 ID を付加する
- エラーシェイプを標準化する
- ページネーションをイテレータまたはヘルパーメソッドとして公開する
- マルチテナントケースの場合に、各要求ごとに認証オーバーライドをサポートする
- 生成された要求と応答のタイプを保存し、手動で書き直すのではなく
例えば、 code アプリケーションは client.orders.listAll() または client.orders.list({ cursor })例えば、 __CAPGO_KEEP_0__-スタイルのクライアントは、 __CAPGO_KEEP_1__ が製品である場合に意味があります
SDK-styleクライアントは、APIが製品である場合に意味があります。
良好なクライアントのエコノミクスは、以下のようになります:
型付きのページまたは非同期イテレータを返します
client.orders.list()ストリーミングを処理することなく、低レベルのフェッチ セットアップを各呼び出しにリークさせないclient.files.stream()認証はグローバルに設定でき、リクエストごとにオーバーライドできる- 呼び出し元は、固定された型付きエラー オブジェクトを受け取るのではなく、適時投げられたペイロードを受け取るのではなく
- これはメンテナンスコストを追加します。契約の漂白が広がるのを防ぎます。各消費チームが同じ境界規則をわずかに異なる形で再構築するのを防ぎます。
または
完全に型付けされたクライアントはゴールラインではありません。ゴールラインは、APIが進化しても、生成は公開契約から始まり、実行時検証は境界を保護し、DTOマッピングは内部の変更を外部に漏らさないクライアントのことです。
実際に役に立つエラー処理、テスト、観測性
ほとんどのTypeScript APIの例は、過度に静かです。リクエストは成功し、JSONはインターフェイスと一致し、失敗は throw new Error("something went wrong")。生産環境では、そんなに丁寧に振る舞うことはありません。
最初の修正は機械的です。TypeScriptでは、 キャッチされた値は unknown、読み込む前に狭められます。 message, stack、レスポンスプロパティ。 cause専門家のガイドラインでは、カスタムエラークラスを作成し、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のパース失敗、または予期しないスローから生じる失敗に耐えられるように見えます.
エラーが一時的な場合のみリトライする
エラーの分類の2番目の大きな改善は、TypeScript SDKとAPIの操作のガイドラインが、清潔なルールに収束することです: リトライするべき一時的なエラーは、ネットワークエラーまたはHTTP 429および503のレスポンスなどです。早期の検証、エラーのコンテキストの保存、ビジネスルールのエラーのリトライの回避が推奨されます。同様のガイドラインも Promise.all 失敗を速くする並列作業の Promise.allSettled 部分的な成功が許容される場合(SDK エラーハンドリングパターン).
私は3つのバケットを好みます:
- 検証エラー リクエストがプロセスを離れた直前に間違っていたことを意味します。
- 一時的なエラー リトライにバックオフを組み込むと成功する可能性があります。
- 永久的なエラー ビジネスルール、権限、またはリソースが不足していることを反映し、直接表面化する必要があります。
その分類は、汎用的な「失敗時にリトライ」ヘルパーよりも良いcodeを実現します。
フィールドルール: リトライは、運輸の不確実性に属するものであり、ドメインの異議申し立てとは関係ありません。
オブザビリティは、失敗を記録するだけでなく、失敗を説明する必要があります。
API
TypeScriptで使用する場合、リクエストが境界を越えるたびに、関連ID、ルート名、リクエストメタデータ、正規化されたエラーシェイプを付与する必要があります。
- __CAPGO_KEEP_1__ __CAPGO_KEEP_2__
- __CAPGO_KEEP_3__ __CAPGO_KEEP_4__
- __CAPGO_KEEP_5__ __CAPGO_KEEP_6__
- __CAPGO_KEEP_7__ エラークラスとルートを除外し、単にステータスcodeを取得
__CAPGO_KEEP_9__ Capgo、CapacitorとElectron環境でライブアップデートの送信と追跡に型付きAPIを提供します。クライアント側の契約修正が制御されたロールアウトとバージョンごとの可視性が必要な場合に便利です。アプリストアの待ち時間の代わりに。チームがフィードバックループを完全に締め付けるには、このガイドは アプリ観測性 実装だけではなく契約をテストする
単独のユニットテストでは漂流を検出できません。漂流が発生する場所でテストを追加してください。
境界検証テスト:
- 不正な入力をスキーマにフィードし、失敗の形状を断言してください。 契約テスト:
- 実際のHTTPレスポンスが公開された契約と一致することを確認してください。 型付きエラー断言:
- 一時的な失敗と恒久的な失敗が正しく標準化されることを確認してください。 クライアント統合テスト:
- クライアント統合テスト: 生成されたまたはラッピングされたクライアントは、実際のレスポンスを正しく解釈する必要があります。
型付きAPIの強力なテストスイートは、codeパスを証明するだけでなく、契約が真実を伝えていることを証明します。
信頼と制御の下で製品を配信する
品質のリリースは、繰り返しのループから得られるものであり、英雄的な行為ではありません。
TypeScriptパイプラインで信頼できるAPIは、通常、次の要素を含みます: CIでスキーマチェック、生成されたアーティファクトのタイプチェック、マージ前に契約差分レビュー、そして、クライアントの人口が準備されていない場合に、展開パスが遅くなるか、ロールバックすることができる。
品質のリリースループ
私は、チームがフォローするように、製品チェックリストを短く保つことを好みます:
- 契約の変化にCIを失敗させる: OpenAPIが変更された場合、生成されたタイプとクライアントは同じ変更で更新する必要があります。
- 契約を共有する: 公開DTOパッケージには、リリースの規律が必要であり、気軽なリファクタリングではありません。
- チャネルまたはコホートごとに展開する: Don't expose every consumer to a breaking integration change at once.
- Rollbackを簡単にする: 契約、クライアント、またはWebバンドルをリバートすることが、運用上の面倒な作業であるべきです。
インフラストラクチャとデプロイワークフローの同時移行を行うチーム向けの開発者向けクラウド移行ガイド クラウド移行のための開発者向けガイド is a helpful planning reference because API reliability often degrades during platform transitions, not just during code changes.
正確さよりも制御が重要です。
__CAPGO_KEEP_0__ または Electron のスタックが含まれている場合、__CAPGO_KEEP_1__ ツールは、契約のバグを修正した後、ユーザーに修正を適用するまでの時間差を短縮できます。重要なのは、「より速い更新」は抽象的なものではなく、「チャネルベースのロールアウト、ロールバック保護、バージョンレベルの観察性」であることです。契約の修正が制御されるようにすることです。
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 __CAPGO_KEEP_0__ __CAPGO_KEEP_1__
__CAPGO_KEEP_0__
Capgo gives teams shipping Capacitor and Electron apps a typed way to deliver web bundle fixes, control rollout channels, and monitor adoption and failures by version. If your API contract fixes also need to reach clients quickly without waiting on store review, visit Capgo.
