API规范

!> 阿里代码手册：Java开发手册-华山版1565599341.pdf

通讯规范与协议

• 通讯规范与协议

地址命名

1. 尽量在一级url区分领域和客户端 后续的都是操作动作说明 并且简短一些

• /服务路由/客户端版本/功能模块/具体功能，例子：/yunbanfang-demand/web/v1/demand/create

2. 类名已经体现了领域 接口方法名就不要再说明了 分页列表接口方法名是page 列表是list 不太一样

• 不需要 DemandInfoAppController.list4App，这样就行了 DemandInfoAppController.page

3. 能共用的接口就公用 有点不一样用策略去区分

4. 语义要英化 简单

5. 语义功能要说明清楚 不要歧义

6. 接口的命名地址不要用驼峰 有多个单词表示一个接口操作的 使用中横线 (-)隔开

   • /order/update-goods

7. 接口的返回参数 不要包含有工程结构的前后缀

   • 目前我们的
   • 加上Req后缀的类，标识这是一个请求实体类
   • 加上Vo后缀的类，标识这是一个响应实体类

但这些后缀的用途只限定于工程结构实体说明，它们只具有代码工程含义，不存在任何业务含义！不要将这些后缀作为接口请求参数变量的后缀

• 例如 订单详情信息 加上Vo后缀的类，标识这是一个响应实体类

  • private OrderDetailVo orderDetailVo;

  • private OrderDetailVo orderListReq;

• 返回给前端的字段名 没有必要加上Vo后缀 请求实体也没必要加上Req后缀 在业务含义上 它就只是订单详情信息、订单列表请求对象名称

  • private OrderDetailVo orderDetail;

  • private OrderDetailVo orderList;

业务服务

• Service层的职责是处理数据返回数据，不要包含api层的返回结构DataResponse 有需要出现校验出错的 抛自定义异常