中间件¶

🌐 Translation by AI and humans

This translation was made by AI guided by humans. 🤝

It could have mistakes of misunderstanding the original meaning, or looking unnatural, etc. 🤖

You can improve this translation by helping us guide the AI LLM better.

English version

你可以向 FastAPI 应用添加中间件。

“中间件”是一个函数，它会在每个特定的路径操作处理每个请求之前运行，也会在返回每个响应之前运行。

它接收你的应用的每一个请求。
然后它可以对这个请求做一些事情或者执行任何需要的代码。
然后它将这个请求传递给应用程序的其他部分（某个路径操作）处理。
之后它获取应用程序生成的响应（由某个路径操作产生）。
它可以对该响应做一些事情或者执行任何需要的代码。
然后它返回这个响应。

技术细节

如果你有使用 yield 的依赖，依赖中的退出代码会在中间件之后运行。

如果有任何后台任务（会在后台任务一节中介绍，你稍后会看到），它们会在所有中间件之后运行。

创建中间件¶

要创建中间件，你可以在函数的顶部使用装饰器 @app.middleware("http")。

中间件函数会接收：

request。
一个函数 call_next，它会把 request 作为参数接收。
- 这个函数会把 request 传递给相应的路径操作。
- 然后它返回由相应路径操作生成的 response。
在返回之前，你可以进一步修改 response。

Python 3.9+

import time

from fastapi import FastAPI, Request

app = FastAPI()


@app.middleware("http")
async def add_process_time_header(request: Request, call_next):
    start_time = time.perf_counter()
    response = await call_next(request)
    process_time = time.perf_counter() - start_time
    response.headers["X-Process-Time"] = str(process_time)
    return response

🤓 Other versions and variants

Python 3.10+

import time

from fastapi import FastAPI, Request

app = FastAPI()


@app.middleware("http")
async def add_process_time_header(request: Request, call_next):
    start_time = time.perf_counter()
    response = await call_next(request)
    process_time = time.perf_counter() - start_time
    response.headers["X-Process-Time"] = str(process_time)
    return response

Tip

请记住可以使用 X- 前缀添加专有自定义请求头。

但是如果你有希望让浏览器中的客户端可见的自定义请求头，你需要把它们加到你的 CORS 配置（CORS (Cross-Origin Resource Sharing)）的 expose_headers 参数中，参见 Starlette 的 CORS 文档。

技术细节

你也可以使用 from starlette.requests import Request。

FastAPI 为了开发者方便提供了该对象，但它直接来自 Starlette。

在 `response` 之前与之后¶

你可以在任何路径操作接收 request 之前，添加要与该 request 一起运行的代码。

也可以在生成 response 之后、返回之前添加代码。

例如，你可以添加一个自定义请求头 X-Process-Time，其值为处理请求并生成响应所花费的秒数：

Python 3.9+

import time

from fastapi import FastAPI, Request

app = FastAPI()


@app.middleware("http")
async def add_process_time_header(request: Request, call_next):
    start_time = time.perf_counter()
    response = await call_next(request)
    process_time = time.perf_counter() - start_time
    response.headers["X-Process-Time"] = str(process_time)
    return response

🤓 Other versions and variants

Python 3.10+

import time

from fastapi import FastAPI, Request

app = FastAPI()


@app.middleware("http")
async def add_process_time_header(request: Request, call_next):
    start_time = time.perf_counter()
    response = await call_next(request)
    process_time = time.perf_counter() - start_time
    response.headers["X-Process-Time"] = str(process_time)
    return response

Tip

这里我们使用 time.perf_counter() 而不是 time.time()，因为在这类场景中它可能更精确。🤓

多个中间件的执行顺序¶

当你使用 @app.middleware() 装饰器或 app.add_middleware() 方法添加多个中间件时，每个新中间件都会包裹应用，形成一个栈。最后添加的中间件是“最外层”的，最先添加的是“最内层”的。

在请求路径上，最外层的中间件先运行。

在响应路径上，它最后运行。

例如：

app.add_middleware(MiddlewareA)
app.add_middleware(MiddlewareB)

这会产生如下执行顺序：

请求：MiddlewareB → MiddlewareA → 路由
响应：路由 → MiddlewareA → MiddlewareB

这种栈式行为确保中间件按可预测且可控的顺序执行。

其他中间件¶

你可以稍后在高级用户指南：高级中间件中阅读更多关于其他中间件的内容。

你将在下一节中了解如何使用中间件处理 CORS。