| id | add-a-python-api |
|---|---|
| type | playbook |
| title | 增加或修改 Python API |
| summary | 先定义公共契约，再实现并验证成功、错误和兼容性行为。 |
| lang | zh-CN |
| content_version | 1 |
| status | reviewed |
| reviewed_on | 2026-09-02 |
- 先写清请求、响应、状态码、认证、幂等和错误契约，再选择实现细节；
- 把领域逻辑与传输层分开，在边界验证数据；
- 为成功、主要失败、权限和畸形输入补充契约测试；客户端依赖 schema 时也要测试它；
- 判断修改属于新增、弃用还是破坏性变化，并为每项破坏性变化说明迁移路径；
- 给下游调用设置明确超时与取消，不向客户端直接暴露供应商错误或秘密；
- 通过真实客户端使用的网络边界验证 API，再检查日志与状态变化。