API規範約定
阿新 • • 發佈：2019-11-29
為了高效開發，節約編寫文件的成本，API服務使用Swagger來描述
2.3 API臃腫
2.4 返回值規範
一、API設計原則
- 控制API的粒度和數量
- 命名要遵循簡單、可讀、統一原則；
- 優先設計API，然後編碼
二、URL設計【針對後端開發】
2.1 HTTP規範
動詞目前暫時以下面兩種 HTTP 方法，對應 CRUD 操作。
GET：讀取（Read） POST：新建（Create,Update,Delete） PUT：更新（Update） PATCH：更新（Update），通常是部分更新 DELETE：刪除（Delete）
2.2 命名規範
- 簡潔
- 可讀
- 禁止返回無效的欄位，給前端人員增加聯調的溝通成本的同時暴露底層資訊。如下圖所示：
三、HTTP狀態碼
3.1 常用狀態碼
2xx：操作成功 4xx：客戶端錯誤 5xx：伺服器錯誤
完整狀態碼參看
2xx 狀態碼 200請求(或處理)成功 201請求(或處理)失敗 4xx 狀態碼 400 Bad Request：請求引數不完整或不正確。 401 Unauthorized：未授權標識。 403 Forbidden：使用者通過了身份驗證，但是不具有訪問資源所需的許可權。 404 Not Found：所請求的資源不存在，或不可用。 405 Method Not Allowed：使用者已經通過身份驗證，但是所用的 HTTP 方法不在他的許可權之內。 410 Gone：所請求的資源已從這個地址轉移，不再可用。 415 Unsupported Media Type：客戶端要求的返回格式不支援。比如，API 只能返回 JSON 格式，但是客戶端要求返回 XML 格式。 422 Unprocessable Entity ：客戶端上傳的附件無法處理，導致請求失敗。 429 Too Many Requests：客戶端的請求次數超過限額。 5xx 狀態碼 一般來說，API 不會向用戶透露伺服器的詳細資訊，所以只要兩個狀態碼就夠了。 500 Internal Server Error：客戶端請求有效，伺服器處理時發生了意外。 503 Service Unavailable：伺服器無法處理請求，一般用於網站維護狀態。
四、API返回格式規範
4.1API 的請求格式
http://{域名}/v1/{模組}/{動作}
域名：https://localhost:5011 或者 http://localhost:5010 或者 https://api.stonecontact.com
模組: controller名稱，比如user。
動作: 每個模組所實現的功能.。比如: add，delete 等.
前端元件具體格式以餓了麼官網的元件為規範，
文件描述詳見Swagger
伺服器返回狀態碼以.NET Core的HttpStatusCode物件為主，不夠的可以進行擴充套件
4.2API 返回格式
響應一級目錄包含三個欄位如下所示：code，message，data{
"code": 200,
"message": "",
"data":
}
4.2.1 伺服器異常格式
{
"code": 500,
"message": "內部請求出錯！",
"data": 0
}
4.2.2 驗證返回錯誤格式
{
"code": 400,
"message": "Validation errors",
"data": [
"'Color Name' 不能為空。",
"ColorName is mandatory.(Length:0-50)",
"'Color Name_ CN' 不能為空。"
]
}
4.2.3 列表格式
{
"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
}
}
4.2.4 許可權格式
{
"code": 401,
}
4.2.5 返回單個物件
{
"code": 200,
"message": "Operation success.",
"data": {
"colorID": 4,
"colorName": "Brown",
"pri": 0,
"updateTimeTag": "2019-07-11T01:06:20.0629948Z",
"colorName_CN": "棕色"
}
}
4.2.6 樹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
}
]
}
]
}
4.2.7 返回DropDownList格式
"code":200,
"msg":"成功",
"data":[
{
"text":"China",
"value":"0"
},
{
"text":"America",
"value":"1"
},
{
"text":"Canada",
"value":"3"
}
],
5.3API 返回碼
API 返回碼如下:5.4內部服務呼叫介面
//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);
}
&n