核心概念：从外部看 FastAPI 的编程模型

把这一章当成认人：每个概念先给一句话定义，再说它解决了什么手工活，然后钻到官方文档停笔的下一层讲机制——怎么实现的、代价是什么、何时失效。读完这七个词，看懂别人的 FastAPI 代码就不再需要靠猜。

1.1web 框架到底替你做了什么

web 框架是夹在操作系统的 socket 和你的业务函数之间、负责把字节翻译成对象再翻译回字节的那层代码。

底层机制（比文档深一层）：框架做的不是"处理请求"这种笼统的事，而是一条确定的字节翻译链。第一步是解析（parse）：把 GET /items/5 HTTP/1.1 这串字节拆成结构化字段——方法 GET、路径 /items/5、协议版本、各个 header、以及可选的请求体。第二步是路由（routing）：拿解析出的"方法 + 路径"去一张注册表里查，找到对应的处理函数。第三步是编码（encode）：把函数返回的 Python 对象序列化成 JSON 字节，再补上状态行 HTTP/1.1 200 OK 和 header，拼成完整响应送回。普通 web 框架到此为止；FastAPI 在第二步和第三步之间额外插入了"用类型注解校验输入"，在第三步额外插入了"用类型注解过滤输出"——多出来的这两刀，是后面六个概念的全部主题。

场景走查：浏览器发出 GET /items/5。操作系统把字节交给运行中的服务器进程 → 框架解析出 method=GET、path=/items/5 → 在注册表里查到 /items/{item_id} 这条记录绑定着名为 read_item 的函数 → 框架把 5 作为参数喂进去 → 函数返回一个 Python dict → 框架把 dict 编码成 JSON 字节加上响应头送回浏览器。整条链里你只写了 read_item 一个函数，其余都是框架的活。

与下一个概念的关系：上面那张"注册表"——把 URL+方法 映射到函数——就是下一个概念 path operation 的本体。

1.2path operation（路径操作）

path operation 是一个 (URL 路径 + HTTP 方法) 到一个函数的绑定，由装饰器在程序导入时登记。

底层机制（比文档深一层）：关键时机是导入时，不是请求时。Python 执行到 @app.get("/items/{item_id}") 这一行时（也就是模块被 import 加载的那一刻），装饰器立即运行：它把下面那个函数注册进 app 内部的路由表，并当场用 inspect.signature() 读出函数的完整签名——每个参数叫什么、是什么类型、有没有默认值。等到第一个请求进来时，路由表和签名解析早已就绪，请求阶段只是查表 + 套用早就算好的规则。这解释了一个常被忽略的事实：写错类型注解导致的报错往往在服务启动时就抛出，而不是等到那个端点被访问。官方对这套东西的术语是精确的：装饰器叫 path operation decorator，被装饰的函数叫 path operation function，两者合起来叫 path operation——不是 route，不是 endpoint，不是 handler。

from fastapi import FastAPI

app = FastAPI()

# @app.get(...) 在 import 这个模块时就执行：
#   1) 把 read_item 登记进 app 的路由表，键是 ("GET", "/items/{item_id}")
#   2) 立即 inspect.signature(read_item) 读出 item_id: int 这个签名
@app.get("/items/{item_id}")
def read_item(item_id: int):
    return {"item_id": item_id}

场景走查：请求 GET /items/5 如何匹配到 read_item。框架解析出 method=GET、path=/items/5 → 在路由表里逐条比对路径模式，/items/{item_id} 这条能匹配上，且其中 {item_id} 是一个占位段 → 框架抓出占位段对应的子串 "5" → 因为导入时已记得 item_id 的注解是 int，框架把 "5" 转换并校验成整数 5 → 调用 read_item(item_id=5)。同一个 path /items/5 配上不同的 method（比如 DELETE）会匹配到另一个 path operation，互不干扰。

与下一个概念的关系：上面"导入时读出签名、请求时按注解把 '5' 变成 5"这件事，揭开了本教程的核心命题——类型注解不只是提示，它是框架的运行时真相来源。

1.3类型注解即规约（全章核心）

在 FastAPI 里，函数参数的类型注解同时决定这个参数从哪来、按什么规则校验、在文档里长什么样。

底层机制（比文档深一层）：导入时框架用 inspect.signature() 拿到每个参数的注解后，按一套确定规则推断它的来源：

• 参数名出现在路径的 {} 里 → 它是路径参数（path parameter），从 URL 路径段取值。
• 注解是一个 Pydantic 模型（BaseModel 子类）→ 它是请求体（request body），从 HTTP body 的 JSON 取值。
• 注解是普通标量（int/str/float/bool）且名字没出现在路径里 → 它是查询参数（query parameter），从 URL 问号后面取值。

这套默认推断可以用 Path() / Query() / Body() 显式覆盖。推断出来源后，同一份注解被喂给四个不同的消费者：输入校验器、类型转换器、OpenAPI schema 生成器、以及编辑器的类型补全。一处声明，四处生效——这正是图 1.1 要画的事。

@app.get("/items/{item_id}")
def f(item_id: int, q: str | None = None):
    ...

场景走查：定义 def read_item(item_id: int, q: str | None = None) 绑定到 /items/{item_id}。导入时框架读签名 → 判定 item_id 为路径参数、q 为查询参数 → 同步生成一份 OpenAPI schema，记下"这个端点接受一个整型路径参数和一个可选字符串查询参数" → 运行时访问 /items/abc（路径参数给了非整数）框架直接返回 422、根本不调用你的函数；访问 /docs 则能看到这两个参数的交互式表单——全部出自那一行签名。

与下一个概念的关系：当注解不是 int 这种标量、而是一个自定义的数据形状（一个用户、一个订单）时，就需要 Pydantic 模型来声明这个形状。

1.4Pydantic 模型

Pydantic 模型是一个继承 BaseModel 的类，用字段的类型注解声明数据形状，从而自动获得校验与序列化能力。

底层机制（比文档深一层）：编译发生在类定义时，不是每次校验时。class Item(BaseModel) 这行被执行的瞬间，BaseModel 的元类（metaclass，控制类如何被创建的机制）遍历类里所有带注解的字段，把它们编译成一套校验器并缓存在类上。之后每次校验一个请求体，只是调用这套早已编译好的校验器，而不是重新解析字段定义。这与"类型注解即规约"是同一个时机哲学——代价前置到定义/导入时，换取请求时的速度。校验器的内核由 Rust 实现（03 章会拆开看这是 v2 比 v1 快 5–50× 的根源），这里只需记住：定义时编译一次，请求时调用 N 次。

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

# 类定义这一刻，元类就把三个字段编译成校验器并缓存在 Item 上
class Item(BaseModel):
    name: str
    price: float
    description: str | None = None   # 可选字段，缺省 None

# 注解是 Pydantic 模型 → item 被判定为请求体，从 JSON body 取值
@app.post("/items")
def create_item(item: Item):
    # 想把模型转回 dict 用 model_dump()（Pydantic v2），不是 v1 的 .dict()
    return {"received": item.model_dump()}

场景走查：客户端 POST 一个缺了 price 的 JSON {"name": "book"} 到 /items。框架从 body 读出这个 dict → 交给 Item 早已编译好的校验器 → 校验器发现必填字段 price 缺失 → 框架不调用 create_item，直接返回 422，响应体里精确标出 "loc": ["body", "price"]、"msg": "Field required"。整个过程你没写一行校验代码，错误定位却精确到字段。

与下一个概念的关系：Pydantic 模型用在输入侧能校验请求体；把同一类思路用在输出侧——声明响应该长什么样——就是 response_model。

1.5response_model

response_model 声明一个端点响应的类型，框架据此对返回值做过滤、校验，并生成响应侧的文档。

底层机制（比文档深一层）：返回值会被再跑一遍序列化。你的函数把对象 return 出来后，框架并不直接把它丢给 JSON 编码器，而是先用 response_model 声明的那个 Pydantic 模型的序列化器过一遍——只有模型里声明过的字段才会被读出来写进响应，模型里没有的字段被静默丢弃。这就是它能挡住数据泄漏的机制：过滤发生在"模型声明了什么"这一层，而不是"你返回了什么"。但要点清楚——这是输出过滤，不是鉴权。它能保证 password_hash 不出现在 JSON 里，但它不判断"当前这个调用者有没有资格看这条记录"。鉴权是另一件事（属于 Depends 的领域）。

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class UserOut(BaseModel):   # 对外契约：只暴露这两个字段
    id: int
    name: str

# response_model 指定返回值要过 UserOut 的序列化器
@app.get("/users/{user_id}", response_model=UserOut)
def read_user(user_id: int):
    # 故意返回一个带敏感字段的 dict
    return {
        "id": user_id,
        "name": "Ada",
        "password_hash": "$2b$12$xxxxx",   # 不在 UserOut 里 → 被静默过滤掉
    }

预期输出（访问 GET /users/7 的响应体）：

{"id": 7, "name": "Ada"}

运行环境：FastAPI 0.135.2 / Python 3.13

场景走查：函数从数据库取出完整 user 对象（含 password_hash）并返回 → 框架不直接序列化，而是先用 UserOut 的序列化器过滤 → 只有 id 和 name 被读出 → 编码成 JSON 送回。同时 /docs 里这个端点的"响应"部分会自动显示 UserOut 的结构——输出文档也来自这一处声明。

与下一个概念的关系：上面反复提到"谁有权调这个接口"该由别处管——那个"别处"就是 Depends：把鉴权、取数据库连接这类前置准备声明成可注入的依赖。

1.6Depends / 依赖注入

Depends 把"这个 path operation 执行前需要先准备好的东西"声明成一个函数，由框架自动调用并把结果注入进来。

底层机制（比文档深一层）：Depends(get_current_user) 里存的是未被调用的函数本身（注意没有括号——传的是 get_current_user 不是 get_current_user()）。框架拿到这个函数后，递归地用 inspect.signature() 读它的签名：如果这个依赖函数自己的参数里又有 Depends(...)，那就是它的子依赖，于是这些依赖关系连成一张图（graph）。请求到来时，框架对这张图做深度优先解析（先解析最底层的子依赖，再往上逐层调用），把每一层的返回值注入到需要它的地方，最后才调用你的端点函数。03 章会展开这张图的解析顺序、缓存策略和 yield 清理；这里要记住的核心是：Depends 存的是"配方"（怎么准备）而非"成品"，框架在请求时按配方现做。

from typing import Annotated
from fastapi import FastAPI, Depends, Header, HTTPException

app = FastAPI()

# 一个依赖：从 header 解析当前用户，逻辑只写这一次
def get_current_user(x_token: Annotated[str, Header()]) -> str:
    if x_token != "secret":
        raise HTTPException(status_code=401, detail="bad token")
    return "Ada"

# 现代写法：Annotated[类型, Depends(依赖函数)]
# 三个端点共用 get_current_user，各自不重复鉴权逻辑
@app.get("/profile")
def profile(user: Annotated[str, Depends(get_current_user)]):
    return {"viewer": user}

@app.get("/settings")
def settings(user: Annotated[str, Depends(get_current_user)]):
    return {"owner": user}

场景走查：三个端点 /profile、/settings、/orders 都在签名里写了 user: Annotated[str, Depends(get_current_user)]。请求 GET /profile 带着 header X-Token: secret 到达 → 框架看到 profile 依赖 get_current_user → 先调用 get_current_user（它自己又依赖一个 header 参数，框架先把 x_token 取出喂进去）→ 校验通过返回 "Ada" → 把 "Ada" 作为 user 注入 profile → 执行 profile 返回 {"viewer": "Ada"}。鉴权逻辑写一次，三个端点共享。

与下一个概念的关系：到这里六个概念里有五个——path operation、类型注解、Pydantic、response_model、Depends——全是 FastAPI 在每个端点外面加的那层封装。最后一个概念退后一步，看这层封装底下还站着谁。

1.7三层封装：FastAPI / Starlette / ASGI

FastAPI 是架在 Starlette 之上、Starlette 又架在 ASGI 协议之上的一层薄封装。

底层机制（比文档深一层）：三层各管一段。最底层 ASGI（Asynchronous Server Gateway Interface，异步服务器网关接口）是一份协议——它规定 web 服务器（如 Uvicorn）和应用之间用什么形状互相调用，本身不含实现。中间层 Starlette 是一个实现了 ASGI 协议的工具箱：路由表、Request/Response 封装、中间件栈、WebSocket、把同步函数丢进线程池的调度，全是它提供的；但它不自带服务器。最上层 FastAPI 直接继承 Starlette（class FastAPI(Starlette)），路由、请求对象、线程池调度全是继承来的——FastAPI 自己新增的唯一东西，就是在每个 path operation 外面加的那层"读类型 → 校验输入 → 序列化输出 → 生成 OpenAPI 文档"。这正好补全了 index 页「一句话本质」的后半句："其余一切，都是架在 ASGI 协议之上的一层薄封装。"前面 1.3–1.6 讲的那层封装，就坐落在这张分层图的最上面一格。

场景走查（把图 1.2 走一遍）：客户端 POST {"name":"book","price":9.9} 到一个签名为 def create_item(item: Item) 的端点。请求体作为 JSON bytes 到达 → Starlette 层把它解析成 dict → FastAPI 那层封装用 Item 的校验器把 dict 校验并构造成 Item 实例 → 把这个实例作为 item 注入你的函数。若 body 是 {"name":"book"}（缺 price），流程在第三步分叉：校验器报错 → 直接返回 422，create_item 不被调用。注意解析（Starlette 的活）和校验（FastAPI 那层的活）分属两层——这正是三层封装在一次请求里的体现。

与下一章的关系：这一章把七个部件逐个命名了。下一章把它们装回机器，沿着 Uvicorn → ASGI → Starlette → FastAPI 这条链，看一个请求从网线上的字节一路走到 JSON 响应，每一层各自发生了什么。