FastAPI 中的中间件如何工作？

Question

FastAPI 中的中间件如何工作？

Accepted Answer

**Middleware**（中间件）在 FastAPI 中是为**每个请求和响应**运行的代码——封装你的端点以处理日志、计时、CORS 和添加头等跨切面关注点。FastAPI 使用 Starlette 的中间件系统（基于 ASGI）。

## 编写自定义中间件

```python
import time

@app.middleware("http")
async def add_timing(request: Request, call_next):
    start = time.time()
    response = await call_next(request)        # call the endpoint (and any inner middleware)
    response.headers["X-Process-Time"] = str(time.time() - start)   # modify the response
    return response
```

模式是：`await call_next(request)` 之前的代码在**进入时**运行（在端点之前），`call_next` 调用端点，之后的代码在**退出时**运行（修改响应）。这包装每个请求——这里，向所有响应添加一个计时头。

## 请求/响应流

```text
Request  → MW1 → MW2 → endpoint
Response ← MW1 ← MW2 ← endpoint
Middleware wraps the endpoint; runs in order on the way in, reverse on the way out.
```

## 内置/常见中间件

```python
from fastapi.middleware.cors import CORSMiddleware
from fastapi.middleware.gzip import GZipMiddleware

app.add_middleware(CORSMiddleware, allow_origins=["https://app.example.com"], ...)  # CORS
app.add_middleware(GZipMiddleware, minimum_size=1000)                               # compression
```

中间件通常通过 `add_middleware` 添加——CORS（允许跨源请求）、GZip（压缩响应）和可信主机检查是典型的内置中间件。

## 中间件的常见用途

```text
✓ Logging / request timing / metrics
✓ CORS (cross-origin request handling)
✓ Adding security or custom headers
✓ Response compression (GZip)
✓ Request ID / correlation ID injection
```

## 中间件 vs 依赖项

```text
Middleware   → runs for ALL requests; works at the raw request/response level (headers,
               timing, the whole response). Best for truly global concerns.
Dependencies → per-endpoint (or grouped) logic with access to parsed params, DI, and
               typed values. Best for auth, validation, shared parameters.
→ Use middleware for global cross-cutting concerns; dependencies for endpoint logic.
```

## 为什么这很重要

中间件是处理 FastAPI 中**全局、跨切面关注点**的正确机制——应该应用于每个请求和响应的逻辑，如日志、请求计时、CORS、压缩和自定义头。

理解它对于正确构建应用程序结构很重要：中间件封装所有端点（在前后运行，能够修改请求和响应），使其非常适合应用范围内的行为，否则在每个端点中重复会很繁琐且容易出错。

了解**中间件**（全局、原始请求/响应级别）和**依赖项**（每个端点、可访问解析/类型化值和依赖注入——更适合身份验证和验证）之间的区别对于选择正确的工具至关重要。

CORS 和压缩等常见需求由内置中间件处理，而自定义中间件涵盖日志和仪器——使这个实用、经常使用的知识对构建结构良好、可观测的 API 至关重要。