类型注解是接口契约，用于明确协作边界、支持静态检查与重构安全：优先用typeddict/dataclass替代dict/any，用protocol+typevar实现可替换抽象，收敛类型别名至types.py，配置mypy禁用误报项并启用增量检查。
类型注解不是装饰，是接口契约
在大型自动化项目里，类型注解最直接的作用不是让 IDE 更“聪明”，而是让函数、类、配置项之间的协作边界变得可读、可校验。比如一个调度任务函数 run_job 接收一个 job_config: dict，后续却要从中取 job_config["timeout"] 和 job_config["retries"] —— 这种隐式结构极易出错。换成 run_job(job_config: JobConfig)，配合 TypedDict 或 dataclass，IDE 能提示字段、mypy 能报错、新成员能一眼看懂约束。
常见错误现象：用 dict 或 Any 当万金油，结果改一个字段名，调用链上三处地方静默失败，直到运行时抛 KeyError 或 AttributeError。
- 优先用
TypedDict描述固定结构的字典（如 YAML 配置解析结果），它比Dict[str, Any]严格且无运行时开销 - 对需要实例化、带方法或默认值的对象，用
@dataclass+__post_init__做轻量校验，而不是把校验逻辑散落在各处 - 避免给参数加
Union[None, str]，直接用Optional[str]；mypy 对后者有专门优化，前者容易漏判
泛型和 Protocol 让抽象层真正可替换
自动化项目常有“多种执行器”场景：本地 shell、SSH、K8s Job、Airflow Operator。如果每个都写死类型，新增一种就得改所有调度入口。这时用 Protocol 定义最小契约，再配 TypeVar 约束泛型返回，就能做到“换实现不改调用”。
使用场景：封装统一的 execute(task: Task) -> ExecutionResult，但底层可能是 LocalExecutor、K8sExecutor，它们不需要继承同一基类，只要满足 Protocol 就行。
- 定义
class Executor(Protocol): def run(self, cmd: str) -> int: ...，比抽象基类更轻量，也更符合 Python 的鸭子类型习惯 - 泛型参数别滥用：
def retry[T](fn: Callable[[], T]) -> T:是合理的；但若T在函数体内只出现一次且无约束，不如直接写具体类型 - mypy 默认不检查
Protocol实现是否完整，需加# type: ignore[attr-defined]的地方越多，说明协议设计越松散——这不是类型系统的错，是接口没想清楚
mypy 配置必须关掉 “未使用导入” 类警告
自动化项目大量依赖配置驱动、插件注册、动态 import，mypy 默认开启的 unused-import 和 no-redef 会误报。比如从 plugins/ 目录自动加载模块，类型存根写在 plugins/__init__.pyi 里，但 mypy 会因“没在源码中显式 import”而标红 PluginClass。
仅使用 Python 将 Claw Code 虚拟化框架与 OpenClaw 集成，提供 184 种工具和 200 多条命令，用于安全分析和代码质量...
性能影响：开启 follow_imports = normal 会让 mypy 加载全部依赖类型信息，大型项目首次检查可能超 2 分钟；设为 silent 可提速 50%+，代价是跨包类型错误可能漏检。
- 在
mypy.ini中明确关闭：disable_error_code = unused-import, no-redef - 对动态加载模块，用
if TYPE_CHECKING:块做类型导入，既不污染运行时，又能让 mypy 看到类型 - CI 中建议用
mypy --incremental，并缓存.mypy_cache，否则每次全量检查成本太高
类型别名要收敛，别在每个文件里重复定义
像 JobId = str、Timestamp = float、RetryPolicy = Dict[str, Union[int, bool]] 这类别名，如果散落在十几个文件里，一旦某处改了定义（比如 JobId 改成 UUID），其他地方不会报错，直到运行时出问题。
容易踩的坑：用字符串字面量写前向引用（如 "JobConfig"）解决循环导入，结果拼错一个字母，mypy 不报错，因为当成了未解析的字符串。
- 所有公共类型别名统一放在
types.py，项目根目录下导出__all__，其他模块只从这里 import - 循环引用优先用
from __future__ import annotations（Python 3.7+ 默认启用），而不是字符串前向引用 -
RetryPolicy这种复杂结构，宁可用NamedTuple或dataclass封装，别用嵌套Dict+Union—— 可读性差，mypy 推导也容易崩
类型注解真正起作用的地方，往往不在写代码那一刻，而在三个月后你 grep 出来十处调用点，发现其中两处传了错误的 timeout 单位，而 mypy 已经帮你标红了那行 run_job(..., timeout="30s") —— 这时候才意识到，当初多花三十秒写个 Timeout = NewType("Timeout", int) 是值得的。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
