django-redis 中文文檔

阿新 • • 發佈：2019-02-25

swe vat psu shortcut tle mar 之前 exc 內容

Andrey Antukh, [email protected] 4.7.0

翻譯: RaPoSpectre

1. 介紹

django-redis 基於 BSD 許可, 是一個使 Django 支持 Redis cache/session 後端的全功能組件.

1.1 為何要用 django-redis ?

因為:

持續更新
本地化的 redis-py URL 符號連接字符串
可擴展客戶端
可擴展解析器
可擴展序列器
默認客戶端主/從支持
完善的測試
已在一些項目的生產環境中作為 cache 和 session 使用
支持永不超時設置
原生進入 redis 客戶端/連接池支持

高可配置 ( 例如仿真緩存的異常行為 )
默認支持 unix 套接字
支持 Python 2.7, 3.4, 3.5 以及 3.6

1.2 可用的 django-redis 版本

穩定版本: 4.7.0
穩定版本: 3.8.4

1.3 我該使用哪個版本

版本號像 3.6, 3.7 … 等的是主要發行版本, 會包含向後不兼容的內容. 跟多信息請在升級前閱讀升級日誌.

版本號像 3.7.0, 3.7.1… 等的是小更新或者 bug 修復版本, 一般只會包含 bug 修復, 沒有功能更新.

1.4 依賴

1.4.1 Django 版本支持

django-redis 3.8.x 支持 django 1.4, 1.5, 1.6, 1.7 (或許會有 1.8)
django-redis 4.4.x 支持 django 1.6, 1.7, 1.8, 1.9 和 1.10

1.4.2 Redis Server 支持

django-redis 3.x.y 支持 redis-server 2.6.x 或更高
django-redis 4.x.y 支持 redis-server 2.8.x 或更高

1.4.3 其他依賴

所有版本的 django-redis 基於 redis-py >= 2.10.0.

2. 用戶指南

2.1 安裝

安裝 django-redis 最簡單的方法就是用 pip :

pip install django-redis

2.2 作為 cache backend 使用配置

為了使用 django-redis , 你應該將你的 django cache setting 改成這樣:

CACHES = {
    "default": {
        "BACKEND": "django_redis.cache.RedisCache",
        "LOCATION": "redis://127.0.0.1:6379/1",
        "OPTIONS": {
            "CLIENT_CLASS": "django_redis.client.DefaultClient",
        }
    }
}

為了更好的互操作性並使連接字符串更加 “標準”, 從 3.8.0 開始 django-redis 使用 redis-py native url notation 作為連接字符串.

URL 格式舉例

redis://[:password]@localhost:6379/0
rediss://[:password]@localhost:6379/0
unix://[:password]@/path/to/socket.sock?db=0

支持三種 URL scheme :

redis://: 普通的 TCP 套接字連接
rediss://: SSL 包裹的 TCP 套接字連接
unix://: Unix 域套接字連接

指定數據庫數字的方法:

db 查詢參數, 例如: redis://localhost?db=0
如果使用 redis:// scheme, 可以直接將數字寫在路徑中, 例如: redis://localhost/0

在某些環境下連接密碼放在 url 是不安全的, 這時你可以忽略密碼或者使用方便的 OPTIONS 設置:

CACHES = {
    "default": {
        "BACKEND": "django_redis.cache.RedisCache",
        "LOCATION": "redis://127.0.0.1:6379/1",
        "OPTIONS": {
            "CLIENT_CLASS": "django_redis.client.DefaultClient",
            "PASSWORD": "mysecret"
        }
    }
}

註意, 這樣配置不會覆蓋 uri 中的密碼, 所以如果你已經在 uri 中設置了密碼, 此設置將被忽略.

2.3 作為 session backend 使用配置

Django 默認可以使用任何 cache backend 作為 session backend, 將 django-redis 作為 session 儲存後端不用安裝任何額外的 backend

SESSION_ENGINE = "django.contrib.sessions.backends.cache"
SESSION_CACHE_ALIAS = "default"

2.4 使用 django-redis 進行測試

django-redis 支持定制基於 Redis 的客戶端 ( 參考[可擴展 redis 客戶端][] ) 可以用來測試, 例如: 替換默認的客戶端為 fakerdis (https://github.com/jamesls/fakeredis) 或者 mockredis (https://github.com/locationlabs/mockredis). 這樣做可以不用依賴真的 redis server 做集成測試.

使用 fakeredis 舉例:

import fakeredis
CACHES = {
    "default": {
        "OPTIONS": {
            "REDIS_CLIENT_CLASS": "fakeredis.FakeStrictRedis",
        }
    }
}

如果在測試完畢後想清理所有數據, 在你的 TestCase 中加入如下代碼:

def tearDown(self):
    from django_redis import get_redis_connection
    get_redis_connection("default").flushall()

3. 進階使用

3.1 Pickle 版本

django-redis 使用 pickle 序列化幾乎所有數據.

默認使用最新的 pickle. 如果你想設置其他版本, 使用 PICKLE_VERSION 參數:

CACHES = {
    "default": {
        # ...
        "OPTIONS": {
            "PICKLE_VERSION": -1  # Use the latest protocol version
        }
    }
}

3.2 套接字超時

套接字超時設置使用 SOCKET_TIMEOUT 和 SOCKET_CONNECT_TIMEOUT 參數:

CACHES = {
    "default": {
        # ...
        "OPTIONS": {
            "SOCKET_CONNECT_TIMEOUT": 5,  # in seconds
            "SOCKET_TIMEOUT": 5,  # in seconds
        }
    }
}

SOCKET_CONNECT_TIMEOUT : socket 建立連接超時設置

SOCKET_TIMEOUT : 連接建立後的讀寫操作超時設置

3.3 壓縮支持

django-redis 支持壓縮, 但默認是關閉的. 你可以激活它:

CACHES = {
    "default": {
        # ...
        "OPTIONS": {
            "COMPRESSOR": "django_redis.compressors.zlib.ZlibCompressor",
        }
    }
}

使用 lzma 壓縮的例子:

import lzma

CACHES = {
    "default": {
        # ...
        "OPTIONS": {
            "COMPRESSOR": "django_redis.compressors.lzma.LzmaCompressor",
        }
    }
}

3.4 memcached 異常行為

在某些情況下, redis 只作為緩存使用, 當它關閉時如果你不希望觸發異常. 這是 memcached backend 的默認行為, 你可以使用 django-redis 模擬這種情況.

為了設置這種類似memcached 的行為 ( 忽略連接異常 ), 使用 IGNORE_EXCEPTIONS 參數:

CACHES = {
    "default": {
        # ...
        "OPTIONS": {
            "IGNORE_EXCEPTIONS": True,
        }
    }
}

Also, you can apply the same settings to all configured caches, you can set the global flag in your settings:

當然,你也可以給所有緩存配置相同的忽略行為:

DJANGO_REDIS_IGNORE_EXCEPTIONS = True

3.5 日誌忽略異常

當使用 IGNORE_EXCEPTIONS 或者 DJANGO_REDIS_IGNORE_EXCEPTIONS 參數忽略異常時, 你也許會用到 DJANGO_REDIS_LOG_IGNORED_EXCEPTIONS 參數來配置日誌異常:

DJANGO_REDIS_LOG_IGNORED_EXCEPTIONS = True

如果你想設置指定的 logger 輸出異常, 只需要設置全局變量 DJANGO_REDIS_LOGGER 為 logger 的名稱或其路徑即可. 如果沒有 logger 被設置並且 DJANGO_REDIS_LOG_IGNORED_EXCEPTIONS=True 時此參數將取 name :

DJANGO_REDIS_LOGGER = ‘some.specified.logger‘

3.6 永不超時設置

django-redis comes with infinite timeouts support out of the box. And it behaves in same way as django backend contract specifies:

django-redis 支持永不超時設置. 其表現和 django backend 指定的相同:

timeout=0 立即過期
timeout=None 永不超時

cache.set("key", "value", timeout=None)

3.7 通過值 (value) 獲取 ttl (time to live)

With redis, you can access to ttl of any stored key, for it, django-redis exposes ttl function.

It returns:

在 redis 中, 你可以獲取任何 key 的 ttl, django-redis 也支持獲取 ttl 的函數:

它返回:

0 key 不存在 (或已過期).
None key 存在但沒有設置過期.
ttl 任何有超時設置的 key 的超時值.

以 keys 搜索過期:

>>> from django.core.cache import cache
>>> cache.set("foo", "value", timeout=25)
>>> cache.ttl("foo")
25
>>> cache.ttl("not-existent")
0

3.8 expire & persist

除了簡單的 ttl 查詢, 你可以使用 persist 或者 expire 方法讓一個值永久存在或者指定一個新的過期時間:

使用 persist 的例子:

>>> cache.set("foo", "bar", timeout=22)
>>> cache.ttl("foo")
22
>>> cache.persist("foo")
>>> cache.ttl("foo")
None

使用 expire 的例子:

>>> cache.set("foo", "bar", timeout=22)
>>> cache.expire("foo", timeout=5)
>>> cache.ttl("foo")
5

3.9 locks

django-redis 支持 redis 分布式鎖. 鎖的線程接口是相同的, 因此你可以使用它作為替代.

使用 python 上下文管理器分配鎖的例子:

with cache.lock("somekey"):
    do_some_thing()

3.10 掃描 & 刪除鍵 (keys)

django-redis 支持使用全局通配符的方式來檢索或者刪除鍵.

使用通配符搜索的例子

>>> from django.core.cache import cache
>>> cache.keys("foo_*")
["foo_1", "foo_2"]

這個簡單的寫法將返回所有匹配的值, 但在擁有很大數據量的數據庫中這樣做並不合適. 在 redis 的 server side cursors 2.8 版及以上, 你可以使用 iter_keys 取代 keys 方法, iter_keys 將返回匹配值的叠代器, 你可以使用叠代器高效的進行遍歷.

使用 server side cursors 搜索

>>> from django.core.cache import cache
>>> cache.iter_keys("foo_*")
<generator object algo at 0x7ffa9c2713a8>
>>> next(cache.iter_keys("foo_*"))
"foo_1"

如果要刪除鍵, 使用 delete_pattern 方法, 它和 keys 方法一樣也支持全局通配符, 此函數將會返回刪掉的鍵的數量

使用 delete_pattern 的例子

>>> from django.core.cache import cache
>>> cache.delete_pattern("foo_*")

3.11 Redis 本地命令

django-redis 有限制的支持一些 Redis 原子操作, 例如 SETNX 和 INCR 命令.

你可以在 set() 方法中加上 nx 參數使用來使用 SETNX 命令

例子:

>>> from django.core.cache import cache
>>> cache.set("key", "value1", nx=True)
True
>>> cache.set("key", "value2", nx=True)
False
>>> cache.get("key")
"value1"

當值 (value) 有合適的鍵 (key) 時, incr 和 decr 也可以使用 Redis 原子操作

3.12 原生客戶端使用

在某些情況下你的應用需要進入原生 Redis 客戶端使用一些 django cache 接口沒有暴露出來的進階特性. 為了避免儲存新的原生連接所產生的另一份設置, django-redis 提供了方法 get_redis_connection(alias) 使你獲得可重用的連接字符串.

>>> from django_redis import get_redis_connection
>>> con = get_redis_connection("default")
>>> con
<redis.client.StrictRedis object at 0x2dc4510>

警告不是所有的擴展客戶端都支持這個特性.

3.13 連接池

django-redis 使用 redis-py 的連接池接口, 並提供了簡單的配置方式. 除此之外, 你可以為 backend 定制化連接池的產生.

redis-py 默認不會關閉連接, 盡可能重用連接

3.13.1 配置默認連接池

配置默認連接池很簡單, 你只需要在 CACHES 中使用 CONNECTION_POOL_KWARGS 設置連接池的最大連接數量即可:

CACHES = {
    "default": {
        "BACKEND": "django_redis.cache.RedisCache",
        ...
        "OPTIONS": {
            "CONNECTION_POOL_KWARGS": {"max_connections": 100}
        }
    }
}

你可以得知連接池已經打開多少連接:

from django.core.cache import get_cache
from django_redis import get_redis_connection

r = get_redis_connection("default")  # Use the name you have defined for Redis in settings.CACHES
connection_pool = r.connection_pool
print("Created connections so far: %d" % connection_pool._created_connections)

3.13.2 使用你自己的連接池子類

有時你想使用自己的連接池子類. django-redis 提供了 CONNECTION_POOL_CLASS 來配置連接池子類

myproj/mypool.py

from redis.connection import ConnectionPool

class MyOwnPool(ConnectionPool):
    # Just doing nothing, only for example purpose
    pass

setting.py

# Omitting all backend declaration boilerplate code.

"OPTIONS": {
    "CONNECTION_POOL_CLASS": "myproj.mypool.MyOwnPool",
}

3.13.3 定制化的 connection factory

如果之前的方法都不合適, 你可以定制 django-redis 的 connection factory 過程甚至完全重寫.

django-redis 默認使用Django setting 中 DJANGO_REDIS_CONNECTION_FACTORY 參數指定的django_redis.pool.ConnectionFactory 類產生連接.

ConnectionFactory 類的部分接口

# Note: Using Python 3 notation for code documentation ;)

class ConnectionFactory(object):
    def get_connection_pool(self, params:dict):
        # Given connection parameters in the `params` argument,
        # return new connection pool.
        # It should be overwritten if you want do something
        # before/after creating the connection pool, or return your
        # own connection pool.
        pass

    def get_connection(self, params:dict):
        # Given connection parameters in the `params` argument,
        # return a new connection.
        # It should be overwritten if you want to do something
        # before/after creating a new connection.
        # The default implementation uses `get_connection_pool`
        # to obtain a pool and create a new connection in the
        # newly obtained pool.
        pass

    def get_or_create_connection_pool(self, params:dict):
        # This is a high layer on top of `get_connection_pool` for
        # implementing a cache of created connection pools.
        # It should be overwritten if you want change the default
        # behavior.
        pass

    def make_connection_params(self, url:str) -> dict:
        # The responsibility of this method is to convert basic connection
        # parameters and other settings to fully connection pool ready
        # connection parameters.
        pass

    def connect(self, url:str):
        # This is really a public API and entry point for this
        # factory class. This encapsulates the main logic of creating
        # the previously mentioned `params` using `make_connection_params`
        # and creating a new connection using the `get_connection` method.
        pass

3.14 可擴展解析器

redis-py (django-redis 使用的 Redis 客戶端) 支持的純凈 Python Redis 解析器可以滿足大部分普通任務, 但如果你想要性能更好, 可以使用 hiredis

hiredis 是一個用 C 寫的 Redis 客戶端, 並且他的解析器可以用在 django-redis 中:

"OPTIONS": {
    "PARSER_CLASS": "redis.connection.HiredisParser",
}

3.15 可擴展客戶端

django_redis 設計的非常靈活和可配置。它提供了可擴展的後端，擁有易擴展的特性.

3.15.1 默認客戶端

我們已經說明了默認客戶端幾乎所有的特點, 但有一個例外: 默認客戶端支持主從配置.

如果需要主從設置, 你需要更改 LOCATION 參數:

"LOCATION": [
    "redis://127.0.0.1:6379/1",
    "redis://127.0.0.1:6378/1",
]

第一個字段代表 master 服務器, 第二個字段代表 slave 服務器.

警告主從設置沒有在生產環境中經過大量測試

3.15.2 分片客戶端

此可擴展客戶端實現了客戶端分片, 它幾乎繼承了默認客戶端的全部功能. 如果需要使用, 請將配置改成這樣

CACHES = {
    "default": {
        "BACKEND": "django_redis.cache.RedisCache",
        "LOCATION": [
            "redis://127.0.0.1:6379/1",
            "redis://127.0.0.1:6379/2",
        ],
        "OPTIONS": {
            "CLIENT_CLASS": "django_redis.client.ShardClient",
        }
    }
}

警告分片客戶端仍處於試驗階段, 請在生產環境中謹慎使用

3.15.3 集群客戶端

我們同時也在嘗試解決驚群問題, 更多信息請閱讀Wikipedia

和上文講的一樣, 客戶端基本繼承了默認客戶端所有功能, 增加額外的方法以獲取/設置鍵 (keys)

設置舉例

CACHES = {
    "default": {
        "BACKEND": "django_redis.cache.RedisCache",
        "LOCATION": "redis://127.0.0.1:6379/1",
        "OPTIONS": {
            "CLIENT_CLASS": "django_redis.client.HerdClient",
        }
    }
}

一些其他的設置:

CACHE_HERD_TIMEOUT: 設置集群超時 (默認值為: 60s)

3.16 可擴展序列器

客戶端在將數據發給服務器之前先會序列化數據. django-redis 默認使用 Python pickle 序列化數據.

如果需要使用 json 序列化數據, 使用 JSONSerializer

設置舉例

CACHES = {
    "default": {
        "BACKEND": "django_redis.cache.RedisCache",
        "LOCATION": "redis://127.0.0.1:6379/1",
        "OPTIONS": {
            "CLIENT_CLASS": "django_redis.client.DefaultClient",
            "SERIALIZER": "django_redis.serializers.json.JSONSerializer",
        }
    }
}

使用 MsgPack http://msgpack.org/ 進行序列化 (需要 msgpack-python 庫支持)

設置舉例

CACHES = {
    "default": {
        "BACKEND": "django_redis.cache.RedisCache",
        "LOCATION": "redis://127.0.0.1:6379/1",
        "OPTIONS": {
            "CLIENT_CLASS": "django_redis.client.DefaultClient",
            "SERIALIZER": "django_redis.serializers.msgpack.MSGPackSerializer",
        }
    }
}

3.17 可擴展 Redis 客戶端

django-redis 默認使用 redis.client.StrictClient 作為 Redis 客戶端, 你可以使用其他客戶端替代, 比如之前在講測試時我們用 fakeredis 代替真實客戶端.

使用 REDIS_CLIENT_CLASS in the CACHES 來配置你的客戶端, 使用 REDIS_CLIENT_KWARGS 提供配置客戶端的參數 (可選).

設置舉例

CACHES = {
    "default": {
        "OPTIONS": {
            "REDIS_CLIENT_CLASS": "my.module.ClientClass",
            "REDIS_CLIENT_KWARGS": {"some_setting": True},
        }
    }
}

4. 許可

Copyright (c) 2011-2015 Andrey Antukh <[email protected]>
Copyright (c) 2011 Sean Bleier

All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
   notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
   notice, this list of conditions and the following disclaimer in the
   documentation and/or other materials provided with the distribution.
3. The name of the author may not be used to endorse or promote products
   derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS‘‘ AND ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

In Django, how can I find out the request.session sessionid and use it as a variable?

Ask Question 78

I‘m aware that you can get session variables using request.session[‘variable_name‘], but there doesn‘t seem to be a way to grab the sessionid as a variable in a similar way. Is this documented anywhere? I can‘t find it. Thanks for your help!

django shareimprove this question asked Feb 8 ‘09 at 18:31

rmh 2,04162631 add a comment

8 Answers

activeoldestvotes 123

Much simpler:

request.session.session_key

Note the key will only exist if there is a session, no key, no session. You can use this to test if a session exists. If you want to create a session, call create.

django-redis 中文文檔

swe vat psu shortcut tle mar 之前 exc 內容 Andrey Antukh, [email protected] 4.7.0 翻譯: RaPoSpectre 1. 介紹 django-redis 基於 BSD 許可, 是一個使 Django 支

django-redis 中文文檔

1. 介紹

1.1 為何要用 django-redis ?

1.2 可用的 django-redis 版本

1.3 我該使用哪個版本

1.4 依賴

1.4.1 Django 版本支持

1.4.2 Redis Server 支持

1.4.3 其他依賴

2. 用戶指南

2.1 安裝

2.2 作為 cache backend 使用配置

2.3 作為 session backend 使用配置

2.4 使用 django-redis 進行測試

3. 進階使用

3.1 Pickle 版本

3.2 套接字超時

3.3 壓縮支持

3.4 memcached 異常行為

3.5 日誌忽略異常

3.6 永不超時設置

3.7 通過值 (value) 獲取 ttl (time to live)

3.8 expire & persist

3.9 locks

3.10 掃描 & 刪除鍵 (keys)

3.11 Redis 本地命令

3.12 原生客戶端使用

3.13 連接池

3.13.1 配置默認連接池

3.13.2 使用你自己的連接池子類

3.13.3 定制化的 connection factory

3.14 可擴展解析器

3.15 可擴展客戶端

3.15.1 默認客戶端

3.15.2 分片客戶端

3.15.3 集群客戶端

3.16 可擴展序列器

3.17 可擴展 Redis 客戶端

4. 許可

In Django, how can I find out the request.session sessionid and use it as a variable?

8 Answers

相關推薦