FastAPI教程：创建自定义中间件

什么是中间件？

中间件是FastAPI中的一个核心概念，它是一种在HTTP请求到达路由处理程序之前或响应返回给客户端之后执行的代码块。简单来说，中间件就像是一个“守门员”，可以对所有进出的请求和响应进行统一处理，常用于添加通用功能，如日志记录、认证、错误处理等，而无需在每个路由中重复代码。

为什么需要自定义中间件？

FastAPI内置了一些常用的中间件，但实际开发中，您可能需要特定功能来满足项目需求。自定义中间件允许您灵活扩展框架功能，例如：

• 记录每个请求的详细日志，便于调试和分析。
• 在请求中添加自定义认证逻辑，确保安全访问。
• 统一处理错误或异常，返回标准化的错误响应。
• 监控性能，测量请求处理时间以优化效率。

创建自定义中间件的步骤

创建自定义中间件很简单，只需遵循以下三个基本步骤：

1. 导入FastAPI和相关模块

首先，确保您已经安装FastAPI和Uvicorn（一个ASGI服务器），可以通过运行 pip install fastapi uvicorn 来安装。然后，在代码中导入必要的模块。

2. 定义中间件函数

中间件函数是一个异步函数，接收两个主要参数：request（包含HTTP请求信息）和 call_next（用于调用下一个中间件或路由处理程序）。您可以根据需要添加更多参数，但这两个是必需的。

3. 使用装饰器注册中间件

使用 @app.middleware("http") 装饰器将中间件函数绑定到FastAPI应用程序实例。这样，每当有请求时，FastAPI就会自动调用这个中间件。

代码示例：创建一个简单的日志中间件

下面是一个完整的示例，展示如何创建一个自定义中间件来记录每个请求的路径和处理时间。

from fastapi import FastAPI, Request
import time  # 用于计算时间

# 创建FastAPI应用实例
app = FastAPI()

# 使用装饰器注册自定义中间件
@app.middleware("http")
async def custom_middleware(request: Request, call_next):
    """
    自定义中间件函数：记录请求日志和处理时间。
    参数:
        request: FastAPI的Request对象，包含请求数据。
        call_next: 异步函数，调用下一个中间件或路由处理程序。
    """
    # 记录请求开始时间
    start_time = time.time()
    
    # 调用下一个中间件或路由处理程序，获取响应
    response = await call_next(request)
    
    # 计算请求处理耗时
    process_time = time.time() - start_time
    
    # 将处理时间添加到响应头中，方便客户端查看
    response.headers["X-Process-Time"] = str(process_time)
    
    # 输出简单日志到控制台（实际中可替换为文件或数据库）
    print(f"Request path: {request.url.path}, Time taken: {process_time:.4f} seconds")
    
    # 返回响应，继续处理
    return response

# 定义一个简单的路由来测试中间件
@app.get("/")
async def root():
    """根路由，返回欢迎消息。"""
    return {"message": "Hello, welcome to FastAPI with custom middleware!"}

# 运行应用（使用uvicorn server:app --reload启动）

代码解释

• 导入模块：FastAPI 用于创建应用，Request 用于访问请求数据，time 用于时间计算。
• 定义中间件函数：custom_middleware 是一个异步函数，使用 async def 定义。它接收 request 和 call_next 参数。
  • request: Request: 提供请求的详细信息，如URL路径、方法等。
  • call_next: 这是一个异步函数，用于将控制权传递给下一个中间件或最终的路由处理程序；调用 await call_next(request) 来继续处理请求。
• 逻辑处理：
  • 记录开始时间，在调用 call_next 之前。
  • 调用 call_next 获取响应，这会处理请求并生成响应。
  • 计算耗时，并在响应头中添加 X-Process-Time 字段。
  • 打印日志，便于开发者查看。
• 返回响应：中间件函数必须返回响应对象，以继续响应流程。

实际应用场景

自定义中间件非常灵活，适用于多种场景：

• 日志记录：如上例，记录请求细节或处理时间。
• 认证和授权：检查请求头中的令牌（如JWT），验证用户身份。
• 错误处理：捕获异常，返回统一的错误JSON格式，避免应用崩溃。
• 性能监控：集成监控工具，统计请求数据以优化应用性能。
• 修改请求/响应：例如，添加跨域资源共享（CORS）头或压缩响应数据。

注意事项

• 异步函数：中间件函数必须是异步的（使用 async def），因为FastAPI基于异步框架。如果使用同步代码，可能导致性能瓶颈。
• 顺序问题：中间件的执行顺序基于注册顺序；在 @app.middleware("http") 中定义的中间件会按顺序执行。
• 避免阻塞：确保中间件逻辑高效，避免长时间操作阻塞请求流。
• 测试：在实际部署前，通过运行应用测试中间件功能，确保没有错误。

总结

通过本教程，您学会了如何在FastAPI中创建自定义中间件。中间件是扩展应用功能的强大工具，可以帮助您实现代码复用和高效管理。建议从简单示例开始，逐步尝试复杂功能，以适应您的项目需求。如果遇到问题，可以查阅FastAPI官方文档或社区资源获取更多帮助。

下一步学习

掌握自定义中间件后，您可以进一步探索FastAPI的其他特性，如依赖注入、路由分组或WebSocket支持，以构建更强大的Web应用。