接口设计规范

基本原则

• 单一职责：一个接口只做一个行为，避免大而全的接口，避免出现根据入参控制接口行为的情况，这种情况需要拆分为多个接口，实现内部可以再进行抽象封装
• 性能：基于性能考虑，可以基于业务场景封装多个原子接口，例如上层需要获取3个以上的接口进行组装数据，可以提供一个封装后的接口，减少性能损耗
• 事务统一：一个事务内的操作在一个接口内，尽量不要使用分布式事务
• 通用性：接口要具有一定的通用性，避免频繁的修改

命名和注释规范

• 接口命名要具有明确业务含义
• 清晰易懂，避免无意义的英文缩写和拼音
• 接口的javadoc上必须添加注释
• 基本命名规范：动作+业务含义

• • create-新增
  • add-添加
  • remove-移除
  • modify-修改
  • query-查询单个接口
  • queryxxxList-查询列表
  • queryxxxPage-分页查询

参数规范

• 入参使用封装类，不要直接使用基本类型，避免接口后续扩展报错
• 入参不能使用java基础类型，必须使用包装类型，避免接口升级报错
• 入参的参数校验通过javax.validation注解实现
• 出参统一使用ResultDTO，包含code、message和data
• 出参不能直接返回领域对象，必须定义DTO进行返回，避免后续领域对象变更影响接口

异常规范

• 接口异常统一拦截返回ResultDTO，避免抛出异常
• 异常内容必须包含明确的errorCode和errorMsg
• 异常详细信息返回给客户端

日志规范

• 对外暴露的接口必须记录请求日志
• 异常请求必须打印日志
• 日志包含完整的请求参数、时间、异常详细信息

版本控制

• 接口升级和修改，需要兼容老版本
• 老版本接口标识为@Deprecated，在下次变更时及时删除无用接口

稳定性控制

• 接口需要自我保护，通过限流和熔断避免系统压力较大造成服务报错
• 幂等设计，对于写接口需要考虑幂等，避免重复数据写入
• 批量接口设计

• • 提供的批量接口需要评估应用性能，设置合理的最大限制，或者内部拆分为小批量数据处理
  • 在接口注释中说明接口耗时情况，避免客户端耗时设置较短报错
  • 设置合理的限流阈值，避免应用崩溃