API规范约定，让你写出高质量的API！

雨点打透心脏的1/2处 2023-06-30 08:52 6阅读 0赞

## 摘要 ##

**API的设计原则：**

*  控制API的粒度和数量
 *  命名要遵循简单、可读、统一原则；
 *  优先设计API，然后编码

**多说一句：** 在现在流行的微服务、敏捷开发等这些项目一般为了更高效的开发，节约编写文档的成本，API服务都会使用Swagger来生成描述。

--------------------

### URL设计【针对后端开发】 ###

#### HTTP规范 ####

**动词目前暂时以下面两种 HTTP 方法，对应 CRUD 操作。**

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

#### 命名规范 ####

*  简洁

<table> 
 <thead> 
  <tr> 
   <th>简洁</th> 
   <th>繁琐</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>captcha</td> 
   <td>get-captcha-image</td> 
  </tr> 
  <tr> 
   <td>info</td> 
   <td>getUserInfo</td> 
  </tr> 
  <tr> 
   <td>cars</td> 
   <td>getAllCars</td> 
  </tr> 
 </tbody> 
</table>

*  可读

<table> 
 <thead> 
  <tr> 
   <th>可读好</th> 
   <th>可读性差</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>delete</td> 
   <td>delete-sysuser</td> 
  </tr> 
  <tr> 
   <td>add</td> 
   <td>addDetIstr</td> 
  </tr> 
  <tr> 
   <td>update</td> 
   <td>updateDetIstr</td> 
  </tr> 
  <tr> 
   <td>get</td> 
   <td>appGetByNO</td> 
  </tr> 
 </tbody> 
</table>

#### API臃肿 ####

**接口数量控制**

> 反对不经过设计的API，导致API接口失控，接口过多，影响前端调试。  
>   
> 能合并的接口，尽量合并，不要写重复的接口  
>   
> 一个类的接口不要超过6个,如下图所示：![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L01yc19jaGVucw_size_16_color_FFFFFF_t_70]

#### 返回值规范 ####

*  禁止返回无效的字段，给前端人员增加联调的沟通成本的同时暴露底层信息。如下图所示：  
    ![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L01yc19jaGVucw_size_16_color_FFFFFF_t_70 1]

#### API接口注释规范 ####

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L01yc19jaGVucw_size_16_color_FFFFFF_t_70 2]

--------------------

### HTTP状态码 ###

##### 常用状态码 #####

2xx：操作成功
    4xx：客户端错误
    5xx：服务器错误

**完整状态码，传送门：[HTTP系列：HTTP状态码][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 返回码

<table> 
 <thead> 
  <tr> 
   <th>API 返回码</th> 
   <th>含义</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>200</td> 
   <td>请求成功</td> 
  </tr> 
  <tr> 
   <td>40000</td> 
   <td>验证错误</td> 
  </tr> 
  <tr> 
   <td>500</td> 
   <td>服务器端错误</td> 
  </tr> 
  <tr> 
   <td>400</td> 
   <td>资源找不到</td> 
  </tr> 
 </tbody> 
</table>

*  内部服务调用接口

//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);
    }

--------------------

## 最后 ##

*  **更多参考精彩博文请看这里：[《陈永佳的博客》][Link 1]**
 *  **喜欢博主的小伙伴可以加个关注、点个赞哦，持续更新嘿嘿！**

[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L01yc19jaGVucw_size_16_color_FFFFFF_t_70]: https://img-blog.csdnimg.cn/20200116105710324.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L01yc19jaGVucw==,size_16,color_FFFFFF,t_70
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L01yc19jaGVucw_size_16_color_FFFFFF_t_70 1]: https://img-blog.csdnimg.cn/20200116105733925.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L01yc19jaGVucw==,size_16,color_FFFFFF,t_70
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L01yc19jaGVucw_size_16_color_FFFFFF_t_70 2]: https://img-blog.csdnimg.cn/20200116105753536.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L01yc19jaGVucw==,size_16,color_FFFFFF,t_70
[HTTP_HTTP]: https://blog.csdn.net/Mrs_chens/article/details/101379442
[Link 1]: https://blog.csdn.net/Mrs_chens