====== 框架 ======

.net  读 dot net

<code csharp>
using System ; //引用头文件
namespace 控制台 ; //命名空间 【Program的命名空间就是：控制台】
   class Program ; //class 用于声明一个类
</code>

使用中建议、类名称与文件名保持一样	尽量一个类一个文件

====== 一、命名规范 ======

===== 1. 大小写风格 =====

  * **PascalCase**
    * 用于：类、接口、结构、枚举、属性、方法、事件、命名空间
    * 例：''OrderService''、''GetUserInfo()''、''UserName''
  * **camelCase**
    * 用于：参数、局部变量
    * 例：''userId'', ''totalCount''
  * **带下划线camelCase**
    * 用于：私有字段（Roslyn、.NET Runtime 推荐）
    * 例：''_logger'', ''_cache''
  * **SCREAMING_CASE**
    * 用于：常量、''static readonly'' 字段
    * 例：''DEFAULT_BUFFER_SIZE'';

===== 2. 接口命名 =====

  * 接口必须以 **I** 开头
  * 示例：''IList'', ''ILoggerFactory''

===== 3. 枚举命名 =====

  * 枚举成员：PascalCase
  * 不使用前缀（如 ''Enum_''）
<code csharp>
enum FileState { Open, Closed, Locked }
</code>

===== 4. 命名空间 =====

  * PascalCase
  * 公司或组织级前缀
  * 示例：''Microsoft.Extensions.Logging''

----

====== 二、代码布局与格式 ======

===== 1. 缩进与空白 =====

  * '', ; { }'' 后加空格；方法调用括号内无空格
<code csharp>
DoWork(item, index);
</code>

===== 2. 大括号（Brace）风格 =====

使用 Allman 风格（每个 ''{'' 独占一行）：
<code csharp>
public void Run()
{
    ...
}
</code>

===== 3. 空行规则 =====

  * 成组代码块之间使用 1 行空行
  * 方法之间留 1 行空行
  * 不要连续多个空行

----

====== 三、成员排序（微软推荐顺序） ======

类内部成员推荐顺序：

  - 常量
  - 静态字段
  - 字段
  - 构造函数
  - 属性
  - 事件
  - 方法
  - 嵌套类型

<code csharp>
# region 常量

# endregion

# region 静态字段 

# endregion

# region 字段

# endregion

# region 构造函数 

# endregion

# region 属性 

# endregion

# region 事件 

# endregion

# region 方法 

# endregion

# region 嵌套类型

# endregion
</code>

----

====== 四、表达式与语言特性 ======

===== 1. var 使用 =====

  * 仅当类型明确或无关紧要时使用 var
<code csharp>
var list = new List<int>();  // 类型明显
</code>
  * 如果不明显，使用显式类型：
<code csharp>
int count = GetCount();
</code>

===== 2. 表达式体成员 =====

  * 适用于简单成员：
<code csharp>
public int Count => _items.Count;
public override string ToString() => Name;
</code>

===== 3. Lambda 风格 =====

  * 简短 lambda 可在一行
  * 多行 lambda 保持缩进
<code csharp>
items.Where(x =>
{
    return x.Enabled;
});
</code>

----

====== 五、可读性规范 ======

===== 1. 方法长度 =====

  * 尽量短小，一个方法保持单一职责

===== 2. 参数顺序 =====

  * 必选参数在前，可选参数在后
  * ''CancellationToken'' 必须是最后一个参数：
<code csharp>
public Task RunAsync(int id, CancellationToken cancellationToken);
</code>

===== 3. 布尔命名 =====

  * 使用肯定句：''isReady'', ''hasValue'', ''canExecute''
  * 避免：''isNotValid'', ''noItems''

----

====== 六、注释规范 ======

===== 1. 文档注释 XML =====

公共 API 必须有 XML 注释：
<code csharp>
/// <summary>
/// 获取用户信息。
/// </summary>
public User GetUser(int id) { ... }
</code>

===== 2. 行注释 =====

只用于解释复杂逻辑，避免写显而易见的注释。

----

====== 七、异常与错误处理 ======

===== 1. 异常名称 =====

继承 Exception 且名称以 Exception 结尾
<code csharp>
class InvalidConfigurationException : Exception { }
</code>

===== 2. 不要使用异常控制流程 =====

避免：
<code csharp>
try { ... } catch { ... } // 控制逻辑
</code>
异常应该保留给意外情况，而不是正常控制流程。

因为异常的代价比较高

----

====== 八、文件与项目结构 ======

===== 1. 每个类型单独一个文件 =====

除非：
  * 小型私有辅助类
  * 局部类型

===== 2. 文件命名 =====

文件名与主类名一致：
<code text>
OrderService.cs
</code>

===== 3. using 指令 =====

按以下顺序分组——每组之间空一行：

  - System.* 命名空间
  - 第三方包
  - 当前项目命名空间

示例：
<code csharp>
using System;
using System.Collections.Generic;

using Newtonsoft.Json;

using MyApp.Core;
</code>

----

====== 九、异步编程规范（微软官方 async 规则） ======

===== 1. 异步方法必须以 Async 结尾 =====

<code csharp>
public Task SaveAsync();
</code>

===== 2. 仅在使用 await 时将方法标记为 async =====

===== 3. ConfigureAwait =====

库代码中使用：
<code csharp>
await task.ConfigureAwait(false);
</code>

----

====== 十、不可变性与集合规范 ======

===== 1. 优先使用只读字段 =====

<code csharp>
private readonly ILogger _logger;
</code>

===== 2. 公开集合使用 IReadOnlyList / IEnumerable =====

避免暴露可变集合类型。