workers-best-practices

Cloudflare Workers の API、型、設定に関するあなたの知識は古くなっている可能性があります。Workers のコードを書いたりレビューしたりする際は、事前学習よりも検索を優先してください。

既存のコードの基準としては、プロジェクトにインストールされているバージョン、生成された型、Wrangler の互換性設定を使用してください。API、設定、ランタイムの動作、制限に関する主張を検証するために、関連する Cloudflare ドキュメントを検索してください。

リファレンス

タスクに関連するセクションを読んでください:

リファレンス	使用するタイミング
設定と可観測性	互換性日付、バインディング、生成された型、シークレット、ログ、トレース
ランタイムパターン	ストリーミング、Promise のライフタイム、リクエスト状態、サービス呼び出し、セキュリティ、ランタイムテスト
プラットフォーム API チェック	ハンドラーのシグネチャ、プラットフォームクラス、バインディングへのアクセス、シリアライゼーション

証拠が見つからない場合は、Workers のベストプラクティスを参照するか、Cloudflare ドキュメントディレクトリで該当する製品を探してください。設定フィールドには、インストールされている Wrangler スキーマを使用してください。新しい型パッケージは、プロジェクトで設定されたターゲットを置き換えるものではありません。

互換性日付を最新に保つ

新しい Workers には今日の日付を使用してください。既存の Workers については、定期的な更新を推奨し、互換性の変更を確認して関連するテストを実行してください。既存の動作を、設定された日付とフラグに対して評価してください。詳しくは互換性ガイダンスを参照してください。

可観測性を有効にする

Worker を作成するとき、または本番環境向けに準備するときは、Workers LogsとTracesを有効にしてください。observability.enabledとobservability.traces.enabledをtrueに設定してください。トップレベルの設定だけではトレースは有効になりません。構造化 JSON ログを使用し、ワークロードに合わせてサンプリングを設定してください。レビュー時には、ログやトレースの欠落を指摘してください。詳しくは設定例を参照してください。

指摘すべきアンチパターン

アンチパターン	影響と推奨されるパターン
無制限のデータに対する await response.text() などのバッファリング	Worker のメモリを使い果たす可能性があります。大きな本文や無制限の本文をストリーミングしてください。
ソースコードや設定へのシークレットのハードコード	バージョン管理を通じて認証情報が漏えいします。Wrangler のシークレットを使用してください。
セキュリティ上重要なトークンや ID に対する Math.random() の使用	値が予測可能になります。crypto.randomUUID() または crypto.getRandomValues() を使用してください。
await せず、返さず、ctx.waitUntil() に関連付けもしない非同期処理の開始	処理が破棄されたり、エラーが見逃されたりする可能性があります。リクエストまたはバックグラウンド処理のライフタイムに関連付けてください。
モジュールレベルの可変なリクエスト状態	リクエスト間でデータが漏えいし、I/O の所有権エラーが発生する可能性があります。リクエスト状態は明示的に渡してください。
Worker のバインディングで利用可能な操作に対する Cloudflare REST API の呼び出し	ネットワークと認証のオーバーヘッドが増加します。利用可能なバインディングを使用してください。
一般的なエラー処理としての ctx.passThroughOnException() の使用	オリジンに転送することで Worker の障害が隠れる可能性があります。明示的なエラー処理と構造化されたエラーレスポンスを使用してください。
Wrangler のバインディングと重複する手書きの Env	設定との不整合が生じる可能性があります。wrangler types でバインディングの型を生成してください。
シークレット値の直接的な文字列比較	タイミングの差が露呈する可能性があります。Web Crypto による比較パターンを使用してください。
const { waitUntil } = ctx のように ctx のメソッドを分割代入すること	レシーバーが失われます。ctx.waitUntil(...) を呼び出してください。
Env やハンドラーパラメーターに対する any の使用	バインディングやハンドラーの契約に関するエラーが隠れます。プロジェクトで生成された型とプラットフォームの型を使用してください。
プラットフォームの型との一致を強制するための as unknown as T	互換性の問題が隠れます。根本にある契約を修正してください。
プラットフォームの基底クラスを拡張する代わりに implements を使用すること	実行時の動作、this.ctx、this.env は継承されません。適切な基底クラスを使用してください。
プラットフォームクラスのメソッド内で env.X をバインドせずに使用すること	バインディングには this.env.X からアクセスできます。バインディングへのアクセスパターンを参照してください。
Queues、Workflow のステップ、ストレージ、WebSockets に同じシリアライズ規則を適用すること	有効なペイロードを拒否したり、サポートされていないペイロードを受け入れたりする可能性があります。各 API とエンコーディングを確認してください。

検証

影響を受ける Workers の動作について、プロジェクト既存のチェックを使用してください。型チェックではバインディングまたはハンドラーの契約に関する変更を確認し、動作の変更には関連するランタイムテストを実行してください。必須のリポジトリチェックは維持してください。範囲を絞った編集であれば、Workers 全体の監査は必要ありません。

対象範囲

このスキルでは、Workers 固有のベストプラクティスとコードレビューを扱います。関連トピックについては、以下を参照してください。

• Durable Objects：durable-objects スキルを読み込みます
• Workflows：Workflows のルールを参照してください
• CLI コマンド：cf-cli スキルを読み込むか、Wrangler 設定ファイルのあるプロジェクトでは wrangler スキルを読み込みます