RESTful接口设计要求
1.使用范围
本设计要求旨在基于标准的RESTfuI协议，对部分内容的使用加以约束，指导RESTfuI接口的设计人员设计出相对统
一的接口，提高接口的可复用性，增强系统的扩展性。
2.参考文档
RESTful官方文档
HTTP官方文档
3.基本规范
3.1命名规约
【推荐】RESTfuI接口采用以下格式进行命名：[协议]：//[域名]/[项目代码]/[模块名称]/[版本]/[资源路径]。模块名称可
以有多级，使用斜线（/)分开，根据项目的情况确定。
正例：https://api.example.com/auth/v1/users/{user_id}//版本v1的查询用户列表的APl接口
https://api.example.com/
3.2域名
【推荐】在不会引起跨域问题的前提下，应该尽量将API部署在专用域名之下。
正例：https://api.example.com
3.3模块
【强制】模块命名尽量采用全小写单词，如果需要连接多个单词，则采用中划线（一），如果要把多个单词连接起来形
成一个具有描述性的名称则使用下划线（二）连接。
3.4资源路径
1.【强制】资源的路径应该从根到子依次如下：
/{resources}/{resource_id}/{sub_resources}/{sub_resource_id}/{sub_resource_property}
2.【强制】URL中不采用大小写混合的驼峰命名方式，尽量采用全小写单词，如果需要连接多个单词，则采用连接
符，不能出现一。
正例：/api/task_groups
反例：/api/task-groups
3.【强制】接口路径使用资源名词而非动词，动作应由HTTPMethod体现，资源组可以进行逻辑嵌套
正例：POST/api/tasks或/api/task_groups/1/tasks表示在id为1的任务组下创建任务
反例：POST/api/create_task
4.接口路径中的获取复数资源的时候使接口路径中的获取复数资源的时候使用复数
正例：
/api/tasks
反例：
/api/task/list
3.5请求参数
1.【强制】如果有请求参数，请求参数使用小驼峰。
2.【推荐】header中要加入一个唯一的追踪标识符“X-Trace-ID”（TraceID），用于请求的跟踪和对账。
1 X-Trace-ID: 123e4567-e89b-12d3-a456-426614174000
3.POST请求参数放入body中，使用json编码方式。
正例：
1PoST http://www.eXample.com HTTP/1.1
2 Content-Type: application/json;charset=utf-8
3X-Trace-ID:123e4567-e89b-12d3-a456-426614174000
4
5["title":"test","subValue":[1,2,3]}
6
3.6过滤信息
【推荐】在请求时推荐使用过滤，排序和分页，减轻服务器的负担和网络通信的数据量。
1.分页参数
limit：指定每页显示的资源数量。
offset：指定从哪里开始获取资源。
1 GET /api/items?limit=10&offset=20
。或者使用page参数：
1 GET /api/items?page=3&limit=10
2.排序参数
sort：指定排序的字段。
order：指定排序的方向(升序或降序)。
1GET/api/items?sort=created_at&order=desc
3.筛选参数
filter：根据特定条件筛选资源。
。可以使用多个筛选参数来细化条件。
1 GET/api/items?filter[status]=active&filter[type]=premium
4.搜索参数
search：对资源进行搜索。
1 GET /api/items?search=widget
5.日期范围
date_from和date_to：指定日期范围进行筛选
1 GET /api/orders?date_from=2023-01-01&date_to=2023-01-31
4.响应
【强制】HTTP请求的返回码是200的情况下，响应数据应该包含三个属性，状态码（code）、信息描述
(message)、响应数据(data)。
4.1状态码
（code)
【推荐】状态码分成三类，业务逻辑错误（1xxx）、数据验证错误（2xxx）和其它（3xxx）
·业务逻辑错误
A
B
C
错误代码
错误消息
描述
2
1001
InvalidOperation
请求的操作无效或未被支持。
3
1002
ResourceNotFound
请求的资源不存在。
4
1003
ResourceAlreadyExists
请求创建的资源已经存在。
1004
ResourcelnUse
资源正在使用中，无法执行请求的操作
1005
PermissionDenied
用户没有足够的权限执行请求的操作。
7
1006
QuotaExceeded
请求的操作导致配额超限。
8
1007
ServiceUnavailable
服务当前不可用，可能是临时的。
9
1008
DependenciesFailed
请求的操作依赖于其他服务，而这些服务失败了。
10
1009
PaymentRequired
请求的操作需要支付，但未提供支付信息。
数据验证错误
A
B
C
错误代码
错误消息
描述
2
2001
ValidationError
请求的数据验证失败。
3
2002
MissingField
请求中缺少必要的字段。
4
2003
InvalidField
请求中的字段值无效。
5
2004
FieldFormatError
请求中的字段格式错误。
6
2005
FieldRangeError
请求中的字段值超出允许的范围。
7
2006
FieldLengthError
请求中的字段长度不符合要求。
8
2007
DuplicateEntry
请求中的数据已经存在，导致重复。
其他错误
A
B
C
1
错误代码
错误消息
描述
2
3001
Timeout
请求处理超时。
3
3002
NetworkError
网络错误，如DNS查询失败或连接拒绝。
寸
3003
ConfigurationError
服务配置错误，如数据库连接失败。
5
3004
SystemMaintenance
系统正在维护中，暂时无法提供服务。
6
3005
UnknownError
出现未知错误，无法确定具体原因。
4.2信息描述（message）
【强制】信息描述填写项目定义的状态值。
正例：
1//object类型数据
2
3
"code":500002,
4
"meSSage":"UNKNOWN"
5
"data":{}
6
4.3响应数据（data）
1.【强制】array类型数据。通过list字段，保证data的Object结构。
正例：
//array类型数据。
2
3
"code":100000,
4
"message":"SUcCESs"
5
"data":{
6
"list": []
8
2
【强制】空数组使用[]，而不是null。
正例：
"code":100000，
3
"message":"sUcCESs"
4
"data":{
5
"id":1,
6
"role_ids":[]
反例：
1{
2
"code":100000,
3
"message":"SUcCESs",
寸
"data":{
5
"id":1,
6
"role_ids": null
8}
9
5.异步策略
RESTfuI接口的异步策略是指在设计和实现RESTfuIAPI时采用的一种方法，它允许服务器在处理请求时不必立即返
回结果，而是可以在处理完成后通过某种机制将结果通知给客户端。这种策略适用于那些处理时间较长或者需要等待
其他操作完成的请求，如大量数据的处理、远程服务的调用等。
5.1复杂业务逻辑
利用webhooks、事件源（Server-SendEvent)、websocket等技术。
5.2大文件上传下载
白
【推荐】对于大文件的上传下载建议使用异步策略，接口快速返回，文件参与的事务分别进行处理，在返回结果中携
带可查询进度的接口地址。
【推荐】文件上传成功返回文件ID，避免暴露内部路径。
【推荐】设计独立的文件上传和下载接口，并独立部署避免和其它服务使用相同的网关，造成其它服务的延迟。
6.说明文档
接口描述
详细解释接口的用途，包括业务场景、处理逻辑等。例如：
此接口用于获取系统中已注册用户的基本信息，包括用户名、年龄、性别等，以及它的处理逻辑和可能的业务场
景。
请求头
·列出必须包含的请求头信息，如Content－Type：application/json用于表示请求体的格式为JSON。
·对于需要身份验证的接口，说明认证相关的请求头，如Authorization：Bearer[token]。
请求体
·如果请求方式允许有请求体（如POST、PUT），详细说明请求体的结构。
·给出请求体数据类型，并给出示例数据。例如：
2
"username":"testuser"
3
"password":"123456"
响应头
【强制】列出可能包含的响应头信息，如“Content-Type:application/json”表示响应体为JSON格式。
响应体&状态码
根据不同的状态码，详细说明响应体的结构。
给出成功和失败情况下的示例数据。例如，对于获取用户信息成功的响应：
1{
2"id":1,
3"username":"testuser
4"age":25，
5 "gender":"male"
6}
对于错误情况，给出错误返回的示例数据：
1{
"error":"Invalidusernameorpassword"
3}
数据格式
数据格式
【推荐】参数或者返回值如果有表示状态的字段，要用枚举类型定义出来。
【推荐】时间字段以ISO8601格式返回：YYYY-MM-DDTHH:MM:SS+08:00
【推荐】如果时间的精度要求到毫秒级别，使用UNIX时间戳。
格式
含义
人人人人
是公历中0000到9999年的十进制数字。
“”（连字符）在字符串中实际出现两次。
MM
是一年中从01（1月）到12（12月）的月份
DD
是一个月中从01到31的日期。
T
“T"出现在字符串中，表示时间元素的开始。
HH
是自午夜以来经过的完整小时数，以00到24的两位小数表示。
：（冒号）在字符串中实际出现两次。
mm
是自小时开始以来的完整分钟数，从00到59的两位小数。
55
是自分钟开始以来的完整秒数，从00到59的两位小数。
“（点）按字面意思出现在字符串中。
ssS
是自第二个开始以来的完整毫秒数，以三位十进制数字表示。
是指定为*Z”（UTC）或"+"或"-"的时区偏移量，后跟时间表达式HH:mm
正例：
1#原时间
2Updated Date:2017-12-04T18:07:57+08:00
3 CreationDate:2017-12-04T18:07:44+08:00
4 Registry Expiry Date:2018-12-04T18:07:44+08:00
5
6#换算成北京时间：
7UpdatedDate:2017-12-05 02:07:57
8 CreationDate:2017-12-05 02:07:44
9Registry Expiry Date:2018-12-05 02:07:44
7.安全
7.1网络环境划分
【推荐】将网络环境划分为三种，即互联网环境、石油内部网络环境以及系统内部微隔离网络环境。接口设计人员要
依据使用环境来确定接口设计时所采用的安全策略。
·互联网环境：与外部互联的环境。
·石油内部网络环境：中石油的内部网络。
7.2认证和授权
应使用安全的身份验证和授权机制来验证客户端的身份，并确定其是否有权访问特定的资源，
7.2.1APIKey
【推荐】APTKey通常用于简单的API访问控制，适用于不需要用户授权的场景，服务器根据APIKey识别客户端并允
议在石油内部网络或者微隔离网络中使用。
7.2.2OAuthtoken
【推荐】OAuthToken是一种复杂的认证机制，涉及到授权流程，设置有效期，并且可以提供更细粒度的控制，在需
要更复杂授权流程的场景建议使用OAuthToken。建议在互联网环境或者石油内部网络环境中使用。