SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场modern-csharp-coding-standards

modern-csharp-coding-standards

编程与开发

查看项目

更新于 10-15 12:38

技能介绍

用途

本技能用于在以下场景中提供现代 C# 编码规范指导：编写新的 C# 代码或重构既有代码；为库或服务设计公共 API；优化性能关键路径；用强类型实现领域模型；构建大量使用 async/await 的应用；处理二进制数据、缓冲区或高吞吐场景。

核心原则

  • 默认不可变：使用 record 类型与 init-only 属性。
  • 类型安全：利用可空引用类型与值对象。
  • 现代模式匹配：广泛使用 switch 表达式与模式。
  • 处处异步：优先使用带正确取消支持的异步 API。
  • 零分配模式：在性能关键代码中使用 Span<T> 与 Memory<T>。
  • API 设计：接受抽象，返回适当具体的类型。
  • 组合优于继承：避免抽象基类，优先组合。
  • 值对象用结构体：使用 readonly record struct 表示值对象。

命名约定

  • 命名空间：PascalCase，点分隔，如 MyCompany.MyProduct.Core。
  • 类、record、结构体：PascalCase，如 OrderService、OrderSummary。
  • 接口：I + PascalCase，如 IOrderRepository。
  • 方法：PascalCase，如 GetOrderAsync。
  • 属性：PascalCase，如 OrderDate。
  • 事件：PascalCase，如 OrderCompleted。
  • 公共常量：PascalCase，如 MaxRetryCount。
  • 私有字段：_camelCase，如 _orderRepository。
  • 参数、局部变量：camelCase，如 orderId、totalAmount。
  • 类型参数：T 或 T + PascalCase，如 T、TKey、TValue。
  • 枚举成员：PascalCase，如 OrderStatus.Pending。

异步方法以 Async 结尾，例如 GetOrderAsync、SaveChangesAsync；例外是框架未使用 Async 后缀的事件处理器与接口实现（如 ASP.NET Core 中间件的 InvokeAsync）。布尔值以 is、has、can、should 等前缀命名，如 IsActive、HasOrders、CanDelete。集合使用复数名词，如 Orders、CountsByName。

文件组织

每个顶层类型（类、record、结构体、接口、枚举）应位于各自文件中，文件名与类型名完全一致；嵌套类型保留在包含类型的文件中。始终使用文件作用域命名空间（C# 10+）。using 指令放在文件顶部、命名空间之外；启用 ImplicitUsings 时常见命名空间已自动导入。using 顺序为：System.* 命名空间、第三方命名空间、项目命名空间。

代码风格

控制流始终使用大括号，即使只有单行。单表达式成员使用表达式主体。当右侧类型明显时使用 var，否则显式声明类型。空值处理优先使用模式匹配而非 null 检查，如 order is not null、order is { Status: OrderStatus.Active }、customer?.Name ?? "Unknown"、items ??= []。字符串优先使用插值而非拼接或 string.Format，并可使用原始字符串字面量。始终显式指定访问修饰符，不依赖默认值。修饰符顺序为：访问修饰符 -> static -> extern -> new -> virtual/abstract/override/sealed -> readonly -> volatile -> async -> partial。

类型设计

默认密封类（sealed），除非明确设计为基类；这有助于性能（去虚拟化）并传达意图。优先组合而非继承。保持接口聚焦，优先多个小接口而非一个大接口，例如将 IOrderReader 与 IOrderWriter 分离。

语言与性能模式

技能涵盖：record 用于不可变数据（C# 9+）；值对象用 readonly record struct；模式匹配（C# 8-12）；可空引用类型（C# 8+）；组合优于继承；async/await 最佳实践；Span 与 Memory 用于零分配代码；API 设计原则（接受抽象、返回适当具体类型、方法签名最佳实践）；错误处理（Result 类型模式，即铁路导向编程）。

测试模式

示例展示使用 record 构建器（OrderBuilder）构造测试数据，配合 with 表达式修改；使用 xUnit 的 [Fact]、[Theory]、[InlineData]；使用 FluentAssertions 进行断言，包括异常断言与消息匹配。

CancellationToken 约定

异步方法将 CancellationToken 作为最后一个参数，可选令牌默认值为 default。始终将令牌向下游异步调用传递，绝不忽略收到的 CancellationToken。

XML 文档

为公共 API 表面添加简洁的 XML 文档。不要为私有或内部成员（除非是库的 InternalsVisibleTo API）、自明成员（如 public string Name { get; }）或测试方法添加 XML 文档。

避免基于反射的元编程

技能建议避免 AutoMapper、Mapster 等基于反射的库，改用显式映射方法；对合法的反射需求可使用 UnsafeAccessorAttribute。

应避免的反模式

可变 DTO；用类表示值对象；深层继承层次；暴露可变集合；忘记 CancellationToken；阻塞异步代码；在循环中使用字符串拼接；重复分配大数组（应使用 ArrayPool）。

分析器强制

可在 Directory.Build.props 或 .editorconfig 中配置分析器自动强制规范，例如：

<PropertyGroup> <EnforceCodeStyleInBuild>true</EnforceCodeStyleInBuild> <AnalysisLevel>latest-all</AnalysisLevel> <TreatWarningsAsErrors>true</TreatWarningsAsErrors> </PropertyGroup>

关键 .editorconfig 规则示例：

[*.cs] csharp_style_namespace_declarations = file_scoped:warning csharp_prefer_braces = true:warning csharp_style_var_for_built_in_types = true:suggestion csharp_style_var_when_type_is_apparent = true:suggestion dotnet_style_require_accessibility_modifiers = always:warning csharp_style_prefer_pattern_matching = true:suggestion

最佳实践摘要

推荐：DTO、消息与领域实体使用 record；值对象使用 readonly record struct；利用 switch 表达式进行模式匹配；启用并遵守可空引用类型；所有 I/O 使用 async/await；所有异步方法接受 CancellationToken；高性能场景使用 Span<T> 与 Memory<T>；接受抽象（IEnumerable<T>、IReadOnlyList<T>）；返回合适的接口或具体类型；预期错误使用 Result<T, TError>；库代码使用 ConfigureAwait(false)；大分配使用 ArrayPool<T> 池化缓冲区；优先组合而非继承；应用代码避免抽象基类。

避免：record 可用时使用可变类；用类表示值对象；深层继承层次；忽略可空引用类型警告；阻塞异步代码（.Result、.Wait()）；Span<byte> 足够时使用 byte[]；忘记 CancellationToken 参数；从 API 返回可变集合；对预期业务错误抛出异常；循环中字符串拼接；重复分配大数组。

知识来源与资源

规范基于公开内容，包括 Microsoft Framework Design Guidelines（.NET 命名、类型设计与 API 表面约定的权威参考）以及 C# 语言设计说明（Mads Torgersen 等），涉及文件作用域命名空间、模式匹配优于类型检查、required 成员、var 使用指南等设计理由。

附加资源链接：

  • C# 语言规范：https://learn.microsoft.com/en-us/dotnet/csharp/
  • 模式匹配：https://learn.microsoft.com/en-us/dotnet/csharp/fundamentals/functional/pattern-matching
  • Span 与 Memory：https://learn.microsoft.com/en-us/dotnet/standard/memory-and-spans/
  • 异步最佳实践：https://learn.microsoft.com/en-us/archive/msdn-magazine/2013/march/async-await-best-practices-in-asynchronous-programming
  • .NET 性能提示：https://learn.microsoft.com/en-us/dotnet/framework/performance/
  • C# 编码约定：https://learn.microsoft.com/en-us/dotnet/csharp/fundamentals/coding-style/coding-conventions
  • C# 标识符命名规则：https://learn.microsoft.com/en-us/dotnet/csharp/fundamentals/coding-style/identifier-names
  • .NET 的 .editorconfig：https://learn.microsoft.com/en-us/dotnet/fundamentals/code-analysis/code-style-rule-options

限制

资料未提供该技能的安装命令、收费方式、支持平台或具体版本要求，这些信息暂未提供。