框架架構設計

AppFuse Server 的整體架構和設計理念

---

設計理念

AppFuse Server 是工具集，不是框架。

核心原則

1. 提供工具，不強制架構

   • 開發者可自由組合使用
   • 不包含具體業務邏輯

2. 介面導向設計

   • 核心功能定義為介面
   • 底層實作可替換

3. 最小依賴原則

   • 各模組盡量獨立
   • 按需引入

4. Spring 整合選配

   • 核心不依賴 Spring
   • 提供可選的 Spring 整合

---

整體架構

┌─────────────────────────────────────────────────────────────┐
│                    AppFuse Server                           │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐           │
│  │  Cache  │ │   CSV   │ │  HTTP   │ │ Content │           │
│  └─────────┘ └─────────┘ └─────────┘ └─────────┘           │
│                                                             │
│  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐           │
│  │  Link   │ │Security │ │ Crypto  │ │   JPA   │           │
│  └─────────┘ └─────────┘ └─────────┘ └─────────┘           │
│                                                             │
│  ┌─────────┐ ┌─────────┐ ┌─────────┐                       │
│  │  NLS    │ │  JSON   │ │  Text   │  ...更多工具           │
│  └─────────┘ └─────────┘ └─────────┘                       │
│                                                             │
├─────────────────────────────────────────────────────────────┤
│                   Spring Boot 4.0                           │
├─────────────────────────────────────────────────────────────┤
│                      Java 25                                │
└─────────────────────────────────────────────────────────────┘

---

模組架構模式

分層架構 + 適配器模式

以 Cache 模組為例：

┌─────────────────────────────────────────────┐
│          Builder Layer (建構器層)            │
│  CacheBuilder, DualCacheBuilder             │
└──────────────────┬──────────────────────────┘
                   │
┌──────────────────▼──────────────────────────┐
│          Core Layer (核心實作層)             │
│  ManagedCache, DualLayerCache               │
└──────────────────┬──────────────────────────┘
                   │
┌──────────────────▼──────────────────────────┐
│          API Layer (抽象層)                  │
│  Cache<K,V>, CacheManager                   │
└──────────────────┬──────────────────────────┘
                   │
┌──────────────────▼──────────────────────────┐
│        Adapter Layer (適配器層)              │
│  EhcacheCacheAdapter (可替換)               │
└─────────────────────────────────────────────┘

依賴隔離層

以 CSV 模組為例：

應用程式代碼 → AppFuse CSV API (穩定)
                     ↓
            底層實作 (可替換)
            - Univocity Parsers
            - Jackson CSV
            - 未來：其他庫

---

模組清單

核心模組

模組	Package	用途
Cache	io.leandev.appfuse.cache	快取管理
CSV	io.leandev.appfuse.csv	CSV 處理
HTTP	io.leandev.appfuse.http	HTTP 客戶端
Content	io.leandev.appfuse.content	MIME 檢測
Link	io.leandev.appfuse.web.link	HATEOAS 連結
Security	io.leandev.appfuse.security	登入鎖定

工具模組

模組	Package	用途
Converter	io.leandev.appfuse.converter	型別轉換
Crypto	io.leandev.appfuse.crypto	加密工具
JSON	io.leandev.appfuse.json	JSON 處理
XML	io.leandev.appfuse.xml	XML 處理
Text	io.leandev.appfuse.text	文字處理
NLS	io.leandev.appfuse.nls	國際化
JPA	io.leandev.appfuse.jpa	JPA 工具

---

依賴管理

傳遞依賴

AppFuse Server 使用 api 方式聲明核心依賴，自動傳遞給使用者：

• Spring Boot Starters
• Apache HttpClient 5.x
• jakarta.ws.rs-api
• jjwt-api

可選依賴

某些模組有可選依賴：

• Cache 模組：Ehcache
• JPA 模組：Hibernate

---

擴展指南

新增模組

1. 建立 Package: io.leandev.appfuse.{module}
2. 定義核心介面
3. 提供預設實作
4. 撰寫測試
5. 更新文檔

替換底層實作

以 Cache 模組為例：

1. 實作 CacheAdapter<K,V> 介面
2. 實作 CacheManagerAdapter 介面
3. 註冊到 CacheManagerBuilder

---

與參考實作的關係

appfuse-server (框架)
    ↓ 依賴
app-tenant-server (參考實作)
    - 展示框架使用方式
    - 驗證框架正確性
    - 提供最佳實踐範例