ABP Community Learning

Appearance

第二十四章：社群熱門開源模組整合 ​

學習目標

  • 了解 ABP 社群生態與主要模組
  • 掌握模組選型與評估方法
  • 實作模組安裝、配置與整合
  • 管理模組相依性與版本衝突

先備知識

  • 已完成第五章（ABP Module 結構）
  • 熟悉 NuGet 與 .NET CLI
  • 了解多模組架構

正文

一、ABP 社群生態概覽

主要資源

  • EasyAbp：最活躍社群組織，提供 20+ 模組
  • GitHub Discussions：官方支援與討論
  • NuGet.org：模組發佈源

常用模組分類

分類模組用途
資料管理DataDictionary字典表管理
FileManagement檔案存儲與管理
業務功能SettingManagement系統設定
NotificationCenter通知中心
Accounting記帳與財務
電商Order訂單管理
Payment支付整合
內容管理CMS內容發佈
工作流程WorkflowEngine流程引擎（如 Elsa）

二、模組選型評估

評估準則

  • 活躍度：最後更新時間、Issue 回應速度
  • 相容性：支援的 ABP 版本與 .NET 版本
  • 功能完整性：是否涵蓋需求功能
  • 文件質量：是否有完整使用指南
  • 社群支援：Issue 修復情況、Pull Request 接受度

檢查模組品質

bash()

bash
# bash - 查看 NuGet 套件資訊
dotnet package search EasyAbp.DataDictionary

# 檢查 GitHub 倉庫
# https://github.com/EasyAbp/DataDictionary
# 看：Star 數、最後提交日期、Issue 狀態

三、模組安裝與配置

安裝 EasyAbp DataDictionary 範例

bash()

bash
# bash
# 1. 安裝 NuGet 套件（核心）
dotnet add package EasyAbp.DataDictionary.Domain

# 2. 安裝 Application 層
dotnet add package EasyAbp.DataDictionary.Application

# 3. 安裝 EntityFrameworkCore 層
dotnet add package EasyAbp.DataDictionary.EntityFrameworkCore

# 4. 安裝 HTTP API 層
dotnet add package EasyAbp.DataDictionary.HttpApi

# 5. 安裝 Web UI（若有）
dotnet add package EasyAbp.DataDictionary.Web

在 Module 中依賴

csharp()

csharp
// csharp - MyProjectModule.cs
using EasyAbp.DataDictionary;

[DependsOn(
    typeof(DataDictionaryModule),  // 新增模組依賴
    typeof(AbpAuditingModule)
)]
public class MyProjectModule : AbpModule
{
    public override void ConfigureServices(ServiceConfigurationContext context)
    {
        // 模組會自動註冊其服務
    }
}

建立資料庫遷移

bash()

bash
# bash
# 建立新 migration（包含 DataDictionary 表）
dotnet ef migrations add AddDataDictionary \
    -p src/MyProject.EntityFrameworkCore \
    -s src/MyProject.DbMigrator

# 應用遷移
dotnet ef database update \
    -p src/MyProject.EntityFrameworkCore \
    -s src/MyProject.DbMigrator

四、模組配置與客製

使用模組選項

csharp()

csharp
// csharp - MyProjectModule.cs
public override void ConfigureServices(ServiceConfigurationContext context)
{
    // 配置 DataDictionary 模組選項
    Configure<DataDictionaryOptions>(options =>
    {
        options.MaxCacheSize = 1000;
        options.CacheDuration = TimeSpan.FromHours(1);
    });
}

擴充模組功能

csharp()

csharp
// csharp - 繼承模組的 AppService 進行擴充
public class ExtendedDataDictionaryAppService : DataDictionaryAppService
{
    public override async Task<DictionaryDto> GetAsync(Guid id)
    {
        var result = await base.GetAsync(id);
        
        // 自訂邏輯：新增額外資訊
        result.ExtraData = await GetExtraDataAsync(id);
        
        return result;
    }
}

五、相依性管理

版本衝突診斷

bash()

bash
# bash
# 查看套件相依性樹
dotnet package tree list

# 檢查衝突
dotnet build --no-restore -v diag | grep "conflict"

解決版本衝突

場景：模組 A 依賴 Volo.Abp 9.3，模組 B 依賴 Volo.Abp 9.4

解決方案：

  1. 聯繫模組維護者更新相依性
  2. 使用專案級 Directory.Packages.props 統一版本

xml()

xml
<!-- xml - Directory.Packages.props -->
<Project>
  <ItemGroup>
    <PackageVersion Include="Volo.Abp" Version="9.4.0" />
    <PackageVersion Include="EasyAbp.DataDictionary.Domain" Version="2.0.0" />
  </ItemGroup>
</Project>

在 .csproj 中引用

xml()

xml
<!-- xml - src/MyProject.Domain/MyProject.Domain.csproj -->
<ItemGroup>
  <PackageReference Include="Volo.Abp" />
  <PackageReference Include="EasyAbp.DataDictionary.Domain" />
</ItemGroup>

六、常見集成模式

模組 + 自訂邏輯

csharp()

csharp
// csharp - 使用 DataDictionary 實現業務枚舉
public class BookService
{
    private readonly IDataDictionaryAppService _dataDictionaryService;
    
    public BookService(IDataDictionaryAppService dataDictionaryService)
    {
        _dataDictionaryService = dataDictionaryService;
    }
    
    public async Task<List<string>> GetCategoriesAsync()
    {
        // 從字典表獲取分類
        var categories = await _dataDictionaryService.GetListAsync("BookCategories");
        return categories.Select(c => c.DisplayText).ToList();
    }
}

模組鏈：通知 + 支付整合

csharp()

csharp
// csharp - 支付完成時發送通知
public class PaymentEventHandler : ILocalEventHandler<PaymentCompletedEvent>
{
    private readonly INotificationAppService _notificationService;
    
    public async Task HandleEventAsync(PaymentCompletedEvent eventData)
    {
        await _notificationService.SendAsync(
            new NotificationDto
            {
                Title = "支付成功",
                Content = $"訂單 {eventData.OrderId} 支付完成",
                RecipientId = eventData.UserId
            }
        );
    }
}

七、升級與維護

定期檢查模組更新

bash()

bash
# bash
# 檢查過時的 NuGet 套件
dotnet outdated

# 更新特定套件
dotnet add package EasyAbp.DataDictionary --upgrade

處理破壞性變更

社群模組偶爾有破壞性變更，升級時應：

  1. 審視 Release Notes：檢查 Breaking Changes
  2. 測試新版本：在開發/Staging 環境完整測試
  3. 逐步升級：若無相依性，先升級關鍵模組

八、常見問題與解決

Q：模組 UI 與自訂 UI 衝突 A：在 _Layout.cshtml 中優先載入自訂樣式，覆寫模組樣式

Q：模組多次註冊同一服務 A：確認只在一個 Module 中 [DependsOn(typeof(ModuleA))]，避免重複

Q：模組建置失敗，提示缺失相依性 A：執行 dotnet restore 並檢查 NuGet 源配置

九、實務最佳實務

  • 使用模組前評估品質與活躍度
  • 版本選擇：一般選用最新穩定版
  • 文件化所有集成模組與版本
  • 定期更新相依性但謹慎測試
  • 加入單元測試驗證模組集成

實作練習

  1. 安裝並配置 EasyAbp DataDictionary 模組
  2. 在應用中使用模組功能
  3. 擴充模組 AppService 新增自訂邏輯
  4. 解決一次版本衝突問題

習題（至少 6 題）

概念題（易）

  1. 評估社群模組品質的關鍵指標為何？（難度：易）
  2. 何時應選擇集成現有模組 vs 自行開發？（難度：中）

計算 / 練習題（中） 3. 設計一個包含 5 個社群模組的整合方案，識別相依性與風險。（難度：中） 4. 制定模組升級計畫：現有 5 個模組，評估升級順序與風險。（難度：中）

實作 / 編碼題（較難） 5. 安裝並集成 3 個社群模組（如 DataDictionary、FileManagement、NotificationCenter），並實作模組間協作。（難度：較難） 6. 為社群模組編寫完整集成測試，驗證與主應用的相容性。（難度：較難）

術語表

  • Module Integration（模組整合）：將社群模組集成至主應用
  • Dependency Injection（依賴注入）：通過 DependsOn 宣告模組依賴
  • NuGet Package（NuGet 套件）：.NET 套件管理格式
  • Breaking Change（破壞性變更）：升級時不相容的改變

參考資料

習題解答：content/solutions/ch24-solutions.md

Released under the MIT License.

Copyright © 2025 ABP Community Learning Kit