Spring-Boot on Bill.Lin's Notes

Cloudflare Turnstile 實戰：Vue 3 + Spring Boot 雙端整合

Tue, 28 Apr 2026 00:00:00 +0800

為什麼選 Turnstile

方案	價格	使用者體驗	隱私
Cloudflare Turnstile	免費（無流量上限）	多數情況完全無感	不依賴 Google，不發 tracking cookie
reCAPTCHA v3	免費（有配額）	無感，但 score 閾值需自行調	Google 蒐集使用者行為
hCaptcha	有免費層	可能出現拼圖互動	較注重隱私，非 Google

Turnstile 使用 JavaScript challenge + machine learning 評估訪客，大多數真實使用者不需要任何互動即可通過。sitekey 不需要 Cloudflare 付費計畫。

運作原理與雙端流程

Vue SPA                Cloudflare CDN          Spring Boot 後端
  │                          │                        │
  │  1. 動態載入 api.js       │                        │
  │─────────────────────────▶│                        │
  │                          │                        │
  │  2. widget 完成挑戰，回傳 token                    │
  │◀─────────────────────────│                        │
  │                                                    │
  │  3. POST /api/contact（含 cf-turnstile-response）  │
  │───────────────────────────────────────────────────▶│
  │                                                    │
  │                   4. POST siteverify（帶 secret）  │
  │                          ◀─────────────────────── │
  │                          │                        │
  │                   5. {"success": true}            │
  │                          ──────────────────────── ▶│
  │                                                    │
  │  6. 200 OK                                         │
  │◀───────────────────────────────────────────────────│

三個核心事實：

HikariCP 連線池調校

Mon, 15 Jan 2024 00:00:00 +0800

為什麼需要連線池

每次建立一條 MySQL 連線涉及：

TCP 三向交握
MySQL 認證協議（握手、登入封包）
SSL 協商（若啟用）

單次耗時 ~5–30ms，在高並發場景下，每個請求都新建連線會讓延遲成為瓶頸。連線池預先建立固定數量的連線並重複使用，消除這段開銷。

另一個角度：MySQL Server 端的連線數有上限（max_connections，預設 151）。連線池讓多個應用執行緒共享少量資料庫連線。

HikariCP 核心參數

spring:
  datasource:
    hikari:
      maximum-pool-size: 10       # 連線池最大連線數
      minimum-idle: 5             # 最少保持的閒置連線數
      connection-timeout: 30000   # 向池請求連線的最長等待時間（ms），超過拋出例外
      idle-timeout: 600000        # 閒置連線在池中存活的最長時間（ms），10 分鐘
      max-lifetime: 1800000       # 連線在池中存活的最長時間（ms），30 分鐘
      leak-detection-threshold: 60000  # 連線被借出後超過此時間未歸還，印出警告（ms）
      pool-name: HikariPool-Main

maximumPoolSize 公式

HikariCP 官方推薦公式（基於 PostgreSQL 基準測試，MySQL 也適用）：

Spring Boot 3 + Virtual Threads 實戰

Mon, 15 Jan 2024 00:00:00 +0800

什麼是 Virtual Threads

Java 21 正式引入 Virtual Threads（Project Loom），目的是讓 I/O-bound 的應用在不改變同步程式碼風格的前提下，獲得接近非同步的吞吐量。

Carrier Thread vs Virtual Thread — M:N 調度

OS Thread (Carrier Thread) [N 條]
    │
    ├── Virtual Thread 1  (執行中)
    ├── Virtual Thread 2  (等待 I/O，已卸載)
    └── Virtual Thread 3  (等待 I/O，已卸載)

Platform Thread（傳統）：1:1 對應 OS thread，每條佔 ~1MB stack，數量上限約數千條。
Virtual Thread：M:N，大量 virtual threads 映射到少量 carrier threads（通常等於 CPU cores）。
當 virtual thread 遇到阻塞 I/O，JVM 自動將它從 carrier thread 卸載（unmount），carrier thread 可繼續處理其他 virtual threads；I/O 完成後再重新掛載（mount）。

這讓你可以為每個 HTTP 請求建立一條 virtual thread，而不用擔心耗盡 OS threads。

六角形架構（Ports & Adapters）實戰

Mon, 15 Jan 2024 00:00:00 +0800

核心概念

六角形架構（Hexagonal Architecture），又稱 Ports & Adapters，由 Alistair Cockburn 提出。

核心原則：應用程式核心（Domain + Application）不依賴任何基礎設施細節。資料庫、HTTP、Kafka 等都是「外部細節」，透過 Port（介面）與核心溝通。

               ┌─────────────────────────────────┐
  HTTP ───────►│  Input Adapter (Controller)     │
  Kafka ──────►│                                 │
               │  ┌───────────────────────────┐  │
               │  │  Application (Use Cases)  │  │
               │  │  ┌─────────────────────┐  │  │
               │  │  │    Domain           │  │  │
               │  │  │  (Pure Java)        │  │  │
               │  │  └─────────────────────┘  │  │
               │  └───────────────────────────┘  │
               │                                 │
               │  Output Adapter (Repository)    │───► MySQL
               │  Output Adapter (EventPublisher)│───► Kafka
               └─────────────────────────────────┘

依賴方向：Adapters → Application → Domain。Domain 不認識任何 Adapter。

分散式 ID 生成系統：Snowflake 算法與企業級實現

Tue, 13 Sep 2022 23:05:38 +0800

分散式 ID 生成系統：Snowflake 算法與企業級實現

概述

在分散式系統中，生成全域唯一 ID 是一個關鍵挑戰。不同於單體應用可以依賴資料庫的自增主鍵，分散式系統需要考慮多節點併發、高可用性、效能、順序性等多重需求。Twitter 開源的 Snowflake 算法為這個問題提供了優雅的解決方案。

分散式 ID 的核心挑戰

傳統方案的局限性

UUID 方案

/**
 * 傳統 UUID 生成器
 * 優點：本地生成、無網路依賴、效能高
 * 缺點：無序性、儲存空間大、不適合作為主鍵
 */
public class UUIDGenerator {
    
    public static String generateUUID() {
        return UUID.randomUUID().toString();
        // 範例: 550e8400-e29b-41d4-a716-446655440000
    }
    
    public static String generateCompactUUID() {
        return UUID.randomUUID().toString().replace("-", "");
        // 範例: 550e8400e29b41d4a716446655440000
    }
}

資料庫自增方案

/**
 * 資料庫自增 ID 方案
 * 優點：單調遞增、實現簡單
 * 缺點：單點故障、效能瓶頸、難以水平擴展
 */
@Entity
@Table(name = "id_generator")
public class DatabaseIdGenerator {
    
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
    
    @Column(name = "stub", unique = true)
    private String stub = "a";
    
    // getter/setter
}

@Repository
public interface IdGeneratorRepository extends JpaRepository<DatabaseIdGenerator, Long> {
    
    @Modifying
    @Query("DELETE FROM DatabaseIdGenerator")
    void clearAll();
}

分散式 ID 的設計目標

全域唯一性：在分散式環境下保證 ID 全域唯一
高可用性：系統故障時仍能正常生成 ID
高效能：支援高併發場景下的快速生成
遞增性：保證生成的 ID 具有時間順序性
可擴展性：支援水平擴展，節點數量可動態調整

Snowflake 算法深度解析

算法核心思想

Snowflake 算法使用 64 位長整型來生成 ID，結構如下：

Kotlin lateinit 完整實作指南：延遲初始化與企業級開發最佳實踐

Thu, 05 Aug 2021 21:07:54 +0800

Kotlin lateinit 完整實作指南

簡介

在 Kotlin 開發中，lateinit 關鍵字提供了一種延遲初始化屬性的優雅方式，特別適用於依賴注入、Android 開發和 Spring Boot 應用。本文將深入探討 lateinit 的工作原理、使用場景、與 lazy 的比較，以及在企業級開發中的最佳實踐。

lateinit 基本概念

核心特性

lateinit 是 Kotlin 提供的延遲初始化修飾符，允許開發者聲明非空屬性而不需要立即初始化：

class UserService {
    // 延遲初始化，避免空值檢查
    lateinit var userRepository: UserRepository
    lateinit var cacheManager: CacheManager
    
    fun initializeServices() {
        userRepository = UserRepositoryImpl()
        cacheManager = RedisCacheManager()
    }
    
    fun findUser(id: Long): User {
        // 直接使用，無需空值檢查
        return userRepository.findById(id) ?: throw UserNotFoundException(id)
    }
}

語法規則與限制

class PropertyRules {
    // ✅ 正確：var 屬性
    lateinit var validProperty: String
    
    // ❌ 錯誤：lateinit 不能用於 val
    // lateinit val invalidProperty: String // 編譯錯誤
    
    // ❌ 錯誤：原始類型不支援
    // lateinit var invalidInt: Int // 編譯錯誤
    
    // ❌ 錯誤：可空類型不支援
    // lateinit var invalidNullable: String? // 編譯錯誤
    
    // ✅ 正確：自定義類別
    lateinit var database: Database
    
    // ✅ 正確：介面類型
    lateinit var service: ServiceInterface
}

lateinit 詳細機制

內部實現原理

// Kotlin 編譯後的 Java 等效代碼
public class UserService {
    private String name;
    
    public final String getName() {
        String var1 = this.name;
        if (var1 == null) {
            Intrinsics.throwUninitializedPropertyAccessException("name");
        }
        return var1;
    }
    
    public final void setName(String value) {
        Intrinsics.checkNotNullParameter(value, "value");
        this.name = value;
    }
}

初始化檢查機制

class InitializationChecker {
    lateinit var database: Database
    lateinit var config: AppConfig
    
    fun checkInitialization() {
        // 檢查是否已初始化
        if (::database.isInitialized) {
            println("Database is ready")
        } else {
            println("Database not initialized")
        }
        
        // 安全初始化模式
        if (!::config.isInitialized) {
            config = loadDefaultConfig()
        }
    }
    
    fun safeAccess(): String {
        return if (::database.isInitialized) {
            database.getConnectionInfo()
        } else {
            "Database not available"
        }
    }
}

企業級應用場景

1. Spring Boot 依賴注入

@Service
class UserManagementService {
    
    @Autowired
    lateinit var userRepository: UserRepository
    
    @Autowired
    lateinit var emailService: EmailService
    
    @Autowired
    lateinit var auditService: AuditService
    
    @Value("\${app.user.max-login-attempts}")
    lateinit var maxLoginAttempts: String
    
    @PostConstruct
    fun validateDependencies() {
        require(::userRepository.isInitialized) { "UserRepository not injected" }
        require(::emailService.isInitialized) { "EmailService not injected" }
        require(::auditService.isInitialized) { "AuditService not injected" }
        
        logger.info("All dependencies initialized successfully")
    }
    
    fun createUser(userData: UserCreateRequest): User {
        val user = User(
            email = userData.email,
            username = userData.username,
            hashedPassword = hashPassword(userData.password)
        )
        
        val savedUser = userRepository.save(user)
        
        // 發送歡迎郵件
        emailService.sendWelcomeEmail(savedUser)
        
        // 記錄審計日誌
        auditService.logUserCreation(savedUser)
        
        return savedUser
    }
    
    companion object {
        private val logger = LoggerFactory.getLogger(UserManagementService::class.java)
    }
}

2. Android 開發中的應用

class MainActivity : AppCompatActivity() {
    
    // View 元件延遲初始化
    lateinit var recyclerView: RecyclerView
    lateinit var adapter: UserAdapter
    lateinit var viewModel: UserViewModel
    
    // 網路元件
    lateinit var apiService: ApiService
    lateinit var networkManager: NetworkManager
    
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)
        
        initializeViews()
        initializeNetwork()
        initializeViewModel()
        setupObservers()
    }
    
    private fun initializeViews() {
        recyclerView = findViewById(R.id.recyclerView)
        adapter = UserAdapter { user -> onUserClicked(user) }
        recyclerView.adapter = adapter
        recyclerView.layoutManager = LinearLayoutManager(this)
    }
    
    private fun initializeNetwork() {
        apiService = RetrofitBuilder.createApiService()
        networkManager = NetworkManager(this)
    }
    
    private fun initializeViewModel() {
        viewModel = ViewModelProvider(this)[UserViewModel::class.java]
    }
    
    private fun setupObservers() {
        // 確保所有元件都已初始化
        require(::viewModel.isInitialized) { "ViewModel not initialized" }
        require(::adapter.isInitialized) { "Adapter not initialized" }
        
        viewModel.users.observe(this) { users ->
            adapter.submitList(users)
        }
        
        viewModel.loading.observe(this) { isLoading ->
            // 處理載入狀態
        }
    }
    
    private fun onUserClicked(user: User) {
        if (::networkManager.isInitialized && networkManager.isConnected()) {
            // 處理用戶點擊事件
            viewModel.loadUserDetails(user.id)
        } else {
            showNoNetworkError()
        }
    }
}

3. 配置管理系統

@Component
class ConfigurationManager {
    
    @Value("\${database.url}")
    lateinit var databaseUrl: String
    
    @Value("\${database.username}")
    lateinit var databaseUsername: String
    
    @Value("\${redis.host}")
    lateinit var redisHost: String
    
    @Value("\${jwt.secret}")
    lateinit var jwtSecret: String
    
    lateinit var databaseConfig: DatabaseConfig
    lateinit var redisConfig: RedisConfig
    lateinit var securityConfig: SecurityConfig
    
    @PostConstruct
    fun initializeConfigurations() {
        validateRequiredProperties()
        buildConfigurations()
        logConfigurationStatus()
    }
    
    private fun validateRequiredProperties() {
        val errors = mutableListOf<String>()
        
        if (!::databaseUrl.isInitialized || databaseUrl.isBlank()) {
            errors.add("Database URL not configured")
        }
        
        if (!::databaseUsername.isInitialized || databaseUsername.isBlank()) {
            errors.add("Database username not configured")
        }
        
        if (!::redisHost.isInitialized || redisHost.isBlank()) {
            errors.add("Redis host not configured")
        }
        
        if (!::jwtSecret.isInitialized || jwtSecret.isBlank()) {
            errors.add("JWT secret not configured")
        }
        
        if (errors.isNotEmpty()) {
            throw ConfigurationException("Configuration errors: ${errors.joinToString(", ")}")
        }
    }
    
    private fun buildConfigurations() {
        databaseConfig = DatabaseConfig(
            url = databaseUrl,
            username = databaseUsername,
            maxPoolSize = 20,
            connectionTimeout = Duration.ofSeconds(30)
        )
        
        redisConfig = RedisConfig(
            host = redisHost,
            port = 6379,
            timeout = Duration.ofSeconds(10)
        )
        
        securityConfig = SecurityConfig(
            jwtSecret = jwtSecret,
            tokenExpiration = Duration.ofHours(24),
            refreshTokenExpiration = Duration.ofDays(7)
        )
    }
    
    private fun logConfigurationStatus() {
        logger.info("Configuration initialized successfully:")
        logger.info("- Database: ${databaseConfig.url}")
        logger.info("- Redis: ${redisConfig.host}:${redisConfig.port}")
        logger.info("- Security: JWT configured with ${securityConfig.tokenExpiration} expiration")
    }
    
    fun getDatabaseConfig(): DatabaseConfig {
        require(::databaseConfig.isInitialized) { "Database configuration not initialized" }
        return databaseConfig
    }
    
    fun getRedisConfig(): RedisConfig {
        require(::redisConfig.isInitialized) { "Redis configuration not initialized" }
        return redisConfig
    }
    
    fun getSecurityConfig(): SecurityConfig {
        require(::securityConfig.isInitialized) { "Security configuration not initialized" }
        return securityConfig
    }
    
    companion object {
        private val logger = LoggerFactory.getLogger(ConfigurationManager::class.java)
    }
}

lateinit vs lazy 詳細比較

特性對比表

特性	lateinit	lazy
初始化時機	手動控制	首次訪問時
線程安全	否	是（預設）
可變性	var（可重新賦值）	val（不可變）
初始化檢查	::property.isInitialized	無需檢查
記憶體開銷	低	略高（Lazy包裝）
適用場景	依賴注入、外部初始化	延遲計算、高開銷操作

使用場景比較

class ComparisonExample {
    
    // lateinit：適合依賴注入
    @Autowired
    lateinit var repository: UserRepository
    
    // lazy：適合計算密集型初始化
    private val expensiveResource: DatabaseConnection by lazy {
        createDatabaseConnection() // 僅在首次使用時執行
    }
    
    // lateinit：可重新賦值
    lateinit var currentUser: User
    
    fun switchUser(newUser: User) {
        currentUser = newUser // 可以重新賦值
    }
    
    // lazy：線程安全的單例初始化
    private val singleton: ServiceManager by lazy(LazyThreadSafetyMode.SYNCHRONIZED) {
        ServiceManager.create()
    }
    
    // lateinit：手動控制初始化時機
    lateinit var testDatabase: TestDatabase
    
    @BeforeEach
    fun setupTest() {
        testDatabase = createTestDatabase()
    }
    
    @AfterEach
    fun cleanupTest() {
        if (::testDatabase.isInitialized) {
            testDatabase.cleanup()
        }
    }
}

進階使用模式

1. 條件初始化模式

class ConditionalInitialization {
    lateinit var primaryDatabase: Database
    lateinit var secondaryDatabase: Database
    
    fun initializeDatabases(config: DatabaseConfig) {
        // 主資料庫總是初始化
        primaryDatabase = createDatabase(config.primary)
        
        // 次要資料庫僅在啟用時初始化
        if (config.enableSecondary) {
            secondaryDatabase = createDatabase(config.secondary)
        }
    }
    
    fun executeQuery(query: String): QueryResult {
        val result = primaryDatabase.execute(query)
        
        // 安全地使用次要資料庫
        if (::secondaryDatabase.isInitialized) {
            secondaryDatabase.logQuery(query, result)
        }
        
        return result
    }
}

2. 初始化鏈模式

class InitializationChain {
    lateinit var configService: ConfigService
    lateinit var databaseService: DatabaseService
    lateinit var cacheService: CacheService
    lateinit var businessService: BusinessService
    
    fun initializeAll() {
        initializeConfig()
        initializeDatabase()
        initializeCache()
        initializeBusiness()
        validateInitialization()
    }
    
    private fun initializeConfig() {
        configService = ConfigService()
        logger.info("Config service initialized")
    }
    
    private fun initializeDatabase() {
        require(::configService.isInitialized) { "Config service must be initialized first" }
        databaseService = DatabaseService(configService.getDatabaseConfig())
        logger.info("Database service initialized")
    }
    
    private fun initializeCache() {
        require(::configService.isInitialized) { "Config service must be initialized first" }
        cacheService = CacheService(configService.getCacheConfig())
        logger.info("Cache service initialized")
    }
    
    private fun initializeBusiness() {
        require(::databaseService.isInitialized) { "Database service must be initialized first" }
        require(::cacheService.isInitialized) { "Cache service must be initialized first" }
        
        businessService = BusinessService(databaseService, cacheService)
        logger.info("Business service initialized")
    }
    
    private fun validateInitialization() {
        val errors = mutableListOf<String>()
        
        if (!::configService.isInitialized) errors.add("ConfigService")
        if (!::databaseService.isInitialized) errors.add("DatabaseService")
        if (!::cacheService.isInitialized) errors.add("CacheService")
        if (!::businessService.isInitialized) errors.add("BusinessService")
        
        if (errors.isNotEmpty()) {
            throw InitializationException("未初始化的服務: ${errors.joinToString(", ")}")
        }
        
        logger.info("所有服務初始化完成")
    }
    
    companion object {
        private val logger = LoggerFactory.getLogger(InitializationChain::class.java)
    }
}

3. 資源管理模式

class ResourceManager : AutoCloseable {
    lateinit var connectionPool: ConnectionPool
    lateinit var cacheManager: CacheManager
    lateinit var fileManager: FileManager
    
    private val initializedResources = mutableSetOf<String>()
    
    fun initializeConnectionPool(config: ConnectionConfig) {
        connectionPool = ConnectionPool.create(config)
        initializedResources.add("connectionPool")
        logger.info("Connection pool initialized with ${config.maxConnections} connections")
    }
    
    fun initializeCacheManager(config: CacheConfig) {
        cacheManager = CacheManager.create(config)
        initializedResources.add("cacheManager")
        logger.info("Cache manager initialized with ${config.maxSize} max size")
    }
    
    fun initializeFileManager(config: FileConfig) {
        fileManager = FileManager.create(config)
        initializedResources.add("fileManager")
        logger.info("File manager initialized with root: ${config.rootPath}")
    }
    
    fun getResourceStatus(): Map<String, Boolean> {
        return mapOf(
            "connectionPool" to ::connectionPool.isInitialized,
            "cacheManager" to ::cacheManager.isInitialized,
            "fileManager" to ::fileManager.isInitialized
        )
    }
    
    override fun close() {
        logger.info("開始關閉資源管理器")
        
        // 按相反順序關閉資源
        if (::fileManager.isInitialized) {
            try {
                fileManager.close()
                logger.info("File manager closed")
            } catch (e: Exception) {
                logger.error("Error closing file manager", e)
            }
        }
        
        if (::cacheManager.isInitialized) {
            try {
                cacheManager.close()
                logger.info("Cache manager closed")
            } catch (e: Exception) {
                logger.error("Error closing cache manager", e)
            }
        }
        
        if (::connectionPool.isInitialized) {
            try {
                connectionPool.close()
                logger.info("Connection pool closed")
            } catch (e: Exception) {
                logger.error("Error closing connection pool", e)
            }
        }
        
        initializedResources.clear()
        logger.info("資源管理器關閉完成")
    }
    
    companion object {
        private val logger = LoggerFactory.getLogger(ResourceManager::class.java)
    }
}

測試策略

1. 單元測試模式

class UserServiceTest {
    
    @Mock
    lateinit var userRepository: UserRepository
    
    @Mock
    lateinit var emailService: EmailService
    
    @InjectMocks
    lateinit var userService: UserService
    
    @BeforeEach
    fun setup() {
        MockitoAnnotations.openMocks(this)
        
        // 驗證依賴注入是否成功
        assertTrue(::userRepository.isInitialized, "UserRepository should be initialized")
        assertTrue(::emailService.isInitialized, "EmailService should be initialized")
        assertTrue(::userService.isInitialized, "UserService should be initialized")
    }
    
    @Test
    fun `should create user successfully`() {
        // Given
        val userData = UserCreateRequest(
            email = "test@example.com",
            username = "testuser"
        )
        val expectedUser = User(1L, "test@example.com", "testuser")
        
        `when`(userRepository.save(any())).thenReturn(expectedUser)
        doNothing().`when`(emailService).sendWelcomeEmail(any())
        
        // When
        val result = userService.createUser(userData)
        
        // Then
        assertEquals(expectedUser, result)
        verify(userRepository).save(any())
        verify(emailService).sendWelcomeEmail(expectedUser)
    }
    
    @Test
    fun `should handle uninitialized dependencies gracefully`() {
        // 測試未初始化的情況
        val service = UserService()
        
        assertFalse(service::userRepository.isInitialized)
        assertFalse(service::emailService.isInitialized)
        
        assertThrows<UninitializedPropertyAccessException> {
            service.createUser(UserCreateRequest("test@example.com", "test"))
        }
    }
}

2. 整合測試模式

@SpringBootTest
@TestPropertySource(properties = [
    "spring.datasource.url=jdbc:h2:mem:testdb",
    "spring.jpa.hibernate.ddl-auto=create-drop"
])
class UserServiceIntegrationTest {
    
    @Autowired
    lateinit var userService: UserService
    
    @Autowired
    lateinit var userRepository: UserRepository
    
    @TestConfiguration
    class TestConfig {
        @Bean
        @Primary
        fun mockEmailService(): EmailService = mockk(relaxed = true)
    }
    
    @Test
    fun `should initialize all dependencies in Spring context`() {
        // 驗證 Spring 上下文中的依賴注入
        assertTrue(userService::userRepository.isInitialized)
        assertTrue(userService::emailService.isInitialized)
        
        // 執行實際的業務邏輯測試
        val userData = UserCreateRequest("integration@test.com", "integrationuser")
        val result = userService.createUser(userData)
        
        assertNotNull(result.id)
        assertEquals("integration@test.com", result.email)
        assertEquals("integrationuser", result.username)
        
        // 驗證資料實際儲存
        val savedUser = userRepository.findById(result.id!!)
        assertTrue(savedUser.isPresent)
        assertEquals(result.email, savedUser.get().email)
    }
}

效能優化與最佳實踐

1. 記憶體管理

class MemoryOptimizedService {
    // 大型物件使用 lateinit 延遲初始化
    lateinit var largeDataSet: LargeDataSet
    lateinit var heavyProcessor: HeavyProcessor
    
    // 小型配置物件可以直接初始化
    private val config = ServiceConfig()
    
    fun initializeHeavyResources() {
        if (!::largeDataSet.isInitialized) {
            largeDataSet = LargeDataSet.loadFromDatabase()
            logger.info("Large dataset loaded: ${largeDataSet.size} records")
        }
        
        if (!::heavyProcessor.isInitialized) {
            heavyProcessor = HeavyProcessor(largeDataSet)
            logger.info("Heavy processor initialized")
        }
    }
    
    fun processDataIfReady(input: String): String? {
        return if (::heavyProcessor.isInitialized) {
            heavyProcessor.process(input)
        } else {
            logger.warn("Heavy processor not initialized, skipping processing")
            null
        }
    }
    
    // 清理資源
    fun cleanup() {
        if (::heavyProcessor.isInitialized) {
            heavyProcessor.cleanup()
        }
        
        if (::largeDataSet.isInitialized) {
            largeDataSet.cleanup()
        }
    }
    
    companion object {
        private val logger = LoggerFactory.getLogger(MemoryOptimizedService::class.java)
    }
}

2. 線程安全考量

class ThreadSafeService {
    @Volatile
    lateinit var sharedResource: SharedResource
    
    private val initializationLock = ReentrantLock()
    private val condition = initializationLock.newCondition()
    
    fun initializeSharedResource(config: ResourceConfig) {
        initializationLock.withLock {
            if (!::sharedResource.isInitialized) {
                sharedResource = SharedResource.create(config)
                condition.signalAll() // 通知等待的線程
                logger.info("Shared resource initialized")
            }
        }
    }
    
    fun accessSharedResource(): String {
        // 等待初始化完成
        initializationLock.withLock {
            while (!::sharedResource.isInitialized) {
                condition.await(5, TimeUnit.SECONDS)
                if (!::sharedResource.isInitialized) {
                    throw TimeoutException("Shared resource initialization timeout")
                }
            }
        }
        
        return sharedResource.getData()
    }
    
    fun isResourceReady(): Boolean {
        return ::sharedResource.isInitialized
    }
    
    companion object {
        private val logger = LoggerFactory.getLogger(ThreadSafeService::class.java)
    }
}

常見陷阱與錯誤處理

1. 常見錯誤模式

class CommonMistakes {
    lateinit var service: SomeService
    
    // ❌ 錯誤：在初始化前訪問
    fun badExample1() {
        service.doSomething() // UninitializedPropertyAccessException
    }
    
    // ❌ 錯誤：忘記檢查初始化狀態
    fun badExample2() {
        val result = service.getData() // 可能未初始化
        return result
    }
    
    // ✅ 正確：檢查後訪問
    fun goodExample1() {
        if (::service.isInitialized) {
            service.doSomething()
        } else {
            logger.warn("Service not initialized")
        }
    }
    
    // ✅ 正確：防禦性初始化
    fun goodExample2(): String {
        if (!::service.isInitialized) {
            service = SomeService.createDefault()
        }
        return service.getData()
    }
}

2. 錯誤處理策略

class ErrorHandlingService {
    lateinit var primaryService: PrimaryService
    lateinit var backupService: BackupService
    
    fun processRequest(request: Request): Response {
        return try {
            // 嘗試使用主要服務
            if (::primaryService.isInitialized) {
                primaryService.process(request)
            } else {
                throw ServiceNotInitializedException("Primary service not available")
            }
        } catch (e: ServiceNotInitializedException) {
            logger.warn("Primary service unavailable, falling back to backup", e)
            
            // 備援服務處理
            if (::backupService.isInitialized) {
                backupService.process(request)
            } else {
                throw ServiceUnavailableException("No services available")
            }
        } catch (e: Exception) {
            logger.error("Unexpected error processing request", e)
            throw ProcessingException("Failed to process request", e)
        }
    }
    
    fun healthCheck(): HealthStatus {
        val status = HealthStatus()
        
        status.primaryServiceAvailable = ::primaryService.isInitialized
        status.backupServiceAvailable = ::backupService.isInitialized
        
        status.overallStatus = when {
            status.primaryServiceAvailable -> HealthStatus.Status.HEALTHY
            status.backupServiceAvailable -> HealthStatus.Status.DEGRADED
            else -> HealthStatus.Status.UNHEALTHY
        }
        
        return status
    }
    
    companion object {
        private val logger = LoggerFactory.getLogger(ErrorHandlingService::class.java)
    }
}

企業級最佳實踐

1. 初始化驗證框架

@Component
class InitializationValidator {
    
    fun validateObject(obj: Any): ValidationResult {
        val result = ValidationResult()
        val clazz = obj::class
        
        // 使用反射檢查所有 lateinit 屬性
        clazz.memberProperties
            .filterIsInstance<KMutableProperty1<Any, Any>>()
            .filter { it.isLateinit }
            .forEach { property ->
                try {
                    if (!property.isInitialized(obj)) {
                        result.addError("Property '${property.name}' is not initialized")
                    } else {
                        result.addSuccess("Property '${property.name}' is initialized")
                    }
                } catch (e: Exception) {
                    result.addError("Error checking property '${property.name}': ${e.message}")
                }
            }
        
        return result
    }
    
    @EventListener
    fun onApplicationReady(event: ApplicationReadyEvent) {
        logger.info("開始驗證應用程式初始化狀態")
        
        val context = event.applicationContext
        val beanNames = context.beanDefinitionNames
        
        var totalBeans = 0
        var validatedBeans = 0
        var errorCount = 0
        
        beanNames.forEach { beanName ->
            try {
                val bean = context.getBean(beanName)
                totalBeans++
                
                val result = validateObject(bean)
                if (result.hasErrors()) {
                    logger.warn("Bean '$beanName' has initialization issues: ${result.getErrors()}")
                    errorCount += result.getErrorCount()
                } else {
                    validatedBeans++
                }
            } catch (e: Exception) {
                logger.debug("Skipped validation for bean '$beanName': ${e.message}")
            }
        }
        
        logger.info("初始化驗證完成: $validatedBeans/$totalBeans beans validated, $errorCount errors found")
    }
    
    companion object {
        private val logger = LoggerFactory.getLogger(InitializationValidator::class.java)
    }
}

data class ValidationResult(
    private val errors: MutableList<String> = mutableListOf(),
    private val successes: MutableList<String> = mutableListOf()
) {
    fun addError(error: String) = errors.add(error)
    fun addSuccess(success: String) = successes.add(success)
    fun hasErrors() = errors.isNotEmpty()
    fun getErrors() = errors.toList()
    fun getSuccesses() = successes.toList()
    fun getErrorCount() = errors.size
}

2. 監控與診斷

@Component
class LateinitMonitor {
    
    private val meterRegistry: MeterRegistry = Metrics.globalRegistry
    private val initializationTimer = Timer.builder("lateinit.initialization.time")
        .description("Time taken to initialize lateinit properties")
        .register(meterRegistry)
    
    fun <T> monitorInitialization(
        propertyName: String,
        initializer: () -> T
    ): T {
        return Timer.Sample.start(meterRegistry).use { sample ->
            try {
                val result = initializer()
                
                // 記錄成功的初始化
                Counter.builder("lateinit.initialization.success")
                    .tag("property", propertyName)
                    .register(meterRegistry)
                    .increment()
                
                sample.stop(initializationTimer.withTag("property", propertyName))
                logger.info("Successfully initialized property: $propertyName")
                
                result
            } catch (e: Exception) {
                // 記錄失敗的初始化
                Counter.builder("lateinit.initialization.failure")
                    .tag("property", propertyName)
                    .tag("error", e.javaClass.simpleName)
                    .register(meterRegistry)
                    .increment()
                
                logger.error("Failed to initialize property: $propertyName", e)
                throw e
            }
        }
    }
    
    @Scheduled(fixedRate = 60000) // 每分鐘檢查一次
    fun reportInitializationStatus() {
        val successCount = meterRegistry.counter("lateinit.initialization.success").count()
        val failureCount = meterRegistry.counter("lateinit.initialization.failure").count()
        val totalCount = successCount + failureCount
        
        if (totalCount > 0) {
            val successRate = (successCount / totalCount) * 100
            logger.info("Lateinit initialization statistics - Success rate: ${"%.2f".format(successRate)}% ($successCount/$totalCount)")
        }
    }
    
    companion object {
        private val logger = LoggerFactory.getLogger(LateinitMonitor::class.java)
    }
}

效能基準測試

初始化效能比較

@BenchmarkMode(Mode.AverageTime)
@OutputTimeUnit(TimeUnit.NANOSECONDS)
@State(Scope.Benchmark)
class LateinitPerformanceBenchmark {
    
    // 測試類別
    class LateinitExample {
        lateinit var service: ExpensiveService
        
        fun initializeService() {
            service = ExpensiveService()
        }
    }
    
    class LazyExample {
        private val service: ExpensiveService by lazy { ExpensiveService() }
        
        fun getService(): ExpensiveService = service
    }
    
    class EagerExample {
        private val service: ExpensiveService = ExpensiveService()
        
        fun getService(): ExpensiveService = service
    }
    
    @Benchmark
    fun lateinitInitialization(): ExpensiveService {
        val example = LateinitExample()
        example.initializeService()
        return example.service
    }
    
    @Benchmark
    fun lazyInitialization(): ExpensiveService {
        val example = LazyExample()
        return example.getService()
    }
    
    @Benchmark
    fun eagerInitialization(): ExpensiveService {
        val example = EagerExample()
        return example.getService()
    }
    
    @Benchmark
    fun lateinitAccessAfterInit(): String {
        val example = LateinitExample()
        example.initializeService()
        return example.service.getData() // 訪問已初始化的屬性
    }
    
    @Benchmark
    fun lazyAccess(): String {
        val example = LazyExample()
        example.getService() // 首次訪問，觸發初始化
        return example.getService().getData() // 再次訪問，使用快取值
    }
}

總結

lateinit 是 Kotlin 中強大的延遲初始化機制，特別適用於：

JWT 認證機制完整實作：Spring Security 整合與最佳實踐

Thu, 01 Jul 2021 23:39:52 +0800

概述

JSON Web Token (JWT) 是一種開放標準 (RFC 7519)，定義了一種簡潔、自包含的方式，用於在各方之間安全地傳輸資訊。JWT 在現代 Web 應用程式中廣泛用於身份驗證和授權，特別適合分散式系統和微服務架構。

JWT 核心特徵

無狀態性：伺服器不需要儲存 Session 資訊
可擴展性：適合分散式和微服務環境
跨域支援：支援跨網域請求
自包含：Token 包含所有必要的使用者資訊
數位簽名：確保 Token 的完整性和真實性

JWT 結構

JWT 由三部分組成，以點號（.）分隔：

`1`	`Header.Payload.Signature`

Header：包含 Token 類型和簽名演算法
Payload：包含聲明（Claims），即使用者資訊和其他資料
Signature：用於驗證 Token 是否被篡改

Spring Boot 整合實作

1. 依賴配置

Maven 依賴設定

<properties>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <java.version>17</java.version>
    <maven.compiler.source>17</maven.compiler.source>
    <maven.compiler.target>17</maven.compiler.target>
    <jjwt.version>0.12.3</jjwt.version>
</properties>

<!-- Spring Boot Starters -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-security</artifactId>
</dependency>

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-data-jpa</artifactId>
</dependency>

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-validation</artifactId>
</dependency>

<!-- JWT Library (推薦使用最新版本) -->
<dependency>
    <groupId>io.jsonwebtoken</groupId>
    <artifactId>jjwt-api</artifactId>
    <version>${jjwt.version}</version>
</dependency>

<dependency>
    <groupId>io.jsonwebtoken</groupId>
    <artifactId>jjwt-impl</artifactId>
    <version>${jjwt.version}</version>
    <scope>runtime</scope>
</dependency>

<dependency>
    <groupId>io.jsonwebtoken</groupId>
    <artifactId>jjwt-jackson</artifactId>
    <version>${jjwt.version}</version>
    <scope>runtime</scope>
</dependency>

Gradle 依賴設定

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-web'
    implementation 'org.springframework.boot:spring-boot-starter-security'
    implementation 'org.springframework.boot:spring-boot-starter-data-jpa'
    implementation 'org.springframework.boot:spring-boot-starter-validation'
    
    implementation 'io.jsonwebtoken:jjwt-api:0.12.3'
    runtimeOnly 'io.jsonwebtoken:jjwt-impl:0.12.3'
    runtimeOnly 'io.jsonwebtoken:jjwt-jackson:0.12.3'
}

2. 資料模型

認證請求 DTO

package com.example.jwt.dto;

import jakarta.validation.constraints.NotBlank;
import jakarta.validation.constraints.Size;

public class AuthenticationRequest {
    
    @NotBlank(message = "使用者名稱不能為空")
    @Size(min = 3, max = 50, message = "使用者名稱長度必須在3-50字符之間")
    private String username;
    
    @NotBlank(message = "密碼不能為空")
    @Size(min = 6, max = 100, message = "密碼長度必須在6-100字符之間")
    private String password;
    
    // 建構子
    public AuthenticationRequest() {}
    
    public AuthenticationRequest(String username, String password) {
        this.username = username;
        this.password = password;
    }
    
    // Getters and Setters
    public String getUsername() {
        return username;
    }
    
    public void setUsername(String username) {
        this.username = username;
    }
    
    public String getPassword() {
        return password;
    }
    
    public void setPassword(String password) {
        this.password = password;
    }
}

認證回應 DTO

package com.example.jwt.dto;

import com.fasterxml.jackson.annotation.JsonProperty;

public class AuthenticationResponse {
    
    @JsonProperty("access_token")
    private final String accessToken;
    
    @JsonProperty("token_type")
    private final String tokenType = "Bearer";
    
    @JsonProperty("expires_in")
    private final long expiresIn;
    
    @JsonProperty("refresh_token")
    private String refreshToken;
    
    public AuthenticationResponse(String accessToken, long expiresIn) {
        this.accessToken = accessToken;
        this.expiresIn = expiresIn;
    }
    
    public AuthenticationResponse(String accessToken, long expiresIn, String refreshToken) {
        this.accessToken = accessToken;
        this.expiresIn = expiresIn;
        this.refreshToken = refreshToken;
    }
    
    // Getters
    public String getAccessToken() {
        return accessToken;
    }
    
    public String getTokenType() {
        return tokenType;
    }
    
    public long getExpiresIn() {
        return expiresIn;
    }
    
    public String getRefreshToken() {
        return refreshToken;
    }
}

使用者實體

package com.example.jwt.entity;

import jakarta.persistence.*;
import jakarta.validation.constraints.Email;
import jakarta.validation.constraints.NotBlank;
import org.springframework.security.core.GrantedAuthority;
import org.springframework.security.core.authority.SimpleGrantedAuthority;
import org.springframework.security.core.userdetails.UserDetails;

import java.time.LocalDateTime;
import java.util.*;
import java.util.stream.Collectors;

@Entity
@Table(name = "users")
public class User implements UserDetails {
    
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
    
    @NotBlank
    @Column(unique = true, nullable = false)
    private String username;
    
    @NotBlank
    @Email
    @Column(unique = true, nullable = false)
    private String email;
    
    @NotBlank
    @Column(nullable = false)
    private String password;
    
    @Column(name = "first_name")
    private String firstName;
    
    @Column(name = "last_name")
    private String lastName;
    
    @Column(name = "enabled")
    private boolean enabled = true;
    
    @Column(name = "account_non_expired")
    private boolean accountNonExpired = true;
    
    @Column(name = "credentials_non_expired")
    private boolean credentialsNonExpired = true;
    
    @Column(name = "account_non_locked")
    private boolean accountNonLocked = true;
    
    @Column(name = "created_at")
    private LocalDateTime createdAt = LocalDateTime.now();
    
    @Column(name = "updated_at")
    private LocalDateTime updatedAt = LocalDateTime.now();
    
    @ElementCollection(targetClass = Role.class, fetch = FetchType.EAGER)
    @Enumerated(EnumType.STRING)
    @CollectionTable(name = "user_roles")
    private Set<Role> roles = new HashSet<>();
    
    // 建構子
    public User() {}
    
    public User(String username, String email, String password) {
        this.username = username;
        this.email = email;
        this.password = password;
        this.roles.add(Role.USER);
    }
    
    // UserDetails interface 實作
    @Override
    public Collection<? extends GrantedAuthority> getAuthorities() {
        return roles.stream()
                .map(role -> new SimpleGrantedAuthority("ROLE_" + role.name()))
                .collect(Collectors.toList());
    }
    
    @Override
    public String getPassword() {
        return password;
    }
    
    @Override
    public String getUsername() {
        return username;
    }
    
    @Override
    public boolean isAccountNonExpired() {
        return accountNonExpired;
    }
    
    @Override
    public boolean isAccountNonLocked() {
        return accountNonLocked;
    }
    
    @Override
    public boolean isCredentialsNonExpired() {
        return credentialsNonExpired;
    }
    
    @Override
    public boolean isEnabled() {
        return enabled;
    }
    
    // Getters and Setters
    public Long getId() { return id; }
    public void setId(Long id) { this.id = id; }
    
    public void setUsername(String username) { this.username = username; }
    
    public String getEmail() { return email; }
    public void setEmail(String email) { this.email = email; }
    
    public void setPassword(String password) { this.password = password; }
    
    public String getFirstName() { return firstName; }
    public void setFirstName(String firstName) { this.firstName = firstName; }
    
    public String getLastName() { return lastName; }
    public void setLastName(String lastName) { this.lastName = lastName; }
    
    public Set<Role> getRoles() { return roles; }
    public void setRoles(Set<Role> roles) { this.roles = roles; }
    
    public LocalDateTime getCreatedAt() { return createdAt; }
    public LocalDateTime getUpdatedAt() { return updatedAt; }
    
    @PreUpdate
    public void preUpdate() {
        this.updatedAt = LocalDateTime.now();
    }
}

enum Role {
    USER, ADMIN, MODERATOR
}

3. JWT 工具類

package com.example.jwt.util;

import io.jsonwebtoken.*;
import io.jsonwebtoken.io.Decoders;
import io.jsonwebtoken.security.Keys;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.security.core.userdetails.UserDetails;
import org.springframework.stereotype.Component;

import javax.crypto.SecretKey;
import java.util.Date;
import java.util.HashMap;
import java.util.Map;
import java.util.function.Function;

@Component
public class JwtUtil {
    
    private static final Logger logger = LoggerFactory.getLogger(JwtUtil.class);
    
    @Value("${jwt.secret}")
    private String jwtSecret;
    
    @Value("${jwt.expiration}")
    private long jwtExpiration;
    
    @Value("${jwt.refresh-expiration}")
    private long refreshExpiration;
    
    /**
     * 從 Token 中提取使用者名稱
     */
    public String extractUsername(String token) {
        return extractClaim(token, Claims::getSubject);
    }
    
    /**
     * 從 Token 中提取過期時間
     */
    public Date extractExpiration(String token) {
        return extractClaim(token, Claims::getExpiration);
    }
    
    /**
     * 從 Token 中提取特定的聲明
     */
    public <T> T extractClaim(String token, Function<Claims, T> claimsResolver) {
        final Claims claims = extractAllClaims(token);
        return claimsResolver.apply(claims);
    }
    
    /**
     * 提取 Token 中的所有聲明
     */
    private Claims extractAllClaims(String token) {
        try {
            return Jwts.parser()
                    .verifyWith(getSignInKey())
                    .build()
                    .parseSignedClaims(token)
                    .getPayload();
        } catch (ExpiredJwtException e) {
            logger.warn("JWT token 已過期: {}", e.getMessage());
            throw e;
        } catch (UnsupportedJwtException e) {
            logger.warn("不支援的 JWT token: {}", e.getMessage());
            throw e;
        } catch (MalformedJwtException e) {
            logger.warn("格式錯誤的 JWT token: {}", e.getMessage());
            throw e;
        } catch (IllegalArgumentException e) {
            logger.warn("JWT claims string 為空: {}", e.getMessage());
            throw e;
        }
    }
    
    /**
     * 檢查 Token 是否過期
     */
    public boolean isTokenExpired(String token) {
        try {
            return extractExpiration(token).before(new Date());
        } catch (ExpiredJwtException e) {
            return true;
        }
    }
    
    /**
     * 生成訪問 Token
     */
    public String generateAccessToken(UserDetails userDetails) {
        Map<String, Object> claims = new HashMap<>();
        claims.put("roles", userDetails.getAuthorities());
        return createToken(claims, userDetails.getUsername(), jwtExpiration);
    }
    
    /**
     * 生成刷新 Token
     */
    public String generateRefreshToken(UserDetails userDetails) {
        return createToken(new HashMap<>(), userDetails.getUsername(), refreshExpiration);
    }
    
    /**
     * 創建 Token
     */
    private String createToken(Map<String, Object> claims, String subject, long expiration) {
        Date now = new Date();
        Date expiryDate = new Date(now.getTime() + expiration);
        
        return Jwts.builder()
                .claims(claims)
                .subject(subject)
                .issuedAt(now)
                .expiration(expiryDate)
                .signWith(getSignInKey())
                .compact();
    }
    
    /**
     * 驗證 Token
     */
    public boolean validateToken(String token, UserDetails userDetails) {
        try {
            final String username = extractUsername(token);
            return (username.equals(userDetails.getUsername()) && !isTokenExpired(token));
        } catch (JwtException | IllegalArgumentException e) {
            logger.warn("JWT token 驗證失敗: {}", e.getMessage());
            return false;
        }
    }
    
    /**
     * 驗證 Token 格式和簽名
     */
    public boolean validateToken(String token) {
        try {
            Jwts.parser()
                    .verifyWith(getSignInKey())
                    .build()
                    .parseSignedClaims(token);
            return true;
        } catch (JwtException | IllegalArgumentException e) {
            logger.warn("JWT token 驗證失敗: {}", e.getMessage());
            return false;
        }
    }
    
    /**
     * 獲取簽名金鑰
     */
    private SecretKey getSignInKey() {
        byte[] keyBytes = Decoders.BASE64.decode(jwtSecret);
        return Keys.hmacShaKeyFor(keyBytes);
    }
    
    /**
     * 獲取 Token 的剩餘有效時間（毫秒）
     */
    public long getExpirationTime() {
        return jwtExpiration;
    }
    
    /**
     * 檢查 Token 是否需要刷新（剩餘時間少於 30 分鐘）
     */
    public boolean shouldRefreshToken(String token) {
        try {
            Date expiration = extractExpiration(token);
            Date now = new Date();
            long timeLeft = expiration.getTime() - now.getTime();
            return timeLeft < (30 * 60 * 1000); // 30 分鐘
        } catch (Exception e) {
            return false;
        }
    }
}

4. JWT 請求過濾器

package com.example.jwt.filter;

import com.example.jwt.service.CustomUserDetailsService;
import com.example.jwt.util.JwtUtil;
import jakarta.servlet.FilterChain;
import jakarta.servlet.ServletException;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.security.authentication.UsernamePasswordAuthenticationToken;
import org.springframework.security.core.context.SecurityContextHolder;
import org.springframework.security.core.userdetails.UserDetails;
import org.springframework.security.web.authentication.WebAuthenticationDetailsSource;
import org.springframework.stereotype.Component;
import org.springframework.util.StringUtils;
import org.springframework.web.filter.OncePerRequestFilter;

import java.io.IOException;

@Component
public class JwtAuthenticationFilter extends OncePerRequestFilter {
    
    private static final Logger logger = LoggerFactory.getLogger(JwtAuthenticationFilter.class);
    
    private static final String BEARER_PREFIX = "Bearer ";
    private static final String AUTHORIZATION_HEADER = "Authorization";
    
    @Autowired
    private JwtUtil jwtUtil;
    
    @Autowired
    private CustomUserDetailsService userDetailsService;
    
    @Override
    protected void doFilterInternal(HttpServletRequest request, 
                                    HttpServletResponse response, 
                                    FilterChain filterChain) throws ServletException, IOException {
        
        try {
            String jwt = getJwtFromRequest(request);
            
            if (StringUtils.hasText(jwt) && jwtUtil.validateToken(jwt)) {
                String username = jwtUtil.extractUsername(jwt);
                
                // 檢查 SecurityContext 中是否已有認證資訊
                if (username != null && SecurityContextHolder.getContext().getAuthentication() == null) {
                    UserDetails userDetails = userDetailsService.loadUserByUsername(username);
                    
                    if (jwtUtil.validateToken(jwt, userDetails)) {
                        UsernamePasswordAuthenticationToken authentication = 
                            new UsernamePasswordAuthenticationToken(
                                userDetails, null, userDetails.getAuthorities());
                        
                        authentication.setDetails(new WebAuthenticationDetailsSource().buildDetails(request));
                        SecurityContextHolder.getContext().setAuthentication(authentication);
                        
                        logger.debug("設定使用者 '{}' 的安全上下文", username);
                    }
                }
            }
        } catch (Exception e) {
            logger.error("無法設定使用者認證: {}", e.getMessage());
        }
        
        filterChain.doFilter(request, response);
    }
    
    /**
     * 從請求中提取 JWT Token
     */
    private String getJwtFromRequest(HttpServletRequest request) {
        String bearerToken = request.getHeader(AUTHORIZATION_HEADER);
        
        if (StringUtils.hasText(bearerToken) && bearerToken.startsWith(BEARER_PREFIX)) {
            return bearerToken.substring(BEARER_PREFIX.length());
        }
        
        return null;
    }
    
    @Override
    protected boolean shouldNotFilter(HttpServletRequest request) throws ServletException {
        String path = request.getRequestURI();
        // 排除不需要 JWT 驗證的路徑
        return path.startsWith("/api/auth/") || 
               path.startsWith("/swagger-ui/") || 
               path.startsWith("/v3/api-docs/") ||
               path.equals("/health") ||
               path.equals("/favicon.ico");
    }
}

5. Spring Security 配置

package com.example.jwt.config;

import com.example.jwt.filter.JwtAuthenticationFilter;
import com.example.jwt.service.CustomUserDetailsService;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.authentication.AuthenticationManager;
import org.springframework.security.authentication.AuthenticationProvider;
import org.springframework.security.authentication.dao.DaoAuthenticationProvider;
import org.springframework.security.config.annotation.authentication.configuration.AuthenticationConfiguration;
import org.springframework.security.config.annotation.method.configuration.EnableMethodSecurity;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
import org.springframework.security.config.annotation.web.configurers.AbstractHttpConfigurer;
import org.springframework.security.config.http.SessionCreationPolicy;
import org.springframework.security.crypto.bcrypt.BCryptPasswordEncoder;
import org.springframework.security.crypto.password.PasswordEncoder;
import org.springframework.security.web.SecurityFilterChain;
import org.springframework.security.web.authentication.UsernamePasswordAuthenticationFilter;
import org.springframework.web.cors.CorsConfiguration;
import org.springframework.web.cors.CorsConfigurationSource;
import org.springframework.web.cors.UrlBasedCorsConfigurationSource;

import java.util.Arrays;

@Configuration
@EnableWebSecurity
@EnableMethodSecurity(prePostEnabled = true)
public class SecurityConfig {
    
    @Autowired
    private CustomUserDetailsService userDetailsService;
    
    @Autowired
    private JwtAuthenticationFilter jwtAuthenticationFilter;
    
    @Autowired
    private JwtAuthenticationEntryPoint jwtAuthenticationEntryPoint;
    
    @Bean
    public PasswordEncoder passwordEncoder() {
        return new BCryptPasswordEncoder(12);
    }
    
    @Bean
    public AuthenticationProvider authenticationProvider() {
        DaoAuthenticationProvider authProvider = new DaoAuthenticationProvider();
        authProvider.setUserDetailsService(userDetailsService);
        authProvider.setPasswordEncoder(passwordEncoder());
        return authProvider;
    }
    
    @Bean
    public AuthenticationManager authenticationManager(AuthenticationConfiguration config) throws Exception {
        return config.getAuthenticationManager();
    }
    
    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            .csrf(AbstractHttpConfigurer::disable)
            .cors(cors -> cors.configurationSource(corsConfigurationSource()))
            .sessionManagement(session -> session.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
            .authorizeHttpRequests(authz -> authz
                // 公開端點
                .requestMatchers(
                    "/api/auth/**",
                    "/swagger-ui/**",
                    "/v3/api-docs/**",
                    "/health",
                    "/favicon.ico"
                ).permitAll()
                // 管理員端點
                .requestMatchers("/api/admin/**").hasRole("ADMIN")
                // 其他端點需要認證
                .anyRequest().authenticated()
            )
            .exceptionHandling(ex -> ex.authenticationEntryPoint(jwtAuthenticationEntryPoint))
            .authenticationProvider(authenticationProvider())
            .addFilterBefore(jwtAuthenticationFilter, UsernamePasswordAuthenticationFilter.class);
        
        return http.build();
    }
    
    @Bean
    public CorsConfigurationSource corsConfigurationSource() {
        CorsConfiguration configuration = new CorsConfiguration();
        configuration.setAllowedOriginPatterns(Arrays.asList("*"));
        configuration.setAllowedMethods(Arrays.asList("GET", "POST", "PUT", "DELETE", "OPTIONS"));
        configuration.setAllowedHeaders(Arrays.asList("*"));
        configuration.setAllowCredentials(true);
        
        UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource();
        source.registerCorsConfiguration("/**", configuration);
        return source;
    }
}

6. 認證控制器

package com.example.jwt.controller;

import com.example.jwt.dto.AuthenticationRequest;
import com.example.jwt.dto.AuthenticationResponse;
import com.example.jwt.service.AuthenticationService;
import jakarta.validation.Valid;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/api/auth")
@CrossOrigin(origins = "*", maxAge = 3600)
public class AuthController {
    
    @Autowired
    private AuthenticationService authenticationService;
    
    /**
     * 使用者登入
     */
    @PostMapping("/login")
    public ResponseEntity<AuthenticationResponse> login(
            @Valid @RequestBody AuthenticationRequest request) {
        
        AuthenticationResponse response = authenticationService.authenticate(request);
        return ResponseEntity.ok(response);
    }
    
    /**
     * 刷新 Token
     */
    @PostMapping("/refresh")
    public ResponseEntity<AuthenticationResponse> refreshToken(
            @RequestHeader("Authorization") String refreshToken) {
        
        AuthenticationResponse response = authenticationService.refreshToken(refreshToken);
        return ResponseEntity.ok(response);
    }
    
    /**
     * 登出（可選：加入黑名單機制）
     */
    @PostMapping("/logout")
    public ResponseEntity<Void> logout(@RequestHeader("Authorization") String token) {
        authenticationService.logout(token);
        return ResponseEntity.ok().build();
    }
    
    /**
     * 驗證 Token 有效性
     */
    @GetMapping("/validate")
    public ResponseEntity<Boolean> validateToken(@RequestHeader("Authorization") String token) {
        boolean isValid = authenticationService.validateToken(token);
        return ResponseEntity.ok(isValid);
    }
}

7. 認證服務

package com.example.jwt.service;

import com.example.jwt.dto.AuthenticationRequest;
import com.example.jwt.dto.AuthenticationResponse;
import com.example.jwt.util.JwtUtil;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.security.authentication.AuthenticationManager;
import org.springframework.security.authentication.BadCredentialsException;
import org.springframework.security.authentication.UsernamePasswordAuthenticationToken;
import org.springframework.security.core.Authentication;
import org.springframework.security.core.userdetails.UserDetails;
import org.springframework.stereotype.Service;

@Service
public class AuthenticationService {
    
    @Autowired
    private AuthenticationManager authenticationManager;
    
    @Autowired
    private CustomUserDetailsService userDetailsService;
    
    @Autowired
    private JwtUtil jwtUtil;
    
    @Autowired
    private TokenBlacklistService tokenBlacklistService;
    
    /**
     * 認證使用者並生成 Token
     */
    public AuthenticationResponse authenticate(AuthenticationRequest request) {
        try {
            // 驗證使用者憑證
            Authentication authentication = authenticationManager.authenticate(
                new UsernamePasswordAuthenticationToken(
                    request.getUsername(),
                    request.getPassword()
                )
            );
            
            // 載入使用者詳細資訊
            UserDetails userDetails = userDetailsService.loadUserByUsername(request.getUsername());
            
            // 生成 Token
            String accessToken = jwtUtil.generateAccessToken(userDetails);
            String refreshToken = jwtUtil.generateRefreshToken(userDetails);
            
            return new AuthenticationResponse(
                accessToken,
                jwtUtil.getExpirationTime(),
                refreshToken
            );
            
        } catch (BadCredentialsException e) {
            throw new BadCredentialsException("使用者名稱或密碼錯誤");
        }
    }
    
    /**
     * 刷新 Token
     */
    public AuthenticationResponse refreshToken(String refreshToken) {
        // 移除 Bearer 前綴
        String token = refreshToken.startsWith("Bearer ") ? 
            refreshToken.substring(7) : refreshToken;
        
        if (!jwtUtil.validateToken(token)) {
            throw new RuntimeException("無效的刷新 Token");
        }
        
        String username = jwtUtil.extractUsername(token);
        UserDetails userDetails = userDetailsService.loadUserByUsername(username);
        
        String newAccessToken = jwtUtil.generateAccessToken(userDetails);
        
        return new AuthenticationResponse(newAccessToken, jwtUtil.getExpirationTime());
    }
    
    /**
     * 登出並將 Token 加入黑名單
     */
    public void logout(String token) {
        String jwtToken = token.startsWith("Bearer ") ? 
            token.substring(7) : token;
        
        tokenBlacklistService.blacklistToken(jwtToken);
    }
    
    /**
     * 驗證 Token
     */
    public boolean validateToken(String token) {
        String jwtToken = token.startsWith("Bearer ") ? 
            token.substring(7) : token;
        
        return jwtUtil.validateToken(jwtToken) && 
               !tokenBlacklistService.isTokenBlacklisted(jwtToken);
    }
}

配置檔案

application.yml

# JWT 配置
jwt:
  # 使用強密鑰（至少256位）
  secret: ${JWT_SECRET:dGhpc2lzYXZlcnlzZWN1cmVzZWNyZXRrZXl0aGF0aXNhdGxlYXN0MjU2Yml0c2xvbmc=}
  # Access Token 過期時間（15分鐘）
  expiration: 900000
  # Refresh Token 過期時間（7天）
  refresh-expiration: 604800000

# Spring Security 配置
spring:
  security:
    # OAuth2 配置（可選）
    oauth2:
      client:
        registration:
          google:
            client-id: ${GOOGLE_CLIENT_ID:}
            client-secret: ${GOOGLE_CLIENT_SECRET:}
            scope: openid,profile,email

# 日誌配置
logging:
  level:
    com.example.jwt: DEBUG
    org.springframework.security: DEBUG

安全性最佳實踐

1. 密鑰管理

// 生成安全的密鑰
public class KeyGenerator {
    public static void main(String[] args) {
        SecretKey key = Keys.secretKeyFor(SignatureAlgorithm.HS256);
        String encodedKey = Encoders.BASE64.encode(key.getEncoded());
        System.out.println("Generated key: " + encodedKey);
    }
}

2. Token 黑名單服務

package com.example.jwt.service;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.data.redis.core.RedisTemplate;
import org.springframework.stereotype.Service;

import java.util.concurrent.TimeUnit;

@Service
public class TokenBlacklistService {
    
    @Autowired
    private RedisTemplate<String, String> redisTemplate;
    
    private static final String BLACKLIST_PREFIX = "jwt:blacklist:";
    
    /**
     * 將 Token 加入黑名單
     */
    public void blacklistToken(String token) {
        String key = BLACKLIST_PREFIX + token;
        // 設定過期時間等於 Token 的剩餘有效時間
        redisTemplate.opsForValue().set(key, "blacklisted", 24, TimeUnit.HOURS);
    }
    
    /**
     * 檢查 Token 是否在黑名單中
     */
    public boolean isTokenBlacklisted(String token) {
        String key = BLACKLIST_PREFIX + token;
        return Boolean.TRUE.equals(redisTemplate.hasKey(key));
    }
}

3. 異常處理

package com.example.jwt.exception;

import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.security.authentication.BadCredentialsException;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestControllerAdvice;

@RestControllerAdvice
public class GlobalExceptionHandler {
    
    @ExceptionHandler(BadCredentialsException.class)
    public ResponseEntity<ErrorResponse> handleBadCredentials(BadCredentialsException e) {
        ErrorResponse error = new ErrorResponse(
            HttpStatus.UNAUTHORIZED.value(),
            "認證失敗",
            e.getMessage()
        );
        return ResponseEntity.status(HttpStatus.UNAUTHORIZED).body(error);
    }
    
    @ExceptionHandler(JwtException.class)
    public ResponseEntity<ErrorResponse> handleJwtException(JwtException e) {
        ErrorResponse error = new ErrorResponse(
            HttpStatus.UNAUTHORIZED.value(),
            "Token 錯誤",
            e.getMessage()
        );
        return ResponseEntity.status(HttpStatus.UNAUTHORIZED).body(error);
    }
}

class ErrorResponse {
    private int status;
    private String error;
    private String message;
    private long timestamp;
    
    public ErrorResponse(int status, String error, String message) {
        this.status = status;
        this.error = error;
        this.message = message;
        this.timestamp = System.currentTimeMillis();
    }
    
    // Getters and Setters
    // ...
}

使用範例

1. 前端整合

// JavaScript 前端範例
class AuthService {
    constructor() {
        this.baseURL = 'http://localhost:8080/api';
        this.token = localStorage.getItem('accessToken');
    }
    
    async login(username, password) {
        try {
            const response = await fetch(`${this.baseURL}/auth/login`, {
                method: 'POST',
                headers: {
                    'Content-Type': 'application/json',
                },
                body: JSON.stringify({ username, password })
            });
            
            if (response.ok) {
                const data = await response.json();
                this.token = data.access_token;
                localStorage.setItem('accessToken', this.token);
                localStorage.setItem('refreshToken', data.refresh_token);
                return data;
            } else {
                throw new Error('登入失敗');
            }
        } catch (error) {
            console.error('登入錯誤:', error);
            throw error;
        }
    }
    
    async apiCall(endpoint, options = {}) {
        const config = {
            ...options,
            headers: {
                'Authorization': `Bearer ${this.token}`,
                'Content-Type': 'application/json',
                ...options.headers
            }
        };
        
        let response = await fetch(`${this.baseURL}${endpoint}`, config);
        
        // 如果 Token 過期，嘗試刷新
        if (response.status === 401) {
            await this.refreshToken();
            config.headers['Authorization'] = `Bearer ${this.token}`;
            response = await fetch(`${this.baseURL}${endpoint}`, config);
        }
        
        return response;
    }
    
    async refreshToken() {
        const refreshToken = localStorage.getItem('refreshToken');
        if (!refreshToken) {
            this.logout();
            return;
        }
        
        try {
            const response = await fetch(`${this.baseURL}/auth/refresh`, {
                method: 'POST',
                headers: {
                    'Authorization': `Bearer ${refreshToken}`
                }
            });
            
            if (response.ok) {
                const data = await response.json();
                this.token = data.access_token;
                localStorage.setItem('accessToken', this.token);
            } else {
                this.logout();
            }
        } catch (error) {
            console.error('Token 刷新失敗:', error);
            this.logout();
        }
    }
    
    logout() {
        localStorage.removeItem('accessToken');
        localStorage.removeItem('refreshToken');
        this.token = null;
        window.location.href = '/login';
    }
}

2. 測試範例

package com.example.jwt;

import com.example.jwt.util.JwtUtil;
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.security.core.userdetails.User;
import org.springframework.security.core.userdetails.UserDetails;

import java.util.ArrayList;

import static org.junit.jupiter.api.Assertions.*;

@SpringBootTest
public class JwtUtilTest {
    
    @Autowired
    private JwtUtil jwtUtil;
    
    @Test
    public void testGenerateAndValidateToken() {
        // 建立測試使用者
        UserDetails userDetails = new User("testuser", "password", new ArrayList<>());
        
        // 生成 Token
        String token = jwtUtil.generateAccessToken(userDetails);
        assertNotNull(token);
        
        // 驗證 Token
        assertTrue(jwtUtil.validateToken(token, userDetails));
        
        // 提取使用者名稱
        String extractedUsername = jwtUtil.extractUsername(token);
        assertEquals("testuser", extractedUsername);
        
        // 檢查 Token 是否未過期
        assertFalse(jwtUtil.isTokenExpired(token));
    }
}

效能最佳化

1. Redis 快取

@Configuration
@EnableCaching
public class CacheConfig {
    
    @Bean
    public CacheManager cacheManager(RedisConnectionFactory connectionFactory) {
        RedisCacheConfiguration config = RedisCacheConfiguration.defaultCacheConfig()
                .entryTtl(Duration.ofMinutes(15))
                .serializeKeysWith(RedisSerializationContext.SerializationPair
                        .fromSerializer(new StringRedisSerializer()))
                .serializeValuesWith(RedisSerializationContext.SerializationPair
                        .fromSerializer(new GenericJackson2JsonRedisSerializer()));
        
        return RedisCacheManager.builder(connectionFactory)
                .cacheDefaults(config)
                .build();
    }
}

2. 非同步處理

@Service
public class AsyncAuthService {
    
    @Async
    @EventListener
    public void handleUserLogin(UserLoginEvent event) {
        // 記錄登入日誌
        // 發送通知
        // 更新使用者統計
    }
}

監控和日誌

1. 認證監控

@Component
public class AuthenticationEventListener {
    
    private static final Logger logger = LoggerFactory.getLogger(AuthenticationEventListener.class);
    
    @EventListener
    public void onAuthenticationSuccess(AuthenticationSuccessEvent event) {
        String username = event.getAuthentication().getName();
        logger.info("使用者 {} 登入成功", username);
    }
    
    @EventListener
    public void onAuthenticationFailure(AbstractAuthenticationFailureEvent event) {
        String username = event.getAuthentication().getName();
        logger.warn("使用者 {} 登入失敗: {}", username, event.getException().getMessage());
    }
}

2. 效能監控

@Aspect
@Component
public class JwtPerformanceAspect {
    
    private static final Logger logger = LoggerFactory.getLogger(JwtPerformanceAspect.class);
    
    @Around("execution(* com.example.jwt.util.JwtUtil.*(..))")
    public Object measureExecutionTime(ProceedingJoinPoint joinPoint) throws Throwable {
        long startTime = System.currentTimeMillis();
        Object result = joinPoint.proceed();
        long endTime = System.currentTimeMillis();
        
        logger.debug("方法 {} 執行時間: {} ms", 
                    joinPoint.getSignature().getName(), 
                    endTime - startTime);
        
        return result;
    }
}

常見問題與解決方案

1. Token 過期處理

// 自動 Token 刷新攔截器
@Component
public class TokenRefreshInterceptor implements HandlerInterceptor {
    
    @Autowired
    private JwtUtil jwtUtil;
    
    @Override
    public boolean preHandle(HttpServletRequest request, 
                           HttpServletResponse response, 
                           Object handler) throws Exception {
        
        String token = getTokenFromRequest(request);
        
        if (token != null && jwtUtil.shouldRefreshToken(token)) {
            // 設定回應標頭提示前端刷新 Token
            response.setHeader("X-Token-Refresh-Required", "true");
        }
        
        return true;
    }
}

2. 跨域處理

@Configuration
public class CorsConfig implements WebMvcConfigurer {
    
    @Override
    public void addCorsMappings(CorsRegistry registry) {
        registry.addMapping("/api/**")
                .allowedOriginPatterns("*")
                .allowedMethods("GET", "POST", "PUT", "DELETE", "OPTIONS")
                .allowedHeaders("*")
                .allowCredentials(true)
                .maxAge(3600);
    }
}

總結

核心優勢

無狀態性：伺服器無需存儲 Session，適合分散式系統
可擴展性：支援微服務架構和負載均衡
跨域支援：解決傳統 Session 的跨域問題
安全性：數位簽名確保 Token 完整性
靈活性：可攜帶自訂使用者資訊

最佳實踐

使用強密鑰：至少 256 位的隨機密鑰
適當的過期時間：短期 Access Token + 長期 Refresh Token
Token 黑名單：支援登出和緊急撤銷
HTTPS 傳輸：確保 Token 傳輸安全
輸入驗證：驗證所有使用者輸入
錯誤處理：優雅處理認證錯誤
監控日誌：記錄認證事件和異常

常用命令速查

# 生成密鑰
openssl rand -base64 32

# 解析 JWT Token
echo "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..." | cut -d. -f2 | base64 -d

# 測試 API
curl -X POST http://localhost:8080/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"password"}'

# 使用 Token 訪問 API
curl -X GET http://localhost:8080/api/users \
  -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."

JWT 是現代 Web 應用程式認證的標準解決方案，正確實作能夠提供安全、可擴展的認證機制。記住：安全性設計應該從一開始就考慮，而不是後續添加的功能。

YAML 語法從入門到實踐

Tue, 29 Jun 2021 13:45:56 +0800

前言

在現代軟體開發中，設定檔是不可或缺的一環。從 Java 的 Spring Boot 框架 (Spring MVC 過往使用大量的 XML)，到我目前使用的 Hugo 靜態網站產生器，都能看到 .properties、.yml 或 .toml 等格式的身影。

雖然這些格式各有優勢，但在雲原生領域，特別是設定 Kubernetes (K8s) 資源時，YAML (YAML Ain’t Markup Language) 已成為事實上的標準。因此，掌握 YAML 的語法至關重要。

核心語法

YAML 的設計目標是易於人類閱讀和撰寫。它的語法主要基於縮排和幾個簡單的符號。

註解: 使用 # 號標示單行註解。
文件開頭: 使用三個連字號 --- 作為文件的開始符號 (選用)。

鍵值對 (Key-Value Pair)

YAML 的基本組成單位是鍵值對，格式為 key: value (注意冒號後面需要一個空格)。

`1`	`apiVersion: v1`

階層/物件 (Objects)

透過換行和縮排 (建議使用兩個空格) 來表示階層關係。這在 JSON 中相當於一個物件。

以下範例等同於 spring.datasource.username = "root"。

1
2
3

spring:
  datasource:
    username: root

陣列/列表 (Arrays/Lists)

陣列有兩種常見的表示方式：

CQRS (Command Query Responsibility Segregation) 完整實作指南：命令與查詢職責分離的企業架構模式

Sun, 16 May 2021 21:18:11 +0800

CQRS (Command Query Responsibility Segregation) 完整實作指南

模式概述

CQRS (Command Query Responsibility Segregation，命令查詢職責分離) 是一種架構模式，將讀取操作（Query）和寫入操作（Command）分離到不同的模型中。這種分離允許每個模型針對其特定用途進行優化，提高系統的擴展性和性能。

核心概念

1. CQS 原則基礎

CQS (Command Query Separation) 原則是 CQRS 的理論基礎：

Command（命令）：
- 會對系統產生影響的動作
- 改變系統狀態
- 不回傳結果（void）
- 具有副作用
Query（查詢）：
- 不會對系統產生影響的動作
- 不改變系統狀態
- 回傳結果
- 無副作用

2. CQRS 擴展

CQRS 將 CQS 原則從方法級別擴展到架構級別：

寫入模型（Write Model）：專注於業務邏輯和數據一致性
讀取模型（Read Model）：專注於查詢性能和數據展示
分離的數據存儲：不同的存儲可以針對讀寫操作進行優化

傳統 CQRS 實現

1. 基本架構

// 命令接口
public interface Command {
    // 命令標記接口
}

// 查詢接口
public interface Query<T> {
    // 查詢標記接口
}

// 命令處理器接口
public interface CommandHandler<T extends Command> {
    void handle(T command);
}

// 查詢處理器接口
public interface QueryHandler<T extends Query<R>, R> {
    R handle(T query);
}

// 命令總線
@Component
public class CommandBus {
    private final Map<Class<? extends Command>, CommandHandler<? extends Command>> handlers;
    
    public CommandBus(List<CommandHandler<? extends Command>> handlerList) {
        this.handlers = handlerList.stream()
            .collect(Collectors.toMap(
                this::getCommandType,
                Function.identity()
            ));
    }
    
    @SuppressWarnings("unchecked")
    public <T extends Command> void send(T command) {
        CommandHandler<T> handler = (CommandHandler<T>) handlers.get(command.getClass());
        if (handler == null) {
            throw new IllegalArgumentException("未找到命令處理器: " + command.getClass());
        }
        handler.handle(command);
    }
    
    @SuppressWarnings("unchecked")
    private Class<? extends Command> getCommandType(CommandHandler<? extends Command> handler) {
        return (Class<? extends Command>) ((ParameterizedType) handler.getClass()
            .getGenericInterfaces()[0]).getActualTypeArguments()[0];
    }
}

// 查詢總線
@Component
public class QueryBus {
    private final Map<Class<? extends Query<?>>, QueryHandler<? extends Query<?>, ?>> handlers;
    
    public QueryBus(List<QueryHandler<? extends Query<?>, ?>> handlerList) {
        this.handlers = handlerList.stream()
            .collect(Collectors.toMap(
                this::getQueryType,
                Function.identity()
            ));
    }
    
    @SuppressWarnings("unchecked")
    public <T extends Query<R>, R> R send(T query) {
        QueryHandler<T, R> handler = (QueryHandler<T, R>) handlers.get(query.getClass());
        if (handler == null) {
            throw new IllegalArgumentException("未找到查詢處理器: " + query.getClass());
        }
        return handler.handle(query);
    }
    
    @SuppressWarnings("unchecked")
    private Class<? extends Query<?>> getQueryType(QueryHandler<? extends Query<?>, ?> handler) {
        return (Class<? extends Query<?>>) ((ParameterizedType) handler.getClass()
            .getGenericInterfaces()[0]).getActualTypeArguments()[0];
    }
}

2. 用戶管理系統示例

// 用戶實體（寫入模型）
@Entity
@Table(name = "users")
public class User {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
    
    @Column(nullable = false, unique = true)
    private String username;
    
    @Column(nullable = false)
    private String password;
    
    @Column(nullable = false)
    private String email;
    
    @Enumerated(EnumType.STRING)
    private UserStatus status;
    
    @CreationTimestamp
    private LocalDateTime createdAt;
    
    @UpdateTimestamp
    private LocalDateTime updatedAt;
    
    // 業務方法
    public void activate() {
        this.status = UserStatus.ACTIVE;
    }
    
    public void deactivate() {
        this.status = UserStatus.INACTIVE;
    }
    
    public void updatePassword(String newPassword) {
        this.password = newPassword;
    }
    
    // 構造函數、getter、setter 略
}

// 用戶狀態枚舉
public enum UserStatus {
    ACTIVE, INACTIVE, PENDING, BANNED
}

// 用戶讀取模型
@Document(collection = "user_views")
public class UserView {
    @Id
    private String id;
    private Long userId;
    private String username;
    private String email;
    private String status;
    private String createdAt;
    private String updatedAt;
    private int totalOrders;
    private BigDecimal totalSpent;
    private String lastLoginAt;
    
    // 構造函數、getter、setter 略
}

// 創建用戶命令
public class CreateUserCommand implements Command {
    private final String username;
    private final String password;
    private final String email;
    
    public CreateUserCommand(String username, String password, String email) {
        this.username = username;
        this.password = password;
        this.email = email;
    }
    
    // Getter 方法
    public String getUsername() { return username; }
    public String getPassword() { return password; }
    public String getEmail() { return email; }
}

// 更新用戶命令
public class UpdateUserCommand implements Command {
    private final Long userId;
    private final String email;
    private final UserStatus status;
    
    public UpdateUserCommand(Long userId, String email, UserStatus status) {
        this.userId = userId;
        this.email = email;
        this.status = status;
    }
    
    // Getter 方法
    public Long getUserId() { return userId; }
    public String getEmail() { return email; }
    public UserStatus getStatus() { return status; }
}

// 用戶查詢
public class GetUserQuery implements Query<UserView> {
    private final Long userId;
    
    public GetUserQuery(Long userId) {
        this.userId = userId;
    }
    
    public Long getUserId() { return userId; }
}

// 用戶列表查詢
public class GetUserListQuery implements Query<Page<UserView>> {
    private final String username;
    private final UserStatus status;
    private final Pageable pageable;
    
    public GetUserListQuery(String username, UserStatus status, Pageable pageable) {
        this.username = username;
        this.status = status;
        this.pageable = pageable;
    }
    
    // Getter 方法
    public String getUsername() { return username; }
    public UserStatus getStatus() { return status; }
    public Pageable getPageable() { return pageable; }
}

// 創建用戶命令處理器
@Component
public class CreateUserCommandHandler implements CommandHandler<CreateUserCommand> {
    private final UserRepository userRepository;
    private final PasswordEncoder passwordEncoder;
    private final ApplicationEventPublisher eventPublisher;
    
    public CreateUserCommandHandler(UserRepository userRepository, 
                                   PasswordEncoder passwordEncoder,
                                   ApplicationEventPublisher eventPublisher) {
        this.userRepository = userRepository;
        this.passwordEncoder = passwordEncoder;
        this.eventPublisher = eventPublisher;
    }
    
    @Override
    @Transactional
    public void handle(CreateUserCommand command) {
        // 驗證用戶名是否已存在
        if (userRepository.existsByUsername(command.getUsername())) {
            throw new IllegalArgumentException("用戶名已存在: " + command.getUsername());
        }
        
        // 創建用戶
        User user = new User();
        user.setUsername(command.getUsername());
        user.setPassword(passwordEncoder.encode(command.getPassword()));
        user.setEmail(command.getEmail());
        user.setStatus(UserStatus.ACTIVE);
        
        User savedUser = userRepository.save(user);
        
        // 發布事件
        eventPublisher.publishEvent(new UserCreatedEvent(savedUser.getId(), 
            savedUser.getUsername(), savedUser.getEmail()));
    }
}

// 更新用戶命令處理器
@Component
public class UpdateUserCommandHandler implements CommandHandler<UpdateUserCommand> {
    private final UserRepository userRepository;
    private final ApplicationEventPublisher eventPublisher;
    
    public UpdateUserCommandHandler(UserRepository userRepository, 
                                   ApplicationEventPublisher eventPublisher) {
        this.userRepository = userRepository;
        this.eventPublisher = eventPublisher;
    }
    
    @Override
    @Transactional
    public void handle(UpdateUserCommand command) {
        User user = userRepository.findById(command.getUserId())
            .orElseThrow(() -> new IllegalArgumentException("用戶不存在: " + command.getUserId()));
        
        // 更新用戶信息
        if (command.getEmail() != null) {
            user.setEmail(command.getEmail());
        }
        if (command.getStatus() != null) {
            user.setStatus(command.getStatus());
        }
        
        userRepository.save(user);
        
        // 發布事件
        eventPublisher.publishEvent(new UserUpdatedEvent(user.getId(), 
            user.getUsername(), user.getEmail(), user.getStatus()));
    }
}

// 用戶查詢處理器
@Component
public class GetUserQueryHandler implements QueryHandler<GetUserQuery, UserView> {
    private final UserViewRepository userViewRepository;
    
    public GetUserQueryHandler(UserViewRepository userViewRepository) {
        this.userViewRepository = userViewRepository;
    }
    
    @Override
    public UserView handle(GetUserQuery query) {
        return userViewRepository.findByUserId(query.getUserId())
            .orElseThrow(() -> new IllegalArgumentException("用戶不存在: " + query.getUserId()));
    }
}

// 用戶列表查詢處理器
@Component
public class GetUserListQueryHandler implements QueryHandler<GetUserListQuery, Page<UserView>> {
    private final UserViewRepository userViewRepository;
    
    public GetUserListQueryHandler(UserViewRepository userViewRepository) {
        this.userViewRepository = userViewRepository;
    }
    
    @Override
    public Page<UserView> handle(GetUserListQuery query) {
        return userViewRepository.findByFilters(
            query.getUsername(), 
            query.getStatus(), 
            query.getPageable()
        );
    }
}

3. 事件驅動架構

// 用戶創建事件
public class UserCreatedEvent {
    private final Long userId;
    private final String username;
    private final String email;
    private final LocalDateTime occurredAt;
    
    public UserCreatedEvent(Long userId, String username, String email) {
        this.userId = userId;
        this.username = username;
        this.email = email;
        this.occurredAt = LocalDateTime.now();
    }
    
    // Getter 方法
    public Long getUserId() { return userId; }
    public String getUsername() { return username; }
    public String getEmail() { return email; }
    public LocalDateTime getOccurredAt() { return occurredAt; }
}

// 用戶更新事件
public class UserUpdatedEvent {
    private final Long userId;
    private final String username;
    private final String email;
    private final UserStatus status;
    private final LocalDateTime occurredAt;
    
    public UserUpdatedEvent(Long userId, String username, String email, UserStatus status) {
        this.userId = userId;
        this.username = username;
        this.email = email;
        this.status = status;
        this.occurredAt = LocalDateTime.now();
    }
    
    // Getter 方法
    public Long getUserId() { return userId; }
    public String getUsername() { return username; }
    public String getEmail() { return email; }
    public UserStatus getStatus() { return status; }
    public LocalDateTime getOccurredAt() { return occurredAt; }
}

// 讀取模型投影處理器
@Component
public class UserViewProjectionHandler {
    private final UserViewRepository userViewRepository;
    
    public UserViewProjectionHandler(UserViewRepository userViewRepository) {
        this.userViewRepository = userViewRepository;
    }
    
    @EventListener
    @Async
    public void handle(UserCreatedEvent event) {
        UserView userView = new UserView();
        userView.setUserId(event.getUserId());
        userView.setUsername(event.getUsername());
        userView.setEmail(event.getEmail());
        userView.setStatus(UserStatus.ACTIVE.name());
        userView.setCreatedAt(event.getOccurredAt().toString());
        userView.setUpdatedAt(event.getOccurredAt().toString());
        userView.setTotalOrders(0);
        userView.setTotalSpent(BigDecimal.ZERO);
        
        userViewRepository.save(userView);
    }
    
    @EventListener
    @Async
    public void handle(UserUpdatedEvent event) {
        UserView userView = userViewRepository.findByUserId(event.getUserId())
            .orElseThrow(() -> new IllegalStateException("用戶視圖不存在: " + event.getUserId()));
        
        userView.setUsername(event.getUsername());
        userView.setEmail(event.getEmail());
        userView.setStatus(event.getStatus().name());
        userView.setUpdatedAt(event.getOccurredAt().toString());
        
        userViewRepository.save(userView);
    }
}

事件溯源 (Event Sourcing) 整合

1. 事件存儲

// 事件基類
@MappedSuperclass
public abstract class DomainEvent {
    private String eventId;
    private String aggregateId;
    private String eventType;
    private LocalDateTime occurredAt;
    private String userId;
    private long version;
    
    protected DomainEvent() {
        this.eventId = UUID.randomUUID().toString();
        this.occurredAt = LocalDateTime.now();
    }
    
    protected DomainEvent(String aggregateId, String eventType, String userId, long version) {
        this();
        this.aggregateId = aggregateId;
        this.eventType = eventType;
        this.userId = userId;
        this.version = version;
    }
    
    // Getter 和 Setter 方法
    public String getEventId() { return eventId; }
    public void setEventId(String eventId) { this.eventId = eventId; }
    public String getAggregateId() { return aggregateId; }
    public void setAggregateId(String aggregateId) { this.aggregateId = aggregateId; }
    public String getEventType() { return eventType; }
    public void setEventType(String eventType) { this.eventType = eventType; }
    public LocalDateTime getOccurredAt() { return occurredAt; }
    public void setOccurredAt(LocalDateTime occurredAt) { this.occurredAt = occurredAt; }
    public String getUserId() { return userId; }
    public void setUserId(String userId) { this.userId = userId; }
    public long getVersion() { return version; }
    public void setVersion(long version) { this.version = version; }
}

// 事件存儲實體
@Entity
@Table(name = "event_store")
public class EventStore {
    @Id
    private String eventId;
    
    @Column(nullable = false)
    private String aggregateId;
    
    @Column(nullable = false)
    private String eventType;
    
    @Column(nullable = false, columnDefinition = "TEXT")
    private String eventData;
    
    @Column(nullable = false)
    private LocalDateTime occurredAt;
    
    @Column
    private String userId;
    
    @Column(nullable = false)
    private long version;
    
    // 構造函數、getter、setter 略
}

// 事件存儲倉庫
@Repository
public interface EventStoreRepository extends JpaRepository<EventStore, String> {
    List<EventStore> findByAggregateIdOrderByVersionAsc(String aggregateId);
    List<EventStore> findByAggregateIdAndVersionGreaterThanOrderByVersionAsc(String aggregateId, long version);
    boolean existsByAggregateIdAndVersion(String aggregateId, long version);
}

// 事件存儲服務
@Service
public class EventStoreService {
    private final EventStoreRepository eventStoreRepository;
    private final ObjectMapper objectMapper;
    
    public EventStoreService(EventStoreRepository eventStoreRepository, ObjectMapper objectMapper) {
        this.eventStoreRepository = eventStoreRepository;
        this.objectMapper = objectMapper;
    }
    
    public void saveEvent(DomainEvent event) {
        try {
            EventStore eventStore = new EventStore();
            eventStore.setEventId(event.getEventId());
            eventStore.setAggregateId(event.getAggregateId());
            eventStore.setEventType(event.getEventType());
            eventStore.setEventData(objectMapper.writeValueAsString(event));
            eventStore.setOccurredAt(event.getOccurredAt());
            eventStore.setUserId(event.getUserId());
            eventStore.setVersion(event.getVersion());
            
            eventStoreRepository.save(eventStore);
        } catch (JsonProcessingException e) {
            throw new RuntimeException("事件序列化失敗", e);
        }
    }
    
    public List<DomainEvent> getEvents(String aggregateId) {
        return eventStoreRepository.findByAggregateIdOrderByVersionAsc(aggregateId)
            .stream()
            .map(this::deserializeEvent)
            .collect(Collectors.toList());
    }
    
    public List<DomainEvent> getEventsFromVersion(String aggregateId, long version) {
        return eventStoreRepository.findByAggregateIdAndVersionGreaterThanOrderByVersionAsc(aggregateId, version)
            .stream()
            .map(this::deserializeEvent)
            .collect(Collectors.toList());
    }
    
    private DomainEvent deserializeEvent(EventStore eventStore) {
        try {
            Class<?> eventClass = Class.forName(eventStore.getEventType());
            return (DomainEvent) objectMapper.readValue(eventStore.getEventData(), eventClass);
        } catch (Exception e) {
            throw new RuntimeException("事件反序列化失敗", e);
        }
    }
}

2. 聚合根與事件溯源

// 聚合根基類
public abstract class AggregateRoot {
    private String id;
    private long version;
    private final List<DomainEvent> uncommittedEvents = new ArrayList<>();
    
    protected AggregateRoot() {
        this.id = UUID.randomUUID().toString();
        this.version = 0;
    }
    
    protected AggregateRoot(String id) {
        this.id = id;
        this.version = 0;
    }
    
    protected void addEvent(DomainEvent event) {
        event.setAggregateId(this.id);
        event.setVersion(this.version + 1);
        this.uncommittedEvents.add(event);
    }
    
    public List<DomainEvent> getUncommittedEvents() {
        return new ArrayList<>(uncommittedEvents);
    }
    
    public void markEventsAsCommitted() {
        this.version += uncommittedEvents.size();
        this.uncommittedEvents.clear();
    }
    
    public void loadFromHistory(List<DomainEvent> events) {
        events.forEach(this::apply);
        this.version = events.size();
    }
    
    protected abstract void apply(DomainEvent event);
    
    // Getter 和 Setter 方法
    public String getId() { return id; }
    public long getVersion() { return version; }
}

// 用戶聚合根
public class UserAggregate extends AggregateRoot {
    private String username;
    private String email;
    private UserStatus status;
    private LocalDateTime createdAt;
    private LocalDateTime updatedAt;
    
    public UserAggregate() {
        super();
    }
    
    public UserAggregate(String id) {
        super(id);
    }
    
    // 創建用戶
    public static UserAggregate create(String username, String email, String userId) {
        UserAggregate user = new UserAggregate();
        user.addEvent(new UserCreatedDomainEvent(user.getId(), username, email, userId));
        return user;
    }
    
    // 更新用戶
    public void updateUser(String email, UserStatus status, String userId) {
        if (!Objects.equals(this.email, email) || !Objects.equals(this.status, status)) {
            this.addEvent(new UserUpdatedDomainEvent(this.getId(), this.username, email, status, userId));
        }
    }
    
    // 刪除用戶
    public void deleteUser(String userId) {
        this.addEvent(new UserDeletedDomainEvent(this.getId(), this.username, userId));
    }
    
    @Override
    protected void apply(DomainEvent event) {
        if (event instanceof UserCreatedDomainEvent) {
            apply((UserCreatedDomainEvent) event);
        } else if (event instanceof UserUpdatedDomainEvent) {
            apply((UserUpdatedDomainEvent) event);
        } else if (event instanceof UserDeletedDomainEvent) {
            apply((UserDeletedDomainEvent) event);
        }
    }
    
    private void apply(UserCreatedDomainEvent event) {
        this.username = event.getUsername();
        this.email = event.getEmail();
        this.status = UserStatus.ACTIVE;
        this.createdAt = event.getOccurredAt();
        this.updatedAt = event.getOccurredAt();
    }
    
    private void apply(UserUpdatedDomainEvent event) {
        this.username = event.getUsername();
        this.email = event.getEmail();
        this.status = event.getStatus();
        this.updatedAt = event.getOccurredAt();
    }
    
    private void apply(UserDeletedDomainEvent event) {
        this.status = UserStatus.INACTIVE;
        this.updatedAt = event.getOccurredAt();
    }
    
    // Getter 方法
    public String getUsername() { return username; }
    public String getEmail() { return email; }
    public UserStatus getStatus() { return status; }
    public LocalDateTime getCreatedAt() { return createdAt; }
    public LocalDateTime getUpdatedAt() { return updatedAt; }
}

// 用戶創建領域事件
public class UserCreatedDomainEvent extends DomainEvent {
    private String username;
    private String email;
    
    public UserCreatedDomainEvent() {
        super();
    }
    
    public UserCreatedDomainEvent(String aggregateId, String username, String email, String userId) {
        super(aggregateId, "UserCreatedDomainEvent", userId, 1);
        this.username = username;
        this.email = email;
    }
    
    // Getter 和 Setter 方法
    public String getUsername() { return username; }
    public void setUsername(String username) { this.username = username; }
    public String getEmail() { return email; }
    public void setEmail(String email) { this.email = email; }
}

// 用戶更新領域事件
public class UserUpdatedDomainEvent extends DomainEvent {
    private String username;
    private String email;
    private UserStatus status;
    
    public UserUpdatedDomainEvent() {
        super();
    }
    
    public UserUpdatedDomainEvent(String aggregateId, String username, String email, UserStatus status, String userId) {
        super(aggregateId, "UserUpdatedDomainEvent", userId, 1);
        this.username = username;
        this.email = email;
        this.status = status;
    }
    
    // Getter 和 Setter 方法
    public String getUsername() { return username; }
    public void setUsername(String username) { this.username = username; }
    public String getEmail() { return email; }
    public void setEmail(String email) { this.email = email; }
    public UserStatus getStatus() { return status; }
    public void setStatus(UserStatus status) { this.status = status; }
}

// 用戶刪除領域事件
public class UserDeletedDomainEvent extends DomainEvent {
    private String username;
    
    public UserDeletedDomainEvent() {
        super();
    }
    
    public UserDeletedDomainEvent(String aggregateId, String username, String userId) {
        super(aggregateId, "UserDeletedDomainEvent", userId, 1);
        this.username = username;
    }
    
    // Getter 和 Setter 方法
    public String getUsername() { return username; }
    public void setUsername(String username) { this.username = username; }
}

企業級應用場景

1. 電商系統實現

// 訂單聚合根
public class OrderAggregate extends AggregateRoot {
    private String customerId;
    private List<OrderItem> items;
    private BigDecimal totalAmount;
    private OrderStatus status;
    private LocalDateTime createdAt;
    private LocalDateTime updatedAt;
    
    public OrderAggregate() {
        super();
        this.items = new ArrayList<>();
        this.totalAmount = BigDecimal.ZERO;
        this.status = OrderStatus.PENDING;
    }
    
    // 創建訂單
    public static OrderAggregate create(String customerId, List<OrderItem> items, String userId) {
        OrderAggregate order = new OrderAggregate();
        order.addEvent(new OrderCreatedDomainEvent(order.getId(), customerId, items, userId));
        return order;
    }
    
    // 添加商品
    public void addItem(OrderItem item, String userId) {
        this.addEvent(new OrderItemAddedDomainEvent(this.getId(), item, userId));
    }
    
    // 確認訂單
    public void confirm(String userId) {
        if (this.status != OrderStatus.PENDING) {
            throw new IllegalStateException("只有待處理的訂單可以確認");
        }
        this.addEvent(new OrderConfirmedDomainEvent(this.getId(), userId));
    }
    
    // 取消訂單
    public void cancel(String reason, String userId) {
        if (this.status == OrderStatus.SHIPPED || this.status == OrderStatus.DELIVERED) {
            throw new IllegalStateException("已發貨或已送達的訂單不能取消");
        }
        this.addEvent(new OrderCancelledDomainEvent(this.getId(), reason, userId));
    }
    
    @Override
    protected void apply(DomainEvent event) {
        if (event instanceof OrderCreatedDomainEvent) {
            apply((OrderCreatedDomainEvent) event);
        } else if (event instanceof OrderItemAddedDomainEvent) {
            apply((OrderItemAddedDomainEvent) event);
        } else if (event instanceof OrderConfirmedDomainEvent) {
            apply((OrderConfirmedDomainEvent) event);
        } else if (event instanceof OrderCancelledDomainEvent) {
            apply((OrderCancelledDomainEvent) event);
        }
    }
    
    private void apply(OrderCreatedDomainEvent event) {
        this.customerId = event.getCustomerId();
        this.items = new ArrayList<>(event.getItems());
        this.totalAmount = calculateTotalAmount();
        this.status = OrderStatus.PENDING;
        this.createdAt = event.getOccurredAt();
        this.updatedAt = event.getOccurredAt();
    }
    
    private void apply(OrderItemAddedDomainEvent event) {
        this.items.add(event.getItem());
        this.totalAmount = calculateTotalAmount();
        this.updatedAt = event.getOccurredAt();
    }
    
    private void apply(OrderConfirmedDomainEvent event) {
        this.status = OrderStatus.CONFIRMED;
        this.updatedAt = event.getOccurredAt();
    }
    
    private void apply(OrderCancelledDomainEvent event) {
        this.status = OrderStatus.CANCELLED;
        this.updatedAt = event.getOccurredAt();
    }
    
    private BigDecimal calculateTotalAmount() {
        return items.stream()
            .map(item -> item.getPrice().multiply(BigDecimal.valueOf(item.getQuantity())))
            .reduce(BigDecimal.ZERO, BigDecimal::add);
    }
    
    // Getter 方法
    public String getCustomerId() { return customerId; }
    public List<OrderItem> getItems() { return new ArrayList<>(items); }
    public BigDecimal getTotalAmount() { return totalAmount; }
    public OrderStatus getStatus() { return status; }
    public LocalDateTime getCreatedAt() { return createdAt; }
    public LocalDateTime getUpdatedAt() { return updatedAt; }
}

// 訂單項目
public class OrderItem {
    private String productId;
    private String productName;
    private int quantity;
    private BigDecimal price;
    
    public OrderItem(String productId, String productName, int quantity, BigDecimal price) {
        this.productId = productId;
        this.productName = productName;
        this.quantity = quantity;
        this.price = price;
    }
    
    // Getter 和 Setter 方法
    public String getProductId() { return productId; }
    public void setProductId(String productId) { this.productId = productId; }
    public String getProductName() { return productName; }
    public void setProductName(String productName) { this.productName = productName; }
    public int getQuantity() { return quantity; }
    public void setQuantity(int quantity) { this.quantity = quantity; }
    public BigDecimal getPrice() { return price; }
    public void setPrice(BigDecimal price) { this.price = price; }
}

// 訂單狀態
public enum OrderStatus {
    PENDING, CONFIRMED, SHIPPED, DELIVERED, CANCELLED
}

// 訂單創建命令
public class CreateOrderCommand implements Command {
    private final String customerId;
    private final List<OrderItem> items;
    
    public CreateOrderCommand(String customerId, List<OrderItem> items) {
        this.customerId = customerId;
        this.items = items;
    }
    
    // Getter 方法
    public String getCustomerId() { return customerId; }
    public List<OrderItem> getItems() { return items; }
}

// 訂單確認命令
public class ConfirmOrderCommand implements Command {
    private final String orderId;
    
    public ConfirmOrderCommand(String orderId) {
        this.orderId = orderId;
    }
    
    public String getOrderId() { return orderId; }
}

// 訂單查詢
public class GetOrderQuery implements Query<OrderView> {
    private final String orderId;
    
    public GetOrderQuery(String orderId) {
        this.orderId = orderId;
    }
    
    public String getOrderId() { return orderId; }
}

// 訂單視圖
@Document(collection = "order_views")
public class OrderView {
    @Id
    private String id;
    private String orderId;
    private String customerId;
    private String customerName;
    private List<OrderItemView> items;
    private BigDecimal totalAmount;
    private String status;
    private String createdAt;
    private String updatedAt;
    
    // 構造函數、getter、setter 略
}

// 訂單項目視圖
public class OrderItemView {
    private String productId;
    private String productName;
    private int quantity;
    private BigDecimal price;
    private BigDecimal subtotal;
    
    // 構造函數、getter、setter 略
}

2. 庫存管理系統

// 庫存聚合根
public class InventoryAggregate extends AggregateRoot {
    private String productId;
    private int quantity;
    private int reservedQuantity;
    private LocalDateTime lastUpdated;
    
    public InventoryAggregate() {
        super();
    }
    
    // 初始化庫存
    public static InventoryAggregate initialize(String productId, int initialQuantity, String userId) {
        InventoryAggregate inventory = new InventoryAggregate();
        inventory.addEvent(new InventoryInitializedDomainEvent(inventory.getId(), productId, initialQuantity, userId));
        return inventory;
    }
    
    // 增加庫存
    public void addStock(int quantity, String reason, String userId) {
        if (quantity <= 0) {
            throw new IllegalArgumentException("增加的庫存數量必須大於0");
        }
        this.addEvent(new StockAddedDomainEvent(this.getId(), this.productId, quantity, reason, userId));
    }
    
    // 預留庫存
    public void reserveStock(int quantity, String orderId, String userId) {
        if (quantity <= 0) {
            throw new IllegalArgumentException("預留的庫存數量必須大於0");
        }
        if (this.quantity - this.reservedQuantity < quantity) {
            throw new IllegalStateException("可用庫存不足");
        }
        this.addEvent(new StockReservedDomainEvent(this.getId(), this.productId, quantity, orderId, userId));
    }
    
    // 確認庫存消耗
    public void confirmStock(int quantity, String orderId, String userId) {
        if (quantity <= 0) {
            throw new IllegalArgumentException("確認的庫存數量必須大於0");
        }
        if (this.reservedQuantity < quantity) {
            throw new IllegalStateException("預留庫存不足");
        }
        this.addEvent(new StockConfirmedDomainEvent(this.getId(), this.productId, quantity, orderId, userId));
    }
    
    // 釋放預留庫存
    public void releaseReservedStock(int quantity, String orderId, String userId) {
        if (quantity <= 0) {
            throw new IllegalArgumentException("釋放的庫存數量必須大於0");
        }
        if (this.reservedQuantity < quantity) {
            throw new IllegalStateException("預留庫存不足");
        }
        this.addEvent(new StockReleasedDomainEvent(this.getId(), this.productId, quantity, orderId, userId));
    }
    
    @Override
    protected void apply(DomainEvent event) {
        if (event instanceof InventoryInitializedDomainEvent) {
            apply((InventoryInitializedDomainEvent) event);
        } else if (event instanceof StockAddedDomainEvent) {
            apply((StockAddedDomainEvent) event);
        } else if (event instanceof StockReservedDomainEvent) {
            apply((StockReservedDomainEvent) event);
        } else if (event instanceof StockConfirmedDomainEvent) {
            apply((StockConfirmedDomainEvent) event);
        } else if (event instanceof StockReleasedDomainEvent) {
            apply((StockReleasedDomainEvent) event);
        }
    }
    
    private void apply(InventoryInitializedDomainEvent event) {
        this.productId = event.getProductId();
        this.quantity = event.getInitialQuantity();
        this.reservedQuantity = 0;
        this.lastUpdated = event.getOccurredAt();
    }
    
    private void apply(StockAddedDomainEvent event) {
        this.quantity += event.getQuantity();
        this.lastUpdated = event.getOccurredAt();
    }
    
    private void apply(StockReservedDomainEvent event) {
        this.reservedQuantity += event.getQuantity();
        this.lastUpdated = event.getOccurredAt();
    }
    
    private void apply(StockConfirmedDomainEvent event) {
        this.quantity -= event.getQuantity();
        this.reservedQuantity -= event.getQuantity();
        this.lastUpdated = event.getOccurredAt();
    }
    
    private void apply(StockReleasedDomainEvent event) {
        this.reservedQuantity -= event.getQuantity();
        this.lastUpdated = event.getOccurredAt();
    }
    
    // 計算可用庫存
    public int getAvailableQuantity() {
        return quantity - reservedQuantity;
    }
    
    // Getter 方法
    public String getProductId() { return productId; }
    public int getQuantity() { return quantity; }
    public int getReservedQuantity() { return reservedQuantity; }
    public LocalDateTime getLastUpdated() { return lastUpdated; }
}

// 庫存相關領域事件
public class InventoryInitializedDomainEvent extends DomainEvent {
    private String productId;
    private int initialQuantity;
    
    public InventoryInitializedDomainEvent() {
        super();
    }
    
    public InventoryInitializedDomainEvent(String aggregateId, String productId, int initialQuantity, String userId) {
        super(aggregateId, "InventoryInitializedDomainEvent", userId, 1);
        this.productId = productId;
        this.initialQuantity = initialQuantity;
    }
    
    // Getter 和 Setter 方法
    public String getProductId() { return productId; }
    public void setProductId(String productId) { this.productId = productId; }
    public int getInitialQuantity() { return initialQuantity; }
    public void setInitialQuantity(int initialQuantity) { this.initialQuantity = initialQuantity; }
}

public class StockAddedDomainEvent extends DomainEvent {
    private String productId;
    private int quantity;
    private String reason;
    
    public StockAddedDomainEvent() {
        super();
    }
    
    public StockAddedDomainEvent(String aggregateId, String productId, int quantity, String reason, String userId) {
        super(aggregateId, "StockAddedDomainEvent", userId, 1);
        this.productId = productId;
        this.quantity = quantity;
        this.reason = reason;
    }
    
    // Getter 和 Setter 方法
    public String getProductId() { return productId; }
    public void setProductId(String productId) { this.productId = productId; }
    public int getQuantity() { return quantity; }
    public void setQuantity(int quantity) { this.quantity = quantity; }
    public String getReason() { return reason; }
    public void setReason(String reason) { this.reason = reason; }
}

public class StockReservedDomainEvent extends DomainEvent {
    private String productId;
    private int quantity;
    private String orderId;
    
    public StockReservedDomainEvent() {
        super();
    }
    
    public StockReservedDomainEvent(String aggregateId, String productId, int quantity, String orderId, String userId) {
        super(aggregateId, "StockReservedDomainEvent", userId, 1);
        this.productId = productId;
        this.quantity = quantity;
        this.orderId = orderId;
    }
    
    // Getter 和 Setter 方法
    public String getProductId() { return productId; }
    public void setProductId(String productId) { this.productId = productId; }
    public int getQuantity() { return quantity; }
    public void setQuantity(int quantity) { this.quantity = quantity; }
    public String getOrderId() { return orderId; }
    public void setOrderId(String orderId) { this.orderId = orderId; }
}

Spring Boot 整合

1. 配置類

@Configuration
@EnableAsync
@EnableJpaRepositories(basePackages = "com.example.repository")
@EnableMongoRepositories(basePackages = "com.example.readmodel.repository")
public class CqrsConfiguration {
    
    @Bean
    public ObjectMapper objectMapper() {
        ObjectMapper mapper = new ObjectMapper();
        mapper.registerModule(new JavaTimeModule());
        mapper.disable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS);
        return mapper;
    }
    
    @Bean
    public ApplicationEventPublisher applicationEventPublisher(ApplicationContext context) {
        return context;
    }
    
    @Bean
    public TaskExecutor taskExecutor() {
        ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor();
        executor.setCorePoolSize(5);
        executor.setMaxPoolSize(10);
        executor.setQueueCapacity(25);
        executor.setThreadNamePrefix("cqrs-async-");
        executor.initialize();
        return executor;
    }
}

// 資料庫配置
@Configuration
public class DatabaseConfiguration {
    
    @Primary
    @Bean
    @ConfigurationProperties("spring.datasource")
    public DataSource primaryDataSource() {
        return DataSourceBuilder.create().build();
    }
    
    @Bean
    @ConfigurationProperties("spring.datasource.readonly")
    public DataSource readOnlyDataSource() {
        return DataSourceBuilder.create().build();
    }
    
    @Primary
    @Bean
    public JdbcTemplate primaryJdbcTemplate(@Qualifier("primaryDataSource") DataSource dataSource) {
        return new JdbcTemplate(dataSource);
    }
    
    @Bean
    public JdbcTemplate readOnlyJdbcTemplate(@Qualifier("readOnlyDataSource") DataSource dataSource) {
        return new JdbcTemplate(dataSource);
    }
}

2. 控制器實現

@RestController
@RequestMapping("/api/users")
public class UserController {
    private final CommandBus commandBus;
    private final QueryBus queryBus;
    
    public UserController(CommandBus commandBus, QueryBus queryBus) {
        this.commandBus = commandBus;
        this.queryBus = queryBus;
    }
    
    @PostMapping
    public ResponseEntity<ApiResponse<Void>> createUser(@RequestBody @Valid CreateUserRequest request) {
        try {
            CreateUserCommand command = new CreateUserCommand(
                request.getUsername(),
                request.getPassword(),
                request.getEmail()
            );
            
            commandBus.send(command);
            
            return ResponseEntity.ok(ApiResponse.<Void>success()
                .message("用戶創建成功")
                .build());
        } catch (Exception e) {
            return ResponseEntity.badRequest().body(ApiResponse.<Void>failure("創建用戶失敗")
                .error(e.getMessage())
                .build());
        }
    }
    
    @GetMapping("/{id}")
    public ResponseEntity<ApiResponse<UserView>> getUser(@PathVariable Long id) {
        try {
            GetUserQuery query = new GetUserQuery(id);
            UserView user = queryBus.send(query);
            
            return ResponseEntity.ok(ApiResponse.success(user)
                .message("用戶查詢成功")
                .build());
        } catch (Exception e) {
            return ResponseEntity.notFound().build();
        }
    }
    
    @GetMapping
    public ResponseEntity<ApiResponse<Page<UserView>>> getUsers(
            @RequestParam(required = false) String username,
            @RequestParam(required = false) UserStatus status,
            @PageableDefault(size = 20) Pageable pageable) {
        
        try {
            GetUserListQuery query = new GetUserListQuery(username, status, pageable);
            Page<UserView> users = queryBus.send(query);
            
            return ResponseEntity.ok(ApiResponse.success(users)
                .message("用戶列表查詢成功")
                .metadata("total", users.getTotalElements())
                .metadata("pages", users.getTotalPages())
                .build());
        } catch (Exception e) {
            return ResponseEntity.badRequest().body(ApiResponse.<Page<UserView>>failure("查詢用戶列表失敗")
                .error(e.getMessage())
                .build());
        }
    }
    
    @PutMapping("/{id}")
    public ResponseEntity<ApiResponse<Void>> updateUser(@PathVariable Long id, 
                                                        @RequestBody @Valid UpdateUserRequest request) {
        try {
            UpdateUserCommand command = new UpdateUserCommand(id, request.getEmail(), request.getStatus());
            commandBus.send(command);
            
            return ResponseEntity.ok(ApiResponse.<Void>success()
                .message("用戶更新成功")
                .build());
        } catch (Exception e) {
            return ResponseEntity.badRequest().body(ApiResponse.<Void>failure("更新用戶失敗")
                .error(e.getMessage())
                .build());
        }
    }
}

// 請求 DTO
public class CreateUserRequest {
    @NotBlank(message = "用戶名不能為空")
    private String username;
    
    @NotBlank(message = "密碼不能為空")
    @Size(min = 6, message = "密碼長度至少6位")
    private String password;
    
    @NotBlank(message = "郵箱不能為空")
    @Email(message = "郵箱格式不正確")
    private String email;
    
    // 構造函數、getter、setter 略
}

public class UpdateUserRequest {
    @Email(message = "郵箱格式不正確")
    private String email;
    
    private UserStatus status;
    
    // 構造函數、getter、setter 略
}

3. 測試實現

@SpringBootTest
@Transactional
class CqrsIntegrationTest {
    
    @Autowired
    private CommandBus commandBus;
    
    @Autowired
    private QueryBus queryBus;
    
    @Autowired
    private UserRepository userRepository;
    
    @Autowired
    private UserViewRepository userViewRepository;
    
    @Test
    void testCreateAndQueryUser() {
        // Given
        CreateUserCommand command = new CreateUserCommand("testuser", "password123", "test@example.com");
        
        // When
        commandBus.send(command);
        
        // Then
        // 驗證寫入模型
        Optional<User> user = userRepository.findByUsername("testuser");
        assertThat(user).isPresent();
        assertThat(user.get().getEmail()).isEqualTo("test@example.com");
        assertThat(user.get().getStatus()).isEqualTo(UserStatus.ACTIVE);
        
        // 等待異步投影完成
        await().atMost(5, TimeUnit.SECONDS).until(() -> {
            return userViewRepository.findByUserId(user.get().getId()).isPresent();
        });
        
        // 驗證讀取模型
        GetUserQuery query = new GetUserQuery(user.get().getId());
        UserView userView = queryBus.send(query);
        
        assertThat(userView.getUsername()).isEqualTo("testuser");
        assertThat(userView.getEmail()).isEqualTo("test@example.com");
        assertThat(userView.getStatus()).isEqualTo(UserStatus.ACTIVE.name());
    }
    
    @Test
    void testUpdateUser() {
        // Given
        User user = createTestUser();
        
        // When
        UpdateUserCommand command = new UpdateUserCommand(user.getId(), "updated@example.com", UserStatus.INACTIVE);
        commandBus.send(command);
        
        // Then
        User updatedUser = userRepository.findById(user.getId()).orElseThrow();
        assertThat(updatedUser.getEmail()).isEqualTo("updated@example.com");
        assertThat(updatedUser.getStatus()).isEqualTo(UserStatus.INACTIVE);
        
        // 驗證讀取模型最終一致性
        await().atMost(5, TimeUnit.SECONDS).until(() -> {
            UserView userView = userViewRepository.findByUserId(user.getId()).orElse(null);
            return userView != null && 
                   "updated@example.com".equals(userView.getEmail()) &&
                   UserStatus.INACTIVE.name().equals(userView.getStatus());
        });
    }
    
    @Test
    void testUserListQuery() {
        // Given
        createTestUser("user1", "user1@example.com", UserStatus.ACTIVE);
        createTestUser("user2", "user2@example.com", UserStatus.INACTIVE);
        
        // When
        GetUserListQuery query = new GetUserListQuery(null, UserStatus.ACTIVE, PageRequest.of(0, 10));
        Page<UserView> result = queryBus.send(query);
        
        // Then
        assertThat(result.getContent()).hasSize(1);
        assertThat(result.getContent().get(0).getUsername()).isEqualTo("user1");
        assertThat(result.getContent().get(0).getStatus()).isEqualTo(UserStatus.ACTIVE.name());
    }
    
    private User createTestUser() {
        return createTestUser("testuser", "test@example.com", UserStatus.ACTIVE);
    }
    
    private User createTestUser(String username, String email, UserStatus status) {
        User user = new User();
        user.setUsername(username);
        user.setPassword("password123");
        user.setEmail(email);
        user.setStatus(status);
        return userRepository.save(user);
    }
}

@WebMvcTest(UserController.class)
class UserControllerTest {
    
    @Autowired
    private MockMvc mockMvc;
    
    @MockBean
    private CommandBus commandBus;
    
    @MockBean
    private QueryBus queryBus;
    
    @Test
    void testCreateUser() throws Exception {
        // Given
        CreateUserRequest request = new CreateUserRequest("testuser", "password123", "test@example.com");
        
        // When & Then
        mockMvc.perform(post("/api/users")
                .contentType(MediaType.APPLICATION_JSON)
                .content(objectMapper.writeValueAsString(request)))
                .andExpect(status().isOk())
                .andExpect(jsonPath("$.success").value(true))
                .andExpect(jsonPath("$.message").value("用戶創建成功"));
        
        verify(commandBus).send(any(CreateUserCommand.class));
    }
    
    @Test
    void testGetUser() throws Exception {
        // Given
        UserView userView = new UserView();
        userView.setUserId(1L);
        userView.setUsername("testuser");
        userView.setEmail("test@example.com");
        userView.setStatus(UserStatus.ACTIVE.name());
        
        when(queryBus.send(any(GetUserQuery.class))).thenReturn(userView);
        
        // When & Then
        mockMvc.perform(get("/api/users/1"))
                .andExpect(status().isOk())
                .andExpect(jsonPath("$.success").value(true))
                .andExpect(jsonPath("$.data.username").value("testuser"))
                .andExpect(jsonPath("$.data.email").value("test@example.com"));
        
        verify(queryBus).send(any(GetUserQuery.class));
    }
}

性能優化與最佳實踐

1. 事件處理優化

// 批量事件處理
@Component
public class BatchEventProcessor {
    private final List<DomainEvent> eventBatch = new ArrayList<>();
    private final Object lock = new Object();
    
    @Value("${cqrs.event.batch.size:100}")
    private int batchSize;
    
    @Value("${cqrs.event.batch.timeout:5000}")
    private long batchTimeout;
    
    @Autowired
    private EventStoreService eventStoreService;
    
    @Autowired
    private ApplicationEventPublisher eventPublisher;
    
    @PostConstruct
    public void initialize() {
        // 定期刷新批次
        ScheduledExecutorService scheduler = Executors.newScheduledThreadPool(1);
        scheduler.scheduleAtFixedRate(this::flushBatch, batchTimeout, batchTimeout, TimeUnit.MILLISECONDS);
    }
    
    public void addEvent(DomainEvent event) {
        synchronized (lock) {
            eventBatch.add(event);
            if (eventBatch.size() >= batchSize) {
                flushBatch();
            }
        }
    }
    
    private void flushBatch() {
        List<DomainEvent> toProcess;
        synchronized (lock) {
            if (eventBatch.isEmpty()) {
                return;
            }
            toProcess = new ArrayList<>(eventBatch);
            eventBatch.clear();
        }
        
        // 批量保存事件
        toProcess.forEach(eventStoreService::saveEvent);
        
        // 批量發布事件
        toProcess.forEach(eventPublisher::publishEvent);
    }
}

// 異步事件處理
@Component
public class AsyncEventHandler {
    private final ThreadPoolTaskExecutor executor;
    
    public AsyncEventHandler() {
        this.executor = new ThreadPoolTaskExecutor();
        this.executor.setCorePoolSize(5);
        this.executor.setMaxPoolSize(20);
        this.executor.setQueueCapacity(100);
        this.executor.setThreadNamePrefix("async-event-");
        this.executor.initialize();
    }
    
    @EventListener
    public void handleUserCreated(UserCreatedEvent event) {
        executor.submit(() -> {
            try {
                // 異步處理用戶創建事件
                processUserCreatedEvent(event);
            } catch (Exception e) {
                // 錯誤處理和重試邏輯
                handleEventProcessingError(event, e);
            }
        });
    }
    
    private void processUserCreatedEvent(UserCreatedEvent event) {
        // 具體的事件處理邏輯
        updateUserView(event);
        sendWelcomeEmail(event);
        updateStatistics(event);
    }
    
    private void handleEventProcessingError(Object event, Exception e) {
        // 實現錯誤處理和重試邏輯
        log.error("事件處理失敗: " + event.getClass().getSimpleName(), e);
    }
}

2. 讀寫分離優化

// 讀寫分離路由
@Component
public class DatabaseRouter {
    private final DataSource writeDataSource;
    private final DataSource readDataSource;
    
    public DatabaseRouter(@Qualifier("writeDataSource") DataSource writeDataSource,
                         @Qualifier("readDataSource") DataSource readDataSource) {
        this.writeDataSource = writeDataSource;
        this.readDataSource = readDataSource;
    }
    
    public DataSource getDataSource(boolean isWrite) {
        return isWrite ? writeDataSource : readDataSource;
    }
}

// 動態數據源切換
@Component
public class DynamicDataSourceContextHolder {
    private static final ThreadLocal<Boolean> contextHolder = new ThreadLocal<>();
    
    public static void setWriteDataSource() {
        contextHolder.set(true);
    }
    
    public static void setReadDataSource() {
        contextHolder.set(false);
    }
    
    public static boolean isWriteDataSource() {
        return Boolean.TRUE.equals(contextHolder.get());
    }
    
    public static void clearDataSourceType() {
        contextHolder.remove();
    }
}

// 讀寫分離攔截器
@Component
public class ReadWriteSplittingInterceptor implements HandlerInterceptor {
    
    @Override
    public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) {
        String method = request.getMethod();
        if ("GET".equals(method)) {
            DynamicDataSourceContextHolder.setReadDataSource();
        } else {
            DynamicDataSourceContextHolder.setWriteDataSource();
        }
        return true;
    }
    
    @Override
    public void afterCompletion(HttpServletRequest request, HttpServletResponse response, Object handler, Exception ex) {
        DynamicDataSourceContextHolder.clearDataSourceType();
    }
}

監控與診斷

// CQRS 監控
@Component
public class CqrsMonitor {
    private final MeterRegistry meterRegistry;
    private final Counter commandCounter;
    private final Counter queryCounter;
    private final Timer commandTimer;
    private final Timer queryTimer;
    
    public CqrsMonitor(MeterRegistry meterRegistry) {
        this.meterRegistry = meterRegistry;
        this.commandCounter = Counter.builder("cqrs.commands")
            .description("Total number of commands processed")
            .register(meterRegistry);
        this.queryCounter = Counter.builder("cqrs.queries")
            .description("Total number of queries processed")
            .register(meterRegistry);
        this.commandTimer = Timer.builder("cqrs.command.duration")
            .description("Command processing time")
            .register(meterRegistry);
        this.queryTimer = Timer.builder("cqrs.query.duration")
            .description("Query processing time")
            .register(meterRegistry);
    }
    
    public <T extends Command> void recordCommand(T command, Runnable execution) {
        commandCounter.increment(Tags.of("type", command.getClass().getSimpleName()));
        commandTimer.recordCallable(() -> {
            execution.run();
            return null;
        });
    }
    
    public <T extends Query<R>, R> R recordQuery(T query, Supplier<R> execution) {
        queryCounter.increment(Tags.of("type", query.getClass().getSimpleName()));
        return queryTimer.recordCallable(execution::get);
    }
}

// 事件存儲監控
@Component
public class EventStoreMonitor {
    private final MeterRegistry meterRegistry;
    private final Counter eventsSaved;
    private final Counter eventsLoaded;
    private final Timer saveTimer;
    private final Timer loadTimer;
    
    public EventStoreMonitor(MeterRegistry meterRegistry) {
        this.meterRegistry = meterRegistry;
        this.eventsSaved = Counter.builder("eventstore.events.saved")
            .description("Number of events saved to event store")
            .register(meterRegistry);
        this.eventsLoaded = Counter.builder("eventstore.events.loaded")
            .description("Number of events loaded from event store")
            .register(meterRegistry);
        this.saveTimer = Timer.builder("eventstore.save.duration")
            .description("Time taken to save events")
            .register(meterRegistry);
        this.loadTimer = Timer.builder("eventstore.load.duration")
            .description("Time taken to load events")
            .register(meterRegistry);
    }
    
    public void recordEventSaved(String eventType) {
        eventsSaved.increment(Tags.of("type", eventType));
    }
    
    public void recordEventLoaded(String eventType) {
        eventsLoaded.increment(Tags.of("type", eventType));
    }
    
    public <T> T recordSaveOperation(Supplier<T> operation) {
        return saveTimer.recordCallable(operation::get);
    }
    
    public <T> T recordLoadOperation(Supplier<T> operation) {
        return loadTimer.recordCallable(operation::get);
    }
}

總結

CQRS 是一種強大的架構模式，特別適用於：

Spring Boot SFTP 工具類：企業級安全文件傳輸系統實作指南

Tue, 05 Jan 2021 19:18:59 +0800

函式庫選擇說明：原始 com.jcraft:jsch 自 2018 年後已停止維護，存在已知安全漏洞且不支援新版 OpenSSH 演算法。本文使用社群維護的 fork com.github.mwiede:jsch，API 完全相容，持續更新安全修補。

SFTP 企業級工具類實作指南

簡介

在現代企業應用中，安全的文件傳輸是不可或缺的功能。SFTP（SSH File Transfer Protocol）提供了一種安全、可靠的文件傳輸方案。本文將詳細介紹如何在 Spring Boot 中實作企業級的 SFTP 工具類，包含連線池管理、錯誤處理、效能優化等關鍵功能。

核心依賴配置

Maven 依賴

<dependencies>
    <!-- SFTP 核心依賴 -->
    <dependency>
        <groupId>com.github.mwiede</groupId>
        <artifactId>jsch</artifactId>
        <version>0.2.20</version>
    </dependency>
    
    <!-- Apache Commons Pool2 連線池 -->
    <dependency>
        <groupId>org.apache.commons</groupId>
        <artifactId>commons-pool2</artifactId>
        <version>2.11.1</version>
    </dependency>
    
    <!-- Spring Boot Starter -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter</artifactId>
    </dependency>
    
    <!-- Spring Boot Configuration Processor -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-configuration-processor</artifactId>
        <optional>true</optional>
    </dependency>
    
    <!-- Micrometer 監控 -->
    <dependency>
        <groupId>io.micrometer</groupId>
        <artifactId>micrometer-core</artifactId>
    </dependency>
</dependencies>

Gradle 依賴

dependencies {
    // SFTP 核心依賴
    implementation 'com.github.mwiede:jsch:0.2.20'
    
    // Apache Commons Pool2 連線池
    implementation 'org.apache.commons:commons-pool2:2.11.1'
    
    // Spring Boot Starter
    implementation 'org.springframework.boot:spring-boot-starter'
    
    // Spring Boot Configuration Processor
    annotationProcessor 'org.springframework.boot:spring-boot-configuration-processor'
    
    // Micrometer 監控
    implementation 'io.micrometer:micrometer-core'
}

配置類別

SFTP 配置屬性

import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.context.annotation.Configuration;
import lombok.Data;

@Data
@Configuration
@ConfigurationProperties(prefix = "sftp")
public class SftpProperties {
    
    // 連線配置
    private String host;
    private int port = 22;
    private String username;
    private String password;
    private String privateKeyPath;
    private String passphrase;
    
    // 連線池配置
    private Pool pool = new Pool();
    
    // 超時配置
    private int connectTimeout = 30000;
    private int sessionTimeout = 30000;
    private int channelTimeout = 30000;
    
    // 重試配置
    private int maxRetries = 3;
    private int retryDelay = 1000;
    
    // 安全配置
    private boolean strictHostKeyChecking = false;
    private String knownHostsFile;
    private String hostKeyAlgorithms;
    
    @Data
    public static class Pool {
        private int maxActive = 10;
        private int maxIdle = 5;
        private int minIdle = 1;
        private long maxWait = 10000;
        private boolean testOnBorrow = true;
        private boolean testOnReturn = true;
        private boolean testWhileIdle = true;
        private long timeBetweenEvictionRuns = 60000;
        private long minEvictableIdleTime = 300000;
    }
}

application.yml 配置

sftp:
  host: sftp.example.com
  port: 22
  username: ${SFTP_USERNAME:sftpuser}
  password: ${SFTP_PASSWORD:}
  private-key-path: ${SFTP_PRIVATE_KEY_PATH:}
  passphrase: ${SFTP_PASSPHRASE:}
  
  # 連線池配置
  pool:
    max-active: 20
    max-idle: 10
    min-idle: 2
    max-wait: 15000
    test-on-borrow: true
    test-on-return: true
    test-while-idle: true
    time-between-eviction-runs: 60000
    min-evictable-idle-time: 300000
  
  # 超時配置
  connect-timeout: 30000
  session-timeout: 30000
  channel-timeout: 30000
  
  # 重試配置
  max-retries: 3
  retry-delay: 1000
  
  # 安全配置
  strict-host-key-checking: false
  known-hosts-file: ~/.ssh/known_hosts
  host-key-algorithms: ssh-rsa,ssh-dss

# 監控配置
management:
  endpoints:
    web:
      exposure:
        include: health,metrics,info,sftp
  metrics:
    tags:
      application: sftp-service

核心實作類別

SFTP 連線工廠

import com.jcraft.jsch.*;
import lombok.extern.slf4j.Slf4j;
import org.apache.commons.pool2.BasePooledObjectFactory;
import org.apache.commons.pool2.PooledObject;
import org.apache.commons.pool2.impl.DefaultPooledObject;
import org.springframework.stereotype.Component;

import java.io.File;
import java.util.Properties;

@Slf4j
@Component
public class SftpConnectionFactory extends BasePooledObjectFactory<ChannelSftp> {

    private final SftpProperties sftpProperties;
    private final JSch jsch;

    public SftpConnectionFactory(SftpProperties sftpProperties) {
        this.sftpProperties = sftpProperties;
        this.jsch = new JSch();
        initializeJSch();
    }

    private void initializeJSch() {
        try {
            // 設定私鑰
            if (sftpProperties.getPrivateKeyPath() != null) {
                if (sftpProperties.getPassphrase() != null) {
                    jsch.addIdentity(sftpProperties.getPrivateKeyPath(), sftpProperties.getPassphrase());
                } else {
                    jsch.addIdentity(sftpProperties.getPrivateKeyPath());
                }
            }
            
            // 設定 known_hosts
            if (sftpProperties.getKnownHostsFile() != null) {
                jsch.setKnownHosts(sftpProperties.getKnownHostsFile());
            }
            
            log.info("SFTP JSch 初始化完成");
        } catch (JSchException e) {
            log.error("SFTP JSch 初始化失敗", e);
            throw new RuntimeException("SFTP JSch 初始化失敗", e);
        }
    }

    @Override
    public ChannelSftp create() throws Exception {
        log.debug("創建新的 SFTP 連線到 {}:{}", sftpProperties.getHost(), sftpProperties.getPort());
        
        Session session = jsch.getSession(
            sftpProperties.getUsername(),
            sftpProperties.getHost(),
            sftpProperties.getPort()
        );
        
        // 設定密碼（如果有）
        if (sftpProperties.getPassword() != null) {
            session.setPassword(sftpProperties.getPassword());
        }
        
        // 設定連線屬性
        Properties config = new Properties();
        config.put("StrictHostKeyChecking", sftpProperties.isStrictHostKeyChecking() ? "yes" : "no");
        
        if (sftpProperties.getHostKeyAlgorithms() != null) {
            config.put("server_host_key", sftpProperties.getHostKeyAlgorithms());
        }
        
        session.setConfig(config);
        session.setTimeout(sftpProperties.getSessionTimeout());
        
        // 建立連線
        session.connect(sftpProperties.getConnectTimeout());
        
        Channel channel = session.openChannel("sftp");
        channel.connect(sftpProperties.getChannelTimeout());
        
        ChannelSftp channelSftp = (ChannelSftp) channel;
        log.debug("SFTP 連線創建成功");
        
        return channelSftp;
    }

    @Override
    public PooledObject<ChannelSftp> wrap(ChannelSftp channelSftp) {
        return new DefaultPooledObject<>(channelSftp);
    }

    @Override
    public boolean validateObject(PooledObject<ChannelSftp> pooledObject) {
        ChannelSftp channelSftp = pooledObject.getObject();
        return channelSftp != null && channelSftp.isConnected();
    }

    @Override
    public void destroyObject(PooledObject<ChannelSftp> pooledObject) throws Exception {
        ChannelSftp channelSftp = pooledObject.getObject();
        if (channelSftp != null) {
            Session session = channelSftp.getSession();
            if (channelSftp.isConnected()) {
                channelSftp.disconnect();
            }
            if (session != null && session.isConnected()) {
                session.disconnect();
            }
        }
        log.debug("SFTP 連線已銷毀");
    }
}

SFTP 連線池管理器

import org.apache.commons.pool2.ObjectPool;
import org.apache.commons.pool2.impl.GenericObjectPool;
import org.apache.commons.pool2.impl.GenericObjectPoolConfig;
import org.springframework.stereotype.Component;
import lombok.extern.slf4j.Slf4j;

@Slf4j
@Component
public class SftpConnectionPoolManager {

    private final ObjectPool<ChannelSftp> sftpPool;
    private final SftpProperties sftpProperties;

    public SftpConnectionPoolManager(SftpConnectionFactory factory, SftpProperties sftpProperties) {
        this.sftpProperties = sftpProperties;
        this.sftpPool = createPool(factory);
    }

    private ObjectPool<ChannelSftp> createPool(SftpConnectionFactory factory) {
        GenericObjectPoolConfig<ChannelSftp> config = new GenericObjectPoolConfig<>();
        
        config.setMaxTotal(sftpProperties.getPool().getMaxActive());
        config.setMaxIdle(sftpProperties.getPool().getMaxIdle());
        config.setMinIdle(sftpProperties.getPool().getMinIdle());
        config.setMaxWaitMillis(sftpProperties.getPool().getMaxWait());
        config.setTestOnBorrow(sftpProperties.getPool().isTestOnBorrow());
        config.setTestOnReturn(sftpProperties.getPool().isTestOnReturn());
        config.setTestWhileIdle(sftpProperties.getPool().isTestWhileIdle());
        config.setTimeBetweenEvictionRunsMillis(sftpProperties.getPool().getTimeBetweenEvictionRuns());
        config.setMinEvictableIdleTimeMillis(sftpProperties.getPool().getMinEvictableIdleTime());
        
        return new GenericObjectPool<>(factory, config);
    }

    public ChannelSftp borrowConnection() throws Exception {
        return sftpPool.borrowObject();
    }

    public void returnConnection(ChannelSftp channelSftp) {
        if (channelSftp != null) {
            try {
                sftpPool.returnObject(channelSftp);
            } catch (Exception e) {
                log.error("歸還 SFTP 連線失敗", e);
            }
        }
    }

    public void invalidateConnection(ChannelSftp channelSftp) {
        if (channelSftp != null) {
            try {
                sftpPool.invalidateObject(channelSftp);
            } catch (Exception e) {
                log.error("無效化 SFTP 連線失敗", e);
            }
        }
    }

    public int getActiveConnections() {
        return sftpPool.getNumActive();
    }

    public int getIdleConnections() {
        return sftpPool.getNumIdle();
    }
}

企業級 SFTP 工具類

import com.jcraft.jsch.ChannelSftp;
import com.jcraft.jsch.SftpException;
import io.micrometer.core.instrument.Counter;
import io.micrometer.core.instrument.MeterRegistry;
import io.micrometer.core.instrument.Timer;
import lombok.extern.slf4j.Slf4j;
import org.springframework.stereotype.Component;

import java.io.*;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.Paths;
import java.util.ArrayList;
import java.util.List;
import java.util.Vector;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.ExecutorService;
import java.util.concurrent.Executors;
import java.util.function.Function;

@Slf4j
@Component
public class SftpUtil {

    private final SftpConnectionPoolManager connectionPoolManager;
    private final SftpProperties sftpProperties;
    private final ExecutorService executorService;
    
    // 監控指標
    private final Counter uploadCounter;
    private final Counter downloadCounter;
    private final Counter deleteCounter;
    private final Counter errorCounter;
    private final Timer uploadTimer;
    private final Timer downloadTimer;

    public SftpUtil(SftpConnectionPoolManager connectionPoolManager, 
                    SftpProperties sftpProperties,
                    MeterRegistry meterRegistry) {
        this.connectionPoolManager = connectionPoolManager;
        this.sftpProperties = sftpProperties;
        this.executorService = Executors.newFixedThreadPool(10);
        
        // 初始化監控指標
        this.uploadCounter = Counter.builder("sftp.upload.total")
                .description("Total number of file uploads")
                .register(meterRegistry);
        this.downloadCounter = Counter.builder("sftp.download.total")
                .description("Total number of file downloads")
                .register(meterRegistry);
        this.deleteCounter = Counter.builder("sftp.delete.total")
                .description("Total number of file deletions")
                .register(meterRegistry);
        this.errorCounter = Counter.builder("sftp.error.total")
                .description("Total number of errors")
                .register(meterRegistry);
        this.uploadTimer = Timer.builder("sftp.upload.duration")
                .description("File upload duration")
                .register(meterRegistry);
        this.downloadTimer = Timer.builder("sftp.download.duration")
                .description("File download duration")
                .register(meterRegistry);
    }

    /**
     * 上傳文件
     */
    public boolean uploadFile(String localFilePath, String remoteFilePath) {
        return uploadTimer.recordCallable(() -> {
            boolean success = executeWithRetry(channelSftp -> {
                try {
                    createRemoteDirectoryIfNotExists(channelSftp, getParentPath(remoteFilePath));
                    
                    try (FileInputStream fis = new FileInputStream(localFilePath)) {
                        channelSftp.put(fis, remoteFilePath);
                        log.info("文件上傳成功: {} -> {}", localFilePath, remoteFilePath);
                        uploadCounter.increment();
                        return true;
                    }
                } catch (Exception e) {
                    log.error("文件上傳失敗: {} -> {}", localFilePath, remoteFilePath, e);
                    errorCounter.increment();
                    throw new RuntimeException("文件上傳失敗", e);
                }
            });
            return success;
        });
    }

    /**
     * 批量上傳文件
     */
    public List<CompletableFuture<Boolean>> uploadFilesAsync(List<FileTransferRequest> requests) {
        List<CompletableFuture<Boolean>> futures = new ArrayList<>();
        
        for (FileTransferRequest request : requests) {
            CompletableFuture<Boolean> future = CompletableFuture.supplyAsync(() -> 
                uploadFile(request.getLocalPath(), request.getRemotePath()), executorService);
            futures.add(future);
        }
        
        return futures;
    }

    /**
     * 下載文件
     */
    public boolean downloadFile(String remoteFilePath, String localFilePath) {
        return downloadTimer.recordCallable(() -> {
            boolean success = executeWithRetry(channelSftp -> {
                try {
                    createLocalDirectoryIfNotExists(getParentPath(localFilePath));
                    
                    try (FileOutputStream fos = new FileOutputStream(localFilePath)) {
                        channelSftp.get(remoteFilePath, fos);
                        log.info("文件下載成功: {} -> {}", remoteFilePath, localFilePath);
                        downloadCounter.increment();
                        return true;
                    }
                } catch (Exception e) {
                    log.error("文件下載失敗: {} -> {}", remoteFilePath, localFilePath, e);
                    errorCounter.increment();
                    throw new RuntimeException("文件下載失敗", e);
                }
            });
            return success;
        });
    }

    /**
     * 下載文件到輸出流
     */
    public void downloadFileToStream(String remoteFilePath, OutputStream outputStream) {
        executeWithRetry(channelSftp -> {
            try {
                channelSftp.get(remoteFilePath, outputStream);
                log.info("文件下載到流成功: {}", remoteFilePath);
                downloadCounter.increment();
                return true;
            } catch (Exception e) {
                log.error("文件下載到流失敗: {}", remoteFilePath, e);
                errorCounter.increment();
                throw new RuntimeException("文件下載到流失敗", e);
            }
        });
    }

    /**
     * 獲取文件內容為字符串
     */
    public String getFileContent(String remoteFilePath) {
        return executeWithRetry(channelSftp -> {
            try (InputStream inputStream = channelSftp.get(remoteFilePath);
                 BufferedReader reader = new BufferedReader(new InputStreamReader(inputStream))) {
                
                StringBuilder content = new StringBuilder();
                String line;
                while ((line = reader.readLine()) != null) {
                    content.append(line).append("\n");
                }
                
                log.info("獲取文件內容成功: {}", remoteFilePath);
                return content.toString();
            } catch (Exception e) {
                log.error("獲取文件內容失敗: {}", remoteFilePath, e);
                errorCounter.increment();
                throw new RuntimeException("獲取文件內容失敗", e);
            }
        });
    }

    /**
     * 刪除文件
     */
    public boolean deleteFile(String remoteFilePath) {
        return executeWithRetry(channelSftp -> {
            try {
                channelSftp.rm(remoteFilePath);
                log.info("文件刪除成功: {}", remoteFilePath);
                deleteCounter.increment();
                return true;
            } catch (Exception e) {
                log.error("文件刪除失敗: {}", remoteFilePath, e);
                errorCounter.increment();
                throw new RuntimeException("文件刪除失敗", e);
            }
        });
    }

    /**
     * 列出目錄文件
     */
    public List<SftpFileInfo> listFiles(String remotePath) {
        return executeWithRetry(channelSftp -> {
            try {
                Vector<ChannelSftp.LsEntry> entries = channelSftp.ls(remotePath);
                List<SftpFileInfo> fileInfos = new ArrayList<>();
                
                for (ChannelSftp.LsEntry entry : entries) {
                    if (!entry.getFilename().equals(".") && !entry.getFilename().equals("..")) {
                        SftpFileInfo fileInfo = new SftpFileInfo();
                        fileInfo.setFilename(entry.getFilename());
                        fileInfo.setSize(entry.getAttrs().getSize());
                        fileInfo.setModifiedTime(entry.getAttrs().getMTime());
                        fileInfo.setDirectory(entry.getAttrs().isDir());
                        fileInfos.add(fileInfo);
                    }
                }
                
                log.info("列出目錄文件成功: {}, 共 {} 個文件", remotePath, fileInfos.size());
                return fileInfos;
            } catch (Exception e) {
                log.error("列出目錄文件失敗: {}", remotePath, e);
                errorCounter.increment();
                throw new RuntimeException("列出目錄文件失敗", e);
            }
        });
    }

    /**
     * 檢查文件是否存在
     */
    public boolean fileExists(String remoteFilePath) {
        return executeWithRetry(channelSftp -> {
            try {
                channelSftp.stat(remoteFilePath);
                return true;
            } catch (SftpException e) {
                if (e.id == ChannelSftp.SSH_FX_NO_SUCH_FILE) {
                    return false;
                }
                throw new RuntimeException("檢查文件存在性失敗", e);
            }
        });
    }

    /**
     * 創建遠端目錄
     */
    public void createRemoteDirectory(String remotePath) {
        executeWithRetry(channelSftp -> {
            try {
                createRemoteDirectoryIfNotExists(channelSftp, remotePath);
                log.info("創建遠端目錄成功: {}", remotePath);
                return true;
            } catch (Exception e) {
                log.error("創建遠端目錄失敗: {}", remotePath, e);
                errorCounter.increment();
                throw new RuntimeException("創建遠端目錄失敗", e);
            }
        });
    }

    /**
     * 帶重試機制的執行器
     */
    private <T> T executeWithRetry(Function<ChannelSftp, T> operation) {
        int attempts = 0;
        Exception lastException = null;
        
        while (attempts < sftpProperties.getMaxRetries()) {
            ChannelSftp channelSftp = null;
            try {
                channelSftp = connectionPoolManager.borrowConnection();
                return operation.apply(channelSftp);
            } catch (Exception e) {
                lastException = e;
                attempts++;
                
                if (channelSftp != null) {
                    connectionPoolManager.invalidateConnection(channelSftp);
                    channelSftp = null;
                }
                
                if (attempts < sftpProperties.getMaxRetries()) {
                    log.warn("SFTP 操作失敗，第 {} 次重試", attempts, e);
                    try {
                        Thread.sleep(sftpProperties.getRetryDelay());
                    } catch (InterruptedException ie) {
                        Thread.currentThread().interrupt();
                        throw new RuntimeException("操作被中斷", ie);
                    }
                }
            } finally {
                if (channelSftp != null) {
                    connectionPoolManager.returnConnection(channelSftp);
                }
            }
        }
        
        throw new RuntimeException("SFTP 操作失敗，已重試 " + sftpProperties.getMaxRetries() + " 次", lastException);
    }

    /**
     * 創建遠端目錄（如果不存在）
     */
    private void createRemoteDirectoryIfNotExists(ChannelSftp channelSftp, String remotePath) throws SftpException {
        if (remotePath == null || remotePath.trim().isEmpty()) {
            return;
        }
        
        String[] dirs = remotePath.split("/");
        String currentPath = "";
        
        for (String dir : dirs) {
            if (dir.isEmpty()) continue;
            
            currentPath += "/" + dir;
            try {
                channelSftp.stat(currentPath);
            } catch (SftpException e) {
                if (e.id == ChannelSftp.SSH_FX_NO_SUCH_FILE) {
                    channelSftp.mkdir(currentPath);
                } else {
                    throw e;
                }
            }
        }
    }

    /**
     * 創建本地目錄（如果不存在）
     */
    private void createLocalDirectoryIfNotExists(String localPath) throws IOException {
        if (localPath != null && !localPath.trim().isEmpty()) {
            Path path = Paths.get(localPath);
            if (!Files.exists(path)) {
                Files.createDirectories(path);
            }
        }
    }

    /**
     * 獲取父路徑
     */
    private String getParentPath(String filePath) {
        if (filePath == null) return null;
        
        int lastSlashIndex = filePath.lastIndexOf('/');
        if (lastSlashIndex > 0) {
            return filePath.substring(0, lastSlashIndex);
        }
        return null;
    }

    /**
     * 獲取連線池狀態
     */
    public SftpConnectionPoolStatus getConnectionPoolStatus() {
        SftpConnectionPoolStatus status = new SftpConnectionPoolStatus();
        status.setActiveConnections(connectionPoolManager.getActiveConnections());
        status.setIdleConnections(connectionPoolManager.getIdleConnections());
        return status;
    }
}

支援類別

文件傳輸請求類

import lombok.Data;
import lombok.AllArgsConstructor;
import lombok.NoArgsConstructor;

@Data
@NoArgsConstructor
@AllArgsConstructor
public class FileTransferRequest {
    private String localPath;
    private String remotePath;
}

SFTP 文件信息類

import lombok.Data;

@Data
public class SftpFileInfo {
    private String filename;
    private long size;
    private int modifiedTime;
    private boolean directory;
}

連線池狀態類

import lombok.Data;

@Data
public class SftpConnectionPoolStatus {
    private int activeConnections;
    private int idleConnections;
}

服務層整合

SFTP 服務類

import org.springframework.stereotype.Service;
import org.springframework.web.multipart.MultipartFile;
import lombok.extern.slf4j.Slf4j;

import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.Paths;
import java.util.List;
import java.util.UUID;

@Slf4j
@Service
public class SftpService {

    private final SftpUtil sftpUtil;
    private static final String TEMP_DIR = System.getProperty("java.io.tmpdir");

    public SftpService(SftpUtil sftpUtil) {
        this.sftpUtil = sftpUtil;
    }

    /**
     * 上傳 MultipartFile 到 SFTP
     */
    public boolean uploadMultipartFile(MultipartFile file, String remoteDirectory) {
        String tempFilePath = null;
        try {
            // 創建臨時文件
            tempFilePath = createTempFile(file);
            
            // 構建遠端路徑
            String remoteFilePath = remoteDirectory + "/" + file.getOriginalFilename();
            
            // 上傳文件
            boolean success = sftpUtil.uploadFile(tempFilePath, remoteFilePath);
            
            if (success) {
                log.info("MultipartFile 上傳成功: {}", file.getOriginalFilename());
            }
            
            return success;
        } catch (Exception e) {
            log.error("MultipartFile 上傳失敗: {}", file.getOriginalFilename(), e);
            return false;
        } finally {
            // 清理臨時文件
            if (tempFilePath != null) {
                cleanupTempFile(tempFilePath);
            }
        }
    }

    /**
     * 批量上傳文件
     */
    public void uploadFiles(List<MultipartFile> files, String remoteDirectory) {
        for (MultipartFile file : files) {
            uploadMultipartFile(file, remoteDirectory);
        }
    }

    /**
     * 下載文件並返回字節數組
     */
    public byte[] downloadFileAsBytes(String remoteFilePath) {
        String tempFilePath = null;
        try {
            // 創建臨時文件路徑
            tempFilePath = TEMP_DIR + "/" + UUID.randomUUID() + "_download";
            
            // 下載文件
            boolean success = sftpUtil.downloadFile(remoteFilePath, tempFilePath);
            
            if (success) {
                Path path = Paths.get(tempFilePath);
                return Files.readAllBytes(path);
            }
            
            return null;
        } catch (Exception e) {
            log.error("下載文件失敗: {}", remoteFilePath, e);
            return null;
        } finally {
            // 清理臨時文件
            if (tempFilePath != null) {
                cleanupTempFile(tempFilePath);
            }
        }
    }

    /**
     * 獲取目錄文件列表
     */
    public List<SftpFileInfo> listDirectoryFiles(String remotePath) {
        return sftpUtil.listFiles(remotePath);
    }

    /**
     * 刪除文件
     */
    public boolean deleteFile(String remoteFilePath) {
        return sftpUtil.deleteFile(remoteFilePath);
    }

    /**
     * 檢查文件是否存在
     */
    public boolean checkFileExists(String remoteFilePath) {
        return sftpUtil.fileExists(remoteFilePath);
    }

    /**
     * 創建臨時文件
     */
    private String createTempFile(MultipartFile file) throws IOException {
        String tempFileName = UUID.randomUUID() + "_" + file.getOriginalFilename();
        Path tempPath = Paths.get(TEMP_DIR, tempFileName);
        Files.write(tempPath, file.getBytes());
        return tempPath.toString();
    }

    /**
     * 清理臨時文件
     */
    private void cleanupTempFile(String tempFilePath) {
        try {
            Files.deleteIfExists(Paths.get(tempFilePath));
        } catch (IOException e) {
            log.warn("清理臨時文件失敗: {}", tempFilePath, e);
        }
    }
}

控制器層

SFTP 控制器

import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;
import org.springframework.web.multipart.MultipartFile;
import lombok.extern.slf4j.Slf4j;

import java.util.List;

@Slf4j
@RestController
@RequestMapping("/api/sftp")
public class SftpController {

    private final SftpService sftpService;

    public SftpController(SftpService sftpService) {
        this.sftpService = sftpService;
    }

    /**
     * 上傳文件
     */
    @PostMapping("/upload")
    public ResponseEntity<String> uploadFile(@RequestParam("file") MultipartFile file,
                                           @RequestParam("directory") String directory) {
        try {
            boolean success = sftpService.uploadMultipartFile(file, directory);
            if (success) {
                return ResponseEntity.ok("文件上傳成功");
            } else {
                return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR)
                        .body("文件上傳失敗");
            }
        } catch (Exception e) {
            log.error("上傳文件異常", e);
            return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR)
                    .body("上傳文件異常: " + e.getMessage());
        }
    }

    /**
     * 批量上傳文件
     */
    @PostMapping("/upload/batch")
    public ResponseEntity<String> uploadFiles(@RequestParam("files") List<MultipartFile> files,
                                            @RequestParam("directory") String directory) {
        try {
            sftpService.uploadFiles(files, directory);
            return ResponseEntity.ok("批量上傳成功");
        } catch (Exception e) {
            log.error("批量上傳文件異常", e);
            return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR)
                    .body("批量上傳異常: " + e.getMessage());
        }
    }

    /**
     * 下載文件
     */
    @GetMapping("/download")
    public ResponseEntity<byte[]> downloadFile(@RequestParam("filePath") String filePath) {
        try {
            byte[] fileBytes = sftpService.downloadFileAsBytes(filePath);
            if (fileBytes != null) {
                return ResponseEntity.ok()
                        .header("Content-Disposition", "attachment; filename=\"" + 
                                filePath.substring(filePath.lastIndexOf("/") + 1) + "\"")
                        .body(fileBytes);
            } else {
                return ResponseEntity.notFound().build();
            }
        } catch (Exception e) {
            log.error("下載文件異常", e);
            return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).build();
        }
    }

    /**
     * 列出目錄文件
     */
    @GetMapping("/list")
    public ResponseEntity<List<SftpFileInfo>> listFiles(@RequestParam("directory") String directory) {
        try {
            List<SftpFileInfo> files = sftpService.listDirectoryFiles(directory);
            return ResponseEntity.ok(files);
        } catch (Exception e) {
            log.error("列出目錄文件異常", e);
            return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).build();
        }
    }

    /**
     * 刪除文件
     */
    @DeleteMapping("/delete")
    public ResponseEntity<String> deleteFile(@RequestParam("filePath") String filePath) {
        try {
            boolean success = sftpService.deleteFile(filePath);
            if (success) {
                return ResponseEntity.ok("文件刪除成功");
            } else {
                return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR)
                        .body("文件刪除失敗");
            }
        } catch (Exception e) {
            log.error("刪除文件異常", e);
            return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR)
                    .body("刪除文件異常: " + e.getMessage());
        }
    }

    /**
     * 檢查文件是否存在
     */
    @GetMapping("/exists")
    public ResponseEntity<Boolean> checkFileExists(@RequestParam("filePath") String filePath) {
        try {
            boolean exists = sftpService.checkFileExists(filePath);
            return ResponseEntity.ok(exists);
        } catch (Exception e) {
            log.error("檢查文件存在性異常", e);
            return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).build();
        }
    }
}

監控與健康檢查

SFTP 健康檢查

import org.springframework.boot.actuator.health.Health;
import org.springframework.boot.actuator.health.HealthIndicator;
import org.springframework.stereotype.Component;
import lombok.extern.slf4j.Slf4j;

@Slf4j
@Component
public class SftpHealthIndicator implements HealthIndicator {

    private final SftpUtil sftpUtil;

    public SftpHealthIndicator(SftpUtil sftpUtil) {
        this.sftpUtil = sftpUtil;
    }

    @Override
    public Health health() {
        try {
            // 檢查連線池狀態
            SftpConnectionPoolStatus poolStatus = sftpUtil.getConnectionPoolStatus();
            
            Health.Builder builder = Health.up()
                    .withDetail("activeConnections", poolStatus.getActiveConnections())
                    .withDetail("idleConnections", poolStatus.getIdleConnections())
                    .withDetail("status", "SFTP 服務正常運行");
            
            return builder.build();
        } catch (Exception e) {
            log.error("SFTP 健康檢查失敗", e);
            return Health.down()
                    .withDetail("error", e.getMessage())
                    .withDetail("status", "SFTP 服務異常")
                    .build();
        }
    }
}

自訂監控端點

import org.springframework.boot.actuate.endpoint.annotation.Endpoint;
import org.springframework.boot.actuator.endpoint.annotation.ReadOperation;
import org.springframework.stereotype.Component;

import java.util.HashMap;
import java.util.Map;

@Component
@Endpoint(id = "sftp")
public class SftpEndpoint {

    private final SftpUtil sftpUtil;

    public SftpEndpoint(SftpUtil sftpUtil) {
        this.sftpUtil = sftpUtil;
    }

    @ReadOperation
    public Map<String, Object> sftpInfo() {
        Map<String, Object> info = new HashMap<>();
        
        try {
            SftpConnectionPoolStatus poolStatus = sftpUtil.getConnectionPoolStatus();
            info.put("connectionPool", poolStatus);
            info.put("status", "healthy");
        } catch (Exception e) {
            info.put("status", "unhealthy");
            info.put("error", e.getMessage());
        }
        
        return info;
    }
}

測試

單元測試

import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.extension.ExtendWith;
import org.mockito.Mock;
import org.mockito.junit.jupiter.MockitoExtension;
import org.springframework.test.context.junit.jupiter.SpringJUnitConfig;

import java.io.ByteArrayInputStream;
import java.io.InputStream;

import static org.junit.jupiter.api.Assertions.*;
import static org.mockito.Mockito.*;

@ExtendWith(MockitoExtension.class)
@SpringJUnitConfig
class SftpUtilTest {

    @Mock
    private SftpConnectionPoolManager mockConnectionPoolManager;

    @Mock
    private ChannelSftp mockChannelSftp;

    @Mock
    private SftpProperties mockSftpProperties;

    private SftpUtil sftpUtil;

    @BeforeEach
    void setUp() {
        when(mockSftpProperties.getMaxRetries()).thenReturn(3);
        when(mockSftpProperties.getRetryDelay()).thenReturn(1000);
        
        sftpUtil = new SftpUtil(mockConnectionPoolManager, mockSftpProperties, null);
    }

    @Test
    void testUploadFile_Success() throws Exception {
        // Given
        String localPath = "test.txt";
        String remotePath = "/remote/test.txt";
        
        when(mockConnectionPoolManager.borrowConnection()).thenReturn(mockChannelSftp);
        
        // When
        boolean result = sftpUtil.uploadFile(localPath, remotePath);
        
        // Then
        assertTrue(result);
        verify(mockChannelSftp, times(1)).put(any(InputStream.class), eq(remotePath));
        verify(mockConnectionPoolManager, times(1)).returnConnection(mockChannelSftp);
    }

    @Test
    void testDownloadFile_Success() throws Exception {
        // Given
        String remotePath = "/remote/test.txt";
        String localPath = "test.txt";
        InputStream mockInputStream = new ByteArrayInputStream("test content".getBytes());
        
        when(mockConnectionPoolManager.borrowConnection()).thenReturn(mockChannelSftp);
        when(mockChannelSftp.get(remotePath)).thenReturn(mockInputStream);
        
        // When
        boolean result = sftpUtil.downloadFile(remotePath, localPath);
        
        // Then
        assertTrue(result);
        verify(mockChannelSftp, times(1)).get(eq(remotePath), any());
        verify(mockConnectionPoolManager, times(1)).returnConnection(mockChannelSftp);
    }

    @Test
    void testFileExists_FileExists() throws Exception {
        // Given
        String remotePath = "/remote/test.txt";
        
        when(mockConnectionPoolManager.borrowConnection()).thenReturn(mockChannelSftp);
        when(mockChannelSftp.stat(remotePath)).thenReturn(null); // 不拋出異常表示文件存在
        
        // When
        boolean result = sftpUtil.fileExists(remotePath);
        
        // Then
        assertTrue(result);
        verify(mockChannelSftp, times(1)).stat(remotePath);
        verify(mockConnectionPoolManager, times(1)).returnConnection(mockChannelSftp);
    }
}

整合測試

import org.junit.jupiter.api.Test;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.test.context.ActiveProfiles;
import org.springframework.test.context.junit.jupiter.SpringJUnitConfig;
import org.springframework.beans.factory.annotation.Autowired;

@SpringBootTest
@ActiveProfiles("test")
@SpringJUnitConfig
class SftpIntegrationTest {

    @Autowired
    private SftpService sftpService;

    @Test
    void testSftpServiceIntegration() {
        // 整合測試應該使用測試 SFTP 服務器
        // 這裡只是展示測試結構
        
        // Given
        String testDirectory = "/test";
        
        // When & Then
        // 執行實際的 SFTP 操作測試
        assertDoesNotThrow(() -> {
            sftpService.listDirectoryFiles(testDirectory);
        });
    }
}

最佳實踐

1. 安全性考慮

# 生產環境配置
sftp:
  # 使用環境變數或 Vault 管理敏感信息
  username: ${SFTP_USERNAME}
  password: ${SFTP_PASSWORD}
  private-key-path: ${SFTP_PRIVATE_KEY_PATH}
  
  # 啟用嚴格的主機密鑰檢查
  strict-host-key-checking: true
  known-hosts-file: /etc/ssh/ssh_known_hosts
  
  # 使用安全的主機密鑰算法
  host-key-algorithms: rsa-sha2-512,rsa-sha2-256

2. 效能優化

// 使用批量操作
@Component
public class SftpBatchProcessor {
    
    public void processBatchUpload(List<FileTransferRequest> requests) {
        // 分批處理大量文件
        int batchSize = 10;
        for (int i = 0; i < requests.size(); i += batchSize) {
            List<FileTransferRequest> batch = requests.subList(i, 
                Math.min(i + batchSize, requests.size()));
            processBatch(batch);
        }
    }
    
    private void processBatch(List<FileTransferRequest> batch) {
        // 並行處理批次
        List<CompletableFuture<Boolean>> futures = 
            sftpUtil.uploadFilesAsync(batch);
        
        // 等待所有任務完成
        CompletableFuture.allOf(futures.toArray(new CompletableFuture[0])).join();
    }
}

3. 錯誤處理策略

@Component
public class SftpErrorHandler {
    
    public void handleSftpError(Exception e, String operation, String filePath) {
        if (e instanceof SftpException) {
            SftpException sftpException = (SftpException) e;
            switch (sftpException.id) {
                case ChannelSftp.SSH_FX_NO_SUCH_FILE:
                    log.warn("文件不存在: {}", filePath);
                    break;
                case ChannelSftp.SSH_FX_PERMISSION_DENIED:
                    log.error("權限不足: {}", filePath);
                    break;
                case ChannelSftp.SSH_FX_CONNECTION_LOST:
                    log.error("連線中斷: {}", filePath);
                    // 觸發重連
                    break;
                default:
                    log.error("SFTP 操作失敗: {} - {}", operation, filePath, e);
            }
        } else {
            log.error("一般錯誤: {} - {}", operation, filePath, e);
        }
    }
}

總結

本文詳細介紹了企業級 SFTP 工具類的完整實作，包含以下關鍵特性：

Spring Data JPA Pageable 分頁查詢：完整實作與效能優化指南

Tue, 07 Jan 2020 13:26:41 +0800

概述

在處理大量資料時，分頁查詢是必不可少的功能。Spring Data JPA 提供了強大的 Pageable 接口，配合 Specification 可以輕鬆實現靈活的分頁查詢功能。本文將深入介紹如何使用這些功能來構建高效的分頁系統。

核心概念

Pageable：分頁參數接口，定義頁面大小、頁碼和排序規則
Page：分頁結果接口，包含資料和分頁資訊
Specification：查詢規格接口，用於動態構建查詢條件
Criteria API：JPA 標準的類型安全查詢 API

架構優勢

類型安全：Criteria API 提供編譯時檢查
動態查詢：根據條件動態構建 SQL
自動計數：自動執行 COUNT 查詢計算總數
靈活排序：支援多欄位排序
效能優化：支援各種優化策略

基礎配置

1. 依賴設定

<!-- Spring Boot Starter Data JPA -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-data-jpa</artifactId>
</dependency>

<!-- Spring Boot Starter Web -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>

<!-- Database Driver (以 MySQL 為例) -->
<dependency>
    <groupId>com.mysql</groupId>
    <artifactId>mysql-connector-j</artifactId>
    <scope>runtime</scope>
</dependency>

<!-- Spring Boot Starter Validation -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-validation</artifactId>
</dependency>

2. 實體類定義

package com.example.pagination.entity;

import jakarta.persistence.*;
import jakarta.validation.constraints.NotBlank;
import jakarta.validation.constraints.Email;
import org.hibernate.annotations.CreationTimestamp;
import org.hibernate.annotations.UpdateTimestamp;

import java.time.LocalDateTime;

@Entity
@Table(name = "users", indexes = {
    @Index(name = "idx_username", columnList = "username"),
    @Index(name = "idx_email", columnList = "email"),
    @Index(name = "idx_status", columnList = "status"),
    @Index(name = "idx_created_at", columnList = "created_at")
})
public class User {
    
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
    
    @NotBlank
    @Column(unique = true, nullable = false, length = 50)
    private String username;
    
    @NotBlank
    @Email
    @Column(unique = true, nullable = false, length = 100)
    private String email;
    
    @Column(name = "first_name", length = 50)
    private String firstName;
    
    @Column(name = "last_name", length = 50)
    private String lastName;
    
    @Enumerated(EnumType.STRING)
    @Column(nullable = false)
    private UserStatus status = UserStatus.ACTIVE;
    
    @Column(name = "age")
    private Integer age;
    
    @Column(name = "city", length = 100)
    private String city;
    
    @CreationTimestamp
    @Column(name = "created_at", nullable = false, updatable = false)
    private LocalDateTime createdAt;
    
    @UpdateTimestamp
    @Column(name = "updated_at", nullable = false)
    private LocalDateTime updatedAt;
    
    // 建構子
    public User() {}
    
    public User(String username, String email, String firstName, String lastName) {
        this.username = username;
        this.email = email;
        this.firstName = firstName;
        this.lastName = lastName;
    }
    
    // Getters and Setters
    public Long getId() { return id; }
    public void setId(Long id) { this.id = id; }
    
    public String getUsername() { return username; }
    public void setUsername(String username) { this.username = username; }
    
    public String getEmail() { return email; }
    public void setEmail(String email) { this.email = email; }
    
    public String getFirstName() { return firstName; }
    public void setFirstName(String firstName) { this.firstName = firstName; }
    
    public String getLastName() { return lastName; }
    public void setLastName(String lastName) { this.lastName = lastName; }
    
    public UserStatus getStatus() { return status; }
    public void setStatus(UserStatus status) { this.status = status; }
    
    public Integer getAge() { return age; }
    public void setAge(Integer age) { this.age = age; }
    
    public String getCity() { return city; }
    public void setCity(String city) { this.city = city; }
    
    public LocalDateTime getCreatedAt() { return createdAt; }
    public LocalDateTime getUpdatedAt() { return updatedAt; }
}

enum UserStatus {
    ACTIVE, INACTIVE, SUSPENDED, DELETED
}

3. Repository 接口

package com.example.pagination.repository;

import com.example.pagination.entity.User;
import org.springframework.data.domain.Page;
import org.springframework.data.domain.Pageable;
import org.springframework.data.jpa.domain.Specification;
import org.springframework.data.jpa.repository.JpaRepository;
import org.springframework.data.jpa.repository.JpaSpecificationExecutor;
import org.springframework.data.jpa.repository.Query;
import org.springframework.data.repository.query.Param;
import org.springframework.stereotype.Repository;

import java.time.LocalDateTime;
import java.util.List;

@Repository
public interface UserRepository extends JpaRepository<User, Long>, JpaSpecificationExecutor<User> {
    
    // 基本分頁查詢
    Page<User> findByStatus(UserStatus status, Pageable pageable);
    
    // 複合條件分頁查詢
    Page<User> findByStatusAndAgeGreaterThan(UserStatus status, Integer age, Pageable pageable);
    
    // 模糊查詢分頁
    Page<User> findByUsernameContainingIgnoreCase(String username, Pageable pageable);
    
    // 時間範圍查詢
    Page<User> findByCreatedAtBetween(LocalDateTime start, LocalDateTime end, Pageable pageable);
    
    // 自訂查詢分頁
    @Query("SELECT u FROM User u WHERE u.city = :city AND u.age BETWEEN :minAge AND :maxAge")
    Page<User> findByCityAndAgeBetween(@Param("city") String city, 
                                       @Param("minAge") Integer minAge, 
                                       @Param("maxAge") Integer maxAge, 
                                       Pageable pageable);
    
    // 原生 SQL 分頁查詢
    @Query(value = "SELECT * FROM users u WHERE u.email LIKE %:emailDomain%", 
           countQuery = "SELECT COUNT(*) FROM users u WHERE u.email LIKE %:emailDomain%",
           nativeQuery = true)
    Page<User> findByEmailDomain(@Param("emailDomain") String emailDomain, Pageable pageable);
    
    // 投影查詢（只查詢部分欄位）
    @Query("SELECT new com.example.pagination.dto.UserSummaryDto(u.id, u.username, u.email, u.status) " +
           "FROM User u WHERE u.status = :status")
    Page<UserSummaryDto> findUserSummariesByStatus(@Param("status") UserStatus status, Pageable pageable);
}

Specification 動態查詢

1. 基礎 Specification

package com.example.pagination.specification;

import com.example.pagination.entity.User;
import com.example.pagination.entity.UserStatus;
import org.springframework.data.jpa.domain.Specification;

import jakarta.persistence.criteria.*;
import java.time.LocalDateTime;
import java.util.ArrayList;
import java.util.List;

public class UserSpecification {
    
    /**
     * 根據使用者名稱模糊查詢
     */
    public static Specification<User> usernameContains(String username) {
        return (root, query, criteriaBuilder) -> {
            if (username == null || username.trim().isEmpty()) {
                return criteriaBuilder.conjunction();
            }
            return criteriaBuilder.like(
                criteriaBuilder.lower(root.get("username")), 
                "%" + username.toLowerCase() + "%"
            );
        };
    }
    
    /**
     * 根據郵箱模糊查詢
     */
    public static Specification<User> emailContains(String email) {
        return (root, query, criteriaBuilder) -> {
            if (email == null || email.trim().isEmpty()) {
                return criteriaBuilder.conjunction();
            }
            return criteriaBuilder.like(
                criteriaBuilder.lower(root.get("email")), 
                "%" + email.toLowerCase() + "%"
            );
        };
    }
    
    /**
     * 根據狀態查詢
     */
    public static Specification<User> statusEquals(UserStatus status) {
        return (root, query, criteriaBuilder) -> {
            if (status == null) {
                return criteriaBuilder.conjunction();
            }
            return criteriaBuilder.equal(root.get("status"), status);
        };
    }
    
    /**
     * 根據年齡範圍查詢
     */
    public static Specification<User> ageBetween(Integer minAge, Integer maxAge) {
        return (root, query, criteriaBuilder) -> {
            List<Predicate> predicates = new ArrayList<>();
            
            if (minAge != null) {
                predicates.add(criteriaBuilder.greaterThanOrEqualTo(root.get("age"), minAge));
            }
            if (maxAge != null) {
                predicates.add(criteriaBuilder.lessThanOrEqualTo(root.get("age"), maxAge));
            }
            
            return criteriaBuilder.and(predicates.toArray(new Predicate[0]));
        };
    }
    
    /**
     * 根據城市查詢
     */
    public static Specification<User> cityEquals(String city) {
        return (root, query, criteriaBuilder) -> {
            if (city == null || city.trim().isEmpty()) {
                return criteriaBuilder.conjunction();
            }
            return criteriaBuilder.equal(root.get("city"), city);
        };
    }
    
    /**
     * 根據創建時間範圍查詢
     */
    public static Specification<User> createdAtBetween(LocalDateTime startDate, LocalDateTime endDate) {
        return (root, query, criteriaBuilder) -> {
            List<Predicate> predicates = new ArrayList<>();
            
            if (startDate != null) {
                predicates.add(criteriaBuilder.greaterThanOrEqualTo(root.get("createdAt"), startDate));
            }
            if (endDate != null) {
                predicates.add(criteriaBuilder.lessThanOrEqualTo(root.get("createdAt"), endDate));
            }
            
            return criteriaBuilder.and(predicates.toArray(new Predicate[0]));
        };
    }
    
    /**
     * 複合查詢 - 根據多個條件
     */
    public static Specification<User> withFilters(String username, String email, 
                                                  UserStatus status, Integer minAge, 
                                                  Integer maxAge, String city) {
        return Specification.where(usernameContains(username))
                .and(emailContains(email))
                .and(statusEquals(status))
                .and(ageBetween(minAge, maxAge))
                .and(cityEquals(city));
    }
    
    /**
     * 進階查詢 - 支援 OR 條件
     */
    public static Specification<User> searchByKeyword(String keyword) {
        return (root, query, criteriaBuilder) -> {
            if (keyword == null || keyword.trim().isEmpty()) {
                return criteriaBuilder.conjunction();
            }
            
            String likePattern = "%" + keyword.toLowerCase() + "%";
            
            return criteriaBuilder.or(
                criteriaBuilder.like(criteriaBuilder.lower(root.get("username")), likePattern),
                criteriaBuilder.like(criteriaBuilder.lower(root.get("email")), likePattern),
                criteriaBuilder.like(criteriaBuilder.lower(root.get("firstName")), likePattern),
                criteriaBuilder.like(criteriaBuilder.lower(root.get("lastName")), likePattern),
                criteriaBuilder.like(criteriaBuilder.lower(root.get("city")), likePattern)
            );
        };
    }
}

2. 動態 Specification 建構器

package com.example.pagination.specification;

import org.springframework.data.jpa.domain.Specification;

import jakarta.persistence.criteria.CriteriaBuilder;
import jakarta.persistence.criteria.Predicate;
import jakarta.persistence.criteria.Root;
import java.util.ArrayList;
import java.util.List;

public class DynamicSpecificationBuilder<T> {
    
    private List<Specification<T>> specifications = new ArrayList<>();
    
    public DynamicSpecificationBuilder<T> with(String field, String operation, Object value) {
        if (value != null) {
            specifications.add(createSpecification(field, operation, value));
        }
        return this;
    }
    
    public DynamicSpecificationBuilder<T> with(Specification<T> specification) {
        if (specification != null) {
            specifications.add(specification);
        }
        return this;
    }
    
    public Specification<T> build() {
        if (specifications.isEmpty()) {
            return null;
        }
        
        Specification<T> result = specifications.get(0);
        for (int i = 1; i < specifications.size(); i++) {
            result = Specification.where(result).and(specifications.get(i));
        }
        return result;
    }
    
    private Specification<T> createSpecification(String field, String operation, Object value) {
        return (root, query, criteriaBuilder) -> {
            switch (operation.toLowerCase()) {
                case "eq":
                case "equals":
                    return criteriaBuilder.equal(root.get(field), value);
                    
                case "ne":
                case "not_equals":
                    return criteriaBuilder.notEqual(root.get(field), value);
                    
                case "gt":
                case "greater_than":
                    return criteriaBuilder.greaterThan(root.get(field), (Comparable) value);
                    
                case "gte":
                case "greater_than_or_equal":
                    return criteriaBuilder.greaterThanOrEqualTo(root.get(field), (Comparable) value);
                    
                case "lt":
                case "less_than":
                    return criteriaBuilder.lessThan(root.get(field), (Comparable) value);
                    
                case "lte":
                case "less_than_or_equal":
                    return criteriaBuilder.lessThanOrEqualTo(root.get(field), (Comparable) value);
                    
                case "like":
                case "contains":
                    return criteriaBuilder.like(
                        criteriaBuilder.lower(root.get(field)), 
                        "%" + value.toString().toLowerCase() + "%"
                    );
                    
                case "starts_with":
                    return criteriaBuilder.like(
                        criteriaBuilder.lower(root.get(field)), 
                        value.toString().toLowerCase() + "%"
                    );
                    
                case "ends_with":
                    return criteriaBuilder.like(
                        criteriaBuilder.lower(root.get(field)), 
                        "%" + value.toString().toLowerCase()
                    );
                    
                case "in":
                    if (value instanceof List) {
                        return root.get(field).in((List<?>) value);
                    }
                    return criteriaBuilder.equal(root.get(field), value);
                    
                case "is_null":
                    return criteriaBuilder.isNull(root.get(field));
                    
                case "is_not_null":
                    return criteriaBuilder.isNotNull(root.get(field));
                    
                default:
                    throw new IllegalArgumentException("不支援的操作: " + operation);
            }
        };
    }
}

DTO 和分頁請求處理

1. 分頁請求 DTO

package com.example.pagination.dto;

import com.example.pagination.entity.UserStatus;
import jakarta.validation.constraints.Min;
import jakarta.validation.constraints.Max;
import org.springframework.data.domain.PageRequest;
import org.springframework.data.domain.Pageable;
import org.springframework.data.domain.Sort;

import java.time.LocalDateTime;

public class UserPageRequest {
    
    @Min(value = 0, message = "頁碼不能小於 0")
    private int page = 0;
    
    @Min(value = 1, message = "每頁大小不能小於 1")
    @Max(value = 100, message = "每頁大小不能超過 100")
    private int size = 20;
    
    private String sortBy = "id";
    private String sortDirection = "DESC";
    
    // 查詢條件
    private String username;
    private String email;
    private UserStatus status;
    private Integer minAge;
    private Integer maxAge;
    private String city;
    private String keyword; // 關鍵字搜索
    private LocalDateTime startDate;
    private LocalDateTime endDate;
    
    // 建構子
    public UserPageRequest() {}
    
    public UserPageRequest(int page, int size) {
        this.page = page;
        this.size = size;
    }
    
    /**
     * 轉換為 Pageable 物件
     */
    public Pageable toPageable() {
        Sort.Direction direction = Sort.Direction.fromString(sortDirection);
        Sort sort = Sort.by(direction, sortBy);
        return PageRequest.of(page, size, sort);
    }
    
    /**
     * 檢查是否有查詢條件
     */
    public boolean hasFilters() {
        return username != null || email != null || status != null ||
               minAge != null || maxAge != null || city != null ||
               keyword != null || startDate != null || endDate != null;
    }
    
    // Getters and Setters
    public int getPage() { return page; }
    public void setPage(int page) { this.page = page; }
    
    public int getSize() { return size; }
    public void setSize(int size) { this.size = size; }
    
    public String getSortBy() { return sortBy; }
    public void setSortBy(String sortBy) { this.sortBy = sortBy; }
    
    public String getSortDirection() { return sortDirection; }
    public void setSortDirection(String sortDirection) { this.sortDirection = sortDirection; }
    
    public String getUsername() { return username; }
    public void setUsername(String username) { this.username = username; }
    
    public String getEmail() { return email; }
    public void setEmail(String email) { this.email = email; }
    
    public UserStatus getStatus() { return status; }
    public void setStatus(UserStatus status) { this.status = status; }
    
    public Integer getMinAge() { return minAge; }
    public void setMinAge(Integer minAge) { this.minAge = minAge; }
    
    public Integer getMaxAge() { return maxAge; }
    public void setMaxAge(Integer maxAge) { this.maxAge = maxAge; }
    
    public String getCity() { return city; }
    public void setCity(String city) { this.city = city; }
    
    public String getKeyword() { return keyword; }
    public void setKeyword(String keyword) { this.keyword = keyword; }
    
    public LocalDateTime getStartDate() { return startDate; }
    public void setStartDate(LocalDateTime startDate) { this.startDate = startDate; }
    
    public LocalDateTime getEndDate() { return endDate; }
    public void setEndDate(LocalDateTime endDate) { this.endDate = endDate; }
}

2. 分頁回應 DTO

package com.example.pagination.dto;

import org.springframework.data.domain.Page;

import java.util.List;

public class PageResponse<T> {
    
    private List<T> content;
    private int page;
    private int size;
    private long totalElements;
    private int totalPages;
    private boolean first;
    private boolean last;
    private boolean hasNext;
    private boolean hasPrevious;
    private int numberOfElements;
    
    // 建構子
    public PageResponse() {}
    
    public PageResponse(Page<T> page) {
        this.content = page.getContent();
        this.page = page.getNumber();
        this.size = page.getSize();
        this.totalElements = page.getTotalElements();
        this.totalPages = page.getTotalPages();
        this.first = page.isFirst();
        this.last = page.isLast();
        this.hasNext = page.hasNext();
        this.hasPrevious = page.hasPrevious();
        this.numberOfElements = page.getNumberOfElements();
    }
    
    public static <T> PageResponse<T> of(Page<T> page) {
        return new PageResponse<>(page);
    }
    
    // Getters and Setters
    public List<T> getContent() { return content; }
    public void setContent(List<T> content) { this.content = content; }
    
    public int getPage() { return page; }
    public void setPage(int page) { this.page = page; }
    
    public int getSize() { return size; }
    public void setSize(int size) { this.size = size; }
    
    public long getTotalElements() { return totalElements; }
    public void setTotalElements(long totalElements) { this.totalElements = totalElements; }
    
    public int getTotalPages() { return totalPages; }
    public void setTotalPages(int totalPages) { this.totalPages = totalPages; }
    
    public boolean isFirst() { return first; }
    public void setFirst(boolean first) { this.first = first; }
    
    public boolean isLast() { return last; }
    public void setLast(boolean last) { this.last = last; }
    
    public boolean isHasNext() { return hasNext; }
    public void setHasNext(boolean hasNext) { this.hasNext = hasNext; }
    
    public boolean isHasPrevious() { return hasPrevious; }
    public void setHasPrevious(boolean hasPrevious) { this.hasPrevious = hasPrevious; }
    
    public int getNumberOfElements() { return numberOfElements; }
    public void setNumberOfElements(int numberOfElements) { this.numberOfElements = numberOfElements; }
}

3. 使用者摘要 DTO

package com.example.pagination.dto;

import com.example.pagination.entity.UserStatus;

public class UserSummaryDto {
    
    private Long id;
    private String username;
    private String email;
    private UserStatus status;
    
    // 建構子
    public UserSummaryDto() {}
    
    public UserSummaryDto(Long id, String username, String email, UserStatus status) {
        this.id = id;
        this.username = username;
        this.email = email;
        this.status = status;
    }
    
    // Getters and Setters
    public Long getId() { return id; }
    public void setId(Long id) { this.id = id; }
    
    public String getUsername() { return username; }
    public void setUsername(String username) { this.username = username; }
    
    public String getEmail() { return email; }
    public void setEmail(String email) { this.email = email; }
    
    public UserStatus getStatus() { return status; }
    public void setStatus(UserStatus status) { this.status = status; }
}

Service 層實作

1. 使用者服務介面

package com.example.pagination.service;

import com.example.pagination.dto.PageResponse;
import com.example.pagination.dto.UserPageRequest;
import com.example.pagination.dto.UserSummaryDto;
import com.example.pagination.entity.User;
import com.example.pagination.entity.UserStatus;
import org.springframework.data.domain.Page;

public interface UserService {
    
    /**
     * 分頁查詢使用者
     */
    PageResponse<User> findUsers(UserPageRequest request);
    
    /**
     * 關鍵字搜索使用者
     */
    PageResponse<User> searchUsers(String keyword, UserPageRequest request);
    
    /**
     * 根據狀態分頁查詢使用者摘要
     */
    PageResponse<UserSummaryDto> findUserSummariesByStatus(UserStatus status, UserPageRequest request);
    
    /**
     * 高級搜索
     */
    PageResponse<User> advancedSearch(UserPageRequest request);
}

2. 使用者服務實作

package com.example.pagination.service.impl;

import com.example.pagination.dto.PageResponse;
import com.example.pagination.dto.UserPageRequest;
import com.example.pagination.dto.UserSummaryDto;
import com.example.pagination.entity.User;
import com.example.pagination.entity.UserStatus;
import com.example.pagination.repository.UserRepository;
import com.example.pagination.service.UserService;
import com.example.pagination.specification.DynamicSpecificationBuilder;
import com.example.pagination.specification.UserSpecification;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.data.domain.Page;
import org.springframework.data.domain.Pageable;
import org.springframework.data.jpa.domain.Specification;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;

@Service
@Transactional(readOnly = true)
public class UserServiceImpl implements UserService {
    
    @Autowired
    private UserRepository userRepository;
    
    @Override
    public PageResponse<User> findUsers(UserPageRequest request) {
        Pageable pageable = request.toPageable();
        
        if (!request.hasFilters()) {
            // 沒有過濾條件，直接分頁查詢
            Page<User> page = userRepository.findAll(pageable);
            return PageResponse.of(page);
        }
        
        // 有過濾條件，使用 Specification
        Specification<User> spec = UserSpecification.withFilters(
            request.getUsername(),
            request.getEmail(),
            request.getStatus(),
            request.getMinAge(),
            request.getMaxAge(),
            request.getCity()
        );
        
        Page<User> page = userRepository.findAll(spec, pageable);
        return PageResponse.of(page);
    }
    
    @Override
    public PageResponse<User> searchUsers(String keyword, UserPageRequest request) {
        Pageable pageable = request.toPageable();
        Specification<User> spec = UserSpecification.searchByKeyword(keyword);
        
        Page<User> page = userRepository.findAll(spec, pageable);
        return PageResponse.of(page);
    }
    
    @Override
    public PageResponse<UserSummaryDto> findUserSummariesByStatus(UserStatus status, UserPageRequest request) {
        Pageable pageable = request.toPageable();
        Page<UserSummaryDto> page = userRepository.findUserSummariesByStatus(status, pageable);
        return PageResponse.of(page);
    }
    
    @Override
    public PageResponse<User> advancedSearch(UserPageRequest request) {
        Pageable pageable = request.toPageable();
        
        // 使用動態 Specification 建構器
        DynamicSpecificationBuilder<User> builder = new DynamicSpecificationBuilder<>();
        
        builder.with("username", "contains", request.getUsername())
               .with("email", "contains", request.getEmail())
               .with("status", "equals", request.getStatus())
               .with("age", "gte", request.getMinAge())
               .with("age", "lte", request.getMaxAge())
               .with("city", "equals", request.getCity())
               .with("createdAt", "gte", request.getStartDate())
               .with("createdAt", "lte", request.getEndDate());
        
        // 如果有關鍵字，添加關鍵字搜索
        if (request.getKeyword() != null && !request.getKeyword().trim().isEmpty()) {
            builder.with(UserSpecification.searchByKeyword(request.getKeyword()));
        }
        
        Specification<User> spec = builder.build();
        Page<User> page = userRepository.findAll(spec, pageable);
        return PageResponse.of(page);
    }
}

Controller 層實作

1. 使用者控制器

package com.example.pagination.controller;

import com.example.pagination.dto.PageResponse;
import com.example.pagination.dto.UserPageRequest;
import com.example.pagination.dto.UserSummaryDto;
import com.example.pagination.entity.User;
import com.example.pagination.entity.UserStatus;
import com.example.pagination.service.UserService;
import jakarta.validation.Valid;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/api/users")
@CrossOrigin(origins = "*", maxAge = 3600)
public class UserController {
    
    @Autowired
    private UserService userService;
    
    /**
     * 分頁查詢使用者
     */
    @GetMapping
    public ResponseEntity<PageResponse<User>> getUsers(@Valid UserPageRequest request) {
        PageResponse<User> response = userService.findUsers(request);
        return ResponseEntity.ok(response);
    }
    
    /**
     * 關鍵字搜索使用者
     */
    @GetMapping("/search")
    public ResponseEntity<PageResponse<User>> searchUsers(
            @RequestParam String keyword,
            @Valid UserPageRequest request) {
        
        PageResponse<User> response = userService.searchUsers(keyword, request);
        return ResponseEntity.ok(response);
    }
    
    /**
     * 高級搜索
     */
    @PostMapping("/advanced-search")
    public ResponseEntity<PageResponse<User>> advancedSearch(@Valid @RequestBody UserPageRequest request) {
        PageResponse<User> response = userService.advancedSearch(request);
        return ResponseEntity.ok(response);
    }
    
    /**
     * 根據狀態查詢使用者摘要
     */
    @GetMapping("/summaries")
    public ResponseEntity<PageResponse<UserSummaryDto>> getUserSummaries(
            @RequestParam UserStatus status,
            @Valid UserPageRequest request) {
        
        PageResponse<UserSummaryDto> response = userService.findUserSummariesByStatus(status, request);
        return ResponseEntity.ok(response);
    }
    
    /**
     * 使用路徑參數的分頁查詢
     */
    @GetMapping("/page/{page}/size/{size}")
    public ResponseEntity<PageResponse<User>> getUsersWithPathParams(
            @PathVariable int page,
            @PathVariable int size,
            @RequestParam(required = false) String sortBy,
            @RequestParam(required = false) String sortDirection) {
        
        UserPageRequest request = new UserPageRequest(page, size);
        if (sortBy != null) request.setSortBy(sortBy);
        if (sortDirection != null) request.setSortDirection(sortDirection);
        
        PageResponse<User> response = userService.findUsers(request);
        return ResponseEntity.ok(response);
    }
}

2. 分頁配置控制器

package com.example.pagination.controller;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.data.domain.PageRequest;
import org.springframework.data.domain.Pageable;
import org.springframework.data.domain.Sort;
import org.springframework.data.web.PageableDefault;
import org.springframework.data.web.SortDefault;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

import java.util.HashMap;
import java.util.Map;

@RestController
@RequestMapping("/api/config")
public class PageConfigController {
    
    /**
     * 使用 Spring 自動解析的 Pageable 參數
     */
    @GetMapping("/users")
    public ResponseEntity<Map<String, Object>> getUsersWithSpringPageable(
            @PageableDefault(page = 0, size = 20) 
            @SortDefault(sort = "id", direction = Sort.Direction.DESC) 
            Pageable pageable) {
        
        Map<String, Object> result = new HashMap<>();
        result.put("page", pageable.getPageNumber());
        result.put("size", pageable.getPageSize());
        result.put("sort", pageable.getSort().toString());
        
        return ResponseEntity.ok(result);
    }
    
    /**
     * 動態排序欄位驗證
     */
    @GetMapping("/users/validated")
    public ResponseEntity<Pageable> getValidatedPageable(
            @RequestParam(defaultValue = "0") int page,
            @RequestParam(defaultValue = "20") int size,
            @RequestParam(defaultValue = "id") String sortBy,
            @RequestParam(defaultValue = "DESC") String sortDirection) {
        
        // 驗證排序欄位
        String[] allowedSortFields = {"id", "username", "email", "createdAt", "updatedAt"};
        boolean isValidSortField = false;
        for (String field : allowedSortFields) {
            if (field.equals(sortBy)) {
                isValidSortField = true;
                break;
            }
        }
        
        if (!isValidSortField) {
            sortBy = "id"; // 預設排序欄位
        }
        
        Sort.Direction direction = Sort.Direction.fromString(sortDirection);
        Sort sort = Sort.by(direction, sortBy);
        Pageable pageable = PageRequest.of(page, size, sort);
        
        return ResponseEntity.ok(pageable);
    }
}

OFFSET 分頁效能問題與替代方案

Page<T> 預設使用 LIMIT ? OFFSET ? 實作，OFFSET 越大效能越差（MySQL 需掃描並丟棄前 N 筆資料）。