其他

API规范约定

为了高效开发,节约编写文档的成本,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);
}