oRPCで契約を中心に型安全なAPIを組み立てる

契約と実装の失敗を分ける

契約にない入力、認証失敗、サーバー例外、OpenAPIからの呼び出しを別のケースとして記録します。`@orpc/contract`の型が揃った後も、HTTPステータス、エラー本文、ログの相関IDは実行時の確認項目です。選択したNodeまたはBunのアダプターで同じテストを回し、環境差を残します。スキーマライブラリを変えた場合は、同じ契約の受け入れ結果が保たれるかを比較します。Cloudflareを選ぶ場合はDurable Objectsの状態保持も別ケースにします。Pub/SubをmemoryからRedisへ移した場合の再起動後の通知も確認します。OpenAPIの仕様と実際のHTTP応答を照合し、ZodやValibotを選んだ場合の拒否値も同じテストケースで比較します。入力値の型変換とエラー形式を契約側と実装側で照合し、クライアントの生成型だけを根拠にしません。

最小契約から統合を増やす順序

最初はHTTPの一つの手続きだけを実装し、型検査、入力失敗、OpenAPI生成、クライアント呼び出しを一つのCIジョブで確認します。その後に選んだフレームワークやレート制限を加え、どのパッケージ導入で挙動が変わったかを追える状態にします。

契約を単一の情報源に置くコア構成

oRPCは、APIコントラクトを単一の情報源として定義する`@orpc/contract`、APIを実装する`@orpc/server`、型安全に呼び出す`@orpc/client`、OpenAPI互換性を加える`@orpc/openapi`で構成されています。READMEの中心は、パッケージを必要な責務ごとに選ぶ設計です。

この構造では、最初に契約を決め、サーバー実装とクライアント利用を同じ型から確認できます。型検査が通ることは、認証や業務ルールの正しさを意味しません。入力拒否、エラー形式、生成されたOpenAPI文書を実データで確認する必要があります。

Zod、Valibot、ArkTypeを選択肢にする

スキーマ検証には`@orpc/zod`、`@orpc/valibot`、`@orpc/arktype`があります。READMEは、それぞれZod、Valibot、ArkTypeとの統合パッケージとして掲載しています。既存アプリが採用している検証ライブラリに合わせやすい構成ですが、三つを同時に入れる必要があるとは書かれていません。

確認時は、文字列から数値への変換、欠落フィールド、未知フィールド、配列要素の失敗を契約に沿って試します。`@orpc/json-schema`はOpenAPIリクエスト向けのsmart coercionを提供すると説明されているため、変換後の値をサーバー側でログまたはテストから確認しておくべきです。

Pub/Subとレート制限は実行基盤を選ぶ

組み込み機能として、`@orpc/publisher`にはmemory、Redis、Upstashのアダプター、`@orpc/ratelimit`にもmemory、Redis、Upstashのアダプターがあります。`@orpc/hibernation`はCloudflare Durable ObjectsのWebSocket Hibernation APIの利用を扱います。

これらは同じ名前で交換できる便利機能というより、状態の保存先や実行環境に依存する部品です。ローカルのmemory設定からRedisへ移す場合は、複数プロセス間の通知、再起動後の状態、制限値の単位を確認します。READMEは個別の性能値や障害時の挙動を説明していないため、負荷試験の結果を機能説明に置き換えません。

Next.jsからtRPCまで接続先が広い

統合パッケージには、Next.js Server Functions用の`@orpc/next`、AI SDKのツールへ変換する`@orpc/ai-sdk`、TanStack Query、Pinia Colada、SWR向けのデータ取得連携があります。Nest、Node、Bun、Cloudflare、既存tRPCルーター向けのパッケージも一覧にあります。

選択肢が多い分、実行環境を先に固定するのが要点です。Next.jsのサーバー関数とCloudflare Durable Objectsでは、ライフサイクルも利用できるAPIも違います。使う統合のREADMEへ進み、同じ契約から生成される型、エラー処理、ストリーミングの境界を確認します。

可観測性はOpenTelemetryとPinoを分けて導入

可観測性の項目には`@orpc/opentelemetry`、`@orpc/pino`、`@orpc/evlog`が並びます。分散トレースをOpenTelemetryで収集するのか、PinoまたはEvlogでログを整えるのかは、既存の監視基盤に合わせて決める構成です。READMEはログ内容や個人情報のマスキング規則までは定めていません。

APIの型安全性を監視の正しさと同一視しないことが大切です。リクエストID、契約名、失敗した検証項目を出す場合も、認証情報や入力本文をそのまま記録しない設計を別に確認します。実験では一つの成功と一つの検証失敗を発生させ、トレースとログの対応を見ます。

MITライセンスとパッケージ単位の採用判断

リポジトリのライセンスはMITです。READMEには公式ドキュメントとDiscordへの入口があり、リリース情報としてv2.0.0-beta.31が素材に記録されています。ベータ版である以上、パッケージ間のAPI変更や統合側の追随を確認する前提で扱うべきです。

採用の手順は、契約、サーバー、クライアントの最小例を一つのテストにし、OpenAPI文書、スキーマ失敗、選択したアダプターの再起動を記録することです。oRPCの全パッケージを導入するのではなく、現行のNodeやフレームワークに必要な名前空間だけを固定できるチームに適しています。

編集部の結論

oRPCは、APIの入力と出力を契約として共有し、TypeScriptクライアントとサーバーの型を揃えたいチームに向きます。まず`@orpc/contract`で小さな契約を定義し、`@orpc/server`と`@orpc/client`を接続して、OpenAPI出力と実際のバリデーション結果を確認してください。必要な統合だけを追加し、RedisやCloudflareを使う場合は各アダプターの条件を個別に確かめます。

公式情報源

1. Official documentation
2. Official README
3. Project repository
4. Release notes