启用会话¶

会话是通过一段中间件实现的。

要启用会话功能，请执行以下操作

• 编辑MIDDLEWARE 设置，并确保它包含 'django.contrib.sessions.middleware.SessionMiddleware'。由 django-admin startproject 创建的默认 settings.py 已激活 SessionMiddleware。

如果您不想使用会话，您可以从MIDDLEWARE中删除SessionMiddleware行，并从您的INSTALLED_APPS中删除'django.contrib.sessions'。这将节省您少量开销。

配置会话引擎¶

默认情况下，Django 将会话存储在您的数据库中（使用模型django.contrib.sessions.models.Session）。虽然这很方便，但在某些设置中，将会话数据存储在其他位置更快，因此可以配置 Django 将会话数据存储在您的文件系统或缓存中。

在视图中使用会话¶

当激活SessionMiddleware时，每个HttpRequest对象（任何 Django 视图函数的第一个参数）将具有一个session属性，这是一个类似字典的对象。

您可以在视图中的任何点读取和写入request.session。您可以多次编辑它。

class backends.base.SessionBase¶

这是所有会话对象的基类。它具有以下标准字典方法

__getitem__(key)¶

示例：fav_color = request.session['fav_color']

__setitem__(key, value)¶

示例：request.session['fav_color'] = 'blue'

__delitem__(key)¶

示例：del request.session['fav_color']。如果给定的key不在会话中，则会引发KeyError。

__contains__(key)¶

示例：'fav_color' in request.session

get(key, default=None)¶

aget(key, default=None)¶

异步版本：aget()

示例：fav_color = request.session.get('fav_color', 'red')

Django 5.1 中的更改

添加了aget()函数。

aset(key, value)¶

Django 5.1 新特性。

示例：await request.session.aset('fav_color', 'red')

update(dict)¶

aupdate(dict)¶

异步版本：aupdate()

示例：request.session.update({'fav_color': 'red'})

Django 5.1 中的更改

添加了aupdate()函数。

pop(key, default=__not_given)¶

apop(key, default=__not_given)¶

异步版本：apop()

示例：fav_color = request.session.pop('fav_color', 'blue')

Django 5.1 中的更改

添加了apop()函数。

keys()¶

akeys()¶

异步版本：akeys()

Django 5.1 中的更改

添加了akeys()函数。

values()¶

avalues()¶

异步版本：avalues()

Django 5.1 中的更改

添加了avalues()函数。

has_key(key)¶

ahas_key(key)¶

异步版本：ahas_key()

Django 5.1 中的更改

添加了ahas_key()函数。

items()¶

aitems()¶

异步版本：aitems()

Django 5.1 中的更改

添加了aitems()函数。

setdefault()¶

asetdefault()¶

异步版本：asetdefault()

Django 5.1 中的更改

添加了asetdefault()函数。

clear()¶

它还具有以下方法：

flush()¶

aflush()¶

异步版本：aflush()

删除会话中的当前会话数据并删除会话cookie。如果您想确保用户浏览器无法再次访问以前的会话数据（例如，django.contrib.auth.logout()函数会调用它），则可以使用此方法。

Django 5.1 中的更改

添加了aflush()函数。

set_test_cookie()¶

aset_test_cookie()¶

异步版本：aset_test_cookie()

设置测试cookie以确定用户浏览器是否支持cookie。由于cookie的工作方式，您必须等到用户的下一个页面请求才能测试它。有关更多信息，请参见下面的设置测试cookie。

Django 5.1 中的更改

添加了aset_test_cookie()函数。

test_cookie_worked()¶

atest_cookie_worked()¶

异步版本：atest_cookie_worked()

根据用户浏览器是否接受测试cookie，返回True或False。由于cookie的工作方式，您必须在之前的单独页面请求中调用set_test_cookie()或aset_test_cookie()。有关更多信息，请参见下面的设置测试cookie。

Django 5.1 中的更改

添加了atest_cookie_worked()函数。

delete_test_cookie()¶

adelete_test_cookie()¶

异步版本：adelete_test_cookie()

删除测试cookie。用它来清理。

Django 5.1 中的更改

添加了adelete_test_cookie()函数。

get_session_cookie_age()¶

返回设置SESSION_COOKIE_AGE的值。这可以在自定义会话后端中被覆盖。

set_expiry(value)¶

aset_expiry(value)¶

异步版本：aset_expiry()

设置会话的过期时间。您可以传递多个不同的值。

• 如果value是整数，则会话将在指定秒数的空闲时间后过期。例如，调用request.session.set_expiry(300)将使会话在5分钟后过期。

• 如果value是datetime或timedelta对象，会话将在该特定日期/时间过期。

• 如果value是0，则用户会话cookie将在用户关闭网页浏览器时过期。

• 如果value是None，则会话将恢复为使用全局会话过期策略。

读取会话不视为过期目的的活动。会话过期时间是从上次修改会话的时间计算的。

Django 5.1 中的更改

添加了aset_expiry()函数。

get_expiry_age()¶

aget_expiry_age()¶

异步版本：aget_expiry_age()

返回此会话过期前剩余的秒数。对于没有自定义过期时间（或设置为在浏览器关闭时过期）的会话，这将等于SESSION_COOKIE_AGE。

此函数接受两个可选关键字参数

• modification：会话的最后修改时间，作为datetime对象。默认为当前时间。

• expiry：会话的过期信息，作为datetime对象，一个int（以秒为单位），或None。默认为会话中由set_expiry()/aset_expiry()存储的值（如果存在），或None。

注意

此方法由会话后端用于在保存会话时确定会话过期时间（以秒为单位）。它并非真正用于此上下文之外。

特别是，虽然**可以**确定会话的剩余生命周期，**只有当**您拥有正确的modification值**并且**expiry设置为datetime对象时，您可以拥有modification值，通过手工计算过期时间更为直接。

expires_at = modification + timedelta(seconds=settings.SESSION_COOKIE_AGE)

Django 5.1 中的更改

添加了aget_expiry_age()函数。

get_expiry_date()¶

aget_expiry_date()¶

异步版本：aget_expiry_date()

返回此会话将过期的日期。对于没有自定义过期时间（或设置为在浏览器关闭时过期）的会话，这将等于SESSION_COOKIE_AGE秒后的日期。

此函数接受与get_expiry_age()相同的关键字参数，并应用类似的使用说明。

Django 5.1 中的更改

添加了aget_expiry_date()函数。

get_expire_at_browser_close()¶

aget_expire_at_browser_close()¶

异步版本：aget_expire_at_browser_close()

返回True或False，取决于用户会话cookie是否会在用户关闭网页浏览器时过期。

Django 5.1 中的更改

添加了aget_expire_at_browser_close()函数。

clear_expired()¶

aclear_expired()¶

异步版本：aclear_expired()

从会话存储中删除过期的会话。此类方法由clearsessions调用。

Django 5.1 中的更改

添加了aclear_expired()函数。

cycle_key()¶

acycle_key()¶

异步版本：acycle_key()

创建一个新的会话密钥，同时保留当前会话数据。django.contrib.auth.login()调用此方法以减轻会话固定问题。

Django 5.1 中的更改

添加了acycle_key()函数。

def post_comment(request, new_comment):
    if request.session.get("has_commented", False):
        return HttpResponse("You've already commented.")
    c = comments.Comment(comment=new_comment)
    c.save()
    request.session["has_commented"] = True
    return HttpResponse("Thanks for your comment!")

def login(request):
    m = Member.objects.get(username=request.POST["username"])
    if m.check_password(request.POST["password"]):
        request.session["member_id"] = m.id
        return HttpResponse("You're logged in.")
    else:
        return HttpResponse("Your username and password didn't match.")

def logout(request):
    try:
        del request.session["member_id"]
    except KeyError:
        pass
    return HttpResponse("You're logged out.")

设置测试 Cookie¶

为了方便起见，Django 提供了一种方法来测试用户的浏览器是否接受 Cookie。在视图中调用 request.session 的 set_test_cookie() 方法，并在后续视图中调用 test_cookie_worked() 方法——不要在同一个视图调用中调用。

由于 Cookie 的工作方式，set_test_cookie() 和 test_cookie_worked() 之间的这种笨拙的分割是必要的。当你设置 Cookie 时，你实际上无法知道浏览器是否接受它，直到浏览器的下一个请求。

最好使用 delete_test_cookie() 来清理你自己。在你验证测试 Cookie 成功后执行此操作。

这是一个典型的用法示例。

from django.http import HttpResponse
from django.shortcuts import render


def login(request):
    if request.method == "POST":
        if request.session.test_cookie_worked():
            request.session.delete_test_cookie()
            return HttpResponse("You're logged in.")
        else:
            return HttpResponse("Please enable cookies and try again.")
    request.session.set_test_cookie()
    return render(request, "foo/login_form.html")

在视图外部使用会话¶

>>> from importlib import import_module
>>> from django.conf import settings
>>> SessionStore = import_module(settings.SESSION_ENGINE).SessionStore

有一个 API 可用于在视图外部操作会话数据。

>>> from django.contrib.sessions.backends.db import SessionStore
>>> s = SessionStore()
>>> # stored as seconds since epoch since datetimes are not serializable in JSON.
>>> s["last_login"] = 1376587691
>>> s.create()
>>> s.session_key
'2b1189a188b44ad18c35e113ac6ceead'
>>> s = SessionStore(session_key="2b1189a188b44ad18c35e113ac6ceead")
>>> s["last_login"]
1376587691

SessionStore.create() 用于创建一个新的会话（即一个没有从会话存储加载并且 session_key=None 的会话）。save() 用于保存现有会话（即从会话存储加载的会话）。对新会话调用 save() 也可能有效，但有一小概率会生成与现有会话冲突的 session_key。create() 调用 save() 并循环，直到生成一个未使用的 session_key。

如果您使用的是 django.contrib.sessions.backends.db 后端，则每个会话都是一个普通的 Django 模型。Session 模型定义在 django/contrib/sessions/models.py 中。因为它是一个普通的模型，您可以使用普通的 Django 数据库 API 访问会话。

>>> from django.contrib.sessions.models import Session
>>> s = Session.objects.get(pk="2b1189a188b44ad18c35e113ac6ceead")
>>> s.expire_date
datetime.datetime(2005, 8, 20, 13, 35, 12)

请注意，您需要调用 get_decoded() 来获取会话字典。这是必要的，因为字典以编码格式存储。

>>> s.session_data
'KGRwMQpTJ19hdXRoX3VzZXJfaWQnCnAyCkkxCnMuMTExY2ZjODI2Yj...'
>>> s.get_decoded()
{'user_id': 42}

会话何时保存¶

默认情况下，只有在会话被修改时，Django 才会保存到会话数据库——也就是说，如果它的任何字典值已被赋值或删除。

# Session is modified.
request.session["foo"] = "bar"

# Session is modified.
del request.session["foo"]

# Session is modified.
request.session["foo"] = {}

# Gotcha: Session is NOT modified, because this alters
# request.session['foo'] instead of request.session.
request.session["foo"]["bar"] = "baz"

在上例的最后一种情况下，我们可以通过设置会话对象上的 modified 属性来显式地告诉会话对象它已被修改。

request.session.modified = True

要更改此默认行为，请将 SESSION_SAVE_EVERY_REQUEST 设置设置为 True。设置为 True 时，Django 将在每个请求中将会话保存到数据库。

请注意，只有在创建或修改会话时才会发送会话 Cookie。如果 SESSION_SAVE_EVERY_REQUEST 为 True，则会话 Cookie 将在每次请求时发送。

类似地，每次发送会话 Cookie 时都会更新会话 Cookie 的 expires 部分。

如果响应的状态码为 500，则不会保存会话。

浏览器会话与持久化会话¶

您可以使用 SESSION_EXPIRE_AT_BROWSER_CLOSE 设置来控制会话框架是使用浏览器会话还是持久化会话。

默认情况下，SESSION_EXPIRE_AT_BROWSER_CLOSE 设置为 False，这意味着会话 Cookie 将存储在用户的浏览器中，只要 SESSION_COOKIE_AGE 指定的时间内。如果您不希望用户每次打开浏览器都必须登录，请使用此设置。

如果 SESSION_EXPIRE_AT_BROWSER_CLOSE 设置为 True，Django 将使用浏览器会话 Cookie——一旦用户关闭浏览器就会过期的 Cookie。如果您希望用户每次打开浏览器都必须登录，请使用此设置。

此设置是一个全局默认值，可以通过显式调用 request.session 的 set_expiry() 方法（如上文 在视图中使用会话 中所述）来在每个会话级别覆盖。

清除会话存储¶

随着用户在您的网站上创建新的会话，会话数据可能会在您的会话存储中累积。如果您使用的是数据库后端，则 django_session 数据库表将增大。如果您使用的是文件后端，则您的临时目录将包含越来越多的文件。

要理解这个问题，请考虑使用数据库后端时会发生什么。当用户登录时，Django 会向 django_session 数据库表添加一行。每次会话数据更改时，Django 都会更新此行。如果用户手动注销，Django 将删除该行。但如果用户_不_注销，则该行永远不会被删除。文件后端也发生类似的过程。

Django_不_提供过期会话的自动清除。因此，定期清除过期会话是您的工作。Django 为此提供了一个清理管理命令：clearsessions。建议定期调用此命令，例如作为每日 cron 作业。

请注意，缓存后端不会受到此问题的困扰，因为缓存会自动删除陈旧数据。Cookie 后端也不会，因为会话数据由用户的浏览器存储。

设置¶

一些 Django 设置 可以让您控制会话行为。

• SESSION_CACHE_ALIAS

• SESSION_COOKIE_AGE

• SESSION_COOKIE_DOMAIN

• SESSION_COOKIE_HTTPONLY

• SESSION_COOKIE_NAME

• SESSION_COOKIE_PATH

• SESSION_COOKIE_SAMESITE

• SESSION_COOKIE_SECURE

• SESSION_ENGINE

• SESSION_EXPIRE_AT_BROWSER_CLOSE

• SESSION_FILE_PATH

• SESSION_SAVE_EVERY_REQUEST

• SESSION_SERIALIZER

会话安全性¶

站点内的子域名能够为整个域名设置客户端的 Cookie。如果允许来自不受信任用户控制的子域名的 Cookie，则可能导致会话固定。

例如，攻击者可以登录 good.example.com 并获取其帐户的有效会话。如果攻击者控制 bad.example.com，则他们可以使用它将他们的会话密钥发送给您，因为子域名被允许为 *.example.com 设置 Cookie。当您访问 good.example.com 时，您将以攻击者的身份登录，并且可能无意中将您的敏感个人数据（例如信用卡信息）输入攻击者的帐户。

另一种可能的攻击是，如果 good.example.com 将其 SESSION_COOKIE_DOMAIN 设置为 "example.com"，这将导致来自该站点的会话 Cookie 被发送到 bad.example.com。

技术细节¶

• 当使用 JSONSerializer 时，会话字典接受任何 json 可序列化的值。

• 会话数据存储在名为 django_session 的数据库表中。

• 只有在需要时，Django 才会发送 Cookie。如果您没有设置任何会话数据，它不会发送会话 Cookie。

扩展数据库支持的会话引擎¶

通过继承 AbstractBaseSession 和 SessionStore 类，可以创建基于 Django 中包含的引擎（即 db 和 cached_db）的自定义数据库支持的会话引擎。

可以从 django.contrib.sessions.base_session 导入 AbstractBaseSession 和 BaseSessionManager，这样就可以在不包含 django.contrib.sessions 在 INSTALLED_APPS 中的情况下导入它们。

class base_session.AbstractBaseSession¶

抽象的基础会话模型。

session_key¶

主键。字段本身最多可以包含 40 个字符。当前实现生成一个 32 个字符的字符串（数字和小写 ASCII 字母的随机序列）。

session_data¶

包含编码和序列化会话字典的字符串。

expire_date¶

指定会话过期时间的日期时间。

用户无法使用已过期的会话，但是，它们可能仍会存储在数据库中，直到运行 clearsessions 管理命令。

classmethod get_session_store_class()¶

返回要与此会话模型一起使用的会话存储类。

get_decoded()¶

返回解码后的会话数据。

解码由会话存储类执行。

您还可以通过子类化 BaseSessionManager 来自定义模型管理器。

class base_session.BaseSessionManager¶

encode(session_dict)¶

返回给定的会话字典，序列化并编码为字符串。

编码由与模型类绑定的会话存储类执行。

save(session_key, session_dict, expire_date)¶

保存提供的会话密钥的会话数据，或者在数据为空的情况下删除会话。

通过覆盖下面描述的方法和属性来实现 SessionStore 类的自定义。

class backends.db.SessionStore¶

实现基于数据库的会话存储。

classmethod get_model_class()¶

如果需要自定义会话模型，请重写此方法。

create_model_instance(data)¶

返回会话模型对象的新的实例，该实例表示当前会话状态。

重写此方法可以修改会话模型数据，然后将其保存到数据库。

class backends.cached_db.SessionStore¶

实现缓存的数据库支持的会话存储。

cache_key_prefix¶

添加到会话密钥以构建缓存密钥字符串的前缀。

from django.contrib.sessions.backends.db import SessionStore as DBStore
from django.contrib.sessions.base_session import AbstractBaseSession
from django.db import models


class CustomSession(AbstractBaseSession):
    account_id = models.IntegerField(null=True, db_index=True)

    @classmethod
    def get_session_store_class(cls):
        return SessionStore


class SessionStore(DBStore):
    @classmethod
    def get_model_class(cls):
        return CustomSession

    def create_model_instance(self, data):
        obj = super().create_model_instance(data)
        try:
            account_id = int(data.get("_auth_user_id"))
        except (ValueError, TypeError):
            account_id = None
        obj.account_id = account_id
        return obj

class SessionStore(CachedDBStore):
    cache_key_prefix = "mysessions.custom_cached_db_backend"

    # ...

URL 中的会话 ID¶

Django 会话框架完全且仅基于 Cookie。它不会像 PHP 那样作为最后手段将会话 ID 放入 URL 中。这是一个有意的设计决策。这种行为不仅使 URL 难看，还会使您的站点容易受到通过“Referer”标头进行的会话 ID 窃取的攻击。