starlette实现jwt身份验证的核心做法是编写一个自定义中间件,在请求进入路由前解析authorization头中的bearer token,利用pyjwt库验证签名并提取用户信息,随后将解析出的payload挂载到request.state上供后续视图使用。具体操作需安装starlette和pyjwt,定义包含密钥、算法和过期时间配置的中间件类,并在其__call__方法中处理认证逻辑,若验证失败则返回401响应,成功则将用户数据存入request.state.user。

如何构建支持Bearer Token的认证中间件
构建中间件的关键在于继承starlette.middleware.base.BaseHTTPMiddleware并重写dispatch方法,该方法接收当前请求和下一个处理函数,通过检查请求头获取Token并进行验证。如果Token有效,中间件会将解码后的JSON数据附加到request.state对象中,这样下游的路由处理器就可以直接访问这些信息而无需重复解析;如果Token缺失或无效,则立即终止请求链并返回HTTP 401 Unauthorized错误,确保未授权请求不会到达业务逻辑层。

import jwt
from starlette.middleware.base import BaseHTTPMiddleware
from starlette.responses import JSONResponse
from starlette.requests import Request
SECRET_KEY = "your-secret-key"
ALGORITHM = "HS256"
class JWTAuthMiddleware(BaseHTTPMiddleware):
def __init__(self, app, secret_key=SECRET_KEY, algorithm=ALGORITHM):
super().__init__(app)
self.secret_key = secret_key
self.algorithm = algorithm
async def dispatch(self, request: Request, call_next):
# 1. 获取 Authorization 头
auth_header = request.headers.get("Authorization")
if not auth_header:
return JSONResponse(
status_code=401,
content={"detail": "Missing Authorization header"}
)
# 2. 检查 Bearer 格式
parts = auth_header.split()
if len(parts) != 2 or parts[0] != "Bearer":
return JSONResponse(
status_code=401,
content={"detail": "Invalid token format"}
)
token = parts[1]
try:
# 3. 解码并验证 Token
payload = jwt.decode(token, self.secret_key, algorithms=[self.algorithm])
# 4. 将用户信息挂载到 request.state
request.state.user = payload
except jwt.ExpiredSignatureError:
return JSONResponse(
status_code=401,
content={"detail": "Token has expired"}
)
except jwt.InvalidTokenError:
return JSONResponse(
status_code=401,
content={"detail": "Invalid token"}
)
# 5. 继续处理请求
response = await call_next(request)
return response
上述代码展示了完整的中间件实现,其中dispatch方法首先从request.headers中提取Authorization字段,然后校验其是否以Bearer开头。接着调用jwt.decode进行签名验证,若一切正常,解码后的字典会被赋值给request.state.user,最后调用call_next将控制权传递给应用的其他部分。这种设计使得认证逻辑与业务逻辑完全解耦。
Starlette 1.5.1 是轻量级 Python ASGI 框架与工具集,提供路由、请求响应、中间件、WebSocket 和后台任务等组件,适合构建异步 Web 服务。本下载为官方 PyPI 通用 wheel 包,可使用 pip 安装,并由包管理器处理依赖;运行应用时还需配置 ASGI 服务器。
如何在路由中安全地访问已认证的用户数据
在路由函数中访问用户数据时,必须通过request.state属性来获取之前中间件注入的信息,而不是直接从请求参数或全局变量中读取。这种方式保证了类型安全和上下文隔离,每个请求都有独立的state对象,避免了并发请求之间的数据污染。开发者需要在路由签名中声明Request类型,并通过request.state.user访问具体的用户载荷内容,如用户ID或角色信息。

from starlette.applications import Starlette
from starlette.routing import Route
from starlette.responses import JSONResponse
from starlette.requests import Request
# 假设上面的 JWTAuthMiddleware 已定义
app = Starlette(
routes=[
Route("/profile", get_profile),
],
middleware=[
JWTAuthMiddleware(),
]
)
async def get_profile(request: Request):
# 安全地访问已认证的用户数据
user = getattr(request.state, 'user', None)
if not user:
return JSONResponse(
status_code=401,
content={"detail": "User not authenticated"}
)
# 使用用户数据生成响应
return JSONResponse(
status_code=200,
content={
"user_id": user.get("sub"),
"username": user.get("username"),
"message": f"Hello, {user.get('username')}!"
}
)
在get_profile路由中,我们首先通过getattr安全地获取request.state.user,即使中间件未正确设置也不会引发AttributeError。随后,我们从user字典中提取sub(通常为用户唯一标识)和username等字段,构建JSON响应返回给客户端。这种模式确保了只有经过中间件验证的请求才能访问受保护的资源,且数据流清晰可控。
当Token中包含自定义字段如role时会发生什么
当JWT Payload中包含自定义字段如role时,这些字段会原样保留在解码后的字典中,并随request.state.user一起传递到路由层。这意味着开发者可以在路由中直接访问user['role']来进行基于角色的访问控制(RBAC),例如判断用户是否为管理员。只要这些字段在签发Token时被正确写入Payload,它们就会在验证通过后自动可用,无需额外配置或解析步骤。

















