JSON～TypeScript：現実に即したタイプ

手書き文字がずれてしまう理由

ドキュメントや記憶に基づいて作成されたインターフェイスは楽観的になる傾向があります。彼らは、存在するものすべてにマークを付け、Null 許容フィールドが常に存在すると想定し、プレミアム アカウントにのみ表示されるネストされたオブジェクトを静かに見逃します。次に、TypeScript はサーバーが約束しなかった形状を強制し、最初の `undefined` はコンパイル時ではなく本番環境で表示されます。実際の応答から生成すると、プロセスが逆になります。コンパイラは、期待された形状ではなく、観察された形状をチェックします。

生成されたファイルの読み取り

便利な変換では、ネストされたオブジェクトにキーの後に名前を付け、配列要素の型をそのまま維持し、不確実性を明示的に表現します。すべての意味を伝える 3 つのマーカーに注目してください。

                export interface Order {
  id: string;
  total: number;
  coupon?: string;            // absent in some responses
  shippedAt: string | null;   // present but null until shipped
  items: Array<OrderItem>;
}
              

`coupon?: string` と `shippedAt: string | null` の違いは表面的なものではありません。オプションとは、キーが欠落している可能性があることを意味します。 null は、値のないキーが存在することを意味します。 API は両方を同じペイロード内で行うことが多く、それらを混同すると文字列を想定したコードに null チェックがプッシュされます。

複数のサンプルを使用する

単一の応答で、必要なすべてがマークされます。 2 つまたは 3 つの応答 (理想的には空のアカウントから 1 つと完全なアカウントから 1 つ) を貼り付けると、オプションのキーが表示されます。サンプルに欠落しているフィールドは `?` になり、null の場合があるフィールドは `null` と結合されます。これは利用可能な正確性のアップグレードの中で最も安価であり、生成された型を一度書き込むのではなく、API が変更されたときに再生成する必要がある理由です。

生成されたインターフェイスを API の唯一の説明にしないでください。スキーマまたはコントラクトのテストを並行して保持し、サーバーの変更によってユーザー セッションではなくビルドが失敗するようにします。

タイプが属する場所

• 専用の `types/` または `api/` フォルダ。コンポーネントに分散されていません。
• エンドポイントまたはリソースごとに 1 つのファイル。エンドポイントの名前とキャプチャされた日付を示すコメントが含まれます。
• 再生成メモ: どの呼び出しによってペイロードが生成されたのか、次の人がそれを繰り返すことができます。
• エクスポートはフェッチ レイヤーとコンポーネントの両方で消費されるため、変更は 1 か所だけで中断されます。

厳密モードをオンにする

生成された型は `strict` が有効な場合にのみ有効です。これは、直接アクセスしたときにオプションのキーが実際のエラーになるためです。生成されたインターフェイスをフェッチ境界で `unknown` とペアにし、使用前に絞り込みます。 `JSON.parse` は `any` を返すため、生成されたインターフェイスへのキャストは、期待する場所ではなく検証されたポイントになるはずです。

アップロードしないペイロードから生成する

API レスポンスは、アカウント データ、注文、トークンなど、ほとんどの開発者が扱う最も機密性の高い JSON です。ブラウザで JSON から TypeScript への変換を実行すると、ペイロードはローカルで解析され、決して送信されないため、最初に編集せずに実際の応答を貼り付けることができ、ツールはオフラインで動作し続けます。