Rust RFC 3373:禁止函数体内的非本地定义 —— 面向局部推理的 Lint 提案深度解析
Rust RFC 3373:禁止函数体内的非本地定义 —— 面向局部推理的 Lint 提案深度解析
本文基于 RFC 3373 原文 展开,介绍 Rust 语言治理仓库(rfcs)中一项重要的语言设计提案:为「在函数或表达式内定义、却对外部可见的 impl 块与导出宏」引入一条默认警告(warn-by-default)的 lint。读完后,你将理解该提案要解决的工具链与人类阅读问题、三类具体规则的判定条件、从警告到硬性错误的演进路线,以及它对现有代码生态(尤其是宏生成代码与 rustdoc)的影响边界。
背景与问题:非本地定义让交叉引用失去边界
在当前的 Rust 语言中,允许在函数体、闭包、static/const 初始化表达式、enum 判别式赋值等「包含表达式的项」里定义新的项(impl 块、macro_rules! 宏等),并且这些定义在语义上可以被该函数之外的代码所引用。RFC 3373 的 Motivation 部分指出了这一能力带来的两类实际成本:
- 工具侧成本:IDE 等负责「使用点 ↔ 定义点」交叉引用(cross-referencing)的工具,为了找到一个函数内某处使用对应的定义,要么必须去搜索所有其他函数体和所有包含表达式的项内部,要么干脆放弃对这类定义的交叉引用能力。前者意味着索引范围无法界定,后者意味着工具功能存在盲区。
- 人类侧成本:程序员人工排查「这个定义在哪里」时,会面临同样的困境——无法确信「定义一定不在其他函数内部」,搜索范围被迫扩散到整个 crate。
该 RFC 的核心主张因此很直接:通过 lint 限制「函数内定义的项对外可见」的形态,让人类排查时有明确的范围边界,「不必去其他函数或项里找定义,也不会漏掉任何相关定义」。并且它预见到,如果未来某个 Rust 版本最终彻底禁止这种写法,工具链也可以直接依赖这一语言级保证,进一步简化实现。
提案的元信息(来自 RFC 原文头部):
- Feature Name:N/A(不引入新的 feature gate,而是以 lint 形式落地);
- 起始日期:2022-01-19;
- 上游 PR 编号:rust-lang/rfcs#3373;
- 跟踪 issue:rust-lang/rust#120363。
提案主体:一条针对非本地定义的 warn-by-default lint
哪些位置算「包含表达式的项」
RFC 的 Explanation 部分首先界定了检查发生的位置范围。Rust 中以下四类项被称为**"expression-containing items"**(包含表达式的项),因为它们内部可以出现表达式,因而也可能嵌套定义其他项:
- 函数(Functions);
- 闭包(Closures);
- 赋值给
static项或非匿名const项的值; - 赋值给
enum变体(enum variant)的判别式值。
注意第 3 条特意排除了「匿名 const」(anonymous const,例如 [N; 3] 这类常量表达式语境下产生的常量项)——是否也要对匿名 const 中的定义触发警告,被 RFC 明确留作未决问题(见下文「未决问题」一节)。
lint 的三条具体规则
在上述「包含表达式的项」内部(任意嵌套层级),Rust 将对以下三种情况发出 warn-by-default 的 lint:
规则一:裸 impl Type 块(为类型添加固有方法)
嵌套在包含表达式的项内的项,不得定义
impl Type块,除非Type本身也嵌套在同一个包含表达式的项内部。
也就是说,在函数体里给一个「外部类型」补方法(inherent impl)会触发警告;但给同一个函数体内局部定义的类型补方法则不会,因为类型与方法定义的可见范围被约束在了同一局部作用域内,不会形成跨函数的引用。
规则二:impl Trait for Type 块(为类型实现 trait)
嵌套在包含表达式的项内的项,不得定义
impl Trait for Type,除非Trait或Type二者之一嵌套在同一个包含表达式的项内部。
这里采用的是「任一局部化即放行」的宽松条件:只要 trait 和类型中有一个是局部的,这条 impl 就不会产生纯粹的「非本地引用」——另一个(外部)侧的可见性仍然可以被工具链在正常的位置索引到。
规则三:对外导出的宏定义
嵌套在包含表达式的项内的项,不得定义在包含表达式的项外部可见的导出宏(例如使用
#[macro_export]的macro_rules!宏)。
#[macro_export] 会把宏提升到 crate 根并在对外部暴露;这类定义是「在局部定义、却全局可见」的典型,正是本 RFC 要抑制的形态。
lint 的挂载点(spans)
对诊断系统来说,警告应该报在哪一处 token 上直接决定了用户能否快速定位问题。RFC 明确规定:
- 对
impl块,lint 挂载到impltoken; - 对宏定义,lint 挂载到
macro_rules!token。
这与 RFC 过程文档 0000-template.md 中对 RFC 编写「应给出示例错误消息」的要求一致:把诊断锚定在定义语句的起始关键字上,保证开发者在函数体中扫到警告时,一眼就能对应到那条有问题的定义语句,而不是被定位到某个嵌套深处或调用点。
下面以伪代码形式示意规则一被警告的形态(示例为本文根据 RFC 规则编写的说明性代码,非仓库内代码):
struct Outer; // 定义在函数之外
fn f() {
impl Outer { // 该 `impl` token 处触发 lint:
fn method(&self) {}
// Outer 是外部类型,impl 却是函数内定义的
// 「非本地定义」
}
}
若 impl 的目标类型 Outer 本身也定义在同一个函数体内,或(规则二)trait 与类型之一为局部定义,则不会触发该警告。
从警告到硬错误的演进路线
RFC 对这条 lint 的长期强度做了明确的阶段性规划:
- 第一阶段(本 RFC):warn-by-default 的 lint 先行落地,用于收集生态数据、给存量代码留出迁移窗口;
- 第二阶段(候选 Rust 2024 版本):评估将该 lint 升级为 deny-by-default——即在新版本 edition 中默认视为错误;
- 第三阶段(候选 2027):评估直接做成 hard error(硬性编译错误)。
RFC 同时强调:在推进二、三阶段之前,「会先评估对生态与既有使用场景的影响」。这一分步策略与 Rust 的 edition 机制(如 RFC 3501 Edition 2024 所描述的版本演进流程)相衔接:edition 为「破坏性变更的默认值收紧」提供了按版本分批生效的通道,而 lint 先行则是标准的生态铺垫手段。
缺点与生态影响
RFC 的 Drawbacks 部分坦承了迁移成本:
- 一部分现有代码正在使用这种「函数内定义对外可见的 impl/宏」的模式,升级后将需要迁移到别的写法;
- 更关键的是宏生成的代码与工具生成的代码(RFC 特别点名了 rustdoc 这类工具)也可能产出这种模式。这意味着变更的压力不仅落在手写代码上,还可能传导到宏作者和文档/代码生成工具的实现上,需要这些工具重构生成策略以符合新约束。
这一条缺点也解释了为什么 RFC 选择「lint 先行 + 分版本升级」的节奏:给代码生成方留出改造时间,同时通过 crater 式的全生态扫描(见下节未决问题)量化真实影响面。
先例(Prior art):与 Rust 的「局部推理」设计哲学一致
RFC 在 Prior art 一节指出,该提案并非孤立发明,而是与 Rust 设计中一系列「支持局部推理(local reasoning)、避免全局推理」的既有取向一脉相承,例如:
- 函数签名的非推断性(non-inference of function signatures):函数签名不能从函数体反推,阅读调用方无需进入函数体即可理解其契约;
impl Trait的不透明性约束:函数体不得影响签名中impl Trait的非不透明性质,除非这些性质在签名中显式体现。
本 lint 是同一思想的延伸:让「使用点」的读者不必被迫深入「任意其他函数体」去找定义,使符号解析与理解范围重新收敛到可预期的边界内。
未决问题(Unresolved questions)
RFC 明确列出两个悬而未决的事项:
- 需要一次 crater run(对 crates.io 全生态的扫描试验),以量化这种模式在存量代码中的普遍程度,为是否升级 lint 强度提供数据支撑;
- 匿名
const项中的定义是否也应当被标记:前文已述,当前规则只覆盖static与非匿名const项的赋值表达式;对匿名const报警是否会产生大量无意义的警告,尚无结论。
这两个问题决定了提案从「概念通过」到「真正落地」之间还需完成的验证工作,也是阅读该 RFC 状态时应注意的适用前提。
未来可能性:与独立 derive 机制的交互
RFC 的 Future possibilities 一节前瞻了一个尚未实现的机制:若未来 Rust 提供「独立 derive」(standalone derive,例如 derive Trait for Type 作为与 Type 定义分离的独立语句),那么该机制生成的 impl 块也将适用与本 RFC 完全相同的约束——即不允许出现「在函数内为外部类型实现 trait」的形态。这保证了即便语法机制演进,「非本地定义」这一语义边界的一致性依然保持。
总结
RFC 3373 用一个范围明确、规则精确的 warn-by-default lint,回应了「函数内非本地定义」给 IDE 交叉引用和人类阅读带来的边界失守问题。其设计要点可以归纳为:
- 检查范围锁定在四类「包含表达式的项」(函数、闭包、
static/非匿名const的赋值、enum变体判别式)内部任意深度; - 三条规则分别约束裸
impl Type、impl Trait for Type与#[macro_export]导出宏,判定核心是「被引用的 trait/类型是否同处一个局部作用域」; - 诊断锚定在
impl/macro_rules!token,保证可定位性; - 强度上采取 warn →(2024 候选)deny →(2027 候选)hard error 的渐进路线,并以 crater 数据与匿名
const的结论作为推进前提。
对 Rust 语言实现者、crate 维护者和代码生成工具作者而言,关注 RFC 3373 原文 及其跟踪 issue(rust-lang/rust#120363)的后续进展,可以提前预判这条 lint 的落地时点并安排代码结构上的迁移;对 Rust RFC 的完整流程(含 FCP 与 active 状态的含义),可参考 README.md 中的 RFC 流程说明与 0000-template.md 中的 RFC 模板结构。