starlette 本身不内置 session 管理,而是通过中间件机制实现。开发者通常使用 starlette.middleware.sessions.sessionmiddleware 配合加密密钥来管理会话状态。

如何配置 SessionMiddleware 并启用会话功能
在 Starlette 应用中集成 Session 功能,核心是实例化 SessionMiddleware 并将其添加到应用栈中。该中间件会自动处理请求中的 Cookie,解析会话数据并在响应前重新序列化。

from starlette.applications import Starlette
from starlette.responses import JSONResponse
from starlette.middleware.sessions import SessionMiddleware
import os
app = Starlette()
# 必须设置一个足够长的随机字符串作为密钥以保障安全
app.add_middleware(SessionMiddleware, secret_key=os.environ.get('SECRET_KEY', 'change-me'))
@app.route('/set')
def set_session(request):
request.session['user_id'] = 123
return JSONResponse({'status': 'ok'})
@app.route('/get')
def get_session(request):
user_id = request.session.get('user_id')
return JSONResponse({'user_id': user_id})
上述代码展示了最基础的用法。调用 add_middleware 时传入 secret_key 参数,这是生成签名和加密数据的必要凭证。访问 /set 路由会将数据存入当前用户的会话字典,而 /get 路由则读取该数据。所有操作都通过 request.session 对象进行,它表现为一个标准的 Python 字典。
SessionMiddleware 的底层数据处理流程是怎样的
理解 SessionMiddleware 的工作流程有助于排查问题。当请求到达时,中间件首先从 Cookie 中提取名为 session 的数据块。如果存在数据,它会使用配置的密钥进行解密和验证签名,确保数据未被篡改。随后,将解析出的字典赋值给 request.session。在处理完业务逻辑后,如果 request.session 被修改过,中间件会在响应阶段重新加密、签名并将结果写回 Cookie。
记录结构化的Claude Code轨迹、影子git diff,并在代理行为需要法医级调试而非临时转录审查时回放分支。

# 模拟中间件内部的核心逻辑示意
import json
from itsdangerous import URLSafeTimedSerializer
class MockSessionMiddleware:
def __init__(self, app, secret_key):
self.app = app
self.serializer = URLSafeTimedSerializer(secret_key)
async def __call__(self, scope, receive, send):
if scope['type'] != 'http':
await self.app(scope, receive, send)
return
# 1. 接收请求
cookies = scope.get('headers', [])
session_data = self.extract_session(cookies)
# 2. 注入 session 对象到 scope/state (简化版)
# 实际 Starlette 中是通过 ASGI state 或 request 对象传递
request_state = {'session': session_data}
# 3. 调用下游应用
await self.app(scope, receive, send)
# 4. 检查修改并更新 Cookie
if request_state['session'].modified:
new_cookie = self.serialize(request_state['session'])
# 写入 response headers
pass
def extract_session(self, cookies):
# 查找 session cookie
for h in cookies:
if h[0] == b'cookie':
# 解析 cookie 字符串
pass
return ModifiedDict()
在实际开发中,不需要手动实现上述逻辑,但了解其过程能帮助用户意识到性能开销。每次请求都会涉及序列化和反序列化操作,因此应避免在会话中存储过大的数据。此外,SessionMiddleware 默认使用 itsdangerous 库进行签名,这意味着数据是明文存储在客户端 Cookie 中的,只是不可篡改。如果需要完全加密,需更换为支持加密的中间件或自定义实现。
如何判断 request.session 是否发生了变更
在 Starlette 中,request.session 是一个特殊的字典对象,它不仅存储数据,还追踪自身的变更状态。中间件依赖这个状态来决定是否需要重新生成 Cookie。如果用户只读取数据而未进行任何写入操作,中间件会跳过序列化步骤,从而节省计算资源。
可以通过检查 request.session.modified 属性来确认变更情况。当执行 __setitem__(如 session['key'] = value)或 pop、clear 等方法时,modified 标志会被自动设为 True。如果直接替换整个字典对象(如 request.session = {...}),由于没有触发原对象的修改方法,modified 可能不会被正确标记,导致数据丢失。因此,始终建议通过键值对方式修改会话内容,而不是替换整个字典。这种设计确保了中间件能准确捕获每一次有效的状态变更,维持会话的一致性。










