FastAPI 必须写 Type Hints 才能启用自动校验、文档生成和 IDE 补全；缺失类型提示会导致接口契约模糊、数据校验失效、协作成本上升，且需配合 mypy/pyright 和 Pydantic 模型规范落地。
FastAPI 里不写 Type Hints 就等于没写接口契约
FastAPI 的核心能力（自动校验、文档生成、IDE 补全）全部依赖 type 注解驱动。如果只写 def create_user(name)，它根本不知道 name 是字符串还是字典，更不会帮你拦截前端传来的 {"name": null} 这类非法数据。
实际协作中，后端不加类型提示 → 前端反复问“这个字段能传空吗？”“数组里元素是 int 还是 str？”→ 沟通成本飙升。而加上 name: str 和 tags: list[str] | None = None，Swagger UI 自动渲染出明确约束，连测试用例都能自动生成。
- 必填字段用普通类型，如
email: str；可选字段用Optional[str]或str | None（Python 3.10+） - 路径参数、查询参数、请求体都必须标注，否则 FastAPI 不做校验也不进文档
- 嵌套模型必须定义为 Pydantic
BaseModel子类，不能只用dict或Any
mypy 检查时总报错 "Cannot find implementation or library stub"？
这是新手最常卡住的点：你写了 from fastapi import FastAPI，mypy 却说找不到 FastAPI 类型定义。原因不是你代码错了，而是 mypy 默认不加载第三方库的类型存根（stub）。
解决方法很简单，但容易漏掉一步：
立即学习“Python免费学习笔记（深入）”；
图片提示词生成器？不止如此。 马甲系统 —— 把脑海中的画面，翻译成AI能理解的专业表达。 用得越多，它越懂你：首次需要多问几句确认方向，用久了几乎一说就懂。 用得越多，它越快：缓存机制让后续对话越来越省。 RAG进化：成功案例持续入库，越跑越聪明。 输入「新手指南」查看完整功能介绍
- 先装类型存根：
pip install fastapi[all]（官方推荐）或pip install types-fastapi - 确保
pyproject.toml里有[tool.mypy]配置段，并启用plugins = ["pydantic.mypy"]（如果用了 Pydantic v2） - 检查 Python 版本是否 ≥ 3.8 ——
mypy对低版本的typing支持不全，比如Literal在 3.7 下会报错
团队里有人不写类型，怎么低成本推动落地？
强制全员一次性补全所有函数类型不现实。更有效的是从“高频痛点”切入，让效果可见：
- 把 CI 流水线里的
mypy --disallow-untyped-defs改成--disallow-incomplete-defs：允许无注解函数存在，但一旦写了参数就得标类型，渐进式推进 - 在 pre-commit hook 中加入
pyright（比 mypy 更快、对 VS Code 友好），保存即提示，开发者不用切终端 - 重点盯死 API 入口函数和 DTO 模型类——这两个地方类型错一个，下游至少五个人要调试
Union 和 Optional 写法混乱导致 IDE 提示失效
比如写 status: str | None 没问题，但写成 status: Optional[str] 且没导入 from typing import Optional，VS Code 就无法推导 status 可能为 None，补全和高亮全丢。
Python 3.10+ 推荐统一用 | 语法，但要注意兼容性陷阱：
-
list[int] | None合法，但list[int | None]≠list[int] | None—— 前者是“元素可为空的整数列表”，后者是“整个列表可能为空” - 避免混用：同一项目不要一半用
Optional[T]，一半用T | None，pyright会警告 “inconsistent union style” - 复杂嵌套如
dict[str, list[dict[str, int | float]]]，建议拆成命名类型别名，否则 IDE 解析延迟明显
类型提示不是越多越好，而是关键路径上不能含糊。一个 id: int 写错成 id: str，可能让数据库查询走错索引；一个 price: float 没标，前端传字符串进来就静默转成 0.0——这种 bug 往往要到线上才暴露，而类型系统能在保存文件那一刻就拦住它。
