エラーメッセージ

良いエラーメッセージは、ユーザーに次に何をすべきかを伝えます。Playgroundの公開APIによって発生するエラーのあいまいさは、開発者に問題を開くよう促します。

ネットワークエラーを考えてみましょう—エラーの種類を推測し、次のステップを要約した関連メッセージを表示できますか？

  • ネットワークエラー: “インターネット接続が不安定です。ページを再読み込みしてみてください。
  • 404: “ファイルが見つかりませんでした”。
  • 403: “サーバーがファイルへのアクセスをブロックしました”。
  • CORS: これはブラウザのセキュリティ機能であることを明確にし、詳細な説明へのリンクを追加します（MDNまたは他の信頼できるソース）。ユーザーにファイルを他の場所、例えばraw.githubusercontent.comに移動するよう提案し、サーバーでCORSヘッダーを設定する方法を説明するリソースへのリンクを提供します。

私たちはコードのフォーマットとリンティングを自動的に処理します。リラックスして、タイプし続け、機械に作業を任せてください。

公開API

Playgroundは、可能な限り狭いAPIの範囲を維持することを目指しています。

公開APIは追加が簡単ですが、削除が難しいです。新しいAPIを導入するのに1つのPRが必要ですが、削除するには千のPRが必要になることがあります、特に他のプロジェクトがすでにそれを使用している場合は。

  • 不要な関数、クラス、定数、または他のコンポーネントを公開しないでください。

ブループリント

ブループリントは、Playgroundと対話するための主要な方法です。これらのJSONファイルは、Playgroundが順番に実行する一連のステップを記述しています。

ガイドライン

ブループリントのステップは簡潔で焦点を絞ったものであるべきです。1つのことを行い、それをうまく行うべきです。

  • 新しいステップを作成する必要がある場合は、まず既存のものをリファクタリングしてみてください。
  • それが不十分な場合は、新しいステップが新しい機能を提供することを確認してください。既存のステップの機能を複製しないでください。
  • ステップが複数回呼び出されることを想定してください。
  • 特定の順序で実行されることを想定してください。
  • それを確認するためにユニットテストを追加してください。

ブループリントは直感的でわかりやすいものであるべきです。

  • オプションである可能性のある引数を要求しないでください。
  • プレーンな引数を使用してください。例えば、slugの代わりにpathを使用してください。
  • 定数を仮想JSONファイルで定義してください—PHPファイルを変更しないでください。
  • ブループリントのためのTypeScript型を定義してください。これがPlaygroundがそのJSONスキーマを生成する方法です。
  • ブループリントステップを処理する関数を書いてください。定義した型の引数を受け入れてください。
  • ドキュメント文字列に使用例を提供してください。それは自動的にドキュメントに反映されます。