`microdot.session` --- 签名 cookie 会话¶

一个按用户的键/值存储，由单个 session cookie 中的 jwt 支持。该 JWT 使用仅应用知晓的密钥进行签名，因此客户端可以读取该 cookie，但若不被服务器检测到就无法篡改载荷。

class Session¶

class microdot.session.Session(app: Microdot | None = None, secret_key: bytes | str | None = None, cookie_options: dict | None = None)¶

app: 要安装到其上的 microdot.Microdot 实例。可选；如果未给出，可稍后调用 initialize()。
secret_key: 用于签名会话 JWT 的对称密钥。在任何会话被读取或写入之前都是必需的 -- 在没有它的情况下访问 get() 会抛出 ValueError。应将其存放在源代码管理之外；在摄像头上这通常是 FAT 文件系统上的一个文件。
cookie_options: 每当写入会话 cookie 时转发给 microdot.Response.set_cookie() 的选项字典。默认设置 path='/' 和 http_only=True。对于仅 HTTPS 的部署，请添加 secure=True。

initialize(app: Microdot, secret_key=None, cookie_options=None)¶: 如果构造被推迟，则附加到 app。若给出，secret_key / cookie_options 会覆盖构造函数的值。

get(request) → SessionDict¶: 返回 request 的会话字典。该字典在首次访问时从 session cookie 惰性解码，并在该请求的其余部分缓存于 request.g._session 上。被篡改 / 无法验证签名的 cookie 会返回一个空 dict。

encode(payload: dict, secret_key=None) → str¶: 用会话的密钥将 payload 编码为一个 JWT。供内部使用；为想要铸造兼容令牌的调用者暴露。

decode(session: str, secret_key=None) → dict¶: 验证并解码一个 JWT 字符串会话值。任何验证失败时返回 {}。

secret_key: bytes | str | None¶: 用于签名和验证会话 JWT 的签名密钥。可在构造后设置。在被设置之前为 None；在没有它的情况下读取会话会抛出 ValueError。

cookie_options: dict¶: 在写入会话 cookie 时应用于该 cookie 的选项字典，转发给 microdot.Response.set_cookie()。在 initialize() 运行后，默认设置 path='/' 和 http_only=True。

class SessionDict¶

class microdot.session.SessionDict(request, session_dict)¶

由 Session.get() 返回的类 dict 对象。它是 dict 的子类，因此所有标准的变更操作都有效；两个额外的方法将更改提交回响应。

save()¶: 将（可能已变更的）会话作为一个新的 session cookie 写回响应。如果不调用此方法，就地的编辑会在请求结束时丢失。

delete()¶: 通过在响应上发出一个 cookie 删除头部来移除会话。

模块级装饰器¶

microdot.session.with_session(f)¶

装饰器，将会话字典作为第二个参数传递给路由处理器:

from microdot import Microdot
from microdot.session import Session, with_session

app = Microdot()
Session(app, secret_key=load_secret())

@app.get('/counter')
@with_session
async def counter(request, session):
    session['n'] = session.get('n', 0) + 1
    session.save()
    return {'n': session['n']}

该装饰器不会自动保存 -- 当会话被修改后请调用 SessionDict.save()。

会话载荷本身是一个常规的 Python dict，在 JWT 内部序列化为 JSON。请保持其小巧：每个请求和每个响应都携带完整的 cookie，而 JWT 并非为存储大对象而设计。对于大于几百字节的按用户状态，请用一个小的会话标识符作为键，在服务器端存储数据。