接口规范
- 工作小总结
- 时间：2021-07-20 10:30
- 3145人已阅读
简介
原则RPC-DUBBO命名约定参数约定其他约定示例HTTP命名规范协议规范示例状态码其他版本发布版本升级超时时间原则如无必要，勿增接口；强调API的可理解性，可发现性和可用性；从具体的实施和用例中抽象出来。RPC-DUBBO命名约定【Must】接口以XXXRemoteService命名；【Must】请求响应以XXXRequest、XXXResponse接口；【Must】请求响应参数命名统一驼峰。参
🔔🔔🔔好消息!好消息!🔔🔔🔔
有需要的朋友👉:联系凯哥
原则
RPC-DUBBO
命名约定
参数约定
其他约定
示例
HTTP
命名规范
协议规范
示例
状态码
其他
版本发布
版本升级
超时时间
原则
如无必要，勿增接口；
强调API的可理解性，可发现性和可用性；
从具体的实施和用例中抽象出来。
RPC-DUBBO
命名约定
【Must】接口以XXXRemoteService命名；
【Must】请求响应以XXXRequest、XXXResponse接口；
【Must】请求响应参数命名统一驼峰。
参数约定
【Must】接口入参和返回参数是一个大对象，不定义多参；
【Must】不使用void、null作为返回值。
其他约定
【Must】不使用重载；
【Must】批量接口返回值数量不得超过200；
【Must】不适用循环rpc；
【Should】返回值中可以定义code；
【Should】优先使用强类型，不使用map、json作为返回值。
示例
{ "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。
示例
{ "success": true, // 标识该次请求后台是否处理成功 "error": { // 请求失败的，给出错误信息 } "data": ... // 数据内容，每个业务接口具体定义 "paging": { // 如果是分页数据，给出分页信息 }} |
状态码
其他
版本发布
api发布只在master上进行
版本升级
http接口版本可以使用PathVariable或者queryString
为了保持兼容性，不轻易删除字段，新增而不是修改
超时时间
推荐快速失败，读接口可超时重试
除特殊情况，不设置3s以上的超时时间