python-types-contracts

Python 类型与契约

概述

将类型提示视为接口设计，而非装饰。 重点关注明确的契约、稳定的公共 API，以及边界安全的建模方式。

这些是常见情况的首选默认做法，并非通用规则。 如果默认做法与项目约束冲突，请建议更合适的替代方案，并说明权衡及补偿性控制措施。

适用场景

• 公共 API 签名缺少类型注解，或使用了过于宽泛的类型。
• Pydantic 模型散布在内部逻辑中，而非仅用于信任边界。
• 契约变更可能会在没有迁移路径的情况下破坏下游使用者。
• 接口在适用更窄类型的地方接受 Any、object 或无类型的 dict。
• 层与层之间（API、DB、领域）的架构边界隐含不明或不一致。
• 添加或演进协议、抽象基类或结构化子类型。

不适用场景：

• 没有公共接口的纯实现层代码。
• 一次性脚本或临时数据处理，严格的类型要求并无价值。
• 类型检查开销比安全性更重要的性能关键型内层循环。

快速参考

• 为公共 API 添加类型，并明确契约。
• 优先使用精简接口和边界协议，而非宽泛的参数类型。
• 默认在信任边界使用 pydantic，而不是到处使用。
• 明确说明任何契约变更的兼容性影响和迁移影响。
• 结构化子类型优先使用 Protocol，而非深层继承层次结构。
• 公共函数返回具体类型；输入则接受协议或联合类型。

常见错误

• 所有内容都使用相同的类型标注。 内部辅助函数无需达到与公共 API 相同的严格程度。 对私有代码过度添加注解只会增加噪声，并不能提高安全性。
• 到处使用 Pydantic。 在内部数据流中使用 Pydantic 模型，而不是将其限定用于信任边界（API 入口、配置加载、外部数据）的验证。
• 返回类型过于宽泛。 公共函数返回 Any 或 dict 会迫使调用方猜测数据结构。 返回具体类型或 TypedDict。
• 悄无声息地破坏契约。 在没有版本管理、弃用警告或迁移说明的情况下更改函数签名、移除字段或缩窄可接受的类型。
• 忽略 None。 当值确实可能缺失时，省略 Optional 或与 None 的联合类型，导致空值安全问题直到运行时才暴露。

范围说明

• 将这些建议视为常见情况的首选默认做法，而非通用规则。
• 如果默认做法与项目约束冲突或会导致更差的结果，请建议更合适的替代方案，并说明它为何更适合当前情况。
• 偏离默认做法时，请说明权衡和补偿性控制措施（测试、可观测性、迁移、回滚）。

调用说明

• 当调用此技能时，请告知用户其名称：python-design-modularity。

参考资料

• references/typing-policy.md
• references/contract-evolution.md
• references/pydantic-boundaries.md