id	python-product-quality
type	guide
title	构建能够持续修改的 Python 产品
summary	从有用脚本走向可运行、可维护 Python 产品的一套实用质量模型。
lang	zh-CN
content_version	1
status	reviewed
reviewed_on	2026-09-02

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

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

1. 从一个用户结果开始

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

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

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

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

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

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

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