新建 REST API 微服務 → Core Profile
新建含資料庫的 Web 應用 → Web Profile
既有大型企業系統 / 需要 Batch + MQ → Full Platform

// === 傳統方式：使用執行緒池處理請求 ===
@ApplicationScoped
public class TraditionalOrderService {

    @Resource
    private ManagedExecutorService executorService;

    public CompletableFuture<OrderResult> processOrder(OrderRequest request) {
        return CompletableFuture.supplyAsync(() -> {
            // 受限於執行緒池大小（通常 50-200）
            return doProcessOrder(request);
        }, executorService);
    }
}

// === Jakarta EE 12 + Virtual Thread：每個請求一個虛擬執行緒 ===
@ApplicationScoped
public class ModernOrderService {

    @Resource
    private ManagedExecutorService virtualExecutor; // 配置為 Virtual Thread

    /**
     * 使用 Virtual Thread 處理訂單。
     * 不再受限於執行緒池大小，可輕鬆處理數萬並行請求。
     */
    public OrderResult processOrder(OrderRequest request) {
        try (var scope = new StructuredTaskScope.ShutdownOnFailure()) {
            // 同時查詢庫存、計算價格、檢查風控
            Subtask<Inventory> inventory = scope.fork(() -> checkInventory(request));
            Subtask<Price> price = scope.fork(() -> calculatePrice(request));
            Subtask<RiskResult> risk = scope.fork(() -> checkRisk(request));

            scope.join();
            scope.throwIfFailed();

            return new OrderResult(
                inventory.get(),
                price.get(),
                risk.get()
            );
        } catch (Exception e) {
            throw new OrderProcessingException("訂單處理失敗", e);
        }
    }
}

<!-- server.xml - 啟用 Virtual Thread -->
<featureManager>
    <feature>concurrent-3.2</feature>
    <feature>restfulWS-5.0</feature>
</featureManager>

<!-- 配置 Virtual Thread Executor -->
<managedExecutorService jndiName="concurrent/virtualExecutor">
    <contextService>
        <contextInfo>AllContextTypes</contextInfo>
    </contextService>
    <!-- Virtual Thread 不需要指定 maxAsync -->
    <virtualThreads>true</virtualThreads>
</managedExecutorService>

/**
 * 結構化並行：銀行轉帳風控檢查範例。
 * 同時執行多項檢查，任一失敗則全部取消。
 */
public TransferDecision evaluateTransfer(TransferRequest request) 
        throws InterruptedException, ExecutionException {
    
    try (var scope = new StructuredTaskScope.ShutdownOnFailure()) {
        
        // 並行執行四項風控檢查
        Subtask<AmlResult> amlCheck = scope.fork(
            () -> antiMoneyLaunderingCheck(request));
        Subtask<FraudResult> fraudCheck = scope.fork(
            () -> fraudDetection(request));
        Subtask<LimitResult> limitCheck = scope.fork(
            () -> dailyLimitCheck(request));
        Subtask<SanctionResult> sanctionCheck = scope.fork(
            () -> sanctionScreening(request));

        // 等待所有子任務完成，任一失敗自動取消其他
        scope.join();
        scope.throwIfFailed();

        return TransferDecision.approve(
            amlCheck.get(),
            fraudCheck.get(),
            limitCheck.get(),
            sanctionCheck.get()
        );
    }
}

/**
 * 使用 Record 定義 API 回應物件。
 * 自動產生 constructor、equals、hashCode、toString。
 */
public record ApiResponse<T>(
    int status,
    String message,
    T data,
    Instant timestamp
) {
    // Compact Constructor 驗證
    public ApiResponse {
        if (status < 100 || status > 599) {
            throw new IllegalArgumentException("無效的 HTTP 狀態碼: " + status);
        }
        if (timestamp == null) {
            timestamp = Instant.now();
        }
    }

    // 便利工廠方法
    public static <T> ApiResponse<T> success(T data) {
        return new ApiResponse<>(200, "成功", data, Instant.now());
    }

    public static <T> ApiResponse<T> error(int status, String message) {
        return new ApiResponse<>(status, message, null, Instant.now());
    }
}

/**
 * 使用 Record 定義 DTO。
 */
public record CreateOrderRequest(
    @NotBlank String customerId,
    @NotEmpty List<OrderItem> items,
    @Valid ShippingAddress address
) {}

public record OrderItem(
    @NotBlank String productId,
    @Positive int quantity,
    @PositiveOrZero BigDecimal unitPrice
) {}

/**
 * Pattern Matching for switch（JEP 441）
 * 取代冗長的 instanceof 鏈。
 */
public String handlePayment(PaymentMethod payment) {
    return switch (payment) {
        case CreditCard cc when cc.isExpired() -> 
            "信用卡已過期: " + cc.maskedNumber();
        case CreditCard cc -> 
            "信用卡付款: " + cc.maskedNumber();
        case BankTransfer bt -> 
            "銀行轉帳: " + bt.bankCode() + " " + bt.accountNumber();
        case DigitalWallet dw -> 
            "電子錢包: " + dw.provider();
        case null -> 
            throw new IllegalArgumentException("付款方式不可為 null");
    };
}

/**
 * Record Pattern（JEP 440）解構。
 */
public void processTransaction(Transaction tx) {
    if (tx instanceof Transfer(var from, var to, var amount) 
            && amount.compareTo(BigDecimal.valueOf(1_000_000)) > 0) {
        logger.warn("大額轉帳警示: {} -> {}, 金額: {}", from, to, amount);
        notifyCompliance(tx);
    }
}

// Java 21 新增有序集合介面
SequencedCollection<Transaction> recentTx = getRecentTransactions();

// 取得第一筆和最後一筆
Transaction first = recentTx.getFirst();
Transaction last = recentTx.getLast();

// 反轉順序
SequencedCollection<Transaction> reversed = recentTx.reversed();

// SequencedMap
SequencedMap<String, BigDecimal> dailyBalances = getDailyBalances();
Map.Entry<String, BigDecimal> earliest = dailyBalances.firstEntry();
Map.Entry<String, BigDecimal> latest = dailyBalances.lastEntry();

/**
 * Scoped Values 取代 ThreadLocal，更適合 Virtual Thread。
 */
public class RequestContext {

    // 定義 Scoped Value
    public static final ScopedValue<UserPrincipal> CURRENT_USER = ScopedValue.newInstance();
    public static final ScopedValue<String> CORRELATION_ID = ScopedValue.newInstance();

    /**
     * 在請求處理鏈中綁定上下文。
     */
    public Response handleRequest(UserPrincipal user, String correlationId) {
        return ScopedValue
            .where(CURRENT_USER, user)
            .where(CORRELATION_ID, correlationId)
            .call(() -> {
                // 在此 scope 內的所有程式碼都能存取這些值
                return processBusinessLogic();
            });
    }
}

// 在服務層中使用
@ApplicationScoped
public class AuditService {

    public void logAction(String action) {
        UserPrincipal user = RequestContext.CURRENT_USER.get();
        String corrId = RequestContext.CORRELATION_ID.get();
        logger.info("[{}] 使用者 {} 執行: {}", corrId, user.getName(), action);
    }
}

// Java 25: Primitive Types in Patterns
public String classifyTransaction(double amount) {
    return switch (amount) {
        case double a when a < 0 -> "退款";
        case double a when a == 0 -> "零額交易";
        case double a when a < 10_000 -> "一般交易";
        case double a when a < 1_000_000 -> "大額交易";
        default -> "超大額交易 — 需人工審核";
    };
}

// Java 25: Flexible Constructor Bodies
public class BankAccount {
    private final String accountId;
    private final BigDecimal initialBalance;
    
    public BankAccount(String accountId, BigDecimal initialBalance) {
        // Java 25 允許在 super() 之前執行驗證
        if (accountId == null || accountId.isBlank()) {
            throw new IllegalArgumentException("帳號不可為空");
        }
        if (initialBalance.compareTo(BigDecimal.ZERO) < 0) {
            throw new IllegalArgumentException("初始餘額不可為負");
        }
        this.accountId = accountId;
        this.initialBalance = initialBalance;
    }
}

# === Jakarta EE 12 + Java 21 生產環境 JVM 參數 ===

JAVA_OPTS=" \
  # 記憶體配置
  -Xms2g -Xmx4g \
  -XX:MetaspaceSize=256m \
  -XX:MaxMetaspaceSize=512m \
  
  # GC 策略 — 推薦 G1GC（通用場景）
  -XX:+UseG1GC \
  -XX:MaxGCPauseMillis=200 \
  -XX:G1HeapRegionSize=16m \
  -XX:+G1UseAdaptiveIHOP \
  
  # 或使用 ZGC（低延遲場景，如交易系統）
  # -XX:+UseZGC \
  # -XX:+ZGenerational \
  
  # Virtual Thread 調校
  -Djdk.virtualThreadScheduler.parallelism=8 \
  -Djdk.virtualThreadScheduler.maxPoolSize=256 \
  
  # 安全性
  -Djava.security.egd=file:/dev/urandom \
  
  # Diagnostics
  -XX:+HeapDumpOnOutOfMemoryError \
  -XX:HeapDumpPath=/var/log/app/heapdump.hprof \
  -Xlog:gc*:file=/var/log/app/gc.log:time,uptime,level,tags:filecount=10,filesize=50m \
  
  # Container 支援（Kubernetes 環境）
  -XX:+UseContainerSupport \
  -XX:MaxRAMPercentage=75.0 \
"

# 方法一：使用 winget（推薦）
winget install EclipseAdoptium.Temurin.21.JDK

# 方法二：使用 Scoop
scoop bucket add java
scoop install temurin21-jdk

# 方法三：使用 SDKMAN!（WSL 環境）
sdk install java 21.0.5-tem

# 驗證安裝
java --version
# openjdk 21.0.5 2024-10-15 LTS

# 設定環境變數
[System.Environment]::SetEnvironmentVariable("JAVA_HOME", "C:\Program Files\Eclipse Adoptium\jdk-21", "Machine")
[System.Environment]::SetEnvironmentVariable("Path", "$env:JAVA_HOME\bin;$env:Path", "Machine")

# 方法一：APT
sudo apt update
sudo apt install -y temurin-21-jdk

# 方法二：SDKMAN!（推薦，支援多版本管理）
curl -s "https://get.sdkman.io" | bash
source "$HOME/.sdkman/bin/sdkman-init.sh"
sdk install java 21.0.5-tem

# 設定 JAVA_HOME
echo 'export JAVA_HOME=$(sdk home java current)' >> ~/.bashrc
source ~/.bashrc

# 驗證
java --version
javac --version

# 方法一：Homebrew
brew install --cask temurin@21

# 方法二：SDKMAN!
sdk install java 21.0.5-tem

# 驗證
java --version
/usr/libexec/java_home -V

# Windows (winget)
winget install Apache.Maven

# Linux / macOS (SDKMAN!)
sdk install maven 3.9.9

# 驗證
mvn --version

# Maven settings.xml 企業級設定範本（~/.m2/settings.xml）

<?xml version="1.0" encoding="UTF-8"?>
<settings xmlns="http://maven.apache.org/SETTINGS/1.2.0"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.2.0 
          https://maven.apache.org/xsd/settings-1.2.0.xsd">
    
    <!-- 企業 Proxy 設定 -->
    <proxies>
        <proxy>
            <id>corp-proxy</id>
            <active>true</active>
            <protocol>https</protocol>
            <host>proxy.company.com</host>
            <port>8080</port>
            <nonProxyHosts>localhost|*.company.com</nonProxyHosts>
        </proxy>
    </proxies>
    
    <!-- 企業私有 Repository -->
    <mirrors>
        <mirror>
            <id>nexus</id>
            <mirrorOf>*</mirrorOf>
            <url>https://nexus.company.com/repository/maven-public/</url>
        </mirror>
    </mirrors>
    
    <profiles>
        <profile>
            <id>jakarta-ee-12</id>
            <properties>
                <maven.compiler.source>21</maven.compiler.source>
                <maven.compiler.target>21</maven.compiler.target>
                <maven.compiler.release>21</maven.compiler.release>
                <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
            </properties>
        </profile>
    </profiles>
    
    <activeProfiles>
        <activeProfile>jakarta-ee-12</activeProfile>
    </activeProfiles>
</settings>

# SDKMAN!
sdk install gradle 8.10

# 驗證
gradle --version

// .vscode/extensions.json — 推薦擴充套件
{
    "recommendations": [
        "redhat.java",
        "vscjava.vscode-java-pack",
        "vscjava.vscode-maven",
        "vscjava.vscode-java-debug",
        "vscjava.vscode-java-test",
        "vscjava.vscode-java-dependency",
        "redhat.vscode-xml",
        "redhat.vscode-yaml",
        "ms-azuretools.vscode-docker",
        "ms-kubernetes-tools.vscode-kubernetes-tools",
        "github.copilot",
        "github.copilot-chat"
    ]
}

// .vscode/settings.json — 專案設定
{
    "java.configuration.runtimes": [
        {
            "name": "JavaSE-21",
            "path": "/path/to/jdk-21",
            "default": true
        }
    ],
    "java.compile.nullAnalysis.mode": "automatic",
    "java.format.settings.url": ".vscode/java-formatter.xml",
    "java.saveActions.organizeImports": true,
    "editor.formatOnSave": true,
    "files.encoding": "utf8"
}

# Windows — Docker Desktop
winget install Docker.DockerDesktop

# Linux — Podman（無 Daemon，更適合企業環境）
sudo apt install -y podman podman-compose

# 驗證
docker --version   # 或 podman --version
docker compose version

# 建立開發用 docker-compose.yml

# docker-compose-dev.yml — 開發環境基礎設施
version: '3.9'
services:
  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_DB: appdb
      POSTGRES_USER: appuser
      POSTGRES_PASSWORD: ${DB_PASSWORD:-devpassword}
    ports:
      - "5432:5432"
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U appuser -d appdb"]
      interval: 10s
      timeout: 5s
      retries: 5

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"
    command: redis-server --requirepass ${REDIS_PASSWORD:-devpassword}

  kafka:
    image: confluentinc/cp-kafka:7.7.0
    environment:
      KAFKA_NODE_ID: 1
      KAFKA_PROCESS_ROLES: broker,controller
      KAFKA_LISTENERS: PLAINTEXT://0.0.0.0:9092,CONTROLLER://0.0.0.0:9093
      KAFKA_ADVERTISED_LISTENERS: PLAINTEXT://localhost:9092
      KAFKA_CONTROLLER_LISTENER_NAMES: CONTROLLER
      KAFKA_CONTROLLER_QUORUM_VOTERS: 1@localhost:9093
      CLUSTER_ID: 'MkU3OEVBNTcwNTJENDM2Qk'
    ports:
      - "9092:9092"

volumes:
  pgdata:

# 安裝 kubectl
# Windows
winget install Kubernetes.kubectl

# Linux
curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"
sudo install -o root -g root -m 0755 kubectl /usr/local/bin/kubectl

# macOS
brew install kubectl

# 安裝本地 K8s 叢集（開發用）
# 方法一：minikube
winget install Kubernetes.minikube
minikube start --cpus=4 --memory=8192 --driver=docker

# 方法二：kind（Kubernetes in Docker）
go install sigs.k8s.io/kind@latest
kind create cluster --name jakarta-dev

# 驗證
kubectl cluster-info
kubectl get nodes

# 使用 Jakarta EE Starter Maven Archetype
mvn archetype:generate \
  -DarchetypeGroupId=org.eclipse.starter \
  -DarchetypeArtifactId=jakarta-starter \
  -DarchetypeVersion=2.2.0 \
  -DgroupId=com.company.app \
  -DartifactId=my-jakarta-app \
  -Dversion=1.0.0-SNAPSHOT \
  -Dprofile=web \
  -DjakartaVersion=12 \
  -Druntime=open-liberty \
  -DinteractiveMode=false

my-jakarta-app/
├── pom.xml                          # Jakarta EE 12 BOM 已配置
├── src/
│   ├── main/
│   │   ├── java/
│   │   │   └── com/company/app/
│   │   │       ├── RestApplication.java   # JAX-RS Application
│   │   │       └── HelloResource.java     # 範例 REST 端點
│   │   ├── resources/
│   │   │   └── META-INF/
│   │   │       ├── beans.xml              # CDI 配置
│   │   │       └── persistence.xml        # JPA 配置（Web Profile）
│   │   └── webapp/
│   │       └── WEB-INF/
│   └── test/
│       └── java/
└── README.md

<!-- server.xml — Open Liberty 基本配置 -->
<server description="Jakarta EE 12 Application">

    <!-- 功能選擇：按需載入，不載入不需要的 -->
    <featureManager>
        <feature>jakartaee-12.0</feature>
        <feature>microProfile-7.0</feature>
    </featureManager>

    <!-- HTTP 端點 -->
    <httpEndpoint id="defaultHttpEndpoint"
                  httpPort="9080"
                  httpsPort="9443" />

    <!-- 資料來源 -->
    <dataSource id="DefaultDataSource" jndiName="jdbc/appDB">
        <jdbcDriver libraryRef="postgresql-lib" />
        <properties.postgresql serverName="localhost"
                               portNumber="5432"
                               databaseName="appdb"
                               user="appuser"
                               password="${env.DB_PASSWORD}" />
        <connectionManager maxPoolSize="50"
                          minPoolSize="10"
                          connectionTimeout="30s" />
    </dataSource>

    <library id="postgresql-lib">
        <fileset dir="${server.config.dir}/lib" includes="postgresql-*.jar" />
    </library>

    <!-- 應用程式 -->
    <webApplication id="myapp" location="myapp.war"
                    contextRoot="/">
        <classloader apiTypeVisibility="spec,ibm-api,third-party" />
    </webApplication>

</server>

# Payara Server
asadmin start-domain

# Payara Micro — 直接執行 WAR
java -jar payara-micro.jar --deploy myapp.war --port 8080

# Payara Micro — Docker
docker run -p 8080:8080 -v ./myapp.war:/opt/payara/deployments/myapp.war \
  payara/micro:6.2024.12-jdk21

<!-- web.xml 或 glassfish-web.xml -->
<!-- Payara 資料來源配置 -->
<resource-ref>
    <res-ref-name>jdbc/appDB</res-ref-name>
    <res-type>javax.sql.DataSource</res-type>
</resource-ref>

# Standalone 模式
./standalone.sh -c standalone-full.xml

# 使用 Galleon 精簡安裝
galleon.sh install wildfly:current \
  --layers=ee-core-profile-server,jpa,jms \
  --dir=my-wildfly

# Docker
docker run -p 8080:8080 -p 9990:9990 \
  quay.io/wildfly/wildfly:latest-jdk21

<subsystem xmlns="urn:jboss:domain:datasources:7.1">
    <datasources>
        <datasource jndi-name="java:jboss/datasources/AppDS"
                    pool-name="AppDS">
            <connection-url>jdbc:postgresql://localhost:5432/appdb</connection-url>
            <driver>postgresql</driver>
            <security user-name="appuser" password="${env.DB_PASSWORD}" />
            <pool>
                <min-pool-size>10</min-pool-size>
                <max-pool-size>50</max-pool-size>
            </pool>
        </datasource>
    </datasources>
</subsystem>

# 下載 Eclipse GlassFish 8
# 啟動 Domain
./bin/asadmin start-domain

# 部署應用
./bin/asadmin deploy myapp.war

# Docker
docker run -p 8080:8080 -p 4848:4848 \
  eclipse/glassfish:8.0.0-jdk21

jakarta-enterprise-app/
├── pom.xml                          # Parent POM
├── app-domain/                      # Domain Layer（核心業務邏輯）
│   ├── pom.xml
│   └── src/main/java/
│       └── com/company/app/domain/
│           ├── model/               # Entity、Value Object、Aggregate
│           ├── repository/          # Repository 介面（Port）
│           ├── service/             # Domain Service
│           └── event/               # Domain Event
├── app-application/                 # Application Layer（Use Case）
│   ├── pom.xml
│   └── src/main/java/
│       └── com/company/app/application/
│           ├── usecase/             # Use Case 實作
│           ├── dto/                 # DTO / Command / Query
│           └── port/                # Input/Output Port
├── app-infrastructure/              # Infrastructure Layer（技術實作）
│   ├── pom.xml
│   └── src/main/java/
│       └── com/company/app/infrastructure/
│           ├── persistence/         # JPA Repository 實作
│           ├── messaging/           # Kafka/RabbitMQ Adapter
│           ├── cache/               # Redis Adapter
│           ├── external/            # 外部 API Client
│           └── config/              # CDI Producer、Configuration
├── app-api/                         # API Layer（REST 端點）
│   ├── pom.xml
│   └── src/
│       ├── main/
│       │   ├── java/
│       │   │   └── com/company/app/api/
│       │   │       ├── resource/    # JAX-RS Resource
│       │   │       ├── filter/      # Request/Response Filter
│       │   │       ├── mapper/      # Exception Mapper
│       │   │       └── config/      # Application Config
│       │   ├── resources/
│       │   │   └── META-INF/
│       │   │       ├── beans.xml
│       │   │       └── persistence.xml
│       │   └── webapp/
│       │       └── WEB-INF/
│       └── test/
└── app-ear/                         # EAR 打包（可選）
    └── pom.xml

<?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>

    <groupId>com.company.app</groupId>
    <artifactId>jakarta-enterprise-app</artifactId>
    <version>1.0.0-SNAPSHOT</version>
    <packaging>pom</packaging>

    <name>Jakarta EE 12 Enterprise Application</name>
    <description>企業級 Jakarta EE 12 Multi Module 專案</description>

    <!-- 子模組 -->
    <modules>
        <module>app-domain</module>
        <module>app-application</module>
        <module>app-infrastructure</module>
        <module>app-api</module>
    </modules>

    <!-- 版本統一管理 -->
    <properties>
        <!-- Java -->
        <java.version>21</java.version>
        <maven.compiler.release>${java.version}</maven.compiler.release>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>

        <!-- Jakarta EE 12 -->
        <jakarta.ee.version>12.0.0</jakarta.ee.version>

        <!-- MicroProfile -->
        <microprofile.version>7.0</microprofile.version>

        <!-- Testing -->
        <junit.version>5.11.4</junit.version>
        <mockito.version>5.14.2</mockito.version>
        <testcontainers.version>1.20.4</testcontainers.version>
        <arquillian.version>1.9.1.Final</arquillian.version>
        <rest-assured.version>5.5.0</rest-assured.version>

        <!-- Logging -->
        <slf4j.version>2.0.16</slf4j.version>
        <logback.version>1.5.12</logback.version>

        <!-- Database -->
        <postgresql.version>42.7.4</postgresql.version>
        <flyway.version>10.21.0</flyway.version>

        <!-- Plugins -->
        <maven-compiler-plugin.version>3.14.1</maven-compiler-plugin.version>
        <maven-surefire-plugin.version>3.5.2</maven-surefire-plugin.version>
        <maven-failsafe-plugin.version>3.5.2</maven-failsafe-plugin.version>
        <maven-war-plugin.version>3.4.0</maven-war-plugin.version>
        <liberty-maven-plugin.version>3.11.3</liberty-maven-plugin.version>
        <jacoco-plugin.version>0.8.12</jacoco-plugin.version>
        <spotbugs-plugin.version>4.8.6.6</spotbugs-plugin.version>
    </properties>

    <!-- 依賴版本管理 -->
    <dependencyManagement>
        <dependencies>
            <!-- Jakarta EE 12 BOM -->
            <dependency>
                <groupId>jakarta.platform</groupId>
                <artifactId>jakarta.jakartaee-bom</artifactId>
                <version>${jakarta.ee.version}</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>

            <!-- MicroProfile BOM -->
            <dependency>
                <groupId>org.eclipse.microprofile</groupId>
                <artifactId>microprofile</artifactId>
                <version>${microprofile.version}</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>

            <!-- JUnit 5 BOM -->
            <dependency>
                <groupId>org.junit</groupId>
                <artifactId>junit-bom</artifactId>
                <version>${junit.version}</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>

            <!-- Testcontainers BOM -->
            <dependency>
                <groupId>org.testcontainers</groupId>
                <artifactId>testcontainers-bom</artifactId>
                <version>${testcontainers.version}</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>

            <!-- 內部模組版本 -->
            <dependency>
                <groupId>${project.groupId}</groupId>
                <artifactId>app-domain</artifactId>
                <version>${project.version}</version>
            </dependency>
            <dependency>
                <groupId>${project.groupId}</groupId>
                <artifactId>app-application</artifactId>
                <version>${project.version}</version>
            </dependency>
            <dependency>
                <groupId>${project.groupId}</groupId>
                <artifactId>app-infrastructure</artifactId>
                <version>${project.version}</version>
            </dependency>

            <!-- Database -->
            <dependency>
                <groupId>org.postgresql</groupId>
                <artifactId>postgresql</artifactId>
                <version>${postgresql.version}</version>
            </dependency>
            <dependency>
                <groupId>org.flywaydb</groupId>
                <artifactId>flyway-core</artifactId>
                <version>${flyway.version}</version>
            </dependency>

            <!-- Logging -->
            <dependency>
                <groupId>org.slf4j</groupId>
                <artifactId>slf4j-api</artifactId>
                <version>${slf4j.version}</version>
            </dependency>
        </dependencies>
    </dependencyManagement>

    <!-- 所有模組共用的依賴 -->
    <dependencies>
        <!-- Jakarta EE API（由 Application Server 提供） -->
        <dependency>
            <groupId>jakarta.platform</groupId>
            <artifactId>jakarta.jakartaee-api</artifactId>
            <version>${jakarta.ee.version}</version>
            <scope>provided</scope>
        </dependency>

        <!-- Testing -->
        <dependency>
            <groupId>org.junit.jupiter</groupId>
            <artifactId>junit-jupiter</artifactId>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>org.mockito</groupId>
            <artifactId>mockito-core</artifactId>
            <version>${mockito.version}</version>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>org.mockito</groupId>
            <artifactId>mockito-junit-jupiter</artifactId>
            <version>${mockito.version}</version>
            <scope>test</scope>
        </dependency>
    </dependencies>

    <!-- Plugin 管理 -->
    <build>
        <pluginManagement>
            <plugins>
                <plugin>
                    <groupId>org.apache.maven.plugins</groupId>
                    <artifactId>maven-compiler-plugin</artifactId>
                    <version>${maven-compiler-plugin.version}</version>
                    <configuration>
                        <release>${java.version}</release>
                        <compilerArgs>
                            <arg>-parameters</arg>
                        </compilerArgs>
                    </configuration>
                </plugin>
                <plugin>
                    <groupId>org.apache.maven.plugins</groupId>
                    <artifactId>maven-surefire-plugin</artifactId>
                    <version>${maven-surefire-plugin.version}</version>
                </plugin>
                <plugin>
                    <groupId>org.apache.maven.plugins</groupId>
                    <artifactId>maven-failsafe-plugin</artifactId>
                    <version>${maven-failsafe-plugin.version}</version>
                    <executions>
                        <execution>
                            <goals>
                                <goal>integration-test</goal>
                                <goal>verify</goal>
                            </goals>
                        </execution>
                    </executions>
                </plugin>
                <plugin>
                    <groupId>org.apache.maven.plugins</groupId>
                    <artifactId>maven-war-plugin</artifactId>
                    <version>${maven-war-plugin.version}</version>
                    <configuration>
                        <failOnMissingWebXml>false</failOnMissingWebXml>
                    </configuration>
                </plugin>
                <plugin>
                    <groupId>io.openliberty.tools</groupId>
                    <artifactId>liberty-maven-plugin</artifactId>
                    <version>${liberty-maven-plugin.version}</version>
                </plugin>
                <plugin>
                    <groupId>org.jacoco</groupId>
                    <artifactId>jacoco-maven-plugin</artifactId>
                    <version>${jacoco-plugin.version}</version>
                    <executions>
                        <execution>
                            <goals>
                                <goal>prepare-agent</goal>
                            </goals>
                        </execution>
                        <execution>
                            <id>report</id>
                            <phase>test</phase>
                            <goals>
                                <goal>report</goal>
                            </goals>
                        </execution>
                    </executions>
                </plugin>
            </plugins>
        </pluginManagement>

        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
            </plugin>
            <plugin>
                <groupId>org.jacoco</groupId>
                <artifactId>jacoco-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>

    <!-- Profiles -->
    <profiles>
        <!-- 開發環境 -->
        <profile>
            <id>dev</id>
            <activation>
                <activeByDefault>true</activeByDefault>
            </activation>
            <properties>
                <env>dev</env>
            </properties>
        </profile>
        <!-- 測試環境 -->
        <profile>
            <id>staging</id>
            <properties>
                <env>staging</env>
            </properties>
        </profile>
        <!-- 生產環境 -->
        <profile>
            <id>prod</id>
            <properties>
                <env>prod</env>
            </properties>
        </profile>
        <!-- 安全掃描 -->
        <profile>
            <id>security</id>
            <build>
                <plugins>
                    <plugin>
                        <groupId>org.owasp</groupId>
                        <artifactId>dependency-check-maven</artifactId>
                        <version>10.0.4</version>
                        <executions>
                            <execution>
                                <goals>
                                    <goal>check</goal>
                                </goals>
                            </execution>
                        </executions>
                        <configuration>
                            <failBuildOnCVSS>7</failBuildOnCVSS>
                        </configuration>
                    </plugin>
                </plugins>
            </build>
        </profile>
    </profiles>
</project>

<?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>com.company.app</groupId>
        <artifactId>jakarta-enterprise-app</artifactId>
        <version>1.0.0-SNAPSHOT</version>
    </parent>

    <artifactId>app-domain</artifactId>
    <packaging>jar</packaging>
    <name>Domain Layer</name>
    <description>核心業務邏輯 — 不依賴任何外部框架</description>

    <dependencies>
        <!-- Domain Layer 只依賴 Jakarta Validation 和 Jakarta Persistence API -->
        <dependency>
            <groupId>jakarta.validation</groupId>
            <artifactId>jakarta.validation-api</artifactId>
            <scope>provided</scope>
        </dependency>
        <dependency>
            <groupId>jakarta.persistence</groupId>
            <artifactId>jakarta.persistence-api</artifactId>
            <scope>provided</scope>
        </dependency>
    </dependencies>
</project>

<?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>com.company.app</groupId>
        <artifactId>jakarta-enterprise-app</artifactId>
        <version>1.0.0-SNAPSHOT</version>
    </parent>

    <artifactId>app-application</artifactId>
    <packaging>jar</packaging>
    <name>Application Layer</name>

    <dependencies>
        <dependency>
            <groupId>${project.groupId}</groupId>
            <artifactId>app-domain</artifactId>
        </dependency>
    </dependencies>
</project>

<?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>com.company.app</groupId>
        <artifactId>jakarta-enterprise-app</artifactId>
        <version>1.0.0-SNAPSHOT</version>
    </parent>

    <artifactId>app-infrastructure</artifactId>
    <packaging>jar</packaging>
    <name>Infrastructure Layer</name>

    <dependencies>
        <dependency>
            <groupId>${project.groupId}</groupId>
            <artifactId>app-domain</artifactId>
        </dependency>
        <dependency>
            <groupId>${project.groupId}</groupId>
            <artifactId>app-application</artifactId>
        </dependency>
        <!-- Database -->
        <dependency>
            <groupId>org.postgresql</groupId>
            <artifactId>postgresql</artifactId>
            <scope>runtime</scope>
        </dependency>
        <dependency>
            <groupId>org.flywaydb</groupId>
            <artifactId>flyway-core</artifactId>
        </dependency>
        <!-- Testcontainers -->
        <dependency>
            <groupId>org.testcontainers</groupId>
            <artifactId>postgresql</artifactId>
            <scope>test</scope>
        </dependency>
    </dependencies>
</project>

<?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>com.company.app</groupId>
        <artifactId>jakarta-enterprise-app</artifactId>
        <version>1.0.0-SNAPSHOT</version>
    </parent>

    <artifactId>app-api</artifactId>
    <packaging>war</packaging>
    <name>API Layer</name>

    <dependencies>
        <dependency>
            <groupId>${project.groupId}</groupId>
            <artifactId>app-application</artifactId>
        </dependency>
        <dependency>
            <groupId>${project.groupId}</groupId>
            <artifactId>app-infrastructure</artifactId>
        </dependency>
        <!-- MicroProfile -->
        <dependency>
            <groupId>org.eclipse.microprofile</groupId>
            <artifactId>microprofile</artifactId>
            <type>pom</type>
            <scope>provided</scope>
        </dependency>
        <!-- Integration Test -->
        <dependency>
            <groupId>io.rest-assured</groupId>
            <artifactId>rest-assured</artifactId>
            <version>${rest-assured.version}</version>
            <scope>test</scope>
        </dependency>
    </dependencies>

    <build>
        <finalName>${project.artifactId}</finalName>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-war-plugin</artifactId>
            </plugin>
            <!-- Open Liberty 開發模式 -->
            <plugin>
                <groupId>io.openliberty.tools</groupId>
                <artifactId>liberty-maven-plugin</artifactId>
                <configuration>
                    <serverName>defaultServer</serverName>
                    <deployPackages>all</deployPackages>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>

# 使用 archetype 建立新專案
mvn archetype:generate \
  -DarchetypeGroupId=com.company.archetype \
  -DarchetypeArtifactId=jakarta-ee12-archetype \
  -DarchetypeVersion=1.0.0 \
  -DgroupId=com.company.newapp \
  -DartifactId=my-new-service \
  -Dversion=1.0.0-SNAPSHOT

# 常用 Maven 指令
mvn clean compile              # 編譯
mvn test                       # 執行單元測試
mvn verify                     # 執行整合測試
mvn package                    # 打包 WAR
mvn liberty:dev                # Open Liberty 開發模式（熱部署）
mvn liberty:run                # 啟動 Liberty Server
mvn -Psecurity verify          # 執行安全掃描

/**
 * Input Port：建立訂單的 Use Case 介面。
 * 定義在 Application Layer，由 API Layer 呼叫。
 */
public interface CreateOrderUseCase {
    
    /**
     * 建立訂單。
     * @param command 建立訂單命令
     * @return 訂單 ID
     */
    OrderId execute(CreateOrderCommand command);
}

/**
 * Command 物件使用 Record 定義。
 */
public record CreateOrderCommand(
    CustomerId customerId,
    List<OrderItemCommand> items,
    ShippingAddress shippingAddress
) {
    public CreateOrderCommand {
        Objects.requireNonNull(customerId, "customerId 不可為 null");
        if (items == null || items.isEmpty()) {
            throw new IllegalArgumentException("訂單項目不可為空");
        }
    }
}

/**
 * Output Port：訂單 Repository 介面。
 * 定義在 Domain Layer，由 Infrastructure Layer 實作。
 */
public interface OrderRepository {
    
    Optional<Order> findById(OrderId id);
    
    Order save(Order order);
    
    List<Order> findByCustomerId(CustomerId customerId);
    
    void delete(OrderId id);
}

/**
 * Output Adapter：JPA 實作的 OrderRepository。
 */
@ApplicationScoped
public class JpaOrderRepository implements OrderRepository {

    @PersistenceContext
    private EntityManager em;

    @Override
    public Optional<Order> findById(OrderId id) {
        return Optional.ofNullable(em.find(OrderEntity.class, id.value()))
            .map(OrderMapper::toDomain);
    }

    @Override
    @Transactional
    public Order save(Order order) {
        OrderEntity entity = OrderMapper.toEntity(order);
        if (entity.getId() == null) {
            em.persist(entity);
        } else {
            entity = em.merge(entity);
        }
        return OrderMapper.toDomain(entity);
    }

    @Override
    public List<Order> findByCustomerId(CustomerId customerId) {
        return em.createQuery(
                "SELECT o FROM OrderEntity o WHERE o.customerId = :customerId", 
                OrderEntity.class)
            .setParameter("customerId", customerId.value())
            .getResultList()
            .stream()
            .map(OrderMapper::toDomain)
            .toList();
    }

    @Override
    @Transactional
    public void delete(OrderId id) {
        em.createQuery("DELETE FROM OrderEntity o WHERE o.id = :id")
            .setParameter("id", id.value())
            .executeUpdate();
    }
}

/**
 * Application Service：建立訂單 Use Case 的具體實作。
 */
@ApplicationScoped
@Transactional
public class CreateOrderService implements CreateOrderUseCase {

    private static final Logger logger = Logger.getLogger(CreateOrderService.class.getName());

    @Inject
    private OrderRepository orderRepository;

    @Inject
    private InventoryPort inventoryPort;

    @Inject
    private Event<OrderCreatedEvent> orderCreatedEvent;

    @Override
    public OrderId execute(CreateOrderCommand command) {
        logger.info("建立訂單: customerId=" + command.customerId());

        // 1. 檢查庫存
        for (OrderItemCommand item : command.items()) {
            if (!inventoryPort.checkAvailability(item.productId(), item.quantity())) {
                throw new InsufficientStockException(item.productId());
            }
        }

        // 2. 建立 Domain 物件
        Order order = Order.create(
            command.customerId(),
            command.items().stream()
                .map(i -> new OrderItem(i.productId(), i.quantity(), i.unitPrice()))
                .toList(),
            command.shippingAddress()
        );

        // 3. 持久化
        Order savedOrder = orderRepository.save(order);

        // 4. 發布 Domain Event
        orderCreatedEvent.fire(new OrderCreatedEvent(
            savedOrder.getId(),
            savedOrder.getCustomerId(),
            savedOrder.getTotalAmount(),
            Instant.now()
        ));

        logger.info("訂單建立成功: orderId=" + savedOrder.getId());
        return savedOrder.getId();
    }
}

jakarta-enterprise-app/
├── pom.xml
│
├── app-domain/
│   ├── pom.xml
│   └── src/
│       ├── main/java/com/company/app/domain/
│       │   ├── model/
│       │   │   ├── order/
│       │   │   │   ├── Order.java              # Aggregate Root
│       │   │   │   ├── OrderId.java             # Value Object (Record)
│       │   │   │   ├── OrderItem.java           # Entity
│       │   │   │   ├── OrderStatus.java         # Enum
│       │   │   │   └── Money.java               # Value Object (Record)
│       │   │   ├── customer/
│       │   │   │   ├── Customer.java
│       │   │   │   ├── CustomerId.java
│       │   │   │   └── ShippingAddress.java
│       │   │   └── common/
│       │   │       └── AuditInfo.java
│       │   ├── repository/
│       │   │   ├── OrderRepository.java         # Output Port
│       │   │   └── CustomerRepository.java
│       │   ├── service/
│       │   │   ├── OrderDomainService.java      # Domain Service
│       │   │   └── PricingService.java
│       │   ├── event/
│       │   │   ├── OrderCreatedEvent.java
│       │   │   └── OrderCancelledEvent.java
│       │   └── exception/
│       │       ├── InsufficientStockException.java
│       │       └── OrderNotFoundException.java
│       └── test/java/com/company/app/domain/
│           ├── model/order/OrderTest.java
│           └── service/PricingServiceTest.java
│
├── app-application/
│   ├── pom.xml
│   └── src/
│       ├── main/java/com/company/app/application/
│       │   ├── usecase/
│       │   │   ├── CreateOrderUseCase.java      # Input Port
│       │   │   ├── CreateOrderService.java      # Use Case 實作
│       │   │   ├── QueryOrderUseCase.java
│       │   │   └── CancelOrderUseCase.java
│       │   ├── dto/
│       │   │   ├── CreateOrderCommand.java      # Command (Record)
│       │   │   ├── OrderResponse.java           # Response (Record)
│       │   │   └── PageResponse.java
│       │   └── port/
│       │       ├── InventoryPort.java           # Output Port
│       │       └── NotificationPort.java
│       └── test/java/
│
├── app-infrastructure/
│   ├── pom.xml
│   └── src/
│       ├── main/java/com/company/app/infrastructure/
│       │   ├── persistence/
│       │   │   ├── entity/
│       │   │   │   ├── OrderEntity.java         # JPA Entity
│       │   │   │   └── CustomerEntity.java
│       │   │   ├── repository/
│       │   │   │   ├── JpaOrderRepository.java  # Adapter
│       │   │   │   └── JpaCustomerRepository.java
│       │   │   └── mapper/
│       │   │       └── OrderMapper.java
│       │   ├── messaging/
│       │   │   ├── KafkaEventPublisher.java
│       │   │   └── KafkaOrderConsumer.java
│       │   ├── cache/
│       │   │   └── RedisInventoryAdapter.java
│       │   ├── external/
│       │   │   └── PaymentGatewayClient.java
│       │   └── config/
│       │       ├── DatabaseProducer.java
│       │       └── CacheProducer.java
│       ├── main/resources/
│       │   └── META-INF/
│       │       └── persistence.xml
│       └── test/java/
│
├── app-api/
│   ├── pom.xml
│   └── src/
│       ├── main/java/com/company/app/api/
│       │   ├── resource/
│       │   │   ├── OrderResource.java           # JAX-RS Resource
│       │   │   ├── CustomerResource.java
│       │   │   └── HealthResource.java
│       │   ├── filter/
│       │   │   ├── CorsFilter.java
│       │   │   ├── LoggingFilter.java
│       │   │   └── AuthenticationFilter.java
│       │   ├── mapper/
│       │   │   ├── GlobalExceptionMapper.java
│       │   │   └── ValidationExceptionMapper.java
│       │   └── config/
│       │       └── JakartaRestApplication.java  # Application 配置
│       ├── main/resources/
│       │   └── META-INF/
│       │       ├── beans.xml
│       │       └── microprofile-config.properties
│       ├── main/webapp/WEB-INF/
│       └── test/java/
│
└── docs/
    ├── architecture/
    │   ├── adr/                                  # Architecture Decision Records
    │   └── diagrams/
    └── api/
        └── openapi.yaml

/**
 * 欄位注入（Field Injection）— 最常見但不推薦用於測試。
 */
@ApplicationScoped
public class OrderService {

    @Inject
    private OrderRepository orderRepository;

    @Inject
    private NotificationService notificationService;
}

/**
 * 建構子注入（Constructor Injection）— 推薦方式，易於測試。
 */
@ApplicationScoped
public class OrderService {

    private final OrderRepository orderRepository;
    private final NotificationService notificationService;

    @Inject
    public OrderService(OrderRepository orderRepository,
                        NotificationService notificationService) {
        this.orderRepository = orderRepository;
        this.notificationService = notificationService;
    }
}

/**
 * 方法注入（Method Injection）。
 */
@ApplicationScoped
public class OrderService {

    private OrderRepository orderRepository;

    @Inject
    public void setOrderRepository(OrderRepository orderRepository) {
        this.orderRepository = orderRepository;
    }
}

/**
 * 請求範圍的審計上下文。
 * 每次 HTTP 請求建立新的實例，請求結束自動銷毀。
 */
@RequestScoped
public class AuditContext {

    private String correlationId;
    private String userId;
    private Instant requestTime;

    @PostConstruct
    public void init() {
        this.correlationId = UUID.randomUUID().toString();
        this.requestTime = Instant.now();
    }

    // getter / setter
    public String getCorrelationId() { return correlationId; }
    public void setUserId(String userId) { this.userId = userId; }
    public String getUserId() { return userId; }
    public Instant getRequestTime() { return requestTime; }
}

/**
 * CDI 5.0: @Startup 讓 Bean 在容器啟動時立即初始化。
 * 適合：快取預載、連線池預熱、配置驗證。
 */
@ApplicationScoped
@Startup  // CDI 5.0 新增
public class CacheWarmupService {

    private static final Logger logger = Logger.getLogger(CacheWarmupService.class.getName());

    @Inject
    private ProductRepository productRepository;

    @Inject
    private CacheService cacheService;

    @PostConstruct
    public void warmup() {
        logger.info("應用啟動 — 開始預載快取...");
        
        List<Product> hotProducts = productRepository.findTopProducts(1000);
        hotProducts.forEach(p -> cacheService.put("product:" + p.getId(), p));
        
        logger.info("快取預載完成: " + hotProducts.size() + " 項產品");
    }
}

/**
 * 啟動時驗證外部服務連線。
 */
@ApplicationScoped
@Startup
public class StartupHealthCheck {

    @Inject
    private DataSource dataSource;

    @PostConstruct
    public void validateConnections() {
        // 啟動時驗證資料庫連線
        try (Connection conn = dataSource.getConnection()) {
            if (!conn.isValid(5)) {
                throw new RuntimeException("資料庫連線驗證失敗");
            }
        } catch (SQLException e) {
            throw new RuntimeException("無法連線至資料庫", e);
        }
    }
}

/**
 * CDI Producer：建立非 CDI 管理的物件。
 */
@ApplicationScoped
public class ConfigProducer {

    @Produces
    @ApplicationScoped
    @Named("objectMapper")
    public ObjectMapper createObjectMapper() {
        return new ObjectMapper()
            .registerModule(new JavaTimeModule())
            .disable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS)
            .setSerializationInclusion(JsonInclude.Include.NON_NULL);
    }

    @Produces
    @RequestScoped
    @Named("correlationId")
    public String createCorrelationId() {
        return UUID.randomUUID().toString();
    }
}

/**
 * 自定義 Qualifier 標註。
 */
@Qualifier
@Retention(RUNTIME)
@Target({FIELD, METHOD, PARAMETER, TYPE})
public @interface CacheType {
    CacheProvider value();
    
    enum CacheProvider {
        REDIS, LOCAL, DISTRIBUTED
    }
}

/**
 * 使用 Qualifier 區分不同快取實作。
 */
@ApplicationScoped
@CacheType(CacheProvider.REDIS)
public class RedisCacheService implements CacheService {
    // Redis 實作
}

@ApplicationScoped
@CacheType(CacheProvider.LOCAL)
public class LocalCacheService implements CacheService {
    // 本地記憶體快取實作
}

// 注入時指定
@ApplicationScoped
public class ProductService {
    
    @Inject
    @CacheType(CacheProvider.REDIS)
    private CacheService cacheService;
}

/**
 * 自定義 Interceptor Binding。
 */
@InterceptorBinding
@Retention(RUNTIME)
@Target({TYPE, METHOD})
public @interface Logged {}

/**
 * 日誌記錄 Interceptor。
 */
@Interceptor
@Logged
@Priority(Interceptor.Priority.APPLICATION)
public class LoggingInterceptor {

    private static final Logger logger = Logger.getLogger(LoggingInterceptor.class.getName());

    @AroundInvoke
    public Object logMethodCall(InvocationContext ctx) throws Exception {
        String method = ctx.getMethod().getDeclaringClass().getSimpleName() 
                       + "." + ctx.getMethod().getName();
        long start = System.nanoTime();
        
        logger.info("→ " + method + " 開始");
        try {
            Object result = ctx.proceed();
            long elapsed = (System.nanoTime() - start) / 1_000_000;
            logger.info("← " + method + " 完成 (" + elapsed + "ms)");
            return result;
        } catch (Exception e) {
            long elapsed = (System.nanoTime() - start) / 1_000_000;
            logger.severe("✗ " + method + " 失敗 (" + elapsed + "ms): " + e.getMessage());
            throw e;
        }
    }
}

// 使用
@ApplicationScoped
public class OrderService {
    
    @Logged
    public Order createOrder(CreateOrderCommand command) {
        // 自動記錄進出日誌
        return doCreateOrder(command);
    }
}

@InterceptorBinding
@Retention(RUNTIME)
@Target({TYPE, METHOD})
public @interface Retry {
    int maxAttempts() default 3;
    long delayMs() default 1000;
}

@Interceptor
@Retry
@Priority(Interceptor.Priority.APPLICATION + 10)
public class RetryInterceptor {

    @AroundInvoke
    public Object retry(InvocationContext ctx) throws Exception {
        Retry config = ctx.getMethod().getAnnotation(Retry.class);
        int maxAttempts = config != null ? config.maxAttempts() : 3;
        long delayMs = config != null ? config.delayMs() : 1000;
        
        Exception lastException = null;
        for (int attempt = 1; attempt <= maxAttempts; attempt++) {
            try {
                return ctx.proceed();
            } catch (OptimisticLockException | PessimisticLockException e) {
                lastException = e;
                if (attempt < maxAttempts) {
                    Thread.sleep(delayMs * attempt); // 指數退避
                }
            }
        }
        throw lastException;
    }
}

/**
 * Domain Event 定義。
 */
public record OrderCreatedEvent(
    OrderId orderId,
    CustomerId customerId,
    BigDecimal totalAmount,
    Instant createdAt
) {}

/**
 * 發布 Event。
 */
@ApplicationScoped
public class OrderService {

    @Inject
    private Event<OrderCreatedEvent> orderCreatedEvent;

    @Transactional
    public Order createOrder(CreateOrderCommand command) {
        Order order = /* ... 建立訂單 ... */;
        
        // 同步發布事件
        orderCreatedEvent.fire(new OrderCreatedEvent(
            order.getId(), order.getCustomerId(),
            order.getTotalAmount(), Instant.now()
        ));
        
        // 非同步發布事件
        orderCreatedEvent.fireAsync(new OrderCreatedEvent(
            order.getId(), order.getCustomerId(),
            order.getTotalAmount(), Instant.now()
        ));
        
        return order;
    }
}

/**
 * 觀察（訂閱）Event。
 */
@ApplicationScoped
public class OrderEventHandler {

    @Inject
    private NotificationService notificationService;

    @Inject
    private InventoryService inventoryService;

    /**
     * 同步處理：在同一交易中執行。
     */
    public void onOrderCreated(@Observes OrderCreatedEvent event) {
        inventoryService.reserveStock(event.orderId());
    }

    /**
     * 非同步處理：在獨立執行緒中執行。
     */
    public void onOrderCreatedAsync(@ObservesAsync OrderCreatedEvent event) {
        notificationService.sendOrderConfirmation(event.customerId(), event.orderId());
    }
}

/**
 * CDI 5.0 Build Compatible Extension 範例：
 * 自動為所有 @Audited 註解的 Bean 註冊攔截器。
 */
public class AuditExtension implements BuildCompatibleExtension {

    @Enhancement(types = Object.class, withAnnotations = Audited.class)
    public void addAuditInterceptor(ClassConfig config) {
        config.addAnnotation(AuditInterceptorBinding.class);
    }

    @Registration(types = Object.class)
    public void registerAuditBeans(BeanInfo bean, Messages messages) {
        if (bean.isClassBean() && bean.hasAnnotation(Audited.class)) {
            messages.info("已註冊審計攔截器: " + bean.beanClass().name());
        }
    }

    @Synthesis
    public void synthesizeBeans(SyntheticComponents components) {
        // 合成一個計數器 Bean，統計已審計的 Bean 數量
        components.addBean(AuditCounter.class)
            .type(AuditCounter.class)
            .scope(ApplicationScoped.class)
            .createWith(AuditCounterCreator.class);
    }
}

/**
 * CDI 5.0 新增：在 CDI SE 中程式化註冊 BuildCompatibleExtension。
 */
public class AppMain {
    public static void main(String[] args) {
        try (SeContainer container = SeContainerInitializer.newInstance()
                .addBuildCompatibleExtensions(new AuditExtension())  // CDI 5.0 新增
                .initialize()) {
            
            var service = container.select(OrderService.class).get();
            service.processOrders();
        }
    }
}

/**
 * Jakarta REST Application 配置。
 */
@ApplicationPath("/api/v1")
public class JakartaRestApplication extends Application {
    // 不需要覆寫任何方法 — CDI 自動掃描 Resource
}

/**
 * JSON-B 配置自訂。
 */
@ApplicationScoped
public class JsonbConfigurator {

    @Produces
    public Jsonb createJsonb() {
        JsonbConfig config = new JsonbConfig()
            .withFormatting(true)
            .withNullValues(false)
            .withDateFormat("yyyy-MM-dd'T'HH:mm:ss.SSSZ", Locale.getDefault())
            .withPropertyNamingStrategy(PropertyNamingStrategy.LOWER_CASE_WITH_UNDERSCORES);
        return JsonbBuilder.create(config);
    }
}

/**
 * API Response 封裝。
 */
public record ApiResponse<T>(
    @JsonbProperty("status_code") int statusCode,
    String message,
    T data,
    @JsonbProperty("timestamp") Instant timestamp,
    @JsonbTransient String internalNote  // 不序列化
) {
    public static <T> ApiResponse<T> ok(T data) {
        return new ApiResponse<>(200, "成功", data, Instant.now(), null);
    }

    public static <T> ApiResponse<T> created(T data) {
        return new ApiResponse<>(201, "建立成功", data, Instant.now(), null);
    }

    public static ApiResponse<Void> error(int code, String message) {
        return new ApiResponse<>(code, message, null, Instant.now(), null);
    }
}

/**
 * 使用 Bean Validation 驗證請求參數。
 */
public record CreateOrderRequest(
    @NotBlank(message = "客戶 ID 不可為空")
    @Size(max = 36, message = "客戶 ID 長度不可超過 36")
    String customerId,

    @NotEmpty(message = "訂單項目不可為空")
    @Size(max = 100, message = "單筆訂單最多 100 項商品")
    List<@Valid OrderItemRequest> items,

    @Valid
    @NotNull(message = "收貨地址不可為空")
    AddressRequest shippingAddress,

    @Size(max = 500, message = "備註不可超過 500 字")
    String notes
) {}

public record OrderItemRequest(
    @NotBlank String productId,
    @Min(value = 1, message = "數量至少為 1")
    @Max(value = 9999, message = "數量不可超過 9999")
    int quantity
) {}

public record AddressRequest(
    @NotBlank String city,
    @NotBlank String district,
    @NotBlank String street,
    @Pattern(regexp = "\\d{3,5}", message = "郵遞區號格式錯誤")
    String zipCode
) {}

/**
 * 統一錯誤回應格式。
 */
public record ErrorResponse(
    int status,
    String error,
    String message,
    String path,
    Instant timestamp,
    List<FieldError> fieldErrors
) {
    public record FieldError(String field, String message, Object rejectedValue) {}
}

/**
 * 全域 Exception Mapper。
 */
@Provider
public class GlobalExceptionMapper implements ExceptionMapper<Exception> {

    private static final Logger logger = Logger.getLogger(GlobalExceptionMapper.class.getName());

    @Context
    private UriInfo uriInfo;

    @Override
    public Response toResponse(Exception exception) {
        return switch (exception) {
            case ConstraintViolationException cve -> handleValidation(cve);
            case WebApplicationException wae -> handleWebApp(wae);
            case OrderNotFoundException nfe -> handleNotFound(nfe);
            case InsufficientStockException ise -> handleConflict(ise);
            default -> handleUnexpected(exception);
        };
    }

    private Response handleValidation(ConstraintViolationException e) {
        List<ErrorResponse.FieldError> fieldErrors = e.getConstraintViolations()
            .stream()
            .map(v -> new ErrorResponse.FieldError(
                v.getPropertyPath().toString(),
                v.getMessage(),
                v.getInvalidValue()))
            .toList();

        ErrorResponse error = new ErrorResponse(
            400, "Validation Error", "請求參數驗證失敗",
            uriInfo.getPath(), Instant.now(), fieldErrors);

        return Response.status(400).entity(error).build();
    }

    private Response handleNotFound(OrderNotFoundException e) {
        ErrorResponse error = new ErrorResponse(
            404, "Not Found", e.getMessage(),
            uriInfo.getPath(), Instant.now(), null);
        return Response.status(404).entity(error).build();
    }

    private Response handleConflict(InsufficientStockException e) {
        ErrorResponse error = new ErrorResponse(
            409, "Conflict", e.getMessage(),
            uriInfo.getPath(), Instant.now(), null);
        return Response.status(409).entity(error).build();
    }

    private Response handleWebApp(WebApplicationException e) {
        ErrorResponse error = new ErrorResponse(
            e.getResponse().getStatus(), "Error", e.getMessage(),
            uriInfo.getPath(), Instant.now(), null);
        return Response.status(e.getResponse().getStatus()).entity(error).build();
    }

    private Response handleUnexpected(Exception e) {
        logger.severe("未預期的錯誤: " + e.getMessage());
        ErrorResponse error = new ErrorResponse(
            500, "Internal Server Error", "伺服器內部錯誤，請聯繫系統管理員",
            uriInfo.getPath(), Instant.now(), null);
        return Response.status(500).entity(error).build();
    }
}

/**
 * 訂單 REST Resource — 完整 CRUD API。
 */
@Path("/orders")
@Produces(MediaType.APPLICATION_JSON)
@Consumes(MediaType.APPLICATION_JSON)
@ApplicationScoped
public class OrderResource {

    @Inject
    private CreateOrderUseCase createOrderUseCase;

    @Inject
    private QueryOrderUseCase queryOrderUseCase;

    @Inject
    private CancelOrderUseCase cancelOrderUseCase;

    /**
     * 建立訂單。
     * POST /api/v1/orders
     */
    @POST
    public Response createOrder(@Valid CreateOrderRequest request) {
        CreateOrderCommand command = new CreateOrderCommand(
            new CustomerId(request.customerId()),
            request.items().stream()
                .map(i -> new OrderItemCommand(
                    new ProductId(i.productId()), i.quantity()))
                .toList(),
            mapAddress(request.shippingAddress())
        );

        OrderId orderId = createOrderUseCase.execute(command);

        return Response
            .status(Response.Status.CREATED)
            .entity(ApiResponse.created(Map.of("orderId", orderId.value())))
            .header("Location", "/api/v1/orders/" + orderId.value())
            .build();
    }

    /**
     * 查詢單一訂單。
     * GET /api/v1/orders/{id}
     */
    @GET
    @Path("/{id}")
    public Response getOrder(@PathParam("id") String id) {
        OrderResponse order = queryOrderUseCase.findById(new OrderId(id));
        return Response.ok(ApiResponse.ok(order)).build();
    }

    /**
     * 查詢訂單清單（分頁）。
     * GET /api/v1/orders?page=0&size=20&sort=createdAt,desc
     */
    @GET
    public Response listOrders(
            @QueryParam("page") @DefaultValue("0") int page,
            @QueryParam("size") @DefaultValue("20") int size,
            @QueryParam("sort") @DefaultValue("createdAt,desc") String sort,
            @QueryParam("status") String status,
            @QueryParam("customerId") String customerId) {

        OrderQuery query = new OrderQuery(page, size, sort, status, customerId);
        PageResponse<OrderResponse> result = queryOrderUseCase.findAll(query);
        return Response.ok(ApiResponse.ok(result)).build();
    }

    /**
     * 取消訂單。
     * DELETE /api/v1/orders/{id}
     */
    @DELETE
    @Path("/{id}")
    public Response cancelOrder(@PathParam("id") String id) {
        cancelOrderUseCase.execute(new OrderId(id));
        return Response.noContent().build();
    }
}

/**
 * 通用分頁回應物件。
 */
public record PageResponse<T>(
    List<T> content,
    int page,
    int size,
    long totalElements,
    int totalPages,
    boolean first,
    boolean last
) {
    public static <T> PageResponse<T> of(List<T> content, int page, int size, long total) {
        int totalPages = (int) Math.ceil((double) total / size);
        return new PageResponse<>(
            content, page, size, total, totalPages,
            page == 0, page >= totalPages - 1
        );
    }
}

/**
 * 排序工具類。
 */
public class SortParser {

    /**
     * 解析排序字串。
     * @param sort 格式: "field,direction" 例如 "createdAt,desc"
     */
    public static String toJpql(String sort, Set<String> allowedFields) {
        if (sort == null || sort.isBlank()) {
            return "o.createdAt DESC";
        }
        String[] parts = sort.split(",");
        String field = parts[0].trim();
        String direction = parts.length > 1 ? parts[1].trim().toUpperCase() : "ASC";

        // 白名單驗證 — 防止 SQL Injection
        if (!allowedFields.contains(field)) {
            throw new IllegalArgumentException("不支援的排序欄位: " + field);
        }
        if (!"ASC".equals(direction) && !"DESC".equals(direction)) {
            throw new IllegalArgumentException("不支援的排序方向: " + direction);
        }

        return "o." + field + " " + direction;
    }
}

/**
 * 使用 MicroProfile OpenAPI 註解描述 API。
 */
@Path("/orders")
@Produces(MediaType.APPLICATION_JSON)
@Consumes(MediaType.APPLICATION_JSON)
@Tag(name = "Orders", description = "訂單管理 API")
@ApplicationScoped
public class OrderResource {

    @POST
    @Operation(summary = "建立訂單", description = "建立新的訂單")
    @APIResponse(responseCode = "201", description = "訂單建立成功",
        content = @Content(schema = @Schema(implementation = ApiResponse.class)))
    @APIResponse(responseCode = "400", description = "請求參數錯誤",
        content = @Content(schema = @Schema(implementation = ErrorResponse.class)))
    @APIResponse(responseCode = "409", description = "庫存不足")
    public Response createOrder(
            @RequestBody(description = "訂單建立請求", required = true,
                content = @Content(schema = @Schema(implementation = CreateOrderRequest.class)))
            @Valid CreateOrderRequest request) {
        // ... 實作
    }

    @GET
    @Path("/{id}")
    @Operation(summary = "查詢訂單", description = "依據訂單 ID 查詢訂單詳情")
    @APIResponse(responseCode = "200", description = "查詢成功")
    @APIResponse(responseCode = "404", description = "訂單不存在")
    public Response getOrder(
            @Parameter(description = "訂單 ID", required = true, example = "ORD-20260101-001")
            @PathParam("id") String id) {
        // ... 實作
    }
}

/**
 * JWT 認證過濾器。
 */
@Provider
@Priority(Priorities.AUTHENTICATION)
public class JwtAuthenticationFilter implements ContainerRequestFilter {

    @Inject
    private JsonWebToken jwt;

    @Override
    public void filter(ContainerRequestContext requestContext) {
        // 跳過公開端點
        if (isPublicEndpoint(requestContext)) {
            return;
        }

        String authHeader = requestContext.getHeaderString(HttpHeaders.AUTHORIZATION);
        if (authHeader == null || !authHeader.startsWith("Bearer ")) {
            requestContext.abortWith(
                Response.status(Response.Status.UNAUTHORIZED)
                    .entity(ApiResponse.error(401, "缺少認證 Token"))
                    .build());
        }
    }

    private boolean isPublicEndpoint(ContainerRequestContext ctx) {
        return ctx.getUriInfo().getPath().startsWith("health")
            || ctx.getUriInfo().getPath().startsWith("openapi");
    }
}

/**
 * 角色授權控制。
 */
@Path("/admin/orders")
@RolesAllowed({"ADMIN", "MANAGER"})
@ApplicationScoped
public class AdminOrderResource {

    @GET
    @RolesAllowed("ADMIN")
    public Response getAllOrders() {
        // 僅 ADMIN 可存取
    }

    @DELETE
    @Path("/{id}")
    @RolesAllowed("ADMIN")
    public Response forceDeleteOrder(@PathParam("id") String id) {
        // 僅 ADMIN 可存取
    }
}

/**
 * 基礎實體：共用的審計欄位。
 */
@MappedSuperclass
public abstract class BaseEntity {

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

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

    @Column(name = "created_by", length = 100)
    private String createdBy;

    @Version
    @Column(name = "version")
    private Long version;

    @PrePersist
    protected void onCreate() {
        this.createdAt = Instant.now();
        this.updatedAt = this.createdAt;
    }

    @PreUpdate
    protected void onUpdate() {
        this.updatedAt = Instant.now();
    }

    // getter
    public Instant getCreatedAt() { return createdAt; }
    public Instant getUpdatedAt() { return updatedAt; }
    public Long getVersion() { return version; }
}

/**
 * 訂單實體 — Aggregate Root。
 */
@Entity
@Table(name = "orders", indexes = {
    @Index(name = "idx_order_customer", columnList = "customer_id"),
    @Index(name = "idx_order_status", columnList = "status"),
    @Index(name = "idx_order_created", columnList = "created_at")
})
@NamedQuery(
    name = "Order.findByStatus",
    query = "SELECT o FROM OrderEntity o WHERE o.status = :status ORDER BY o.createdAt DESC"
)
public class OrderEntity extends BaseEntity {

    @Id
    @Column(name = "id", length = 36)
    private String id;

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

    @Enumerated(EnumType.STRING)
    @Column(name = "status", nullable = false, length = 20)
    private OrderStatus status;

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

    @OneToMany(mappedBy = "order", cascade = CascadeType.ALL, orphanRemoval = true,
               fetch = FetchType.LAZY)
    @OrderBy("lineNumber ASC")
    private List<OrderItemEntity> items = new ArrayList<>();

    @Embedded
    private ShippingAddressEmbeddable shippingAddress;

    // === Domain 方法 ===

    public void addItem(OrderItemEntity item) {
        items.add(item);
        item.setOrder(this);
        recalculateTotal();
    }

    public void removeItem(OrderItemEntity item) {
        items.remove(item);
        item.setOrder(null);
        recalculateTotal();
    }

    private void recalculateTotal() {
        this.totalAmount = items.stream()
            .map(i -> i.getUnitPrice().multiply(BigDecimal.valueOf(i.getQuantity())))
            .reduce(BigDecimal.ZERO, BigDecimal::add);
    }

    // getter / setter 略
}

/**
 * 嵌入式 Value Object。
 */
@Embeddable
public class ShippingAddressEmbeddable {

    @Column(name = "ship_city", length = 50)
    private String city;

    @Column(name = "ship_district", length = 50)
    private String district;

    @Column(name = "ship_street", length = 200)
    private String street;

    @Column(name = "ship_zip", length = 10)
    private String zipCode;

    // 建構子、getter
}

/**
 * 抽象 Repository — 通用 CRUD。
 */
@Dependent
public abstract class AbstractRepository<T, ID> {

    @PersistenceContext
    protected EntityManager em;

    private final Class<T> entityClass;

    protected AbstractRepository(Class<T> entityClass) {
        this.entityClass = entityClass;
    }

    public Optional<T> findById(ID id) {
        return Optional.ofNullable(em.find(entityClass, id));
    }

    @Transactional
    public T save(T entity) {
        em.persist(entity);
        return entity;
    }

    @Transactional
    public T update(T entity) {
        return em.merge(entity);
    }

    @Transactional
    public void delete(T entity) {
        em.remove(em.contains(entity) ? entity : em.merge(entity));
    }

    public List<T> findAll(int offset, int limit) {
        CriteriaQuery<T> cq = em.getCriteriaBuilder().createQuery(entityClass);
        cq.select(cq.from(entityClass));
        return em.createQuery(cq)
            .setFirstResult(offset)
            .setMaxResults(limit)
            .getResultList();
    }

    public long count() {
        CriteriaBuilder cb = em.getCriteriaBuilder();
        CriteriaQuery<Long> cq = cb.createQuery(Long.class);
        cq.select(cb.count(cq.from(entityClass)));
        return em.createQuery(cq).getSingleResult();
    }
}

/**
 * 交易管理範例。
 */
@ApplicationScoped
public class TransferService {

    @PersistenceContext
    private EntityManager em;

    /**
     * 帳戶轉帳 — 必須在同一交易中完成。
     */
    @Transactional(Transactional.TxType.REQUIRED)
    public TransferResult transfer(String fromAccountId, String toAccountId, BigDecimal amount) {
        AccountEntity from = em.find(AccountEntity.class, fromAccountId, 
            LockModeType.PESSIMISTIC_WRITE);
        AccountEntity to = em.find(AccountEntity.class, toAccountId,
            LockModeType.PESSIMISTIC_WRITE);

        if (from == null || to == null) {
            throw new AccountNotFoundException("帳戶不存在");
        }
        if (from.getBalance().compareTo(amount) < 0) {
            throw new InsufficientBalanceException("餘額不足");
        }

        from.debit(amount);
        to.credit(amount);

        // 記錄交易紀錄
        TransactionRecord record = new TransactionRecord(
            fromAccountId, toAccountId, amount, Instant.now());
        em.persist(record);

        return new TransferResult(record.getId(), "轉帳成功");
    }
}

/**
 * 樂觀鎖：使用 @Version 欄位。
 * 適合讀多寫少的場景。
 */
@Entity
public class ProductEntity {
    
    @Id
    private String id;
    
    @Version
    private Long version;  // 每次更新自動遞增
    
    private int stockQuantity;
    
    public void decreaseStock(int quantity) {
        if (this.stockQuantity < quantity) {
            throw new InsufficientStockException("庫存不足");
        }
        this.stockQuantity -= quantity;
        // 若同時有其他交易修改，commit 時 @Version 檢查會丟出 OptimisticLockException
    }
}

/**
 * 悲觀鎖：在查詢時鎖定資料列。
 * 適合寫多或資金相關的高一致性場景。
 */
@ApplicationScoped
public class AccountRepository {

    @PersistenceContext
    private EntityManager em;

    public AccountEntity findForUpdate(String accountId) {
        return em.find(AccountEntity.class, accountId, LockModeType.PESSIMISTIC_WRITE);
    }

    /**
     * 使用 JPQL 悲觀鎖。
     */
    public List<AccountEntity> findOverdueForProcessing() {
        return em.createQuery(
                "SELECT a FROM AccountEntity a WHERE a.status = 'OVERDUE'", 
                AccountEntity.class)
            .setLockMode(LockModeType.PESSIMISTIC_WRITE)
            .setHint("jakarta.persistence.lock.timeout", 5000) // 等待 5 秒
            .getResultList();
    }
}

/**
 * 使用 Entity Graph 解決 N+1 查詢問題。
 */
@Entity
@NamedEntityGraph(
    name = "Order.withItems",
    attributeNodes = {
        @NamedAttributeNode("items"),
        @NamedAttributeNode("shippingAddress")
    }
)
public class OrderEntity extends BaseEntity {
    // ...
}

// 使用 Entity Graph
@ApplicationScoped
public class OrderRepository {

    @PersistenceContext
    private EntityManager em;

    public Optional<OrderEntity> findByIdWithItems(String orderId) {
        EntityGraph<?> graph = em.getEntityGraph("Order.withItems");
        
        return Optional.ofNullable(
            em.find(OrderEntity.class, orderId, 
                Map.of("jakarta.persistence.fetchgraph", graph))
        );
    }

    /**
     * 動態 Entity Graph。
     */
    public List<OrderEntity> findByCustomerWithItems(String customerId) {
        EntityGraph<OrderEntity> graph = em.createEntityGraph(OrderEntity.class);
        graph.addAttributeNodes("items", "shippingAddress");

        return em.createQuery(
                "SELECT o FROM OrderEntity o WHERE o.customerId = :cid", OrderEntity.class)
            .setParameter("cid", customerId)
            .setHint("jakarta.persistence.fetchgraph", graph)
            .getResultList();
    }
}

/**
 * Criteria API — 動態查詢建構。
 */
@ApplicationScoped
public class OrderSearchRepository {

    @PersistenceContext
    private EntityManager em;

    /**
     * 動態條件查詢。
     */
    public PageResponse<OrderEntity> search(OrderSearchCriteria criteria) {
        CriteriaBuilder cb = em.getCriteriaBuilder();
        
        // Count Query
        CriteriaQuery<Long> countQuery = cb.createQuery(Long.class);
        Root<OrderEntity> countRoot = countQuery.from(OrderEntity.class);
        countQuery.select(cb.count(countRoot));
        countQuery.where(buildPredicates(cb, countRoot, criteria));
        long total = em.createQuery(countQuery).getSingleResult();

        // Data Query
        CriteriaQuery<OrderEntity> dataQuery = cb.createQuery(OrderEntity.class);
        Root<OrderEntity> dataRoot = dataQuery.from(OrderEntity.class);
        dataQuery.where(buildPredicates(cb, dataRoot, criteria));
        dataQuery.orderBy(cb.desc(dataRoot.get("createdAt")));

        List<OrderEntity> results = em.createQuery(dataQuery)
            .setFirstResult(criteria.page() * criteria.size())
            .setMaxResults(criteria.size())
            .getResultList();

        return PageResponse.of(results, criteria.page(), criteria.size(), total);
    }

    private Predicate[] buildPredicates(CriteriaBuilder cb, Root<OrderEntity> root,
                                         OrderSearchCriteria criteria) {
        List<Predicate> predicates = new ArrayList<>();

        if (criteria.status() != null) {
            predicates.add(cb.equal(root.get("status"), criteria.status()));
        }
        if (criteria.customerId() != null) {
            predicates.add(cb.equal(root.get("customerId"), criteria.customerId()));
        }
        if (criteria.fromDate() != null) {
            predicates.add(cb.greaterThanOrEqualTo(root.get("createdAt"), criteria.fromDate()));
        }
        if (criteria.toDate() != null) {
            predicates.add(cb.lessThanOrEqualTo(root.get("createdAt"), criteria.toDate()));
        }
        if (criteria.minAmount() != null) {
            predicates.add(cb.greaterThanOrEqualTo(root.get("totalAmount"), criteria.minAmount()));
        }

        return predicates.toArray(new Predicate[0]);
    }
}

// Jakarta Query 1.0 — Core Level (JDQL): 所有資料來源通用
@Query("SELECT o FROM Order o WHERE o.status = :status")
List<Order> findByStatus(@Param("status") String status);

// Jakarta Query 1.0 — Extended Level: 僅 RDBMS
@Query("SELECT o FROM Order o JOIN o.items i " +
       "WHERE i.product.category = :category " +
       "GROUP BY o HAVING SUM(i.quantity) > :minQuantity")
List<Order> findBulkOrders(@Param("category") String category,
                           @Param("minQuantity") int minQuantity);

// 自動產生的靜態元模型類別（類似 JPA Metamodel）
// _Product 由 annotation processor 產生
@StaticMetamodel(Product.class)
public interface _Product {
    TextAttribute<Product> name = null;    // 編譯時注入
    TextAttribute<Product> category = null;
    ComparableAttribute<Product, BigDecimal> price = null;
    ComparableAttribute<Product, Integer> stock = null;
}

@Repository
public interface ProductRepository extends CrudRepository<Product, String> {

    /**
     * Fluent Query：使用靜態元模型建構型別安全的查詢條件。
     */
    List<Product> findAll(Restriction<Product> restriction, 
                          Order<Product> order);
}

@ApplicationScoped
public class ProductSearchService {

    @Inject
    private ProductRepository productRepository;

    /**
     * 動態搜尋：根據使用者輸入條件動態組合查詢。
     */
    public List<Product> search(ProductSearchCriteria criteria) {
        // 使用靜態元模型建構型別安全的限制條件
        List<Restriction<Product>> restrictions = new ArrayList<>();
        
        if (criteria.category() != null) {
            restrictions.add(_Product.category.equalTo(criteria.category()));
        }
        if (criteria.minPrice() != null) {
            restrictions.add(_Product.price.greaterThanEqual(criteria.minPrice()));
        }
        if (criteria.maxPrice() != null) {
            restrictions.add(_Product.price.lessThanEqual(criteria.maxPrice()));
        }
        if (criteria.keyword() != null) {
            restrictions.add(_Product.name.contains(criteria.keyword()));
        }
        
        // 組合所有條件（AND）
        Restriction<Product> combined = Restriction.all(restrictions);
        
        // 排序
        Order<Product> order = _Product.price.asc();
        
        return productRepository.findAll(combined, order);
    }
}

@Repository
public interface OrderRepository extends CrudRepository<OrderEntity, String> {

    /**
     * 方法名稱衍生查詢。
     */
    List<OrderEntity> findByStatus(OrderStatus status);

    List<OrderEntity> findByCustomerIdOrderByCreatedAtDesc(String customerId);

    /**
     * 分頁查詢。
     */
    Page<OrderEntity> findByStatus(OrderStatus status, PageRequest pageRequest);

    /**
     * 使用 @Query 自訂查詢（Jakarta Query 語法）。
     */
    @Query("SELECT o FROM OrderEntity o WHERE o.totalAmount > :minAmount AND o.status = :status")
    List<OrderEntity> findHighValueOrders(
        @Param("minAmount") BigDecimal minAmount,
        @Param("status") OrderStatus status);

    /**
     * Jakarta Data 1.1 — Stateful Operations。
     */
    @Persist
    OrderEntity save(OrderEntity order);
    
    @Merge
    OrderEntity update(OrderEntity order);
    
    @Remove
    void remove(OrderEntity order);
    
    @Refresh
    void refresh(OrderEntity order);

    /**
     * 計數查詢。
     */
    long countByStatus(OrderStatus status);

    /**
     * 刪除操作。
     */
    @Delete
    void deleteByStatusAndCreatedAtBefore(OrderStatus status, Instant before);
}

// 使用 Repository
@ApplicationScoped
public class OrderQueryService {

    @Inject
    private OrderRepository orderRepository;

    public PageResponse<OrderResponse> findOrders(int page, int size, OrderStatus status) {
        PageRequest pageRequest = PageRequest.ofPage(page + 1).size(size);
        Page<OrderEntity> result = orderRepository.findByStatus(status, pageRequest);

        List<OrderResponse> content = result.content().stream()
            .map(OrderMapper::toResponse)
            .toList();

        return PageResponse.of(content, page, size, result.totalElements());
    }
}

/**
 * Record Projection — 只查詢需要的欄位。
 */
public record OrderSummary(
    String orderId,
    String customerName,
    BigDecimal totalAmount,
    OrderStatus status
) {}

@Repository
public interface OrderRepository extends CrudRepository<OrderEntity, String> {

    /**
     * Record Projection 查詢：只回傳摘要欄位，避免載入完整 Entity。
     */
    List<OrderSummary> findSummaryByStatus(OrderStatus status);
    
    Page<OrderSummary> findSummaryByCustomerId(String customerId, PageRequest pageRequest);
}

/**
 * Jakarta NoSQL 1.1 — MongoDB 範例。
 * 與 Jakarta Data Repository 整合，使用相同的 Repository 模式。
 */
@Entity
public class ProductDocument {

    @Id
    private String id;

    @Column("product_name")
    private String name;

    @Column("category")
    private String category;

    @Column("tags")
    private List<String> tags;

    @Column("specifications")
    private Map<String, String> specifications;
}

/**
 * NoSQL Repository — 語法與 RDBMS Repository 一致。
 * Jakarta Query Core Level 語法通用於 NoSQL。
 */
@Repository
public interface ProductDocumentRepository extends CrudRepository<ProductDocument, String> {
    List<ProductDocument> findByCategory(String category);
    List<ProductDocument> findByTagsContaining(String tag);
}

// Jakarta Data 1.1 風格
@Repository
public interface ProductRepository extends CrudRepository<Product, String> {
    List<Product> findByCategoryOrderByPriceAsc(String category);
}

// Spring Data JPA 對照
// public interface ProductRepository extends JpaRepository<Product, String> {
//     List<Product> findByCategoryOrderByPriceAsc(String category);
// }
// 語法幾乎相同，遷移成本極低

/**
 * JWT Token 工具類。
 */
@ApplicationScoped
public class JwtTokenService {

    @Inject
    @ConfigProperty(name = "jwt.issuer")
    private String issuer;

    @Inject
    @ConfigProperty(name = "jwt.expiration-minutes", defaultValue = "30")
    private int expirationMinutes;

    private PrivateKey privateKey;
    private PublicKey publicKey;

    @PostConstruct
    public void init() {
        try {
            KeyPairGenerator keyGen = KeyPairGenerator.getInstance("RSA");
            keyGen.initialize(2048);
            KeyPair keyPair = keyGen.generateKeyPair();
            this.privateKey = keyPair.getPrivate();
            this.publicKey = keyPair.getPublic();
        } catch (NoSuchAlgorithmException e) {
            throw new RuntimeException("無法初始化 JWT 金鑰", e);
        }
    }

    /**
     * 產生 JWT Token。
     */
    public String generateToken(String userId, Set<String> roles, Map<String, Object> claims) {
        Instant now = Instant.now();
        Instant expiry = now.plus(expirationMinutes, ChronoUnit.MINUTES);

        return Jwts.builder()
            .setIssuer(issuer)
            .setSubject(userId)
            .setIssuedAt(Date.from(now))
            .setExpiration(Date.from(expiry))
            .claim("groups", roles)
            .claim("upn", userId)
            .addClaims(claims)
            .signWith(privateKey, SignatureAlgorithm.RS256)
            .compact();
    }
}

<!-- server.xml — OpenID Connect 配置 -->
<featureManager>
    <feature>socialLogin-1.0</feature>
    <feature>jwt-1.0</feature>
    <feature>mpJwt-2.1</feature>
</featureManager>

<oidcLogin id="keycloak"
    clientId="${env.OIDC_CLIENT_ID}"
    clientSecret="${env.OIDC_CLIENT_SECRET}"
    discoveryEndpoint="https://keycloak.company.com/realms/app/.well-known/openid-configuration"
    scope="openid profile email"
    signatureAlgorithm="RS256">
</oidcLogin>

<mpJwt id="myMpJwt"
    issuer="https://keycloak.company.com/realms/app"
    jwksUri="https://keycloak.company.com/realms/app/protocol/openid-connect/certs"
    audiences="my-app" />

/**
 * 角色定義。
 */
public final class Roles {
    public static final String ADMIN = "ADMIN";
    public static final String MANAGER = "MANAGER";
    public static final String USER = "USER";
    public static final String AUDITOR = "AUDITOR";
    
    private Roles() {}
}

/**
 * 方法級角色控制（傳統方式）。
 */
@Path("/users")
@ApplicationScoped
public class UserResource {

    @Inject
    private JsonWebToken jwt;

    @Inject
    private SecurityContext securityContext;

    @GET
    @RolesAllowed({Roles.ADMIN, Roles.MANAGER})
    public Response listUsers() {
        String currentUser = jwt.getSubject();
        Set<String> groups = jwt.getGroups();
        // ...
    }

    @GET
    @Path("/me")
    @RolesAllowed({Roles.USER, Roles.ADMIN, Roles.MANAGER})
    public Response getCurrentUser() {
        Principal principal = securityContext.getCallerPrincipal();
        return Response.ok(Map.of("userId", principal.getName())).build();
    }

    @DELETE
    @Path("/{id}")
    @RolesAllowed(Roles.ADMIN)
    public Response deleteUser(@PathParam("id") String id) {
        // 僅 ADMIN 可刪除使用者
    }
}

/**
 * Security 5.0 Permission Store — 使用者友善的權限管理。
 * 權限不再僅綁定角色，可以定義更細粒度的操作權限。
 */
// Permission Store 允許定義如下的權限映射：
// ROLE:ADMIN  -> permission:user:delete, permission:user:create, permission:order:cancel
// ROLE:MANAGER -> permission:order:approve, permission:report:view
// ROLE:USER   -> permission:order:create, permission:order:view:own

/**
 * 基於權限（而非角色）的存取控制。
 */
@Path("/orders")
@ApplicationScoped
public class OrderResource {

    @Inject
    private SecurityContext securityContext;

    @POST
    @Path("/{id}/approve")
    // Security 5.0: 可結合 Permission Store 做細粒度控制
    @RolesAllowed({Roles.MANAGER, Roles.ADMIN})
    public Response approveOrder(@PathParam("id") String orderId) {
        // Permission Store 背後可查詢使用者是否擁有 "order:approve" 權限
        // 而非僅檢查角色
    }
}

/**
 * Security 5.0: 多重認證機制配置。
 * 不同 URL 可使用不同的認證方式。
 */
// /api/** -> JWT Bearer Token 認證
// /admin/** -> Form-based 認證 + MFA
// /internal/** -> CLIENT-CERT 雙向 TLS 認證
// /health/** -> 無認證（公開端點）

/**
 * 認證機制定義（Security 5.0）。
 */
@BasicAuthenticationMechanismDefinition(realmName = "admin-realm")
@FormAuthenticationMechanismDefinition(
    loginToContinue = @LoginToContinue(
        loginPage = "/login.xhtml",
        errorPage = "/login-error.xhtml"
    )
)
@ApplicationScoped
public class SecurityConfig {
    // Security 5.0 允許多重認證機制共存
    // 根據 URL Pattern 自動選擇適當的認證方式
}

/**
 * CLIENT-CERT 認證（Security 5.0 新增）。
 * 適用於服務間通訊的 mTLS 場景。
 */
// Open Liberty 配置範例：
// <ssl id="internalSSL" keyStoreRef="serverKeyStore" 
//      trustStoreRef="clientTrustStore" clientAuthentication="true"/>

/**
 * Rate Limiting Filter — 防止 API 濫用。
 */
@Provider
@Priority(Priorities.USER - 100)
public class RateLimitFilter implements ContainerRequestFilter {

    private final ConcurrentHashMap<String, AtomicInteger> requestCounts 
        = new ConcurrentHashMap<>();

    private static final int MAX_REQUESTS_PER_MINUTE = 100;

    @Override
    public void filter(ContainerRequestContext requestContext) {
        String clientId = extractClientId(requestContext);
        AtomicInteger count = requestCounts.computeIfAbsent(clientId, k -> new AtomicInteger(0));

        if (count.incrementAndGet() > MAX_REQUESTS_PER_MINUTE) {
            requestContext.abortWith(
                Response.status(429)
                    .header("Retry-After", "60")
                    .entity(ApiResponse.error(429, "請求過於頻繁，請稍後再試"))
                    .build());
        }
    }

    private String extractClientId(ContainerRequestContext ctx) {
        String auth = ctx.getHeaderString(HttpHeaders.AUTHORIZATION);
        if (auth != null && auth.startsWith("Bearer ")) {
            return "jwt:" + auth.hashCode();
        }
        return "ip:" + ctx.getHeaderString("X-Forwarded-For");
    }
}

/**
 * Security Headers Filter。
 */
@Provider
public class SecurityHeadersFilter implements ContainerResponseFilter {

    @Override
    public void filter(ContainerRequestContext requestContext, 
                       ContainerResponseContext responseContext) {
        responseContext.getHeaders().putSingle(
            "X-Content-Type-Options", "nosniff");
        responseContext.getHeaders().putSingle(
            "X-Frame-Options", "DENY");
        responseContext.getHeaders().putSingle(
            "X-XSS-Protection", "0");  // 現代瀏覽器建議設為 0，改用 CSP
        responseContext.getHeaders().putSingle(
            "Strict-Transport-Security", "max-age=31536000; includeSubDomains");
        responseContext.getHeaders().putSingle(
            "Cache-Control", "no-store");
        responseContext.getHeaders().putSingle(
            "Content-Security-Policy", "default-src 'self'");
        responseContext.getHeaders().putSingle(
            "Referrer-Policy", "strict-origin-when-cross-origin");
        responseContext.getHeaders().putSingle(
            "Permissions-Policy", "camera=(), microphone=(), geolocation=()");
    }
}

/**
 * 安全的輸入驗證範例。
 */
@ApplicationScoped
public class InputValidator {

    private static final Pattern SAFE_STRING = Pattern.compile("^[a-zA-Z0-9\\-_]{1,100}$");
    private static final Pattern EMAIL_PATTERN = Pattern.compile(
        "^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$");

    /**
     * 驗證輸入字串是否安全。
     */
    public String sanitize(String input) {
        if (input == null) return null;
        return input.replaceAll("[<>\"'&]", "");
    }

    /**
     * 驗證 ID 格式（防止注入）。
     */
    public boolean isValidId(String id) {
        return id != null && SAFE_STRING.matcher(id).matches();
    }
}

/**
 * 使用 ManagedExecutorService 執行並行任務。
 */
@ApplicationScoped
public class ReportService {

    @Resource(name = "concurrent/reportExecutor")
    private ManagedExecutorService executor;

    /**
     * 並行產生多份報表。
     */
    public Map<String, ReportResult> generateReports(List<String> reportTypes) {
        Map<String, Future<ReportResult>> futures = new HashMap<>();

        for (String type : reportTypes) {
            futures.put(type, executor.submit(() -> generateReport(type)));
        }

        Map<String, ReportResult> results = new HashMap<>();
        for (Map.Entry<String, Future<ReportResult>> entry : futures.entrySet()) {
            try {
                results.put(entry.getKey(), entry.getValue().get(30, TimeUnit.SECONDS));
            } catch (Exception e) {
                results.put(entry.getKey(), ReportResult.error(e.getMessage()));
            }
        }
        return results;
    }
}

/**
 * 非同步 REST 處理。
 */
@Path("/reports")
@ApplicationScoped
public class ReportResource {

    @Resource
    private ManagedExecutorService executor;

    @Inject
    private ReportService reportService;

    /**
     * 非同步生成報表。
     */
    @POST
    @Path("/generate")
    public void generateReportAsync(
            @QueryParam("type") String type,
            @Suspended AsyncResponse asyncResponse) {

        // 設定超時
        asyncResponse.setTimeout(60, TimeUnit.SECONDS);
        asyncResponse.setTimeoutHandler(ar ->
            ar.resume(Response.status(408)
                .entity(ApiResponse.error(408, "報表生成超時"))
                .build()));

        executor.submit(() -> {
            try {
                ReportResult result = reportService.generateReport(type);
                asyncResponse.resume(Response.ok(ApiResponse.ok(result)).build());
            } catch (Exception e) {
                asyncResponse.resume(Response.serverError()
                    .entity(ApiResponse.error(500, "報表生成失敗"))
                    .build());
            }
        });
    }
}

/**
 * Jakarta Concurrency 3.2 + Virtual Thread。
 * 配置 ManagedExecutorService 使用 Virtual Thread。
 */
// Open Liberty server.xml
// <managedExecutorService jndiName="concurrent/virtualExecutor">
//     <virtualThreads>true</virtualThreads>
// </managedExecutorService>

@ApplicationScoped
public class HighConcurrencyService {

    @Resource(name = "concurrent/virtualExecutor")
    private ManagedExecutorService virtualExecutor;

    /**
     * 使用 Virtual Thread 批次處理。
     * 可同時處理數千個任務，不受執行緒池大小限制。
     */
    public List<ProcessResult> batchProcess(List<Task> tasks) {
        List<Future<ProcessResult>> futures = tasks.stream()
            .map(task -> virtualExecutor.submit(() -> processTask(task)))
            .toList();

        return futures.stream()
            .map(f -> {
                try {
                    return f.get(10, TimeUnit.SECONDS);
                } catch (Exception e) {
                    return ProcessResult.error(e.getMessage());
                }
            })
            .toList();
    }
}

/**
 * Bulkhead Pattern（艙壁模式）：隔離不同類型的任務。
 */
@ApplicationScoped
public class BulkheadService {

    @Resource(name = "concurrent/orderExecutor")
    private ManagedExecutorService orderExecutor;    // 訂單處理專用

    @Resource(name = "concurrent/reportExecutor")
    private ManagedExecutorService reportExecutor;   // 報表專用

    @Resource(name = "concurrent/notifyExecutor")
    private ManagedExecutorService notifyExecutor;   // 通知專用

    /**
     * 訂單處理不會因報表生成佔用而受影響。
     */
    public Future<OrderResult> processOrder(Order order) {
        return orderExecutor.submit(() -> doProcessOrder(order));
    }

    public Future<ReportResult> generateReport(String type) {
        return reportExecutor.submit(() -> doGenerateReport(type));
    }
}

<!-- META-INF/batch-jobs/daily-settlement.xml -->
<job id="dailySettlement" xmlns="https://jakarta.ee/xml/ns/jakartaee"
     restartable="true">
    
    <step id="validateData" next="processSettlement">
        <batchlet ref="dataValidationBatchlet" />
    </step>
    
    <step id="processSettlement" next="generateReport">
        <chunk item-count="100" retry-limit="3" skip-limit="10">
            <reader ref="settlementReader" />
            <processor ref="settlementProcessor" />
            <writer ref="settlementWriter" />
            <retryable-exception-classes>
                <include class="java.sql.SQLTransientException" />
            </retryable-exception-classes>
            <skippable-exception-classes>
                <include class="com.company.app.InvalidRecordException" />
            </skippable-exception-classes>
        </chunk>
    </step>
    
    <step id="generateReport">
        <batchlet ref="reportBatchlet" />
    </step>
</job>

/**
 * ItemReader：讀取待結算交易。
 */
@Dependent
@Named("settlementReader")
public class SettlementReader implements ItemReader {

    @PersistenceContext
    private EntityManager em;

    private List<TransactionEntity> transactions;
    private int index;

    @Override
    public void open(Serializable checkpoint) {
        index = checkpoint != null ? (int) checkpoint : 0;
        transactions = em.createQuery(
                "SELECT t FROM TransactionEntity t WHERE t.status = 'PENDING' ORDER BY t.id",
                TransactionEntity.class)
            .getResultList();
    }

    @Override
    public TransactionEntity readItem() {
        if (index >= transactions.size()) return null;
        return transactions.get(index++);
    }

    @Override
    public Serializable checkpointInfo() {
        return index;
    }
}

/**
 * ItemProcessor：計算結算金額。
 */
@Dependent
@Named("settlementProcessor")
public class SettlementProcessor implements ItemProcessor {

    @Inject
    private FeeCalculator feeCalculator;

    @Override
    public SettlementResult processItem(Object item) {
        TransactionEntity tx = (TransactionEntity) item;
        BigDecimal fee = feeCalculator.calculate(tx);
        BigDecimal netAmount = tx.getAmount().subtract(fee);
        return new SettlementResult(tx.getId(), netAmount, fee);
    }
}

/**
 * ItemWriter：批次寫入結算結果。
 */
@Dependent
@Named("settlementWriter")
public class SettlementWriter implements ItemWriter {

    @PersistenceContext
    private EntityManager em;

    @Override
    public void writeItems(List<Object> items) {
        for (Object item : items) {
            SettlementResult result = (SettlementResult) item;
            em.persist(result.toEntity());
        }
        em.flush();
    }
}

<!-- 使用 Partition 實現平行處理 -->
<step id="parallelProcess">
    <chunk item-count="50">
        <reader ref="partitionedReader" />
        <processor ref="settlementProcessor" />
        <writer ref="settlementWriter" />
    </chunk>
    <partition>
        <mapper ref="settlementPartitionMapper" />
    </partition>
</step>

/**
 * Partition Mapper：將資料分成多個分區並行處理。
 */
@Dependent
@Named("settlementPartitionMapper")
public class SettlementPartitionMapper implements PartitionMapper {

    @PersistenceContext
    private EntityManager em;

    @Override
    public PartitionPlan mapPartitions() {
        long totalRecords = em.createQuery(
            "SELECT COUNT(t) FROM TransactionEntity t WHERE t.status = 'PENDING'", Long.class)
            .getSingleResult();

        int partitions = Math.min(10, (int) Math.ceil(totalRecords / 1000.0));
        long batchSize = totalRecords / partitions;

        PartitionPlanImpl plan = new PartitionPlanImpl();
        plan.setPartitions(partitions);
        plan.setThreads(partitions);

        Properties[] props = new Properties[partitions];
        for (int i = 0; i < partitions; i++) {
            props[i] = new Properties();
            props[i].setProperty("startId", String.valueOf(i * batchSize));
            props[i].setProperty("endId", String.valueOf((i + 1) * batchSize));
        }
        plan.setPartitionProperties(props);
        return plan;
    }
}

/**
 * Redis 快取服務 — 使用 Jedis Client。
 */
@ApplicationScoped
public class RedisCacheService {

    private JedisPool jedisPool;

    @Inject
    @ConfigProperty(name = "redis.host", defaultValue = "localhost")
    private String redisHost;

    @Inject
    @ConfigProperty(name = "redis.port", defaultValue = "6379")
    private int redisPort;

    @PostConstruct
    public void init() {
        JedisPoolConfig config = new JedisPoolConfig();
        config.setMaxTotal(50);
        config.setMaxIdle(20);
        config.setMinIdle(5);
        config.setTestOnBorrow(true);
        jedisPool = new JedisPool(config, redisHost, redisPort);
    }

    @PreDestroy
    public void destroy() {
        if (jedisPool != null) jedisPool.close();
    }

    /**
     * 快取查詢結果。
     */
    public <T> Optional<T> get(String key, Class<T> type) {
        try (Jedis jedis = jedisPool.getResource()) {
            String value = jedis.get(key);
            if (value == null) return Optional.empty();
            return Optional.of(JsonbBuilder.create().fromJson(value, type));
        }
    }

    public void put(String key, Object value, int ttlSeconds) {
        try (Jedis jedis = jedisPool.getResource()) {
            String json = JsonbBuilder.create().toJson(value);
            jedis.setex(key, ttlSeconds, json);
        }
    }

    public void evict(String key) {
        try (Jedis jedis = jedisPool.getResource()) {
            jedis.del(key);
        }
    }
}

/**
 * Cache Aside Pattern 實作。
 */
@ApplicationScoped
public class CachedProductService {

    @Inject
    private RedisCacheService cache;

    @Inject
    private ProductRepository productRepository;

    private static final int CACHE_TTL = 3600; // 1 小時

    public ProductResponse getProduct(String productId) {
        String cacheKey = "product:" + productId;

        // 1. 先查快取
        Optional<ProductResponse> cached = cache.get(cacheKey, ProductResponse.class);
        if (cached.isPresent()) return cached.get();

        // 2. 查資料庫
        ProductEntity entity = productRepository.findById(productId)
            .orElseThrow(() -> new ProductNotFoundException(productId));
        ProductResponse response = ProductMapper.toResponse(entity);

        // 3. 寫入快取
        cache.put(cacheKey, response, CACHE_TTL);
        return response;
    }

    @Transactional
    public void updateProduct(String productId, UpdateProductRequest request) {
        // 更新資料庫
        productRepository.update(productId, request);
        // 清除快取
        cache.evict("product:" + productId);
    }
}

/**
 * Kafka Producer — 發送領域事件。
 */
@ApplicationScoped
public class KafkaEventPublisher {

    private KafkaProducer<String, String> producer;

    @Inject
    @ConfigProperty(name = "kafka.bootstrap.servers")
    private String bootstrapServers;

    @PostConstruct
    public void init() {
        Properties props = new Properties();
        props.put(ProducerConfig.BOOTSTRAP_SERVERS_CONFIG, bootstrapServers);
        props.put(ProducerConfig.KEY_SERIALIZER_CLASS_CONFIG, StringSerializer.class.getName());
        props.put(ProducerConfig.VALUE_SERIALIZER_CLASS_CONFIG, StringSerializer.class.getName());
        props.put(ProducerConfig.ACKS_CONFIG, "all");
        props.put(ProducerConfig.RETRIES_CONFIG, 3);
        props.put(ProducerConfig.ENABLE_IDEMPOTENCE_CONFIG, true);
        producer = new KafkaProducer<>(props);
    }

    public void publish(String topic, String key, Object event) {
        String json = JsonbBuilder.create().toJson(event);
        ProducerRecord<String, String> record = new ProducerRecord<>(topic, key, json);
        producer.send(record, (metadata, exception) -> {
            if (exception != null) {
                Logger.getLogger(getClass().getName())
                    .severe("Kafka 發送失敗: " + exception.getMessage());
            }
        });
    }

    @PreDestroy
    public void close() {
        if (producer != null) producer.close();
    }
}

/**
 * Kafka Consumer — 使用 MicroProfile Reactive Messaging（推薦）。
 */
@ApplicationScoped
public class OrderEventConsumer {

    @Inject
    private InventoryService inventoryService;

    @Incoming("order-events")
    public CompletionStage<Void> onOrderEvent(Message<String> message) {
        try {
            OrderCreatedEvent event = JsonbBuilder.create()
                .fromJson(message.getPayload(), OrderCreatedEvent.class);
            inventoryService.reserveStock(event.orderId());
            return message.ack();
        } catch (Exception e) {
            return message.nack(e);
        }
    }
}

/**
 * JMS + RabbitMQ 整合（使用 Jakarta Messaging 3.1）。
 */
@ApplicationScoped
public class JmsNotificationSender {

    @Resource(lookup = "jms/notificationQueue")
    private Queue notificationQueue;

    @Inject
    private JMSContext jmsContext;

    /**
     * 發送通知訊息到 Queue。
     */
    public void sendNotification(NotificationMessage notification) {
        String json = JsonbBuilder.create().toJson(notification);
        jmsContext.createProducer()
            .setDeliveryMode(DeliveryMode.PERSISTENT)
            .setTimeToLive(3600_000) // 1 小時後過期
            .send(notificationQueue, json);
    }
}

/**
 * MDB（Message Driven Bean）— 訊息消費者。
 */
@MessageDriven(activationConfig = {
    @ActivationConfigProperty(propertyName = "destinationLookup", propertyValue = "jms/notificationQueue"),
    @ActivationConfigProperty(propertyName = "destinationType", propertyValue = "jakarta.jms.Queue"),
    @ActivationConfigProperty(propertyName = "maxSession", propertyValue = "10")
})
public class NotificationMDB implements MessageListener {

    @Inject
    private EmailService emailService;

    @Override
    public void onMessage(Message message) {
        try {
            String json = message.getBody(String.class);
            NotificationMessage notification = JsonbBuilder.create()
                .fromJson(json, NotificationMessage.class);
            emailService.send(notification);
        } catch (JMSException e) {
            Logger.getLogger(getClass().getName()).severe("訊息處理失敗: " + e.getMessage());
        }
    }
}

/**
 * Jakarta Messaging 3.1 — 簡化 API 範例。
 */
@ApplicationScoped
public class MessagingService {

    @Inject
    private JMSContext jmsContext;

    @Resource(lookup = "jms/orderTopic")
    private Topic orderTopic;

    @Resource(lookup = "jms/deadLetterQueue")
    private Queue deadLetterQueue;

    /**
     * 發送訊息至 Topic（簡化 API）。
     */
    public void publishOrderEvent(OrderEvent event) {
        String json = JsonbBuilder.create().toJson(event);
        jmsContext.createProducer()
            .setDeliveryMode(DeliveryMode.PERSISTENT)
            .setProperty("eventType", event.type().name())
            .send(orderTopic, json);
    }

    /**
     * 延遲傳送 — 例如 30 分鐘後自動取消未付款訂單。
     */
    public void scheduleOrderTimeout(String orderId, long delayMillis) {
        jmsContext.createProducer()
            .setDeliveryDelay(delayMillis)
            .send(deadLetterQueue, orderId);
    }
}

/**
 * 共享持久訂閱 — 多個 Consumer 共享同一 Topic 訂閱。
 * 適用於微服務水平擴展場景。
 */
@MessageDriven(activationConfig = {
    @ActivationConfigProperty(
        propertyName = "destinationLookup", propertyValue = "jms/orderTopic"),
    @ActivationConfigProperty(
        propertyName = "destinationType", propertyValue = "jakarta.jms.Topic"),
    @ActivationConfigProperty(
        propertyName = "subscriptionDurability", propertyValue = "Durable"),
    @ActivationConfigProperty(
        propertyName = "subscriptionName", propertyValue = "orderProcessing"),
    @ActivationConfigProperty(
        propertyName = "shareSubscriptions", propertyValue = "true")
})
public class SharedOrderSubscriber implements MessageListener {

    @Override
    public void onMessage(Message message) {
        try {
            String json = message.getBody(String.class);
            // 多個 Pod 共享訂閱，每條訊息只被一個 Consumer 處理
        } catch (JMSException e) {
            throw new RuntimeException("訊息處理失敗", e);
        }
    }
}

# === Multi-Stage Build — Jakarta EE 12 Application ===

# Stage 1: Build
FROM maven:3.9-eclipse-temurin-21 AS builder
WORKDIR /build
COPY pom.xml .
COPY app-domain/pom.xml app-domain/
COPY app-application/pom.xml app-application/
COPY app-infrastructure/pom.xml app-infrastructure/
COPY app-api/pom.xml app-api/
# 先下載依賴（利用 Docker Layer Cache）
RUN mvn dependency:go-offline -B
COPY . .
RUN mvn clean package -DskipTests -B

# Stage 2: Runtime
FROM icr.io/appcafe/open-liberty:24.0.0.12-kernel-slim-java21-openj9-ubi-minimal

# 安裝需要的 Feature
COPY --chown=1001:0 src/main/liberty/config/server.xml /config/
RUN features.sh

# 複製應用程式
COPY --from=builder --chown=1001:0 /build/app-api/target/app-api.war /config/apps/

# 複製 JDBC Driver
COPY --chown=1001:0 lib/postgresql-*.jar /config/lib/

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

# 安全性：使用非 root 使用者
USER 1001

EXPOSE 9080 9443

# k8s/deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: jakarta-app
  namespace: production
  labels:
    app: jakarta-app
    version: v1.0.0
spec:
  replicas: 3
  selector:
    matchLabels:
      app: jakarta-app
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxSurge: 1
      maxUnavailable: 0
  template:
    metadata:
      labels:
        app: jakarta-app
        version: v1.0.0
      annotations:
        prometheus.io/scrape: "true"
        prometheus.io/port: "9080"
        prometheus.io/path: "/metrics"
    spec:
      serviceAccountName: jakarta-app-sa
      securityContext:
        runAsNonRoot: true
        runAsUser: 1001
        fsGroup: 1001
      containers:
        - name: jakarta-app
          image: registry.company.com/jakarta-app:1.0.0
          imagePullPolicy: IfNotPresent
          ports:
            - containerPort: 9080
              name: http
              protocol: TCP
            - containerPort: 9443
              name: https
              protocol: TCP
          env:
            - name: DB_HOST
              valueFrom:
                configMapKeyRef:
                  name: jakarta-app-config
                  key: db.host
            - name: DB_PASSWORD
              valueFrom:
                secretKeyRef:
                  name: jakarta-app-secrets
                  key: db.password
            - name: JAVA_OPTS
              value: >-
                -Xms512m -Xmx1g
                -XX:+UseG1GC
                -XX:+UseContainerSupport
                -XX:MaxRAMPercentage=75.0
          resources:
            requests:
              cpu: "500m"
              memory: "1Gi"
            limits:
              cpu: "2000m"
              memory: "2Gi"
          livenessProbe:
            httpGet:
              path: /health/live
              port: 9080
            initialDelaySeconds: 30
            periodSeconds: 10
            failureThreshold: 3
          readinessProbe:
            httpGet:
              path: /health/ready
              port: 9080
            initialDelaySeconds: 15
            periodSeconds: 5
            failureThreshold: 3
          startupProbe:
            httpGet:
              path: /health/started
              port: 9080
            initialDelaySeconds: 10
            periodSeconds: 5
            failureThreshold: 30
          volumeMounts:
            - name: config-volume
              mountPath: /config/configDropins/overrides
              readOnly: true
      volumes:
        - name: config-volume
          configMap:
            name: jakarta-app-liberty-config

# k8s/service.yaml
apiVersion: v1
kind: Service
metadata:
  name: jakarta-app-service
  namespace: production
spec:
  selector:
    app: jakarta-app
  ports:
    - name: http
      port: 80
      targetPort: 9080
      protocol: TCP
  type: ClusterIP
---
# k8s/ingress.yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: jakarta-app-ingress
  namespace: production
  annotations:
    nginx.ingress.kubernetes.io/ssl-redirect: "true"
    nginx.ingress.kubernetes.io/rate-limit: "100"
    nginx.ingress.kubernetes.io/rate-limit-window: "1m"
    cert-manager.io/cluster-issuer: "letsencrypt-prod"
spec:
  ingressClassName: nginx
  tls:
    - hosts:
        - api.company.com
      secretName: api-tls-secret
  rules:
    - host: api.company.com
      http:
        paths:
          - path: /api
            pathType: Prefix
            backend:
              service:
                name: jakarta-app-service
                port:
                  number: 80

# k8s/configmap.yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: jakarta-app-config
  namespace: production
data:
  db.host: "postgres-service.database.svc.cluster.local"
  db.port: "5432"
  db.name: "appdb"
  kafka.bootstrap.servers: "kafka-0.kafka.messaging.svc.cluster.local:9092"
  redis.host: "redis-service.cache.svc.cluster.local"
---
# k8s/secret.yaml（使用 SealedSecret 或 External Secrets Operator）
apiVersion: v1
kind: Secret
metadata:
  name: jakarta-app-secrets
  namespace: production
type: Opaque
data:
  db.password: <base64-encoded>
  jwt.secret: <base64-encoded>
  redis.password: <base64-encoded>

# k8s/hpa.yaml
apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: jakarta-app-hpa
  namespace: production
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: jakarta-app
  minReplicas: 3
  maxReplicas: 20
  metrics:
    - type: Resource
      resource:
        name: cpu
        target:
          type: Utilization
          averageUtilization: 70
    - type: Resource
      resource:
        name: memory
        target:
          type: Utilization
          averageUtilization: 80
  behavior:
    scaleUp:
      stabilizationWindowSeconds: 60
      policies:
        - type: Percent
          value: 50
          periodSeconds: 60
    scaleDown:
      stabilizationWindowSeconds: 300
      policies:
        - type: Percent
          value: 10
          periodSeconds: 120

# Ingress 啟用 HTTP/3（以 nginx-ingress 為例）
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: jakarta-app-ingress
  annotations:
    nginx.ingress.kubernetes.io/enable-http3: "true"
    nginx.ingress.kubernetes.io/quic: "true"
spec:
  ingressClassName: nginx
  tls:
    - hosts:
        - api.company.com
      secretName: api-tls-secret
  rules:
    - host: api.company.com
      http:
        paths:
          - path: /api
            pathType: Prefix
            backend:
              service:
                name: jakarta-app-service
                port:
                  number: 80

/**
 * MicroProfile Config — 外部化配置。
 */
@ApplicationScoped
public class AppConfig {

    // 簡單型別注入
    @Inject
    @ConfigProperty(name = "app.name", defaultValue = "Jakarta App")
    private String appName;

    @Inject
    @ConfigProperty(name = "app.max-retry", defaultValue = "3")
    private int maxRetry;

    @Inject
    @ConfigProperty(name = "app.features.cache-enabled", defaultValue = "true")
    private boolean cacheEnabled;

    // Optional 型別 — 配置可能不存在
    @Inject
    @ConfigProperty(name = "app.custom-header")
    private Optional<String> customHeader;

    // Provider 型別 — 動態取值
    @Inject
    @ConfigProperty(name = "app.rate-limit")
    private Provider<Integer> rateLimit;

    public int getCurrentRateLimit() {
        return rateLimit.get(); // 每次呼叫都取最新值
    }
}

# META-INF/microprofile-config.properties
app.name=Jakarta EE 12 Demo
app.max-retry=3
app.features.cache-enabled=true
app.rate-limit=100

# 資料庫配置
db.host=${DB_HOST:localhost}
db.port=${DB_PORT:5432}
db.name=${DB_NAME:appdb}

# JWT 配置
jwt.issuer=https://auth.company.com
jwt.expiration-minutes=30

/**
 * Jakarta Config 1.0（候選規格）— 概念示範。
 * 若正式納入 Jakarta EE 12，將標準化配置注入。
 */
@ApplicationScoped
public class JakartaConfigExample {

    // 與 MicroProfile Config 語法高度一致
    @Inject
    @ConfigProperty(name = "app.database.url")
    private String databaseUrl;

    // Profile 支援：dev / staging / production
    @Inject
    @ConfigProperty(name = "app.cache.ttl-seconds", defaultValue = "3600")
    private int cacheTtlSeconds;

    // 動態配置觀察
    @Inject
    @ConfigProperty(name = "app.feature.new-ui-enabled")
    private Provider<Boolean> newUiEnabled;

    public boolean isNewUiEnabled() {
        return newUiEnabled.get(); // 每次呼叫取得最新值
    }
}

/**
 * 就緒探針 — 檢查外部依賴。
 */
@Readiness
@ApplicationScoped
public class DatabaseHealthCheck implements HealthCheck {

    @Resource(lookup = "jdbc/appDB")
    private DataSource dataSource;

    @Override
    public HealthCheckResponse call() {
        try (Connection conn = dataSource.getConnection()) {
            boolean valid = conn.isValid(5);
            return HealthCheckResponse.named("database")
                .status(valid)
                .withData("vendor", conn.getMetaData().getDatabaseProductName())
                .withData("url", conn.getMetaData().getURL())
                .build();
        } catch (SQLException e) {
            return HealthCheckResponse.named("database")
                .down()
                .withData("error", e.getMessage())
                .build();
        }
    }
}

/**
 * 存活探針 — 檢查應用基本狀態。
 */
@Liveness
@ApplicationScoped
public class AppLivenessCheck implements HealthCheck {

    @Override
    public HealthCheckResponse call() {
        long freeMemory = Runtime.getRuntime().freeMemory();
        long totalMemory = Runtime.getRuntime().totalMemory();
        double memoryUsage = 1.0 - ((double) freeMemory / totalMemory);

        return HealthCheckResponse.named("app-liveness")
            .status(memoryUsage < 0.95) // 記憶體使用率 < 95%
            .withData("memoryUsage", String.format("%.1f%%", memoryUsage * 100))
            .build();
    }
}

/**
 * 啟動探針。
 */
@Startup
@ApplicationScoped
public class AppStartupCheck implements HealthCheck {

    private volatile boolean ready = false;

    @PostConstruct
    public void init() {
        ready = true;
    }

    @Override
    public HealthCheckResponse call() {
        return HealthCheckResponse.named("app-startup")
            .status(ready)
            .build();
    }
}

/**
 * MicroProfile Metrics — 自訂業務指標。
 */
@ApplicationScoped
public class OrderMetricsService {

    @Inject
    private MetricRegistry metricRegistry;

    @Counted(name = "orders_created_total", description = "建立的訂單總數")
    @Timed(name = "order_creation_duration", description = "訂單建立耗時")
    public Order createOrder(CreateOrderCommand command) {
        // 自動計數和計時
        return doCreateOrder(command);
    }

    /**
     * 手動操作 Gauge。
     */
    @PostConstruct
    public void registerGauges() {
        metricRegistry.gauge("orders_pending_count", 
            () -> countPendingOrders());
    }

    /**
     * Histogram — 記錄訂單金額分佈。
     */
    public void recordOrderAmount(BigDecimal amount) {
        Histogram histogram = metricRegistry.histogram("order_amount_distribution");
        histogram.update(amount.longValue());
    }
}

/**
 * OpenAPI 全域設定。
 */
@OpenAPIDefinition(
    info = @Info(
        title = "Jakarta EE 12 企業應用 API",
        version = "1.0.0",
        description = "企業級訂單管理系統 REST API",
        contact = @Contact(name = "架構團隊", email = "arch@company.com")
    ),
    servers = {
        @Server(url = "https://api.company.com", description = "Production"),
        @Server(url = "https://staging-api.company.com", description = "Staging"),
        @Server(url = "http://localhost:9080", description = "Development")
    },
    security = @SecurityRequirement(name = "bearerAuth")
)
@SecurityScheme(
    securitySchemeName = "bearerAuth",
    type = SecuritySchemeType.HTTP,
    scheme = "bearer",
    bearerFormat = "JWT"
)
public class OpenApiConfig {
}

/**
 * MicroProfile JWT — 在微服務間傳播 Token。
 */
@ApplicationScoped
public class InventoryClient {

    @Inject
    @RestClient
    private InventoryServiceApi inventoryApi;

    @Inject
    private JsonWebToken jwt;

    /**
     * 呼叫庫存服務時自動傳播 JWT。
     */
    public StockInfo checkStock(String productId) {
        return inventoryApi.getStock(productId);
    }
}

/**
 * MicroProfile Rest Client 定義。
 */
@RegisterRestClient(configKey = "inventory-service")
@Path("/api/v1/inventory")
public interface InventoryServiceApi {

    @GET
    @Path("/{productId}/stock")
    @Produces(MediaType.APPLICATION_JSON)
    StockInfo getStock(@PathParam("productId") String productId);
}

# microprofile-config.properties
inventory-service/mp-rest/url=http://inventory-service:9080
inventory-service/mp-rest/scope=jakarta.enterprise.context.RequestScoped

/**
 * MicroProfile Fault Tolerance — 容錯機制。
 */
@ApplicationScoped
public class ResilientPaymentService {

    @Inject
    @RestClient
    private PaymentGatewayApi paymentGateway;

    /**
     * 重試 + 超時 + 斷路器 + 降級。
     */
    @Retry(maxRetries = 3, delay = 1000, jitter = 200,
           retryOn = {ConnectException.class, TimeoutException.class})
    @Timeout(value = 5, unit = ChronoUnit.SECONDS)
    @CircuitBreaker(
        requestVolumeThreshold = 10,
        failureRatio = 0.5,
        delay = 30, delayUnit = ChronoUnit.SECONDS,
        successThreshold = 3
    )
    @Fallback(fallbackMethod = "paymentFallback")
    @Bulkhead(value = 20, waitingTaskQueue = 50)
    public PaymentResult processPayment(PaymentRequest request) {
        return paymentGateway.charge(request);
    }

    /**
     * 降級方法 — 當主要方法失敗時呼叫。
     */
    public PaymentResult paymentFallback(PaymentRequest request) {
        return new PaymentResult("PENDING", "付款閘道暫時不可用，已排入重試佇列");
    }
}

# .github/workflows/ci-cd.yaml
name: Jakarta EE 12 CI/CD

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

permissions:
  contents: read
  packages: write
  security-events: write

env:
  REGISTRY: ghcr.io
  IMAGE_NAME: ${{ github.repository }}
  JAVA_VERSION: '21'

jobs:
  # === Stage 1: Build & Test ===
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set up JDK 21
        uses: actions/setup-java@v4
        with:
          java-version: ${{ env.JAVA_VERSION }}
          distribution: 'temurin'
          cache: 'maven'

      - name: Build & Unit Test
        run: mvn clean verify -B

      - name: Upload Test Reports
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: test-reports
          path: '**/target/surefire-reports/'

      - name: Upload Coverage
        uses: actions/upload-artifact@v4
        with:
          name: coverage-report
          path: '**/target/site/jacoco/'

  # === Stage 2: Code Quality ===
  quality:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Set up JDK 21
        uses: actions/setup-java@v4
        with:
          java-version: ${{ env.JAVA_VERSION }}
          distribution: 'temurin'
          cache: 'maven'

      - name: SonarQube Scan
        env:
          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
        run: |
          mvn sonar:sonar \
            -Dsonar.host.url=${{ secrets.SONAR_URL }} \
            -Dsonar.token=${{ secrets.SONAR_TOKEN }} \
            -Dsonar.projectKey=jakarta-app

  # === Stage 3: Security Scan ===
  security:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: OWASP Dependency Check
        run: |
          mvn org.owasp:dependency-check-maven:check \
            -DfailBuildOnCVSS=7 -B

      - name: Upload OWASP Report
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: dependency-check-report
          path: '**/target/dependency-check-report.html'

  # === Stage 4: Build & Push Docker Image ===
  docker:
    needs: [build, quality, security]
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set up JDK 21
        uses: actions/setup-java@v4
        with:
          java-version: ${{ env.JAVA_VERSION }}
          distribution: 'temurin'
          cache: 'maven'

      - name: Build WAR
        run: mvn clean package -DskipTests -B

      - name: Log in to Container Registry
        uses: docker/login-action@v3
        with:
          registry: ${{ env.REGISTRY }}
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Build and Push Docker Image
        uses: docker/build-push-action@v6
        with:
          context: .
          push: true
          tags: |
            ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ github.sha }}
            ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:latest

      - name: Trivy Container Scan
        uses: aquasecurity/trivy-action@master
        with:
          image-ref: '${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ github.sha }}'
          format: 'sarif'
          output: 'trivy-results.sarif'
          severity: 'CRITICAL,HIGH'

      - name: Upload Trivy Results
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: 'trivy-results.sarif'

  # === Stage 5: Deploy to Staging ===
  deploy-staging:
    needs: docker
    runs-on: ubuntu-latest
    environment: staging
    steps:
      - uses: actions/checkout@v4

      - name: Deploy to Kubernetes (Staging)
        run: |
          kubectl set image deployment/jakarta-app \
            jakarta-app=${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ github.sha }} \
            --namespace staging
          kubectl rollout status deployment/jakarta-app --namespace staging --timeout=300s

// Jenkinsfile
pipeline {
    agent {
        kubernetes {
            yaml """
apiVersion: v1
kind: Pod
spec:
  containers:
  - name: maven
    image: maven:3.9-eclipse-temurin-21
    command: ['sleep', 'infinity']
  - name: docker
    image: docker:dind
    securityContext:
      privileged: true
"""
        }
    }

    environment {
        REGISTRY = 'registry.company.com'
        IMAGE_NAME = 'jakarta-app'
    }

    stages {
        stage('Build & Test') {
            steps {
                container('maven') {
                    sh 'mvn clean verify -B'
                }
            }
            post {
                always {
                    junit '**/target/surefire-reports/*.xml'
                    jacoco execPattern: '**/target/jacoco.exec'
                }
            }
        }

        stage('Security Scan') {
            steps {
                container('maven') {
                    sh 'mvn org.owasp:dependency-check-maven:check -DfailBuildOnCVSS=7'
                }
            }
        }

        stage('Docker Build & Push') {
            when { branch 'main' }
            steps {
                container('docker') {
                    sh """
                        docker build -t ${REGISTRY}/${IMAGE_NAME}:${BUILD_NUMBER} .
                        docker push ${REGISTRY}/${IMAGE_NAME}:${BUILD_NUMBER}
                    """
                }
            }
        }

        stage('Deploy Staging') {
            when { branch 'main' }
            steps {
                sh """
                    kubectl set image deployment/jakarta-app \
                      jakarta-app=${REGISTRY}/${IMAGE_NAME}:${BUILD_NUMBER} \
                      --namespace staging
                """
            }
        }
    }
}

<!-- Parent POM — SonarQube Plugin 設定 -->
<properties>
    <sonar.projectKey>jakarta-enterprise-app</sonar.projectKey>
    <sonar.organization>company</sonar.organization>
    <sonar.java.source>${java.version}</sonar.java.source>
    <sonar.coverage.jacoco.xmlReportPaths>
        ${project.basedir}/target/site/jacoco/jacoco.xml
    </sonar.coverage.jacoco.xmlReportPaths>
    <sonar.exclusions>
        **/dto/**,**/config/**,**/entity/**
    </sonar.exclusions>
</properties>

# Trivy — Container Image 掃描
trivy image --severity CRITICAL,HIGH \
  registry.company.com/jakarta-app:latest

# Trivy — 檔案系統掃描
trivy fs --severity CRITICAL,HIGH .

# OWASP Dependency Check — Maven Plugin
mvn org.owasp:dependency-check-maven:check \
  -DfailBuildOnCVSS=7 \
  -DsuppressionFile=owasp-suppressions.xml

<!-- pom.xml — CycloneDX SBOM Plugin -->
<plugin>
    <groupId>org.cyclonedx</groupId>
    <artifactId>cyclonedx-maven-plugin</artifactId>
    <version>2.8.2</version>
    <configuration>
        <projectType>application</projectType>
        <schemaVersion>1.5</schemaVersion>
        <includeBomSerialNumber>true</includeBomSerialNumber>
        <includeCompileScope>true</includeCompileScope>
        <includeRuntimeScope>true</includeRuntimeScope>
        <includeTestScope>false</includeTestScope>
        <outputFormat>json</outputFormat>
    </configuration>
    <executions>
        <execution>
            <phase>package</phase>
            <goals>
                <goal>makeBom</goal>
            </goals>
        </execution>
    </executions>
</plugin>

# 產生 SBOM
mvn package  # SBOM 自動產生於 target/bom.json

# 手動產生 CycloneDX SBOM
mvn org.cyclonedx:cyclonedx-maven-plugin:makeBom

# 產生 SPDX 格式 SBOM
mvn org.spdx:spdx-maven-plugin:createSPDX

# GitHub Actions — SBOM 產生與上傳
- name: Generate SBOM
  run: mvn org.cyclonedx:cyclonedx-maven-plugin:makeBom -B

- name: Upload SBOM as Release Asset
  uses: actions/upload-artifact@v4
  with:
    name: sbom
    path: '**/target/bom.json'

- name: SBOM 漏洞掃描
  run: |
    trivy sbom target/bom.json --severity CRITICAL,HIGH --exit-code 1

# .github/workflows/security-scan.yaml
name: Security Scan

on:
  schedule:
    - cron: '0 2 * * 1' # 每週一凌晨 2 點
  push:
    branches: [main]

jobs:
  sast:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run SonarQube SAST
        run: mvn sonar:sonar -Dsonar.qualitygate.wait=true

  sca:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: OWASP Dependency Check
        run: mvn org.owasp:dependency-check-maven:check -DfailBuildOnCVSS=7

  container-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Trivy Container Scan
        uses: aquasecurity/trivy-action@master
        with:
          scan-type: 'image'
          image-ref: 'registry.company.com/jakarta-app:latest'
          severity: 'CRITICAL,HIGH'
          exit-code: '1'

  dast:
    runs-on: ubuntu-latest
    needs: [sast, sca]
    steps:
      - name: OWASP ZAP Full Scan
        uses: zaproxy/action-full-scan@v0.10.0
        with:
          target: 'https://staging-api.company.com'
          rules_file_name: 'zap-rules.tsv'

# 產生 SBOM（CycloneDX 格式）
mvn org.cyclonedx:cyclonedx-maven-plugin:makeBom

# 產生 SBOM（SPDX 格式）
mvn org.spdx:spdx-maven-plugin:createSPDX

<!-- pom.xml — CycloneDX Plugin -->
<plugin>
    <groupId>org.cyclonedx</groupId>
    <artifactId>cyclonedx-maven-plugin</artifactId>
    <version>2.8.2</version>
    <executions>
        <execution>
            <phase>package</phase>
            <goals>
                <goal>makeBom</goal>
            </goals>
        </execution>
    </executions>
</plugin>

/**
 * Jakarta Agentic AI 1.0（概念示範 — 前瞻規格）。
 * 以下 API 為概念性示意，正式規格發布後可能有所調整。
 */
@ApplicationScoped
public class AiAssistedOrderService {

    // 概念：透過標準化 API 注入 AI 服務
    // @Inject
    // @AiModel(provider = "azure-openai", model = "gpt-4o")
    // private AiCompletionService aiService;

    /**
     * AI 輔助的訂單分析 — 概念範例。
     */
    public OrderAnalysis analyzeOrder(OrderEntity order) {
        // 實務上目前使用各 AI SDK 直接整合
        // Jakarta Agentic AI 的目標是標準化此類整合模式
        
        // 概念性 API 示意：
        // AiRequest request = AiRequest.builder()
        //     .systemPrompt("你是一個訂單風險分析助手...")
        //     .userMessage("分析以下訂單: " + order.toSummary())
        //     .maxTokens(500)
        //     .temperature(0.3)
        //     .build();
        // AiResponse response = aiService.complete(request);
        
        return new OrderAnalysis(order.getId(), "待 Jakarta Agentic AI 正式發布");
    }
}

## 範例 1: 生成 Repository
Prompt: "使用 Jakarta Data 1.1 建立 OrderRepository，
需支援：依狀態分頁查詢、依客戶 ID 查詢最近 30 天訂單、
統計各狀態訂單數量。使用 CrudRepository 介面。"

## 範例 2: 生成測試
Prompt: "為 OrderService.createOrder() 方法撰寫 JUnit 5 
單元測試，使用 Mockito mock OrderRepository 和 
NotificationService。涵蓋：正常建立、庫存不足例外、
無效客戶 ID 三個情境。"

## 範例 3: 安全審查
Prompt: "審查以下 Jakarta REST Resource 的安全性，
檢查 OWASP Top 10 相關問題，特別注意注入攻擊、
認證/授權、敏感資料曝露。提供修改建議。"

/**
 * AI 生成的測試（經人工審查修正）。
 * Prompt: "為 TransferService.transfer() 生成完整測試"
 */
@ExtendWith(MockitoExtension.class)
class TransferServiceTest {

    @InjectMocks
    private TransferService transferService;

    @Mock
    private EntityManager em;

    @Test
    @DisplayName("正常轉帳 — 雙方餘額正確更新")
    void shouldTransferSuccessfully() {
        // Given
        AccountEntity from = new AccountEntity("A001", new BigDecimal("10000"));
        AccountEntity to = new AccountEntity("A002", new BigDecimal("5000"));
        
        when(em.find(eq(AccountEntity.class), eq("A001"), any(LockModeType.class)))
            .thenReturn(from);
        when(em.find(eq(AccountEntity.class), eq("A002"), any(LockModeType.class)))
            .thenReturn(to);

        // When
        TransferResult result = transferService.transfer("A001", "A002", new BigDecimal("3000"));

        // Then
        assertNotNull(result);
        assertEquals(new BigDecimal("7000"), from.getBalance());
        assertEquals(new BigDecimal("8000"), to.getBalance());
        verify(em).persist(any(TransactionRecord.class));
    }

    @Test
    @DisplayName("餘額不足 — 拋出例外")
    void shouldThrowWhenInsufficientBalance() {
        AccountEntity from = new AccountEntity("A001", new BigDecimal("100"));
        AccountEntity to = new AccountEntity("A002", new BigDecimal("5000"));
        
        when(em.find(eq(AccountEntity.class), eq("A001"), any(LockModeType.class)))
            .thenReturn(from);
        when(em.find(eq(AccountEntity.class), eq("A002"), any(LockModeType.class)))
            .thenReturn(to);

        assertThrows(InsufficientBalanceException.class, 
            () -> transferService.transfer("A001", "A002", new BigDecimal("500")));
    }

    @Test
    @DisplayName("帳戶不存在 — 拋出例外")
    void shouldThrowWhenAccountNotFound() {
        when(em.find(eq(AccountEntity.class), eq("INVALID"), any(LockModeType.class)))
            .thenReturn(null);

        assertThrows(AccountNotFoundException.class, 
            () -> transferService.transfer("INVALID", "A002", new BigDecimal("100")));
    }
}

/**
 * 結構化日誌 — JSON 格式。
 */
@ApplicationScoped
public class StructuredLogger {

    private static final Logger logger = Logger.getLogger(StructuredLogger.class.getName());

    @Inject
    private AuditContext auditContext;

    /**
     * 記錄業務事件。
     */
    public void logBusinessEvent(String eventType, String message, Map<String, Object> data) {
        Map<String, Object> logEntry = new LinkedHashMap<>();
        logEntry.put("timestamp", Instant.now().toString());
        logEntry.put("level", "INFO");
        logEntry.put("correlationId", auditContext.getCorrelationId());
        logEntry.put("userId", auditContext.getUserId());
        logEntry.put("eventType", eventType);
        logEntry.put("message", message);
        logEntry.put("data", data);

        logger.info(JsonbBuilder.create().toJson(logEntry));
    }
}

<!-- log4j2.xml — JSON Layout -->
<Configuration status="WARN">
    <Appenders>
        <Console name="Console" target="SYSTEM_OUT">
            <JsonTemplateLayout eventTemplateUri="classpath:EcsLayout.json">
                <EventTemplateAdditionalField
                    key="service.name" value="jakarta-app" />
                <EventTemplateAdditionalField
                    key="service.version" value="1.0.0" />
            </JsonTemplateLayout>
        </Console>
    </Appenders>
    <Loggers>
        <Root level="INFO">
            <AppenderRef ref="Console" />
        </Root>
    </Loggers>
</Configuration>

/**
 * 自訂 Prometheus 指標。
 */
@ApplicationScoped
public class BusinessMetrics {

    @Inject
    private MetricRegistry metricRegistry;

    private Counter orderCounter;
    private Histogram orderDuration;
    private Gauge pendingOrders;

    @PostConstruct
    public void init() {
        Metadata counterMeta = Metadata.builder()
            .withName("business_orders_total")
            .withDescription("Total number of orders processed")
            .build();
        orderCounter = metricRegistry.counter(counterMeta);

        Metadata histMeta = Metadata.builder()
            .withName("business_order_processing_seconds")
            .withDescription("Order processing duration")
            .build();
        orderDuration = metricRegistry.histogram(histMeta);
    }

    public void recordOrderCreated() {
        orderCounter.inc();
    }

    public void recordProcessingTime(long durationMs) {
        orderDuration.update(durationMs);
    }
}

/**
 * OpenTelemetry 手動追蹤（補充自動追蹤不足）。
 */
@ApplicationScoped
public class TracedOrderService {

    @Inject
    private Tracer tracer;

    @Inject
    private OrderRepository orderRepository;

    public Order createOrder(CreateOrderCommand command) {
        Span span = tracer.buildSpan("createOrder")
            .withTag("customerId", command.customerId())
            .start();

        try (Scope scope = tracer.activateSpan(span)) {
            // 子 Span: 驗證
            Span validateSpan = tracer.buildSpan("validateOrder").start();
            validateOrder(command);
            validateSpan.finish();

            // 子 Span: 持久化
            Span persistSpan = tracer.buildSpan("persistOrder").start();
            Order order = orderRepository.save(mapToEntity(command));
            persistSpan.finish();

            span.setTag("orderId", order.getId());
            return order;
        } catch (Exception e) {
            span.setTag("error", true);
            span.log(Map.of("error.message", e.getMessage()));
            throw e;
        } finally {
            span.finish();
        }
    }
}

# prometheus-alerts.yaml
groups:
  - name: jakarta-app-alerts
    rules:
      - alert: HighErrorRate
        expr: rate(http_server_requests_total{status=~"5.."}[5m]) > 0.05
        for: 5m
        labels:
          severity: critical
        annotations:
          summary: "API 5xx 錯誤率超過 5%"
          description: "{{ $labels.instance }} 的 5xx 錯誤率 {{ $value | humanizePercentage }}"

      - alert: HighLatency
        expr: histogram_quantile(0.95, rate(http_server_request_duration_seconds_bucket[5m])) > 2
        for: 10m
        labels:
          severity: warning
        annotations:
          summary: "API P95 回應時間超過 2 秒"

      - alert: PodRestart
        expr: increase(kube_pod_container_status_restarts_total[1h]) > 3
        labels:
          severity: warning
        annotations:
          summary: "Pod 在 1 小時內重啟超過 3 次"

/**
 * 單元測試 — JUnit 5 + Mockito。
 */
@ExtendWith(MockitoExtension.class)
class OrderServiceTest {

    @InjectMocks
    private OrderServiceImpl orderService;

    @Mock
    private OrderRepository orderRepository;

    @Mock
    private InventoryService inventoryService;

    @Mock
    private Event<OrderCreatedEvent> orderCreatedEvent;

    @Test
    @DisplayName("建立訂單 — 正常流程")
    void createOrder_shouldSucceed() {
        // Given
        CreateOrderCommand command = new CreateOrderCommand(
            new CustomerId("C001"),
            List.of(new OrderItemCommand(new ProductId("P001"), 2)),
            new Address("台北市", "信義區", "信義路", "110")
        );
        when(inventoryService.checkStock("P001", 2)).thenReturn(true);
        when(orderRepository.save(any())).thenAnswer(inv -> inv.getArgument(0));

        // When
        Order result = orderService.createOrder(command);

        // Then
        assertNotNull(result);
        assertEquals("C001", result.getCustomerId().value());
        verify(orderRepository).save(any());
        verify(orderCreatedEvent).fire(any());
    }

    @Test
    @DisplayName("建立訂單 — 庫存不足應拋出例外")
    void createOrder_insufficientStock_shouldThrow() {
        CreateOrderCommand command = new CreateOrderCommand(
            new CustomerId("C001"),
            List.of(new OrderItemCommand(new ProductId("P001"), 999)),
            new Address("台北市", "信義區", "信義路", "110")
        );
        when(inventoryService.checkStock("P001", 999)).thenReturn(false);

        assertThrows(InsufficientStockException.class, 
            () -> orderService.createOrder(command));
        verify(orderRepository, never()).save(any());
    }

    @ParameterizedTest
    @CsvSource({
        "100, 10, 90",
        "500, 500, 0",
        "1000, 1, 999"
    })
    @DisplayName("庫存扣減 — 參數化測試")
    void decreaseStock_shouldCalculateCorrectly(int initial, int decrease, int expected) {
        ProductEntity product = new ProductEntity("P001", initial);
        product.decreaseStock(decrease);
        assertEquals(expected, product.getStockQuantity());
    }
}

/**
 * 整合測試 — 使用 Testcontainers 啟動真實資料庫。
 */
@Testcontainers
@ExtendWith(MockitoExtension.class)
class OrderRepositoryIT {

    @Container
    static PostgreSQLContainer<?> postgres = new PostgreSQLContainer<>("postgres:16-alpine")
        .withDatabaseName("testdb")
        .withUsername("test")
        .withPassword("test");

    @Container
    static GenericContainer<?> redis = new GenericContainer<>("redis:7-alpine")
        .withExposedPorts(6379);

    private static EntityManagerFactory emf;

    @BeforeAll
    static void setup() {
        Map<String, Object> props = Map.of(
            "jakarta.persistence.jdbc.url", postgres.getJdbcUrl(),
            "jakarta.persistence.jdbc.user", postgres.getUsername(),
            "jakarta.persistence.jdbc.password", postgres.getPassword(),
            "jakarta.persistence.schema-generation.database.action", "create"
        );
        emf = Persistence.createEntityManagerFactory("test-pu", props);
    }

    @Test
    @DisplayName("訂單 CRUD — 整合測試")
    void shouldPerformCrudOperations() {
        EntityManager em = emf.createEntityManager();
        em.getTransaction().begin();

        OrderEntity order = new OrderEntity();
        order.setId(UUID.randomUUID().toString());
        order.setCustomerId("C001");
        order.setStatus(OrderStatus.PENDING);
        order.setTotalAmount(new BigDecimal("1500.00"));
        em.persist(order);
        em.getTransaction().commit();

        // 查詢
        OrderEntity found = em.find(OrderEntity.class, order.getId());
        assertNotNull(found);
        assertEquals("C001", found.getCustomerId());
        assertEquals(OrderStatus.PENDING, found.getStatus());

        em.close();
    }

    @AfterAll
    static void tearDown() {
        if (emf != null) emf.close();
    }
}

/**
 * ArchUnit — 架構規範自動化驗證。
 */
@AnalyzeClasses(packages = "com.company.app")
class ArchitectureTest {

    @ArchTest
    static final ArchRule domain_should_not_depend_on_infrastructure =
        noClasses().that().resideInAPackage("..domain..")
            .should().dependOnClassesThat().resideInAPackage("..infrastructure..")
            .because("Domain 層不能依賴 Infrastructure 層");

    @ArchTest
    static final ArchRule controllers_should_only_call_services =
        classes().that().resideInAPackage("..api..")
            .should().onlyDependOnClassesThat()
            .resideInAnyPackage("..api..", "..application..", "..domain..",
                "jakarta..", "java..", "org.eclipse..")
            .because("API 層只能依賴 Application 和 Domain 層");

    @ArchTest
    static final ArchRule services_should_be_annotated =
        classes().that().resideInAPackage("..application.service..")
            .should().beAnnotatedWith(ApplicationScoped.class)
            .because("Application Service 必須標註 @ApplicationScoped");

    @ArchTest
    static final ArchRule entities_should_be_in_domain =
        classes().that().areAnnotatedWith(Entity.class)
            .should().resideInAPackage("..domain..")
            .because("JPA Entity 必須在 Domain 層");
}

/**
 * Pact 契約測試 — Consumer 端。
 */
@ExtendWith(PactConsumerTestExt.class)
@PactTestFor(providerName = "inventory-service", port = "8888")
class InventoryClientPactTest {

    @Pact(consumer = "order-service")
    public V4Pact checkStockPact(PactDslWithProvider builder) {
        return builder
            .given("product P001 has 50 units in stock")
            .uponReceiving("a request to check stock for P001")
            .path("/api/v1/inventory/P001/stock")
            .method("GET")
            .willRespondWith()
            .status(200)
            .body(new PactDslJsonBody()
                .stringValue("productId", "P001")
                .integerType("quantity", 50)
                .booleanType("available", true))
            .toPact(V4Pact.class);
    }

    @Test
    @PactTestFor(pactMethod = "checkStockPact")
    void shouldCheckStock(MockServer mockServer) {
        // 使用 Mock Server 測試 Client
        InventoryClient client = new InventoryClient(mockServer.getUrl());
        StockInfo result = client.checkStock("P001");
        
        assertEquals("P001", result.productId());
        assertTrue(result.available());
    }
}

# Eclipse Transformer — 自動轉換 javax → jakarta
java -jar org.eclipse.transformer.cli.jar \
  input.war output.war \
  -tr jakarta-renames.properties

// Java EE 8 (javax)
import javax.persistence.Entity;
import javax.inject.Inject;
import javax.ws.rs.GET;
import javax.servlet.http.HttpServletRequest;
import javax.enterprise.context.ApplicationScoped;

// Jakarta EE 12 (jakarta)
import jakarta.persistence.Entity;
import jakarta.inject.Inject;
import jakarta.ws.rs.GET;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.enterprise.context.ApplicationScoped;

# CLI 模式 — 轉換 WAR 檔
java -jar org.eclipse.transformer.cli.jar \
  input.war output.war \
  -tr jakarta-renames.properties

# CLI 模式 — 轉換整個目錄
java -jar org.eclipse.transformer.cli.jar \
  src/ transformed-src/ \
  -tr jakarta-renames.properties \
  -o  # 覆蓋模式

<!-- Maven Plugin 整合 -->
<plugin>
    <groupId>org.eclipse.transformer</groupId>
    <artifactId>transformer-maven-plugin</artifactId>
    <version>0.5.0</version>
    <executions>
        <execution>
            <phase>package</phase>
            <goals>
                <goal>jar</goal>
            </goals>
        </execution>
    </executions>
</plugin>

Phase 1（1-2 月）：Java 21 → CDI 5.0 → Jakarta REST 5.0 → JPA 4.0
Phase 2（2-3 月）：Jakarta Data → Security 5.0 → MicroProfile
Phase 3（3-4 月）：Docker → K8s → CI/CD → 可觀測性
Phase 4（持續）  ：Clean Architecture → DDD → 效能調校 → 安全深化

Git Flow      → 企業產品（銀行、保險）、需要多版本並行維護
Trunk Based   → 網路服務（SaaS、電商）、追求快速迭代部署
GitHub Flow   → 開源專案、小型團隊、簡化的 Git Flow

# Istio Canary 部署範例
apiVersion: networking.istio.io/v1
kind: VirtualService
metadata:
  name: jakarta-app
spec:
  hosts:
    - jakarta-app
  http:
    - route:
        - destination:
            host: jakarta-app
            subset: v1
          weight: 90
        - destination:
            host: jakarta-app
            subset: v2
          weight: 10    # 10% Canary 流量

# Kubernetes Rolling Update Rollback
kubectl rollout undo deployment/jakarta-app --namespace production

# 確認 Rollback 狀態
kubectl rollout status deployment/jakarta-app --namespace production

# 回到特定版本
kubectl rollout undo deployment/jakarta-app --to-revision=3 --namespace production

# 檢視部署歷史
kubectl rollout history deployment/jakarta-app --namespace production

# 容器環境 JVM 參數
JAVA_OPTS="\
  -Xms512m -Xmx1g \
  -XX:+UseContainerSupport \
  -XX:MaxRAMPercentage=75.0 \
  -XX:+HeapDumpOnOutOfMemoryError \
  -XX:HeapDumpPath=/logs/heapdump.hprof \
  -XX:+UseStringDeduplication \
  -Xlog:gc*:file=/logs/gc.log:time,uptime,level,tags:filecount=5,filesize=10m"

# G1GC 調校（通用場景）
-XX:+UseG1GC \
-XX:MaxGCPauseMillis=200 \
-XX:G1HeapRegionSize=4m \
-XX:InitiatingHeapOccupancyPercent=45

# ZGC 調校（低延遲場景）
-XX:+UseZGC \
-XX:+ZGenerational \
-XX:SoftMaxHeapSize=1g

# GC 日誌（生產環境必開）
-Xlog:gc*:file=/logs/gc.log:time,uptime,level,tags:filecount=5,filesize=10m

# 觀察 GC 行為
jstat -gcutil <pid> 1000

# 分析 GC 日誌
# 使用 GCViewer 或 gceasy.io 線上分析

# JFR 效能紀錄
jcmd <pid> JFR.start duration=60s filename=/tmp/recording.jfr

<!-- Open Liberty server.xml 連線池設定 -->
<dataSource jndiName="jdbc/appDB" connectionSharing="MatchOriginalRequest">
    <connectionManager
        maxPoolSize="${env.DB_MAX_POOL:20}"
        minPoolSize="${env.DB_MIN_POOL:5}"
        connectionTimeout="30s"
        maxIdleTime="10m"
        reapTime="3m" />
    <jdbcDriver libraryRef="postgresql-lib" />
    <properties.postgresql
        serverName="${env.DB_HOST}"
        portNumber="${env.DB_PORT:5432}"
        databaseName="${env.DB_NAME}"
        user="${env.DB_USER}"
        password="${env.DB_PASSWORD}" />
</dataSource>

/**
 * 慢查詢檢測 Interceptor。
 */
@Interceptor
@ApplicationScoped
public class SlowQueryMonitor {

    private static final Logger logger = Logger.getLogger(SlowQueryMonitor.class.getName());
    private static final long SLOW_QUERY_THRESHOLD_MS = 500;

    @AroundInvoke
    public Object monitorQuery(InvocationContext ctx) throws Exception {
        long start = System.nanoTime();
        Object result = ctx.proceed();
        long durationMs = (System.nanoTime() - start) / 1_000_000;
        
        if (durationMs > SLOW_QUERY_THRESHOLD_MS) {
            logger.warning("慢查詢偵測: " + ctx.getMethod().getName() 
                + " 耗時 " + durationMs + "ms");
        }
        return result;
    }
}

# PostgreSQL 慢查詢分析
SELECT query, calls, total_exec_time, mean_exec_time
FROM pg_stat_statements
ORDER BY mean_exec_time DESC
LIMIT 20;

/**
 * Thread Pool 隔離設計 — Bulkhead Pattern。
 */
@ApplicationScoped
public class ThreadPoolConfig {

    // 訂單處理專用 — I/O 密集，使用 Virtual Thread
    @Resource(lookup = "concurrent/orderExecutor")
    private ManagedExecutorService orderExecutor;

    // 報表產生專用 — CPU 密集，限制 Thread 數量
    @Resource(lookup = "concurrent/reportExecutor")
    private ManagedExecutorService reportExecutor;
}

<!-- Open Liberty Thread Pool 設定 -->
<managedExecutorService jndiName="concurrent/orderExecutor"
    maxAsync="50"
    virtualThreads="true" />

<managedExecutorService jndiName="concurrent/reportExecutor"
    maxAsync="4" />

# 記憶體問題診斷流程
# 1. Heap Dump
jcmd <pid> GC.heap_dump /tmp/heapdump.hprof

# 2. 用 Eclipse MAT 或 VisualVM 分析
# 重點：Dominator Tree → 找最大物件 → Shortest Paths to GC Roots

# 3. JFR 持續監控
jcmd <pid> JFR.start duration=300s filename=/tmp/memory.jfr

# K8s 診斷三步驟
kubectl logs <pod-name> --tail=100
kubectl describe pod <pod-name>
kubectl get events --namespace <ns> --sort-by=.metadata.creationTimestamp

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

    <groupId>com.example</groupId>
    <artifactId>jakarta-app-parent</artifactId>
    <version>1.0.0-SNAPSHOT</version>
    <packaging>pom</packaging>

    <properties>
        <maven.compiler.source>21</maven.compiler.source>
        <maven.compiler.target>21</maven.compiler.target>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <jakarta.ee.version>12.0.0</jakarta.ee.version>
        <microprofile.version>7.0</microprofile.version>
    </properties>

    <modules>
        <module>domain</module>
        <module>application</module>
        <module>infrastructure</module>
        <module>api</module>
    </modules>

    <dependencyManagement>
        <dependencies>
            <!-- Jakarta EE 12 BOM -->
            <dependency>
                <groupId>jakarta.platform</groupId>
                <artifactId>jakarta.jakartaee-bom</artifactId>
                <version>${jakarta.ee.version}</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
            <!-- MicroProfile BOM -->
            <dependency>
                <groupId>org.eclipse.microprofile</groupId>
                <artifactId>microprofile</artifactId>
                <version>${microprofile.version}</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
            <!-- Test -->
            <dependency>
                <groupId>org.junit</groupId>
                <artifactId>junit-bom</artifactId>
                <version>5.11.0</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
        </dependencies>
    </dependencyManagement>

    <build>
        <pluginManagement>
            <plugins>
                <plugin>
                    <groupId>org.apache.maven.plugins</groupId>
                    <artifactId>maven-compiler-plugin</artifactId>
                    <version>3.13.0</version>
                    <configuration>
                        <release>21</release>
                    </configuration>
                </plugin>
                <plugin>
                    <groupId>org.apache.maven.plugins</groupId>
                    <artifactId>maven-war-plugin</artifactId>
                    <version>3.4.0</version>
                    <configuration>
                        <failOnMissingWebXml>false</failOnMissingWebXml>
                    </configuration>
                </plugin>
                <plugin>
                    <groupId>io.openliberty.tools</groupId>
                    <artifactId>liberty-maven-plugin</artifactId>
                    <version>3.10</version>
                </plugin>
            </plugins>
        </pluginManagement>
    </build>
</project>

# === Stage 1: Build ===
FROM maven:3.9-eclipse-temurin-21 AS build
WORKDIR /app
COPY pom.xml .
RUN mvn dependency:go-offline -B
COPY src ./src
RUN mvn clean package -DskipTests -B

# === Stage 2: Runtime ===
FROM icr.io/appcafe/open-liberty:kernel-slim-java21-openj9-ubi
ARG VERSION=1.0.0

# 安裝 Features
COPY --chown=1001:0 src/main/liberty/config /config/
RUN features.sh

# 複製 WAR
COPY --from=build --chown=1001:0 /app/target/*.war /config/apps/

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

# 非 Root 使用者
USER 1001

EXPOSE 9080 9443

# docker-compose.yml — 本地開發環境
version: '3.9'

services:
  # Jakarta EE Application
  app:
    build:
      context: .
      dockerfile: Dockerfile
    ports:
      - "9080:9080"
      - "9443:9443"
    environment:
      - DB_HOST=postgres
      - DB_PORT=5432
      - DB_NAME=appdb
      - DB_USER=app
      - DB_PASSWORD=secret
      - REDIS_HOST=redis
      - KAFKA_BOOTSTRAP_SERVERS=kafka:9092
      - JAVA_OPTS=-Xms512m -Xmx1g -XX:+UseG1GC
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_started
      kafka:
        condition: service_started
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:9080/health/ready"]
      interval: 30s
      timeout: 10s
      retries: 5

  # PostgreSQL
  postgres:
    image: postgres:16-alpine
    ports:
      - "5432:5432"
    environment:
      POSTGRES_DB: appdb
      POSTGRES_USER: app
      POSTGRES_PASSWORD: secret
    volumes:
      - postgres_data:/var/lib/postgresql/data
      - ./sql/init.sql:/docker-entrypoint-initdb.d/init.sql
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U app -d appdb"]
      interval: 10s
      timeout: 5s
      retries: 5

  # Redis
  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"
    command: redis-server --appendonly yes --maxmemory 256mb --maxmemory-policy allkeys-lru

  # Kafka (KRaft mode)
  kafka:
    image: apache/kafka:3.7.0
    ports:
      - "9092:9092"
    environment:
      KAFKA_NODE_ID: 1
      KAFKA_PROCESS_ROLES: broker,controller
      KAFKA_LISTENERS: PLAINTEXT://0.0.0.0:9092,CONTROLLER://0.0.0.0:9093
      KAFKA_CONTROLLER_QUORUM_VOTERS: 1@kafka:9093
      KAFKA_LOG_DIRS: /var/lib/kafka/data

  # Prometheus
  prometheus:
    image: prom/prometheus:latest
    ports:
      - "9090:9090"
    volumes:
      - ./monitoring/prometheus.yml:/etc/prometheus/prometheus.yml

  # Grafana
  grafana:
    image: grafana/grafana:latest
    ports:
      - "3000:3000"
    environment:
      GF_SECURITY_ADMIN_PASSWORD: admin
    volumes:
      - grafana_data:/var/lib/grafana

  # Jaeger (Distributed Tracing)
  jaeger:
    image: jaegertracing/all-in-one:latest
    ports:
      - "16686:16686"
      - "4317:4317"

volumes:
  postgres_data:
  grafana_data:

# k8s/namespace.yaml
apiVersion: v1
kind: Namespace
metadata:
  name: jakarta-app
  labels:
    app.kubernetes.io/name: jakarta-app
---
# k8s/deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: jakarta-app
  namespace: jakarta-app
spec:
  replicas: 3
  selector:
    matchLabels:
      app: jakarta-app
  template:
    metadata:
      labels:
        app: jakarta-app
    spec:
      serviceAccountName: jakarta-app-sa
      containers:
        - name: app
          image: registry.example.com/jakarta-app:latest
          ports:
            - containerPort: 9080
          resources:
            requests:
              memory: "512Mi"
              cpu: "250m"
            limits:
              memory: "1Gi"
              cpu: "1000m"
          livenessProbe:
            httpGet:
              path: /health/live
              port: 9080
            initialDelaySeconds: 30
            periodSeconds: 10
          readinessProbe:
            httpGet:
              path: /health/ready
              port: 9080
            initialDelaySeconds: 15
            periodSeconds: 5
          startupProbe:
            httpGet:
              path: /health/started
              port: 9080
            failureThreshold: 30
            periodSeconds: 10
---
# k8s/networkpolicy.yaml
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: jakarta-app-netpol
  namespace: jakarta-app
spec:
  podSelector:
    matchLabels:
      app: jakarta-app
  policyTypes:
    - Ingress
    - Egress
  ingress:
    - from:
        - namespaceSelector:
            matchLabels:
              name: ingress-nginx
      ports:
        - protocol: TCP
          port: 9080
  egress:
    - to:
        - namespaceSelector:
            matchLabels:
              name: database
      ports:
        - protocol: TCP
          port: 5432

# .github/workflows/ci-cd.yaml
name: CI/CD Pipeline

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

jobs:
  build-and-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup JDK 21
        uses: actions/setup-java@v4
        with:
          distribution: 'temurin'
          java-version: '21'
          cache: 'maven'

      - name: Build & Test
        run: mvn clean verify -B

      - name: SonarQube Scan
        run: mvn sonar:sonar -Dsonar.projectKey=jakarta-app
        env:
          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}

      - name: OWASP Dependency Check
        run: mvn dependency-check:check -DfailBuildOnCVSS=7

      - name: Build Docker Image
        run: docker build -t jakarta-app:${{ github.sha }} .

      - name: Trivy Container Scan
        uses: aquasecurity/trivy-action@master
        with:
          image-ref: jakarta-app:${{ github.sha }}
          severity: 'CRITICAL,HIGH'
          exit-code: '1'

      - name: SBOM Generation
        run: mvn org.cyclonedx:cyclonedx-maven-plugin:makeBom

      - name: Push to Registry
        if: github.ref == 'refs/heads/main'
        run: |
          docker tag jakarta-app:${{ github.sha }} registry.example.com/jakarta-app:latest
          docker push registry.example.com/jakarta-app:latest

// Jenkinsfile — Declarative Pipeline
pipeline {
    agent { label 'java21' }

    environment {
        JAVA_HOME = tool('JDK-21')
        MAVEN_HOME = tool('Maven-3.9')
    }

    stages {
        stage('Build') {
            steps {
                sh 'mvn clean compile -B'
            }
        }
        stage('Test') {
            steps {
                sh 'mvn test -B'
            }
            post {
                always {
                    junit '**/target/surefire-reports/*.xml'
                }
            }
        }
        stage('SAST') {
            steps {
                withSonarQubeEnv('SonarQube') {
                    sh 'mvn sonar:sonar'
                }
            }
        }
        stage('SCA') {
            steps {
                sh 'mvn dependency-check:check -DfailBuildOnCVSS=7'
            }
        }
        stage('Package') {
            steps {
                sh 'mvn package -DskipTests -B'
            }
        }
        stage('Docker Build & Scan') {
            steps {
                sh "docker build -t jakarta-app:${BUILD_NUMBER} ."
                sh "trivy image --severity HIGH,CRITICAL --exit-code 1 jakarta-app:${BUILD_NUMBER}"
            }
        }
        stage('Deploy') {
            when { branch 'main' }
            steps {
                sh "kubectl set image deployment/jakarta-app app=jakarta-app:${BUILD_NUMBER}"
            }
        }
    }
}

<!-- Open Liberty server.xml Logging 設定 -->
<logging traceSpecification="*=info"
    maxFileSize="50"
    maxFiles="10"
    messageFormat="JSON"
    consoleFormat="JSON"
    consoleLogLevel="INFO" />

<!-- Log4j2 設定（如在應用內使用） -->
<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="WARN">
    <Appenders>
        <Console name="Console" target="SYSTEM_OUT">
            <JsonLayout compact="true" eventEol="true"
                properties="true" stacktraceAsString="true">
                <KeyValuePair key="service" value="jakarta-app" />
                <KeyValuePair key="environment" value="${env:APP_ENV:-dev}" />
            </JsonLayout>
        </Console>
        <RollingFile name="File"
            fileName="logs/app.log"
            filePattern="logs/app-%d{yyyy-MM-dd}-%i.log.gz">
            <JsonLayout compact="true" eventEol="true" />
            <Policies>
                <TimeBasedTriggeringPolicy interval="1" />
                <SizeBasedTriggeringPolicy size="50MB" />
            </Policies>
            <DefaultRolloverStrategy max="30" />
        </RollingFile>
    </Appenders>
    <Loggers>
        <Logger name="com.example" level="DEBUG" />
        <Root level="INFO">
            <AppenderRef ref="Console" />
            <AppenderRef ref="File" />
        </Root>
    </Loggers>
</Configuration>