运维手册

接口管理：YApi 契约、Mock 与测试环境隔离

管理接口版本、脱敏样例和测试授权，核查导入覆盖、契约漂移及 MongoDB 数据恢复。

接口管理：YApi 契约与环境治理

YApi 在本蓝图中保存接口定义、请求响应样例、Mock 与测试集合，服务开发、测试和产品协作。官方项目提供接口调试、响应断言及多种文档导入能力；具体插件与格式兼容性应按选定代码版本验证。YApi 官方说明

接口管理平台不是生产 API 网关，不负责为业务接口实施最终鉴权、限流或审计保全。Mock 返回正确不代表真实服务正确，文档发布成功也不等于接口已经上线。全部接入、测试调用和迁移演练都待目标环境授权。

先确认官方项目、选定维护分支或发行包、Node.js 与 MongoDB 兼容性、插件来源和安全审查结果。官方 README 中包含较早的环境与安装示例，不能将其中最低版本或第三方镜像直接当作当前生产基线；本方案不提供未经核验的一键安装命令。

每个项目登记接口负责人、契约来源、批准的测试环境、数据等级及对外共享范围。确定契约以代码生成还是平台编辑为准，避免双方定时覆盖。认证令牌、Cookie、真实个人信息和数据库连接串不进入 Mock、导入文件或公开文档。

先创建隔离试点项目，导入一组脱敏接口样例，并比较路径、方法、参数、必填项、错误码和嵌套字段。导入前导出现有定义并预览覆盖范围，对同路径同方法重复项形成明确处理规则，不能直接全量覆盖团队共享项目。

将接口变更与 GitLab 提交、禅道需求和 Jenkins 构建关联。破坏性变更必须给出调用方清单、兼容窗口及旧字段退出方案。Mock 仅使用合成数据；测试集合按环境拆分，默认选择隔离测试入口，禁止从通用测试节点自动访问生产内网。

检查文档更新时间与实际发布版本是否偏离、失败测试是否被长期忽略、项目成员是否仍有业务需要，以及分享链接是否超出受众。抽查鉴权失败、分页边界、空值、超长请求与错误码，而不只保留正常返回样例。

测试执行前识别创建、删除、发消息、扣减等有副作用的接口，准备专用测试账号和可清理数据。巡检只读测试也需限制频率与响应保存范围，不把包含令牌的调试结果复制到公开站点。平台自身同时观察响应耗时、MongoDB 连接和存储容量。

导入失败先校验文件格式、大小和解析错误，确认插件支持范围；导入成功但字段消失则比较导入前快照和重复覆盖规则。Mock 正常而真实接口失败，按 DNS、TLS、网络出口、认证、参数和业务依赖逐段排查，不通过关闭证书验证来“修好”测试。

多项目同时无响应时检查应用与数据库依赖；个别项目看不见时核对项目权限和成员状态。测试脚本出现异常外联或敏感数据时，停止该集合执行并保留脱敏证据，由负责人评估令牌吊销和数据影响。

本方案要求同时登记 MongoDB 数据、应用配置、插件及选定代码版本；接口导出文件只是可移植的内容副本，不能默认包含所有成员、权限、测试状态和密钥。备份方法按实际数据库拓扑设计，避免把运行中的数据目录直接复制视为一致备份。

在隔离实例恢复后，对照项目数、接口数、目录、测试断言和成员权限抽验；测试出口先关闭，防止恢复的定时任务访问真实业务。恢复点之后的编辑需从受控变更记录补回，不直接覆盖仍在协作的生产项目。

要求证明跨项目权限拒绝、敏感字段不进入样例、导入前后差异可审阅、契约测试使用正确环境，以及恢复后核心接口定义可用。维护来源不明、运行时安全评估未完成、无法隔离有副作用测试或现有项目没有导出恢复点时，停止扩大使用。

功能入口参照 YApi 项目维护者文档；运行环境需回到所选版本核验，不能将文档页展示的历史版本当作本平台推荐版本。可与代码仓库手册建立契约来源追踪。