本地 API 契约

先沿实际客户端、接口实现、OpenAPI/DTO 和契约测试确认已有约定：认证、错误封装、状态码、分页和字段命名。已有消费者的行为是兼容边界，不因上游示例推荐 REST 风格就重命名路由、改统一返回结构或切换版本。

需要作出的判断

• 区分新增接口与破坏性变更。新增可选字段通常比删除字段、改类型或改变 null 语义更容易兼容；列出真实消费者，必要时安排并存或迁移，而不是只更新服务端测试。
• 参数校验包括类型、长度、枚举、页大小和排序范围。排序键映射到服务端允许的字段；租户与资源访问范围来自可信认证上下文，不能由请求参数决定。
• 沿已有分页机制选 offset 或 cursor。cursor 分页需要稳定排序及唯一兜底字段，明确筛选条件变化时的行为；“列表查询能返回”不能证明翻页无遗漏或重复。
• 对可能被重试的写入明确幂等语义。幂等键需绑定调用方、操作和请求内容，解决并发首次请求、相同键不同内容及结果复用；不能仅通过前端禁用按钮保证。
• 去重状态与业务提交保持可恢复一致，避免业务已成功但结果未记录时再次执行，或失败请求永久占用键。核对进程重启、键保留期及重复请求的恢复路径；旧客户端未提供幂等键时，不能承诺任意重试都能去重。
• 延续既有 HTTP 状态码与错误结构。新接口根据语义区分创建、异步受理、校验、认证、授权、冲突与限流；不要给成功状态放错误内容，或在响应暴露内部栈和敏感字段。

验证与交付

选择能暴露本次契约变化的请求、响应和消费方测试，覆盖与改动有关的缺字段、非法值、权限、分页边界或重复请求。有服务环境时做真实 HTTP 调用；只有单元测试或 mock 时说明边界。输出改动后的契约、兼容性判断、执行证据及消费者迁移事项。具体库接口先按锁定版本查官方文档。