接口定义

基础规范

基础共识

1. 不必严格遵循RESTful

2. Method：get用于查询, post用于增删改，复杂条件查询也可post

3. POST Content-Type 默认 application/json"；/在提交文件数据时格式为multipart/form-data

4. POST queryString意见：post不建议通过queryString携带参数，但token之类的会话标识也可以携带

5. 禁止Path传参（便于移动端统一接口处理）

6. 后缀版本号：如 /customer/v1

基本要素

可参考 [技术文档模板#文档模板-11.系分-接口定义DemoV20200525]

返回模型

一、标准Result模型

|

Result{

private boolean success = ``false``;``//true表示请求处理成功，false表示请求处理失败

private String errorMsg = ``""``;``// 错误信息：用户错误提示，接口实现要注意文案，app注意为空容错

private String errorCode = ``""``;``// 错误代码：技术错误码，便于开发调试定位问题。errorCode不要混入http响应码。

private T model;``//业务数据模型

}

|

二、标准分页模型

标准分页参数 count,pageTotal,pageSize,pageNo都应该包装到 T model中，确保Result模型的一致性

设计原则

1. 面向自身领域去思考
   1. 接口是表达领域故事的，是对关键事件、行为、动作的抽取。不要面向crud定义接口，不要面向页面逻辑去定义接口（页面多变，多变潜在意味着难以被复用）
   2. 面向共性去设计（抽象出共性规范），避免被被上下游特定业务特性侵入（将差异包装成可扩展点对外暴露）
   3. 接口路径 翻译成中文，应该是可理解的、明确无二义的，清楚表达出领域故事的
   4. 没有业务意义的动词不是一个好动词
2. project内部建议进一步划分子模块，接口聚合归拢到对应子模块，方便自身管理，也方便外部理解
3. 接口路径层次化：比如 /项目/模块/子模块/聚合/行为，如 /account/login/smsVerifyCode/send
4. 接口定义是安全的，无潜在的越权访问漏洞，无关键业务数据容易被穷举的漏洞
5. 尽可能的去复用、去扩展已有的接口，而非上来就新增加一个新的（毕竟做加法是最简单的，真的去认真思考过已有的无法复用或扩展吗，新定义的又是如何考量扩展性的）
6. 接口建议
   1. 根据唯一键（可能是组合键）返回单笔数据：/channel/detail?channel；
   2. 根据唯一键（可能是组合键）返回多笔数据：/channel/search?paramA=¶mB=