Channels 2.3.0 请求体处理重构：AsgiHandler 基于 SpooledTemporaryFile 的内存优化与兼容性迁移指南

• 后端
• WebSocket
• 异步编程

Channels 2.3.0 将AsgiHandler的 HTTP 请求体处理从“一次性整体读入内存”改为“基于 spooled temporary file 的流式处理”，在服务 Django 视图时显著降低峰值内存占用并增强对 DoS 攻击的防护，同时仍完整支持大文件上传。本文以官方 2.3.0 发布说明为骨架，结合仓库中的变更日志与后续版本记录，讲解本次改动的技术原理、向后不兼容的 API 变化、测试代码迁移方式，以及该机制在后继版本（3.0.x、4.0.x）中的演进与最终归宿，帮助你在升级或维护 Channels 项目时准确理解并正确处理请求体。

一、改动背景：为什么 2.3.0 之前“困难”

在 Channels 2.3.0 之前，AsgiHandler处理 HTTP 请求体时，会将整个请求体以 bytes 形式一次性读入内存。这带来一个两难问题：

• 如果限制请求体大小，可以控制内存峰值、降低被恶意大请求拖垮的风险，但会限制合法的大文件上传；
• 如果放开限制以支持大文件上传，则任意客户端都可以发送超大请求体，导致进程内存被快速占满，形成 DoS 攻击面。

官方发布说明（docs/releases/2.3.0.rst）明确指出了这一矛盾：AsgiHandler的请求体处理更新为使用 spooled temporary file，而不是把整个请求体读入内存，从而：

• 显著降低服务 Django 视图时的最大内存需求（significantly reduces the maximum memory requirements）；
• 防范 DoS 攻击（protects from DoS attacks）；
• 同时仍然允许大文件上传（whilst still allowing large file uploads）。

“既能控制内存占用、又能防 DoS、还能支持大文件上传”这三者的组合，在旧实现下是困难的（a combination that had previously beendifficult），正是本次重构要解决的核心问题。

二、核心技术原理：spooled temporary file 如何同时满足三个目标

本次改动的关键，是引入 Python 标准库tempfile.SpooledTemporaryFile作为请求体的承载介质。

SpooledTemporaryFile的工作机制是“先内存、后落盘”的分级存储：

1. 小请求体：数据量未超过设定的max_size（默认阈值，通常在内存量级）时，数据保存在内存中的 BytesIO 缓冲区，读写速度与纯内存无异；
2. 大请求体：一旦数据量超过阈值，缓冲区自动滚动（spool）到磁盘上的临时文件，此后写入与读取都发生在磁盘上，内存占用不再随请求体大小线性增长。

对AsgiHandler而言，这意味着：

• 常规的小型 GET/POST 请求（如表单、JSON API）依旧走内存路径，性能几乎不受影响；
• 超大请求体（如大文件上传）超出阈值后自动落盘，进程内存峰值被钳制在一个可控的上限，不再由“最坏请求体大小”决定；
• 因为内存占用不再与请求体大小成正比，攻击者无法再通过发送巨型 body 轻易耗尽服务器内存，天然削弱了此类 DoS 手段；
• 同时上传功能保持可用，不需要人为砍掉大文件上传能力。

因此，“降内存、防 DoS、保上传”三个目标，通过一个 spooled 临时文件机制被同时满足——这正是 2.3.0 发布说明中强调的此前“困难”之所在。

三、向后不兼容变更：AsgiRequest.__init__()的 stream 化

任何底层存储介质的更换，都会沿 API 边界向上传导。2.3.0 的请求体重构引入了向后不兼容变更（Backwards Incompatible Changes），仓库 CHANGELOG.txt 与发布说明记录如下：

由于请求体处理被重写，AsgiRequest.__init__()调整为期望一个类文件对象 stream，而不是以 bytes 形式传入的整个body。

也就是说，AsgiRequest构造函数的签名语义发生了实质变化：

这一变化直接影响到直接实例化AsgiRequest的测试代码。发布说明给出了明确迁移指引：

Test cases instantiating requests directly will likely need to be updated to wrap the providedbodyin, e.g.,io.BytesIO.

即：凡是直接在测试中构造AsgiRequest的用例，都需要把原先传入的body字节串包装进io.BytesIO，以符合新的 stream 参数契约。

迁移示例

改造前的测试写法（2.3.0 之前）：

request = AsgiRequest(scope, body=b"hello world")

改造后的测试写法（2.3.0 及以后）：

import io request = AsgiRequest(scope, stream=io.BytesIO(b"hello world"))

如果被测逻辑只需读取完整内容，也可显式兼容两种形态：

import io if isinstance(body, bytes): stream = io.BytesIO(body) else: stream = body # 已是 file-like request = AsgiRequest(scope, stream=stream)

升级到 2.3.0 时，检索代码中所有直接调用AsgiRequest(...)的位置（尤其是tests/目录下的用例），将 bytes 型 body 统一改为io.BytesIO(body)包装，即可完成迁移。

四、本次改动在仓库中的记录与佐证

仓库中与本次改动直接相关的证据链如下：

• docs/releases/2.3.0.rst：官方 2.3.0 发布说明，包含内存优化、DoS 防护、大文件上传、AsgiRequest.__init__()stream 化及测试迁移指引的全部原始表述；
• CHANGELOG.txt：在2.3.0 (2019-09-18)条目下复述了同一改动：Adjusted AsgiHandler HTTP body handling to use a spooled temporary file, rather than reading the whole request body into memory.，并记录了AsgiRequest.__init__()期望 file-likestream、测试需用io.BytesIO包装 body 的迁移要求；
• 紧随其后的CHANGELOG.txt记录2.3.1 (2019-10-23)增加了 Python 3.8 兼容性，可作为 2.3.0/2.3.1 时代使用 Python 版本的前提参考。

需要注意的是，AsgiHandler/AsgiRequest是 Channels 自带的“包裹 Django 视图”的 HTTP 处理类，其使用场景是在 ASGI 环境下、由 Channels 自身把http.request事件转换为 Django 请求对象再调用视图。

五、演进与归宿：从 2.3.0 的优化到 4.0.0 的移除

理解 2.3.0 的改动，还需要把它放进 Channels 的版本演进时间线中，因为该机制后续经历了“弃用—安全修复—移除”三个阶段：

5.1 3.0.0：AsgiHandler被标记弃用

docs/releases/3.0.0.rst 记录，从 Channels 3.0.0 起，内置的AsgiHandler被弃用，官方建议升级到 Django 3.0+，改用 Django 自带的get_asgi_application()作为 HTTP 处理器，并将在停止支持 Django 2.2 后移除 Channels 的AsgiHandler。官方推荐的asgi.py入口写法：

from django.core.asgi import get_asgi_application from channels.routing import ProtocolTypeRouter application = ProtocolTypeRouter({ "http": get_asgi_application(), # Other protocols here. })

5.2 3.0.3：遗留AsgiHandler的安全修复

docs/releases/3.0.3.rst 记录了 CVE-2020-35681：遗留的channels.http.AsgiHandler在 Channels 3.0.x（3.0.3 之前）未能正确隔离请求作用域，多数情况下会崩溃，但在特定时序下可能把响应发给错误的客户端，导致会话标识符等敏感数据泄漏。该问题影响所有未显式指定'http'处理器、或显式使用channels.http.AsgiHandler（为支持 Django 2.2）的用户，应在 3.0.3 立即升级。该问题仅影响 Channels 自带的遗留类，不影响 Django 3.0 提供的ASGIHandler。

这一事件也从侧面说明：2.3.0 在请求体层面解决的内存/DoS 问题，是AsgiHandler生命周期中的一个重要改进，但该类的长期维护价值在 Django 官方 ASGI 支持成熟后迅速下降。

5.3 4.0.0：AsgiHandler与AsgiRequest正式移除

docs/releases/4.0.0.rst 记录：Channels 4.0.0 移除了已弃用的AsgiHandler（它用于包裹 Django 视图），并同时移除了仅服务于AsgiHandler的AsgiRequest。

因此，在当前仓库（channels/init.py 标注版本为 4.2.0）的源码树中，已经不存在AsgiHandler/AsgiRequest的实现代码，2.3.0 的 spooled temporary file 优化作为历史实现，已完整融入并终结于这条演进链中。新项目应直接使用 Django 的get_asgi_application()；只有维护 2.x/3.0.x 老项目时，才需要接触本文所述的请求体机制与迁移要求。

六、实战自查清单：升级与维护要点

无论你是停留在 2.3.0 时代维护旧系统，还是从旧版迁移到 Django 原生 ASGI，都可以用以下清单完成自查：

1. 请求体内存策略：确认所使用版本的AsgiHandler（2.3.0+）已采用 spooled temporary file；若仍在 2.3.0 之前，超大上传请求会整体驻留内存，存在 DoS 风险，应升级；
2. 测试代码签名：直接实例化AsgiRequest的用例，必须把 bytes 型body包装为io.BytesIOstream 再传入，否则在新版本会因参数契约不符而失败；
3. 中间件/自封装代码：若有代码自行读取request.body或透传请求体，确认其能正确处理 file-like stream（必要时读取stream.read()），而不是假设 body 一定是完整 bytes；
4. 安全与弃用状态：运行在 Channels 3.0.x 且使用遗留AsgiHandler的，应立即升级到 3.0.3+ 以规避 CVE-2020-35681；3.0.0 起已弃用该类，继续使用会收到弃用警告；
5. 长期方向：新代码一律采用 Django 3.0+ 的get_asgi_application()处理 HTTP，Channels 专注于 WebSocket 等自有协议；升级到 4.x 后遗留类已彻底移除。

结语

Channels 2.3.0 的 spooled temporary file 重构，是请求体处理路径上一次“小而关键”的工程改进：用标准库的分级存储机制，一举调和了内存峰值、DoS 防护与大文件上传三者之间的矛盾，并顺势把AsgiRequest的接口从“整包 bytes”推进到“file-like stream”，使后续实现无需再为请求体尺寸提前买单。理解这条改动及其在 3.0.0 弃用、3.0.3 安全修复、4.0.0 移除中的完整生命周期，无论对老项目的安全升级，还是对新项目的架构选择，都是一份有价值的历史参照。

关键仓库依据：发布说明 docs/releases/2.3.0.rst，变更日志 CHANGELOG.txt，后继演进记录 docs/releases/3.0.0.rst、docs/releases/3.0.3.rst、docs/releases/4.0.0.rst，当前版本标记见 channels/init.py。

• 后端
• WebSocket
• 异步编程