starlette 本身不包含内置的 session 管理,需要借助第三方库如 starlette-session 或 itsdangerous 来实现。推荐使用 starlette-session,它通过中间件拦截请求,自动从 cookie 中读取并解密 session 数据,将其注入到 request.state 中供视图函数使用。

如何配置 Starlette-Session 中间件
配置的核心在于实例化 SessionMiddleware 并将其添加到应用栈中。你需要指定密钥用于签名和加密,以及存储后端(默认是内存,生产环境建议用 Redis)。

from starlette.applications import Starlette
from starlette.middleware.sessions import SessionMiddleware
app = Starlette()
app.add_middleware(SessionMiddleware, secret_key="change-me-in-production")
@app.route("/")
async def homepage(request):
request.session["user"] = "admin"
return PlainTextResponse("Session set")
上述代码展示了最简配置。启动服务后,访问根路径会在响应头中设置一个名为 session 的 Cookie。后续请求携带该 Cookie,中间件会自动解析并挂载到 request.session 对象上,该对象行为类似 Python 字典。
Session 数据的读写与持久化策略
在路由处理函数中,直接对 request.session 进行字典操作即可。数据在每次响应返回前会被序列化、签名并写入 Cookie。若需持久化,可替换默认的 BaseBackend 为基于数据库或缓存的实现。
记录结构化的Claude Code轨迹、影子git diff,并在代理行为需要法医级调试而非临时转录审查时回放分支。

@app.route("/check")
async def check_session(request):
user = request.session.get("user")
if not user:
return PlainTextResponse("Not logged in")
return PlainTextResponse(f"Hello {user}")
此段代码演示了读取逻辑。如果用户未登录,get 方法返回 None。在生产环境中,应确保 secret_key 足够复杂且保密,同时考虑设置 Cookie 的 httponly 和 samesite 属性以增强安全性。
Session 过期与清理机制如何处理
默认实现中,Session 数据存储在客户端 Cookie 中,没有服务端过期时间概念,除非设置了 Cookie 的 Max-Age。对于需要服务端控制生命周期的场景,需自定义 Backend 或在业务层记录最后活跃时间。
当使用内存存储时,重启服务会导致所有 Session 丢失。若集成 Redis 后端,可利用 Redis 的 TTL 功能实现自动过期。开发者需在初始化 Backend 时传入过期秒数,中间件会在每次读写时检查并刷新 TTL。










