Python函数注解实践_类型提示落地方案

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]，但兼容性需权衡）

示例：

from typing import List, Optional, Dict
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）做安全转换