パス型
新しい型を定義する際は、このガイダンスに従ってください。明示的に要求された場合のみ既存コードを変更し、編集は最小限かつ適切な範囲に留めてください。これらのルールは進行中の移行の目標状態として扱い、準拠が難しい場合はユーザーに進め方を尋ねてください。
- アプリサーバーのプロトコル型では、URI 移行中の後方互換性のために
LegacyAppPathStringを使用します。プロトコル境界でPathUriに変換し、内部ではPathUriを使用します。一部の設定値など、ホストローカルなロジックでは、代わりにAbsolutePathBufまたはPathBufを使用します。 - 実行サーバーのプロトコル型では、
PathUriを使用します。内部では、必要に応じてPathUriまたはAbsolutePathBufを使用します。 - 両サーバーで共有される依存関係では、
PathUriまたはユースケースを分離する個別のAPIを使用します。 - モデルが生成することが期待されるツール呼び出し引数は、機能固有のパス処理コードを持つ通常の
Stringとして逆シリアル化する必要があります。
移行要件
コードを上記のガイドラインに準拠させるように移行する際は、以下の要件に留意してください。
- 既存のアプリサーバークライアントは、レガシーなネイティブパス文字列を送受信し続ける
- アプリサーバーは、異種プラットフォームのパスURIを保持および操作できる
- 実行サーバーAPIは file:// URI を使用する
- ローカルのみの操作では、モデルから見えるテキストを変更してはならない
- モデルのツール引数には、任意のOSの生の相対パスまたは絶対パスが含まれる可能性がある
- パスの推論は、関連する環境がオンラインになる前に機能する必要がある
- URI は、実行者のパス規則またはオペレーティングシステムを明示的にエンコードしてはならない
- ユーザーは環境のOS/パス規則を明示的に設定してはならない
- URI は、ロールアウト、データベース、またはその他の永続ストレージにまだ保存すべきではない
- パス変換エラー: セキュリティ関連パスではフェイルクローズ、UI/診断ではフェイルオープン
- ローカルヘルパーよりも、
PathUriまたはLegacyAppPathString上の小さく焦点を絞ったメソッドを優先する - 診断では
PathUri値をURIとして表現する
実際のユーザーにとって正しく動作する限り、パスとURIの間の変換が多少ロッシーであっても問題ありません。
URIへの移行により、新たな重大な障害モードが追加されるべきではありません。以前は失敗しなかった一部の場所でエラーを表面化する必要がありますが、最小限に抑えるべきです。