本文详细阐述了在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）是国内首个国密前后端分离快速开发平台，集成国密加解密插件， 软件层面完全符合等保测评要求，同时实现国产化机型、中间件、数据库适配，是您的不二之选！ 技术框架与密码结合，让更多的人认识密码，使用密码；更是让前后分离“密”不可分。采用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应用的关键技能之一。
