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。

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

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

Side Project 企業級專案配置指南：完整開發環境設定與最佳實踐

Wed, 01 Jan 2020 20:31:25 +0800

Side Project 企業級專案配置指南

簡介

在現代軟體開發中，一個良好的專案配置是成功的關鍵。本文將深入介紹如何從零開始建立一個企業級的 Side Project，包含完整的開發環境設定、專案結構規劃、依賴管理、容器化部署、監控系統與 CI/CD 流程。

專案結構規劃

標準 Maven 專案結構

project-root/
├── src/
│   ├── main/
│   │   ├── java/
│   │   │   └── com/
│   │   │       └── company/
│   │   │           └── project/
│   │   │               ├── Application.java
│   │   │               ├── config/
│   │   │               │   ├── AppConfig.java
│   │   │               │   ├── SecurityConfig.java
│   │   │               │   └── DatabaseConfig.java
│   │   │               ├── controller/
│   │   │               ├── service/
│   │   │               │   ├── impl/
│   │   │               │   └── dto/
│   │   │               ├── repository/
│   │   │               ├── entity/
│   │   │               ├── exception/
│   │   │               └── util/
│   │   └── resources/
│   │       ├── application.yml
│   │       ├── application-dev.yml
│   │       ├── application-prod.yml
│   │       ├── logback-spring.xml
│   │       ├── banner.txt
│   │       └── db/
│   │           └── migration/
│   └── test/
│       ├── java/
│       │   └── com/
│       │       └── company/
│       │           └── project/
│       │               ├── integration/
│       │               ├── unit/
│       │               └── TestApplication.java
│       └── resources/
│           └── application-test.yml
├── docker/
│   ├── Dockerfile
│   ├── docker-compose.yml
│   └── docker-compose.prod.yml
├── .github/
│   └── workflows/
│       ├── ci.yml
│       └── cd.yml
├── docs/
│   ├── api/
│   └── setup/
├── scripts/
│   ├── build.sh
│   ├── deploy.sh
│   └── setup.sh
├── pom.xml
├── README.md
└── .gitignore

核心依賴管理

完整的 Maven 依賴配置

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 
         http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>3.1.5</version>
        <relativePath/>
    </parent>

    <groupId>com.company</groupId>
    <artifactId>side-project</artifactId>
    <version>1.0.0</version>
    <name>Side Project</name>
    <description>Enterprise Side Project Configuration</description>
    <packaging>jar</packaging>

    <properties>
        <java.version>17</java.version>
        <maven.compiler.source>17</maven.compiler.source>
        <maven.compiler.target>17</maven.compiler.target>
        <spring-cloud.version>2022.0.4</spring-cloud.version>
        <springdoc.version>2.2.0</springdoc.version>
        <mapstruct.version>1.5.5.Final</mapstruct.version>
        <testcontainers.version>1.19.0</testcontainers.version>
        <jackson.version>2.15.2</jackson.version>
        <guava.version>32.1.2-jre</guava.version>
        <commons-lang3.version>3.13.0</commons-lang3.version>
        <liquibase.version>4.23.2</liquibase.version>
    </properties>

    <dependencies>
        <!-- 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-data-jpa</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-validation</artifactId>
        </dependency>
        
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-cache</artifactId>
        </dependency>
        
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-data-redis</artifactId>
        </dependency>
        
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-actuator</artifactId>
        </dependency>
        
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-aop</artifactId>
        </dependency>

        <!-- Database -->
        <dependency>
            <!-- Spring Boot 3 / MySQL 8.0.31+ 請改用新 artifact -->
            <groupId>com.mysql</groupId>
            <artifactId>mysql-connector-j</artifactId>
            <version>8.3.0</version>
        </dependency>
        
        <dependency>
            <groupId>com.h2database</groupId>
            <artifactId>h2</artifactId>
            <scope>test</scope>
        </dependency>
        
        <!-- Database Migration -->
        <dependency>
            <groupId>org.liquibase</groupId>
            <artifactId>liquibase-core</artifactId>
            <version>${liquibase.version}</version>
        </dependency>

        <!-- Documentation -->
        <dependency>
            <groupId>org.springdoc</groupId>
            <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
            <version>${springdoc.version}</version>
        </dependency>

        <!-- JSON Processing -->
        <dependency>
            <groupId>com.fasterxml.jackson.core</groupId>
            <artifactId>jackson-core</artifactId>
            <version>${jackson.version}</version>
        </dependency>
        
        <dependency>
            <groupId>com.fasterxml.jackson.core</groupId>
            <artifactId>jackson-databind</artifactId>
            <version>${jackson.version}</version>
        </dependency>
        
        <dependency>
            <groupId>com.fasterxml.jackson.datatype</groupId>
            <artifactId>jackson-datatype-jsr310</artifactId>
            <version>${jackson.version}</version>
        </dependency>

        <!-- Utilities -->
        <dependency>
            <groupId>org.apache.commons</groupId>
            <artifactId>commons-lang3</artifactId>
            <version>${commons-lang3.version}</version>
        </dependency>
        
        <dependency>
            <groupId>com.google.guava</groupId>
            <artifactId>guava</artifactId>
            <version>${guava.version}</version>
        </dependency>

        <!-- Mapping -->
        <dependency>
            <groupId>org.mapstruct</groupId>
            <artifactId>mapstruct</artifactId>
            <version>${mapstruct.version}</version>
        </dependency>

        <!-- Lombok -->
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <optional>true</optional>
        </dependency>

        <!-- Monitoring -->
        <dependency>
            <groupId>io.micrometer</groupId>
            <artifactId>micrometer-registry-prometheus</artifactId>
        </dependency>
        
        <dependency>
            <groupId>net.logstash.logback</groupId>
            <artifactId>logstash-logback-encoder</artifactId>
            <version>7.4</version>
        </dependency>

        <!-- JWT -->
        <dependency>
            <groupId>io.jsonwebtoken</groupId>
            <artifactId>jjwt-api</artifactId>
            <version>0.11.5</version>
        </dependency>
        
        <dependency>
            <groupId>io.jsonwebtoken</groupId>
            <artifactId>jjwt-impl</artifactId>
            <version>0.11.5</version>
            <scope>runtime</scope>
        </dependency>
        
        <dependency>
            <groupId>io.jsonwebtoken</groupId>
            <artifactId>jjwt-jackson</artifactId>
            <version>0.11.5</version>
            <scope>runtime</scope>
        </dependency>

        <!-- Test Dependencies -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
        
        <dependency>
            <groupId>org.springframework.security</groupId>
            <artifactId>spring-security-test</artifactId>
            <scope>test</scope>
        </dependency>
        
        <dependency>
            <groupId>org.testcontainers</groupId>
            <artifactId>junit-jupiter</artifactId>
            <version>${testcontainers.version}</version>
            <scope>test</scope>
        </dependency>
        
        <dependency>
            <groupId>org.testcontainers</groupId>
            <artifactId>mysql</artifactId>
            <version>${testcontainers.version}</version>
            <scope>test</scope>
        </dependency>
        
        <dependency>
            <groupId>org.testcontainers</groupId>
            <artifactId>redis</artifactId>
            <version>${testcontainers.version}</version>
            <scope>test</scope>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
                <configuration>
                    <excludes>
                        <exclude>
                            <groupId>org.projectlombok</groupId>
                            <artifactId>lombok</artifactId>
                        </exclude>
                    </excludes>
                </configuration>
            </plugin>
            
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>3.11.0</version>
                <configuration>
                    <source>17</source>
                    <target>17</target>
                    <annotationProcessorPaths>
                        <path>
                            <groupId>org.mapstruct</groupId>
                            <artifactId>mapstruct-processor</artifactId>
                            <version>${mapstruct.version}</version>
                        </path>
                        <path>
                            <groupId>org.projectlombok</groupId>
                            <artifactId>lombok</artifactId>
                            <version>${lombok.version}</version>
                        </path>
                        <path>
                            <groupId>org.projectlombok</groupId>
                            <artifactId>lombok-mapstruct-binding</artifactId>
                            <version>0.2.0</version>
                        </path>
                    </annotationProcessorPaths>
                </configuration>
            </plugin>
            
            <plugin>
                <groupId>org.liquibase</groupId>
                <artifactId>liquibase-maven-plugin</artifactId>
                <version>${liquibase.version}</version>
                <configuration>
                    <propertyFile>src/main/resources/liquibase.properties</propertyFile>
                </configuration>
            </plugin>
            
            <plugin>
                <groupId>org.jacoco</groupId>
                <artifactId>jacoco-maven-plugin</artifactId>
                <version>0.8.10</version>
                <executions>
                    <execution>
                        <goals>
                            <goal>prepare-agent</goal>
                        </goals>
                    </execution>
                    <execution>
                        <id>report</id>
                        <phase>test</phase>
                        <goals>
                            <goal>report</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>
            
            <plugin>
                <groupId>com.google.cloud.tools</groupId>
                <artifactId>jib-maven-plugin</artifactId>
                <version>3.3.2</version>
                <configuration>
                    <from>
                        <image>eclipse-temurin:17-jre-alpine</image>
                    </from>
                    <to>
                        <image>your-registry/side-project:${project.version}</image>
                    </to>
                    <container>
                        <jvmFlags>
                            <jvmFlag>-Xms512m</jvmFlag>
                            <jvmFlag>-Xmx2g</jvmFlag>
                        </jvmFlags>
                        <mainClass>com.company.project.Application</mainClass>
                        <ports>
                            <port>8080</port>
                        </ports>
                    </container>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>

應用程式配置

主要配置檔案 - application.yml

# 應用程式配置
spring:
  application:
    name: side-project
  
  profiles:
    active: ${SPRING_PROFILES_ACTIVE:dev}
  
  # 資料庫配置
  datasource:
    url: jdbc:mysql://${DB_HOST:localhost}:${DB_PORT:3306}/${DB_NAME:side_project}?useSSL=false&serverTimezone=Asia/Taipei&allowPublicKeyRetrieval=true
    username: ${DB_USERNAME:root}
    password: ${DB_PASSWORD:password}
    driver-class-name: com.mysql.cj.jdbc.Driver
    hikari:
      minimum-idle: 5
      maximum-pool-size: 20
      idle-timeout: 30000
      connection-timeout: 30000
      max-lifetime: 1800000
      pool-name: HikariCP
  
  # JPA 配置
  jpa:
    hibernate:
      ddl-auto: validate
    show-sql: false
    properties:
      hibernate:
        dialect: org.hibernate.dialect.MySQL8Dialect
        format_sql: true
        use_sql_comments: true
        jdbc:
          batch_size: 25
          order_inserts: true
          order_updates: true
        connection:
          provider_disables_autocommit: true
        query:
          in_clause_parameter_padding: true
        cache:
          use_second_level_cache: true
          use_query_cache: true
          region:
            factory_class: org.hibernate.cache.jcache.JCacheRegionFactory
  
  # Redis 配置
  redis:
    host: ${REDIS_HOST:localhost}
    port: ${REDIS_PORT:6379}
    password: ${REDIS_PASSWORD:}
    database: 0
    timeout: 10000ms
    lettuce:
      pool:
        max-active: 200
        max-idle: 20
        min-idle: 5
        max-wait: 10000ms
  
  # Cache 配置
  cache:
    type: redis
    redis:
      time-to-live: 600000
      cache-null-values: false
  
  # Security 配置
  security:
    oauth2:
      client:
        registration:
          google:
            client-id: ${GOOGLE_CLIENT_ID:your-google-client-id}
            client-secret: ${GOOGLE_CLIENT_SECRET:your-google-client-secret}
            scope: openid,profile,email
  
  # Liquibase 配置
  liquibase:
    change-log: classpath:db/changelog/db.changelog-master.xml
    enabled: true
  
  # Jackson 配置
  jackson:
    serialization:
      write-dates-as-timestamps: false
      indent-output: true
    deserialization:
      fail-on-unknown-properties: false
    time-zone: Asia/Taipei
    default-property-inclusion: non_null

# 服務器配置
server:
  port: ${SERVER_PORT:8080}
  servlet:
    context-path: /api
  compression:
    enabled: true
    mime-types: text/html,text/xml,text/plain,text/css,text/javascript,application/javascript,application/json
    min-response-size: 1024
  error:
    include-stacktrace: never
    include-message: always

# 日誌配置
logging:
  level:
    root: INFO
    com.company.project: DEBUG
    org.springframework.security: DEBUG
    org.hibernate.SQL: DEBUG
    org.hibernate.type.descriptor.sql.BasicBinder: TRACE
  pattern:
    console: "%d{yyyy-MM-dd HH:mm:ss} [%thread] %-5level %logger{36} - %msg%n"
    file: "%d{yyyy-MM-dd HH:mm:ss} [%thread] %-5level %logger{36} - %msg%n"
  file:
    name: logs/application.log
  logback:
    rollingpolicy:
      max-file-size: 10MB
      max-history: 30

# 管理端點配置
management:
  endpoints:
    web:
      exposure:
        include: health,info,metrics,prometheus,liquibase,caches
  endpoint:
    health:
      show-details: always
  health:
    redis:
      enabled: true
    db:
      enabled: true
  metrics:
    export:
      prometheus:
        enabled: true
    tags:
      application: ${spring.application.name}
      environment: ${spring.profiles.active}

# SpringDoc 配置
springdoc:
  api-docs:
    path: /api-docs
  swagger-ui:
    path: /swagger-ui.html
    operations-sorter: method
    tags-sorter: alpha
  packages-to-scan: com.company.project.controller

# 應用程式自訂配置
app:
  jwt:
    secret: ${JWT_SECRET:your-secret-key-must-be-at-least-256-bits}
    expiration: ${JWT_EXPIRATION:86400000} # 24 hours
    refresh-expiration: ${JWT_REFRESH_EXPIRATION:604800000} # 7 days
  
  cors:
    allowed-origins: ${CORS_ALLOWED_ORIGINS:http://localhost:3000,http://localhost:8080}
    allowed-methods: ${CORS_ALLOWED_METHODS:GET,POST,PUT,DELETE,OPTIONS}
    allowed-headers: ${CORS_ALLOWED_HEADERS:*}
    allow-credentials: true
  
  rate-limit:
    enabled: true
    requests-per-minute: 60
    burst-capacity: 100
  
  file-storage:
    upload-dir: ${FILE_UPLOAD_DIR:uploads/}
    max-file-size: ${MAX_FILE_SIZE:10MB}
    allowed-extensions: ${ALLOWED_EXTENSIONS:jpg,jpeg,png,gif,pdf,docx,xlsx}

開發環境配置 - application-dev.yml

spring:
  datasource:
    url: jdbc:mysql://localhost:3306/side_project_dev?useSSL=false&serverTimezone=Asia/Taipei
    username: root
    password: mysql
  
  jpa:
    hibernate:
      ddl-auto: update
    show-sql: true
  
  redis:
    host: localhost
    port: 6379
  
  liquibase:
    enabled: false

logging:
  level:
    root: DEBUG
    com.company.project: DEBUG
    org.springframework.web: DEBUG
    org.springframework.security: DEBUG

management:
  endpoints:
    web:
      exposure:
        include: "*"

app:
  jwt:
    secret: dev-secret-key-for-development-only-not-for-production
    expiration: 86400000
  
  cors:
    allowed-origins: "http://localhost:3000,http://localhost:8080"

生產環境配置 - application-prod.yml

spring:
  datasource:
    url: jdbc:mysql://${DB_HOST}:${DB_PORT}/${DB_NAME}?useSSL=true&serverTimezone=Asia/Taipei
    username: ${DB_USERNAME}
    password: ${DB_PASSWORD}
    hikari:
      minimum-idle: 10
      maximum-pool-size: 50
      idle-timeout: 60000
      connection-timeout: 30000
      max-lifetime: 1800000
  
  jpa:
    hibernate:
      ddl-auto: validate
    show-sql: false
  
  redis:
    host: ${REDIS_HOST}
    port: ${REDIS_PORT}
    password: ${REDIS_PASSWORD}
    ssl: true
  
  liquibase:
    enabled: true

logging:
  level:
    root: WARN
    com.company.project: INFO
  file:
    name: /var/log/side-project/application.log

management:
  endpoints:
    web:
      exposure:
        include: health,info,metrics,prometheus
  endpoint:
    health:
      show-details: when-authorized

app:
  jwt:
    secret: ${JWT_SECRET}
    expiration: ${JWT_EXPIRATION:3600000}
  
  cors:
    allowed-origins: ${CORS_ALLOWED_ORIGINS}

核心配置類別

主要應用程式配置

package com.company.project.config;

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

@Data
@Configuration
@ConfigurationProperties(prefix = "app")
public class AppProperties {
    
    private Jwt jwt = new Jwt();
    private Cors cors = new Cors();
    private RateLimit rateLimit = new RateLimit();
    private FileStorage fileStorage = new FileStorage();
    
    @Data
    public static class Jwt {
        private String secret;
        private long expiration;
        private long refreshExpiration;
    }
    
    @Data
    public static class Cors {
        private String allowedOrigins;
        private String allowedMethods;
        private String allowedHeaders;
        private boolean allowCredentials;
    }
    
    @Data
    public static class RateLimit {
        private boolean enabled;
        private int requestsPerMinute;
        private int burstCapacity;
    }
    
    @Data
    public static class FileStorage {
        private String uploadDir;
        private String maxFileSize;
        private String allowedExtensions;
    }
}

資料庫配置

package com.company.project.config;

import com.zaxxer.hikari.HikariConfig;
import com.zaxxer.hikari.HikariDataSource;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Primary;
import org.springframework.data.jpa.repository.config.EnableJpaAuditing;
import org.springframework.data.jpa.repository.config.EnableJpaRepositories;
import org.springframework.transaction.annotation.EnableTransactionManagement;

import javax.sql.DataSource;

@Configuration
@EnableJpaRepositories(basePackages = "com.company.project.repository")
@EnableJpaAuditing
@EnableTransactionManagement
public class DatabaseConfig {

    @Bean
    @Primary
    @ConfigurationProperties("spring.datasource.hikari")
    public HikariConfig hikariConfig() {
        return new HikariConfig();
    }

    @Bean
    @Primary
    public DataSource dataSource() {
        return new HikariDataSource(hikariConfig());
    }
}

Redis 配置

package com.company.project.config;

import org.springframework.boot.autoconfigure.data.redis.RedisProperties;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.data.redis.connection.RedisConnectionFactory;
import org.springframework.data.redis.connection.lettuce.LettuceConnectionFactory;
import org.springframework.data.redis.core.RedisTemplate;
import org.springframework.data.redis.serializer.GenericJackson2JsonRedisSerializer;
import org.springframework.data.redis.serializer.StringRedisSerializer;
import org.springframework.cache.annotation.EnableCaching;
import org.springframework.cache.CacheManager;
import org.springframework.data.redis.cache.RedisCacheManager;
import org.springframework.data.redis.cache.RedisCacheConfiguration;

import java.time.Duration;

@Configuration
@EnableCaching
public class RedisConfig {

    @Bean
    public RedisConnectionFactory redisConnectionFactory(RedisProperties redisProperties) {
        return new LettuceConnectionFactory(redisProperties.getHost(), redisProperties.getPort());
    }

    @Bean
    public RedisTemplate<String, Object> redisTemplate(RedisConnectionFactory connectionFactory) {
        RedisTemplate<String, Object> template = new RedisTemplate<>();
        template.setConnectionFactory(connectionFactory);
        
        // 設定序列化器
        template.setKeySerializer(new StringRedisSerializer());
        template.setValueSerializer(new GenericJackson2JsonRedisSerializer());
        template.setHashKeySerializer(new StringRedisSerializer());
        template.setHashValueSerializer(new GenericJackson2JsonRedisSerializer());
        
        template.afterPropertiesSet();
        return template;
    }

    @Bean
    public CacheManager cacheManager(RedisConnectionFactory connectionFactory) {
        RedisCacheConfiguration config = RedisCacheConfiguration.defaultCacheConfig()
                .entryTtl(Duration.ofMinutes(10))
                .serializeKeysWith(org.springframework.data.redis.serializer.RedisSerializationContext.SerializationPair.fromSerializer(new StringRedisSerializer()))
                .serializeValuesWith(org.springframework.data.redis.serializer.RedisSerializationContext.SerializationPair.fromSerializer(new GenericJackson2JsonRedisSerializer()));

        return RedisCacheManager.builder(connectionFactory)
                .cacheDefaults(config)
                .build();
    }
}

安全配置

package com.company.project.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
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
public class SecurityConfig {

    private final AppProperties appProperties;
    private final JwtAuthenticationFilter jwtAuthenticationFilter;

    public SecurityConfig(AppProperties appProperties, JwtAuthenticationFilter jwtAuthenticationFilter) {
        this.appProperties = appProperties;
        this.jwtAuthenticationFilter = jwtAuthenticationFilter;
    }

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http.csrf(csrf -> csrf.disable())
            .cors(cors -> cors.configurationSource(corsConfigurationSource()))
            .sessionManagement(session -> session.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
            .authorizeHttpRequests(authz -> authz
                .requestMatchers("/api/auth/**", "/api/public/**").permitAll()
                .requestMatchers("/api-docs/**", "/swagger-ui/**", "/swagger-ui.html").permitAll()
                .requestMatchers("/actuator/health", "/actuator/info").permitAll()
                .anyRequest().authenticated()
            )
            .addFilterBefore(jwtAuthenticationFilter, UsernamePasswordAuthenticationFilter.class);

        return http.build();
    }

    @Bean
    public PasswordEncoder passwordEncoder() {
        return new BCryptPasswordEncoder();
    }

    @Bean
    public CorsConfigurationSource corsConfigurationSource() {
        CorsConfiguration configuration = new CorsConfiguration();
        configuration.setAllowedOrigins(Arrays.asList(appProperties.getCors().getAllowedOrigins().split(",")));
        configuration.setAllowedMethods(Arrays.asList(appProperties.getCors().getAllowedMethods().split(",")));
        configuration.setAllowedHeaders(Arrays.asList(appProperties.getCors().getAllowedHeaders().split(",")));
        configuration.setAllowCredentials(appProperties.getCors().isAllowCredentials());
        
        UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource();
        source.registerCorsConfiguration("/**", configuration);
        return source;
    }
}

OpenAPI 配置

package com.company.project.config;

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.info.Contact;
import io.swagger.v3.oas.models.info.License;
import io.swagger.v3.oas.models.security.SecurityRequirement;
import io.swagger.v3.oas.models.security.SecurityScheme;
import io.swagger.v3.oas.models.Components;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class OpenApiConfig {

    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("Side Project API")
                        .version("1.0.0")
                        .description("Enterprise Side Project API Documentation")
                        .contact(new Contact()
                                .name("Bill Lin")
                                .email("bill@example.com")
                                .url("https://github.com/yourhandle"))
                        .license(new License()
                                .name("MIT License")
                                .url("https://opensource.org/licenses/MIT")))
                .addSecurityItem(new SecurityRequirement().addList("Bearer Authentication"))
                .components(new Components()
                        .addSecuritySchemes("Bearer Authentication",
                                new SecurityScheme()
                                        .type(SecurityScheme.Type.HTTP)
                                        .scheme("bearer")
                                        .bearerFormat("JWT")));
    }
}

容器化配置

Dockerfile

# Multi-stage build
FROM eclipse-temurin:17-jdk-alpine AS builder

WORKDIR /app
COPY pom.xml .
COPY src ./src

RUN ./mvnw clean package -DskipTests

FROM eclipse-temurin:17-jre-alpine

# 建立非 root 使用者
RUN addgroup -g 1001 -S appgroup && \
    adduser -u 1001 -S appuser -G appgroup

WORKDIR /app

# 複製 JAR 檔案
COPY --from=builder /app/target/*.jar app.jar

# 建立必要目錄
RUN mkdir -p /app/logs /app/uploads && \
    chown -R appuser:appgroup /app

# 切換到非 root 使用者
USER appuser

# 健康檢查
HEALTHCHECK --interval=30s --timeout=10s --start-period=30s --retries=3 \
  CMD curl -f http://localhost:8080/actuator/health || exit 1

# 暴露埠號
EXPOSE 8080

# JVM 調優參數
ENV JAVA_OPTS="-Xms512m -Xmx2g -XX:+UseG1GC -XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=/app/logs/"

# 啟動應用程式
ENTRYPOINT ["sh", "-c", "java $JAVA_OPTS -jar app.jar"]

docker-compose.yml

version: '3.8'

services:
  app:
    build: .
    ports:
      - "8080:8080"
    environment:
      - SPRING_PROFILES_ACTIVE=docker
      - DB_HOST=mysql
      - DB_PORT=3306
      - DB_NAME=side_project
      - DB_USERNAME=root
      - DB_PASSWORD=mysql
      - REDIS_HOST=redis
      - REDIS_PORT=6379
    depends_on:
      - mysql
      - redis
    volumes:
      - ./logs:/app/logs
      - ./uploads:/app/uploads
    networks:
      - app-network
    restart: unless-stopped

  mysql:
    image: mysql:8.0
    environment:
      - MYSQL_ROOT_PASSWORD=mysql
      - MYSQL_DATABASE=side_project
      - MYSQL_USER=app
      - MYSQL_PASSWORD=app
    ports:
      - "3306:3306"
    volumes:
      - mysql_data:/var/lib/mysql
      - ./docker/mysql/init.sql:/docker-entrypoint-initdb.d/init.sql
    networks:
      - app-network
    restart: unless-stopped

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"
    volumes:
      - redis_data:/data
    networks:
      - app-network
    restart: unless-stopped

  prometheus:
    image: prom/prometheus:latest
    ports:
      - "9090:9090"
    volumes:
      - ./docker/prometheus/prometheus.yml:/etc/prometheus/prometheus.yml
    networks:
      - app-network
    restart: unless-stopped

  grafana:
    image: grafana/grafana:latest
    ports:
      - "3000:3000"
    environment:
      - GF_SECURITY_ADMIN_PASSWORD=admin
    volumes:
      - grafana_data:/var/lib/grafana
      - ./docker/grafana/dashboards:/etc/grafana/provisioning/dashboards
      - ./docker/grafana/datasources:/etc/grafana/provisioning/datasources
    networks:
      - app-network
    restart: unless-stopped

  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./docker/nginx/nginx.conf:/etc/nginx/nginx.conf
      - ./docker/nginx/ssl:/etc/nginx/ssl
    depends_on:
      - app
    networks:
      - app-network
    restart: unless-stopped

volumes:
  mysql_data:
  redis_data:
  grafana_data:

networks:
  app-network:
    driver: bridge

生產環境 docker-compose.prod.yml

version: '3.8'

services:
  app:
    image: your-registry/side-project:latest
    deploy:
      replicas: 3
      resources:
        limits:
          memory: 2G
          cpus: '1'
        reservations:
          memory: 1G
          cpus: '0.5'
      restart_policy:
        condition: on-failure
        delay: 10s
        max_attempts: 3
    environment:
      - SPRING_PROFILES_ACTIVE=prod
      - DB_HOST=mysql-prod
      - DB_PORT=3306
      - DB_NAME=side_project_prod
      - DB_USERNAME=${DB_USERNAME}
      - DB_PASSWORD=${DB_PASSWORD}
      - REDIS_HOST=redis-prod
      - REDIS_PORT=6379
      - REDIS_PASSWORD=${REDIS_PASSWORD}
      - JWT_SECRET=${JWT_SECRET}
    secrets:
      - db_password
      - jwt_secret
    networks:
      - app-network
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

  mysql-prod:
    image: mysql:8.0
    environment:
      - MYSQL_ROOT_PASSWORD_FILE=/run/secrets/db_password
      - MYSQL_DATABASE=side_project_prod
    volumes:
      - mysql_prod_data:/var/lib/mysql
    secrets:
      - db_password
    networks:
      - app-network
    deploy:
      resources:
        limits:
          memory: 2G
          cpus: '1'

  redis-prod:
    image: redis:7-alpine
    command: redis-server --requirepass ${REDIS_PASSWORD}
    volumes:
      - redis_prod_data:/data
    networks:
      - app-network
    deploy:
      resources:
        limits:
          memory: 512M
          cpus: '0.5'

secrets:
  db_password:
    external: true
  jwt_secret:
    external: true

volumes:
  mysql_prod_data:
  redis_prod_data:

networks:
  app-network:
    driver: overlay

監控配置

logback-spring.xml

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
    <include resource="org/springframework/boot/logging/logback/defaults.xml"/>
    
    <springProfile name="!prod">
        <include resource="org/springframework/boot/logging/logback/console-appender.xml"/>
        <root level="INFO">
            <appender-ref ref="CONSOLE"/>
        </root>
    </springProfile>
    
    <springProfile name="prod">
        <appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
            <file>/var/log/side-project/application.log</file>
            <encoder class="net.logstash.logback.encoder.LoggingEventCompositeJsonEncoder">
                <providers>
                    <timestamp/>
                    <logLevel/>
                    <loggerName/>
                    <mdc/>
                    <message/>
                    <stackTrace/>
                </providers>
            </encoder>
            <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
                <fileNamePattern>/var/log/side-project/application.%d{yyyy-MM-dd}.%i.log</fileNamePattern>
                <timeBasedFileNamingAndTriggeringPolicy class="ch.qos.logback.core.rolling.SizeAndTimeBasedFNATP">
                    <maxFileSize>100MB</maxFileSize>
                </timeBasedFileNamingAndTriggeringPolicy>
                <maxHistory>30</maxHistory>
                <totalSizeCap>3GB</totalSizeCap>
            </rollingPolicy>
        </appender>
        
        <appender name="METRICS" class="ch.qos.logback.core.rolling.RollingFileAppender">
            <file>/var/log/side-project/metrics.log</file>
            <encoder class="net.logstash.logback.encoder.LoggingEventCompositeJsonEncoder">
                <providers>
                    <timestamp/>
                    <logLevel/>
                    <loggerName/>
                    <mdc/>
                    <message/>
                </providers>
            </encoder>
            <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
                <fileNamePattern>/var/log/side-project/metrics.%d{yyyy-MM-dd}.log</fileNamePattern>
                <maxHistory>7</maxHistory>
            </rollingPolicy>
        </appender>
        
        <logger name="metrics" level="INFO" additivity="false">
            <appender-ref ref="METRICS"/>
        </logger>
        
        <root level="INFO">
            <appender-ref ref="FILE"/>
        </root>
    </springProfile>
</configuration>

Prometheus 配置

# docker/prometheus/prometheus.yml
global:
  scrape_interval: 15s
  evaluation_interval: 15s

scrape_configs:
  - job_name: 'side-project'
    static_configs:
      - targets: ['app:8080']
    metrics_path: '/actuator/prometheus'
    scrape_interval: 10s
    
  - job_name: 'mysql'
    static_configs:
      - targets: ['mysql:3306']
    
  - job_name: 'redis'
    static_configs:
      - targets: ['redis:6379']

CI/CD 配置

GitHub Actions - CI

# .github/workflows/ci.yml
name: CI

on:
  push:
    branches: [ main, develop ]
  pull_request:
    branches: [ main ]

jobs:
  test:
    runs-on: ubuntu-latest
    
    services:
      mysql:
        image: mysql:8.0
        env:
          MYSQL_ROOT_PASSWORD: mysql
          MYSQL_DATABASE: side_project_test
        ports:
          - 3306:3306
        options: >-
          --health-cmd="mysqladmin ping"
          --health-interval=10s
          --health-timeout=5s
          --health-retries=3
      
      redis:
        image: redis:7-alpine
        ports:
          - 6379:6379
        options: >-
          --health-cmd="redis-cli ping"
          --health-interval=10s
          --health-timeout=5s
          --health-retries=3
    
    steps:
    - uses: actions/checkout@v3
    
    - name: Set up JDK 17
      uses: actions/setup-java@v3
      with:
        java-version: '17'
        distribution: 'temurin'
    
    - name: Cache Maven dependencies
      uses: actions/cache@v3
      with:
        path: ~/.m2
        key: ${{ runner.os }}-m2-${{ hashFiles('**/pom.xml') }}
        restore-keys: ${{ runner.os }}-m2
    
    - name: Run tests
      run: mvn clean test
      env:
        SPRING_PROFILES_ACTIVE: test
        DB_HOST: localhost
        DB_PORT: 3306
        DB_NAME: side_project_test
        DB_USERNAME: root
        DB_PASSWORD: mysql
        REDIS_HOST: localhost
        REDIS_PORT: 6379
    
    - name: Generate test report
      uses: dorny/test-reporter@v1
      if: success() || failure()
      with:
        name: Maven Tests
        path: target/surefire-reports/*.xml
        reporter: java-junit
    
    - name: Upload coverage to Codecov
      uses: codecov/codecov-action@v3
      with:
        file: ./target/site/jacoco/jacoco.xml
    
    - name: SonarCloud Scan
      uses: SonarSource/sonarcloud-github-action@master
      env:
        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}

GitHub Actions - CD

# .github/workflows/cd.yml
name: CD

on:
  push:
    branches: [ main ]
    tags: [ 'v*' ]

jobs:
  deploy:
    runs-on: ubuntu-latest
    if: github.ref == 'refs/heads/main'
    
    steps:
    - uses: actions/checkout@v3
    
    - name: Set up JDK 17
      uses: actions/setup-java@v3
      with:
        java-version: '17'
        distribution: 'temurin'
    
    - name: Build with Maven
      run: mvn clean package -DskipTests
    
    - name: Build Docker image
      run: |
        docker build -t ${{ secrets.REGISTRY_URL }}/side-project:${{ github.sha }} .
        docker tag ${{ secrets.REGISTRY_URL }}/side-project:${{ github.sha }} ${{ secrets.REGISTRY_URL }}/side-project:latest
    
    - name: Login to Container Registry
      uses: docker/login-action@v2
      with:
        registry: ${{ secrets.REGISTRY_URL }}
        username: ${{ secrets.REGISTRY_USERNAME }}
        password: ${{ secrets.REGISTRY_PASSWORD }}
    
    - name: Push Docker image
      run: |
        docker push ${{ secrets.REGISTRY_URL }}/side-project:${{ github.sha }}
        docker push ${{ secrets.REGISTRY_URL }}/side-project:latest
    
    - name: Deploy to production
      uses: appleboy/ssh-action@v0.1.5
      with:
        host: ${{ secrets.HOST }}
        username: ${{ secrets.USERNAME }}
        key: ${{ secrets.SSH_KEY }}
        script: |
          cd /opt/side-project
          docker-compose pull
          docker-compose up -d
          docker system prune -f

部署腳本

建構腳本 - scripts/build.sh

#!/bin/bash

# 建構腳本
set -e

echo "開始建構 Side Project..."

# 清理舊的建構檔案
echo "清理舊的建構檔案..."
mvn clean

# 執行測試
echo "執行測試..."
mvn test

# 建構應用程式
echo "建構應用程式..."
mvn package -DskipTests

# 建構 Docker 映像
echo "建構 Docker 映像..."
docker build -t side-project:latest .

echo "建構完成！"

部署腳本 - scripts/deploy.sh

#!/bin/bash

# 部署腳本
set -e

ENVIRONMENT=${1:-dev}
VERSION=${2:-latest}

echo "部署 Side Project 到 $ENVIRONMENT 環境..."

case $ENVIRONMENT in
    "dev")
        echo "部署到開發環境..."
        docker-compose -f docker-compose.yml up -d
        ;;
    "staging")
        echo "部署到測試環境..."
        docker-compose -f docker-compose.staging.yml up -d
        ;;
    "prod")
        echo "部署到生產環境..."
        docker-compose -f docker-compose.prod.yml up -d
        ;;
    *)
        echo "未知環境: $ENVIRONMENT"
        exit 1
        ;;
esac

echo "部署完成！"
echo "健康檢查中..."
sleep 30

# 健康檢查
for i in {1..5}; do
    if curl -f http://localhost:8080/actuator/health > /dev/null 2>&1; then
        echo "應用程式健康狀態正常"
        break
    else
        echo "健康檢查失敗，重試中... ($i/5)"
        sleep 10
    fi
done

resources/banner.txt

   _____ _     _        _____           _           _   
  / ____(_)   | |      |  __ \         (_)         | |  
 | (___  _  __| | ___  | |__) |____ ___ _  ___  ___| |_ 
  \___ \| |/ _` |/ _ \ |  ___/ '__/ _ \ |/ _ \/ __| __|
  ____) | | (_| |  __/ | |   | | | (_) | |  __/ (__| |_ 
 |_____/|_|\__,_|\___| |_|   |_|  \___/| |\___|\___|\__|
                                      _/ |              
                                     |__/               

:: Spring Boot :: (v3.1.5)
:: Application Version :: 1.0.0
:: Environment :: ${spring.profiles.active}
:: Port :: ${server.port}

最佳實踐與建議

1. 安全性最佳實踐

# 生產環境安全配置
security:
  headers:
    frame-options: DENY
    content-type-options: nosniff
    xss-protection: 1; mode=block
    referrer-policy: strict-origin-when-cross-origin
  
  ssl:
    enabled: true
    key-store: /etc/ssl/keystore.p12
    key-store-password: ${SSL_KEYSTORE_PASSWORD}
    key-store-type: PKCS12

2. 效能優化配置

# JVM 調優
JAVA_OPTS: >
  -server
  -Xms1g
  -Xmx2g
  -XX:+UseG1GC
  -XX:MaxGCPauseMillis=200
  -XX:+UseStringDeduplication
  -XX:+HeapDumpOnOutOfMemoryError
  -XX:HeapDumpPath=/var/log/side-project/
  -Dspring.profiles.active=prod

3. 監控與告警

# 自訂監控指標
management:
  metrics:
    export:
      prometheus:
        enabled: true
      cloudwatch:
        enabled: true
        namespace: SideProject
        step: 1m
    distribution:
      percentiles:
        http.server.requests: 0.5, 0.95, 0.99
        spring.data.repository.invocations: 0.5, 0.95, 0.99

4. 資料庫優化

# 資料庫連線池優化
spring:
  datasource:
    hikari:
      minimum-idle: 10
      maximum-pool-size: 50
      idle-timeout: 600000
      connection-timeout: 30000
      max-lifetime: 1800000
      leak-detection-threshold: 60000
      connection-test-query: SELECT 1

踩坑紀錄

Spring Boot 3 Jakarta 遷移

Spring Boot 3 需要 Java 17+ 且所有 javax.* → jakarta.*。若從 Boot 2.x 升級，常見的 compile error：

Architecture on Bill.Lin's Notes

Outbox Pattern — 分散式事務一致性

問題：Dual-Write

可能的失敗情境

Outbox Pattern 解法

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

核心概念

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

UML 統一建模語言完整指南

概述

UML 圖形分類

結構圖（Structure Diagrams）

行為圖（Behavior Diagrams）

互動圖（Interaction Diagrams）

類別圖關係詳解

1. 依賴關係（Dependency）

2. 關聯關係（Association）

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

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

模式概述

核心概念

1. CQS 原則基礎

2. CQRS 擴展

傳統 CQRS 實現

1. 基本架構

2. 用戶管理系統示例

3. 事件驅動架構

事件溯源 (Event Sourcing) 整合

1. 事件存儲

2. 聚合根與事件溯源

企業級應用場景

1. 電商系統實現

2. 庫存管理系統

Spring Boot 整合

1. 配置類

2. 控制器實現

3. 測試實現

性能優化與最佳實踐

1. 事件處理優化

2. 讀寫分離優化

監控與診斷

總結

Side Project 企業級專案配置指南：完整開發環境設定與最佳實踐

Side Project 企業級專案配置指南

簡介

專案結構規劃

標準 Maven 專案結構

核心依賴管理

完整的 Maven 依賴配置

應用程式配置

主要配置檔案 - application.yml

開發環境配置 - application-dev.yml

生產環境配置 - application-prod.yml

核心配置類別

主要應用程式配置

資料庫配置

Redis 配置

安全配置

OpenAPI 配置

容器化配置

Dockerfile

docker-compose.yml

生產環境 docker-compose.prod.yml

監控配置

logback-spring.xml

Prometheus 配置

CI/CD 配置

GitHub Actions - CI

GitHub Actions - CD

部署腳本

建構腳本 - scripts/build.sh

部署腳本 - scripts/deploy.sh

自訂 Banner

resources/banner.txt

最佳實踐與建議

1. 安全性最佳實踐

2. 效能優化配置

3. 監控與告警

4. 資料庫優化

踩坑紀錄