背景

在團隊兩年多陸續負責了幾個專案的開發上線已經程式碼的review，特別是對老專案的重構過程中，發現之前的API設計是沒有任何規範和約定的，不同的開發同學有不同的習慣，因此需要一套規範去約定，現在分享一下我們目前試執行的一套規範，一起交流完善下。

WebAPI開發流程

• 第一步首先設計介面文件，公司內部有一套自研的多人協作文件系統，可以很好的做到這一步，並能很好的做好版本控制。如果公司內部沒有可以基於showdoc搭建一套
• 第二步有技術負責人確認介面以及欄位的命名規範

• 第三步找對應API對接人，確認介面是否符合要求

  這三步其實是個閉環，只有等到全部通過後才會正式開始開發API

命名規範

• 所有介面中不能出現拼音，統一用英語
• 不能有特殊字元，例如/

• 介面命名遵循像個原則: 簡單 易懂

  出入參規範

• 命名規範參考之前的一篇文章
• 若需要使用分割符，只可以使用中劃線 -

• 禁止把所有資料庫欄位全部返回，統一使用Dto,只返回呼叫方需要的欄位

  HTTP 請求方法使用規範

根據 HTTP 標準，HTTP 請求可以使用多種請求方法。
HTTP1.0 定義了三種請求方法： GET, POST 和 HEAD方法。
HTTP1.1 新增了六種請求方法：OPTIONS、PUT、PATCH、DELETE、TRACE 和 CONNECT 方法。
這裡統一隻是用 GET, POST,PUT,DELETE,PATCH

GET（SELECT）： 從伺服器獲取單個資源或者資源列表
POST（CREATE）：傳送請求建立一個新的資源
PUT（UPDATE）：通過介面更新伺服器上的資源資訊，資源內容全量更新，提供資源全部欄位資訊
DELETE（DELETE）：通過刪除伺服器上的資源
PATCH（UPDATE） ：通過介面更新伺服器上的資源資訊，資源內容增量更新，僅提供更新的屬性資訊
具體使用規範，使用GET查詢獲取資訊，POST建立新的資源，PUT修改已存在資源資訊，DELETE刪除伺服器資源資訊，不強制要求使用Patch。

HTTP碼狀態使用規範

• 200 OK ：成功
• 201 CREATED：成功建立資料 不強制使用，可以使用200
• 400 Bad Request：提交的引數錯誤。錯誤資訊中要能體現哪個parameter沒有通過validation，為什麼
• 401 Unauthorized：客戶端傳入了一個無效的auth token。客戶端需要更新token進行重試，包括讓使用者重新登陸
• 403 Forbidden：訪問被拒絕。最常見的case為水平越權。和401的區別是：如果改介面需要使用者登陸，無有效的登陸token，則返回401，表示登陸驗證未通過。登陸驗證通過後，但是因為要操作的資源沒有許可權，則返回403.比如使用者更新或者刪除不屬於自己的resource
• 404 Not Found： 資源為找到
• 429 Too Many Requests：對於限頻介面請求次數超頻
• 500 Internal Server Error：應用伺服器內部錯誤
• 502 Bad Gateway：閘道器或者代理處理請求錯誤
• 503 Service Unavailable：應用伺服器暫時不可用
• 504 Gateway Timeout： 閘道器超時。閘道器從上游服務沒有在設定的時長內獲取到資料。

自定義Header規範，

x-[應用英文縮寫]-[語義化英文單詞說明用途]

示例：
X-Test-Authorization: qwaszxerdfcvtyghbn

返回規範

全部統一使用 Content-Type = application/json 格式返回

請求失敗的Response

• Http碼的狀態為200或者201
• code統一為 200，message 為success
• isSuccess為true
• 有返回值時，統一通過data返回,無返回值時為{}，禁止使用null返回
• 返回的header中追加標記本次請求的唯一值的 X-[專案英文縮寫]-ResponseId

{
  "isSuccess": true,
  "code": 200,
  "message": "success",
  "data": {
    "id": 0,
    "value": "Default"
  },
  "timestamp": "02/02/2020 13:19:22"
}

請求異常的Response

• Http碼的狀態根據上一小節介紹的按需使用
• code和http碼對應，message 為對應異常說明
• isSuccess為false
• data統一返回為{}
• 返回的header中追加標記本次請求的唯一值的 X-[專案英文縮寫]-ResponseId

{
  "isSuccess": false,
  "code": 400,
  "message": "Bad Request",
  "value": {},
  "timestamp": "02/02/2020 13:35:33"
}

介面註釋說明

約定

• 專案統一使用swagger
• 介面相關的文件地址
• 相關jira.$ 分割 XXX-XXX $ XXX-XXX
• 可能的返回的狀態碼
• 對應引數說明

/// <summary>
/// PUT api/values/5
/// </summary>
/// <param name="id">id</param>
/// <param name="dto">dto</param>
/// <remarks>
/// <url>doc: https://www.cnblogs.com/sagecheng/</url> <br/>
/// <br/>
/// <br/>
/// <jira>jira: XXX-XXX</jira>
/// </remarks>
/// <returns></returns>
/// <response code="200"> success </response>
/// <response code="400">If the id is null</response>
/// <response code="404">If the id is not found</response>
[HttpPut("{id}")]
[ProducesResponseType(StatusCodes.Status200OK)]
[ProducesResponseType(StatusCodes.Status400BadRequest)]
[ProducesResponseType(StatusCodes.Status404NotFound)]
public ApiResult Put(int id, [FromBody] ValueDto dto)
{
    var info = values.FirstOrDefault(o => o.Id == id);
    if (info == null)
    {
        throw new ApiException(StatusCodes.Status404NotFound, "Not Found");
    }
    info.Value = dto.Value;
    return ApiResult.GetSuccessResult();
}

Swagger相關效果

整體效果

註釋效果

參考文章

Swashbuckle 和 ASP.NET Core 入