Apifox 生产落地案例

五、生产落地案例

案例一：从「Postman + Swagger 双份维护」收敛到一处定义。背景是一个约 200 个接口的内部平台，后端用注解生成 Swagger 文档，前端各自在 Postman 里维护一份调试集合。问题很明显：接口改了字段，Swagger 更新但 Postman 集合没人动，前端拿着旧集合调半天；联调时后端没写完，前端只能干等。做法是三步：第一步，把 OpenAPI 文件导入 Apifox，生成接口定义与文档，取消手工维护的 Postman 集合；第二步，为未完成的接口开启 Mock，前端按 Mock 数据先写页面，后端完成后再把环境切回真实地址；第三步，把核心链路（登录、下单、支付回调、对账查询）做成自动化测试场景，在流水线里每次合并请求后跑一次，并用 CLI 产出 HTML 报告存档。关键配置上，把「前置 URL」按环境区分，token 通过登录接口的后置脚本自动写入环境变量，任何人跑场景都不需要手工填凭据；CI 里的 access token 走流水线密钥变量注入。效果是联调等待时间大幅缩短，接口字段不一致导致的问题基本消失。踩过的坑：一是环境变量误写成全局变量，切到预发环境时请求仍打到测试环境，排查了很久才定位到脚本里用的是 pm.globals.set("baseUrl", ...)；二是Mock 期望优先级写反，本想「参数为特定值时返回错误结构」，结果被更宽泛的期望先命中，导致前端一直拿到成功响应；三是CI 里的令牌一度写死在配置文件中并提交进了仓库，发现后立即吊销重建，并改成密钥变量注入——这件事后来纳入了团队的安全检查项。

案例二：把接口回归接进流水线，做发布前门禁。背景是一个对外提供服务的系统，每次发版前靠人工点一遍核心接口，容易漏。做法是：把冒烟场景（约 30 个步骤，覆盖登录、核心读写、权限校验、错误码）做成一个 Apifox 测试场景，在流水线的「构建后、部署前」阶段执行；场景里对每个步骤都加了断言，不仅校 HTTP 状态码，还校业务码和关键字段的类型。门禁规则是：冒烟场景失败即阻断发布；全量回归场景（覆盖边缘分支）失败只告警不阻断，由值班同学判断。效果是发布前的人工验证时间大幅下降，且错误码回归这类「看着没坏其实坏了」的问题能被自动拦住。坑与解决：一是场景依赖固定测试账号，两个流水线并发跑时互相踩数据，后来给每次运行生成带时间戳的账号/订单号，并把清理步骤加进场景尾部；二是断言写得太严（比如断言了自增 ID 的具体值），环境一变就红，改成只断言「非空且类型正确」；三是报告只留在流水线里没人看，后来固定把 HTML 报告归档到构建产物中，并在失败时附上失败步骤的响应体，排查效率明显提升。