构建能够持续修改的 Python 产品

好的 Python 产品不取决于框架选择或代码数量。它要解决清楚的用户问题，在系统边界上行为稳定，并且能持续修改，而不是拿用户数据和生产环境碰运气。

从一个用户结果开始

先写一句具体的话：“给定这个输入，这类用户可以得到这个结果。“在选择框架前把它变成验收示例。如果结果无法观察，产品要求就还不能测试。

明确系统边界

让领域逻辑独立于 HTTP、数据库、文件、模型供应商和其他 API。在边界验证不可信输入，返回稳定的错误结构，并给每次网络调用设置超时。

像设计成功一样设计失败

提前决定哪些操作可以重试、哪些必须幂等、哪些需要人工确认。不要隐藏部分失败，要保留足够上下文，让用户或运维人员不必猜测就能恢复。

分层验证契约

用快速单元测试覆盖领域规则，用集成测试覆盖边界，用少量端到端测试覆盖真实用户路径。测试全绿只证明被实际执行的行为，不能证明没有覆盖到的部分。

让运行状态可见

使用结构化日志、请求或任务 ID、有意义的健康检查，以及与用户结果相关的指标。不要记录密钥、原始凭据或敏感数据。发生失败时，应能回答哪里失败、影响谁、如何恢复。

发布可回退的修改

固定运行时和依赖，记录配置；必要时把数据结构变更和应用发布拆开；部署前先定义回退方式。最后要通过真实用户接口验证线上行为，而不是只相信构建或部署输出。

把 AI、Agent、Skill、MCP 和 API 都当作边界

模型输出也是不可信输入。工具只获得完成任务所需的最小权限；结构化输出必须验证；时间和成本需要上限；工具调用要可追踪；不可逆操作应要求人工确认。Skill 或 MCP server 提高了复用能力，但不能替代认证、授权、测试与审计。

完成标准

• 用户结果和失败行为已经记录；
• 边界输入输出有类型并经过验证；
• 主要行为和恢复路径都有测试；
• 日志和健康信号能回答行动问题且不泄漏秘密；
• 已知发布与回退命令；
• 已通过真实用户路径检查生产行为。

来源

本指南的分层测试模型依据 pytest 官方文档，运行可观测性部分依据 Python logging 官方文档。

验证记录

关于作者

Organizational byline for FlyPython guides, verification records, and corrections. 编辑标准与联系方式 →