其他
API规范约定
本文来源:
https://www.cnblogs.com/jackyfei/p/11933756.html
为了高效开发,节约编写文档的成本,API服务使用Swagger来描述
一、API设计原则
控制API的粒度和数量
命名要遵循简单、可读、统一原则;
优先设计API,然后编码
二、URL设计【针对后端开发】
2.1 HTTP规范
动词目前暂时以下面两种 HTTP 方法,对应 CRUD 操作。
1GET:读取(Read)
2POST:新建(Create,Update,Delete)
3PUT:更新(Update)
4PATCH:更新(Update),通常是部分更新
5DELETE:删除(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 常用状态码
12xx:操作成功
24xx:客户端错误
35xx:服务器错误
完整状态码参看
12xx 状态码
2200请求(或处理)成功
3201请求(或处理)失败
4
54xx 状态码
6400 Bad Request:请求参数不完整或不正确。
7401 Unauthorized:未授权标识。
8403 Forbidden:用户通过了身份验证,但是不具有访问资源所需的权限。
9404 Not Found:所请求的资源不存在,或不可用。
10405 Method Not Allowed:用户已经通过身份验证,但是所用的 HTTP 方法不在他的权限之内。
11410 Gone:所请求的资源已从这个地址转移,不再可用。
12415 Unsupported Media Type:客户端要求的返回格式不支持。比如,API 只能返回 JSON 格式,但是客户端要求返回 XML 格式。
13422 Unprocessable Entity :客户端上传的附件无法处理,导致请求失败。
14429 Too Many Requests:客户端的请求次数超过限额。
15
165xx 状态码
17一般来说,API 不会向用户透露服务器的详细信息,所以只要两个状态码就够了。
18500 Internal Server Error:客户端请求有效,服务器处理时发生了意外。
19503 Service Unavailable:服务器无法处理请求,一般用于网站维护状态。
四、API返回格式规范
4.1API 的请求格式
1http://{域名}/v1/{模块}/{动作}
2域名:https://localhost:5011 或者 http://localhost:5010 或者 https://api.stonecontact.com
3模块: controller名称,比如user。
4动作: 每个模块所实现的功能.。比如: add,delete 等.
5
6前端组件具体格式以饿了么官网的组件为规范,
7文档描述详见Swagger
8服务器返回状态码以HttpStatusCode对象为主,不够的可以进行扩展
4.2API 返回格式
响应一级目录包含三个字段如下所示:code,message,data
1{
2 "code": 200,
3 "message": "",
4 "data":
5}
4.2.1 服务器异常格式
1{
2 "code": 500,
3 "message": "内部请求出错!",
4 "data": 0
5}
4.2.2 验证返回错误格式
1{
2 "code": 400,
3 "message": "Validation errors",
4 "data": [
5 "'Color Name' 不能为空。",
6 "ColorName is mandatory.(Length:0-50)",
7 "'Color Name_ CN' 不能为空。"
8 ]
9}
4.2.3 列表格式
1{
2 "code": 200,
3 "message": "Operation success.",
4 "data": {
5 "grid": [
6 {
7 "colorID": 5,
8 "colorName": "White",
9 "pri": 0,
10 "updateTimeTag": "2019-07-11T01:11:12.8490797Z",
11 "colorName_CN": "白色"
12 },
13 {
14 "colorID": 6,
15 "colorName": "Red",
16 "pri": 0,
17 "updateTimeTag": "2019-07-11T01:11:12.8496838Z",
18 "colorName_CN": "红色"
19 },
20 {
21 "colorID": 7,
22 "colorName": "Multicolor",
23 "pri": 0,
24 "updateTimeTag": "2019-07-11T01:11:12.8496915Z",
25 "colorName_CN": "混合"
26 }
27 ],
28 "recordCount": 19
29 }
30}
4.2.4 权限格式
1{
2 "code": 401,
3}
4.2.5 返回单个对象
1{
2 "code": 200,
3 "message": "Operation success.",
4 "data": {
5 "colorID": 4,
6 "colorName": "Brown",
7 "pri": 0,
8 "updateTimeTag": "2019-07-11T01:06:20.0629948Z",
9 "colorName_CN": "棕色"
10 }
11}
4.2.6 树Tree格式
1{
2 "code": 200,
3 "message": "Operation success.",
4 "data": [
5 {
6 "id": 365,
7 "text": "Stone Blocks",
8 "pid": 0,
9 "expanded": true,
10 "leaf": true,
11 "children": [
12 {
13 "id": 366,
14 "text": "Marble Blocks",
15 "pid": 365,
16 "expanded": true,
17 "leaf": false,
18 "children": null
19 },
20 {
21 "id": 367,
22 "text": "Granite Blocks",
23 "pid": 365,
24 "expanded": true,
25 "leaf": false,
26 "children": null
27 }
28 ]
29 },
30 {
31 "id": 172,
32 "text": "Stone Tiles & Slabs",
33 "pid": 0,
34 "expanded": true,
35 "leaf": true,
36 "children": [
37 {
38 "id": 173,
39 "text": "Alabaster Tiles & Slabs",
40 "pid": 172,
41 "expanded": true,
42 "leaf": false,
43 "children": null
44 },
45 {
46 "id": 174,
47 "text": "BlueStone Tiles & Slabs",
48 "pid": 172,
49 "expanded": true,
50 "leaf": false,
51 "children": null
52 }
53 ]
54 }
55 ]
56}
4.2.7 返回DropDownList格式
1"code":200,
2 "msg":"成功",
3 "data":[
4 {
5 "text":"China",
6 "value":"0"
7 },
8 {
9 "text":"America",
10 "value":"1"
11 },
12 {
13 "text":"Canada",
14 "value":"3"
15 }
16 ],
5.3API 返回码
API 返回码如下:
API 返回码 | 含义 |
---|---|
200 | 请求成功 |
40000 | 验证错误 |
500 | 服务器端错误 |
400 | 资源找不到 |
5.4内部服务调用接口
1//1.get调用方法
2//1.1带参数
3//Map<String, Object> param = new HashMap<>();
4//param.add("PageSize", 20);
5//param.add("PageIndex", 5);
6//var client = RestSharpHelper.getClient("url");
7//var data = client.sendRequest(RestSharp.Method.GET, param);
8
9//1.2不带参数
10var client = RestSharpHelper.getClient("http://localhost:5010/api/v1/sysColor/list");
11var response = client.sendRequest(Method.GET);
12if (response.StatusCode == HttpStatusCode.OK) {
13 var result = JSON.parseObject(response.data.data,ColorResult.class);
14}
15
16//2.post调用方法
17var client2 = RestSharpHelper.getClient("http://localhost:5010/api/v1/sysColor/list");
18var response2 = client2.sendRequest(Method.POST, JSON.toJsonString(new PostModel() { }));
19
20if (response2.StatusCode == HttpStatusCode.OK) {
21 var result2 = JSON.parseObject(response2.data.data,ColorResult.class);
22}
● 线程同步手记
● 微服务学习导航
● 微服务划分的姿势