请求和响应对象

应用程序代码设置的属性

Django 不会自己设置这些属性，但如果你的应用程序设置了这些属性，就会使用它们。

HttpRequest.current_app

url 模板标签将使用它的值作为 reverse() 的 current_app 参数。

HttpRequest.urlconf

这将作为当前请求的根 URLconf，覆盖 ROOT_URLCONF 设置。详情请参见 Django 如何处理一个请求。

urlconf 可以设置为 None，以恢复之前中间件所做的任何更改，并返回到使用 ROOT_URLCONF。

HttpRequest.exception_reporter_filter

这将代替当前请求的 DEFAULT_EXCEPTION_REPORTER_FILTER 使用。详情请参见 自定义错误报告。

HttpRequest.exception_reporter_class

这将代替 DEFAULT_EXCEPTION_REPORTER 用于当前请求。详情请参见 自定义错误报告。

中间件设置的属性

Django 的 contrib 应用中包含的一些中间件会在请求中设置属性。如果你没有在请求中看到属性，请确认在 MIDDLEWARE 中列出了相应的中间件类。

HttpRequest.session

来自 SessionMiddleware。一个可读可写的，类似字典的对象，代表当前会话。

HttpRequest.site

来自 CurrentSiteMiddleware。由 Site() 或 RequestSite 返回的 get_current_site() 的实例，代表当前站点。

HttpRequest.user

从 AuthenticationMiddleware。AUTH_USER_MODEL 的一个实例，代表当前登录的用户。如果用户当前没有登录，user 将被设置为一个 AnonymousUser 的实例。你可以用 is_authenticated 来区分它们，比如：

if request.user.is_authenticated:
    ... # Do something for logged-in users.
else:
    ... # Do something for anonymous users.

方法

HttpRequest.get_host()

使用 HTTP_X_FORWARDED_HOST （如果 USE_X_FORWARDED_HOST 已启用）和 HTTP_HOST 头信息，按顺序返回请求的发起主机。如果它们没有提供一个值，则该方法使用 SERVER_NAME 和 SERVER_PORT 的组合，详见 PEP 3333。

例如："127.0.0.1:8000"

Raises django.core.exceptions.DisallowedHost if the host is not in ALLOWED_HOSTS or the domain name is invalid according to RFC 1034/1035.

备注

get_host() 方法在主机处于多个代理后面时失效。一个解决方案是使用中间件重写代理头，如下面的例子：

class MultipleProxyMiddleware:
    FORWARDED_FOR_FIELDS = [
        'HTTP_X_FORWARDED_FOR',
        'HTTP_X_FORWARDED_HOST',
        'HTTP_X_FORWARDED_SERVER',
    ]

    def __init__(self, get_response):
        self.get_response = get_response

    def __call__(self, request):
        """
        Rewrites the proxy headers so that only the most
        recent proxy is used.
        """
        for field in self.FORWARDED_FOR_FIELDS:
            if field in request.META:
                if ',' in request.META[field]:
                    parts = request.META[field].split(',')
                    request.META[field] = parts[-1].strip()
        return self.get_response(request)

这个中间件应该定位在任何其他依赖于:meth:~HttpRequest.get_host() 值的中间件之前——例如 CommonMiddleware 或 CsrfViewMiddleware。

HttpRequest.get_port()

使用 HTTP_X_FORWARDED_PORT （如果 :set:`USE_X_FORWARDED_PORT` 已启用）和 SERVER_PORT META 变量中的信息，按顺序返回请求的起始端口。

HttpRequest.get_full_path()

返回 path，加上附加的查询字符串（如果适用）。

例如："/music/bands/the_beatles/?print=true"

HttpRequest.get_full_path_info()

像 get_full_path() 一样，但使用 path_info 代替 path。

例如："/minfo/music/bands/the_beatles/?print=true"

HttpRequest.build_absolute_uri(location=None)

返回 location 的绝对 URI 形式。如果没有提供 location，location 将被设置为 request.get_full_path()。

如果 location 已经是一个绝对 URI，它将不会被改变。否则，绝对 URI 将使用这个请求中可用的服务器变量建立。例如：

>>> request.build_absolute_uri()
'https://example.com/music/bands/the_beatles/?print=true'
>>> request.build_absolute_uri('/bands/')
'https://example.com/bands/'
>>> request.build_absolute_uri('https://example2.com/bands/')
'https://example2.com/bands/'

备注

Mixing HTTP and HTTPS on the same site is discouraged, therefore build_absolute_uri() will always generate an absolute URI with the same scheme the current request has. If you need to redirect users to HTTPS, it's best to let your web server redirect all HTTP traffic to HTTPS.

HttpRequest.get_signed_cookie(key, default=RAISE_ERROR, salt='', max_age=None)

返回已签名 cookie 的 cookie 值，如果签名不再有效，则会引发 django.core.signing.BadSignature 异常。如果你提供了 default 参数，异常将被抑制，并返回默认值。

可选的 salt 参数可以用来提供额外的保护，以防止对你秘钥的暴力攻击。如果提供了这个参数，max_age 参数将根据附加在 cookie 值上的签名时间戳进行检查，以确保 cookie 不超过 max_age 秒。

例子：

>>> request.get_signed_cookie('name')
'Tony'
>>> request.get_signed_cookie('name', salt='name-salt')
'Tony' # assuming cookie was set using the same salt
>>> request.get_signed_cookie('nonexistent-cookie')
...
KeyError: 'nonexistent-cookie'
>>> request.get_signed_cookie('nonexistent-cookie', False)
False
>>> request.get_signed_cookie('cookie-that-was-tampered-with')
...
BadSignature: ...
>>> request.get_signed_cookie('name', max_age=60)
...
SignatureExpired: Signature age 1677.3839159 > 60 seconds
>>> request.get_signed_cookie('name', False, max_age=60)
False

更多信息请参见 加密签名。

HttpRequest.is_secure()

如果请求是安全的，返回 True；如果请求是通过 HTTPS 发出的，返回 True。

HttpRequest.accepts(mime_type)

如果请求的 Accept 头符合 mime_type 参数，则返回 True。

>>> request.accepts('text/html')
True

大多数浏览器默认发送 Accept: */*，默认情况下，这将为所有内容类型返回 True。在 API 请求中设置一个显式的 Accept 头，对于只为那些消费者返回不同的内容类型是很有用的。参见 内容协商示例 使用 accepts() 向 API 消费者返回不同的内容。

如果一个响应根据 Accept 头的内容而变化，并且你使用了某种形式的缓存，比如 Django 的 cache middleware，你应该用 vary_on_headers('Accept') 来装饰视图，这样响应就会被正确地缓存。

HttpRequest.read(size=None)

HttpRequest.readline()

HttpRequest.readlines()

HttpRequest.__iter__()

实现从 HttpRequest 实例中读取文件的类似接口的方法。这使得它可以以流式方式处理一个传入的请求。一个常见的用例是用迭代解析器处理一个大的 XML 有效载荷，而无需在内存中构建一个完整的 XML 树。

给定这个标准接口，一个 HttpRequest 实例可以直接传递给 XML 解析器，如 ElementTree：

import xml.etree.ElementTree as ET
for element in ET.iterparse(request):
    process(element)

方法

QueryDict 实现了所有标准的字典方法，因为它是字典的一个子类。这里概述了例外情况：

QueryDict.__init__(query_string=None, mutable=False, encoding=None)

基于 query_string 实例化一个 QueryDict 对象。

>>> QueryDict('a=1&a=2&c=3')
<QueryDict: {'a': ['1', '2'], 'c': ['3']}>

如果没有传入 query_string，产生的 QueryDict 将是空的（它将没有键或值）。

你遇到的大多数 QueryDicts，特别是那些在 request.POST 和 request.GET 的，将是不可变的。如果你自己实例化一个，你可以通过传递 mutable=True 到它的 __init__() 来使它可变。

设置键和值的字符串将从 encoding 转换为 str。如果没有设置 encoding，则默认为 DEFAULT_CHARSET。

classmethod QueryDict.fromkeys(iterable, value='', mutable=False, encoding=None)

创建一个新的 QueryDict，键来自 iterable，每个值等于 value。例如：

>>> QueryDict.fromkeys(['a', 'a', 'b'], value='val')
<QueryDict: {'a': ['val', 'val'], 'b': ['val']}>

QueryDict.__getitem__(key)

返回给定键的值。如果键有多个值，则返回最后一个值。如果键不存在，会引发 django.utils.datastructures.MultiValueDictKeyError。（这是 Python 标准的 KeyError 的一个子类，所以你可以坚持捕捉 KeyError。)

QueryDict.__setitem__(key, value)

将给定的键设置为 [value] （一个单一元素为 value 的列表）。请注意，这个函数和其他有副作用的字典函数一样，只能在一个可变的 QueryDict 上调用（比如通过 QueryDict.copy() 创建的）。

QueryDict.__contains__(key)

如果给定的键被设置，返回 True。这让你可以执行，例如，if "foo" in request.GET。

QueryDict.get(key, default=None)

使用与 __getitem__() 相同的逻辑，如果键不存在，则用钩子返回一个默认值。

QueryDict.setdefault(key, default=None)

与 dict.setdefault() 一样，只是它在内部使用 __setitem__()。

QueryDict.update(other_dict)

取一个 QueryDict 或一个字典。就像 dict.update() 一样，除了它 附加 到当前的字典项，而不是替换它们。例如：

>>> q = QueryDict('a=1', mutable=True)
>>> q.update({'a': '2'})
>>> q.getlist('a')
['1', '2']
>>> q['a'] # returns the last
'2'

QueryDict.items()

与 dict.items() 一样，除了使用与 __getitem__() 相同的最后值逻辑，并返回一个迭代器对象而不是视图对象。例如：

>>> q = QueryDict('a=1&a=2&a=3')
>>> list(q.items())
[('a', '3')]

QueryDict.values()

与 dict.values() 一样，除了使用与 __getitem__() 相同的最后值逻辑，并返回一个迭代器而不是视图对象。例如：

>>> q = QueryDict('a=1&a=2&a=3')
>>> list(q.values())
['3']

此外，QueryDict 有以下方法：

QueryDict.copy()

使用 copy.deepcopy() 返回对象的副本。这个副本将是可变的，即使原始副本不是。

QueryDict.getlist(key, default=None)

返回带有请求键的数据列表。如果键不存在且 default 是 None，则返回一个空列表。除非提供的默认值不是一个列表，否则保证返回一个列表。

QueryDict.setlist(key, list_)

将给定的键设置为 list_ （与 __setitem__() 不同）。

QueryDict.appendlist(key, item)

将一个项目添加到与键相关联的内部列表中。

QueryDict.setlistdefault(key, default_list=None)

和 setdefault() 一样，只不过它取的是一个值的列表，而不是单个值。

QueryDict.lists()

像 items() 一样，除了它包含了所有的值，作为一个列表，为字典的每个成员。例如：

>>> q = QueryDict('a=1&a=2&a=3')
>>> q.lists()
[('a', ['1', '2', '3'])]

QueryDict.pop(key)

返回给定键的值列表，并从字典中删除它们。如果键不存在，则引发 KeyError。例如：

>>> q = QueryDict('a=1&a=2&a=3', mutable=True)
>>> q.pop('a')
['1', '2', '3']

QueryDict.popitem()

删除字典中的任意成员（因为没有排序的概念），并返回一个包含键和键的所有值的二元元组。当调用空字典时，会引发 KeyError。例如：

>>> q = QueryDict('a=1&a=2&a=3', mutable=True)
>>> q.popitem()
('a', ['1', '2', '3'])

QueryDict.dict()

返回 QueryDict 的 dict 表示。对于 QueryDict 中的每一个 (key, list) 对，dict 将有 (key, item)，其中 item 是列表中的一个元素，使用与 QueryDict.__getitem__() 相同的逻辑：

>>> q = QueryDict('a=1&a=3&a=5')
>>> q.dict()
{'a': '5'}

QueryDict.urlencode(safe=None)

返回一个查询字符串格式的数据字符串。例如：

>>> q = QueryDict('a=2&b=3&b=5')
>>> q.urlencode()
'a=2&b=3&b=5'

使用 safe 参数来传递不需要编码的字符。例如：

>>> q = QueryDict(mutable=True)
>>> q['next'] = '/a&b/'
>>> q.urlencode(safe='/')
'next=/a%26b/'

用法

>>> from django.http import HttpResponse
>>> response = HttpResponse("Here's the text of the web page.")
>>> response = HttpResponse("Text only, please.", content_type="text/plain")
>>> response = HttpResponse(b'Bytestrings are also accepted.')
>>> response = HttpResponse(memoryview(b'Memoryview as well.'))

>>> response = HttpResponse()
>>> response.write("<p>Here's the text of the web page.</p>")
>>> response.write("<p>Here's another paragraph.</p>")

>>> response = HttpResponse()
>>> response.headers['Age'] = 120
>>> del response.headers['Age']

>>> response = HttpResponse()
>>> response['Age'] = 120
>>> del response['Age']

>>> response = HttpResponse(headers={'Age': 120})

>>> response = HttpResponse(my_data, headers={
...     'Content-Type': 'application/vnd.ms-excel',
...     'Content-Disposition': 'attachment; filename="foo.xls"',
... })

属性

HttpResponse.content

一个代表内容的字节字符串，必要时由字符串编码。

HttpResponse.headers

A case insensitive, dict-like object that provides an interface to all HTTP headers on the response. See 设置头字段.

HttpResponse.charset

表示响应将被编码的字符集的字符串。如果在 HttpResponse 实例化时没有给出，将从 content_type 中提取，如果不成功，将使用 DEFAULT_CHARSET 设置。

HttpResponse.status_code

响应的 HTTP 状态码。

除非 reason_phrase 被明确设置，否则在构造函数外修改 status_code 的值也会修改 reason_phrase 的值。

HttpResponse.reason_phrase

响应的 HTTP 原因短语。它使用 HTTP 标准的 默认的原因短语。

除非明确设置，否则 reason_phrase 由 status_code 的值决定。

HttpResponse.streaming

这总是 False。

此属性的存在是为了让中间件能够将流式响应与常规响应区别对待。

HttpResponse.closed

True 如果响应已经结束。

方法

HttpResponse.__init__(content=b'', content_type=None, status=200, reason=None, charset=None, headers=None)

Instantiates an HttpResponse object with the given page content, content type, and headers.

content 最常见的是迭代器、字节字符串、memoryview 或字符串。其他类型将通过对它们的字符串表示进行编码而转换为字节组。迭代器应该返回字符串或字节字符串，这些将被连接在一起以形成响应的内容。

content_type 是 MIME 类型，可选择用字符集编码完成，用于填充 HTTP Content-Type 头。如果没有指定，则由 'text/html' 和 DEFAULT_CHARSET 配置组成，默认情况下："text/html; charset=utf-8"。

status 是响应的 HTTP 状态码。你可以使用 Python 的 http.HTTPStatus 来实现有意义的别名，比如 HTTPStatus.NO_CONTENT。

reason 是 HTTP 响应短语。如果没有提供，将使用默认短语。

charset 是对响应进行编码的字符集。如果没有给出，将从 content_type 中提取，如果不成功，将使用 DEFAULT_CHARSET 配置。

headers is a dict of HTTP headers for the response.

HttpResponse.__setitem__(header, value)

将给定的响应头名设置为给定的值。header 和 value 都应该是字符串。

HttpResponse.__delitem__(header)

删除指定名称的响应头。如果头不存在，则静默失败。不区分大小写。

HttpResponse.__getitem__(header)

返回给定响应头名的值。不区分大小写。

HttpResponse.get(header, alternate=None)

返回给定响应头的值，如果头不存在，则返回 alternate。

HttpResponse.has_header(header)

根据对给定名称的响应头进行不区分大小写的检查，返回 True 或 False。

HttpResponse.items()

像 dict.items() 一样作用于响应的 HTTP 头信息。

HttpResponse.setdefault(header, value)

设置响应头，除非它已经被设置。

HttpResponse.set_cookie(key, value='', max_age=None, expires=None, path='/', domain=None, secure=False, httponly=False, samesite=None)

设置一个 cookie。参数与 Python 标准库中的 Morsel cookie 对象相同。

• max_age should be a timedelta object, an integer number of seconds, or None (default) if the cookie should last only as long as the client's browser session. If expires is not specified, it will be calculated.

  Changed in Django 4.1:

  Support for timedelta objects was added.

• expires 应是格式为 "Wdy, DD-Mon-YY HH:MM:SS GMT" 的字符串，或者是 UTC 的 datetime.datetime 对象。如果 expires 是一个 datetime 对象，将计算 max_age。

• 如果你想设置一个跨域的 cookie，请使用 domain。例如，domain="example.com" 将设置一个可被 www.example.com、blog.example.com 等域读取的 cookie。否则，一个 cookie 将只能被设置它的域读取。

• 如果你想让 cookie 只在使用 https 方案进行请求时才发送给服务器，请使用 secure=True。

• 如果你想防止客户端的 JavaScript 访问 cookie，请使用 httponly=True。

  HttpOnly 是包含在 Set-Cookie HTTP 响应头中的一个标志。它是 RFC 6265 标准中 Cookie 的一部分，可以作为一种有用的方式来降低客户端脚本访问受保护 Cookie 数据的风险。

• 使用 samesite='Strict' 或 samesite='Lax' 来告诉浏览器在执行跨源请求时不要发送这个 cookie。SameSite 并不是所有浏览器都支持，所以它并不能替代 Django 的 CSRF 保护，而是一种深度防御措施。

  使用 samesite=''None' （字符串）来明确说明这个 cookie 会随着所有的同站和跨站请求而发送。

警告

RFC 6265 规定，用户代理应支持至少 4096 字节的 cookies。对于很多浏览器来说，这也是最大的尺寸。如果试图存储一个超过 4096 字节的 cookie，Django 不会引发异常，但很多浏览器不会正确设置 cookie。

HttpResponse.set_signed_cookie(key, value, salt='', max_age=None, expires=None, path='/', domain=None, secure=False, httponly=False, samesite=None)

像 set_cookie() 一样，但是 在设置 cookie 之前对它进行加密签名。与 HttpRequest.get_signed_cookie() 一起使用。你可以使用可选的 salt 参数来增加密钥强度，但你需要记得把它传递给相应的 HttpRequest.get_signed_cookie() 调用。

HttpResponse.delete_cookie(key, path='/', domain=None, samesite=None)

删除给定键的 cookie。如果键不存在，则静默失败。

由于 cookie 的工作方式，path 和 domain 应该与你在 set_cookie() 中使用的值相同，否则 cookie 可能不会被删除。

HttpResponse.close()

本方法在请求结束时由 WSGI 服务器直接调用。

HttpResponse.write(content)

这个方法使一个 HttpResponse 实例成为一个类似文件的对象。

HttpResponse.flush()

这个方法使一个 HttpResponse 实例成为一个类似文件的对象。

HttpResponse.tell()

这个方法使一个 HttpResponse 实例成为一个类似文件的对象。

HttpResponse.getvalue()

返回 HttpResponse.content 的值。本方法使一个 :class:`HttpResponse`实例成为一个类流对象。

HttpResponse.readable()

总是 False。此方法使 HttpResponse 实例成为一个类流对象。

HttpResponse.seekable()

总是 False。此方法使 HttpResponse 实例成为一个类流对象。

HttpResponse.writable()

总是 True。此方法使 HttpResponse 实例成为一个类流对象。

HttpResponse.writelines(lines)

将行的列表写入响应。不添加行的分隔符。此方法使 HttpResponse 实例成为一个类流对象。

用法

典型的用法可能是：

>>> from django.http import JsonResponse
>>> response = JsonResponse({'foo': 'bar'})
>>> response.content
b'{"foo": "bar"}'

>>> response = JsonResponse([1, 2, 3], safe=False)

>>> response = JsonResponse(data, encoder=MyJSONEncoder)

方法

FileResponse.set_headers(open_file)

该方法在响应初始化过程中自动调用，并根据 open_file 设置各种头文件（Content-Length、Content-Type 和 Content-Disposition）。