Architecture on Bill.Lin's Notes

Outbox Pattern — 分散式事務一致性

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

問題：Dual-Write

在微服務中，一個業務操作往往需要：

寫入資料庫（持久化訂單）
發布事件到 Kafka（通知下游服務）

這兩個動作無法包在同一個 ACID transaction 裡（資料庫 + Kafka 是兩個不同的資源管理器）：

// 危險的 Dual-Write：兩個操作不是原子的
@Transactional
public void createOrder(CreateOrderCommand cmd) {
    Order order = orderRepository.save(new Order(cmd));  // DB 寫入成功
    kafkaTemplate.send("order.created", new OrderCreatedEvent(order)); // 若此處失敗？
    // DB 已提交，但 Kafka 事件未送出 → 下游永遠不知道這筆訂單
}

可能的失敗情境

情境 A：DB 成功，Kafka 失敗
  → 訂單存在，但下游沒收到事件，資料不一致

情境 B：Kafka 成功，DB 回滾
  → 下游已處理不存在的訂單

情境 C：應用程序在兩個操作中間 crash
  → 同情境 A 或 B

Outbox Pattern 解法

核心思想：把事件記錄寫入與業務資料同一個 DB transaction，讓 DB 的 ACID 保證兩者的原子性。再由獨立的 Publisher 非同步地將事件發布到 Kafka。

六角形架構（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，結構如下：

代碼壞味道 (Code Smells) 完整識別與重構指南：軟體品質改善最佳實踐

Thu, 17 Mar 2022 22:50:11 +0800

代碼壞味道 (Code Smells) 完整識別與重構指南

概述

代碼壞味道是指代碼中存在的設計缺陷和結構問題，雖然不會導致程序功能錯誤，但會影響代碼的可讀性、可維護性和可擴展性。本文將深入探討各種代碼壞味道的識別方法、重構技巧和預防策略。

經典四大軟體設計問題

1. Rigidity (僵化性) - 難以變更

問題描述： 系統中存在過多的相依性，導致任何小的變更都需要修改大量相關代碼。

症狀：

修改一個小功能需要改動多個模組
開發人員害怕進行代碼變更
估算工作量困難，因為變更範圍難以預測

壞味道示例：

// 僵化的訂單處理系統
public class OrderService {
    private DatabaseConnection dbConnection;
    private EmailService emailService;
    private InventoryService inventoryService;
    private PaymentService paymentService;
    private LoggingService loggingService;
    
    public void processOrder(Order order) {
        // 直接依賴具體實現，難以變更
        dbConnection.connect("jdbc:mysql://localhost:3306/orders");
        
        // 硬編碼的業務邏輯
        if (order.getType().equals("PREMIUM")) {
            order.setDiscount(0.1);
        } else if (order.getType().equals("STANDARD")) {
            order.setDiscount(0.05);
        }
        
        // 緊密耦合的操作順序
        inventoryService.reserveItems(order.getItems());
        paymentService.processPayment(order.getPayment());
        dbConnection.saveOrder(order);
        emailService.sendConfirmationEmail(order.getCustomer());
        loggingService.log("Order processed: " + order.getId());
    }
}

重構解決方案：

UML 統一建模語言完整指南：軟體設計與架構建模最佳實踐

Mon, 12 Jul 2021 23:33:14 +0800

UML 統一建模語言完整指南

概述

UML（Unified Modeling Language，統一建模語言）是一種標準化的建模語言，用於軟體系統的視覺化、規範、建構和文檔化。UML 提供了多種圖形表示法，幫助開發人員理解系統結構、行為和互動關係。

UML 圖形分類

結構圖（Structure Diagrams）

類別圖（Class Diagram）：展示類別及其關係
物件圖（Object Diagram）：展示特定時刻的物件實例
封裝圖（Package Diagram）：展示套件及其依賴關係
部署圖（Deployment Diagram）：展示系統部署結構

行為圖（Behavior Diagrams）

使用案例圖（Use Case Diagram）：展示系統功能和用戶互動
活動圖（Activity Diagram）：展示工作流程和業務邏輯
狀態圖（State Diagram）：展示物件狀態變化

互動圖（Interaction Diagrams）

序列圖（Sequence Diagram）：展示物件間的時間順序互動
協作圖（Collaboration Diagram）：展示物件間的協作關係
時序圖（Timing Diagram）：展示物件在時間軸上的狀態變化

類別圖關係詳解

1. 依賴關係（Dependency）

符號： 虛線箭頭 A -----> B

意義： A 類別使用 B 類別，通常是臨時性的使用關係，如方法參數、局部變數或靜態方法調用。

Java 實現範例：

// 依賴關係示例
public class OrderService {
    
    // 方法參數依賴
    public void processOrder(Order order, PaymentProcessor processor) {
        // OrderService 依賴 PaymentProcessor
        processor.processPayment(order.getAmount());
    }
    
    // 靜態方法依賴
    public void validateOrder(Order order) {
        // OrderService 依賴 OrderValidator
        if (!OrderValidator.validate(order)) {
            throw new ValidationException("無效的訂單");
        }
    }
    
    // 局部變數依賴
    public void sendNotification(Order order) {
        // OrderService 依賴 EmailService
        EmailService emailService = new EmailService();
        emailService.sendOrderConfirmation(order);
    }
}

// 被依賴的類
public class PaymentProcessor {
    public void processPayment(BigDecimal amount) {
        // 處理付款邏輯
    }
}

public class OrderValidator {
    public static boolean validate(Order order) {
        return order != null && order.getAmount() != null;
    }
}

public class EmailService {
    public void sendOrderConfirmation(Order order) {
        // 發送確認郵件
    }
}

2. 關聯關係（Association）

符號： 實線箭頭 A -----> B

SOLID 設計原則完整指南：物件導向程式設計的五大核心原則

Thu, 08 Jul 2021 21:20:39 +0800

概述

SOLID 是物件導向程式設計和軟體架構設計中五個核心設計原則的縮寫，由 Robert C. Martin（Uncle Bob）在 21 世紀初期提出。這些原則旨在讓軟體設計更加容易理解、靈活且可維護。

SOLID 原則不僅適用於物件導向程式設計，也是現代軟體架構的基石，從微服務設計到 Clean Architecture 都深受其影響。

SOLID 原則概覽

首字母	英文原則名稱	中文名稱	核心概念
S	Single Responsibility Principle	單一職責原則	一個類別應該只有一個改變的理由
O	Open/Closed Principle	開閉原則	對擴展開放，對修改封閉
L	Liskov Substitution Principle	里氏替換原則	子類別應該能完全替換父類別
I	Interface Segregation Principle	介面隔離原則	客戶端不應該依賴它不需要的介面
D	Dependency Inversion Principle	依賴反轉原則	依賴於抽象而非具體實作

1. Single Responsibility Principle (SRP) - 單一職責原則

定義

一個類別應該只有一個引起它變化的原因

核心概念

高內聚性：類別內部的方法和屬性應該為同一個目標服務
低耦合性：減少類別之間的依賴關係
明確責任：每個類別都應該有明確且單一的職責

違反 SRP 的範例

// ❌ 違反 SRP：一個類別承擔多種職責
public class User {
    private String name;
    private String email;
    
    // 用戶資料驗證職責
    public boolean validateEmail(String email) {
        return email.contains("@") && email.contains(".");
    }
    
    // 用戶持久化職責
    public void saveToDatabase() {
        // 資料庫存儲邏輯
        System.out.println("儲存用戶到資料庫");
    }
    
    // 用戶通知職責
    public void sendWelcomeEmail() {
        // 郵件發送邏輯
        System.out.println("發送歡迎郵件");
    }
    
    // 用戶報表職責
    public String generateUserReport() {
        return "用戶報表: " + name + " - " + email;
    }
}

遵循 SRP 的重構範例

// ✅ 遵循 SRP：職責分離
// 1. 用戶實體類別（僅負責用戶資料）
public class User {
    private String name;
    private String email;
    
    public User(String name, String email) {
        this.name = name;
        this.email = email;
    }
    
    // Getter and Setter methods
    public String getName() { return name; }
    public String getEmail() { return email; }
    public void setName(String name) { this.name = name; }
    public void setEmail(String email) { this.email = email; }
}

// 2. 用戶驗證服務（僅負責驗證邏輯）
@Service
public class UserValidator {
    
    public boolean validateEmail(String email) {
        return email != null && 
               email.contains("@") && 
               email.contains(".") &&
               email.length() > 5;
    }
    
    public boolean validateName(String name) {
        return name != null && 
               name.trim().length() > 0 && 
               name.length() <= 50;
    }
    
    public ValidationResult validateUser(User user) {
        ValidationResult result = new ValidationResult();
        
        if (!validateName(user.getName())) {
            result.addError("用戶名格式無效");
        }
        
        if (!validateEmail(user.getEmail())) {
            result.addError("郵箱格式無效");
        }
        
        return result;
    }
}

// 3. 用戶持久化服務（僅負責資料存取）
@Repository
public class UserRepository {
    
    public void save(User user) {
        // 資料庫存儲邏輯
        System.out.println("儲存用戶到資料庫: " + user.getName());
    }
    
    public User findByEmail(String email) {
        // 查詢邏輯
        return new User("找到的用戶", email);
    }
    
    public List<User> findAll() {
        // 查詢所有用戶
        return Arrays.asList(new User("用戶1", "user1@example.com"));
    }
}

// 4. 用戶通知服務（僅負責通知邏輯）
@Service
public class UserNotificationService {
    
    public void sendWelcomeEmail(User user) {
        System.out.println("發送歡迎郵件給: " + user.getEmail());
    }
    
    public void sendPasswordResetEmail(User user) {
        System.out.println("發送密碼重設郵件給: " + user.getEmail());
    }
    
    public void sendAccountActivationEmail(User user) {
        System.out.println("發送帳戶啟用郵件給: " + user.getEmail());
    }
}

// 5. 用戶報表服務（僅負責報表生成）
@Service
public class UserReportService {
    
    public String generateUserReport(User user) {
        return String.format("用戶報表\n姓名: %s\n郵箱: %s\n生成時間: %s", 
                           user.getName(), 
                           user.getEmail(), 
                           LocalDateTime.now());
    }
    
    public String generateUsersListReport(List<User> users) {
        StringBuilder report = new StringBuilder("用戶列表報表\n");
        users.forEach(user -> 
            report.append(String.format("- %s (%s)\n", user.getName(), user.getEmail()))
        );
        return report.toString();
    }
}

// 6. 用戶服務協調器（組合各種服務）
@Service
public class UserService {
    
    private final UserValidator userValidator;
    private final UserRepository userRepository;
    private final UserNotificationService notificationService;
    
    public UserService(UserValidator userValidator, 
                      UserRepository userRepository,
                      UserNotificationService notificationService) {
        this.userValidator = userValidator;
        this.userRepository = userRepository;
        this.notificationService = notificationService;
    }
    
    public Result<User> createUser(String name, String email) {
        User user = new User(name, email);
        
        // 驗證用戶資料
        ValidationResult validation = userValidator.validateUser(user);
        if (!validation.isValid()) {
            return Result.failure("驗證失敗: " + validation.getErrors());
        }
        
        // 儲存用戶
        userRepository.save(user);
        
        // 發送歡迎郵件
        notificationService.sendWelcomeEmail(user);
        
        return Result.success(user);
    }
}

SRP 的好處

降低複雜度：每個類別的責任明確，易於理解
提高可讀性：程式碼結構清晰，功能劃分明確
增強可維護性：修改某個功能時，只需要關注特定的類別
提升可測試性：職責單一的類別更容易進行單元測試
促進重用性：功能獨立的類別可以在不同場景中重複使用

2. Open/Closed Principle (OCP) - 開閉原則

定義

軟體實體（類別、模組、函數等）應該對擴展開放，對修改封閉

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 是一種強大的架構模式，特別適用於：