一、API

1. 传输协议

采用HTTP JSON通讯协议

2. API版本控制

将API得版本号放入URL，http://api.example.com/v{n}/
v{n} n代表版本号，使用整形得版本号，例如v1, v2

3. 请求方法

对于资源的具体操作类型，由HTTP动词表示。

GET（SELECT）：从服务器取出资源（一项或多项）。
POST（CREATE）：在服务器新建一个资源。
PUT（UPDATE）：在服务器更新资源（客户端提供改变后的完整资源）。
PATCH（UPDATE）：在服务器更新资源（客户端提供改变后的部分资源）
DELETE（DELETE）：从服务器删除资源。

4. 路径规则

API中的名词也应该使用复数, http://api.example.com/v1/orders

GET/orders/{ID}：获取某个指定订单的信息
POST/orders/list：列出订单
POST/orders：新建一个订单
PUT/orders/{ID}：更新某个指定订单的信息
PATCH/orders/status/{ID}：更新某个指定订单的状态
DELETE/products/{ID}：删除某个订单

列出资源一般使用GET方法，然后在URL中携带参数，这里使用POST方法的考虑是POST方法使body携带参数更加好表达一下条件参数，另外使用URL携带有长度限制(某些场景可能需要携带较多的参数)，不必强制符合restful规范，应该结合实际场景处理。

对与类似token这样的参数，可以将参数放置Header进行携带

5. 请求报文示例

列出订单
POST /orders/list

请求体

{"count": 10, "page": 1, "sort": "name", "filter": {"name": "手机"}
}

响应体

{"code": "200010000000", "message": "成功", "data": {"total": 2, "records": [{"id": 1, "name": "水杯", "price": 12.5}, {"id": 2, "name": "手机", "price": 2999}]}
}

新建订单
POST /orders

请求体

{"name": "U盘", "price": 99
}

响应体

{"code": "201010000000", "message": "成功"
}

二、状态码

1. 返回结果

请求的返回值状态均为成功200，具体业务状态编码从返回的数据获取，页面根据自定义状态码做出响应，返回值格式如下

{"code": "200010000000", "message": "认证成功，欢迎登录！", "data": ""
}

2. 状态码定义

自定义状态码，长度12位，其中

1-3位为状态类型，同HTTP状态码，页面根据前3位做出响应
4-5位为微服务编号，方便定位(如果不是微服务可根据实际情况)
6位为错误类型(程序错误/业务错误)
7-8位为错误代码
9-12位为错误顺序号
状态码：http状态码 + 微服务编号 + 错误类型 + 错误代码 + 顺序号
示例：宽带订单数据错误
406 + 07 + 2 + 03 + 0001 = 406072030001

状态码看起来比较长，但是这么规划之后，状态码的管理就变得清晰很多。此外，我们可以利用状态码的规则，将每个请求的响应日志记录起来，之后通过ELK等方式可以方便的分析我们的服务各种错误的分布情况，进而改进程序。

状态码的实现可以参考September

2.1 http状态码

状态码	语义	使用场景
200	OK	正常返回消息，什么问题没有
201	Created	创建资源成功
202	Accepted	请求已接受，但处理过程较长，不能马上返回结果
304	Not Modified	没有任何修改发生
401	Unauthorized	无权限访问（已登录）
403	Forbidden	拒绝访问（未登录）
404	Not Found	不存在所请求资源
406	Not Acceptable	请求未接受，参数校验未通过或其他业务类型错误
409	Conflict	请求资源发生冲突
500	Internal Server Error	服务器的非业务类型错误

2.2 微服务编号

微服务编号	微服务名称	说明
00	预留
01	注册中心
02	服务网关
03	认证中心
04	服务监控
…	…	其他业务类微服务

2.3 状态码类型

类型编码	类型名称	说明
0	正常
1	程序错误类
2	实体/业务类

2.4 错误代码(程序错误类)

程序错误代码	程序错误名称	说明
00	正常
01	异常
02	数据库
03	队列
…	…

2.5 错误代码(实体/业务类)

实体/业务代码	实体/业务代码名称	说明
00	正常
01	商品
02	用户
03	订单
…	…

2.6 错误顺序号

错误顺序代码	错误名称	说明
000	正常
101	系统错误
201	文件不存在
202	文件格式错误
203	文件大小错误
301	数据不存在
302	数据已存在
…	…

关于Restful API与状态码的设计相关推荐

关于 RESTful API HTTP状态码
关于 RESTful API 中 HTTP 状态码的定义其中 2XX/3XX 其实都是请求成功,但是结果不同.4XX 是请求出错,5XX 是服务器处理出现错误. 200 这个最容易理解,就是正确的请 ...
趣说API HTTP 状态码的使用
在设计API HTTP 状态码的时候,我们总能听到两种声音: 第一种,也是大家最常用的: 所有接口的状态码都返回 200,然后在自定义错误码: # 正确响应 {"code: 200,&quo ...
RESTful API无状态理解
RESTful API无状态的理解 1. 传统会话 2. RESTFUL 参考链接 1. 传统会话传统web应用程序使用远程会话.在这种方法中,应用状态完全保存在服务器上.远程会话样式是客户机-服务 ...
HttpClient 4 API –获取状态码-getStatusLine（）。getStatusCode（）示例
在HttpClient API中获取状态代码的快速指南. getStatusLine().getStatusCode()示例和相关的错误. 1.简介在这个非常快速的教程中,我将展示如何使用HttpC ...
拦截httpservlet返回码_设计 API 接口，实现统一格式返回
来源:老顾聊技术前言在移动互联网,分布式.微服务盛行的今天,现在项目绝大部分都采用的微服务框架,前后端分离方式.一般系统的大致整体架构图如下: 接口交互前端和后端进行交互,前端按照约定请求URL ...
python flask 返回值状态码设置
在使用Flask以及插件Flask-RESTful来开发RESTful API时,返回值和状态码的设计是非常重要的一个部分.对于初学者,在不使用response或errorhandler()等装饰器时 ...
RESTful API标准设计教程
目前互联网上充斥着大量的关于RESTful API(为了方便,以后API和RESTful API 一个意思)如何设计的文章,然而却没有一个"万能"的设计标准:如何鉴权?API格式如 ...
RESTful API的理解
技术交流的时候遇到了这样的一个问题,被问及开发中用到的是不是Restful API,我说的是,我们现在用到的不属于完全是Restful API.因为我了解到的Restful API,是通过具体的UR ...
HTTP常见状态码详细解析
https://www.tuicool.com/articles/UrUni2j HTTP状态码(英语:HTTP Status Code)是用以表示网页服务器超文本传输协议响应状态的3位数字代码. ...

关于Restful API与状态码的设计