Django-缓存

这篇讲什么

  • 缓存是把需要很多计算资源的结果存起来,下次请求不必再算一遍。
  • Django 自带一套可以按粒度选的缓存系统:整站(中间件)、单个视图(cache_page)、模板片段({% cache %})和最灵活的底层 API。这篇把这四层用法、CACHES 的配置项和各后端的实际差别都跑了一遍,基线 Django 5.2.19。

概述

  • 对中等流量的网站来说,尽量减少开销非常必要。缓存就是把需要很多计算资源的结果存起来,下次请求不必再算一遍。
  • Django 自带一套健壮的缓存系统,可以按四种粒度使用:整站(中间件)、单个视图(cache_page)、模板片段({% cache %})、以及最灵活的底层 API(cache.set/get)。

设置缓存

  • 通过 settings.py 里的 CACHES 决定数据存在哪里(内存、数据库、文件系统还是 Redis)。注意键名是 CACHES,老笔记写成 CACHE。

  • 完全不配 CACHES 时的默认值(实测):

    1
    {'default': {'BACKEND': 'django.core.cache.backends.locmem.LocMemCache'}}
    • 也就是说默认是进程内内存缓存:多进程部署(Gunicorn 开多个 worker)时每个进程各存各的,别指望它跨进程共享。
  • TIMEOUT 的三种取值(实测):

    1
    2
    3
    默认 TIMEOUT(不传 timeout): 300
    set(timeout=0) 后 get: None # 立即失效
    set(timeout=None) -> 存进 _expire_info['forever'] # 永不过期

五个后端逐个实测

  • 内存(开发够用)

    settings.py
    1
    2
    3
    4
    5
    6
    7
    CACHES = {
    "default": {
    "BACKEND": "django.core.cache.backends.locmem.LocMemCache",
    "LOCATION": "unique-snowflake", # 不同 LOCATION 才是不同实例
    "TIMEOUT": 60,
    }
    }
  • 数据库

    settings.py
    1
    2
    3
    4
    5
    6
    CACHES = {
    "default": {
    "BACKEND": "django.core.cache.backends.db.DatabaseCache",
    "LOCATION": "my_cache_table",
    }
    }
    • 必须先建表:

      1
      python manage.py createcachetable
    • 实测生成的表结构(SQLite):

      1
      cache_key varchar(255) PRIMARY KEY / value TEXT / expires datetime
    • 存进去的一行实测长这样(value 是 pickle 后的二进制):

      1
      (':1:dbk', 'gAWVBwAAAAAAAACMA2RidpQu', '2026-11-04 14:20:28')
  • 文件系统

    settings.py
    1
    2
    3
    4
    5
    6
    CACHES = {
    "default": {
    "BACKEND": "django.core.cache.backends.filebased.FileBasedCache",
    "LOCATION": r"E:\Desktop\Test\cache_files",
    }
    }
    • 实测落盘成一堆 .djcache 文件(如 9aa49c99….djcache)。
    • LOCATION 写成相对路径会吃警告(见下面的 caches.W003)。
  • 内置 Redis 缓存后端

    settings.py
    1
    2
    3
    4
    5
    6
    7
    8
    CACHES = {
    "default": {
    "BACKEND": "django.core.cache.backends.redis.RedisCache",
    "LOCATION": "redis://:password@127.0.0.1:6379/1",
    "KEY_PREFIX": "site",
    "VERSION": 1,
    }
    }
    • 老笔记这段是错的,两处都要改:

      1
      2
      3
      pip install django-redis-cache
      'BACKEND': 'redis_cache.cache.RedisCache'
      → InvalidCacheBackendError: Could not find backend 'redis_cache.cache.RedisCache': No module named 'redis_cache'
      • django-redis-cache / redis_cache 这套早就没人维护了。Django 4.0 起自带 django.core.cache.backends.redis.RedisCache,只要装了 redis 这个 Python 包就能用(本机 redis 8.1.0)。
    • 实测内置后端读写正常:set / get / touch 都通过,Redis 里的键名是 :1:probe_key 这种形式,TTL 能查到(实测 [30])。

    • 「默认使用 1 数据库」这句现在要说准:是 URL 末尾的 /1 决定用几号库,不是内置默认。不带 /1 就是 0 号库。

    • 如果非要用 django-redis(本机装了 7.0.0),密码必须写在 URL 里;老笔记那种 OPTIONS: {"PASSWORD": ...} 写法在 redis-py 8 这一代会失败:

      1
      AuthenticationError: HELLO must be called with the client already authenticated
  • 哑缓存(测试时关掉缓存)

    settings.py
    1
    CACHES = {"default": {"BACKEND": "django.core.cache.backends.dummy.DummyCache"}}
    • 实测:set 返回 None、get 返回 None、has_key 为 False,而 incr 直接 ValueError: Key 'x' not found。
  • 三个真实的 check 项(实测)

    1
    2
    3
    caches.E001  You must define a 'default' cache using the CACHES setting.
    caches.W003 ... LOCATION path is relative
    caches.W002 ... LOCATION 与 STATIC_ROOT 重叠
    • W002 提醒你别把缓存目录和静态目录设成同一个,collectstatic/clear 会互相踩。

底层缓存 API

  • 5.2 起 django.core.cache.backends.redis.RedisCache 是官方内置的,不用再装 django-redis-cache 那种第三方包。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
from django.core.cache import cache

cache.set("k", "v", 30) # None
cache.get("k") # 'v'
cache.add("k", "x") # False(键已存在时 add 不覆盖)
cache.incr("n") # 6
cache.decr("n") # 5
cache.touch("k", 30) # True
cache.get_or_set("k3", "created") # 'created'
cache.get_many(["k", "k2", "k3"]) # {'k': 'v', 'k2': 'x', 'k3': 'created'}
cache.delete("k") # True
cache.delete_many(["k2"]) # None
cache.has_key("k") # True
cache.clear() # None
  • 上面每一行的返回值都是实测的,几个容易看错的:

    • set / delete_many / clear 返回 None,不要写 if cache.delete(key): 来判断成功与否。
    • add 只在键不存在时才写,返回布尔;这是「只有我抢到才做后续动作」的轻量做法。
    • incr / decr 要求键已存在且值是整数,否则 ValueError;要「没有就初始化」用 get_or_set。
    • has_key 在 5.2 上仍然存在(实测 True,源码 django/core/cache/backends/base.py),网上说它已删除是错的。
  • 键名规则(实测):真正存进后端的是 前缀:版本:键名。

    1
    KEY_PREFIX = "PFX"、VERSION = 2 时 → 内部键 MY::PFX:2:hello
    • 自定义 KEY_FUNCTION 可以改这个拼装方式。注意 cache_key 不是配置项(实测不存在),别照某些教程写。

缓存的四个使用层级

  • 1)整站缓存(两个中间件)

    settings.py
    1
    2
    3
    4
    5
    6
    7
    8
    MIDDLEWARE = [
    "django.middleware.cache.UpdateCacheMiddleware", # 必须放最前
    "django.middleware.common.CommonMiddleware",
    "django.middleware.cache.FetchFromCacheMiddleware", # 必须放最后
    ]

    CACHE_MIDDLEWARE_SECONDS = 60
    CACHE_MIDDLEWARE_KEY_PREFIX = "site"
    • 顺序是文档要求,但5.2 并不会帮你检查:实测故意把两条放错位置,manage.py check 依然 System check identified no issues (0 silenced).,简单请求也照样命中缓存。所以顺序只能自己保证 —— 这是典型的「错了也不一定立刻发现」。
  • 2)单个视图

    views.py
    1
    2
    3
    4
    5
    6
    7
    8
    from django.views.decorators.cache import cache_page
    from django.views.decorators.http import require_GET


    @require_GET
    @cache_page(60 * 15)
    def index(request):
    return HttpResponse(str(random.random()))
    • 实测连续两次请求:响应头 Cache-Control: max-age=900,两次的 body 完全相同(0.28277575163740776),说明第二次是命中缓存而不是重新执行视图。
  • 3)只控制浏览器/CDN 的缓存头

    views.py
    1
    2
    3
    4
    5
    6
    7
    from django.views.decorators.cache import cache_control, never_cache

    @cache_control(max_age=33)
    def partial(request): ...

    @never_cache
    def private_page(request): ...
    • 实测响应头:

      1
      2
      @cache_control(max_age=33) -> Cache-Control: max-age=33
      @never_cache -> Cache-Control: max-age=0, no-cache, no-store, must-revalidate, private
    • 登录页、含个人信息的页面用 never_cache,否则会和整站缓存/CDN 配合出问题(A 用户看到 B 用户的页面)。

  • 4)模板片段

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    {% load cache %}
    <!DOCTYPE html>
    <html lang="zh">
    <head><meta charset="UTF-8"><title>缓存</title></head>
    <body>
    <h1>Redis cache!</h1>
    {% cache 120 cache_name %}
    <p>这段被冻住 120 秒:计数 {{ counter }}</p>
    {% endcache %}
    </body>
    </html>
    • 实测:第一次渲染出 计数 1,第二次(视图里计数器已经加到 2)仍然输出 计数 1,说明片段确实被缓存住了。

    • 两个参数就够:{% cache 缓存秒数 缓存名 %}。老笔记里那句「参数 1 时间、参数 2 名字」是对的。

    • 想让不同用户/不同参数得到不同结果,把变化项写进名字或 variation:

      1
      2
      {% cache 120 sidebar user.username %}
      {% cache 600 header request.user variation:request.user %}
      • 实测按 user 隔离是生效的(不同 user 各存各的)。
    • 别把 cache_key_prefix='p' 当标签参数写,那是内部函数 make_template_fragment_key 的参数,写在模板里会:

      1
      TemplateSyntaxError: Could not parse the remainder: '='p''

新手卡点清单

  • 都是实测过的:

    卡点 症状 正确做法
    照抄 redis_cache.cache.RedisCache InvalidCacheBackendError ... No module named 'redis_cache' 用内置 django.core.cache.backends.redis.RedisCache
    用 OPTIONS: {"PASSWORD": ...} 传 Redis 密码 AuthenticationError: HELLO must be called with the client already authenticated 密码写进 URL:redis://:password@host:6379/1
    settings 里写 CACHE 配置根本不生效 键名是 CACHES
    用 db 后端但没建表 读写报表不存在 python manage.py createcachetable
    以为 cache.delete() 返回布尔 判断永远走 else 它返回 None;要确认就再 get 一次
    多 worker 部署用 locmem 命中率忽高忽低 换 Redis / 数据库 / 文件后端
    整站缓存 + 登录页不加 never_cache 用户看到别人的页面 个人化视图加 never_cache 或带 variation
    中间件顺序放错 5.2 不报错,问题延后暴露 自己保证首/尾顺序

参考

本文结束 感谢您的阅读
正在加载今日诗词....