Memcached¶

Memcached 是一个完全基于内存的缓存服务器，最初是为了处理 LiveJournal.com 上的高负载而开发的，随后由 Danga Interactive 开源。Facebook 和维基百科等网站使用它来减少数据库访问并显著提高网站性能。

Memcached 作为守护进程运行，并分配给定的内存量。它所做的只是提供一个快速接口来添加、检索和删除缓存中的数据。所有数据都直接存储在内存中，因此没有数据库或文件系统使用的开销。

在安装 Memcached 本身后，您需要安装 Memcached 绑定。有几个 Python Memcached 绑定可用；Django 支持的两个是 pylibmc 和 pymemcache。

要将 Memcached 与 Django 一起使用

• 将 BACKEND 设置为 django.core.cache.backends.memcached.PyMemcacheCache 或 django.core.cache.backends.memcached.PyLibMCCache（取决于您选择的 memcached 绑定）

• 将 LOCATION 设置为 ip:port 值，其中 ip 是 Memcached 守护进程的 IP 地址，port 是 Memcached 正在运行的端口，或者设置为 unix:path 值，其中 path 是 Memcached Unix 套接字文件的路径。

在此示例中，Memcached 在 localhost (127.0.0.1) 端口 11211 上运行，使用 pymemcache 绑定

CACHES = {
    "default": {
        "BACKEND": "django.core.cache.backends.memcached.PyMemcacheCache",
        "LOCATION": "127.0.0.1:11211",
    }
}

在此示例中，Memcached 通过本地 Unix 套接字文件 /tmp/memcached.sock 使用 pymemcache 绑定可用

CACHES = {
    "default": {
        "BACKEND": "django.core.cache.backends.memcached.PyMemcacheCache",
        "LOCATION": "unix:/tmp/memcached.sock",
    }
}

Memcached 的一个极佳特性是它能够在多台服务器上共享缓存。这意味着您可以在多台机器上运行 Memcached 守护进程，程序将把这组机器视为一个单个缓存，而无需在每台机器上复制缓存值。要利用此功能，请在 LOCATION 中包含所有服务器地址，可以是分号或逗号分隔的字符串，也可以是列表。

在此示例中，缓存在 IP 地址为 172.19.26.240 和 172.19.26.242 的 Memcached 实例上共享，两者都在端口 11211 上

CACHES = {
    "default": {
        "BACKEND": "django.core.cache.backends.memcached.PyMemcacheCache",
        "LOCATION": [
            "172.19.26.240:11211",
            "172.19.26.242:11211",
        ],
    }
}

在以下示例中，缓存在 IP 地址为 172.19.26.240（端口 11211）、172.19.26.242（端口 11212）和 172.19.26.244（端口 11213）的 Memcached 实例上共享

CACHES = {
    "default": {
        "BACKEND": "django.core.cache.backends.memcached.PyMemcacheCache",
        "LOCATION": [
            "172.19.26.240:11211",
            "172.19.26.242:11212",
            "172.19.26.244:11213",
        ],
    }
}

默认情况下，PyMemcacheCache 后端设置以下选项（您可以在您的 OPTIONS 中覆盖它们）

"OPTIONS": {
    "allow_unicode_keys": True,
    "default_noreply": False,
    "serde": pymemcache.serde.pickle_serde,
}

关于 Memcached 的最后一点是，基于内存的缓存有一个缺点：由于缓存的数据存储在内存中，因此如果服务器崩溃，数据将会丢失。显然，内存并非用于永久数据存储，因此不要依赖基于内存的缓存作为您的唯一数据存储。毫无疑问，任何 Django 缓存后端都不应该用于永久存储——它们都旨在作为缓存解决方案，而不是存储解决方案——但我们在这里指出这一点，因为基于内存的缓存特别临时。

Redis¶

Redis 是一个内存数据库，可用于缓存。首先，您需要在本地或远程机器上运行一个 Redis 服务器。

设置 Redis 服务器后，您需要安装 Redis 的 Python 绑定。 redis-py 是 Django 原生支持的绑定。还建议安装 hiredis-py 包。

要将 Redis 作为缓存后端与 Django 一起使用

• 将 BACKEND 设置为 django.core.cache.backends.redis.RedisCache。

• 将 LOCATION 设置为指向您的 Redis 实例的 URL，使用相应的方案。有关可用方案的详细信息，请参阅 redis-py 文档 details on the available schemes。

例如，如果 Redis 在 localhost (127.0.0.1) 端口 6379 上运行

CACHES = {
    "default": {
        "BACKEND": "django.core.cache.backends.redis.RedisCache",
        "LOCATION": "redis://127.0.0.1:6379",
    }
}

Redis 服务器通常受身份验证保护。为了提供用户名和密码，请将它们与 URL 一起添加到 LOCATION 中

CACHES = {
    "default": {
        "BACKEND": "django.core.cache.backends.redis.RedisCache",
        "LOCATION": "redis://username:password@127.0.0.1:6379",
    }
}

如果您在复制模式下设置了多个 Redis 服务器，则可以将服务器指定为分号或逗号分隔的字符串，也可以指定为列表。在使用多台服务器时，写操作将在第一台服务器（领导者）上执行。读操作将在随机选择的其他服务器（副本）上执行

CACHES = {
    "default": {
        "BACKEND": "django.core.cache.backends.redis.RedisCache",
        "LOCATION": [
            "redis://127.0.0.1:6379",  # leader
            "redis://127.0.0.1:6378",  # read-replica 1
            "redis://127.0.0.1:6377",  # read-replica 2
        ],
    }
}

数据库缓存¶

Django 可以将其缓存的数据存储在您的数据库中。如果您有一个快速且索引良好的数据库服务器，这将非常有效。

要使用数据库表作为缓存后端

• 将 BACKEND 设置为 django.core.cache.backends.db.DatabaseCache

• 将 LOCATION 设置为 tablename，即数据库表的名称。此名称可以是任何您想要的名称，只要它是一个有效的表名称，并且在您的数据库中尚未使用即可。

在此示例中，缓存表的名称为 my_cache_table

CACHES = {
    "default": {
        "BACKEND": "django.core.cache.backends.db.DatabaseCache",
        "LOCATION": "my_cache_table",
    }
}

与其他缓存后端不同，数据库缓存不支持在数据库级别自动剔除过期条目。相反，每次调用 add()、set() 或 touch() 时都会剔除过期的缓存条目。

python manage.py createcachetable

class CacheRouter:
    """A router to control all database cache operations"""

    def db_for_read(self, model, **hints):
        "All cache read operations go to the replica"
        if model._meta.app_label == "django_cache":
            return "cache_replica"
        return None

    def db_for_write(self, model, **hints):
        "All cache write operations go to primary"
        if model._meta.app_label == "django_cache":
            return "cache_primary"
        return None

    def allow_migrate(self, db, app_label, model_name=None, **hints):
        "Only install the cache model on primary"
        if app_label == "django_cache":
            return db == "cache_primary"
        return None

文件系统缓存¶

基于文件的后端将每个缓存值序列化并存储为单独的文件。要使用此后端，请将 BACKEND 设置为 "django.core.cache.backends.filebased.FileBasedCache"，并将 LOCATION 设置为合适的目录。例如，要将缓存数据存储在 /var/tmp/django_cache 中，请使用以下设置

CACHES = {
    "default": {
        "BACKEND": "django.core.cache.backends.filebased.FileBasedCache",
        "LOCATION": "/var/tmp/django_cache",
    }
}

如果您使用的是 Windows，请在路径的开头加上驱动器号，如下所示

CACHES = {
    "default": {
        "BACKEND": "django.core.cache.backends.filebased.FileBasedCache",
        "LOCATION": "c:/foo/bar",
    }
}

目录路径应为绝对路径，即应从文件系统的根目录开始。在设置的末尾添加斜杠与否无关紧要。

确保此设置指向的目录要么存在且可读可写，要么可以由您的 Web 服务器运行的用户创建。继续上面的示例，如果您的服务器以用户 apache 运行，请确保目录 /var/tmp/django_cache 存在且用户 apache 可读可写，或者可以由用户 apache 创建。

本地内存缓存¶

如果您的设置文件中未指定其他缓存，则此缓存为默认缓存。如果您想要内存缓存的速度优势，但没有运行 Memcached 的能力，请考虑使用本地内存缓存后端。此缓存是每个进程（见下文）的缓存，并且是线程安全的。要使用它，请将 BACKEND 设置为 "django.core.cache.backends.locmem.LocMemCache"。例如

CACHES = {
    "default": {
        "BACKEND": "django.core.cache.backends.locmem.LocMemCache",
        "LOCATION": "unique-snowflake",
    }
}

缓存 LOCATION 用于识别各个内存存储。如果您只有一个 locmem 缓存，您可以省略 LOCATION；但是，如果您有多个本地内存缓存，则需要为其中至少一个分配名称以保持它们彼此独立。

缓存使用最近最少使用 (LRU) 剔除策略。

请注意，每个进程将拥有自己的私有缓存实例，这意味着无法进行跨进程缓存。这也意味着本地内存缓存在内存效率方面并不高，因此它可能不适合生产环境。它非常适合开发环境。

虚拟缓存（用于开发）¶

最后，Django 带有一个“虚拟”缓存，它实际上不缓存——它只是实现了缓存接口，但什么也不做。

如果您有一个在多个地方使用重型缓存的生产站点，但又有一个您不想缓存并且不想更改代码以专门处理后者的开发/测试环境，这将非常有用。要激活虚拟缓存，请将 BACKEND 设置如下

CACHES = {
    "default": {
        "BACKEND": "django.core.cache.backends.dummy.DummyCache",
    }
}

使用自定义缓存后端¶

虽然 Django 内置支持许多缓存后端，但有时您可能希望使用自定义缓存后端。要将外部缓存后端与 Django 一起使用，请使用 Python 导入路径作为 BACKEND 的 CACHES 设置，如下所示

CACHES = {
    "default": {
        "BACKEND": "path.to.backend",
    }
}

如果您正在构建自己的后端，您可以使用标准缓存后端作为参考实现。您可以在 Django 源代码的 django/core/cache/backends/ 目录中找到代码。

注意：如果没有真正令人信服的原因，例如主机不支持它们，您应该坚持使用 Django 附带的缓存后端。它们经过了充分测试并且有良好的文档记录。

缓存参数¶

每个缓存后端都可以提供其他参数来控制缓存行为。这些参数作为 CACHES 设置中的其他键提供。有效参数如下

• TIMEOUT：缓存使用的默认超时时间（以秒为单位）。此参数默认为 300 秒（5 分钟）。您可以将 TIMEOUT 设置为 None，以便默认情况下缓存键永不过期。值为 0 会导致键立即过期（实际上是“不缓存”）。

• OPTIONS：应传递给缓存后端的任何选项。有效选项列表因后端而异，并且由第三方库支持的缓存后端会将其选项直接传递给底层缓存库。

  实现其自身剔除策略的缓存后端（即 locmem、filesystem 和 database 后端）将遵循以下选项

  • MAX_ENTRIES：在删除旧值之前，缓存中允许的最大条目数。此参数默认为 300。

  • CULL_FREQUENCY：达到 MAX_ENTRIES 时剔除的条目分数。实际比率为 1 / CULL_FREQUENCY，因此将 CULL_FREQUENCY 设置为 2 表示在达到 MAX_ENTRIES 时剔除一半的条目。此参数应为整数，默认为 3。

    CULL_FREQUENCY 的值为 0 表示在达到 MAX_ENTRIES 时将清空整个缓存。在某些后端（尤其是 database）上，这使得剔除速度大大提高，但代价是缓存未命中次数增加。

  Memcached 和 Redis 后端将 OPTIONS 的内容作为关键字参数传递给客户端构造函数，从而允许更高级地控制客户端行为。有关示例用法，请参见下文。

• KEY_PREFIX：一个字符串，它将自动包含（默认情况下前缀）在 Django 服务器使用的所有缓存键中。

  有关更多信息，请参阅 缓存文档。

• VERSION：Django 服务器生成的缓存键的默认版本号。

  有关更多信息，请参阅 缓存文档。

• KEY_FUNCTION 一个包含点分路径的字符串，该路径指向一个函数，该函数定义如何将前缀、版本和键组合成最终的缓存键。

  有关更多信息，请参阅 缓存文档。

在此示例中，文件系统后端配置了 60 秒的超时时间和 1000 个项目的最大容量。

CACHES = {
    "default": {
        "BACKEND": "django.core.cache.backends.filebased.FileBasedCache",
        "LOCATION": "/var/tmp/django_cache",
        "TIMEOUT": 60,
        "OPTIONS": {"MAX_ENTRIES": 1000},
    }
}

这是一个基于 pylibmc 的后端的示例配置，它启用了二进制协议、SASL 身份验证和 ketama 行为模式。

CACHES = {
    "default": {
        "BACKEND": "django.core.cache.backends.memcached.PyLibMCCache",
        "LOCATION": "127.0.0.1:11211",
        "OPTIONS": {
            "binary": True,
            "username": "user",
            "password": "pass",
            "behaviors": {
                "ketama": True,
            },
        },
    }
}

这是一个基于 pymemcache 的后端的示例配置，它启用了客户端池（通过保持客户端连接可以提高性能），将 memcache/网络错误视为缓存未命中，并在连接的套接字上设置 TCP_NODELAY 标志。

CACHES = {
    "default": {
        "BACKEND": "django.core.cache.backends.memcached.PyMemcacheCache",
        "LOCATION": "127.0.0.1:11211",
        "OPTIONS": {
            "no_delay": True,
            "ignore_exc": True,
            "max_pool_size": 4,
            "use_pooling": True,
        },
    }
}

这是一个基于 redis 的后端的示例配置，它选择数据库 10（默认情况下 Redis 附带 16 个逻辑数据库），并设置自定义的 连接池类（默认情况下使用 redis.ConnectionPool）。

CACHES = {
    "default": {
        "BACKEND": "django.core.cache.backends.redis.RedisCache",
        "LOCATION": "redis://127.0.0.1:6379",
        "OPTIONS": {
            "db": "10",
            "pool_class": "redis.BlockingConnectionPool",
        },
    }
}

在 URLconf 中指定每个视图缓存¶

前面章节中的示例硬编码了视图被缓存的事实，因为cache_page会就地修改my_view函数。这种方法将您的视图与缓存系统耦合在一起，这出于多种原因并非理想之选。例如，您可能希望在另一个无缓存的站点上重用视图函数，或者您可能希望将视图分发给可能希望在未缓存的情况下使用它们的人员。解决这些问题的方案是在 URLconf 中指定每个视图的缓存，而不是在视图函数本身旁边指定。

您可以在 URLconf 中引用视图函数时，使用cache_page将其包装起来。以下是之前 URLconf 的旧版本

urlpatterns = [
    path("foo/<int:code>/", my_view),
]

这是相同的内容，使用cache_page包装了my_view

from django.views.decorators.cache import cache_page

urlpatterns = [
    path("foo/<int:code>/", cache_page(60 * 15)(my_view)),
]

访问缓存¶

django.core.cache.caches¶

您可以通过类似字典的对象访问CACHES设置中配置的缓存：django.core.cache.caches。在同一线程中对相同别名的重复请求将返回相同的对象。

>>> from django.core.cache import caches
>>> cache1 = caches["myalias"]
>>> cache2 = caches["myalias"]
>>> cache1 is cache2
True

如果指定的键不存在，则会引发InvalidCacheBackendError。

为了提供线程安全性，每个线程都会返回缓存后端的不同实例。

django.core.cache.cache¶

作为快捷方式，默认缓存可作为django.core.cache.cache使用

>>> from django.core.cache import cache

此对象等效于caches['default']。

基本用法¶

基本接口为

cache.set(key, value, timeout=DEFAULT_TIMEOUT, version=None)¶

>>> cache.set("my_key", "hello, world!", 30)

cache.get(key, default=None, version=None)¶

>>> cache.get("my_key")
'hello, world!'

key 应为str，value可以是任何可 pickle 的 Python 对象。

timeout参数是可选的，默认为CACHES设置中相应后端的timeout参数（如上所述）。它是值应在缓存中存储的秒数。将None传递给timeout将永远缓存该值。timeout为0将不会缓存该值。

如果对象在缓存中不存在，则cache.get()将返回None

>>> # Wait 30 seconds for 'my_key' to expire...
>>> cache.get("my_key")
None

如果您需要确定对象是否存在于缓存中，并且您已存储字面值None，请使用哨兵对象作为默认值

>>> sentinel = object()
>>> cache.get("my_key", sentinel) is sentinel
False
>>> # Wait 30 seconds for 'my_key' to expire...
>>> cache.get("my_key", sentinel) is sentinel
True

cache.get()可以接受default参数。这指定了如果对象在缓存中不存在要返回的值

>>> cache.get("my_key", "has expired")
'has expired'

cache.add(key, value, timeout=DEFAULT_TIMEOUT, version=None)¶

要仅在键不存在时添加键，请使用add()方法。它与set()的参数相同，但如果指定的键已存在，则不会尝试更新缓存

>>> cache.set("add_key", "Initial value")
>>> cache.add("add_key", "New value")
>>> cache.get("add_key")
'Initial value'

如果您需要知道add()是否已将值存储在缓存中，则可以检查返回值。如果值已存储，则它将返回True，否则返回False。

cache.get_or_set(key, default, timeout=DEFAULT_TIMEOUT, version=None)¶

如果您想获取键的值，或者在键不存在于缓存中时设置一个值，可以使用 get_or_set() 方法。它接受与 get() 相同的参数，但默认值将被设置为该键的新缓存值，而不是被返回。

>>> cache.get("my_new_key")  # returns None
>>> cache.get_or_set("my_new_key", "my new value", 100)
'my new value'

您还可以传递任何可调用对象作为 default 值。

>>> import datetime
>>> cache.get_or_set("some-timestamp-key", datetime.datetime.now)
datetime.datetime(2014, 12, 11, 0, 15, 49, 457920)

cache.get_many(keys, version=None)¶

还有一个 get_many() 接口，它只访问缓存一次。 get_many() 返回一个字典，其中包含您请求的所有实际存在于缓存中（并且未过期）的键。

>>> cache.set("a", 1)
>>> cache.set("b", 2)
>>> cache.set("c", 3)
>>> cache.get_many(["a", "b", "c"])
{'a': 1, 'b': 2, 'c': 3}

cache.set_many(dict, timeout)¶

为了更有效地设置多个值，可以使用 set_many() 传递一个键值对字典。

>>> cache.set_many({"a": 1, "b": 2, "c": 3})
>>> cache.get_many(["a", "b", "c"])
{'a': 1, 'b': 2, 'c': 3}

与 cache.set() 一样， set_many() 接受一个可选的 timeout 参数。

在受支持的后端（memcached）上， set_many() 返回一个插入失败的键列表。

cache.delete(key, version=None)¶

您可以使用 delete() 显式删除键，以清除特定对象的缓存。

>>> cache.delete("a")
True

delete() 如果键成功删除则返回 True，否则返回 False。

cache.delete_many(keys, version=None)¶

如果您想一次清除多个键， delete_many() 可以接受一个要清除的键列表。

>>> cache.delete_many(["a", "b", "c"])

cache.clear()¶

最后，如果您想删除缓存中的所有键，请使用 cache.clear()。请谨慎使用此方法； clear() 将删除缓存中的 所有 内容，而不仅仅是您的应用程序设置的键。

>>> cache.clear()

cache.touch(key, timeout=DEFAULT_TIMEOUT, version=None)¶

cache.touch() 为键设置新的过期时间。例如，要更新一个键使其在 10 秒后过期。

>>> cache.touch("a", 10)
True

与其他方法一样， timeout 参数是可选的，默认为 CACHES 设置中相应后端的 TIMEOUT 选项。

touch() 如果键成功更新则返回 True，否则返回 False。

cache.incr(key, delta=1, version=None)¶

cache.decr(key, delta=1, version=None)¶

您还可以分别使用 incr() 或 decr() 方法递增或递减已存在的键。默认情况下，现有的缓存值将递增或递减 1。可以通过向增量/减量调用提供参数来指定其他增量/减量值。如果您尝试递增或递减一个不存在的缓存键，则会引发 ValueError。

>>> cache.set("num", 1)
>>> cache.incr("num")
2
>>> cache.incr("num", 10)
12
>>> cache.decr("num")
11
>>> cache.decr("num", 5)
6

cache.close()¶

如果缓存后端实现了 close() 方法，您可以使用它关闭与缓存的连接。

>>> cache.close()

缓存键前缀¶

如果您在服务器之间或生产环境和开发环境之间共享缓存实例，则可能导致一台服务器缓存的数据被另一台服务器使用。如果缓存数据格式在服务器之间不同，则可能导致一些非常难以诊断的问题。

为了防止这种情况，Django 提供了为服务器使用的所有缓存键添加前缀的功能。当保存或检索特定的缓存键时，Django 会自动在缓存键前面加上 KEY_PREFIX 缓存设置的值。

通过确保每个 Django 实例都有一个不同的 KEY_PREFIX，您可以确保缓存值不会发生冲突。

缓存版本控制¶

当您更改使用缓存值的运行代码时，您可能需要清除任何现有的缓存值。最简单的方法是刷新整个缓存，但这可能导致丢失仍然有效且有用的缓存值。

Django 提供了一种更好地定位单个缓存值的方法。Django 的缓存框架有一个系统范围的版本标识符，使用 VERSION 缓存设置指定。此设置的值会自动与缓存前缀和用户提供的缓存键组合，以获得最终的缓存键。

默认情况下，任何键请求都将自动包含站点默认的缓存键版本。但是，基本缓存函数都包含一个 version 参数，因此您可以指定特定的缓存键版本来设置或获取。例如

>>> # Set version 2 of a cache key
>>> cache.set("my_key", "hello world!", version=2)
>>> # Get the default version (assuming version=1)
>>> cache.get("my_key")
None
>>> # Get version 2 of the same key
>>> cache.get("my_key", version=2)
'hello world!'

可以使用 incr_version() 和 decr_version() 方法递增和递减特定键的版本。这使得可以将特定键提升到新版本，而不会影响其他键。继续我们之前的示例

>>> # Increment the version of 'my_key'
>>> cache.incr_version("my_key")
>>> # The default version still isn't available
>>> cache.get("my_key")
None
# Version 2 isn't available, either
>>> cache.get("my_key", version=2)
None
>>> # But version 3 *is* available
>>> cache.get("my_key", version=3)
'hello world!'

缓存键转换¶

如前两节所述，用户提供的缓存键不会原样使用——它会与缓存前缀和键版本组合以提供最终的缓存键。默认情况下，这三个部分使用冒号连接以生成最终字符串。

def make_key(key, key_prefix, version):
    return "%s:%s:%s" % (key_prefix, version, key)

如果希望以不同的方式组合这些部分，或对最终键应用其他处理（例如，获取键部分的哈希摘要），则可以提供自定义键函数。

缓存设置 KEY_FUNCTION 指定了一个指向与上述 make_key() 原型匹配的函数的点分路径。如果提供了该函数，则将使用此自定义键函数，而不是默认的键组合函数。

缓存键警告¶

Memcached 是最常用的生产缓存后端，它不允许缓存键长度超过 250 个字符或包含空格或控制字符，使用此类键会导致异常。为了鼓励可移植的缓存代码并最大程度地减少意外情况，其他内置缓存后端会在使用可能导致 Memcached 错误的键时发出警告（django.core.cache.backends.base.CacheKeyWarning）。

如果使用的是可以接受更广泛的键范围的生产后端（自定义后端或非 Memcached 内置后端之一），并且希望在不发出警告的情况下使用此更广泛的范围，则可以在其中一个 INSTALLED_APPS 的 management 模块中使用以下代码来抑制 CacheKeyWarning。

import warnings

from django.core.cache import CacheKeyWarning

warnings.simplefilter("ignore", CacheKeyWarning)

如果希望为其中一个内置后端提供自定义键验证逻辑，则可以对其进行子类化，仅重写 validate_key 方法，并按照 使用自定义缓存后端 的说明进行操作。例如，要为 locmem 后端执行此操作，请将以下代码放在某个模块中。

from django.core.cache.backends.locmem import LocMemCache


class CustomLocMemCache(LocMemCache):
    def validate_key(self, key):
        """Custom validation, raising exceptions or warnings as needed."""
        ...

…并在 BACKEND 部分的 CACHES 设置中使用此类的点分 Python 路径。