基础规范
基础共识
不必严格遵循RESTful
Method:get用于查询, post用于增删改,复杂条件查询也可post
POST Content-Type 默认 application/json";/在提交文件数据时格式为multipart/form-data
POST queryString意见:post不建议通过queryString携带参数,但token之类的会话标识也可以携带
禁止Path传参(便于移动端统一接口处理)
后缀版本号:如 /customer/v1
基本要素
可参考 [技术文档模板#文档模板-11.系分-接口定义DemoV20200525]
返回模型
一、标准Result模型
|
Result<T>{
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模型的一致性
设计原则
- 面向自身领域去思考
- 接口是表达领域故事的,是对关键事件、行为、动作的抽取。不要面向crud定义接口,不要面向页面逻辑去定义接口(页面多变,多变潜在意味着难以被复用)
- 面向共性去设计(抽象出共性规范),避免被被上下游特定业务特性侵入(将差异包装成可扩展点对外暴露)
- 接口路径 翻译成中文,应该是可理解的、明确无二义的,清楚表达出领域故事的
- 没有业务意义的动词不是一个好动词
- project内部建议进一步划分子模块,接口聚合归拢到对应子模块,方便自身管理,也方便外部理解
- 接口路径层次化:比如 /项目/模块/子模块/聚合/行为,如 /account/login/smsVerifyCode/send
- 接口定义是安全的,无潜在的越权访问漏洞,无关键业务数据容易被穷举的漏洞
- 尽可能的去复用、去扩展已有的接口,而非上来就新增加一个新的(毕竟做加法是最简单的,真的去认真思考过已有的无法复用或扩展吗,新定义的又是如何考量扩展性的)
- 接口建议
- 根据唯一键(可能是组合键)返回单笔数据:/channel/detail?channel;
- 根据唯一键(可能是组合键)返回多笔数据:/channel/search?paramA=¶mB=