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 命名规范
- 简洁
简洁 |
繁琐 |
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:服务器错误
![点击并拖拽以移动](https://www.icode9.com/i/l/?n=20&i=blog/603760/202111/603760-20211113215336493-61792338.gif)
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:服务器无法处理请求,一般用于网站维护状态。
![点击并拖拽以移动](https://www.icode9.com/i/l/?n=20&i=blog/603760/202111/603760-20211113215336493-61792338.gif)
四、API返回格式规范
4.1API 的请求格式
1 2 3 4 5 6 7 8 |
|
4.2API 返回格式
响应一级目录包含三个字段如下所示:code,message,data
1 2 3 4 5 |
|
4.2.1 服务器异常格式
1 2 3 4 5 |
|
4.2.2 验证返回错误格式
1 2 3 4 5 6 7 8 9 |
|
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 |
|
4.2.4 权限格式
1 2 3 |
|
4.2.5 返回单个对象
1 2 3 4 5 6 7 8 9 10 11 |
|
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 |
|
4.2.7 返回DropDownList格式
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
|
5.3API 返回码
API 返回码如下:
API 返回码 |
含义 |
200 |
请求成功 |
40000 |
验证错误 |
500 |
服务器端错误 |
400 |
资源找不到 |
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 |
|
标签:code,text,约定,规范,API,var,格式,data 来源: https://www.cnblogs.com/songjuntao/p/15549982.html