接口前缀
接口前缀由/{环境前缀}/[版本号]/[调用客户端标识]/{模块}构成，花括号内容必须项，中括号内容为建议项，url必须以“/”开始
环境前缀
- local-api 本地环境前缀（建议）
- dev-api 开发环境前缀
- test-api 测试环境前缀
- pre-api 预发环境前缀
- prod-api 线上环境前缀
版本号
由于存在老接口兼容问题，暂不考虑版本号调用客户端标识
由于存在老接口兼容问题，暂不考虑版本号 - /app/medicine或/app/ 医生移动端接口前缀
- /app/patient 患者移动端接口前缀
- pc端不做限制
模块
模块二级名称，如：im，iam，system等
注：本文档后续的接口举例中，除特殊说明外，忽略接口前缀接口分级
接口分为一级，二级及三级 - 一级： 患者移动端接口，稳定性要求99.9%，时间基线1s，设计并发量不低于5000，如需校验登录用户，应该在controller方法上加上@RequiresLogin(userTypes = UserTypeEnum.PATIENT)
- 二级：医生端移动接口，稳定性要求99.9%，时间基线2s，设计并发量不低于1000，如需校验登录用户，应该在controller方法上加上@RequiresLogin(userTypes = UserTypeEnum.MEDICINE)
- 三级：PC管理端接口，稳定性要求99%，时间基线3s，上传和导出接口可适当放宽至10s，优化后超过10s的数据处理应该通过其他途径处理，如批量计算，定时处理或数据平台等，设计并发量不低于500，如需校验登录用户，应该在controller方法上加上@RequiresLogin(userTypes = UserTypeEnum.MANAGER)
当一个接口同时被以上各个客户端调用时，分级遵从从严规则。
注：@RequiresLogin(userTypes = UserTypeEnum.xxx)可以加在controller类上，加载类上表示该类中的所有接口访问时都会校验用户类型为xxx，另外userTypes参数可以传多个，传多个时表示只要用户满足其中一种类型，即可访问接口方法
接口方法允许get,post,put及delete方法 - get方法标注接口时，表明该接口安全（不会对数据库数据造成修改）并且幂等（该接口调用一次和多次效果一致），适用于查询类接口
- post方法标注接口时，表明该接口既不安全，也不幂等，适用于新增接口
- put方法标注接口时，表明该接口不安全，但幂等，适用于更新接口
- delete方法标注接口时，表明该接口不安全，但幂等，适用于删除接口
注：如果更新接口不幂等，如：/minotor/switch，调用该接口，总是取反设备的启停状态，此时不适用put方法，而应该定义为post方法。接口命名
接口命名参照restful命名规范，但不一定需要严格遵从该规范。比如，restful命名规范不建议使用动词，但在某些情况下，使用动能能让人直观了解接口的作用，例如启动某台设备，可以命名为：/monitor/start/{monitorId}；闭关某台设备，可以命名为：/monitor/stop/{monitorId}。下面是在尽量兼顾老接口的基础上，对部分接口命名的一些具体规定。 - 对象列表（分页）查询：/对象名/list，使用get方法
- 对象详情查询：/对象名/{id}，使用get方法
- 对象批量导出：/对象名/{export} ，使用post方法
- 对象批量导入：/对象名/{import} ，使用post方法
- 新增对象：/对象名 ，使用post方法
- 更新对象：/对象名 ，使用put方法
- 批量删除对象：/对象名 使用delete方法
- 删除对象：/对象名/{id} 使用delete方法
- 其他方法视具体情况命名，命名中允许使用动词，遵从从简原则，但应尽量能直观反应出接口的含义
另外，接口命名应该遵从一下规则： - 严禁使用大写或中文
- URI开头必须包含（/）
- URI结尾不应包含（/）
- 多个单词之间必须使用（/）分割
接口参数
- 提供给客户端的接口，如果需要登录后才能访问的接口，登录标识符传递在header中，并且命名为Authorization
- 微服务内部调用接口，如果接口需要登录用户信息时，应该显式声明，被调用者无义务传递Authorization header
- 微服务内部调用接口，应该通过固定密钥校验调用者，如果存在敏感数据，应该使用签名校验调用者
- 如无特殊情况，接口中日期统一传递yyyy-MM-dd HH:mm:ss
返回值
- 返回值统一使用R类，严禁使用AjaxResult类，
- 返回值格式如下：
{ "msg": "操作成功", //请求提示语 "code": 200, //http请求状态码 "data": null //业务数据 } 返回值中，code值为200时表示接口调用成功； - 接口返回的业务数据因该避免冗余字段，例如：接口返回了alias字段,值为null，但实际上数据库中该字段值不为null，只是接口没有查询，这就造成了数据不一致问题。后端应通过定义dto类来尽量避免这种情况，尤其对于远程联调的接口尤其如此！
- 如无特殊情况，接口中日期统一返回yyyy-MM-dd HH:mm:ss