rustc E0214 错误详解：为什么 `Vec(&str)` 不合法，泛型参数为何必须使用尖括号

rustc 错误码 E0214（parenthesized type parameters may only be used with a Fn trait）是 Rust 编译器在"类型参数被误写成圆括号形式"时发出的编译错误。本文以 E0214 官方错误文档 为主体，结合 rustc 的 AST 降级（lowering）源码与 compiletest 测试用例，讲解该错误的触发场景、编译器内部判定逻辑、Fn 族 trait 的圆括号例外语法，以及如何修复并规避此类问题。

1. 错误现象：一个看起来"合理"的写法

假设你要声明一个元素为字符串切片引用的 Vec，写成下面这样：

let v: Vec(&str) = vec!["foo"];

Rust 编译器（rustc）会拒绝这段代码，并抛出错误码 E0214，完整报错输出为：

error[E0214]: parenthesized type parameters may only be used with a `Fn` trait
  --> src/main.rs:2:12
   |
LL |     let v: Vec(&str) = vec!["foo"];
   |            ^^^^^^^^^ only `Fn` traits may use parentheses
   |
help: use angle brackets instead
   |
LL -     let v: Vec(&str) = vec!["foo"];
LL +     let v: Vec<&str> = vec!["foo"];
   |

这段报错信息正是官方文档所描述的：泛型类型参数应该用尖括号（angle brackets）而非圆括号（parentheses）描述。Vec(&str) 想要表达的其实是 Vec<&str>，即"以 &str 为元素类型的 Vec"。

官方文档中的出错示例与修复如下：

// 错误：使用圆括号包裹泛型参数
let v: Vec(&str) = vec!["foo"];

// 修复：改为尖括号
let v: Vec<&str> = vec!["foo"];

2. 根因：圆括号在类型语法中的语义分工

Rust 的语法中，为类型或函数名附加泛型实参的标准形式是尖括号（<、>）。圆括号在这类上下文里并不是泛型的合法分隔符，因此 Vec(&str) 会被 rustc 判定为语法上不支持的写法。

文档中明确给出了这一限制的唯一例外：当前只有在为 Fn 族 trait 描述参数列表（parameter lists）时，圆括号才被允许与泛型类型一起使用。也就是说，Fn(A) -> B、FnMut(A, B)、FnOnce() 这类写法是合法的 trait 约束语法，而把同一套圆括号语法套用到 Vec、HashMap、Option 等普通泛型类型上就会触发 E0214。

2.1 Fn 族 trait 的合法圆括号写法

在 trait bound（trait 约束）中，Fn 族 trait 可以自然地使用圆括号书写函数签名式的参数与返回类型：

// Fn 族 trait 使用圆括号表达参数表是合法的
fn call_twice<F: Fn(i32) -> i32>(f: F) -> i32 {
    f(1) + f(2)
}

// 多个参数、无返回值也可以
let mut f: Box<dyn FnMut(&str) -> usize> = Box::new(|s| s.len());

从语法语义上讲，这里的 Fn(i32) -> i32 中的圆括号部分承载的是函数参数列表，而不是"泛型参数"；它和 Fn<(i32,), Output = i32> 这种显式写法表达的是同一类 trait 实参，只是提供了更简洁的语法糖。

3. 编译器内部判定：AST 降级阶段的 GenericArgsMode

E0214 并非简单的解析错误，它发生在 rustc 把 AST 降级（lower）为 HIR 的阶段，对应 crate 是 compiler/rustc_ast_lowering。在 HIR 降级过程中，LoweringContext 会为路径中的每一个 segment 计算一个"泛型实参处理模式"（enum GenericArgsMode）：

enum GenericArgsMode {
    /// Allow paren sugar, don't allow RTN.
    ParenSugar,
    /// Allow RTN, don't allow paren sugar.
    ReturnTypeNotation,
    // Error if parenthesized generics or RTN are encountered.
    Err,
    /// Silence errors when lowering generics. Only used with `Res::Err`.
    Silence,
}

• ParenSugar：允许"圆括号语法糖"（即 Fn(A) -> B 形式的参数表），用于 trait 路径；
• ReturnTypeNotation：允许返回类型记法（RTN，如 T::method(..) -> Ret），与本文错误无关但相互对立；
• Err：一旦遇到圆括号或 RTN 就报错，普通类型实参（如 Vec(&str)）会落入此模式；
• Silence：在解析结果已是错误（Res::Err）时静默降级，避免重复报错。

从 path.rs 的源码可以看到模式选择完全取决于路径的解析结果 base_res：

let generic_args_mode = match base_res {
    // `a::b::Trait(Args)`
    Res::Def(DefKind::Trait, _) if i + 1 == proj_start => {
        GenericArgsMode::ParenSugar
    }
    // `a::b::Trait(Args)::TraitItem`
    Res::Def(DefKind::AssocFn, _)
    | Res::Def(DefKind::AssocConst { .. }, _)
    | Res::Def(DefKind::AssocTy, _)
        if i + 2 == proj_start =>
    {
        GenericArgsMode::ParenSugar
    }
    Res::Def(DefKind::AssocFn, _) if i + 1 == proj_start => {
        match allow_return_type_notation {
            AllowReturnTypeNotation::Yes => GenericArgsMode::ReturnTypeNotation,
            AllowReturnTypeNotation::No => GenericArgsMode::Err,
        }
    }
    // Avoid duplicated errors.
    Res::Err => GenericArgsMode::Silence,
    // An error
    _ => GenericArgsMode::Err,
};

可以推断出该判定的整体逻辑：

• 当路径最终解析为一个 trait（如 bound 中的 Fn、Iterator 等 trait 约束场景）时，进入 ParenSugar 分支；
• 当路径解析为结构体、枚举、联合体等非 trait 的泛型类型（如 Vec、Option）时，命中最后的兜底分支 GenericArgsMode::Err；
• 只有 Err 分支才会真正构造 E0214 诊断。

4. 诊断对象与"改圆括号为尖括号"的自动建议

在 rustc_ast_lowering/src/diagnostics.rs 中，E0214 通过 #[derive(Diagnostic)] 声明式定义：

#[derive(Diagnostic)]
#[diag("parenthesized type parameters may only be used with a `Fn` trait", code = E0214)]
pub(crate) struct GenericTypeWithParentheses {
    #[primary_span]
    #[label("only `Fn` traits may use parentheses")]
    pub span: Span,
    #[subdiagnostic]
    pub sub: Option<UseAngleBrackets>,
}

#[derive(Subdiagnostic)]
#[multipart_suggestion("use angle brackets instead", applicability = "maybe-incorrect")]
pub(crate) struct UseAngleBrackets {
    #[suggestion_part(code = "<")]
    pub open_param: Span,
    #[suggestion_part(code = ">")]
    pub close_param: Span,
}

这里的两个关键信息点：

1. 主诊断文本（即前面报错输出第一行）来自 GenericTypeWithParentheses，其主 span 上的标注文案是 only Fn traits may use parentheses；
2. UseAngleBrackets 是一个多段建议（multipart suggestion）：编译器会定位到圆括号起点与终点，在合适位置分别插入 < 和 >，从而自动把 Vec(&str) 改写为 Vec<&str>，对应报错里的 help: use angle brackets instead 及 LL + 行。

4.1 建议的具体构造逻辑

真正触发 E0214 的代码位于 path.rs 的 GenericArgsMode::Err 分支。其思路是：既然圆括号非法，就把它当作"本应使用尖括号的泛型实参列表"处理——先算出待替换的两段 span，再继续用尖括号版本进行降级：

GenericArgsMode::Err => {
    // Suggest replacing parentheses with angle brackets `Trait(params...)` to `Trait<params...>`
    let sub = if !data.inputs.is_empty() {
        // Start of the span to the 1st character of 1st argument
        let open_param = data.inputs_span.shrink_to_lo().to(data
            .inputs
            .first()
            .unwrap()
            .span
            .shrink_to_lo());
        // Last character position of last argument to the end of the span
        let close_param = data
            .inputs
            .last()
            .unwrap()
            .span
            .shrink_to_hi()
            .to(data.inputs_span.shrink_to_hi());

        Some(UseAngleBrackets { open_param, close_param })
    } else {
        None
    };
    let guar = self
        .dcx()
        .emit_err(GenericTypeWithParentheses { span: data.span, sub });
    (
        self.lower_angle_bracketed_parameter_data(
            &data.as_angle_bracketed_args(),
            param_mode,
            ImplTraitContext::AlreadyErrored(guar),
        )
        .0,
        false,
    )
}

值得注意的细节：

• 参数非空时才提供替换建议，此时 open_param 覆盖"圆括号起点到第一个实参之间"、close_param 覆盖"最后一个实参到圆括号终点之间"，二者恰好拼出可替换的 <...> 区域；
• 参数为空时（sub = None）只报主错误、不给替换建议，因为没有参数可供计算插入位置；
• 报错后编译器仍调用 lower_angle_bracketed_parameter_data 用"尖括号等价形式"继续降级，并传入 ImplTraitContext::AlreadyErrored(guar)，从而在已经报错的情况下尽可能恢复后续的类型检查流程，避免产生一连串衍生错误。

5. 何时合法：Fn 族 trait 的 ParenSugar 走向

对照第 4 节，合法的 Fn(A) -> B 约束不会报错，是因为它在 path.rs 走的是 ParenSugar 分支并调用 lower_parenthesized_parameter_data 把"圆括号参数表"正规化为 trait 实参：

GenericArgsMode::ParenSugar | GenericArgsMode::Silence => self
    .lower_parenthesized_parameter_data(
        data,
        itctx,
        bound_modifier_allowed_features,
    ),

因此：

• 合法：fn apply<F: Fn(i32) -> i32>(f: F)、Box<dyn Fn() -> String>、FnMut(&str, &str) 等 trait 约束与 trait 对象中的圆括号写法；
• 非法：Vec(&str)、Option(i32)、HashMap(String, i32) 等对具体类型的圆括号写法，均触发 E0214。

判断要点可归纳为：只有出现在 trait（尤其是 Fn 族）路径位置的圆括号才是语法糖，出现在普通数据类型位置的圆括号一律是错误。

6. 测试验证：compiletest 用例与错误文档的双重保障

本仓库对 E0214 的回归测试位于 tests/ui/error-codes/E0214.rs，通过行内注释标注期望错误：

fn main() {
    let v: Vec(&str) = vec!["foo"];
    //~^ ERROR E0214
}

对应的 E0214.stderr 是 compiletest 记录的精确输出基准（含诊断文案、标注位置与修复建议的每一行）。当编译器的实现发生任何改动导致输出变化时，该测试都会提醒维护者同步更新。

此外，error_codes 文档目录 中的示例本身也携带 compile_fail,E0214 属性，会被文档/代码示例测试框架当作期望编译失败且错误码为 E0214 的用例来校验，确保"文档示例永远正确、可复现"。这与第 6 节测试用例形成双保险：文档正文与编译器行为保持一致。

7. 复现、排查与修复指引

在命令行中，你可以使用以下方式快速查看该错误的完整说明（本地 rustc 已包含内嵌的错误码解释）：

rustc --explain E0214

排查与修复的一般步骤：

1. 看到报错中出现了"类型名 + 圆括号"的写法（Vec(&str)、HashMap(&str, i32) 等），先确认它是否出现在 trait bound 或 trait 对象的 Fn 族参数表位置；
2. 若针对的是普通数据类型的泛型参数，只需把圆括号整体替换为尖括号，保持内部参数不变：Vec(&str) → Vec<&str>；
3. 由于 rustc 在 E0214 中默认附带 use angle brackets instead 的 multipart 建议，多数 IDE 与 cargo fix / rustfix 流程可直接应用自动改写；
4. 若希望表达的是函数指针或闭包类型，请使用 fn(&str) 或 dyn Fn(&str) 等明确语法，而不是给 Vec 套圆括号。

8. 小结

E0214 是 rustc 对"泛型实参语法被误用为圆括号"的明确提示：尖括号是泛型实参的唯一合法分隔符，圆括号只允许作为 Fn 族 trait 参数列表的语法糖。从 E0214 文档、诊断对象定义、模式分派与降级逻辑 到 compiletest 测试 的完整链路可以看出，rustc 不仅负责报错，还通过 GenericArgsMode 的模式匹配精确区分"trait 圆括号糖"与"普通类型圆括号错误"，并以多段建议的形式给出可直接套用的修复——这也是编译器诊断系统对开发者友好的一个典型切片。