package com.tutorial.springboot;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@SpringBootApplication
public class DemoApplication {

    public static void main(String[] args) {
        SpringApplication.run(DemoApplication.class, args);
    }
}

@RestController
class HelloController {

    // Java 25 record 直接當作 JSON 回應的 DTO
    record Greeting(String message, String version) {
    }

    @GetMapping("/hello")
    Greeting hello() {
        return new Greeting("Hello, Spring Boot 4.x", "4.1");
    }
}

// package-info.java — 宣告整個套件預設為「非空」
@NullMarked
package com.example.order.domain;

import org.jspecify.annotations.NullMarked;

import org.jspecify.annotations.Nullable;

public interface OrderRepository {

    // 回傳值可能為 null，必須明確標註
    @Nullable Order findByOrderNo(String orderNo);

    // 參數與回傳值都不可為 null（受 @NullMarked 保護，不必逐一標註）
    Order save(Order order);
}

import org.springframework.beans.factory.BeanRegistrar;
import org.springframework.beans.factory.BeanRegistry;
import org.springframework.core.env.Environment;

public class PaymentGatewayRegistrar implements BeanRegistrar {

    @Override
    public void register(BeanRegistry registry, Environment env) {
        // 依設定動態決定要註冊哪些通道，且對 AOT 友善
        for (String channel : env.getProperty("payment.channels", String[].class, new String[0])) {
            registry.registerBean("gateway-" + channel, PaymentGateway.class,
                    spec -> spec.supplier(ctx -> new PaymentGateway(channel)));
        }
    }
}

@Configuration(proxyBeanMethods = false)
@Import(PaymentGatewayRegistrar.class)
public class PaymentConfig {
}

import org.springframework.resilience.annotation.ConcurrencyLimit;
import org.springframework.resilience.annotation.Retryable;

@Service
public class InventoryService {

    // 最多重試 3 次，指數退避；只針對指定例外重試
    @Retryable(maxAttempts = 3, delay = 200, multiplier = 2.0,
               includes = TransientDataAccessException.class)
    public void reserve(String sku, int qty) {
        inventoryClient.reserve(sku, qty);
    }

    // 同時最多 10 個執行緒進入，超過者排隊（等同輕量版 Bulkhead）
    @ConcurrencyLimit(10)
    public Report generateHeavyReport(ReportRequest request) {
        return reportEngine.render(request);
    }
}

// 1. Record — DTO 樣板碼歸零
public record OrderRequest(String customerId, List<OrderLine> lines) {}

// 2. Sealed interface + pattern matching — 領域事件分派型別安全
public sealed interface PaymentResult permits Approved, Declined, Pending {}

public String describe(PaymentResult result) {
    return switch (result) {
        case Approved a  -> "已核准，授權碼 " + a.authCode();
        case Declined d  -> "已拒絕，原因 " + d.reason();
        case Pending p   -> "處理中，預計 " + p.etaSeconds() + " 秒";
    };
}

// 3. Text Block — SQL 與 JSON 可讀性大幅提升
private static final String FIND_ACTIVE_ORDERS = """
        SELECT o.id, o.customer_id, o.total_amount
        FROM orders o
        WHERE o.status = 'ACTIVE'
          AND o.created_at >= ?
        ORDER BY o.created_at DESC
        """;

// 4. Virtual Threads — 由設定啟用，不需改程式
// application.yml: spring.threads.virtual.enabled: true

spring:
  # 1. 虛擬執行緒 — I/O 密集型服務吞吐可提升數倍
  threads:
    virtual:
      enabled: true
  # 2. 延遲初始化 — 縮短啟動時間，但第一次請求變慢，正式環境慎用
  main:
    lazy-initialization: false
  jmx:
    enabled: false   # 不用 JMX 就關掉，省下註冊開銷

# 3. JVM 層級：容器環境務必設定記憶體上限比例
java -XX:MaxRAMPercentage=75.0 -XX:+UseZGC -jar app.jar

package com.tutorial.springboot.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import tools.jackson.databind.SerializationFeature;
import tools.jackson.databind.json.JsonMapper;

@Configuration
public class JsonConfig {

    // 定義了自己的 JsonMapper, Spring Boot 的 JacksonAutoConfiguration
    // 因為標了 @ConditionalOnMissingBean 就會自動退讓
    @Bean
    JsonMapper jsonMapper() {
        return JsonMapper.builder()
                .disable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS)
                .build();
    }
}

// 確保本組態在 DataSourceAutoConfiguration 之後才評估
@AutoConfiguration(after = DataSourceAutoConfiguration.class)
@ConditionalOnClass(JdbcTemplate.class)
public class MyJdbcAutoConfiguration {
    // ...
}

package com.tutorial.springboot.order;

import org.springframework.stereotype.Service;

@Service
public class OrderService {

    // ✅ 建構子注入 — 唯一推薦方式
    private final OrderRepository repository;
    private final PaymentGateway gateway;

    // 只有一個建構子時可以省略 @Autowired
    public OrderService(OrderRepository repository, PaymentGateway gateway) {
        this.repository = repository;
        this.gateway = gateway;
    }
}

spring:
  config:
    import:
      - "optional:file:./config/local.yml"       # optional: 檔案不存在也不報錯
      - "classpath:shared/common.yml"
      - "configtree:/run/secrets/"               # K8s Secret 掛載為檔案樹
      - "classpath:legacy.properties[encoding=utf-8]"   # 🆕 4.1 指定編碼

# application.yml
spring:
  application:
    name: order-service
---
spring:
  config:
    activate:
      on-profile: dev
server:
  port: 8080
logging:
  level:
    com.tutorial: DEBUG
---
spring:
  config:
    activate:
      on-profile: prod
server:
  port: 8443
logging:
  level:
    com.tutorial: INFO

package com.tutorial.springboot;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.boot.context.metrics.buffering.BufferingApplicationStartup;

@SpringBootApplication
public class DemoApplication {

    public static void main(String[] args) {
        SpringApplication app = new SpringApplication(DemoApplication.class);
        // 記錄最耗時的 2048 個啟動步驟, 之後可由 /actuator/startup 查詢
        app.setApplicationStartup(new BufferingApplicationStartup(2048));
        app.run(args);
    }
}

management:
  endpoints:
    web:
      exposure:
        include: startup

Invoke-WebRequest -Uri "https://start.spring.io/starter.zip?type=maven-project&language=java&bootVersion=4.1.0&groupId=com.tutorial&artifactId=order-service&name=order-service&packageName=com.tutorial.order&javaVersion=25&dependencies=web,actuator,validation" -OutFile order-service.zip

Expand-Archive -Path order-service.zip -DestinationPath order-service
Set-Location order-service

# 安裝 (SDKMAN)
sdk install springboot

# 建立專案
spring init --build=maven --java-version=25 --boot-version=4.1.0 \
    --dependencies=web,actuator,validation \
    --group-id=com.tutorial --artifact-id=order-service \
    --package-name=com.tutorial.order order-service

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

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

    <groupId>com.tutorial</groupId>
    <artifactId>order-service</artifactId>
    <version>1.0.0-SNAPSHOT</version>
    <name>order-service</name>
    <description>Spring Boot 4.x 教學範例專案</description>

    <properties>
        <java.version>25</java.version>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <!-- 覆寫 BOM 管理的版本時, 一律改屬性, 不要在 dependency 直接寫 version -->
        <testcontainers.version>2.0.0</testcontainers.version>
    </properties>

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

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-devtools</artifactId>
            <scope>runtime</scope>
            <optional>true</optional>
        </dependency>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
                <configuration>
                    <excludes>
                        <exclude>
                            <groupId>org.projectlombok</groupId>
                            <artifactId>lombok</artifactId>
                        </exclude>
                    </excludes>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>

<parent>
    <groupId>com.company</groupId>
    <artifactId>company-parent</artifactId>
    <version>3.2.0</version>
</parent>

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-dependencies</artifactId>
            <version>4.1.0</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

<plugin>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-maven-plugin</artifactId>
    <version>4.1.0</version>
    <executions>
        <execution>
            <goals>
                <goal>repackage</goal>
            </goals>
        </execution>
    </executions>
</plugin>

// build.gradle.kts — Gradle 9
plugins {
    java
    id("org.springframework.boot") version "4.1.0"
    id("io.spring.dependency-management") version "1.1.7"
}

group = "com.tutorial"
version = "1.0.0-SNAPSHOT"

java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(25)
    }
}

repositories {
    mavenCentral()
}

dependencies {
    implementation("org.springframework.boot:spring-boot-starter-web")
    implementation("org.springframework.boot:spring-boot-starter-validation")
    implementation("org.springframework.boot:spring-boot-starter-actuator")

    developmentOnly("org.springframework.boot:spring-boot-devtools")

    testImplementation("org.springframework.boot:spring-boot-starter-test")
    testRuntimeOnly("org.junit.platform:junit-platform-launcher")
}

tasks.withType<Test> {
    useJUnitPlatform()
}

tasks.named<org.springframework.boot.gradle.tasks.bundling.BootJar>("bootJar") {
    archiveFileName = "app.jar"
}

{
  "java.configuration.updateBuildConfiguration": "automatic",
  "java.format.settings.url": ".vscode/java-formatter.xml",
  "java.compile.nullAnalysis.mode": "automatic",
  "spring-boot.ls.problem.application-properties.unknown-property": "WARNING",
  "files.encoding": "utf8"
}

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "java",
      "name": "Spring Boot - OrderServiceApplication",
      "request": "launch",
      "mainClass": "com.tutorial.order.OrderServiceApplication",
      "projectName": "order-service",
      "args": "--spring.profiles.active=dev",
      "env": {
        "SPRING_DATASOURCE_PASSWORD": "${env:LOCAL_DB_PASSWORD}"
      }
    }
  ]
}

<!-- 平行建置與增量編譯 -->
<properties>
    <maven.compiler.parameters>true</maven.compiler.parameters>
</properties>

# Maven 平行建置 (依 CPU 核心數)
mvn -T 1C clean package

# Gradle 平行 + 建置快取
./gradlew build --parallel --build-cache

org.gradle.parallel=true
org.gradle.caching=true
org.gradle.configuration-cache=true
org.gradle.jvmargs=-Xmx4g -XX:MaxMetaspaceSize=1g

<plugin>
    <groupId>org.owasp</groupId>
    <artifactId>dependency-check-maven</artifactId>
    <version>12.1.0</version>
    <executions>
        <execution>
            <goals><goal>check</goal></goals>
        </execution>
    </executions>
</plugin>

order-service/
├── .mvn/wrapper/                    # Maven Wrapper (必須進版控)
├── mvnw / mvnw.cmd
├── pom.xml
├── .editorconfig
├── .gitignore
├── Dockerfile
├── compose.yaml                     # 本機依賴服務 (Boot 會自動偵測)
└── src/
    ├── main/
    │   ├── java/com/tutorial/order/
    │   │   └── OrderServiceApplication.java   # ⚠️ 必須在根 package
    │   └── resources/
    │       ├── application.yml              # 主設定
    │       ├── application-dev.yml          # 開發環境
    │       ├── application-prod.yml         # 正式環境
    │       ├── logback-spring.xml           # 日誌設定
    │       ├── db/migration/                # Flyway SQL
    │       │   └── V1__init_schema.sql
    │       ├── static/                      # 靜態資源
    │       ├── templates/                   # 樣板引擎
    │       └── META-INF/
    │           └── additional-spring-configuration-metadata.json
    └── test/
        ├── java/com/tutorial/order/
        └── resources/
            └── application-test.yml

com.tutorial.order/
├── OrderServiceApplication.java
├── config/          # @Configuration、SecurityConfig、OpenApiConfig
├── controller/      # @RestController
├── service/         # @Service 業務邏輯
├── repository/      # @Repository 資料存取
├── entity/          # JPA @Entity
├── dto/             # request / response record
├── mapper/          # Entity ↔ DTO 轉換
├── exception/       # 自訂例外 + @RestControllerAdvice
└── util/            # 工具類

com.tutorial.order/
├── OrderServiceApplication.java
├── common/                  # 跨功能共用
│   ├── config/
│   ├── exception/
│   └── util/
├── order/                   # 訂單功能 (完整垂直切片)
│   ├── OrderController.java
│   ├── OrderService.java
│   ├── OrderRepository.java
│   ├── Order.java
│   └── dto/
├── payment/                 # 付款功能
│   ├── PaymentController.java
│   ├── PaymentService.java
│   └── ...
└── inventory/               # 庫存功能
    └── ...

com.tutorial.order/
├── domain/                          # ⚠️ 零 Spring 相依
│   ├── model/
│   │   ├── Order.java               # 聚合根
│   │   ├── OrderLine.java
│   │   ├── Money.java               # 值物件
│   │   └── OrderStatus.java
│   ├── event/
│   │   └── OrderPlacedEvent.java
│   └── service/
│       └── OrderPricingService.java # 純領域邏輯
├── application/
│   ├── port/
│   │   ├── in/
│   │   │   └── PlaceOrderUseCase.java
│   │   └── out/
│   │       ├── LoadOrderPort.java
│   │       └── SaveOrderPort.java
│   └── service/
│       └── PlaceOrderService.java   # @Service, @Transactional
└── infrastructure/
    ├── web/
    │   ├── OrderRestController.java
    │   └── dto/
    ├── persistence/
    │   ├── OrderJpaEntity.java
    │   ├── OrderJpaRepository.java
    │   └── OrderPersistenceAdapter.java
    └── config/
        └── BeanConfiguration.java

// ===== domain 層 — 零框架相依 =====
package com.tutorial.order.domain.model;

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

public record Money(BigDecimal amount, String currency) {

    public Money {
        Objects.requireNonNull(amount, "amount 不可為 null");
        if (amount.signum() < 0) {
            throw new IllegalArgumentException("金額不可為負數");
        }
    }

    public Money plus(Money other) {
        if (!currency.equals(other.currency)) {
            throw new IllegalArgumentException("幣別不同無法相加");
        }
        return new Money(amount.add(other.amount), currency);
    }
}

package com.tutorial.order.domain.model;

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

public class Order {

    private final String id;
    private final String customerId;
    private final List<OrderLine> lines;
    private OrderStatus status;
    private final Instant createdAt;

    public Order(String id, String customerId, List<OrderLine> lines, Instant createdAt) {
        if (lines == null || lines.isEmpty()) {
            throw new IllegalArgumentException("訂單至少要有一個品項");
        }
        this.id = id;
        this.customerId = customerId;
        this.lines = List.copyOf(lines);
        this.status = OrderStatus.PENDING;
        this.createdAt = createdAt;
    }

    /** 業務規則封裝在聚合根內，外部無法繞過。 */
    public void confirm() {
        if (status != OrderStatus.PENDING) {
            throw new IllegalStateException("只有待處理訂單可以確認，目前狀態：" + status);
        }
        this.status = OrderStatus.CONFIRMED;
    }

    public Money totalAmount() {
        return lines.stream()
                .map(OrderLine::subtotal)
                .reduce(new Money(java.math.BigDecimal.ZERO, "TWD"), Money::plus);
    }

    public String id() { return id; }
    public String customerId() { return customerId; }
    public List<OrderLine> lines() { return lines; }
    public OrderStatus status() { return status; }
    public Instant createdAt() { return createdAt; }
}

// ===== application 層 — Port 介面 =====
package com.tutorial.order.application.port.out;

import com.tutorial.order.domain.model.Order;
import java.util.Optional;

public interface LoadOrderPort {
    Optional<Order> loadById(String orderId);
}

package com.tutorial.order.application.port.in;

import com.tutorial.order.domain.model.Order;
import java.util.List;

public interface PlaceOrderUseCase {

    record Command(String customerId, List<Item> items) {
        public record Item(String sku, int quantity) {}
    }

    Order placeOrder(Command command);
}

// ===== application 層 — 使用案例實作 =====
package com.tutorial.order.application.service;

import com.tutorial.order.application.port.in.PlaceOrderUseCase;
import com.tutorial.order.application.port.out.SaveOrderPort;
import com.tutorial.order.domain.model.Order;
import com.tutorial.order.domain.model.OrderLine;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;

import java.time.Instant;
import java.util.List;
import java.util.UUID;

@Service
public class PlaceOrderService implements PlaceOrderUseCase {

    private final SaveOrderPort saveOrderPort;

    public PlaceOrderService(SaveOrderPort saveOrderPort) {
        this.saveOrderPort = saveOrderPort;
    }

    @Override
    @Transactional
    public Order placeOrder(Command command) {
        List<OrderLine> lines = command.items().stream()
                .map(item -> OrderLine.of(item.sku(), item.quantity()))
                .toList();

        Order order = new Order(UUID.randomUUID().toString(),
                command.customerId(), lines, Instant.now());
        return saveOrderPort.save(order);
    }
}

// ===== infrastructure 層 — 出站介面卡 =====
package com.tutorial.order.infrastructure.persistence;

import com.tutorial.order.application.port.out.SaveOrderPort;
import com.tutorial.order.domain.model.Order;
import org.springframework.stereotype.Component;

@Component
public class OrderPersistenceAdapter implements SaveOrderPort {

    private final OrderJpaRepository jpaRepository;
    private final OrderMapper mapper;

    public OrderPersistenceAdapter(OrderJpaRepository jpaRepository, OrderMapper mapper) {
        this.jpaRepository = jpaRepository;
        this.mapper = mapper;
    }

    @Override
    public Order save(Order order) {
        OrderJpaEntity saved = jpaRepository.save(mapper.toEntity(order));
        return mapper.toDomain(saved);
    }
}

order-platform/
├── pom.xml                       # <packaging>pom</packaging>
├── order-domain/                 # 純領域模型 (零 Spring)
├── order-application/            # 使用案例 + Port
├── order-infrastructure/         # JPA、Kafka、外部 API 介面卡
├── order-api/                    # REST Controller + 啟動類別
└── order-common/                 # 跨模組共用工具

<!-- 根 pom.xml -->
<packaging>pom</packaging>
<modules>
    <module>order-domain</module>
    <module>order-application</module>
    <module>order-infrastructure</module>
    <module>order-api</module>
    <module>order-common</module>
</modules>

package com.tutorial.order.arch;

import com.tngtech.archunit.junit.AnalyzeClasses;
import com.tngtech.archunit.junit.ArchTest;
import com.tngtech.archunit.lang.ArchRule;

import static com.tngtech.archunit.lang.syntax.ArchRuleDefinition.noClasses;

@AnalyzeClasses(packages = "com.tutorial.order")
class ArchitectureTest {

    @ArchTest
    static final ArchRule domain_不可相依_spring =
            noClasses().that().resideInAPackage("..domain..")
                    .should().dependOnClassesThat().resideInAnyPackage("org.springframework..");

    @ArchTest
    static final ArchRule domain_不可相依_infrastructure =
            noClasses().that().resideInAPackage("..domain..")
                    .should().dependOnClassesThat().resideInAPackage("..infrastructure..");

    @ArchTest
    static final ArchRule controller_不可直接呼叫_repository =
            noClasses().that().resideInAPackage("..controller..")
                    .should().dependOnClassesThat().resideInAPackage("..repository..");
}

<dependency>
    <groupId>com.tngtech.archunit</groupId>
    <artifactId>archunit-junit5</artifactId>
    <version>1.4.1</version>
    <scope>test</scope>
</dependency>

<!-- ✅ 正確: 覆寫 BOM 定義的版本屬性 -->
<properties>
    <java.version>25</java.version>
    <testcontainers.version>2.0.1</testcontainers.version>
    <postgresql.version>42.7.9</postgresql.version>
</properties>

<!-- ❌ 錯誤: 在 dependency 直接寫 version, 會與 BOM 打架 -->
<dependency>
    <groupId>org.postgresql</groupId>
    <artifactId>postgresql</artifactId>
    <version>42.6.0</version>
</dependency>

mvn help:effective-pom | Select-String -Pattern "\.version>" -Context 0,0

// build.gradle.kts
extra["testcontainers.version"] = "2.0.1"

// 或用強制解析 (最後手段)
configurations.all {
    resolutionStrategy {
        force("org.postgresql:postgresql:42.7.9")
    }
}

<!-- ⚠️ 過渡用：先讓專案編得過、跑得起來 -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-classic</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-test-classic</artifactId>
    <scope>test</scope>
</dependency>

<!-- ✅ JDBC Driver 一律 runtime -->
<dependency>
    <groupId>org.postgresql</groupId>
    <artifactId>postgresql</artifactId>
    <scope>runtime</scope>
</dependency>

<!-- ✅ Lombok: 只在編譯期 -->
<dependency>
    <groupId>org.projectlombok</groupId>
    <artifactId>lombok</artifactId>
    <optional>true</optional>
</dependency>

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

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

    <groupId>com.company.platform</groupId>
    <artifactId>company-spring-boot-parent</artifactId>
    <version>1.0.0</version>
    <packaging>pom</packaging>

    <properties>
        <java.version>25</java.version>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <maven.compiler.parameters>true</maven.compiler.parameters>
    </properties>

    <dependencies>
        <!-- 所有專案強制引入的共用相依 -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-actuator</artifactId>
        </dependency>
        <dependency>
            <groupId>com.company.platform</groupId>
            <artifactId>company-logging-spring-boot-starter</artifactId>
            <version>1.0.0</version>
        </dependency>
    </dependencies>

    <build>
        <pluginManagement>
            <plugins>
                <plugin>
                    <groupId>org.apache.maven.plugins</groupId>
                    <artifactId>maven-enforcer-plugin</artifactId>
                    <executions>
                        <execution>
                            <id>enforce-rules</id>
                            <goals><goal>enforce</goal></goals>
                            <configuration>
                                <rules>
                                    <requireMavenVersion>
                                        <version>[3.9.0,)</version>
                                    </requireMavenVersion>
                                    <requireJavaVersion>
                                        <version>[25,)</version>
                                    </requireJavaVersion>
                                    <!-- 禁止使用不允許的相依 -->
                                    <bannedDependencies>
                                        <excludes>
                                            <exclude>log4j:log4j</exclude>
                                            <exclude>commons-collections:commons-collections</exclude>
                                            <exclude>org.apache.derby:*</exclude>
                                        </excludes>
                                    </bannedDependencies>
                                    <!-- 禁止版本收斂衝突 -->
                                    <dependencyConvergence/>
                                </rules>
                            </configuration>
                        </execution>
                    </executions>
                </plugin>
            </plugins>
        </pluginManagement>

        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-enforcer-plugin</artifactId>
            </plugin>
            <plugin>
                <groupId>org.owasp</groupId>
                <artifactId>dependency-check-maven</artifactId>
                <version>12.1.0</version>
                <configuration>
                    <failBuildOnCVSS>7</failBuildOnCVSS>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
    <exclusions>
        <!-- 改用 Undertow 取代預設的 Tomcat -->
        <exclusion>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-tomcat</artifactId>
        </exclusion>
    </exclusions>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-undertow</artifactId>
</dependency>

# 分析建置期相依解析耗時
mvn -X clean package | Select-String "Resolving"

# 離線建置 (CI 有本地 repo cache 時)
mvn -o clean package

# 只重新建置變更的模組
mvn -pl order-api -am clean package

<plugin>
    <groupId>org.cyclonedx</groupId>
    <artifactId>cyclonedx-maven-plugin</artifactId>
    <version>2.9.1</version>
    <executions>
        <execution>
            <phase>package</phase>
            <goals><goal>makeAggregateBom</goal></goals>
        </execution>
    </executions>
</plugin>

// @SpringBootApplication 等同於下面三個註解
@SpringBootConfiguration   // = @Configuration, 標示這是設定類別且為應用主類別
@EnableAutoConfiguration   // 啟動自動組態機制
@ComponentScan             // 掃描本 package 及子 package
public class OrderServiceApplication {
    public static void main(String[] args) {
        SpringApplication.run(OrderServiceApplication.class, args);
    }
}

@SpringBootApplication(exclude = {
        // 本服務不連資料庫, 排除以免因缺少 DataSource 設定而啟動失敗
        DataSourceAutoConfiguration.class,
        // 使用自訂的 Security 設定, 不要官方預設的
        SecurityAutoConfiguration.class
})
public class GatewayApplication { }

spring:
  autoconfigure:
    exclude:
      - org.springframework.boot.autoconfigure.jdbc.DataSourceAutoConfiguration

package com.tutorial.order.config;

import jakarta.validation.constraints.Max;
import jakarta.validation.constraints.Min;
import jakarta.validation.constraints.NotBlank;
import jakarta.validation.constraints.NotNull;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.boot.context.properties.bind.DefaultValue;
import org.springframework.validation.annotation.Validated;

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

@Validated
@ConfigurationProperties(prefix = "app.payment")
public record PaymentProperties(

        @NotBlank String gatewayUrl,

        @NotBlank String merchantId,

        @NotNull @DefaultValue("5s") Duration connectTimeout,

        @NotNull @DefaultValue("30s") Duration readTimeout,

        @Min(0) @Max(10) @DefaultValue("3") int maxRetries,

        @DefaultValue("false") boolean sandboxMode,

        @DefaultValue({"TWD", "USD"}) List<String> allowedCurrencies,

        Retry retry
) {

    public record Retry(
            @DefaultValue("1s") Duration initialInterval,
            @DefaultValue("2.0") double multiplier,
            @DefaultValue("10s") Duration maxInterval
    ) {}
}

// 方式一: 在設定類別上宣告 (推薦, 意圖明確)
@Configuration
@EnableConfigurationProperties(PaymentProperties.class)
public class PaymentConfig { }

// 方式二: 掃描整個 package
@ConfigurationPropertiesScan("com.tutorial.order.config")
@SpringBootApplication
public class OrderServiceApplication { }

app:
  payment:
    gateway-url: https://payment.example.com/api
    merchant-id: MERCHANT-001
    connect-timeout: 3s
    read-timeout: 20s
    max-retries: 5
    sandbox-mode: false
    allowed-currencies:
      - TWD
      - USD
    retry:
      initial-interval: 500ms
      multiplier: 2.0
      max-interval: 8s

audit-spring-boot-starter/
├── pom.xml
└── src/main/
    ├── java/com/company/audit/
    │   ├── AuditProperties.java
    │   ├── AuditService.java
    │   ├── DefaultAuditService.java
    │   ├── AuditAspect.java
    │   ├── Auditable.java
    │   └── autoconfigure/
    │       └── AuditAutoConfiguration.java
    └── resources/META-INF/
        ├── spring/
        │   └── org.springframework.boot.autoconfigure.AutoConfiguration.imports
        └── additional-spring-configuration-metadata.json

<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

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

    <groupId>com.company.platform</groupId>
    <!-- ⚠️ 第三方 starter 命名: xxx-spring-boot-starter -->
    <artifactId>audit-spring-boot-starter</artifactId>
    <version>1.0.0</version>

    <properties>
        <java.version>25</java.version>
    </properties>

    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-aspectj</artifactId>
        </dependency>
        <!-- 產生設定 metadata, 提供 IDE 自動完成 -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-configuration-processor</artifactId>
            <optional>true</optional>
        </dependency>
    </dependencies>
</project>

package com.company.audit;

import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.boot.context.properties.bind.DefaultValue;

import java.util.List;

@ConfigurationProperties(prefix = "company.audit")
public record AuditProperties(

        @DefaultValue("true") boolean enabled,

        /** 稽核日誌輸出目標。 */
        @DefaultValue("LOG") Target target,

        /** 需要遮罩的欄位名稱。 */
        @DefaultValue({"password", "creditCardNo", "idNo"}) List<String> maskedFields,

        @DefaultValue("false") boolean includeArguments
) {

    public enum Target { LOG, DATABASE, KAFKA }
}

package com.company.audit;

public interface AuditService {
    void record(AuditEvent event);
}

package com.company.audit;

import java.time.Instant;

public record AuditEvent(
        String actor,
        String action,
        String resource,
        Instant occurredAt,
        String detail) {
}

package com.company.audit;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

public class DefaultAuditService implements AuditService {

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

    private final AuditProperties properties;

    public DefaultAuditService(AuditProperties properties) {
        this.properties = properties;
    }

    @Override
    public void record(AuditEvent event) {
        log.info("AUDIT actor={} action={} resource={} at={} detail={}",
                event.actor(), event.action(), event.resource(),
                event.occurredAt(), mask(event.detail()));
    }

    private String mask(String detail) {
        if (detail == null) {
            return null;
        }
        String result = detail;
        for (String field : properties.maskedFields()) {
            result = result.replaceAll("(?i)(\"" + field + "\"\\s*:\\s*\")[^\"]*(\")", "$1***$2");
        }
        return result;
    }
}

package com.company.audit;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface Auditable {
    String action();
    String resource() default "";
}

package com.company.audit;

import org.aspectj.lang.ProceedingJoinPoint;
import org.aspectj.lang.annotation.Around;
import org.aspectj.lang.annotation.Aspect;

import java.time.Instant;
import java.util.Arrays;

@Aspect
public class AuditAspect {

    private final AuditService auditService;
    private final AuditProperties properties;

    public AuditAspect(AuditService auditService, AuditProperties properties) {
        this.auditService = auditService;
        this.properties = properties;
    }

    @Around("@annotation(auditable)")
    public Object audit(ProceedingJoinPoint pjp, Auditable auditable) throws Throwable {
        Object result = pjp.proceed();
        String detail = properties.includeArguments()
                ? Arrays.toString(pjp.getArgs())
                : null;
        auditService.record(new AuditEvent(
                currentActor(), auditable.action(), auditable.resource(),
                Instant.now(), detail));
        return result;
    }

    // 實務上應從 SecurityContextHolder 取得
    private String currentActor() {
        return "SYSTEM";
    }
}

package com.company.audit.autoconfigure;

import com.company.audit.AuditAspect;
import com.company.audit.AuditProperties;
import com.company.audit.AuditService;
import com.company.audit.DefaultAuditService;
import org.springframework.boot.autoconfigure.AutoConfiguration;
import org.springframework.boot.autoconfigure.condition.ConditionalOnClass;
import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean;
import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
import org.springframework.boot.context.properties.EnableConfigurationProperties;
import org.springframework.context.annotation.Bean;

@AutoConfiguration
@ConditionalOnClass(org.aspectj.lang.annotation.Aspect.class)
@ConditionalOnProperty(prefix = "company.audit", name = "enabled", havingValue = "true", matchIfMissing = true)
@EnableConfigurationProperties(AuditProperties.class)
public class AuditAutoConfiguration {

    @Bean
    @ConditionalOnMissingBean   // 讓使用者可以自行覆寫
    AuditService auditService(AuditProperties properties) {
        return new DefaultAuditService(properties);
    }

    @Bean
    @ConditionalOnMissingBean
    AuditAspect auditAspect(AuditService auditService, AuditProperties properties) {
        return new AuditAspect(auditService, properties);
    }
}

com.company.audit.autoconfigure.AuditAutoConfiguration

{
  "properties": [
    {
      "name": "company.audit.enabled",
      "type": "java.lang.Boolean",
      "description": "是否啟用稽核日誌功能。",
      "defaultValue": true
    },
    {
      "name": "company.audit.target",
      "type": "com.company.audit.AuditProperties$Target",
      "description": "稽核日誌輸出目標。",
      "defaultValue": "LOG"
    },
    {
      "name": "company.audit.masked-fields",
      "type": "java.util.List<java.lang.String>",
      "description": "需要遮罩的欄位名稱清單。"
    }
  ],
  "hints": [
    {
      "name": "company.audit.target",
      "values": [
        { "value": "LOG", "description": "輸出到應用日誌。" },
        { "value": "DATABASE", "description": "寫入稽核資料表。" },
        { "value": "KAFKA", "description": "發送到 Kafka topic。" }
      ]
    }
  ]
}

@Service
public class OrderService {

    @Auditable(action = "PLACE_ORDER", resource = "order")
    public Order placeOrder(PlaceOrderCommand command) {
        // 業務邏輯
        return null;
    }
}

// 在共用模組 company-common 中
package com.company.common.http;

import org.springframework.boot.context.properties.ConfigurationPropertiesSource;

import java.time.Duration;

@ConfigurationPropertiesSource   // 🆕 標記此型別需產生設定 metadata
public record HttpClientSettings(
        Duration connectTimeout,
        Duration readTimeout,
        int maxConnections) {
}

// 在應用模組中直接引用, IDE 仍能提供 app.upstream.http.connect-timeout 的提示
@ConfigurationProperties(prefix = "app.upstream")
public record UpstreamProperties(String baseUrl, HttpClientSettings http) {
}

package com.company.audit.autoconfigure;

import com.company.audit.AuditService;
import org.junit.jupiter.api.Test;
import org.springframework.boot.autoconfigure.AutoConfigurations;
import org.springframework.boot.test.context.runner.ApplicationContextRunner;

import static org.assertj.core.api.Assertions.assertThat;

class AuditAutoConfigurationTest {

    private final ApplicationContextRunner runner = new ApplicationContextRunner()
            .withConfiguration(AutoConfigurations.of(AuditAutoConfiguration.class));

    @Test
    void 預設應註冊_AuditService() {
        runner.run(context -> assertThat(context).hasSingleBean(AuditService.class));
    }

    @Test
    void 設為_disabled_時不應註冊() {
        runner.withPropertyValues("company.audit.enabled=false")
                .run(context -> assertThat(context).doesNotHaveBean(AuditService.class));
    }

    @Test
    void 使用者自訂_Bean_應優先() {
        runner.withUserConfiguration(CustomAuditConfig.class)
                .run(context -> assertThat(context.getBean(AuditService.class))
                        .isInstanceOf(CustomAuditService.class));
    }
}

@ConfigurationProperties(prefix = "app.payment")
public record PaymentProperties(String apiKey) {}

management:
  endpoint:
    configprops:
      show-values: NEVER   # 或 WHEN_AUTHORIZED
    env:
      show-values: NEVER

# 1. 命令列參數 (最高優先)
java -jar app.jar --spring.profiles.active=prod

# 2. 環境變數 (容器化首選)
$env:SPRING_PROFILES_ACTIVE = "prod"

# 3. JVM 系統屬性
java -Dspring.profiles.active=prod -jar app.jar

# application.yml
spring:
  profiles:
    group:
      prod:
        - prod-db
        - prod-cache
        - prod-security
        - metrics-on
      local:
        - local-db
        - mock-external

package com.tutorial.order.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Profile;

@Configuration
public class NotificationConfig {

    @Bean
    @Profile("prod")
    NotificationSender realSender(SmsClient client) {
        return new SmsNotificationSender(client);
    }

    @Bean
    @Profile("!prod")   // 非 prod 環境
    NotificationSender mockSender() {
        return event -> System.out.println("[MOCK] 發送通知: " + event);
    }
}

# ===== application.yml — 所有環境共通 =====
spring:
  application:
    name: order-service
  jackson:
    default-property-inclusion: non_null
    # 🆕 4.1: 通用讀寫特性可用 read/write 前綴設定
    write:
      dates-as-timestamps: false
  threads:
    virtual:
      enabled: true
  jpa:
    open-in-view: false          # ⚠️ 務必關閉, 預設 true 會造成連線佔用過久

server:
  shutdown: graceful             # 優雅關閉, 搭配 K8s preStop
  compression:
    enabled: true
  error:
    include-message: never       # 🔒 不要把例外訊息回傳給用戶端
    include-stacktrace: never
    include-binding-errors: never

management:
  endpoints:
    web:
      exposure:
        include: health,info,metrics,prometheus
  endpoint:
    health:
      probes:
        enabled: true            # 提供 liveness / readiness 子端點
      show-details: when-authorized
    configprops:
      show-values: never         # 🔒
    env:
      show-values: never         # 🔒

app:
  order:
    max-items-per-order: 100
    default-currency: TWD

logging:
  level:
    root: INFO

# ===== application-dev.yml =====
spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/orderdb
    username: dev
    password: dev      # ⚠️ 僅限本機開發, 正式環境絕不寫死
  jpa:
    hibernate:
      ddl-auto: update
    show-sql: true
    properties:
      hibernate:
        format_sql: true

logging:
  level:
    com.tutorial: DEBUG
    org.springframework.web: DEBUG
    org.hibernate.SQL: DEBUG

management:
  endpoints:
    web:
      exposure:
        include: "*"     # 開發環境全開, 方便除錯

# ===== application-prod.yml =====
spring:
  datasource:
    # 一律從環境變數注入, 不寫死
    url: ${SPRING_DATASOURCE_URL}
    username: ${SPRING_DATASOURCE_USERNAME}
    password: ${SPRING_DATASOURCE_PASSWORD}
    hikari:
      maximum-pool-size: 20
      minimum-idle: 5
      connection-timeout: 3000
      max-lifetime: 1200000
  jpa:
    hibernate:
      ddl-auto: validate      # ⚠️ 正式環境絕不用 update 或 create
    show-sql: false
  config:
    import:
      - "optional:configtree:/run/secrets/"   # K8s Secret

server:
  port: 8080
  tomcat:
    threads:
      max: 200
    accept-count: 100

logging:
  level:
    root: WARN
    com.tutorial: INFO

spring:
  config:
    import:
      # 檔案不存在也不報錯
      - "optional:file:./config/override.yml"
      # K8s Secret 掛載目錄 (每個檔名 = 屬性名, 內容 = 屬性值)
      - "optional:configtree:/run/secrets/"
      # 🆕 4.1: 指定編碼, 解決中文 properties 亂碼
      - "classpath:messages/legacy.properties[encoding=utf-8]"

/run/secrets/
├── spring.datasource.password      → spring.datasource.password
├── app.payment.api-key             → app.payment.api-key
└── jwt.signing-key                 → jwt.signing-key

apiVersion: v1
kind: Secret
metadata:
  name: order-service-secrets
stringData:
  spring.datasource.password: "實際密碼"
  app.payment.api-key: "實際金鑰"
---
apiVersion: apps/v1
kind: Deployment
spec:
  template:
    spec:
      containers:
        - name: order-service
          volumeMounts:
            - name: secrets
              mountPath: /run/secrets
              readOnly: true
      volumes:
        - name: secrets
          secret:
            secretName: order-service-secrets

<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-vault-config</artifactId>
</dependency>

spring:
  config:
    import: "vault://secret/order-service"
  cloud:
    vault:
      uri: ${VAULT_ADDR}
      authentication: KUBERNETES
      kubernetes:
        role: order-service
        service-account-token-file: /var/run/secrets/kubernetes.io/serviceaccount/token
      kv:
        enabled: true
        backend: secret

<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-bootstrap</artifactId>
</dependency>

package com.tutorial.order.config;

import org.springframework.beans.factory.annotation.Value;
import org.springframework.cloud.context.config.annotation.RefreshScope;
import org.springframework.stereotype.Component;

@Component
@RefreshScope   // 呼叫 /actuator/refresh 後會重新建立此 Bean
public class FeatureToggle {

    private final boolean newPricingEnabled;

    public FeatureToggle(@Value("${app.feature.new-pricing:false}") boolean newPricingEnabled) {
        this.newPricingEnabled = newPricingEnabled;
    }
}

spring:
  datasource:
    hikari:
      # ⚡ 連線池大小公式: 核心數 * 2 + 有效磁碟數
      # 不是越大越好, 過大會造成資料庫端 context switch 成本上升
      maximum-pool-size: 20
      minimum-idle: 5
      connection-timeout: 3000     # 取不到連線就快速失敗
      idle-timeout: 600000
      max-lifetime: 1200000        # 應小於資料庫端的 wait_timeout
      leak-detection-threshold: 60000

server:
  tomcat:
    threads:
      max: 200          # 用虛擬執行緒時此值意義降低
      min-spare: 20
    accept-count: 100
    max-connections: 8192
    connection-timeout: 20000
  compression:
    enabled: true
    min-response-size: 2048
    # 🆕 4.1: 可加入額外要壓縮的 MIME 類型
    additional-mime-types: application/problem+json

spring:
  ssl:
    bundle:
      jks:
        server:
          key:
            alias: server
          keystore:
            location: /run/secrets/keystore.p12
            password: ${KEYSTORE_PASSWORD}
            type: PKCS12
server:
  ssl:
    bundle: server

logging:
  level:
    root: INFO
    com.tutorial: DEBUG
    org.springframework.web: INFO
    org.hibernate.SQL: DEBUG
    org.hibernate.orm.jdbc.bind: TRACE   # Hibernate 6+ 顯示參數值
  pattern:
    console: "%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n"
  file:
    name: logs/order-service.log
  logback:
    rollingpolicy:
      max-file-size: 100MB
      max-history: 30
      total-size-cap: 3GB

logging:
  structured:
    format:
      console: ecs      # ecs (Elastic) | gelf (Graylog) | logstash
      file: ecs
  file:
    name: logs/order-service.json

{
  "@timestamp": "2026-07-31T10:23:45.123Z",
  "log.level": "INFO",
  "process.pid": 1234,
  "process.thread.name": "http-nio-8080-exec-1",
  "service.name": "order-service",
  "log.logger": "com.tutorial.order.OrderService",
  "message": "訂單建立成功",
  "orderId": "ORD-20260731-0001",
  "trace.id": "8f2a1b3c4d5e6f70",
  "span.id": "1a2b3c4d"
}

logging:
  structured:
    ecs:
      service:
        name: order-service
        version: 1.0.0
        environment: production
        node-name: ${HOSTNAME:unknown}

package com.tutorial.order.web;

import jakarta.servlet.FilterChain;
import jakarta.servlet.ServletException;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import org.slf4j.MDC;
import org.springframework.core.annotation.Order;
import org.springframework.stereotype.Component;
import org.springframework.web.filter.OncePerRequestFilter;

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

@Component
@Order(1)
public class RequestContextFilter extends OncePerRequestFilter {

    private static final String REQUEST_ID = "requestId";
    private static final String USER_ID = "userId";

    @Override
    protected void doFilterInternal(HttpServletRequest request,
                                    HttpServletResponse response,
                                    FilterChain chain) throws ServletException, IOException {
        String requestId = request.getHeader("X-Request-Id");
        if (requestId == null || requestId.isBlank()) {
            requestId = UUID.randomUUID().toString();
        }
        MDC.put(REQUEST_ID, requestId);
        MDC.put(USER_ID, resolveUserId(request));
        response.setHeader("X-Request-Id", requestId);
        try {
            chain.doFilter(request, response);
        } finally {
            // ⚠️ 一定要清除, 否則執行緒池重用時會污染下一個請求
            MDC.clear();
        }
    }

    private String resolveUserId(HttpServletRequest request) {
        return request.getUserPrincipal() != null
                ? request.getUserPrincipal().getName()
                : "anonymous";
    }
}

logging:
  pattern:
    console: "%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level [req=%X{requestId} user=%X{userId}] %logger{36} - %msg%n"

package com.tutorial.order.config;

import org.slf4j.MDC;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.task.TaskDecorator;

import java.util.Map;

@Configuration
public class AsyncMdcConfig {

    @Bean
    TaskDecorator mdcTaskDecorator() {
        return runnable -> {
            Map<String, String> parentContext = MDC.getCopyOfContextMap();
            return () -> {
                if (parentContext != null) {
                    MDC.setContextMap(parentContext);
                }
                try {
                    runnable.run();
                } finally {
                    MDC.clear();
                }
            };
        };
    }
}

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
    <include resource="org/springframework/boot/logging/logback/defaults.xml"/>

    <springProperty scope="context" name="appName" source="spring.application.name"/>

    <!-- 開發環境: 人類可讀 -->
    <springProfile name="dev,local">
        <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
            <encoder>
                <pattern>%d{HH:mm:ss.SSS} %highlight(%-5level) %cyan(%logger{20}) [req=%X{requestId}] - %msg%n</pattern>
            </encoder>
        </appender>
        <root level="INFO">
            <appender-ref ref="CONSOLE"/>
        </root>
    </springProfile>

    <!-- 正式環境: 結構化 JSON, 只輸出到 stdout -->
    <springProfile name="prod,stage">
        <appender name="JSON" class="ch.qos.logback.core.ConsoleAppender">
            <encoder class="org.springframework.boot.logging.logback.StructuredLogEncoder">
                <format>ecs</format>
            </encoder>
        </appender>
        <root level="WARN">
            <appender-ref ref="JSON"/>
        </root>
        <logger name="com.tutorial" level="INFO"/>
    </springProfile>
</configuration>

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
    <exclusions>
        <exclusion>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-logging</artifactId>
        </exclusion>
    </exclusions>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-log4j2</artifactId>
</dependency>

// ✅ 正確: 用參數化, 等級未啟用時不會做字串串接
log.debug("處理訂單 orderId={} items={}", orderId, itemCount);

// ❌ 錯誤: 無論等級是否啟用都會執行串接
log.debug("處理訂單 orderId=" + orderId + " items=" + itemCount);

// ✅ 昂貴運算用 lambda (SLF4J 2.x fluent API)
log.atDebug()
   .addArgument(() -> expensiveSerialization(order))
   .log("訂單詳情: {}");

// ✅ 記錄例外: 例外物件放最後一個參數, 不要用字串串接
log.error("付款失敗 orderId={}", orderId, exception);

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

<!-- Logback 非同步 Appender -->
<appender name="ASYNC" class="ch.qos.logback.classic.AsyncAppender">
    <queueSize>8192</queueSize>
    <discardingThreshold>0</discardingThreshold>  <!-- 0 = 不丟棄任何日誌 -->
    <neverBlock>false</neverBlock>                 <!-- true = 佇列滿時丟棄而非阻塞 -->
    <appender-ref ref="JSON"/>
</appender>

// 昂貴運算前先檢查等級
if (log.isDebugEnabled()) {
    log.debug("完整訂單內容: {}", objectMapper.writeValueAsString(order));
}

package com.tutorial.order.common;

public final class MaskUtils {

    private MaskUtils() {}

    /** 身分證號遮罩: A123456789 → A12****789 */
    public static String maskIdNo(String idNo) {
        if (idNo == null || idNo.length() < 6) {
            return "***";
        }
        return idNo.substring(0, 3) + "****" + idNo.substring(idNo.length() - 3);
    }

    /** 信用卡遮罩: 只保留末四碼 */
    public static String maskCardNo(String cardNo) {
        if (cardNo == null || cardNo.length() < 4) {
            return "****";
        }
        return "**** **** **** " + cardNo.substring(cardNo.length() - 4);
    }
}

// ❌ 危險: 使用者可輸入 "abc\nINFO 假的日誌行"
log.info("使用者查詢: {}", userInput);

// ✅ 安全: 先清除控制字元
log.info("使用者查詢: {}", userInput.replaceAll("[\\r\\n]", "_"));

package com.tutorial.order.web;

import com.tutorial.order.web.dto.CreateOrderRequest;
import com.tutorial.order.web.dto.OrderResponse;
import com.tutorial.order.web.dto.PageResponse;
import jakarta.validation.Valid;
import jakarta.validation.constraints.Min;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.validation.annotation.Validated;
import org.springframework.web.bind.annotation.*;
import org.springframework.web.util.UriComponentsBuilder;

import java.net.URI;

@RestController
@RequestMapping("/api/orders")
@Validated
public class OrderController {

    private final OrderApplicationService orderService;

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

    @PostMapping
    ResponseEntity<OrderResponse> create(@Valid @RequestBody CreateOrderRequest request,
                                         UriComponentsBuilder uriBuilder) {
        OrderResponse created = orderService.create(request);
        URI location = uriBuilder.path("/api/orders/{id}")
                .buildAndExpand(created.id())
                .toUri();
        return ResponseEntity.created(location).body(created);
    }

    @GetMapping("/{id}")
    OrderResponse findById(@PathVariable String id) {
        return orderService.findById(id);
    }

    @GetMapping
    PageResponse<OrderResponse> search(
            @RequestParam(required = false) String customerId,
            @RequestParam(required = false) String status,
            @RequestParam(defaultValue = "0") @Min(0) int page,
            @RequestParam(defaultValue = "20") @Min(1) int size) {
        return orderService.search(customerId, status, page, size);
    }

    @PatchMapping("/{id}/status")
    OrderResponse updateStatus(@PathVariable String id,
                               @Valid @RequestBody UpdateStatusRequest request) {
        return orderService.updateStatus(id, request.status());
    }

    @DeleteMapping("/{id}")
    @ResponseStatus(HttpStatus.NO_CONTENT)
    void cancel(@PathVariable String id) {
        orderService.cancel(id);
    }
}

package com.tutorial.order.web.dto;

import jakarta.validation.Valid;
import jakarta.validation.constraints.*;

import java.util.List;

public record CreateOrderRequest(

        @NotBlank(message = "客戶編號不可為空")
        @Size(max = 32, message = "客戶編號長度不可超過 {max}")
        String customerId,

        @NotEmpty(message = "訂單至少要有一個品項")
        @Size(max = 100, message = "單筆訂單品項數不可超過 {max}")
        @Valid
        List<OrderLineRequest> lines,

        @Pattern(regexp = "TWD|USD|JPY", message = "幣別僅支援 TWD、USD、JPY")
        String currency,

        @Size(max = 500)
        String remark) {

    public record OrderLineRequest(

            @NotBlank(message = "商品編號不可為空")
            String sku,

            @Min(value = 1, message = "數量至少為 {value}")
            @Max(value = 999, message = "單一品項數量不可超過 {value}")
            int quantity) {
    }
}

package com.tutorial.order.web.dto;

import com.fasterxml.jackson.annotation.JsonFormat;

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

public record OrderResponse(
        String id,
        String customerId,
        String status,
        BigDecimal totalAmount,
        String currency,
        List<OrderLineResponse> lines,

        @JsonFormat(shape = JsonFormat.Shape.STRING, pattern = "yyyy-MM-dd'T'HH:mm:ss'Z'", timezone = "UTC")
        Instant createdAt) {

    public record OrderLineResponse(String sku, String productName, int quantity, BigDecimal subtotal) {}
}

package com.tutorial.order.web;

import com.tutorial.order.domain.exception.BusinessRuleViolationException;
import com.tutorial.order.domain.exception.OrderNotFoundException;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.http.HttpStatus;
import org.springframework.http.ProblemDetail;
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 java.net.URI;
import java.time.Instant;
import java.util.List;
import java.util.Map;

@RestControllerAdvice
public class GlobalExceptionHandler {

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

    @ExceptionHandler(OrderNotFoundException.class)
    ProblemDetail handleNotFound(OrderNotFoundException ex) {
        ProblemDetail problem = ProblemDetail.forStatusAndDetail(
                HttpStatus.NOT_FOUND, "找不到指定的訂單");
        problem.setType(URI.create("https://api.company.com/errors/order-not-found"));
        problem.setTitle("訂單不存在");
        problem.setProperty("orderId", ex.getOrderId());
        problem.setProperty("timestamp", Instant.now());
        return problem;
    }

    @ExceptionHandler(MethodArgumentNotValidException.class)
    ProblemDetail handleValidation(MethodArgumentNotValidException ex) {
        List<Map<String, String>> errors = ex.getBindingResult().getFieldErrors().stream()
                .map(error -> Map.of(
                        "field", error.getField(),
                        "message", error.getDefaultMessage() == null ? "驗證失敗" : error.getDefaultMessage()))
                .toList();

        ProblemDetail problem = ProblemDetail.forStatusAndDetail(
                HttpStatus.BAD_REQUEST, "請求內容驗證失敗");
        problem.setType(URI.create("https://api.company.com/errors/validation-failed"));
        problem.setTitle("參數驗證失敗");
        problem.setProperty("errors", errors);
        problem.setProperty("timestamp", Instant.now());
        return problem;
    }

    @ExceptionHandler(BusinessRuleViolationException.class)
    ProblemDetail handleBusinessRule(BusinessRuleViolationException ex) {
        ProblemDetail problem = ProblemDetail.forStatusAndDetail(
                HttpStatus.UNPROCESSABLE_ENTITY, ex.getMessage());
        problem.setType(URI.create("https://api.company.com/errors/business-rule-violation"));
        problem.setTitle("業務規則不符");
        problem.setProperty("ruleCode", ex.getRuleCode());
        return problem;
    }

    @ExceptionHandler(Exception.class)
    ProblemDetail handleUnexpected(Exception ex, WebRequest request) {
        // 🔒 內部細節只寫進日誌, 不回傳給用戶端
        log.error("未預期的例外, path={}", request.getDescription(false), ex);

        ProblemDetail problem = ProblemDetail.forStatusAndDetail(
                HttpStatus.INTERNAL_SERVER_ERROR, "系統發生非預期錯誤，請聯繫系統管理員");
        problem.setType(URI.create("https://api.company.com/errors/internal-error"));
        problem.setTitle("系統錯誤");
        problem.setProperty("timestamp", Instant.now());
        return problem;
    }
}

{
  "type": "https://api.company.com/errors/validation-failed",
  "title": "參數驗證失敗",
  "status": 400,
  "detail": "請求內容驗證失敗",
  "instance": "/api/orders",
  "errors": [
    { "field": "customerId", "message": "客戶編號不可為空" },
    { "field": "lines[0].quantity", "message": "數量至少為 1" }
  ],
  "timestamp": "2026-07-31T10:23:45.123Z"
}

spring:
  mvc:
    apiversion:
      # 版本來源: header / query / path-segment / media-type-parameter
      use:
        header: X-API-Version
      # 未指定版本時的預設值
      default-version: "1.0"
      # 是否要求請求必須帶版本
      required: false
      supported:
        - "1.0"
        - "2.0"

package com.tutorial.order.web;

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;

@RestController
@RequestMapping("/api/orders")
public class VersionedOrderController {

    // 只有 X-API-Version: 1.0 的請求會進來
    @GetMapping(path = "/{id}", version = "1.0")
    OrderResponseV1 findByIdV1(@PathVariable String id) {
        return orderService.findByIdV1(id);
    }

    // X-API-Version: 2.0 走這個, 回應結構不同
    @GetMapping(path = "/{id}", version = "2.0")
    OrderResponseV2 findByIdV2(@PathVariable String id) {
        return orderService.findByIdV2(id);
    }
}

package com.tutorial.order.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.accept.ApiVersionDeprecationHandler;

@Configuration
public class ApiVersionConfig {

    @Bean
    ApiVersionDeprecationHandler deprecationHandler() {
        return (version, request, response) -> {
            if ("1.0".equals(version.toString())) {
                response.setHeader("Deprecation", "true");
                response.setHeader("Sunset", "Wed, 31 Dec 2026 23:59:59 GMT");
                response.setHeader("Link", "<https://api.company.com/docs/v2>; rel=\"successor-version\"");
            }
        };
    }
}

package com.tutorial.order.client;

import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestHeader;
import org.springframework.web.service.annotation.GetExchange;
import org.springframework.web.service.annotation.HttpExchange;
import org.springframework.web.service.annotation.PostExchange;

@HttpExchange(url = "/api/payments", accept = "application/json")
public interface PaymentClient {

    @PostExchange
    PaymentResponse charge(@RequestBody ChargeRequest request);

    @GetExchange("/{paymentId}")
    PaymentResponse findById(@PathVariable String paymentId);

    @PostExchange("/{paymentId}/refund")
    RefundResponse refund(@PathVariable String paymentId,
                          @RequestBody RefundRequest request,
                          @RequestHeader("Idempotency-Key") String idempotencyKey);
}

spring:
  http:
    client:
      # 全域預設
      connect-timeout: 3s
      read-timeout: 10s
      # 🆕 4.1: Cookie 處理策略
      cookie-handling: ignore
    serviceclient:
      payment:
        base-url: ${PAYMENT_SERVICE_URL}
        connect-timeout: 2s
        read-timeout: 5s

package com.tutorial.order.config;

import com.tutorial.order.client.PaymentClient;
import org.springframework.boot.autoconfigure.http.client.service.ImportHttpServices;
import org.springframework.context.annotation.Configuration;

@Configuration
@ImportHttpServices(group = "payment", types = PaymentClient.class)
public class HttpClientConfig {
}

@Service
public class PaymentService {

    private final PaymentClient paymentClient;

    public PaymentService(PaymentClient paymentClient) {
        this.paymentClient = paymentClient;
    }

    public PaymentResponse pay(Order order) {
        return paymentClient.charge(new ChargeRequest(
                order.id(), order.totalAmount(), order.currency()));
    }
}

spring:
  jackson:
    # 跨格式 (JSON / XML / CBOR) 通用的讀取特性
    read:
      fail-on-unknown-properties: false
    # 通用的寫入特性
    write:
      dates-as-timestamps: false
    # factory 層級的讀寫限制 (防禦超大 payload)
    factory:
      stream-read-constraints:
        max-string-length: 20000000
        max-nesting-depth: 1000

package com.tutorial.order.config;

import org.springframework.boot.autoconfigure.jackson.JsonFactoryBuilderCustomizer;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class JacksonConfig {

    @Bean
    JsonFactoryBuilderCustomizer jsonFactoryCustomizer() {
        return builder -> builder.streamReadConstraints(
                tools.jackson.core.StreamReadConstraints.builder()
                        .maxStringLength(20_000_000)
                        .build());
    }
}

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

package com.tutorial.order.config;

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

@Configuration
public class OpenApiConfig {

    @Bean
    OpenAPI orderServiceOpenApi() {
        return new OpenAPI()
                .info(new Info()
                        .title("訂單服務 API")
                        .version("2.0")
                        .description("提供訂單建立、查詢、狀態更新與取消功能")
                        .contact(new Contact().name("平台團隊").email("platform@company.com")))
                .schemaRequirement("bearerAuth", new SecurityScheme()
                        .type(SecurityScheme.Type.HTTP)
                        .scheme("bearer")
                        .bearerFormat("JWT"));
    }
}

springdoc:
  api-docs:
    # 🔒 正式環境關閉, 或限制存取
    enabled: ${SPRINGDOC_ENABLED:false}
  swagger-ui:
    enabled: ${SPRINGDOC_ENABLED:false}
    path: /swagger-ui.html

server:
  compression:
    enabled: true
    mime-types: application/json,application/problem+json,text/html,text/plain
    min-response-size: 2048
  tomcat:
    threads:
      max: 200
    max-http-form-post-size: 2MB
    max-swallow-size: 2MB

spring:
  threads:
    virtual:
      enabled: true      # ⚡ I/O 密集型 API 吞吐可提升數倍
  mvc:
    async:
      request-timeout: 30s

// ⚡ 大量資料用串流, 不要一次載入記憶體
@GetMapping(value = "/export", produces = "text/csv")
StreamingResponseBody export() {
    return outputStream -> {
        try (var writer = new BufferedWriter(new OutputStreamWriter(outputStream, StandardCharsets.UTF_8));
             var stream = orderRepository.streamAll()) {
            writer.write("id,customerId,amount\n");
            stream.forEach(order -> {
                try {
                    writer.write("%s,%s,%s%n".formatted(order.id(), order.customerId(), order.amount()));
                } catch (IOException e) {
                    throw new UncheckedIOException(e);
                }
            });
        }
    };
}

package com.tutorial.order.config;

import org.springframework.boot.http.client.InetAddressFilter;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class HttpSecurityConfig {

    /** 🔒 封鎖對內網位址的外送請求，防禦 SSRF。 */
    @Bean
    InetAddressFilter blockInternalAddresses() {
        return address -> !(address.isLoopbackAddress()
                || address.isSiteLocalAddress()
                || address.isLinkLocalAddress()
                || address.isAnyLocalAddress());
    }
}

@Bean
CorsConfigurationSource corsConfigurationSource() {
    CorsConfiguration config = new CorsConfiguration();
    config.setAllowedOrigins(List.of("https://app.company.com"));
    config.setAllowedMethods(List.of("GET", "POST", "PUT", "PATCH", "DELETE"));
    config.setAllowedHeaders(List.of("Authorization", "Content-Type", "X-API-Version"));
    config.setAllowCredentials(true);
    config.setMaxAge(3600L);

    UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource();
    source.registerCorsConfiguration("/api/**", config);
    return source;
}

package com.tutorial.order.persistence;

import jakarta.persistence.*;
import org.hibernate.annotations.CreationTimestamp;
import org.hibernate.annotations.UpdateTimestamp;

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

@Entity
@Table(name = "orders", indexes = {
        @Index(name = "idx_orders_customer_id", columnList = "customer_id"),
        @Index(name = "idx_orders_status_created", columnList = "status, created_at")
})
public class OrderEntity {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @Column(name = "order_no", nullable = false, unique = true, length = 32)
    private String orderNo;

    @Column(name = "customer_id", nullable = false, length = 32)
    private String customerId;

    @Enumerated(EnumType.STRING)   // ⚠️ 絕不用 ORDINAL, 列舉順序一改資料就全錯
    @Column(nullable = false, length = 20)
    private OrderStatus status;

    @Column(name = "total_amount", nullable = false, precision = 19, scale = 4)
    private BigDecimal totalAmount;

    // ⚠️ 集合預設就是 LAZY, 明確寫出來避免誤解
    @OneToMany(mappedBy = "order", cascade = CascadeType.ALL,
               orphanRemoval = true, fetch = FetchType.LAZY)
    private List<OrderLineEntity> lines = new ArrayList<>();

    @Version                       // 樂觀鎖: 併發更新時拋出 OptimisticLockingFailureException
    private Long version;

    @CreationTimestamp
    @Column(name = "created_at", nullable = false, updatable = false)
    private Instant createdAt;

    @UpdateTimestamp
    @Column(name = "updated_at")
    private Instant updatedAt;

    protected OrderEntity() {
        // JPA 需要無參數建構子
    }

    public OrderEntity(String orderNo, String customerId, BigDecimal totalAmount) {
        this.orderNo = orderNo;
        this.customerId = customerId;
        this.totalAmount = totalAmount;
        this.status = OrderStatus.CREATED;
    }

    /** 雙向關聯必須同時維護兩邊，否則 orphanRemoval 與快取會失準。 */
    public void addLine(OrderLineEntity line) {
        lines.add(line);
        line.setOrder(this);
    }

    public void removeLine(OrderLineEntity line) {
        lines.remove(line);
        line.setOrder(null);
    }

    // ⚠️ equals/hashCode 只用業務鍵, 不用 id (id 在 persist 前為 null)
    @Override
    public boolean equals(Object o) {
        if (this == o) {
            return true;
        }
        if (!(o instanceof OrderEntity other)) {
            return false;
        }
        return orderNo != null && orderNo.equals(other.orderNo);
    }

    @Override
    public int hashCode() {
        return Objects.hash(orderNo);
    }
}

package com.tutorial.order.persistence;

import org.springframework.data.domain.Page;
import org.springframework.data.domain.Pageable;
import org.springframework.data.jpa.repository.EntityGraph;
import org.springframework.data.jpa.repository.JpaRepository;
import org.springframework.data.jpa.repository.Query;
import org.springframework.data.repository.query.Param;

import java.time.Instant;
import java.util.List;
import java.util.Optional;

public interface OrderRepository extends JpaRepository<OrderEntity, Long> {

    Optional<OrderEntity> findByOrderNo(String orderNo);

    // ✅ 用 EntityGraph 一次載入關聯, 解決 N+1
    @EntityGraph(attributePaths = {"lines"})
    Optional<OrderEntity> findWithLinesByOrderNo(String orderNo);

    // ✅ 分頁查詢用 JOIN FETCH 時要搭配 countQuery
    @Query(value = """
            SELECT DISTINCT o FROM OrderEntity o
            LEFT JOIN FETCH o.lines
            WHERE o.customerId = :customerId
              AND o.createdAt >= :since
            """,
           countQuery = """
            SELECT COUNT(o) FROM OrderEntity o
            WHERE o.customerId = :customerId
              AND o.createdAt >= :since
            """)
    Page<OrderEntity> findByCustomerSince(@Param("customerId") String customerId,
                                          @Param("since") Instant since,
                                          Pageable pageable);

    // ✅ 只要部分欄位時用 Projection, 不要撈整個 Entity
    @Query("""
            SELECT new com.tutorial.order.persistence.OrderSummary(
                o.orderNo, o.customerId, o.status, o.totalAmount)
            FROM OrderEntity o
            WHERE o.status = :status
            """)
    List<OrderSummary> findSummariesByStatus(@Param("status") OrderStatus status);
}

package com.tutorial.order.persistence;

import java.math.BigDecimal;

/** 查詢投影，避免載入整個 Entity。 */
public record OrderSummary(String orderNo, String customerId,
                           OrderStatus status, BigDecimal totalAmount) {
}

package com.tutorial.order.report;

import org.springframework.jdbc.core.simple.JdbcClient;
import org.springframework.stereotype.Repository;

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

@Repository
public class OrderReportRepository {

    private final JdbcClient jdbcClient;

    public OrderReportRepository(JdbcClient jdbcClient) {
        this.jdbcClient = jdbcClient;
    }

    public List<DailySales> dailySales(LocalDate from, LocalDate to) {
        return jdbcClient.sql("""
                SELECT CAST(o.created_at AS DATE) AS sales_date,
                       COUNT(*)                   AS order_count,
                       SUM(o.total_amount)        AS total_amount
                FROM orders o
                WHERE o.status = 'COMPLETED'
                  AND o.created_at >= :from
                  AND o.created_at < :to
                GROUP BY CAST(o.created_at AS DATE)
                ORDER BY sales_date
                """)
                .param("from", from)
                .param("to", to)
                .query(DailySales.class)
                .list();
    }

    public record DailySales(LocalDate salesDate, long orderCount, BigDecimal totalAmount) {}
}

package com.tutorial.order.application;

import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Isolation;
import org.springframework.transaction.annotation.Propagation;
import org.springframework.transaction.annotation.Transactional;
import org.springframework.transaction.support.TransactionSynchronizationManager;
import org.springframework.transaction.support.TransactionSynchronization;

@Service
public class OrderApplicationService {

    private final OrderRepository orderRepository;
    private final PaymentClient paymentClient;
    private final ApplicationEventPublisher eventPublisher;

    public OrderApplicationService(OrderRepository orderRepository,
                                   PaymentClient paymentClient,
                                   ApplicationEventPublisher eventPublisher) {
        this.orderRepository = orderRepository;
        this.paymentClient = paymentClient;
        this.eventPublisher = eventPublisher;
    }

    // ✅ 查詢一律標 readOnly, Hibernate 會跳過 dirty checking, 效能明顯提升
    @Transactional(readOnly = true)
    public OrderResponse findByOrderNo(String orderNo) {
        return orderRepository.findWithLinesByOrderNo(orderNo)
                .map(OrderMapper::toResponse)
                .orElseThrow(() -> new OrderNotFoundException(orderNo));
    }

    @Transactional
    public OrderResponse create(CreateOrderRequest request) {
        OrderEntity order = OrderMapper.toEntity(request);
        orderRepository.save(order);

        // ⚠️ 絕不在交易中呼叫外部 API! 網路延遲會拉長交易時間, 拖垮連線池
        // 改為交易提交後才觸發
        eventPublisher.publishEvent(new OrderCreatedEvent(order.getOrderNo()));

        return OrderMapper.toResponse(order);
    }

    // 需要獨立交易 (例如稽核紀錄, 主交易失敗也要保留)
    @Transactional(propagation = Propagation.REQUIRES_NEW)
    public void recordAudit(String orderNo, String action) {
        // ...
    }

    // 高併發扣庫存: 悲觀鎖
    @Transactional(isolation = Isolation.READ_COMMITTED, timeout = 5)
    public void deductStock(String sku, int quantity) {
        // ...
    }
}

package com.tutorial.order.application;

import org.springframework.modulith.events.ApplicationModuleListener;
import org.springframework.stereotype.Component;
import org.springframework.transaction.event.TransactionPhase;
import org.springframework.transaction.event.TransactionalEventListener;

@Component
public class OrderCreatedHandler {

    private final PaymentClient paymentClient;

    public OrderCreatedHandler(PaymentClient paymentClient) {
        this.paymentClient = paymentClient;
    }

    /** 交易成功提交後才呼叫外部付款服務。 */
    @TransactionalEventListener(phase = TransactionPhase.AFTER_COMMIT)
    public void onOrderCreated(OrderCreatedEvent event) {
        paymentClient.charge(new ChargeRequest(event.orderNo()));
    }
}

<dependency>
    <groupId>org.flywaydb</groupId>
    <artifactId>flyway-core</artifactId>
</dependency>
<dependency>
    <groupId>org.flywaydb</groupId>
    <artifactId>flyway-database-postgresql</artifactId>
</dependency>

src/main/resources/db/migration/
├── V1__create_orders_table.sql
├── V2__create_order_lines_table.sql
├── V3__add_orders_status_index.sql
└── V4__add_orders_remark_column.sql

-- V1__create_orders_table.sql
CREATE TABLE orders (
    id           BIGSERIAL       PRIMARY KEY,
    order_no     VARCHAR(32)     NOT NULL UNIQUE,
    customer_id  VARCHAR(32)     NOT NULL,
    status       VARCHAR(20)     NOT NULL,
    total_amount NUMERIC(19, 4)  NOT NULL,
    version      BIGINT          NOT NULL DEFAULT 0,
    created_at   TIMESTAMPTZ     NOT NULL DEFAULT NOW(),
    updated_at   TIMESTAMPTZ
);

CREATE INDEX idx_orders_customer_id ON orders (customer_id);
CREATE INDEX idx_orders_status_created ON orders (status, created_at);

COMMENT ON TABLE orders IS '訂單主檔';
COMMENT ON COLUMN orders.status IS '訂單狀態: CREATED/PAID/SHIPPED/COMPLETED/CANCELLED';

spring:
  flyway:
    enabled: true
    baseline-on-migrate: true       # 既有資料庫首次導入時使用
    validate-on-migrate: true
    out-of-order: false             # ⚠️ 正式環境保持 false
    clean-disabled: true            # 🔒 防止意外清空資料庫
    locations: classpath:db/migration
  jpa:
    hibernate:
      ddl-auto: validate            # 由 Flyway 負責 DDL, JPA 只做驗證

// ❌ N+1: 1 次查訂單 + N 次查明細
List<OrderEntity> orders = orderRepository.findByCustomerId(customerId);
orders.forEach(o -> o.getLines().size());   // 每次觸發一次 SQL

// ✅ 1 次查完
@EntityGraph(attributePaths = {"lines"})
List<OrderEntity> findByCustomerId(String customerId);

logging:
  level:
    org.hibernate.SQL: DEBUG
spring:
  jpa:
    properties:
      hibernate:
        generate_statistics: true

spring:
  jpa:
    properties:
      hibernate:
        jdbc:
          batch_size: 50              # ⚡ 批次寫入
          fetch_size: 100
        order_inserts: true           # 讓 batch 更有效
        order_updates: true
        batch_versioned_data: true
        query:
          in_clause_parameter_padding: true   # ⚡ 提升執行計畫快取命中率
        generate_statistics: false    # 正式環境關閉
  datasource:
    hikari:
      maximum-pool-size: 20
      minimum-idle: 5
      connection-timeout: 3000
      max-lifetime: 1200000
    # 🆕 4.1: 延遲取得連線, 進入交易但沒查詢時不佔連線
    connection-fetch: lazy

@Transactional
public void bulkImport(List<OrderEntity> orders) {
    int batchSize = 50;
    for (int i = 0; i < orders.size(); i++) {
        entityManager.persist(orders.get(i));
        if (i > 0 && i % batchSize == 0) {
            entityManager.flush();
            entityManager.clear();   // ⚠️ 一定要 clear, 否則 persistence context 無限成長導致 OOM
        }
    }
}

// ❌ 危險: 使用者可注入任意 SQL
String sql = "SELECT * FROM orders ORDER BY " + sortColumn;

// ✅ 安全: 白名單驗證
private static final Set<String> ALLOWED_SORT = Set.of("created_at", "total_amount", "status");

if (!ALLOWED_SORT.contains(sortColumn)) {
    throw new IllegalArgumentException("不支援的排序欄位");
}

@Converter
public class EncryptedStringConverter implements AttributeConverter<String, String> {

    private final TextEncryptor encryptor;

    public EncryptedStringConverter(TextEncryptor encryptor) {
        this.encryptor = encryptor;
    }

    @Override
    public String convertToDatabaseColumn(String attribute) {
        return attribute == null ? null : encryptor.encrypt(attribute);
    }

    @Override
    public String convertToEntityAttribute(String dbData) {
        return dbData == null ? null : encryptor.decrypt(dbData);
    }
}

package com.tutorial.order.persistence;

import org.junit.jupiter.api.Test;
import org.springframework.boot.test.autoconfigure.jdbc.AutoConfigureTestDatabase;
import org.springframework.boot.test.autoconfigure.orm.jpa.DataJpaTest;
import org.springframework.boot.testcontainers.service.connection.ServiceConnection;
import org.springframework.test.context.bean.override.mockito.MockitoBean;
import org.testcontainers.containers.PostgreSQLContainer;
import org.testcontainers.junit.jupiter.Container;
import org.testcontainers.junit.jupiter.Testcontainers;

import static org.assertj.core.api.Assertions.assertThat;

@DataJpaTest
@AutoConfigureTestDatabase(replace = AutoConfigureTestDatabase.Replace.NONE)
@Testcontainers
class OrderRepositoryTest {

    @Container
    @ServiceConnection
    static PostgreSQLContainer<?> postgres = new PostgreSQLContainer<>("postgres:17-alpine");

    private final OrderRepository repository;

    OrderRepositoryTest(OrderRepository repository) {
        this.repository = repository;
    }

    @Test
    void 應能依訂單編號查詢並一次載入明細() {
        OrderEntity order = new OrderEntity("ORD-001", "CUST-001", new BigDecimal("1000.00"));
        order.addLine(new OrderLineEntity("SKU-001", 2, new BigDecimal("500.00")));
        repository.save(order);

        var found = repository.findWithLinesByOrderNo("ORD-001");

        assertThat(found).isPresent();
        assertThat(found.get().getLines()).hasSize(1);
    }
}

package com.tutorial.order.security;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.HttpMethod;
import org.springframework.security.config.Customizer;
import org.springframework.security.config.annotation.method.configuration.EnableMethodSecurity;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.http.SessionCreationPolicy;
import org.springframework.security.crypto.bcrypt.BCryptPasswordEncoder;
import org.springframework.security.crypto.password.PasswordEncoder;
import org.springframework.security.web.SecurityFilterChain;
import org.springframework.web.cors.CorsConfiguration;
import org.springframework.web.cors.CorsConfigurationSource;
import org.springframework.web.cors.UrlBasedCorsConfigurationSource;

import java.util.List;

@Configuration
@EnableMethodSecurity   // 啟用 @PreAuthorize / @PostAuthorize
public class SecurityConfig {

    @Bean
    SecurityFilterChain apiFilterChain(HttpSecurity http) throws Exception {
        return http
                .securityMatcher("/api/**")
                // 無狀態 JWT API 不需要 CSRF
                .csrf(csrf -> csrf.disable())
                .cors(cors -> cors.configurationSource(corsConfigurationSource()))
                .sessionManagement(session ->
                        session.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
                .authorizeHttpRequests(auth -> auth
                        .requestMatchers(HttpMethod.GET, "/api/public/**").permitAll()
                        .requestMatchers("/api/admin/**").hasRole("ADMIN")
                        .requestMatchers(HttpMethod.POST, "/api/orders").hasAuthority("SCOPE_order:write")
                        .requestMatchers(HttpMethod.GET, "/api/orders/**").hasAuthority("SCOPE_order:read")
                        // ⚠️ 一定要有 anyRequest, 且應為 authenticated 而非 permitAll
                        .anyRequest().authenticated())
                .oauth2ResourceServer(oauth2 -> oauth2.jwt(Customizer.withDefaults()))
                .exceptionHandling(ex -> ex
                        .authenticationEntryPoint(new ProblemDetailAuthenticationEntryPoint())
                        .accessDeniedHandler(new ProblemDetailAccessDeniedHandler()))
                .headers(headers -> headers
                        .contentSecurityPolicy(csp ->
                                csp.policyDirectives("default-src 'self'; frame-ancestors 'none'"))
                        .frameOptions(frame -> frame.deny())
                        .httpStrictTransportSecurity(hsts -> hsts
                                .includeSubDomains(true)
                                .maxAgeInSeconds(31_536_000)))
                .build();
    }

    /** Actuator 使用獨立的 filter chain。 */
    @Bean
    SecurityFilterChain actuatorFilterChain(HttpSecurity http) throws Exception {
        return http
                .securityMatcher("/actuator/**")
                .authorizeHttpRequests(auth -> auth
                        .requestMatchers("/actuator/health/**", "/actuator/info").permitAll()
                        .anyRequest().hasRole("MONITORING"))
                .httpBasic(Customizer.withDefaults())
                .csrf(csrf -> csrf.disable())
                .build();
    }

    @Bean
    PasswordEncoder passwordEncoder() {
        // 🔒 strength 至少 10, 12 為建議值 (依硬體調整, 目標約 250ms)
        return new BCryptPasswordEncoder(12);
    }

    @Bean
    CorsConfigurationSource corsConfigurationSource() {
        CorsConfiguration config = new CorsConfiguration();
        config.setAllowedOrigins(List.of("https://app.company.com"));
        config.setAllowedMethods(List.of("GET", "POST", "PUT", "PATCH", "DELETE"));
        config.setAllowedHeaders(List.of("Authorization", "Content-Type", "X-API-Version", "Idempotency-Key"));
        config.setExposedHeaders(List.of("X-Request-Id"));
        config.setAllowCredentials(true);
        config.setMaxAge(3600L);

        UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource();
        source.registerCorsConfiguration("/api/**", config);
        return source;
    }
}

spring:
  security:
    oauth2:
      resourceserver:
        jwt:
          issuer-uri: https://auth.company.com/realms/order
          # 或直接指定 JWK Set
          jwk-set-uri: https://auth.company.com/realms/order/protocol/openid-connect/certs
          audiences:
            - order-service
          # 🆕 4.1: 用 SpEL 從巢狀 claim 取出權限
          authorities-claim-expressions:
            SCOPE_: "[?(@.scope)]"
            ROLE_: "realm_access.roles"

package com.tutorial.order.security;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.core.GrantedAuthority;
import org.springframework.security.core.authority.SimpleGrantedAuthority;
import org.springframework.security.oauth2.jwt.Jwt;
import org.springframework.security.oauth2.server.resource.authentication.JwtAuthenticationConverter;
import org.springframework.security.oauth2.server.resource.authentication.JwtGrantedAuthoritiesConverter;

import java.util.Collection;
import java.util.List;
import java.util.Map;
import java.util.stream.Stream;

@Configuration
public class JwtConfig {

    @Bean
    JwtAuthenticationConverter jwtAuthenticationConverter() {
        JwtGrantedAuthoritiesConverter scopes = new JwtGrantedAuthoritiesConverter();
        scopes.setAuthorityPrefix("SCOPE_");
        scopes.setAuthoritiesClaimName("scope");

        JwtAuthenticationConverter converter = new JwtAuthenticationConverter();
        converter.setJwtGrantedAuthoritiesConverter(jwt ->
                Stream.concat(
                        scopes.convert(jwt).stream(),
                        extractRealmRoles(jwt).stream()
                ).toList());
        return converter;
    }

    @SuppressWarnings("unchecked")
    private Collection<GrantedAuthority> extractRealmRoles(Jwt jwt) {
        Map<String, Object> realmAccess = jwt.getClaim("realm_access");
        if (realmAccess == null) {
            return List.of();
        }
        List<String> roles = (List<String>) realmAccess.getOrDefault("roles", List.of());
        return roles.stream()
                .map(role -> (GrantedAuthority) new SimpleGrantedAuthority("ROLE_" + role))
                .toList();
    }
}

package com.tutorial.order.application;

import org.springframework.security.access.prepost.PostAuthorize;
import org.springframework.security.access.prepost.PreAuthorize;
import org.springframework.security.core.annotation.AuthenticationPrincipal;
import org.springframework.stereotype.Service;

@Service
public class OrderSecurityService {

    @PreAuthorize("hasRole('ADMIN')")
    public void deleteOrder(String orderNo) { }

    /** 只能查自己的訂單，除非是管理員。 */
    @PostAuthorize("returnObject.customerId == authentication.name or hasRole('ADMIN')")
    public OrderResponse findByOrderNo(String orderNo) {
        return null;
    }

    /** 用自訂 Bean 做複雜授權判斷。 */
    @PreAuthorize("@orderPermissionEvaluator.canModify(authentication, #orderNo)")
    public void updateOrder(String orderNo, UpdateOrderRequest request) { }

    /** 組合條件。 */
    @PreAuthorize("hasAuthority('SCOPE_order:write') and #request.amount <= 100000")
    public void createHighValueOrder(CreateOrderRequest request) { }
}

package com.tutorial.order.security;

import org.springframework.security.core.Authentication;
import org.springframework.stereotype.Component;

@Component("orderPermissionEvaluator")
public class OrderPermissionEvaluator {

    private final OrderRepository orderRepository;

    public OrderPermissionEvaluator(OrderRepository orderRepository) {
        this.orderRepository = orderRepository;
    }

    public boolean canModify(Authentication authentication, String orderNo) {
        return orderRepository.findByOrderNo(orderNo)
                .map(order -> order.getCustomerId().equals(authentication.getName())
                        && order.getStatus() == OrderStatus.CREATED)
                .orElse(false);
    }
}

spring:
  security:
    oauth2:
      client:
        registration:
          keycloak:
            client-id: order-web
            client-secret: ${OAUTH_CLIENT_SECRET}
            authorization-grant-type: authorization_code
            scope: openid,profile,email,order:read
            redirect-uri: "{baseUrl}/login/oauth2/code/{registrationId}"
        provider:
          keycloak:
            issuer-uri: https://auth.company.com/realms/order

@Bean
SecurityFilterChain webFilterChain(HttpSecurity http) throws Exception {
    return http
            .securityMatcher("/**")
            .authorizeHttpRequests(auth -> auth
                    .requestMatchers("/", "/login/**", "/css/**", "/js/**").permitAll()
                    .anyRequest().authenticated())
            .oauth2Login(oauth2 -> oauth2
                    .defaultSuccessUrl("/dashboard", true)
                    .failureUrl("/login?error"))
            .logout(logout -> logout
                    .logoutSuccessUrl("/")
                    .invalidateHttpSession(true)
                    .deleteCookies("JSESSIONID"))
            // 🔒 有狀態的瀏覽器登入必須開啟 CSRF
            .csrf(Customizer.withDefaults())
            .build();
}

// ❌ 撈 10000 筆再過濾, 極慢且浪費
@PostFilter("filterObject.customerId == authentication.name")
List<OrderResponse> findAll();

// ✅ 在查詢就加條件
List<OrderResponse> findByCustomerId(String customerId);

package com.tutorial.order.security;

import io.github.bucket4j.Bandwidth;
import io.github.bucket4j.Bucket;
import org.springframework.stereotype.Component;

import java.time.Duration;
import java.util.Map;
import java.util.concurrent.ConcurrentHashMap;

@Component
public class LoginAttemptLimiter {

    private final Map<String, Bucket> buckets = new ConcurrentHashMap<>();

    /** 每個帳號每 15 分鐘最多 5 次登入嘗試。 */
    public boolean tryConsume(String username) {
        return buckets.computeIfAbsent(username, key -> Bucket.builder()
                        .addLimit(Bandwidth.builder()
                                .capacity(5)
                                .refillIntervally(5, Duration.ofMinutes(15))
                                .build())
                        .build())
                .tryConsume(1);
    }
}

package com.tutorial.order.persistence;

import jakarta.persistence.Column;
import jakarta.persistence.Entity;
import org.hibernate.annotations.TenantId;

@Entity
public class OrderEntity {

    @TenantId
    @Column(name = "tenant_id", nullable = false)
    private String tenantId;
}

@Bean
CurrentTenantIdentifierResolver<String> tenantResolver() {
    return new CurrentTenantIdentifierResolver<>() {
        @Override
        public String resolveCurrentTenantIdentifier() {
            Authentication auth = SecurityContextHolder.getContext().getAuthentication();
            if (auth instanceof JwtAuthenticationToken jwtAuth) {
                return jwtAuth.getToken().getClaimAsString("tenant_id");
            }
            throw new IllegalStateException("無法判定租戶");
        }

        @Override
        public boolean validateExistingCurrentSessions() {
            return true;
        }
    };
}

spring:
  ssl:
    bundle:
      pem:
        upstream:
          truststore:
            certificate: file:/run/secrets/ca.pem
management:
  endpoint:
    health:
      group:
        readiness:
          include: db, ssl

package com.tutorial.order.domain;

import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Nested;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.params.ParameterizedTest;
import org.junit.jupiter.params.provider.CsvSource;
import org.junit.jupiter.params.provider.ValueSource;

import java.math.BigDecimal;

import static org.assertj.core.api.Assertions.assertThat;
import static org.assertj.core.api.Assertions.assertThatThrownBy;

@DisplayName("訂單領域模型")
class OrderTest {

    @Nested
    @DisplayName("建立訂單時")
    class WhenCreating {

        @Test
        @DisplayName("應計算正確的總金額")
        void 應計算正確的總金額() {
            Order order = Order.create("CUST-001", Currency.TWD);
            order.addLine("SKU-001", 2, Money.of("500.00", Currency.TWD));
            order.addLine("SKU-002", 1, Money.of("300.00", Currency.TWD));

            assertThat(order.totalAmount()).isEqualTo(Money.of("1300.00", Currency.TWD));
        }

        @Test
        @DisplayName("沒有品項時不可送出")
        void 沒有品項時不可送出() {
            Order order = Order.create("CUST-001", Currency.TWD);

            assertThatThrownBy(order::submit)
                    .isInstanceOf(BusinessRuleViolationException.class)
                    .hasMessageContaining("至少要有一個品項");
        }
    }

    @ParameterizedTest(name = "數量 {0} 應被拒絕")
    @ValueSource(ints = {0, -1, 1000})
    void 不合法的數量應被拒絕(int quantity) {
        Order order = Order.create("CUST-001", Currency.TWD);

        assertThatThrownBy(() -> order.addLine("SKU-001", quantity, Money.of("100", Currency.TWD)))
                .isInstanceOf(IllegalArgumentException.class);
    }

    @ParameterizedTest(name = "{0} 折扣 {1}% 後應為 {2}")
    @CsvSource({
            "1000.00, 10, 900.00",
            "1000.00,  0, 1000.00",
            " 999.99, 15, 849.99"
    })
    void 折扣計算(String original, int discountPercent, String expected) {
        Money result = Money.of(original, Currency.TWD).discount(discountPercent);

        assertThat(result).isEqualTo(Money.of(expected, Currency.TWD));
    }
}

package com.tutorial.order.application;

import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.extension.ExtendWith;
import org.mockito.ArgumentCaptor;
import org.mockito.InjectMocks;
import org.mockito.Mock;
import org.mockito.junit.jupiter.MockitoExtension;

import java.util.Optional;

import static org.assertj.core.api.Assertions.assertThat;
import static org.assertj.core.api.Assertions.assertThatThrownBy;
import static org.mockito.ArgumentMatchers.any;
import static org.mockito.BDDMockito.given;
import static org.mockito.Mockito.verify;

@ExtendWith(MockitoExtension.class)
class OrderApplicationServiceTest {

    @Mock
    private OrderRepository orderRepository;

    @Mock
    private ApplicationEventPublisher eventPublisher;

    @InjectMocks
    private OrderApplicationService service;

    @Test
    void 建立訂單後應發佈事件() {
        given(orderRepository.save(any(OrderEntity.class)))
                .willAnswer(invocation -> invocation.getArgument(0));

        service.create(new CreateOrderRequest("CUST-001",
                List.of(new OrderLineRequest("SKU-001", 2)), "TWD", null));

        ArgumentCaptor<OrderCreatedEvent> captor = ArgumentCaptor.forClass(OrderCreatedEvent.class);
        verify(eventPublisher).publishEvent(captor.capture());
        assertThat(captor.getValue().orderNo()).isNotBlank();
    }

    @Test
    void 訂單不存在時應拋出例外() {
        given(orderRepository.findWithLinesByOrderNo("ORD-999")).willReturn(Optional.empty());

        assertThatThrownBy(() -> service.findByOrderNo("ORD-999"))
                .isInstanceOf(OrderNotFoundException.class);
    }
}

package com.tutorial.order.web;

import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.web.servlet.WebMvcTest;
import org.springframework.http.MediaType;
import org.springframework.security.test.context.support.WithMockUser;
import org.springframework.test.context.bean.override.mockito.MockitoBean;
import org.springframework.test.web.servlet.MockMvc;

import static org.mockito.ArgumentMatchers.any;
import static org.mockito.BDDMockito.given;
import static org.mockito.BDDMockito.willThrow;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.post;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.*;

@WebMvcTest(OrderController.class)
class OrderControllerTest {

    @Autowired
    private MockMvc mockMvc;

    // 🔄 4.x 用 @MockitoBean, @MockBean 已移除
    @MockitoBean
    private OrderApplicationService orderService;

    @Test
    @WithMockUser(authorities = "SCOPE_order:write")
    void 建立訂單成功應回_201_且帶_Location() throws Exception {
        given(orderService.create(any())).willReturn(
                new OrderResponse("ORD-001", "CUST-001", "CREATED",
                        new BigDecimal("1000.00"), "TWD", List.of(), Instant.now()));

        mockMvc.perform(post("/api/orders")
                        .contentType(MediaType.APPLICATION_JSON)
                        .content("""
                                {
                                  "customerId": "CUST-001",
                                  "currency": "TWD",
                                  "lines": [{"sku": "SKU-001", "quantity": 2}]
                                }
                                """))
                .andExpect(status().isCreated())
                .andExpect(header().exists("Location"))
                .andExpect(jsonPath("$.id").value("ORD-001"));
    }

    @Test
    @WithMockUser(authorities = "SCOPE_order:write")
    void 驗證失敗應回_400_且為_ProblemDetail() throws Exception {
        mockMvc.perform(post("/api/orders")
                        .contentType(MediaType.APPLICATION_JSON)
                        .content("""
                                {"customerId": "", "lines": []}
                                """))
                .andExpect(status().isBadRequest())
                .andExpect(content().contentTypeCompatibleWith("application/problem+json"))
                .andExpect(jsonPath("$.title").value("參數驗證失敗"))
                .andExpect(jsonPath("$.errors").isArray());
    }

    @Test
    @WithMockUser(authorities = "SCOPE_order:read")
    void 訂單不存在應回_404() throws Exception {
        willThrow(new OrderNotFoundException("ORD-999"))
                .given(orderService).findByOrderNo("ORD-999");

        mockMvc.perform(get("/api/orders/ORD-999"))
                .andExpect(status().isNotFound())
                .andExpect(jsonPath("$.title").value("訂單不存在"));
    }

    @Test
    void 未認證應回_401() throws Exception {
        mockMvc.perform(get("/api/orders/ORD-001"))
                .andExpect(status().isUnauthorized());
    }
}

package com.tutorial.order.web;

import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.boot.test.web.server.LocalServerPort;
import org.springframework.http.MediaType;
import org.springframework.test.web.servlet.client.RestTestClient;

@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
class OrderApiTest {

    @Autowired
    private RestTestClient restTestClient;

    @Test
    void 建立訂單後應能查回() {
        // 建立
        String location = restTestClient.post()
                .uri("/api/orders")
                .contentType(MediaType.APPLICATION_JSON)
                .headers(h -> h.setBearerAuth(testToken()))
                .bodyValue("""
                        {
                          "customerId": "CUST-001",
                          "currency": "TWD",
                          "lines": [{"sku": "SKU-001", "quantity": 2}]
                        }
                        """)
                .exchange()
                .expectStatus().isCreated()
                .expectHeader().exists("Location")
                .returnResult(Void.class)
                .getResponseHeaders()
                .getFirst("Location");

        // 查詢
        restTestClient.get()
                .uri(location)
                .headers(h -> h.setBearerAuth(testToken()))
                .exchange()
                .expectStatus().isOk()
                .expectBody()
                .jsonPath("$.customerId").isEqualTo("CUST-001")
                .jsonPath("$.status").isEqualTo("CREATED");
    }
}

@WebMvcTest(OrderController.class)
@AutoConfigureMockMvc
class OrderControllerRestTestClientTest {

    @Autowired
    private RestTestClient client;   // 綁定到 MockMvc, 不開真實埠
}

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-testcontainers</artifactId>
    <scope>test</scope>
</dependency>
<dependency>
    <groupId>org.testcontainers</groupId>
    <artifactId>postgresql</artifactId>
    <scope>test</scope>
</dependency>
<dependency>
    <groupId>org.testcontainers</groupId>
    <artifactId>junit-jupiter</artifactId>
    <scope>test</scope>
</dependency>

package com.tutorial.order;

import org.springframework.boot.test.context.TestConfiguration;
import org.springframework.boot.testcontainers.service.connection.ServiceConnection;
import org.springframework.context.annotation.Bean;
import org.testcontainers.containers.PostgreSQLContainer;
import org.testcontainers.kafka.KafkaContainer;
import org.testcontainers.containers.GenericContainer;
import org.testcontainers.utility.DockerImageName;

/** 共用的測試容器設定，多個測試類別共用同一組容器。 */
@TestConfiguration(proxyBeanMethods = false)
public class TestcontainersConfig {

    @Bean
    @ServiceConnection
    PostgreSQLContainer<?> postgresContainer() {
        return new PostgreSQLContainer<>(DockerImageName.parse("postgres:17-alpine"))
                .withReuse(true);   // ⚡ 本機開發時重用容器, 大幅加速
    }

    @Bean
    @ServiceConnection(name = "redis")
    GenericContainer<?> redisContainer() {
        return new GenericContainer<>(DockerImageName.parse("redis:7-alpine"))
                .withExposedPorts(6379)
                .withReuse(true);
    }

    @Bean
    @ServiceConnection
    KafkaContainer kafkaContainer() {
        return new KafkaContainer(DockerImageName.parse("apache/kafka:4.1.0"))
                .withReuse(true);
    }
}

package com.tutorial.order;

import org.springframework.boot.SpringApplication;

/** 本機開發用: 直接跑起完整的相依服務。 */
public class TestOrderServiceApplication {

    public static void main(String[] args) {
        SpringApplication.from(OrderServiceApplication::main)
                .with(TestcontainersConfig.class)
                .run(args);
    }
}

# 直接用測試容器啟動本機開發環境
mvn spring-boot:test-run

# ~/.testcontainers.properties
testcontainers.reuse.enable=true

package com.tutorial.order;

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

import static org.assertj.core.api.Assertions.assertThat;

@SpringBootTest
@Import(TestcontainersConfig.class)
@ActiveProfiles("test")
class OrderIntegrationTest {

    @Autowired
    private OrderApplicationService orderService;

    @Autowired
    private OrderRepository orderRepository;

    @Test
    @Transactional   // ⚠️ 測試結束自動回滾, 但要注意這會讓 AFTER_COMMIT 事件不觸發
    void 完整下單流程() {
        OrderResponse created = orderService.create(new CreateOrderRequest(
                "CUST-001", List.of(new OrderLineRequest("SKU-001", 2)), "TWD", null));

        assertThat(orderRepository.findByOrderNo(created.id())).isPresent();
    }
}

// JSON 序列化測試
@JsonTest
class OrderResponseJsonTest {

    @Autowired
    private JacksonTester<OrderResponse> json;

    @Test
    void 序列化應使用_ISO_時間格式() throws Exception {
        OrderResponse response = new OrderResponse("ORD-001", "CUST-001", "CREATED",
                new BigDecimal("1000.00"), "TWD", List.of(),
                Instant.parse("2026-07-31T10:00:00Z"));

        assertThat(json.write(response))
                .hasJsonPathStringValue("$.createdAt")
                .extractingJsonPathStringValue("$.createdAt")
                .isEqualTo("2026-07-31T10:00:00Z");
    }
}

// 外部 HTTP Client 測試
@RestClientTest(PaymentClient.class)
class PaymentClientTest {

    @Autowired
    private PaymentClient paymentClient;

    @Autowired
    private MockRestServiceServer server;

    @Test
    void 付款成功應回傳交易編號() {
        server.expect(requestTo("/api/payments"))
                .andExpect(method(HttpMethod.POST))
                .andRespond(withSuccess("""
                        {"paymentId": "PAY-001", "status": "SUCCESS"}
                        """, MediaType.APPLICATION_JSON));

        PaymentResponse response = paymentClient.charge(
                new ChargeRequest("ORD-001", new BigDecimal("1000"), "TWD"));

        assertThat(response.paymentId()).isEqualTo("PAY-001");
        server.verify();
    }
}

import static org.awaitility.Awaitility.await;
import static java.time.Duration.ofSeconds;

@Test
void 非同步處理應在_5_秒內完成() {
    orderService.submitAsync("ORD-001");

    await().atMost(ofSeconds(5))
            .pollInterval(ofMillis(100))
            .untilAsserted(() ->
                    assertThat(orderRepository.findByOrderNo("ORD-001"))
                            .get()
                            .extracting(OrderEntity::getStatus)
                            .isEqualTo(OrderStatus.SUBMITTED));
}

<plugin>
    <groupId>org.jacoco</groupId>
    <artifactId>jacoco-maven-plugin</artifactId>
    <version>0.8.13</version>
    <executions>
        <execution>
            <goals><goal>prepare-agent</goal></goals>
        </execution>
        <execution>
            <id>check</id>
            <phase>verify</phase>
            <goals><goal>check</goal></goals>
            <configuration>
                <rules>
                    <rule>
                        <element>PACKAGE</element>
                        <includes>
                            <include>com.tutorial.order.domain.*</include>
                        </includes>
                        <limits>
                            <limit>
                                <counter>LINE</counter>
                                <value>COVEREDRATIO</value>
                                <minimum>0.85</minimum>
                            </limit>
                        </limits>
                    </rule>
                </rules>
            </configuration>
        </execution>
    </executions>
</plugin>