ホームページ  >  記事  >  バックエンド開発  >  インターフェース設計書を共有する際の12の注意点

インターフェース設計書を共有する際の12の注意点

藏色散人
藏色散人転載
2023-04-24 10:58:332473ブラウズ

はじめに

私たちはバックエンド開発を行っており、インターフェイス ドキュメントを定義する必要がよくあります

最近 インターフェイス ドキュメントのレビュー を行っていたとき、小規模パートナーによって定義された パラメータが列挙値 であることがわかりましたが、インターフェイス ドキュメントには 対応する特定の列挙値 。実際、インターフェイスドキュメントをうまく書く方法は非常に重要です。今日は、Tianluo 兄弟がインターフェイス設計ドキュメントに関する 12 の注意点をお届けします~

インターフェース設計書を共有する際の12の注意点

  • ##パブリック アカウント : カタツムリを拾う少年 (カタツムリに関する丁寧なオリジナルのインタビュー PDF があります)
  • github アドレス、すべてのスターに感謝します:
  • github
1. インターフェース名は明確ですか?

言い換えれば、あなたのインターフェースは何をするもので、理解しやすく明確ですか?一般的なインターフェイス

urlでは、インターフェイスの機能が見える必要もあります。たとえば、ユーザー情報のクエリ (queryUserInfo) は、適切なインターフェイス名 です。

インターフェース設計書を共有する際の12の注意点

2. インターフェイス アドレスは完了していますか?

インターフェイスのアドレスは、インターフェイスの

URL アドレスとも呼ばれます。つまり、他の人があなたのインターフェースを呼び出すときに URL が使用されるということです。たとえば、/api/user/queryUserInfoインターフェイス アドレス です。ただし、ここで言いたいのは、これは完全なインターフェイス アドレスではないということです。インターフェイスは HTTP という名前ですか?

HTTP が呼び出された場合、ドメイン名 は何ですか? ###ポート###。適切な http インターフェイス アドレスは次のようになります:

https//tianluo.com:15000/api/user/queryUserInfo

3. インターフェイスのリクエスト メソッドは正しいですか? インターフェース設計書を共有する際の12の注意点

インターフェイスのリクエスト メソッドには通常、次のものが含まれます:

GET: リソースを取得するためサーバーから、

URL
    でパラメータを渡すことができます。これは通常、データのクエリに使用されます。
  • POST: データをサーバーに送信します。通常、追加、変更、削除などの操作に使用されます。
  • PUT: リソースをサーバーに更新します。通常はデータの更新に使用されます。
  • DELETE: サーバーからリソースを削除します。通常はデータの削除に使用されます。
  • PATCH: サーバーのリソースを部分的に更新します。通常は一部のデータを変更するために使用されます。
  • HEAD:
  • GET
  • リクエストと似ていますが、エンティティのコンテンツではなく応答ヘッダーのみを返します。通常、リソースのメタ情報を取得するために使用されます。
  • オプション: サポートされているリクエスト メソッドとその他の情報を返すようにサーバーに要求します。通常、クライアントとサーバーがリクエスト メソッドをネゴシエートするために使用されます。
  • インターフェイス ドキュメントを定義するときは、インターフェイスのリクエスト メソッドがどれであるかを明確に記述する必要があります。通常の状況では、
  • POST と GET
をより頻繁に使用します。すべてのインターフェイスに

POST を使用する企業もあります。

#4. リクエスト パラメータの 8 つの主要要素

インターフェース設計書を共有する際の12の注意点インターフェースを定義するとき、リクエスト パラメータは

最も重要な部分の 1 つです

。修飾されたインターフェイス ドキュメントの場合、リクエスト パラメーターには次の 8 つの要素が含まれている必要があります。

パラメーター名: パラメーターの名前は、userId

のようにキャメル ケースで付けられます。
  • Type: String、Integer などのパラメータのタイプ。
  • Required: リクエスト パラメータが必須かどうか。必要な場合、アップストリームがこのパラメータを渡さない場合、パラメータ検証例外がスローされる必要があります。 デフォルト値: このパラメータが渡されない場合、デフォルト値はありますか、またデフォルト値は何ですか。
  • 値の範囲:
  • Long、Integer
  • などの数値型の場合は、列挙型の場合は
  • 1~10
  • などの範囲値になります。 value、これは、ACTIVE、INACTIVE などの列挙範囲です。 パラメータ形式: たとえば、パラメータが日付の場合は、yyyyMMdd
  • などのパラメータ形式を指定する必要があります。入力パラメータの値の例: 例を提供します。応答パラメーターの値。これにより、開発者はこのパラメーターをよりよく理解し、使用できるようになります。 備考: この入力パラメータ フィールドに
  • 特別な指示
  • がある場合は、この列で説明できます。特に説明がなければ、このパラメータの機能を説明するだけで大​​丈夫です。
  • 以下はパラメータを入力するためのサンプルドキュメントです
  • :
#パラメータ名タイプ必須かどうかデフォルト値値の範囲パラメータ形式入力パラメータ値例備考(説明)userId Long は #0L0~99999999Lなし666LUserIdbirthDay文字列は1990010119900101~20231231yyyyMMdd 19940107ユーザーの誕生日

インターフェース設計書を共有する際の12の注意点##5. 応答パラメータの 7 つの主要要件

応答パラメータは実際には次のとおりです。入力パラメータと同様に、7 つの要素があります:

パラメータ名: 応答パラメータの名前を記述します。
  • パラメータ タイプ:
  • String、Integer
  • などの応答パラメータのデータ タイプを記述します。 パラメータ形式:
  • yyyy-MM-dd、HH:mm:ss
  • などの応答パラメータのデータ形式を記述します。 パラメータの説明: 応答パラメータの意味の詳細な説明。
  • 値の範囲:
  • 整数範囲、文字列長
  • などの応答パラメータの値の範囲を説明します。 Required: 応答パラメータが必須かどうかを説明します。
  • サンプル値: 開発者がこのパラメーターをよりよく理解して使用できるように、この応答パラメーターのサンプル値を提供します。
  • 違いは、応答パラメーターが通常
code, msg, data

: <pre class="brush:php;toolbar:false">{ &quot;code&quot;: 0, &quot;message&quot;: &quot;success&quot;, &quot;data&quot;: { &quot;name&quot;: &quot;Tom&quot;, &quot;age&quot;: 20, &quot;gender&quot;: &quot;男&quot; } }</pre>6 の形式で返されることです。インターフェイス エラー コード

優れたインターフェイスドキュメントには、エラーコードの列挙が含まれている必要があります。一般的なエラー コード定義には 3 つの列が含まれます:

エラー コード、エラー コード情報、意味

##エラー コードエラー情報意味##1001パラメータエラーユーザーは存在しません1003データベース エラーデータベース アクセス エラー

インターフェース設計書を共有する際の12の注意点

7.接口安全

定义接口文档时,对于一些需要保护的接口,也需要考虑接口的安全,例如权限管理、防止 SQL 注入等。

因此,接口文档应当包含接口的安全性说明:例如接口的访问授权方式、数据传输加密方式等。此外,接口文档还应该对于敏感数据和操作进行标注,方便使用者注意隐私和安全问题

インターフェース設計書を共有する際の12の注意点

8. 接口版本管理

在接口文档定义时,接口版本管理是非常重要的一个方面。由于软件项目的迭代和升级,接口可能会随着版本的变化而发生变化。为了避免接口变化给用户带来不必要的困扰,需要对接口进行版本管理。

以下是一些常用的接口版本管理方法:

  • 在接口文档中明确版本号:在接口文档中明确标识接口的版本号,例如在接口地址中添加版本号信息,如https://example.com/api/v1/user,表示该接口的版本号为v1
  • 使用语义化版本号:采用语义化版本号(Semantic Versioning)规范,即版本号格式为X.Y.Z,其中X表示主版本号、Y表示次版本号、Z表示修订号。当进行兼容性变更时,需升级主版本号;当增加功能且不影响现有功能时,需升级次版本号;当进行bug修复或小功能改进时,需升级修订号。
  • 增量发布:在接口发生变化时,先发布新版本的接口,同时保留旧版本的接口。用户可以根据自己的需求来选择使用哪个版本的接口。随着新版本的接口逐步替换旧版本的接口,最终可以将旧版本的接口废弃。

无论采用何种方法,接口版本管理都应该得到充分的考虑。在接口版本变化时,需要及时更新接口文档(详细描述版本的变化、兼容性问题、版本切换方式等),以确保用户能够获得最新的接口信息。

9. 维护接口文档更新迭代

如果接口发生了变更,比如参数有哪些变更,错误码变更等等,都需要维护到文档上。同时需要登记变更的记录

不正なリクエストパラメータ 1002
指定されたユーザー ID に基づいて、対応するユーザー情報が見つかりませんでした
日期 变更描述 操作人
2023-04-16 创建接口文档,定义了第一版接口文档 捡田螺的小男孩
2023-04-18 修改接口文档,增加了错误码,出参等 田螺哥

インターフェース設計書を共有する際の12の注意点

10.明确请求头有哪些

接口文档,是需要写清楚的请求头的。接口文档的请求头可以看到以下的信息:

  • Content-Type:指定请求体的数据格式,如application/json、application/x-www-form-urlencoded、multipart/form-data等。
  • Authorization:用于身份验证的令牌信息,如Token、Bearer等。
  • Accept:指定客户端可以接受的响应数据格式,如application/json、text/html等。
  • User-Agent:指定客户端的类型和版本信息,可以用于服务端进行针对性优化。
  • Accept-Encoding:指定客户端可以接受的数据压缩格式,如gzip、deflate等。
  • Cache-Control:指定客户端缓存的策略,如no-cache、max-age等。
  • Cookie:包含客户端发送给服务器的cookie信息。

这是是一个接口文档的请求头的示例:

POST /api/user HTTP/1.1
Host: example.com
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
Accept: application/json
User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/96.0.4664.110 Safari/537.36
Accept-Encoding: gzip, deflate, br
Cache-Control: no-cache
Cookie: _ga=GA1.2.1234567890.1234567890; _gid=GA1.2.0987654321.0987654321
If-None-Match: W/"2a-3TjT7VaqgkT1nJdKjX9Cpijp2FA"
Referer: https://example.com/login
Origin: https://example.com
Content-Length: 43

{"name": "John Doe", "age": 25, "email": "john.doe@example.com"}

11 接口请求示例

接口文档,需要提供接口的使用案例:以方便开发者理解接口的使用方法和调用流程

12. 接口测试

一般来说,接口文档需要完善:接口测试的方法和测试结果,以便用户可以测试接口是否符合自己的需求,让用户用得放心~哈哈

以上がインターフェース設計書を共有する際の12の注意点の詳細内容です。詳細については、PHP 中国語 Web サイトの他の関連記事を参照してください。

声明:
この記事はjuejin.imで複製されています。侵害がある場合は、admin@php.cn までご連絡ください。