APIFox接口管理规范

背景： 团队目前在apifox项目管理中，接口的使用非常混乱。同一个项目存在多个未区分的服务，前置URL也不一致，导致无法进行新增接口的自动化测试集成。此外，环境变量和全局参数的使用也没有统一标准，导致接口无法正常运行或调试效率低下。所以团队内需要遵循统一的标准规范来管理apifox的接口和接口用例。

---

• 项目管理：
  • 每个项目应该有一个独立的项目空间，用于存放相关的接口文档、服务配置和环境变量等。
  • 项目名称应该清晰明确，并且在apifox中进行统一命名。
• 接口分类和分组:
  • 将接口分类和分组，使其提高的可读性和可维护性。将相关的接口进行逻辑上的分组，例如按模块、功能或业务流程等进行分类，不同服务务必进行区分，请不要混淆服务和项目的概念。
• 接口设计：
  • 每个接口都应该有一个唯一的标识符(例如URL路径，根据服务进行分组，每个接口默认继承父目录对应服务的前置URL，每个环境不同服务的前置URL必须保持唯一性，URL不能以"/“结尾，接口URL路径必须以”/"作为起始位)，用于识别和区分不同的接口.同时也应该遵循一致的命名规则。
  • 在接口设计中，应包含必要的请求方法、参数、请求体、响应体等信息，并进行描述，每个参数必须添加注释信息，可选项参数应加上示例。
• 环境变量和服务配置：
  • 为每个环境(例如开发、测试、生产)设置相应的环境变量和服务配置。变量和配置应该在apifox中进行集中管理，并在需要时进行正确的切换。PS:除了所有接口都有的统一参数的情况外，不要添加全局参数，环境变量新增字段需要同步至其他环境，值不需要同步，新增字段请添加注释，并在群内通知说明
• 接口版本控制：
  • 对于需要进行版本控制的接口，应采用一致的版本命名规则，例如在URL路径中使用版本号路径(前提需要后端指定版本路径)或者通过复制或新增接口用例的方式增加新版本接口的改动，不要对原有接口或接口用例直接进行修改，接口改动一定要添加注释进行说明，并在通知群进行说明。
• 共享和访问权限：
  • 确保合适的团队成员能够共享和访问正确的接口文档和配置信息。设定适当的访问权限，以确保敏感信息不被未授权人员访问。
  • 在修改之前请先进行同步最新的接口变动，调试成功之前不要进行保存和同步。如果改动较多请在其他分支或者克隆项目后进行修改。
• 定期更新和维护：
  • 对接口文档、服务配置和环境变量等内容进行定期更新和维护，以反映项目的实际情况和需求变化。群内通知。
• 自动化测试用例使用规范：
  • 核心业务接口除外，新增功能进行自动化用例要分开创建用例套件，不同用例需要使用相同字段，但值需要区分的场景，请首先使用测试数据，或创建多组用例执行。 读写操作场景用例分离(写数据前提不能污染生产环境，并且进行数据隔离或数据回收)，核心业务接口保持一致。 变量数据引用优先级：测试数据>环境变量>临时变量
  • 环境变量相同字段不能使用别名的方式增加新的值，环境变量固定之后请不要随便修改引用、字段和值，如有新增字段请同步至各环境，修改环境变量字段或值后请在通知群进行说明。请遵循以上标准规范保持测试数据的同步。 接口数据格式统一规范，code状态码，接口统一校验
• 内部使用须知：
  • 请内部使用apifox的成员加入apifox提醒通知群，以便及时知晓apifox项目接口最新变化，和标准规范，同时方便问题反馈。