Flask Session Interface API
SessionInterface 是 Session 的底层抽象，允许你替换 Flask 默认的 Cookie 存储方式为 Redis、数据库等外部存储。
自定义实现只需继承 SessionInterface 并实现两个方法。
SessionInterface 抽象基类
| 属性/方法 | 说明 |
|---|---|
| null_session_class | 当 Session 不可用时使用的类。默认为 NullSession |
| pickle_based | bool，Session 是否基于 pickle 序列化。默认为 False |
| open_session(app, request) | 从请求中读取 Session 数据。返回 SessionMixin 实例或 None |
| save_session(app, session, response) | 将 Session 数据保存到响应中 |
| make_null_session(app) | 创建空 Session（当 open_session 返回 None 时自动调用） |
| is_null_session(obj) | 判断是否为 NullSession 实例 |
Cookie 选项方法
以下方法用于获取 Session Cookie 的各项属性，可被重写：
| 方法 | 说明 |
|---|---|
| get_cookie_name(app) | 获取 Cookie 名称。默认读取 SESSION_COOKIE_NAME 配置 |
| get_cookie_domain(app) | 获取 Cookie Domain。默认读取 SESSION_COOKIE_DOMAIN 配置 |
| get_cookie_path(app) | 获取 Cookie Path。默认读取 SESSION_COOKIE_PATH 或 APPLICATION_ROOT |
| get_cookie_httponly(app) | 获取 HttpOnly 标志。默认读取 SESSION_COOKIE_HTTPONLY |
| get_cookie_secure(app) | 获取 Secure 标志。默认读取 SESSION_COOKIE_SECURE |
| get_cookie_samesite(app) | 获取 SameSite 值。默认读取 SESSION_COOKIE_SAMESITE |
| get_cookie_partitioned(app) | 获取 Partitioned 标志。默认读取 SESSION_COOKIE_PARTITIONED（v3.1+） |
| get_expiration_time(app, session) | 获取 Session 过期时间。永久 Session 返回 now + lifetime |
| should_set_cookie(app, session) | 判断是否需要设置 Cookie。Session 被修改或永久 + SESSION_REFRESH_EACH_REQUEST 时返回 True |
内置实现
| 类 | 说明 |
|---|---|
| SecureCookieSessionInterface | 默认实现。使用 itsdangerous 签名 Cookie 存储 Session 数据。key_derivation="hmac"，digest_method=sha1 |
| SecureCookieSession | 基于 CallbackDict 的 Session 类。检测顶层键的修改，自动设置 modified=True |
| NullSession | 未设置 SECRET_KEY 时使用的占位 Session。读取正常，修改时报错 |
| SessionMixin | Session 类的 Mixin。提供 permanent、new、modified、accessed 属性 |
替换默认 Session 实现
实例
from flask import Flask
from flask.sessions import SessionInterface, SessionMixin
# 自定义 Session 类
class MySession(dict, SessionMixin):
pass
# 自定义 Session 接口
class MySessionInterface(SessionInterface):
def open_session(self, app, request):
# 从请求中加载 Session
user_id = request.headers.get("X-User-ID")
if user_id:
return MySession(user_id=user_id)
return MySession()
def save_session(self, app, session, response):
# 保存 Session 到响应
if "user_id" in session:
response.headers["X-Session-ID"] = session["user_id"]
app = Flask(__name__)
# 替换默认的 Session 实现
app.session_interface = MySessionInterface()
from flask.sessions import SessionInterface, SessionMixin
# 自定义 Session 类
class MySession(dict, SessionMixin):
pass
# 自定义 Session 接口
class MySessionInterface(SessionInterface):
def open_session(self, app, request):
# 从请求中加载 Session
user_id = request.headers.get("X-User-ID")
if user_id:
return MySession(user_id=user_id)
return MySession()
def save_session(self, app, session, response):
# 保存 Session 到响应
if "user_id" in session:
response.headers["X-Session-ID"] = session["user_id"]
app = Flask(__name__)
# 替换默认的 Session 实现
app.session_interface = MySessionInterface()