理解 FastAPI 请求生命周期与钩子函数

理解 FastAPI 请求生命周期与钩子函数

目录

1. 🌐 FastAPI 请求生命周期解析
2. 🔧 请求前与请求后：生命周期中的关键环节
3. 🎯 使用事件钩子函数管理应用状态
4. 🛠️ 实践示例：构建完整的生命周期管理流程

🌐 1. FastAPI 请求生命周期解析

在 Web 开发中，每个请求的处理过程都涉及一系列操作，从接收请求到返回响应，这一过程被称为“请求生命周期”。FastAPI 作为一款高性能的 Python Web 框架，提供了精确控制请求生命周期的机制，使得开发者能够在请求的不同阶段插入自定义逻辑，以提升应用的灵活性和可维护性。

生命周期的核心环节包括：

1. 接收请求：客户端向服务器发起 HTTP 请求，FastAPI 接收该请求并解析路径、方法等信息。
2. 路由匹配：请求的路径和方法与定义的路由进行匹配，确定执行的视图函数。
3. 依赖项注入：执行视图函数前，FastAPI 加载并解析视图中所需的依赖项。
4. 视图函数执行：调用匹配到的视图函数，执行业务逻辑并返回响应数据。
5. 响应返回：将视图函数返回的数据序列化为 HTTP 响应对象，返回给客户端。
6. 关闭连接：释放资源，断开客户端的连接。

这一过程中，FastAPI 提供了多种方式在生命周期的不同阶段插入自定义逻辑，其中最常用的是事件钩子函数。

🔧 2. 请求前与请求后：生命周期中的关键环节

请求前的操作

在请求进入视图函数前，可能需要进行一些初始化工作，比如：

• 记录日志
• 验证请求参数
• 设定请求上下文信息
• 连接数据库或缓存

FastAPI 支持在视图函数执行前，使用依赖项或中间件拦截请求，进行这些预处理操作。

示例：在请求前打印日志信息

from fastapi import FastAPI, Request

app = FastAPI()

@app.middleware("http")
async def log_requests(request: Request, call_next):
    """
    请求前中间件，记录请求路径和方法。
    """
    print(f"收到请求: {request.method} {request.url}")
    response = await call_next(request)  # 继续执行下一个环节
    return response

代码解析：

• 使用 @app.middleware("http") 定义中间件，在请求进入视图函数前执行 log_requests。
• 通过 request 对象可以访问请求的路径和方法，并记录相关信息。
• call_next(request) 表示将请求传递给下一个处理环节，继续生命周期流程。

请求后的操作

请求处理完毕后，通常需要执行一些后续任务，比如：

• 释放资源
• 记录操作日志
• 异步触发其他任务（如通知）

FastAPI 允许在请求完成后，通过中间件或依赖项处理这些逻辑。

示例：在请求后释放资源

@app.middleware("http")
async def release_resources(request: Request, call_next):
    response = await call_next(request)  # 继续请求处理
    print("请求处理完毕，释放资源")
    return response

代码解析：

• 在请求完成后，通过打印日志表示资源已释放。
• 这一方式适用于需要在响应返回后执行的任务，如关闭数据库连接或清理临时数据。

🎯 3. 使用事件钩子函数管理应用状态

除了请求前后的中间件处理，FastAPI 还提供了事件钩子函数，用于在应用启动和关闭时执行特定任务。这些钩子函数是管理应用状态和资源的理想方式，常见场景包括：

• 在应用启动时初始化数据库连接池
• 在应用关闭时断开数据库连接
• 启动定时任务或异步任务调度器

FastAPI 提供了两个关键事件钩子：

1. @app.on_event("startup")：应用启动时触发，仅执行一次，适用于初始化操作。
2. @app.on_event("shutdown")：应用关闭时触发，适用于清理资源和释放内存。

示例1：启动和关闭时管理数据库连接

from fastapi import FastAPI
import asyncpg

app = FastAPI()

DATABASE_URL = "postgresql://user:password@localhost/dbname"

@app.on_event("startup")
async def startup():
    """
    应用启动时初始化数据库连接池。
    """
    global pool
    pool = await asyncpg.create_pool(DATABASE_URL)
    print("数据库连接池已建立")

@app.on_event("shutdown")
async def shutdown():
    """
    应用关闭时释放数据库连接池。
    """
    await pool.close()
    print("数据库连接池已关闭")

@app.get("/users")
async def get_users():
    async with pool.acquire() as connection:
        rows = await connection.fetch("SELECT id, name FROM users")
        return [{"id": row["id"], "name": row["name"]} for row in rows]

代码解析：

• 启动时，通过 asyncpg.create_pool 建立数据库连接池。
• 关闭时，通过 pool.close() 释放连接池，防止连接泄露。

示例2：应用启动时加载配置文件

import json

config = {}

@app.on_event("startup")
async def load_config():
    """
    启动时加载配置文件。
    """
    global config
    with open("config.json", "r") as f:
        config = json.load(f)
    print("配置文件加载完成")

代码解析：

• 通过 json 加载配置文件，存储在全局变量 config 中，以便后续访问。
• 确保配置文件在应用启动时加载，避免在每个请求中重复读取。

🛠️ 4. 实践示例：构建完整的生命周期管理流程

以下示例展示了如何通过事件钩子函数和中间件，完整地管理应用的启动、请求和关闭生命周期。

from fastapi import FastAPI, Request
import asyncpg
import json

app = FastAPI()
DATABASE_URL = "postgresql://user:password@localhost/dbname"
config = {}

@app.on_event("startup")
async def startup():
    global pool, config
    pool = await asyncpg.create_pool(DATABASE_URL)
    with open("config.json", "r") as f:
        config = json.load(f)
    print("应用启动，数据库连接池已建立，配置文件加载完成")

@app.on_event("shutdown")
async def shutdown():
    await pool.close()
    print("应用关闭，数据库连接池已释放")

@app.middleware("http")
async def log_requests(request: Request, call_next):
    print(f"请求路径: {request.url.path}")
    response = await call_next(request)
    print("请求结束")
    return response

@app.get("/health")
async def health_check():
    return {"status": "ok"}

示例解析：

• 启动和关闭时分别加载配置和释放资源。
• 每次请求记录路径，保证所有请求均受监控。
• 提供 health_check 接口用于检查应用状态。