接口规范

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


上一篇: 故障问题处理指南

下一篇: 项目管理模板

Top Top