Django 缓存框架

Memcached

Memcached is an entirely memory-based cache server, originally developed to handle high loads at LiveJournal.com and subsequently open-sourced by Danga Interactive. It is used by sites such as Facebook and Wikipedia to reduce database access and dramatically increase site performance.

Memcached 以一个守护进程的形式运行，并且被分配了指定数量的 RAM。它所做的就是提供一个快速接口用于在缓存中添加，检索和删除数据。所有数据都直接存储在内存中，因此不会产生数据库或文件系统使用的开销。

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

在 Django 中使用 Memcached ：

• 设置 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 socket 文件的路径。

在这个例子中，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',
        ]
    }
}

By default, the PyMemcacheCache backend sets the following options (you can override them in your OPTIONS):

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

关于 Memcached 的最后一点是，基于内存的缓存有一个缺点：因为缓存的数据存储在内存中，如果你的服务器崩溃，数据将丢失。显然，内存并不是用来永久存储数据的，所以不要依赖基于内存的缓存作为你唯一的数据存储。毫无疑问，Django 缓存后端中的 每个 都不应该用于永久存储 —— 它们的目的都是为了缓存的解决方案，而不是存储 —— 但我们在这里指出这一点是因为基于内存的缓存是格外临时的。

Redis

Redis is an in-memory database that can be used for caching. To begin you'll need a Redis server running either locally or on a remote machine.

After setting up the Redis server, you'll need to install Python bindings for Redis. redis-py is the binding supported natively by Django. Installing the additional hiredis-py package is also recommended.

To use Redis as your cache backend with Django:

• Set BACKEND to django.core.cache.backends.redis.RedisCache.
• Set LOCATION to the URL pointing to your Redis instance, using the appropriate scheme. See the redis-py docs for details on the available schemes.

For example, if Redis is running on localhost (127.0.0.1) port 6379:

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

Often Redis servers are protected with authentication. In order to supply a username and password, add them in the LOCATION along with the URL:

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

If you have multiple Redis servers set up in the replication mode, you can specify the servers either as a semicolon or comma delimited string, or as a list. While using multiple servers, write operations are performed on the first server (leader). Read operations are performed on the other servers (replicas) chosen at random:

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',
    }
}

Unlike other cache backends, the database cache does not support automatic culling of expired entries at the database level. Instead, expired cache entries are culled each time add(), set(), or touch() is called.

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

本地内存缓存

如果你的配置文件中没有指定其他缓存，那么这是默认的缓存。如果你想获得内存缓存的速度优势，但又不具备运行 Memcached 的能力，可以考虑使用本地内存缓存后端。这个缓存是每进程所有（见下文）和线程安全的。要使用它，可以将 BACKEND 设置为 "django.core.cache.backends.locmem.LocMemCache"。例如：

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

LOCATION 被用于标识各个内存存储。如果只有一个 locmem 缓存，你可以忽略 LOCATION 。但是如果你有多个本地内存缓存，那么你至少要为其中一个起个名字，以便将它们区分开。

这种缓存使用最近最少使用（LRU）的淘汰策略。

请注意，每个进程都会有自己的私有缓存实例，这意味着不可能进行跨进程缓存。这也意味着本地内存缓存的内存效率不是特别高，所以对于生产环境来说，它可能不是一个好的选择。对于开发来说是不错的选择。

缓存参数

每个缓存后端可以通过额外的参数来控制缓存行为。这些参数在 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 ），这使得缓存速度 更 快，但代价是缓存未命中更多。

  The Memcached and Redis backends pass the contents of OPTIONS as keyword arguments to the client constructors, allowing for more advanced control of client behavior. For example usage, see below.

• 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／网络错误视为缓存失效，并在连接的 socket 上设置了 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,
        }
    }
}

Here's an example configuration for a redis based backend that selects database 10 (by default Redis ships with 16 logical databases), specifies a parser class (redis.connection.HiredisParser will be used by default if the hiredis-py package is installed), and sets a custom connection pool class (redis.ConnectionPool is used by default):

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

基本用法

基本接口是：

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 是一个字符串，value 可以任何 picklable 形式的 Python 对象。

timeout 参数是可选的，默认为 CACHES 中相应后端的 timeout 参数。它是值存在缓存里的秒数。timeout 设置为 None 时将永久缓存。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() 可以带一个默认参数。如果对象不在缓存中，将返回指定的值。

>>> 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'

你也可以传递任何可调用的值作为默认值：

>>> 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() 接口，返回一个字典，其中包含你请求的键，这些键真实存在缓存中（并且没过期）：

>>> 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() ，否则返回 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 还是 get 特定缓存键的版本。举例：

>>> # 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() 原型匹配的函数路径。如果提供，这个自定义键函数将代替默认的键组合函数来使用。