Spring on Bill.Lin's Notes

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;
    
    // 其他屬性...
}

資料庫儲存：

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 提供兩個核心類型：

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 的問題：

Swagger/OpenAPI 完整指南：API 文檔化與測試最佳實踐

Thu, 01 Jul 2021 20:47:27 +0800

注意：舊版 Springfox（io.springfox:springfox-swagger2）已停止維護，且與 Spring Boot 2.6+ 的 Spring MVC path matching 策略不相容，亦不支援 Spring Boot 3。請改用 org.springdoc:springdoc-openapi-starter-webmvc-ui（支援 OpenAPI 3，相容 Spring Boot 3）。

概述

Swagger（現稱為 OpenAPI）是目前最流行的 REST API 文檔化工具之一。它不僅能自動生成美觀的 API 文檔，還提供互動式測試介面，支援多種程式語言的客戶端程式碼生成。本文將全面介紹如何在 Spring Boot 專案中整合和使用 Swagger，從基礎配置到進階功能的完整實戰指南。

版本選擇與依賴配置

OpenAPI 3.0 vs Swagger 2.0

特性	Swagger 2.0	OpenAPI 3.0
規範版本	較舊	最新標準
Spring Boot 支援	良好	原生支援
功能豐富度	基本功能	豐富特性
社群活躍度	維護模式	積極開發
推薦度	僅限舊專案	強烈推薦

現代化依賴配置（OpenAPI 3.0）

<!-- 推薦：SpringDoc OpenAPI 3 -->
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.2.0</version>
</dependency>

<!-- 安全整合 -->
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-security</artifactId>
    <version>2.2.0</version>
</dependency>

<!-- WebFlux 支援 -->
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webflux-ui</artifactId>
    <version>2.2.0</version>
</dependency>

傳統 Swagger 2.0 配置（僅供參考）

<!-- 傳統：Springfox Swagger 2 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>3.0.0</version>
</dependency>

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>3.0.0</version>
</dependency>

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

OpenAPI 3.0 基礎配置

1. 應用程式配置

# application.yml
springdoc:
  api-docs:
    path: /api-docs
    enabled: true
  swagger-ui:
    path: /swagger-ui.html
    enabled: true
    operations-sorter: method
    tags-sorter: alpha
    try-it-out-enabled: true
    filter: true
    display-request-duration: true
  packages-to-scan: com.example.controller
  paths-to-match: /api/**
  default-consumes-media-type: application/json
  default-produces-media-type: application/json

# 自訂配置
app:
  api:
    title: E-Commerce API
    description: 電商平台核心 API 服務
    version: 1.0.0
    contact:
      name: API Support Team
      email: api-support@example.com
      url: https://example.com/support
    license:
      name: Apache 2.0
      url: https://www.apache.org/licenses/LICENSE-2.0.html
    terms-of-service: https://example.com/terms

2. 進階 OpenAPI 配置類

@Configuration
@EnableOpenApi
public class OpenApiConfiguration {
    
    @Value("${app.api.title}")
    private String title;
    
    @Value("${app.api.description}")
    private String description;
    
    @Value("${app.api.version}")
    private String version;
    
    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
            .info(createApiInfo())
            .servers(createServers())
            .security(createSecurityRequirements())
            .components(createComponents());
    }
    
    private Info createApiInfo() {
        return new Info()
            .title(title)
            .description(description)
            .version(version)
            .contact(new Contact()
                .name("API Support Team")
                .email("api-support@example.com")
                .url("https://example.com/support"))
            .license(new License()
                .name("Apache 2.0")
                .url("https://www.apache.org/licenses/LICENSE-2.0.html"))
            .termsOfService("https://example.com/terms");
    }
    
    private List<Server> createServers() {
        return List.of(
            new Server()
                .url("https://api.example.com")
                .description("Production Server"),
            new Server()
                .url("https://staging-api.example.com")
                .description("Staging Server"),
            new Server()
                .url("http://localhost:8080")
                .description("Development Server")
        );
    }
    
    private List<SecurityRequirement> createSecurityRequirements() {
        return List.of(
            new SecurityRequirement().addList("bearerAuth"),
            new SecurityRequirement().addList("apiKey")
        );
    }
    
    private Components createComponents() {
        return new Components()
            .addSecuritySchemes("bearerAuth", new SecurityScheme()
                .type(SecurityScheme.Type.HTTP)
                .scheme("bearer")
                .bearerFormat("JWT")
                .description("JWT Bearer Token Authentication"))
            .addSecuritySchemes("apiKey", new SecurityScheme()
                .type(SecurityScheme.Type.APIKEY)
                .in(SecurityScheme.In.HEADER)
                .name("X-API-Key")
                .description("API Key Authentication"))
            .addSchemas("Error", createErrorSchema())
            .addSchemas("PageInfo", createPageInfoSchema());
    }
    
    private Schema<?> createErrorSchema() {
        return new Schema<>()
            .type("object")
            .addProperties("timestamp", new Schema<>().type("string").format("date-time"))
            .addProperties("status", new Schema<>().type("integer"))
            .addProperties("error", new Schema<>().type("string"))
            .addProperties("message", new Schema<>().type("string"))
            .addProperties("path", new Schema<>().type("string"));
    }
    
    private Schema<?> createPageInfoSchema() {
        return new Schema<>()
            .type("object")
            .addProperties("page", new Schema<>().type("integer"))
            .addProperties("size", new Schema<>().type("integer"))
            .addProperties("totalElements", new Schema<>().type("integer"))
            .addProperties("totalPages", new Schema<>().type("integer"));
    }
}

控制器註解詳解

1. 完整的 REST Controller 範例

@RestController
@RequestMapping("/api/v1/users")
@Tag(name = "User Management", description = "用戶管理相關 API")
@SecurityRequirement(name = "bearerAuth")
public class UserController {
    
    private final UserService userService;
    
    public UserController(UserService userService) {
        this.userService = userService;
    }
    
    @GetMapping
    @Operation(
        summary = "獲取用戶列表",
        description = "分頁查詢用戶資訊，支援多種過濾條件",
        tags = {"User Management"}
    )
    @ApiResponses(value = {
        @ApiResponse(
            responseCode = "200",
            description = "成功獲取用戶列表",
            content = @Content(
                mediaType = "application/json",
                schema = @Schema(implementation = PagedUserResponse.class),
                examples = @ExampleObject(
                    name = "用戶列表範例",
                    value = """
                        {
                          "content": [
                            {
                              "id": 1,
                              "username": "john_doe",
                              "email": "john@example.com",
                              "firstName": "John",
                              "lastName": "Doe",
                              "createdAt": "2023-01-15T10:30:00Z"
                            }
                          ],
                          "pageable": {
                            "page": 0,
                            "size": 20,
                            "totalElements": 1,
                            "totalPages": 1
                          }
                        }
                        """
                )
            )
        ),
        @ApiResponse(
            responseCode = "400",
            description = "請求參數錯誤",
            content = @Content(
                mediaType = "application/json",
                schema = @Schema(implementation = ErrorResponse.class)
            )
        ),
        @ApiResponse(
            responseCode = "401", 
            description = "未授權訪問",
            content = @Content(schema = @Schema(implementation = ErrorResponse.class))
        ),
        @ApiResponse(
            responseCode = "403", 
            description = "權限不足",
            content = @Content(schema = @Schema(implementation = ErrorResponse.class))
        )
    })
    public ResponseEntity<Page<UserResponse>> getUsers(
        @Parameter(
            description = "頁碼（從 0 開始）",
            example = "0",
            schema = @Schema(minimum = "0", defaultValue = "0")
        )
        @RequestParam(defaultValue = "0") 
        @Min(0) int page,
        
        @Parameter(
            description = "每頁大小",
            example = "20", 
            schema = @Schema(minimum = "1", maximum = "100", defaultValue = "20")
        )
        @RequestParam(defaultValue = "20") 
        @Min(1) @Max(100) int size,
        
        @Parameter(
            description = "排序欄位，格式：field,direction",
            example = "createdAt,desc",
            array = @ArraySchema(schema = @Schema(type = "string"))
        )
        @RequestParam(defaultValue = "createdAt,desc") String[] sort,
        
        @Parameter(
            description = "用戶名搜尋關鍵字",
            example = "john"
        )
        @RequestParam(required = false) String username,
        
        @Parameter(
            description = "郵箱搜尋關鍵字", 
            example = "example.com"
        )
        @RequestParam(required = false) String email,
        
        @Parameter(
            description = "用戶狀態過濾",
            schema = @Schema(allowableValues = {"ACTIVE", "INACTIVE", "SUSPENDED"})
        )
        @RequestParam(required = false) UserStatus status
    ) {
        UserSearchCriteria criteria = UserSearchCriteria.builder()
            .username(username)
            .email(email)
            .status(status)
            .build();
            
        Pageable pageable = createPageable(page, size, sort);
        Page<UserResponse> users = userService.findUsers(criteria, pageable);
        
        return ResponseEntity.ok(users);
    }
    
    @GetMapping("/{id}")
    @Operation(
        summary = "根據 ID 獲取用戶",
        description = "根據用戶 ID 獲取詳細資訊"
    )
    @ApiResponses(value = {
        @ApiResponse(
            responseCode = "200",
            description = "成功獲取用戶資訊",
            content = @Content(
                mediaType = "application/json",
                schema = @Schema(implementation = UserDetailResponse.class)
            )
        ),
        @ApiResponse(responseCode = "404", description = "用戶不存在")
    })
    public ResponseEntity<UserDetailResponse> getUserById(
        @Parameter(
            description = "用戶 ID",
            required = true,
            example = "123"
        )
        @PathVariable 
        @Positive Long id
    ) {
        UserDetailResponse user = userService.findDetailById(id);
        return ResponseEntity.ok(user);
    }
    
    @PostMapping
    @Operation(
        summary = "創建新用戶",
        description = "創建新的用戶帳戶，郵箱必須唯一"
    )
    @ApiResponses(value = {
        @ApiResponse(
            responseCode = "201",
            description = "用戶創建成功",
            content = @Content(
                mediaType = "application/json",
                schema = @Schema(implementation = UserResponse.class)
            )
        ),
        @ApiResponse(
            responseCode = "400", 
            description = "請求資料驗證失敗",
            content = @Content(
                mediaType = "application/json",
                schema = @Schema(implementation = ValidationErrorResponse.class)
            )
        ),
        @ApiResponse(
            responseCode = "409", 
            description = "郵箱已存在"
        )
    })
    public ResponseEntity<UserResponse> createUser(
        @io.swagger.v3.oas.annotations.parameters.RequestBody(
            description = "用戶創建請求",
            required = true,
            content = @Content(
                mediaType = "application/json",
                schema = @Schema(implementation = CreateUserRequest.class),
                examples = @ExampleObject(
                    name = "用戶創建範例",
                    value = """
                        {
                          "username": "john_doe",
                          "email": "john@example.com",
                          "firstName": "John",
                          "lastName": "Doe",
                          "password": "SecurePassword123!"
                        }
                        """
                )
            )
        )
        @RequestBody @Valid CreateUserRequest request
    ) {
        UserResponse user = userService.createUser(request);
        URI location = URI.create("/api/v1/users/" + user.getId());
        return ResponseEntity.created(location).body(user);
    }
    
    @PutMapping("/{id}")
    @Operation(
        summary = "更新用戶資訊",
        description = "更新指定用戶的基本資訊"
    )
    public ResponseEntity<UserResponse> updateUser(
        @PathVariable @Positive Long id,
        @RequestBody @Valid UpdateUserRequest request
    ) {
        UserResponse user = userService.updateUser(id, request);
        return ResponseEntity.ok(user);
    }
    
    @DeleteMapping("/{id}")
    @Operation(
        summary = "刪除用戶",
        description = "軟刪除指定用戶（標記為已刪除狀態）"
    )
    @ApiResponses(value = {
        @ApiResponse(responseCode = "204", description = "刪除成功"),
        @ApiResponse(responseCode = "404", description = "用戶不存在"),
        @ApiResponse(responseCode = "409", description = "用戶有關聯資料，無法刪除")
    })
    public ResponseEntity<Void> deleteUser(
        @PathVariable @Positive Long id
    ) {
        userService.deleteUser(id);
        return ResponseEntity.noContent().build();
    }
    
    @PostMapping("/{id}/avatar")
    @Operation(
        summary = "上傳用戶頭像",
        description = "上傳用戶頭像圖片，支援 JPG、PNG 格式"
    )
    @ApiResponses(value = {
        @ApiResponse(
            responseCode = "200",
            description = "頭像上傳成功",
            content = @Content(
                mediaType = "application/json",
                schema = @Schema(implementation = UploadResponse.class)
            )
        ),
        @ApiResponse(responseCode = "400", description = "檔案格式不支援"),
        @ApiResponse(responseCode = "413", description = "檔案大小超出限制")
    })
    public ResponseEntity<UploadResponse> uploadAvatar(
        @PathVariable @Positive Long id,
        @Parameter(
            description = "頭像圖片檔案",
            required = true,
            content = @Content(mediaType = "multipart/form-data")
        )
        @RequestParam("file") MultipartFile file
    ) {
        UploadResponse response = userService.uploadAvatar(id, file);
        return ResponseEntity.ok(response);
    }
}

2. DTO 類別註解

@Schema(description = "用戶創建請求")
public class CreateUserRequest {
    
    @Schema(
        description = "用戶名",
        example = "john_doe",
        minLength = 3,
        maxLength = 50,
        pattern = "^[a-zA-Z0-9_]+$"
    )
    @NotBlank(message = "用戶名不能為空")
    @Size(min = 3, max = 50, message = "用戶名長度必須在 3-50 字元之間")
    @Pattern(regexp = "^[a-zA-Z0-9_]+$", message = "用戶名只能包含字母、數字和底線")
    private String username;
    
    @Schema(
        description = "郵箱地址",
        example = "john@example.com",
        format = "email"
    )
    @NotBlank(message = "郵箱不能為空")
    @Email(message = "郵箱格式不正確")
    private String email;
    
    @Schema(
        description = "名字",
        example = "John",
        maxLength = 30
    )
    @NotBlank(message = "名字不能為空")
    @Size(max = 30, message = "名字長度不能超過 30 字元")
    private String firstName;
    
    @Schema(
        description = "姓氏",
        example = "Doe",
        maxLength = 30
    )
    @NotBlank(message = "姓氏不能為空")
    @Size(max = 30, message = "姓氏長度不能超過 30 字元")
    private String lastName;
    
    @Schema(
        description = "密碼",
        example = "SecurePassword123!",
        minLength = 8,
        maxLength = 100,
        format = "password"
    )
    @NotBlank(message = "密碼不能為空")
    @Size(min = 8, max = 100, message = "密碼長度必須在 8-100 字元之間")
    @Pattern(
        regexp = "^(?=.*[a-z])(?=.*[A-Z])(?=.*\\d)(?=.*[@$!%*?&])[A-Za-z\\d@$!%*?&]+$",
        message = "密碼必須包含大小寫字母、數字和特殊字元"
    )
    private String password;
    
    @Schema(
        description = "出生日期",
        example = "1990-01-15",
        format = "date"
    )
    @Past(message = "出生日期必須是過去的日期")
    private LocalDate birthDate;
    
    @Schema(
        description = "用戶角色",
        allowableValues = {"USER", "ADMIN", "MODERATOR"},
        defaultValue = "USER"
    )
    private UserRole role = UserRole.USER;
    
    // Getters and Setters...
}

@Schema(description = "分頁用戶回應")
public class PagedUserResponse {
    
    @Schema(description = "用戶列表")
    private List<UserResponse> content;
    
    @Schema(description = "分頁資訊")
    private PageInfo pageable;
    
    // Getters and Setters...
}

@Schema(description = "用戶基本資訊回應")
public class UserResponse {
    
    @Schema(description = "用戶 ID", example = "123")
    private Long id;
    
    @Schema(description = "用戶名", example = "john_doe")
    private String username;
    
    @Schema(description = "郵箱", example = "john@example.com")
    private String email;
    
    @Schema(description = "全名", example = "John Doe")
    private String fullName;
    
    @Schema(description = "頭像 URL", example = "https://example.com/avatars/123.jpg")
    private String avatarUrl;
    
    @Schema(description = "用戶狀態", allowableValues = {"ACTIVE", "INACTIVE", "SUSPENDED"})
    private UserStatus status;
    
    @Schema(description = "創建時間", format = "date-time")
    private LocalDateTime createdAt;
    
    @Schema(description = "最後登入時間", format = "date-time")
    private LocalDateTime lastLoginAt;
    
    // Getters and Setters...
}

安全配置整合

1. JWT Bearer Token 整合

@Configuration
@EnableWebSecurity
public class SecurityConfiguration {
    
    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        return http
            .csrf(csrf -> csrf.disable())
            .authorizeHttpRequests(auth -> auth
                // Swagger 相關路徑公開
                .requestMatchers(
                    "/api-docs/**",
                    "/swagger-ui/**", 
                    "/swagger-ui.html",
                    "/webjars/**"
                ).permitAll()
                // 公開 API
                .requestMatchers(HttpMethod.POST, "/api/v1/auth/**").permitAll()
                .requestMatchers(HttpMethod.GET, "/api/v1/public/**").permitAll()
                // 需要認證的 API
                .anyRequest().authenticated()
            )
            .oauth2ResourceServer(oauth2 -> oauth2
                .jwt(jwt -> jwt.jwtDecoder(jwtDecoder()))
            )
            .sessionManagement(session -> session
                .sessionCreationPolicy(SessionCreationPolicy.STATELESS)
            )
            .build();
    }
    
    @Bean
    public JwtDecoder jwtDecoder() {
        return NimbusJwtDecoder.withJwkSetUri("https://your-auth-server/.well-known/jwks.json")
            .build();
    }
}

// 在 Controller 中指定安全需求
@RestController
@RequestMapping("/api/v1/admin")
@Tag(name = "Admin Management", description = "管理員專用 API")
@SecurityRequirement(name = "bearerAuth")
@PreAuthorize("hasRole('ADMIN')")
public class AdminController {
    
    @GetMapping("/users")
    @Operation(
        summary = "管理員查看所有用戶",
        description = "需要 ADMIN 角色權限"
    )
    @PreAuthorize("hasAuthority('USER_READ_ALL')")
    public ResponseEntity<Page<UserResponse>> getAllUsersForAdmin(
        @ParameterObject Pageable pageable
    ) {
        // Implementation...
        return ResponseEntity.ok().build();
    }
}

2. API Key 認證

@Component
public class ApiKeyAuthenticationFilter extends OncePerRequestFilter {
    
    private static final String API_KEY_HEADER = "X-API-Key";
    private final ApiKeyService apiKeyService;
    
    public ApiKeyAuthenticationFilter(ApiKeyService apiKeyService) {
        this.apiKeyService = apiKeyService;
    }
    
    @Override
    protected void doFilterInternal(
        HttpServletRequest request,
        HttpServletResponse response,
        FilterChain filterChain
    ) throws ServletException, IOException {
        
        String apiKey = request.getHeader(API_KEY_HEADER);
        
        if (apiKey != null && apiKeyService.isValidApiKey(apiKey)) {
            ApiKeyDetails details = apiKeyService.getApiKeyDetails(apiKey);
            ApiKeyAuthenticationToken authentication = 
                new ApiKeyAuthenticationToken(details);
            SecurityContextHolder.getContext().setAuthentication(authentication);
        }
        
        filterChain.doFilter(request, response);
    }
}

// 在特定 Controller 中使用 API Key
@RestController
@RequestMapping("/api/v1/webhook")
@Tag(name = "Webhook API", description = "第三方系統回調 API")
@SecurityRequirement(name = "apiKey")
public class WebhookController {
    
    @PostMapping("/payment")
    @Operation(
        summary = "支付結果回調",
        description = "第三方支付系統回調通知"
    )
    public ResponseEntity<Void> handlePaymentWebhook(
        @RequestBody PaymentWebhookRequest request
    ) {
        // Implementation...
        return ResponseEntity.ok().build();
    }
}

進階功能配置

1. 自訂文檔分組

@Configuration
public class OpenApiGroupConfiguration {
    
    @Bean
    @Primary
    public GroupedOpenApi publicApi() {
        return GroupedOpenApi.builder()
            .group("public")
            .displayName("Public API")
            .pathsToMatch("/api/v1/public/**", "/api/v1/auth/**")
            .build();
    }
    
    @Bean
    public GroupedOpenApi userApi() {
        return GroupedOpenApi.builder()
            .group("user")
            .displayName("User API")
            .pathsToMatch("/api/v1/users/**", "/api/v1/profile/**")
            .addOperationCustomizer((operation, handlerMethod) -> {
                operation.addSecurityItem(new SecurityRequirement().addList("bearerAuth"));
                return operation;
            })
            .build();
    }
    
    @Bean
    public GroupedOpenApi adminApi() {
        return GroupedOpenApi.builder()
            .group("admin")
            .displayName("Admin API")
            .pathsToMatch("/api/v1/admin/**")
            .addOperationCustomizer((operation, handlerMethod) -> {
                operation.addSecurityItem(new SecurityRequirement().addList("bearerAuth"));
                // 添加管理員 API 的額外標籤
                operation.addTagsItem("Admin Only");
                return operation;
            })
            .build();
    }
    
    @Bean
    public GroupedOpenApi internalApi() {
        return GroupedOpenApi.builder()
            .group("internal")
            .displayName("Internal API")
            .pathsToMatch("/api/internal/**")
            .addOperationCustomizer((operation, handlerMethod) -> {
                operation.addSecurityItem(new SecurityRequirement().addList("apiKey"));
                return operation;
            })
            .build();
    }
}

2. 自訂操作符處理器

@Component
public class CustomOperationCustomizer implements OperationCustomizer {
    
    @Override
    public Operation customize(Operation operation, HandlerMethod handlerMethod) {
        // 自動添加通用錯誤回應
        addCommonErrorResponses(operation);
        
        // 為分頁端點添加通用參數
        if (isPaginationEndpoint(handlerMethod)) {
            addPaginationParameters(operation);
        }
        
        // 添加請求追蹤資訊
        addRequestTrackingInfo(operation);
        
        return operation;
    }
    
    private void addCommonErrorResponses(Operation operation) {
        ApiResponses responses = operation.getResponses();
        
        if (responses.get("400") == null) {
            responses.addApiResponse("400", new ApiResponse()
                .description("請求參數錯誤")
                .content(new Content()
                    .addMediaType("application/json", new MediaType()
                        .schema(new Schema<>().$ref("#/components/schemas/Error")))));
        }
        
        if (responses.get("500") == null) {
            responses.addApiResponse("500", new ApiResponse()
                .description("內部伺服器錯誤")
                .content(new Content()
                    .addMediaType("application/json", new MediaType()
                        .schema(new Schema<>().$ref("#/components/schemas/Error")))));
        }
    }
    
    private boolean isPaginationEndpoint(HandlerMethod handlerMethod) {
        return Arrays.stream(handlerMethod.getMethodParameters())
            .anyMatch(param -> Pageable.class.isAssignableFrom(param.getParameterType()));
    }
    
    private void addPaginationParameters(Operation operation) {
        if (operation.getParameters() == null) {
            operation.setParameters(new ArrayList<>());
        }
        
        // 添加通用分頁參數
        operation.getParameters().add(new Parameter()
            .name("page")
            .in(ParameterIn.QUERY)
            .description("頁碼（從 0 開始）")
            .schema(new IntegerSchema().minimum(BigDecimal.ZERO)._default(0)));
            
        operation.getParameters().add(new Parameter()
            .name("size")
            .in(ParameterIn.QUERY)
            .description("每頁大小")
            .schema(new IntegerSchema().minimum(BigDecimal.ONE).maximum(BigDecimal.valueOf(100))._default(20)));
    }
    
    private void addRequestTrackingInfo(Operation operation) {
        operation.addExtension("x-request-id", "自動生成的請求追蹤 ID");
        operation.addExtension("x-rate-limit", "API 呼叫頻率限制資訊");
    }
}

3. 自訂 Schema 處理器

@Component
public class CustomModelConverter implements ModelConverter {
    
    @Override
    public ModelConverterContext resolve(
        AnnotatedType annotatedType,
        ModelConverterContext context,
        Iterator<ModelConverter> chain
    ) {
        if (chain.hasNext()) {
            context = chain.next().resolve(annotatedType, context, chain);
        }
        
        // 自訂枚舉處理
        if (annotatedType.getType() instanceof Class<?> clazz && clazz.isEnum()) {
            Schema<?> schema = context.getDefinedModels().get(annotatedType.getType().getTypeName());
            if (schema != null) {
                enhanceEnumSchema(schema, clazz);
            }
        }
        
        return context;
    }
    
    @SuppressWarnings("unchecked")
    private void enhanceEnumSchema(Schema<?> schema, Class<?> enumClass) {
        if (enumClass.isEnum()) {
            Enum<?>[] enumConstants = (Enum<?>[]) enumClass.getEnumConstants();
            
            List<String> enumValues = Arrays.stream(enumConstants)
                .map(Enum::name)
                .collect(Collectors.toList());
                
            schema.setEnum(enumValues);
            
            // 添加枚舉描述
            StringBuilder description = new StringBuilder(schema.getDescription() != null ? 
                schema.getDescription() : "");
            description.append("\n\n可用值：\n");
            
            for (Enum<?> enumConstant : enumConstants) {
                description.append("- `").append(enumConstant.name()).append("`");
                
                // 如果枚舉有描述方法，添加描述
                try {
                    Method getDescription = enumClass.getMethod("getDescription");
                    Object desc = getDescription.invoke(enumConstant);
                    if (desc != null) {
                        description.append(": ").append(desc);
                    }
                } catch (Exception ignored) {
                    // 忽略沒有 getDescription 方法的情況
                }
                
                description.append("\n");
            }
            
            schema.setDescription(description.toString());
        }
    }
}

測試整合

1. API 文檔測試

@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
@TestMethodOrder(OrderAnnotation.class)
class OpenApiDocumentationTest {
    
    @Autowired
    private TestRestTemplate restTemplate;
    
    @LocalServerPort
    private int port;
    
    @Test
    @Order(1)
    void testOpenApiJsonGeneration() {
        String url = "http://localhost:" + port + "/api-docs";
        
        ResponseEntity<String> response = restTemplate.getForEntity(url, String.class);
        
        assertThat(response.getStatusCode()).isEqualTo(HttpStatus.OK);
        assertThat(response.getBody()).isNotNull();
        
        // 驗證 JSON 結構
        DocumentContext context = JsonPath.parse(response.getBody());
        assertThat(context.read("$.openapi", String.class)).isEqualTo("3.0.1");
        assertThat(context.read("$.info.title", String.class)).isNotEmpty();
        assertThat(context.read("$.paths", Map.class)).isNotEmpty();
    }
    
    @Test
    @Order(2)
    void testSwaggerUiAccess() {
        String url = "http://localhost:" + port + "/swagger-ui.html";
        
        ResponseEntity<String> response = restTemplate.getForEntity(url, String.class);
        
        assertThat(response.getStatusCode()).isEqualTo(HttpStatus.OK);
        assertThat(response.getBody()).contains("Swagger UI");
    }
    
    @Test
    @Order(3)
    void testApiGroupsGeneration() {
        String[] groups = {"public", "user", "admin", "internal"};
        
        for (String group : groups) {
            String url = "http://localhost:" + port + "/api-docs/" + group;
            ResponseEntity<String> response = restTemplate.getForEntity(url, String.class);
            
            assertThat(response.getStatusCode()).isEqualTo(HttpStatus.OK);
            
            DocumentContext context = JsonPath.parse(response.getBody());
            assertThat(context.read("$.paths", Map.class)).isNotEmpty();
        }
    }
    
    @Test
    @Order(4)
    void testSecuritySchemesDefinition() {
        String url = "http://localhost:" + port + "/api-docs";
        
        ResponseEntity<String> response = restTemplate.getForEntity(url, String.class);
        DocumentContext context = JsonPath.parse(response.getBody());
        
        // 驗證安全方案定義
        assertThat(context.read("$.components.securitySchemes.bearerAuth.type", String.class))
            .isEqualTo("http");
        assertThat(context.read("$.components.securitySchemes.apiKey.type", String.class))
            .isEqualTo("apiKey");
    }
}

2. 契約測試

@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
class ApiContractTest {
    
    @Autowired
    private TestRestTemplate restTemplate;
    
    @Autowired
    private ObjectMapper objectMapper;
    
    @LocalServerPort
    private int port;
    
    @Test
    void testUserApiContract() throws Exception {
        // 獲取 OpenAPI 規範
        String openApiJson = getOpenApiJson();
        OpenAPIV3Parser parser = new OpenAPIV3Parser();
        OpenAPI openAPI = parser.readContents(openApiJson).getOpenAPI();
        
        // 測試用戶創建端點
        PathItem userPath = openAPI.getPaths().get("/api/v1/users");
        assertThat(userPath).isNotNull();
        
        Operation postOperation = userPath.getPost();
        assertThat(postOperation).isNotNull();
        assertThat(postOperation.getSummary()).isEqualTo("創建新用戶");
        
        // 驗證請求 Schema
        RequestBody requestBody = postOperation.getRequestBody();
        assertThat(requestBody).isNotNull();
        
        Content content = requestBody.getContent();
        MediaType mediaType = content.get("application/json");
        assertThat(mediaType).isNotNull();
        
        // 驗證回應 Schema
        ApiResponse response201 = postOperation.getResponses().get("201");
        assertThat(response201).isNotNull();
        assertThat(response201.getDescription()).isEqualTo("用戶創建成功");
    }
    
    @Test
    void testActualApiMatchesContract() throws Exception {
        // 根據文檔測試實際 API
        String requestJson = """
            {
              "username": "test_user",
              "email": "test@example.com",
              "firstName": "Test",
              "lastName": "User",
              "password": "TestPassword123!"
            }
            """;
        
        HttpHeaders headers = new HttpHeaders();
        headers.setContentType(MediaType.APPLICATION_JSON);
        headers.setBearerAuth("valid-jwt-token");
        
        HttpEntity<String> request = new HttpEntity<>(requestJson, headers);
        
        // 假設這個端點在測試環境中可用
        String url = "http://localhost:" + port + "/api/v1/users";
        ResponseEntity<String> response = restTemplate.postForEntity(url, request, String.class);
        
        // 根據文檔，應該返回 201 或 401（如果沒有有效 token）
        assertThat(response.getStatusCode())
            .isIn(HttpStatus.CREATED, HttpStatus.UNAUTHORIZED);
    }
    
    private String getOpenApiJson() {
        String url = "http://localhost:" + port + "/api-docs";
        return restTemplate.getForObject(url, String.class);
    }
}

部署與 CI/CD 整合

1. 文檔生成腳本

#!/bin/bash
# scripts/generate-api-docs.sh

set -e

echo "🚀 生成 API 文檔..."

# 啟動應用程式
echo "啟動 Spring Boot 應用程式..."
java -jar target/api-service.jar --server.port=8080 &
APP_PID=$!

# 等待應用程式啟動
echo "等待應用程式啟動..."
for i in {1..30}; do
    if curl -s http://localhost:8080/actuator/health > /dev/null; then
        echo "應用程式已啟動"
        break
    fi
    sleep 2
done

# 生成 OpenAPI JSON
echo "下載 OpenAPI 規範..."
curl -o docs/openapi.json http://localhost:8080/api-docs

# 生成不同格式的文檔
echo "生成 HTML 文檔..."
npx @redocly/openapi-cli build-docs docs/openapi.json --output docs/api.html

echo "生成 Markdown 文檔..."
npx widdershins docs/openapi.json -o docs/api.md

# 生成客戶端 SDK
echo "生成客戶端 SDK..."
mkdir -p generated/java-client
npx @openapitools/openapi-generator-cli generate \
    -i docs/openapi.json \
    -g java \
    -o generated/java-client \
    --additional-properties=invokerPackage=com.example.client

# 停止應用程式
echo "停止應用程式..."
kill $APP_PID

echo "✅ API 文檔生成完成"

2. GitHub Actions 工作流程

# .github/workflows/api-docs.yml
name: Generate API Documentation

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

jobs:
  generate-docs:
    runs-on: ubuntu-latest
    
    steps:
    - uses: actions/checkout@v3
    
    - name: Set up JDK 17
      uses: actions/setup-java@v3
      with:
        java-version: '17'
        distribution: 'temurin'
        
    - name: Cache Maven dependencies
      uses: actions/cache@v3
      with:
        path: ~/.m2
        key: ${{ runner.os }}-m2-${{ hashFiles('**/pom.xml') }}
        
    - name: Build application
      run: mvn clean package -DskipTests
      
    - name: Setup Node.js
      uses: actions/setup-node@v3
      with:
        node-version: '18'
        
    - name: Install documentation tools
      run: |
        npm install -g @redocly/openapi-cli
        npm install -g widdershins
        npm install -g @openapitools/openapi-generator-cli
        
    - name: Generate API documentation
      run: |
        chmod +x scripts/generate-api-docs.sh
        ./scripts/generate-api-docs.sh
        
    - name: Upload documentation artifacts
      uses: actions/upload-artifact@v3
      with:
        name: api-documentation
        path: |
          docs/
          generated/
          
    - name: Deploy to GitHub Pages
      if: github.ref == 'refs/heads/main'
      uses: peaceiris/actions-gh-pages@v3
      with:
        github_token: ${{ secrets.GITHUB_TOKEN }}
        publish_dir: ./docs

3. Docker 整合

# Dockerfile.docs
FROM openjdk:17-jdk-slim as builder

WORKDIR /app
COPY . .
RUN ./mvnw clean package -DskipTests

FROM node:18-alpine as docs-generator

WORKDIR /app

# 安裝文檔生成工具
RUN npm install -g @redocly/openapi-cli widdershins @openapitools/openapi-generator-cli

# 複製應用程式
COPY --from=builder /app/target/*.jar app.jar

# 生成文檔的腳本
COPY scripts/generate-docs-docker.sh .
RUN chmod +x generate-docs-docker.sh

EXPOSE 8080

CMD ["./generate-docs-docker.sh"]

效能優化與最佳實踐

1. 大型 API 的文檔優化

@Configuration
public class OpenApiPerformanceConfiguration {
    
    @Bean
    @ConditionalOnProperty(name = "springdoc.api-docs.enabled", havingValue = "true")
    public OpenApiCustomiser openApiCustomiser() {
        return openApi -> {
            // 移除不必要的 Schema
            removeUnusedSchemas(openApi);
            
            // 簡化複雜的嵌套對象
            simplifyNestedObjects(openApi);
            
            // 添加快取頭
            addCacheHeaders(openApi);
        };
    }
    
    private void removeUnusedSchemas(OpenAPI openApi) {
        if (openApi.getComponents() != null && openApi.getComponents().getSchemas() != null) {
            Set<String> usedSchemas = findUsedSchemas(openApi);
            openApi.getComponents().getSchemas().entrySet()
                .removeIf(entry -> !usedSchemas.contains(entry.getKey()));
        }
    }
    
    private Set<String> findUsedSchemas(OpenAPI openApi) {
        Set<String> usedSchemas = new HashSet<>();
        
        if (openApi.getPaths() != null) {
            openApi.getPaths().values().forEach(pathItem -> {
                Stream.of(
                    pathItem.getGet(), pathItem.getPost(), pathItem.getPut(),
                    pathItem.getDelete(), pathItem.getPatch()
                ).filter(Objects::nonNull)
                .forEach(operation -> collectUsedSchemas(operation, usedSchemas));
            });
        }
        
        return usedSchemas;
    }
    
    private void collectUsedSchemas(Operation operation, Set<String> usedSchemas) {
        // 從請求體收集
        if (operation.getRequestBody() != null && 
            operation.getRequestBody().getContent() != null) {
            operation.getRequestBody().getContent().values()
                .forEach(mediaType -> collectSchemaRefs(mediaType.getSchema(), usedSchemas));
        }
        
        // 從回應收集
        if (operation.getResponses() != null) {
            operation.getResponses().values().forEach(response -> {
                if (response.getContent() != null) {
                    response.getContent().values()
                        .forEach(mediaType -> collectSchemaRefs(mediaType.getSchema(), usedSchemas));
                }
            });
        }
    }
    
    private void collectSchemaRefs(Schema<?> schema, Set<String> usedSchemas) {
        if (schema != null) {
            if (schema.get$ref() != null) {
                String schemaName = schema.get$ref().substring("#/components/schemas/".length());
                usedSchemas.add(schemaName);
            }
            
            // 遞迴處理嵌套 Schema
            if (schema.getProperties() != null) {
                schema.getProperties().values().forEach(prop -> 
                    collectSchemaRefs((Schema<?>) prop, usedSchemas));
            }
        }
    }
}

2. 快取策略

@RestController
@RequestMapping("/api-docs")
public class CachedApiDocsController {
    
    private final SpringDocConfigProperties springDocConfigProperties;
    private final ObjectMapper objectMapper;
    private final Cache<String, String> apiDocsCache;
    
    public CachedApiDocsController(
        SpringDocConfigProperties springDocConfigProperties,
        ObjectMapper objectMapper
    ) {
        this.springDocConfigProperties = springDocConfigProperties;
        this.objectMapper = objectMapper;
        this.apiDocsCache = Caffeine.newBuilder()
            .maximumSize(10)
            .expireAfterWrite(Duration.ofMinutes(30))
            .build();
    }
    
    @GetMapping(
        value = "/{group}",
        produces = MediaType.APPLICATION_JSON_VALUE
    )
    public ResponseEntity<String> getCachedApiDocs(
        @PathVariable String group,
        HttpServletRequest request
    ) {
        String cacheKey = group + "_" + getVersionHash();
        
        String cachedDocs = apiDocsCache.get(cacheKey, key -> {
            // 生成文檔的邏輯
            return generateApiDocs(group);
        });
        
        return ResponseEntity.ok()
            .cacheControl(CacheControl.maxAge(Duration.ofHours(1)))
            .eTag(calculateETag(cachedDocs))
            .body(cachedDocs);
    }
    
    private String getVersionHash() {
        // 基於應用程式版本和配置生成雜湊
        String version = getClass().getPackage().getImplementationVersion();
        return DigestUtils.md5Hex(version != null ? version : "dev");
    }
    
    private String calculateETag(String content) {
        return "\"" + DigestUtils.md5Hex(content) + "\"";
    }
}

3. 環境配置最佳實踐

# application-dev.yml
springdoc:
  api-docs:
    enabled: true
  swagger-ui:
    enabled: true
    try-it-out-enabled: true
    operations-sorter: method
    tags-sorter: alpha
    display-request-duration: true
    doc-expansion: list
    default-models-expand-depth: 2

# application-prod.yml  
springdoc:
  api-docs:
    enabled: false  # 生產環境關閉
  swagger-ui:
    enabled: false  # 生產環境關閉

# application-staging.yml
springdoc:
  api-docs:
    enabled: true
  swagger-ui:
    enabled: true
    try-it-out-enabled: false  # 測試環境禁止直接測試

監控與分析

1. API 使用情況追蹤

@Component
public class ApiUsageTracker {
    
    private final MeterRegistry meterRegistry;
    private final Counter apiCallsCounter;
    private final Timer apiResponseTimer;
    
    public ApiUsageTracker(MeterRegistry meterRegistry) {
        this.meterRegistry = meterRegistry;
        this.apiCallsCounter = Counter.builder("api.calls")
            .description("API 呼叫次數")
            .register(meterRegistry);
        this.apiResponseTimer = Timer.builder("api.response.time")
            .description("API 回應時間")
            .register(meterRegistry);
    }
    
    @EventListener
    public void trackApiCall(ApiCallEvent event) {
        apiCallsCounter
            .tag("endpoint", event.getEndpoint())
            .tag("method", event.getMethod())
            .tag("status", String.valueOf(event.getStatusCode()))
            .increment();
            
        apiResponseTimer
            .tag("endpoint", event.getEndpoint())
            .record(event.getResponseTime(), TimeUnit.MILLISECONDS);
    }
}

@RestController
@RequestMapping("/api/v1/analytics")
@Tag(name = "API Analytics", description = "API 使用情況分析")
public class ApiAnalyticsController {
    
    private final MeterRegistry meterRegistry;
    
    public ApiAnalyticsController(MeterRegistry meterRegistry) {
        this.meterRegistry = meterRegistry;
    }
    
    @GetMapping("/metrics")
    @Operation(summary = "獲取 API 使用統計")
    public ResponseEntity<ApiMetrics> getApiMetrics() {
        Map<String, Double> endpointCalls = new HashMap<>();
        Map<String, Double> averageResponseTimes = new HashMap<>();
        
        meterRegistry.getMeters().forEach(meter -> {
            if (meter instanceof Counter counter && meter.getId().getName().equals("api.calls")) {
                String endpoint = meter.getId().getTag("endpoint");
                endpointCalls.put(endpoint, counter.count());
            }
            
            if (meter instanceof Timer timer && meter.getId().getName().equals("api.response.time")) {
                String endpoint = meter.getId().getTag("endpoint");
                averageResponseTimes.put(endpoint, timer.mean(TimeUnit.MILLISECONDS));
            }
        });
        
        ApiMetrics metrics = new ApiMetrics(endpointCalls, averageResponseTimes);
        return ResponseEntity.ok(metrics);
    }
}

總結

Swagger/OpenAPI 是現代 API 開發的必備工具，提供了從文檔生成到測試、監控的完整解決方案。透過本文的深入介紹，我們了解到：

Spring RestTemplate 完整實戰指南：HTTP 客戶端最佳實踐

Wed, 30 Jun 2021 19:39:44 +0800

注意：RestTemplate 自 Spring 5.0 起已進入 maintenance mode，Spring 官方建議新專案改用 RestClient（Spring 6.1+）或 WebClient（reactive 場景）。本文保留 RestTemplate 用法作為參考，並在最後提供三種 HTTP client 的選擇建議。

概述

RestTemplate 是 Spring Framework 提供的同步 HTTP 客戶端，用於簡化 RESTful Web 服務的調用。雖然在 Spring 5.0 之後被標記為維護模式（推薦使用 WebClient），但在許多現有項目中仍廣泛使用。本文將深入介紹 RestTemplate 的完整使用方法和最佳實踐。

核心特性

簡化 HTTP 操作：提供便捷的 GET、POST、PUT、DELETE 等方法
自動序列化：支援 JSON、XML 等格式的自動轉換
異常處理：統一的異常處理機制
攔截器支援：請求和響應攔截器
靈活配置：連接池、超時、重試等配置

適用場景

微服務通信：服務間的 HTTP 調用
第三方 API 整合：調用外部 REST API
資料同步：不同系統間的資料交換
輕量級 HTTP 客戶端：簡單的 HTTP 請求需求

基礎配置與設定

1. 依賴配置

<dependencies>
    <!-- Spring Boot Starter Web -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    
    <!-- Apache HttpClient（可選，提供更好的連接池支援） -->
    <dependency>
        <groupId>org.apache.httpcomponents</groupId>
        <artifactId>httpclient</artifactId>
    </dependency>
    
    <!-- OkHttp（可選，現代化的 HTTP 客戶端） -->
    <dependency>
        <groupId>com.squareup.okhttp3</groupId>
        <artifactId>okhttp</artifactId>
    </dependency>
    
    <!-- Jackson（JSON 處理） -->
    <dependency>
        <groupId>com.fasterxml.jackson.core</groupId>
        <artifactId>jackson-databind</artifactId>
    </dependency>
    
    <!-- Testing -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-test</artifactId>
        <scope>test</scope>
    </dependency>
</dependencies>

2. 基礎配置類

package com.example.resttemplate.config;

import org.apache.http.client.HttpClient;
import org.apache.http.impl.client.HttpClients;
import org.apache.http.impl.conn.PoolingHttpClientConnectionManager;
import org.springframework.boot.web.client.RestTemplateBuilder;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.client.HttpComponentsClientHttpRequestFactory;
import org.springframework.http.client.SimpleClientHttpRequestFactory;
import org.springframework.http.converter.json.MappingJackson2HttpMessageConverter;
import org.springframework.web.client.RestTemplate;

import java.time.Duration;
import java.util.Arrays;

@Configuration
public class RestTemplateConfig {
    
    /**
     * 基礎 RestTemplate 配置
     */
    @Bean("basicRestTemplate")
    public RestTemplate basicRestTemplate() {
        SimpleClientHttpRequestFactory factory = new SimpleClientHttpRequestFactory();
        factory.setConnectTimeout(5000);  // 連接超時 5 秒
        factory.setReadTimeout(10000);    // 讀取超時 10 秒
        
        RestTemplate restTemplate = new RestTemplate(factory);
        
        // 添加 JSON 消息轉換器
        restTemplate.getMessageConverters().add(new MappingJackson2HttpMessageConverter());
        
        return restTemplate;
    }
    
    /**
     * 使用 RestTemplateBuilder 構建（推薦方式）
     */
    @Bean("standardRestTemplate")
    public RestTemplate standardRestTemplate(RestTemplateBuilder builder) {
        return builder
                .setConnectTimeout(Duration.ofSeconds(5))
                .setReadTimeout(Duration.ofSeconds(10))
                .additionalMessageConverters(new MappingJackson2HttpMessageConverter())
                .build();
    }
    
    /**
     * 高性能 RestTemplate（使用 Apache HttpClient）
     */
    @Bean("highPerformanceRestTemplate")
    public RestTemplate highPerformanceRestTemplate() {
        // 連接池管理器
        PoolingHttpClientConnectionManager connectionManager = new PoolingHttpClientConnectionManager();
        connectionManager.setMaxTotal(200);          // 最大連接數
        connectionManager.setDefaultMaxPerRoute(50); // 每個路由的最大連接數
        
        // HttpClient 配置
        HttpClient httpClient = HttpClients.custom()
                .setConnectionManager(connectionManager)
                .setConnectionManagerShared(true)
                .build();
        
        // 請求工廠
        HttpComponentsClientHttpRequestFactory factory = new HttpComponentsClientHttpRequestFactory(httpClient);
        factory.setConnectTimeout(5000);
        factory.setReadTimeout(10000);
        
        return new RestTemplate(factory);
    }
    
    /**
     * 帶有自訂配置的 RestTemplate
     */
    @Bean("customRestTemplate")
    public RestTemplate customRestTemplate() {
        RestTemplate restTemplate = new RestTemplate();
        
        // 添加攔截器
        restTemplate.setInterceptors(Arrays.asList(
                new LoggingInterceptor(),
                new AuthenticationInterceptor(),
                new RetryInterceptor()
        ));
        
        // 設置錯誤處理器
        restTemplate.setErrorHandler(new CustomResponseErrorHandler());
        
        return restTemplate;
    }
}

3. 屬性配置

# application.yml
rest-client:
  connection:
    timeout: 5000
    read-timeout: 10000
    max-connections: 200
    max-connections-per-route: 50
  retry:
    max-attempts: 3
    delay: 1000
  base-urls:
    user-service: "http://localhost:8081"
    order-service: "http://localhost:8082"
    payment-service: "http://localhost:8083"

@ConfigurationProperties(prefix = "rest-client")
@Component
public class RestClientProperties {
    
    private Connection connection = new Connection();
    private Retry retry = new Retry();
    private Map<String, String> baseUrls = new HashMap<>();
    
    // getter 和 setter 方法
    
    public static class Connection {
        private int timeout = 5000;
        private int readTimeout = 10000;
        private int maxConnections = 200;
        private int maxConnectionsPerRoute = 50;
        
        // getter 和 setter 方法
    }
    
    public static class Retry {
        private int maxAttempts = 3;
        private long delay = 1000;
        
        // getter 和 setter 方法
    }
}

基礎 HTTP 操作

1. GET 請求

package com.example.resttemplate.service;

import org.springframework.beans.factory.annotation.Qualifier;
import org.springframework.core.ParameterizedTypeReference;
import org.springframework.http.*;
import org.springframework.stereotype.Service;
import org.springframework.web.client.RestTemplate;
import org.springframework.web.util.UriComponentsBuilder;

import java.net.URI;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

@Service
public class RestClientService {
    
    private final RestTemplate restTemplate;
    
    public RestClientService(@Qualifier("standardRestTemplate") RestTemplate restTemplate) {
        this.restTemplate = restTemplate;
    }
    
    /**
     * 基礎 GET 請求
     */
    public User getUserById(Long userId) {
        String url = "https://api.example.com/users/{id}";
        return restTemplate.getForObject(url, User.class, userId);
    }
    
    /**
     * 帶有查詢參數的 GET 請求
     */
    public List<User> getUsersByDepartment(String department, int page, int size) {
        String url = "https://api.example.com/users";
        
        URI uri = UriComponentsBuilder.fromUriString(url)
                .queryParam("department", department)
                .queryParam("page", page)
                .queryParam("size", size)
                .build()
                .toUri();
        
        ResponseEntity<List<User>> response = restTemplate.exchange(
                uri,
                HttpMethod.GET,
                null,
                new ParameterizedTypeReference<List<User>>() {}
        );
        
        return response.getBody();
    }
    
    /**
     * 使用 Map 作為 URI 變數
     */
    public User getUserWithMap(Long userId) {
        String url = "https://api.example.com/users/{id}/profile/{section}";
        
        Map<String, Object> uriVariables = new HashMap<>();
        uriVariables.put("id", userId);
        uriVariables.put("section", "basic");
        
        return restTemplate.getForObject(url, User.class, uriVariables);
    }
    
    /**
     * 帶有請求頭的 GET 請求
     */
    public User getUserWithHeaders(Long userId, String authToken) {
        String url = "https://api.example.com/users/{id}";
        
        HttpHeaders headers = new HttpHeaders();
        headers.set("Authorization", "Bearer " + authToken);
        headers.set("Accept", MediaType.APPLICATION_JSON_VALUE);
        
        HttpEntity<String> entity = new HttpEntity<>(headers);
        
        ResponseEntity<User> response = restTemplate.exchange(
                url,
                HttpMethod.GET,
                entity,
                User.class,
                userId
        );
        
        return response.getBody();
    }
    
    /**
     * 獲取完整的響應資訊
     */
    public ResponseEntity<User> getUserWithFullResponse(Long userId) {
        String url = "https://api.example.com/users/{id}";
        
        ResponseEntity<User> response = restTemplate.getForEntity(url, User.class, userId);
        
        // 可以獲取狀態碼、頭部、主體等資訊
        HttpStatus statusCode = response.getStatusCode();
        HttpHeaders responseHeaders = response.getHeaders();
        User user = response.getBody();
        
        return response;
    }
}

2. POST 請求

/**
 * POST 請求範例
 */
@Service
public class PostRequestService {
    
    private final RestTemplate restTemplate;
    
    public PostRequestService(@Qualifier("standardRestTemplate") RestTemplate restTemplate) {
        this.restTemplate = restTemplate;
    }
    
    /**
     * 基礎 POST 請求
     */
    public User createUser(User newUser) {
        String url = "https://api.example.com/users";
        return restTemplate.postForObject(url, newUser, User.class);
    }
    
    /**
     * 帶有請求頭的 POST 請求
     */
    public ResponseEntity<User> createUserWithHeaders(User newUser, String authToken) {
        String url = "https://api.example.com/users";
        
        HttpHeaders headers = new HttpHeaders();
        headers.setContentType(MediaType.APPLICATION_JSON);
        headers.set("Authorization", "Bearer " + authToken);
        
        HttpEntity<User> request = new HttpEntity<>(newUser, headers);
        
        return restTemplate.postForEntity(url, request, User.class);
    }
    
    /**
     * 表單數據 POST 請求
     */
    public String submitForm(String email, String password) {
        String url = "https://api.example.com/login";
        
        HttpHeaders headers = new HttpHeaders();
        headers.setContentType(MediaType.APPLICATION_FORM_URLENCODED);
        
        MultiValueMap<String, String> formData = new LinkedMultiValueMap<>();
        formData.add("email", email);
        formData.add("password", password);
        
        HttpEntity<MultiValueMap<String, String>> request = new HttpEntity<>(formData, headers);
        
        return restTemplate.postForObject(url, request, String.class);
    }
    
    /**
     * JSON 數據 POST 請求
     */
    public ApiResponse<User> createUserWithResponse(CreateUserRequest request) {
        String url = "https://api.example.com/users";
        
        HttpHeaders headers = new HttpHeaders();
        headers.setContentType(MediaType.APPLICATION_JSON);
        headers.set("X-Request-ID", generateRequestId());
        
        HttpEntity<CreateUserRequest> httpEntity = new HttpEntity<>(request, headers);
        
        ResponseEntity<ApiResponse<User>> response = restTemplate.exchange(
                url,
                HttpMethod.POST,
                httpEntity,
                new ParameterizedTypeReference<ApiResponse<User>>() {}
        );
        
        return response.getBody();
    }
    
    /**
     * 文件上傳 POST 請求
     */
    public String uploadFile(MultipartFile file, String description) {
        String url = "https://api.example.com/files/upload";
        
        HttpHeaders headers = new HttpHeaders();
        headers.setContentType(MediaType.MULTIPART_FORM_DATA);
        
        MultiValueMap<String, Object> formData = new LinkedMultiValueMap<>();
        formData.add("file", file.getResource());
        formData.add("description", description);
        
        HttpEntity<MultiValueMap<String, Object>> request = new HttpEntity<>(formData, headers);
        
        return restTemplate.postForObject(url, request, String.class);
    }
    
    private String generateRequestId() {
        return UUID.randomUUID().toString();
    }
}

3. PUT 和 DELETE 請求

/**
 * PUT 和 DELETE 請求範例
 */
@Service
public class UpdateDeleteService {
    
    private final RestTemplate restTemplate;
    
    public UpdateDeleteService(@Qualifier("standardRestTemplate") RestTemplate restTemplate) {
        this.restTemplate = restTemplate;
    }
    
    /**
     * PUT 更新請求
     */
    public User updateUser(Long userId, User updatedUser) {
        String url = "https://api.example.com/users/{id}";
        
        HttpHeaders headers = new HttpHeaders();
        headers.setContentType(MediaType.APPLICATION_JSON);
        
        HttpEntity<User> request = new HttpEntity<>(updatedUser, headers);
        
        ResponseEntity<User> response = restTemplate.exchange(
                url,
                HttpMethod.PUT,
                request,
                User.class,
                userId
        );
        
        return response.getBody();
    }
    
    /**
     * PATCH 部分更新請求
     */
    public User partialUpdateUser(Long userId, Map<String, Object> updates) {
        String url = "https://api.example.com/users/{id}";
        
        HttpHeaders headers = new HttpHeaders();
        headers.setContentType(MediaType.APPLICATION_JSON);
        
        HttpEntity<Map<String, Object>> request = new HttpEntity<>(updates, headers);
        
        ResponseEntity<User> response = restTemplate.exchange(
                url,
                HttpMethod.PATCH,
                request,
                User.class,
                userId
        );
        
        return response.getBody();
    }
    
    /**
     * DELETE 刪除請求
     */
    public void deleteUser(Long userId) {
        String url = "https://api.example.com/users/{id}";
        restTemplate.delete(url, userId);
    }
    
    /**
     * 帶有響應的 DELETE 請求
     */
    public ApiResponse<Void> deleteUserWithResponse(Long userId, String authToken) {
        String url = "https://api.example.com/users/{id}";
        
        HttpHeaders headers = new HttpHeaders();
        headers.set("Authorization", "Bearer " + authToken);
        
        HttpEntity<String> request = new HttpEntity<>(headers);
        
        ResponseEntity<ApiResponse<Void>> response = restTemplate.exchange(
                url,
                HttpMethod.DELETE,
                request,
                new ParameterizedTypeReference<ApiResponse<Void>>() {},
                userId
        );
        
        return response.getBody();
    }
    
    /**
     * 批量刪除請求
     */
    public void deleteUsers(List<Long> userIds) {
        String url = "https://api.example.com/users/batch";
        
        HttpHeaders headers = new HttpHeaders();
        headers.setContentType(MediaType.APPLICATION_JSON);
        
        DeleteBatchRequest request = new DeleteBatchRequest(userIds);
        HttpEntity<DeleteBatchRequest> httpEntity = new HttpEntity<>(request, headers);
        
        restTemplate.exchange(
                url,
                HttpMethod.DELETE,
                httpEntity,
                Void.class
        );
    }
}

高級功能與自訂

1. 攔截器實作

/**
 * 日誌攔截器
 */
@Component
public class LoggingInterceptor implements ClientHttpRequestInterceptor {
    
    private static final Logger logger = LoggerFactory.getLogger(LoggingInterceptor.class);
    
    @Override
    public ClientHttpResponse intercept(
            HttpRequest request,
            byte[] body,
            ClientHttpRequestExecution execution) throws IOException {
        
        logRequest(request, body);
        
        long startTime = System.currentTimeMillis();
        ClientHttpResponse response = execution.execute(request, body);
        long duration = System.currentTimeMillis() - startTime;
        
        logResponse(response, duration);
        
        return response;
    }
    
    private void logRequest(HttpRequest request, byte[] body) {
        logger.info("===========================request begin================================================");
        logger.info("URI         : {}", request.getURI());
        logger.info("Method      : {}", request.getMethod());
        logger.info("Headers     : {}", request.getHeaders());
        logger.info("Request body: {}", new String(body, StandardCharsets.UTF_8));
        logger.info("==========================request end================================================");
    }
    
    private void logResponse(ClientHttpResponse response, long duration) throws IOException {
        logger.info("============================response begin==========================================");
        logger.info("Status code  : {}", response.getStatusCode());
        logger.info("Status text  : {}", response.getStatusText());
        logger.info("Headers      : {}", response.getHeaders());
        logger.info("Duration     : {} ms", duration);
        logger.info("=======================response end=================================================");
    }
}

/**
 * 認證攔截器
 */
@Component
public class AuthenticationInterceptor implements ClientHttpRequestInterceptor {
    
    private final TokenService tokenService;
    
    public AuthenticationInterceptor(TokenService tokenService) {
        this.tokenService = tokenService;
    }
    
    @Override
    public ClientHttpResponse intercept(
            HttpRequest request,
            byte[] body,
            ClientHttpRequestExecution execution) throws IOException {
        
        // 獲取並設置認證 token
        String token = tokenService.getCurrentToken();
        if (token != null) {
            request.getHeaders().set("Authorization", "Bearer " + token);
        }
        
        return execution.execute(request, body);
    }
}

/**
 * 重試攔截器
 */
@Component
public class RetryInterceptor implements ClientHttpRequestInterceptor {
    
    private static final Logger logger = LoggerFactory.getLogger(RetryInterceptor.class);
    
    private final int maxRetries;
    private final long retryDelay;
    
    public RetryInterceptor(@Value("${rest-client.retry.max-attempts:3}") int maxRetries,
                           @Value("${rest-client.retry.delay:1000}") long retryDelay) {
        this.maxRetries = maxRetries;
        this.retryDelay = retryDelay;
    }
    
    @Override
    public ClientHttpResponse intercept(
            HttpRequest request,
            byte[] body,
            ClientHttpRequestExecution execution) throws IOException {
        
        IOException lastException = null;
        
        for (int attempt = 1; attempt <= maxRetries; attempt++) {
            try {
                ClientHttpResponse response = execution.execute(request, body);
                
                // 檢查是否需要重試（例如：5xx 錯誤）
                if (shouldRetry(response) && attempt < maxRetries) {
                    logger.warn("Request failed with status {}, retrying... (attempt {}/{})",
                               response.getStatusCode(), attempt, maxRetries);
                    
                    // 等待後重試
                    try {
                        Thread.sleep(retryDelay * attempt); // 指數退避
                    } catch (InterruptedException e) {
                        Thread.currentThread().interrupt();
                        throw new IOException("Interrupted during retry delay", e);
                    }
                    continue;
                }
                
                return response;
                
            } catch (IOException e) {
                lastException = e;
                
                if (attempt < maxRetries) {
                    logger.warn("Request failed, retrying... (attempt {}/{}) - {}", 
                               attempt, maxRetries, e.getMessage());
                    
                    try {
                        Thread.sleep(retryDelay * attempt);
                    } catch (InterruptedException ie) {
                        Thread.currentThread().interrupt();
                        throw new IOException("Interrupted during retry delay", ie);
                    }
                } else {
                    logger.error("Request failed after {} attempts", maxRetries, e);
                }
            }
        }
        
        throw lastException;
    }
    
    private boolean shouldRetry(ClientHttpResponse response) throws IOException {
        HttpStatus status = response.getStatusCode();
        return status.is5xxServerError() || status == HttpStatus.REQUEST_TIMEOUT;
    }
}

2. 自訂錯誤處理器

/**
 * 自訂響應錯誤處理器
 */
@Component
public class CustomResponseErrorHandler implements ResponseErrorHandler {
    
    private static final Logger logger = LoggerFactory.getLogger(CustomResponseErrorHandler.class);
    
    @Override
    public boolean hasError(ClientHttpResponse response) throws IOException {
        HttpStatus status = response.getStatusCode();
        return status.series() == HttpStatus.Series.CLIENT_ERROR ||
               status.series() == HttpStatus.Series.SERVER_ERROR;
    }
    
    @Override
    public void handleError(ClientHttpResponse response) throws IOException {
        HttpStatus status = response.getStatusCode();
        String responseBody = getResponseBody(response);
        
        logger.error("HTTP Error: {} - {}, Response: {}", 
                    status.value(), status.getReasonPhrase(), responseBody);
        
        switch (status.series()) {
            case CLIENT_ERROR:
                handleClientError(status, responseBody);
                break;
            case SERVER_ERROR:
                handleServerError(status, responseBody);
                break;
            default:
                throw new RestClientException("Unknown HTTP error: " + status);
        }
    }
    
    private void handleClientError(HttpStatus status, String responseBody) {
        switch (status) {
            case BAD_REQUEST:
                throw new BadRequestException("Invalid request: " + responseBody);
            case UNAUTHORIZED:
                throw new UnauthorizedException("Authentication required");
            case FORBIDDEN:
                throw new ForbiddenException("Access denied");
            case NOT_FOUND:
                throw new NotFoundException("Resource not found");
            case CONFLICT:
                throw new ConflictException("Resource conflict: " + responseBody);
            case TOO_MANY_REQUESTS:
                throw new RateLimitException("Rate limit exceeded");
            default:
                throw new ClientErrorException("Client error: " + status + " - " + responseBody);
        }
    }
    
    private void handleServerError(HttpStatus status, String responseBody) {
        switch (status) {
            case INTERNAL_SERVER_ERROR:
                throw new ServerErrorException("Internal server error: " + responseBody);
            case BAD_GATEWAY:
                throw new BadGatewayException("Bad gateway");
            case SERVICE_UNAVAILABLE:
                throw new ServiceUnavailableException("Service unavailable");
            case GATEWAY_TIMEOUT:
                throw new GatewayTimeoutException("Gateway timeout");
            default:
                throw new ServerErrorException("Server error: " + status + " - " + responseBody);
        }
    }
    
    private String getResponseBody(ClientHttpResponse response) {
        try (InputStream inputStream = response.getBody()) {
            return StreamUtils.copyToString(inputStream, StandardCharsets.UTF_8);
        } catch (IOException e) {
            logger.warn("Failed to read response body", e);
            return "Unable to read response body";
        }
    }
}

3. 自訂異常類別

// 基礎異常類別
public abstract class RestClientException extends RuntimeException {
    public RestClientException(String message) {
        super(message);
    }
    
    public RestClientException(String message, Throwable cause) {
        super(message, cause);
    }
}

// 客戶端錯誤異常
public class ClientErrorException extends RestClientException {
    public ClientErrorException(String message) {
        super(message);
    }
}

public class BadRequestException extends ClientErrorException {
    public BadRequestException(String message) {
        super(message);
    }
}

public class UnauthorizedException extends ClientErrorException {
    public UnauthorizedException(String message) {
        super(message);
    }
}

public class ForbiddenException extends ClientErrorException {
    public ForbiddenException(String message) {
        super(message);
    }
}

public class NotFoundException extends ClientErrorException {
    public NotFoundException(String message) {
        super(message);
    }
}

public class ConflictException extends ClientErrorException {
    public ConflictException(String message) {
        super(message);
    }
}

public class RateLimitException extends ClientErrorException {
    public RateLimitException(String message) {
        super(message);
    }
}

// 服務器錯誤異常
public class ServerErrorException extends RestClientException {
    public ServerErrorException(String message) {
        super(message);
    }
}

public class BadGatewayException extends ServerErrorException {
    public BadGatewayException(String message) {
        super(message);
    }
}

public class ServiceUnavailableException extends ServerErrorException {
    public ServiceUnavailableException(String message) {
        super(message);
    }
}

public class GatewayTimeoutException extends ServerErrorException {
    public GatewayTimeoutException(String message) {
        super(message);
    }
}

實際應用場景

1. 微服務通信

/**
 * 用戶服務客戶端
 */
@Service
public class UserServiceClient {
    
    private final RestTemplate restTemplate;
    private final RestClientProperties properties;
    
    public UserServiceClient(@Qualifier("highPerformanceRestTemplate") RestTemplate restTemplate,
                            RestClientProperties properties) {
        this.restTemplate = restTemplate;
        this.properties = properties;
    }
    
    /**
     * 獲取用戶資訊
     */
    public Optional<User> getUserById(Long userId) {
        String url = properties.getBaseUrls().get("user-service") + "/api/users/{id}";
        
        try {
            User user = restTemplate.getForObject(url, User.class, userId);
            return Optional.ofNullable(user);
        } catch (NotFoundException e) {
            return Optional.empty();
        }
    }
    
    /**
     * 批量獲取用戶資訊
     */
    public List<User> getUsersByIds(List<Long> userIds) {
        String url = properties.getBaseUrls().get("user-service") + "/api/users/batch";
        
        HttpHeaders headers = new HttpHeaders();
        headers.setContentType(MediaType.APPLICATION_JSON);
        
        HttpEntity<List<Long>> request = new HttpEntity<>(userIds, headers);
        
        ResponseEntity<List<User>> response = restTemplate.exchange(
                url,
                HttpMethod.POST,
                request,
                new ParameterizedTypeReference<List<User>>() {}
        );
        
        return response.getBody();
    }
    
    /**
     * 創建用戶
     */
    public User createUser(CreateUserRequest request) {
        String url = properties.getBaseUrls().get("user-service") + "/api/users";
        
        HttpHeaders headers = new HttpHeaders();
        headers.setContentType(MediaType.APPLICATION_JSON);
        
        HttpEntity<CreateUserRequest> httpEntity = new HttpEntity<>(request, headers);
        
        return restTemplate.postForObject(url, httpEntity, User.class);
    }
    
    /**
     * 更新用戶狀態
     */
    public void updateUserStatus(Long userId, UserStatus status) {
        String url = properties.getBaseUrls().get("user-service") + "/api/users/{id}/status";
        
        HttpHeaders headers = new HttpHeaders();
        headers.setContentType(MediaType.APPLICATION_JSON);
        
        UpdateStatusRequest request = new UpdateStatusRequest(status);
        HttpEntity<UpdateStatusRequest> httpEntity = new HttpEntity<>(request, headers);
        
        restTemplate.exchange(url, HttpMethod.PUT, httpEntity, Void.class, userId);
    }
}

/**
 * 訂單服務客戶端
 */
@Service
public class OrderServiceClient {
    
    private final RestTemplate restTemplate;
    private final RestClientProperties properties;
    
    public OrderServiceClient(@Qualifier("highPerformanceRestTemplate") RestTemplate restTemplate,
                             RestClientProperties properties) {
        this.restTemplate = restTemplate;
        this.properties = properties;
    }
    
    /**
     * 創建訂單
     */
    public Order createOrder(CreateOrderRequest request) {
        String url = properties.getBaseUrls().get("order-service") + "/api/orders";
        
        HttpHeaders headers = new HttpHeaders();
        headers.setContentType(MediaType.APPLICATION_JSON);
        headers.set("X-Request-ID", UUID.randomUUID().toString());
        
        HttpEntity<CreateOrderRequest> httpEntity = new HttpEntity<>(request, headers);
        
        ResponseEntity<Order> response = restTemplate.postForEntity(url, httpEntity, Order.class);
        
        if (response.getStatusCode() == HttpStatus.CREATED) {
            return response.getBody();
        } else {
            throw new RuntimeException("Failed to create order: " + response.getStatusCode());
        }
    }
    
    /**
     * 獲取用戶訂單列表
     */
    public PagedResponse<Order> getUserOrders(Long userId, int page, int size) {
        String url = properties.getBaseUrls().get("order-service") + "/api/users/{userId}/orders";
        
        URI uri = UriComponentsBuilder.fromUriString(url)
                .queryParam("page", page)
                .queryParam("size", size)
                .build(userId);
        
        ResponseEntity<PagedResponse<Order>> response = restTemplate.exchange(
                uri,
                HttpMethod.GET,
                null,
                new ParameterizedTypeReference<PagedResponse<Order>>() {}
        );
        
        return response.getBody();
    }
    
    /**
     * 取消訂單
     */
    public void cancelOrder(Long orderId, String reason) {
        String url = properties.getBaseUrls().get("order-service") + "/api/orders/{id}/cancel";
        
        HttpHeaders headers = new HttpHeaders();
        headers.setContentType(MediaType.APPLICATION_JSON);
        
        CancelOrderRequest request = new CancelOrderRequest(reason);
        HttpEntity<CancelOrderRequest> httpEntity = new HttpEntity<>(request, headers);
        
        restTemplate.exchange(url, HttpMethod.POST, httpEntity, Void.class, orderId);
    }
}

2. 第三方 API 整合

/**
 * 第三方支付服務整合
 */
@Service
public class PaymentGatewayClient {
    
    private final RestTemplate restTemplate;
    private final PaymentConfig paymentConfig;
    
    public PaymentGatewayClient(@Qualifier("customRestTemplate") RestTemplate restTemplate,
                               PaymentConfig paymentConfig) {
        this.restTemplate = restTemplate;
        this.paymentConfig = paymentConfig;
    }
    
    /**
     * 創建支付訂單
     */
    public PaymentResponse createPayment(PaymentRequest paymentRequest) {
        String url = paymentConfig.getBaseUrl() + "/api/v1/payments";
        
        HttpHeaders headers = createAuthHeaders();
        headers.setContentType(MediaType.APPLICATION_JSON);
        
        HttpEntity<PaymentRequest> request = new HttpEntity<>(paymentRequest, headers);
        
        try {
            ResponseEntity<PaymentResponse> response = restTemplate.postForEntity(
                    url, request, PaymentResponse.class);
            
            return response.getBody();
        } catch (Exception e) {
            throw new PaymentException("Failed to create payment", e);
        }
    }
    
    /**
     * 查詢支付狀態
     */
    public PaymentStatus queryPaymentStatus(String paymentId) {
        String url = paymentConfig.getBaseUrl() + "/api/v1/payments/{paymentId}/status";
        
        HttpHeaders headers = createAuthHeaders();
        HttpEntity<String> request = new HttpEntity<>(headers);
        
        try {
            ResponseEntity<PaymentStatusResponse> response = restTemplate.exchange(
                    url, HttpMethod.GET, request, PaymentStatusResponse.class, paymentId);
            
            return response.getBody().getStatus();
        } catch (NotFoundException e) {
            throw new PaymentNotFoundException("Payment not found: " + paymentId);
        }
    }
    
    /**
     * 退款請求
     */
    public RefundResponse processRefund(String paymentId, RefundRequest refundRequest) {
        String url = paymentConfig.getBaseUrl() + "/api/v1/payments/{paymentId}/refund";
        
        HttpHeaders headers = createAuthHeaders();
        headers.setContentType(MediaType.APPLICATION_JSON);
        
        HttpEntity<RefundRequest> request = new HttpEntity<>(refundRequest, headers);
        
        try {
            ResponseEntity<RefundResponse> response = restTemplate.exchange(
                    url, HttpMethod.POST, request, RefundResponse.class, paymentId);
            
            return response.getBody();
        } catch (Exception e) {
            throw new RefundException("Failed to process refund", e);
        }
    }
    
    /**
     * 創建認證頭
     */
    private HttpHeaders createAuthHeaders() {
        HttpHeaders headers = new HttpHeaders();
        
        String auth = paymentConfig.getApiKey() + ":" + paymentConfig.getApiSecret();
        String encodedAuth = Base64.getEncoder().encodeToString(auth.getBytes());
        
        headers.set("Authorization", "Basic " + encodedAuth);
        headers.set("X-API-Version", paymentConfig.getApiVersion());
        
        return headers;
    }
}

/**
 * 外部資料同步服務
 */
@Service
public class DataSyncService {
    
    private final RestTemplate restTemplate;
    private final DataSyncConfig config;
    
    public DataSyncService(@Qualifier("standardRestTemplate") RestTemplate restTemplate,
                          DataSyncConfig config) {
        this.restTemplate = restTemplate;
        this.config = config;
    }
    
    /**
     * 同步用戶資料
     */
    @Async
    public CompletableFuture<SyncResult> syncUserData() {
        String url = config.getExternalApiUrl() + "/users/export";
        
        HttpHeaders headers = new HttpHeaders();
        headers.set("Authorization", "Bearer " + config.getAccessToken());
        headers.set("Accept", MediaType.APPLICATION_JSON_VALUE);
        
        HttpEntity<String> request = new HttpEntity<>(headers);
        
        try {
            ResponseEntity<List<ExternalUser>> response = restTemplate.exchange(
                    url, 
                    HttpMethod.GET, 
                    request, 
                    new ParameterizedTypeReference<List<ExternalUser>>() {}
            );
            
            List<ExternalUser> externalUsers = response.getBody();
            
            // 處理同步邏輯
            int syncedCount = processSyncData(externalUsers);
            
            return CompletableFuture.completedFuture(
                    new SyncResult(true, syncedCount, "Sync completed successfully"));
            
        } catch (Exception e) {
            return CompletableFuture.completedFuture(
                    new SyncResult(false, 0, "Sync failed: " + e.getMessage()));
        }
    }
    
    private int processSyncData(List<ExternalUser> externalUsers) {
        // 同步處理邏輯
        return externalUsers != null ? externalUsers.size() : 0;
    }
}

效能優化與監控

1. 連接池優化

/**
 * 高效能 RestTemplate 配置
 */
@Configuration
public class HighPerformanceRestTemplateConfig {
    
    @Bean("pooledRestTemplate")
    public RestTemplate pooledRestTemplate() {
        // 連接池管理器配置
        PoolingHttpClientConnectionManager connectionManager = new PoolingHttpClientConnectionManager();
        connectionManager.setMaxTotal(300);              // 最大連接數
        connectionManager.setDefaultMaxPerRoute(100);    // 每個路由的最大連接數
        connectionManager.setValidateAfterInactivity(2000); // 連接空閒檢查時間
        
        // 連接池清理策略
        connectionManager.closeExpiredConnections();
        connectionManager.closeIdleConnections(30, TimeUnit.SECONDS);
        
        // 請求配置
        RequestConfig requestConfig = RequestConfig.custom()
                .setConnectionRequestTimeout(5000)    // 從連接池獲取連接的超時時間
                .setConnectTimeout(5000)              // 連接超時時間
                .setSocketTimeout(30000)              // 讀取超時時間
                .build();
        
        // HttpClient 配置
        CloseableHttpClient httpClient = HttpClients.custom()
                .setConnectionManager(connectionManager)
                .setDefaultRequestConfig(requestConfig)
                .setRetryHandler(new DefaultHttpRequestRetryHandler(3, true))
                .setKeepAliveStrategy((response, context) -> 30 * 1000) // 30 秒 keep-alive
                .build();
        
        // 請求工廠
        HttpComponentsClientHttpRequestFactory factory = new HttpComponentsClientHttpRequestFactory(httpClient);
        
        return new RestTemplate(factory);
    }
    
    /**
     * 連接池監控
     */
    @Component
    public class ConnectionPoolMonitor {
        
        private final PoolingHttpClientConnectionManager connectionManager;
        private final MeterRegistry meterRegistry;
        
        public ConnectionPoolMonitor(PoolingHttpClientConnectionManager connectionManager,
                                   MeterRegistry meterRegistry) {
            this.connectionManager = connectionManager;
            this.meterRegistry = meterRegistry;
            
            // 註冊連接池指標
            Gauge.builder("http.connections.total")
                    .description("Total connections in pool")
                    .register(meterRegistry, this, monitor -> monitor.connectionManager.getTotalStats().getMax());
            
            Gauge.builder("http.connections.available")
                    .description("Available connections in pool")
                    .register(meterRegistry, this, monitor -> monitor.connectionManager.getTotalStats().getAvailable());
            
            Gauge.builder("http.connections.leased")
                    .description("Leased connections in pool")
                    .register(meterRegistry, this, monitor -> monitor.connectionManager.getTotalStats().getLeased());
        }
        
        @EventListener
        @Async
        public void logConnectionPoolStats(ApplicationReadyEvent event) {
            ScheduledExecutorService executor = Executors.newScheduledThreadPool(1);
            executor.scheduleAtFixedRate(this::logStats, 0, 30, TimeUnit.SECONDS);
        }
        
        private void logStats() {
            PoolStats totalStats = connectionManager.getTotalStats();
            logger.info("Connection Pool Stats - Total: {}, Available: {}, Leased: {}, Pending: {}",
                       totalStats.getMax(), totalStats.getAvailable(), 
                       totalStats.getLeased(), totalStats.getPending());
        }
    }
}

2. 響應時間監控

/**
 * HTTP 請求監控攔截器
 */
@Component
public class MetricsInterceptor implements ClientHttpRequestInterceptor {
    
    private final MeterRegistry meterRegistry;
    private final Timer.Builder timerBuilder;
    
    public MetricsInterceptor(MeterRegistry meterRegistry) {
        this.meterRegistry = meterRegistry;
        this.timerBuilder = Timer.builder("http.client.requests")
                .description("HTTP client request duration");
    }
    
    @Override
    public ClientHttpResponse intercept(
            HttpRequest request, 
            byte[] body, 
            ClientHttpRequestExecution execution) throws IOException {
        
        Timer.Sample sample = Timer.start(meterRegistry);
        
        try {
            ClientHttpResponse response = execution.execute(request, body);
            
            // 記錄成功請求指標
            sample.stop(timerBuilder
                    .tag("method", request.getMethod().name())
                    .tag("uri", getUriTemplate(request.getURI()))
                    .tag("status", String.valueOf(response.getStatusCode().value()))
                    .tag("outcome", getOutcome(response))
                    .register(meterRegistry));
            
            return response;
            
        } catch (IOException e) {
            // 記錄失敗請求指標
            sample.stop(timerBuilder
                    .tag("method", request.getMethod().name())
                    .tag("uri", getUriTemplate(request.getURI()))
                    .tag("status", "IO_ERROR")
                    .tag("outcome", "ERROR")
                    .register(meterRegistry));
            
            throw e;
        }
    }
    
    private String getUriTemplate(URI uri) {
        String path = uri.getPath();
        // 簡化路徑模板（移除具體 ID）
        return path.replaceAll("/\\d+", "/{id}");
    }
    
    private String getOutcome(ClientHttpResponse response) throws IOException {
        HttpStatus status = response.getStatusCode();
        if (status.is2xxSuccessful()) {
            return "SUCCESS";
        } else if (status.is4xxClientError()) {
            return "CLIENT_ERROR";
        } else if (status.is5xxServerError()) {
            return "SERVER_ERROR";
        } else {
            return "UNKNOWN";
        }
    }
}

3. 快取策略

/**
 * 帶快取的 REST 客戶端
 */
@Service
public class CachedRestClientService {
    
    private final RestTemplate restTemplate;
    private final CacheManager cacheManager;
    
    public CachedRestClientService(@Qualifier("standardRestTemplate") RestTemplate restTemplate,
                                  CacheManager cacheManager) {
        this.restTemplate = restTemplate;
        this.cacheManager = cacheManager;
    }
    
    /**
     * 帶快取的用戶查詢
     */
    @Cacheable(value = "users", key = "#userId", unless = "#result == null")
    public User getUserById(Long userId) {
        String url = "https://api.example.com/users/{id}";
        return restTemplate.getForObject(url, User.class, userId);
    }
    
    /**
     * 快取失效更新
     */
    @CacheEvict(value = "users", key = "#userId")
    public User updateUser(Long userId, User updatedUser) {
        String url = "https://api.example.com/users/{id}";
        
        HttpHeaders headers = new HttpHeaders();
        headers.setContentType(MediaType.APPLICATION_JSON);
        
        HttpEntity<User> request = new HttpEntity<>(updatedUser, headers);
        
        ResponseEntity<User> response = restTemplate.exchange(
                url, HttpMethod.PUT, request, User.class, userId);
        
        return response.getBody();
    }
    
    /**
     * 條件快取：基於響應頭的快取策略
     */
    public User getUserWithConditionalCache(Long userId) {
        String url = "https://api.example.com/users/{id}";
        
        // 檢查快取
        Cache cache = cacheManager.getCache("users");
        Cache.ValueWrapper cachedValue = cache.get(userId);
        
        HttpHeaders headers = new HttpHeaders();
        
        if (cachedValue != null) {
            CachedUser cachedUser = (CachedUser) cachedValue.get();
            // 添加 If-None-Match 頭
            headers.set("If-None-Match", cachedUser.getEtag());
        }
        
        HttpEntity<String> request = new HttpEntity<>(headers);
        
        try {
            ResponseEntity<User> response = restTemplate.exchange(
                    url, HttpMethod.GET, request, User.class, userId);
            
            // 更新快取
            String etag = response.getHeaders().getETag();
            if (etag != null) {
                CachedUser cachedUser = new CachedUser(response.getBody(), etag);
                cache.put(userId, cachedUser);
            }
            
            return response.getBody();
            
        } catch (HttpClientErrorException e) {
            if (e.getStatusCode() == HttpStatus.NOT_MODIFIED && cachedValue != null) {
                // 返回快取的值
                return ((CachedUser) cachedValue.get()).getUser();
            }
            throw e;
        }
    }
    
    private static class CachedUser {
        private final User user;
        private final String etag;
        
        public CachedUser(User user, String etag) {
            this.user = user;
            this.etag = etag;
        }
        
        public User getUser() { return user; }
        public String getEtag() { return etag; }
    }
}

測試策略

1. 單元測試

/**
 * RestTemplate 單元測試
 */
@ExtendWith(MockitoExtension.class)
class RestClientServiceTest {
    
    @Mock
    private RestTemplate restTemplate;
    
    @InjectMocks
    private RestClientService restClientService;
    
    private MockRestServiceServer mockServer;
    private ObjectMapper objectMapper;
    
    @BeforeEach
    void setUp() {
        mockServer = MockRestServiceServer.createServer(restTemplate);
        objectMapper = new ObjectMapper();
    }
    
    @Test
    @DisplayName("成功獲取用戶資訊")
    void testGetUserById_Success() throws JsonProcessingException {
        // Given
        Long userId = 1L;
        User expectedUser = new User(userId, "john@example.com", "John", "Doe");
        String expectedJson = objectMapper.writeValueAsString(expectedUser);
        
        mockServer.expect(requestTo("https://api.example.com/users/1"))
                  .andExpect(method(HttpMethod.GET))
                  .andRespond(withSuccess(expectedJson, MediaType.APPLICATION_JSON));
        
        // When
        User actualUser = restClientService.getUserById(userId);
        
        // Then
        mockServer.verify();
        assertThat(actualUser).isNotNull();
        assertThat(actualUser.getId()).isEqualTo(userId);
        assertThat(actualUser.getEmail()).isEqualTo("john@example.com");
    }
    
    @Test
    @DisplayName("用戶不存在時拋出異常")
    void testGetUserById_NotFound() {
        // Given
        Long userId = 999L;
        
        mockServer.expect(requestTo("https://api.example.com/users/999"))
                  .andExpect(method(HttpMethod.GET))
                  .andRespond(withStatus(HttpStatus.NOT_FOUND));
        
        // When & Then
        assertThatThrownBy(() -> restClientService.getUserById(userId))
                .isInstanceOf(NotFoundException.class);
        
        mockServer.verify();
    }
    
    @Test
    @DisplayName("帶有查詢參數的 GET 請求")
    void testGetUsersByDepartment() throws JsonProcessingException {
        // Given
        String department = "IT";
        int page = 0;
        int size = 10;
        List<User> expectedUsers = Arrays.asList(
                new User(1L, "john@example.com", "John", "Doe"),
                new User(2L, "jane@example.com", "Jane", "Smith")
        );
        String expectedJson = objectMapper.writeValueAsString(expectedUsers);
        
        mockServer.expect(requestTo(containsString("https://api.example.com/users")))
                  .andExpect(queryParam("department", "IT"))
                  .andExpect(queryParam("page", "0"))
                  .andExpect(queryParam("size", "10"))
                  .andExpect(method(HttpMethod.GET))
                  .andRespond(withSuccess(expectedJson, MediaType.APPLICATION_JSON));
        
        // When
        List<User> actualUsers = restClientService.getUsersByDepartment(department, page, size);
        
        // Then
        mockServer.verify();
        assertThat(actualUsers).hasSize(2);
    }
    
    @Test
    @DisplayName("POST 請求創建用戶")
    void testCreateUser() throws JsonProcessingException {
        // Given
        User newUser = new User(null, "bob@example.com", "Bob", "Johnson");
        User createdUser = new User(3L, "bob@example.com", "Bob", "Johnson");
        String requestJson = objectMapper.writeValueAsString(newUser);
        String responseJson = objectMapper.writeValueAsString(createdUser);
        
        mockServer.expect(requestTo("https://api.example.com/users"))
                  .andExpect(method(HttpMethod.POST))
                  .andExpect(content().json(requestJson))
                  .andExpected(header("Content-Type", "application/json"))
                  .andRespond(withSuccess(responseJson, MediaType.APPLICATION_JSON));
        
        // When
        User actualUser = restClientService.createUser(newUser);
        
        // Then
        mockServer.verify();
        assertThat(actualUser.getId()).isEqualTo(3L);
        assertThat(actualUser.getEmail()).isEqualTo("bob@example.com");
    }
    
    @Test
    @DisplayName("服務器錯誤時的重試機制")
    void testRetryOnServerError() {
        // Given
        Long userId = 1L;
        
        mockServer.expect(times(3), requestTo("https://api.example.com/users/1"))
                  .andExpect(method(HttpMethod.GET))
                  .andRespond(withServerError());
        
        // When & Then
        assertThatThrownBy(() -> restClientService.getUserById(userId))
                .isInstanceOf(ServerErrorException.class);
        
        mockServer.verify();
    }
}

2. 整合測試

/**
 * RestTemplate 整合測試
 */
@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
@TestPropertySource(locations = "classpath:application-integration-test.properties")
class RestClientIntegrationTest {
    
    @Autowired
    private RestClientService restClientService;
    
    @Autowired
    private TestRestTemplate testRestTemplate;
    
    @MockBean
    private RestTemplate restTemplate;
    
    private WireMockServer wireMockServer;
    
    @BeforeEach
    void setUp() {
        wireMockServer = new WireMockServer(wireMockConfig().port(8089));
        wireMockServer.start();
        configureFor("localhost", 8089);
    }
    
    @AfterEach
    void tearDown() {
        wireMockServer.stop();
    }
    
    @Test
    @DisplayName("完整的用戶管理流程")
    void testCompleteUserManagementFlow() throws JsonProcessingException {
        ObjectMapper objectMapper = new ObjectMapper();
        
        // 1. 模擬創建用戶 API
        User newUser = new User(null, "integration@example.com", "Integration", "Test");
        User createdUser = new User(1L, "integration@example.com", "Integration", "Test");
        
        stubFor(post(urlEqualTo("/api/users"))
                .willReturn(aResponse()
                        .withStatus(201)
                        .withHeader("Content-Type", "application/json")
                        .withBody(objectMapper.writeValueAsString(createdUser))));
        
        // 2. 模擬獲取用戶 API
        stubFor(get(urlEqualTo("/api/users/1"))
                .willReturn(aResponse()
                        .withStatus(200)
                        .withHeader("Content-Type", "application/json")
                        .withBody(objectMapper.writeValueAsString(createdUser))));
        
        // 3. 模擬更新用戶 API
        User updatedUser = new User(1L, "updated@example.com", "Updated", "User");
        stubFor(put(urlEqualTo("/api/users/1"))
                .willReturn(aResponse()
                        .withStatus(200)
                        .withHeader("Content-Type", "application/json")
                        .withBody(objectMapper.writeValueAsString(updatedUser))));
        
        // 4. 模擬刪除用戶 API
        stubFor(delete(urlEqualTo("/api/users/1"))
                .willReturn(aResponse().withStatus(204)));
        
        // 執行測試流程
        // 創建用戶
        User created = restClientService.createUser(newUser);
        assertThat(created.getId()).isEqualTo(1L);
        
        // 獲取用戶
        User retrieved = restClientService.getUserById(1L);
        assertThat(retrieved.getEmail()).isEqualTo("integration@example.com");
        
        // 更新用戶
        User updated = restClientService.updateUser(1L, updatedUser);
        assertThat(updated.getEmail()).isEqualTo("updated@example.com");
        
        // 刪除用戶
        assertDoesNotThrow(() -> restClientService.deleteUser(1L));
        
        // 驗證所有請求都被調用
        verify(postRequestedFor(urlEqualTo("/api/users")));
        verify(getRequestedFor(urlEqualTo("/api/users/1")));
        verify(putRequestedFor(urlEqualTo("/api/users/1")));
        verify(deleteRequestedFor(urlEqualTo("/api/users/1")));
    }
    
    @Test
    @DisplayName("錯誤處理和重試機制")
    void testErrorHandlingAndRetry() {
        // 模擬服務器錯誤，然後成功
        stubFor(get(urlEqualTo("/api/users/1"))
                .inScenario("Retry Scenario")
                .whenScenarioStateIs(STARTED)
                .willSetStateTo("First Attempt")
                .willReturn(aResponse().withStatus(500)));
        
        stubFor(get(urlEqualTo("/api/users/1"))
                .inScenario("Retry Scenario")
                .whenScenarioStateIs("First Attempt")
                .willSetStateTo("Second Attempt")
                .willReturn(aResponse().withStatus(500)));
        
        stubFor(get(urlEqualTo("/api/users/1"))
                .inScenario("Retry Scenario")
                .whenScenarioStateIs("Second Attempt")
                .willReturn(aResponse()
                        .withStatus(200)
                        .withHeader("Content-Type", "application/json")
                        .withBody("{\"id\":1,\"email\":\"test@example.com\"}")));
        
        // 執行測試
        User user = restClientService.getUserById(1L);
        assertThat(user.getId()).isEqualTo(1L);
        
        // 驗證重試了 3 次
        verify(3, getRequestedFor(urlEqualTo("/api/users/1")));
    }
}

現代化替代方案

1. WebClient 遷移指南

/**
 * WebClient 遷移範例
 */
@Service
public class ModernRestClientService {
    
    private final WebClient webClient;
    
    public ModernRestClientService(WebClient.Builder webClientBuilder) {
        this.webClient = webClientBuilder
                .baseUrl("https://api.example.com")
                .defaultHeader(HttpHeaders.CONTENT_TYPE, MediaType.APPLICATION_JSON_VALUE)
                .build();
    }
    
    /**
     * 異步 GET 請求
     */
    public Mono<User> getUserByIdAsync(Long userId) {
        return webClient.get()
                .uri("/users/{id}", userId)
                .retrieve()
                .bodyToMono(User.class);
    }
    
    /**
     * 響應式 POST 請求
     */
    public Mono<User> createUserAsync(User newUser) {
        return webClient.post()
                .uri("/users")
                .bodyValue(newUser)
                .retrieve()
                .bodyToMono(User.class);
    }
    
    /**
     * 錯誤處理
     */
    public Mono<User> getUserWithErrorHandling(Long userId) {
        return webClient.get()
                .uri("/users/{id}", userId)
                .retrieve()
                .onStatus(HttpStatus::is4xxClientError, 
                         response -> Mono.error(new NotFoundException("User not found")))
                .onStatus(HttpStatus::is5xxServerError,
                         response -> Mono.error(new ServerErrorException("Server error")))
                .bodyToMono(User.class);
    }
    
    /**
     * 流式處理
     */
    public Flux<User> getAllUsersStream() {
        return webClient.get()
                .uri("/users/stream")
                .retrieve()
                .bodyToFlux(User.class);
    }
}

2. RestTemplate vs WebClient 對比

特性	RestTemplate	WebClient
API 風格	同步阻塞	異步非阻塞
響應式支援	不支援	完整支援
效能	中等	高
記憶體使用	較高	較低
背壓處理	不支援	支援
Spring 5+ 支援	維護模式	主推方案
學習曲線	較低	較高

最佳實踐與建議

1. 配置最佳實踐

/**
 * RestTemplate 最佳實踐配置
 */
@Configuration
public class RestTemplateBestPractices {
    
    /**
     * 生產環境推薦配置
     */
    @Bean
    @Primary
    public RestTemplate productionRestTemplate() {
        // 1. 使用連接池
        PoolingHttpClientConnectionManager connectionManager = new PoolingHttpClientConnectionManager();
        connectionManager.setMaxTotal(200);
        connectionManager.setDefaultMaxPerRoute(50);
        connectionManager.setValidateAfterInactivity(2000);
        
        // 2. 配置超時
        RequestConfig requestConfig = RequestConfig.custom()
                .setConnectionRequestTimeout(5000)
                .setConnectTimeout(5000)
                .setSocketTimeout(30000)
                .build();
        
        // 3. 配置重試
        HttpRequestRetryHandler retryHandler = new DefaultHttpRequestRetryHandler(3, true);
        
        // 4. 配置 Keep-Alive
        ConnectionKeepAliveStrategy keepAliveStrategy = (response, context) -> 30 * 1000;
        
        CloseableHttpClient httpClient = HttpClients.custom()
                .setConnectionManager(connectionManager)
                .setDefaultRequestConfig(requestConfig)
                .setRetryHandler(retryHandler)
                .setKeepAliveStrategy(keepAliveStrategy)
                .build();
        
        HttpComponentsClientHttpRequestFactory factory = new HttpComponentsClientHttpRequestFactory(httpClient);
        
        RestTemplate restTemplate = new RestTemplate(factory);
        
        // 5. 添加攔截器
        restTemplate.setInterceptors(Arrays.asList(
                new LoggingInterceptor(),
                new MetricsInterceptor(meterRegistry),
                new AuthenticationInterceptor(tokenService)
        ));
        
        // 6. 設置錯誤處理器
        restTemplate.setErrorHandler(new CustomResponseErrorHandler());
        
        return restTemplate;
    }
    
    /**
     * 常見錯誤和解決方案
     */
    public void demonstrateCommonPitfalls() {
        // ❌ 錯誤：未設置超時
        RestTemplate badTemplate = new RestTemplate();
        
        // ✅ 正確：設置合理的超時
        SimpleClientHttpRequestFactory factory = new SimpleClientHttpRequestFactory();
        factory.setConnectTimeout(5000);
        factory.setReadTimeout(30000);
        RestTemplate goodTemplate = new RestTemplate(factory);
        
        // ❌ 錯誤：未使用連接池
        // 每次請求都創建新連接
        
        // ✅ 正確：使用連接池復用連接
        // 見上面的生產環境配置
        
        // ❌ 錯誤：未處理異常
        try {
            String result = badTemplate.getForObject("http://api.example.com/data", String.class);
        } catch (Exception e) {
            // 直接忽略異常
        }
        
        // ✅ 正確：適當的異常處理
        try {
            String result = goodTemplate.getForObject("http://api.example.com/data", String.class);
        } catch (ResourceAccessException e) {
            logger.error("Network error", e);
            throw new ServiceUnavailableException("Service temporarily unavailable");
        } catch (HttpClientErrorException e) {
            logger.error("Client error: {}", e.getStatusCode(), e);
            throw new BadRequestException("Invalid request");
        }
    }
}

2. 安全性考量

/**
 * RestTemplate 安全配置
 */
@Configuration
public class SecureRestTemplateConfig {
    
    /**
     * HTTPS 配置
     */
    @Bean
    public RestTemplate secureRestTemplate() throws Exception {
        TrustStrategy acceptingTrustStrategy = (X509Certificate[] chain, String authType) -> true;
        
        SSLContext sslContext = org.apache.http.ssl.SSLContexts.custom()
                .loadTrustMaterial(null, acceptingTrustStrategy)
                .build();
        
        SSLConnectionSocketFactory csf = new SSLConnectionSocketFactory(sslContext);
        
        CloseableHttpClient httpClient = HttpClients.custom()
                .setSSLSocketFactory(csf)
                .build();
        
        HttpComponentsClientHttpRequestFactory requestFactory = 
                new HttpComponentsClientHttpRequestFactory();
        requestFactory.setHttpClient(httpClient);
        
        return new RestTemplate(requestFactory);
    }
    
    /**
     * 認證配置
     */
    @Component
    public class SecureAuthInterceptor implements ClientHttpRequestInterceptor {
        
        @Override
        public ClientHttpResponse intercept(
                HttpRequest request, 
                byte[] body, 
                ClientHttpRequestExecution execution) throws IOException {
            
            // 1. 添加 API Key
            request.getHeaders().set("X-API-Key", getApiKey());
            
            // 2. 添加請求簽名
            String signature = generateSignature(request, body);
            request.getHeaders().set("X-Signature", signature);
            
            // 3. 添加時間戳防重放
            request.getHeaders().set("X-Timestamp", String.valueOf(System.currentTimeMillis()));
            
            return execution.execute(request, body);
        }
        
        private String getApiKey() {
            // 從安全配置中獲取 API Key
            return securityConfig.getApiKey();
        }
        
        private String generateSignature(HttpRequest request, byte[] body) {
            // 實作請求簽名邏輯
            return hmacSha256(request.getURI() + new String(body), getSecretKey());
        }
    }
}

總結

RestTemplate 作為 Spring 生態系統中的經典 HTTP 客戶端，提供了豐富的功能和良好的擴展性：

Spring Framework 註解完整指南：從基礎到進階應用

Thu, 05 Sep 2019 23:50:29 +0800

概述

Spring Framework 廣泛使用註解（Annotations）來簡化配置和提升開發效率。從 Spring 2.5 開始引入註解驅動配置，到 Spring Boot 的自動配置，註解已成為現代 Spring 應用程式開發的核心。本文將系統性地整理 Spring 生態系統中的重要註解，並提供實用的程式碼範例。

核心容器註解

1. Bean 定義與管理

@Component 系列

// 通用組件
@Component
public class UserValidator {
    public boolean validate(User user) {
        return user != null && user.getEmail() != null;
    }
}

// 服務層組件
@Service
public class UserService {
    @Autowired
    private UserRepository userRepository;
    
    public User findById(Long id) {
        return userRepository.findById(id).orElse(null);
    }
}

// 資料存取層組件
@Repository
public class UserRepositoryImpl implements UserRepository {
    @PersistenceContext
    private EntityManager entityManager;
    
    @Override
    public Optional<User> findById(Long id) {
        User user = entityManager.find(User.class, id);
        return Optional.ofNullable(user);
    }
}

// Web 層組件
@Controller
public class UserController {
    @Autowired
    private UserService userService;
    
    @GetMapping("/users/{id}")
    @ResponseBody
    public User getUser(@PathVariable Long id) {
        return userService.findById(id);
    }
}

// RESTful API 控制器
@RestController  // 等同於 @Controller + @ResponseBody
@RequestMapping("/api/users")
public class UserRestController {
    @Autowired
    private UserService userService;
    
    @GetMapping("/{id}")
    public User getUser(@PathVariable Long id) {
        return userService.findById(id);
    }
}

@Configuration 和 @Bean

@Configuration
@EnableTransactionManagement
@ComponentScan(basePackages = "com.example")
public class AppConfiguration {
    
    @Bean
    @Primary  // 當有多個相同類型的 Bean 時，優先使用這個
    public DataSource primaryDataSource() {
        HikariDataSource dataSource = new HikariDataSource();
        dataSource.setJdbcUrl("jdbc:mysql://localhost:3306/primary");
        dataSource.setUsername("user");
        dataSource.setPassword("password");
        return dataSource;
    }
    
    @Bean
    @Qualifier("secondary")  // 使用限定符區分
    public DataSource secondaryDataSource() {
        HikariDataSource dataSource = new HikariDataSource();
        dataSource.setJdbcUrl("jdbc:mysql://localhost:3306/secondary");
        dataSource.setUsername("user");
        dataSource.setPassword("password");
        return dataSource;
    }
    
    @Bean
    @Scope("prototype")  // 每次注入都創建新實例
    public OrderProcessor orderProcessor() {
        return new OrderProcessor();
    }
    
    @Bean
    @Lazy  // 延遲初始化
    public ExpensiveService expensiveService() {
        return new ExpensiveService();
    }
}

`@Configuration(proxyBeanMethods = false)`

預設 proxyBeanMethods = true：Spring 會用 CGLIB 代理 @Configuration 類別，確保 @Bean 方法之間互相呼叫時回傳的是同一個 singleton。