Django2.0手册:Django’s cache framework

Memcached¶

The fastest, most efficient type of cache supported natively by Django,
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 runs as a daemon and is allotted a specified amount of RAM. All it
does is provide a fast interface for adding, retrieving and deleting data in
the cache. All data is stored directly in memory, so there’s no overhead of
database or filesystem usage.

After installing Memcached itself, you’ll need to install a Memcached
binding. There are several Python Memcached bindings available; the
two most common are python-memcached and pylibmc.

To use Memcached with Django:

• Set BACKEND to
  django.core.cache.backends.memcached.MemcachedCache or
  django.core.cache.backends.memcached.PyLibMCCache (depending
  on your chosen memcached binding)
• Set LOCATION to ip:port values,
  where ip is the IP address of the Memcached daemon and port is the
  port on which Memcached is running, or to a unix:path value, where
  path is the path to a Memcached Unix socket file.

In this example, Memcached is running on localhost (127.0.0.1) port 11211, using
the python-memcached binding:

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

In this example, Memcached is available through a local Unix socket file
/tmp/memcached.sock using the python-memcached binding:

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

When using the pylibmc binding, do not include the unix:/ prefix:

CACHES = {
    'default': {
        'BACKEND': 'django.core.cache.backends.memcached.PyLibMCCache',
        'LOCATION': '/tmp/memcached.sock',
    }
}

One excellent feature of Memcached is its ability to share a cache over
multiple servers. This means you can run Memcached daemons on multiple
machines, and the program will treat the group of machines as a single
cache, without the need to duplicate cache values on each machine. To take
advantage of this feature, include all server addresses in
LOCATION, either as a semicolon or comma
delimited string, or as a list.

In this example, the cache is shared over Memcached instances running on IP
address 172.19.26.240 and 172.19.26.242, both on port 11211:

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

In the following example, the cache is shared over Memcached instances running
on the IP addresses 172.19.26.240 (port 11211), 172.19.26.242 (port 11212), and
172.19.26.244 (port 11213):

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

A final point about Memcached is that memory-based caching has a
disadvantage: because the cached data is stored in memory, the data will be
lost if your server crashes. Clearly, memory isn’t intended for permanent data
storage, so don’t rely on memory-based caching as your only data storage.
Without a doubt, none of the Django caching backends should be used for
permanent storage — they’re all intended to be solutions for caching, not
storage — but we point this out here because memory-based caching is
particularly temporary.

Database caching¶

Django can store its cached data in your database. This works best if you’ve
got a fast, well-indexed database server.

To use a database table as your cache backend:

• Set BACKEND to
  django.core.cache.backends.db.DatabaseCache
• Set LOCATION to tablename, the name of the
  database table. This name can be whatever you want, as long as it’s a valid
  table name that’s not already being used in your database.

In this example, the cache table’s name is my_cache_table:

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

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

Filesystem caching¶

The file-based backend serializes and stores each cache value as a separate
file. To use this backend set BACKEND to
"django.core.cache.backends.filebased.FileBasedCache" and
LOCATION to a suitable directory. For example,
to store cached data in /var/tmp/django_cache, use this setting:

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

If you’re on Windows, put the drive letter at the beginning of the path,
like this:

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

The directory path should be absolute — that is, it should start at the root
of your filesystem. It doesn’t matter whether you put a slash at the end of the
setting.

Make sure the directory pointed-to by this setting exists and is readable and
writable by the system user under which your Web server runs. Continuing the
above example, if your server runs as the user apache, make sure the
directory /var/tmp/django_cache exists and is readable and writable by the
user apache.

Local-memory caching¶

This is the default cache if another is not specified in your settings file. If
you want the speed advantages of in-memory caching but don’t have the capability
of running Memcached, consider the local-memory cache backend. This cache is
per-process (see below) and thread-safe. To use it, set BACKEND to "django.core.cache.backends.locmem.LocMemCache". For
example:

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

The cache LOCATION is used to identify individual
memory stores. If you only have one locmem cache, you can omit the
LOCATION; however, if you have more than one local
memory cache, you will need to assign a name to at least one of them in
order to keep them separate.

Note that each process will have its own private cache instance, which means no
cross-process caching is possible. This obviously also means the local memory
cache isn’t particularly memory-efficient, so it’s probably not a good choice
for production environments. It’s nice for development.

Dummy caching (for development)¶

Finally, Django comes with a “dummy” cache that doesn’t actually cache — it
just implements the cache interface without doing anything.

This is useful if you have a production site that uses heavy-duty caching in
various places but a development/test environment where you don’t want to cache
and don’t want to have to change your code to special-case the latter. To
activate dummy caching, set BACKEND like so:

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

使用自定义的缓存后台¶

While Django includes support for a number of cache backends out-of-the-box,
sometimes you might want to use a customized cache backend. To use an external
cache backend with Django, use the Python import path as the
BACKEND of the CACHES setting, like so:

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

If you’re building your own backend, you can use the standard cache backends
as reference implementations. You’ll find the code in the
django/core/cache/backends/ directory of the Django source.

Note: Without a really compelling reason, such as a host that doesn’t support
them, you should stick to the cache backends included with Django. They’ve
been well-tested and are easy to use.

Cache arguments¶

Each cache backend can be given additional arguments to control caching
behavior. These arguments are provided as additional keys in the
CACHES setting. Valid arguments are as follows:

• TIMEOUT: The default timeout, in
  seconds, to use for the cache. This argument defaults to 300 seconds (5 minutes).
  You can set TIMEOUT to None so that, by default, cache keys never
  expire. A value of 0 causes keys to immediately expire (effectively
  “don’t cache”).

• OPTIONS: Any options that should be
  passed to the cache backend. The list of valid options will vary
  with each backend, and cache backends backed by a third-party library
  will pass their options directly to the underlying cache library.

  Cache backends that implement their own culling strategy (i.e.,
  the locmem, filesystem and database backends) will
  honor the following options:

  • MAX_ENTRIES: The maximum number of entries allowed in
    the cache before old values are deleted. This argument
    defaults to 300.

  • CULL_FREQUENCY: The fraction of entries that are culled
    when MAX_ENTRIES is reached. The actual ratio is
    1 / CULL_FREQUENCY, so set CULL_FREQUENCY to 2 to
    cull half the entries when MAX_ENTRIES is reached. This argument
    should be an integer and defaults to 3.

    A value of 0 for CULL_FREQUENCY means that the
    entire cache will be dumped when MAX_ENTRIES is reached.
    On some backends (database in particular) this makes culling much
    faster at the expense of more cache misses.

  Memcached 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: A string that will be
  automatically included (prepended by default) to all cache keys
  used by the Django server.

  See the cache documentation for
  more information.

• VERSION: The default version number
  for cache keys generated by the Django server.

  See the cache documentation for more
  information.

• KEY_FUNCTION
  A string containing a dotted path to a function that defines how
  to compose a prefix, version and key into a final cache key.

  See the cache documentation
  for more information.

In this example, a filesystem backend is being configured with a timeout
of 60 seconds, and a maximum capacity of 1000 items:

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

Here’s an example configuration for a python-memcached based backend with
an object size limit of 2MB:

CACHES = {
    'default': {
        'BACKEND': 'django.core.cache.backends.memcached.MemcachedCache',
        'LOCATION': '127.0.0.1:11211',
        'OPTIONS': {
            'server_max_value_length': 1024 * 1024 * 2,
        }
    }
}

Here’s an example configuration for a pylibmc based backend that enables
the binary protocol, SASL authentication, and the ketama behavior mode:

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

Specifying per-view cache in the URLconf¶

The examples in the previous section have hard-coded the fact that the view is
cached, because cache_page alters the my_view function in place. This
approach couples your view to the cache system, which is not ideal for several
reasons. For instance, you might want to reuse the view functions on another,
cache-less site, or you might want to distribute the views to people who might
want to use them without being cached. The solution to these problems is to
specify the per-view cache in the URLconf rather than next to the view functions
themselves.

Doing so is easy: simply wrap the view function with cache_page when you
refer to it in the URLconf. Here’s the old URLconf from earlier:

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

Here’s the same thing, with my_view wrapped in cache_page:

from django.views.decorators.cache import cache_page

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

Accessing the cache¶

django.core.cache.caches¶

You can access the caches configured in the CACHES setting
through a dict-like object: django.core.cache.caches. Repeated
requests for the same alias in the same thread will return the same
object.

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

If the named key does not exist, InvalidCacheBackendError will be
raised.

To provide thread-safety, a different instance of the cache backend will
be returned for each thread.

django.core.cache.cache¶

As a shortcut, the default cache is available as
django.core.cache.cache:

>>> from django.core.cache import cache

This object is equivalent to caches['default'].

Basic usage¶

The basic interface is set(key, value, timeout) and get(key):

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

key should be a str, and value can be any picklable Python object.

The timeout argument is optional and defaults to the timeout argument
of the appropriate backend in the CACHES setting (explained above).
It’s the number of seconds the value should be stored in the cache. Passing in
None for timeout will cache the value forever. A timeout of 0
won’t cache the value.

If the object doesn’t exist in the cache, cache.get() returns None:

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

We advise against storing the literal value None in the cache, because you
won’t be able to distinguish between your stored None value and a cache
miss signified by a return value of None.

cache.get() can take a default argument. This specifies which value to
return if the object doesn’t exist in the cache:

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

To add a key only if it doesn’t already exist, use the add() method.
It takes the same parameters as set(), but it will not attempt to
update the cache if the key specified is already present:

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

If you need to know whether add() stored a value in the cache, you can
check the return value. It will return True if the value was stored,
False otherwise.

If you want to get a key’s value or set a value if the key isn’t in the cache,
there is the get_or_set() method. It takes the same parameters as get()
but the default is set as the new cache value for that key, rather than simply
returned:

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

You can also pass any callable as a default value:

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

There’s also a get_many() interface that only hits the cache once.
get_many() returns a dictionary with all the keys you asked for that
actually exist in the cache (and haven’t expired):

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

To set multiple values more efficiently, use set_many() to pass a dictionary
of key-value pairs:

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

Like cache.set(), set_many() takes an optional timeout parameter.

On supported backends (memcached), set_many() returns a list of keys that
failed to be inserted.

You can delete keys explicitly with delete(). This is an easy way of
clearing the cache for a particular object:

>>> cache.delete('a')

If you want to clear a bunch of keys at once, delete_many() can take a list
of keys to be cleared:

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

Finally, if you want to delete all the keys in the cache, use
cache.clear(). Be careful with this; clear() will remove everything
from the cache, not just the keys set by your application.

>>> cache.clear()

You can also increment or decrement a key that already exists using the
incr() or decr() methods, respectively. By default, the existing cache
value will be incremented or decremented by 1. Other increment/decrement values
can be specified by providing an argument to the increment/decrement call. A
ValueError will be raised if you attempt to increment or decrement a
nonexistent cache key.:

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

You can close the connection to your cache with close() if implemented by
the cache backend.

>>> cache.close()

Cache key prefixing¶

If you are sharing a cache instance between servers, or between your
production and development environments, it’s possible for data cached
by one server to be used by another server. If the format of cached
data is different between servers, this can lead to some very hard to
diagnose problems.

To prevent this, Django provides the ability to prefix all cache keys
used by a server. When a particular cache key is saved or retrieved,
Django will automatically prefix the cache key with the value of the
KEY_PREFIX cache setting.

By ensuring each Django instance has a different
KEY_PREFIX, you can ensure that there will be no
collisions in cache values.

Cache versioning¶

When you change running code that uses cached values, you may need to
purge any existing cached values. The easiest way to do this is to
flush the entire cache, but this can lead to the loss of cache values
that are still valid and useful.

Django provides a better way to target individual cache values.
Django’s cache framework has a system-wide version identifier,
specified using the VERSION cache setting.
The value of this setting is automatically combined with the cache
prefix and the user-provided cache key to obtain the final cache key.

By default, any key request will automatically include the site
default cache key version. However, the primitive cache functions all
include a version argument, so you can specify a particular cache
key version to set or get. For example:

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

The version of a specific key can be incremented and decremented using
the incr_version() and decr_version() methods. This
enables specific keys to be bumped to a new version, leaving other
keys unaffected. Continuing our previous example:

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

Cache key transformation¶

As described in the previous two sections, the cache key provided by a
user is not used verbatim — it is combined with the cache prefix and
key version to provide a final cache key. By default, the three parts
are joined using colons to produce a final string:

def make_key(key, key_prefix, version):
    return ':'.join([key_prefix, str(version), key])

If you want to combine the parts in different ways, or apply other
processing to the final key (e.g., taking a hash digest of the key
parts), you can provide a custom key function.

The KEY_FUNCTION cache setting
specifies a dotted-path to a function matching the prototype of
make_key() above. If provided, this custom key function will
be used instead of the default key combining function.

Cache key warnings¶

Memcached, the most commonly-used production cache backend, does not allow
cache keys longer than 250 characters or containing whitespace or control
characters, and using such keys will cause an exception. To encourage
cache-portable code and minimize unpleasant surprises, the other built-in cache
backends issue a warning (django.core.cache.backends.base.CacheKeyWarning)
if a key is used that would cause an error on memcached.

If you are using a production backend that can accept a wider range of keys (a
custom backend, or one of the non-memcached built-in backends), and want to use
this wider range without warnings, you can silence CacheKeyWarning with
this code in the management module of one of your
INSTALLED_APPS:

import warnings

from django.core.cache import CacheKeyWarning

warnings.simplefilter("ignore", CacheKeyWarning)

If you want to instead provide custom key validation logic for one of the
built-in backends, you can subclass it, override just the validate_key
method, and follow the instructions for using a custom cache backend. For
instance, to do this for the locmem backend, put this code in a module:

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

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

…and use the dotted Python path to this class in the
BACKEND portion of your CACHES setting.