Security on Bill.Lin's Notes

openssl — 憑證、加密與 TLS 除錯命令列指南

Sun, 23 Aug 2026 00:00:00 +0800

macOS 上有兩套 openssl 可能同時存在，指令語法看起來一樣，但底層實作不同、行為也會有差異，先搞清楚自己在用哪一套，後面踩坑機率會少很多。

macOS LibreSSL vs Homebrew OpenSSL

macOS 內建的 /usr/bin/openssl 其實不是正牌 OpenSSL，而是 LibreSSL（OpenSSL 的 fork）：

1
2

/usr/bin/openssl version
# LibreSSL 3.3.6

透過 Homebrew 安裝的才是正牌 OpenSSL：

brew install openssl@3

/opt/homebrew/bin/openssl version
# OpenSSL 3.6.3 9 Jun 2026 (Library: OpenSSL 3.6.3 9 Jun 2026)

Homebrew 預設不會 link openssl@3（避免覆蓋系統版本），所以裝完之後單純打 openssl 很可能還是吃到 /usr/bin/openssl（LibreSSL）。確認目前 PATH 解析到哪一個：

which -a openssl
# /opt/homebrew/bin/openssl   <- 如果 Homebrew bin 在 PATH 前面，這行會排第一個
# /usr/bin/openssl

openssl version   # 實際會執行到的那個

如果 which openssl 解析到的不是想要的版本，把 Homebrew 版加進 PATH（放前面）：

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

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

為什麼選 Turnstile

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

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

運作原理與雙端流程

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

三個核心事實：

Dockerfile 進階多階段建構

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

基礎複習：Builder + Runtime 模式

# Stage 1: 建構
FROM eclipse-temurin:21-jdk AS builder
WORKDIR /app
COPY . .
RUN ./mvnw package -q -DskipTests

# Stage 2: 執行（只複製 jar，不含 JDK 與 source code）
FROM eclipse-temurin:21-jre-jammy
COPY --from=builder /app/target/app.jar /app.jar
ENTRYPOINT ["java", "-jar", "/app.jar"]

多階段建構的目的：最終 image 只含執行所需的檔案，不含原始碼、建構工具、測試依賴。

Cache Mount：加速重複建構

每次 docker build 若依賴沒有改變，Maven/npm 都會重新下載套件，非常耗時。--mount=type=cache 讓套件管理器的 cache 跨 build 持久化。

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 工具類具備以下優勢：

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

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

概述

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

JWT 核心特徵

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

JWT 結構

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

`1`	`Header.Payload.Signature`

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

Spring Boot 整合實作

1. 依賴配置

Maven 依賴設定

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

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

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

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

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

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

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

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

Gradle 依賴設定

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

2. 資料模型

認證請求 DTO

package com.example.jwt.dto;

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

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

認證回應 DTO

package com.example.jwt.dto;

import com.fasterxml.jackson.annotation.JsonProperty;

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

使用者實體

package com.example.jwt.entity;

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

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

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

enum Role {
    USER, ADMIN, MODERATOR
}

3. JWT 工具類

package com.example.jwt.util;

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

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

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

4. JWT 請求過濾器

package com.example.jwt.filter;

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

import java.io.IOException;

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

5. Spring Security 配置

package com.example.jwt.config;

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

import java.util.Arrays;

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

6. 認證控制器

package com.example.jwt.controller;

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

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

7. 認證服務

package com.example.jwt.service;

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

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

配置檔案

application.yml

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

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

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

安全性最佳實踐

1. 密鑰管理

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

2. Token 黑名單服務

package com.example.jwt.service;

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

import java.util.concurrent.TimeUnit;

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

3. 異常處理

package com.example.jwt.exception;

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

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

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

使用範例

1. 前端整合

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

2. 測試範例

package com.example.jwt;

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

import java.util.ArrayList;

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

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

效能最佳化

1. Redis 快取

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

2. 非同步處理

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

監控和日誌

1. 認證監控

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

2. 效能監控

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

常見問題與解決方案

1. Token 過期處理

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

2. 跨域處理

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

總結

核心優勢

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

最佳實踐

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

常用命令速查

# 生成密鑰
openssl rand -base64 32

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

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

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

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

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

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

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

SFTP 企業級工具類實作指南

簡介

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

核心依賴配置

Maven 依賴

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

Gradle 依賴

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

配置類別

SFTP 配置屬性

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

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

application.yml 配置

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

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

核心實作類別

SFTP 連線工廠

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

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

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

    private final SftpProperties sftpProperties;
    private final JSch jsch;

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

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

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

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

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

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

SFTP 連線池管理器

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

@Slf4j
@Component
public class SftpConnectionPoolManager {

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

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

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

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

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

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

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

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

企業級 SFTP 工具類

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

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

@Slf4j
@Component
public class SftpUtil {

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

支援類別

文件傳輸請求類

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

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

SFTP 文件信息類

import lombok.Data;

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

連線池狀態類

import lombok.Data;

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

服務層整合

SFTP 服務類

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

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

@Slf4j
@Service
public class SftpService {

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

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

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

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

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

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

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

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

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

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

控制器層

SFTP 控制器

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

import java.util.List;

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

    private final SftpService sftpService;

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

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

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

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

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

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

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

監控與健康檢查

SFTP 健康檢查

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

@Slf4j
@Component
public class SftpHealthIndicator implements HealthIndicator {

    private final SftpUtil sftpUtil;

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

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

自訂監控端點

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

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

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

    private final SftpUtil sftpUtil;

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

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

測試

單元測試

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

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

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

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

    @Mock
    private SftpConnectionPoolManager mockConnectionPoolManager;

    @Mock
    private ChannelSftp mockChannelSftp;

    @Mock
    private SftpProperties mockSftpProperties;

    private SftpUtil sftpUtil;

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

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

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

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

整合測試

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

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

    @Autowired
    private SftpService sftpService;

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

最佳實踐

1. 安全性考慮

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

2. 效能優化

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

3. 錯誤處理策略

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

總結

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

Spring 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。