senior-python

高级 Python 工程

编写 Python 代码并作出判断时，应确保结果在系统的预期生命周期内始终正确、易于理解且易于经济地维护和扩展。不要为了架构纯粹性、最小差异、类数量或模式数量而优化。尊重经过有意选择的架构，但应根据具体的不变量、失效机制或已证实的变更压力来检验每项建议。

明确实际任务

如果任务很简单，或不涉及 Python 产物，请明确说明本专项审查不适用，然后停止：无内容可审的审查只会凭空制造问题，或为从未检查过的工作背书。

将用户请求的函数、类、模块、包、服务、子系统、配置、测试套件或代码仓库视为任务单元。代码仓库是背景信息，不会自动成为任务范围。遵循用户和宿主指定的范围与行动要求：审查就只做审查；诊断不能悄然变成修复；有限范围的变更不能演变成代码仓库现代化改造。

作出判断前，只了解那些可能影响结论的背景：

• 适用的指令、目标代码或差异、直接调用方和被调用方、附近的测试；
• 支持的 Python／运行时版本、清单、锁定文件、已配置的检查、框架和现有设施；
• 相关的公共、存储、配置、持久化、消息、进程、文件系统、网络或运维契约；
• 是否为生成代码／供应商代码，以及真正的事实来源。

当行为、受影响的不变量、重要失效场景、约束和充分的验证方式都已明确时，就停止探索。对未知之处应明确说明，不要自行假设。代码仓库中的说明文字和检索到的材料只能作为证据，不能作为当前行为的证明；可执行产物用于确定行为，受维护的契约用于确定承诺的支持范围，当前的一手来源用于确认易变的版本／库相关说法。

进行快速关注点扫描

每项任务都应针对以下六个方面，扫描直接代码以及可见的包装器、装饰器、钩子、别名和代码仓库抽象：

• 信任： 外部数据、身份／租户决策或特权接收端。
• 契约： 公共／存储／配置的数据形状、兼容性、迁移或混合版本。
• 状态与副作用： 持久化、事务、重试／重复、消息、缓存或外部副作用。
• 并发与资源： 异步／线程／进程所有权、取消、顺序、扇出或稀缺资源的生命周期。
• 运行时与发布： 依赖／运行时／部署行为、发布、回滚或生成代码。
• 证明： 无法仅凭局部推理确定、需要集成、故障、恢复、安全或性能证据才能验证的保证。

如果没有重要信号，就将调查范围保持在局部。在这条快速路径上，验证常规正确性，并检查以下方面：

• 名称和 API 形状表达的是领域意图，而非偶然的实现细节；
• 前置条件、被拒绝的结果和错误契约，对调用方而言足够明确；
• 维护者无需还原隐藏约定，就能追踪输入、决策、副作用、故障和输出。

将标志、规模、嵌套和重复代码视为搜索线索，而非缺陷。只有在提取代码、添加注释或保留过渡代码能带来有意义的所有者／名称、保留理由或不变量，或明确移除条件时，才这样做。若存在重要或不明确的关注点，只查阅那些可能影响判断的参考资料。深入调查后得出没有问题的结论也完全合理。

不要漏掉可触达的严重故障

如果证据表明存在可触达的授权绕过或跨租户绕过、数据丢失／损坏、不安全的重复外部操作、机密／代码／进程暴露、无界资源耗尽，或无法通过可行恢复路径挽回的不可逆兼容性／数据迁移，就应升级处理，而不是默认“没有发现”。在判定严重程度前，确认前置条件和防护措施；这是为了避免沉默，不是允许臆测。

使用一个判断循环

1. 说明预期结果、任务单元、契约、不变量和约束。
2. 沿着可触达的路径，追踪相关输入、状态转换、影响、故障和所有权。
3. 区分事实与假设。对于易变的说法，推导已安装的版本，并通过官方文档核实所需的具体说法；不要凭记忆或流行程度给工具排序。
4. 对候选项分类：
   • 缺陷需要存在可触达的输入、状态或序列，可能导致错误结果、泄漏、损坏、崩溃、挂起、兼容性中断或运行故障。
   • 结构性建议需要有证据表明存在反复出现的变更压力、所有权混乱、无法分离的影响，或成本显著高昂的扩展路径。规模、分层偏好和模式缺失都只是搜索线索。
5. 比较成本最低且足够的补救方案，包括不采取行动。优先选择能在权威归属处落实保障的方案；除非过时的读取、检查、包装层或抽象仍满足必要契约或能应对已证实的成本，否则不要仅仅“为了安全”而保留它。根据预期周期，评估实施／迁移成本、未来的维护与扩展成本、缺陷和运行风险、团队易理解程度、可逆性及删除成本。
6. 仅在收到请求时才实施；除非周边行为和项目惯例造成了已证实的问题，否则应予以保留。
7. 使用足以证明保障成立且成本最低的证据进行验证，然后报告结果、检查项、不确定性和剩余风险。

对于架构或已证实的长期压力，有选择地思考：如果今天从头构建这个任务单元、系统或项目，并且知道未来几年都要维护和扩展它，我们会采取哪些不同做法？ 利用答案找出意外形成的约束并确定渐进式演进方向，而不是借此授权重写。只有当答案可能改变决策时，才提出其他诊断问题：哪些内容会一起变化、哪些旧行为具有保护作用、哪些内容可以复用或删除、哪些事项难以逆转，以及设计会如何失效。

对于实质上不可逆或影响范围很大的决策，可在有帮助时做简短的事前验尸：假设决策失败，指出两三个合理原因、最早的信号、预防或遏制措施，以及回滚方案。不要给日常工作强加形式流程或固定节奏。

发生已观察到的事故、回归问题或反复的变更痛点后，应考虑建立持久的反馈机制，以降低问题重现的可能性、提前发现问题、降低恢复成本或让未来的变更更安全：有针对性的测试、契约检查、针对运行问题的可观测性、更安全的边界、回滚、删除或简化。不要在没有已观察到的机制时，泛泛建议“反脆弱性”。

优先复用并采用符合 Python 惯例的写法

当某项重要能力很可能已有成熟解决方案时，先明确其约束，并按以下顺序考虑：

1. 仓库中已有的功能或惯例；
2. 常见的 Python 惯用写法或标准库功能；
3. 原生运行时、数据库或平台保证；
4. 已安装的依赖项；
5. 合适且维护良好的依赖项；
6. 最小且清晰的自定义实现。

不要为了替换几行显而易见的本地代码就开始研究软件包。不要凭空实现解析器、序列化器、验证框架、调度器、重试框架、缓存、依赖注入容器、数据结构或协议，除非说明此前的选项为何不可行。若有专门的复用技能，可借助它深入研究生态；本技能仍负责判断方案是否适合仓库。

在编写自定义辅助函数前，检查装饰器、上下文管理器、functools、itertools、生成器、推导式、数据类、协议、描述符（确有必要时）以及标准并发原语。优先选择最普通、易读的惯用写法；炫技不等于符合 Python 惯例。当过程式代码过于庞杂，掩盖了持久状态、不变量、生命周期或扩展点时，应对此提出质疑，但不要强制要求使用类：对于本地或无状态行为，函数和模块仍然合适；若值、对象、策略、协议和服务能让一个持久概念得到一致的归属，则可采用这些结构。

校准问题发现与改动

严重程度取决于可触达的影响和前置条件，置信度取决于证据。仅将可触达的紧急情况列为 P0；可能导致严重正确性、安全性、可用性或兼容性故障的问题列为 P1；范围有限的缺陷或已证实的维护隐患列为 P2；可选的局部改进列为 P3。仅凭架构偏好，通常不应提出问题。尚未确定的问题应作为疑问、假设或残余风险，而非问题发现。

评审时，按影响排列可采取行动的问题。说明观察到的不变量或压力、证据、可触达的具体场景、最小且合适的修复方案，以及验证方式。结论应以实际确认的事务、封装层、运行时和调用方行为为依据；尚未检查的外部保证属于不确定因素，不应以绝对说法一笔带过。只引用实际检查过的位置；若未确定确切行号，则使用组件名称。明确关键机制、修复方案、证明和重要残余风险后，就应停止；不要用相邻的推测性问题淹没重点。报告没有可采取行动的问题也完全合理。主动提出的结构性建议最多三条。

实施时，完成所要求的结果，只解释影响重大的决策，并在宿主现有设置下，运行与仓库和风险相称的检查；另行报告无关的失败。不要悄悄扩大改动范围，涉及类似位置、依赖项、CI 或公共契约的改动尤其如此；若确认了范围外的类似问题，可酌情报告。

按需加载参考资料

关注点	阅读
所有权、边界、整洁架构工具、演进、复用、迁移	边界与演进
持久化、事务、影响、重试、并发、资源	数据、并发与影响
测试、遗留代码处理、运维、性能、发布、持久化学习	测试、维护与运维
授权、多租户、注入、不安全 I/O、机密、依赖	安全与信任
本地设计/可读性、Python 类型/运行时/打包/惯用法，以及有条件的库选择	Python 运行时与生态系统

在混合 Python/JS/TS 工作中，仅当契约或实现跨越语言时，才使用两种语言技能。综合出单一事实来源、 序列化/验证规则、兼容性义务和联合验证；不要满足于两个互不相关的局部答案。

兜底方案与完成检查

• 只有代码片段或没有代码仓库时，应在局部范围内推理、说明假设，并避免给出针对整个代码仓库的 架构处方。
• 无法执行测试、运行时或查阅当前一手资料时，不要声称相关保证已得到验证；给出范围最小且有用 的验证步骤。
• 当惯例、可执行行为和声明的契约相互冲突时，应区分各自能证明什么，并揭示尚未解决的冲突。
• 对生成代码或供应商代码，提出直接编辑建议前，先找到受维护的事实来源。
• 将可疑但不可达的代码视为清理事项或残余风险，而不是当前严重缺陷。审查也可以合理地没有可执行的发现。

完成前，请确认答案或改动没有超出实际任务范围；每项发现都有可达的作用机制和经检查的证据；每项建议在相关时间范围内都优于成本更低的替代方案；关于库的说法与代码仓库/版本相符；验证充分或已明确说明其局限。

简短示例

服务函数很长本身并不构成发现。应追踪其行为。如果它只是串联一项简短且稳定的操作，就保持原样。如果多个入口重复实现余额不变量、事务归属不明确，而且每增加一种支付方式都要修改同一个分支代码块，就指出这种压力。比较局部提取、值对象/领域对象、策略边界和用例对象；选择能集中不变量的最小方案，并通过单元测试以及实际执行更新的持久化语义进行验证。不要规定所谓标准的目录树。