python-services

Python 服务与 CLI

工作规则

• 在边界处验证外部输入和响应；保留异常原因。
• 区分缺失结果与空结果。 当空集合表示成功时，应要求响应中包含该字段，而不是默认将其设为空；全默认值模型可能会将 {} 验证为成功。通过真实的验证边界测试缺失、拼写错误、明确为空和已填充的载荷。
• 简单的顺序任务保持同步。限制并发任务数量，保留取消能力，并保留任务引用。
• 为网络调用设置超时；仅重试失败，以及语义允许重试的操作。
• 通过原子写入和数据库约束确保作业幂等性。
• 保持已发布的 API 行为和共享的迁移历史。
• 让遥测数据对应实际运维问题，并验证其输出。

规范

• 简单优先：每项更改都应尽可能简单，影响的代码尽可能少
• 只修改必要内容；避免引入无关更改
• 不要使用投机取巧的变通方案：如果修复方案感觉不对，就退一步，实施干净的解决方案
• 添加新的抽象前，先确认它会在至少 3 处用到。否则就内联实现。
• 验证：参见下方的“验证”部分；完成前，所有检查都必须通过且零警告

验证

• uv run pytest 通过，且零失败
• uv run ruff check . 通过，且零警告
• uv run ty check . 通过，且零错误
• 覆盖率目标：80% 以上（uv run pytest --cov；添加 --cov-report=html 可生成可浏览的报告）

特定任务参考

实现或审查对应行为前，请先阅读相关参考文档：

• 对于打包、环境配置、CLI 设置或 pytest 行为： tooling-and-tests.md。
• 对于 asyncio、后台作业、重试、连接池、超时或健康检查： concurrency-and-resilience.md。
• 对于 API、验证、错误、迁移、日志、指标或追踪： service-boundaries.md。

适用于相应主题的现有专项参考文档：

• cli-tools.md。
• fastapi.md。