企业官网建设流程全解析

本篇以 Roc 编译器仓库中的快照测试文档 test/snapshots/statement/return_stmt.md 为核心线索，系统讲解return语句的词法、语法、规范化（canonicalization）、类型检查全流程：它为什么不能出现在模块顶层、在函数体内如何实现提前返回、以及?运算符如何复用它。读完本文，你将不仅会写合法的return代码，更能理解 Roc 编译器在 9 个测试阶段中是如何逐步验证这段语法的。

一、快照测试：Roc 编译器如何"逐级"验证一段源码

Roc 是一个 fast、friendly、functional 的编程语言（见仓库根目录 README.md）。它拥有一个非常独特的快照测试（snapshot test）体系：每个测试文件本身就是一段带有结构化元信息的 Markdown 文档，编译器测试框架会读取其中的SOURCE源码，依次跑完**分词（tokenize）→ 解析（parse）→ 格式化（format）→ 规范化（canonicalize）→ 类型推断（types）**等多个管线阶段，然后把每个阶段的中间产物与文档中期望值逐一对拍。

return_stmt.md正是这一体系中 statement 类快照测试的一个样例，它与同目录下的break_for_loop.md、dbg_stmt.md、expect_stmt.md、for_stmt.md等共同构成对"语句（statement）"语法族的覆盖。快照文件按固定节（section）组织，每节以# 节名开头，紧跟着用~~~ini/~~~roc/~~~zig/~~~clojure围栏标注的数据块。下面逐节拆解。

二、逐节解剖 return_stmt.md：九段式测试文档

2.1 META：测试属性声明

# META ~~~ini description=Debug expression stmt type=statement ~~~

META节用 INI 格式声明该测试的两个关键属性：

• description：人类可读的测试描述，本例为 "Debug expression stmt"。值得注意，虽然描述写的是 Debug，但真正测试的对象是return，这属于历史遗留的措辞，测试语义以SOURCE为准；
• type=statement：声明本测试属于 statement（语句）测试类别，测试框架据此将其归入语句语法快照组。

2.2 SOURCE：被测源码

# SOURCE ~~~roc return Bool.True ~~~

SOURCE是被测试的完整 Roc 源码，只有一个顶层语句：return Bool.True，即"在模块顶层直接返回布尔标签True"。

2.3 EXPECTED：期望的结果

# EXPECTED NIL

EXPECTED记录的是程序执行/求值阶段的期望输出。此处为NIL，表示该快照并不期望任何运行结果——它是一段注定编译失败的代码，测试的重点是编译器能否在规范化阶段正确地报告"顶层 return"错误，而不是让程序跑起来。

2.4 PROBLEMS：期望的诊断报告

# PROBLEMS NIL

PROBLEMS记录期望出现的编译器诊断（diagnostic）列表。此处同样为NIL，说明在该快照的管线配置下，错误不会被当作 "problem" 呈现，而是以规范化阶段产物中内嵌的s-runtime-error节点形式体现（见 2.7 节）。与之对比，同目录下的 break_outside_loop.md 在PROBLEMS节中就给出了完整的(reports ...)结构，包含 severity 为runtime_error、标题 "Break Outside Loop" 的格式化诊断文本，可见快照测试对"非法语句"既有 NIL 形式、也有显式报告形式。

2.5 TOKENS：词法分析产物

# TOKENS ~~~zig KwReturn,UpperIdent,NoSpaceDotUpperIdent, EndOfFile, ~~~

这是 tokenizer（词法分析器）的输出序列：

• KwReturn：关键字return被识别为保留关键字 token。该映射定义在 src/parse/tokenize.zig：.{ "return", .KwReturn }；
• UpperIdent：Bool是大写开头的标识符，被识别为 UpperIdent（Roc 约定大写标识符为标签/类型名）；
• NoSpaceDotUpperIdent：True前有一个不带空格的点号（Bool.True），被词法分析器合并识别为"紧邻点的大写标识符" token。这正是 Roc 标签限定（qualified tag）写法的词法特征；
• EndOfFile：源码结束标记。

这一序列精确反映了return Bool.True在字符流层面的切分方式，是理解后续 AST 的前提。

2.6 PARSE：语法树产物

# PARSE ~~~clojure (s-return (e-tag (raw "Bool.True"))) ~~~

PARSE节展示 parser 生成的语法树（AST）。整体是一个s-return语句节点，其操作数是一个e-tag标签表达式，raw 文本为Bool.True。

对应的解析器实现位于 src/parse/Parser.zig：当解析器在表达式内核（expr kernel）位置遇到KwReturntoken 时，会记录起始位置、前进一个 token，并把expr_return压入 open-syntax 栈，随后继续解析其后的操作数表达式。也就是说，return <expr>在语法层面被建模为"前缀关键字 + 跟随表达式"，表达式部分采用与普通表达式一致的优先级解析逻辑。

2.7 CANONICALIZE：规范化（CIR）产物

# CANONICALIZE ~~~clojure (can-ir (s-runtime-error (tag "return_outside_fn"))) ~~~

CANONICALIZE节展示规范化阶段（canonicalization）生成的 CIR（canonical IR）。关键事实来了：顶层return不是被规范化为s_return语句，而是被替换为一个s-runtime-error节点，携带return_outside_fn标签。也就是说，编译器在规范化阶段就判定"顶层 return 非法"，并把这段代码标记为必然在运行时出错（实际上由于代码非法，根本不会进入运行阶段）。

这一行为与源码严格对应：

• 在 src/canonicalize/Can.zig 的语句规范化逻辑中，.@"return"分支会先规范化操作数表达式，然后检查self.enclosing_lambda（当前是否处于某个 lambda 函数体内）：若存在则构造合法的s_return语句（记录表达式与所属 lambda 的索引）；否则调用pushMalformed注入return_outside_fn诊断；
• 同文件 src/canonicalize/Can.zig 处理模块顶层语句列表时，遇到return会直接报告invalid_top_level_statement，注释明确写着 "Not valid at top-level"，while、break等语句也有同样的顶层限制。

2.8 FORMATTED 与 TYPES

# FORMATTED ~~~roc NO CHANGE ~~~ # TYPES ~~~clojure (inferred-types (defs) (expressions)) ~~~

• FORMATTED = NO CHANGE：格式化器认为该源码已符合 Roc 官方格式，无需改动。这反过来说明即便语义非法，return Bool.True在字形上是完全合规的代码——格式检查与语义检查是相互独立的管线；
• TYPES中defs与expressions均为空：因为代码在规范化阶段就已被判非法，类型检查阶段没有任何可推断的定义与表达式，类型产物为空也是"错误被提前拦截"的佐证。

2.9 小结：一张表看懂快照结构

三、正确的打开方式：return 在函数体内的提前返回

既然顶层return非法，那么它合法的使用场景是什么？答案是函数（lambda）体内。仓库中同目录的 test/snapshots/statement/return_stmt_block_example.md 提供了标准范例：

foo : U64 -> Try(Str, [TooBig]) foo = |num| { str = if (num > 10) { return Err(TooBig) } else { "SMALL" } Ok(str) }

这个例子的技术要点：

1. 函数foo接收U64，返回Try(Str, [TooBig])——Try是 Roc 的 Result 风格类型（成功时携带Str，失败时携带标签联合[TooBig]）；
2. 在if的条件分支内，当num > 10时执行return Err(TooBig)立即退出整个函数，不再继续执行后面的Ok(str)；
3. 由于提前返回的存在，if的两个分支（一个return、一个字符串字面量）可以拥有不同的"分支结果类型"，这正是return在类型系统里被设计为"发散（diverge）"表达式的直接收益。

该快照的CANONICALIZE节显示，return Err(TooBig)被规范化为(e-return (e-tag (name "Err") (args (e-tag (name "TooBig")))))——注意这里用的是e-return（表达式形式的 return，出现在 if 分支内部），与顶层测试中的s-return（语句形式）相区别。TYPES节最终给出foo : U64 -> Try(Str, [TooBig])的完整类型，证明该写法可以通过类型检查。

四、源码级原理：return 在编译器各阶段的生命周期

结合 src/canonicalize/Statement.zig 中对s_return节点的注释定义：

/// A early return of the enclosing function. /// /// Not valid at the top level of a module /// /// ```roc /// return Err(-1) /// ``` s_return: struct { expr: Expr.Idx, /// The lambda this return belongs to (for type unification). lambda: Expr.Idx, },

可以总结return的完整生命周期：

1. 词法：return是保留字，token 为KwReturn（src/parse/tokenize.zig）；任何把return用作标识符的代码都会在 src/parse/AST.zig 的保留字检查中被拒绝；
2. 语法：parser 以expr_return前缀状态解析return <expr>（src/parse/Parser.zig），产生s-returnAST 节点；
3. 规范化：canonicalizer 依据enclosing_lambda判断合法性（src/canonicalize/Can.zig）。enclosing_lambda在进入 lambda 体时被保存并替换为当前 lambda 的表达式索引（src/canonicalize/Can.zig），离开后恢复。合法时生成s_return（含所属 lambda 引用，供后续类型统一）；非法时生成s-runtime-error+return_outside_fn诊断；
4. 诊断呈现：return_outside_fn诊断在 src/canonicalize/ModuleEnv.zig 中被渲染为标题 "Return Outside Function" 的报告，headline 明确写道："Thereturnkeyword can only be used inside function bodies."（return关键字只能用在函数体内）；
5. 类型检查：在 src/check/Check.zig 的.s_return分支中，checker 会：
   • 检查 return 表达式的类型是否与ret.lambda的期望返回类型相容（checkReturnRelation/appendReturnConstraint）；
   • 把 return 语句本身的类型统一为 flex 变量（flex var），使其能与任意分支类型统一——这正是"含提前返回的分支可以匹配其他分支类型"的实现基础；
   • 置diverges = true，标记该语句之后的代码不可达；
6. 提升（hoisting）分析：s_return/e_return都会参与 hoist 失效标记（src/check/Check.zig、src/check/Check.zig），确保 return 所在表达式树中涉及被提升（hoist）的子表达式时能正确重新计算。

五、隐藏的复用者：?运算符的"隐式 return"

return还有一个容易被忽略的"客户"：Roc 的?（try）运算符。在 src/canonicalize/Can.zig 的addTryReturnErr函数中可以看到，?出错时生成的失败值会被包进Err标签，然后构造一个e_return表达式，其上下文标记为.try_suffix；同样地，若当前不在 lambda 体内，也会注入return_outside_fn诊断。

因此在 src/canonicalize/ModuleEnv.zig 中，return_outside_fn诊断会根据data.context区分两种场景渲染：

• .try_suffix：标题为 "Try Operator Outside Function"，提示 "The?operator can only be used inside function bodies because it can cause an early return."（?会造成提前返回，因此只能在函数体内使用）；
• .return_statement/.return_expr：标题为 "Return Outside Function"，即前面 2.7 节描述的场景。

这意味着return_stmt.md快照验证的"函数外禁止提前返回"这一语义约束，同时约束着显式的return与隐式的?两类语法，是编译器统一防御的一个典型切面。

六、可验证的阅读路径与延伸实验

如果你想在仓库中亲手验证本文所有结论，可按以下路径对照阅读：

1. 快照本体：test/snapshots/statement/return_stmt.md（全文 38 行）；
2. 合法用法对照：test/snapshots/statement/return_stmt_block_example.md（函数体内的提前返回 + 完整 CIR + 类型推断）；
3. 同族语句对比：test/snapshots/statement/break_outside_loop.md（break在循环外同样非法的诊断示例）、test/snapshots/statement/for_stmt.md（循环语句快照）；
4. 词法：return关键字表 src/parse/tokenize.zig；
5. 语法：KwReturn前缀解析 src/parse/Parser.zig；
6. 规范化：语句级 return src/canonicalize/Can.zig、顶层拦截 src/canonicalize/Can.zig、?隐式 return src/canonicalize/Can.zig；
7. IR 定义：s_return节点 src/canonicalize/Statement.zig；
8. 诊断渲染："Return Outside Function" src/canonicalize/ModuleEnv.zig；
9. 类型检查：发散语义与 flex 统一 src/check/Check.zig。

你可以尝试把return_stmt.md的SOURCE改成return Bool.True出现在函数体内（参照 block_example 的写法），或在顶层尝试return Err(TooBig)、在函数内尝试?，观察快照测试各节产物的变化——TOKENS、PARSE、CANONICALIZE、TYPES四节会分别给出词法、语法、规范化与类型层面的差异化反馈，这正是这套快照体系"分层拦截错误"的设计价值所在。