Avalonia Zafiro 开发命名与编码规范指南：从命名、字段约定到基于 Result 的错误处理体系-平芜编程栈

AI 技能
AI 插件
人工智能

【免费下载链接】agentic-awesome-skills

AAS Core is the local, agent-first control plane for complete catalog discovery, agent-owned selection, stack validation, and planning, backed by 2,600+ agentic skills. Includes CLI, local MCP, catalog, plugins, and Workbench.

项目地址：https://gitcode.com/GitHub_Trending/an/agentic-awesome-skills

点击查看免费下载

本篇指南以 naming-standards.md 为骨架，系统阐述在使用 Avalonia UI 与 Zafiro 工具包进行跨平台开发时强制遵循的命名与编码规范：包括显式命名、Async 后缀禁用、私有字段不加下划线、静态状态规避、方法小型化设计，以及基于 CSharpFunctionalExtensions 的 Result/Maybe 错误处理体系。读完本文，你将掌握一套可直接落地到 Zafiro MVVM 项目中的代码风格基线，并理解其背后与响应式编程（DynamicData/System.Reactive）的协同逻辑。

规范背景：为什么需要统一的命名与编码标准

在 SKILL.md 中，该技能将命名与编码规范定位为"强制性约定"（mandatory conventions），服务于四大核心支柱：Functional-Reactive MVVM（基于 DynamicData 与 ReactiveUI 的纯 MVVM）、Safety & Predictability（用Result类型做显式错误处理、避免用异常做流程控制）、Cross-Platform Excellence（ViewModel 严格与 Avalonia 解耦、组合优于继承）、Zafiro First（优先复用 Zafiro 既有抽象与辅助方法）。

命名规范是这些支柱的"代码层表达"：显式命名降低阅读成本，Async 后缀约定消除异步方法命名噪音，私有字段命名约束让属性/字段边界一目了然，静态状态禁令保障可测试性与可预测性，而 Result/Maybe 约定则直接把"错误是值而非异常"的函数式理念固化进日常编码中。它与 core-technical-skills.md 中"函数式编程、不可变性、内向依赖流"的架构原则一脉相承。

通用命名与编码规范

规范的第一部分规定了适用于整个代码库的基础性命名与设计规则：

显式命名（Explicit Names）：优先选择清晰直白的名称，而不是"聪明"的缩写或隐晦表达。可读性（clarity）始终高于技巧性（cleverness），这也是后续所有规范的底层价值观。
禁用 Async 后缀（Async Suffix）：即使方法返回Task，也不得在方法名中使用Async后缀。这是 .NET 生态中一种常见的代码风格选择（与部分团队约定相反），其意图是让调用方不依赖命名后缀来推断异步性，而是通过返回类型Task/ValueTask与await语义本身来感知，从而保持命名精炼、统一。
私有字段不加下划线（Private Fields）：禁止为私有字段使用_前缀。这意味着项目采用"裸字段命名"风格（例如private int count;而非private int _count;），字段与局部变量在命名形式上一致，配合显式命名约定保证可区分性。
规避静态状态（Static State）：除非有明确理由并已文档化（explicitly justified and documented），否则避免使用静态状态。静态可变状态会引入隐藏的全局耦合、破坏测试隔离并放大并发问题，这与该技能追求的可预测性、可测试性直接冲突。
方法设计（Method Design）：方法应保持短小、富有表现力、低圈复杂度（low cyclomatic complexity）。小方法意味着单一职责与高可读性，也更容易被组合与单元测试覆盖。

规范落地示例

结合规范，一个符合标准的 Zafiro ViewModel 片段应形如：

public class ProjectListViewModel { private readonly IProjectService projectService; // 无下划线前缀 private readonly SourceCache<ProjectModel, int> projectsCache; public ProjectListViewModel(IProjectService projectService) { this.projectService = projectService; projectsCache = new SourceCache<ProjectModel, int>(model => model.Id); } // 即使内部是异步操作，也不使用 Async 后缀 public IObservable<IChangeSet<ProjectModel, int>> Connect() { return projectsCache.Connect(); } // 返回 Task 的方法同样遵循无 Async 后缀约定 public Task Load() { return projectService.GetProjects(); } }

错误处理规范：Result 优先、异常仅限极端情况

错误处理是本规范的核心章节，它把"函数式错误处理"确立为项目的强制模式：

Result 与 Maybe（Result & Maybe）：流程控制与错误处理必须使用CSharpFunctionalExtensions库中的类型。Result用于表示"成功携带值 / 失败携带错误信息"的操作结果，Maybe用于表示可空值的存在性语义，二者都是"把错误与缺失建模为值"的典型函数式做法。
异常仅限真正异常（Exceptions）：异常被严格保留给真正异常、不可恢复（truly exceptional, unrecoverable）的情形，例如进程级故障、基础设施不可用等。可预期的业务失败（校验失败、加载失败、权限不足）一律走Result通道，绝不通过抛出/捕获异常来做流程分支。
边界隔离（Boundaries）：绝不允许异常跨架构边界泄漏（Never allow exceptions to leak across architectural boundaries）。例如在 MVVM 分层中，ViewModel 与 View 之间、领域层与 UI 层之间的边界必须由Result/Maybe显式承载错误，异常在产生后应尽快被转换为Result或由边界处理器统一收口。

与 Zafiro 响应式体系的配合

该规范与技能中的响应式规则高度协同。在 avalonia-reactive-rules.md 中强调"不得在Subscribe中放置业务逻辑、订阅仅用于副作用"，而错误处理管道正是这一原则的典型应用：不要手写Subscribe去捕获错误，而是用 Zafiro 的HandleErrorsWith把错误直接管道化地送到通知服务。

patterns.md 给出了标准的错误处理管道示例：

LoadProjects.HandleErrorsWith(uiServices.NotificationService, "Could not load projects");

这里HandleErrorsWith(notificationService, message)是 Zafiro 为ReactiveCommand提供的扩展方法（见 zafiro-shortcuts.md 的 Command & Interaction 小节），它自动把命令执行中产生的错误转交给notificationService展示给用户，而错误本身在命令内部正是以Result形式流转的。

Result 流的响应式便捷操作

在响应式管道中处理Result/Maybe时，Zafiro 提供了对应的快捷扩展（同样记录于 zafiro-shortcuts.md），避免重复编写冗长的 Rx 组合：

标准 Rx 写法	Zafiro 快捷方式	语义
`Where(r => r.IsSuccess).Select(r => r.Value)`	`Successes()`	仅放行成功结果并取出值
`Where(r => r.IsFailure).Select(r => r.Error)`	`Failures()`	仅放行失败结果并取出错误
`Where(m => m.HasValue).Select(m => m.Value)`	`Values()`	仅放行有值的 Maybe 并取值
`Where(m => !m.HasValue).ToSignal()`	`Empties()`	仅放行空 Maybe 的"信号"

提示：在编写自定义 Rx 逻辑前，请先检查Zafiro.Reactive.ObservableMixin与Zafiro.CSharpFunctionalExtensions.ObservableExtensions是否已有现成实现（zafiro-shortcuts.md）。

错误处理管道的完整模式

结合 patterns.md 的 Mandatory Validation Pattern，可以看到 Result 思想在动态集合校验中的落地——校验失败被建模为布尔信号，而非抛出异常：

this.ValidationRule( StagesSource .Connect() .FilterOnObservable(stage => stage.IsValid) .IsEmpty(), b => !b, _ => "Stages are not valid") .DisposeWith(Disposables);

其含义是：监听StagesSource集合，仅放行校验无效的项（FilterOnObservable(stage => stage.IsValid)），当"无效项集合为空"这一条件不成立（b => !b）时，触发校验错误并给出消息"Stages are not valid"。这里的DisposeWith(Disposables)负责生命周期管理，对应规范中"订阅应最小化、集中化且仅用于副作用"的要求。

规范执行前的检查流程

该技能在编写代码前强制要求先执行三步检查（SKILL.md 的 Procedure Before Writing Code），这些检查与命名规范共同保证代码风格的一致性：

先搜索（Search First）：在代码库中搜索相似实现或已有的 Zafiro 辅助方法，避免重复造轮子——这也呼应"Zafiro First"支柱与命名规范中"复用优于发明"的精神。
可复用扩展（Reusable Extensions）：若缺少辅助方法，优先提出新的可复用扩展方法，而不是在业务代码中内联复杂逻辑；扩展方法本身同样要遵循显式命名与低圈复杂度的要求。
响应式管道（Reactive Pipelines）：确保集合场景使用 DynamicData 操作符（Connect、Filter、Transform、Sort、Bind、DisposeMany）而非普通 Rx 操作符（avalonia-reactive-rules.md），保持管道"单链可读"。

规范限制与适用前提

需要说明的是，本规范是面向特定团队与技术栈（Avalonia + Zafiro + DynamicData/ReactiveUI）的强制性约定，其适用前提包括：

代码库为 C# / 现代 .NET 技术栈，且已引入CSharpFunctionalExtensions、Zafiro（含Zafiro.Reactive.ObservableMixin、Zafiro.CSharpFunctionalExtensions.ObservableExtensions）等依赖（依赖项细节以实际项目为准）；
团队接受"无 Async 后缀""无下划线字段"这两类在 .NET 社区存在分歧的风格选择，并通过统一规范保证一致性；
该规范不能替代环境特定的验证、测试与专家评审（SKILL.md 的 Limitations 部分），当输入、权限、安全边界或成功标准缺失时应停下来请求澄清。

对于希望深入了解完整技能体系的读者，可以继续阅读同目录下的 avalonia-reactive-rules.md（UI 与响应式规则）、zafiro-shortcuts.md（Rx/Zafiro 快捷映射）以及 patterns.md（RefreshableCollection 等进阶模式），完整技能的入口为 SKILL.md。