FastAPI 高级中间件使用指南

FastAPI 高级中间件使用指南

fastapi FastAPI framework, high performance, easy to learn, fast to code, ready for production 项目地址: https://gitcode.com/gh_mirrors/fa/fastapi

什么是中间件

在 FastAPI 框架中，中间件是一种强大的机制，允许开发者在请求到达路由处理程序之前或响应返回客户端之后执行特定操作。中间件可以用于多种场景，如身份验证、日志记录、请求修改等。

ASGI 中间件基础

FastAPI 基于 Starlette 框架并实现了 ASGI 规范，因此可以兼容任何符合 ASGI 标准的中间件。这意味着你不仅可以使用 FastAPI 或 Starlette 提供的中间件，还可以集成第三方 ASGI 中间件。

添加中间件的两种方式

1. 直接包装方式（原生 ASGI 方式）：

from some_library import SomeMiddleware

app = FastAPI()
wrapped_app = SomeMiddleware(app, config="value")

2. 推荐方式（使用 FastAPI 的 add_middleware 方法）：

from fastapi import FastAPI
from some_library import SomeMiddleware

app = FastAPI()
app.add_middleware(SomeMiddleware, config="value")

推荐使用第二种方式，因为它能确保 FastAPI 的内部错误处理和自定义异常处理器正常工作。

FastAPI 内置常用中间件

HTTPS 重定向中间件

HTTPSRedirectMiddleware 强制将所有 HTTP 请求重定向到 HTTPS，确保通信安全：

from fastapi import FastAPI
from fastapi.middleware.httpsredirect import HTTPSRedirectMiddleware

app = FastAPI()
app.add_middleware(HTTPSRedirectMiddleware)

可信主机中间件

TrustedHostMiddleware 防止 HTTP 主机头攻击，只允许特定域名的请求：

from fastapi import FastAPI
from fastapi.middleware.trustedhost import TrustedHostMiddleware

app = FastAPI()
app.add_middleware(
    TrustedHostMiddleware,
    allowed_hosts=["example.com", "*.example.com"]
)

参数说明：

• allowed_hosts: 允许的主机名列表，支持通配符（如 *.example.com）
• 如果允许所有主机，可以设置为 ["*"] 或省略此中间件

GZip 压缩中间件

GZipMiddleware 自动压缩响应数据，减少传输量：

from fastapi import FastAPI
from fastapi.middleware.gzip import GZipMiddleware

app = FastAPI()
app.add_middleware(GZipMiddleware)

可配置参数：

• minimum_size: 最小压缩大小（字节），默认 500
• compresslevel: 压缩级别（1-9），默认 9（最高压缩率）

中间件工作原理深度解析

中间件在 FastAPI 请求处理流程中的位置：

1. 接收请求
2. 中间件预处理
3. 路由处理
4. 中间件后处理
5. 发送响应

这种机制使得中间件非常适合处理跨切面关注点（cross-cutting concerns），如：

• 认证和授权
• 请求日志记录
• 性能监控
• 异常处理
• 请求/响应修改

高级使用技巧

自定义中间件开发

虽然本文主要介绍如何使用现有中间件，但了解如何创建自定义中间件也很重要。基本结构如下：

from fastapi import Request

async def custom_middleware(request: Request, call_next):
    # 请求前处理
    response = await call_next(request)
    # 响应后处理
    return response

中间件执行顺序

中间件的执行顺序与添加顺序相反（类似栈结构）：

1. 最后添加的中间件最先处理请求
2. 最先添加的中间件最后处理响应

性能考量

使用中间件时需注意：

1. 每个中间件都会增加少量处理时间
2. 复杂的中间件链可能影响性能
3. 在生产环境中应监控中间件的影响

总结

FastAPI 的中间件系统提供了强大而灵活的请求/响应处理机制。通过合理使用内置中间件和第三方 ASGI 中间件，开发者可以轻松实现各种高级功能，同时保持代码的整洁和可维护性。

对于更复杂的场景，建议参考 ASGI 规范深入了解中间件的工作原理，这将帮助你更好地利用这一强大特性。

fastapi FastAPI framework, high performance, easy to learn, fast to code, ready for production 项目地址: https://gitcode.com/gh_mirrors/fa/fastapi