1.背景

より大きなシステムは複数の異なるモジュールで構成される必要があり、各モジュールのバックグラウンドサービスは通常、異なる開発者によって開発および保守されます。さまざまなモジュールによって提供されるインターフェイスの命名スタイル、プロトコル構造、およびエラーコードに一貫性がないため、ユーザー (クライアントなど) にとって不必要な理解と使用コストが増加します。

バックエンドインターフェースは一般的にREST APIの形で外部サービスを提供しますが、インターフェースの保守性やユーザーエクスペリエンスを向上させるためには、企業やチームで外部インターフェースの統一仕様を策定する必要があります。さらに、標準化されたインターフェイス設計により、ソフトウェアの拡張性と保守性が向上し、コードの冗長性と開発時間が短縮されます。

2.インターフェース設計

URLの設計

HTTP メソッドを使用してリソースを操作します。

CRUD 機能を提供するには、5 つの HTTP メソッド POST、GET、PUT/PATCH、および DELETE を使用します。PUT はリソース全体を更新し、PATCH はリソース情報の一部を更新します。

コレクションを表現するには複数の名詞を使用します。

URL で表されるリソースがコレクションの場合は、名詞を使用する必要があります。

たとえば、フォーラムに多数の投稿がある場合、投稿の URL は https://mysite.com/post ではなく https://mysite.com/posts にする必要があります。

バージョン分けを明確にします。

API のバージョンを分割するには、URL パスにバージョン識別子を追加するのが一般的な方法です。

/v1/employees
/v2/employees

プロトコル

データの送受信の形式として JSON を使用します。
統一されたリターンパケット形式を使用して、実際のデータをデータフィールドにラップします。

{
    
    
  "code": 0,
  "msg": "ok",
  "data":{
    
    }
}

ページングインターフェイスの返信パケットのデータ構造にはレコードの総数が含まれており、その構造は次のとおりです。

"data": {
    
    
  "data":[],
  "total":100
}

命名スタイル

JSON キーの命名にはキャメルケーススタイルが使用されます。

{
    
    
  "thisPropertyIsAnIdentifier": "identifier value"
}

URL パスではハイフンを使用して単語を区切りますが、クエリではアンダースコアを使用して単語を区切ります。

GET https://api.example.com/favorite-teachers?first_name=john&last_name=doe

書類

インターフェイスの Swagger ドキュメントを提供し、明確なプロトコルフィールドの説明を含めます。

3. 一般的なエラーコード

ビジネスエラーコード 1 の先頭の 1XXXX は一般的なエラーコードであり、その他のエラーコードについては、さまざまなモジュールサービスが独自に呼び出し元と一致します。

以下に、一般的なエラーコードをいくつか示します。

10000	入参有误
10001	Token 非法
10002	请求超时
10003	记录未找到
10004	DB 写入失败
10005	DB 更新失败
10006	DB 查询失败
10007	DB 删除失败
10008	JSON 序列化失败
10009	JSON 反序列化失败

4. まとめ

この記事が気に入ったら、WeChat 公開アカウント「Love Meow Big Carp」をフォローして、最新のエキサイティングなコンテンツをご覧ください。

参考文献

Google JSON スタイルガイド
 REST API ベストプラクティス_Lianmiao Big Carp のブログ

シンプルで実現可能なREST API仕様

記事ディレクトリ