N.1  本章重點整理        —— 30 秒掃完全章要點
N.2  目的與適用情境      —— 什麼時候該用、什麼時候不該用
N.3  原理說明            —— 底層機制與設計理念
N.4  架構圖（ASCII）     —— 純文字架構圖，可貼進 Code Comment
N.5  流程圖（Mermaid）   —— 互動流程 / 時序 / 狀態
N.6  程式碼範例          —— Java 25 + Spring 7 + Maven 4，完整可編譯
N.7  最佳實務            —— 團隊可直接採用的規範
N.8  常見錯誤與 Anti-pattern
N.9  效能建議 ⚡
N.10 安全性考量 🔒
N.11 企業實戰案例
N.12 升級注意事項（6.2 → 7.0）🔄
N.13 FAQ
N.14 章節 Checklist
N.15 本章小結

  ┌───────────────────────────────────────────────────────────────────┐
  │  Spring Framework 7.0.x 維護版本時間軸（截至 2026-08）              │
  ├───────────────────────────────────────────────────────────────────┤
  │  7.0.0  2025-11  GA                                                │
  │  7.0.1  2025-12  首批修正                                          │
  │  7.0.2  2025-12  首批修正                                          │
  │  7.0.3  2026-01  ⭐ Retry 監聽器、Jackson XML codec、測試暫停控制    │
  │  7.0.4  2026-02  ⭐ JPA 4.0 / Hibernate ORM 8.0 早期相容            │
  │  7.0.5  2026-02  ⚡ MVC header 處理效能最佳化                       │
  │  7.0.6  2026-03  ⭐ JPA 4.0 explicit flush、AOT hints 對齊 v1.2.0   │
  │  7.0.7  2026-04  ⭐ RestClient 測試支援、驗證效能改善                │
  │  7.0.8  2026-06  🔒 ⭐⭐ 一次修補 16 個 CVE ── 最低安全基線          │
  └───────────────────────────────────────────────────────────────────┘

  🔒 企業安全基線結論：
     ・7.0.x 使用者 ── ⭐ 最低必須 7.0.8（含 16 個 CVE 修補）
     ・6.2.x 使用者 ── ⭐ 最低必須 6.2.19（同批 CVE 的最後一版 OSS 修補）
     ・💀 低於上述版本者，等同已知漏洞暴露中

┌──────────────────────────────────────────────────────────────────────┐
│                      Spring Framework 7.0 四大變                      │
├──────────────────────────────────────────────────────────────────────┤
│                                                                      │
│  ① 平台變          JDK 17→建議 25 │ Jakarta EE 10→11 │ Servlet 6.0→6.1 │
│                    GraalVM 25 │ Kotlin 2.2 │ JUnit 5→6                │
│                                                                      │
│  ② 客戶端變        RestTemplate ──棄用──▶ RestClient                   │
│                    HTTP Interface Client + @ImportHttpServices        │
│                    JdbcClient 強化 │ 新增 JmsClient                    │
│                                                                      │
│  ③ 型別安全變      JSR 305 ──取代──▶ JSpecify                          │
│                    可標註泛型 / 陣列 / vararg 的 nullness              │
│                    Jackson 2.x ──取代──▶ Jackson 3.x (tools.jackson)  │
│                                                                      │
│  ④ 能力內建變      Spring Retry ──收斂──▶ core.retry + @Retryable      │
│                    API Versioning 內建 MVC / WebFlux                  │
│                    BeanRegistrar 程式化註冊 │ @Proxyable 代理控制       │
│                    測試 Context Pausing │ RestTestClient               │
│                                                                      │
└──────────────────────────────────────────────────────────────────────┘

┌──────────────────────────────────────────────────────────────┐
│                    沒有 Spring 的世界                         │
├──────────────────────────────────────────────────────────────┤
│  OrderService.java                                           │
│  ├─ new OrderRepository(dataSource)      ← 自己組裝           │
│  ├─ conn.setAutoCommit(false)            ← 自己管交易         │
│  ├─ try { ... } catch { conn.rollback() }← 自己處理回滾       │
│  ├─ logger.info("audit: ...")            ← 自己插稽核         │
│  ├─ if (!user.hasRole("ADMIN")) throw    ← 自己檢查權限       │
│  └─ 業務邏輯（只有 10 行）                                     │
└──────────────────────────────────────────────────────────────┘
                            ▼  導入 Spring
┌──────────────────────────────────────────────────────────────┐
│                     有 Spring 的世界                          │
├──────────────────────────────────────────────────────────────┤
│  @Service                                                    │
│  class OrderService {                                        │
│      private final OrderRepository repo;   ← 容器注入         │
│      @Transactional                        ← 容器管交易       │
│      @Audited                              ← AOP 插稽核       │
│      @PreAuthorize("hasRole('ADMIN')")     ← AOP 檢權限       │
│      Order place(OrderCommand cmd) {                         │
│          業務邏輯（就是那 10 行）                              │
│      }                                                       │
│  }                                                           │
└──────────────────────────────────────────────────────────────┘

        你的應用程式
             │
             ▼
┌────────────────────────────┐
│      Spring Boot 4.x       │  ← 做決策：預設用哪個 Server、
│  Auto Configuration        │     預設哪些 Bean、預設什麼設定
│  Starter / Actuator        │     （@ConditionalOnClass 等）
└────────────┬───────────────┘
             │  委派給
             ▼
┌────────────────────────────┐
│  Spring Framework 7.x      │  ← 提供能力：IoC、AOP、
│  IoC / AOP / TX / MVC ...  │     Transaction、MVC、WebFlux
└────────────┬───────────────┘
             │  執行於
             ▼
┌────────────────────────────┐
│  JDK 25 + Jakarta EE 11    │
└────────────────────────────┘

╔══════════════════════════════════════════════════════════════════════════╗
║                    Spring Framework 7.x 全景架構                          ║
╠══════════════════════════════════════════════════════════════════════════╣
║                                                                          ║
║  ┌────────────────────────────────────────────────────────────────────┐  ║
║  │                        Web 層（擇一或並存）                          │  ║
║  │  ┌──────────────────────┐      ┌──────────────────────────────┐    │  ║
║  │  │  spring-webmvc       │      │  spring-webflux              │    │  ║
║  │  │  Servlet 6.1 Stack   │      │  Reactive Stack (Netty 4.2)  │    │  ║
║  │  │  DispatcherServlet   │      │  DispatcherHandler           │    │  ║
║  │  └──────────┬───────────┘      └──────────────┬───────────────┘    │  ║
║  │             └──────────┬───────────────────────┘                   │  ║
║  │                        ▼                                           │  ║
║  │              ┌──────────────────┐                                  │  ║
║  │              │   spring-web     │  HTTP 抽象 / RestClient /        │  ║
║  │              │                  │  HTTP Interface / API Versioning │  ║
║  │              └──────────────────┘                                  │  ║
║  └────────────────────────────────────────────────────────────────────┘  ║
║                                                                          ║
║  ┌──────────────────────┐  ┌──────────────────┐  ┌────────────────────┐  ║
║  │   資料存取 / 整合      │  │      AOP         │  │     測試            │  ║
║  │  spring-jdbc         │  │  spring-aop      │  │  spring-test       │  ║
║  │  spring-orm          │  │  spring-aspects  │  │  TestContext       │  ║
║  │  spring-tx           │  │  Proxy / @Aspect │  │  MockMvc           │  ║
║  │  spring-r2dbc        │  │                  │  │  WebTestClient     │  ║
║  │  spring-jms          │  │                  │  │  RestTestClient ⭐  │  ║
║  │  spring-messaging    │  │                  │  │                    │  ║
║  └──────────────────────┘  └──────────────────┘  └────────────────────┘  ║
║                                                                          ║
║  ┌────────────────────────────────────────────────────────────────────┐  ║
║  │                        Core Container（地基）                        │  ║
║  │  ┌────────────────┐ ┌────────────────┐ ┌──────────────────────┐    │  ║
║  │  │ spring-beans   │ │ spring-context │ │ spring-expression    │    │  ║
║  │  │ BeanFactory    │ │ ApplicationCtx │ │ SpEL                 │    │  ║
║  │  │ BeanDefinition │ │ Event / Cache  │ │ (7.0: Optional 支援) │    │  ║
║  │  │ BeanRegistrar⭐│ │ @Retryable ⭐  │ │                      │    │  ║
║  │  └────────────────┘ └────────────────┘ └──────────────────────┘    │  ║
║  │  ┌──────────────────────────────────────────────────────────────┐  │  ║
║  │  │ spring-core                                                  │  │  ║
║  │  │ Resource / Environment / TypeConversion / AOT RuntimeHints   │  │  ║
║  │  │ core.retry (RetryTemplate ⭐) / ClassFileMetadataReader ⭐    │  │  ║
║  │  └──────────────────────────────────────────────────────────────┘  │  ║
║  └────────────────────────────────────────────────────────────────────┘  ║
║                                                                          ║
║  ⭐ = Spring Framework 7.0 新增                                           ║
╚══════════════════════════════════════════════════════════════════════════╝

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

    <groupId>com.enterprise.tutorial</groupId>
    <artifactId>spring7-quickstart</artifactId>
    <version>1.0.0</version>
    <packaging>jar</packaging>

    <properties>
        <maven.compiler.release>25</maven.compiler.release>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <spring.version>7.0.8</spring.version>
        <junit.version>6.0.0</junit.version>
    </properties>

    <dependencyManagement>
        <dependencies>
            <!-- Spring Framework BOM：統一管理所有 spring-* 版本 -->
            <dependency>
                <groupId>org.springframework</groupId>
                <artifactId>spring-framework-bom</artifactId>
                <version>${spring.version}</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
        </dependencies>
    </dependencyManagement>

    <dependencies>
        <dependency>
            <groupId>org.springframework</groupId>
            <artifactId>spring-context</artifactId>
        </dependency>

        <!-- JSpecify：7.0 起的 null-safety 標準標註 -->
        <dependency>
            <groupId>org.jspecify</groupId>
            <artifactId>jspecify</artifactId>
            <version>1.0.0</version>
        </dependency>

        <dependency>
            <groupId>org.springframework</groupId>
            <artifactId>spring-test</artifactId>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>org.junit.jupiter</groupId>
            <artifactId>junit-jupiter</artifactId>
            <version>${junit.version}</version>
            <scope>test</scope>
        </dependency>
    </dependencies>
</project>

package com.enterprise.tutorial.hello;

import org.springframework.context.annotation.AnnotationConfigApplicationContext;
import org.springframework.context.annotation.ComponentScan;
import org.springframework.context.annotation.Configuration;
import org.springframework.stereotype.Service;

/**
 * Spring Framework 7 最小可執行範例。
 * 展示：ApplicationContext 啟動 → 元件掃描 → 建構子注入 → 優雅關閉。
 */
public final class HelloApplication {

    public static void main(String[] args) {
        // try-with-resources 確保 close() 被呼叫，觸發 @PreDestroy 與 DisposableBean
        try (var context = new AnnotationConfigApplicationContext(AppConfig.class)) {
            GreetingService service = context.getBean(GreetingService.class);
            System.out.println(service.greet("Spring 7"));
        }
    }

    @Configuration(proxyBeanMethods = false)
    @ComponentScan
    static class AppConfig {
        // proxyBeanMethods = false 可省下 CGLIB 代理，加快啟動並降低記憶體
    }
}

@Service
class GreetingService {

    private final MessageFormatter formatter;

    // 建構子注入：Spring 4.3 起單一建構子可省略 @Autowired
    GreetingService(MessageFormatter formatter) {
        this.formatter = formatter;
    }

    String greet(String name) {
        return formatter.format("Hello, %s! Running on Java %s"
                .formatted(name, Runtime.version().feature()));
    }
}

@Service
class MessageFormatter {

    String format(String raw) {
        return "[%s] %s".formatted(java.time.LocalDate.now(), raw);
    }
}

package com.enterprise.tutorial.highlight;

import org.jspecify.annotations.NullMarked;
import org.jspecify.annotations.Nullable;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.retry.RetryPolicy;
import org.springframework.core.retry.RetryTemplate;
import org.springframework.resilience.annotation.ConcurrencyLimit;
import org.springframework.resilience.annotation.EnableResilientMethods;
import org.springframework.resilience.annotation.Retryable;
import org.springframework.stereotype.Service;

import java.time.Duration;

/**
 * Spring Framework 7.0 四大亮點的最小示範：
 * ① JSpecify null-safety  ② 內建 Resilience
 * ③ 程式化 RetryTemplate  ④ 併發限流
 */
@NullMarked  // 套件/類別層級宣告：預設所有型別皆為非 null
@Configuration(proxyBeanMethods = false)
@EnableResilientMethods  // ② 啟用 @Retryable / @ConcurrencyLimit
class ResilienceHighlightConfig {

    @Bean
    RetryTemplate retryTemplate() {
        // ③ 程式化重試：從 Spring Retry 專案收斂進 spring-core
        return new RetryTemplate(
                RetryPolicy.builder()
                        .maxAttempts(3)
                        .delay(Duration.ofMillis(200))
                        .multiplier(2.0)
                        .maxDelay(Duration.ofSeconds(2))
                        .build());
    }
}

@Service
class InventoryService {

    // ② 宣告式重試：遠端服務不穩時自動退避重試
    @Retryable(maxAttempts = 3, delay = 300, multiplier = 2.0,
               includes = TransientRemoteException.class)
    // ④ 併發限流：同時最多 10 個執行緒進入，超過的排隊等待
    @ConcurrencyLimit(10)
    public StockLevel query(String sku) {
        return remoteQuery(sku);
    }

    // ① JSpecify：明確標示「可能回傳 null」，IDE 與靜態分析工具可據此檢查
    public @Nullable StockLevel findCached(String sku) {
        return null;
    }

    private StockLevel remoteQuery(String sku) {
        throw new UnsupportedOperationException("demo only");
    }
}

record StockLevel(String sku, int quantity) {}

class TransientRemoteException extends RuntimeException {
    TransientRemoteException(String message) {
        super(message);
    }
}

BeanDefinition（Bean 的「藍圖」）
    ├─ beanClassName / scope / lazyInit / primary / fallback
    ├─ ConstructorArgumentValues
    ├─ MutablePropertyValues
    └─ initMethodName / destroyMethodName
              │
              ▼
BeanDefinitionRegistry（藍圖的登記處）
              │
              ▼
BeanFactory（依藍圖生產實例）
    ├─ DefaultListableBeanFactory  ← 最完整的實作
    ├─ 三級快取（解決循環依賴）
    └─ BeanPostProcessor 鏈
              │
              ▼
   實際的 Bean 實例（Singleton Pool）

┌───────────────────────────────────────────────────────────────────────────┐
│              Spring Framework 7.x 模組相依樹（由下而上）                     │
└───────────────────────────────────────────────────────────────────────────┘

  應用程式
      │  典型宣告
      ├──▶ spring-webmvc ──┬──▶ spring-web ────┐
      │                    │                    │
      ├──▶ spring-webflux ─┘                    │
      │                                          ▼
      ├──▶ spring-orm ─────▶ spring-jdbc ──▶ spring-tx ──┐
      │         │                                          │
      ├──▶ spring-jms ─────▶ spring-messaging ─────┐      │
      │                                             │      │
      └──▶ spring-context ◀─────────────────────────┴──────┘
                  │
       ┌──────────┼──────────┬─────────────┐
       ▼          ▼          ▼             ▼
  spring-aop  spring-beans  spring-      （企業服務：
       │          │        expression      Event/Cache/
       └────┬─────┴───────────┘            Schedule/Retry）
            ▼
       spring-core
            │
            ▼
   commons-logging 1.3.0     ← 7.0：取代已移除的 spring-jcl
            │
            ▼
     JDK 17 / 21 / 25


┌───────────────────────────────────────────────────────────────────────────┐
│  只引入 spring-context 時，Maven 會自動帶進：                                │
│    spring-core, spring-beans, spring-aop, spring-expression               │
│  → 這 5 個 artifact 就是「Core Container 完整體」                           │
└───────────────────────────────────────────────────────────────────────────┘

<!-- 情境 A：純核心容器（批次程式、CLI 工具） -->
<dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-context</artifactId>
    <!-- 自動帶進 core / beans / aop / expression -->
</dependency>

<!-- 情境 B：傳統 Web + 資料庫（最常見的企業應用） -->
<dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-webmvc</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-jdbc</artifactId>
    <!-- 自動帶進 spring-tx -->
</dependency>

<!-- 情境 C：JPA -->
<dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-orm</artifactId>
</dependency>
<dependency>
    <groupId>org.hibernate.orm</groupId>
    <artifactId>hibernate-core</artifactId>
    <version>7.2.0.Final</version>
</dependency>

<!-- 情境 D：反應式 Web + R2DBC -->
<dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-webflux</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-r2dbc</artifactId>
</dependency>

<!-- 情境 E：測試（所有專案都該有） -->
<dependency>
    <groupId>org.springframework</groupId>
    <artifactId>spring-test</artifactId>
    <scope>test</scope>
</dependency>

# Maven 4：列出完整相依樹，確認沒有意外引入
mvn dependency:tree -Dincludes=org.springframework

# 找出版本衝突
mvn dependency:tree -Dverbose -Dincludes=org.springframework

# 檢查是否還殘留已移除的 spring-jcl
mvn dependency:tree | Select-String "spring-jcl"

# 列出「宣告了但沒用到」與「用到了但沒宣告」的相依
mvn dependency:analyze

package com.enterprise.tutorial.architecture;

import org.springframework.core.env.Environment;
import org.springframework.core.io.Resource;
import org.springframework.core.io.support.PathMatchingResourcePatternResolver;
import org.springframework.core.io.support.ResourcePatternResolver;
import org.springframework.stereotype.Component;

import java.io.IOException;
import java.io.UncheckedIOException;
import java.nio.charset.StandardCharsets;
import java.util.List;

/**
 * 展示 spring-core 的 Resource 與 Environment 抽象：
 * 同一份程式碼可讀取 classpath、檔案系統、JAR 內的資源，不需要 if/else。
 */
@Component
public class SqlScriptLoader {

    private final ResourcePatternResolver resolver;
    private final Environment environment;

    public SqlScriptLoader(Environment environment) {
        this.resolver = new PathMatchingResourcePatternResolver();
        this.environment = environment;
    }

    /**
     * 載入指定 profile 對應的所有 SQL 腳本。
     * 例如 profile=dev 會讀取 classpath*:/db/dev/*.sql
     */
    public List<String> loadScripts() {
        String profile = environment.getActiveProfiles().length > 0
                ? environment.getActiveProfiles()[0]
                : "default";
        String pattern = "classpath*:/db/%s/*.sql".formatted(profile);

        try {
            Resource[] resources = resolver.getResources(pattern);
            return java.util.Arrays.stream(resources)
                    .map(SqlScriptLoader::readAsString)
                    .toList();
        } catch (IOException ex) {
            throw new UncheckedIOException(
                    "無法載入 SQL 腳本，pattern=" + pattern, ex);
        }
    }

    private static String readAsString(Resource resource) {
        try (var in = resource.getInputStream()) {
            return new String(in.readAllBytes(), StandardCharsets.UTF_8);
        } catch (IOException ex) {
            throw new UncheckedIOException(
                    "無法讀取資源：" + resource.getDescription(), ex);
        }
    }
}

┌─────────────────────────────────────────────────────────────────┐
│  BeanFactory（基礎契約 · spring-beans）                          │
│  ├─ getBean(String / Class)                                     │
│  ├─ containsBean / isSingleton / isPrototype                    │
│  └─ 預設「延遲載入」：呼叫 getBean() 才實例化                     │
└────────────────────────┬────────────────────────────────────────┘
                         │ extends
                         ▼
┌─────────────────────────────────────────────────────────────────┐
│  ApplicationContext（企業級 · spring-context）                   │
│  ├─ ListableBeanFactory     取得所有 Bean 名稱 / 型別查詢         │
│  ├─ HierarchicalBeanFactory 父子容器                            │
│  ├─ MessageSource           國際化                              │
│  ├─ ApplicationEventPublisher 事件發布                          │
│  ├─ ResourcePatternResolver 資源載入（classpath*: 萬用字元）      │
│  ├─ EnvironmentCapable      Profile / PropertySource            │
│  └─ 預設「積極載入」：refresh() 時就建立所有非 lazy singleton      │
└─────────────────────────────────────────────────────────────────┘

問題：
  @Service (singleton)  ──注入──▶  @Component @Scope("prototype")
  結果：Prototype 只在 Singleton 建立時被注入一次，
        之後每次呼叫拿到的都是「同一個」實例 → prototype 語意失效

三種解法：
  ① ObjectProvider<T>       ← ✅ 推薦，型別安全、無 CGLIB 開銷
  ② @Lookup 方法注入         ← 需要 CGLIB 代理
  ③ 注入 ApplicationContext  ← ❌ 不推薦，造成框架耦合

╔═════════════════════════════════════════════════════════════════════════╗
║                    Spring IoC 容器內部結構                                ║
╠═════════════════════════════════════════════════════════════════════════╣
║                                                                         ║
║  【輸入：Bean 的來源】                                                    ║
║  ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌────────────────┐  ║
║  │ @Component   │ │ @Bean 方法    │ │  XML 定義     │ │ BeanRegistrar ⭐│  ║
║  │ 元件掃描      │ │ @Configuration│ │ (Legacy)     │ │ 程式化註冊      │  ║
║  └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ └───────┬────────┘  ║
║         └────────────────┴────────────────┴─────────────────┘           ║
║                                  ▼                                      ║
║  ┌───────────────────────────────────────────────────────────────────┐  ║
║  │              BeanDefinitionRegistry（藍圖登記處）                    │  ║
║  │  Map<String beanName, BeanDefinition>                             │  ║
║  │  BeanDefinition = { class, scope, lazy, primary, fallback,        │  ║
║  │                     ctorArgs, propertyValues, initMethod, ... }   │  ║
║  └────────────────────────────────┬──────────────────────────────────┘  ║
║                                   │                                     ║
║          ┌────────────────────────▼─────────────────────────┐           ║
║          │      BeanFactoryPostProcessor 鏈（改藍圖）         │           ║
║          │  ConfigurationClassPostProcessor                  │           ║
║          │  PropertySourcesPlaceholderConfigurer（${...}）    │           ║
║          └────────────────────────┬─────────────────────────┘           ║
║                                   ▼                                     ║
║  ┌───────────────────────────────────────────────────────────────────┐  ║
║  │         DefaultListableBeanFactory（生產線）                        │  ║
║  │                                                                   │  ║
║  │   建構子 ──▶ 屬性填充 ──▶ Aware ──▶ BPP前 ──▶ init ──▶ BPP後       │  ║
║  │                  ▲                    │              │            │  ║
║  │                  │              @PostConstruct   AOP 代理 ⭐        │  ║
║  │            ┌─────┴──────┐                                         │  ║
║  │            │  三級快取   │  singletonObjects（成品）                │  ║
║  │            │  循環依賴   │  earlySingletonObjects（半成品）          │  ║
║  │            │  解析       │  singletonFactories（工廠）              │  ║
║  │            └────────────┘                                         │  ║
║  └────────────────────────────────┬──────────────────────────────────┘  ║
║                                   ▼                                     ║
║  ┌───────────────────────────────────────────────────────────────────┐  ║
║  │            Singleton Pool（就緒的 Bean，可能是 Proxy）                │  ║
║  └───────────────────────────────────────────────────────────────────┘  ║
║                                                                         ║
║  【周邊服務（ApplicationContext 提供）】                                   ║
║  Environment │ MessageSource │ EventMulticaster │ ResourceLoader        ║
╚═════════════════════════════════════════════════════════════════════════╝

package com.enterprise.tutorial.core;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.ComponentScan;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.FilterType;
import org.springframework.context.annotation.Import;
import org.springframework.context.annotation.Primary;
import org.springframework.context.annotation.Profile;
import org.springframework.context.annotation.PropertySource;
import org.springframework.context.support.PropertySourcesPlaceholderConfigurer;
import org.springframework.core.env.Environment;

import javax.sql.DataSource;
import java.time.Clock;
import java.time.ZoneId;

/**
 * 企業級組態類別範本（Spring Framework 7）。
 * 重點：
 *   - proxyBeanMethods = false 省下 CGLIB 代理
 *   - basePackageClasses 取代字串路徑（型別安全）
 *   - @Bean 宣告最具體的回傳型別
 */
@Configuration(proxyBeanMethods = false)
@ComponentScan(
        basePackageClasses = CoreConfig.class,
        excludeFilters = @ComponentScan.Filter(
                type = FilterType.REGEX,
                pattern = ".*\\.testsupport\\..*"))
@PropertySource("classpath:application.properties")
@Import(PersistenceConfig.class)
public class CoreConfig {

    /**
     * 處理 ${...} 佔位符。
     * 必須是 static，因為它是 BeanFactoryPostProcessor，
     * 需要在組態類別本身被實例化之前就執行。
     */
    @Bean
    static PropertySourcesPlaceholderConfigurer placeholderConfigurer() {
        return new PropertySourcesPlaceholderConfigurer();
    }

    /**
     * 注入 Clock 而非直接呼叫 LocalDateTime.now()，
     * 讓時間相關邏輯可被測試（測試時注入 Clock.fixed）。
     */
    @Bean
    Clock systemClock(Environment env) {
        String zone = env.getProperty("app.timezone", "Asia/Taipei");
        return Clock.system(ZoneId.of(zone));
    }

    @Bean
    @Primary
    @Profile("prod")
    AuditWriter databaseAuditWriter(DataSource dataSource) {
        return new DatabaseAuditWriter(dataSource);
    }

    @Bean
    @Profile("!prod")
    AuditWriter consoleAuditWriter() {
        return new ConsoleAuditWriter();
    }
}

package com.enterprise.tutorial.core;

import org.springframework.beans.factory.BeanRegistrar;
import org.springframework.beans.factory.BeanRegistry;
import org.springframework.core.env.Environment;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Import;

import java.util.List;

/**
 * ⭐ Spring Framework 7.0 新增：BeanRegistrar
 *
 * 使用情境：需要依據設定檔動態註冊「數量不定」的 Bean。
 * 例如：application.properties 設定了 3 個下游系統，
 *       就要註冊 3 個對應的 Client Bean。
 *
 * 傳統做法（❌）：在一個 @Bean 方法裡 new 出 List<Client>，
 *               但這樣每個 Client 都不是獨立的 Bean，
 *               無法各自被 @Qualifier 注入、無法各自被 AOP 攔截。
 */
class DownstreamClientRegistrar implements BeanRegistrar {

    @Override
    public void register(BeanRegistry registry, Environment env) {
        // 從設定讀取：app.downstream.systems=billing,inventory,notification
        List<String> systems = List.of(
                env.getProperty("app.downstream.systems", "").split(","));

        for (String system : systems) {
            if (system.isBlank()) {
                continue;
            }
            String name = system.trim();
            String baseUrl = env.getRequiredProperty(
                    "app.downstream.%s.url".formatted(name));

            // 每個下游系統註冊成一個獨立、具名的 Bean
            registry.registerBean(name + "Client", DownstreamClient.class,
                    spec -> spec
                            .description("下游系統 %s 的 HTTP 客戶端".formatted(name))
                            .supplier(ctx -> new DownstreamClient(name, baseUrl)));
        }
    }
}

@Configuration(proxyBeanMethods = false)
@Import(DownstreamClientRegistrar.class)   // 7.0 起 @Import 可直接匯入 BeanRegistrar
class DownstreamConfig {
}

record DownstreamClient(String systemName, String baseUrl) {
}

package com.enterprise.tutorial.core;

import org.springframework.aop.framework.ProxyConfig;
import org.springframework.aop.framework.autoproxy.AutoProxyUtils;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Proxyable;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;

/**
 * ⭐ 7.0：全域代理策略一致化 + @Proxyable 個別覆寫
 *
 * 7.0 起，「全域預設 CGLIB」（如 Spring Boot 的行為）會一致地
 * 套用到所有 proxy processor（含 @Async、@Retryable 等），
 * 不再只影響 @Transactional。
 */
@Configuration(proxyBeanMethods = false)
class ProxyStrategyConfig {

    /**
     * 宣告一個名稱固定的 ProxyConfig Bean，
     * 即可設定「本 ApplicationContext 的預設代理行為」。
     */
    @Bean(name = AutoProxyUtils.DEFAULT_PROXY_CONFIG_BEAN_NAME)
    ProxyConfig defaultProxyConfig() {
        ProxyConfig config = new ProxyConfig();
        config.setProxyTargetClass(true);   // 全域預設 CGLIB
        config.setExposeProxy(false);       // 不曝露 AopContext（有效能成本）
        return config;
    }
}

/** 在 CGLIB 全域預設下，個別退回 JDK 動態代理（介面代理）。 */
@Service
@Proxyable(Proxyable.Type.INTERFACES)
class DefaultPaymentService implements PaymentService {

    @Override
    @Transactional
    public void pay(String orderId) {
        // ...
    }
}

/** 明確指定要用哪些介面來代理，可覆寫上下文預設。 */
@Service
@Proxyable(interfaces = ReportService.class)
class ExcelReportService implements ReportService, InternalDiagnostics {

    @Override
    public byte[] render(String reportId) {
        return new byte[0];
    }

    @Override
    public String diagnose() {
        // 這個方法不會出現在代理的介面上，外部無法透過代理呼叫
        return "OK";
    }
}

interface PaymentService {
    void pay(String orderId);
}

interface ReportService {
    byte[] render(String reportId);
}

interface InternalDiagnostics {
    String diagnose();
}

package com.enterprise.tutorial.core;

import jakarta.annotation.PostConstruct;
import jakarta.annotation.PreDestroy;
import org.springframework.beans.BeansException;
import org.springframework.beans.factory.BeanNameAware;
import org.springframework.beans.factory.DisposableBean;
import org.springframework.beans.factory.InitializingBean;
import org.springframework.beans.factory.config.BeanPostProcessor;
import org.springframework.context.ApplicationContextAware;
import org.springframework.context.ApplicationContext;
import org.springframework.stereotype.Component;

/**
 * 執行後的輸出順序：
 *   1. 建構子
 *   2. setBeanName
 *   3. setApplicationContext
 *   4. BPP.postProcessBeforeInitialization
 *   5. @PostConstruct
 *   6. afterPropertiesSet
 *   7. BPP.postProcessAfterInitialization   ← AOP 代理在此產生
 *   -- 容器 close() --
 *   8. @PreDestroy
 *   9. destroy
 *
 * ⚠️ 注意：@PostConstruct 使用的是 jakarta.annotation，
 *    7.0 已完全移除對 javax.annotation 的支援。
 */
@Component
public class LifecycleDemoBean
        implements BeanNameAware, ApplicationContextAware,
                   InitializingBean, DisposableBean {

    private String beanName;

    public LifecycleDemoBean() {
        System.out.println("1. 建構子");
    }

    @Override
    public void setBeanName(String name) {
        this.beanName = name;
        System.out.println("2. setBeanName: " + name);
    }

    @Override
    public void setApplicationContext(ApplicationContext ctx) throws BeansException {
        System.out.println("3. setApplicationContext");
    }

    @PostConstruct
    void onPostConstruct() {
        System.out.println("5. @PostConstruct");
    }

    @Override
    public void afterPropertiesSet() {
        System.out.println("6. afterPropertiesSet");
    }

    @PreDestroy
    void onPreDestroy() {
        System.out.println("8. @PreDestroy");
    }

    @Override
    public void destroy() {
        System.out.println("9. destroy");
    }
}

@Component
class LifecycleTracingPostProcessor implements BeanPostProcessor {

    @Override
    public Object postProcessBeforeInitialization(Object bean, String beanName) {
        if (bean instanceof LifecycleDemoBean) {
            System.out.println("4. BPP.before");
        }
        return bean;
    }

    @Override
    public Object postProcessAfterInitialization(Object bean, String beanName) {
        if (bean instanceof LifecycleDemoBean) {
            System.out.println("7. BPP.after（AOP 代理在此產生）");
        }
        return bean;
    }
}

package com.enterprise.tutorial.core;

import org.springframework.expression.spel.SpelParserConfiguration;
import org.springframework.expression.spel.standard.SpelExpressionParser;
import org.springframework.expression.spel.support.StandardEvaluationContext;

import java.util.Optional;

/**
 * ⭐ 7.0 SpEL 兩大變化：
 *   ① Optional 的 null-safe 導覽與 Elvis 自動解包
 *   ② maxOperations 預設上限 10,000（7.0.8 起），防範運算式 DoS
 */
public class SpelDemo {

    record Address(String city) {}
    record Customer(String name, Optional<Address> address) {}

    public static void main(String[] args) {
        // ② 安全設定：明確指定運算上限（推薦做法）
        var config = new SpelParserConfiguration(
                /* autoGrowNullReferences */ false,
                /* autoGrowCollections */ false,
                /* maximumAutoGrowSize */ 16,
                /* maxOperations */ 10_000);
        var parser = new SpelExpressionParser(config);

        var customer = new Customer("王小明", Optional.of(new Address("台北")));
        var context = new StandardEvaluationContext(customer);

        // ① Optional 的 null-safe 導覽：自動解包，不需要 .get()
        String city = parser.parseExpression("address?.city")
                .getValue(context, String.class);
        System.out.println("城市 = " + city);   // 台北

        // ① Elvis 運算子：Optional.empty() 時自動走到預設值
        var noAddress = new Customer("李小華", Optional.empty());
        String fallback = parser.parseExpression("address?.city ?: '未提供'")
                .getValue(new StandardEvaluationContext(noAddress), String.class);
        System.out.println("城市 = " + fallback);   // 未提供
    }
}

package com.enterprise.tutorial.core;

import org.springframework.beans.factory.ObjectProvider;
import org.springframework.beans.factory.config.ConfigurableBeanFactory;
import org.springframework.context.annotation.Scope;
import org.springframework.stereotype.Component;
import org.springframework.stereotype.Service;

/**
 * ✅ 用 ObjectProvider 取得 prototype，每次呼叫都是新實例。
 * 相比 @Lookup 的優點：不需要 CGLIB 代理、型別安全、可用 orderedStream() 等 API。
 */
@Service
class ReportGeneratorService {

    private final ObjectProvider<ReportBuilder> builderProvider;

    ReportGeneratorService(ObjectProvider<ReportBuilder> builderProvider) {
        this.builderProvider = builderProvider;
    }

    String generate(String title) {
        // 每次呼叫 getObject() 都得到全新的 prototype 實例
        ReportBuilder builder = builderProvider.getObject();
        return builder.title(title).section("摘要").build();
    }
}

@Component
@Scope(ConfigurableBeanFactory.SCOPE_PROTOTYPE)
class ReportBuilder {

    private final StringBuilder sb = new StringBuilder();

    ReportBuilder title(String title) {
        sb.append("# ").append(title).append('\n');
        return this;
    }

    ReportBuilder section(String name) {
        sb.append("## ").append(name).append('\n');
        return this;
    }

    String build() {
        return sb.toString();
    }
}

# 找出所有殘留的 javax 註解（升 7.0 必修）
Get-ChildItem -Recurse -Include *.java | Select-String "javax\.(annotation|inject)"

# 找出可能受 SpEL maxOperations 影響的複雜運算式
Get-ChildItem -Recurse -Include *.java,*.xml,*.properties | Select-String "#\{.*\}"

# 找出使用 XML lang namespace 的設定
Get-ChildItem -Recurse -Include *.xml | Select-String "lang:"

┌─────────────────────────────────────────────────────────────────┐
│  情境                              建議寫法                       │
├─────────────────────────────────────────────────────────────────┤
│  必要相依，只有一個候選     ──▶  ServiceA a  （直接宣告）          │
│  可選相依，可能不存在       ──▶  ObjectProvider<ServiceA>         │
│  多個候選，全部都要         ──▶  List<ServiceA>                   │
│  多個候選，依名稱取用       ──▶  Map<String, ServiceA>            │
│  prototype，每次要新的      ──▶  ObjectProvider<ServiceA>         │
│  重量級，可能用不到         ──▶  ObjectProvider<ServiceA>         │
│  需要依條件挑選候選         ──▶  ObjectProvider + orderedStream() │
└─────────────────────────────────────────────────────────────────┘

// 6.2 的寫法（已棄用）
import org.springframework.lang.Nullable;
public @Nullable String find(String id) { ... }

// 7.0 的寫法
import org.jspecify.annotations.Nullable;
public @Nullable String find(String id) { ... }

// package-info.java —— 一次宣告，整個套件生效
@org.jspecify.annotations.NullMarked
package com.enterprise.tutorial.domain;

┌──────────────────────────────────────────────────────────────────────────┐
│                    三種注入方式的執行時序差異                               │
└──────────────────────────────────────────────────────────────────────────┘

【建構子注入】✅ 推薦
  時間軸 ──────────────────────────────────────────────────────────▶
  │
  ├─ 解析建構子參數 ──▶ 遞迴建立相依 Bean
  │                        │
  ├─ new Service(dep1, dep2) ◀────┘
  │      │
  │      └─▶ 此刻物件已完整，所有 final 欄位已賦值
  │
  └─ 後續：Aware / @PostConstruct / AOP 代理
     └─▶ ✅ @PostConstruct 中可安全使用所有相依


【Setter 注入】⚠️ 僅限可選相依
  時間軸 ──────────────────────────────────────────────────────────▶
  │
  ├─ new Service()          ◀── 此刻 dep1/dep2 都是 null！
  │
  ├─ setDep1(dep1)
  ├─ setDep2(dep2)          ◀── 到這裡才完整
  │
  └─ 後續：Aware / @PostConstruct / AOP 代理
     └─▶ ⚠️ 若建構子中就使用 dep1 → NullPointerException


【欄位注入】❌ 不建議
  時間軸 ──────────────────────────────────────────────────────────▶
  │
  ├─ new Service()          ◀── 欄位皆為 null
  │
  ├─ 反射 field.setAccessible(true)
  ├─ 反射 field.set(bean, dep1)   ◀── 繞過 final、繞過封裝
  │
  └─ 後續：...
     └─▶ ❌ 測試時必須用 ReflectionTestUtils 或啟動 Spring
     └─▶ ❌ AOT / Native Image 需額外的反射 hint
     └─▶ ❌ 相依數量無上限，容易養出 God Class

package com.enterprise.tutorial.di;

import org.jspecify.annotations.NullMarked;
import org.jspecify.annotations.Nullable;
import org.springframework.beans.factory.ObjectProvider;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;

import java.time.Clock;
import java.util.Optional;

/**
 * 企業級 Service 的標準寫法（Spring Framework 7）。
 *
 * 要點：
 *   ① 所有欄位 final —— 不可變、執行緒安全
 *   ② 單一建構子 —— 可省略 @Autowired
 *   ③ 可選相依用 ObjectProvider —— 不存在時不會啟動失敗
 *   ④ @NullMarked —— 預設非 null，可為 null 者明確標註
 *   ⑤ 注入 Clock —— 讓時間可測試
 */
@NullMarked
@Service
public class OrderService {

    private final OrderRepository repository;
    private final PricingService pricingService;
    private final Clock clock;

    /** 可選相依：若沒有設定折扣模組，這裡會是 empty，不影響啟動。 */
    private final ObjectProvider<DiscountPolicy> discountPolicy;

    public OrderService(OrderRepository repository,
                        PricingService pricingService,
                        Clock clock,
                        ObjectProvider<DiscountPolicy> discountPolicy) {
        this.repository = repository;
        this.pricingService = pricingService;
        this.clock = clock;
        this.discountPolicy = discountPolicy;
    }

    @Transactional
    public Order place(OrderCommand command) {
        var basePrice = pricingService.calculate(command.items());

        // 可選相依的標準用法：有就用，沒有就走預設
        var finalPrice = discountPolicy.getIfAvailable(NoDiscountPolicy::new)
                .apply(basePrice, command.customerId());

        var order = new Order(
                command.customerId(),
                command.items(),
                finalPrice,
                clock.instant());

        return repository.save(order);
    }

    /** 明確標示可能回傳 null —— 呼叫端會被 IDE/NullAway 提醒要檢查。 */
    public @Nullable Order findLatest(String customerId) {
        return repository.findLatestByCustomer(customerId).orElse(null);
    }

    /** 更好的做法：直接回傳 Optional，讓型別本身表達語意。 */
    public Optional<Order> findLatestOptional(String customerId) {
        return repository.findLatestByCustomer(customerId);
    }
}

package com.enterprise.tutorial.di;

import org.jspecify.annotations.NullMarked;
import org.springframework.beans.factory.ObjectProvider;
import org.springframework.core.annotation.Order;
import org.springframework.stereotype.Component;
import org.springframework.stereotype.Service;

import java.math.BigDecimal;
import java.util.List;
import java.util.Map;

/**
 * 集合注入：實作可擴充的驗證鏈。
 * 新增一個驗證規則 = 新增一個 @Component，不需要改任何既有程式碼（開放封閉原則）。
 */
@NullMarked
@Service
class PaymentValidationService {

    /** List 注入：所有 PaymentValidator 都會被注入，依 @Order 排序。 */
    private final List<PaymentValidator> validators;

    /** Map 注入：key 是 Bean 名稱，適合「依代碼查策略」的場景。 */
    private final Map<String, PaymentChannel> channels;

    PaymentValidationService(List<PaymentValidator> validators,
                             Map<String, PaymentChannel> channels) {
        this.validators = validators;
        this.channels = channels;
    }

    void validate(PaymentRequest request) {
        // 依 @Order 由小到大依序執行
        validators.forEach(v -> v.validate(request));
    }

    PaymentChannel resolveChannel(String channelCode) {
        PaymentChannel channel = channels.get(channelCode);
        if (channel == null) {
            throw new IllegalArgumentException(
                    "不支援的支付通道：%s（可用：%s）"
                            .formatted(channelCode, channels.keySet()));
        }
        return channel;
    }
}

interface PaymentValidator {
    void validate(PaymentRequest request);
}

@Component
@Order(10)   // 最先執行：基本欄位檢查
class RequiredFieldValidator implements PaymentValidator {
    @Override
    public void validate(PaymentRequest request) {
        if (request.amount() == null || request.amount().signum() <= 0) {
            throw new IllegalArgumentException("金額必須大於 0");
        }
    }
}

@Component
@Order(20)   // 其次：額度檢查
class AmountLimitValidator implements PaymentValidator {

    private static final BigDecimal MAX = new BigDecimal("1000000");

    @Override
    public void validate(PaymentRequest request) {
        if (request.amount().compareTo(MAX) > 0) {
            throw new IllegalArgumentException("單筆金額不得超過 " + MAX);
        }
    }
}

@Component
@Order(30)   // 最後：風控（成本最高，放最後）
class RiskControlValidator implements PaymentValidator {
    @Override
    public void validate(PaymentRequest request) {
        // 呼叫風控服務...
    }
}

interface PaymentChannel {
    void charge(PaymentRequest request);
}

@Component("CREDIT_CARD")
class CreditCardChannel implements PaymentChannel {
    @Override
    public void charge(PaymentRequest request) { }
}

@Component("BANK_TRANSFER")
class BankTransferChannel implements PaymentChannel {
    @Override
    public void charge(PaymentRequest request) { }
}

record PaymentRequest(String customerId, BigDecimal amount, String channelCode) {}

package com.enterprise.tutorial.di;

import org.springframework.beans.factory.annotation.Qualifier;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.stereotype.Service;

import javax.sql.DataSource;
import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

/**
 * ✅ 型別安全的限定詞：重構時 IDE 會自動更新，打錯字編譯期就會發現。
 * ❌ 反例：@Qualifier("readOnlyDataSource") —— 字串打錯只有執行期才知道。
 */
@Qualifier
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.FIELD, ElementType.METHOD, ElementType.PARAMETER, ElementType.TYPE})
@Documented
@interface ReadOnly {
}

@Qualifier
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.FIELD, ElementType.METHOD, ElementType.PARAMETER, ElementType.TYPE})
@Documented
@interface ReadWrite {
}

@Configuration(proxyBeanMethods = false)
class DataSourceConfig {

    @Bean
    @ReadWrite
    DataSource primaryDataSource() {
        return createDataSource("jdbc:postgresql://primary:5432/app");
    }

    @Bean
    @ReadOnly
    DataSource replicaDataSource() {
        return createDataSource("jdbc:postgresql://replica:5432/app");
    }

    private DataSource createDataSource(String url) {
        throw new UnsupportedOperationException("由實際的連線池實作提供");
    }
}

@Service
class ReportQueryService {

    private final DataSource dataSource;

    // 型別安全：如果 @ReadOnly 的 Bean 被移除，這裡編譯仍過但啟動即失敗（早期發現）
    ReportQueryService(@ReadOnly DataSource dataSource) {
        this.dataSource = dataSource;
    }
}

// ============ package-info.java ============
/**
 * 領域模型套件。
 * 宣告 @NullMarked 後，本套件內所有型別預設為「非 null」，
 * 只有明確標註 @Nullable 的才允許 null。
 */
@NullMarked
package com.enterprise.tutorial.domain;

import org.jspecify.annotations.NullMarked;

package com.enterprise.tutorial.domain;

import org.jspecify.annotations.Nullable;

import java.util.List;
import java.util.Map;

/**
 * JSpecify 相較 JSR 305 的關鍵優勢：可標註「泛型參數」「陣列元素」「vararg 元素」。
 */
public interface CustomerRepository {

    /** 回傳值非 null（因為 @NullMarked），找不到時應拋例外。 */
    Customer getById(String id);

    /** 明確標註可回傳 null。 */
    @Nullable Customer findById(String id);

    /**
     * ⭐ 泛型元素的 nullness：
     * List 本身非 null，且「元素」也非 null。
     */
    List<Customer> findAll();

    /**
     * ⭐ JSR 305 做不到的事：
     * List 本身非 null，但「元素可以是 null」。
     */
    List<@Nullable Customer> findByIds(List<String> ids);

    /**
     * ⭐ Map 的 key 非 null、value 可為 null。
     */
    Map<String, @Nullable Customer> findAsMap(List<String> ids);

    /**
     * ⭐ vararg 元素的 nullness：
     * 陣列本身非 null，元素也非 null。
     */
    List<Customer> findByTags(String... tags);

    /**
     * ⭐ 陣列本身非 null，但元素可為 null。
     */
    void batchUpdate(@Nullable Customer[] customers);
}

record Customer(String id, String name, @Nullable String email) {
}

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-compiler-plugin</artifactId>
    <configuration>
        <release>25</release>
        <parameters>true</parameters>
        <compilerArgs>
            <arg>-XDcompilePolicy=simple</arg>
            <arg>--should-stop=ifError=FLOW</arg>
            <arg>-Xplugin:ErrorProne -XepOpt:NullAway:JSpecifyMode=true
                 -XepOpt:NullAway:AnnotatedPackages=com.enterprise.tutorial</arg>
        </compilerArgs>
        <annotationProcessorPaths>
            <path>
                <groupId>com.google.errorprone</groupId>
                <artifactId>error_prone_core</artifactId>
                <version>2.36.0</version>
            </path>
            <path>
                <groupId>com.uber.nullaway</groupId>
                <artifactId>nullaway</artifactId>
                <version>0.12.3</version>
            </path>
        </annotationProcessorPaths>
    </configuration>
</plugin>

package com.enterprise.tutorial.di.cycle;

import org.springframework.context.ApplicationEventPublisher;
import org.springframework.context.event.EventListener;
import org.springframework.beans.factory.ObjectProvider;
import org.springframework.stereotype.Service;

// ═══════════════════════════════════════════════════════════
// ❌ 問題：A ⇄ B 建構子循環依賴，啟動即失敗
// ═══════════════════════════════════════════════════════════
/*
@Service
class BadUserService {
    BadUserService(BadNotificationService notification) { }   // A → B
}

@Service
class BadNotificationService {
    BadNotificationService(BadUserService userService) { }    // B → A ❌
}
*/

// ═══════════════════════════════════════════════════════════
// ✅ 方案一：抽出共用元件（最推薦）
// ═══════════════════════════════════════════════════════════
@Service
class UserQueryService {          // 兩者共用的查詢邏輯，抽成獨立元件
    User findById(String id) {
        return new User(id, "user@example.com");
    }
}

@Service
class UserServiceV1 {
    private final UserQueryService query;
    UserServiceV1(UserQueryService query) { this.query = query; }
}

@Service
class NotificationServiceV1 {
    private final UserQueryService query;    // 不再依賴 UserService
    NotificationServiceV1(UserQueryService query) { this.query = query; }
}

// ═══════════════════════════════════════════════════════════
// ✅ 方案二：事件解耦（適合「通知」語意，見第 12 章）
// ═══════════════════════════════════════════════════════════
@Service
class UserServiceV2 {
    private final ApplicationEventPublisher publisher;

    UserServiceV2(ApplicationEventPublisher publisher) {
        this.publisher = publisher;
    }

    void register(String email) {
        // ... 註冊邏輯 ...
        publisher.publishEvent(new UserRegisteredEvent(email));
    }
}

@Service
class NotificationServiceV2 {
    // 完全不知道 UserService 的存在 —— 徹底解耦
    @EventListener
    void onUserRegistered(UserRegisteredEvent event) {
        // 寄送歡迎信
    }
}

record UserRegisteredEvent(String email) {}

// ═══════════════════════════════════════════════════════════
// ✅ 方案三：ObjectProvider 延遲解析（B 只在少數情況被用到）
// ═══════════════════════════════════════════════════════════
@Service
class UserServiceV3 {
    private final ObjectProvider<AuditService> auditProvider;

    UserServiceV3(ObjectProvider<AuditService> auditProvider) {
        this.auditProvider = auditProvider;   // 建構時不解析，不觸發循環
    }

    void deleteUser(String id) {
        // 只有真的要稽核時才取得 Bean
        auditProvider.ifAvailable(audit -> audit.record("DELETE_USER", id));
    }
}

@Service
class AuditService {
    private final UserServiceV3 userService;

    AuditService(UserServiceV3 userService) {
        this.userService = userService;
    }

    void record(String action, String target) { }
}

record User(String id, String email) {}

# 找出所有使用舊 Spring nullness 註解的檔案
Get-ChildItem -Recurse -Include *.java |
    Select-String "org\.springframework\.lang\.(Nullable|NonNull)"

# 批次替換（先確認範圍再執行，建議在 Git 乾淨狀態下操作）
Get-ChildItem -Recurse -Include *.java | ForEach-Object {
    (Get-Content $_.FullName -Raw) `
        -replace 'org\.springframework\.lang\.Nullable', 'org.jspecify.annotations.Nullable' `
        -replace 'org\.springframework\.lang\.NonNull', 'org.jspecify.annotations.NonNull' |
    Set-Content $_.FullName -NoNewline
}

# 找出欄位注入（重構目標）
Get-ChildItem -Recurse -Include *.java |
    Select-String -Pattern "@Autowired" -Context 0,1 |
    Where-Object { $_.Context.PostContext -match "private|protected|public" }

// ❌ 業務邏輯只有 1 行，周邊關注點卻有 20 行
public Order placeOrder(OrderCommand cmd) {
    long start = System.nanoTime();
    log.info("placeOrder 開始, customerId={}", cmd.customerId());
    if (!securityService.hasPermission(currentUser(), "ORDER_CREATE")) {
        throw new AccessDeniedException("無權限");
    }
    TransactionStatus tx = txManager.getTransaction(new DefaultTransactionDefinition());
    try {
        Order order = repository.save(new Order(cmd));   // ← 唯一的業務邏輯
        txManager.commit(tx);
        auditService.record("ORDER_CREATE", order.id());
        return order;
    } catch (RuntimeException e) {
        txManager.rollback(tx);
        log.error("placeOrder 失敗", e);
        throw e;
    } finally {
        metrics.record("placeOrder", System.nanoTime() - start);
        log.info("placeOrder 結束");
    }
}

// ✅ 業務邏輯與周邊關注點徹底分離
@Transactional
@PreAuthorize("hasAuthority('ORDER_CREATE')")
@Audited("ORDER_CREATE")
@Observed(name = "order.place")
public Order placeOrder(OrderCommand cmd) {
    return repository.save(new Order(cmd));
}

                  ┌─────────────────────────────────────────┐
                  │           @Around（前半段）               │
                  │  ┌───────────────────────────────────┐  │
                  │  │           @Before                 │  │
                  │  │  ┌─────────────────────────────┐  │  │
                  │  │  │                             │  │  │
                  │  │  │     目標方法執行             │  │  │
                  │  │  │   joinPoint.proceed()       │  │  │
                  │  │  │                             │  │  │
                  │  │  └─────────────────────────────┘  │  │
                  │  │       ↓ 正常          ↓ 例外       │  │
                  │  │  @AfterReturning  @AfterThrowing  │  │
                  │  │  ┌─────────────────────────────┐  │  │
                  │  │  │        @After（finally）     │  │  │
                  │  │  └─────────────────────────────┘  │  │
                  │  └───────────────────────────────────┘  │
                  │           @Around（後半段）               │
                  └─────────────────────────────────────────┘

⚠️ 注意：@After 一定會執行（等同 finally），
   @AfterReturning 只在正常回傳時執行，
   @AfterThrowing 只在拋出例外時執行（且例外仍會繼續往外傳）。
   只有 @Around 能「吞掉例外」或「改寫回傳值」。

【JDK 動態代理】
   caller ──▶ Proxy (implements OrderService)
                  │
                  ├─ InvocationHandler
                  │     └─ 執行 Advice 鏈
                  │
                  └──▶ OrderServiceImpl (target)

   ⚠️ 只能注入為 OrderService，注入為 OrderServiceImpl 會失敗

【CGLIB】
   caller ──▶ OrderServiceImpl$$SpringCGLIB$$0  (extends OrderServiceImpl)
                  │
                  ├─ MethodInterceptor
                  │     └─ 執行 Advice 鏈
                  │
                  └──▶ super.method() 或委派給 target

   ⚠️ final 方法不會被攔截，且完全沒有警告

// ① 上下文層級：宣告名稱固定的 ProxyConfig Bean
@Bean(name = AutoProxyUtils.DEFAULT_PROXY_CONFIG_BEAN_NAME)
ProxyConfig defaultProxyConfig() {
    ProxyConfig config = new ProxyConfig();
    config.setProxyTargetClass(true);
    return config;
}

// ② Bean 層級：@Proxyable 覆寫上下文預設
@Service
@Proxyable(Proxyable.Type.INTERFACES)   // 這個 Bean 改用 JDK Proxy
class SpecialService implements MyApi { }

execution( modifiers?  return-type  declaring-type?  method-name(params)  throws? )
              │            │            │                │        │
           可省略       必填         可省略           必填    必填
                       * = 任意                                (..) = 任意參數
                                                              (*)  = 恰好一個參數
                                                              ()   = 無參數

範例：
execution(public * com.app.service.*Service.find*(..))
   │       │    │        │            │       │     └─ 任意參數
   │       │    │        │            │       └─ 方法名以 find 開頭
   │       │    │        │            └─ 類別名以 Service 結尾
   │       │    │        └─ service 套件（不含子套件；要含子套件用 service..*）
   │       │    └─ 任意回傳型別
   │       └─ 只比對 public 方法
   └─ 方法執行

╔════════════════════════════════════════════════════════════════════════════╗
║              Spring AOP 代理建立與呼叫的完整路徑                              ║
╠════════════════════════════════════════════════════════════════════════════╣
║                                                                            ║
║  【建立期：Bean 初始化階段】                                                  ║
║                                                                            ║
║   OrderServiceImpl 實例                                                     ║
║          │                                                                 ║
║          ▼                                                                 ║
║   ┌──────────────────────────────────────────────────────────────────┐     ║
║   │  AbstractAutoProxyCreator（一種 BeanPostProcessor）                │     ║
║   │  postProcessAfterInitialization()                                 │     ║
║   │                                                                   │     ║
║   │  ① 找出所有候選 Advisor（Aspect + Spring 內建）                     │     ║
║   │     ├─ @Transactional → BeanFactoryTransactionAttributeSource...  │     ║
║   │     ├─ @Async         → AsyncAnnotationAdvisor                    │     ║
║   │     ├─ @Cacheable     → BeanFactoryCacheOperationSourceAdvisor    │     ║
║   │     ├─ @Retryable ⭐  → RetryAnnotationBeanPostProcessor          │     ║
║   │     └─ @Aspect 自訂    → InstantiationModelAwarePointcutAdvisor    │     ║
║   │                                                                   │     ║
║   │  ② 用 Pointcut 過濾：哪些 Advisor 適用於這個 Bean？                  │     ║
║   │                                                                   │     ║
║   │  ③ 決定代理策略                                                    │     ║
║   │     ┌─────────────────────────────────────────────────┐           │     ║
║   │     │ @Proxyable 有指定? ──是──▶ 用它 ⭐7.0             │           │     ║
║   │     │        │否                                       │           │     ║
║   │     │ ProxyConfig Bean 有設定? ──是──▶ 用它 ⭐7.0       │           │     ║
║   │     │        │否                                       │           │     ║
║   │     │ proxyTargetClass=true? ──是──▶ CGLIB             │           │     ║
║   │     │        │否                                       │           │     ║
║   │     │ 有實作介面? ──是──▶ JDK Proxy ──否──▶ CGLIB       │           │     ║
║   │     └─────────────────────────────────────────────────┘           │     ║
║   │                                                                   │     ║
║   │  ④ 產生代理，回傳代理物件（取代原始 Bean 放入容器）                   │     ║
║   └───────────────────────────────┬──────────────────────────────────┘     ║
║                                   ▼                                        ║
║               容器中的是 Proxy，不是 OrderServiceImpl                        ║
║                                                                            ║
║  ════════════════════════════════════════════════════════════════════      ║
║                                                                            ║
║  【呼叫期：執行階段】                                                        ║
║                                                                            ║
║   Controller ──呼叫──▶ Proxy.placeOrder()                                  ║
║                            │                                               ║
║                            ▼                                               ║
║        ┌───────────────────────────────────────────────┐                   ║
║        │  ReflectiveMethodInvocation（攔截器鏈）         │                   ║
║        │                                               │                   ║
║        │  Interceptor 1: @Around 前半 / 安全檢查         │                   ║
║        │      │  proceed()                             │                   ║
║        │      ▼                                        │                   ║
║        │  Interceptor 2: TransactionInterceptor        │                   ║
║        │      │  begin transaction                     │                   ║
║        │      ▼                                        │                   ║
║        │  Interceptor 3: CacheInterceptor              │                   ║
║        │      │  查快取                                 │                   ║
║        │      ▼                                        │                   ║
║        │  Interceptor 4: RetryInterceptor ⭐            │                   ║
║        │      │                                        │                   ║
║        │      ▼                                        │                   ║
║        │  ═══ target.placeOrder() 真正執行 ═══           │                   ║
║        │      │                                        │                   ║
║        │      ▼ （逆序返回，各層做後置處理）               │                   ║
║        └───────────────────────────────────────────────┘                   ║
║                            │                                               ║
║                            ▼                                               ║
║                        回傳結果                                             ║
║                                                                            ║
║  ⚠️ 致命陷阱：target.placeOrder() 內若呼叫 this.otherMethod()，              ║
║     那是「原始物件」的呼叫，完全不經過 Proxy → 所有 Advice 失效！              ║
╚════════════════════════════════════════════════════════════════════════════╝

package com.enterprise.tutorial.aop;

import org.aspectj.lang.ProceedingJoinPoint;
import org.aspectj.lang.annotation.Around;
import org.aspectj.lang.annotation.Aspect;
import org.aspectj.lang.annotation.Pointcut;
import org.aspectj.lang.reflect.MethodSignature;
import org.jspecify.annotations.NullMarked;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.EnableAspectJAutoProxy;
import org.springframework.core.annotation.Order;
import org.springframework.stereotype.Component;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
import java.time.Clock;
import java.time.Instant;

/**
 * 啟用 AOP。
 * proxyTargetClass = true 表示強制 CGLIB；
 * ⭐ 7.0 起這個設定會一致套用到所有 proxy processor，
 *    而不只是 @Transactional。
 */
@Configuration(proxyBeanMethods = false)
@EnableAspectJAutoProxy(proxyTargetClass = true)
class AopConfig {
}

/** 自訂稽核註解 —— 用 @annotation pointcut 比 execution 更精確且可重構。 */
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public @interface Audited {
    /** 稽核事件代碼，例如 ORDER_CREATE。 */
    String value();

    /** 是否記錄方法參數（含個資時應設為 false）。 */
    boolean logArguments() default false;
}

@NullMarked
@Aspect
@Component
@Order(100)   // 數值越小越外層；稽核應在交易之外（交易 Advisor 預設 Ordered.LOWEST_PRECEDENCE）
public class AuditAspect {

    private final AuditWriter writer;
    private final Clock clock;

    public AuditAspect(AuditWriter writer, Clock clock) {
        this.writer = writer;
        this.clock = clock;
    }

    /** 具名 Pointcut：可重複使用，且比字串散落各處好維護。 */
    @Pointcut("@annotation(com.enterprise.tutorial.aop.Audited)")
    void auditedMethod() {
    }

    @Around("auditedMethod() && @annotation(audited)")
    public Object audit(ProceedingJoinPoint pjp, Audited audited) throws Throwable {
        var signature = (MethodSignature) pjp.getSignature();
        Instant start = clock.instant();
        String actor = CurrentUser.name();

        try {
            Object result = pjp.proceed();
            writer.success(new AuditRecord(
                    audited.value(),
                    actor,
                    signature.toShortString(),
                    audited.logArguments() ? maskSensitive(pjp.getArgs()) : "[hidden]",
                    start,
                    clock.instant()));
            return result;
        } catch (Throwable ex) {
            writer.failure(new AuditRecord(
                    audited.value(),
                    actor,
                    signature.toShortString(),
                    "[hidden]",
                    start,
                    clock.instant()), ex);
            throw ex;   // ⚠️ 一定要重拋，否則會吞掉例外
        }
    }

    /** 🔒 稽核日誌絕不可原樣記錄敏感資料。 */
    private String maskSensitive(Object[] args) {
        var sb = new StringBuilder("[");
        for (Object arg : args) {
            String text = String.valueOf(arg);
            sb.append(text.replaceAll("\\d{4}-?\\d{4}-?\\d{4}-?(\\d{4})", "****-****-****-$1"))
              .append(", ");
        }
        return sb.append(']').toString();
    }
}

record AuditRecord(String event, String actor, String method,
                   String arguments, Instant startedAt, Instant endedAt) {
}

interface AuditWriter {
    void success(AuditRecord record);

    void failure(AuditRecord record, Throwable cause);
}

final class CurrentUser {
    private CurrentUser() {
    }

    static String name() {
        return "system";
    }
}

package com.enterprise.tutorial.aop;

import org.aspectj.lang.JoinPoint;
import org.aspectj.lang.ProceedingJoinPoint;
import org.aspectj.lang.annotation.After;
import org.aspectj.lang.annotation.AfterReturning;
import org.aspectj.lang.annotation.AfterThrowing;
import org.aspectj.lang.annotation.Around;
import org.aspectj.lang.annotation.Aspect;
import org.aspectj.lang.annotation.Before;
import org.aspectj.lang.annotation.Pointcut;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.stereotype.Component;

/**
 * 五種 Advice 的執行順序（同一個 Aspect 內）：
 *   @Around（前）→ @Before → 目標方法
 *                    → @AfterReturning 或 @AfterThrowing
 *                    → @After → @Around（後）
 */
@Aspect
@Component
public class AdviceOrderDemoAspect {

    private static final Logger log = LoggerFactory.getLogger(AdviceOrderDemoAspect.class);

    /** 只攔截 service 套件（含子套件）下的 public 方法。 */
    @Pointcut("execution(public * com.enterprise.tutorial.service..*.*(..))")
    void serviceLayer() {
    }

    @Around("serviceLayer()")
    public Object around(ProceedingJoinPoint pjp) throws Throwable {
        log.debug("① @Around 前 - {}", pjp.getSignature().toShortString());
        long start = System.nanoTime();
        try {
            Object result = pjp.proceed();
            log.debug("⑥ @Around 後 - 耗時 {} ms", (System.nanoTime() - start) / 1_000_000);
            return result;
        } catch (Throwable ex) {
            log.debug("⑥ @Around 後（例外）");
            throw ex;
        }
    }

    @Before("serviceLayer()")
    public void before(JoinPoint jp) {
        log.debug("② @Before - args={}", (Object) jp.getArgs());
    }

    /** returning 的變數名必須與參數名一致，Spring 會自動綁定回傳值。 */
    @AfterReturning(pointcut = "serviceLayer()", returning = "result")
    public void afterReturning(JoinPoint jp, Object result) {
        log.debug("④ @AfterReturning - result={}", result);
    }

    /** ⚠️ @AfterThrowing 無法阻止例外往外傳；要吞掉例外只能用 @Around。 */
    @AfterThrowing(pointcut = "serviceLayer()", throwing = "ex")
    public void afterThrowing(JoinPoint jp, Throwable ex) {
        log.error("④ @AfterThrowing - {}", ex.getMessage());
    }

    /** 等同 finally，正常與例外都會執行。 */
    @After("serviceLayer()")
    public void after(JoinPoint jp) {
        log.debug("⑤ @After（finally）");
    }
}

package com.enterprise.tutorial.aop;

import org.jspecify.annotations.NullMarked;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.retry.RetryPolicy;
import org.springframework.core.retry.RetryTemplate;
import org.springframework.resilience.annotation.ConcurrencyLimit;
import org.springframework.resilience.annotation.EnableResilientMethods;
import org.springframework.resilience.annotation.Retryable;
import org.springframework.stereotype.Service;
import reactor.core.publisher.Mono;

import java.time.Duration;

/** ⭐ 7.0 新增：啟用 @Retryable 與 @ConcurrencyLimit。 */
@Configuration(proxyBeanMethods = false)
@EnableResilientMethods
class ResilienceConfig {
}

@NullMarked
@Service
public class PaymentGatewayClient {

    /**
     * ⭐ @Retryable：宣告式重試。
     *   - delay / jitter / multiplier / maxDelay 提供完整的指數退避控制
     *   - includes / excludes 精確指定要重試的例外
     *   - ⚠️ 只重試「暫時性」錯誤，業務錯誤重試只會放大問題
     */
    @Retryable(
            maxAttempts = 4,
            delay = 200,
            jitter = 100,
            multiplier = 2.0,
            maxDelay = 3000,
            includes = {GatewayTimeoutException.class, GatewayUnavailableException.class},
            excludes = {InsufficientFundsException.class})   // 餘額不足重試 100 次也沒用
    public PaymentResult charge(String orderId, long amountCents) {
        return doCharge(orderId, amountCents);
    }

    /**
     * ⭐ @Retryable 會自動偵測反應式回傳型別，
     *    對 Mono / Flux 套用 Reactor 的 retry 操作子，而非阻塞式重試。
     */
    @Retryable(maxAttempts = 3, delay = 100, multiplier = 2.0)
    public Mono<PaymentResult> chargeReactive(String orderId, long amountCents) {
        return Mono.fromCallable(() -> doCharge(orderId, amountCents));
    }

    /**
     * ⭐ @ConcurrencyLimit：限制同時進入此方法的執行緒數。
     * 用途：保護下游系統（下游只能承受 10 個併發連線）。
     * ⚠️ 這是「限流」不是「熔斷」；下游持續失敗時仍需搭配重試策略與逾時。
     */
    @ConcurrencyLimit(10)
    public ReconciliationReport reconcile(String batchId) {
        return doReconcile(batchId);
    }

    private PaymentResult doCharge(String orderId, long amountCents) {
        throw new UnsupportedOperationException("由實際的 HTTP 客戶端提供");
    }

    private ReconciliationReport doReconcile(String batchId) {
        throw new UnsupportedOperationException("由實際實作提供");
    }
}

/**
 * ⭐ 程式化重試：RetryTemplate。
 * 適用於「無法用註解」的情境（例如在 lambda 內、在非 Bean 的工具類別中）。
 */
@NullMarked
@Service
class ProgrammaticRetryService {

    private final RetryTemplate retryTemplate;

    ProgrammaticRetryService() {
        RetryPolicy policy = RetryPolicy.builder()
                .maxAttempts(5)
                .delay(Duration.ofMillis(150))
                .multiplier(2.0)
                .maxDelay(Duration.ofSeconds(5))
                .jitter(Duration.ofMillis(50))
                .includes(GatewayTimeoutException.class)
                .build();
        this.retryTemplate = new RetryTemplate(policy);
    }

    String fetchExchangeRate(String currencyPair) {
        return retryTemplate.execute(() -> callRateApi(currencyPair));
    }

    private String callRateApi(String pair) {
        throw new UnsupportedOperationException("由實際實作提供");
    }
}

class GatewayTimeoutException extends RuntimeException {
}

class GatewayUnavailableException extends RuntimeException {
}

class InsufficientFundsException extends RuntimeException {
}

record PaymentResult(String transactionId, boolean success) {
}

record ReconciliationReport(String batchId, int matched, int unmatched) {
}

package com.enterprise.tutorial.aop;

import io.micrometer.core.instrument.MeterRegistry;
import io.micrometer.core.instrument.Timer;
import org.aspectj.lang.ProceedingJoinPoint;
import org.aspectj.lang.annotation.Around;
import org.aspectj.lang.annotation.Aspect;
import org.aspectj.lang.reflect.MethodSignature;
import org.springframework.core.annotation.Order;
import org.springframework.stereotype.Component;

/**
 * ⚠️ 效能監控剖面本身必須極輕量，否則會變成效能問題的來源。
 * 三個原則：
 *   ① 不要在 Advice 中做 I/O
 *   ② Tag 的 cardinality 要有界（不要用 userId、orderId 當 tag）
 *   ③ 用 @Order 放在最外層，才能量到完整耗時
 */
@Aspect
@Component
@Order(1)
public class MetricsAspect {

    private final MeterRegistry registry;

    public MetricsAspect(MeterRegistry registry) {
        this.registry = registry;
    }

    @Around("execution(public * com.enterprise.tutorial.service..*.*(..))")
    public Object measure(ProceedingJoinPoint pjp) throws Throwable {
        var signature = (MethodSignature) pjp.getSignature();
        Timer.Sample sample = Timer.start(registry);
        String outcome = "success";
        try {
            return pjp.proceed();
        } catch (Throwable ex) {
            outcome = "error";
            throw ex;
        } finally {
            sample.stop(Timer.builder("service.method.duration")
                    // ✅ 有界的 tag：類別名與方法名的組合是有限的
                    .tag("class", signature.getDeclaringType().getSimpleName())
                    .tag("method", signature.getName())
                    .tag("outcome", outcome)
                    .publishPercentileHistogram()
                    .register(registry));
        }
    }
}

package com.enterprise.tutorial.aop;

import org.springframework.aop.framework.AopContext;
import org.springframework.beans.factory.ObjectProvider;
import org.springframework.context.annotation.EnableAspectJAutoProxy;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Propagation;
import org.springframework.transaction.annotation.Transactional;

import java.util.List;

// ═══════════════════════════════════════════════════════════════
// ❌ 問題：自我呼叫，@Transactional(REQUIRES_NEW) 完全沒生效
// ═══════════════════════════════════════════════════════════════
@Service
class BrokenBatchService {

    public void processAll(List<String> ids) {
        for (String id : ids) {
            processOne(id);   // ❌ this.processOne()，不經過 Proxy
        }
    }

    @Transactional(propagation = Propagation.REQUIRES_NEW)
    public void processOne(String id) {
        // 期待：每筆各自交易，一筆失敗不影響其他
        // 實際：完全沒有交易，或跟外層共用交易
    }
}

// ═══════════════════════════════════════════════════════════════
// ✅ 解法一：拆成兩個 Bean（最推薦 —— 職責也更清楚）
// ═══════════════════════════════════════════════════════════════
@Service
class BatchOrchestrator {

    private final BatchItemProcessor processor;

    BatchOrchestrator(BatchItemProcessor processor) {
        this.processor = processor;
    }

    public void processAll(List<String> ids) {
        for (String id : ids) {
            try {
                processor.processOne(id);   // ✅ 跨 Bean 呼叫，經過 Proxy
            } catch (RuntimeException ex) {
                // 單筆失敗不中斷整批
            }
        }
    }
}

@Service
class BatchItemProcessor {

    @Transactional(propagation = Propagation.REQUIRES_NEW)
    public void processOne(String id) {
        // ✅ 交易正常生效
    }
}

// ═══════════════════════════════════════════════════════════════
// ✅ 解法二：注入自己（ObjectProvider 避免建構子循環依賴）
// ═══════════════════════════════════════════════════════════════
@Service
class SelfInjectingBatchService {

    private final ObjectProvider<SelfInjectingBatchService> self;

    SelfInjectingBatchService(ObjectProvider<SelfInjectingBatchService> self) {
        this.self = self;
    }

    public void processAll(List<String> ids) {
        SelfInjectingBatchService proxy = self.getObject();   // 取得的是 Proxy
        ids.forEach(proxy::processOne);
    }

    @Transactional(propagation = Propagation.REQUIRES_NEW)
    public void processOne(String id) {
    }
}

// ═══════════════════════════════════════════════════════════════
// ⚠️ 解法三：AopContext.currentProxy()（不推薦，有效能與可讀性成本）
// ═══════════════════════════════════════════════════════════════
@EnableAspectJAutoProxy(exposeProxy = true)   // 必須開啟，否則拋 IllegalStateException
@Service
class AopContextBatchService {

    public void processAll(List<String> ids) {
        var proxy = (AopContextBatchService) AopContext.currentProxy();
        ids.forEach(proxy::processOne);
    }

    @Transactional(propagation = Propagation.REQUIRES_NEW)
    public void processOne(String id) {
    }
}

// 6.2（Spring Retry 專案）
import org.springframework.retry.annotation.Backoff;
import org.springframework.retry.annotation.EnableRetry;
import org.springframework.retry.annotation.Retryable;

@EnableRetry
@Retryable(retryFor = TimeoutException.class,
           maxAttempts = 4,
           backoff = @Backoff(delay = 200, multiplier = 2.0, maxDelay = 3000))

// 7.0（核心 API）⭐
import org.springframework.resilience.annotation.EnableResilientMethods;
import org.springframework.resilience.annotation.Retryable;

@EnableResilientMethods
@Retryable(includes = TimeoutException.class,
           maxAttempts = 4,
           delay = 200, multiplier = 2.0, maxDelay = 3000, jitter = 100)

# 找出寬鬆的 pointcut（效能與正確性風險）
Get-ChildItem -Recurse -Include *.java |
    Select-String -Pattern 'execution\(\s*\*\s+\*\.\*\('

# 找出沒有 @Order 的 Aspect
Get-ChildItem -Recurse -Include *.java |
    Select-String -Pattern '@Aspect' -Context 2,2 |
    Where-Object { $_.Context.PreContext -notmatch '@Order' -and
                   $_.Context.PostContext -notmatch '@Order' }

# 找出仍在使用 Spring Retry 舊套件的檔案
Get-ChildItem -Recurse -Include *.java |
    Select-String -Pattern 'org\.springframework\.retry\.'

import org.springframework.aop.support.AopUtils;

boolean isProxy      = AopUtils.isAopProxy(bean);
boolean isCglib      = AopUtils.isCglibProxy(bean);
boolean isJdkProxy   = AopUtils.isJdkDynamicProxy(bean);
Class<?> targetClass = AopUtils.getTargetClass(bean);

┌──────────────────────────────────────────────────────────────────────┐
│  你的系統是 I/O 密集且併發極高（> 10k 同時連線）嗎？                     │
│      │否                                    │是                       │
│      ▼                                      ▼                        │
│  ✅ Spring MVC                      團隊熟悉反應式程式設計嗎？          │
│  （搭配虛擬執行緒                        │是         │否               │
│    可處理絕大多數場景）                   ▼           ▼                │
│                                    ✅ WebFlux   ✅ MVC + 虛擬執行緒     │
│                                                （Java 21+，成本最低）  │
└──────────────────────────────────────────────────────────────────────┘

// 7.0 之前：** 只能在結尾
@GetMapping("/static/**")           // ✅ 一直都支援

// ⭐ 7.0 新增：** 可以在開頭或中間
@GetMapping("/**/pages/index.html") // ✅ 7.0 起支援
@GetMapping("/**/*.pdf")            // ✅ 7.0 起支援

// 6.2 的做法：直接操作 List，容易搞錯順序、容易誤刪預設轉換器
@Override
public void extendMessageConverters(List<HttpMessageConverter<?>> converters) {
    converters.add(0, myConverter);          // 順序靠索引，脆弱
    converters.removeIf(c -> c instanceof StringHttpMessageConverter);
}

// ⭐ 7.0 的做法：語意化的 Builder
@Override
public void configureMessageConverters(HttpMessageConverters.ServerBuilder builder) {
    builder.jsonMessageConverter(new JacksonJsonHttpMessageConverter(customJsonMapper()))
           .stringMessageConverter(new StringHttpMessageConverter(StandardCharsets.UTF_8))
           .additionalMessageConverter(new CsvHttpMessageConverter());
}

// ⭐ 7.0 建立 JsonMapper 的正確方式
import tools.jackson.databind.json.JsonMapper;
import tools.jackson.databind.SerializationFeature;
import tools.jackson.datatype.jsr310.JavaTimeModule;

JsonMapper mapper = JsonMapper.builder()
        .addModule(new JavaTimeModule())
        .disable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS)
        .build();

╔════════════════════════════════════════════════════════════════════════════╗
║                    Spring MVC 請求處理完整管線                                ║
╠════════════════════════════════════════════════════════════════════════════╣
║                                                                            ║
║   HTTP Request                                                             ║
║        │                                                                   ║
║        ▼                                                                   ║
║  ┌──────────────────────────────────────────────────────────────────┐      ║
║  │  Servlet Filter Chain（Servlet 6.1 / Jakarta EE 11）              │      ║
║  │  CharacterEncodingFilter → CorsFilter → Security Filter Chain     │      ║
║  │  → RequestContextFilter → 自訂 Filter                              │      ║
║  └────────────────────────────┬─────────────────────────────────────┘      ║
║                               ▼                                            ║
║  ┌──────────────────────────────────────────────────────────────────┐      ║
║  │                     DispatcherServlet                             │      ║
║  │                                                                   │      ║
║  │  ① 檢查 multipart → MultipartResolver                             │      ║
║  │                                                                   │      ║
║  │  ② getHandler(request)                                            │      ║
║  │     └─ RequestMappingHandlerMapping                               │      ║
║  │          ├─ PathPattern 比對 ⭐ 7.0 支援前導 /**/                  │      ║
║  │          ├─ HTTP method / params / headers / consumes / produces  │      ║
║  │          ├─ ⭐ API version 比對（7.0 新增，見第 8 章）              │      ║
║  │          └─ 回傳 HandlerExecutionChain（Handler + Interceptors）   │      ║
║  │                                                                   │      ║
║  │  ③ Interceptor.preHandle()（依序）                                 │      ║
║  │                                                                   │      ║
║  │  ④ getHandlerAdapter(handler)                                     │      ║
║  │     └─ RequestMappingHandlerAdapter                               │      ║
║  │          │                                                        │      ║
║  │          ├─ HandlerMethodArgumentResolver（解析參數）               │      ║
║  │          │    @RequestBody   → HttpMessageConverter.read()        │      ║
║  │          │    @RequestParam  → 型別轉換 + 驗證                     │      ║
║  │          │    @PathVariable  → 從 PathPattern 抽取                 │      ║
║  │          │    @Valid         → Bean Validation 3.1（第 9 章）      │      ║
║  │          │                                                        │      ║
║  │          ├─ ═══ 呼叫 Controller 方法 ═══                            │      ║
║  │          │      └─ Service（@Transactional / AOP 代理）             │      ║
║  │          │                                                        │      ║
║  │          └─ HandlerMethodReturnValueHandler（處理回傳值）           │      ║
║  │               @ResponseBody   → HttpMessageConverter.write()      │      ║
║  │               ResponseEntity  → 同上 + 狀態碼 + 標頭                │      ║
║  │               String / ModelAndView → ViewResolver                │      ║
║  │                                                                   │      ║
║  │  ⑤ Interceptor.postHandle()（逆序）                                │      ║
║  │                                                                   │      ║
║  │  ⑥ 若有例外 → HandlerExceptionResolver                            │      ║
║  │       └─ ExceptionHandlerExceptionResolver                        │      ║
║  │            → @ExceptionHandler / @ControllerAdvice                │      ║
║  │            → ProblemDetail（RFC 9457）                             │      ║
║  │                                                                   │      ║
║  │  ⑦ 渲染 View（若非 @ResponseBody）                                 │      ║
║  │                                                                   │      ║
║  │  ⑧ Interceptor.afterCompletion()（逆序，等同 finally）              │      ║
║  └────────────────────────────┬─────────────────────────────────────┘      ║
║                               ▼                                            ║
║                        HTTP Response                                       ║
║                                                                            ║
║  ❌ 7.0 移除：ThemeResolver、Undertow 支援、                                 ║
║               suffixPatternMatch / trailingSlashMatch / favorPathExtension  ║
║  ⚠️ 7.0 棄用：PathMatcher / AntPathMatcher、<mvc:*> XML、                    ║
║               HandlerMappingIntrospector SPI、XLS / RSS / PDF View          ║
╚════════════════════════════════════════════════════════════════════════════╝

package com.enterprise.tutorial.web;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.converter.HttpMessageConverters;
import org.springframework.http.converter.StringHttpMessageConverter;
import org.springframework.http.converter.json.JacksonJsonHttpMessageConverter;
import org.springframework.web.servlet.config.annotation.ContentNegotiationConfigurer;
import org.springframework.web.servlet.config.annotation.CorsRegistry;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
import org.springframework.web.servlet.config.annotation.InterceptorRegistry;
import org.springframework.web.servlet.config.annotation.PathMatchConfigurer;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
import tools.jackson.databind.SerializationFeature;
import tools.jackson.databind.json.JsonMapper;
import tools.jackson.datatype.jsr310.JavaTimeModule;

import java.nio.charset.StandardCharsets;
import java.time.Duration;

/**
 * Spring Framework 7.0 的 MVC 組態範本。
 *
 * ⚠️ 7.0 移除的設定（若你的舊程式碼有這些，會編譯失敗）：
 *   - configurer.setUseSuffixPatternMatch(true)
 *   - configurer.setUseTrailingSlashMatch(true)
 *   - contentNegotiation.favorPathExtension(true)
 */
@Configuration(proxyBeanMethods = false)
@EnableWebMvc
public class WebMvcConfig implements WebMvcConfigurer {

    private final AuditInterceptor auditInterceptor;

    public WebMvcConfig(AuditInterceptor auditInterceptor) {
        this.auditInterceptor = auditInterceptor;
    }

    /** ⭐ 7.0 新增：語意化的 HttpMessageConverters 組態 API。 */
    @Override
    public void configureMessageConverters(HttpMessageConverters.ServerBuilder builder) {
        builder.jsonMessageConverter(new JacksonJsonHttpMessageConverter(jsonMapper()))
               .stringMessageConverter(
                       new StringHttpMessageConverter(StandardCharsets.UTF_8));
    }

    /** ⭐ 7.0 預設 Jackson 3.x：套件是 tools.jackson，建構用 JsonMapper.builder()。 */
    @Bean
    JsonMapper jsonMapper() {
        return JsonMapper.builder()
                .addModule(new JavaTimeModule())
                .disable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS)
                .build();
    }

    /**
     * 內容協商。
     * ⚠️ 7.0 已移除 favorPathExtension —— 這是安全強化，
     *    因為 /admin/users.json 曾被用來繞過路徑安全規則。
     */
    @Override
    public void configureContentNegotiation(ContentNegotiationConfigurer configurer) {
        configurer.favorParameter(false)
                  .ignoreAcceptHeader(false)
                  .defaultContentType(org.springframework.http.MediaType.APPLICATION_JSON);
    }

    /**
     * 路徑比對。
     * ⚠️ 7.0 已移除 setUseSuffixPatternMatch / setUseTrailingSlashMatch。
     * PathPattern 是唯一選項（PathMatcher / AntPathMatcher 已棄用）。
     */
    @Override
    public void configurePathMatch(PathMatchConfigurer configurer) {
        configurer.addPathPrefix("/api",
                clazz -> clazz.isAnnotationPresent(
                        org.springframework.web.bind.annotation.RestController.class));
    }

    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        registry.addInterceptor(auditInterceptor)
                .addPathPatterns("/api/**")
                .excludePathPatterns("/api/health", "/api/metrics");
    }

    /**
     * 🔒 CORS：生產環境絕不可用 allowedOrigins("*")，
     *    尤其是搭配 allowCredentials(true) 時（規格上會被拒絕）。
     */
    @Override
    public void addCorsMappings(CorsRegistry registry) {
        registry.addMapping("/api/**")
                .allowedOrigins("https://app.enterprise.com",
                                "https://admin.enterprise.com")
                .allowedMethods("GET", "POST", "PUT", "PATCH", "DELETE")
                .allowedHeaders("Authorization", "Content-Type", "X-Request-Id")
                .exposedHeaders("X-Request-Id", "X-Total-Count")
                .allowCredentials(true)
                .maxAge(Duration.ofHours(1).toSeconds());
    }
}

package com.enterprise.tutorial.web;

import jakarta.validation.Valid;
import jakarta.validation.constraints.Max;
import jakarta.validation.constraints.Min;
import jakarta.validation.constraints.NotBlank;
import jakarta.validation.constraints.Positive;
import org.jspecify.annotations.NullMarked;
import org.springframework.http.HttpStatus;
import org.springframework.http.MediaType;
import org.springframework.http.ResponseEntity;
import org.springframework.validation.annotation.Validated;
import org.springframework.web.bind.annotation.DeleteMapping;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PatchMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestHeader;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.ResponseStatus;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.util.UriComponentsBuilder;

import java.math.BigDecimal;
import java.net.URI;
import java.util.List;

/**
 * 企業級 Controller 範本。
 *
 * 原則：
 *   ① Controller 只做「協定轉換」，不含業務邏輯
 *   ② 輸入輸出一律用 DTO（record），不直接曝露 Entity
 *   ③ 一律標註 produces / consumes，讓內容協商明確
 *   ④ 回傳 ResponseEntity 以精確控制狀態碼與標頭
 *   ⑤ @Validated 在類別上，才能驗證方法參數（非 @RequestBody 的）
 */
@NullMarked
@Validated
@RestController
@RequestMapping(value = "/orders", produces = MediaType.APPLICATION_JSON_VALUE)
public class OrderController {

    private final OrderApplicationService service;

    public OrderController(OrderApplicationService service) {
        this.service = service;
    }

    @GetMapping("/{orderId}")
    public OrderResponse getOne(@PathVariable String orderId) {
        return service.findById(orderId);
    }

    /** 分頁查詢：參數層級驗證需要類別上有 @Validated。 */
    @GetMapping
    public PagedResponse<OrderResponse> search(
            @RequestParam(required = false) String customerId,
            @RequestParam(defaultValue = "0") @Min(0) int page,
            @RequestParam(defaultValue = "20") @Min(1) @Max(100) int size,
            @RequestParam(defaultValue = "createdAt,desc") String sort) {
        return service.search(new OrderQuery(customerId, page, size, sort));
    }

    /**
     * 建立資源：
     *   - 回傳 201 Created
     *   - Location 標頭指向新資源
     *   - 冪等鍵防止重複提交（🔒 見 6.10）
     */
    @PostMapping(consumes = MediaType.APPLICATION_JSON_VALUE)
    public ResponseEntity<OrderResponse> create(
            @Valid @RequestBody CreateOrderRequest request,
            @RequestHeader("Idempotency-Key") @NotBlank String idempotencyKey,
            UriComponentsBuilder uriBuilder) {

        OrderResponse created = service.create(request, idempotencyKey);
        URI location = uriBuilder.path("/orders/{id}")
                .buildAndExpand(created.orderId())
                .toUri();
        return ResponseEntity.created(location).body(created);
    }

    /** 部分更新用 PATCH；完整替換才用 PUT。 */
    @PatchMapping(value = "/{orderId}", consumes = MediaType.APPLICATION_JSON_VALUE)
    public OrderResponse patch(@PathVariable String orderId,
                               @Valid @RequestBody PatchOrderRequest request) {
        return service.patch(orderId, request);
    }

    /** 刪除成功回 204，不回傳內容。 */
    @DeleteMapping("/{orderId}")
    @ResponseStatus(HttpStatus.NO_CONTENT)
    public void delete(@PathVariable String orderId) {
        service.cancel(orderId);
    }
}

/** DTO 用 record：不可變、自動 equals/hashCode、Jackson 3.x 原生支援。 */
record CreateOrderRequest(
        @NotBlank String customerId,
        @Valid List<OrderLineRequest> lines) {
}

record OrderLineRequest(
        @NotBlank String sku,
        @Positive int quantity,
        @Positive BigDecimal unitPrice) {
}

record PatchOrderRequest(String shippingAddress, String note) {
}

record OrderResponse(String orderId, String customerId,
                     BigDecimal total, String status) {
}

record OrderQuery(String customerId, int page, int size, String sort) {
}

record PagedResponse<T>(List<T> content, int page, int size, long totalElements) {
}

package com.enterprise.tutorial.web;

import org.jspecify.annotations.NullMarked;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.http.HttpHeaders;
import org.springframework.http.HttpStatus;
import org.springframework.http.HttpStatusCode;
import org.springframework.http.ProblemDetail;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.MethodArgumentNotValidException;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestControllerAdvice;
import org.springframework.web.context.request.WebRequest;
import org.springframework.web.servlet.mvc.method.annotation.ResponseEntityExceptionHandler;

import java.net.URI;
import java.time.Instant;
import java.util.LinkedHashMap;
import java.util.Map;
import java.util.UUID;

/**
 * 全域例外處理。
 *
 * 繼承 ResponseEntityExceptionHandler 可接管 Spring MVC 內建例外
 * （400 / 404 / 405 / 415 等），統一輸出 ProblemDetail 格式。
 *
 * 🔒 安全原則：對外訊息「有用但不洩密」，詳細技術資訊只寫日誌。
 */
@NullMarked
@RestControllerAdvice
public class GlobalExceptionHandler extends ResponseEntityExceptionHandler {

    private static final Logger log = LoggerFactory.getLogger(GlobalExceptionHandler.class);
    private static final URI BASE = URI.create("https://api.enterprise.com/problems/");

    /** 業務例外：422 Unprocessable Entity。 */
    @ExceptionHandler(BusinessException.class)
    public ProblemDetail handleBusiness(BusinessException ex) {
        ProblemDetail problem = ProblemDetail.forStatusAndDetail(
                HttpStatus.UNPROCESSABLE_ENTITY, ex.getMessage());
        problem.setType(BASE.resolve(ex.errorCode().toLowerCase()));
        problem.setTitle("業務規則不符");
        problem.setProperty("errorCode", ex.errorCode());
        problem.setProperty("timestamp", Instant.now());
        return problem;
    }

    /** 找不到資源：404。 */
    @ExceptionHandler(ResourceNotFoundException.class)
    public ProblemDetail handleNotFound(ResourceNotFoundException ex) {
        ProblemDetail problem = ProblemDetail.forStatusAndDetail(
                HttpStatus.NOT_FOUND, ex.getMessage());
        problem.setType(BASE.resolve("resource-not-found"));
        problem.setTitle("資源不存在");
        return problem;
    }

    /** 覆寫內建的驗證例外處理，加入欄位層級的錯誤明細。 */
    @Override
    protected ResponseEntity<Object> handleMethodArgumentNotValid(
            MethodArgumentNotValidException ex,
            HttpHeaders headers,
            HttpStatusCode status,
            WebRequest request) {

        Map<String, String> fieldErrors = new LinkedHashMap<>();
        ex.getBindingResult().getFieldErrors().forEach(
                fe -> fieldErrors.put(fe.getField(), fe.getDefaultMessage()));

        ProblemDetail problem = ProblemDetail.forStatus(HttpStatus.BAD_REQUEST);
        problem.setType(BASE.resolve("validation-failed"));
        problem.setTitle("輸入驗證失敗");
        problem.setDetail("請求中有 %d 個欄位不符合規則".formatted(fieldErrors.size()));
        problem.setProperty("fieldErrors", fieldErrors);
        return ResponseEntity.badRequest().body(problem);
    }

    /**
     * 兜底處理：未預期的例外。
     * 🔒 關鍵：對外只給 traceId，絕不回傳 stack trace 或內部訊息。
     */
    @ExceptionHandler(Exception.class)
    public ProblemDetail handleUnexpected(Exception ex) {
        String traceId = UUID.randomUUID().toString();
        log.error("未預期的例外 traceId={}", traceId, ex);

        ProblemDetail problem = ProblemDetail.forStatusAndDetail(
                HttpStatus.INTERNAL_SERVER_ERROR,
                "系統發生錯誤，請聯繫客服並提供追蹤碼");
        problem.setType(BASE.resolve("internal-error"));
        problem.setTitle("系統錯誤");
        problem.setProperty("traceId", traceId);
        return problem;
    }
}

class BusinessException extends RuntimeException {
    private final String errorCode;

    BusinessException(String errorCode, String message) {
        super(message);
        this.errorCode = errorCode;
    }

    String errorCode() {
        return errorCode;
    }
}

class ResourceNotFoundException extends RuntimeException {
    ResourceNotFoundException(String message) {
        super(message);
    }
}

{
  "type": "https://api.enterprise.com/problems/validation-failed",
  "title": "輸入驗證失敗",
  "status": 400,
  "detail": "請求中有 2 個欄位不符合規則",
  "instance": "/api/orders",
  "fieldErrors": {
    "customerId": "不得為空白",
    "lines[0].quantity": "必須是正數"
  }
}

package com.enterprise.tutorial.web;

import jakarta.servlet.FilterChain;
import jakarta.servlet.ServletException;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import org.jspecify.annotations.Nullable;
import org.slf4j.MDC;
import org.springframework.core.Ordered;
import org.springframework.core.annotation.Order;
import org.springframework.stereotype.Component;
import org.springframework.web.filter.OncePerRequestFilter;
import org.springframework.web.method.HandlerMethod;
import org.springframework.web.servlet.HandlerInterceptor;

import java.io.IOException;
import java.util.UUID;

/**
 * Filter：Servlet 層級，最早執行、最晚結束。
 * 適合：關聯 ID、編碼、壓縮、CORS、認證。
 * ⚠️ 此時還不知道會由哪個 Controller 處理。
 */
@Component
@Order(Ordered.HIGHEST_PRECEDENCE + 10)
public class RequestIdFilter extends OncePerRequestFilter {

    private static final String HEADER = "X-Request-Id";
    private static final String MDC_KEY = "requestId";

    @Override
    protected void doFilterInternal(HttpServletRequest request,
                                    HttpServletResponse response,
                                    FilterChain chain)
            throws ServletException, IOException {

        String requestId = request.getHeader(HEADER);
        // 🔒 不信任外部輸入：長度與字元集都要驗證，避免 log injection
        if (requestId == null || !requestId.matches("[A-Za-z0-9-]{1,64}")) {
            requestId = UUID.randomUUID().toString();
        }

        MDC.put(MDC_KEY, requestId);
        response.setHeader(HEADER, requestId);
        try {
            chain.doFilter(request, response);
        } finally {
            MDC.remove(MDC_KEY);   // ⚠️ 一定要清除，否則執行緒池會污染下一個請求
        }
    }
}

/**
 * Interceptor：Spring MVC 層級，在 DispatcherServlet 內部執行。
 * 適合：需要知道「哪個 Controller 方法」的邏輯，例如註解驅動的稽核。
 */
@Component
public class AuditInterceptor implements HandlerInterceptor {

    @Override
    public boolean preHandle(HttpServletRequest request,
                             HttpServletResponse response,
                             Object handler) {
        if (handler instanceof HandlerMethod hm) {
            // ✅ Interceptor 拿得到 HandlerMethod，Filter 拿不到
            Audited audited = hm.getMethodAnnotation(Audited.class);
            if (audited != null) {
                request.setAttribute("auditEvent", audited.value());
            }
        }
        return true;
    }

    @Override
    public void afterCompletion(HttpServletRequest request,
                                HttpServletResponse response,
                                Object handler,
                                @Nullable Exception ex) {
        // 等同 finally，即使拋例外也會執行
    }
}

package com.enterprise.tutorial.web;

import jakarta.validation.constraints.NotNull;
import org.springframework.core.io.InputStreamResource;
import org.springframework.core.io.Resource;
import org.springframework.http.ContentDisposition;
import org.springframework.http.HttpHeaders;
import org.springframework.http.MediaType;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestPart;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.multipart.MultipartFile;

import java.nio.charset.StandardCharsets;
import java.util.Set;

@RestController
@RequestMapping("/documents")
public class DocumentController {

    /** 🔒 白名單：絕不可用黑名單，也不可信任 Content-Type 標頭。 */
    private static final Set<String> ALLOWED_EXTENSIONS =
            Set.of("pdf", "png", "jpg", "jpeg", "docx", "xlsx");
    private static final long MAX_SIZE_BYTES = 10L * 1024 * 1024;

    private final DocumentStorageService storage;

    public DocumentController(DocumentStorageService storage) {
        this.storage = storage;
    }

    @PostMapping(consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
    public ResponseEntity<UploadResponse> upload(
            @RequestPart("file") @NotNull MultipartFile file,
            @RequestPart("metadata") DocumentMetadata metadata) {

        // 🔒 ① 大小檢查
        if (file.getSize() > MAX_SIZE_BYTES) {
            throw new BusinessException("FILE_TOO_LARGE", "檔案不得超過 10 MB");
        }

        // 🔒 ② 副檔名白名單（原始檔名可能含路徑穿越字元，必須淨化）
        String original = file.getOriginalFilename();
        if (original == null || original.contains("..") || original.contains("/")
                || original.contains("\\")) {
            throw new BusinessException("INVALID_FILENAME", "檔名不合法");
        }
        String ext = original.substring(original.lastIndexOf('.') + 1).toLowerCase();
        if (!ALLOWED_EXTENSIONS.contains(ext)) {
            throw new BusinessException("UNSUPPORTED_TYPE", "不支援的檔案類型");
        }

        // 🔒 ③ 用系統產生的檔名儲存，不使用使用者提供的檔名
        String storedId = storage.store(file, metadata, ext);
        return ResponseEntity.ok(new UploadResponse(storedId, file.getSize()));
    }

    /**
     * 下載：用 Resource 串流，避免把整個檔案讀進記憶體。
     * ⚠️ 大檔案用 byte[] 回傳會直接把堆積打爆。
     */
    @GetMapping("/{documentId}")
    public ResponseEntity<Resource> download(@PathVariable String documentId) {
        StoredDocument doc = storage.load(documentId);

        // 🔒 Content-Disposition 用 ContentDisposition builder 正確編碼檔名，
        //    避免標頭注入（檔名含 \r\n 或 " 時）
        ContentDisposition disposition = ContentDisposition.attachment()
                .filename(doc.displayName(), StandardCharsets.UTF_8)
                .build();

        return ResponseEntity.ok()
                .header(HttpHeaders.CONTENT_DISPOSITION, disposition.toString())
                .contentType(MediaType.APPLICATION_OCTET_STREAM)
                .contentLength(doc.size())
                .body(new InputStreamResource(doc.openStream()));
    }
}

record DocumentMetadata(String category, String description) {
}

record UploadResponse(String documentId, long size) {
}

# ① 找出使用已移除路徑選項的檔案（升級必修）
Get-ChildItem -Recurse -Include *.java |
    Select-String -Pattern 'setUseSuffixPatternMatch|setUseTrailingSlashMatch|favorPathExtension|setUseRegisteredSuffixPatternMatch|matchOptionalTrailingSeparator'

# ② 找出 Jackson 2.x 的 databind / core 匯入（註解套件不用改）
Get-ChildItem -Recurse -Include *.java |
    Select-String -Pattern 'com\.fasterxml\.jackson\.(databind|core|datatype)'

# ③ 找出使用 Jackson2 轉換器與 Builder
Get-ChildItem -Recurse -Include *.java |
    Select-String -Pattern 'MappingJackson2HttpMessageConverter|Jackson2ObjectMapperBuilder'

# ④ 找出 XML MVC namespace
Get-ChildItem -Recurse -Include *.xml | Select-String -Pattern '<mvc:'

# ⑤ 找出使用 HttpHeaders 當作 MultiValueMap 的地方
Get-ChildItem -Recurse -Include *.java |
    Select-String -Pattern 'MultiValueMap<String,\s*String>\s+\w+\s*=\s*.*[Hh]eaders'

# ⑥ 找出 Undertow 相依
Get-ChildItem -Recurse -Include pom.xml,*.gradle | Select-String -Pattern 'undertow'

# ⑦ 找出已棄用的 View 類別
Get-ChildItem -Recurse -Include *.java |
    Select-String -Pattern 'servlet\.view\.(document|feed)'

┌────────────────────────────────────────────────────────────────────┐
│  ① 你需要「背壓」或「串流」嗎？                                       │
│     （SSE、WebSocket 串流、大量資料分批推送、Kafka 消費）              │
│         │是                              │否                        │
│         ▼                                ▼                         │
│    ✅ WebFlux                    ② 你的併發需求 > 10k 連線嗎？        │
│    （不可取代的能力）                     │是            │否           │
│                                          ▼              ▼          │
│                          ③ 有 Java 21+ 嗎？        ✅ Spring MVC     │
│                             │是         │否        （最簡單）        │
│                             ▼           ▼                          │
│                    ✅ MVC + 虛擬執行緒  ④ 團隊有反應式經驗?           │
│                    （成本最低，                │是      │否           │
│                      建議首選）                ▼        ▼            │
│                                          ✅ WebFlux  ⚠️ 先升 JDK     │
└────────────────────────────────────────────────────────────────────┘

┌──────────────────────────────────────────────────────────────────┐
│  Publisher<T>                                                    │
│    void subscribe(Subscriber<? super T> s)                       │
│    ↑ Mono<T> 與 Flux<T> 都是它的實作                               │
├──────────────────────────────────────────────────────────────────┤
│  Subscriber<T>                                                   │
│    void onSubscribe(Subscription s)   ← 拿到 Subscription 才能要資料│
│    void onNext(T item)                ← 收到一個元素               │
│    void onError(Throwable t)          ← 終止（錯誤）               │
│    void onComplete()                  ← 終止（正常）               │
├──────────────────────────────────────────────────────────────────┤
│  Subscription                                                    │
│    void request(long n)   ⭐ 這就是「背壓」：我現在只能處理 n 個      │
│    void cancel()                                                 │
├──────────────────────────────────────────────────────────────────┤
│  Processor<T,R> extends Subscriber<T>, Publisher<R>              │
└──────────────────────────────────────────────────────────────────┘

【背壓的實際運作】
   Publisher                              Subscriber
       │                                       │
       │◀────────── request(10) ───────────────┤  「我要 10 筆」
       │─────────── onNext(1) ────────────────▶│
       │─────────── onNext(2) ────────────────▶│
       │              ...                      │
       │─────────── onNext(10) ───────────────▶│
       │                                       │  處理中...
       │◀────────── request(5) ────────────────┤  「再給我 5 筆」
       │─────────── onNext(11) ───────────────▶│

   ⭐ 關鍵：資料的流動速度由「消費者」決定，不是生產者。
      這是 WebFlux 相較於「一般非同步」的根本差異。

// 冷 Publisher：每次 subscribe 都重新執行
Flux<String> cold = Flux.defer(() -> Flux.just(callApi()));
cold.subscribe();   // 呼叫 API 一次
cold.subscribe();   // 又呼叫 API 一次！

// 熱 Publisher：所有 subscriber 共享同一個資料流
Flux<String> hot = cold.share();
hot.subscribe();    // 呼叫 API
hot.subscribe();    // 共享上面的結果

// ⚠️ 最常見的錯誤：忘記 Publisher 是冷的
Mono<Order> order = orderRepository.findById(id);
order.subscribe(this::sendEmail);      // 查一次 DB
order.subscribe(this::updateCache);    // 又查一次 DB！
// ✅ 正確：用 cache() 或把邏輯串在同一條鏈上

【WebFlux 的執行緒模型】

  Netty Event Loop（數量 = CPU 核心數，例如 8 個）
  ┌──────────────────────────────────────────────────────────┐
  │  reactor-http-nio-1                                      │
  │  reactor-http-nio-2                                      │
  │  ...                                                     │
  │  reactor-http-nio-8                                      │
  └──────────────────────────────────────────────────────────┘
       │
       │  ⚠️ 這 8 個執行緒要服務「全部」的請求。
       │     任何一個被阻塞 1 秒，就等於 1/8 的服務能力消失 1 秒。
       │
       ▼
  ┌──────────────────────────────────────────────────────────┐
  │  ❌ 錯誤：直接在事件迴圈上做阻塞呼叫                          │
  │     jdbcTemplate.query(...)   ← 阻塞 50ms                 │
  │     Thread.sleep(100)         ← 阻塞 100ms                │
  │     restTemplate.getForObject(...)  ← 阻塞               │
  │                                                          │
  │  ✅ 正確：用 subscribeOn(boundedElastic) 隔離              │
  │     Mono.fromCallable(() -> jdbcTemplate.query(...))     │
  │         .subscribeOn(Schedulers.boundedElastic())        │
  │                                                          │
  │  ✅ 更好：改用真正非阻塞的 R2DBC / WebClient               │
  └──────────────────────────────────────────────────────────┘

╔════════════════════════════════════════════════════════════════════════════╗
║           Spring MVC（阻塞）vs WebFlux（非阻塞）架構對照                       ║
╠════════════════════════════════════════════════════════════════════════════╣
║                                                                            ║
║  【Spring MVC + 平台執行緒】                                                 ║
║                                                                            ║
║   1000 個併發請求                                                            ║
║        │                                                                   ║
║        ▼                                                                   ║
║   ┌────────────────────────────────────────────────────┐                   ║
║   │  Tomcat Thread Pool（預設 200）                     │                   ║
║   │  ████████████████████████ 200 個執行緒全部忙碌       │                   ║
║   │  剩下 800 個請求在佇列中排隊 ⏳                       │                   ║
║   └────────────────┬───────────────────────────────────┘                   ║
║                    │ 每個執行緒：                                            ║
║                    │   ① 呼叫 DB（等待 30ms，執行緒閒置但被佔用）             ║
║                    │   ② 呼叫下游 API（等待 80ms，同上）                     ║
║                    │   ③ 組裝回應（1ms 真正在做事）                          ║
║                    │                                                       ║
║                    │  ⚠️ 111ms 中有 110ms 執行緒是「閒著但被佔用」             ║
║                    │  ⚠️ 記憶體：200 × ~1MB 堆疊 = 200 MB                    ║
║                    ▼                                                       ║
║                 回應                                                        ║
║                                                                            ║
║  ──────────────────────────────────────────────────────────────────────    ║
║                                                                            ║
║  【Spring MVC + 虛擬執行緒（Java 21+）】⭐ 折衷方案                           ║
║                                                                            ║
║   1000 個併發請求                                                            ║
║        │                                                                   ║
║        ▼                                                                   ║
║   ┌────────────────────────────────────────────────────┐                   ║
║   │  Virtual Thread Executor（1000 個虛擬執行緒）        │                   ║
║   │  掛載在少數 Carrier Thread（= CPU 核心數）之上        │                   ║
║   │                                                    │                   ║
║   │  阻塞時，虛擬執行緒「卸載」，Carrier 去服務其他請求     │                   ║
║   └────────────────┬───────────────────────────────────┘                   ║
║                    │  ✅ 程式碼仍是同步阻塞風格（好懂、好除錯）                 ║
║                    │  ✅ 記憶體：虛擬執行緒堆疊在堆積上，數 KB 起               ║
║                    │  ⚠️ 沒有背壓機制                                        ║
║                    │  ⚠️ synchronized / 原生方法內阻塞會 pinning              ║
║                    ▼                                                       ║
║                 回應                                                        ║
║                                                                            ║
║  ──────────────────────────────────────────────────────────────────────    ║
║                                                                            ║
║  【Spring WebFlux + Netty】                                                 ║
║                                                                            ║
║   1000 個併發請求                                                            ║
║        │                                                                   ║
║        ▼                                                                   ║
║   ┌────────────────────────────────────────────────────┐                   ║
║   │  Netty Event Loop（8 個執行緒，= CPU 核心數）        │                   ║
║   │  ████ 事件驅動，執行緒永不等待 I/O                    │                   ║
║   └────────────────┬───────────────────────────────────┘                   ║
║                    │                                                       ║
║        ┌───────────▼────────────┐                                          ║
║        │  DispatcherHandler      │                                         ║
║        │    ├─ HandlerMapping    │                                         ║
║        │    ├─ HandlerAdapter    │                                         ║
║        │    └─ ResultHandler     │                                         ║
║        └───────────┬────────────┘                                          ║
║                    │  回傳 Mono/Flux（此時「什麼都還沒發生」）                 ║
║                    ▼                                                       ║
║        ┌────────────────────────────────────────────┐                      ║
║        │  Reactor 操作子鏈（宣告式）                   │                      ║
║        │                                            │                      ║
║        │  R2DBC 查詢 ──▶ map ──▶ WebClient 呼叫      │                      ║
║        │       │                      │             │                      ║
║        │       └─ 非阻塞 ─────────────┘             │                      ║
║        │                                            │                      ║
║        │  ⭐ 背壓：下游用 request(n) 控制上游速度      │                      ║
║        └────────────────────┬───────────────────────┘                      ║
║                             ▼                                              ║
║                     訂閱時才真正執行                                          ║
║                             │                                              ║
║                             ▼                                              ║
║                   回應（可為串流：SSE / NDJSON）                              ║
║                                                                            ║
║  ✅ 記憶體：8 × 1MB = 8 MB                                                   ║
║  ✅ 背壓：完整支援                                                           ║
║  ❌ 一個阻塞呼叫 = 1/8 服務能力消失                                           ║
╚════════════════════════════════════════════════════════════════════════════╝

package com.enterprise.tutorial.reactive;

import org.jspecify.annotations.NullMarked;
import org.springframework.http.MediaType;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
import reactor.core.publisher.Flux;
import reactor.core.publisher.Mono;

import java.time.Duration;

/**
 * WebFlux 的註解式寫法與 MVC 幾乎相同，
 * 差別只在回傳型別是 Mono / Flux。
 */
@NullMarked
@RestController
@RequestMapping("/reactive/orders")
public class ReactiveOrderController {

    private final ReactiveOrderService service;

    public ReactiveOrderController(ReactiveOrderService service) {
        this.service = service;
    }

    /** 單筆查詢：Mono。找不到時用 switchIfEmpty 轉為 404。 */
    @GetMapping("/{orderId}")
    public Mono<ResponseEntity<OrderView>> getOne(@PathVariable String orderId) {
        return service.findById(orderId)
                .map(ResponseEntity::ok)
                .defaultIfEmpty(ResponseEntity.notFound().build());
    }

    /** 清單查詢：Flux。框架會自動聚合成 JSON 陣列。 */
    @GetMapping
    public Flux<OrderView> list(@RequestParam(defaultValue = "100") int limit) {
        return service.findAll().take(limit);
    }

    /**
     * ⭐ 串流回應（Server-Sent Events）——這是 WebFlux 不可取代的能力。
     * 客戶端會「邊收邊處理」，不需要等待全部資料。
     */
    @GetMapping(value = "/stream", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
    public Flux<OrderEvent> streamEvents() {
        return service.orderEventStream()
                // 心跳：避免中介的代理伺服器因閒置而斷線
                .mergeWith(Flux.interval(Duration.ofSeconds(15))
                        .map(tick -> OrderEvent.heartbeat()))
                .onErrorResume(ex -> Flux.just(OrderEvent.error(ex.getMessage())));
    }

    /** NDJSON 串流：適合大量資料匯出，前端可逐行解析。 */
    @GetMapping(value = "/export", produces = MediaType.APPLICATION_NDJSON_VALUE)
    public Flux<OrderView> export() {
        return service.findAll()
                // limitRate：明確告訴上游一次只取 500 筆，避免記憶體堆積
                .limitRate(500);
    }

    /** 建立：@RequestBody 也可以是 Mono。 */
    @PostMapping
    public Mono<ResponseEntity<OrderView>> create(@RequestBody Mono<CreateOrder> request) {
        return request.flatMap(service::create)
                .map(created -> ResponseEntity
                        .created(java.net.URI.create("/reactive/orders/" + created.id()))
                        .body(created));
    }
}

record OrderView(String id, String customerId, String status) {
}

record CreateOrder(String customerId) {
}

record OrderEvent(String type, String payload) {
    static OrderEvent heartbeat() {
        return new OrderEvent("heartbeat", "");
    }

    static OrderEvent error(String message) {
        return new OrderEvent("error", message);
    }
}

package com.enterprise.tutorial.reactive;

import org.jspecify.annotations.NullMarked;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.MediaType;
import org.springframework.stereotype.Component;
import org.springframework.web.reactive.function.server.RouterFunction;
import org.springframework.web.reactive.function.server.ServerRequest;
import org.springframework.web.reactive.function.server.ServerResponse;
import reactor.core.publisher.Mono;

import static org.springframework.web.reactive.function.server.RequestPredicates.accept;
import static org.springframework.web.reactive.function.server.RouterFunctions.route;

/**
 * 函式式路由：
 *   ✅ 路由規則集中可見（不用翻遍所有 Controller）
 *   ✅ 可組合、可測試（Handler 就是普通類別）
 *   ✅ 對 AOT / Native Image 更友善（無需反射掃描註解）
 *   ⚠️ 沒有註解式的自動 OpenAPI 文件產生
 */
@NullMarked
@Configuration(proxyBeanMethods = false)
public class OrderRoutes {

    @Bean
    RouterFunction<ServerResponse> orderRouter(OrderHandler handler) {
        return route()
                .path("/fn/orders", builder -> builder
                        .GET("/{id}", accept(MediaType.APPLICATION_JSON), handler::getOne)
                        .GET("", accept(MediaType.APPLICATION_JSON), handler::list)
                        .GET("/stream", accept(MediaType.TEXT_EVENT_STREAM), handler::stream)
                        .POST("", handler::create)
                        .DELETE("/{id}", handler::cancel))
                // 集中式的錯誤處理
                .onError(OrderNotFoundException.class,
                        (ex, req) -> ServerResponse.notFound().build())
                .onError(IllegalArgumentException.class,
                        (ex, req) -> ServerResponse.badRequest()
                                .bodyValue(new ErrorBody("INVALID_INPUT", ex.getMessage())))
                .build();
    }
}

@NullMarked
@Component
class OrderHandler {

    private final ReactiveOrderService service;

    OrderHandler(ReactiveOrderService service) {
        this.service = service;
    }

    Mono<ServerResponse> getOne(ServerRequest request) {
        String id = request.pathVariable("id");
        return service.findById(id)
                .flatMap(order -> ServerResponse.ok().bodyValue(order))
                .switchIfEmpty(ServerResponse.notFound().build());
    }

    Mono<ServerResponse> list(ServerRequest request) {
        int limit = request.queryParam("limit").map(Integer::parseInt).orElse(100);
        return ServerResponse.ok()
                .body(service.findAll().take(limit), OrderView.class);
    }

    Mono<ServerResponse> stream(ServerRequest request) {
        return ServerResponse.ok()
                .contentType(MediaType.TEXT_EVENT_STREAM)
                .body(service.orderEventStream(), OrderEvent.class);
    }

    Mono<ServerResponse> create(ServerRequest request) {
        return request.bodyToMono(CreateOrder.class)
                .flatMap(service::create)
                .flatMap(created -> ServerResponse
                        .created(java.net.URI.create("/fn/orders/" + created.id()))
                        .bodyValue(created));
    }

    Mono<ServerResponse> cancel(ServerRequest request) {
        return service.cancel(request.pathVariable("id"))
                .then(ServerResponse.noContent().build());
    }
}

record ErrorBody(String code, String message) {
}

class OrderNotFoundException extends RuntimeException {
}

package com.enterprise.tutorial.reactive;

import org.jspecify.annotations.NullMarked;
import org.springframework.stereotype.Service;
import reactor.core.publisher.Flux;
import reactor.core.publisher.Mono;
import reactor.core.scheduler.Schedulers;
import reactor.util.retry.Retry;

import java.time.Duration;
import java.util.List;

@NullMarked
@Service
public class OrderAggregationService {

    private final CustomerClient customerClient;
    private final InventoryClient inventoryClient;
    private final PricingClient pricingClient;
    private final LegacyJdbcRepository legacyRepository;

    public OrderAggregationService(CustomerClient customerClient,
                                   InventoryClient inventoryClient,
                                   PricingClient pricingClient,
                                   LegacyJdbcRepository legacyRepository) {
        this.customerClient = customerClient;
        this.inventoryClient = inventoryClient;
        this.pricingClient = pricingClient;
        this.legacyRepository = legacyRepository;
    }

    /**
     * ⭐ 並行呼叫 3 個下游服務並合併。
     * 三個呼叫「同時」進行，總耗時 ≈ 最慢的那個，而非三者相加。
     * 這種宣告式組合是 WebFlux 相較於手寫 CompletableFuture 的優勢。
     */
    public Mono<OrderDetail> loadDetail(String orderId, String customerId, String sku) {
        return Mono.zip(
                        customerClient.findById(customerId)
                                .timeout(Duration.ofMillis(300))
                                .onErrorResume(ex -> Mono.just(Customer.unknown())),
                        inventoryClient.checkStock(sku)
                                .timeout(Duration.ofMillis(200))
                                .onErrorReturn(StockInfo.unavailable()),
                        pricingClient.quote(sku)
                                .timeout(Duration.ofMillis(500))
                                .retryWhen(Retry.backoff(3, Duration.ofMillis(100))
                                        .maxBackoff(Duration.ofSeconds(2))
                                        .jitter(0.5)))
                .map(tuple -> new OrderDetail(
                        orderId, tuple.getT1(), tuple.getT2(), tuple.getT3()))
                // checkpoint：在 stack trace 中標記位置，大幅改善除錯體驗
                .checkpoint("loadDetail(orderId=%s)".formatted(orderId));
    }

    /**
     * flatMap vs concatMap vs flatMapSequential：
     *   flatMap           —— 並行執行，結果順序「不保證」
     *   concatMap         —— 依序執行（前一個完成才開始下一個），順序保證
     *   flatMapSequential —— 並行執行，但結果依原順序輸出
     */
    public Flux<StockInfo> checkStockInParallel(List<String> skus) {
        return Flux.fromIterable(skus)
                // 第二個參數是「併發上限」，防止一次打爆下游
                .flatMap(inventoryClient::checkStock, 8)
                .onErrorContinue((ex, item) ->
                        // 單筆失敗不中斷整條串流
                        System.err.println("查詢庫存失敗: " + item));
    }

    /**
     * ⚠️ 不得已必須呼叫阻塞式 API（例如舊有的 JDBC Repository）時的正確做法。
     * 關鍵：subscribeOn(boundedElastic) 把阻塞呼叫隔離到專用執行緒池，
     *       絕不可讓它跑在 Netty 事件迴圈上。
     */
    public Mono<LegacyRecord> loadFromLegacy(String id) {
        return Mono.fromCallable(() -> legacyRepository.findById(id))
                .subscribeOn(Schedulers.boundedElastic())
                .timeout(Duration.ofSeconds(3))
                .doOnError(ex -> System.err.println("舊系統查詢失敗: " + ex.getMessage()));
    }

    /**
     * ⭐ 背壓的實際運用：處理無限串流時控制速率。
     */
    public Flux<ProcessedEvent> processEventStream(Flux<RawEvent> source) {
        return source
                // 一次只向上游要 100 筆，處理完 75% 才要下一批
                .limitRate(100, 75)
                // 若下游來不及，最多緩衝 1000 筆，超過就丟棄最舊的
                .onBackpressureBuffer(1000,
                        dropped -> System.err.println("背壓丟棄: " + dropped),
                        reactor.core.publisher.BufferOverflowStrategy.DROP_OLDEST)
                .flatMap(this::process, 16)
                .checkpoint("processEventStream");
    }

    private Mono<ProcessedEvent> process(RawEvent event) {
        return Mono.just(new ProcessedEvent(event.id()));
    }
}

record OrderDetail(String orderId, Customer customer, StockInfo stock, Quote quote) {
}

record Customer(String id, String name) {
    static Customer unknown() {
        return new Customer("unknown", "未知客戶");
    }
}

record StockInfo(String sku, int available) {
    static StockInfo unavailable() {
        return new StockInfo("", 0);
    }
}

record Quote(String sku, java.math.BigDecimal price) {
}

record LegacyRecord(String id, String data) {
}

record RawEvent(String id) {
}

record ProcessedEvent(String id) {
}

package com.enterprise.tutorial.reactive;

import org.jspecify.annotations.NullMarked;
import org.reactivestreams.Publisher;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.slf4j.MDC;
import org.springframework.core.Ordered;
import org.springframework.stereotype.Component;
import org.springframework.web.server.ServerWebExchange;
import org.springframework.web.server.WebFilter;
import org.springframework.web.server.WebFilterChain;
import reactor.core.publisher.Mono;
import reactor.util.context.Context;

import java.util.UUID;

/**
 * ⚠️ WebFlux 中 ThreadLocal 完全不可靠：
 *    一條反應式鏈可能在多個不同的執行緒上執行，
 *    MDC / SecurityContextHolder / TransactionSynchronizationManager
 *    這些以 ThreadLocal 為基礎的機制都會失效。
 *
 * ✅ 正解：Reactor Context —— 它「隨著訂閱鏈傳遞」，與執行緒無關。
 */
@NullMarked
@Component
public class RequestContextWebFilter implements WebFilter, Ordered {

    static final String REQUEST_ID = "requestId";

    @Override
    public Mono<Void> filter(ServerWebExchange exchange, WebFilterChain chain) {
        String requestId = exchange.getRequest().getHeaders().getFirst("X-Request-Id");
        // 🔒 不信任外部輸入
        if (requestId == null || !requestId.matches("[A-Za-z0-9-]{1,64}")) {
            requestId = UUID.randomUUID().toString();
        }
        exchange.getResponse().getHeaders().set("X-Request-Id", requestId);

        return chain.filter(exchange)
                // ⭐ 寫入 Context —— 整條鏈的下游都能讀到
                .contextWrite(Context.of(REQUEST_ID, requestId));
    }

    @Override
    public int getOrder() {
        return Ordered.HIGHEST_PRECEDENCE;
    }
}

@NullMarked
@Component
class ContextAwareService {

    private static final Logger log = LoggerFactory.getLogger(ContextAwareService.class);

    Mono<String> doWork(String input) {
        return Mono.deferContextual(ctx -> {
            // ⭐ 從 Context 讀取，而非 ThreadLocal
            String requestId = ctx.getOrDefault(RequestContextWebFilter.REQUEST_ID, "unknown");
            return Mono.just(input)
                    .doOnNext(v -> logWithMdc(requestId, "處理中: " + v))
                    .map(String::toUpperCase);
        });
    }

    /**
     * 若一定要用 MDC（例如既有的日誌格式），
     * 必須手動在「同一個回呼內」設定與清除。
     */
    private void logWithMdc(String requestId, String message) {
        MDC.put(RequestContextWebFilter.REQUEST_ID, requestId);
        try {
            log.info(message);
        } finally {
            MDC.remove(RequestContextWebFilter.REQUEST_ID);
        }
    }
}

package com.enterprise.tutorial.reactive;

import com.google.gson.Gson;
import com.google.gson.GsonBuilder;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.codec.ServerCodecConfigurer;
import org.springframework.http.codec.gson.GsonDecoder;
import org.springframework.http.codec.gson.GsonEncoder;
import org.springframework.resilience.annotation.Retryable;
import org.springframework.stereotype.Service;
import org.springframework.web.reactive.config.WebFluxConfigurer;
import reactor.core.publisher.Mono;

/**
 * ⭐ 7.0 新增：WebFlux 的 Gson 編解碼器。
 *
 * ⚠️ 重要限制：GsonDecoder 「無法解碼 Flux」（只能 Mono）。
 *    原因是 Gson 的 API 無法做到「串流式的部分反序列化」。
 *    若你需要串流解碼，仍應使用 Jackson 3.x。
 */
@Configuration(proxyBeanMethods = false)
class GsonCodecConfig implements WebFluxConfigurer {

    @Bean
    Gson gson() {
        return new GsonBuilder()
                .serializeNulls()
                .setDateFormat("yyyy-MM-dd'T'HH:mm:ss")
                .create();
    }

    @Override
    public void configureHttpMessageCodecs(ServerCodecConfigurer configurer) {
        Gson gson = gson();
        configurer.customCodecs().register(new GsonEncoder(gson));
        configurer.customCodecs().register(new GsonDecoder(gson));
    }
}

/**
 * ⭐ 7.0：@Retryable 會自動偵測反應式回傳型別。
 *
 * 回傳 Mono / Flux 時，框架不會用「阻塞式重試」，
 * 而是套用 Reactor 的 retryWhen 操作子 —— 不佔用執行緒。
 */
@Service
class ReactiveExternalClient {

    @Retryable(maxAttempts = 3,
               delay = 100,
               multiplier = 2.0,
               maxDelay = 2000,
               jitter = 50,
               includes = java.io.IOException.class)
    Mono<String> fetch(String resourceId) {
        return Mono.fromCallable(() -> callRemote(resourceId));
    }

    private String callRemote(String id) {
        throw new UnsupportedOperationException("由實際的 WebClient 呼叫提供");
    }
}

package com.enterprise.tutorial.reactive;

import org.junit.jupiter.api.Test;
import org.springframework.http.MediaType;
import org.springframework.test.web.reactive.server.WebTestClient;
import reactor.core.publisher.Flux;
import reactor.core.publisher.Mono;
import reactor.test.StepVerifier;

import java.time.Duration;

import static org.mockito.ArgumentMatchers.anyString;
import static org.mockito.Mockito.mock;
import static org.mockito.Mockito.when;

class ReactiveOrderControllerTest {

    private final ReactiveOrderService service = mock(ReactiveOrderService.class);

    private final WebTestClient client = WebTestClient
            .bindToController(new ReactiveOrderController(service))
            .configureClient()
            .responseTimeout(Duration.ofSeconds(5))
            .build();

    @Test
    void 查詢存在的訂單應回傳200() {
        when(service.findById("O-1"))
                .thenReturn(Mono.just(new OrderView("O-1", "C-1", "PAID")));

        client.get().uri("/reactive/orders/O-1")
                .accept(MediaType.APPLICATION_JSON)
                .exchange()
                .expectStatus().isOk()
                .expectBody()
                .jsonPath("$.id").isEqualTo("O-1")
                .jsonPath("$.status").isEqualTo("PAID");
    }

    @Test
    void 查詢不存在的訂單應回傳404() {
        when(service.findById(anyString())).thenReturn(Mono.empty());

        client.get().uri("/reactive/orders/NOT-EXIST")
                .exchange()
                .expectStatus().isNotFound();
    }

    @Test
    void SSE串流應依序輸出事件() {
        when(service.orderEventStream()).thenReturn(Flux.just(
                new OrderEvent("created", "O-1"),
                new OrderEvent("paid", "O-1")));

        Flux<OrderEvent> events = client.get().uri("/reactive/orders/stream")
                .accept(MediaType.TEXT_EVENT_STREAM)
                .exchange()
                .expectStatus().isOk()
                .returnResult(OrderEvent.class)
                .getResponseBody();

        // ⭐ StepVerifier：驗證反應式串流的標準工具
        StepVerifier.create(events)
                .expectNextMatches(e -> "created".equals(e.type()))
                .expectNextMatches(e -> "paid".equals(e.type()))
                .thenCancel()
                .verify(Duration.ofSeconds(5));
    }

    @Test
    void 虛擬時間測試超時邏輯() {
        // ⭐ withVirtualTime：不用真的等 5 秒，測試瞬間完成
        StepVerifier.withVirtualTime(() ->
                        Mono.delay(Duration.ofSeconds(5)).thenReturn("done"))
                .expectSubscription()
                .expectNoEvent(Duration.ofSeconds(5))
                .expectNext("done")
                .verifyComplete();
    }
}

# ① 找出 WebFlux 模組中的阻塞式相依（最高風險）
Get-ChildItem -Recurse -Include *.java |
    Select-String -Pattern 'JdbcTemplate|EntityManager|RestTemplate|Thread\.sleep'

# ② 找出反應式鏈中的 block() 呼叫
Get-ChildItem -Recurse -Include *.java |
    Select-String -Pattern '\.block\(\)|\.blockFirst\(\)|\.blockLast\(\)'

# ③ 找出 WebFlux 中誤用 ThreadLocal / MDC / SecurityContextHolder
Get-ChildItem -Recurse -Include *.java |
    Select-String -Pattern 'ThreadLocal|MDC\.|SecurityContextHolder'

# ④ 找出沒有 timeout 的 WebClient 呼叫（需人工複核）
Get-ChildItem -Recurse -Include *.java |
    Select-String -Pattern 'webClient\.' -Context 0,6 |
    Where-Object { $_.Context.PostContext -notmatch 'timeout' }

# ⑤ 找出殘留的 ListenableFuture
Get-ChildItem -Recurse -Include *.java |
    Select-String -Pattern 'ListenableFuture'

<dependency>
    <groupId>io.projectreactor.tools</groupId>
    <artifactId>blockhound-junit-platform</artifactId>
    <version>1.0.13.RELEASE</version>
    <scope>test</scope>
</dependency>

Level 0：HTTP 當作傳輸管道
   POST /api  { "action": "getOrder", "id": "123" }
   ❌ 這是 RPC over HTTP，不是 REST

Level 1：引入資源
   POST /orders/get   { "id": "123" }
   POST /orders/create { ... }
   ⚠️ 有資源概念，但仍用 POST 做所有事

Level 2：使用 HTTP 動詞與狀態碼   ⭐ 企業實務的目標
   GET    /orders/123        → 200
   POST   /orders            → 201 + Location
   PATCH  /orders/123        → 200
   DELETE /orders/123        → 204
   ✅ 絕大多數企業 API 應該達到這一層

Level 3：HATEOAS（超媒體驅動）
   GET /orders/123 →
   { "id":"123", "status":"PENDING",
     "_links": { "cancel": {"href":"/orders/123/cancel"},
                 "pay":    {"href":"/orders/123/payment"} } }
   💡 理論上最完整，但實務上採用率低
      （前端通常已知道 API 結構，額外的 links 增加傳輸量與複雜度）
      建議：對外開放 API 或需要動態流程時才考慮

① 標頭（Header）        —— 推薦
   X-API-Version: 1.2
   ✅ URL 乾淨、快取友善、不影響資源識別

② 媒體型別參數（Media Type Parameter）—— 最符合 REST 精神
   Accept: application/json;version=1.2
   ✅ 理論最正確   ⚠️ 客戶端與工具支援度較低

③ 查詢參數（Query Parameter）
   GET /api/orders?version=1.2
   ⚠️ 會影響快取鍵，且容易與業務參數混淆

④ 路徑段（Path Segment）—— 最常見但爭議最大
   GET /api/v1/orders
   ✅ 直覺、易除錯、瀏覽器可直接測試
   ❌ 嚴格來說違反 REST（同一資源不應有多個 URI）

╔════════════════════════════════════════════════════════════════════════════╗
║                    企業級 RESTful API 分層架構                                ║
╠════════════════════════════════════════════════════════════════════════════╣
║                                                                            ║
║  ┌──────────────────────────────────────────────────────────────────┐      ║
║  │  客戶端                                                            │      ║
║  │  Web App / Mobile App / 合作夥伴系統 / 內部微服務                    │      ║
║  └────────────────────────────┬─────────────────────────────────────┘      ║
║                               │  X-API-Version: 1.2  ⭐7.0                  ║
║                               │  Authorization: Bearer ...                  ║
║                               │  Idempotency-Key: ...                       ║
║                               ▼                                            ║
║  ┌──────────────────────────────────────────────────────────────────┐      ║
║  │  API Gateway（限流 / 認證 / 路由 / TLS 終止）                       │      ║
║  └────────────────────────────┬─────────────────────────────────────┘      ║
║                               ▼                                            ║
║  ┌──────────────────────────────────────────────────────────────────┐      ║
║  │  Spring 應用                                                      │      ║
║  │                                                                   │      ║
║  │  ┌────────────────────────────────────────────────────────────┐   │      ║
║  │  │  ① API 版本解析 ⭐7.0                                        │   │      ║
║  │  │     ApiVersionResolver: Header / MediaType / Query / Path   │   │      ║
║  │  │     ApiVersionParser  : "1.2" → SemanticVersion            │   │      ║
║  │  │     支援 deprecated 標記 → 回應自動附帶棄用資訊               │   │      ║
║  │  └────────────────────────┬───────────────────────────────────┘   │      ║
║  │                           ▼                                       │      ║
║  │  ┌────────────────────────────────────────────────────────────┐   │      ║
║  │  │  ② Controller 層（協定轉換）                                 │   │      ║
║  │  │     @RestController + @RequestMapping(version = "1.2") ⭐   │   │      ║
║  │  │     • 輸入：Request DTO（record）+ Bean Validation 3.1      │   │      ║
║  │  │     • 輸出：Response DTO + ResponseEntity                  │   │      ║
║  │  │     • 錯誤：ProblemDetail（RFC 9457）                       │   │      ║
║  │  │     ⚠️ 不含業務邏輯                                          │   │      ║
║  │  └────────────────────────┬───────────────────────────────────┘   │      ║
║  │                           ▼                                       │      ║
║  │  ┌────────────────────────────────────────────────────────────┐   │      ║
║  │  │  ③ Application Service（用例編排）                           │   │      ║
║  │  │     @Transactional 交易邊界                                 │   │      ║
║  │  │     冪等性檢查（Idempotency-Key）                            │   │      ║
║  │  │     DTO ⇄ Domain 轉換                                       │   │      ║
║  │  └────────────────────────┬───────────────────────────────────┘   │      ║
║  │                           ▼                                       │      ║
║  │  ┌────────────────────────────────────────────────────────────┐   │      ║
║  │  │  ④ Domain Layer（業務規則）                                  │   │      ║
║  │  │     Entity / Value Object / Domain Service                 │   │      ║
║  │  │     ⚠️ 不依賴 Spring、不依賴 HTTP                            │   │      ║
║  │  └────────────────────────┬───────────────────────────────────┘   │      ║
║  │                           ▼                                       │      ║
║  │  ┌────────────────────────────────────────────────────────────┐   │      ║
║  │  │  ⑤ Infrastructure（技術實作）                                │   │      ║
║  │  │     Repository（JdbcClient / JPA）                          │   │      ║
║  │  │     下游 API 客戶端                                          │   │      ║
║  │  │       ├─ RestClient          ✅ 同步                        │   │      ║
║  │  │       ├─ WebClient           ✅ 反應式                      │   │      ║
║  │  │       ├─ HTTP Interface ⭐    ✅ 宣告式（強烈推薦）           │   │      ║
║  │  │       └─ RestTemplate        ⚠️ 7.0 棄用 / 7.1 @Deprecated  │   │      ║
║  │  └────────────────────────────────────────────────────────────┘   │      ║
║  └──────────────────────────────────────────────────────────────────┘      ║
║                                                                            ║
║  【橫切關注點】                                                              ║
║  OpenAPI 文件 │ 限流 │ 冪等性 │ 稽核 │ 追蹤（W3C traceparent）│ 快取（ETag）  ║
╚════════════════════════════════════════════════════════════════════════════╝

package com.enterprise.tutorial.api;

import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ApiVersionConfigurer;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

/**
 * ⭐ Spring Framework 7.0 新功能：API 版本控制。
 *
 * 過去必須自訂 RequestCondition 或用路徑前綴硬幹，
 * 7.0 把版本控制做成 HandlerMapping 的一級比對條件。
 */
@Configuration(proxyBeanMethods = false)
@EnableWebMvc
public class ApiVersionConfig implements WebMvcConfigurer {

    @Override
    public void configureApiVersioning(ApiVersionConfigurer configurer) {
        configurer
                // ① 版本從哪裡讀取（可同時註冊多種，依序嘗試）
                .useRequestHeader("X-API-Version")
                .useMediaTypeParameter(
                        org.springframework.http.MediaType.APPLICATION_JSON, "version")

                // ② 沒帶版本時的預設值（避免既有客戶端全部壞掉）
                .setDefaultVersion("1.0")

                // ③ 是否要求版本必須是「已註冊」的
                //    true  = 未知版本回 400（嚴格，推薦）
                //    false = 未知版本走預設（寬鬆）
                .setVersionRequired(false)

                // ④ 明確列出支援的版本
                .addSupportedVersions("1.0", "1.1", "2.0")

                // ⑤ ⭐ 標記已棄用的版本
                //    框架會自動在回應加上棄用相關資訊
                .setDeprecationHandler(new StandardApiDeprecationHandler()
                        .configureVersion("1.0")
                        .setDeprecationDate(java.time.ZonedDateTime.parse(
                                "2026-01-01T00:00:00Z"))
                        .setSunsetDate(java.time.ZonedDateTime.parse(
                                "2026-12-31T00:00:00Z"))
                        .setDeprecationLink(java.net.URI.create(
                                "https://api.enterprise.com/docs/migration/v1-to-v2")));
    }
}

package com.enterprise.tutorial.api;

import jakarta.validation.Valid;
import org.jspecify.annotations.NullMarked;
import org.springframework.http.MediaType;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import java.math.BigDecimal;
import java.time.Instant;
import java.util.List;

/**
 * ⭐ 7.0：version 屬性直接寫在 @RequestMapping 家族的註解上。
 *
 * 版本比對規則：
 *   version = "1.0"   → 精確比對
 *   version = "1.0+"  → 1.0 以上（含）都比對
 */
@NullMarked
@RestController
@RequestMapping(value = "/api/orders", produces = MediaType.APPLICATION_JSON_VALUE)
public class VersionedOrderController {

    private final OrderApplicationService service;

    public VersionedOrderController(OrderApplicationService service) {
        this.service = service;
    }

    // ═══════════════════════════════════════════════════════════
    // v1.0：舊版格式（已標記棄用）
    //   回應中 total 是 double、沒有幣別、狀態是英文大寫
    // ═══════════════════════════════════════════════════════════
    @GetMapping(value = "/{orderId}", version = "1.0")
    public OrderResponseV1 getOrderV1(@PathVariable String orderId) {
        Order order = service.findById(orderId);
        return new OrderResponseV1(
                order.id(),
                order.customerId(),
                order.total().doubleValue(),   // ⚠️ 舊版用 double，有精度問題
                order.status().name());
    }

    // ═══════════════════════════════════════════════════════════
    // v2.0：新版格式
    //   • total 改為結構化的 Money（修正精度問題）
    //   • 新增 createdAt / lines
    //   • status 改為小寫 kebab-case
    // ═══════════════════════════════════════════════════════════
    @GetMapping(value = "/{orderId}", version = "2.0")
    public OrderResponseV2 getOrderV2(@PathVariable String orderId) {
        Order order = service.findById(orderId);
        return new OrderResponseV2(
                order.id(),
                order.customerId(),
                new Money(order.total(), "TWD"),
                order.status().name().toLowerCase().replace('_', '-'),
                order.createdAt(),
                order.lines().stream()
                        .map(l -> new OrderLineV2(l.sku(), l.quantity(),
                                new Money(l.unitPrice(), "TWD")))
                        .toList());
    }

    /**
     * 「1.1 以上」都套用此版本。
     * 適合用於「新增後就沒再改過」的端點，避免重複宣告。
     */
    @GetMapping(value = "/{orderId}/timeline", version = "1.1+")
    public List<TimelineEntry> timeline(@PathVariable String orderId) {
        return service.timeline(orderId);
    }

    /** 未標註 version → 適用所有版本。 */
    @PostMapping
    public ResponseEntity<OrderResponseV2> create(
            @Valid @RequestBody CreateOrderRequest request) {
        Order created = service.create(request);
        return ResponseEntity
                .created(java.net.URI.create("/api/orders/" + created.id()))
                .body(toV2(created));
    }

    private OrderResponseV2 toV2(Order order) {
        return new OrderResponseV2(order.id(), order.customerId(),
                new Money(order.total(), "TWD"),
                order.status().name().toLowerCase(),
                order.createdAt(), List.of());
    }
}

record OrderResponseV1(String orderId, String customerId,
                       double total, String status) {
}

record OrderResponseV2(String orderId, String customerId, Money total,
                       String status, Instant createdAt,
                       List<OrderLineV2> lines) {
}

record OrderLineV2(String sku, int quantity, Money unitPrice) {
}

/** ✅ 金額一律用 BigDecimal + 幣別，絕不用 double。 */
record Money(BigDecimal amount, String currency) {
}

record TimelineEntry(Instant at, String event, String actor) {
}

package com.enterprise.tutorial.api.client;

import org.jspecify.annotations.Nullable;
import org.springframework.http.MediaType;
import org.springframework.http.ResponseEntity;
import org.springframework.web.service.annotation.DeleteExchange;
import org.springframework.web.service.annotation.GetExchange;
import org.springframework.web.service.annotation.HttpExchange;
import org.springframework.web.service.annotation.PostExchange;

import java.io.InputStream;
import java.util.List;

/**
 * ⭐ HTTP Interface：宣告式 HTTP 客戶端。
 *
 * 只要定義介面，Spring 會自動產生實作。
 * 相較於手寫 RestClient 呼叫的優點：
 *   ✅ 型別安全的契約
 *   ✅ 易於 Mock 測試
 *   ✅ 呼叫端程式碼極簡潔
 *   ✅ 對 AOT / Native 友善
 */
@HttpExchange(url = "/customers", accept = MediaType.APPLICATION_JSON_VALUE)
public interface CustomerApiClient {

    @GetExchange("/{customerId}")
    CustomerDto findById(@org.springframework.web.bind.annotation.PathVariable
                         String customerId);

    @GetExchange
    List<CustomerDto> search(
            @org.springframework.web.bind.annotation.RequestParam
            @Nullable String keyword,
            @org.springframework.web.bind.annotation.RequestParam
            int page,
            @org.springframework.web.bind.annotation.RequestParam
            int size);

    @PostExchange(contentType = MediaType.APPLICATION_JSON_VALUE)
    ResponseEntity<CustomerDto> create(
            @org.springframework.web.bind.annotation.RequestBody
            CreateCustomerDto request);

    @DeleteExchange("/{customerId}")
    void delete(@org.springframework.web.bind.annotation.PathVariable
                String customerId);

    /**
     * ⭐ 7.0 新增：支援 InputStream 回傳，可串流下載大檔，
     *    不需要先把整個回應讀進記憶體。
     */
    @GetExchange(value = "/{customerId}/avatar",
                 accept = MediaType.APPLICATION_OCTET_STREAM_VALUE)
    ResponseEntity<InputStream> downloadAvatar(
            @org.springframework.web.bind.annotation.PathVariable
            String customerId);
}

@HttpExchange(url = "/inventory")
interface InventoryApiClient {

    @GetExchange("/{sku}")
    StockDto checkStock(@org.springframework.web.bind.annotation.PathVariable
                        String sku);
}

record CustomerDto(String id, String name, String email) {
}

record CreateCustomerDto(String name, String email) {
}

record StockDto(String sku, int available) {
}

package com.enterprise.tutorial.api.client;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.client.JdkClientHttpRequestFactory;
import org.springframework.web.client.RestClient;
import org.springframework.web.client.support.RestClientHttpServiceGroupConfigurer;
import org.springframework.web.service.registry.ImportHttpServices;

import java.net.http.HttpClient;
import java.time.Duration;

/**
 * ⭐ 7.0 新增：@ImportHttpServices —— 以「群組」方式註冊 HTTP 服務。
 *
 * 相較於 6.x 必須為每個介面寫一個 @Bean 方法產生 Proxy，
 * 7.0 可以一次註冊整組，並用 GroupConfigurer 統一設定。
 */
@Configuration(proxyBeanMethods = false)
public class HttpClientConfig {

    /** 群組一：CRM 系統的所有 API。 */
    @Configuration(proxyBeanMethods = false)
    @ImportHttpServices(group = "crm",
                        types = {CustomerApiClient.class})
    static class CrmClients {
    }

    /** 群組二：庫存系統的所有 API。 */
    @Configuration(proxyBeanMethods = false)
    @ImportHttpServices(group = "inventory",
                        types = {InventoryApiClient.class})
    static class InventoryClients {
    }

    /**
     * ⭐ 針對不同群組套用不同設定（baseUrl、逾時、預設標頭、API 版本）。
     */
    @Bean
    RestClientHttpServiceGroupConfigurer groupConfigurer() {
        return groups -> {
            groups.filterByName("crm").forEachClient((group, builder) ->
                    builder.baseUrl("https://crm.enterprise.com/api")
                           .defaultHeader("X-API-Version", "2.0")
                           .requestFactory(requestFactory(Duration.ofSeconds(3)))
                           .defaultStatusHandler(
                                   status -> status.value() == 429,
                                   (req, res) -> {
                                       throw new RateLimitedException(
                                               res.getHeaders().getFirst("Retry-After"));
                                   }));

            groups.filterByName("inventory").forEachClient((group, builder) ->
                    builder.baseUrl("https://inventory.enterprise.com/api")
                           // 庫存查詢要求低延遲，逾時設得更短
                           .requestFactory(requestFactory(Duration.ofMillis(800))));
        };
    }

    /**
     * 🔒 每個 HTTP 客戶端都必須設定「連線逾時」與「讀取逾時」。
     *    沒有逾時的 HTTP 呼叫是生產事故的頭號來源。
     */
    private JdkClientHttpRequestFactory requestFactory(Duration readTimeout) {
        HttpClient httpClient = HttpClient.newBuilder()
                .connectTimeout(Duration.ofSeconds(2))
                .followRedirects(HttpClient.Redirect.NEVER)   // 🔒 防 SSRF 重導
                .build();
        var factory = new JdkClientHttpRequestFactory(httpClient);
        factory.setReadTimeout(readTimeout);
        return factory;
    }

    /** 一般用途的 RestClient（非 HTTP Interface 場景）。 */
    @Bean
    RestClient defaultRestClient() {
        return RestClient.builder()
                .requestFactory(requestFactory(Duration.ofSeconds(5)))
                .defaultHeader("User-Agent", "enterprise-api/2.0")
                .build();
    }
}

class RateLimitedException extends RuntimeException {
    RateLimitedException(String retryAfter) {
        super("下游限流，請於 %s 秒後重試".formatted(retryAfter));
    }
}

package com.enterprise.tutorial.api.client;

import org.springframework.http.HttpStatusCode;
import org.springframework.http.MediaType;
import org.springframework.stereotype.Service;
import org.springframework.web.client.RestClient;

import java.util.List;

/**
 * ⚠️ RestTemplate 在 7.0 已於文件層級標示棄用，7.1 將加上 @Deprecated。
 *    新程式碼一律使用 RestClient（同步）或 WebClient（反應式）。
 *
 * RestClient 相較 RestTemplate 的優點：
 *   ✅ 流暢的 Builder API（與 WebClient 一致，降低心智負擔）
 *   ✅ 更好的錯誤處理（onStatus 精確控制）
 *   ✅ 更清楚的型別推導（ParameterizedTypeReference）
 */
@Service
public class PartnerApiService {

    private final RestClient restClient;

    public PartnerApiService(RestClient defaultRestClient) {
        this.restClient = defaultRestClient;
    }

    public PartnerDto fetch(String partnerId) {
        return restClient.get()
                .uri("https://partner.example.com/partners/{id}", partnerId)
                .accept(MediaType.APPLICATION_JSON)
                .retrieve()
                // 精確的錯誤映射：不同狀態碼對應不同的領域例外
                .onStatus(HttpStatusCode::is4xxClientError, (req, res) -> {
                    if (res.getStatusCode().value() == 404) {
                        throw new PartnerNotFoundException(partnerId);
                    }
                    throw new PartnerApiException(
                            "呼叫夥伴 API 失敗: " + res.getStatusCode());
                })
                .onStatus(HttpStatusCode::is5xxServerError, (req, res) -> {
                    // 5xx 是暫時性錯誤 → 拋出可重試的例外
                    throw new PartnerTemporaryException(
                            "夥伴系統暫時不可用: " + res.getStatusCode());
                })
                .body(PartnerDto.class);
    }

    /** 泛型回傳需要 ParameterizedTypeReference。 */
    public List<PartnerDto> list(int page, int size) {
        return restClient.get()
                .uri(uriBuilder -> uriBuilder
                        .scheme("https").host("partner.example.com")
                        .path("/partners")
                        .queryParam("page", page)
                        .queryParam("size", size)
                        .build())
                .retrieve()
                .body(new org.springframework.core.ParameterizedTypeReference<>() {
                });
    }

    /** 需要完整回應（狀態碼 + 標頭）時用 toEntity()。 */
    public String createAndGetLocation(CreatePartnerDto request) {
        var response = restClient.post()
                .uri("https://partner.example.com/partners")
                .contentType(MediaType.APPLICATION_JSON)
                .body(request)
                .retrieve()
                .toEntity(PartnerDto.class);

        return response.getHeaders().getLocation() != null
                ? response.getHeaders().getLocation().toString()
                : "";
    }
}

record PartnerDto(String id, String name) {
}

record CreatePartnerDto(String name) {
}

class PartnerNotFoundException extends RuntimeException {
    PartnerNotFoundException(String id) {
        super("找不到夥伴: " + id);
    }
}

class PartnerApiException extends RuntimeException {
    PartnerApiException(String message) {
        super(message);
    }
}

class PartnerTemporaryException extends RuntimeException {
    PartnerTemporaryException(String message) {
        super(message);
    }
}

package com.enterprise.tutorial.api;

import jakarta.validation.constraints.Max;
import jakarta.validation.constraints.Min;
import jakarta.validation.constraints.Pattern;
import org.jspecify.annotations.NullMarked;
import org.jspecify.annotations.Nullable;
import org.springframework.http.CacheControl;
import org.springframework.http.HttpHeaders;
import org.springframework.http.ResponseEntity;
import org.springframework.validation.annotation.Validated;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PutMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestHeader;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

import java.time.Duration;
import java.util.List;
import java.util.Set;

@NullMarked
@Validated
@RestController
@RequestMapping("/api/products")
public class ProductController {

    /** 🔒 排序白名單：絕不可把使用者輸入直接拼進 SQL 的 ORDER BY。 */
    private static final Set<String> SORTABLE_FIELDS =
            Set.of("name", "price", "createdAt", "stock");

    private final ProductService service;

    public ProductController(ProductService service) {
        this.service = service;
    }

    /**
     * 分頁 + 排序 + 篩選的標準寫法。
     *
     * 設計要點：
     *   ① size 必須有上限（防止 ?size=999999999 拖垮資料庫）
     *   ② sort 欄位必須用白名單驗證（防 SQL Injection）
     *   ③ 回應包含分頁中繼資訊，並在標頭附上 X-Total-Count
     */
    @GetMapping
    public ResponseEntity<PageResponse<ProductDto>> search(
            @RequestParam(required = false) @Nullable String keyword,
            @RequestParam(required = false) @Nullable String category,
            @RequestParam(required = false) @Min(0) @Nullable Integer minPrice,
            @RequestParam(required = false) @Min(0) @Nullable Integer maxPrice,
            @RequestParam(defaultValue = "0") @Min(0) int page,
            @RequestParam(defaultValue = "20") @Min(1) @Max(100) int size,
            @RequestParam(defaultValue = "createdAt,desc")
            @Pattern(regexp = "[a-zA-Z]+,(asc|desc)") String sort) {

        String[] sortParts = sort.split(",");
        // 🔒 白名單驗證
        if (!SORTABLE_FIELDS.contains(sortParts[0])) {
            throw new IllegalArgumentException(
                    "不支援的排序欄位：%s（可用：%s）"
                            .formatted(sortParts[0], SORTABLE_FIELDS));
        }

        PageResponse<ProductDto> result = service.search(new ProductQuery(
                keyword, category, minPrice, maxPrice,
                page, size, sortParts[0], sortParts[1]));

        return ResponseEntity.ok()
                .header("X-Total-Count", String.valueOf(result.totalElements()))
                .cacheControl(CacheControl.maxAge(Duration.ofMinutes(1)).cachePublic())
                .body(result);
    }

    /**
     * ETag 條件式請求：
     *   • 客戶端帶 If-None-Match → 未變更時回 304，不傳輸本文（省頻寬）
     *   • 客戶端帶 If-Match     → 樂觀鎖，防止「後寫覆蓋先寫」
     */
    @GetMapping("/{productId}")
    public ResponseEntity<ProductDto> getOne(
            @PathVariable String productId,
            @RequestHeader(value = HttpHeaders.IF_NONE_MATCH, required = false)
            @Nullable String ifNoneMatch) {

        ProductDto product = service.findById(productId);
        String etag = "\"%s\"".formatted(product.version());

        if (etag.equals(ifNoneMatch)) {
            return ResponseEntity.status(304).eTag(etag).build();
        }

        return ResponseEntity.ok()
                .eTag(etag)
                .cacheControl(CacheControl.maxAge(Duration.ofMinutes(5)))
                .body(product);
    }

    /** 樂觀鎖更新：If-Match 不符時回 412 Precondition Failed。 */
    @PutMapping("/{productId}")
    public ResponseEntity<ProductDto> update(
            @PathVariable String productId,
            @RequestHeader(HttpHeaders.IF_MATCH) String ifMatch,
            @RequestBody UpdateProductRequest request) {

        long expectedVersion = Long.parseLong(ifMatch.replace("\"", ""));
        ProductDto updated = service.update(productId, request, expectedVersion);

        return ResponseEntity.ok()
                .eTag("\"%s\"".formatted(updated.version()))
                .body(updated);
    }
}

record ProductDto(String id, String name, java.math.BigDecimal price,
                  int stock, long version) {
}

record UpdateProductRequest(String name, java.math.BigDecimal price) {
}

record ProductQuery(@Nullable String keyword, @Nullable String category,
                    @Nullable Integer minPrice, @Nullable Integer maxPrice,
                    int page, int size, String sortField, String sortDirection) {
}

record PageResponse<T>(List<T> content, int page, int size,
                       long totalElements, int totalPages, boolean hasNext) {
}

package com.enterprise.tutorial.api;

import org.jspecify.annotations.NullMarked;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Propagation;
import org.springframework.transaction.annotation.Transactional;

import java.time.Duration;
import java.time.Instant;

/**
 * 冪等性是「支付」「下單」「轉帳」這類 API 的必要條件。
 *
 * 客戶端在標頭帶上 Idempotency-Key（通常是 UUID）：
 *   • 第一次請求 → 正常處理，儲存結果
 *   • 重複請求（相同 key）→ 直接回傳第一次的結果，不重複執行
 *
 * ⚠️ 常見錯誤：只用「記憶體 Map」實作。
 *    多實例部署時完全無效，必須用共享儲存（Redis / 資料庫）。
 */
@NullMarked
@Service
public class IdempotentOrderService {

    private static final Duration RETENTION = Duration.ofHours(24);

    private final IdempotencyStore store;
    private final OrderApplicationService delegate;

    public IdempotentOrderService(IdempotencyStore store,
                                  OrderApplicationService delegate) {
        this.store = store;
        this.delegate = delegate;
    }

    /**
     * ⚠️ 交易邊界的關鍵：
     *   冪等記錄的寫入必須與業務操作在「同一個交易」中，
     *   否則可能發生「業務成功但冪等記錄失敗」→ 重複執行。
     */
    @Transactional(propagation = Propagation.REQUIRED)
    public OrderResult create(CreateOrderRequest request, String idempotencyKey) {

        // ① 嘗試「原子性地」佔用這個 key
        //    底層應使用 INSERT ... ON CONFLICT DO NOTHING 或 SETNX
        boolean acquired = store.tryAcquire(idempotencyKey, RETENTION);

        if (!acquired) {
            IdempotencyRecord existing = store.find(idempotencyKey);

            // ② 已完成 → 直接回傳原結果
            if (existing.isCompleted()) {
                // 🔒 驗證請求內容一致：同一個 key 帶不同內容應視為錯誤
                if (!existing.requestFingerprint().equals(fingerprint(request))) {
                    throw new IdempotencyConflictException(
                            "相同的 Idempotency-Key 但請求內容不同");
                }
                return existing.result();
            }

            // ③ 處理中 → 回 409，請客戶端稍後重試
            throw new RequestInProgressException(
                    "相同請求正在處理中，請稍後查詢結果");
        }

        // ④ 首次請求：執行業務邏輯
        try {
            OrderResult result = delegate.createOrder(request);
            store.complete(idempotencyKey, result, fingerprint(request), Instant.now());
            return result;
        } catch (RuntimeException ex) {
            // ⚠️ 失敗時釋放 key，讓客戶端可以重試
            //    但「業務規則失敗」不應釋放（重試也會失敗）
            if (ex instanceof TransientFailureException) {
                store.release(idempotencyKey);
            } else {
                store.completeWithFailure(idempotencyKey, ex.getMessage());
            }
            throw ex;
        }
    }

    private String fingerprint(CreateOrderRequest request) {
        return Integer.toHexString(request.hashCode());
    }
}

interface IdempotencyStore {
    boolean tryAcquire(String key, Duration ttl);

    IdempotencyRecord find(String key);

    void complete(String key, OrderResult result, String fingerprint, Instant at);

    void completeWithFailure(String key, String reason);

    void release(String key);
}

record IdempotencyRecord(String key, boolean isCompleted,
                         String requestFingerprint, OrderResult result) {
}

record OrderResult(String orderId, String status) {
}

class IdempotencyConflictException extends RuntimeException {
    IdempotencyConflictException(String message) {
        super(message);
    }
}

class RequestInProgressException extends RuntimeException {
    RequestInProgressException(String message) {
        super(message);
    }
}

class TransientFailureException extends RuntimeException {
}

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.8.0</version>
</dependency>

package com.enterprise.tutorial.api;

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.media.Content;
import io.swagger.v3.oas.annotations.media.Schema;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.responses.ApiResponses;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.http.MediaType;
import org.springframework.http.ProblemDetail;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

/**
 * OpenAPI 註解的原則：
 *   ✅ 只在「程式碼無法自我說明」之處補充（業務語意、錯誤情境、範例）
 *   ❌ 不要為每個欄位都寫 @Schema（型別與名稱已經說明了大半）
 */
@Tag(name = "訂單", description = "訂單建立、查詢與取消")
@RestController
@RequestMapping("/api/orders")
public class DocumentedOrderController {

    @Operation(
            summary = "依訂單編號查詢單筆訂單",
            description = """
                    回傳訂單的完整資訊，包含明細與金額。

                    **權限**：需要 `ORDER_READ`，且只能查詢自己所屬組織的訂單。

                    **版本**：
                    - `1.0`（已棄用，2026-12-31 停止服務）：total 為 double
                    - `2.0`：total 為結構化的 Money 物件
                    """)
    @ApiResponses({
            @ApiResponse(responseCode = "200", description = "查詢成功"),
            @ApiResponse(responseCode = "403",
                    description = "無權限存取此訂單",
                    content = @Content(
                            mediaType = MediaType.APPLICATION_PROBLEM_JSON_VALUE,
                            schema = @Schema(implementation = ProblemDetail.class))),
            @ApiResponse(responseCode = "404",
                    description = "訂單不存在",
                    content = @Content(
                            mediaType = MediaType.APPLICATION_PROBLEM_JSON_VALUE,
                            schema = @Schema(implementation = ProblemDetail.class)))
    })
    @GetMapping("/{orderId}")
    public OrderResponseV2 getOne(
            @Parameter(description = "訂單編號，格式 ORD-yyyyMMdd-NNNNNN",
                       example = "ORD-20260731-000123")
            @PathVariable String orderId) {
        throw new UnsupportedOperationException("由實際實作提供");
    }
}

// ❌ 6.2 的常見做法：路徑前綴 + 重複的 Controller
@RestController
@RequestMapping("/api/v1/orders")
class OrderControllerV1 { /* 完整實作 */ }

@RestController
@RequestMapping("/api/v2/orders")
class OrderControllerV2 { /* 幾乎相同的完整實作 */ }

// ✅ 7.0：單一 Controller + version 屬性
@RestController
@RequestMapping("/api/orders")
class OrderController {

    @GetMapping(value = "/{id}", version = "1.0")
    OrderResponseV1 getV1(@PathVariable String id) { /* 只有 DTO 映射不同 */ }

    @GetMapping(value = "/{id}", version = "2.0")
    OrderResponseV2 getV2(@PathVariable String id) { /* 只有 DTO 映射不同 */ }
}

# ① 找出所有 RestTemplate 使用（7.1 將 @Deprecated）
Get-ChildItem -Recurse -Include *.java | Select-String -Pattern 'RestTemplate'

# ② 找出路徑版本控制的 Controller（可用 7.0 版本機制合併）
Get-ChildItem -Recurse -Include *.java |
    Select-String -Pattern '@RequestMapping\(.*"/v\d+/'

# ③ 找出 RPC 風格的端點（違反 REST）
Get-ChildItem -Recurse -Include *.java |
    Select-String -Pattern '@(Post|Get)Mapping\("/(get|create|update|delete|do)[A-Z]'

# ④ 找出沒有 @Max 限制的 size 參數（DoS 風險）
Get-ChildItem -Recurse -Include *.java |
    Select-String -Pattern '@RequestParam.*\bsize\b' -Context 1,0 |
    Where-Object { $_.Context.PreContext -notmatch '@Max' }

# ⑤ 找出使用 double 表示金額的 DTO（精度風險）
Get-ChildItem -Recurse -Include *.java |
    Select-String -Pattern '(double|Double)\s+(amount|price|total|balance|fee)'

# ⑥ 找出 OkHttp3 與已移除的 API
Get-ChildItem -Recurse -Include *.java,pom.xml |
    Select-String -Pattern 'OkHttp3ClientHttpRequestFactory|okhttp3|ListenableFuture'

需要反應式（回傳 Mono/Flux）?
   │是 ──▶ WebClient
   │否
   ▼
呼叫的是「固定契約的 API」?
   │是 ──▶ ⭐ HTTP Interface（最推薦：型別安全、易測試、程式碼最少）
   │否（動態 URL、一次性呼叫）
   ▼
   RestClient

// ❌ 命令式驗證：邏輯與規則混在一起，無法重用、無法被工具讀取
public void createOrder(OrderRequest req) {
    if (req.getCustomerId() == null || req.getCustomerId().isBlank()) {
        throw new IllegalArgumentException("客戶編號不可為空");
    }
    if (req.getItems() == null || req.getItems().isEmpty()) {
        throw new IllegalArgumentException("訂單至少需要一個品項");
    }
    if (req.getItems().size() > 100) {
        throw new IllegalArgumentException("訂單品項不可超過 100 筆");
    }
    // ...再 50 行
}

第 1 層  客戶端驗證（JS / 前端表單）
         目的：UX，即時回饋
         ⚠️ 絕對不可信任，可被繞過
                    │
                    ▼
第 2 層  API 邊界驗證 ← Bean Validation 的戰場
         目的：格式、範圍、必填、長度、型別
         特性：無狀態、不查 DB、純函式、可並行
         範例：@NotBlank @Size(max=50) @Email @Min(1)
                    │
                    ▼
第 3 層  領域 / 服務層驗證
         目的：業務不變式、跨聚合規則、需要查詢的規則
         特性：有狀態、會查 DB、需交易
         範例：帳號是否已存在、庫存是否足夠、額度是否超限
                    │
                    ▼
第 4 層  資料庫約束
         目的：最後防線，防止併發下的資料不一致
         範例：UNIQUE、FOREIGN KEY、CHECK、NOT NULL

你的程式碼
    │  使用
    ▼
jakarta.validation.*（Jakarta Validation 3.1 — 規格 / API）
    │  由誰實作
    ▼
org.hibernate.validator.*（Hibernate Validator 9.x — 參考實作）
    │  Spring 如何接上
    ▼
org.springframework.validation.beanvalidation.LocalValidatorFactoryBean
    （同時實作 jakarta.validation.Validator 與 Spring 的 org.springframework.validation.Validator）

標在 @RequestBody 參數上           ──▶ @Valid（或 @Validated 若需 Groups）
標在 DTO 的巢狀欄位 / 集合上        ──▶ @Valid（唯一選擇）
標在 Service 類別上（開啟方法驗證）  ──▶ @Validated（唯一選擇）
需要依情境切換規則                  ──▶ @Validated(Xxx.class)