以下屁话都是乱说的, 我是个忠实的RESTful用户
建议遵循 https://cloud.google.com/apis/design?hl=zh-cn
以下内容仅供特殊情况下使用
API文档规范
API文档作为详细设计的一部分,其必须在开发之前完成。为提高前后端协同效率,详细设阶段需要提供所有前后端和对外接口;RPC接口可后续补充;
0. 通用规范
URL要求:
- 需要包含接口URL(具体域名或IP可不写)
- URL需要包含通信方式http / https / ws 等
- URL使用-连接多个单词
- 常用动词, 见下动词表,动词可自定义,但curd类功能如无特殊情况请参照动词表;
- URL不能包含特殊字符和敏感词汇,除非这些字符有特殊的编码需求
- 必须包含/api/admin-api 或 /api/rpc-api
- url应该存在层级关系,除固定前缀外,应为/项目简称/模块名/[二级模块名,如有]/功能名/动词/[id, 如有]
URL结尾动词 | 说明 |
---|---|
create | 创建、新增 |
update | 编辑、修改 |
delete | 删除 |
get | 查询、获取 |
page | 分页查询 |
export | 导出 |
import | 导入 |
样例:
- 创建角色:/admin-api/cl/acct/role/create
- 修改角色:/admin-api/cl/acct/role/update
- 删除角色:/admin-api/cl/acct/role/delete、 /admin-api/cl/acct/role/delete/{id}
- 获取角色信息:/admin-api/cl/acct/role/get、/admin-api/cl/acct/role/get/{id}、/admin-api/cl/acct/role/get-by-user
- 获取角色分页:/admin-api/cl/acct/role/page
- 导出角色:/admin-api/cl/acct/role/export
- 导入角色:/admin-api/cl/acct/role/import
接口描述要求:
- 必须包含功能描述
- 加密与否,签名与否 ,如有需说明加解密方式与签名方式
- 如有特殊需要注意的,需注明
请求方式要求:
- 目前仅使用get / post; 且必须写明get / post
- 对于涉及数据修改的操作(如更新,删除),应使用POST请求。POST请求可以发送大量数据,且数据不会显示在URL中,特别的,分页查询应为POST
- 对于数据查询的操作,且无涉及敏感内容,应使用GET请求
- 所有GET请求不应该携带body, 避免中间件过滤
请求字段要求:
- 请求参数,包括header与body,参数需要写明必填、类型、长度和意义,如需计算写明计算规则
- 如涉及常量,则必须描述所有常量及其意义
- 涉及前后端传参或对外接口时,Long类型字段必须使用String类型避免精度丢失
- 字段的命名应遵循驼峰命名法
- 编码使用UTF-8
响应要求:
- 响应参数,参数需要写明必填、类型、长度、意义和mock值,如需计算写明计算规则
- 必须包含code, data, msg字段; 其中data为空的时候设置为{},不可为null; code正常是为0,其余情况下为错误码
- 无特别设计时,相应正常以及业务异常时,HTTP STATUS均为200; 如特殊情况,需注明
- 编码使用UTF-8
1. 内部非前后端接口文档额外规范(包括但不限于RPC, MQ等)
MQ类:
- 必须写明Topic, 消息类型,TAG等基础信息
- 如有加解密方式,必须写明
- 写明消息体,以及消息内具体字段含义
- 建议使用@link 关联涉及的producer, consumer
RPC类:
- 推荐在url中加上接口版本
- 如果header中需要特殊参数,必须说明
- 返回值应用CommonResult包裹,特殊比特流返回等除外
- 异步接口需要特殊注明,如提供后续查询结果接口,注明
- 如果为批量接口,使用列表或者其他集合类包裹所有结果,不要有任一元素直接失败返回整体失败。
2. 外部接口文档额外规范
强制要求:
- 每个接口必须包含:
- 功能描述
- 通信方式 —— [https, http, tpc, websocket等]
- 数据格式 ——[json, xml等]
- 请求示例与响应实例
- 有可能返回的错误码及其含义
- SDK(如有)
- 对外HTTP接口强制要求HTTPS
- 涉及敏感字段传输必须使用POST, 且考虑加密传输
- 金钱类参数必须使用String类型传输
- 时间传输如果使用String类型,需要说明时区
- mock字段参数或结果,不应该出现真实的名称,但可以是本公司或者合作公司名称
推荐要求:
- 推荐包含:
- 对接准备
- 快速入门
- 各具体场景下业务方案 / 风控方案 / 推荐配置
- 接口之间的时序图/流程图
- 各语言调用接口的样例代码 / Postman项目文件
- 服务支持协议
- 常见问题
- 版本号与版本说明
- header中,如特别不需cdn缓存的接口,推荐加上cache-control
- 不推荐返回跨域header为*
- 推荐使用/v1,/v2之类的待版本号的url,用于同时支持多版本服务
附录标准字段
本节介绍了需要类似概念时应使用的一组标准消息字段定义。这将确保相同的概念在不同 API 中具有相同的名称和语义。
发表回复