文昕
RESTful接口设计要求
1.使用范围
本设计要求旨在基于标准的 RESTul 协议， 对部分内容的使用加以约束，指导 RESTu接口的设计人员设计出相对统
一的接口，提高接口的可复用性，增强系统的扩展性。
2.参考文档
RESTful官方文档
HTTP官方文档
3.基本规范
3.1命名规约
【推荐】RESTful接口采用以下格式进行命名：[协议]:/[域名]/[项目代码]/[模块名称]/[版本][资源路径]。模块名称可
以有多级，使用斜线()分开，根据项目的情况确定。
-ia 明  /asn/sas//ne/woeade/s 
注意：一个产品无论后端有多少个服务组成也应该只有一个API入口，示例中的API入口为：
https://api.example.com/
3.2 域名
【推荐】在不会引起跨域问题的前提下，应该尽量将 API部署在专用域名之下。
正例:http:/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．【强制】接口路径使用资源名词而非动词，动作应由 HTTP Method 体现，资源组可以进行逻辑嵌套
正例：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”（Trace ID)，用于请求的跟踪和对账。
3.POST请求参数放入body中，使用json 编码方式。
正例：
5 ["title":"test","subvValue":[1,2,3]}
3.6过滤信息
【推荐】在请求时推荐使用过滤，排序和分页，减轻服务器的负担和网络通信的数据量。
1.分页参数
。Limit：指定每页显示的资源数量。
。offset：指定从哪里开始获取资源。
。或者使用page参数
2. 排序参数
指定排序的字段。
巩order :
：指定排序的方向 (升序或降序)。
3. 筛选参数
。filter：根据特定条件筛选资源。
可以使用多个筛选参数来细化条件。
4. 搜索参数
。search ：对资源进行搜索。
1 GET /api/items?s
5.日期范围
。 date_from 和 date_to ： 指定日期范围进行筛选。
4.响应
(message)、响应数据（data)。
4.1 状态码(code)
【推荐】状态码分成三类，业务逻辑错误（1xxx）、数据验证错误（2xxx）和其它（3xx)
·业务逻辑错误
错误代码
错误消息
Invalidoperation
请求的操作无效或未被支持。
00
请求的资源不存在
003
请求创建的资源已经存
1004
1005
PermissionDenied
用户没有足够的权限执行请求的操作
1006
QuotaExceeded
1007
ServiceUnavailable
服务当前不可用，可能是临时的
1008
1009
PaymentRequired
请求的操作
旦未提供支付信息
·数据验证错误
错误代码
错误消息
描述
2001
ValidationErr
2002
请求中缺少必要的字段
2003
InvalidField
请求中的
字段值无效
2004
2005
2006
2007
·其他错误
错误代码
错误消息
描述
3001
Timeout
请求处理超时。
3002
NetworkError
网络错误，如DNS查询失败或连接拒绝。
ConfigurationError
服务配置错误，如数据库连接失败。
3004
系统正在维护中，暂时无法提供服务。
ystemMaintenance
UnknownError
4.2信息描述（message)
【强制】信息描述填写项目定义的状态值。
正例：
object类型数据
2
eep
51
4.3 响应数据(data)
1. 【强制】 array 类型数据。通过 list字段，
a的Object结构
正例
ay类型数据。
"code":100000,
"ist":[]
2．【强制】空数组使用，而不是 null。
正例：
反例
"role_ids": null
5.异步策略
RESTul接口的异步策略是指在设计和实现 RESTful API时采用的一种方法，它允许服务器在处理请求时不必立即返
回结果，而是可以在处理完成后通过某种机制将结果通知给客户端。这种策略适用于那些处理时间较长或者需要等待
其他操作完成的请求，如大量数据的处理、远程服务的调用等。
5.1 复杂业务逻辑
在业务逻辑比较复杂，不能第一时间获取到结果的接口，建议使用异步的策略，另外设计一个查询结果的接口，或者
利用webhooks、事件源（Server-Send Event)、websocket等技术。
5.2大文件上传下载
【推荐】 对于大文件的上传下载建议使用异步策略，接口快速返回，文件参与的事务分别进行处理，在返回结果中携 
带可查询进度的接口地址。
【推荐】文件上传成功返回文件ID，避免暴露内部路径。
【推荐】设计独立的文件上传和下载接口，并独立部署避免和其它服务使用相同的网关，造成其它服务的延迟。
说明文性
接口描述
详细解释接口的用途，包括业务场景、处理逻辑等。例如：
此接口用于获取系统中已注册用户的基本信息，包括用户名、年龄、性别等，以及它的处理逻辑和可能的业务场
景。
请求头
·列出必须包含的请求头信息，如Content－Type：appLication/json 用于表示请求体的格式为JSON。
：对于需要身份验证的接口，说明认证相关的请求头，如Authorization：Bearer[token]。
请求体
·如果请求方式允许有请求体（如POST、PUT)，详细说明请求体的结构。
给出请求体数据类型，并给出示例数据。例如：
1{
4}
响应头
【强制】列出可能包含的响应头信息，如“Content-Type: appiationjson"表示响应体为JSON格式。
响应体&状态码
·根据不同的状态码，详细说明响应体的结构。
给出成功和失败情况下的示例数据。例如，对于获取用户信息成功的响应
4f"age: 25,
·对于错误情况，给出错误返回的示例数据：
数据格式
【推荐】参数或者返回值如果有表示状态的字段，要用枚举类型定义出来。
【推荐】时间字段以ISO 8601格式返回：YYYY-MM-DDTHH:MM:SS+08:00
【推荐】 如果时间的精度要求到毫秒级别，使用 UNIX 时间戳。
格式
含义
YYYY
是公历中0000到9999年的十进制数字，
“（(连字符）在字符串中实际出现两次。
是一年中从01（1月）到12（12月）的月份。
是一个月中从01到31的日期。
“出现在字符串中，表示时间元素的开始。
是自午夜以来经过的完整小时数，以00到24的两位小数表示。
“（冒号）在字符串中实际出现两次。
是自小时开始以来的完整分钟数，从00到59的两位小数。
是自分钟开始以来的完整秒数，从00到59的两位小数。
”（点）按字面意思出现在字符串中。
是指定为
正例：
1#原时间
2 Updated Date:2017-12-04T18:07:57+08:00
Registry Expiry Date:2018-12-04T18:07:4
#换算成北京时间：
8 Creation Date:2017-12-05 02:07:44
9Registry Expiry Date:2018-12-0502:07:44
7.安全
7.1 网络环境划分
【推荐】将网络环境划分为三种，即互联网环境、石油内部网络环境以及系统内部微隔离网络环境。接口设计人员要
依据使用环境来确定接口设计时所采用的安全策略。
·互联网环境：与外部互联的环境。
·石油内部网络环境：中石油的内部网络。
·系统内部微隔离网络环境：使用微隔离技术为一组微服务隔离出来的独立环境。
7.2认证和授权
应使用安全的身份验证和授权机制来验证客户端的身份，并确定其是否有权访问特定的资源。
7.2.1 API Key
【推荐】API Key通常用于简单的API访问控制，
，适用于不需要用户授权的场景，服务器根据APIKey识别客户端并允