starlette 实现 jwt 令牌校验的核心做法是编写一个自定义的 middleware,在请求处理的中间层拦截带有 authorization 头的请求,使用 pyjwt 库解析并验证签名。如果验证通过,将解析出的用户信息存入 request.state 供后续路由访问;如果失败则直接返回 401 错误。这样做的好处是将鉴权逻辑与业务路由解耦,确保只有合法的请求才能进入具体的视图函数。

如何定义 JWT 中间件类
要定义 JWT 中间件,需要继承 starlette.middleware.base.BaseHTTPMiddleware 并重写 dispatch 方法。在这个方法中,首先检查请求头是否包含 Bearer 前缀的 Token,然后调用 jwt.decode() 进行验签。验签成功后,将解码后的 payload(通常包含用户 ID)挂载到 request.state.user 上,最后继续调用下一个中间件或路由处理程序。

import jwt
from starlette.middleware.base import BaseHTTPMiddleware
from starlette.requests import Request
from starlette.responses import JSONResponse
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):
# 获取 Authorization 头
auth_header = request.headers.get("Authorization")
# 检查是否存在 Bearer Token
if not auth_header or not auth_header.startswith("Bearer "):
return JSONResponse(
status_code=401,
content={"detail": "Missing or invalid authorization header"}
)
token = auth_header.split(" ")[1]
try:
# 解码并验证 JWT
payload = jwt.decode(token, self.secret_key, algorithms=[self.algorithm])
# 将用户信息存入 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"}
)
# 继续处理请求
response = await call_next(request)
return response
上述代码展示了中间件的完整实现。它首先提取 Token,然后尝试解码。如果解码成功,用户数据就被附加到了请求对象的状态中。如果发生过期或无效错误,立即返回 401 响应,阻止请求继续向下传递。这种设计确保了所有经过该中间件的请求都经过了身份验证。
如何在路由中使用验证后的用户信息
在路由函数中,可以通过 request.state.user 访问经过 JWT 验证的用户信息。由于中间件已经确保了 Token 的有效性,因此在路由中可以直接使用这些数据,而无需再次进行复杂的验证逻辑。这种方式使得路由函数保持简洁,专注于业务逻辑而非安全验证。
Starlette 1.5.1 是轻量级 Python ASGI 框架与工具集,提供路由、请求响应、中间件、WebSocket 和后台任务等组件,适合构建异步 Web 服务。本下载为官方 PyPI 通用 wheel 包,可使用 pip 安装,并由包管理器处理依赖;运行应用时还需配置 ASGI 服务器。

from starlette.applications import Starlette
from starlette.routing import Route
from starlette.responses import JSONResponse
async def protected_view(request):
# 从 request.state 获取用户信息
user = request.state.user
return JSONResponse({
"message": f"Hello, user {user.get('sub')}!",
"user_data": user
})
# 创建应用并注册中间件
app = Starlette(routes=[Route("/protected", protected_view)])
app.add_middleware(JWTAuthMiddleware)
在这个示例中,protected_view 是一个受保护的路由。当请求到达时,JWTAuthMiddleware 会先执行,验证 Token 并将用户信息存入 request.state.user。随后,protected_view 被调用,直接从 request.state 中读取用户数据并返回。这种模式清晰地分离了关注点,提高了代码的可维护性。
如何处理 Token 刷新机制
在实际应用中,除了访问令牌(Access Token),通常还需要刷新令牌(Refresh Token)来延长用户的会话时间。可以在中间件中增加对 Refresh Token 的检查,或者在路由中提供专门的刷新接口。这里展示一个简单的刷新逻辑:在验证 Access Token 的同时,检查其是否即将过期,如果是,则生成一个新的 Access Token 并在响应头中返回。
exp










