在 Python 项目中引入 mypy 静态类型检查…

适合为 Python 代码库添加类型安全、在 CI 中强制类型检查，或为 FastAPI/Django 项目集成类型提示。

适用场景

解决思路

1. 安装 mypy 及常用类型存根：`pip install mypy`；常用存根 `pip install mypy types-requests types-PyYAML types-redis`；FastAPI 项目 `pip install mypy pydantic`；Django 项目 `pip install mypy django-stubs`；开发环境 `pip install mypy pre-commit`。
2. 为变量添加类型提示：使用基本类型如 `name: str = 'Alice'`、`age: int = 30`；可依赖类型推断如 `count = 10`；使用 `Union[int, str]` 表示多类型；使用 `Optional[str]` 表示可空。
3. 为函数添加类型提示：标注参数和返回值，如 `def greet(name: str) -> str:`；为默认参数标注，如 `age: int = 18`；无返回值用 `-> None`；永不返回用 `-> NoReturn`。
4. 为集合添加类型提示：使用 `List[int]`、`Dict[str, int]`、`Set[int]`、`Tuple[float, float]`、`Tuple[int, ...]`；Python 3.9+ 使用 `list[int]`、`dict[str, int]`。
5. 为类添加类型提示：声明类属性类型；在 `__init__` 中标注参数和 `-> None`；为方法标注返回类型；`@classmethod` 返回 `'User'` 或 `cls` 类型。
6. 使用 `Literal` 类型限制取值：如 `Literal['debug', 'info', 'warning', 'error']`，让 mypy 拒绝不在字面量集合中的值。
7. 使用类型别名和 `NewType` 创建语义化类型：如 `UserId = int`、`JSON = Union[...]`、`Headers = Dict[str, str]`；用 `UserId = NewType('UserId', int)` 区分不同 ID。
8. 使用 `TypeVar` 和 `Generic` 创建泛型函数与类：`T = TypeVar('T')`；`def first_element(items: List[T]) -> T:`；`class Stack(Generic[T]):`；可用 `NumericType = TypeVar('NumericType', int, float)` 限定类型。
9. 使用 `Protocol` 实现结构化类型：定义 `class Drawable(Protocol): def draw(self) -> str: ...`；任何有 `draw()` 方法的类都匹配；用 `@runtime_checkable` 支持 `isinstance` 检查。
10. 使用 `Callable` 标注函数参数：如 `Callable[[int], int]`；泛型 `Callable[[T], R]`；类型别名 `Validator = Callable[[str, int], bool]`。
11. 编写 `mypy.ini` 配置：设置 `python_version`、`files`、`exclude`；严格性如 `disallow_untyped_defs = True`、`no_implicit_optional = True`、`warn_return_any = True`、`warn_unused_ignores = True`、`warn_redundant_casts = True`；错误报告如 `show_error_codes = True`、`show_column_numbers = True`、`pretty = True`；增量如 `incremental = True`、`cache_dir = .mypy_cache`；per-module 如 `[mypy-tests.*]`、`[mypy-migrations.*]`、`[mypy-redis.*]`。
12. 编写 `pyproject.toml` 的 `[tool.mypy]` 配置：设置 `python_version`、`files`、`exclude`；严格性如 `disallow_untyped_defs = true`、`strict_equality = true`；错误报告如 `show_error_codes = true`、`color_output = true`；增量如 `incremental = true`、`cache_dir = '.mypy_cache'`；用 `[[tool.mypy.overrides]]` 按模块覆盖。
13. 使用 `--strict` 或等效 flags 开启严格模式：运行 `mypy --strict src/`；或手动组合所有严格 flags 如 `--disallow-any-unimported`、`--disallow-any-expr`、`--disallow-untyped-defs`、`--no-implicit-optional`、`--warn-redundant-casts`、`--warn-unused-ignores`、`--warn-return-any`、`--warn-unreachable`、`--strict-equality`；如需放宽，可在 `mypy.ini` 中设置 `strict = True` 并单独关闭 `disallow_any_expr` 等。
14. 增量采用：从入口文件开始检查，如 `mypy main.py`；逐步扩大检查范围，如 `mypy main.py app/services.py`、`mypy src/`。
15. 按模块逐步启用严格模式：在 `mypy.ini` 中全局保持宽松，然后为特定新模块设置 `disallow_untyped_defs = True`、`warn_return_any = True`；对遗留模块设置 `ignore_errors = True`。
16. 在迁移中策略性使用 `# type: ignore`：使用带错误码的忽略，如 `# type: ignore[import]`、`# type: ignore[no-untyped-def]`、`# type: ignore[index]`；尽量少用整行忽略，并加注释说明原因。
17. 使用 `reveal_type` 查看推断类型：在代码中插入 `reveal_type(variable)`，运行 mypy 后查看它显示的类型。
18. FastAPI 集成：用 Pydantic `BaseModel` 定义模型；为端点函数标注参数和返回类型，如 `def read_user(user_id: int) -> User`；为 `list_users` 返回 `List[User]`。
19. 异步 FastAPI 类型检查：为 `async def` 端点标注返回类型；为异步依赖函数标注返回类型，如 `async def get_db() -> AsyncSession:`；在端点中使用 `db: AsyncSession = Depends(get_db)`。
20. FastAPI 依赖注入类型：使用 `Annotated` 标注依赖，如 `current_user: Annotated[User, Depends(get_current_user)]`；使用 `Annotated[AsyncSession, Depends(get_db)]`；为依赖服务类定义类型化构造函数。
21. Django 集成：安装 `django-stubs`；在 `mypy.ini` 中设置 `plugins = mypy_django_plugin.main` 和 `[mypy.plugins.django-stubs]` 的 `django_settings_module`。
22. Django 模型类型提示：为模型字段添加类型标注，如 `email: models.EmailField = models.EmailField(unique=True)`；为模型方法标注返回类型；`@classmethod` 返回 `models.QuerySet['User']`。
23. Django 视图类型提示：为视图函数标注 `HttpRequest`、`HttpResponse`、`JsonResponse` 和返回类型；使用 `get_object_or_404` 等。
24. 安装第三方类型存根：运行 `pip install types-requests`、`pip install types-PyYAML`、`pip install types-redis`、`pip install types-boto3`；用 `mypy --install-types` 自动安装缺失存根。
25. 创建自定义 stub：在 `stubs/` 目录下创建 `.pyi` 文件，如 `stubs/external_lib.pyi`，声明类和方法签名；在 `mypy.ini` 中设置 `mypy_path = stubs`。
26. 忽略缺失导入：在 `mypy.ini` 中按模块设置 `ignore_missing_imports = True`，如 `[mypy-redis.*]`、`[mypy-celery.*]`，或用 `[mypy-celery.*,redis.*,boto3.*]`。
27. GitHub Actions 集成：创建 `.github/workflows/type-check.yml`；在步骤中设置 Python、安装 mypy 和依赖、安装类型存根；运行 `mypy src/`；对新增代码运行 `mypy --strict src/api/`。
28. Pre-commit hook 集成：在 `.pre-commit-config.yaml` 中添加 `pre-commit/mirrors-mypy` 仓库和 hook，`args: [--strict, --ignore-missing-imports]`，`additional_dependencies` 加入类型存根；运行 `pip install pre-commit` 和 `pre-commit install`。
29. Makefile 目标：添加 `typecheck`、`typecheck-strict`、`typecheck-report` 目标，分别运行 `mypy src/`、`mypy --strict src/`、`mypy src/ --html-report mypy-report`；可组合到 `ci` 目标。
30. 使用 `@overload` 为函数提供多个签名：定义多个 `@overload` 声明；最后写实现函数并用 `Union` 接收所有参数类型；让 mypy 根据输入推断返回类型。
31. 使用 `TypedDict` 定义结构化字典：定义 `class UserDict(TypedDict):` 并列出键和类型；函数参数和返回值使用 `UserDict`；mypy 会检查缺失键或错误类型。
32. 使用 `Final` 和 `@final`：用 `API_VERSION: Final = 'v1'` 定义常量；用 `@final` 装饰不可子类化的类；mypy 会拒绝重新赋值或继承。
33. 使用 `Self` 类型支持方法链：在返回 `self` 的方法中标注 `-> Self`，如 `def add(self, value: int) -> Self:`；支持类型安全的链式调用。
34. 根据场景选择 mypy 或 pyright：需要官方标准、Django/SQLAlchemy/Pydantic 插件、渐进式控制时用 mypy；需要更快检查、VS Code/Pylance 实时反馈、更严格默认、更好类型推断时用 pyright；可在 `pyproject.toml` 中同时配置 `[tool.mypy]` 和 `[tool.pyright]`，并在 CI 中运行 `mypy src/` 和 `pyright src/`。
35. 参考本地 mypy 配置模式：严格默认（如 `disallow_untyped_defs = true`、`check_untyped_defs = true`、`no_implicit_optional = true`、`warn_return_any = true`、`strict_equality = true`）；宽松配置（用 `disable_error_code` 列表临时关闭）；增量采用（`ignore_errors = true`）；忽略缺失导入（`ignore_missing_imports = true`）。
36. 最佳实践：先类型化关键业务模块；用类型别名提升可读性；公共 API 显式标注类型，内部辅助函数可依赖推断；用 `reveal_type` 调试；为 `# type: ignore` 添加原因注释。
37. 避免反模式：不要到处用 `Any`，应使用 `Protocol` 或具体类型；不要全局设置 `ignore_errors = True`，应只对遗留模块忽略；不要遗漏 `Optional`，应对可能为 `None` 的返回值显式标注并检查。
38. 使用常用 mypy 命令：`mypy main.py`、`mypy src/`、`mypy --strict src/`、`mypy --install-types`、`mypy src/ --html-report mypy-report`、`mypy --show-error-codes src/`、`mypy --ignore-missing-imports src/`、`mypy --follow-imports=silent src/`、`mypy --incremental src/`、`mypy --verbose src/`。
39. 识别常见错误码：`[attr-defined]`、`[arg-type]`、`[return-value]`、`[assignment]`、`[call-overload]`、`[index]`、`[operator]`、`[import]`、`[misc]`、`[no-untyped-def]`、`[var-annotated]`。

适用边界 · 注意事项

• 需要极快的大代码库类型检查或 VS Code/Pylance 实时反馈时，pyright 可能更合适。
• 项目完全使用动态类型且不打算逐步添加类型注解时，mypy 收益有限。
• 依赖大量无类型存根的第三方库且无法忽略导入时，类型检查噪音可能较大。