FastAPI中端点与中间件之间的数据传递：使用request.state

花韻仙語

发布时间：2025-12-13 22:35:15

426人浏览过

来源于php中文网

原创

FastAPI中端点与中间件之间的数据传递：使用request.state

本文详细阐述了在fastapi应用中，如何利用`request.state`机制在http中间件和api端点之间传递请求特有的数据。通过将自定义数据（如api积分）存储在`request.state`对象上，开发者可以实现中间件在处理请求前或后访问并利用这些信息，从而构建灵活的业务逻辑，例如统一的api积分扣减或日志记录。

在构建复杂的Web服务时，经常需要在API端点中定义一些与当前请求相关的特定数据，并希望在全局的HTTP中间件中访问这些数据，以执行统一的逻辑，例如API积分扣减、权限检查或日志记录。FastAPI（基于Starlette）提供了一个优雅的解决方案，即通过request.state对象来实现端点与中间件之间的数据共享。

理解request.state

request.state是Starlette Request对象的一个属性，它是一个可变的字典状对象，允许开发者在单个请求的生命周期内存储任意的键值对数据。这意味着，任何在请求处理链中能够访问到request对象的组件（包括中间件、依赖注入函数和API端点）都可以写入或读取request.state中的数据。

实现数据传递的步骤

以下是如何利用request.state将API端点定义的积分数据传递给HTTP中间件的详细步骤。

1. 定义HTTP中间件

首先，我们需要定义一个HTTP中间件。在这个中间件中，我们将执行以下操作：

在请求被处理之前，初始化request.state中用于存储API积分的属性（例如api_credits），以确保其始终存在，并提供一个默认值（如None）。
调用call_next(request)，将请求传递给后续的路由处理或下一个中间件。
在请求处理完毕并生成响应后，从request.state.api_credits中读取由端点设置的值，并执行相应的业务逻辑（例如打印或扣减积分）。

from fastapi import FastAPI, Request
from starlette.responses import JSONResponse

app = FastAPI()

@app.middleware("http")
async def api_credit_middleware(request: Request, call_next):
    """
    HTTP中间件，用于在请求处理前后访问和处理API积分。
    """
    # 1. 在请求被处理前，初始化request.state.api_credits
    # 这样做可以确保即使端点没有设置，该属性也存在，避免AttributeError
    request.state.api_credits = None 

    # 2. 将请求传递给下一个处理者（例如API端点）
    response = await call_next(request)

    # 3. 在请求处理完毕后，从request.state中读取API积分
    if request.state.api_credits is not None:
        credits_to_deduct = request.state.api_credits
        print(f"中间件：正在处理端点 '{request.url.path}'，需扣除 {credits_to_deduct} API积分。")
        # 这里可以添加实际的积分扣减逻辑，例如更新用户数据库
        # 注意：实际扣减逻辑可能涉及异步操作和数据库事务
    else:
        print(f"中间件：端点 '{request.url.path}' 未设置API积分。")

    return response

2. 在API端点中设置数据

接下来，在你的API端点函数中，你可以直接通过request.state属性来设置你希望传递给中间件的数据。

Snowy(SnowyAdmin)快速开发平台3.5.1

Snowy（SnowyAdmin）是国内首个国密前后端分离快速开发平台，集成国密加解密插件，软件层面完全符合等保测评要求，同时实现国产化机型、中间件、数据库适配，是您的不二之选！技术框架与密码结合，让更多的人认识密码，使用密码；更是让前后分离“密”不可分。采用SpringBoot+MybatisPlus+AntDesignVue+Vite 等更多组件及前沿技术开发，注释丰富，代码简洁，开箱即用

下载

@app.post("/myendpoint1")
async def my_endpoint_one(request: Request):
    """
    示例端点1：设置API积分并返回消息。
    """
    api_credit_cost = 2
    request.state.api_credits = api_credit_cost
    print(f"端点1：已设置API积分：{api_credit_cost}")
    return {"message": "myendpoint1 processed"}

@app.post("/myendpoint2")
async def my_endpoint_two(request: Request):
    """
    示例端点2：设置不同的API积分并返回消息。
    """
    api_credit_cost = 5
    request.state.api_credits = api_credit_cost
    print(f"端点2：已设置API积分：{api_credit_cost}")
    return {"message": "myendpoint2 processed"}

@app.get("/no-credits")
async def no_credits_endpoint():
    """
    示例端点3：不设置API积分。
    """
    return {"message": "This endpoint does not require API credits"}

完整示例代码

将上述中间件和端点组合起来，形成一个完整的FastAPI应用：

from fastapi import FastAPI, Request
from starlette.responses import JSONResponse

app = FastAPI()

@app.middleware("http")
async def api_credit_middleware(request: Request, call_next):
    """
    HTTP中间件，用于在请求处理前后访问和处理API积分。
    """
    # 1. 在请求被处理前，初始化request.state.api_credits
    # 这样做可以确保即使端点没有设置，该属性也存在，避免AttributeError
    request.state.api_credits = None 

    # 2. 将请求传递给下一个处理者（例如API端点）
    response = await call_next(request)

    # 3. 在请求处理完毕后，从request.state中读取API积分
    if request.state.api_credits is not None:
        credits_to_deduct = request.state.api_credits
        print(f"中间件：正在处理端点 '{request.url.path}'，需扣除 {credits_to_deduct} API积分。")
        # 这里可以添加实际的积分扣减逻辑，例如更新用户数据库
        # 注意：实际扣减逻辑可能涉及异步操作和数据库事务
    else:
        print(f"中间件：端点 '{request.url.path}' 未设置API积分。")

    return response

@app.post("/myendpoint1")
async def my_endpoint_one(request: Request):
    """
    示例端点1：设置API积分并返回消息。
    """
    api_credit_cost = 2
    request.state.api_credits = api_credit_cost
    print(f"端点1：已设置API积分：{api_credit_cost}")
    return {"message": "myendpoint1 processed"}

@app.post("/myendpoint2")
async def my_endpoint_two(request: Request):
    """
    示例端点2：设置不同的API积分并返回消息。
    """
    api_credit_cost = 5
    request.state.api_credits = api_credit_cost
    print(f"端点2：已设置API积分：{api_credit_cost}")
    return {"message": "myendpoint2 processed"}

@app.get("/no-credits")
async def no_credits_endpoint():
    """
    示例端点3：不设置API积分。
    """
    return {"message": "This endpoint does not require API credits"}

# 运行应用: uvicorn your_module_name:app --reload

运行与测试

将上述代码保存为 main.py。
使用 uvicorn main:app --reload 运行应用。
使用 curl 或 Postman/Insomnia 等工具发送请求：
- curl -X POST http://127.0.0.1:8000/myendpoint1
- curl -X POST http://127.0.0.1:8000/myendpoint2
- curl -X GET http://127.0.0.1:8000/no-credits

你将在控制台看到如下输出（根据请求不同）：

# 请求 /myendpoint1 时
端点1：已设置API积分：2
中间件：正在处理端点 '/myendpoint1'，需扣除 2 API积分。

# 请求 /myendpoint2 时
端点2：已设置API积分：5
中间件：正在处理端点 '/myendpoint2'，需扣除 5 API积分。

# 请求 /no-credits 时
中间件：端点 '/no-credits' 未设置API积分。

注意事项与最佳实践

请求作用域： request.state中的数据仅在当前请求的生命周期内有效。每个新请求都会有一个全新的request.state对象。
数据类型： request.state可以存储任何Python对象，但建议存储简单、可序列化的数据，以保持清晰。
初始化与默认值： 在中间件中访问request.state的自定义属性之前，最好先进行初始化或检查其是否存在（如if hasattr(request.state, 'api_credits')或像示例中那样先赋None），以避免AttributeError。
命名约定： 为request.state中的属性选择清晰且唯一的名称，以避免不同组件之间可能出现的命名冲突。
类型提示： 虽然request.state本身是动态的，但在使用时可以通过注释或自定义类型来提高代码可读性，例如：request.state.api_credits: Optional[int] = None。
替代方案： 对于更复杂的全局配置或应用级状态，FastAPI的依赖注入系统或应用程序的app.state（全局应用状态）可能是更合适的选择。但对于请求级别的特定数据传递，request.state是首选。

总结

request.state是FastAPI提供的一个强大且灵活的机制，用于在单个HTTP请求的生命周期内，在中间件和API端点之间共享数据。通过合理利用这一特性，开发者可以有效地解耦业务逻辑，使得API端点专注于其核心功能，而中间件则负责统一的横切关注点，如认证、授权、日志和资源扣减等。掌握request.state的使用，是构建高效、可维护FastAPI应用的关键技能之一。

如何批量重命名多级子目录中的PDF文件（以所在操作员文件夹名为前缀）

Python requests 性能优化技巧

Python 类的 MRO（方法解析顺序）解析

Python 异常处理机制的执行流程

Python 配置文件加载的设计模式