為了高效開發，節約編寫文檔的成本，API服務使用Swagger來描述
一、API設計原則
- 控制API的粒度和數量
- 命名要遵循簡單、可讀、統一原則；
- 優先設計API，然后編碼
二、URL設計【針對后端開發】
2.1 HTTP規范
動詞目前暫時以下面兩種 HTTP 方法，對應 CRUD 操作。
GET：讀取（Read）
POST：新建（Create,Update,Delete）
PUT：更新（Update）
PATCH：更新（Update），通常是部分更新
DELETE：刪除（Delete）
2.2 命名規范
- 簡潔
- 可讀
2.3 API臃腫
2.4 返回值規范
- 禁止返回無效的字段，給前端人員增加聯調的溝通成本的同時暴露底層信息。如下圖所示：
2.5 API接口注釋規范
三、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);
}