Command-Line API项目：关于移除TreatUnmatchedTokensAsErrors的技术探讨

背景与现状

在Command-Line API项目中，TreatUnmatchedTokensAsErrors是一个长期存在的功能选项，它主要用于处理命令行解析过程中未被匹配的令牌(token)。当前设计允许开发者设置这个标志来决定是否将未匹配的令牌视为错误。

这个功能最初的主要应用场景是在组合式CLI工具中，比如dotnet new和dotnet msbuild这样的命令。在这些场景下，.NET CLI会先解析自己识别的参数，然后将未被识别的参数传递给后续的解析器处理。dotnet new特别有趣，它会根据选择的模板动态构建解析器。

问题分析

经过深入的技术评估，开发团队发现使用CliArgument定义一个字符串数组参数，然后将这个数组传递给后续解析器，是比TreatUnmatchedTokensAsErrors更优的解决方案。这种新方法有几个显著优势：

1. 类型安全：避免了将Token类型暴露到解析层之外，可以保持Token作为内部类型
2. 解析清晰度：一旦出现未匹配令牌，解析过程往往会变得复杂且容易出问题
3. 设计一致性：与组合式CLI的设计理念更加契合

技术挑战与解决方案

在讨论移除TreatUnmatchedTokensAsErrors时，团队考虑了多种实际应用场景和技术挑战：

1. 参数传递的精确性

有开发者指出，简单的字符串数组方法无法区分以下两种情况：

• dotnet msbuild -- -interactive：应该在名为-interactive的目录中搜索项目
• dotnet msbuild -interactive：应该在当前目录搜索项目并以交互模式构建

这表明在某些场景下，参数位置和分隔符--的语义需要被精确保留。

2. 动态解析需求

dotnet watch等工具需要解析结构未知的命令行，并将部分参数传递给任意子命令。这要求API必须支持灵活的参数传递机制。

3. POSIX兼容性

POSIX标准规定--必须是命令行调用中最后一个选项/参数，在所有其他选项/参数之后。这种标准行为需要在新的设计中得到妥善处理。

替代方案设计

基于以上分析，团队提出了几种替代设计方案：

方案一：显式字符串数组参数

创建一个CliCommand，其中包含一个string[]类型的参数，专门用于收集和传递"额外"参数。这种方法：

• 完全避免未匹配令牌的概念
• 将参数传递变为显式行为
• 保持解析器的简洁性

方案二：专用占位命令

引入一种特殊的CliCommand作为占位符，所有后续选项和参数都与之关联。这种设计：

• 更符合组合式CLI的思维模型
• 可以自然地处理--分隔符
• 提供更清晰的API语义

方案三：显式注册额外参数

提供API让CLI作者显式注册对额外参数的支持：

var command = new Command("example").AddExtraArgumentOption();

这种方法：

• 使参数处理成为显式选择
• 可以控制参数的作用域和可见性
• 保持与POSIX标准的一致性

实施建议

基于技术讨论，建议采取以下实施路径：

1. 分阶段移除：先标记TreatUnmatchedTokensAsErrors为过时，给开发者迁移时间
2. 增强字符串数组方案：完善对--分隔符的处理支持
3. 提供迁移指南：详细说明从旧模式到新模式的转换方法
4. 收集反馈：在预览版本中测试新方案的实际效果

结论

移除TreatUnmatchedTokensAsErrors代表了Command-Line API项目向着更清晰、更一致的解析模型迈进。新的设计方案不仅解决了当前的技术债务，还为组合式CLI工具提供了更强大的支持基础。通过显式而非隐式的参数传递机制，API将变得更可预测、更易于维护，同时保持足够的灵活性来满足各种复杂场景的需求。

这一变更虽然涉及一定的迁移成本，但从长期架构演进的视角来看，将显著提升库的设计质量和用户体验。开发团队将继续关注实际应用中的反馈，确保这一重要改进平稳落地。