深入理解 SemaphoreSlim 在.NET Core API 開發中的應用

什么是 SemaphoreSlim

SemaphoreSlim 的核心方法

構造函數

等待方法

釋放方法

基本使用模式

同步使用模式

異步使用模式（推薦在 API 中使用）

在 Web 開發中的常見用途

1. 限制 API 接口的并發請求數

2. 保護共享資源的并發訪問

3. 控制外部服務的調用頻率

4. 實現分布式鎖的本地補充

注意事項與最佳實踐

1. 確保正確釋放信號量

2. 合理設置信號量的生命周期

3. 避免過度限制并發

4. 注意異步操作中的取消機制

5. 警惕死鎖風險

6. 結合限流中間件使用

7. 多實例部署的局限性

總結

在.NET Core API 開發中，并發控制是保證系統穩定性和數據一致性的關鍵環節。當多個請求同時訪問共享資源時，若不加以控制，很容易引發數據錯亂、性能下降等問題。SemaphoreSlim作為.NET 框架中輕量級的信號量實現，為我們提供了簡單而高效的并發控制方案。本文將詳細介紹 SemaphoreSlim 的工作原理、使用方法以及在 Web 開發中的常見應用場景。

什么是 SemaphoreSlim

SemaphoreSlim 是.NET Framework 4.0 引入的輕量級信號量類，位于System.Threading命名空間下。它專為短期等待場景設計，相比傳統的Semaphore類，具有更低的系統開銷和更高的性能。

信號量的核心作用是限制同時訪問某個資源的并發數量。可以將其理解為一個帶計數器的門控機制：當計數器大于 0 時，允許線程進入并將計數器減 1；當計數器為 0 時，后續線程必須等待直到有線程釋放資源（計數器加 1）。

與傳統 Semaphore 相比，SemaphoreSlim 的優勢在于：

不依賴操作系統內核對象，減少了用戶態與內核態之間的切換開銷

支持異步等待（WaitAsync方法），非常適合異步 API 開發

內存占用更小，創建和銷毀的成本更低

支持取消令牌（CancellationToken），便于實現超時控制和操作取消

SemaphoreSlim 的核心方法

SemaphoreSlim 提供了一組簡潔而強大的方法來實現并發控制，掌握這些方法是正確使用 SemaphoreSlim 的基礎：

構造函數

// 初始化一個可同時允許maxCount個線程訪問的信號量
public SemaphoreSlim(int initialCount);
public SemaphoreSlim(int initialCount, int maxCount);

initialCount：信號量的初始計數，即初始允許的并發數量

maxCount：信號量的最大計數，規定了允許的最大并發數量

等待方法

// 同步等待，直到信號量可用
public void Wait();
public bool Wait(int millisecondsTimeout);
public bool Wait(TimeSpan timeout);
public void Wait(CancellationToken cancellationToken);// 異步等待，適合異步方法中使用
public Task WaitAsync();
public Task<bool> WaitAsync(int millisecondsTimeout);
public Task<bool> WaitAsync(TimeSpan timeout);
public Task WaitAsync(CancellationToken cancellationToken);

等待方法的作用是申請訪問權限：當調用這些方法時，線程會嘗試獲取信號量。如果當前計數大于 0，計數減 1 并立即返回；否則，線程會進入等待狀態，直到有其他線程釋放信號量或等待超時 / 被取消。

釋放方法

// 釋放信號量，增加計數
public void Release();
public int Release(int releaseCount);

釋放方法用于歸還訪問權限：當線程完成對共享資源的訪問后，應調用Release方法將信號量計數加 1，允許其他等待的線程獲取訪問權限。Release(int releaseCount)可以一次釋放多個計數，但釋放的總數不能超過maxCount。

基本使用模式

使用 SemaphoreSlim 的核心原則是 **"先等待，后訪問，最后釋放"**，通常遵循以下模式：

同步使用模式

// 創建一個最多允許3個并發訪問的信號量
private static readonly SemaphoreSlim _semaphore = new SemaphoreSlim(3);public void AccessResource()
{try{// 等待獲取信號量_semaphore.Wait();// 訪問共享資源的邏輯UseSharedResource();}finally{// 釋放信號量，必須放在finally中確保一定會執行_semaphore.Release();}
}

異步使用模式（推薦在 API 中使用）

private static readonly SemaphoreSlim _semaphore = new SemaphoreSlim(3);public async Task AccessResourceAsync()
{try{// 異步等待獲取信號量await _semaphore.WaitAsync();// 異步訪問共享資源的邏輯await UseSharedResourceAsync();}finally{// 釋放信號量_semaphore.Release();}
}

在 Web 開發中的常見用途

在.NET Core API 開發中，SemaphoreSlim 有多種實用場景，尤其適合處理那些需要限制并發量的操作：

1. 限制 API 接口的并發請求數

當 API 接口調用涉及到資源密集型操作（如復雜計算、大數據處理）時，無限制的并發可能導致服務器資源耗盡。使用 SemaphoreSlim 可以限制同時處理的請求數量：

[ApiController]
[Route("api/[controller]")]
public class DataProcessorController : ControllerBase
{// 限制最多5個并發請求private static readonly SemaphoreSlim _processorSemaphore = new SemaphoreSlim(5);[HttpPost("process")]public async Task<IActionResult> ProcessData([FromBody] DataRequest request){try{// 等待獲取處理權限，設置5秒超時if (!await _processorSemaphore.WaitAsync(5000)){return StatusCode(StatusCodes.Status429TooManyRequests, "當前請求過多，請稍后再試");}// 處理數據var result = await DataProcessor.ProcessAsync(request);return Ok(result);}finally{_processorSemaphore.Release();}}
}

2. 保護共享資源的并發訪問

當多個請求需要訪問同一個共享資源（如文件、非線程安全的服務實例）時，SemaphoreSlim 可以確保資源操作的原子性：

public class FileService
{private readonly SemaphoreSlim _fileAccessSemaphore = new SemaphoreSlim(1);private readonly string _filePath = "data.json";public async Task UpdateFileAsync(string content){await _fileAccessSemaphore.WaitAsync();try{// 讀取當前內容var currentContent = await File.ReadAllTextAsync(_filePath);// 處理內容var newContent = ProcessContent(currentContent, content);// 寫入新內容await File.WriteAllTextAsync(_filePath, newContent);}finally{_fileAccessSemaphore.Release();}}
}

3. 控制外部服務的調用頻率

調用第三方 API 時，通常會有頻率限制（Rate Limiting）。使用 SemaphoreSlim 可以控制并發調用數量，避免觸發限制：

public class ExternalApiClient
{private readonly HttpClient _httpClient;// 根據第三方API的限制設置并發數private readonly SemaphoreSlim _apiSemaphore = new SemaphoreSlim(10);private readonly int _apiTimeoutMs = 3000;public ExternalApiClient(HttpClient httpClient){_httpClient = httpClient;}public async Task<TResult> CallApiAsync<TResult>(string endpoint){try{// 等待獲取調用權限if (!await _apiSemaphore.WaitAsync(_apiTimeoutMs)){throw new TimeoutException("等待調用第三方API超時");}// 調用外部APIvar response = await _httpClient.GetAsync(endpoint);response.EnsureSuccessStatusCode();return await response.Content.ReadFromJsonAsync<TResult>();}finally{_apiSemaphore.Release();}}
}

4. 實現分布式鎖的本地補充

在分布式系統中，雖然需要分布式鎖（如 Redis 鎖）來跨實例同步，但結合 SemaphoreSlim 可以減少分布式鎖的競爭：

public class DistributedTaskService
{private readonly IDistributedLock _distributedLock;// 每個實例最多處理2個任務，減少分布式鎖競爭private readonly SemaphoreSlim _localSemaphore = new SemaphoreSlim(2);public async Task ExecuteTaskAsync(string taskId){// 先獲取本地信號量，減少分布式鎖的競爭await _localSemaphore.WaitAsync();try{// 再獲取分布式鎖using (var lockResult = await _distributedLock.AcquireLockAsync(taskId)){if (lockResult.Success){await ProcessTaskAsync(taskId);}}}finally{_localSemaphore.Release();}}
}

注意事項與最佳實踐

雖然 SemaphoreSlim 使用簡單，但在實際應用中仍需注意以下幾點，以避免常見問題：

1. 確保正確釋放信號量

最常見的錯誤是忘記釋放信號量或在異常情況下未能釋放，這會導致信號量計數永遠無法恢復，最終所有請求都陷入無限等待。因此，務必將Release調用放在finally塊中，確保無論是否發生異常都會執行。

2. 合理設置信號量的生命周期

在 Web 應用中，SemaphoreSlim 通常應聲明為static或使用單例模式，以確保它在應用生命周期內保持狀態。如果每次請求都創建新的 SemaphoreSlim 實例，將失去并發控制的作用。

// 正確：靜態字段，應用域內共享
private static readonly SemaphoreSlim _semaphore = new SemaphoreSlim(5);// 錯誤：每次實例化都會創建新的信號量
public class MyController : ControllerBase
{private readonly SemaphoreSlim _badSemaphore = new SemaphoreSlim(5);// ...
}

3. 避免過度限制并發

信號量的作用是 "限制" 而非 "禁止" 并發，設置過小的并發數會導致系統吞吐量下降。應根據實際負載測試結果，結合服務器資源（CPU、內存、IO 等）合理設置最大并發數。

4. 注意異步操作中的取消機制

在異步場景中，建議使用帶CancellationToken的WaitAsync重載，以便在請求被取消（如客戶端斷開連接）時能夠及時釋放資源：

// 結合HTTP請求的取消令牌
public async Task<IActionResult> MyAction()
{try{// 使用RequestAborted令牌await _semaphore.WaitAsync(ControllerContext.HttpContext.RequestAborted);// ...}finally{_semaphore.Release();}
}