API规范约定

2019-11-28 来源: 张飞洪 发布在  https://www.cnblogs.com/jackyfei/p/11933756.html

  为了高效开发,节约编写文档的成本,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 命名规范

  • 简洁
简洁
繁琐
captcha
get-captcha-image
info
getUserInfo
cars
getAllCars
  • 可读
可读好
可读性差
delete
delete-sysuser
add
addDetIstr
update
updateDetIstr
get
appGetByNO
2.3 API臃肿
接口数量控制
反对不经过设计的API,导致API接口失控,接口过多,影响前端调试。
能合并的接口,尽量合并,不要写重复的接口
一个类的接口不要超过6个,如下图所示:
 
2.4 返回值规范
  • 禁止返回无效的字段,给前端人员增加联调的沟通成本的同时暴露底层信息。如下图所示:
2.5 API接口注释规范

三、HTTP状态码

3.1 常用状态码

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

完整状态码参看

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返回格式规范

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 返回码如下:
API 返回码
含义
200
请求成功
40000
验证错误
500
服务器端错误
400
资源找不到

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

相关文章