API規範約定，讓你寫出高質量的API！

摘要

API的設計原則：

• 控制API的粒度和數量
• 命名要遵循簡單、可讀、統一原則；
• 優先設計API，然後編碼

多說一句： 在現在流行的微服務、敏捷開發等這些項目一般爲了更高效的開發，節約編寫文檔的成本，API服務都會使用Swagger來生成描述。

---

URL設計【針對後端開發】

HTTP規範

動詞目前暫時以下面兩種 HTTP 方法，對應 CRUD 操作。

GET：讀取（Read）
POST：新建（Create,Update,Delete）
PUT：更新（Update）
PATCH：更新（Update），通常是部分更新
DELETE：刪除（Delete）

命名規範

• 簡潔

簡潔	繁瑣
captcha	get-captcha-image
info	getUserInfo
cars	getAllCars

• 可讀

可讀好	可讀性差
delete	delete-sysuser
add	addDetIstr
update	updateDetIstr
get	appGetByNO

API臃腫

接口數量控制

反對不經過設計的API，導致API接口失控，接口過多，影響前端調試。

能合併的接口，儘量合併，不要寫重複的接口

一個類的接口不要超過6個,如下圖所示：

返回值規範

• 禁止返回無效的字段，給前端人員增加聯調的溝通成本的同時暴露底層信息。如下圖所示：
  

API接口註釋規範

---

HTTP狀態碼

常用狀態碼

2xx：操作成功
4xx：客戶端錯誤
5xx：服務器錯誤

完整狀態碼，傳送門：HTTP系列：HTTP狀態碼

2xx 狀態碼
200請求(或處理)成功
201請求(或處理)失敗
 
4xx 狀態碼
Bad Request：請求參數不完整或不正確。
Unauthorized：未授權標識。
Forbidden：用戶通過了身份驗證，但是不具有訪問資源所需的權限。
Not Found：所請求的資源不存在，或不可用。
Method Not Allowed：用戶已經通過身份驗證，但是所用的 HTTP 方法不在他的權限之內。
Gone：所請求的資源已從這個地址轉移，不再可用。
Unsupported Media Type：客戶端要求的返回格式不支持。比如，API 只能返回 JSON 格式，但是客戶端要求返回 XML 格式。
Unprocessable Entity ：客戶端上傳的附件無法處理，導致請求失敗。
Too Many Requests：客戶端的請求次數超過限額。
 
5xx 狀態碼
一般來說，API 不會向用戶透露服務器的詳細信息，所以只要兩個狀態碼就夠了。
Internal Server Error：客戶端請求有效，服務器處理時發生了意外。
Service Unavailable：服務器無法處理請求，一般用於網站維護狀態。

---

API返回格式規範

API 的請求格式

http://{域名}/v1/{模塊}/{動作}
域名：https://localhost:5011 或者 http://localhost:5010 或者 https://api.stonecontact.com
模塊: controller名稱，比如user。
動作: 每個模塊所實現的功能.。比如: add，delete 等.
  
前端組件具體格式以餓了麼官網的組件爲規範，
文檔描述詳見Swagger
服務器返回狀態碼以.NET Core的HttpStatusCode對象爲主，不夠的可以進行擴展　

API 返回格式

• 響應一級目錄包含三個字段如下所示：code，message，data

{
 "code": 200,
 "message": "", 
 "data":    
}

• 服務器異常格式

{
 "code": 500,
 "message": "內部請求出錯！",
 "data": 0
}

• 驗證返回錯誤格式

{
    "code": 400,
    "message": "Validation errors",
    "data": [
        "'Color Name' 不能爲空。",
        "ColorName is mandatory.(Length:0-50)",
        "'Color Name_ CN' 不能爲空。"
    ]
}

• 列表格式

{
  "code": 200,
  "message": "Operation success.",
  "data": {
    "grid": [
      {
        "colorID": 5,
        "colorName": "White",
        "pri": 0,
        "updateTimeTag": "2019-07-11T01:11:12.8490797Z",
        "colorName_CN": "白色"
      },
      {
        "colorID": 6,
        "colorName": "Red",
        "pri": 0,
        "updateTimeTag": "2019-07-11T01:11:12.8496838Z",
        "colorName_CN": "紅色"
      },
      {
        "colorID": 7,
        "colorName": "Multicolor",
        "pri": 0,
        "updateTimeTag": "2019-07-11T01:11:12.8496915Z",
        "colorName_CN": "混合"
      }
    ],
    "recordCount": 19
  }
}

• 權限格式

{
 "code": 401,
}

• 返回單個對象

{
    "code": 200,
    "message": "Operation success.",
    "data": {
        "colorID": 4,
        "colorName": "Brown",
        "pri": 0,
        "updateTimeTag": "2019-07-11T01:06:20.0629948Z",
        "colorName_CN": "棕色"
    }
}

• 樹Tree格式

{
  "code": 200,
  "message": "Operation success.",
  "data": [
    {
      "id": 365,
      "text": "Stone Blocks",
      "pid": 0,
      "expanded": true,
      "leaf": true,
      "children": [
        {
          "id": 366,
          "text": "Marble Blocks",
          "pid": 365,
          "expanded": true,
          "leaf": false,
          "children": null
        },
        {
          "id": 367,
          "text": "Granite Blocks",
          "pid": 365,
          "expanded": true,
          "leaf": false,
          "children": null
        }
      ]
    },
    {
      "id": 172,
      "text": "Stone Tiles & Slabs",
      "pid": 0,
      "expanded": true,
      "leaf": true,
      "children": [
        {
          "id": 173,
          "text": "Alabaster Tiles & Slabs",
          "pid": 172,
          "expanded": true,
          "leaf": false,
          "children": null
        },
        {
          "id": 174,
          "text": "BlueStone Tiles & Slabs",
          "pid": 172,
          "expanded": true,
          "leaf": false,
          "children": null
        }
      ]
    }
  ]
}

• 返回DropDownList格式

"code":200,
    "msg":"成功",
    "data":[
        {
            "text":"China",
            "value":"0"
        },
        {
            "text":"America",
            "value":"1"
        },
        {
            "text":"Canada",
            "value":"3"
        }
    ],

• API 返回碼

API 返回碼	含義
200	請求成功
40000	驗證錯誤
500	服務器端錯誤
400	資源找不到

• 內部服務調用接口

//1.Get調用方法
//1.1帶參數
//Dictionary<string, object> param = new Dictionary<string, object>();
//param.Add("PageSize", 20);
//param.Add("PageIndex", 5);
//var client = RestSharpHelper.GetClient("url");
//var data = client.SendRequest(RestSharp.Method.GET, param);
 
//1.2不帶參數
var client = RestSharpHelper.GetClient("http://localhost:5010/api/v1/SysColor/list");
var response = client.SendRequest(Method.GET);
if (response.StatusCode == HttpStatusCode.OK)
{
    var result = JsonConvert.DeserializeObject<ColorResult>(response.Data.Data);
}
 
//2.Post調用方法
var client2 = RestSharpHelper.GetClient("http://localhost:5010/api/v1/SysColor/list");
var response2 = client2.SendRequest(Method.POST, JsonConvert.SerializeObject(new PostModel() { }));
 
if (response2.StatusCode == HttpStatusCode.OK)
{
    var result2 = JsonConvert.DeserializeObject<ColorResult>(response2.Data.Data);
}

---

最後

• 更多參考精彩博文請看這裏：《陳永佳的博客》

• 喜歡博主的小夥伴可以加個關注、點個贊哦，持續更新嘿嘿！