C#大師秘笈：優雅封裝外部API的終極指南

哈囉，親愛的程式碼魔法師們！今天，讓我們一同踏上一段奇妙的旅程，探索如何用C#優雅地封裝外部API調用。無論你是剛入門的小鮮肉，還是經驗豐富的老司機，這篇文章都能讓你的程式碼更上一層樓。準備好你的鍵盤，我們要開始施展魔法了！🧙‍♂️✨

1. 為什麼要封裝外部API？

想像一下，如果你的程式碼是一個精美的壽司餐廳，外部API就是你的食材供應商。你會直接把整條鮪魚放在客人面前嗎？當然不會！你需要把它處理成美味可口的握壽司。封裝外部API就是這個道理，它能：

提高程式碼的可讀性：告別雜亂無章的HTTP請求
增強可維護性：API改變時，只需修改一處程式碼
提升可測試性：更容易模擬（mock）API回應
統一錯誤處理：不用到處捕捉異常
方便添加額外功能：輕鬆加入重試、日誌等功能

2. 打造堅實地基：API客戶端類別

首先，我們要創建一個專門的API客戶端類別，就像是蓋房子要先打地基一樣。這個類別將是我們所有API操作的大本營。

public class SuperDuperApiClient
{
    private readonly HttpClient _httpClient;
    private readonly string _apiKey;
    private readonly string _baseUrl;

    public SuperDuperApiClient(HttpClient httpClient, IOptions<SuperDuperApiOptions> options)
    {
        _httpClient = httpClient;
        _apiKey = options.Value.ApiKey;
        _baseUrl = options.Value.BaseUrl;
        
        _httpClient.DefaultRequestHeaders.Add("Authorization", $"Bearer {_apiKey}");
        _httpClient.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));
    }

    // 這裡將是我們的API方法大本營
}

看！這就是我們的API客戶端類別，它就像是一個有專業執照的外賣員，隨時準備幫我們送外賣（呼叫API）。

3. 添加調味料：實現API方法

現在，讓我們來實現一些具體的API方法，就像在壽司上添加美味的調味料一樣：

public class SuperDuperApiClient
{
    // ... 前面的程式碼 ...

    public async Task<UserInfo> GetUserInfoAsync(int userId)
    {
        var response = await _httpClient.GetAsync($"{_baseUrl}/users/{userId}");
        response.EnsureSuccessStatusCode();
        var content = await response.Content.ReadAsStringAsync();
        return JsonConvert.DeserializeObject<UserInfo>(content);
    }

    public async Task<bool> UpdateUserInfoAsync(int userId, UserInfo userInfo)
    {
        var content = new StringContent(JsonConvert.SerializeObject(userInfo), Encoding.UTF8, "application/json");
        var response = await _httpClient.PutAsync($"{_baseUrl}/users/{userId}", content);
        return response.IsSuccessStatusCode;
    }
}

瞧！這就像是我們菜單上的兩道招牌菜：「取得用戶資訊」和「更新用戶資訊」。每次客人點餐，我們都能快速準備好。

4. 秘製醬料：錯誤處理和重試機制

一個優秀的廚師總是有獨特的秘製醬料。在API調用中，我們的「秘製醬料」就是錯誤處理和重試機制：

public async Task<T> ExecuteWithRetry<T>(Func<Task<T>> action, int maxRetries = 3)
{
    for (int i = 0; i < maxRetries; i++)
    {
        try
        {
            return await action();
        }
        catch (HttpRequestException ex) when (i < maxRetries - 1)
        {
            await Task.Delay(1000 * (i + 1));  // 指數退避
            Console.WriteLine($"哎呀！第{i+1}次嘗試失敗，再試一次！");
        }
    }
    throw new Exception($"嘗試{maxRetries}次後仍然失敗，看來外賣員罷工了...");
}

public async Task<UserInfo> GetUserInfoWithRetryAsync(int userId)
{
    return await ExecuteWithRetry(() => GetUserInfoAsync(userId));
}

這個「秘製醬料」能讓我們的API調用更加健壯，就像給壽司添加了美味又風趣的芥末一樣！

5. 擺盤：使用選項模式進行配置

一個好的擺盤能讓美食更加賞心悅目。在程式設計中，我們可以使用選項模式來「擺盤」：

public class SuperDuperApiOptions
{
    public string ApiKey { get; set; }
    public string BaseUrl { get; set; }
}

// 在Startup.cs中
public void ConfigureServices(IServiceCollection services)
{
    services.Configure<SuperDuperApiOptions>(Configuration.GetSection("SuperDuperApi"));
    services.AddHttpClient<SuperDuperApiClient>();
}

這樣，我們的「菜單」就能根據不同的「用餐環境」（開發、測試、生產）靈活調整了。

6. 獨一無二的主廚：Singleton 模式

在一家頂級餐廳，通常只有一位主廚掌控全局。同樣地，有時我們希望整個應用程序中只有一個 API 客戶端實例。這就是 Singleton 模式派上用場的時候了！

6.1 為什麼要使用 Singleton？

想像一下，如果每個服務生都自己跑到廚房煮菜，那餐廳不就大亂了嗎？使用 Singleton 可以：

控制資源使用：只維護一個 HttpClient 實例，有效管理連接池。
保證一致性：所有的 API 調用都通過同一個實例，確保設定一致。
提高效能：避免重複創建和銷毀 API 客戶端實例的開銷。

6.2 實現一個線程安全的 Singleton API 客戶端

public sealed class SuperDuperApiClient
{
    private static readonly Lazy<SuperDuperApiClient> _instance 
        = new Lazy<SuperDuperApiClient>(() => new SuperDuperApiClient());
    
    private readonly HttpClient _httpClient;
    private readonly string _apiKey;
    private readonly string _baseUrl;

    private SuperDuperApiClient()
    {
        // 從配置中讀取 API 密鑰和基礎 URL
        var configuration = new ConfigurationBuilder()
            .SetBasePath(Directory.GetCurrentDirectory())
            .AddJsonFile("appsettings.json")
            .Build();

        _apiKey = configuration["SuperDuperApi:ApiKey"];
        _baseUrl = configuration["SuperDuperApi:BaseUrl"];

        _httpClient = new HttpClient();
        _httpClient.DefaultRequestHeaders.Add("Authorization", $"Bearer {_apiKey}");
        _httpClient.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));
    }

    public static SuperDuperApiClient Instance => _instance.Value;

    // API 方法保持不變
    public async Task<UserInfo> GetUserInfoAsync(int userId)
    {
        // 實現與之前相同
    }

    // 其他方法...
}

6.3 如何使用我們的 Singleton API 客戶端

現在，無論在哪裡需要使用 API 客戶端，我們都可以這樣調用：

public class UserService
{
    public async Task<UserInfo> GetUserAsync(int userId)
    {
        return await SuperDuperApiClient.Instance.GetUserInfoAsync(userId);
    }
}

這就像是整個餐廳的所有點單都通過同一個主廚來處理，確保了菜品的一致性和高效率！

6.4 Singleton 的注意事項

但是，就像一個主廚也有可能累壞一樣，Singleton 模式也有它的局限性：

測試難度增加：因為狀態是全局的，單元測試可能變得複雜。
隱藏依賴關係：使用 Singleton 可能使得類別之間的依賴關係不那麼明顯。

所以，在決定使用 Singleton 時，要像挑選主廚一樣慎重！

7. 品質管控：單元測試

任何一家高級餐廳都有嚴格的品質控管，我們的API客戶端也不例外。讓我們來寫幾個單元測試：

public class SuperDuperApiClientTests
{
    [Fact]
    public async Task GetUserInfoAsync_ShouldReturnUserInfo_WhenUserExists()
    {
        // Arrange
        var mockHttp = new MockHttpMessageHandler();
        var client = mockHttp.ToHttpClient();
        var options = Options.Create(new SuperDuperApiOptions { ApiKey = "test", BaseUrl = "http://api.test" });
        var apiClient = new SuperDuperApiClient(client, options);

        mockHttp.When("http://api.test/users/1")
                .Respond("application/json", "{\"id\":1,\"name\":\"Test User\"}");

        // Act
        var result = await apiClient.GetUserInfoAsync(1);

        // Assert
        Assert.Equal(1, result.Id);
        Assert.Equal("Test User", result.Name);
    }
}

這就像是我們餐廳的試吃環節，確保每道菜都美味可口！

8. 擴展功能：使用裝飾器模式

有時候，我們可能想要為某些特定的API調用添加額外的功能，比如特殊的日誌記錄。這時候，裝飾器模式就派上用場了：

public class LoggingApiClientDecorator : ISuperDuperApiClient
{
    private readonly ISuperDuperApiClient _innerClient;
    private readonly ILogger<LoggingApiClientDecorator> _logger;

    public LoggingApiClientDecorator(ISuperDuperApiClient innerClient, ILogger<LoggingApiClientDecorator> logger)
    {
        _innerClient = innerClient;
        _logger = logger;
    }

    public async Task<UserInfo> GetUserInfoAsync(int userId)
    {
        _logger.LogInformation($"正在獲取用戶 {userId} 的資訊");
        var result = await _innerClient.GetUserInfoAsync(userId);
        _logger.LogInformation($"成功獲取用戶 {userId} 的資訊");
        return result;
    }

    // 其他方法也類似處理...
}

這就像是給我們的壽司添加了特殊的裝飾，既美觀又實用！

9. 效能調校：非同步和並行處理

在繁忙的用餐時段，我們需要同時處理多個訂單。同樣地，當需要調用多個API時，我們可以使用非同步和並行處理來提升效能：

public async Task<List<UserInfo>> GetMultipleUsersInfoAsync(List<int> userIds)
{
    var tasks = userIds.Select(id => GetUserInfoAsync(id));
    return await Task.WhenAll(tasks);
}

這就像是餐廳裡的多個廚師同時工作，大大提高了出餐速度！

10. 安全性：別忘了防護措施

就像餐廳需要遵守食品安全法規一樣，我們的API客戶端也需要注意安全性：

public class SuperDuperApiClient
{
    // ... 其他程式碼 ...

    private void ValidateApiResponse(HttpResponseMessage response)
    {
        if (response.StatusCode == System.Net.HttpStatusCode.Unauthorized)
        {
            throw new UnauthorizedAccessException("噢不！你的 API 金鑰可能過期了。");
        }
        if (response.StatusCode == System.Net.HttpStatusCode.Forbidden)
        {
            throw new UnauthorizedAccessException("哇哦，看來你沒有權限使用這個 API。");
        }
        // 其他狀態碼檢查...
    }
}

這樣，我們就能及時發現並處理各種可能的安全問題，就像餐廳的食品安全檢查一樣重要！

11. 總結：成為API封裝大師

讓我們用一個漂亮的表格來總結我們學到的重點吧：

技巧	說明	好處
創建API客戶端類別	集中管理所有API調用	提高可維護性和可讀性
實現具體API方法	封裝HTTP請求邏輯	簡化使用，隱藏複雜性
錯誤處理和重試機制	優雅處理網絡異常	提高可靠性和穩定性
使用選項模式	靈活配置API參數	適應不同環境，提高可配置性
使用 Singleton 模式	確保全應用程序只有一個 API 客戶端實例	控制資源使用，保證一致性，提高效能
撰寫單元測試	確保功能正確性	提高代碼品質和可維護性
使用裝飾器模式	動態添加額外功能	提高擴展性和靈活性
非同步和並行處理	優化多個API調用	提高性能和響應速度
注重安全性	妥善處理授權和錯誤	保護數據和提高可靠性

看！我們的「API封裝料理」菜單就此完成了。只要按照這些步驟，你就能把原本雜亂無章的API調用，變成一道道精美絕倫的程式碼大餐。

記住，成為一名優秀的「程式碼主廚」需要不斷練習和嘗試。就像學習烹飪一樣，一開始可能會感到困難，但只要保持熱情和耐心，你終將成為API封裝領域的大師級人物！無論是選擇讓你的 API 客戶端成為獨一無二的主廚（Singleton），還是靈活多變的學徒（普通實例），重要的是要根據你的「餐廳」（應用程序）的需求來決定。

12. 實戰技巧：組合所有學到的概念

讓我們來看看如何將所有這些概念組合在一起，創建一個真正強大的API客戶端：

public sealed class SuperDuperApiClient
{
    private static readonly Lazy<SuperDuperApiClient> _instance 
        = new Lazy<SuperDuperApiClient>(() => new SuperDuperApiClient());
    
    private readonly HttpClient _httpClient;
    private readonly ILogger<SuperDuperApiClient> _logger;

    private SuperDuperApiClient()
    {
        var configuration = new ConfigurationBuilder()
            .SetBasePath(Directory.GetCurrentDirectory())
            .AddJsonFile("appsettings.json")
            .Build();

        var apiKey = configuration["SuperDuperApi:ApiKey"];
        var baseUrl = configuration["SuperDuperApi:BaseUrl"];

        _httpClient = new HttpClient { BaseAddress = new Uri(baseUrl) };
        _httpClient.DefaultRequestHeaders.Add("Authorization", $"Bearer {apiKey}");
        _httpClient.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));

        _logger = LoggerFactory.Create(builder => builder.AddConsole()).CreateLogger<SuperDuperApiClient>();
    }

    public static SuperDuperApiClient Instance => _instance.Value;

    public async Task<UserInfo> GetUserInfoAsync(int userId)
    {
        return await ExecuteWithRetry(async () =>
        {
            _logger.LogInformation($"正在獲取用戶 {userId} 的資訊");
            var response = await _httpClient.GetAsync($"users/{userId}");
            ValidateApiResponse(response);
            var content = await response.Content.ReadAsStringAsync();
            var result = JsonConvert.DeserializeObject<UserInfo>(content);
            _logger.LogInformation($"成功獲取用戶 {userId} 的資訊");
            return result;
        });
    }

    private async Task<T> ExecuteWithRetry<T>(Func<Task<T>> action, int maxRetries = 3)
    {
        for (int i = 0; i < maxRetries; i++)
        {
            try
            {
                return await action();
            }
            catch (HttpRequestException ex) when (i < maxRetries - 1)
            {
                _logger.LogWarning($"第{i+1}次嘗試失敗：{ex.Message}。正在重試...");
                await Task.Delay(1000 * (i + 1));
            }
        }
        throw new Exception($"在 {maxRetries} 次嘗試後仍然失敗");
    }

    private void ValidateApiResponse(HttpResponseMessage response)
    {
        if (!response.IsSuccessStatusCode)
        {
            throw new ApiException($"API 調用失敗：{response.StatusCode}", response.StatusCode);
        }
    }
}

public class ApiException : Exception
{
    public HttpStatusCode StatusCode { get; }

    public ApiException(string message, HttpStatusCode statusCode) : base(message)
    {
        StatusCode = statusCode;
    }
}

這個最終版本的 API 客戶端結合了我們討論過的所有概念：Singleton 模式、錯誤處理、重試機制、日誌記錄和安全性檢查。它就像是一個集所有功能於一身的超級主廚，能夠應對各種API調用場景！

結語：你的 API 封裝之旅才正要開始！

親愛的程式碼主廚們，我們的 API 封裝美食之旅到此告一段落。但請記住，這只是開始！就像烹飪一樣，API 封裝的藝術需要不斷練習和創新。

讓我們用一句話來總結今天的學習：

優雅的 API 封裝就像是精美的餐點，不僅口感絕佳，更能帶來賞心悅目的用餐體驗。用心設計你的 API 客戶端，讓每一次調用都如同享受米其林三星料理！無論是由一位主廚掌勺，還是眾多廚師合作，重要的是最終呈現在「客人」（使用者）面前的完美體驗。

記住，遇到困難時別灰心，每個大師曾經都是初學者。保持對編程的熱愛，相信終有一天，你也能成為 API 封裝界的 Gordon Ramsay！

現在，拿起你的鍵盤魔杖，開始你的 API 封裝美食之旅吧！期待看到你的程式碼大餐！

祝你程式碼美味可口，API 調用順心如意！🍣💻✨

C#大師秘笈：優雅封裝外部API的終極指南#

1. 為什麼要封裝外部API？#

2. 打造堅實地基：API客戶端類別#

3. 添加調味料：實現API方法#

4. 秘製醬料：錯誤處理和重試機制#

5. 擺盤：使用選項模式進行配置#

6. 獨一無二的主廚：Singleton 模式#

6.1 為什麼要使用 Singleton？#

6.2 實現一個線程安全的 Singleton API 客戶端#

6.3 如何使用我們的 Singleton API 客戶端#

6.4 Singleton 的注意事項#

7. 品質管控：單元測試#

8. 擴展功能：使用裝飾器模式#

9. 效能調校：非同步和並行處理#

10. 安全性：別忘了防護措施#

11. 總結：成為API封裝大師#

12. 實戰技巧：組合所有學到的概念#

結語：你的 API 封裝之旅才正要開始！#