Backend on Bill.Lin's Notes

HikariCP 連線池調校

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

為什麼需要連線池

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

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

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

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

HikariCP 核心參數

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

maximumPoolSize 公式

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

JPA N+1 偵測與解法

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

什麼是 N+1 問題

載入 1 筆 Order 後，Hibernate 額外發出 N 條 SQL 去撈每筆 Order 的 OrderItem：

SELECT * FROM orders WHERE user_id = 1;        -- 1 條
SELECT * FROM order_items WHERE order_id = 10; -- N 條（每筆 Order 一條）
SELECT * FROM order_items WHERE order_id = 11;
SELECT * FROM order_items WHERE order_id = 12;
...

根源在於 @OneToMany 預設是 LAZY 載入——存取集合屬性時才觸發查詢，在迴圈中存取就變成 N 條。

Spring Boot 3 + Virtual Threads 實戰

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

什麼是 Virtual Threads

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

Carrier Thread vs Virtual Thread — M:N 調度

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

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

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

FTP 工具類實作指南：安全、可靠的檔案傳輸解決方案

Thu, 05 Jan 2023 23:45:46 +0800

安全警告：FTP 為明文協定，帳號密碼與檔案內容在傳輸過程中未加密，不建議在公網或敏感資料場景使用。生產環境請優先考慮 SFTP（SSH 通道加密）或 FTPS（TLS 加密）。若系統限制只能使用 FTP，務必在內網隔離環境中部署，並搭配 VPN 或 IP 白名單控管。

概述

FTP（File Transfer Protocol）是企業環境中常用的檔案傳輸協定。本文提供一個完整、安全且可靠的 FTP 工具類實作，適用於生產環境的檔案上傳、下載和管理需求。

核心特性

✅ 配置外部化：所有連線資訊透過配置檔案管理
✅ 連線池管理：支援連線複用，提升效能
✅ 完整錯誤處理：詳細的異常處理和重試機制
✅ 檔案操作：上傳、下載、刪除、列表等完整功能
✅ 安全考量：密碼加密、連線超時、資源釋放
✅ 日誌記錄：完整的操作日誌和監控

依賴配置

Maven 依賴

<dependencies>
    <!-- Apache Commons Net -->
    <dependency>
        <groupId>commons-net</groupId>
        <artifactId>commons-net</artifactId>
        <version>3.9.0</version>
    </dependency>
    
    <!-- Spring Boot Starter -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter</artifactId>
    </dependency>
    
    <!-- 配置處理 -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-configuration-processor</artifactId>
        <optional>true</optional>
    </dependency>
</dependencies>

Gradle 依賴

dependencies {
    implementation 'commons-net:commons-net:3.9.0'
    implementation 'org.springframework.boot:spring-boot-starter'
    annotationProcessor 'org.springframework.boot:spring-boot-configuration-processor'
}

配置類設計

FTP 配置屬性

package com.example.config;

import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.stereotype.Component;

@Component
@ConfigurationProperties(prefix = "ftp")
public class FtpProperties {
    
    private String host;
    private int port = 21;
    private String username;
    private String password;
    private String basePath = "/";
    private int connectTimeout = 30000;  // 30 秒
    private int dataTimeout = 60000;     // 60 秒
    private int bufferSize = 8192;       // 8KB
    private String encoding = "UTF-8";
    private boolean passiveMode = true;
    private int maxConnections = 10;
    
    // Getters and Setters
    public String getHost() { return host; }
    public void setHost(String host) { this.host = host; }
    
    public int getPort() { return port; }
    public void setPort(int port) { this.port = port; }
    
    public String getUsername() { return username; }
    public void setUsername(String username) { this.username = username; }
    
    public String getPassword() { return password; }
    public void setPassword(String password) { this.password = password; }
    
    public String getBasePath() { return basePath; }
    public void setBasePath(String basePath) { this.basePath = basePath; }
    
    public int getConnectTimeout() { return connectTimeout; }
    public void setConnectTimeout(int connectTimeout) { this.connectTimeout = connectTimeout; }
    
    public int getDataTimeout() { return dataTimeout; }
    public void setDataTimeout(int dataTimeout) { this.dataTimeout = dataTimeout; }
    
    public int getBufferSize() { return bufferSize; }
    public void setBufferSize(int bufferSize) { this.bufferSize = bufferSize; }
    
    public String getEncoding() { return encoding; }
    public void setEncoding(String encoding) { this.encoding = encoding; }
    
    public boolean isPassiveMode() { return passiveMode; }
    public void setPassiveMode(boolean passiveMode) { this.passiveMode = passiveMode; }
    
    public int getMaxConnections() { return maxConnections; }
    public void setMaxConnections(int maxConnections) { this.maxConnections = maxConnections; }
}

應用配置檔案

# application.yml
ftp:
  host: ${FTP_HOST:ftp.example.com}
  port: ${FTP_PORT:21}
  username: ${FTP_USERNAME:}
  password: ${FTP_PASSWORD:}
  base-path: ${FTP_BASE_PATH:/uploads}
  connect-timeout: 30000
  data-timeout: 60000
  buffer-size: 8192
  encoding: UTF-8
  passive-mode: true
  max-connections: 10

# 生產環境建議使用環境變數
# export FTP_HOST=your-ftp-server.com
# export FTP_USERNAME=your-username  
# export FTP_PASSWORD=your-secure-password

核心工具類實作

FTP 連線工廠

package com.example.util;

import org.apache.commons.net.ftp.FTPClient;
import org.apache.commons.net.ftp.FTPReply;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Component;

import com.example.config.FtpProperties;

import java.io.IOException;
import java.util.concurrent.BlockingQueue;
import java.util.concurrent.LinkedBlockingQueue;

@Component
public class FtpConnectionFactory {
    
    private static final Logger logger = LoggerFactory.getLogger(FtpConnectionFactory.class);
    
    @Autowired
    private FtpProperties ftpProperties;
    
    // 注意：FTPClient 非執行緒安全（non-thread-safe）。
    // 此處使用 BlockingQueue 確保同一時間只有一個執行緒持有並使用單一 FTPClient 實例。
    // 從 pool 取出後必須在同一執行緒完成操作並歸還，嚴禁跨執行緒共用同一個 FTPClient 物件。
    private final BlockingQueue<FTPClient> connectionPool = new LinkedBlockingQueue<>();
    
    /**
     * 建立 FTP 連線
     */
    public FTPClient createConnection() throws IOException {
        FTPClient ftpClient = new FTPClient();
        
        try {
            // 設定連線參數
            ftpClient.setConnectTimeout(ftpProperties.getConnectTimeout());
            ftpClient.setDataTimeout(ftpProperties.getDataTimeout());
            ftpClient.setControlEncoding(ftpProperties.getEncoding());
            ftpClient.setBufferSize(ftpProperties.getBufferSize());
            
            // 建立連線
            ftpClient.connect(ftpProperties.getHost(), ftpProperties.getPort());
            
            // 檢查連線回應
            int replyCode = ftpClient.getReplyCode();
            if (!FTPReply.isPositiveCompletion(replyCode)) {
                ftpClient.disconnect();
                throw new IOException("FTP 伺服器拒絕連線，回應碼：" + replyCode);
            }
            
            // 登入
            boolean loginSuccess = ftpClient.login(ftpProperties.getUsername(), ftpProperties.getPassword());
            if (!loginSuccess) {
                ftpClient.disconnect();
                throw new IOException("FTP 登入失敗，請檢查使用者名稱和密碼");
            }
            
            // 設定檔案傳輸模式
            ftpClient.setFileType(FTPClient.BINARY_FILE_TYPE);
            
            // 設定被動/主動模式
            if (ftpProperties.isPassiveMode()) {
                ftpClient.enterLocalPassiveMode();
            } else {
                ftpClient.enterLocalActiveMode();
            }
            
            logger.info("FTP 連線建立成功：{}:{}", ftpProperties.getHost(), ftpProperties.getPort());
            return ftpClient;
            
        } catch (IOException e) {
            logger.error("建立 FTP 連線失敗：{}", e.getMessage());
            if (ftpClient.isConnected()) {
                try {
                    ftpClient.disconnect();
                } catch (IOException ex) {
                    logger.warn("關閉失敗的 FTP 連線時發生錯誤：{}", ex.getMessage());
                }
            }
            throw e;
        }
    }
    
    /**
     * 歸還連線到連線池
     */
    public void returnConnection(FTPClient ftpClient) {
        if (ftpClient != null && ftpClient.isConnected()) {
            if (connectionPool.size() < ftpProperties.getMaxConnections()) {
                connectionPool.offer(ftpClient);
            } else {
                closeConnection(ftpClient);
            }
        }
    }
    
    /**
     * 從連線池獲取連線
     */
    public FTPClient getConnection() throws IOException {
        FTPClient ftpClient = connectionPool.poll();
        if (ftpClient == null || !ftpClient.isConnected()) {
            return createConnection();
        }
        return ftpClient;
    }
    
    /**
     * 關閉連線
     */
    public void closeConnection(FTPClient ftpClient) {
        if (ftpClient != null) {
            try {
                if (ftpClient.isConnected()) {
                    ftpClient.logout();
                    ftpClient.disconnect();
                }
            } catch (IOException e) {
                logger.warn("關閉 FTP 連線時發生錯誤：{}", e.getMessage());
            }
        }
    }
}

主要 FTP 工具類

package com.example.util;

import org.apache.commons.net.ftp.FTPClient;
import org.apache.commons.net.ftp.FTPFile;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Component;
import org.springframework.util.StringUtils;

import com.example.config.FtpProperties;

import java.io.*;
import java.time.LocalDateTime;
import java.time.format.DateTimeFormatter;
import java.util.ArrayList;
import java.util.List;

@Component
public class FtpUtil {
    
    private static final Logger logger = LoggerFactory.getLogger(FtpUtil.class);
    
    @Autowired
    private FtpConnectionFactory connectionFactory;
    
    @Autowired
    private FtpProperties ftpProperties;
    
    /**
     * 上傳檔案
     * 
     * @param localFile 本地檔案
     * @param remotePath 遠端路徑（相對於 basePath）
     * @return 上傳是否成功
     */
    public boolean uploadFile(File localFile, String remotePath) {
        if (!localFile.exists() || !localFile.isFile()) {
            logger.error("本地檔案不存在或不是檔案：{}", localFile.getAbsolutePath());
            return false;
        }
        
        try (FileInputStream fis = new FileInputStream(localFile)) {
            return uploadFile(fis, remotePath, localFile.getName());
        } catch (IOException e) {
            logger.error("讀取本地檔案失敗：{}", e.getMessage());
            return false;
        }
    }
    
    /**
     * 上傳檔案流
     * 
     * @param inputStream 輸入流
     * @param remotePath 遠端路徑
     * @param fileName 檔案名稱
     * @return 上傳是否成功
     */
    public boolean uploadFile(InputStream inputStream, String remotePath, String fileName) {
        FTPClient ftpClient = null;
        
        try {
            ftpClient = connectionFactory.getConnection();
            
            // 確保遠端目錄存在
            String fullPath = buildFullPath(remotePath);
            createDirectoryIfNotExists(ftpClient, fullPath);
            
            // 切換到目標目錄
            if (!ftpClient.changeWorkingDirectory(fullPath)) {
                logger.error("無法切換到目錄：{}", fullPath);
                return false;
            }
            
            // 上傳檔案
            boolean result = ftpClient.storeFile(fileName, inputStream);
            
            if (result) {
                logger.info("檔案上傳成功：{}/{}", fullPath, fileName);
            } else {
                logger.error("檔案上傳失敗：{}/{}", fullPath, fileName);
            }
            
            return result;
            
        } catch (IOException e) {
            logger.error("上傳檔案時發生錯誤：{}", e.getMessage());
            return false;
        } finally {
            connectionFactory.returnConnection(ftpClient);
            closeQuietly(inputStream);
        }
    }
    
    /**
     * 下載檔案
     * 
     * @param remotePath 遠端路徑
     * @param fileName 檔案名稱
     * @param localFile 本地檔案
     * @return 下載是否成功
     */
    public boolean downloadFile(String remotePath, String fileName, File localFile) {
        FTPClient ftpClient = null;
        
        try {
            ftpClient = connectionFactory.getConnection();
            
            String fullPath = buildFullPath(remotePath);
            if (!ftpClient.changeWorkingDirectory(fullPath)) {
                logger.error("遠端目錄不存在：{}", fullPath);
                return false;
            }
            
            // 確保本地目錄存在
            File parentDir = localFile.getParentFile();
            if (!parentDir.exists()) {
                parentDir.mkdirs();
            }
            
            try (FileOutputStream fos = new FileOutputStream(localFile)) {
                boolean result = ftpClient.retrieveFile(fileName, fos);
                
                if (result) {
                    logger.info("檔案下載成功：{}/{} -> {}", fullPath, fileName, localFile.getAbsolutePath());
                } else {
                    logger.error("檔案下載失敗：{}/{}", fullPath, fileName);
                }
                
                return result;
            }
            
        } catch (IOException e) {
            logger.error("下載檔案時發生錯誤：{}", e.getMessage());
            return false;
        } finally {
            connectionFactory.returnConnection(ftpClient);
        }
    }
    
    /**
     * 刪除檔案
     * 
     * @param remotePath 遠端路徑
     * @param fileName 檔案名稱
     * @return 刪除是否成功
     */
    public boolean deleteFile(String remotePath, String fileName) {
        FTPClient ftpClient = null;
        
        try {
            ftpClient = connectionFactory.getConnection();
            
            String fullPath = buildFullPath(remotePath);
            if (!ftpClient.changeWorkingDirectory(fullPath)) {
                logger.error("遠端目錄不存在：{}", fullPath);
                return false;
            }
            
            boolean result = ftpClient.deleteFile(fileName);
            
            if (result) {
                logger.info("檔案刪除成功：{}/{}", fullPath, fileName);
            } else {
                logger.error("檔案刪除失敗：{}/{}", fullPath, fileName);
            }
            
            return result;
            
        } catch (IOException e) {
            logger.error("刪除檔案時發生錯誤：{}", e.getMessage());
            return false;
        } finally {
            connectionFactory.returnConnection(ftpClient);
        }
    }
    
    /**
     * 列出目錄中的檔案
     * 
     * @param remotePath 遠端路徑
     * @return 檔案列表
     */
    public List<FtpFileInfo> listFiles(String remotePath) {
        FTPClient ftpClient = null;
        List<FtpFileInfo> fileList = new ArrayList<>();
        
        try {
            ftpClient = connectionFactory.getConnection();
            
            String fullPath = buildFullPath(remotePath);
            if (!ftpClient.changeWorkingDirectory(fullPath)) {
                logger.error("遠端目錄不存在：{}", fullPath);
                return fileList;
            }
            
            FTPFile[] ftpFiles = ftpClient.listFiles();
            
            for (FTPFile ftpFile : ftpFiles) {
                FtpFileInfo fileInfo = new FtpFileInfo();
                fileInfo.setName(ftpFile.getName());
                fileInfo.setSize(ftpFile.getSize());
                fileInfo.setDirectory(ftpFile.isDirectory());
                fileInfo.setModifyTime(ftpFile.getTimestamp());
                fileList.add(fileInfo);
            }
            
            logger.info("成功列出目錄 {} 中的 {} 個檔案", fullPath, fileList.size());
            
        } catch (IOException e) {
            logger.error("列出檔案時發生錯誤：{}", e.getMessage());
        } finally {
            connectionFactory.returnConnection(ftpClient);
        }
        
        return fileList;
    }
    
    /**
     * 檢查檔案是否存在
     * 
     * @param remotePath 遠端路徑
     * @param fileName 檔案名稱
     * @return 檔案是否存在
     */
    public boolean fileExists(String remotePath, String fileName) {
        FTPClient ftpClient = null;
        
        try {
            ftpClient = connectionFactory.getConnection();
            
            String fullPath = buildFullPath(remotePath);
            if (!ftpClient.changeWorkingDirectory(fullPath)) {
                return false;
            }
            
            FTPFile[] files = ftpClient.listFiles(fileName);
            return files != null && files.length > 0;
            
        } catch (IOException e) {
            logger.error("檢查檔案存在性時發生錯誤：{}", e.getMessage());
            return false;
        } finally {
            connectionFactory.returnConnection(ftpClient);
        }
    }
    
    /**
     * 建立完整路徑
     */
    private String buildFullPath(String remotePath) {
        String basePath = ftpProperties.getBasePath();
        if (!StringUtils.hasText(remotePath)) {
            return basePath;
        }
        
        // 規範化路徑
        String normalizedBasePath = basePath.endsWith("/") ? basePath : basePath + "/";
        String normalizedRemotePath = remotePath.startsWith("/") ? remotePath.substring(1) : remotePath;
        
        return normalizedBasePath + normalizedRemotePath;
    }
    
    /**
     * 遞迴建立目錄
     */
    private void createDirectoryIfNotExists(FTPClient ftpClient, String path) throws IOException {
        String[] pathElements = path.split("/");
        StringBuilder currentPath = new StringBuilder();
        
        for (String element : pathElements) {
            if (StringUtils.hasText(element)) {
                currentPath.append("/").append(element);
                
                if (!ftpClient.changeWorkingDirectory(currentPath.toString())) {
                    if (ftpClient.makeDirectory(currentPath.toString())) {
                        logger.debug("建立目錄：{}", currentPath.toString());
                    } else {
                        throw new IOException("無法建立目錄：" + currentPath.toString());
                    }
                }
            }
        }
    }
    
    /**
     * 安靜地關閉資源
     */
    private void closeQuietly(Closeable closeable) {
        if (closeable != null) {
            try {
                closeable.close();
            } catch (IOException e) {
                // 忽略關閉時的錯誤
            }
        }
    }
}

檔案資訊實體類

package com.example.util;

import java.util.Calendar;

public class FtpFileInfo {
    private String name;
    private long size;
    private boolean isDirectory;
    private Calendar modifyTime;
    
    // Getters and Setters
    public String getName() { return name; }
    public void setName(String name) { this.name = name; }
    
    public long getSize() { return size; }
    public void setSize(long size) { this.size = size; }
    
    public boolean isDirectory() { return isDirectory; }
    public void setDirectory(boolean directory) { isDirectory = directory; }
    
    public Calendar getModifyTime() { return modifyTime; }
    public void setModifyTime(Calendar modifyTime) { this.modifyTime = modifyTime; }
    
    @Override
    public String toString() {
        return String.format("FtpFileInfo{name='%s', size=%d, isDirectory=%s}", 
                           name, size, isDirectory);
    }
}

使用範例

基本使用

@Service
public class FileService {
    
    @Autowired
    private FtpUtil ftpUtil;
    
    /**
     * 上傳使用者頭像
     */
    public boolean uploadAvatar(MultipartFile file, String userId) {
        try {
            String remotePath = "avatars/" + userId;
            String fileName = generateFileName(file.getOriginalFilename());
            
            return ftpUtil.uploadFile(file.getInputStream(), remotePath, fileName);
        } catch (IOException e) {
            logger.error("上傳頭像失敗：{}", e.getMessage());
            return false;
        }
    }
    
    /**
     * 批量上傳檔案
     */
    public List<String> batchUpload(List<MultipartFile> files, String category) {
        List<String> successFiles = new ArrayList<>();
        String remotePath = "uploads/" + category + "/" + getCurrentDate();
        
        for (MultipartFile file : files) {
            try {
                String fileName = generateFileName(file.getOriginalFilename());
                if (ftpUtil.uploadFile(file.getInputStream(), remotePath, fileName)) {
                    successFiles.add(fileName);
                }
            } catch (IOException e) {
                logger.error("批量上傳檔案失敗：{}", file.getOriginalFilename());
            }
        }
        
        return successFiles;
    }
    
    private String generateFileName(String originalName) {
        String timestamp = LocalDateTime.now().format(DateTimeFormatter.ofPattern("yyyyMMddHHmmss"));
        String extension = originalName.substring(originalName.lastIndexOf("."));
        return timestamp + "_" + UUID.randomUUID().toString().substring(0, 8) + extension;
    }
    
    private String getCurrentDate() {
        return LocalDateTime.now().format(DateTimeFormatter.ofPattern("yyyy/MM/dd"));
    }
}

進階功能：檔案同步

@Component
public class FtpSyncService {
    
    @Autowired
    private FtpUtil ftpUtil;
    
    /**
     * 同步本地目錄到 FTP
     */
    public void syncDirectoryToFtp(String localDirPath, String remotePath) {
        File localDir = new File(localDirPath);
        if (!localDir.exists() || !localDir.isDirectory()) {
            logger.error("本地目錄不存在：{}", localDirPath);
            return;
        }
        
        syncDirectoryRecursive(localDir, remotePath);
    }
    
    private void syncDirectoryRecursive(File localDir, String remotePath) {
        File[] files = localDir.listFiles();
        if (files == null) return;
        
        for (File file : files) {
            if (file.isDirectory()) {
                // 遞迴處理子目錄
                String subRemotePath = remotePath + "/" + file.getName();
                syncDirectoryRecursive(file, subRemotePath);
            } else {
                // 上傳檔案
                if (!ftpUtil.fileExists(remotePath, file.getName())) {
                    ftpUtil.uploadFile(file, remotePath);
                    logger.info("同步檔案：{} -> {}/{}", file.getAbsolutePath(), remotePath, file.getName());
                }
            }
        }
    }
}

安全最佳實踐

1. 配置安全

# 使用環境變數或加密配置
ftp:
  host: ${FTP_HOST}
  username: ${FTP_USERNAME}
  password: ${FTP_PASSWORD:#{null}}  # 可以為空，使用 SSH Key

2. 檔案驗證

@Component
public class FileValidator {
    
    private static final List<String> ALLOWED_EXTENSIONS = 
        Arrays.asList(".jpg", ".png", ".pdf", ".doc", ".docx", ".xls", ".xlsx");
    
    private static final long MAX_FILE_SIZE = 10 * 1024 * 1024; // 10MB
    
    public boolean isValidFile(MultipartFile file) {
        // 檢查檔案大小
        if (file.getSize() > MAX_FILE_SIZE) {
            return false;
        }
        
        // 檢查檔案副檔名
        String fileName = file.getOriginalFilename();
        if (fileName == null) return false;
        
        String extension = fileName.substring(fileName.lastIndexOf(".")).toLowerCase();
        return ALLOWED_EXTENSIONS.contains(extension);
    }
}

3. 存取控制

@Component
public class FtpAccessControl {
    
    /**
     * 檢查使用者是否有權限存取指定路徑
     */
    public boolean hasAccess(String userId, String remotePath) {
        // 實作存取控制邏輯
        // 例如：使用者只能存取自己的目錄
        return remotePath.startsWith("users/" + userId + "/");
    }
}

監控與維護

健康檢查

@Component
public class FtpHealthIndicator implements HealthIndicator {
    
    @Autowired
    private FtpConnectionFactory connectionFactory;
    
    @Override
    public Health health() {
        try {
            FTPClient ftpClient = connectionFactory.getConnection();
            boolean isConnected = ftpClient.isConnected();
            connectionFactory.returnConnection(ftpClient);
            
            return isConnected ? 
                Health.up().withDetail("status", "FTP connection available").build() :
                Health.down().withDetail("status", "FTP connection failed").build();
                
        } catch (Exception e) {
            return Health.down().withDetail("error", e.getMessage()).build();
        }
    }
}

效能監控

@Aspect
@Component
public class FtpPerformanceAspect {
    
    private static final Logger logger = LoggerFactory.getLogger(FtpPerformanceAspect.class);
    
    @Around("execution(* com.example.util.FtpUtil.*(..))")
    public Object logExecutionTime(ProceedingJoinPoint joinPoint) throws Throwable {
        long startTime = System.currentTimeMillis();
        
        try {
            Object result = joinPoint.proceed();
            long endTime = System.currentTimeMillis();
            
            logger.info("FTP 操作 {} 執行時間：{}ms", 
                       joinPoint.getSignature().getName(), endTime - startTime);
            
            return result;
        } catch (Exception e) {
            long endTime = System.currentTimeMillis();
            logger.error("FTP 操作 {} 失敗，執行時間：{}ms，錯誤：{}", 
                        joinPoint.getSignature().getName(), endTime - startTime, e.getMessage());
            throw e;
        }
    }
}

常見問題與解決方案

1. 連線逾時問題

// 增加重試機制
@Retryable(value = {IOException.class}, maxAttempts = 3, backoff = @Backoff(delay = 1000))
public boolean uploadFileWithRetry(InputStream inputStream, String remotePath, String fileName) {
    return uploadFile(inputStream, remotePath, fileName);
}

2. 中文檔名問題

// 在 FTP 配置中設定正確的編碼
ftpClient.setControlEncoding("UTF-8");

// 或者對檔名進行編碼處理
String encodedFileName = new String(fileName.getBytes("UTF-8"), "ISO-8859-1");

3. 防火牆問題

1
2
3

# 使用被動模式避免防火牆問題
ftp:
  passive-mode: true

測試範例

@SpringBootTest
class FtpUtilTest {
    
    @Autowired
    private FtpUtil ftpUtil;
    
    @Test
    void testUploadFile() {
        // 建立測試檔案
        File testFile = createTestFile();
        
        // 執行上傳
        boolean result = ftpUtil.uploadFile(testFile, "test", "test.txt");
        
        // 驗證結果
        assertTrue(result);
        assertTrue(ftpUtil.fileExists("test", "test.txt"));
        
        // 清理
        ftpUtil.deleteFile("test", "test.txt");
    }
    
    private File createTestFile() {
        try {
            File tempFile = File.createTempFile("test", ".txt");
            Files.write(tempFile.toPath(), "測試內容".getBytes());
            return tempFile;
        } catch (IOException e) {
            throw new RuntimeException(e);
        }
    }
}

總結

本文提供的 FTP 工具類具備以下優勢：

JPA Enum 型別處理完整指南：映射策略與最佳實踐

Thu, 05 Jan 2023 23:18:48 +0800

概述

在企業級應用程式開發中，Enum（列舉）是表示有限狀態集合的理想選擇，如訂單狀態、使用者角色、審核狀態等。本文深入探討如何在 JPA/Hibernate 中有效處理 Enum 型別，包含各種映射策略、效能考量和實際應用場景。

基本 Enum 映射

1. @Enumerated 註解

JPA 提供 @Enumerated 註解來處理 Enum 映射，支援兩種策略：

EnumType.ORDINAL（數字映射）

// 定義狀態列舉
public enum OrderStatus {
    PENDING,    // 0
    CONFIRMED,  // 1
    SHIPPED,    // 2
    DELIVERED,  // 3
    CANCELLED   // 4
}

// 實體類使用
@Entity
@Table(name = "orders")
public class Order {
    
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
    
    @Enumerated(EnumType.ORDINAL)
    @Column(name = "status", nullable = false)
    private OrderStatus status = OrderStatus.PENDING;
    
    // 其他屬性...
}

資料庫儲存：

Java TreeSet 完整實作指南：紅黑樹有序集合與 NavigableSet 介面詳解

Sun, 02 Oct 2022 00:48:01 +0800

Java TreeSet 完整實作指南

簡介

TreeSet 是 Java 集合框架中實現有序集合的核心類別，基於 TreeMap 實現並使用紅黑樹（Red-Black Tree）數據結構。它保證元素的唯一性和有序性，提供了 O(log n) 的時間複雜度進行搜索、插入和刪除操作。本文將深入探討 TreeSet 的內部實現、各種方法使用、效能特性以及在企業級開發中的最佳實踐。

TreeSet 架構與繼承關係

類別繼承結構

Collection<E>
   ↑
Set<E>
   ↑
SortedSet<E>
   ↑
NavigableSet<E>
   ↑
TreeSet<E>

核心介面關係

// 基本集合介面
public interface Set<E> extends Collection<E> {
    boolean add(E e);
    boolean remove(Object o);
    boolean contains(Object o);
    int size();
    boolean isEmpty();
    Iterator<E> iterator();
}

// 有序集合介面
public interface SortedSet<E> extends Set<E> {
    Comparator<? super E> comparator();
    SortedSet<E> subSet(E fromElement, E toElement);
    SortedSet<E> headSet(E toElement);
    SortedSet<E> tailSet(E fromElement);
    E first();
    E last();
}

// 可導航集合介面
public interface NavigableSet<E> extends SortedSet<E> {
    E lower(E e);
    E floor(E e);
    E ceiling(E e);
    E higher(E e);
    E pollFirst();
    E pollLast();
    Iterator<E> iterator();
    NavigableSet<E> descendingSet();
    Iterator<E> descendingIterator();
    NavigableSet<E> subSet(E fromElement, boolean fromInclusive,
                          E toElement, boolean toInclusive);
    NavigableSet<E> headSet(E toElement, boolean inclusive);
    NavigableSet<E> tailSet(E fromElement, boolean inclusive);
}

TreeSet 核心特性

1. 基於 TreeMap 的實現

// TreeSet 內部實現
public class TreeSet<E> extends AbstractSet<E>
    implements NavigableSet<E>, Cloneable, java.io.Serializable {
    
    // 內部使用 TreeMap 存儲元素
    private transient NavigableMap<E,Object> m;
    
    // 虛擬值，用於將 Set 轉換為 Map
    private static final Object PRESENT = new Object();
    
    // 構造函數
    public TreeSet() {
        this(new TreeMap<E,Object>());
    }
    
    public TreeSet(Comparator<? super E> comparator) {
        this(new TreeMap<>(comparator));
    }
    
    // 基本操作
    public boolean add(E e) {
        return m.put(e, PRESENT) == null;
    }
    
    public boolean remove(Object o) {
        return m.remove(o) == PRESENT;
    }
    
    public boolean contains(Object o) {
        return m.containsKey(o);
    }
    
    public int size() {
        return m.size();
    }
}

2. 自然排序與自定義比較器

// 自然排序 TreeSet
TreeSet<String> naturalOrder = new TreeSet<>();
naturalOrder.add("Charlie");
naturalOrder.add("Alice");
naturalOrder.add("Bob");
// 結果：[Alice, Bob, Charlie]

// 自定義比較器 - 按長度排序
TreeSet<String> lengthOrder = new TreeSet<>(
    Comparator.comparing(String::length)
        .thenComparing(String::compareTo) // 長度相同時按字典序
);
lengthOrder.add("Java");
lengthOrder.add("C++");
lengthOrder.add("Python");
lengthOrder.add("Go");
// 結果：[Go, C++, Java, Python]

// 降序排序
TreeSet<Integer> descendingOrder = new TreeSet<>(Collections.reverseOrder());
descendingOrder.add(5);
descendingOrder.add(2);
descendingOrder.add(8);
descendingOrder.add(1);
// 結果：[8, 5, 2, 1]

// 複雜對象排序
TreeSet<Person> personSet = new TreeSet<>(
    Comparator.comparing(Person::getAge)
        .thenComparing(Person::getName)
);

SortedSet 介面詳解

基本方法實現

public class TreeSetSortedExample {
    
    public static void main(String[] args) {
        TreeSet<Integer> treeSet = new TreeSet<>();
        
        // 添加元素
        treeSet.add(5);
        treeSet.add(2);
        treeSet.add(8);
        treeSet.add(1);
        treeSet.add(9);
        treeSet.add(3);
        
        demonstrateSortedSetMethods(treeSet);
    }
    
    private static void demonstrateSortedSetMethods(TreeSet<Integer> set) {
        System.out.println("Original set: " + set); // [1, 2, 3, 5, 8, 9]
        
        // 獲取比較器
        Comparator<? super Integer> comparator = set.comparator();
        System.out.println("Comparator: " + comparator); // null (natural ordering)
        
        // 第一個和最後一個元素
        System.out.println("First element: " + set.first()); // 1
        System.out.println("Last element: " + set.last());   // 9
        
        // 子集合（含頭不含尾）
        SortedSet<Integer> subSet = set.subSet(2, 8);
        System.out.println("SubSet [2, 8): " + subSet); // [2, 3, 5]
        
        // 頭部集合（不包含指定元素）
        SortedSet<Integer> headSet = set.headSet(5);
        System.out.println("HeadSet (< 5): " + headSet); // [1, 2, 3]
        
        // 尾部集合（包含指定元素）
        SortedSet<Integer> tailSet = set.tailSet(5);
        System.out.println("TailSet (>= 5): " + tailSet); // [5, 8, 9]
        
        // 迭代器
        System.out.print("Forward iteration: ");
        for (Integer value : set) {
            System.out.print(value + " ");
        }
        System.out.println();
        
        // 降序迭代器
        System.out.print("Descending iteration: ");
        Iterator<Integer> descendingIterator = set.descendingIterator();
        while (descendingIterator.hasNext()) {
            System.out.print(descendingIterator.next() + " ");
        }
        System.out.println();
    }
}

NavigableSet 介面詳解

導航方法實現

public class TreeSetNavigableExample {
    
    public static void main(String[] args) {
        TreeSet<Integer> treeSet = new TreeSet<>();
        
        // 添加測試數據
        treeSet.add(1);
        treeSet.add(3);
        treeSet.add(5);
        treeSet.add(7);
        treeSet.add(9);
        
        demonstrateNavigableMethods(treeSet);
    }
    
    private static void demonstrateNavigableMethods(TreeSet<Integer> set) {
        System.out.println("Original set: " + set); // [1, 3, 5, 7, 9]
        
        // Lower 方法：返回嚴格小於指定元素的最大元素
        Integer lower = set.lower(5);
        System.out.println("Lower (< 5): " + lower); // 3
        
        // Floor 方法：返回小於或等於指定元素的最大元素
        Integer floor1 = set.floor(4);
        Integer floor2 = set.floor(5);
        System.out.println("Floor (<= 4): " + floor1); // 3
        System.out.println("Floor (<= 5): " + floor2); // 5
        
        // Ceiling 方法：返回大於或等於指定元素的最小元素
        Integer ceiling1 = set.ceiling(4);
        Integer ceiling2 = set.ceiling(5);
        System.out.println("Ceiling (>= 4): " + ceiling1); // 5
        System.out.println("Ceiling (>= 5): " + ceiling2); // 5
        
        // Higher 方法：返回嚴格大於指定元素的最小元素
        Integer higher = set.higher(5);
        System.out.println("Higher (> 5): " + higher); // 7
        
        // 彈出首尾元素（會刪除元素）
        TreeSet<Integer> copySet = new TreeSet<>(set);
        Integer pollFirst = copySet.pollFirst();
        Integer pollLast = copySet.pollLast();
        System.out.println("Poll first: " + pollFirst); // 1
        System.out.println("Poll last: " + pollLast);   // 9
        System.out.println("After polling: " + copySet); // [3, 5, 7]
        
        // 降序視圖
        NavigableSet<Integer> descendingSet = set.descendingSet();
        System.out.println("Descending set: " + descendingSet); // [9, 7, 5, 3, 1]
        
        // 範圍視圖
        NavigableSet<Integer> rangeSet = set.subSet(3, true, 7, false);
        System.out.println("Range [3, 7): " + rangeSet); // [3, 5]
        
        NavigableSet<Integer> headSet = set.headSet(5, true);
        System.out.println("Head set (<= 5): " + headSet); // [1, 3, 5]
        
        NavigableSet<Integer> tailSet = set.tailSet(5, false);
        System.out.println("Tail set (> 5): " + tailSet); // [7, 9]
        
        // 查找操作
        demonstrateSearchOperations(set);
    }
    
    private static void demonstrateSearchOperations(TreeSet<Integer> set) {
        System.out.println("\n=== Search Operations ===");
        
        // 測試不存在的元素
        int target = 4;
        System.out.println("Searching for: " + target);
        System.out.println("Contains: " + set.contains(target)); // false
        System.out.println("Lower: " + set.lower(target));       // 3
        System.out.println("Floor: " + set.floor(target));       // 3
        System.out.println("Ceiling: " + set.ceiling(target));   // 5
        System.out.println("Higher: " + set.higher(target));     // 5
        
        // 測試邊界情況
        System.out.println("\n=== Boundary Cases ===");
        System.out.println("Lower than first: " + set.lower(1));    // null
        System.out.println("Higher than last: " + set.higher(9));   // null
        System.out.println("Floor of first: " + set.floor(1));      // 1
        System.out.println("Ceiling of last: " + set.ceiling(9));   // 9
    }
}

企業級應用實例

1. 事件調度系統

public class EventScheduler {
    
    private final TreeSet<Event> eventQueue;
    private final ScheduledExecutorService scheduler;
    private final AtomicBoolean running;
    
    public EventScheduler() {
        // 按時間排序事件
        this.eventQueue = new TreeSet<>(Comparator.comparing(Event::getScheduledTime));
        this.scheduler = Executors.newScheduledThreadPool(2);
        this.running = new AtomicBoolean(false);
    }
    
    // 調度事件
    public void scheduleEvent(Event event) {
        synchronized (eventQueue) {
            eventQueue.add(event);
            
            // 如果是最早的事件，重新調度
            if (event.equals(eventQueue.first())) {
                rescheduleNext();
            }
        }
    }
    
    // 取消事件
    public boolean cancelEvent(Event event) {
        synchronized (eventQueue) {
            boolean removed = eventQueue.remove(event);
            if (removed && !eventQueue.isEmpty()) {
                rescheduleNext();
            }
            return removed;
        }
    }
    
    // 獲取即將執行的事件
    public List<Event> getUpcomingEvents(int count) {
        synchronized (eventQueue) {
            return eventQueue.stream()
                    .limit(count)
                    .collect(Collectors.toList());
        }
    }
    
    // 獲取指定時間範圍內的事件
    public List<Event> getEventsInRange(LocalDateTime start, LocalDateTime end) {
        synchronized (eventQueue) {
            Event startEvent = new Event("", start, null);
            Event endEvent = new Event("", end, null);
            
            return eventQueue.subSet(startEvent, true, endEvent, false)
                    .stream()
                    .collect(Collectors.toList());
        }
    }
    
    // 啟動調度器
    public void start() {
        if (running.compareAndSet(false, true)) {
            rescheduleNext();
        }
    }
    
    // 停止調度器
    public void stop() {
        running.set(false);
        scheduler.shutdown();
    }
    
    // 重新調度下一個事件
    private void rescheduleNext() {
        if (!running.get()) {
            return;
        }
        
        synchronized (eventQueue) {
            if (eventQueue.isEmpty()) {
                return;
            }
            
            Event nextEvent = eventQueue.first();
            LocalDateTime now = LocalDateTime.now();
            
            if (nextEvent.getScheduledTime().isBefore(now)) {
                // 立即執行過期事件
                scheduler.submit(this::processNextEvent);
            } else {
                // 計算延遲時間
                long delay = Duration.between(now, nextEvent.getScheduledTime()).toMillis();
                scheduler.schedule(this::processNextEvent, delay, TimeUnit.MILLISECONDS);
            }
        }
    }
    
    // 處理下一個事件
    private void processNextEvent() {
        Event event = null;
        
        synchronized (eventQueue) {
            if (!eventQueue.isEmpty()) {
                event = eventQueue.pollFirst();
            }
        }
        
        if (event != null) {
            try {
                event.execute();
            } catch (Exception e) {
                System.err.println("Event execution failed: " + event.getName());
                e.printStackTrace();
            }
        }
        
        // 調度下一個事件
        rescheduleNext();
    }
    
    // 清理過期事件
    public int cleanupExpiredEvents() {
        synchronized (eventQueue) {
            LocalDateTime cutoff = LocalDateTime.now().minusHours(24);
            Event cutoffEvent = new Event("", cutoff, null);
            
            NavigableSet<Event> expiredEvents = eventQueue.headSet(cutoffEvent, true);
            int count = expiredEvents.size();
            expiredEvents.clear();
            
            return count;
        }
    }
    
    // 獲取統計信息
    public EventStatistics getStatistics() {
        synchronized (eventQueue) {
            LocalDateTime now = LocalDateTime.now();
            long pendingEvents = eventQueue.size();
            long overdueEvents = eventQueue.stream()
                    .filter(event -> event.getScheduledTime().isBefore(now))
                    .count();
            
            LocalDateTime nextEventTime = eventQueue.isEmpty() ? null : eventQueue.first().getScheduledTime();
            
            return new EventStatistics(pendingEvents, overdueEvents, nextEventTime);
        }
    }
    
    // 事件類
    public static class Event {
        private final String name;
        private final LocalDateTime scheduledTime;
        private final Runnable action;
        
        public Event(String name, LocalDateTime scheduledTime, Runnable action) {
            this.name = name;
            this.scheduledTime = scheduledTime;
            this.action = action;
        }
        
        public void execute() {
            if (action != null) {
                action.run();
            }
        }
        
        // Getters
        public String getName() { return name; }
        public LocalDateTime getScheduledTime() { return scheduledTime; }
        
        @Override
        public boolean equals(Object obj) {
            if (this == obj) return true;
            if (obj == null || getClass() != obj.getClass()) return false;
            Event event = (Event) obj;
            return Objects.equals(name, event.name) && 
                   Objects.equals(scheduledTime, event.scheduledTime);
        }
        
        @Override
        public int hashCode() {
            return Objects.hash(name, scheduledTime);
        }
    }
    
    // 統計信息類
    public static class EventStatistics {
        private final long pendingEvents;
        private final long overdueEvents;
        private final LocalDateTime nextEventTime;
        
        public EventStatistics(long pendingEvents, long overdueEvents, LocalDateTime nextEventTime) {
            this.pendingEvents = pendingEvents;
            this.overdueEvents = overdueEvents;
            this.nextEventTime = nextEventTime;
        }
        
        // Getters
        public long getPendingEvents() { return pendingEvents; }
        public long getOverdueEvents() { return overdueEvents; }
        public LocalDateTime getNextEventTime() { return nextEventTime; }
    }
}

2. 範圍查詢緩存系統

public class RangeQueryCache<T extends Comparable<T>> {
    
    private final TreeSet<CacheEntry<T>> cache;
    private final int maxSize;
    private final long ttlMillis;
    
    public RangeQueryCache(int maxSize, long ttlMillis) {
        this.cache = new TreeSet<>(Comparator.comparing(CacheEntry::getKey));
        this.maxSize = maxSize;
        this.ttlMillis = ttlMillis;
    }
    
    // 添加緩存項
    public void put(T key, Object value) {
        synchronized (cache) {
            // 移除舊值
            cache.removeIf(entry -> entry.getKey().equals(key));
            
            // 添加新值
            CacheEntry<T> entry = new CacheEntry<>(key, value, System.currentTimeMillis() + ttlMillis);
            cache.add(entry);
            
            // 清理過期項
            cleanupExpired();
            
            // 如果超過容量，移除最舊的項
            if (cache.size() > maxSize) {
                cache.pollFirst();
            }
        }
    }
    
    // 獲取單個值
    public Object get(T key) {
        synchronized (cache) {
            CacheEntry<T> searchEntry = new CacheEntry<>(key, null, 0);
            CacheEntry<T> found = cache.floor(searchEntry);
            
            if (found != null && found.getKey().equals(key) && !found.isExpired()) {
                return found.getValue();
            }
            
            return null;
        }
    }
    
    // 範圍查詢
    public List<Object> getRangeValues(T fromKey, T toKey) {
        synchronized (cache) {
            CacheEntry<T> fromEntry = new CacheEntry<>(fromKey, null, 0);
            CacheEntry<T> toEntry = new CacheEntry<>(toKey, null, 0);
            
            return cache.subSet(fromEntry, true, toEntry, true)
                    .stream()
                    .filter(entry -> !entry.isExpired())
                    .map(CacheEntry::getValue)
                    .collect(Collectors.toList());
        }
    }
    
    // 獲取最接近的值
    public Object getClosest(T key) {
        synchronized (cache) {
            CacheEntry<T> searchEntry = new CacheEntry<>(key, null, 0);
            CacheEntry<T> floor = cache.floor(searchEntry);
            CacheEntry<T> ceiling = cache.ceiling(searchEntry);
            
            CacheEntry<T> closest = null;
            
            if (floor != null && !floor.isExpired()) {
                closest = floor;
            }
            
            if (ceiling != null && !ceiling.isExpired()) {
                if (closest == null || 
                    key.compareTo(ceiling.getKey()) < closest.getKey().compareTo(key)) {
                    closest = ceiling;
                }
            }
            
            return closest != null ? closest.getValue() : null;
        }
    }
    
    // 獲取前 N 個值
    public List<Object> getTopN(int n) {
        synchronized (cache) {
            return cache.stream()
                    .filter(entry -> !entry.isExpired())
                    .limit(n)
                    .map(CacheEntry::getValue)
                    .collect(Collectors.toList());
        }
    }
    
    // 清理過期項
    private void cleanupExpired() {
        long now = System.currentTimeMillis();
        cache.removeIf(entry -> entry.getExpirationTime() < now);
    }
    
    // 清空緩存
    public void clear() {
        synchronized (cache) {
            cache.clear();
        }
    }
    
    // 獲取緩存統計
    public CacheStatistics getStatistics() {
        synchronized (cache) {
            cleanupExpired();
            return new CacheStatistics(cache.size(), maxSize, getHitRatio());
        }
    }
    
    private double getHitRatio() {
        // 簡化實現，實際應用中需要跟蹤命中率
        return 0.85; // 示例值
    }
    
    // 緩存項
    private static class CacheEntry<T> {
        private final T key;
        private final Object value;
        private final long expirationTime;
        
        public CacheEntry(T key, Object value, long expirationTime) {
            this.key = key;
            this.value = value;
            this.expirationTime = expirationTime;
        }
        
        public boolean isExpired() {
            return System.currentTimeMillis() > expirationTime;
        }
        
        // Getters
        public T getKey() { return key; }
        public Object getValue() { return value; }
        public long getExpirationTime() { return expirationTime; }
    }
    
    // 統計信息
    public static class CacheStatistics {
        private final int currentSize;
        private final int maxSize;
        private final double hitRatio;
        
        public CacheStatistics(int currentSize, int maxSize, double hitRatio) {
            this.currentSize = currentSize;
            this.maxSize = maxSize;
            this.hitRatio = hitRatio;
        }
        
        // Getters
        public int getCurrentSize() { return currentSize; }
        public int getMaxSize() { return maxSize; }
        public double getHitRatio() { return hitRatio; }
    }
}

3. 分數排名系統

public class LeaderboardSystem {
    
    private final TreeSet<Player> leaderboard;
    private final Map<String, Player> playerMap;
    private final int maxSize;
    
    public LeaderboardSystem(int maxSize) {
        // 按分數降序排列，分數相同時按名稱升序
        this.leaderboard = new TreeSet<>(
            Comparator.comparing(Player::getScore, Comparator.reverseOrder())
                .thenComparing(Player::getName)
        );
        this.playerMap = new ConcurrentHashMap<>();
        this.maxSize = maxSize;
    }
    
    // 更新玩家分數
    public void updateScore(String playerName, int score) {
        synchronized (leaderboard) {
            // 移除舊記錄
            Player oldPlayer = playerMap.get(playerName);
            if (oldPlayer != null) {
                leaderboard.remove(oldPlayer);
            }
            
            // 添加新記錄
            Player newPlayer = new Player(playerName, score, System.currentTimeMillis());
            leaderboard.add(newPlayer);
            playerMap.put(playerName, newPlayer);
            
            // 保持排行榜大小
            if (leaderboard.size() > maxSize) {
                Player removed = leaderboard.pollLast();
                playerMap.remove(removed.getName());
            }
        }
    }
    
    // 獲取排行榜
    public List<Player> getLeaderboard() {
        synchronized (leaderboard) {
            return new ArrayList<>(leaderboard);
        }
    }
    
    // 獲取前 N 名
    public List<Player> getTopN(int n) {
        synchronized (leaderboard) {
            return leaderboard.stream()
                    .limit(n)
                    .collect(Collectors.toList());
        }
    }
    
    // 獲取玩家排名
    public int getPlayerRank(String playerName) {
        synchronized (leaderboard) {
            Player player = playerMap.get(playerName);
            if (player == null) {
                return -1;
            }
            
            return leaderboard.headSet(player, false).size() + 1;
        }
    }
    
    // 獲取玩家分數
    public int getPlayerScore(String playerName) {
        Player player = playerMap.get(playerName);
        return player != null ? player.getScore() : -1;
    }
    
    // 獲取分數範圍內的玩家
    public List<Player> getPlayersInScoreRange(int minScore, int maxScore) {
        synchronized (leaderboard) {
            // 創建邊界對象
            Player minPlayer = new Player("", minScore, 0);
            Player maxPlayer = new Player("", maxScore, 0);
            
            return leaderboard.subSet(maxPlayer, true, minPlayer, true)
                    .stream()
                    .filter(p -> p.getScore() >= minScore && p.getScore() <= maxScore)
                    .collect(Collectors.toList());
        }
    }
    
    // 獲取玩家周圍的排名
    public List<Player> getPlayersAround(String playerName, int radius) {
        synchronized (leaderboard) {
            Player player = playerMap.get(playerName);
            if (player == null) {
                return new ArrayList<>();
            }
            
            List<Player> result = new ArrayList<>();
            
            // 獲取前面的玩家
            NavigableSet<Player> before = leaderboard.headSet(player, false);
            before.descendingSet().stream()
                    .limit(radius)
                    .forEach(result::add);
            
            Collections.reverse(result);
            
            // 添加當前玩家
            result.add(player);
            
            // 獲取後面的玩家
            NavigableSet<Player> after = leaderboard.tailSet(player, false);
            after.stream()
                    .limit(radius)
                    .forEach(result::add);
            
            return result;
        }
    }
    
    // 移除玩家
    public boolean removePlayer(String playerName) {
        synchronized (leaderboard) {
            Player player = playerMap.remove(playerName);
            if (player != null) {
                return leaderboard.remove(player);
            }
            return false;
        }
    }
    
    // 清空排行榜
    public void clear() {
        synchronized (leaderboard) {
            leaderboard.clear();
            playerMap.clear();
        }
    }
    
    // 獲取統計信息
    public LeaderboardStatistics getStatistics() {
        synchronized (leaderboard) {
            if (leaderboard.isEmpty()) {
                return new LeaderboardStatistics(0, 0, 0, 0);
            }
            
            int totalPlayers = leaderboard.size();
            int highestScore = leaderboard.first().getScore();
            int lowestScore = leaderboard.last().getScore();
            double averageScore = leaderboard.stream()
                    .mapToInt(Player::getScore)
                    .average()
                    .orElse(0.0);
            
            return new LeaderboardStatistics(totalPlayers, highestScore, lowestScore, averageScore);
        }
    }
    
    // 玩家類
    public static class Player {
        private final String name;
        private final int score;
        private final long timestamp;
        
        public Player(String name, int score, long timestamp) {
            this.name = name;
            this.score = score;
            this.timestamp = timestamp;
        }
        
        // Getters
        public String getName() { return name; }
        public int getScore() { return score; }
        public long getTimestamp() { return timestamp; }
        
        @Override
        public boolean equals(Object obj) {
            if (this == obj) return true;
            if (obj == null || getClass() != obj.getClass()) return false;
            Player player = (Player) obj;
            return score == player.score && 
                   Objects.equals(name, player.name);
        }
        
        @Override
        public int hashCode() {
            return Objects.hash(name, score);
        }
        
        @Override
        public String toString() {
            return String.format("Player{name='%s', score=%d}", name, score);
        }
    }
    
    // 統計信息
    public static class LeaderboardStatistics {
        private final int totalPlayers;
        private final int highestScore;
        private final int lowestScore;
        private final double averageScore;
        
        public LeaderboardStatistics(int totalPlayers, int highestScore, int lowestScore, double averageScore) {
            this.totalPlayers = totalPlayers;
            this.highestScore = highestScore;
            this.lowestScore = lowestScore;
            this.averageScore = averageScore;
        }
        
        // Getters
        public int getTotalPlayers() { return totalPlayers; }
        public int getHighestScore() { return highestScore; }
        public int getLowestScore() { return lowestScore; }
        public double getAverageScore() { return averageScore; }
    }
}

效能分析與優化

1. 時間複雜度分析

public class TreeSetPerformanceAnalysis {
    
    public static void main(String[] args) {
        performanceComparison();
        memoryAnalysis();
        concurrencyTest();
    }
    
    // 效能比較
    private static void performanceComparison() {
        int[] sizes = {1000, 10000, 100000, 1000000};
        
        for (int size : sizes) {
            System.out.println("Size: " + size);
            
            // TreeSet 測試
            long startTime = System.nanoTime();
            TreeSet<Integer> treeSet = new TreeSet<>();
            for (int i = 0; i < size; i++) {
                treeSet.add(i);
            }
            long treeSetInsertTime = System.nanoTime() - startTime;
            
            // 搜索測試
            startTime = System.nanoTime();
            for (int i = 0; i < 1000; i++) {
                treeSet.contains(i * size / 1000);
            }
            long treeSetSearchTime = System.nanoTime() - startTime;
            
            // HashSet 比較
            startTime = System.nanoTime();
            HashSet<Integer> hashSet = new HashSet<>();
            for (int i = 0; i < size; i++) {
                hashSet.add(i);
            }
            long hashSetInsertTime = System.nanoTime() - startTime;
            
            startTime = System.nanoTime();
            for (int i = 0; i < 1000; i++) {
                hashSet.contains(i * size / 1000);
            }
            long hashSetSearchTime = System.nanoTime() - startTime;
            
            System.out.printf("TreeSet - Insert: %d ns, Search: %d ns\n", 
                            treeSetInsertTime, treeSetSearchTime);
            System.out.printf("HashSet - Insert: %d ns, Search: %d ns\n\n", 
                            hashSetInsertTime, hashSetSearchTime);
        }
    }
    
    // 記憶體分析
    private static void memoryAnalysis() {
        Runtime runtime = Runtime.getRuntime();
        
        runtime.gc();
        long beforeMemory = runtime.totalMemory() - runtime.freeMemory();
        
        TreeSet<Integer> treeSet = new TreeSet<>();
        for (int i = 0; i < 100000; i++) {
            treeSet.add(i);
        }
        
        long afterMemory = runtime.totalMemory() - runtime.freeMemory();
        System.out.println("TreeSet memory usage: " + (afterMemory - beforeMemory) + " bytes");
        
        // 對比 HashSet
        runtime.gc();
        beforeMemory = runtime.totalMemory() - runtime.freeMemory();
        
        HashSet<Integer> hashSet = new HashSet<>();
        for (int i = 0; i < 100000; i++) {
            hashSet.add(i);
        }
        
        afterMemory = runtime.totalMemory() - runtime.freeMemory();
        System.out.println("HashSet memory usage: " + (afterMemory - beforeMemory) + " bytes");
    }
    
    // 並發測試
    private static void concurrencyTest() {
        TreeSet<Integer> treeSet = new TreeSet<>();
        ConcurrentSkipListSet<Integer> concurrentSet = new ConcurrentSkipListSet<>();
        
        // 填充初始數據
        for (int i = 0; i < 10000; i++) {
            treeSet.add(i);
            concurrentSet.add(i);
        }
        
        // 並發讀取測試
        int threadCount = 4;
        ExecutorService executor = Executors.newFixedThreadPool(threadCount);
        
        System.out.println("Concurrent read test:");
        
        // TreeSet 同步讀取
        long startTime = System.nanoTime();
        CountDownLatch latch = new CountDownLatch(threadCount);
        
        for (int i = 0; i < threadCount; i++) {
            executor.submit(() -> {
                try {
                    for (int j = 0; j < 10000; j++) {
                        synchronized (treeSet) {
                            treeSet.contains(j);
                        }
                    }
                } finally {
                    latch.countDown();
                }
            });
        }
        
        try {
            latch.await();
        } catch (InterruptedException e) {
            Thread.currentThread().interrupt();
        }
        
        long treeSetTime = System.nanoTime() - startTime;
        System.out.println("TreeSet (synchronized): " + treeSetTime + " ns");
        
        // ConcurrentSkipListSet 測試
        startTime = System.nanoTime();
        latch = new CountDownLatch(threadCount);
        
        for (int i = 0; i < threadCount; i++) {
            executor.submit(() -> {
                try {
                    for (int j = 0; j < 10000; j++) {
                        concurrentSet.contains(j);
                    }
                } finally {
                    latch.countDown();
                }
            });
        }
        
        try {
            latch.await();
        } catch (InterruptedException e) {
            Thread.currentThread().interrupt();
        }
        
        long concurrentSetTime = System.nanoTime() - startTime;
        System.out.println("ConcurrentSkipListSet: " + concurrentSetTime + " ns");
        
        executor.shutdown();
    }
}

2. 最佳化建議

public class TreeSetOptimizationTips {
    
    // 1. 使用適當的比較器
    public static void comparatorOptimization() {
        // 避免在比較器中進行複雜計算
        TreeSet<String> badExample = new TreeSet<>((s1, s2) -> {
            // 壞例子：每次比較都進行昂貴的計算
            return expensiveCalculation(s1) - expensiveCalculation(s2);
        });
        
        // 好例子：預先計算或使用緩存
        Map<String, Integer> cache = new ConcurrentHashMap<>();
        TreeSet<String> goodExample = new TreeSet<>((s1, s2) -> {
            int val1 = cache.computeIfAbsent(s1, TreeSetOptimizationTips::expensiveCalculation);
            int val2 = cache.computeIfAbsent(s2, TreeSetOptimizationTips::expensiveCalculation);
            return val1 - val2;
        });
    }
    
    // 2. 批量操作優化
    public static void batchOperationOptimization() {
        TreeSet<Integer> treeSet = new TreeSet<>();
        
        // 批量添加比單個添加效率更高
        Collection<Integer> batchData = Arrays.asList(1, 2, 3, 4, 5);
        treeSet.addAll(batchData);
        
        // 使用子集合進行批量操作
        NavigableSet<Integer> subSet = treeSet.subSet(2, true, 4, false);
        subSet.clear(); // 比逐個刪除效率更高
    }
    
    // 3. 記憶體優化
    public static void memoryOptimization() {
        // 使用原始類型包裝器時注意自動裝箱
        TreeSet<Integer> set = new TreeSet<>();
        
        // 避免不必要的對象創建
        for (int i = 0; i < 1000; i++) {
            set.add(i); // 會創建 Integer 對象
        }
        
        // 考慮使用專門的原始類型集合庫
        // 如 Eclipse Collections 的 IntSortedSet
    }
    
    // 4. 並發優化
    public static void concurrencyOptimization() {
        TreeSet<Integer> treeSet = new TreeSet<>();
        
        // 使用 ConcurrentSkipListSet 替代同步的 TreeSet
        ConcurrentSkipListSet<Integer> concurrentSet = new ConcurrentSkipListSet<>();
        
        // 或者使用讀寫鎖
        ReadWriteLock lock = new ReentrantReadWriteLock();
        ReadLock readLock = lock.readLock();
        WriteLock writeLock = lock.writeLock();
        
        // 讀操作
        readLock.lock();
        try {
            treeSet.contains(1);
        } finally {
            readLock.unlock();
        }
        
        // 寫操作
        writeLock.lock();
        try {
            treeSet.add(1);
        } finally {
            writeLock.unlock();
        }
    }
    
    private static int expensiveCalculation(String s) {
        // 模擬昂貴的計算
        return s.hashCode() * 31;
    }
}

實際應用場景

1. LeetCode 問題解決

public class TreeSetLeetCodeSolutions {
    
    // LeetCode 1845: 座位預約管理系統
    static class SeatManager {
        private TreeSet<Integer> availableSeats;
        
        public SeatManager(int n) {
            availableSeats = new TreeSet<>();
            for (int i = 1; i <= n; i++) {
                availableSeats.add(i);
            }
        }
        
        public int reserve() {
            return availableSeats.pollFirst();
        }
        
        public void unreserve(int seatNumber) {
            availableSeats.add(seatNumber);
        }
    }
    
    // LeetCode 855: 考場就座
    static class ExamRoom {
        private TreeSet<Integer> seats;
        private int n;
        
        public ExamRoom(int n) {
            this.n = n;
            this.seats = new TreeSet<>();
        }
        
        public int seat() {
            int seat = 0;
            if (!seats.isEmpty()) {
                int maxDistance = seats.first();
                
                // 檢查中間位置
                Integer prev = null;
                for (Integer s : seats) {
                    if (prev != null) {
                        int distance = (s - prev) / 2;
                        if (distance > maxDistance) {
                            maxDistance = distance;
                            seat = prev + distance;
                        }
                    }
                    prev = s;
                }
                
                // 檢查最後位置
                if (n - 1 - seats.last() > maxDistance) {
                    seat = n - 1;
                }
            }
            
            seats.add(seat);
            return seat;
        }
        
        public void leave(int p) {
            seats.remove(p);
        }
    }
    
    // LeetCode 895: 最大頻率棧
    static class FreqStack {
        private TreeSet<Element> elements;
        private Map<Integer, Integer> freq;
        private int timestamp;
        
        public FreqStack() {
            elements = new TreeSet<>((a, b) -> {
                if (a.frequency != b.frequency) {
                    return b.frequency - a.frequency; // 頻率降序
                }
                return b.timestamp - a.timestamp; // 時間降序
            });
            freq = new HashMap<>();
            timestamp = 0;
        }
        
        public void push(int x) {
            int oldFreq = freq.getOrDefault(x, 0);
            int newFreq = oldFreq + 1;
            
            if (oldFreq > 0) {
                elements.remove(new Element(x, oldFreq, -1));
            }
            
            elements.add(new Element(x, newFreq, timestamp++));
            freq.put(x, newFreq);
        }
        
        public int pop() {
            Element top = elements.pollFirst();
            int val = top.value;
            int newFreq = freq.get(val) - 1;
            
            if (newFreq > 0) {
                freq.put(val, newFreq);
                elements.add(new Element(val, newFreq, timestamp++));
            } else {
                freq.remove(val);
            }
            
            return val;
        }
        
        static class Element {
            int value;
            int frequency;
            int timestamp;
            
            Element(int value, int frequency, int timestamp) {
                this.value = value;
                this.frequency = frequency;
                this.timestamp = timestamp;
            }
            
            @Override
            public boolean equals(Object obj) {
                if (this == obj) return true;
                if (obj == null || getClass() != obj.getClass()) return false;
                Element element = (Element) obj;
                return value == element.value && frequency == element.frequency;
            }
            
            @Override
            public int hashCode() {
                return Objects.hash(value, frequency);
            }
        }
    }
    
    // LeetCode 1499: 滿足不等式的最大值
    public int findMaxValueOfEquation(int[][] points, int k) {
        // 使用 TreeSet 維護滑動窗口
        TreeSet<Point> window = new TreeSet<>((a, b) -> {
            if (a.yMinusX != b.yMinusX) {
                return b.yMinusX - a.yMinusX; // 按 y-x 降序
            }
            return a.x - b.x; // 按 x 升序
        });
        
        int maxValue = Integer.MIN_VALUE;
        
        for (int[] point : points) {
            int x = point[0];
            int y = point[1];
            
            // 移除窗口外的點
            window.removeIf(p -> x - p.x > k);
            
            // 如果窗口不為空，計算最大值
            if (!window.isEmpty()) {
                Point best = window.first();
                maxValue = Math.max(maxValue, y + x + best.yMinusX);
            }
            
            // 添加當前點
            window.add(new Point(x, y - x));
        }
        
        return maxValue;
    }
    
    static class Point {
        int x;
        int yMinusX;
        
        Point(int x, int yMinusX) {
            this.x = x;
            this.yMinusX = yMinusX;
        }
    }
}

2. 數據結構應用

public class TreeSetDataStructureApplications {
    
    // 滑動窗口最大值
    public static class SlidingWindowMaximum {
        private TreeSet<Element> window;
        private int windowSize;
        private int index;
        
        public SlidingWindowMaximum(int windowSize) {
            this.window = new TreeSet<>((a, b) -> {
                if (a.value != b.value) {
                    return b.value - a.value; // 值降序
                }
                return a.index - b.index; // 索引升序
            });
            this.windowSize = windowSize;
            this.index = 0;
        }
        
        public void addNumber(int num) {
            // 添加新元素
            window.add(new Element(num, index));
            
            // 移除窗口外的元素
            if (index >= windowSize) {
                window.removeIf(e -> e.index <= index - windowSize);
            }
            
            index++;
        }
        
        public int getMaximum() {
            return window.isEmpty() ? 0 : window.first().value;
        }
        
        static class Element {
            int value;
            int index;
            
            Element(int value, int index) {
                this.value = value;
                this.index = index;
            }
        }
    }
    
    // 動態中位數
    public static class DynamicMedian {
        private TreeSet<Element> elements;
        private int index;
        
        public DynamicMedian() {
            this.elements = new TreeSet<>((a, b) -> {
                if (a.value != b.value) {
                    return a.value - b.value; // 值升序
                }
                return a.index - b.index; // 索引升序
            });
            this.index = 0;
        }
        
        public void addNumber(int num) {
            elements.add(new Element(num, index++));
        }
        
        public double getMedian() {
            int size = elements.size();
            if (size == 0) return 0;
            
            List<Element> sortedElements = new ArrayList<>(elements);
            
            if (size % 2 == 1) {
                return sortedElements.get(size / 2).value;
            } else {
                return (sortedElements.get(size / 2 - 1).value + 
                        sortedElements.get(size / 2).value) / 2.0;
            }
        }
        
        static class Element {
            int value;
            int index;
            
            Element(int value, int index) {
                this.value = value;
                this.index = index;
            }
        }
    }
    
    // 區間調度
    public static class IntervalScheduler {
        private TreeSet<Interval> intervals;
        
        public IntervalScheduler() {
            this.intervals = new TreeSet<>(Comparator.comparing(Interval::getStart));
        }
        
        public boolean canSchedule(int start, int end) {
            Interval newInterval = new Interval(start, end);
            
            // 檢查是否與現有區間重疊
            Interval floor = intervals.floor(newInterval);
            if (floor != null && floor.getEnd() > start) {
                return false;
            }
            
            Interval ceiling = intervals.ceiling(newInterval);
            if (ceiling != null && ceiling.getStart() < end) {
                return false;
            }
            
            return true;
        }
        
        public boolean schedule(int start, int end) {
            if (canSchedule(start, end)) {
                intervals.add(new Interval(start, end));
                return true;
            }
            return false;
        }
        
        public List<Interval> getSchedule() {
            return new ArrayList<>(intervals);
        }
        
        static class Interval {
            private final int start;
            private final int end;
            
            public Interval(int start, int end) {
                this.start = start;
                this.end = end;
            }
            
            public int getStart() { return start; }
            public int getEnd() { return end; }
            
            @Override
            public boolean equals(Object obj) {
                if (this == obj) return true;
                if (obj == null || getClass() != obj.getClass()) return false;
                Interval interval = (Interval) obj;
                return start == interval.start && end == interval.end;
            }
            
            @Override
            public int hashCode() {
                return Objects.hash(start, end);
            }
        }
    }
}

最佳實踐與建議

1. 選擇適當的比較策略

public class TreeSetBestPractices {
    
    // 1. 自然排序 vs 自定義比較器
    public static void comparatorChoice() {
        // 對於實現 Comparable 的類型，使用自然排序
        TreeSet<String> naturalOrder = new TreeSet<>();
        
        // 對於需要自定義排序的情況，使用比較器
        TreeSet<String> customOrder = new TreeSet<>(String.CASE_INSENSITIVE_ORDER);
        
        // 複雜對象的多字段排序
        TreeSet<Person> personSet = new TreeSet<>(
            Comparator.comparing(Person::getAge)
                .thenComparing(Person::getName)
        );
    }
    
    // 2. 空值處理
    public static void nullHandling() {
        // TreeSet 不允許 null 元素
        TreeSet<String> set = new TreeSet<>();
        // set.add(null); // 會拋出 NullPointerException
        
        // 如果需要支持 null 值，使用自定義比較器
        TreeSet<String> nullSafeSet = new TreeSet<>((s1, s2) -> {
            if (s1 == null && s2 == null) return 0;
            if (s1 == null) return -1;
            if (s2 == null) return 1;
            return s1.compareTo(s2);
        });
    }
    
    // 3. 線程安全處理
    public static void threadSafety() {
        TreeSet<Integer> treeSet = new TreeSet<>();
        
        // 方法1：使用 Collections.synchronizedSet
        Set<Integer> syncSet = Collections.synchronizedSet(treeSet);
        
        // 方法2：使用 ConcurrentSkipListSet
        ConcurrentSkipListSet<Integer> concurrentSet = new ConcurrentSkipListSet<>();
        
        // 方法3：使用讀寫鎖
        ReadWriteLock lock = new ReentrantReadWriteLock();
        // 在讀寫操作時使用相應的鎖
    }
    
    // 4. 效能考慮
    public static void performanceConsiderations() {
        // 批量添加比單個添加效率更高
        Collection<Integer> data = Arrays.asList(1, 2, 3, 4, 5);
        TreeSet<Integer> treeSet = new TreeSet<>(data);
        
        // 避免頻繁的範圍查詢操作
        NavigableSet<Integer> subSet = treeSet.subSet(2, true, 4, false);
        // 對 subSet 的操作會影響原始 set
    }
    
    static class Person {
        private String name;
        private int age;
        
        public Person(String name, int age) {
            this.name = name;
            this.age = age;
        }
        
        public String getName() { return name; }
        public int getAge() { return age; }
    }
}

2. 常見錯誤避免

public class TreeSetCommonMistakes {
    
    // 錯誤1：在迭代過程中修改 TreeSet
    public static void avoidConcurrentModification() {
        TreeSet<Integer> set = new TreeSet<>();
        for (int i = 0; i < 10; i++) {
            set.add(i);
        }
        
        // 錯誤的做法
        // for (Integer value : set) {
        //     if (value % 2 == 0) {
        //         set.remove(value); // ConcurrentModificationException
        //     }
        // }
        
        // 正確的做法1：使用迭代器
        Iterator<Integer> iterator = set.iterator();
        while (iterator.hasNext()) {
            if (iterator.next() % 2 == 0) {
                iterator.remove();
            }
        }
        
        // 正確的做法2：收集要刪除的元素
        Set<Integer> toRemove = set.stream()
                .filter(value -> value % 2 == 0)
                .collect(Collectors.toSet());
        set.removeAll(toRemove);
    }
    
    // 錯誤2：比較器不一致
    public static void avoidInconsistentComparator() {
        // 錯誤：比較器與 equals 不一致
        TreeSet<String> badSet = new TreeSet<>((s1, s2) -> {
            return s1.length() - s2.length(); // 只比較長度
        });
        
        badSet.add("abc");
        badSet.add("def"); // 會被忽略，因為長度相同
        
        // 正確：確保比較器一致性
        TreeSet<String> goodSet = new TreeSet<>((s1, s2) -> {
            int lengthCompare = s1.length() - s2.length();
            if (lengthCompare != 0) {
                return lengthCompare;
            }
            return s1.compareTo(s2); // 長度相同時比較內容
        });
    }
    
    // 錯誤3：誤用子集合
    public static void avoidSubSetMisuse() {
        TreeSet<Integer> set = new TreeSet<>();
        for (int i = 0; i < 10; i++) {
            set.add(i);
        }
        
        // 錯誤：認為子集合是獨立的
        NavigableSet<Integer> subSet = set.subSet(2, true, 8, false);
        subSet.clear(); // 這會影響原始 set
        
        // 正確：如果需要獨立的副本
        NavigableSet<Integer> independentCopy = new TreeSet<>(subSet);
    }
}

總結

TreeSet 是 Java 集合框架中功能強大的有序集合實現，基於紅黑樹提供了 O(log n) 的高效操作。通過本文的深入分析，我們了解了：

Reactive Programming 完整指南：Spring WebFlux 與 Project Reactor

Wed, 01 Dec 2021 22:13:40 +0800

概述

Reactive Programming（響應式程式設計）是一種基於資料流和變化傳播的程式設計模式。在 Java 生態系統中，Project Reactor 是實現響應式程式設計的核心函式庫，而 Spring WebFlux 則建立在其之上，提供非阻塞式的 Web 應用程式開發能力。

核心概念

什麼是 Reactive Programming？

響應式程式設計的核心特徵：

非阻塞（Non-blocking）：執行緒不會被 I/O 操作阻塞
事件驅動（Event-driven）：基於事件流處理資料
背壓支援（Backpressure）：自動處理生產者和消費者之間的速度差異
彈性（Resilient）：具備錯誤處理和恢復能力
響應性（Responsive）：快速回應使用者請求

Reactive Streams 規範

Reactive Streams 定義了四個核心介面：

public interface Publisher<T> {
    void subscribe(Subscriber<? super T> s);
}

public interface Subscriber<T> {
    void onSubscribe(Subscription s);
    void onNext(T t);
    void onError(Throwable t);
    void onComplete();
}

public interface Subscription {
    void request(long n);
    void cancel();
}

public interface Processor<T, R> extends Subscriber<T>, Publisher<R> {
}

Project Reactor 基礎

Mono 與 Flux

Project Reactor 提供兩個核心類型：

Java TreeMap 完整實作指南：紅黑樹有序映射與 NavigableMap 介面詳解

Sun, 31 Oct 2021 19:16:31 +0800

Java TreeMap 完整實作指南

簡介

TreeMap 是 Java 集合框架中實現有序映射的核心類別，基於紅黑樹（Red-Black Tree）數據結構實現。它提供了 O(log n) 的時間複雜度進行搜索、插入和刪除操作，並保證鍵的有序性。本文將深入探討 TreeMap 的內部實現、各種方法使用、效能特性以及在企業級開發中的最佳實踐。

TreeMap 架構與繼承關係

類別繼承結構

Map<K,V>
   ↑
SortedMap<K,V> 
   ↑
NavigableMap<K,V>
   ↑
TreeMap<K,V>

核心介面關係

// 基本映射介面
public interface Map<K,V> {
    V put(K key, V value);
    V get(Object key);
    V remove(Object key);
    boolean containsKey(Object key);
    Set<K> keySet();
    Collection<V> values();
    Set<Map.Entry<K, V>> entrySet();
}

// 有序映射介面
public interface SortedMap<K,V> extends Map<K,V> {
    Comparator<? super K> comparator();
    SortedMap<K,V> subMap(K fromKey, K toKey);
    SortedMap<K,V> headMap(K toKey);
    SortedMap<K,V> tailMap(K fromKey);
    K firstKey();
    K lastKey();
}

// 可導航映射介面
public interface NavigableMap<K,V> extends SortedMap<K,V> {
    Map.Entry<K,V> lowerEntry(K key);
    K lowerKey(K key);
    Map.Entry<K,V> floorEntry(K key);
    K floorKey(K key);
    Map.Entry<K,V> ceilingEntry(K key);
    K ceilingKey(K key);
    Map.Entry<K,V> higherEntry(K key);
    K higherKey(K key);
    Map.Entry<K,V> firstEntry();
    Map.Entry<K,V> lastEntry();
    Map.Entry<K,V> pollFirstEntry();
    Map.Entry<K,V> pollLastEntry();
    NavigableMap<K,V> descendingMap();
    NavigableSet<K> navigableKeySet();
    NavigableSet<K> descendingKeySet();
}

TreeMap 核心特性

1. 紅黑樹實現

// TreeMap 內部節點結構
static final class Entry<K,V> implements Map.Entry<K,V> {
    K key;
    V value;
    Entry<K,V> left;
    Entry<K,V> right;
    Entry<K,V> parent;
    boolean color = BLACK;
    
    Entry(K key, V value, Entry<K,V> parent) {
        this.key = key;
        this.value = value;
        this.parent = parent;
    }
}

// 紅黑樹顏色常量
private static final boolean RED = false;
private static final boolean BLACK = true;

// 根節點和大小
private transient Entry<K,V> root;
private transient int size = 0;
private transient int modCount = 0;

// 比較器
private final Comparator<? super K> comparator;

2. 自然排序與自定義比較器

// 自然排序 TreeMap
TreeMap<String, Integer> naturalOrder = new TreeMap<>();
naturalOrder.put("Charlie", 3);
naturalOrder.put("Alice", 1);
naturalOrder.put("Bob", 2);
// 結果：{Alice=1, Bob=2, Charlie=3}

// 自定義比較器
TreeMap<String, Integer> customOrder = new TreeMap<>(
    (s1, s2) -> s2.compareTo(s1) // 降序
);
customOrder.put("Charlie", 3);
customOrder.put("Alice", 1);
customOrder.put("Bob", 2);
// 結果：{Charlie=3, Bob=2, Alice=1}

// 複雜對象比較器
TreeMap<Student, String> studentMap = new TreeMap<>(
    Comparator.comparing(Student::getGrade)
        .thenComparing(Student::getName)
);

SortedMap 介面詳解

基本方法實現

public class TreeMapSortedExample {
    
    public static void main(String[] args) {
        TreeMap<Integer, String> treeMap = new TreeMap<>();
        
        // 添加元素
        treeMap.put(5, "Five");
        treeMap.put(2, "Two");
        treeMap.put(8, "Eight");
        treeMap.put(1, "One");
        treeMap.put(9, "Nine");
        
        // 基本排序方法
        demonstrateSortedMapMethods(treeMap);
    }
    
    private static void demonstrateSortedMapMethods(TreeMap<Integer, String> map) {
        System.out.println("Original map: " + map);
        
        // 獲取比較器
        Comparator<? super Integer> comparator = map.comparator();
        System.out.println("Comparator: " + comparator); // null (natural ordering)
        
        // 第一個和最後一個鍵
        System.out.println("First key: " + map.firstKey()); // 1
        System.out.println("Last key: " + map.lastKey());   // 9
        
        // 子映射（含頭不含尾）
        SortedMap<Integer, String> subMap = map.subMap(2, 8);
        System.out.println("SubMap [2, 8): " + subMap); // {2=Two, 5=Five}
        
        // 頭部映射（不包含指定鍵）
        SortedMap<Integer, String> headMap = map.headMap(5);
        System.out.println("HeadMap (< 5): " + headMap); // {1=One, 2=Two}
        
        // 尾部映射（包含指定鍵）
        SortedMap<Integer, String> tailMap = map.tailMap(5);
        System.out.println("TailMap (>= 5): " + tailMap); // {5=Five, 8=Eight, 9=Nine}
        
        // 鍵集合、值集合、條目集合
        System.out.println("Keys: " + map.keySet());
        System.out.println("Values: " + map.values());
        System.out.println("Entries: " + map.entrySet());
    }
}

NavigableMap 介面詳解

導航方法實現

public class TreeMapNavigableExample {
    
    public static void main(String[] args) {
        TreeMap<Integer, String> treeMap = new TreeMap<>();
        
        // 添加測試數據
        treeMap.put(1, "One");
        treeMap.put(3, "Three");
        treeMap.put(5, "Five");
        treeMap.put(7, "Seven");
        treeMap.put(9, "Nine");
        
        demonstrateNavigableMethods(treeMap);
    }
    
    private static void demonstrateNavigableMethods(TreeMap<Integer, String> map) {
        System.out.println("Original map: " + map);
        
        // Lower 方法：返回嚴格小於指定鍵的最大鍵
        Map.Entry<Integer, String> lowerEntry = map.lowerEntry(5);
        System.out.println("Lower entry (< 5): " + lowerEntry); // 3=Three
        
        Integer lowerKey = map.lowerKey(5);
        System.out.println("Lower key (< 5): " + lowerKey); // 3
        
        // Floor 方法：返回小於或等於指定鍵的最大鍵
        Map.Entry<Integer, String> floorEntry = map.floorEntry(4);
        System.out.println("Floor entry (<= 4): " + floorEntry); // 3=Three
        
        Map.Entry<Integer, String> floorEntry2 = map.floorEntry(5);
        System.out.println("Floor entry (<= 5): " + floorEntry2); // 5=Five
        
        // Ceiling 方法：返回大於或等於指定鍵的最小鍵
        Map.Entry<Integer, String> ceilingEntry = map.ceilingEntry(4);
        System.out.println("Ceiling entry (>= 4): " + ceilingEntry); // 5=Five
        
        Map.Entry<Integer, String> ceilingEntry2 = map.ceilingEntry(5);
        System.out.println("Ceiling entry (>= 5): " + ceilingEntry2); // 5=Five
        
        // Higher 方法：返回嚴格大於指定鍵的最小鍵
        Map.Entry<Integer, String> higherEntry = map.higherEntry(5);
        System.out.println("Higher entry (> 5): " + higherEntry); // 7=Seven
        
        // 首尾條目
        Map.Entry<Integer, String> firstEntry = map.firstEntry();
        Map.Entry<Integer, String> lastEntry = map.lastEntry();
        System.out.println("First entry: " + firstEntry); // 1=One
        System.out.println("Last entry: " + lastEntry);   // 9=Nine
        
        // 彈出首尾條目（會刪除元素）
        TreeMap<Integer, String> copyMap = new TreeMap<>(map);
        Map.Entry<Integer, String> pollFirst = copyMap.pollFirstEntry();
        Map.Entry<Integer, String> pollLast = copyMap.pollLastEntry();
        System.out.println("Poll first: " + pollFirst); // 1=One
        System.out.println("Poll last: " + pollLast);   // 9=Nine
        System.out.println("After polling: " + copyMap); // {3=Three, 5=Five, 7=Seven}
        
        // 降序視圖
        NavigableMap<Integer, String> descendingMap = map.descendingMap();
        System.out.println("Descending map: " + descendingMap);
        
        // 導航鍵集合
        NavigableSet<Integer> navigableKeySet = map.navigableKeySet();
        NavigableSet<Integer> descendingKeySet = map.descendingKeySet();
        System.out.println("Navigable key set: " + navigableKeySet);
        System.out.println("Descending key set: " + descendingKeySet);
        
        // 範圍視圖
        NavigableMap<Integer, String> rangeMap = map.subMap(3, true, 7, false);
        System.out.println("Range [3, 7): " + rangeMap); // {3=Three, 5=Five}
        
        NavigableMap<Integer, String> headMap = map.headMap(5, true);
        System.out.println("Head map (<= 5): " + headMap); // {1=One, 3=Three, 5=Five}
        
        NavigableMap<Integer, String> tailMap = map.tailMap(5, false);
        System.out.println("Tail map (> 5): " + tailMap); // {7=Seven, 9=Nine}
    }
}

企業級應用實例

1. 時間序列數據管理

public class TimeSeriesDataManager {
    
    private final TreeMap<LocalDateTime, Double> timeSeriesData;
    
    public TimeSeriesDataManager() {
        this.timeSeriesData = new TreeMap<>();
    }
    
    // 添加數據點
    public void addDataPoint(LocalDateTime timestamp, Double value) {
        timeSeriesData.put(timestamp, value);
    }
    
    // 獲取指定時間範圍的數據
    public NavigableMap<LocalDateTime, Double> getDataInRange(
            LocalDateTime startTime, LocalDateTime endTime) {
        return timeSeriesData.subMap(startTime, true, endTime, true);
    }
    
    // 獲取最新數據
    public Map.Entry<LocalDateTime, Double> getLatestData() {
        return timeSeriesData.lastEntry();
    }
    
    // 獲取指定時間之前的最新數據
    public Map.Entry<LocalDateTime, Double> getLatestDataBefore(LocalDateTime time) {
        return timeSeriesData.lowerEntry(time);
    }
    
    // 獲取指定時間之後的最早數據
    public Map.Entry<LocalDateTime, Double> getEarliestDataAfter(LocalDateTime time) {
        return timeSeriesData.higherEntry(time);
    }
    
    // 計算時間範圍內的平均值
    public double getAverageInRange(LocalDateTime startTime, LocalDateTime endTime) {
        NavigableMap<LocalDateTime, Double> rangeData = getDataInRange(startTime, endTime);
        return rangeData.values().stream()
                .mapToDouble(Double::doubleValue)
                .average()
                .orElse(0.0);
    }
    
    // 清理舊數據
    public void cleanupOldData(LocalDateTime cutoffTime) {
        timeSeriesData.headMap(cutoffTime, false).clear();
    }
    
    // 獲取數據統計信息
    public DataStatistics getStatistics() {
        if (timeSeriesData.isEmpty()) {
            return new DataStatistics();
        }
        
        DoubleSummaryStatistics stats = timeSeriesData.values().stream()
                .mapToDouble(Double::doubleValue)
                .summaryStatistics();
        
        return new DataStatistics(
            timeSeriesData.firstKey(),
            timeSeriesData.lastKey(),
            stats.getCount(),
            stats.getMin(),
            stats.getMax(),
            stats.getAverage()
        );
    }
    
    public static class DataStatistics {
        private final LocalDateTime earliestTime;
        private final LocalDateTime latestTime;
        private final long count;
        private final double min;
        private final double max;
        private final double average;
        
        public DataStatistics() {
            this(null, null, 0, 0, 0, 0);
        }
        
        public DataStatistics(LocalDateTime earliestTime, LocalDateTime latestTime, 
                            long count, double min, double max, double average) {
            this.earliestTime = earliestTime;
            this.latestTime = latestTime;
            this.count = count;
            this.min = min;
            this.max = max;
            this.average = average;
        }
        
        // Getters
        public LocalDateTime getEarliestTime() { return earliestTime; }
        public LocalDateTime getLatestTime() { return latestTime; }
        public long getCount() { return count; }
        public double getMin() { return min; }
        public double getMax() { return max; }
        public double getAverage() { return average; }
    }
}

2. 範圍查詢系統

public class RangeQuerySystem<T extends Comparable<T>, V> {
    
    private final TreeMap<T, V> dataMap;
    private final ReentrantReadWriteLock lock;
    private final ReadLock readLock;
    private final WriteLock writeLock;
    
    public RangeQuerySystem() {
        this.dataMap = new TreeMap<>();
        this.lock = new ReentrantReadWriteLock();
        this.readLock = lock.readLock();
        this.writeLock = lock.writeLock();
    }
    
    // 線程安全的插入操作
    public void put(T key, V value) {
        writeLock.lock();
        try {
            dataMap.put(key, value);
        } finally {
            writeLock.unlock();
        }
    }
    
    // 線程安全的獲取操作
    public V get(T key) {
        readLock.lock();
        try {
            return dataMap.get(key);
        } finally {
            readLock.unlock();
        }
    }
    
    // 範圍查詢
    public List<Map.Entry<T, V>> rangeQuery(T start, T end) {
        readLock.lock();
        try {
            return new ArrayList<>(dataMap.subMap(start, true, end, true).entrySet());
        } finally {
            readLock.unlock();
        }
    }
    
    // 前綴查詢
    public List<Map.Entry<T, V>> prefixQuery(T prefix) {
        readLock.lock();
        try {
            NavigableMap<T, V> tailMap = dataMap.tailMap(prefix, true);
            List<Map.Entry<T, V>> result = new ArrayList<>();
            
            for (Map.Entry<T, V> entry : tailMap.entrySet()) {
                if (entry.getKey().toString().startsWith(prefix.toString())) {
                    result.add(entry);
                } else {
                    break;
                }
            }
            
            return result;
        } finally {
            readLock.unlock();
        }
    }
    
    // 獲取最接近的值
    public Map.Entry<T, V> getClosest(T target) {
        readLock.lock();
        try {
            Map.Entry<T, V> floor = dataMap.floorEntry(target);
            Map.Entry<T, V> ceiling = dataMap.ceilingEntry(target);
            
            if (floor == null) return ceiling;
            if (ceiling == null) return floor;
            
            // 比較距離
            if (target.compareTo(floor.getKey()) <= ceiling.getKey().compareTo(target)) {
                return floor;
            } else {
                return ceiling;
            }
        } finally {
            readLock.unlock();
        }
    }
    
    // 批量插入
    public void putAll(Map<T, V> map) {
        writeLock.lock();
        try {
            dataMap.putAll(map);
        } finally {
            writeLock.unlock();
        }
    }
    
    // 條件刪除
    public int removeIf(Predicate<Map.Entry<T, V>> condition) {
        writeLock.lock();
        try {
            List<T> keysToRemove = dataMap.entrySet().stream()
                    .filter(condition)
                    .map(Map.Entry::getKey)
                    .collect(Collectors.toList());
            
            keysToRemove.forEach(dataMap::remove);
            return keysToRemove.size();
        } finally {
            writeLock.unlock();
        }
    }
    
    // 獲取統計信息
    public RangeStatistics getStatistics() {
        readLock.lock();
        try {
            return new RangeStatistics(
                dataMap.size(),
                dataMap.isEmpty() ? null : dataMap.firstKey(),
                dataMap.isEmpty() ? null : dataMap.lastKey()
            );
        } finally {
            readLock.unlock();
        }
    }
    
    public static class RangeStatistics {
        private final int size;
        private final Object minKey;
        private final Object maxKey;
        
        public RangeStatistics(int size, Object minKey, Object maxKey) {
            this.size = size;
            this.minKey = minKey;
            this.maxKey = maxKey;
        }
        
        // Getters
        public int getSize() { return size; }
        public Object getMinKey() { return minKey; }
        public Object getMaxKey() { return maxKey; }
    }
}

3. 優先級任務調度器

public class PriorityTaskScheduler {
    
    private final TreeMap<Priority, Queue<Task>> taskQueues;
    private final ExecutorService executor;
    private final ScheduledExecutorService scheduler;
    private final AtomicBoolean running;
    
    public PriorityTaskScheduler(int threadPoolSize) {
        this.taskQueues = new TreeMap<>();
        this.executor = Executors.newFixedThreadPool(threadPoolSize);
        this.scheduler = Executors.newScheduledThreadPool(2);
        this.running = new AtomicBoolean(true);
        
        // 初始化優先級隊列
        for (Priority priority : Priority.values()) {
            taskQueues.put(priority, new ConcurrentLinkedQueue<>());
        }
        
        // 啟動任務調度
        startTaskScheduling();
    }
    
    // 提交任務
    public void submitTask(Task task) {
        if (!running.get()) {
            throw new IllegalStateException("Scheduler is shutdown");
        }
        
        taskQueues.get(task.getPriority()).offer(task);
    }
    
    // 提交延遲任務
    public void submitDelayedTask(Task task, long delay, TimeUnit unit) {
        scheduler.schedule(() -> submitTask(task), delay, unit);
    }
    
    // 提交週期性任務
    public void submitPeriodicTask(Task task, long initialDelay, long period, TimeUnit unit) {
        scheduler.scheduleAtFixedRate(() -> {
            if (running.get()) {
                submitTask(task);
            }
        }, initialDelay, period, unit);
    }
    
    // 啟動任務調度
    private void startTaskScheduling() {
        scheduler.scheduleAtFixedRate(this::processNextTask, 0, 10, TimeUnit.MILLISECONDS);
    }
    
    // 處理下一個任務
    private void processNextTask() {
        if (!running.get()) {
            return;
        }
        
        // 從最高優先級開始查找任務
        NavigableMap<Priority, Queue<Task>> descendingMap = taskQueues.descendingMap();
        
        for (Map.Entry<Priority, Queue<Task>> entry : descendingMap.entrySet()) {
            Queue<Task> queue = entry.getValue();
            Task task = queue.poll();
            
            if (task != null) {
                executor.submit(new TaskRunner(task));
                return;
            }
        }
    }
    
    // 獲取隊列統計信息
    public QueueStatistics getQueueStatistics() {
        Map<Priority, Integer> queueSizes = new EnumMap<>(Priority.class);
        int totalTasks = 0;
        
        for (Map.Entry<Priority, Queue<Task>> entry : taskQueues.entrySet()) {
            int size = entry.getValue().size();
            queueSizes.put(entry.getKey(), size);
            totalTasks += size;
        }
        
        return new QueueStatistics(queueSizes, totalTasks);
    }
    
    // 清空指定優先級的任務
    public int clearTasks(Priority priority) {
        Queue<Task> queue = taskQueues.get(priority);
        int size = queue.size();
        queue.clear();
        return size;
    }
    
    // 關閉調度器
    public void shutdown() {
        running.set(false);
        executor.shutdown();
        scheduler.shutdown();
        
        try {
            if (!executor.awaitTermination(30, TimeUnit.SECONDS)) {
                executor.shutdownNow();
            }
            if (!scheduler.awaitTermination(30, TimeUnit.SECONDS)) {
                scheduler.shutdownNow();
            }
        } catch (InterruptedException e) {
            executor.shutdownNow();
            scheduler.shutdownNow();
            Thread.currentThread().interrupt();
        }
    }
    
    // 優先級枚舉
    public enum Priority {
        LOW(1), NORMAL(2), HIGH(3), CRITICAL(4);
        
        private final int value;
        
        Priority(int value) {
            this.value = value;
        }
        
        public int getValue() {
            return value;
        }
    }
    
    // 任務介面
    public interface Task {
        void execute();
        Priority getPriority();
        String getName();
    }
    
    // 任務運行器
    private static class TaskRunner implements Runnable {
        private final Task task;
        
        public TaskRunner(Task task) {
            this.task = task;
        }
        
        @Override
        public void run() {
            try {
                task.execute();
            } catch (Exception e) {
                System.err.println("Task execution failed: " + task.getName());
                e.printStackTrace();
            }
        }
    }
    
    // 隊列統計信息
    public static class QueueStatistics {
        private final Map<Priority, Integer> queueSizes;
        private final int totalTasks;
        
        public QueueStatistics(Map<Priority, Integer> queueSizes, int totalTasks) {
            this.queueSizes = queueSizes;
            this.totalTasks = totalTasks;
        }
        
        public Map<Priority, Integer> getQueueSizes() { return queueSizes; }
        public int getTotalTasks() { return totalTasks; }
    }
}

效能分析與優化

1. 時間複雜度分析

public class TreeMapPerformanceAnalysis {
    
    public static void main(String[] args) {
        performanceComparison();
        memoryAnalysis();
        concurrencyTest();
    }
    
    // 效能比較
    private static void performanceComparison() {
        int[] sizes = {1000, 10000, 100000, 1000000};
        
        for (int size : sizes) {
            System.out.println("Size: " + size);
            
            // TreeMap 測試
            long startTime = System.nanoTime();
            TreeMap<Integer, String> treeMap = new TreeMap<>();
            for (int i = 0; i < size; i++) {
                treeMap.put(i, "value" + i);
            }
            long treeMapInsertTime = System.nanoTime() - startTime;
            
            // 搜索測試
            startTime = System.nanoTime();
            for (int i = 0; i < 1000; i++) {
                treeMap.get(i * size / 1000);
            }
            long treeMapSearchTime = System.nanoTime() - startTime;
            
            // HashMap 比較
            startTime = System.nanoTime();
            HashMap<Integer, String> hashMap = new HashMap<>();
            for (int i = 0; i < size; i++) {
                hashMap.put(i, "value" + i);
            }
            long hashMapInsertTime = System.nanoTime() - startTime;
            
            startTime = System.nanoTime();
            for (int i = 0; i < 1000; i++) {
                hashMap.get(i * size / 1000);
            }
            long hashMapSearchTime = System.nanoTime() - startTime;
            
            System.out.printf("TreeMap - Insert: %d ns, Search: %d ns\n", 
                            treeMapInsertTime, treeMapSearchTime);
            System.out.printf("HashMap - Insert: %d ns, Search: %d ns\n\n", 
                            hashMapInsertTime, hashMapSearchTime);
        }
    }
    
    // 記憶體分析
    private static void memoryAnalysis() {
        Runtime runtime = Runtime.getRuntime();
        
        runtime.gc();
        long beforeMemory = runtime.totalMemory() - runtime.freeMemory();
        
        TreeMap<Integer, String> treeMap = new TreeMap<>();
        for (int i = 0; i < 100000; i++) {
            treeMap.put(i, "value" + i);
        }
        
        long afterMemory = runtime.totalMemory() - runtime.freeMemory();
        System.out.println("TreeMap memory usage: " + (afterMemory - beforeMemory) + " bytes");
        
        // 對比 HashMap
        runtime.gc();
        beforeMemory = runtime.totalMemory() - runtime.freeMemory();
        
        HashMap<Integer, String> hashMap = new HashMap<>();
        for (int i = 0; i < 100000; i++) {
            hashMap.put(i, "value" + i);
        }
        
        afterMemory = runtime.totalMemory() - runtime.freeMemory();
        System.out.println("HashMap memory usage: " + (afterMemory - beforeMemory) + " bytes");
    }
    
    // 並發測試
    private static void concurrencyTest() {
        TreeMap<Integer, String> treeMap = new TreeMap<>();
        ConcurrentSkipListMap<Integer, String> concurrentMap = new ConcurrentSkipListMap<>();
        
        // 填充初始數據
        for (int i = 0; i < 10000; i++) {
            treeMap.put(i, "value" + i);
            concurrentMap.put(i, "value" + i);
        }
        
        // 並發讀取測試
        int threadCount = 4;
        ExecutorService executor = Executors.newFixedThreadPool(threadCount);
        
        System.out.println("Concurrent read test:");
        
        // TreeMap 同步讀取
        long startTime = System.nanoTime();
        CountDownLatch latch = new CountDownLatch(threadCount);
        
        for (int i = 0; i < threadCount; i++) {
            executor.submit(() -> {
                try {
                    for (int j = 0; j < 10000; j++) {
                        synchronized (treeMap) {
                            treeMap.get(j);
                        }
                    }
                } finally {
                    latch.countDown();
                }
            });
        }
        
        try {
            latch.await();
        } catch (InterruptedException e) {
            Thread.currentThread().interrupt();
        }
        
        long treeMapTime = System.nanoTime() - startTime;
        System.out.println("TreeMap (synchronized): " + treeMapTime + " ns");
        
        // ConcurrentSkipListMap 測試
        startTime = System.nanoTime();
        latch = new CountDownLatch(threadCount);
        
        for (int i = 0; i < threadCount; i++) {
            executor.submit(() -> {
                try {
                    for (int j = 0; j < 10000; j++) {
                        concurrentMap.get(j);
                    }
                } finally {
                    latch.countDown();
                }
            });
        }
        
        try {
            latch.await();
        } catch (InterruptedException e) {
            Thread.currentThread().interrupt();
        }
        
        long concurrentMapTime = System.nanoTime() - startTime;
        System.out.println("ConcurrentSkipListMap: " + concurrentMapTime + " ns");
        
        executor.shutdown();
    }
}

2. 最佳化建議

public class TreeMapOptimizationTips {
    
    // 1. 使用適當的比較器
    public static void comparatorOptimization() {
        // 避免在比較器中進行複雜計算
        TreeMap<String, Integer> badExample = new TreeMap<>((s1, s2) -> {
            // 壞例子：每次比較都進行昂貴的計算
            return expensiveCalculation(s1) - expensiveCalculation(s2);
        });
        
        // 好例子：預先計算或使用緩存
        Map<String, Integer> cache = new ConcurrentHashMap<>();
        TreeMap<String, Integer> goodExample = new TreeMap<>((s1, s2) -> {
            int val1 = cache.computeIfAbsent(s1, TreeMapOptimizationTips::expensiveCalculation);
            int val2 = cache.computeIfAbsent(s2, TreeMapOptimizationTips::expensiveCalculation);
            return val1 - val2;
        });
    }
    
    // 2. 批量操作優化
    public static void batchOperationOptimization() {
        TreeMap<Integer, String> treeMap = new TreeMap<>();
        
        // 批量插入比單個插入效率更高
        Map<Integer, String> batchData = new HashMap<>();
        for (int i = 0; i < 1000; i++) {
            batchData.put(i, "value" + i);
        }
        treeMap.putAll(batchData);
        
        // 使用子映射進行批量操作
        NavigableMap<Integer, String> subMap = treeMap.subMap(100, true, 200, false);
        subMap.clear(); // 比逐個刪除效率更高
    }
    
    // 3. 記憶體優化
    public static void memoryOptimization() {
        // 使用原始類型包裝器時注意自動裝箱
        TreeMap<Integer, Integer> map = new TreeMap<>();
        
        // 避免不必要的對象創建
        for (int i = 0; i < 1000; i++) {
            map.put(i, i * 2); // 會創建 Integer 對象
        }
        
        // 考慮使用專門的原始類型集合庫（如 Eclipse Collections）
        // 或者使用 TIntIntMap 等原始類型映射
    }
    
    // 4. 並發優化
    public static void concurrencyOptimization() {
        TreeMap<Integer, String> treeMap = new TreeMap<>();
        
        // 使用 ConcurrentSkipListMap 替代同步的 TreeMap
        ConcurrentSkipListMap<Integer, String> concurrentMap = new ConcurrentSkipListMap<>();
        
        // 或者使用讀寫鎖
        ReadWriteLock lock = new ReentrantReadWriteLock();
        ReadLock readLock = lock.readLock();
        WriteLock writeLock = lock.writeLock();
        
        // 讀操作
        readLock.lock();
        try {
            treeMap.get(1);
        } finally {
            readLock.unlock();
        }
        
        // 寫操作
        writeLock.lock();
        try {
            treeMap.put(1, "value");
        } finally {
            writeLock.unlock();
        }
    }
    
    private static int expensiveCalculation(String s) {
        // 模擬昂貴的計算
        return s.hashCode() * 31;
    }
}

實際應用場景

1. LeetCode 問題解決

public class TreeMapLeetCodeSolutions {
    
    // LeetCode 2055: 蠟燭之間的盤子
    public int[] platesBetweenCandles(String s, int[][] queries) {
        TreeMap<Integer, Integer> candlePositions = new TreeMap<>();
        
        // 記錄蠟燭位置
        for (int i = 0; i < s.length(); i++) {
            if (s.charAt(i) == '|') {
                candlePositions.put(i, i);
            }
        }
        
        int[] result = new int[queries.length];
        
        for (int i = 0; i < queries.length; i++) {
            int left = queries[i][0];
            int right = queries[i][1];
            
            // 找到範圍內的第一個和最後一個蠟燭
            Integer firstCandle = candlePositions.ceilingKey(left);
            Integer lastCandle = candlePositions.floorKey(right);
            
            if (firstCandle != null && lastCandle != null && firstCandle <= lastCandle) {
                // 計算蠟燭之間的盤子數量
                int totalLength = lastCandle - firstCandle + 1;
                int candleCount = candlePositions.subMap(firstCandle, true, lastCandle, true).size();
                result[i] = totalLength - candleCount;
            } else {
                result[i] = 0;
            }
        }
        
        return result;
    }
    
    // LeetCode 220: 存在重複元素 III
    public boolean containsNearbyAlmostDuplicate(int[] nums, int k, int t) {
        TreeMap<Integer, Integer> window = new TreeMap<>();
        
        for (int i = 0; i < nums.length; i++) {
            int num = nums[i];
            
            // 查找是否存在差值小於等於 t 的數字
            Integer floor = window.floorKey(num);
            Integer ceiling = window.ceilingKey(num);
            
            if ((floor != null && (long) num - floor <= t) || 
                (ceiling != null && (long) ceiling - num <= t)) {
                return true;
            }
            
            // 添加當前數字到窗口
            window.put(num, window.getOrDefault(num, 0) + 1);
            
            // 維護窗口大小
            if (i >= k) {
                int oldNum = nums[i - k];
                window.put(oldNum, window.get(oldNum) - 1);
                if (window.get(oldNum) == 0) {
                    window.remove(oldNum);
                }
            }
        }
        
        return false;
    }
    
    // LeetCode 732: 我的日程安排表 III
    static class MyCalendarThree {
        private TreeMap<Integer, Integer> timeline;
        
        public MyCalendarThree() {
            timeline = new TreeMap<>();
        }
        
        public int book(int start, int end) {
            timeline.put(start, timeline.getOrDefault(start, 0) + 1);
            timeline.put(end, timeline.getOrDefault(end, 0) - 1);
            
            int activeEvents = 0;
            int maxEvents = 0;
            
            for (int count : timeline.values()) {
                activeEvents += count;
                maxEvents = Math.max(maxEvents, activeEvents);
            }
            
            return maxEvents;
        }
    }
}

2. 分佈式系統中的應用

public class DistributedSystemApplications {
    
    // 一致性哈希環
    public static class ConsistentHashRing {
        private final TreeMap<Long, String> ring;
        private final int virtualNodes;
        
        public ConsistentHashRing(int virtualNodes) {
            this.ring = new TreeMap<>();
            this.virtualNodes = virtualNodes;
        }
        
        public void addNode(String node) {
            for (int i = 0; i < virtualNodes; i++) {
                long hash = hash(node + ":" + i);
                ring.put(hash, node);
            }
        }
        
        public void removeNode(String node) {
            for (int i = 0; i < virtualNodes; i++) {
                long hash = hash(node + ":" + i);
                ring.remove(hash);
            }
        }
        
        public String getNode(String key) {
            if (ring.isEmpty()) {
                return null;
            }
            
            long hash = hash(key);
            Map.Entry<Long, String> entry = ring.ceilingEntry(hash);
            
            if (entry == null) {
                entry = ring.firstEntry();
            }
            
            return entry.getValue();
        }
        
        private long hash(String key) {
            return key.hashCode() & 0xFFFFFFFFL;
        }
    }
    
    // 負載平衡器
    public static class LoadBalancer {
        private final TreeMap<Integer, List<String>> weightedServers;
        private final AtomicInteger currentWeight;
        
        public LoadBalancer() {
            this.weightedServers = new TreeMap<>();
            this.currentWeight = new AtomicInteger(0);
        }
        
        public void addServer(String server, int weight) {
            weightedServers.computeIfAbsent(weight, k -> new ArrayList<>()).add(server);
        }
        
        public String selectServer() {
            if (weightedServers.isEmpty()) {
                return null;
            }
            
            // 加權輪詢算法
            int totalWeight = weightedServers.lastKey();
            int current = currentWeight.updateAndGet(w -> (w + 1) % totalWeight);
            
            for (Map.Entry<Integer, List<String>> entry : weightedServers.descendingMap().entrySet()) {
                if (current < entry.getKey()) {
                    List<String> servers = entry.getValue();
                    return servers.get(current % servers.size());
                }
            }
            
            return null;
        }
    }
}

最佳實踐與建議

1. 選擇適當的比較策略

public class TreeMapBestPractices {
    
    // 1. 自然排序 vs 自定義比較器
    public static void comparatorChoice() {
        // 對於實現 Comparable 的類型，使用自然排序
        TreeMap<String, Integer> naturalOrder = new TreeMap<>();
        
        // 對於需要自定義排序的情況，使用比較器
        TreeMap<String, Integer> customOrder = new TreeMap<>(String.CASE_INSENSITIVE_ORDER);
        
        // 複雜對象的多字段排序
        TreeMap<Person, String> personMap = new TreeMap<>(
            Comparator.comparing(Person::getAge)
                .thenComparing(Person::getName)
        );
    }
    
    // 2. 空值處理
    public static void nullHandling() {
        // TreeMap 不允許 null 鍵
        TreeMap<String, Integer> map = new TreeMap<>();
        // map.put(null, 1); // 會拋出 NullPointerException
        
        // 但允許 null 值
        map.put("key", null);
        
        // 如果需要支持 null 鍵，使用自定義比較器
        TreeMap<String, Integer> nullSafeMap = new TreeMap<>((s1, s2) -> {
            if (s1 == null && s2 == null) return 0;
            if (s1 == null) return -1;
            if (s2 == null) return 1;
            return s1.compareTo(s2);
        });
    }
    
    // 3. 線程安全處理
    public static void threadSafety() {
        TreeMap<Integer, String> treeMap = new TreeMap<>();
        
        // 方法1：使用 Collections.synchronizedMap
        Map<Integer, String> syncMap = Collections.synchronizedMap(treeMap);
        
        // 方法2：使用 ConcurrentSkipListMap
        ConcurrentSkipListMap<Integer, String> concurrentMap = new ConcurrentSkipListMap<>();
        
        // 方法3：使用讀寫鎖
        ReadWriteLock lock = new ReentrantReadWriteLock();
        // 在讀寫操作時使用相應的鎖
    }
    
    // 4. 效能考慮
    public static void performanceConsiderations() {
        // 預先指定初始容量（TreeMap 沒有初始容量概念，但可以批量插入）
        Map<Integer, String> initialData = new HashMap<>();
        for (int i = 0; i < 1000; i++) {
            initialData.put(i, "value" + i);
        }
        
        TreeMap<Integer, String> treeMap = new TreeMap<>(initialData);
        
        // 避免頻繁的範圍查詢操作
        NavigableMap<Integer, String> subMap = treeMap.subMap(100, true, 200, false);
        // 對 subMap 的操作會影響原始 map
    }
    
    static class Person {
        private String name;
        private int age;
        
        public Person(String name, int age) {
            this.name = name;
            this.age = age;
        }
        
        public String getName() { return name; }
        public int getAge() { return age; }
    }
}

2. 常見錯誤避免

public class TreeMapCommonMistakes {
    
    // 錯誤1：在迭代過程中修改 TreeMap
    public static void avoidConcurrentModification() {
        TreeMap<Integer, String> map = new TreeMap<>();
        for (int i = 0; i < 10; i++) {
            map.put(i, "value" + i);
        }
        
        // 錯誤的做法
        // for (Integer key : map.keySet()) {
        //     if (key % 2 == 0) {
        //         map.remove(key); // ConcurrentModificationException
        //     }
        // }
        
        // 正確的做法1：使用迭代器
        Iterator<Integer> iterator = map.keySet().iterator();
        while (iterator.hasNext()) {
            if (iterator.next() % 2 == 0) {
                iterator.remove();
            }
        }
        
        // 正確的做法2：收集要刪除的鍵
        List<Integer> keysToRemove = map.keySet().stream()
                .filter(key -> key % 2 == 0)
                .collect(Collectors.toList());
        keysToRemove.forEach(map::remove);
    }
    
    // 錯誤2：比較器不一致
    public static void avoidInconsistentComparator() {
        // 錯誤：比較器與 equals 不一致
        TreeMap<String, Integer> badMap = new TreeMap<>((s1, s2) -> {
            return s1.length() - s2.length(); // 只比較長度
        });
        
        badMap.put("abc", 1);
        badMap.put("def", 2); // 會覆蓋 "abc"，因為長度相同
        
        // 正確：確保比較器一致性
        TreeMap<String, Integer> goodMap = new TreeMap<>((s1, s2) -> {
            int lengthCompare = s1.length() - s2.length();
            if (lengthCompare != 0) {
                return lengthCompare;
            }
            return s1.compareTo(s2); // 長度相同時比較內容
        });
    }
    
    // 錯誤3：誤用子映射
    public static void avoidSubMapMisuse() {
        TreeMap<Integer, String> map = new TreeMap<>();
        for (int i = 0; i < 10; i++) {
            map.put(i, "value" + i);
        }
        
        // 錯誤：認為子映射是獨立的
        NavigableMap<Integer, String> subMap = map.subMap(2, true, 8, false);
        subMap.clear(); // 這會影響原始 map
        
        // 正確：如果需要獨立的副本
        NavigableMap<Integer, String> independentCopy = new TreeMap<>(subMap);
    }
}

總結

TreeMap 是 Java 集合框架中功能強大的有序映射實現，基於紅黑樹提供了 O(log n) 的高效操作。通過本文的深入分析，我們了解了：

QueryDSL 完整實戰指南：類型安全的動態查詢解決方案

Sun, 08 Aug 2021 13:07:45 +0800

維護狀態說明：QueryDSL 4.x 自 2018 年後長期缺乏維護；5.0.0（2022 年）雖遷移至 Jakarta namespace，但開發活躍度仍低。評估新專案時請考量以下替代方案：

方案	適用場景	維護狀態
QueryDSL 5.x	現有專案延續、需要複雜型別安全查詢	低度維護
Spring Data JPA Specification	簡單動態查詢，無需額外依賴	積極維護
jOOQ	複雜 SQL、需要完整 SQL 功能	積極維護
Blaze-Persistence	JPA 進階查詢、Entity View	積極維護

概述

QueryDSL 是一個強大的 Java 查詢框架，提供類型安全的 SQL 查詢建構功能。它通過代碼生成技術創建查詢類型，在編譯時期就能發現查詢錯誤，大幅提升開發效率和代碼質量。本文將深入介紹 QueryDSL 的各種用法和最佳實踐。

核心優勢

類型安全：編譯時檢查，避免執行期錯誤
IDE 支援：完整的自動完成和重構功能
統一 API：支援 JPA、SQL、MongoDB 等多種數據源
動態查詢：靈活的條件組合和查詢建構
效能優化：生成高效的 SQL 查詢

支援的技術棧

JPA/Hibernate：最常用的 ORM 整合
Spring Data JPA：與 Spring 生態完美整合
SQL 數據庫：MySQL、PostgreSQL、Oracle 等
NoSQL 數據庫：MongoDB、Lucene 等

環境配置與設定

1. Maven 依賴配置

<properties>
    <querydsl.version>5.0.0</querydsl.version>
    <maven.compiler.source>17</maven.compiler.source>
    <maven.compiler.target>17</maven.compiler.target>
</properties>

<dependencies>
    <!-- Spring Boot Starter Data JPA -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-data-jpa</artifactId>
    </dependency>
    
    <!-- QueryDSL JPA -->
    <dependency>
        <groupId>com.querydsl</groupId>
        <artifactId>querydsl-jpa</artifactId>
        <version>${querydsl.version}</version>
        <classifier>jakarta</classifier>
    </dependency>
    
    <!-- QueryDSL APT (Annotation Processing Tool) -->
    <dependency>
        <groupId>com.querydsl</groupId>
        <artifactId>querydsl-apt</artifactId>
        <version>${querydsl.version}</version>
        <classifier>jakarta</classifier>
        <scope>provided</scope>
    </dependency>
    
    <!-- Database Driver -->
    <dependency>
        <groupId>mysql</groupId>
        <artifactId>mysql-connector-java</artifactId>
        <scope>runtime</scope>
    </dependency>
    
    <!-- Validation -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-validation</artifactId>
    </dependency>
</dependencies>

<build>
    <plugins>
        <!-- Maven Compiler 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>com.querydsl</groupId>
                        <artifactId>querydsl-apt</artifactId>
                        <version>${querydsl.version}</version>
                        <classifier>jakarta</classifier>
                    </path>
                    <path>
                        <groupId>jakarta.persistence</groupId>
                        <artifactId>jakarta.persistence-api</artifactId>
                        <version>3.1.0</version>
                    </path>
                    <path>
                        <groupId>jakarta.annotation</groupId>
                        <artifactId>jakarta.annotation-api</artifactId>
                        <version>2.1.1</version>
                    </path>
                </annotationProcessorPaths>
            </configuration>
        </plugin>
        
        <!-- Generate Sources Plugin -->
        <plugin>
            <groupId>org.codehaus.mojo</groupId>
            <artifactId>build-helper-maven-plugin</artifactId>
            <version>3.4.0</version>
            <executions>
                <execution>
                    <phase>generate-sources</phase>
                    <goals>
                        <goal>add-source</goal>
                    </goals>
                    <configuration>
                        <sources>
                            <source>target/generated-sources/annotations</source>
                        </sources>
                    </configuration>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

2. Gradle 配置

plugins {
    id 'org.springframework.boot' version '3.1.0'
    id 'io.spring.dependency-management' version '1.1.0'
    id 'java'
}

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-data-jpa'
    implementation 'org.springframework.boot:spring-boot-starter-web'
    implementation 'org.springframework.boot:spring-boot-starter-validation'
    
    // QueryDSL
    implementation 'com.querydsl:querydsl-jpa:5.0.0:jakarta'
    annotationProcessor 'com.querydsl:querydsl-apt:5.0.0:jakarta'
    annotationProcessor 'jakarta.persistence:jakarta.persistence-api'
    annotationProcessor 'jakarta.annotation:jakarta.annotation-api'
    
    runtimeOnly 'mysql:mysql-connector-java'
    testImplementation 'org.springframework.boot:spring-boot-starter-test'
}

// QueryDSL 配置
def queryDslDir = "$buildDir/generated/querydsl"

querydsl {
    jpa = true
    querydslSourcesDir = queryDslDir
}

sourceSets {
    main.java.srcDir queryDslDir
}

configurations {
    querydsl.extendsFrom compileClasspath
}

compileQuerydsl {
    options.annotationProcessorPath = configurations.querydsl
}

IntelliJ IDEA + Gradle APT 常見問題

QueryDSL 依賴 Annotation Processing（APT）在編譯時產生 Q 類別（如 QUser）。IntelliJ 與 Gradle APT 的整合不完美，常見錯誤及解法：

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

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

Kotlin lateinit 完整實作指南

簡介

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

lateinit 基本概念

核心特性

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

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

語法規則與限制

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

lateinit 詳細機制

內部實現原理

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

初始化檢查機制

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

企業級應用場景

1. Spring Boot 依賴注入

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

2. Android 開發中的應用

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

3. 配置管理系統

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

lateinit vs lazy 詳細比較

特性對比表

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

使用場景比較

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

進階使用模式

1. 條件初始化模式

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

2. 初始化鏈模式

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

3. 資源管理模式

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

測試策略

1. 單元測試模式

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

2. 整合測試模式

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

效能優化與最佳實踐

1. 記憶體管理

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

2. 線程安全考量

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

常見陷阱與錯誤處理

1. 常見錯誤模式

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

2. 錯誤處理策略

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

企業級最佳實踐

1. 初始化驗證框架

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

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

2. 監控與診斷

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

效能基準測試

初始化效能比較

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

總結

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

Spring 依賴注入完整指南：@Autowired 與最佳實踐

Sat, 10 Jul 2021 20:27:20 +0800

概述

Spring Framework 的核心特性之一是依賴注入（Dependency Injection, DI），它實現了控制反轉（Inversion of Control, IoC）的設計模式。正確使用依賴注入不僅能提升程式碼的可測試性和可維護性，還能降低組件間的耦合度。本文將深入探討 Spring 中各種依賴注入方式，並重點說明最佳實踐。

為什麼不建議使用 @Autowired Field Injection？

當你在 IntelliJ IDEA 中使用 @Autowired 進行欄位注入時，會看到這樣的警告：

Field injection is not recommended 
Inspection info: Spring Team recommends: 
"Always use constructor based dependency injection in your beans. 
Always use assertions for mandatory dependencies".

這個警告背後有深刻的技術理由，讓我們逐一分析。

Spring 依賴注入的三種方式

1. Field Injection（不建議）

@Service
public class OrderService {
    
    @Autowired
    private PaymentService paymentService;  // ❌ 不建議
    
    @Autowired
    private InventoryService inventoryService;  // ❌ 不建議
    
    @Autowired
    private EmailService emailService;  // ❌ 不建議
    
    public void processOrder(Order order) {
        paymentService.processPayment(order);
        inventoryService.updateStock(order);
        emailService.sendConfirmation(order);
    }
}

Field Injection 的問題：

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

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

概述

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

JWT 核心特徵

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

JWT 結構

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

`1`	`Header.Payload.Signature`

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

Spring Boot 整合實作

1. 依賴配置

Maven 依賴設定

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

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

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

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

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

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

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

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

Gradle 依賴設定

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

2. 資料模型

認證請求 DTO

package com.example.jwt.dto;

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

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

認證回應 DTO

package com.example.jwt.dto;

import com.fasterxml.jackson.annotation.JsonProperty;

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

使用者實體

package com.example.jwt.entity;

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

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

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

enum Role {
    USER, ADMIN, MODERATOR
}

3. JWT 工具類

package com.example.jwt.util;

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

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

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

4. JWT 請求過濾器

package com.example.jwt.filter;

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

import java.io.IOException;

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

5. Spring Security 配置

package com.example.jwt.config;

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

import java.util.Arrays;

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

6. 認證控制器

package com.example.jwt.controller;

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

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

7. 認證服務

package com.example.jwt.service;

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

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

配置檔案

application.yml

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

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

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

安全性最佳實踐

1. 密鑰管理

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

2. Token 黑名單服務

package com.example.jwt.service;

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

import java.util.concurrent.TimeUnit;

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

3. 異常處理

package com.example.jwt.exception;

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

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

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

使用範例

1. 前端整合

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

2. 測試範例

package com.example.jwt;

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

import java.util.ArrayList;

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

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

效能最佳化

1. Redis 快取

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

2. 非同步處理

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

監控和日誌

1. 認證監控

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

2. 效能監控

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

常見問題與解決方案

1. Token 過期處理

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

2. 跨域處理

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

總結

核心優勢

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

最佳實踐

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

常用命令速查

# 生成密鑰
openssl rand -base64 32

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

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

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

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