Python函数注解的核心价值是静态类型检查、IDE提示和可维护性提升，关键在于正确使用标准语法、渐进式落地、接入mypy等工具链检查，并合理处理动态场景。
Python函数注解（Type Hints）不是装饰器，也不影响运行时行为，它的核心价值在于静态类型检查、IDE智能提示和代码可维护性提升。落地关键不在“写不写”，而在“怎么写才可持续”。
用对语法：函数注解 ≠ 字符串文档
错误写法是把类型信息塞进docstring或当注释用：
def add(a, b):
"""a: int, b: int -> int""" # ❌ 类型信息藏在字符串里，工具无法识别
return a + b
正确写法是使用标准注解语法（Python 3.6+）：
- 参数后跟: 类型，返回值后跟-> 类型
- 基础类型直接写：
int、str、bool、float - 容器类型用
typing模块（3.9+ 可用内置如list[int]，但兼容性需权衡）
示例：
立即学习“Python免费学习笔记（深入）”；
macOS UI 自动化技能包 —— 用 Python 控制你的 Mac
下载
让 macOS 自动化像说话一样简单 —— 用代码控制你的 Mac，无需学习 AppleScript 系统要求 macOS 14+ (Sonoma) Python 3.9+ 需要开启：辅助功能 + 屏幕录制权限
from typing import List, Optional, Dict <p>def process_users( user_ids: List[int], config: Optional[Dict[str, str]] = None ) -> List[str]: ...
渐进式落地：从关键函数开始，不强求全覆盖
全量补注解成本高、易出错，推荐分层推进：
- 优先覆盖：公共接口函数（API入口、SDK方法）、核心算法函数、跨模块调用函数
-
暂缓处理：临时脚本、单元测试内部辅助函数、明显只用一次的私有方法（如
_parse_line） -
标记待补：对暂未注解的函数加
# type: ignore或TODO注释，避免被mypy误报
配合工具链：注解只有被检查才有意义
光写注解不检查，等于没写。必须接入静态检查工具：
- mypy：事实标准，支持完整PEP 484，建议作为CI必检项
- pyright / pylance：VS Code默认语言服务器，实时提示友好
-
pylint：开启
missing-function-docstring和missing-type-doc等扩展规则（注意区分docstring类型说明和真实注解）
CI中建议配置mypy严格模式（--disallow-untyped-defs --disallow-incomplete-defs），但初期可先用--check-untyped-defs降低门槛。
处理动态场景：别让类型提示成为包袱
真实项目常有弱类型逻辑（如JSON解析、ORM字段、配置字典），硬套严格类型反而难维护：
- 用
Any要谨慎，优先考虑Union或更具体的协议（如TypedDict） - 对不确定结构的dict，定义
TypedDict比Dict[str, Any]更有价值 - 函数可能返回多种类型？用
Union[Success, Error]或Optional[T]，而非回避注解 - 需要运行时类型分支？结合
isinstance+cast（来自typing）做安全转换
