为了高效开发, 节约编写文档的成本, 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 状态码
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 返回码如下:
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);
- }
来源: https://www.cnblogs.com/jackyfei/p/11933756.html