2022-12-16 17:37:44
浏览数 (1)
原则
- 如无必要，勿增接口；
- 强调API的可理解性，可发现性和可用性；
- 从具体的实施和用例中抽象出来。
RPC-DUBBO
命名约定
- 【Must】接口以XXXRemoteService命名；
- 【Must】请求响应以XXXRequest、XXXResponse接口；
- 【Must】请求响应参数命名统一驼峰。
参数约定
- 【Must】接口入参和返回参数是一个大对象，不定义多参；
- 【Must】不使用void、null作为返回值。
其他约定
- 【Must】不使用重载；
- 【Must】批量接口返回值数量不得超过200；
- 【Must】不适用循环rpc；
- 【Should】返回值中可以定义code；
- 【Should】优先使用强类型，不使用map、json作为返回值。
示例
代码语言：javascript
复制{
"success": true, // 本次响应逻辑上是否成功
"error": {
// 请求失败的，给出错误信息，成功的可以不填
}
"data": ... // 具体数据结构，业务上是否成功
"paging": {
// 如果是分页数据，给出分页信息
}
}
HTTP
命名规范
- 【Must】对外公开(C端、OpenAPI)的API接口以"/api"作为基本路径，以清晰的分离出公共与非公共API；
- 【Must】对内非公开API接口以"/innerapi"作为基本路径；
- 【Must】请求响应参数统一为驼峰；
协议规范
- 【Must】杜绝PathVariable，请求path中不掺杂参数；
- 【Should】post使用application/json格式或者form-urlencoder。
示例
代码语言：javascript
复制{
"success": true, // 标识该次请求后台是否处理成功
"error": {
// 请求失败的，给出错误信息
}
"data": ... // 数据内容，每个业务接口具体定义
"paging": {
// 如果是分页数据，给出分页信息
}
}
状态码
其他
版本发布
版本升级
- http接口版本可以使用PathVariable或者queryString
- 为了保持兼容性，不轻易删除字段，新增而不是修改
超时时间
- 推荐快速失败，读接口可超时重试
- 除特殊情况，不设置3s以上的超时时间
