一个越来越难用的防火墙

如果你用过 Cloudflare 的防火墙，你可能经历过这样的困境：想同时根据 IP 和 URI 拦截某个请求，发现做不到。想说"来自某个 AS 号、且访问路径包含 /wp-admin"的请求才拦截，也做不到。

这不是功能没有，而是架构本身的限制。这篇博客完整讲述了 Cloudflare 是如何一步步从"每个维度单独一套规则"演进到"支持任意组合的表达式防火墙"的，以及为什么最终选择用 Rust 来构建核心匹配引擎。

原文博客: https://blog.cloudflare.com/how-we-made-firewall-rules/

旧系统是怎么工作的

Cloudflare 最早的防火墙能力非常原始：只能针对 IP 地址进行封禁。

if request IP equals 203.0.113.1 then block

随着需求增加，逐渐加入了 CIDR 范围、ASN、国家、User Agent、URI 匹配，还有 Rate Limiting、Zone Lockdown 等功能。但这些功能在实现层面是相互独立的，每一个都只处理单一维度。

到 2017 年，这个防火墙的能力可以被一句话总结：

你可以按任何条件拦截流量，前提是你只挑一个条件。

这些规则在实现上分为两类：

Lookup 匹配：针对 IP、CIDR、ASN、国家、User Agent 这类字段，构造一个 KV 键（比如 zone:www.example.com_ip:203.0.113.1）去全局分布式存储里查。O(1) 复杂度，性能极好，但只能查单一字段的值。如果要组合两个字段，就需要把所有可能的组合都写进 KV，键的数量会爆炸。

正则匹配：针对 URI 的 Page Rules，把所有规则合并成一个大正则：

^(?<block__1>(?:.*/wp-admin/index.php))|(?<block__2>(?:.*/xmlrpc.php))$

正则的命名捕获组被用来编码动作类型。这个方案在 URI 匹配场景下出乎意料地好用，但一旦要同时匹配 URI 加 IP 范围，就没有自然的扩展方式。

灵感：Wireshark

工程师们很早就意识到，新方案的核心应该是一个表达式语言。最初的方案是用 JSON 来表达 DSL：

{
  "And": [
    { "Equals": { "host": "www.example.com" } },
    { "Or": [
      { "Regex": { "path": "^(?:.*/wp-admin/index.php)$" } },
      { "Regex": { "path": "^(?:.*/xmlrpc.php)$" } }
    ]}
  ]
}

计算机处理没问题，但人看起来费力。在把这个 JSON 翻译成"人类语言"时，工程师意识到这个结构非常眼熟——这不就是 Wireshark 的过滤器语法吗？

Wireshark 是网络协议分析工具，它的 Display Filter 语法长这样：

http.host eq "www.example.com" and (http.request.path ~ "wp-admin" or http.request.path ~ "xmlrpc.php")

简洁，人类可读，机器可解析，而且对安全工程师来说几乎零学习成本——他们每天排查攻击时就在用 Wireshark。

Cloudflare 决定借鉴这套语法，但不做 Wireshark 那样的离线数据包分析。他们要的是实时过滤：HTTP 请求进来，毫秒内判断是否匹配，给出处理动作。

核心引擎：wirefilter

基于这个思路，Cloudflare 用 Rust 实现了一个名为 wirefilter 的库（名字向 Wireshark 致敬）。

它做几件事：

• 定义字段及其类型，比如 ip.src 是 IP 类型，http.host 是字符串类型
• 给定一张请求属性表（由 HTTP 服务器填充）
• 解析和校验表达式语法，检查字段名是否合法、操作符是否适用于该字段类型
• 将表达式应用到请求属性表，返回 true/false

请求属性表的字段覆盖了一条 HTTP 请求的完整信息：

wirefilter 被集成到了两个地方：用 Go 写的 REST API（负责校验用户输入的表达式），以及用 Lua 写的边缘代理（负责在请求进来时实际执行匹配）。

Go 侧的集成大致是这样：

var scheme = filterexpr.Scheme{
    "http.host":             filterexpr.TypeString,
    "http.request.uri":      filterexpr.TypeString,
    "ip.src":                filterexpr.TypeIP,
    "ip.geoip.country":      filterexpr.TypeString,
    "ssl":                   filterexpr.TypeBool,
}

expressionHash, err := filterexpr.ValidateFilter(scheme, expression)

Lua 侧则负责在每次请求时填充属性表，然后拿 wirefilter 来做实际的匹配。

为什么选 Rust

这个问题的答案比较直接：需要保证 API 侧和边缘代理侧的行为完全一致。

如果分别用 Go 和 Lua 各写一套实现，任何微小的差异都可能被攻击者利用——比如在 Go 侧判断为合法的规则，在 Lua 侧匹配逻辑略有不同，就可能绕过防火墙。

用一个共享库来封装匹配逻辑，Go 和 Lua 都通过 FFI 调用它，能从根本上消除这种不一致。

在候选语言里，C 和 C++ 有内存安全问题，Go 和 Lua 已经被排除（正是问题所在），JavaScript Worker 方案在性能和集成上有额外复杂度。Rust 在性能、内存安全、低内存占用、以及可以被其他产品复用（比如 Spectrum）这几个维度上综合表现最优。

规则优先级：一个云环境特有的问题

新系统支持复杂表达式后，随之而来的是一个新问题：怎么确定规则之间的执行顺序？

传统防火墙（iptables、家用路由器）用的是显式顺序：规则 1 到规则 N，匹配到第一条就停止。每次改动都重新发布全部规则，顺序是确定的。

但在云端这不可行。一个大客户可能有几十万条规则，每次改动都要重新发布全部规则代价太高，而且在分布式环境下，两条规则同时发布时可能出现竞态条件。

Cloudflare 的解决方案是 priority 值，是一个 int32，数字越小优先级越高。两条规则优先级相同时，再按动作类型排序：

1. Log（最高优先级）
2. Allow
3. Challenge（CAPTCHA）
4. JavaScript Challenge
5. Block（最低优先级）

这套设计有几个好处：

• 单条规则独立发布，发布速度不受规则总数影响
• 优先级不要求唯一，可以给一批规则设置相同的优先级值，起到分组的效果
• 如果你有一个已有的顺序化规则系统，可以直接把顺序号映射成 priority 值导入进来

字段命名的远见

注意到 wirefilter 的字段都有 http. 前缀了吗？这遵循了 Wireshark Display Filter Reference 的命名约定，而不只是一个风格习惯。

这意味着这套引擎从设计上就不是 HTTP 专属的。只要定义了对应协议的字段（比如 smtp.from、dns.query），同一套匹配引擎就可以用于 SMTP、DNS 或者 Layer 4 的流量过滤。Cloudflare 的 Spectrum 产品（支持任意 TCP/UDP 协议的代理）就是这套架构向前延伸的方向。

小结

这篇文章描述了一个典型的工程演进路径：从一堆各自独立、能用但不能组合的功能，到一套统一的、基于表达式的过滤引擎。

几个值得记住的设计决策：

把核心逻辑下沉为库，而不是在每个调用方分别实现。这是保证多语言环境下行为一致的唯一可靠手段，也是选 Rust 写 wirefilter 的直接动因。

表达式语言借鉴成熟工具的语法。Wireshark Display Filter 对安全工程师是零学习成本，从调查工具到防护工具的语法迁移是自然的。

云环境的顺序问题不能用传统方式解决。priority 值而非显式顺序，单条独立发布而非全量重发，是针对分布式环境做的专门设计。

字段命名是架构意图的一部分。http.host 而不只是 host，这个前缀埋下了未来扩展到其他协议的伏笔。

日常使用QClaw进行内容产出与素材整理时，多数使用者都会陷入一种共性困扰，系统给出的呈现形态总是随性散漫，无法贴合实际使用场景的规整需求。想要条理清晰的结构化内容，到手却是杂乱堆砌的零散文字，想要层次分明的规整版式，最终呈现的排版总是混乱无序。反复手动调整版式结构，会大量消耗时间与精力，原本用来提升效率的辅助工具，反而变成了额外的负担。其实这款工具本身具备极强的形态定制潜力，只是大部分使用者只停留在基础使用层面，没有深入摸索输出形态的调控逻辑。

长期深耕这类智能工具的实操摸索与应用沉淀后，会发现多数人对格式调控的理解都停留在浅层认知里。单纯在需求末尾简单标注版式要求，根本达不到精准定制的效果，系统要么直接忽略相关描述，要么过度解读给出偏离预期的内容形态。智能模型在接收需求指令时，会先完成整体语义拆解与逻辑梳理，默认通用化呈现模式适配所有模糊需求。通用化模板侧重普适性，不会贴合个人使用习惯与场景属性，这也是为什么同样的指令，不同人得到的成品质感天差地别。只有把版式细节、排布逻辑、呈现规范都梳理清楚，才能让输出效果稳定贴合预设方向。在日常文案梳理、素材汇总的场景里，层级化文本排布是使用率最高的需求，也是最容易出现错乱问题的环节。很多人只会笼统要求做出分层排版，最终成品常常出现层级颠倒、段落穿插、多余分层的问题，整体阅读逻辑被彻底打乱。想要规避这类问题，核心在于提前梳理好完整的排布框架，把每一层内容的定位、篇幅区间、衔接逻辑都清晰传递出去。明确整体开篇铺垫内容，再划分主体板块的排布顺序，每个板块内部再规划细分内容的呈现节奏，让模型清晰知晓每一部分的定位与作用，从根源上避免层级混乱的情况出现。

把控好基础框架之后，还能进一步细化文字排布的细节规范，控制单段内容的篇幅节奏与行文风格。柔和自然的行文语气，适配日常分享类素材，简洁凝练的表达调性，适合专业类梳理内容。提前界定好文字疏密与表达风格，生成的内容不需要二次润色调整，就能直接投入使用。成熟的使用者都会养成提前规划版式框架的习惯，不再依赖系统默认模式，让每一次产出都能直接匹配使用场景，省去反复修改调整的繁琐步骤。规整化汇总类内容创作中，规整行列排布的呈现形式有着不可替代的实用价值，也是很多使用者难以把控的板块。常常会遇到行列数量不符、内容错位排布、结构残缺的状况，反复重新生成依旧达不到理想效果。打造规整行列内容的关键，在于提前敲定核心归类维度，先梳理好需要展示的核心类目，确定横向与纵向的排布逻辑，再对应填充各类目下的具体信息。模糊的汇总需求只会让模型自主判断结构，自然容易出现各种偏差，清晰的类目界定才是稳定产出的核心前提。

面对结构相对复杂的多层级汇总素材，还可以搭建嵌套式排布形态，这类形态在多维度信息梳理中作用显著。复杂排布模式对指令精准度要求更高，需要清晰划分主体区域与附属区域的对应关系，明确每一处嵌套位置的展示方向与信息类型。只要指令逻辑足够清晰，就能实现多层级规整呈现，满足深度信息梳理的需求，这也是普通简易工具很难做到的优势所在。文本类规整产出之外，结构化素材整理也是高频应用方向，这类内容同样需要严格把控外在呈现样式。不少时候整体内容逻辑没有问题，但排布疏密、段落间距、行文节奏杂乱，会大幅降低阅读观感。调控这类呈现效果，需要提前设定好基础排布规范，统一整体的疏密节奏，理顺段落之间的衔接节奏，让整体观感协调统一。规范好外在形态之后，成品的规整度与可读性都会大幅提升，后续使用时可以直接复用，不用再花费时间做格式优化。

各类基础版式之外，日常素材整理还会用到分段罗列、引用标注、间隔分区等辅助呈现样式，这些细节元素同样有着对应的调控逻辑。所有形态定制的核心逻辑保持一致，都是用具象清晰的描述，替代笼统模糊的需求表达。想要有序罗列内容，就明确标注排布标识与条目数量，想要凸显重点内容，就界定好专属呈现样式，让每一处细节需求都能被精准捕捉。很多人容易忽略一个关键要点，形态定制可以和内容创作需求融合在一起，同一组指令中既能界定创作主题与核心方向，也能同步规划全程排布样式。按照使用顺序规划开篇铺垫、中间主体、末尾总结的排布结构，搭配对应的版式规范，模型就会按照预设流程依次产出完整内容，全程无需人工介入调整，完整实现一站式规整产出。

长期高频使用的各类版式框架，都可以整理成固定套用模板，后续同类场景直接调取使用，不用每次都重新梳理定制指令。模板只需要锁定基础排布框架与核心规范，保留内容创作的灵活空间，既可以保证输出稳定性，又能适配不同主题的创作需求。过于僵硬的模板会限制内容自然度，留有适度弹性空间的框架，才能平衡规整性与文字质感，让成品不会显得生硬刻板。多轮连续的素材创作场景中，还可以依托上下文延续固定版式习惯，前期确定好整套呈现规范，后续同类创作就能自动沿用对应样式，不用重复标注格式需求。这种延续性适配能大幅简化操作流程，适合长期系统化产出的使用模式。同时需要分清指令优先级，临时调整的新式样指令，会优先覆盖过往延续的规范，灵活切换就能适配不同临时场景的定制需求。

多数人都会下意识觉得形态定制是一套复杂难懂的体系，需要钻研各类专业规范与专属逻辑，实际上整套操作都依托自然语言就能完成。不需要额外学习陌生规则，只需要摒弃笼统化表述，把心中预想的呈现模样，细致完整地描述出来。描述的细节越贴合自身使用习惯，最终成品的契合度就越高，所谓定制化掌控，本质就是精准传递自身的审美与使用需求。不同细节粒度的需求描述，最终呈现的成品质感有着天壤之别。只给出核心主题的模糊指令，成品散漫无序，几乎没有复用价值；补充基础版式要求后，整体框架趋于规整，但细节依旧存在瑕疵；完整梳理框架、篇幅、风格、排布的全维度需求，就能直接拿到可直接使用的成品。这一组明显的差异对比，足以说明指令细节度，才是决定最终产出质量的核心关键。

市面上很多使用者会感慨智能工具适配度不高，产出效果达不到预期，根源从来不在工具本身，而是需求传递的精准度不足。智能模型只能依托接收的指令完成创作，无法自主揣测使用者的隐性需求。掌握形态定制的核心思路之后，就能彻底摆脱被动接收默认成品的状态，主动掌控每一次产出的规整度与适配性。任何实用指令体系，都需要经过反复调试、校验、优化的过程，不存在一次就能完美适配所有场景的通用模板。每次产出完成后，对照实际使用需求梳理偏差之处，微调描述逻辑与细节规范，多次打磨之后，就能沉淀出适配个人使用习惯的专属指令。慢慢积累适配不同场景的定制方案，后续各类素材整理、内容创作工作，都能实现高效落地。

系统化沉淀各类定制方案之后，日常工作与素材整理的效率会得到明显提升，以往耗时很久的规整排版工作，现在只需要简单确定需求方向，就能拿到成型素材。看似简单的版式调控技巧，实则打通了智能工具与个人工作流程的适配通道，让辅助工具真正融入日常节奏，而不是单独存在的陌生程序。放眼整体应用领域，QClaw的定制化潜力还有很大挖掘空间，动态适配类排布、多样式融合呈现这类进阶方向，还在等待使用者慢慢探索打磨。根据内容属性自主微调版式结构，同一文档内融合多种规整样式，这些进阶玩法能进一步拓宽使用边界，适配更多复杂专业的产出场景。持续深耕实操细节，就能不断解锁新的使用方式，让工具价值发挥到极致。

所有智能辅助工具的熟练运用，都离不开持续实操摸索与经验总结，没有速成的捷径。只是单纯套用他人的方法，永远只能停留在基础使用阶段，结合自身场景不断测试、调整、感悟，才能真正吃透内在逻辑。慢慢摸清定制化输出的底层规律，就会发现规整化产出并不复杂，轻松就能打造专属自己的高效创作模式。

凌晨三点的办公室里，屏幕上的加载圈还在固执地转动，一份耗时两个多小时的全行业深度调研刚推进到三分之二，网络波动的弹窗毫无征兆地跳了出来。刷新页面的瞬间，所有进度烟消云散，只剩下空白的输入框和满屏的无力感。这是几乎所有深度使用智能工具的人都经历过的至暗时刻，长任务中断带来的不仅是时间的浪费，更是创作节奏的彻底打乱。很多人不知道的是，QClaw早已内置了完整的断点续传体系，只是绝大多数使用者都停留在“接着写”的原始阶段，白白浪费了这个能让工作效率翻倍的核心功能。绝大多数人处理长任务中断的方式，都是直接在新的输入框里敲下“接着上面的内容继续写”，然后祈祷系统能读懂自己的意思。这种做法的成功率不足三成，更多时候得到的是逻辑断裂的内容、重复的论述、甚至完全偏离主题的展开。系统无法凭空还原中断前的上下文状态，它不知道已经写了哪些内容，不知道哪些观点已经论证过，不知道原本的结构框架是什么，更不知道你想要的行文风格和细节要求。这种盲目的续传方式，本质上是把所有的判断压力都丢给了系统，最终的结果自然不尽如人意。

想要真正掌握断点续传的精髓，首先要理解它的底层运行逻辑。QClaw的断点续传从来不是简单的文本拼接，而是基于上下文状态的完整重建。系统在处理长任务时，会在内存中维护一个动态的状态快照，这个快照包含了任务的核心目标、已完成内容的逻辑脉络、未完成部分的执行计划以及所有的风格约束参数。当中断发生时，这个状态快照会随之消失，续传的本质就是手动重建这个状态快照，让系统回到中断前的那个精确的执行节点。很多人会犯的第一个错误，就是把已生成的全部内容原封不动地粘贴到新的输入框里，以为这样就能完整还原上下文。这种做法对于几千字以内的短任务或许有效，但对于上万字的长任务来说，只会导致上下文窗口溢出。系统的上下文承载能力是有限的，当输入的内容超过这个阈值时，它会自动丢弃最早的部分信息，最终导致对整体任务目标的理解出现偏差。正确的做法不是复制全部内容，而是提取已完成内容的核心逻辑骨架，用最精简的语言描述清楚已经写了什么。

提取逻辑骨架是断点续传中最关键的一步，也是最能体现使用者水平的一步。一个好的逻辑骨架应该包含三个核心部分：首先是任务的整体目标和结构框架，明确整个长任务分为哪几个大的板块，每个板块的核心内容是什么；其次是已完成部分的进度节点，精确到最后一个完整的逻辑段落，而不是最后一句话；最后是已论证的核心观点和关键论据，避免后续内容出现重复或者矛盾。把这三个部分用清晰的语言组织起来，就能用不到十分之一的篇幅，还原90%以上的上下文状态。在重建了基础的逻辑骨架之后，接下来需要补充原始任务的所有约束条件。很多人在续传时会忘记这一步，导致续传的内容在风格、篇幅、细节程度上和前面的内容出现明显的差异。原始任务的约束条件包括但不限于：整体的字数要求、每个板块的篇幅分配、行文的风格调性、专业术语的使用规范、数据的呈现方式、案例的选取标准等等。把这些约束条件明确地写在续传指令里，才能保证续传的内容和前面的内容保持高度的一致性。

完成了状态重建之后，不要急于要求系统一次性续传完剩下的所有内容。长任务之所以容易中断，就是因为执行时间过长，中间任何一点微小的波动都可能导致失败。正确的做法是采用增量续传的策略，把剩下的内容按照逻辑结构分成若干个独立的小块，一块一块地进行续传。每完成一个小块，就做一次状态同步，确认这部分内容符合要求之后，再继续下一个小块。这样即使中途再次中断，也只会损失当前小块的进度，而不会影响已经完成的部分。增量续传的块大小需要根据任务的性质来灵活调整，一般来说，每个块的内容控制在两千字左右比较合适。这个长度既能保证内容的完整性和连贯性，又能把单次执行时间控制在一个相对安全的范围内。对于逻辑联系特别紧密的内容，可以适当增大块的大小；对于相对独立的内容，则可以适当减小块的大小。通过这种分而治之的方式，可以把长任务的失败风险降到最低，同时也能让你在整个过程中保持对任务进度的掌控。

在进行每一次增量续传时，都需要在指令中明确当前块的内容范围和具体要求。不要只说“继续写下一部分”，而是要说“接下来写第三部分的第二小节，主要内容是分析市场竞争格局中的头部企业优势，重点对比三家企业的核心竞争力，每个企业的分析篇幅控制在三百字左右，延续前文的对比分析风格”。这种精确的指令能够让系统准确地知道自己接下来要做什么，从而生成符合预期的内容。很多人在续传过程中会遇到一个非常头疼的问题，就是衔接处的生硬感。前一段的最后一句话和后一段的第一句话之间明显脱节，读起来非常不流畅。解决这个问题的方法很简单，就是在续传指令中附上上一个块的最后两到三句话。系统会根据这几句话的语境，自然地过渡到接下来的内容，从而消除衔接处的断点痕迹。这个小小的技巧，能够让续传的内容看起来就像是一次性生成的一样，毫无破绽。

对于特别复杂的长任务，比如生成一本完整的电子书或者一份上百页的行业报告，最好的做法是在任务开始之前就预先设置好断点。在制定任务计划的时候，就把整个任务划分成若干个天然的断点，一般来说，每个大的章节结束的地方就是一个理想的断点。每完成一个章节，就主动保存一次当前的状态，包括这个章节的核心内容总结和下一个章节的执行计划。这样即使中途出现任何意外，都可以从最近的一个断点继续开始，而不会损失太多的进度。预先设置断点还有一个额外的好处，就是能够让你在长任务的执行过程中获得阶段性的成就感。长任务最容易让人放弃的原因，就是看不到即时的反馈，感觉遥遥无期。通过预先设置断点，把一个漫长的大任务分解成一个个清晰可见的小目标，每完成一个小目标就能获得一次正向反馈，从而保持持续的动力。这种任务管理的思维方式，不仅适用于智能工具的使用，也适用于所有类型的长期工作。

很多人以为断点续传只能在同一个会话中进行，一旦关闭了页面或者切换了设备，就只能重新开始。其实这是一个非常普遍的误解，QClaw完全支持跨会话甚至跨设备的断点续传。只要你能够准确地重建中断前的状态快照，无论是在电脑上还是在手机上，无论是在今天还是在一周之后，都可以无缝地继续之前的任务。这对于需要长时间跨度完成的长任务来说，是一个非常重要的功能。跨会话续传的关键在于状态的持久化保存。每次完成一个增量块之后，除了保存生成的内容之外，还要同步保存当前的状态信息。这些状态信息包括：整体任务的进度、已完成内容的逻辑骨架、下一个增量块的内容要求、所有的风格约束参数。把这些信息整理成一段简短的文字，保存在本地的文档里，下次需要续传的时候，只需要把这段文字粘贴到输入框里，就能立刻回到上次中断的地方。

续传完成之后，不要急着直接使用最终的内容，一定要进行一次全面的校验和整合。首先要通读全文，检查各个部分之间的逻辑是否连贯，有没有出现前后矛盾的地方；其次要检查所有的数据和论据是否准确一致，有没有出现重复或者遗漏；最后要检查整体的风格是否统一，有没有出现某个部分的语气和其他部分明显不同的情况。对于发现的问题，进行针对性的修改和调整，确保最终的成品质量。在进行内容校验的时候，要特别注意各个断点衔接处的内容。这些地方是最容易出现问题的，也是最能体现续传质量的地方。如果发现某个衔接处比较生硬，可以手动调整一下前后的语句，让过渡更加自然流畅。对于一些比较重要的长任务，甚至可以专门生成一段过渡文字，把前后两个部分无缝地连接起来。经过这样的打磨之后，没有人能看出来这份内容是经过多次断点续传生成的。

除了基础的文本续传之外，QClaw的断点续传体系还支持更加复杂的增量修改任务。很多时候，我们需要对已经生成的内容进行大规模的修改和调整，这个过程同样可能会中断。处理这种情况的方法和普通的续传类似，首先要明确已经修改了哪些部分，修改的方向和要求是什么，然后把剩下的修改任务分成若干个小块，逐个进行处理。这样可以避免因为一次修改过多内容而导致的中断和返工。对于同时处理多个长任务的使用者来说，建立一个完善的断点管理体系是非常有必要的。可以用一个专门的文档来记录所有正在进行的长任务的状态，包括任务名称、整体目标、当前进度、下一个断点的位置、以及所有的约束参数。每次完成一个断点的任务之后，就更新这个文档的状态。这样无论同时处理多少个任务，都能做到井井有条，不会出现混乱和遗忘的情况。

很多资深的使用者都会根据自己的工作习惯，总结出一套专属的断点续传模板。这些模板包含了状态重建、增量续传、风格保持等所有必要的元素，每次需要续传的时候，只需要把对应的信息填入模板中即可。使用模板不仅能够大幅提高续传的效率，还能保证每次续传的指令质量，避免因为遗漏某些重要信息而导致的续传失败。经过不断的优化和完善，这些模板会变得越来越贴合个人的使用习惯，成为提升工作效率的利器。随着使用经验的积累，你会逐渐发现，断点续传不仅仅是一个解决任务中断问题的功能，更是一种全新的长任务管理思维。它让我们不再害怕长任务的中断，不再因为一次意外就前功尽弃。它教会我们把复杂的大任务分解成简单的小任务，学会在过程中不断地保存状态、总结进度、调整方向。这种思维方式的转变，比掌握任何具体的技巧都更加重要，它能够让我们在面对任何复杂的工作时，都能保持从容和高效。

QClaw的断点续传体系还有很多潜力等待着我们去挖掘，比如基于历史会话的自动状态恢复、智能断点推荐、多任务并行的断点管理等等。这些功能的不断完善，将会让长任务的处理变得越来越轻松。但无论技术如何发展，核心的逻辑永远不会改变：清晰的任务分解、精确的状态描述、增量式的执行方式。掌握了这些核心逻辑，你就能在任何情况下都游刃有余地处理各种长任务，让智能工具真正成为你工作中的得力助手。

内容结构概览

1. 引言 —— 背景与问题缘起

   • Cloudflare Firewall Rules 的需求
   • 为什么选择 Rust

2. 解析器的设计

   • Wireshark DSL 语法的歧义性挑战
   • 三种解析方案的对比
   • 为何放弃解析器生成器，选择手动解析
   • Rust Trait 驱动的解析器架构

3. 执行引擎的演进

   • 初版：直接 AST 解释执行
   • 优化一：用固定数组替代 HashMap，实现 2x 加速
   • 关于 JIT 的思考与放弃原因

4. 核心方案：闭包动态分发

   • Fn trait 与动态分发的原理
   • 将 AST 编译为闭包树
   • 性能、安全、灵活性三者的平衡

5. 彩蛋：WebAssembly 支持

   • wasm-bindgen 与 wasm-pack
   • 20 行代码暴露解析器给前端

在系统编程领域，有一类工程问题天然具有代表性：如何在安全、性能与可维护性之间找到真正的平衡点。Cloudflare 工程团队在构建防火墙规则引擎时，用 Rust 给出了一份值得拆解的答案。

这篇文章基于 Cloudflare 官方博客 Building fast interpreters in Rust，系统梳理其中的工程决策，适合对编译原理、Rust 或系统设计有兴趣的读者。

背景：为什么要自己造这个轮子

Cloudflare 的防火墙规则系统，需要让用户用类似 Wireshark 的过滤语法来描述规则，例如：

ip.addr == 192.168.0.1
http.request.uri matches "gl=se$"

规则需要在 Go、Lua、C、C++ 以及 Workers（JavaScript）等多种环境中运行，并且要满足以下几个硬性指标：

• 性能：规则执行路径在关键链路上，延迟敏感
• 内存安全：生产环境不容许内存漏洞
• 低内存占用：边缘节点资源受限
• 可复用性：需要被多个产品集成

在这个约束组合下，Cloudflare 选择了 Rust，并将这个库以 wirefilter 的名字开源。

第一关：解析器怎么写

Wireshark 语法的歧义陷阱

DSL 设计中，解析器是第一道关口。Wireshark 语法看上去简单，但藏着一个不小的歧义问题。

考虑这个值：2f:31:32:33:34:35:36:37

它同时是合法的 IPv6 地址，也是合法的字节序列。究竟该如何解析，取决于字段的类型：

ipv6.addr == 2f:31:32:33:34:35:36:37   → 解析为 IPv6 地址
http.request.uri == 2f:31:32:33:34:35:36:37  → 解析为字节序列

类似地，80 既可以是端口号（整数），也可以是 HTTP 响应体中的单字节（0x80）。

这意味着解析器不能独立运行——它必须带着一份预先定义好的 Schema（字段名到类型的映射）才能完成解析。

为什么不用解析器生成器

面对这个需求，常见的三类方案分别是：

1. 手动字符解析：用状态机、正则或原生字符串 API
2. 解析器组合子（Parser Combinators）：如 nom、combine 等
3. 解析器生成器：如 pest、LALRPOP 等，通过语法描述自动生成解析器

解析器生成器通常基于独立的词法分析阶段，而这个问题要求词法与类型上下文绑定，大多数生成器做不到。即使用 LALRPOP 这类允许自定义 Lexer 的方案，复杂度也逼近手写，却多了一层黑盒。

最终团队选择了手动解析——在 Rust 中，字符串默认有边界检查，API 丰富，安全性有保证。

Rust Trait 驱动的解析架构

团队将解析器设计为实现统一 Trait 的类型：

pub trait Lex<'i>: Sized {
    fn lex(input: &'i str) -> LexResult<'i, Self>;
}

pub trait LexWith<'i, E>: Sized {
    fn lex_with(input: &'i str, extra: E) -> LexResult<'i, Self>;
}

• Lex：用于不依赖上下文的解析（如字段名、字面量）
• LexWith：用于需要 Schema 的上下文感知解析

顺序解析时，直接链式调用：

let input = skip_space(input);
let (op, input) = CombinedExpr::lex_with(input, scheme)?;
let input = skip_space(input);
let input = expect(input, ")")?;

选择分支时，用 Rust 原生的模式匹配：

if let Ok(input) = expect(input, "(") {
    // 括号表达式
} else if let Ok((op, input)) = UnaryOp::lex(input) {
    // 一元操作符
} else {
    // 其他情况
}

对于枚举类型的解析，用宏来减少重复：

lex_enum!(#[repr(u8)] OrderingOp {
    "eq" | "==" => Equal = EQUAL,
    "ne" | "!=" => NotEqual = LESS | GREATER,
    "ge" | ">=" => GreaterThanEqual = GREATER | EQUAL,
    ...
});

这种方式兼具解析器组合子的无状态清晰性，又保留了完整的语言控制权。

第二关：执行引擎怎么快

初版：直接 AST 解释

最初的执行引擎很直接——让每个 AST 节点实现一个 execute 方法：

trait Expr<'s> {
    fn execute(&self, ctx: &ExecutionContext<'s>) -> bool;
}

ExecutionContext 本质上是一个 HashMap，存储字段名到运行时值的映射。执行时递归遍历 AST，在 Map 里查字段值。

功能正确，但 HashMap 查找的开销不可忽视。

优化：用固定数组替代 HashMap

关键洞察在于：Schema 是提前已知的，字段数量是固定的。因此完全可以用一个定长数组来存运行时值，用字段在 Schema 中的下标来索引，彻底省掉哈希计算。

实现上，用 IndexMap（一个保留插入顺序、支持按下标访问的 HashMap 替代品）替换 Schema 内部的 HashMap，在解析阶段就把字段名解析为下标并存入 AST：

pub struct ExecutionContext<'e> {
    scheme: &'e Scheme,
    values: Box<[Option<LhsValue<'e>>]>,
}

执行时直接按下标取值，不再涉及任何哈希。

效果立竿见影：

约 2 倍的性能提升，且类型错误的检测时机提前到了赋值时，而非执行时，可用性也随之改善。

关于 JIT：想过，但放弃了

"下一步就加 JIT，性能飞起来"——这是 DSL 工程中几乎人人都有过的想法。

但 Cloudflare 团队经过评估后选择放弃，原因很实际：

存储问题：如果静态编译每条规则，需要为 x86-64、ARM、WASM 等多平台分别编译，并维护存储，规则一旦更新逻辑就要全量重编译。

JIT 的代价：JIT 编译发生在运行时，生成原生代码本身就有相当的时间开销，很容易抵消执行加速带来的收益。

安全风险：动态生成代码并标记为可执行内存，本质上是引入了一个运行时的信任边界，这在边缘安全产品中是需要格外谨慎的事。

核心方案：闭包树取代 AST 解释

既然 JIT 不用，有没有一种方式，在不生成原生代码的前提下，尽量逼近 JIT 的运行时性能？

Cloudflare 的答案是：将 AST 编译成一棵闭包树。

Fn trait 与动态分发

Rust 的 Fn trait 系列（Fn、FnMut、FnOnce）允许将闭包装箱为 Box<dyn Fn(...)>，在运行时通过动态分发调用。

核心结构如下：

pub(crate) struct CompiledExpr<'s>(Box<dyn 's + Fn(&ExecutionContext<'s>) -> bool>);

impl<'s> CompiledExpr<'s> {
    pub(crate) fn new(closure: impl 's + Fn(&ExecutionContext<'s>) -> bool) -> Self {
        CompiledExpr(Box::new(closure))
    }

    pub fn execute(&self, ctx: &ExecutionContext<'s>) -> bool {
        self.0(ctx)
    }
}

每个 AST 节点通过 compile() 方法转化为一个闭包，闭包可以捕获所需的数据，也可以嵌套调用其他闭包。

闭包套闭包：组合逻辑的自然表达

以 IP 范围检查为例，在编译阶段就可以把 IPv4 和 IPv6 分开处理并缓存：

RhsValues::Ip(ranges) => {
    let mut v4 = Vec::new();
    let mut v6 = Vec::new();
    for range in ranges {
        match range.clone().into() {
            ExplicitIpRange::V4(r) => v4.push(r),
            ExplicitIpRange::V6(r) => v6.push(r),
        }
    }
    let v4 = RangeSet::from(v4);
    let v6 = RangeSet::from(v6);
    CompiledExpr::new(move |ctx| {
        match cast!(ctx.get_field_value_unchecked(field), Ip) {
            IpAddr::V4(addr) => v4.contains(addr),
            IpAddr::V6(addr) => v6.contains(addr),
        }
    })
}

逻辑组合（AND / OR / XOR）同样用闭包嵌套表达：

match op {
    CombiningOp::And => {
        CompiledExpr::new(move |ctx| items.iter().all(|item| item.execute(ctx)))
    }
    CombiningOp::Or => {
        CompiledExpr::new(move |ctx| items.iter().any(|item| item.execute(ctx)))
    }
    ...
}

最终整棵表达式树变成一个单一的顶层闭包，调用它就等于执行整条规则。

这个方案的收益清单

• 解耦：执行逻辑与 AST 结构完全分离，可以各自演进
• 零原生代码生成：运行时只调用静态验证过的 Rust 函数，没有安全边界问题
• 编译开销极低：装箱闭包的代价远低于真正的代码生成
• 性能意外提升：相较于原始 AST 解释，动态分发带来了约 10~15% 的运行时性能改善

这个结果起初令团队意外——动态分发通常被认为有额外开销，但实测中，闭包树消除了大量递归调用的中间状态，缓存局部性反而更好。

唯一的代价是：相比于真正的 JIT 内联展开，每层闭包仍然有一次虚函数调用开销。但对这个场景而言，这个代价完全可以接受。

彩蛋：20 行代码暴露给前端

Cloudflare 的防火墙规则编辑器有一个 UI，需要在前端实时校验用户输入的规则语法。理想状态是前后端共用同一套解析器。

Rust 对 WebAssembly 的支持恰好提供了这个可能。

借助 wasm-bindgen，只需约 20 行代码就能将解析器暴露为 WASM 模块：

#[wasm_bindgen]
pub struct Scheme(wirefilter::Scheme);

#[wasm_bindgen]
impl Scheme {
    #[wasm_bindgen(constructor)]
    pub fn try_from(fields: &JsValue) -> Result<Scheme, JsValue> {
        fields.into_serde().map(Scheme).map_err(into_js_error)
    }

    pub fn parse(&self, s: &str) -> Result<JsValue, JsValue> {
        let filter = self.0.parse(s).map_err(into_js_error)?;
        JsValue::from_serde(&filter).map_err(into_js_error)
    }
}

配合 wasm-pack，可以自动生成 npm 包并发布。这意味着同一套 Rust 代码可以同时服务于：

• 后端边缘节点的规则执行
• 前端编辑器的实时语法校验
• 甚至 Cloudflare Workers 中的规则运行

总结与思考

Cloudflare 这个案例的核心工程价值在于，它展示了几个在实践中常被忽视的判断：

第一，不是所有问题都适合用现成工具解决。 解析器生成器省事，但一旦 DSL 有上下文相关的歧义，生成器的边界就到了。手写解析器在 Rust 里并不可怕。

第二，性能优化要先找对瓶颈。 HashMap 查找看起来"很快"，但在高频执行路径上，换成数组下标索引就能带来 2 倍提升。数据结构的选择往往比算法优化影响更直接。

第三，JIT 不是银弹。 编译代价、存储复杂性、安全边界，这些隐性成本在边缘场景下完全可以让 JIT 得不偿失。闭包树在这里是一个工程上更务实的折中。

第四，语言特性可以成为架构工具。 Rust 的 Fn trait 和动态分发，不只是语言细节，而是可以用来构建可组合执行引擎的设计原语。

如果你正在设计一个嵌入式规则引擎、DSL 解释器，或者类似的执行框架，这套思路有相当强的参考价值。

原文链接：https://blog.cloudflare.com/building-fast-interpreters-in-rust/

开源仓库：https://github.com/cloudflare/wirefilter