mi-assessment/docs/开发规范/1-编程规约/1.4-多线程与异步规范.md

1.4 多线程与异步规范

本规范旨在指导 .NET 中的多线程与异步编程，确保代码的高效性、稳定性和可维护性，避免常见的死锁、线程饥饿和竞态条件问题。

1. 异步编程 (Async/Await)

1.1 避免 async void

• 规则：严禁使用 async void，唯一的例外是事件处理程序 (Event Handlers)。
• 理由：
  • async void 方法无法被等待 (await)。
  • async void 方法中抛出的异常无法被调用方捕获，会导致进程崩溃（除非在 SynchronizationContext 中捕获）。
  • 难以测试和组合。
• 反例 :

  // ❌ [不推荐] 使用 async void，异常无法被外部捕获
  private async void ExecuteAsync(object obj)
  {
      try 
      {
          await _jobPerformer.Perform(...);
      }
      catch (Exception e) 
      {
          // 必须在内部吞掉所有异常，否则进程崩溃
          Console.WriteLine(e); 
      }
  }
  

• 正例：

  // ✅ [推荐] 返回 Task，允许调用方等待和处理异常
  private async Task ExecuteAsync(object obj)
  {
      try 
      {
          await _jobPerformer.Perform(...);
      }
      catch (Exception e) 
      {
          _logger.LogError(e, "Error occurred");
      }
  }
  

1.2 异步全链路 (Async All the Way)

• 规则：一旦开始使用异步，应在整个调用链路中保持异步。
• 理由：避免同步/异步混合导致的死锁（Sync-over-Async）和线程池饥饿。
• 反例：

  // ❌ [禁止] 在异步方法中阻塞等待
  public void DoSomething()
  {
      DoSomethingAsync().Result; // 或者 .Wait()
  }
  

• 正例：

  // ✅ [推荐] 使用 await
  public async Task DoSomething()
  {
      await DoSomethingAsync();
  }
  

1.3 库代码使用 ConfigureAwait(false)

• 规则：在通用类库 (非 UI 层、非 ASP.NET Core Controller 层) 代码中，应使用 .ConfigureAwait(false)。
• 理由：避免在不需要特定 SynchronizationContext (如 UI 线程) 的情况下强制切回原上下文，提高性能并减少死锁风险。
• 注意：在 ASP.NET Core 应用层代码中通常不需要，因为 ASP.NET Core 没有 SynchronizationContext。但在编写底层 SDK (如 Aegis.Caching) 时必须遵守。
• 正例：

  // ✅ [推荐] 类库代码
  public async Task<string> GetDataAsync()
  {
      var result = await _httpClient.GetStringAsync(url).ConfigureAwait(false);
      return result;
  }
  

1.4 传入 CancellationToken

• 规则：异步方法应尽可能支持 CancellationToken，以便在操作不再需要时取消。
• 正例：

  // ✅ [推荐] 支持取消
  public async Task ProcessAsync(CancellationToken cancellationToken = default)
  {
      while (!cancellationToken.IsCancellationRequested)
      {
          await Task.Delay(1000, cancellationToken);
          // ... 业务逻辑
      }
  }
  

2. 线程与任务 (Threads & Tasks)

2.1 优先使用 Task 而非 Thread

• 规则：使用 Task.Run 或 Task.Factory.StartNew (带有 TaskCreationOptions.LongRunning)，尽量避免直接 new Thread()。
• 理由：Task 基于线程池，资源利用率更高，且 API 更易于组合和异常处理。
• 例外：需要设置线程优先级、名称或必须是前台线程的特殊场景。

2.2 避免长时间阻塞线程池线程

• 规则：如果任务是 CPU 密集型且运行时间很长，应指定 TaskCreationOptions.LongRunning，或者使用独立的线程，避免耗尽线程池导致吞吐量下降。

3. 线程安全与锁 (Locking)

3.1 锁的选择

• 规则：

  • 同步代码：首选 lock (即 Monitor)。
  • 异步代码：必须使用 SemaphoreSlim，严禁在 lock 块中使用 await。
  • 高性能/轻量级：Interlocked 用于简单的计数器或原子交换。
  • 自旋锁：慎用 SpinLock 或 SpinWait，除非非常短的临界区且你非常清楚自己在做什么。 建议：对于大多数业务场景，普通的 lock 或 SemaphoreSlim 足够且更安全。除非经过 Benchmark 证明必须使用自旋锁。

• 正例 (异步锁)：

  private readonly SemaphoreSlim _lock = new SemaphoreSlim(1, 1);
  
  public async Task SafeOperationAsync()
  {
      await _lock.WaitAsync();
      try
      {
          // ✅ 可以在锁内 await
          await DoSomethingAsync();
      }
      finally
      {
          _lock.Release();
      }
  }
  

3.2 线程安全的集合

• 规则：在多线程环境下读写集合，应使用 System.Collections.Concurrent 命名空间下的集合 (如 ConcurrentDictionary, ConcurrentQueue)，而不是手动加锁的 List 或 Dictionary。
• 正例：

  private readonly ConcurrentDictionary<string, User> _cache = new();
  
  public void AddUser(User user)
  {
      // ✅ 线程安全
      _cache.TryAdd(user.Id, user);
  }
  

3.3 静态成员的线程安全

• 规则：静态成员 (Static Members) 在多线程环境下是共享的，必须保证其线程安全。
• 建议：
  • 尽量设计为不可变 (Immutable)。
  • 如果必须可变，使用 lock 或 Concurrent 类型保护。

4. 并行处理 (Parallel)

4.1 控制并发度

• 规则：使用 Parallel.ForEach 或 Task.WhenAll 时，必须控制并发数量 (MaxDegreeOfParallelism)，防止瞬间并发过高压垮下游服务 (数据库、Redis、外部 API)。
• 正例：

  var options = new ParallelOptions { MaxDegreeOfParallelism = 5 };
  await Parallel.ForEachAsync(items, options, async (item, token) =>
  {
      await ProcessItemAsync(item, token);
  });
  

4.2 避免 Parallel 里的共享状态写入

• 规则：避免在并行循环中写入共享变量，这通常是非线程安全的。应使用线程局部变量或并发集合。

5. 最佳实践总结

1. 不要阻塞异步代码：避免 .Result, .Wait()。
2. 异常处理：Task 中的异常会被包装在 AggregateException 中 (如果使用 .Result 或 .Wait())，但在 await 时会解包抛出第一个异常。建议始终使用 await。
3. 避免线程饥饿：不要在线程池线程中执行长时间的同步 IO 操作。
4. 不可变性：尽可能设计不可变对象，天然线程安全。