```
#### `QueryDict.__getitem__(key)`
返回给定键的值。如果键有多个值，则返回最后一个值。如果键不存在，会引发 `django.utils.datastructures.MultiValueDictKeyError`。（这是 Python 标准的 [`KeyError`](https://docs.python.org/3/library/exceptions.html#KeyError) 的一个子类，所以你可以坚持捕捉 `KeyError`。)
#### `QueryDict.__setitem__(key, value)`
将给定的键设置为 `[value]` （一个单一元素为 `value` 的列表）。请注意，这个函数和其他有副作用的字典函数一样，只能在一个可变的 `QueryDict` 上调用（比如通过 [`QueryDict.copy()`](#django.http.QueryDict.copy) 创建的）。
#### `QueryDict.__contains__(key)`
如果给定的键被设置，返回 `True`。这让你可以执行，例如，`if "foo" in request.GET`。
#### `QueryDict.get(key, default=None)`
使用与 [`__getitem__()`](#django.http.QueryDict.__getitem__) 相同的逻辑，如果键不存在，则用钩子返回一个默认值。
#### `QueryDict.setdefault(key, default=None)`
与 [`dict.setdefault()`](https://docs.python.org/3/library/stdtypes.html#dict.setdefault) 一样，只是它在内部使用 [`__setitem__()`](#django.http.QueryDict.__setitem__)。
#### `QueryDict.update(other_dict)`
接受一个 `QueryDict` 或一个字典。类似于 [`dict.update()`](https://docs.python.org/3/library/stdtypes.html#dict.update)，但它会将项目添加到当前字典而不是替换它们。例如：
```pycon
>>> 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()`](https://docs.python.org/3/library/stdtypes.html#dict.items)，不过它使用与 [`__getitem__()`](#django.http.QueryDict.__getitem__) 相同的最后一个值逻辑，并返回一个迭代器对象而不是视图对象。例如：
```pycon
>>> q = QueryDict("a=1&a=2&a=3")
>>> list(q.items())
[('a', '3')]
```
#### `QueryDict.values()`
类似于 [`dict.values()`](https://docs.python.org/3/library/stdtypes.html#dict.values)，不过它使用与 [`__getitem__()`](#django.http.QueryDict.__getitem__) 相同的最后一个值逻辑，并返回一个迭代器而不是视图对象。例如：
```pycon
>>> q = QueryDict("a=1&a=2&a=3")
>>> list(q.values())
['3']
```
此外，`QueryDict` 有以下方法：
#### `QueryDict.copy()`
使用 [`copy.deepcopy()`](https://docs.python.org/3/library/copy.html#copy.deepcopy) 返回对象的副本。这个副本将是可变的，即使原始副本不是。
#### `QueryDict.getlist(key, default=None)`
返回带有请求键的数据列表。如果键不存在且 `default` 是 `None`，则返回一个空列表。除非提供的默认值不是一个列表，否则保证返回一个列表。
#### `QueryDict.setlist(key, list_)`
将给定的键设置为 `list_` （与 [`__setitem__()`](#django.http.QueryDict.__setitem__) 不同）。
#### `QueryDict.appendlist(key, item)`
将一个项目添加到与键相关联的内部列表中。
#### `QueryDict.setlistdefault(key, default_list=None)`
和 [`setdefault()`](#django.http.QueryDict.setdefault) 一样，只不过它取的是一个值的列表，而不是单个值。
#### `QueryDict.lists()`
类似于 [`items()`](#django.http.QueryDict.items)，不过它包括字典中每个成员的所有值，以列表的形式。例如：
```pycon
>>> q = QueryDict("a=1&a=2&a=3")
>>> q.lists()
[('a', ['1', '2', '3'])]
```
#### `QueryDict.pop(key)`
返回给定键的值列表并从字典中删除它们。如果键不存在，则引发 `KeyError`。例如：
```pycon
>>> q = QueryDict("a=1&a=2&a=3", mutable=True)
>>> q.pop("a")
['1', '2', '3']
```
#### `QueryDict.popitem()`
移除字典中的一个任意成员（因为没有顺序概念），并返回一个包含键和该键所有值的列表的两个值的元组。当在空字典上调用时，引发 `KeyError`。例如：
```pycon
>>> q = QueryDict("a=1&a=2&a=3", mutable=True)
>>> q.popitem()
('a', ['1', '2', '3'])
```
#### `QueryDict.dict()`
返回 `QueryDict` 的 `dict` 表示。对于 `QueryDict` 中的每个（键，列表）对，`dict` 将具有（键，项），其中项是列表的一个元素，使用与 [`QueryDict.__getitem__()`](#django.http.QueryDict.__getitem__) 相同的逻辑：
```pycon
>>> q = QueryDict("a=1&a=3&a=5")
>>> q.dict()
{'a': '5'}
```
#### `QueryDict.urlencode(safe=None)`
以查询字符串格式返回数据的字符串。例如：
```pycon
>>> q = QueryDict("a=2&b=3&b=5")
>>> q.urlencode()
'a=2&b=3&b=5'
```
使用 `safe` 参数传递不需要编码的字符。例如：
```pycon
>>> q = QueryDict(mutable=True)
>>> q["next"] = "/a&b/"
>>> q.urlencode(safe="/")
'next=/a%26b/'
```
## `HttpResponse` 对象
#### `class HttpResponse`
与 Django 自动创建的 [`HttpRequest`](#django.http.HttpRequest) 对象不同， [`HttpResponse`](#django.http.HttpResponse) 对象是你的责任。你写的每个视图都要负责实例化、填充和返回一个 [`HttpResponse`](#django.http.HttpResponse) 对象。
[`HttpResponse`](#django.http.HttpResponse) 类位于 [`django.http`](#module-django.http) 模块中。
### 用法
#### 传入字符串
典型的用法是将页面的内容作为字符串、字节串或 [`memoryview`](https://docs.python.org/3/library/stdtypes.html#memoryview) 传递给 [`HttpResponse`](#django.http.HttpResponse) 构造函数：
```pycon
>>> 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` 当作类似文件的对象来使用：
```pycon
>>> response = HttpResponse()
>>> response.write("Here's the text of the web page.
")
>>> response.write("Here's another paragraph.
")
```
#### 传入迭代器
最后，你可以传递 `HttpResponse` 一个迭代器而不是字符串。`HttpResponse` 将立即消耗迭代器，将其内容存储为一个字符串，然后丢弃它。带有 `close()` 方法的对象，如文件和生成器，会立即关闭。
如果你需要将响应从迭代器流式传输到客户端，你必须使用 [`StreamingHttpResponse`](#django.http.StreamingHttpResponse) 类来代替。
#### 设置头字段
要在响应中设置或移除头字段，使用 [`HttpResponse.headers`](#django.http.HttpResponse.headers)：
```pycon
>>> response = HttpResponse()
>>> response.headers["Age"] = 120
>>> del response.headers["Age"]
```
你还可以通过将响应当作字典来操作头部信息：
```pycon
>>> response = HttpResponse()
>>> response["Age"] = 120
>>> del response["Age"]
```
这相当于代理到了 `HttpResponse.headers`，也是 `HttpResponse` 最初提供的接口。
使用这个接口时，不像字典那样，如果头字段不存在，`del` 不会引发 `KeyError`。
你还可以在实例化时设置头部信息：
```pycon
>>> response = HttpResponse(headers={"Age": 120})
```
对于设置 `Cache-Control` 和 `Vary` 头字段，建议使用 [`django.utils.cache.patch_cache_control`](/zh-hans/5.0/ref/utils/#django.utils.cache.patch_cache_control) 和 [`django.utils.cache.patch_vary_headers`](/zh-hans/5.0/ref/utils/#django.utils.cache.patch_vary_headers) 中的 [`patch_cache_control()`](/zh-hans/5.0/ref/utils/#django.utils.cache.patch_cache_control) 和 [`patch_vary_headers()`](/zh-hans/5.0/ref/utils/#django.utils.cache.patch_vary_headers) 方法，因为这些字段可以有多个以逗号分隔的值。这些“补丁”方法保证了其他的值，例如由中间件添加的值，不会被删除。
HTTP 头字段不能包含换行符。试图设置一个包含换行符（CR 或 LF）的头字段将引发 `BadHeaderError`。
#### 告诉浏览器将响应作为文件附件处理
要告诉浏览器将响应视为文件附件，设置 `Content-Type` 和 `Content-Disposition` 头部。例如，这是如何返回一个 Microsoft Excel 电子表格的方式：
```pycon
>>> response = HttpResponse(
... my_data,
... headers={
... "Content-Type": "application/vnd.ms-excel",
... "Content-Disposition": 'attachment; filename="foo.xls"',
... },
... )
```
`Content-Disposition` 头并没有什么 Django 特有的内容，但是很容易忘记语法，所以我们把它包含在这里。
### 属性
#### `HttpResponse.content`
一个代表内容的字节字符串，必要时由字符串编码。
#### `HttpResponse.cookies`
一个包含在响应中的 cookie 的 [`http.cookies.SimpleCookie`](https://docs.python.org/3/library/http.cookies.html#http.cookies.SimpleCookie) 对象。
#### `HttpResponse.headers`
一个不区分大小写的、类似字典的对象，提供对响应中除了 `Set-Cookie` 头部之外的所有 HTTP 头部的接口。请参阅 [设置头字段](#setting-header-fields) 和 [`HttpResponse.cookies`](#django.http.HttpResponse.cookies)。
#### `HttpResponse.charset`
表示响应将被编码的字符集的字符串。如果在 `HttpResponse` 实例化时没有给出，将从 `content_type` 中提取，如果不成功，将使用 [`DEFAULT_CHARSET`](/zh-hans/5.0/ref/settings/#std-setting-DEFAULT_CHARSET) 设置。
#### `HttpResponse.status_code`
响应的 [**HTTP 状态码**](https://datatracker.ietf.org/doc/html/rfc9110.html#section-15)。
除非 [`reason_phrase`](#django.http.HttpResponse.reason_phrase) 被明确设置，否则在构造函数外修改 `status_code` 的值也会修改 `reason_phrase` 的值。
#### `HttpResponse.reason_phrase`
响应的 HTTP 原因短语。它使用 [**HTTP 标准**](https://datatracker.ietf.org/doc/html/rfc9110.html#section-15.1) 中的默认原因短语。
除非明确设置，否则 `reason_phrase` 由 [`status_code`](#django.http.HttpResponse.status_code) 的值决定。
#### `HttpResponse.streaming`
这总是 `False`。
此属性的存在是为了让中间件能够将流式响应与常规响应区别对待。
#### `HttpResponse.closed`
`True` 如果响应已经结束。
### 方法
#### `HttpResponse.__init__(content=b'', content_type=None, status=200, reason=None, charset=None, headers=None)`
使用给定的页面内容、内容类型和头部实例化一个 `HttpResponse` 对象。
`content` 最常见的是迭代器、字节字符串、[`memoryview`](https://docs.python.org/3/library/stdtypes.html#memoryview) 或字符串。其他类型将通过对它们的字符串表示进行编码而转换为字节组。迭代器应该返回字符串或字节字符串，这些将被连接在一起以形成响应的内容。
`content_type` 是 MIME 类型，可选择用字符集编码完成，用于填充 HTTP `Content-Type` 头。如果没有指定，则由 `'text/html'` 和 [`DEFAULT_CHARSET`](/zh-hans/5.0/ref/settings/#std-setting-DEFAULT_CHARSET) 配置组成，默认情况下：`"text/html; charset=utf-8"`。
`status` 是响应的 [**HTTP 状态码**](https://datatracker.ietf.org/doc/html/rfc9110.html#section-15)。你可以使用 Python 的 [`http.HTTPStatus`](https://docs.python.org/3/library/http.html#http.HTTPStatus) 来使用有意义的别名，例如 `HTTPStatus.NO_CONTENT`。
`reason` 是 HTTP 响应短语。如果没有提供，将使用默认短语。
`charset` 是对响应进行编码的字符集。如果没有给出，将从 `content_type` 中提取，如果不成功，将使用 [`DEFAULT_CHARSET`](/zh-hans/5.0/ref/settings/#std-setting-DEFAULT_CHARSET) 配置。
`headers` 是响应的 HTTP 头部的 [`dict`](https://docs.python.org/3/library/stdtypes.html#dict)。
#### `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()`](https://docs.python.org/3/library/stdtypes.html#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`](https://docs.python.org/3/library/http.cookies.html#http.cookies.Morsel) cookie 对象相同。
- `max_age` 应该是一个 [`timedelta`](https://docs.python.org/3/library/datetime.html#datetime.timedelta) 对象、整数秒数，或者 `None` （默认值），如果 cookie 只应持续客户端浏览器会话的时间。如果未指定 `expires`，它将被计算。
- `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](https://owasp.org/www-community/HttpOnly) 是包含在 Set-Cookie HTTP 响应头中的一个标志。它是 [**RFC 6265**](https://datatracker.ietf.org/doc/html/rfc6265.html#section-4.1.2.6) 标准中 Cookie 的一部分，可以作为一种有用的方式来降低客户端脚本访问受保护 Cookie 数据的风险。
- 使用 `samesite='Strict'` 或 `samesite='Lax'` 来告诉浏览器在执行跨源请求时不要发送这个 cookie。[SameSite](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie#samesitesamesite-value) 并不是所有浏览器都支持，所以它并不能替代 Django 的 CSRF 保护，而是一种深度防御措施。
使用 `samesite=''None'` （字符串）来明确说明这个 cookie 会随着所有的同站和跨站请求而发送。
> **Warning**
>
> [**RFC 6265**](https://datatracker.ietf.org/doc/html/rfc6265.html#section-6.1) 规定，用户代理应支持至少 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()`](#django.http.HttpResponse.set_cookie) 一样，但是 [在设置 cookie 之前对它进行加密签名](/zh-hans/5.0/topics/signing/)。与 [`HttpRequest.get_signed_cookie()`](#django.http.HttpRequest.get_signed_cookie) 一起使用。你可以使用可选的 `salt` 参数来增加密钥强度，但你需要记得把它传递给相应的 [`HttpRequest.get_signed_cookie()`](#django.http.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`](#django.http.HttpResponse) 实例成为一个类似文件的对象。
#### `HttpResponse.flush()`
这个方法使一个 [`HttpResponse`](#django.http.HttpResponse) 实例成为一个类似文件的对象。
#### `HttpResponse.tell()`
这个方法使一个 [`HttpResponse`](#django.http.HttpResponse) 实例成为一个类似文件的对象。
#### `HttpResponse.getvalue()`
返回 [`HttpResponse.content`](#django.http.HttpResponse.content) 的值。本方法使一个 :class:HttpResponse\`实例成为一个类流对象。
#### `HttpResponse.readable()`
总是 `False`。此方法使 [`HttpResponse`](#django.http.HttpResponse) 实例成为一个类流对象。
#### `HttpResponse.seekable()`
总是 `False`。此方法使 [`HttpResponse`](#django.http.HttpResponse) 实例成为一个类流对象。
#### `HttpResponse.writable()`
总是 `True`。此方法使 [`HttpResponse`](#django.http.HttpResponse) 实例成为一个类流对象。
#### `HttpResponse.writelines(lines)`
将行的列表写入响应。不添加行的分隔符。此方法使 [`HttpResponse`](#django.http.HttpResponse) 实例成为一个类流对象。
### `HttpResponse` 子类
Django 包含了许多 `HttpResponse` 的子类来处理不同类型的 HTTP 响应。像 `HttpResponse` 一样，这些子类位于 [`django.http`](#module-django.http) 中。
#### `class HttpResponseRedirect`
构造函数的第一个参数是必需的——要重定向的路径。这可以是一个完全限定的 URL（例如 `'https://www.yahoo.com/search/`)，一个没有域名的绝对路径（例如 `'/search/'`），甚至是一个相对路径（例如 `'search/'`）。在最后一种情况下，客户端浏览器会根据当前路径自己重建完整的 URL。参见 [`HttpResponse`](#django.http.HttpResponse) 了解其他可选的构造函数参数。请注意，这将返回一个 HTTP 状态码 302。
#### `url`
这个只读属性表示响应将重定向到的 URL（相当于 `Location` 响应头）。
#### `class HttpResponsePermanentRedirect`
就像 [`HttpResponseRedirect`](#django.http.HttpResponseRedirect) 一样，但它返回的是一个永久重定向（HTTP 状态码 301），而不是“found”重定向（状态码 302）。
#### `class HttpResponseNotModified`
构造函数不接受任何参数，也不应该添加任何内容到这个响应中。用它来表示自用户最后一次请求后，页面没有被修改（状态码 304）。
#### `class HttpResponseBadRequest`
就像 [`HttpResponse`](#django.http.HttpResponse) 一样，但使用 400 状态码。
#### `class HttpResponseNotFound`
就像 [`HttpResponse`](#django.http.HttpResponse) 一样，但使用 404 状态码。
#### `class HttpResponseForbidden`
就像 [`HttpResponse`](#django.http.HttpResponse) 一样，但使用 403 状态码。
#### `class HttpResponseNotAllowed`
就像 [`HttpResponse`](#django.http.HttpResponse) 一样，但使用 405 状态码。构造函数的第一个参数是必需的：一个允许的方法列表（例如 `['GET', 'POST']`）。
#### `class HttpResponseGone`
就像 [`HttpResponse`](#django.http.HttpResponse) 一样，但使用 410 状态码。
#### `class HttpResponseServerError`
就像 [`HttpResponse`](#django.http.HttpResponse) 一样，但使用 500 状态码。
> **Note**
>
> 如果 [`HttpResponse`](#django.http.HttpResponse) 的自定义子类实现了 `render` 方法，Django 会将其视为模拟 [`SimpleTemplateResponse`](/zh-hans/5.0/ref/template-response/#django.template.response.SimpleTemplateResponse)，并且 `render` 方法本身必须返回一个有效的响应对象。
#### 自定义响应类
如果你发现自己需要一个 Django 没有提供的响应类，你可以借助 [`http.HTTPStatus`](https://docs.python.org/3/library/http.html#http.HTTPStatus) 来创建它。例如：
```
from http import HTTPStatus
from django.http import HttpResponse
class HttpResponseNoContent(HttpResponse):
status_code = HTTPStatus.NO_CONTENT
```
## `JsonResponse` 对象
#### `class JsonResponse(data, encoder=DjangoJSONEncoder, safe=True, json_dumps_params=None, **kwargs)`
一个 [`HttpResponse`](#django.http.HttpResponse) 子类，帮助创建一个 JSON 编码的响应。它继承了它的超类的大部分行为，但有一些不同：
其默认的 `Content-Type` 头设置为 `application/json`。
第一个参数 `data` 应该是 `dict` 实例。如果 `safe` 参数设置为 `False` （见下文），它可以是任何 JSON 可序列化的对象。
`encoder`，默认为 [`django.core.serializers.json.DjangoJSONEncoder`](/zh-hans/5.0/topics/serialization/#django.core.serializers.json.DjangoJSONEncoder)，将用于序列化数据。关于这个序列化器的更多细节，请参见 [JSON 序列化](/zh-hans/5.0/topics/serialization/#serialization-formats-json)。
`safe` 布尔参数默认为 `True`。如果它被设置为 `False`，任何对象都可以被传递到序列化中（否则只允许 `dict` 实例）。如果 `safe` 为 `True`，而第一个参数是一个非 `dict` 对象，则会引发一个 [`TypeError`](https://docs.python.org/3/library/exceptions.html#TypeError)。
`json_dumps_params` 参数是一个关键字参数的字典，用来传递给 `json.dumps()` 调用，用于生成响应。
### 用法
典型的用法可能如下所示：
```pycon
>>> from django.http import JsonResponse
>>> response = JsonResponse({"foo": "bar"})
>>> response.content
b'{"foo": "bar"}'
```
#### 序列化非字典对象
为了序列化除了 `dict` 之外的对象，你必须将 `safe` 参数设置为 `False`：
```pycon
>>> response = JsonResponse([1, 2, 3], safe=False)
```
如果没有传递 `safe=False`，将引发一个 [`TypeError`](https://docs.python.org/3/library/exceptions.html#TypeError)。
注意，基于 `dict` 对象的 API 更具可扩展性、灵活性，并且更容易维护前向兼容性。因此，你应该避免在 JSON 编码的响应中使用非字典对象。
> **Warning**
>
> 在 [ECMAScript 第 5 版](https://262.ecma-international.org/5.1/#sec-11.1.4) 之前，可能会对 JavaScript 的 `Array` 构造函数进行恶意操作。因此，Django 默认情况下不允许将非字典对象传递给 [`JsonResponse`](#django.http.JsonResponse) 构造函数。然而，大多数现代浏览器实现了 ECMAScript 5，消除了这种攻击方式。因此，可以禁用这个安全预防措施。
#### 更改默认 JSON 编码器
如果你需要使用不同的 JSON 编码器类，可以将 `encoder` 参数传递给构造方法：
```pycon
>>> response = JsonResponse(data, encoder=MyJSONEncoder)
```
## `StreamingHttpResponse` 对象
#### `class StreamingHttpResponse`
[`StreamingHttpResponse`](#django.http.StreamingHttpResponse) 类用于从 Django 向浏览器流式传输响应。
> **高级用法**
>
> [`StreamingHttpResponse`](#django.http.StreamingHttpResponse) 有点高级，因为重要的是要知道你将在 WSGI 下同步提供你的应用程序，还是在 ASGI 下异步提供，并相应地调整你的用法。
>
> 请仔细阅读这些注释。
[`StreamingHttpResponse`](#django.http.StreamingHttpResponse) 在 WSGI 下的一个示例用法是在生成响应时需要太长时间或使用太多内存的情况下进行流式传输内容。例如，在 [生成大型 CSV 文件](/zh-hans/5.0/howto/outputting-csv/#streaming-csv-files) 时非常有用。
不过，在执行这种操作时需要考虑性能问题。Django 在 WSGI 下设计用于短暂的请求。流式响应将绑定一个工作进程在响应的整个持续时间内。这可能导致性能不佳。
一般来说，你应该在请求-响应周期之外执行昂贵的任务，而不是采用流式响应。
然而，在 ASGI 下提供服务时，一个 [`StreamingHttpResponse`](#django.http.StreamingHttpResponse) 不需要在等待 I/O 时阻止其他请求被处理。这打开了在流式传输内容时进行长时间请求和实施长轮询以及服务器推送事件等模式的可能性。
即使在 ASGI 下，也应该只在绝对需要在将数据传输给客户端之前不迭代整个内容的情况下使用 [`StreamingHttpResponse`](#django.http.StreamingHttpResponse)。因为无法访问内容，许多中间件无法正常工作。例如，对于流式响应，无法生成 `ETag` 和 `Content-Length` 头部。
[`StreamingHttpResponse`](#django.http.StreamingHttpResponse) 不是 [`HttpResponse`](#django.http.HttpResponse) 的子类，因此它的 API 略有不同。然而，它几乎是相同的，但有以下显著的区别。
- 它应该被提供一个产生字节串、[`memoryview`](https://docs.python.org/3/library/stdtypes.html#memoryview) 或字符串作为内容的迭代器。在 WSGI 下提供服务时，这应该是一个同步迭代器。在 ASGI 下提供服务时，应该是一个异步迭代器。
- 除非迭代响应对象本身，否则无法访问其内容。这只应该在响应返回给客户端时发生：你不应该自己迭代响应。
在 WSGI 下，响应将同步迭代。在 ASGI 下，响应将异步迭代。（这就是为什么迭代器类型必须与你使用的协议匹配的原因。）
为了避免崩溃，迭代时将将不正确的迭代器类型映射到正确的类型，并引发警告，但为了执行这个操作，迭代器必须被完全消耗，这就破坏了使用 [`StreamingHttpResponse`](#django.http.StreamingHttpResponse) 的目的。
- 它没有 `content` 属性。相反，它有一个 [`streaming_content`](#django.http.StreamingHttpResponse.streaming_content) 属性。这可以在中间件中用于包装响应可迭代对象，但不应该被消耗。
- 你不能使用类文件对象的 `tell()` 或 `write()` 方法。这样做会引起一个异常。
[`HttpResponseBase`](#django.http.HttpResponseBase) 基类在 [`HttpResponse`](#django.http.HttpResponse) 和 [`StreamingHttpResponse`](#django.http.StreamingHttpResponse) 之间是通用的。
> **Changed in Django 4.2**
>
> 已添加对异步迭代的支持。
### 属性
#### `StreamingHttpResponse.streaming_content`
响应内容的迭代器，根据 [`HttpResponse.charset`](#django.http.HttpResponse.charset) 编码的字节字符串。
#### `StreamingHttpResponse.status_code`
响应的 [**HTTP 状态码**](https://datatracker.ietf.org/doc/html/rfc9110.html#section-15)。
除非 [`reason_phrase`](#django.http.StreamingHttpResponse.reason_phrase) 被明确设置，否则在构造函数外修改 `status_code` 的值也会修改 `reason_phrase` 的值。
#### `StreamingHttpResponse.reason_phrase`
响应的 HTTP 原因短语。它使用 [**HTTP 标准**](https://datatracker.ietf.org/doc/html/rfc9110.html#section-15.1) 中的默认原因短语。
除非明确设置，否则 `reason_phrase` 由 [`status_code`](#django.http.StreamingHttpResponse.status_code) 的值决定。
#### `StreamingHttpResponse.streaming`
这总是 `True`。
#### `StreamingHttpResponse.is_async`
> **New in Django 4.2**
一个布尔值，指示 [`StreamingHttpResponse.streaming_content`](#django.http.StreamingHttpResponse.streaming_content) 是否是异步迭代器。
这对于需要包装 [`StreamingHttpResponse.streaming_content`](#django.http.StreamingHttpResponse.streaming_content) 的中间件非常有用。
### 处理断开连接
> **New in Django 5.0**
如果在流式响应期间客户端断开连接，Django 将取消处理响应的协程。如果你想手动清理资源，可以通过捕获 `asyncio.CancelledError` 来实现：
```
async def streaming_response():
try:
# Do some work here
async for chunk in my_streaming_iterator():
yield chunk
except asyncio.CancelledError:
# Handle disconnect
...
raise
async def my_streaming_view(request):
return StreamingHttpResponse(streaming_response())
```
这个示例只展示了在响应流式传输时如何处理客户端断开连接。如果在返回 `StreamingHttpResponse` 对象之前在视图中执行长时间运行的操作，那么你可能还想在视图本身中处理断开连接，可以参考 [在视图中处理断开连接](/zh-hans/5.0/topics/async/#async-handling-disconnect)。
## `FileResponse` 对象
#### `class FileResponse(open_file, as_attachment=False, filename='', **kwargs)`
[`FileResponse`](#django.http.FileResponse) 是 [`StreamingHttpResponse`](#django.http.StreamingHttpResponse) 的一个子类，它针对二进制文件进行了优化。如果 wsgi 服务器提供的话，它使用 [**wsgi.file\_wrapper**](https://peps.python.org/pep-3333/#optional-platform-specific-file-handling)，否则它将文件以小块的形式流式传输出去。
如果 `as_attachment=True`，`Content-Disposition` 头被设置为 `attachment`，要求浏览器将文件作为下载文件提供给用户。否则，只有在有文件名的情况下，才会设置值为 `inline` 的 `Content-Disposition` 头（浏览器默认）。
如果 `open_file` 没有名字，或者 `open_file` 的名字不合适，可以使用 `filename` 参数提供一个自定义的文件名。请注意，如果你传递了一个类似文件的对象，比如 `io.BytesIO`，你的任务是在把它传递给 `FileResponse` 之前 `` seek()` ``。
当可以从 `open_file` 的内容猜测到时，`Content-Length` 头部将自动设置。
当可以从 `filename` 或 `open_file` 的名称猜测到时，`Content-Type` 头部将自动设置。
`FileResponse` 接受任何具有二进制内容的文件类似对象，例如以二进制模式打开的文件，如下所示：
```pycon
>>> from django.http import FileResponse
>>> response = FileResponse(open("myfile.png", "rb"))
```
该文件会自动关闭，所以不要用上下文管理器打开它。
> **在 ASGI 下使用**
>
> Python 的文件 API 是同步的。这意味着文件必须被完全消耗才能在 ASGI 下提供服务。
>
> 为了异步流式传输文件，你需要使用提供异步文件 API 的第三方包，例如 [aiofiles](https://github.com/Tinche/aiofiles)。
### 方法
#### `FileResponse.set_headers(open_file)`
该方法在响应初始化过程中自动调用，并根据 `open_file` 设置各种头文件（`Content-Length`、`Content-Type` 和 `Content-Disposition`）。
## `HttpResponseBase` 类
#### `class HttpResponseBase`
[`HttpResponseBase`](#django.http.HttpResponseBase) 类是所有 Django 响应共有的。它不应该直接用于创建响应，但在类型检查方面可能会有用。