为了高效开发,节约编写文档的成本,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 的请求格式
1
2
3
4
5
6
7
8
|
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
1
2
3
4
5
|
{
"code"
: 200,
"message"
:
""
,
"data"
:
}
|
4.2.1 服务器异常格式
1
2
3
4
5
|
{
"code"
: 500,
"message"
:
"内部请求出错!"
,
"data"
: 0
}
|
4.2.2 验证返回错误格式
1
2
3
4
5
6
7
8
9
|
{
"code"
: 400,
"message"
:
"Validation errors"
,
"data"
: [
"'Color Name' 不能为空。"
,
"ColorName is mandatory.(Length:0-50)"
,
"'Color Name_ CN' 不能为空。"
]
}
|
4.2.3 列表格式
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
|
{
"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 权限格式
1
2
3
|
{
"code"
: 401,
}
|
4.2.5 返回单个对象
1
2
3
4
5
6
7
8
9
10
11
|
{
"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格式
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
|
{
"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格式
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
|
"code"
:200,
"msg"
:
"成功"
,
"data"
:[
{
"text"
:
"China"
,
"value"
:
"0"
},
{
"text"
:
"America"
,
"value"
:
"1"
},
{
"text"
:
"Canada"
,
"value"
:
"3"
}
],
|
5.3API 返回码
API 返回码如下:
5.4内部服务调用接口
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
|
//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);
}
|