C# 11怎么使用list patterns列表模式匹配？

在C# 11之前，如果我们要根据一个整数列表的前两个元素做不同处理，往往需要手写下标判断和长度校验，代码既冗长又容易越界。C# 11正式引入的列表模式（list patterns）让开发者可以用声明式的方括号语法，直接对数组、List<T>以及其他支持索引和长度的结构进行模式匹配。这种能力建立在模式匹配的基础之上，但把关注点从单个对象转移到了序列的整体形状。

列表模式的基础语法与匹配规则

列表模式使用方括号来表示一个序列，括号内部可以放置常量、占位符、范围模式以及嵌套的其他模式。最常见的写法是使用下划线_作为丢弃模式，表示忽略该位置的元素；使用..作为范围模式，表示零个或多个任意元素。例如[1, 2, _]表示序列长度为三，且第一个元素是1，第二个是2，第三个可以是任意值。

需要特别注意的是，列表模式不只适用于数组，只要类型提供了合适的访问方式就可以匹配。对于List<T>，编译器会利用Count属性和索引器；对于数组则使用Length和下标。如果序列长度不符合模式中显式写出的元素个数与范围模式的组合，整个匹配就会失败。下面的代码展示了最基本的匹配方式：

int[] numbers = { 1, 2, 9 };
if (numbers is [1, 2, _])
{
    Console.WriteLine("前两个元素是1和2");
}
else if (numbers is [1, ..])
{
    Console.WriteLine("第一个元素是1，后面随意");
}

在上面的示例中，第一个条件成功匹配，因为数组正好有三个元素且前两个符合预期。如果把数组改成只有两个元素[1, 2]，那么[1, 2, _]就会失败，但[1, ..]仍然可以匹配，因为..允许后面没有元素。这种灵活性让我们在写校验逻辑时，不必再手动写numbers.Length == 3这样的判断。

列表模式还支持常量模式和关系模式的组合。比如[>= 0, <= 10, ..]可以匹配第一个元素在0到10之间的序列。这里的关系模式需要写在常量位置，编译器会自动展开为对应的比较逻辑。对于字符串数组，也可以直接写["start", ..]来匹配第一个字符串为start的情况。

结合switch表达式实现多分支分发

列表模式真正的威力在于和switch表达式或switch语句配合使用。过去我们可能要用多个if-else来判断集合内容，现在可以把每种形状写成一个arm，代码读起来像一份数据格式说明。switch表达式要求覆盖所有可能，因此通常会用一个包含..的兜底分支。

假设我们在解析一组简单的指令，指令用整数列表表示，第一位代表操作类型，后面是参数。使用列表模式可以写成如下形式，既清晰又不容易漏掉边界情况：

string Describe(List<int> cmd) => cmd switch
{
    [0, ..] => "停止指令",
    [1, var x, ..] => $"移动指令，步长{x}",
    [2, var a, var b] => $"两点指令，坐标({a},{b})",
    [..] => "未知指令"
};

在上面的代码里，var x是一个变量模式，它会把匹配位置的元素捕获到变量x中，供右侧表达式使用。这种写法直接把“解构”和“分支”合二为一，不需要事先用索引把值取出来。兜底分支[..]表示匹配任意列表，保证switch表达式完整。

如果列表里嵌套了其他列表，列表模式也支持嵌套。比如[[1, 2], ..]可以匹配第一个元素本身是一个包含两个元素的列表且值为1和2。但要注意，嵌套匹配会增加编译器的展开成本，对于特别复杂的深层结构，有时用普通的foreach循环反而更直观。在性能敏感的热点路径上，建议先测量再决定是否使用深层列表模式。

常见误用与兼容性注意点

很多人在初次使用列表模式时，会误以为_和..可以随意互换。实际上_只匹配恰好一个元素，而..匹配零个或多个。如果写了[1, _, 2]，那么序列必须正好三个元素；如果写了[1, .., 2]，则中间可以有任意数量元素，但首尾必须分别是1和2。混淆两者会导致匹配失败却难以察觉。

另一个常见问题是试图对不支持的模式目标使用列表模式。列表模式要求目标类型具有可访问的Count或Length，以及索引器或Span支持。对于某些自定义集合，如果没有实现这些成员，编译器会报错。此时可以先用ToArray()转换，或者改用传统的循环判断。下面演示了一个容易出错的写法以及修正方式：

// 假设legacyList是只实现了IEnumerable<int>的旧集合
// if (legacyList is [1, ..]) 编译失败

int[] arr = legacyList.ToArray();
if (arr is [1, ..])
{
    Console.WriteLine("转换后可正常匹配");
}

还有一点是关于空序列的匹配。空列表模式写作[]，它只匹配长度为零的序列。如果写了[..]，它既能匹配空序列也能匹配任意非空序列。在写校验逻辑时，如果要严格区分“没有任何数据”和“有数据但不管内容”，就必须显式使用[]而不是[..]。这个细节在接口参数校验时尤其重要，可以避免把空输入误当成合法指令处理。

从语言版本看，列表模式是C# 11的特性，因此项目文件中的LangVersion必须设置为11或更高，且需要相应版本的.NET SDK。在旧版本编译器上写列表模式会得到语法错误而非运行时异常。团队升级前应当统一开发环境，并在代码评审中留意是否有成员误用导致构建失败。

list_patternsC#_11pattern_matching修改时间：2026-08-17 00:46:15