Best-Practices on Bill.Lin's Notes

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

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

Java TreeSet 完整實作指南

簡介

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

TreeSet 架構與繼承關係

類別繼承結構

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

核心介面關係

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

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

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

TreeSet 核心特性

1. 基於 TreeMap 的實現

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

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

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

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

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

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

SortedSet 介面詳解

基本方法實現

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

NavigableSet 介面詳解

導航方法實現

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

企業級應用實例

1. 事件調度系統

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

2. 範圍查詢緩存系統

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

3. 分數排名系統

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

效能分析與優化

1. 時間複雜度分析

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

2. 最佳化建議

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

實際應用場景

1. LeetCode 問題解決

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

2. 數據結構應用

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

最佳實踐與建議

1. 選擇適當的比較策略

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

2. 常見錯誤避免

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

總結

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

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

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

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

概述

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

經典四大軟體設計問題

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

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

症狀：

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

壞味道示例：

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

重構解決方案：

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

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

Java TreeMap 完整實作指南

簡介

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

TreeMap 架構與繼承關係

類別繼承結構

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

核心介面關係

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

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

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

TreeMap 核心特性

1. 紅黑樹實現

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

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

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

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

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

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

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

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

SortedMap 介面詳解

基本方法實現

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

NavigableMap 介面詳解

導航方法實現

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

企業級應用實例

1. 時間序列數據管理

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

2. 範圍查詢系統

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

3. 優先級任務調度器

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

效能分析與優化

1. 時間複雜度分析

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

2. 最佳化建議

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

實際應用場景

1. LeetCode 問題解決

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

2. 分佈式系統中的應用

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

最佳實踐與建議

1. 選擇適當的比較策略

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

2. 常見錯誤避免

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

總結

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

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

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

Kotlin lateinit 完整實作指南

簡介

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

lateinit 基本概念

核心特性

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

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

語法規則與限制

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

lateinit 詳細機制

內部實現原理

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

初始化檢查機制

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

企業級應用場景

1. Spring Boot 依賴注入

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

2. Android 開發中的應用

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

3. 配置管理系統

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

lateinit vs lazy 詳細比較

特性對比表

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

使用場景比較

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

進階使用模式

1. 條件初始化模式

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

2. 初始化鏈模式

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

3. 資源管理模式

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

測試策略

1. 單元測試模式

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

2. 整合測試模式

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

效能優化與最佳實踐

1. 記憶體管理

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

2. 線程安全考量

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

常見陷阱與錯誤處理

1. 常見錯誤模式

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

2. 錯誤處理策略

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

企業級最佳實踐

1. 初始化驗證框架

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

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

2. 監控與診斷

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

效能基準測試

初始化效能比較

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

總結

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

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

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

概述

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

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

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

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

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

Spring 依賴注入的三種方式

1. Field Injection（不建議）

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

Field Injection 的問題：

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

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

概述

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

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

SOLID 原則概覽

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

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

定義

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

核心概念

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

違反 SRP 的範例

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

遵循 SRP 的重構範例

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

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

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

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

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

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

SRP 的好處

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

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

定義

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

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 工具類的完整實作，包含以下關鍵特性：

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

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

Side Project 企業級專案配置指南

簡介

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

專案結構規劃

標準 Maven 專案結構

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

核心依賴管理

完整的 Maven 依賴配置

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

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

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

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

    <dependencies>
        <!-- Spring Boot Starters -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-data-jpa</artifactId>
        </dependency>
        
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-security</artifactId>
        </dependency>
        
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-validation</artifactId>
        </dependency>
        
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-cache</artifactId>
        </dependency>
        
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-data-redis</artifactId>
        </dependency>
        
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-actuator</artifactId>
        </dependency>
        
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-aop</artifactId>
        </dependency>

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

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

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

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

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

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

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

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

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

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

應用程式配置

主要配置檔案 - application.yml

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

核心配置類別

主要應用程式配置

package com.company.project.config;

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

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

資料庫配置

package com.company.project.config;

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

import javax.sql.DataSource;

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

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

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

Redis 配置

package com.company.project.config;

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

import java.time.Duration;

@Configuration
@EnableCaching
public class RedisConfig {

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

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

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

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

安全配置

package com.company.project.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
import org.springframework.security.config.http.SessionCreationPolicy;
import org.springframework.security.crypto.bcrypt.BCryptPasswordEncoder;
import org.springframework.security.crypto.password.PasswordEncoder;
import org.springframework.security.web.SecurityFilterChain;
import org.springframework.security.web.authentication.UsernamePasswordAuthenticationFilter;
import org.springframework.web.cors.CorsConfiguration;
import org.springframework.web.cors.CorsConfigurationSource;
import org.springframework.web.cors.UrlBasedCorsConfigurationSource;

import java.util.Arrays;

@Configuration
@EnableWebSecurity
public class SecurityConfig {

    private final AppProperties appProperties;
    private final JwtAuthenticationFilter jwtAuthenticationFilter;

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

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

        return http.build();
    }

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

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

OpenAPI 配置

package com.company.project.config;

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

@Configuration
public class OpenApiConfig {

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

容器化配置

Dockerfile

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

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

RUN ./mvnw clean package -DskipTests

FROM eclipse-temurin:17-jre-alpine

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

WORKDIR /app

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

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

# 切換到非 root 使用者
USER appuser

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

# 暴露埠號
EXPOSE 8080

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

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

docker-compose.yml

version: '3.8'

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

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

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

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

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

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

volumes:
  mysql_data:
  redis_data:
  grafana_data:

networks:
  app-network:
    driver: bridge

生產環境 docker-compose.prod.yml

version: '3.8'

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

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

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

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

volumes:
  mysql_prod_data:
  redis_prod_data:

networks:
  app-network:
    driver: overlay

監控配置

logback-spring.xml

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

Prometheus 配置

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

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

CI/CD 配置

GitHub Actions - CI

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

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

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

GitHub Actions - CD

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

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

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

部署腳本

建構腳本 - scripts/build.sh

#!/bin/bash

# 建構腳本
set -e

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

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

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

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

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

echo "建構完成！"

部署腳本 - scripts/deploy.sh

#!/bin/bash

# 部署腳本
set -e

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

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

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

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

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

resources/banner.txt

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

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

最佳實踐與建議

1. 安全性最佳實踐

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

2. 效能優化配置

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

3. 監控與告警

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

4. 資料庫優化

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

踩坑紀錄

Spring Boot 3 Jakarta 遷移

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