C# 微信公眾號標籤管理完整實作：從介面定義到 API 封裝的最佳實務

微信公眾號引入「標籤」功能取代傳統「分組」，支援多維度標記粉絲屬性，單一公眾號最多建立 100 個標籤，每位使用者最多可打 3 個標籤。本文示範如何以 C# 封裝標籤管理相關 API，涵蓋標籤 CRUD、粉絲清單查詢、批量打標/取消標籤、查詢使用者身上標籤等核心功能，程式碼結構清晰，可直接套用於實際專案。

一、標籤功能核心特性

• 取代分組： 支援多標籤交叉篩選，比單層分組更靈活。
• 後台操作： 運營者可在公眾平台手動為粉絲打標籤，並支援即時新增標籤。
• 介面整合： 高級群發、個性化選單等介面皆支援按標籤篩選對象。
• 用戶畫像強化： 用戶卡片新增互動數據（訊息數、留言數、贊賞數）、關注時間、大頭貼，提升運營效率。

二、API 介面設計（ITagApi）

採用介面導向設計，便於單元測試與多實作切換（如正式環境/模擬環境）。

public interface ITagApi
{
    /// 
建立標籤（最多 100 個，名稱 30 字內）
    TagJson CreateTag(string accessToken, string name);

    /// 
取得所有標籤清單（含粉絲計數）
    List<TagCountJson> GetTagList(string accessToken);

    /// 
編輯標籤名稱
    CommonResult UpdateTag(string accessToken, int id, string name);

    /// 
刪除標籤
    CommonResult DeleteTag(string accessToken, int id);

    /// 
取得標籤下的粉絲 OpenID 清單（分頁）
    GetTagResult GetTag(string accessToken, int id, string nextOpenId = null);

    /// 
批量為使用者打標籤（單次最多 50 個 OpenID，每用戶最多 3 標籤）
    CommonResult BatchTagging(string accessToken, int tagId, List<string> openIdList);

    /// 
批量取消使用者標籤
    CommonResult BatchUntagging(string accessToken, int tagId, List<string> openIdList);

    /// 
查詢使用者身上的標籤 ID 清單
    List<int> GetIdList(string accessToken, string openId);
}

三、資料傳輸物件（DTO）定義

/// 
標籤基本資訊
public class TagJson
{
    public int Id { get; set; }        // 微信分配的標籤 ID
    public string Name { get; set; }   // 標籤名稱 (UTF-8)
}

/// 
含粉絲計數的標籤（繼承 TagJson）
public class TagCountJson : TagJson
{
    public int Count { get; set; }     // 此標籤下粉絲數
}

/// 
建立標籤回傳結果
public class TagCreateResult
{
    public TagJson Tag { get; set; }
}

/// 
取得標籤粉絲清單結果
public class GetTagResult
{
    public int Count { get; set; }
    public List<string> Data { get; set; } // OpenID 清單
    public string NextOpenId { get; set; }
}

四、核心 API 實作範例（以建立標籤為例）

public TagJson CreateTag(string accessToken, string name)
{
    var url = $"https://api.weixin.qq.com/cgi-bin/tags/create?access_token={accessToken}";
    var payload = new { tag = new { name } };
    var json = payload.ToJson(); // 需自行實作或使用 Newtonsoft.Json
    var result = JsonHelper<TagCreateResult>.ConvertJson(url, json); // 封裝的 HTTP POST + 反序列化
    return result?.Tag;
}

關鍵點說明：

• URL 必須使用 HTTPS，參數 access_token 需定期刷新快取。
• 請求本文為 JSON，Content-Type: application/json。
• 回傳 JSON 範例：{"tag":{"id":134,"name":"廣東"}}，直接對應 TagCreateResult。
• 統一錯誤處理：微信 API 回傳 errcode != 0 時拋出自訂例外 WeChatApiException，攜帶 errcode、errmsg。

五、其他介面實作重點

六、最佳實務建議

1. AccessToken 管理： 使用單例/快取機制（如 MemoryCache 或 IDistributedCache）集中管理，避免重複請求導致頻率限制。
2. 重試與熔斷： 整合 Polly 實作指數退避重試（網路錯誤）、熔斷（持續 5xx 錯誤），提升穩定性。
3. 日誌記錄： 記錄所有請求/回應 JSON（敏感資訊脫敏），便於除錯與稽核。
4. 單元測試： 對 ITagApi 撰寫 Mock 測試，模擬各種微信回傳碼（0 成功、40001 token 失效、45058 頻率超限等）。
5. 版本相容： 微信 API 可能新增欄位，DTO 採用 JsonProperty 忽略未知屬性，避免反序列化失敗。

七、完整專案結構建議

WeChat.Sdk/
├── Abstractions/
│   └── ITagApi.cs
├── Models/
│   ├── TagJson.cs
│   ├── TagCountJson.cs
│   ├── TagCreateResult.cs
│   └── GetTagResult.cs
├── Impl/
│   └── TagApiClient.cs      // 實作 ITagApi，內含 HttpClient 封裝
├── Exceptions/
│   └── WeChatApiException.cs
└── Extensions/
    └── ServiceCollectionExtensions.cs // DI 註冊擴充方法

遵循介面隔離、單一職責、依賴反轉原則，即可建構出可維護、可測試、可擴充的微信標籤管理模組。