starlette 中设置响应 cookie 的标准做法是实例化一个 starlette.datastructures.setcookie 对象,并将其添加到响应的 headers 集合中。具体实现时,调用 response.set_cookie() 方法即可自动处理这一过程,该方法会生成对应的 set-cookie 头部字段并合并到响应头中。

如何手动构建 Set-Cookie 头部
在 Starlette 的底层逻辑中,响应头是一个支持重复键的字典结构。要手动设置 Cookie,需要创建一个 SetCookie 实例,该实例实现了 __str__ 方法以返回符合 HTTP 标准的字符串格式。将这个实例直接赋值给 response.headers 中的 set-cookie 键,即可完成设置。这种方式适用于需要精细控制头部生成逻辑的场景,但通常推荐使用高层 API。

from starlette.responses import Response
from starlette.datastructures import SetCookie
# 创建响应对象
response = Response(content="Hello World")
# 手动构建 SetCookie 对象
cookie_obj = SetCookie(
path="/",
domain="example.com",
name="session_id",
value="abc123",
max_age=3600,
secure=True,
httponly=True
)
# 将对象添加到 headers
response.headers["set-cookie"] = cookie_obj
# 此时 response.headers 中包含: set-cookie: session_id=abc123; Path=/; Domain=example.com; Max-Age=3600; Secure; HttpOnly
使用 set_cookie 方法的参数影响
set_cookie 方法封装了底层的头部构建逻辑,它接受名称、值以及一系列可选参数如 max_age、expires、path、domain、secure、httponly 和 samesite。当调用此方法时,Starlette 会根据提供的参数生成具体的 Cookie 字符串。如果未指定 path,默认值为当前请求的路径;如果未指定 domain,则默认为当前主机。这些参数的不同组合会直接影响浏览器存储和发送 Cookie 的行为。
使用 Cookiecutter CLI 和 Jinja2 模板生成项目脚手架。支持自定义模板注册表、通过 Python 脚本的生成后钩子,以及与 GitHub 模板仓库 API 的集成。

from starlette.responses import Response
response = Response(content="User Logged In")
# 设置一个带有特定路径和过期时间的 Cookie
response.set_cookie(
key="user_token",
value="xyz789",
path="/dashboard",
max_age=86400, # 24小时
secure=True, # 仅 HTTPS
httponly=True, # 禁止 JS 访问
samesite="strict"
)
# 验证结果
print(response.headers.get("set-cookie"))
# 输出类似: user_token=xyz789; Path=/dashboard; Max-Age=86400; Secure; HttpOnly; SameSite=Strict
多次调用 set_cookie 会发生什么
如果在同一个响应对象上多次调用 set_cookie 方法,Starlette 不会覆盖之前的 Cookie,而是会将新的 Set-Cookie 头部追加到响应头列表中。这意味着浏览器会收到多个 Set-Cookie 指令,分别设置不同的 Cookie。这种行为对于需要在一次响应中设置多个独立 Cookie 的场景非常有用,例如同时设置会话 ID 和用户偏好设置。需要注意的是,每个 Cookie 都是独立的,修改其中一个不会影响其他已设置的 Cookie。










