接口规范

• 原则
• 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以上的超时时间