wp-ability-development

WordPress アビリティの開発

使用する場面

WordPress アビリティが受け付ける内容、返す内容、または実行する処理を決めるときに、このスキルを使用します。登録、公開、クライアントでの使用については、wp-abilities-api を参照してください。

収集するコンテキスト

誰がアビリティを呼び出すのか、何をしたいのか、すでにどのような情報を持っているのか、何を受け取る必要があるのかを特定します。たとえば、パーマリンクからノートを開く呼び出し元はスラッグを知っている場合があります。一方、保存済みの下書きを読み込むエディターは、すでに ID を持っている場合があります。各呼び出し元が利用できる情報を把握すると、アビリティでサポートする入力を選びやすくなります。

既存のアビリティについては、スキーマとコールバックを読んで、何を受け付け、何を返し、何を変更するのかを確認します。関連するアビリティも確認し、共通するオブジェクトの形式や用語を把握します。アビリティが公開されている場合は、契約を変更する前にドキュメント、テスト、既知の呼び出し箇所を確認し、呼び出し元がすでに依存しているものを特定します。

手順

呼び出し元のタスクから始める

呼び出し元が使う言葉でリクエストを説明します。その用語をアビリティの名前、フィールドの説明、結果に使い、実装の概念へ対応付けます。フィールドの説明では、各フィールドが何を制御するか、また重要な場合は省略したときにどうなるかを説明します。呼び出し元は、アビリティの名前、説明、スキーマをもとに、アビリティを選び、リクエストを作成できる必要があります。

たとえば、「この作成者の公開済み投稿を検索する」というリクエストからは、where.status と where.author が考えられます。コールバックでは、これらのフィールドを WordPress のクエリー引数に変換できます。

入力は必要最小限かつ明確にする

• 呼び出し元が渡す必要のある情報を求めます。残りの情報をアビリティが取得できる場合は、参照情報を受け付けます。たとえば、商品 ID と数量を受け取り、保存済みのデータから価格を計算します。
• 呼び出し元に明確な必要性がある場合にフィールドを追加します。選択肢を増やすたびに、検証とサポートが必要な組み合わせも増えます。
• 最初は厳格にします。フィールドが定義されたオブジェクトには、ネストされたオブジェクトも含めて additionalProperties: false を設定します。アビリティが処理できる内容に合わせて、型、許可値、範囲を指定します。たとえば、誤記されたフィルターを拒否すれば、より広いレコード群に一致する前に、呼び出し元がリクエストを修正できます。ユースケースに応じてアビリティが受け付ける内容を広げる場合も、既存のリクエストの意味は維持します。

関連するフィールドにはそれぞれ独自の型を与える

1 つの概念を表すフィールドは、独自のスキーマを持つネストされたオブジェクトにまとめます。名前付きオブジェクトにすることで、呼び出し元と開発者は値を個別に検証、受け渡し、再利用できます。

たとえば、生のコンテンツとレンダリング済みのコンテンツの両方を公開するアビリティでは、それらを content.raw と content.rendered にまとめられます。また、公開日時と更新日時をサイト時刻と GMT の両方で返す場合、それらの日付は site と gmt フィールドを持つ共通の型にまとめられます。

関連する入力制御にはネストされたオブジェクトを使い、各グループが個別に発展できるようにします。タスクごとに、明確な入力形式を 1 つ用意します。状況が異なる場合は、関連するオブジェクト内で選択肢をモデル化し、共通の入力定義を 1 つだけ使えるようにします。スキーマが混在したリクエストや不完全なリクエストを拒否できるように、各分岐で必須となる内容と受け付ける内容を定義します。

たとえば、ID とスラッグの両方で検索できる場合、selector オブジェクトで oneOf を使うと、どちらか一方だけを受け付けられます。

各アビリティの成功時の結果形式を予測可能にする

成功した呼び出しには、安定した結果の型と構造を選びます。コレクションへのクエリーは、一致するレコードが 0 件でも、1 件でも、複数件でもコレクションを返すため、呼び出し元はどの場合でも結果を反復処理できます。単一のレコードとコレクションを切り替えるトップレベルの oneOf を使うと、呼び出し元は結果を使う前に形式を確認する必要があります。使用するスキーマ機能を対象のクライアントがサポートしているか確認します。

呼び出し元が必要とする情報を返す

• 呼び出し元が結果をそのまま利用できるだけの情報を提供します。たとえば、呼び出し元が注文内容を表示する必要がある場合、注文の概要には商品名と商品 ID を含めることができます。
• すでに計算済みの有用な値を返します。たとえば、チェックアウト機能では、合計金額の計算に使用した割引や税額を含めることができます。呼び出し元は料金ルールを再現しなくても、実際の内訳を表示できます。
• 書き込みによって変更された内容を報告します。関連する保存済みの状態を返し、注文の作成と同時に顧客アカウントも作成されたかどうかなど、呼び出し元が把握すべき副作用を説明します。
• 成功した結果を定義するフィールドを必須にします。利用できない場合がある補足値には null を使い、その意味を説明します。フィールドを省略できる場合は、別途明記します。たとえば、注文結果では注文 ID を必須とし、レシートの準備中はレシート URL を null で返すことができます。
• 応答の内容を必要なものに絞ります。呼び出し元が確認でき、利用できる詳細を含めます。追加データの取得、計算、返却にかかるコストと、それによって呼び出し元の作業がどれだけ減るかを比較検討します。

エラーと空の結果をモデル化する

• 要求された操作に失敗した場合は WP_Error を返します。呼び出し元がプログラムで失敗を処理できるように、エラーコードとデータの形式を安定させます。呼び出し元が対応できるエラーコードを文書化します。MCP クライアントが受け取るのはメッセージのみで、コードやデータは受け取れないため、各メッセージには何が問題だったのか、呼び出し元が次に何をできるのかを記述します。
• 想定される空の結果は、成功した呼び出しとして扱います。一致するものがないクエリには、通常のコレクション形式で、項目が空の配列を返します。宣言された型に一致する空の値を選び、その意味を説明します。
• 空の結果を返す前に、データソースのエラーを確認します。必須のデータベースクエリ、リモートリクエスト、その他の読み取りが失敗した場合は WP_Error を返します。呼び出し元が空のコレクションをレコード作成の理由とみなし、読み取りの失敗によって重複が発生する可能性があります。
• 書き込みが途中で失敗した場合は、何が変更され、何を確認できなかったかを説明します。呼び出し元が再試行する前に結果を確認できるよう、その情報をエラーメッセージに含めます。変更がなかったと確証できる場合に限り、何も変更されなかったと伝えます。
• 主要な操作は成功しても結果が不完全になる可能性がある場合は、出力スキーマで結果と並べて errors 配列を定義します。各エントリーには安定したコードとメッセージを含め、必要に応じて影響を受けたフィールドのパスや復旧用データを指定します。たとえば、機能から保存済みの注文と、在庫数を取得できなかったことを示す errors エントリーを返すことができます。完全に成功した場合は、空の errors 配列を返します。

CRUD 機能の一貫性を保つ

関連する機能がまとまって並ぶよう、名前空間内では {object}-{action} を優先します。コレクションと単一レコードの検索には、それぞれ query と get の機能を分けて使います。対応する書き込みには create、update、delete を使います。

• ファミリー内で共有するフィールドは、create と update の書き込み可能なフィールドも含めて、名前、型、意味、ネスト構造を統一します。たとえば、post-query と post-get のどちらも生コンテンツを公開する場合は、両方の結果で content.raw を使います。

• リスト機能のフィルターは、where などの入力オブジェクトにまとめます。呼び出し元が、すべての条件に一致する必要があるのか、いずれかに一致すればよいのか、別のルールが適用されるのかを理解できるよう、フィルターの組み合わせ方法を説明します。

• 通常の編集には、部分更新を優先します。対象を必須にし、呼び出し元が変更したいフィールドを受け付けます。たとえば、タイトルの編集では投稿 ID と新しいタイトルを送信できます。呼び出し元は、古くなっている可能性のある本文のコピーを送り返さずに編集できます。

  指定されたフィールドだけを適用し、値のクリアに対応する場合はその方法を定義します。ネストされた値については、指定されたフィールドで個々のメンバーを編集するのか、値全体を置き換えるのかを明記します。置き換えを意図する場合は、値全体を必須にします。

アノテーションで副作用を記述する

各アビリティの meta.annotations に readonly、destructive、idempotent を設定します。呼び出すフックやサービスの影響も含め、実行時に何が起こるかに基づいて値を決めます。

• readonly: true は、実行しても環境に変更がないことを意味します。
• destructive: true は、実行によって既存の状態が削除または上書きされる可能性があることを意味します。書き込みが追加のみの場合は、destructive: false を使用します。
• idempotent: true は、同じ入力で呼び出しを繰り返しても追加の影響がないことを意味します。たとえば、タイトルがすでに一致していても毎回通知を送るタイトル更新は、追加の影響があります。

これらの主張を実装と照らし合わせて確認する方法については、wp-abilities-verify を参照してください。

実行時に権限を適用する

呼び出し元がアビリティを実行せずに利用できる事前チェックには、権限コールバックを使用します。実行時には、保護されたデータを読み取ったり変更したりする前に認可を適用します。両方の経路で同じ内容を確認する場合は、認可ルールを共通化します。

一部のチェックは、アビリティが実行時に見つける内容に依存します。たとえば、クエリの事前チェックでは、呼び出し元がコレクションを要求できるかどうかを確認できます。実行時には、一致するレコードとフィールドのうち、呼び出し元が参照できるものを確認してから返します。

REST と MCP は、権限エラーメッセージを呼び出し元に公開する場合があります。メッセージや返されるエラーの詳細に、保護されたデータを含めないでください。レコードの存在自体が機密情報である場合は、レコードが存在しない場合とアクセスできない場合で同じ応答を返します。

検証

• 代表的なリクエスト、不正な入力、該当する場合はアクセス拒否を使って、通常の呼び出し経路を試します。返される形式がスキーマと一致するか確認します。
• クエリでは、一致がゼロ件、1 件、複数件の場合を確認します。部分更新では、単一フィールドの変更を試し、応答と保存された値の両方を確認します。値の省略と明示的なクリアがどう動作するかを検証します。
• 公開済みのアビリティを変更する場合は、既存の契約に依存する代表的な呼び出しを確認します。レビューでは、各指摘を呼び出し元から見える影響と具体的な修正に結び付けます。

失敗パターン／デバッグ

• 部分更新によって余分なフィールドが変更されます。実装がデフォルト値を補完したり、ネストされた値を置き換えたりする箇所を追跡し、その動作を意図した編集内容と比較します。
• クライアントが、WordPress では受け入れられるスキーマを拒否します。そのクライアント経由で失敗を再現し、該当するスキーマキーワードや結果の形式をサポートしているか確認します。

エスカレーション

公開済みのアビリティに互換性のない変更が必要な場合は、どの呼び出しが動作しなくなるかを特定し、移行に関する判断を明示します。