Werkzeug 版本演进全解析:从 0.1 到 3.2.0 的变更史与技术路线图

原创2026-10-05 14:24:511,821 阅读
文章标签:后端Web框架

Werkzeug 版本演进全解析:从 0.1 到 3.2.0 的变更史与技术路线图

本文以仓库根目录的 CHANGES.rst(由 docs/changes.rst 通过 .. include:: ../CHANGES.rst 引入)为骨架,逐版本梳理 Werkzeug —— 这套 "The comprehensive WSGI web application library" —— 十余年的演进脉络。读完本文,你将掌握每个版本的核心变更、弃用与移除清单、安全修复要点、路由/表单/测试客户端/开发服务器等核心模块的能力变迁,并能结合仓库源码(src/werkzeug)与测试(tests)深入理解每一项变更背后的实现依据。这份变更记录本身就是一份绝佳的升级指南与技术决策档案:任何一次从旧版本迁移到新版本,都可以对照它逐条核查自己的代码是否踩中移除项或行为变化点。

一、文档定位:一份可当"升级圣经"使用的变更史

docs/changes.rst 本身只有三行——标题加一个 include 指令,真正的正文全部来自仓库根目录的 CHANGES.rst。这份文件按版本倒序组织:最新版本在最上方,最早的 0.1 版本在文件末尾,合计覆盖从 2007 年 12 月(0.1,代号 Wictorinoxger)到当前 3.2.0 的全部历史。

从 pyproject.toml 可以看到,当前仓库版本为 3.2.0.dev,要求 Python >= 3.10,唯一硬依赖是 markupsafe>=3.0.3(对应 3.2.0 的"最低 MarkupSafe 版本提升"条目),watchdog>=6 是可选依赖(对应 Watchdog reloader 的最低版本要求)。这组版本与依赖信息与 CHANGES.rst 顶部完全吻合,阅读变更记录时可以直接以仓库当前状态为参照物。

这份文档的价值有三层:

  1. 升级迁移清单:每个版本都列出了"移除此前已弃用的代码"清单,以及新增弃用项,升级前逐条对照即可规避踩坑;
  2. 安全公告索引:从 GHSA 编号(如 :ghsa:29vq-49wr-vm6x、:ghsa:87hc-h4r5-73f7、:ghsa:f9vj-2wh5-fj8j、:ghsa:2g68-c3qc-8985)可以反查每个安全修复的详情;
  3. 架构演进档案:sans-IO 重构、状态机路由器、类型注解全面化等重大架构决策都留有明确的时间戳。

二、3.2.0:API 现代化与大规模弃用

3.2.0 是当前未发布的最新版本(在 CHANGES.rst 中列于最顶端),核心主题是"收紧类型系统、清理历史包袱"。

2.1 Python 版本与依赖门槛

  • Drop support for Python 3.9(:pr:3098):3.2.0 起最低支持 Python 3.10;
  • 移除此前已弃用的代码(:pr:3099):其中明确删除了 OrderedMultiDict 与 ImmutableOrderedMultiDict——因为底层 MultiDict 本身已保持插入顺序,有序变体不再有意义(对应 3.1.0 的弃用声明);
  • 最低依赖版本提升:MarkupSafe 3.0.3、Watchdog 6.0。

2.2 数据结构与类型体系收紧

3.2.0 对 werkzeug.datastructures 做了系统性的类型重构,这是理解本版本的关键:

  • ImmutableList/ImmutableListMixin 弃用:Accept 改为继承 Sequence,类型标注请改用 tuple、Sequence、MutableSequence;
  • ImmutableDict/ImmutableDictMixin 弃用:改用 Mapping 与 MutableMapping;
  • UpdateDictMixin 弃用:改用 CallbackDict;
  • TypeConversionDict/ImmutableTypeConversionDict 弃用:带类型转换的 get 仍然保留在 MultiDict 与 ImmutableMultiDict 上;
  • RequestCacheControl/ResponseCacheControl 改继承 Mapping/MutableMapping(不再继承 ImmutableDict/dict);
  • cache_control_property 函数与两个类的 cache_property 方法弃用:未知指令请用索引访问 cc[key];
  • 向这两个类传可迭代对象已弃用:请传 mapping(parse_dict_header 的返回值及 from_header 方法的输入正是 mapping)。

一个值得注意的行为变化:Request.parameter_storage_class、dict_storage_class、list_storage_class 属性,以及 parse_cookie、parse_form_data、FormDataParser 的 cls 参数全部弃用。Request.form、files、args、cookies 将恒为 ImmutableMultiDict,Request.access_route 恒为 Sequence。原因在变更记录里写得很清楚:"这些此前允许被覆写以提供有序数据结构,但 Python 的 dict 现在已保证顺序"(:pr:3169)。在源码中可见其实现痕迹:src/werkzeug/wrappers/request.py 里 _get_form 等方法仍保留了对 parameter_storage_class 的兼容分支,但会触发 DeprecationWarning,并注明"将在 Werkzeug 3.3 中移除,将恒为 ImmutableMultiDict"。

2.3 结构化 Header 的统一入口:from_header / to_header

3.2.0 一个极具指导意义的架构变更(:pr:3116):werkzeug.datastructures 中所有结构化 header 类都增加了 from_header 类方法与 to_header 方法,相应地 werkzeug.http 中一批解析函数被弃用:

  • dump_csp_header
  • parse_accept_header
  • parse_cache_control_header
  • parse_content_range_header
  • parse_csp_header
  • parse_etags
  • parse_if_range_header
  • parse_range_header
  • parse_set_header

变更记录给出的理由直指设计动机:"改善静态类型,并减少循环导入"。这与 2.3.0 中 Authorization/WWWAuthenticate 引入 from_header 的路径一脉相承——Werkzeug 正在把"解析函数 + 数据结构"的二元 API 收敛为"结构类自包含解析与序列化"的单一入口。

配套行为变化还有:

  • 空 ContentRange 视为 false,units 恒为字符串,构造参数带默认值;set/unset 方法弃用,改为直接设置/删除 response.content_range;
  • HTTP_STATUS_CODES 弃用,改用 Python 内置 http.HTTPStatus;原因短语从大写改为更常见的标题大小写(:pr:3139)。

2.4 Request/Response 属性的清理与安全强化

一批长期闲置或已被规范废弃的 header 属性被弃用:

  • Request/Response 的 content_md5(:pr:3158)、Request.pragma(:pr:3160)、Request.accept_charsets 与 CharsetAccept 类(:pr:3161);
  • UserAgent 类与 Request.user_agent_class 弃用(:issue:3271):Request.user_agent 现在就是字符串,需要时可直接自行解析;
  • environ_property 函数及 Request.input_stream、remote_user、is_multithread、is_multiprocess、is_run_once 属性弃用(:issue:3275):直接访问 request.environ;
  • testapp 模块及其 test_app 弃用;
  • Request.autocorrect_location_header 属性弃用(:issue:3247):需要绝对 URL 时直接设置 response.location。

CSP 指令侧同步更新:prefetch_src、navigate_to、plugin_types 三个属性弃用(:pr:3114,对应指令已从规范中弃用或移除),同时新增了 required_trusted_types_for、trusted_types、upgrade_insecure_requests 指令的属性支持。

2.5 redirect 默认行为变更:302 → 303

这是一个对应用行为有直接影响的 breaking change(:pr:3092):werkzeug.utils.redirect 的默认状态码从 302 改为 303。其语义是:303 告诉客户端"无论如何都切换为 GET",而 302 在旧客户端实现中只把 POST 切为 GET、其他方法保持不变。

源码佐证清晰可见:src/werkzeug/utils.py 中 def redirect(location: str, code: int = 303, ...),其 docstring 完整说明了各状态码语义:303 See Other 始终用 GET;307 Temporary Redirect 保留当前方法;308 Permanent Redirect 保留方法且永久生效;302/301 因客户端实现不一致而被 307/308 取代。变更记录补充说明:这保留了 GET 与 POST 重定向的既有行为,同时正确适配了 HTMX 等前端库。

配套的测试客户端行为同步调整(均为 :pr:3092):

  • 重定向切换为 GET 时,清理更多请求体信息;
  • 仅当原请求是 POST 时,测试客户端才把 301/302 切换为 GET;
  • 305 不再被当作重定向处理(已从 HTTP 规范中移除);
  • EnvironBuilder.close 关闭 files 中每个键的全部文件(此前只关第一个);
  • EnvironBuilder 可作为 with 上下文管理器使用(:pr:3101)——源码中 __enter__/__exit__ 已实现,close 关闭所有文件;EnvironBuilder.files.add_file 在传入 IO 对象时会自动探测文件名,新增 files.close 方法,且 files.clear 会调用 close。

2.6 路由、URL 转换器与 multipart 解析

  • Map 新增 subdomain_matching 参数(:issue:3005):可关闭子域匹配;bind_to_environ 在启用 host_matching 时忽略 server_name;设置了 default_subdomain 时,无法确定子域就使用它。源码 src/werkzeug/routing/map.py 中 subdomain_matching: bool = True,且 self.subdomain_matching = subdomain_matching and not host_matching——子域匹配默认开启、但与 host_matching 互斥,二者不可同时生效;
  • Map.bind_to_environ 传入 Request 对象时校验 host 是否在 request.trusted_hosts 中,非法 host 返回 400(:issue:3007);
  • 新增 DuplicateRuleError:向 Map 添加与既有 rule 相等的 rule 时抛出(:issue:3037),定义在 src/werkzeug/routing/exceptions.py;
  • int/float URL 转换器不再接受非 ASCII 数字;to_url(构建 URL)时进行校验;int 转换器的 fixed_digits 不再把负号计入位数;float 转换器拒绝溢出到 inf 的值、也不产生科学计数法/inf/nan(:issue:3242、:issue:3146)。源码 src/werkzeug/routing/converters.py 中 IntConverter.to_url 会先 int(value) 再校验 signed/min/max/fixed_digits 宽度,FloatConverter 校验 math.isfinite;
  • multipart 解析失败时关闭已解析的文件,避免 ResourceWarning;SpooledTemporaryFile 恒用于 multipart 文件解析(:pr:3101)。

2.7 其他 3.2.0 亮点

  • Request.sec_fetch_site、sec_fetch_mode、sec_fetch_user、sec_fetch_dest 四个 header 属性新增(:pr:3082);
  • Response.make_conditional 即使不是可满足的 range 请求也会设置 Accept-Ranges(:issue:3108);
  • Request.host、get_host、host_is_trusted 校验字符合法性,空值不再允许,忽略 Unix socket 地址,host_is_trusted 的 trusted_list 参数变为可选(:pr:3113);
  • 开发服务器不再额外发送 100 Continue 响应(Python 基础服务器已发送);
  • Request.if_range 遇到无效弱 ETag 时丢弃该 header(:pr:3163);
  • ETag 与调试器 PIN 改用 SHA3-256(替代 SHA-1,后者在 FIPS 140 下不可用),可能导致缓存失效因为 ETag 值变化(:pr:3164);
  • generate_password_hash 用 secrets.token_urlsafe 生成盐,移除私有 gen_salt 方法(:pr:3167);
  • 测试 Client 新增 query 方法,对应 QUERY 请求方法(src/werkzeug/test.py 中 def query(self, *args, **kw) -> TestResponse);
  • unquote_etag 与 ETags.from_header 丢弃无效的未加引号值;
  • cached_property 在尚未访问缓存时也可被删除;
  • Request 的 header 属性加缓存,后续访问跳过重复解析;
  • Response 的 header 属性可设为 None 来删除该 header。

三、3.1.x 系列:稳定期的小步快跑与安全加固

3.1.x 是 2024 年底到 2026 年初的稳定维护系列,条目多为行为修正与安全补丁,非常适合用来理解"小版本里藏着的坑"。

3.1.0(2024-10-31):最后一个特性型小版本

  • Drop Python 3.8 支持,并移除先前已弃用代码(:pr:2966/2967);
  • Request.max_form_memory_size 默认从无限改为 500kB(:issue:2964):非文件表单字段超过该大小将触发 RequestEntityTooLarge。源码佐证:src/werkzeug/wrappers/request.py 中 max_form_memory_size: int | None = 500_000,注释说明文件部分不受此限(达到上限移入磁盘);
  • cache_control 属性行为大幅调整(:issue:2980 等):字典值恒为 str | None;max_age 无值时返回 None(不再是 -1);no_cache 在请求侧为布尔(存在即为 True,不再是 "*"),响应侧仍为字符串;max_stale/min_fresh/private 无值时返回 True/None(不再 "*");no_transform 修正为布尔;新增 must_understand、stale_while_revalidate、stale_if_error 属性;
  • Cookie CHIPS(Partitioned Cookies)支持(:issue:2797);
  • 新增 421 MisdirectedRequest HTTP 异常(:issue:2850);
  • PBKDF2 默认工作因子提升到 1,000,000 次迭代(:issue:2969);
  • datastructures 内联类型注解,移除 stub 文件(:issue:2970);
  • MultiDict.getlist 类型转换时同时捕获 TypeError 与 ValueError(:issue:2976);
  • 为 MultiDict、Headers、CallbackDict 实现 | 与 |= 运算符,不可变类型禁用 |=(:issue:2977)。

3.1.1~3.1.4:定向修复

  • 3.1.1:修复 str(Request.headers) 恒为空的问题(:issue:2985);
  • 3.1.2:TypeConversionDict.get 的 type 参数允许 callable;Headers 不再继承 MutableMapping(不完全匹配该接口,:issue:2989);
  • 3.1.3:MultiDict 传多值仅接受 list/tuple/set(此前改为接受任意 Collection,但会误伤 bytes 等单值类型);Host 头缺失且回退到 SERVER_NAME 时,IPv6 地址会被 [] 包裹以匹配 Host 头格式(:issue:2993);
  • 3.1.4(2025-11-28):Windows 上 safe_join 禁止特殊设备名(防止经 send_from_directory 读取,secure_filename 早已阻止写入,:ghsa:hgf8-39v-g3f2);调试器 PIN 在 10 次失败后锁定(而非 11 次);multipart 解析器处理块边界处的 \r\n;Watchdog reloader 降低 CPU 占用;Request.json 注解更精确;HTTPException.get_response 的注解与文档更清晰地区分 WSGI 与 sans-IO 响应。

3.1.5~3.1.9:安全补丁与性能

  • 3.1.5(2026-01-08):safe_join 在 Windows 上禁止更多特殊设备名(:ghsa:87hc-h4r5-73f7);multipart 解析器正确拆分块边界处的 \r\n(修复上一版导致的错误 content length);修复 DebuggedApplication(pin_security=False) 的 AttributeError;
  • 3.1.6:Windows safe_join 多段路径中的设备名(:ghsa:29vq-49wr-vm6x);
  • 3.1.7:parse_list_header 保留部分引用的条目、丢弃空条目、未闭合引用返回空;WWWAuthenticate.to_header 无参数时不产生尾随空格;Transfer-Encoding 按集合解析;host 相关校验与 Unix socket 处理(同 3.2.0 条目,:pr:3113);merge_slashes 合并任意数量的连续斜杠;
  • 3.1.8(2026-04-02):Request.host/get_host 在 header 缺失或含非法字符时返回空字符串;
  • 3.1.9(Unreleased):ProfilerMiddleware 在 Python 3.15 上使用 profiling.tracing;uri_to_iri/iri_to_uri 保留空的用户名、密码与 0 端口;parse_options_header/parse_etags/parse_cookie 性能改进;get_host 校验端口范围;int 转换器超长值时返回 404 而非 500;调试器 PIN 在 Podman 的 cgroup 数据下生成更可靠;basic auth 解析拒绝非 base64 字符;application/x-www-form-urlencoded 表单数据不再受 max_form_memory_size 限制(仅受 max_content_length);LimitedStream.readinto 少读时不再调整缓冲区;10+ 转换器单段规则正确赋值;非法 Range 后缀长度 -0 不再被接受。

四、3.0 系列:Python 版本门槛与安全基线确立

3.0.x 集中体现了"破坏性大版本 + 安全补丁维护"的节奏:

  • 3.0.0(2023-09-30):移除先前已弃用代码;弃用 __version__ 属性(改用特性检测或 importlib.metadata.version("werkzeug"));generate_password_hash 默认算法改为 scrypt(:issue:2769);ProfilerMiddleware 的 filename_format 函数可收到 "werkzeug.profiler" environ 键(含 elapsed/time);显式将 PathConverter 标记为非 path isolating;
  • 3.0.1(2023-10-24):修复大 multipart 解析缓慢问题,潜在 DoS 修复;
  • 3.0.2:merge_slashes=False 时重复斜杠请求对单斜杠路由返回 NotFound;TypeConversionDict.get() 的 TypeError 处理与 ValueError 对齐;converter 参数无法解析时抛错;
  • 3.0.3(2024-05-05):开发服务器仅允许 localhost、.localhost、127.0.0.1 或指定主机名发起调试器请求(:ghsa:2g68-c3qc-8985);reloader 对 sys.path 中的 "" 更健壮;adhoc 开发证书 TLS 格式改进;Rule.endpoint 类型注解改为 Any;
  • 3.0.4:multipart/x-www-form-urlencoded 含非法 UTF-8 字节时恢复为"不解析出表单数据"而非 413;调试器 PIN 认证跨线程/进程同步失败计数;开发服务器处理 Python < 3.13 的 SSLEOFError;
  • 3.0.5:Watchdog reloader 忽略"关闭但未写入"事件;IPv6 scope 地址日志;忽略无效 authorization 参数;SharedDataMiddleware 类型注解改进;Python 3.13 下 UID 无关联名称时的调试器 PIN 兼容;
  • 3.0.6(2024-10-25):max_form_memory_size 应用于大非文件字段的解析方式修复(:ghsa:q34m-jh98-gwm2);Windows safe_join 补充 Python < 3.11 的 ntpath.isabs 遗漏路径(:ghsa:f9vj-2wh5-fj8j)。

五、2.x 时代:sans-IO 重构、状态机路由与性能工程

2.x 是架构性变化最密集的时期,理解这段历史有助于把握当前代码结构(sansio/、routing/matcher.py 等目录的存在都源于此)。

5.1 2.0(2021-05-11):告别 Python 2

  • Drop Python 2 与 3.5 支持(:pr:1693);
  • 弃用 format_string、bind_arguments/validate_arguments、HTMLBuilder、escape/unescape(改用 MarkupSafe)、python -m werkzeug.serving CLI、environ["werkzeug.server.shutdown"]、useragents 模块与内置 UA 解析器(建议子类化 user_agent.UserAgent 并设置 Request.user_agent_class);
  • 所有 datetime 值均带 tzinfo=timezone.utc,涉及 http.parse_date 的全部属性(Request.date/if_modified_since/if_unmodified_since、Response.date/expires/last_modified/retry_after 等);
  • Request/Response mixin 全部合并进单一类,BaseRequest/BaseResponse 的 isinstance 检查会告警;
  • JSON 支持不再依赖 simplejson(通过 Request.json_module/Response.json_module 覆写);Response.get_json() 不再缓存结果;
  • Response.freeze() 未设置 ETag 时自动生成;
  • send_file/send_from_directory 从 Flask 移植而来,download_name 替代 Flask 的 attachment_filename;send_file 默认 conditional=True、max_age=None;
  • generate_password_hash 默认 PBKDF2 迭代从 150000 提至 260000,盐长从 8 增至 16,用 secrets 生成盐;
  • 新增 sans-IO 的 Request/Response 基类(非公开 API,为 ASGI 框架铺路);Local 在 Python 3.7+ 用 ContextVar 替代 threading.local;
  • request.values 不再包含 GET 请求的 form(防止坏缓存代理缓存表单数据)。

5.2 2.1(2022-03-28):本地上下文与现代 HTTP

  • 要求 gevent/eventlet 配套 greenlet>=1.0 或 PyPy>=7.3.7;
  • 移除非标准的 werkzeug.server.shutdown、user_agent 解析器内建、python -m werkzeug.serving CLI、locals.get_ident、cookie_date、pbkdf2_hex/pbkdf2_bin/safe_str_cmp(改用 hashlib/hmac)、Href、HTMLBuilder、invalidate_cached_property(改用 del obj.attr)等;
  • 开发服务器升级为 HTTP/1.1:启用 keep-alive 与 chunked 流式响应(threaded/processes 开启时),流式响应使用 Transfer-Encoding: chunked;
  • cached_property 支持 __slots__(配合 _cache_{name} 槽位);
  • TestResponse.text 快捷属性;append_slash_redirect 默认状态码改为 308(保留请求体);Response.autocorrect_location_header 默认关闭(Location 保持相对路径);Request.get_json() 对非 application/json 的 Content-Type 抛 400;
  • run_simple 对 "address already in use" 给出处理指引。

5.3 2.2(2022-07-23):MarkupSafe、状态机路由与调试器上下文

  • 加入 MarkupSafe 依赖,渲染 HTML 时用它转义(:issue:2419);
  • 新增基于状态机的更快 URL 匹配路由器(:pr:2433):自定义 converter 若需匹配 / 必须设置 part_isolating = False(matcher.py 中 StateMachineMatcher 即此产物);
  • 新增 werkzeug.debug.preserve_context 机制:调试控制台执行代码时恢复请求的上下文局部数据;
  • options header 中的名称统一小写(符合 RFC 6266);AnyConverter 构建 URL 时校验值;
  • 新增 sans-IO 的 is_resource_modified、parse_cookie、get_content_length;
  • 2.2.3(2023-02-14):multipart 部分数上限默认 1000,超出抛 RequestEntityTooLarge,缓解 DoS。

5.4 2.3(2023-04-25):性能与 header 重构

  • Drop Python 3.7;pyproject.toml 取代 setup.cfg;
  • **全面弃用"传 bytes 当字符串"**及大量 charset/errors 参数——这是 Python 2 到 3 过渡的历史遗留,移除可省去大量实例检查与编码开销;
  • werkzeug.urls 模块弃用(保留 uri_to_iri/iri_to_uri),改用 urllib.parse;
  • Authorization/WWWAuthenticate 重构(:issue:1769、:pr:2619):两个类都有 type/parameters/token 属性(token 支持 Bearer 这类单 token 方案);不再是 dict 但仍支持 auth[key]、auth.key、auth.get、key in auth;都有 from_header 类方法(parse_authorization_header/parse_www_authenticate_header 弃用);set_basic/set_digest 弃用;可给 response.www_authenticate 赋实例列表以设置多个 header 值;
  • parse_cookie/dump_cookie 重构:性能提升最多 40%/60%;dump_cookie 默认不再多余设置 path="/";
  • 测试客户端 cookie 实现重构:弃用 cookie_jar,不再用 http.cookiejar;发送请求 cookie 时做 domain/path 匹配(默认 localhost 与 /);新增 get_cookie 方法;set_cookie/delete_cookie 的首个位置参数 server_name 弃用,改用 domain;
  • Request.get_json() 对非 application/json 抛 415(而非 400);
  • converter 的 part_isolating 在其 regex 含 / 时默认 False;自定义 converter 的 regex 可以含捕获组而不破坏路由;
  • parse_options_header 提速 2-3 倍并符合 RFC 9110;parse_accept_header 按 RFC 9110 解析、丢弃非法 q 值;
  • generate_password_hash 支持 scrypt;PBKDF2 默认迭代升至 600,000;明文 hash 方法弃用,仅支持 scrypt 与 pbkdf2;
  • 开发服务器(明确标注不可用于生产)会排空请求流至 10GB 或 1000 次读取,使客户端能看到 413 而非 connection reset;丢弃含下划线的 header 键;URL 百分号编码必须始终表示 UTF-8 字节;Request.charset/Response.charset/Client.charset 弃用;
  • max_content_length 在访问流时立即检查、读取流时持续检查(:issue:1513)。

六、1.0 与 0.16:模块化清理的转折点

  • 0.16.0(2019-09-19):弃用 werkzeug 顶层的大多数属性,改为直接子模块导入(如 from werkzeug.urls import url_quote),1.0 移除;
  • 1.0.0(2020-02-06):Drop Python 3.4;移除 0.15 中发出弃用警告的代码;移除大多数顶层属性;请求 cookie 解析为 MultiDict(同名 cookie 全保留,cookies[key] 取第一个,getlist 取全部);InternalServerError 增加 original_exception 属性;Header 相等性比较忽略大小写;CSP header 通过 Response.content_security_policy 数据结构支持;LanguageAccept 支持 "en" 与 "en-US" 回退匹配;MIMEAccept 按 MIME 参数计算特异度;response.cache_control.immutable 标志(浏览器支持仍实验性);429/503 异常支持 retry_after 参数;Map/Rule 新增默认开启的 merge_slashes;新增多个状态码(103、208、306、425、506、508、511);Headers 增加 update/setlist/setlistdefault;WebSocket 规则匹配与构建支持;SharedDataMiddleware 默认 fallback_mimetype 改为 application/octet-stream。

七、0.9~0.15:路由、测试客户端与调试器的成型期

这一阶段(2013-2019)塑造了 Werkzeug 至今的核心面貌:

  • 0.9:LimitedStream.tell 支持;SSL 接口改进与证书自动生成;generate_password_hash 支持任意 hashlib 算法;PBKDF2 支持;safe_join 诞生;If-Range/Range/Content-Range 解析支持;HTTP 异常描述默认转义;CGIRootFix 命名(原 LighttpdCGIRootFix);
  • 0.10:用标准库 ssl 替代 OpenSSL;UUID converter;新增 504/505 异常;reloader 跟踪新增文件;PBKDF2 用 stdlib hmac 实现;MIMEAccept 正确处理 mimetype 参数;Accept 将 q=0 视为不可接受;MapAdapter.match 区分 / 与空路径;
  • 0.11:调试器引入 PIN 认证(防止在生产环境误开调试器);reloader_paths 选项;许多自定义 cached_property 变为 property 子类;BuildError 提供完整句子与建议;caches 新增可选 has 方法;
  • 0.12:response.age 改为 timedelta;cookie 超过默认 4093 字节抛异常(max_cookie_size 属性与 dump_cookie 的 max_size 参数可配置);SharedDataMiddleware 接受列表以保留查找顺序;开发服务器支持 chunked 请求;
  • 0.13:弃用 Python 2.6/3.3;Authorization.qop 为字符串(符合 RFC 2617);
  • 0.14:HTTP 异常被 Request.application 自动捕获;SameSite cookie 属性支持;werkzeug.wsgi.ProxyMiddleware;
  • 0.15.0(2019-03-19):URL 构建提速约 7 倍(每个 Rule 编译自己的构建函数);MapAdapter.build 支持 MultiDict 多值;path_info 默认 /;RequestRedirect 从 301 改为 308(保留动词与请求体);int/float converter 支持 signed=True(如 /jump/<int(signed=True):count>);Unauthorized 增加 www_authenticate 参数;新增 424 FailedDependency;parse_options_header 理解 RFC 2231 参数续行;PBKDF2 迭代 150000;contrib 模块大规模弃用/迁移(LintMiddleware→werkzeug.middleware.lint、ProfilerMiddleware→werkzeug.middleware.profiler、ProxyFix→werkzeug.middleware.proxy_fix、cache 拆分为 cachelib、securecookie/sessions 拆分为 secure-cookie、atom 弃用、jsrouting/limiter/testtools 移除);ProxyFix 重构(逐 header 配置信任的代理数,num_proxies 弃用;新增 X-Forwarded-Port/X-Forwarded-Prefix 支持;原始环境值存于 werkzeug.proxy_fix.orig);wsgi.get_host 不再读 X-Forwarded-For;测试客户端 redirect 处理重写(HEAD 不转 GET、307/308 保留方法与体、307 保留原方法);EnvironBuilder/Client 支持 json 参数。

八、0.1~0.8:WSGI 工具集的奠基

早期版本确立了大量沿用至今的基础设施:

  • 0.1(2007-12-09):初始发布(代号 Wictorinoxger);
  • 0.2:AnyConverter;securecookie;异常 get_response();DispatcherMiddleware;cached_property(原名 lazy_property);dump_cookie/parse_cookie;import_string;BaseResponse.freeze;werkzeug.script;
  • 0.3:Authorization/WWWAuthenticate;parse_list_header/parse_dict_header/parse_authorization_header/parse_www_authenticate_header;parse_form_data;MultiDict 家族抛 BadRequest 子类的特殊 KeyError;run_simple 的 use_debugger/use_evalex 参数;"shallow" request 概念;
  • 0.4:BaseResponse.make_conditional 恒返回 self;CacheControl.no_cache/private 行为调整;304 响应自动移除实体头;Headers 支持切片与索引;
  • 0.5:MIMEAccept/CharsetAccept;自研服务器替代 wsgiref;Client 支持 cookie;is_hop_by_hop_header 等函数;LimitedStream 移入主包并默认抛异常;实验性 multipart 解析器;dump_options_header/parse_options_header;EnvironBuilder 统一了 create_environ/Client/from_values;secure_filename;passthrough_errors;
  • 0.6:OrderedMultiDict;SSL 支持;MapAdapter.match 的 return_rule 参数;FileStorage 暴露 multipart 头;mimetype/mimetype_params 属性;HEAD 在含 GET 时隐式加入路由方法;BaseRequest.url_charset;
  • 0.7:host 匹配;safe_join 加入 security 模块;PATCH 方法(RFC 5789);If-Range/Range/Content-Range 解析支持;import_string 错误信息改进;开发服务器默认解析出 URL 参数用于重定向;
  • 0.8:通用 BadRequestKeyError;_load_form_data 文档化;自动设置 Content-Length;路由 server 名小写化;ProxyFix 基于 X-Forwarded-Proto 更新 wsgi.url_scheme;autocorrect_location_header/automatically_set_content_length 控制开关;Headers 禁止值内换行(防 header 注入);流式 URL 解码降低大表单内存占用。

九、贯穿始终的三大主线

通读全部版本后,可以提炼出三条清晰的技术主线:

  1. 安全优先:从 0.8 的 header 注入防护、0.11 的调试器 PIN、0.15 的 ProxyFix 安全默认值,到 3.x 系列密集的 GHSA 安全补丁(Windows 特殊设备名、multipart DoS、调试器主机白名单、SHA3-256 替代 SHA-1),安全始终是变更记录的高频主题;
  2. 类型注解与 API 收敛:从 2.0 的 py.typed、2.1 的内联注解,到 3.2.0 大规模弃用可变数据结构、统一 from_header/to_header 入口,Werkzeug 持续向"类型友好"演进;
  3. sans-IO 架构:2.0 提取 sans-IO 基类 → 2.2 新增 sans-IO 解析函数 → 3.x 继续深化,为 ASGI 生态复用 Werkzeug 的 HTTP 语义铺路——当前仓库中 src/werkzeug/sansio 目录(含 http.py、request.py、response.py、multipart.py)正是这一路线的实体化成果,配套测试位于 tests/sansio。

十、如何把这份变更史用起来

  • 升级前:从当前版本到目标版本逐段阅读,重点关注"移除先前已弃用的代码"与"行为变化"条目(如 3.2.0 的 redirect 302→303、3.1.0 的 max_form_memory_size 默认值);
  • 排查行为差异:Request.host 校验、cache_control 属性语义、测试客户端重定向规则这类"隐性行为变化"最容易在升级后引发问题,可对照 tests 下的 test_wrappers.py、test_http.py、test_test.py、test_routing.py 等验证预期行为;
  • 追踪安全修复:检索 CHANGES.rst 中的 :ghsa: 引用,核对你的部署是否受影响的组件(multipart 解析、safe_join、调试器、开发服务器);
  • 把握 API 生命周期:某个 API 的"新增→弃用→移除"通常横跨 2-3 个版本,据此规划你的代码迁移窗口期。

综上,CHANGES.rst 不仅是一份发布日志,更是 Werkzeug 的设计决策史:它记录了为什么 redirect 默认 303、为什么 MultiDict 恒为不可变、为什么 ETag 改用 SHA3-256。对任何使用 Werkzeug(尤其是经由 Flask 间接使用)的开发者而言,这份文件都值得作为常备的升级参考手册。

登录后查看全文
werkzeug