基本原则
- 单一职责：一个接口只做一个行为，避免大而全的接口，避免出现根据入参控制接口行为的情况，这种情况需要拆分为多个接口，实现内部可以再进行抽象封装
- 性能：基于性能考虑，可以基于业务场景封装多个原子接口，例如上层需要获取3个以上的接口进行组装数据，可以提供一个封装后的接口，减少性能损耗
- 事务统一：一个事务内的操作在一个接口内，尽量不要使用分布式事务
- 通用性：接口要具有一定的通用性，避免频繁的修改
命名和注释规范
- 接口命名要具有明确业务含义
- 清晰易懂，避免无意义的英文缩写和拼音
- 接口的javadoc上必须添加注释
- 基本命名规范：动作+业务含义
- create-新增
- add-添加
- remove-移除
- modify-修改
- query-查询单个接口
- queryxxxList-查询列表
- queryxxxPage-分页查询
参数规范
- 入参使用封装类，不要直接使用基本类型，避免接口后续扩展报错
- 入参不能使用java基础类型，必须使用包装类型，避免接口升级报错
- 入参的参数校验通过javax.validation注解实现
- 出参统一使用ResultDTO，包含code、message和data
- 出参不能直接返回领域对象，必须定义DTO进行返回，避免后续领域对象变更影响接口
异常规范
- 接口异常统一拦截返回ResultDTO，避免抛出异常
- 异常内容必须包含明确的errorCode和errorMsg
- 异常详细信息返回给客户端
日志规范
- 对外暴露的接口必须记录请求日志
- 异常请求必须打印日志
- 日志包含完整的请求参数、时间、异常详细信息
版本控制
- 接口升级和修改，需要兼容老版本
- 老版本接口标识为@Deprecated，在下次变更时及时删除无用接口
稳定性控制
- 接口需要自我保护，通过限流和熔断避免系统压力较大造成服务报错
- 幂等设计，对于写接口需要考虑幂等，避免重复数据写入
- 批量接口设计
- 提供的批量接口需要评估应用性能，设置合理的最大限制，或者内部拆分为小批量数据处理
- 在接口注释中说明接口耗时情况，避免客户端耗时设置较短报错
- 设置合理的限流阈值，避免应用崩溃
