應用啟動 → 掃描 Classpath → 解析註解 → 建立 Bean → 注入依賴 → 載入配置 → 就緒
            |<---------- 執行期處理，每次啟動都重複 ---------->|

Maven Build → 掃描 Classpath → 解析註解 → 產生 Bytecode → 產出最佳化應用
                |<---------- 建置期處理，只做一次 ---------->|

應用啟動 → 載入預處理結果 → 就緒
            |<-- 極快 -->|

# 建置 JVM 模式
mvn package

# 執行
java -jar target/quarkus-app/quarkus-run.jar

# 建置 Native Image（需要 GraalVM 或 Mandrel）
mvn package -Pnative

# 執行
./target/my-app-1.0.0-runner

# 列出可用 Extension
quarkus extension list

# 新增 Extension
quarkus extension add quarkus-rest-jackson

# 移除 Extension
quarkus extension remove quarkus-rest-jackson

# 搜尋 Extension
quarkus extension list --search kafka

@ApplicationScoped
public class GreetingService {

    public String greet(String name) {
        return "Hello, " + name;
    }
}

@Path("/greeting")
public class GreetingResource {

    @Inject
    GreetingService greetingService;

    @GET
    @Path("/{name}")
    @Produces(MediaType.TEXT_PLAIN)
    public String greet(@PathParam("name") String name) {
        return greetingService.greet(name);
    }
}

HTTP 請求 → Vert.x Event Loop → 路由至處理器
                                    ├─ Reactive Handler → 直接在 Event Loop 處理
                                    └─ Blocking Handler → 分派至 Worker Thread Pool

@Entity
public class Product extends PanacheEntity {
    public String name;
    public BigDecimal price;

    public static List<Product> findByName(String name) {
        return find("name", name).list();
    }
}

// 使用
Product product = new Product();
product.name = "Quarkus T-Shirt";
product.price = new BigDecimal("29.99");
product.persist();

List<Product> products = Product.findByName("Quarkus T-Shirt");

@ApplicationScoped
public class ProductRepository implements PanacheRepository<Product> {

    public List<Product> findByName(String name) {
        return find("name", name).list();
    }
}

# application.properties
quarkus.http.port=8080
quarkus.datasource.db-kind=postgresql
quarkus.datasource.jdbc.url=jdbc:postgresql://localhost:5432/mydb

# 環境特定配置（Profile）
%dev.quarkus.datasource.jdbc.url=jdbc:postgresql://localhost:5432/devdb
%test.quarkus.datasource.jdbc.url=jdbc:postgresql://localhost:5432/testdb
%prod.quarkus.datasource.jdbc.url=jdbc:postgresql://prod-db:5432/proddb

# 啟用管理介面，預設 port 9000
quarkus.management.enabled=true
quarkus.management.port=9000

# 1. 安裝 JDK 21（使用 winget）
winget install EclipseAdoptium.Temurin.21.JDK

# 2. 安裝 Maven
winget install Apache.Maven

# 3. 安裝 Quarkus CLI（透過 JBang）
iex "& { $(iwr https://ps.jbang.dev) } trust add https://repo1.maven.org/maven2/io/quarkus/quarkus-cli/"
iex "& { $(iwr https://ps.jbang.dev) } app install --fresh --force quarkus@quarkusio"

# 4. 驗證安裝
java -version
mvn -version
quarkus version

# 5. 安裝 Docker Desktop
winget install Docker.DockerDesktop

# 1. 安裝 JDK 21（Ubuntu/Debian）
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.4-tem

# 2. 安裝 Maven
sdk install maven

# 3. 安裝 Quarkus CLI
## 方式一：JBang
curl -Ls https://sh.jbang.dev | bash -s - trust add https://repo1.maven.org/maven2/io/quarkus/quarkus-cli/
curl -Ls https://sh.jbang.dev | bash -s - app install --fresh --force quarkus@quarkusio

## 方式二：SDKMAN!
sdk install quarkus

# 4. 安裝 Docker
sudo apt install -y docker.io
sudo usermod -aG docker $USER

# 5. 驗證
java -version
mvn -version
quarkus version
docker --version

# 1. 使用 Homebrew 安裝
brew install --cask temurin@21
brew install maven

# 2. 安裝 Quarkus CLI
brew install quarkusio/tap/quarkus

# 3. 安裝 Docker Desktop
brew install --cask docker

# 4. 驗證
java -version
mvn -version
quarkus version

<project>
    <modelVersion>4.0.0</modelVersion>
    <groupId>com.example</groupId>
    <artifactId>my-quarkus-app</artifactId>
    <version>1.0.0-SNAPSHOT</version>

    <properties>
        <compiler-plugin.version>3.14.1</compiler-plugin.version>
        <maven.compiler.release>21</maven.compiler.release>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <quarkus.platform.artifact-id>quarkus-bom</quarkus.platform.artifact-id>
        <quarkus.platform.group-id>io.quarkus.platform</quarkus.platform.group-id>
        <quarkus.platform.version>3.35.3</quarkus.platform.version>
        <surefire-plugin.version>3.5.2</surefire-plugin.version>
    </properties>

    <dependencyManagement>
        <dependencies>
            <dependency>
                <groupId>${quarkus.platform.group-id}</groupId>
                <artifactId>${quarkus.platform.artifact-id}</artifactId>
                <version>${quarkus.platform.version}</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
        </dependencies>
    </dependencyManagement>

    <dependencies>
        <dependency>
            <groupId>io.quarkus</groupId>
            <artifactId>quarkus-rest</artifactId>
        </dependency>
        <dependency>
            <groupId>io.quarkus</groupId>
            <artifactId>quarkus-rest-jackson</artifactId>
        </dependency>
        <dependency>
            <groupId>io.quarkus</groupId>
            <artifactId>quarkus-arc</artifactId>
        </dependency>
        <!-- 測試 -->
        <dependency>
            <groupId>io.quarkus</groupId>
            <artifactId>quarkus-junit5</artifactId>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>io.rest-assured</groupId>
            <artifactId>rest-assured</artifactId>
            <scope>test</scope>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>${quarkus.platform.group-id}</groupId>
                <artifactId>quarkus-maven-plugin</artifactId>
                <version>${quarkus.platform.version}</version>
                <extensions>true</extensions>
                <executions>
                    <execution>
                        <goals>
                            <goal>build</goal>
                            <goal>generate-code</goal>
                            <goal>generate-code-tests</goal>
                            <goal>native-image-agent</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>
            <plugin>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>${compiler-plugin.version}</version>
                <configuration>
                    <parameters>true</parameters>
                </configuration>
            </plugin>
            <plugin>
                <artifactId>maven-surefire-plugin</artifactId>
                <version>${surefire-plugin.version}</version>
                <configuration>
                    <systemPropertyVariables>
                        <java.util.logging.manager>
                            org.jboss.logmanager.LogManager
                        </java.util.logging.manager>
                    </systemPropertyVariables>
                </configuration>
            </plugin>
        </plugins>
    </build>

    <profiles>
        <profile>
            <id>native</id>
            <activation>
                <property>
                    <name>native</name>
                </property>
            </activation>
            <properties>
                <quarkus.native.enabled>true</quarkus.native.enabled>
            </properties>
        </profile>
    </profiles>
</project>

# 安裝確認
quarkus version

# 建立新專案
quarkus create app com.example:my-app

# 啟動 Dev Mode
quarkus dev

# 管理 Extension
quarkus extension add quarkus-hibernate-orm-panache
quarkus extension list --installed

# 建置
quarkus build

# Native 建置
quarkus build --native

# 更新 Quarkus 版本
quarkus update

// VS Code launch.json
{
    "version": "0.2.0",
    "configurations": [
        {
            "type": "java",
            "name": "Attach to Quarkus",
            "request": "attach",
            "hostName": "localhost",
            "port": 5005
        }
    ]
}

# Docker
docker --version

# Podman（替代方案）
podman --version

# Quarkus 配置使用 Podman
quarkus.native.container-runtime=podman

# kubectl
kubectl version --client

# oc（OpenShift CLI）
oc version

# Helm（K8s 套件管理）
helm version

# kind（本機 K8s 測試叢集）
kind create cluster --name quarkus-dev

# 建立基本 REST 應用
quarkus create app com.example:my-first-app \
    --extension='rest,rest-jackson' \
    --java=21

# 進入專案目錄
cd my-first-app

quarkus create app
# 依提示輸入 groupId、artifactId、版本、Extension 等

quarkus create app com.example:order-service \
    --extension='rest,rest-jackson,hibernate-orm-panache,jdbc-postgresql,smallrye-health,smallrye-openapi' \
    --java=21 \
    --wrapper

mvn io.quarkus.platform:quarkus-maven-plugin:3.35.3:create \
    -DprojectGroupId=com.example \
    -DprojectArtifactId=my-first-app \
    -Dextensions='rest,rest-jackson' \
    -DjavaVersion=21

my-first-app/
├── .mvn/                           # Maven Wrapper 設定
│   └── wrapper/
├── src/
│   ├── main/
│   │   ├── docker/                 # Dockerfile 模板
│   │   │   ├── Dockerfile.jvm      # JVM 模式映像
│   │   │   ├── Dockerfile.legacy-jar
│   │   │   ├── Dockerfile.native   # Native 模式映像
│   │   │   └── Dockerfile.native-micro
│   │   ├── java/
│   │   │   └── com/example/
│   │   │       └── GreetingResource.java  # REST Endpoint
│   │   └── resources/
│   │       ├── application.properties     # 應用配置
│   │       └── META-INF/
│   │           └── resources/
│   │               └── index.html         # 靜態首頁
│   └── test/
│       └── java/
│           └── com/example/
│               ├── GreetingResourceTest.java      # REST 測試
│               └── GreetingResourceIT.java         # Native 整合測試
├── mvnw                            # Maven Wrapper (Unix)
├── mvnw.cmd                        # Maven Wrapper (Windows)
├── pom.xml                         # Maven 配置
└── README.md

# 使用 Quarkus CLI
quarkus dev

# 或使用 Maven
./mvnw quarkus:dev

__  ____  __  _____   ___  __ ____  ______
 --/ __ \/ / / / _ | / _ \/ //_/ / / / __/
 -/ /_/ / /_/ / __ |/ , _/ ,< / /_/ /\ \
--\___\_\____/_/ |_/_/|_/_/|_|\____/___/
2026-05-15 10:00:00,000 INFO  [io.quarkus] (Quarkus Main Thread)
    my-first-app 1.0.0-SNAPSHOT on JVM (powered by Quarkus 3.35.3)
    started in 1.234s. Listening on: http://localhost:8080

Tests paused
Press [e] to edit command line args (currently ''),
      [r] to resume testing,
      [o] Toggle test output,
      [h] for more options>

package com.example;

import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.core.MediaType;

@Path("/hello")
public class GreetingResource {

    @GET
    @Produces(MediaType.TEXT_PLAIN)
    public String hello() {
        return "Hello from Quarkus";
    }
}

package com.example;

import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.core.MediaType;

@Path("/api/greeting")
public class GreetingResource {

    @GET
    @Produces(MediaType.APPLICATION_JSON)
    public Greeting hello() {
        return new Greeting("Hello", "Quarkus");
    }

    public record Greeting(String message, String from) {}
}

# 純文字
curl http://localhost:8080/hello

# JSON
curl http://localhost:8080/api/greeting
# 回傳: {"message":"Hello","from":"Quarkus"}

# 新增依賴（Extension）
quarkus extension add quarkus-hibernate-orm-panache

# 檢視已安裝 Extension
quarkus extension list --installed

# 執行測試
./mvnw test

# 建置 Uber JAR
./mvnw package -Dquarkus.package.jar.type=uber-jar

# 建置 Native Image（使用容器，無需本機 GraalVM）
./mvnw package -Pnative -Dquarkus.native.container-build=true

# 檢視配置文件
cat src/main/resources/application.properties

// 定義服務
@ApplicationScoped
public class OrderService {

    @Inject
    OrderRepository orderRepository;

    @Inject
    NotificationService notificationService;

    @Transactional
    public Order createOrder(CreateOrderRequest request) {
        Order order = new Order();
        order.customerId = request.customerId();
        order.totalAmount = request.totalAmount();
        order.status = OrderStatus.PENDING;
        orderRepository.persist(order);
        notificationService.sendOrderConfirmation(order);
        return order;
    }
}

// 欄位注入（最常用）
@Inject
MyService service;

// 建構子注入（推薦，便於測試）
public class MyResource {
    private final MyService service;

    public MyResource(MyService service) {
        this.service = service;
    }
}

// 方法注入
@Inject
void setService(MyService service) {
    this.service = service;
}

@ApplicationScoped
public class MyService {

    // 單一屬性注入
    @ConfigProperty(name = "greeting.message")
    String message;

    // 帶預設值
    @ConfigProperty(name = "greeting.suffix", defaultValue = "!")
    String suffix;

    // Optional 屬性
    @ConfigProperty(name = "greeting.prefix")
    Optional<String> prefix;
}

# application.properties
greeting.message=Hello
greeting.suffix=!!!

@ConfigMapping(prefix = "app.order")
public interface OrderConfig {
    String defaultCurrency();
    int maxItems();
    Duration timeout();
    Optional<String> prefix();

    // 巢狀配置
    NotificationConfig notification();

    interface NotificationConfig {
        boolean enabled();
        String template();
    }
}

# application.properties
app.order.default-currency=TWD
app.order.max-items=100
app.order.timeout=30S
app.order.notification.enabled=true
app.order.notification.template=order-confirmation

// 使用
@ApplicationScoped
public class OrderService {

    @Inject
    OrderConfig config;

    public void process() {
        String currency = config.defaultCurrency(); // "TWD"
        int max = config.maxItems();                 // 100
        boolean notify = config.notification().enabled(); // true
    }
}

# 新增 YAML 支援
quarkus extension add quarkus-config-yaml

# application.yaml
quarkus:
  http:
    port: 8080
  datasource:
    db-kind: postgresql
    jdbc:
      url: jdbc:postgresql://localhost:5432/mydb

app:
  order:
    default-currency: TWD
    max-items: 100
    notification:
      enabled: true

# 預設配置
quarkus:
  http:
    port: 8080

# Dev Profile
"%dev":
  quarkus:
    http:
      port: 8081
    datasource:
      jdbc:
        url: jdbc:postgresql://localhost:5432/devdb

# Test Profile
"%test":
  quarkus:
    datasource:
      jdbc:
        url: jdbc:postgresql://localhost:5432/testdb

// 新增 Extension
// quarkus extension add quarkus-hibernate-validator

@Path("/api/orders")
public class OrderResource {

    @POST
    @Consumes(MediaType.APPLICATION_JSON)
    @Produces(MediaType.APPLICATION_JSON)
    public Response createOrder(@Valid CreateOrderRequest request) {
        // 驗證自動完成，無效請求回傳 400
        return Response.status(Status.CREATED)
                .entity(orderService.create(request))
                .build();
    }
}

public record CreateOrderRequest(
    @NotBlank(message = "客戶 ID 不可為空")
    String customerId,

    @NotNull(message = "金額不可為空")
    @DecimalMin(value = "0.01", message = "金額必須大於 0")
    BigDecimal amount,

    @Size(min = 1, max = 100, message = "商品數量必須在 1-100 之間")
    List<@Valid OrderItem> items
) {}

public record OrderItem(
    @NotBlank String productId,
    @Min(1) int quantity
) {}

@Path("/api")
public class ApiResource {

    // 處理特定例外
    @ServerExceptionMapper
    public Response handleNotFoundException(NotFoundException e) {
        return Response.status(Status.NOT_FOUND)
                .entity(new ErrorResponse("NOT_FOUND", e.getMessage()))
                .build();
    }

    // 處理驗證例外
    @ServerExceptionMapper
    public Response handleConstraintViolation(ConstraintViolationException e) {
        List<String> errors = e.getConstraintViolations().stream()
                .map(v -> v.getPropertyPath() + ": " + v.getMessage())
                .toList();
        return Response.status(Status.BAD_REQUEST)
                .entity(new ErrorResponse("VALIDATION_ERROR", errors))
                .build();
    }

    public record ErrorResponse(String code, Object details) {}
}

@Provider
public class GlobalExceptionMapper {

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

    @ServerExceptionMapper
    public Response handleException(Exception e) {
        LOG.error("Unexpected error", e);
        return Response.status(Status.INTERNAL_SERVER_ERROR)
                .entity(new ErrorResponse("INTERNAL_ERROR", "系統內部錯誤，請聯繫管理員"))
                .build();
    }

    public record ErrorResponse(String code, String message) {}
}

import org.jboss.logging.Logger;

@ApplicationScoped
public class OrderService {

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

    public Order createOrder(CreateOrderRequest request) {
        LOG.infof("Creating order for customer: %s", request.customerId());
        // ...
        LOG.debugf("Order created: %s", order.id);
        return order;
    }
}

# application.properties

# 全域日誌等級
quarkus.log.level=INFO

# 特定套件日誌等級
quarkus.log.category."com.example".level=DEBUG
quarkus.log.category."org.hibernate.SQL".level=DEBUG

# 日誌格式
quarkus.log.console.format=%d{yyyy-MM-dd HH:mm:ss,SSS} %-5p [%c{3.}] (%t) %s%e%n

# JSON 格式日誌（適合容器化環境）
quarkus.log.console.json=true

@ApplicationScoped
public class AppLifecycle {

    private static final Logger LOG = Logger.getLogger(AppLifecycle.class);

    void onStart(@Observes StartupEvent ev) {
        LOG.info("應用程式啟動完成");
    }

    void onStop(@Observes ShutdownEvent ev) {
        LOG.info("應用程式正在關閉");
    }
}

// 新增 Extension: quarkus-scheduler

@ApplicationScoped
public class ScheduledTasks {

    private static final Logger LOG = Logger.getLogger(ScheduledTasks.class);

    // 每 10 秒執行一次
    @Scheduled(every = "10s")
    void cleanupExpiredSessions() {
        LOG.info("清理過期 Session");
    }

    // 使用 Cron 表達式，每天凌晨 2 點
    @Scheduled(cron = "0 0 2 * * ?")
    void dailyReport() {
        LOG.info("生成每日報表");
    }

    // 可透過配置控制間隔
    @Scheduled(every = "{app.cleanup.interval}")
    void configurableTask() {
        LOG.info("可配置間隔的排程任務");
    }
}

app.cleanup.interval=30s

// Extension: quarkus-rest-qute

@Path("/pages")
public class PageResource {

    @Inject
    Template hello; // 自動對應 src/main/resources/templates/hello.html

    @GET
    @Path("/{name}")
    @Produces(MediaType.TEXT_HTML)
    public TemplateInstance get(@PathParam("name") String name) {
        return hello.data("name", name);
    }
}

<!-- src/main/resources/templates/hello.html -->
<!DOCTYPE html>
<html>
<head><title>Hello</title></head>
<body>
    <h1>Hello, {name}!</h1>
</body>
</html>

@Path("/api/v1/products")
@Produces(MediaType.APPLICATION_JSON)
@Consumes(MediaType.APPLICATION_JSON)
public class ProductResource {

    @Inject
    ProductService productService;

    @GET
    public List<ProductDTO> listAll() {
        return productService.listAll();
    }

    @GET
    @Path("/{id}")
    public ProductDTO getById(@PathParam("id") Long id) {
        return productService.findById(id)
                .orElseThrow(() -> new NotFoundException("Product not found: " + id));
    }

    @POST
    public Response create(@Valid CreateProductRequest request) {
        ProductDTO created = productService.create(request);
        URI location = URI.create("/api/v1/products/" + created.id());
        return Response.created(location).entity(created).build();
    }

    @PUT
    @Path("/{id}")
    public ProductDTO update(@PathParam("id") Long id,
                             @Valid UpdateProductRequest request) {
        return productService.update(id, request);
    }

    @DELETE
    @Path("/{id}")
    public Response delete(@PathParam("id") Long id) {
        productService.delete(id);
        return Response.noContent().build();
    }
}

@Entity
@Table(name = "products")
public class Product extends PanacheEntity {

    @Column(nullable = false)
    public String name;

    @Column(length = 1000)
    public String description;

    @Column(nullable = false, precision = 10, scale = 2)
    public BigDecimal price;

    @Column(nullable = false)
    public String category;

    @Column(name = "created_at", nullable = false, updatable = false)
    public LocalDateTime createdAt;

    @Column(name = "updated_at")
    public LocalDateTime updatedAt;

    @PrePersist
    void onCreate() {
        createdAt = LocalDateTime.now();
        updatedAt = createdAt;
    }

    @PreUpdate
    void onUpdate() {
        updatedAt = LocalDateTime.now();
    }
}

@ApplicationScoped
public class ProductService {

    @Inject
    ProductRepository repository;

    public List<ProductDTO> listAll() {
        return repository.listAll().stream()
                .map(this::toDTO)
                .toList();
    }

    public Optional<ProductDTO> findById(Long id) {
        return repository.findByIdOptional(id)
                .map(this::toDTO);
    }

    @Transactional
    public ProductDTO create(CreateProductRequest request) {
        Product product = new Product();
        product.name = request.name();
        product.description = request.description();
        product.price = request.price();
        product.category = request.category();
        repository.persist(product);
        return toDTO(product);
    }

    @Transactional
    public ProductDTO update(Long id, UpdateProductRequest request) {
        Product product = repository.findByIdOptional(id)
                .orElseThrow(() -> new NotFoundException("Product not found: " + id));
        product.name = request.name();
        product.description = request.description();
        product.price = request.price();
        product.category = request.category();
        return toDTO(product);
    }

    @Transactional
    public void delete(Long id) {
        repository.deleteById(id);
    }

    private ProductDTO toDTO(Product product) {
        return new ProductDTO(
            product.id, product.name, product.description,
            product.price, product.category,
            product.createdAt, product.updatedAt
        );
    }
}

public record ProductDTO(
    Long id,
    String name,
    String description,
    BigDecimal price,
    String category,
    LocalDateTime createdAt,
    LocalDateTime updatedAt
) {}

public record CreateProductRequest(
    @NotBlank String name,
    String description,
    @NotNull @DecimalMin("0.01") BigDecimal price,
    @NotBlank String category
) {}

public record UpdateProductRequest(
    @NotBlank String name,
    String description,
    @NotNull @DecimalMin("0.01") BigDecimal price,
    @NotBlank String category
) {}

@GET
public PaginatedResponse<ProductDTO> listProducts(
        @QueryParam("page") @DefaultValue("0") int page,
        @QueryParam("size") @DefaultValue("20") int size,
        @QueryParam("sort") @DefaultValue("createdAt") String sort,
        @QueryParam("direction") @DefaultValue("desc") String direction,
        @QueryParam("category") String category,
        @QueryParam("search") String search) {

    PanacheQuery<Product> query;

    if (category != null && search != null) {
        query = Product.find("category = ?1 and name like ?2",
                Sort.by(sort).direction(
                    "asc".equalsIgnoreCase(direction) ? Direction.Ascending : Direction.Descending),
                category, "%" + search + "%");
    } else if (category != null) {
        query = Product.find("category", Sort.by(sort), category);
    } else {
        query = Product.findAll(Sort.by(sort));
    }

    List<ProductDTO> items = query.page(page, size).list().stream()
            .map(this::toDTO)
            .toList();

    return new PaginatedResponse<>(
        items,
        query.count(),
        page,
        size
    );
}

public record PaginatedResponse<T>(
    List<T> items,
    long totalCount,
    int page,
    int size
) {
    public int totalPages() {
        return (int) Math.ceil((double) totalCount / size);
    }
}

# 新增 Extension
quarkus extension add quarkus-smallrye-openapi

@Path("/api/v1/products")
@Tag(name = "Product", description = "商品管理 API")
@Produces(MediaType.APPLICATION_JSON)
@Consumes(MediaType.APPLICATION_JSON)
public class ProductResource {

    @GET
    @Operation(summary = "取得商品列表", description = "支援分頁、排序與篩選")
    @APIResponse(responseCode = "200", description = "成功取得商品列表")
    public PaginatedResponse<ProductDTO> listProducts(
            @Parameter(description = "頁碼，從 0 開始") @QueryParam("page") @DefaultValue("0") int page,
            @Parameter(description = "每頁筆數") @QueryParam("size") @DefaultValue("20") int size) {
        // ...
    }

    @POST
    @Operation(summary = "建立商品")
    @APIResponse(responseCode = "201", description = "商品建立成功")
    @APIResponse(responseCode = "400", description = "請求資料驗證失敗")
    public Response create(@Valid CreateProductRequest request) {
        // ...
    }
}

# application.properties
quarkus.smallrye-openapi.info-title=Product Service API
quarkus.smallrye-openapi.info-version=1.0.0
quarkus.smallrye-openapi.info-description=商品管理服務 RESTful API

# Swagger UI（僅 dev/test 環境啟用）
quarkus.swagger-ui.always-include=false
%dev.quarkus.swagger-ui.always-include=true

// Extension: quarkus-rest-client-jackson

@Path("/api")
@RegisterRestClient(configKey = "external-api")
public interface ExternalApiClient {

    @GET
    @Path("/users/{id}")
    UserDTO getUser(@PathParam("id") Long id);

    @POST
    @Path("/notifications")
    @Consumes(MediaType.APPLICATION_JSON)
    void sendNotification(NotificationRequest request);
}

// 使用
@ApplicationScoped
public class UserService {

    @RestClient
    ExternalApiClient apiClient;

    public UserDTO getExternalUser(Long id) {
        return apiClient.getUser(id);
    }
}

# application.properties
quarkus.rest-client.external-api.url=https://api.example.com
quarkus.rest-client.external-api.scope=jakarta.inject.Singleton
quarkus.rest-client.external-api.connect-timeout=5000
quarkus.rest-client.external-api.read-timeout=10000

public record ApiError(
    String code,
    String message,
    String path,
    LocalDateTime timestamp,
    List<FieldError> fieldErrors
) {
    public ApiError(String code, String message, String path) {
        this(code, message, path, LocalDateTime.now(), null);
    }

    public record FieldError(String field, String message) {}
}

# CORS 設定（允許前端跨域存取）
quarkus.http.cors=true
quarkus.http.cors.origins=http://localhost:3000,http://localhost:5173
quarkus.http.cors.methods=GET,POST,PUT,DELETE,OPTIONS
quarkus.http.cors.headers=Content-Type,Authorization
quarkus.http.cors.exposed-headers=X-Total-Count
quarkus.http.cors.access-control-max-age=24H

project-root/
├── backend/                    # Quarkus 後端
│   ├── src/
│   ├── pom.xml
│   └── Dockerfile
├── frontend/                   # 前端框架（Vue/React/Angular）
│   ├── src/
│   ├── package.json
│   └── Dockerfile
├── docker-compose.yaml         # 本機開發環境
├── k8s/                        # Kubernetes 部署設定
│   ├── backend-deployment.yaml
│   └── frontend-deployment.yaml
└── README.md

# application.properties — PostgreSQL 範例
quarkus.datasource.db-kind=postgresql
quarkus.datasource.username=myuser
quarkus.datasource.password=mypassword
quarkus.datasource.jdbc.url=jdbc:postgresql://localhost:5432/mydb
quarkus.datasource.jdbc.max-size=20
quarkus.datasource.jdbc.min-size=5

# 多資料來源
quarkus.datasource."orders".db-kind=postgresql
quarkus.datasource."orders".jdbc.url=jdbc:postgresql://localhost:5432/ordersdb
quarkus.datasource."orders".username=orderuser
quarkus.datasource."orders".password=orderpass

# Hibernate ORM
quarkus.hibernate-orm.database.generation=validate
quarkus.hibernate-orm.log.sql=true

# Dev Profile — 使用 Dev Services，無需手動配置
%dev.quarkus.hibernate-orm.database.generation=drop-and-create

@Entity
@Table(name = "orders")
@NamedQuery(name = "Order.findByStatus",
            query = "FROM Order WHERE status = :status ORDER BY createdAt DESC")
public class Order {

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

    @Column(name = "customer_id", nullable = false)
    public String customerId;

    @Column(nullable = false, precision = 12, scale = 2)
    public BigDecimal totalAmount;

    @Enumerated(EnumType.STRING)
    @Column(nullable = false)
    public OrderStatus status;

    @OneToMany(mappedBy = "order", cascade = CascadeType.ALL, orphanRemoval = true)
    public List<OrderItem> items = new ArrayList<>();

    @Column(name = "created_at", nullable = false, updatable = false)
    public LocalDateTime createdAt;

    @Column(name = "updated_at")
    public LocalDateTime updatedAt;

    @PrePersist
    void onCreate() {
        createdAt = LocalDateTime.now();
        updatedAt = createdAt;
    }

    @PreUpdate
    void onUpdate() {
        updatedAt = LocalDateTime.now();
    }
}

@Entity
@Table(name = "order_items")
public class OrderItem {

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

    @ManyToOne(fetch = FetchType.LAZY)
    @JoinColumn(name = "order_id", nullable = false)
    public Order order;

    @Column(name = "product_id", nullable = false)
    public String productId;

    @Column(nullable = false)
    public int quantity;

    @Column(name = "unit_price", nullable = false, precision = 10, scale = 2)
    public BigDecimal unitPrice;
}

public enum OrderStatus {
    PENDING, CONFIRMED, SHIPPED, DELIVERED, CANCELLED
}

@Entity
public class Product extends PanacheEntity {

    public String name;
    public BigDecimal price;
    public String category;

    // 自訂查詢方法
    public static List<Product> findByCategory(String category) {
        return find("category", category).list();
    }

    public static List<Product> findExpensive(BigDecimal minPrice) {
        return find("price >= ?1 order by price desc", minPrice).list();
    }

    public static long countByCategory(String category) {
        return count("category", category);
    }

    public static PanacheQuery<Product> findByCategoryPaged(String category) {
        return find("category", category);
    }
}

@ApplicationScoped
public class ProductRepository implements PanacheRepository<Product> {

    public List<Product> findByCategory(String category) {
        return find("category", category).list();
    }

    public Optional<Product> findByName(String name) {
        return find("name", name).firstResultOptional();
    }

    public List<Product> search(String keyword, Sort sort) {
        return find("name like ?1 or description like ?1",
                     sort, "%" + keyword + "%").list();
    }

    public PanacheQuery<Product> findAllPaged() {
        return findAll(Sort.by("createdAt").descending());
    }
}

// Extension: quarkus-reactive-pg-client

@ApplicationScoped
public class ReactiveProductRepository {

    @Inject
    PgPool client;

    public Uni<List<Product>> findAll() {
        return client.query("SELECT id, name, price FROM products ORDER BY id")
                .execute()
                .onItem().transform(rowSet -> {
                    List<Product> products = new ArrayList<>();
                    for (Row row : rowSet) {
                        products.add(fromRow(row));
                    }
                    return products;
                });
    }

    public Uni<Product> findById(Long id) {
        return client.preparedQuery("SELECT id, name, price FROM products WHERE id = $1")
                .execute(Tuple.of(id))
                .onItem().transform(RowSet::iterator)
                .onItem().transform(iterator ->
                    iterator.hasNext() ? fromRow(iterator.next()) : null);
    }

    private Product fromRow(Row row) {
        Product p = new Product();
        p.id = row.getLong("id");
        p.name = row.getString("name");
        p.price = row.getBigDecimal("price");
        return p;
    }
}

@ApplicationScoped
public class OrderService {

    @Inject
    OrderRepository orderRepository;

    @Inject
    InventoryService inventoryService;

    // 宣告式交易
    @Transactional
    public Order createOrder(CreateOrderRequest request) {
        Order order = new Order();
        order.customerId = request.customerId();
        order.status = OrderStatus.PENDING;

        for (var item : request.items()) {
            inventoryService.reserve(item.productId(), item.quantity());
            OrderItem orderItem = new OrderItem();
            orderItem.order = order;
            orderItem.productId = item.productId();
            orderItem.quantity = item.quantity();
            orderItem.unitPrice = item.unitPrice();
            order.items.add(orderItem);
        }

        order.totalAmount = order.items.stream()
                .map(i -> i.unitPrice.multiply(BigDecimal.valueOf(i.quantity)))
                .reduce(BigDecimal.ZERO, BigDecimal::add);

        orderRepository.persist(order);
        return order;
    }

    // 程式化交易控制
    @Inject
    UserTransaction userTransaction;

    public void manualTransactionExample() throws Exception {
        userTransaction.begin();
        try {
            // 業務邏輯
            userTransaction.commit();
        } catch (Exception e) {
            userTransaction.rollback();
            throw e;
        }
    }

    // 使用 QuarkusTransaction（簡化 API）
    public Order createOrderProgrammatic(CreateOrderRequest request) {
        return QuarkusTransaction.requiringNew().call(() -> {
            // 在新交易中執行
            Order order = new Order();
            // ...
            orderRepository.persist(order);
            return order;
        });
    }
}

# Extension
quarkus extension add quarkus-flyway

# application.properties
quarkus.flyway.migrate-at-start=true
quarkus.flyway.locations=db/migration
quarkus.flyway.baseline-on-migrate=true

-- src/main/resources/db/migration/V1.0.0__create_products.sql
CREATE TABLE products (
    id BIGSERIAL PRIMARY KEY,
    name VARCHAR(255) NOT NULL,
    description TEXT,
    price DECIMAL(10, 2) NOT NULL,
    category VARCHAR(100) NOT NULL,
    created_at TIMESTAMP NOT NULL DEFAULT NOW(),
    updated_at TIMESTAMP
);

CREATE INDEX idx_products_category ON products(category);

-- src/main/resources/db/migration/V1.1.0__create_orders.sql
CREATE TABLE orders (
    id BIGSERIAL PRIMARY KEY,
    customer_id VARCHAR(100) NOT NULL,
    total_amount DECIMAL(12, 2) NOT NULL,
    status VARCHAR(20) NOT NULL,
    created_at TIMESTAMP NOT NULL DEFAULT NOW(),
    updated_at TIMESTAMP
);

CREATE TABLE order_items (
    id BIGSERIAL PRIMARY KEY,
    order_id BIGINT NOT NULL REFERENCES orders(id),
    product_id VARCHAR(100) NOT NULL,
    quantity INT NOT NULL,
    unit_price DECIMAL(10, 2) NOT NULL
);

quarkus extension add quarkus-liquibase

quarkus.liquibase.migrate-at-start=true
quarkus.liquibase.change-log=db/changelog/db.changelog-master.xml

<!-- src/main/resources/db/changelog/db.changelog-master.xml -->
<?xml version="1.0" encoding="UTF-8"?>
<databaseChangeLog
    xmlns="http://www.liquibase.org/xml/ns/dbchangelog"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangelog
        http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-latest.xsd">

    <include file="db/changelog/changes/001-create-products.xml"/>
    <include file="db/changelog/changes/002-create-orders.xml"/>
</databaseChangeLog>

quarkus extension add quarkus-redis-client

@ApplicationScoped
public class CacheService {

    @Inject
    RedisDataSource redis;

    public void cacheProduct(String key, String productJson) {
        redis.value(String.class).set(key, productJson);
    }

    public String getCachedProduct(String key) {
        return redis.value(String.class).get(key);
    }

    public void invalidate(String key) {
        redis.key().del(key);
    }
}

quarkus.redis.hosts=redis://localhost:6379
quarkus.redis.max-pool-size=10

quarkus extension add quarkus-mongodb-panache

@MongoEntity(collection = "audit_logs")
public class AuditLog extends PanacheMongoEntity {

    public String action;
    public String userId;
    public String details;
    public Instant timestamp;

    public static List<AuditLog> findByUserId(String userId) {
        return find("userId", userId).list();
    }

    public static List<AuditLog> findRecent(int limit) {
        return find("order by timestamp desc").page(0, limit).list();
    }
}

quarkus.mongodb.connection-string=mongodb://localhost:27017
quarkus.mongodb.database=myapp

// ❌ N+1 問題
List<Order> orders = Order.listAll();
for (Order order : orders) {
    order.items.size(); // 每筆 Order 觸發一次查詢
}

// ✅ 使用 JOIN FETCH
List<Order> orders = Order.find(
    "SELECT o FROM Order o LEFT JOIN FETCH o.items"
).list();

// 只查詢需要的欄位
@RegisterForReflection
public record ProductSummary(Long id, String name, BigDecimal price) {}

List<ProductSummary> summaries = Product.find(
    "SELECT new com.example.ProductSummary(p.id, p.name, p.price) FROM Product p"
).project(ProductSummary.class).list();

# Agroal 連線池設定
quarkus.datasource.jdbc.min-size=5
quarkus.datasource.jdbc.max-size=20
quarkus.datasource.jdbc.initial-size=5
quarkus.datasource.jdbc.acquisition-timeout=30S
quarkus.datasource.jdbc.idle-removal-interval=2M
quarkus.datasource.jdbc.max-lifetime=30M
quarkus.datasource.jdbc.leak-detection-interval=1M

# 啟用 SQL 日誌（僅開發環境）
%dev.quarkus.hibernate-orm.log.sql=true
%dev.quarkus.hibernate-orm.log.bind-parameters=true

// 命令式（Imperative）— 在 Worker Thread 執行
@GET
@Path("/blocking")
public String blockingEndpoint() {
    // 同步呼叫，Quarkus 自動分派至 Worker Thread
    return someBlockingOperation();
}

// 響應式（Reactive）— 在 Event Loop 執行
@GET
@Path("/reactive")
public Uni<String> reactiveEndpoint() {
    return Uni.createFrom().item(() -> "Hello Reactive");
}

// Uni 基本操作
@GET
@Path("/user/{id}")
public Uni<UserDTO> getUser(@PathParam("id") Long id) {
    return userRepository.findByIdReactive(id)
            .onItem().ifNotNull().transform(this::toDTO)
            .onItem().ifNull().failWith(() ->
                new NotFoundException("User not found: " + id));
}

// Uni 組合操作
@GET
@Path("/dashboard/{userId}")
public Uni<DashboardDTO> getDashboard(@PathParam("userId") Long userId) {
    Uni<User> userUni = userService.findById(userId);
    Uni<List<Order>> ordersUni = orderService.findByUserId(userId);
    Uni<AccountBalance> balanceUni = accountService.getBalance(userId);

    return Uni.combine().all()
            .unis(userUni, ordersUni, balanceUni)
            .with((user, orders, balance) ->
                new DashboardDTO(user, orders, balance));
}

// Multi 串流
@GET
@Path("/events")
@Produces(MediaType.SERVER_SENT_EVENTS)
@RestStreamElementType(MediaType.APPLICATION_JSON)
public Multi<Event> streamEvents() {
    return Multi.createFrom().ticks().every(Duration.ofSeconds(1))
            .onItem().transform(tick -> new Event("tick-" + tick, Instant.now()));
}

quarkus extension add quarkus-smallrye-context-propagation

@ApplicationScoped
public class AsyncOrderService {

    @Inject
    ManagedExecutor managedExecutor;

    @Transactional
    public Uni<Order> processOrderAsync(Long orderId) {
        // Context Propagation 自動傳播 Transaction 與 Security Context
        return Uni.createFrom().item(() -> {
            Order order = Order.findById(orderId);
            order.status = OrderStatus.CONFIRMED;
            return order;
        }).runSubscriptionOn(managedExecutor);
    }
}

// Extension: 無需額外 Extension，Java 21+ 內建

@Path("/api/orders")
public class OrderResource {

    @GET
    @RunOnVirtualThread  // 在 Virtual Thread 上執行
    public List<OrderDTO> listOrders() {
        // 可以使用阻塞式 API，但不會佔用平台執行緒
        List<Order> orders = Order.listAll();
        return orders.stream().map(this::toDTO).toList();
    }
}

# 全域啟用 Virtual Threads（無需逐一標註 @RunOnVirtualThread）
quarkus.virtual-threads.enabled=true

quarkus extension add quarkus-messaging-kafka

@ApplicationScoped
public class OrderEventProducer {

    @Inject
    @Channel("order-events-out")
    Emitter<OrderEvent> emitter;

    public void sendOrderCreated(Order order) {
        OrderEvent event = new OrderEvent(
            order.id, "ORDER_CREATED", order.customerId, Instant.now()
        );
        emitter.send(Message.of(event)
            .withMetadata(Metadata.of(
                OutgoingKafkaRecordMetadata.<String>builder()
                    .withKey(order.id.toString())
                    .build()
            )));
    }
}

@ApplicationScoped
public class OrderEventConsumer {

    private static final Logger LOG = Logger.getLogger(OrderEventConsumer.class);

    @Incoming("order-events-in")
    public CompletionStage<Void> process(Message<OrderEvent> message) {
        OrderEvent event = message.getPayload();
        LOG.infof("Received order event: %s for order %d", event.type(), event.orderId());

        try {
            // 處理事件
            processEvent(event);
            return message.ack();
        } catch (Exception e) {
            LOG.error("Failed to process event", e);
            return message.nack(e);
        }
    }

    private void processEvent(OrderEvent event) {
        // 業務邏輯
    }
}

# application.properties
# 生產者
mp.messaging.outgoing.order-events-out.connector=smallrye-kafka
mp.messaging.outgoing.order-events-out.topic=order-events
mp.messaging.outgoing.order-events-out.value.serializer=io.quarkus.kafka.client.serialization.ObjectMapperSerializer

# 消費者
mp.messaging.incoming.order-events-in.connector=smallrye-kafka
mp.messaging.incoming.order-events-in.topic=order-events
mp.messaging.incoming.order-events-in.group.id=order-processor
mp.messaging.incoming.order-events-in.value.deserializer=com.example.OrderEventDeserializer
mp.messaging.incoming.order-events-in.auto.offset.reset=earliest

quarkus extension add quarkus-messaging-amqp

@ApplicationScoped
public class NotificationSender {

    @Inject
    @Channel("notifications")
    Emitter<NotificationMessage> emitter;

    public void send(String userId, String content) {
        emitter.send(new NotificationMessage(userId, content, Instant.now()));
    }
}

@ApplicationScoped
public class NotificationReceiver {

    @Incoming("notifications-in")
    public void receive(NotificationMessage message) {
        // 處理通知
    }
}

quarkus extension add quarkus-messaging-rabbitmq

# application.properties
rabbitmq-host=localhost
rabbitmq-port=5672
rabbitmq-username=guest
rabbitmq-password=guest

mp.messaging.outgoing.task-queue.connector=smallrye-rabbitmq
mp.messaging.outgoing.task-queue.exchange.name=tasks
mp.messaging.outgoing.task-queue.exchange.type=direct

quarkus extension add quarkus-messaging-pulsar

# application.properties
mp.messaging.outgoing.events-out.connector=smallrye-pulsar
mp.messaging.outgoing.events-out.serviceUrl=pulsar://localhost:6650
mp.messaging.outgoing.events-out.topic=events

quarkus extension add quarkus-grpc

// src/main/proto/greeting.proto
syntax = "proto3";
package com.example;

option java_package = "com.example.grpc";

service GreetingService {
    rpc SayHello (HelloRequest) returns (HelloReply);
}

message HelloRequest {
    string name = 1;
}

message HelloReply {
    string message = 1;
}

@GrpcService
public class GreetingGrpcService implements GreetingService {

    @Override
    public Uni<HelloReply> sayHello(HelloRequest request) {
        return Uni.createFrom().item(
            HelloReply.newBuilder()
                .setMessage("Hello, " + request.getName())
                .build()
        );
    }
}

// 使用 @Incoming 和 @Outgoing 建立處理管道
@ApplicationScoped
public class OrderPipeline {

    @Incoming("raw-orders")
    @Outgoing("validated-orders")
    public Order validateOrder(Order order) {
        if (order.totalAmount.compareTo(BigDecimal.ZERO) <= 0) {
            throw new IllegalArgumentException("Invalid order amount");
        }
        order.status = OrderStatus.VALIDATED;
        return order;
    }

    @Incoming("validated-orders")
    @Outgoing("enriched-orders")
    public Uni<Order> enrichOrder(Order order) {
        return customerService.getCustomer(order.customerId)
                .onItem().transform(customer -> {
                    order.customerName = customer.name();
                    return order;
                });
    }

    @Incoming("enriched-orders")
    public void processOrder(Order order) {
        // 最終處理
    }
}

# 無需手動配置 Kafka 連線，Dev Services 自動處理
# %dev 環境下，只要有 quarkus-messaging-kafka Extension，
# Quarkus 就會自動啟動 Kafka 容器

# 自訂 Dev Services 設定（可選）
quarkus.kafka.devservices.port=9092
quarkus.kafka.devservices.topic-partitions.order-events=3

// 基於角色的存取控制
@Path("/api/admin")
@RolesAllowed("admin")
public class AdminResource {

    @GET
    @Path("/users")
    public List<UserDTO> listUsers() {
        return userService.listAll();
    }

    @DELETE
    @Path("/users/{id}")
    @RolesAllowed("super-admin") // 更細粒度的角色限制
    public Response deleteUser(@PathParam("id") Long id) {
        userService.delete(id);
        return Response.noContent().build();
    }
}

// 取得安全上下文
@Path("/api/profile")
@Authenticated // 僅要求已認證，不限角色
public class ProfileResource {

    @Inject
    SecurityIdentity identity;

    @GET
    public ProfileDTO getProfile() {
        String username = identity.getPrincipal().getName();
        Set<String> roles = identity.getRoles();
        return new ProfileDTO(username, roles);
    }
}

quarkus extension add quarkus-security-properties-file

# application.properties
quarkus.security.users.embedded.enabled=true
quarkus.security.users.embedded.plain-text=true
quarkus.security.users.embedded.users.admin=admin123
quarkus.security.users.embedded.roles.admin=admin,user
quarkus.security.users.embedded.users.user=user123
quarkus.security.users.embedded.roles.user=user

quarkus extension add quarkus-smallrye-jwt

# application.properties
mp.jwt.verify.publickey.location=META-INF/resources/publicKey.pem
mp.jwt.verify.issuer=https://my-auth-server.example.com
smallrye.jwt.path.groups=groups

@Path("/api/secured")
@Authenticated
public class SecuredResource {

    @Inject
    JsonWebToken jwt;

    @GET
    @Path("/info")
    public Response getTokenInfo() {
        return Response.ok(Map.of(
            "subject", jwt.getSubject(),
            "issuer", jwt.getIssuer(),
            "groups", jwt.getGroups(),
            "expiration", jwt.getExpirationTime()
        )).build();
    }

    @GET
    @Path("/admin")
    @RolesAllowed("admin")
    public String adminOnly() {
        return "Admin content for " + jwt.getName();
    }
}

quarkus extension add quarkus-oidc

# OAuth2 Bearer Token 驗證
quarkus.oidc.auth-server-url=https://auth.example.com/realms/my-realm
quarkus.oidc.client-id=my-api
quarkus.oidc.application-type=service
quarkus.oidc.token.issuer=https://auth.example.com/realms/my-realm

# OIDC — Web Application（Authorization Code Flow）
quarkus.oidc.auth-server-url=https://auth.example.com/realms/my-realm
quarkus.oidc.client-id=my-web-app
quarkus.oidc.credentials.secret=my-client-secret
quarkus.oidc.application-type=web-app

# Token 配置
quarkus.oidc.token.principal-claim=preferred_username
quarkus.oidc.roles.role-claim-path=realm_access/roles

# Logout
quarkus.oidc.logout.path=/logout
quarkus.oidc.logout.post-logout-path=/

# Keycloak 完整設定
quarkus.oidc.auth-server-url=https://keycloak.example.com/realms/enterprise
quarkus.oidc.client-id=order-service
quarkus.oidc.credentials.secret=${OIDC_CLIENT_SECRET}
quarkus.oidc.application-type=service
quarkus.oidc.token.issuer=https://keycloak.example.com/realms/enterprise

# Role Mapping
quarkus.oidc.roles.role-claim-path=realm_access/roles
quarkus.oidc.roles.source=accesstoken

# Token 驗證
quarkus.oidc.token.audience=order-service

# Dev Mode 自動啟動 Keycloak 容器
%dev.quarkus.oidc.devservices.enabled=true
%dev.quarkus.oidc.devservices.realm-path=dev-realm.json

@ApplicationScoped
public class CustomTenantResolver implements TenantConfigResolver {

    @Override
    public Uni<OidcTenantConfig> resolve(RoutingContext context,
                                          OidcRequestContext<OidcTenantConfig> requestContext) {
        String tenantId = context.request().getHeader("X-Tenant-ID");

        if ("tenant-a".equals(tenantId)) {
            OidcTenantConfig config = new OidcTenantConfig();
            config.setTenantId("tenant-a");
            config.setAuthServerUrl("https://auth.tenant-a.example.com/realms/main");
            config.setClientId("my-app");
            return Uni.createFrom().item(config);
        }

        return Uni.createFrom().nullItem(); // 使用預設配置
    }
}

# application.properties
quarkus.http.cors=true
quarkus.http.cors.origins=https://app.example.com,https://admin.example.com
quarkus.http.cors.methods=GET,POST,PUT,DELETE,OPTIONS
quarkus.http.cors.headers=Content-Type,Authorization,X-Requested-With
quarkus.http.cors.exposed-headers=X-Total-Count,X-Request-Id
quarkus.http.cors.access-control-max-age=24H
quarkus.http.cors.access-control-allow-credentials=true

quarkus extension add quarkus-csrf-reactive

quarkus.csrf-reactive.cookie-name=csrf-token
quarkus.csrf-reactive.form-field-name=_csrf

# 使用環境變數（推薦）
quarkus.datasource.password=${DB_PASSWORD}
quarkus.oidc.credentials.secret=${OIDC_SECRET}

# Kubernetes Secret
quarkus.kubernetes-config.secrets.enabled=true
quarkus.kubernetes-config.secrets=my-app-secrets

// 自訂 Credentials Provider
@ApplicationScoped
@Unremovable
public class VaultCredentialsProvider implements CredentialsProvider {

    @Override
    public Map<String, String> getCredentials(String credentialsProviderName) {
        // 從 Vault 或其他安全儲存取得憑證
        return Map.of(
            "user", fetchFromVault("db-user"),
            "password", fetchFromVault("db-password")
        );
    }

    private String fetchFromVault(String key) {
        // 實作 Vault 呼叫
        return "";
    }
}

@QuarkusTest
public class SecuredResourceTest {

    @Test
    public void testUnauthenticated() {
        given()
            .when().get("/api/secured/info")
            .then().statusCode(401);
    }

    @Test
    @TestSecurity(user = "admin", roles = "admin")
    public void testAdminAccess() {
        given()
            .when().get("/api/secured/admin")
            .then().statusCode(200);
    }

    @Test
    @TestSecurity(user = "user", roles = "user")
    public void testUserCannotAccessAdmin() {
        given()
            .when().get("/api/secured/admin")
            .then().statusCode(403);
    }

    @Test
    @OidcSecurity(claims = {
        @Claim(key = "sub", value = "user123"),
        @Claim(key = "email", value = "user@example.com")
    })
    public void testWithOidcClaims() {
        // 使用模擬 OIDC Token 測試
    }
}

// 純單元測試，不啟動 Quarkus 容器
public class OrderServiceTest {

    @Test
    void shouldCalculateOrderTotal() {
        Order order = new Order();
        order.items = List.of(
            createItem("P1", 2, new BigDecimal("10.00")),
            createItem("P2", 1, new BigDecimal("25.50"))
        );

        BigDecimal total = order.calculateTotal();
        assertEquals(new BigDecimal("45.50"), total);
    }

    private OrderItem createItem(String productId, int qty, BigDecimal price) {
        OrderItem item = new OrderItem();
        item.productId = productId;
        item.quantity = qty;
        item.unitPrice = price;
        return item;
    }
}

@QuarkusTest
@TestProfile(IntegrationTestProfile.class)
public class OrderResourceIT {

    @Test
    void shouldCreateOrder() {
        String requestBody = """
            {
                "customerId": "C001",
                "items": [
                    {"productId": "P001", "quantity": 2, "unitPrice": 29.99}
                ]
            }
            """;

        given()
            .contentType(ContentType.JSON)
            .body(requestBody)
        .when()
            .post("/api/v1/orders")
        .then()
            .statusCode(201)
            .body("customerId", equalTo("C001"))
            .body("status", equalTo("PENDING"))
            .header("Location", containsString("/api/v1/orders/"));
    }
}

@QuarkusTest
public class ProductResourceTest {

    @Inject
    ProductRepository productRepository;

    @Test
    @Transactional
    void shouldListProducts() {
        // 準備測試資料
        Product product = new Product();
        product.name = "Test Product";
        product.price = new BigDecimal("9.99");
        product.category = "test";
        productRepository.persist(product);

        // 測試 API
        given()
        .when()
            .get("/api/v1/products")
        .then()
            .statusCode(200)
            .body("size()", greaterThan(0))
            .body("[0].name", equalTo("Test Product"));
    }

    @Test
    void shouldReturn404ForNonExistentProduct() {
        given()
        .when()
            .get("/api/v1/products/99999")
        .then()
            .statusCode(404);
    }
}

Press [r] to resume testing, [o] Toggle test output

Tests: 15 passed, 2 failed, 0 skipped

# 設定 Continuous Testing 行為
quarkus.test.continuous-testing=enabled
quarkus.test.display-test-output=true
quarkus.test.basic-console=false

@QuarkusIntegrationTest // 用於 Native Image 測試
public class ProductResourceNativeIT extends ProductResourceTest {
    // 繼承所有測試方法，在 Native Image 上執行
}

# 執行 Native Test
./mvnw verify -Pnative

<!-- pom.xml — JaCoCo 設定 -->
<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-jacoco</artifactId>
    <scope>test</scope>
</dependency>

quarkus.jacoco.report-location=target/jacoco-report

@QuarkusTest
@QuarkusTestResource(PostgresTestResource.class)
public class OrderRepositoryTest {
    // Testcontainers 自動啟動 PostgreSQL 容器
}

// 或使用 Dev Services（推薦，更簡潔）
// Quarkus 的 Dev Services 在測試時也會自動啟動容器
@QuarkusTest
public class OrderRepositoryTest {

    @Inject
    OrderRepository repository;

    @Test
    @Transactional
    void shouldPersistAndFind() {
        Order order = new Order();
        order.customerId = "C001";
        order.totalAmount = new BigDecimal("100.00");
        order.status = OrderStatus.PENDING;
        repository.persist(order);

        assertNotNull(order.id);

        Order found = repository.findById(order.id);
        assertEquals("C001", found.customerId);
    }
}

@QuarkusTest
public class SecurityTest {

    @Test
    void shouldRejectUnauthenticatedRequest() {
        given()
        .when()
            .get("/api/admin/users")
        .then()
            .statusCode(401);
    }

    @Test
    @TestSecurity(user = "admin", roles = {"admin"})
    void shouldAllowAdminAccess() {
        given()
        .when()
            .get("/api/admin/users")
        .then()
            .statusCode(200);
    }

    @Test
    @TestSecurity(user = "user", roles = {"user"})
    void shouldForbidNonAdminAccess() {
        given()
        .when()
            .get("/api/admin/users")
        .then()
            .statusCode(403);
    }
}

@QuarkusTest
public class ProductApiContractTest {

    @Test
    void shouldReturnValidJsonSchema() {
        given()
        .when()
            .get("/api/v1/products")
        .then()
            .statusCode(200)
            .contentType(ContentType.JSON)
            .body("$", instanceOf(List.class))
            .body("[0].id", notNullValue())
            .body("[0].name", notNullValue())
            .body("[0].price", notNullValue());
    }

    @Test
    void shouldValidateRequestBody() {
        given()
            .contentType(ContentType.JSON)
            .body("{}")
        .when()
            .post("/api/v1/products")
        .then()
            .statusCode(400);
    }
}

Dev Mode 啟動
  → 偵測到 quarkus-jdbc-postgresql Extension
  → 未設定 quarkus.datasource.jdbc.url（在 %dev profile）
  → 自動啟動 PostgreSQL Testcontainer
  → 自動注入連線資訊
  → 應用正常啟動

# 自訂 Dev Services 設定（可選）
quarkus.datasource.devservices.port=5432
quarkus.datasource.devservices.image-name=postgres:16
quarkus.datasource.devservices.db-name=devdb
quarkus.datasource.devservices.init-script-path=init-dev.sql

# 自動啟動 Kafka 容器
quarkus.kafka.devservices.enabled=true
quarkus.kafka.devservices.port=9092
quarkus.kafka.devservices.topic-partitions.order-events=3
quarkus.kafka.devservices.topic-partitions.notification-events=1

quarkus.redis.devservices.enabled=true
quarkus.redis.devservices.port=6379
quarkus.redis.devservices.image-name=redis:7

quarkus.mongodb.devservices.enabled=true
quarkus.mongodb.devservices.port=27017
quarkus.mongodb.devservices.image-name=mongo:7

# 自動啟動 Keycloak 容器
quarkus.oidc.devservices.enabled=true
quarkus.oidc.devservices.realm-path=dev-realm.json
quarkus.oidc.devservices.port=8180

# Dev Services 會自動建立測試使用者
# alice / alice (roles: admin, user)
# bob / bob (roles: user)

# .devservices/docker-compose.yaml
services:
  postgres:
    image: postgres:16
    environment:
      POSTGRES_DB: devdb
      POSTGRES_USER: dev
      POSTGRES_PASSWORD: dev
    ports:
      - "5432:5432"
  redis:
    image: redis:7
    ports:
      - "6379:6379"
  mailpit:
    image: axllent/mailpit
    ports:
      - "1025:1025"
      - "8025:8025"

# 啟用 Dev MCP Server
quarkus.dev-mcp.enabled=true

# 全域日誌等級
quarkus.log.level=INFO

# 套件級日誌
quarkus.log.category."com.example".level=DEBUG
quarkus.log.category."org.hibernate.SQL".level=DEBUG

# 控制台格式
quarkus.log.console.format=%d{yyyy-MM-dd HH:mm:ss,SSS} %-5p [%c{3.}] (%t) %s%e%n

# JSON 結構化日誌（推薦生產環境）
quarkus.log.console.json=true
quarkus.log.console.json.additional-field."service".value=order-service
quarkus.log.console.json.additional-field."environment".value=${ENVIRONMENT:dev}

# 檔案日誌（搭配 Fluentd / Filebeat 收集）
quarkus.log.file.enable=true
quarkus.log.file.path=/var/log/app/application.log
quarkus.log.file.rotation.max-file-size=10M
quarkus.log.file.rotation.max-backup-index=5
quarkus.log.file.json=true

Application (JSON Log)
    → Fluentd / Filebeat / Vector
    → Elasticsearch / OpenSearch
    → Kibana / Grafana

quarkus extension add quarkus-smallrye-health

@Liveness
@ApplicationScoped
public class AppLivenessCheck implements HealthCheck {

    @Override
    public HealthCheckResponse call() {
        return HealthCheckResponse.up("Application is alive");
    }
}

@Readiness
@ApplicationScoped
public class DatabaseReadinessCheck implements HealthCheck {

    @Inject
    AgroalDataSource dataSource;

    @Override
    public HealthCheckResponse call() {
        try (Connection conn = dataSource.getConnection()) {
            conn.createStatement().execute("SELECT 1");
            return HealthCheckResponse.up("Database connection OK");
        } catch (Exception e) {
            return HealthCheckResponse.down("Database connection failed: " + e.getMessage());
        }
    }
}

@Startup
@ApplicationScoped
public class WarmupCheck implements HealthCheck {

    @Override
    public HealthCheckResponse call() {
        return HealthCheckResponse.up("Application warmed up");
    }
}

quarkus extension add quarkus-micrometer-registry-prometheus

@ApplicationScoped
public class OrderMetrics {

    @Inject
    MeterRegistry registry;

    private final AtomicLong activeOrders = new AtomicLong(0);

    @PostConstruct
    void init() {
        registry.gauge("orders.active", activeOrders);
    }

    public void orderCreated() {
        registry.counter("orders.created.total").increment();
        activeOrders.incrementAndGet();
    }

    public void orderCompleted(long processingTimeMs) {
        registry.counter("orders.completed.total").increment();
        activeOrders.decrementAndGet();
        registry.timer("orders.processing.time")
                .record(Duration.ofMillis(processingTimeMs));
    }
}

# Micrometer 設定
quarkus.micrometer.export.prometheus.enabled=true
quarkus.micrometer.binder.http-server.enabled=true
quarkus.micrometer.binder.jvm=true
quarkus.micrometer.binder.system=true

quarkus extension add quarkus-opentelemetry

# OpenTelemetry 設定
quarkus.otel.exporter.otlp.endpoint=http://otel-collector:4317
quarkus.otel.exporter.otlp.protocol=grpc
quarkus.otel.service.name=order-service
quarkus.otel.resource.attributes=deployment.environment=production

# 取樣率
quarkus.otel.traces.sampler=parentbased_traceidratio
quarkus.otel.traces.sampler.arg=0.1

@ApplicationScoped
public class OrderService {

    @Inject
    Tracer tracer;

    public Order processOrder(Long orderId) {
        Span span = tracer.spanBuilder("processOrder")
                .setAttribute("order.id", orderId)
                .startSpan();

        try (Scope scope = span.makeCurrent()) {
            Order order = findOrder(orderId);
            validateOrder(order);
            completeOrder(order);
            span.setAttribute("order.status", order.status.name());
            return order;
        } catch (Exception e) {
            span.setStatus(StatusCode.ERROR, e.getMessage());
            span.recordException(e);
            throw e;
        } finally {
            span.end();
        }
    }
}

// 計數器
@Counted(value = "api.requests", description = "API request count")
@Timed(value = "api.request.duration", description = "API request duration")
@GET
@Path("/products")
public List<ProductDTO> listProducts() {
    return productService.listAll();
}

# 追蹤設定
quarkus.otel.traces.enabled=true
quarkus.otel.logs.enabled=true
quarkus.otel.metrics.enabled=true

# 將管理端點與業務端點隔離
quarkus.management.enabled=true
quarkus.management.port=9000

# 管理端點（Health、Metrics）透過 port 9000 存取
# 業務 API 透過 port 8080 存取

# prometheus.yml
scrape_configs:
  - job_name: 'quarkus-app'
    scrape_interval: 15s
    metrics_path: '/q/metrics'
    static_configs:
      - targets: ['app:9000']
    # 如果使用管理介面
    # 注意 port 改為管理介面的 port

# Extension: quarkus-container-image-docker
quarkus extension add quarkus-container-image-docker

# 或使用 Jib（無需 Docker daemon）
quarkus extension add quarkus-container-image-jib

# Container Image 設定
quarkus.container-image.build=true
quarkus.container-image.group=my-registry.example.com/my-team
quarkus.container-image.name=order-service
quarkus.container-image.tag=${quarkus.application.version}
quarkus.container-image.push=true
quarkus.container-image.registry=my-registry.example.com

FROM registry.access.redhat.com/ubi8/openjdk-21:1.20

ENV LANGUAGE='en_US:en'

COPY --chown=185 target/quarkus-app/lib/ /deployments/lib/
COPY --chown=185 target/quarkus-app/*.jar /deployments/
COPY --chown=185 target/quarkus-app/app/ /deployments/app/
COPY --chown=185 target/quarkus-app/quarkus/ /deployments/quarkus/

EXPOSE 8080
USER 185
ENV JAVA_OPTS_APPEND="-Dquarkus.http.host=0.0.0.0 -Djava.util.logging.manager=org.jboss.logmanager.LogManager"
ENV JAVA_APP_JAR="/deployments/quarkus-run.jar"

ENTRYPOINT [ "/opt/jboss/container/java/run/run-java.sh" ]

FROM quay.io/quarkus/quarkus-micro-image:2.0

WORKDIR /work/
RUN chown 1001 /work \
    && chmod "g+rwX" /work \
    && chown 1001:root /work
COPY --chown=1001:root target/*-runner /work/application

EXPOSE 8080
USER 1001

ENTRYPOINT ["./application", "-Dquarkus.http.host=0.0.0.0"]

# JVM 映像
./mvnw package
docker build -f src/main/docker/Dockerfile.jvm -t my-app:jvm .

# Native 映像（使用容器建置，無需本機 GraalVM）
./mvnw package -Pnative -Dquarkus.native.container-build=true
docker build -f src/main/docker/Dockerfile.native-micro -t my-app:native .

quarkus extension add quarkus-kubernetes

# application.properties — Kubernetes 設定
quarkus.kubernetes.deploy=false
quarkus.kubernetes.namespace=my-namespace
quarkus.kubernetes.replicas=3

# 資源限制
quarkus.kubernetes.resources.requests.cpu=250m
quarkus.kubernetes.resources.requests.memory=256Mi
quarkus.kubernetes.resources.limits.cpu=1000m
quarkus.kubernetes.resources.limits.memory=512Mi

# Service 類型
quarkus.kubernetes.service-type=ClusterIP

# Labels
quarkus.kubernetes.labels."app.kubernetes.io/part-of"=order-system
quarkus.kubernetes.labels."app.kubernetes.io/managed-by"=quarkus

# 環境變數
quarkus.kubernetes.env.vars.ENVIRONMENT=production
quarkus.kubernetes.env.mapping.DB_PASSWORD.from-secret=db-credentials
quarkus.kubernetes.env.mapping.DB_PASSWORD.with-key=password

./mvnw package
# 生成 target/kubernetes/kubernetes.yml

quarkus extension add quarkus-openshift

quarkus.openshift.deploy=true
quarkus.openshift.route.expose=true
quarkus.openshift.route.tls.termination=edge

# 使用 oc CLI 部署
oc login https://api.cluster.example.com
./mvnw package -Dquarkus.openshift.deploy=true

# 從 ConfigMap 讀取配置
quarkus.kubernetes-config.config-maps=order-service-config
quarkus.kubernetes-config.enabled=true

# 從 Secret 讀取敏感配置
quarkus.kubernetes-config.secrets.enabled=true
quarkus.kubernetes-config.secrets=order-service-secrets

# configmap.yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: order-service-config
data:
  application.properties: |
    quarkus.http.port=8080
    app.order.max-items=100
    app.order.default-currency=TWD

# secret.yaml
apiVersion: v1
kind: Secret
metadata:
  name: order-service-secrets
type: Opaque
stringData:
  quarkus.datasource.password: "my-secure-password"
  quarkus.oidc.credentials.secret: "my-oidc-secret"

# Kubernetes Health Probe 自動配置
quarkus.kubernetes.liveness-probe.http-action-path=/q/health/live
quarkus.kubernetes.liveness-probe.initial-delay=5s
quarkus.kubernetes.liveness-probe.period=10s

quarkus.kubernetes.readiness-probe.http-action-path=/q/health/ready
quarkus.kubernetes.readiness-probe.initial-delay=10s
quarkus.kubernetes.readiness-probe.period=10s

quarkus.kubernetes.startup-probe.http-action-path=/q/health/started
quarkus.kubernetes.startup-probe.initial-delay=0s
quarkus.kubernetes.startup-probe.period=5s
quarkus.kubernetes.startup-probe.failure-threshold=10

# Rolling Update 策略
quarkus.kubernetes.rolling-update.max-unavailable=25%
quarkus.kubernetes.rolling-update.max-surge=25%

# HPA — Horizontal Pod Autoscaler
apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: order-service-hpa
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: order-service
  minReplicas: 2
  maxReplicas: 10
  metrics:
    - type: Resource
      resource:
        name: cpu
        target:
          type: Utilization
          averageUtilization: 70
    - type: Resource
      resource:
        name: memory
        target:
          type: Utilization
          averageUtilization: 80

# 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 package -DskipTests -B

# Stage 2: Runtime
FROM registry.access.redhat.com/ubi8/openjdk-21-runtime:1.20
COPY --from=build --chown=185 /app/target/quarkus-app/ /deployments/
EXPOSE 8080
USER 185
ENTRYPOINT ["java", "-jar", "/deployments/quarkus-run.jar"]

apiVersion: apps/v1
kind: Deployment
metadata:
  name: order-service
  labels:
    app: order-service
spec:
  replicas: 3
  selector:
    matchLabels:
      app: order-service
  template:
    metadata:
      labels:
        app: order-service
    spec:
      containers:
        - name: order-service
          image: registry.example.com/order-service:1.0.0
          ports:
            - containerPort: 8080
              name: http
            - containerPort: 9000
              name: management
          env:
            - name: JAVA_OPTS_APPEND
              value: "-XX:MaxRAMPercentage=75.0"
          envFrom:
            - configMapRef:
                name: order-service-config
            - secretRef:
                name: order-service-secrets
          resources:
            requests:
              cpu: 250m
              memory: 256Mi
            limits:
              cpu: 1000m
              memory: 512Mi
          livenessProbe:
            httpGet:
              path: /q/health/live
              port: management
            initialDelaySeconds: 5
            periodSeconds: 10
          readinessProbe:
            httpGet:
              path: /q/health/ready
              port: management
            initialDelaySeconds: 10
            periodSeconds: 10
          startupProbe:
            httpGet:
              path: /q/health/started
              port: management
            periodSeconds: 5
            failureThreshold: 12
---
apiVersion: v1
kind: Service
metadata:
  name: order-service
spec:
  selector:
    app: order-service
  ports:
    - name: http
      port: 80
      targetPort: 8080
    - name: management
      port: 9000
      targetPort: 9000

# 安裝 Mandrel（推薦用於 Quarkus）
sdk install java 23.1.4.r21-mandrel

# 或使用容器建置（無需本機安裝）
./mvnw package -Pnative -Dquarkus.native.container-build=true

# 方式一：本機建置（需安裝 GraalVM/Mandrel）
export GRAALVM_HOME=/path/to/graalvm
./mvnw package -Pnative

# 方式二：容器建置（推薦，無需本機安裝）
./mvnw package -Pnative -Dquarkus.native.container-build=true

# 方式三：直接建置容器映像
./mvnw package -Pnative \
    -Dquarkus.native.container-build=true \
    -Dquarkus.container-image.build=true

# 啟用 AOT Caching
quarkus.class-loading.aot-cache.enabled=true

# 啟動時間量測
quarkus.log.category."io.quarkus".level=INFO
# 啟動日誌會包含啟動時間

# 使用 wrk 進行 HTTP 效能測試
wrk -t12 -c400 -d30s http://localhost:8080/api/v1/products

# 使用 hey 進行 HTTP 效能測試
hey -n 10000 -c 100 http://localhost:8080/api/v1/products

# 啟用 JFR（JVM Flight Recorder）
quarkus.jfr.enabled=true

# 手動啟動 JFR
java -XX:StartFlightRecording=filename=recording.jfr,duration=60s \
     -jar target/quarkus-app/quarkus-run.jar

# 分析 JFR 記錄
jfr print --events jdk.CPULoad recording.jfr

# JVM 記憶體調校
quarkus.native.additional-build-args=\
    -H:+PrintAnalysisCallTree,\
    --initialize-at-build-time=org.example.MyClass

# 容器記憶體設定
JAVA_OPTS_APPEND="-XX:MaxRAMPercentage=75.0 -XX:+UseG1GC -XX:MaxGCPauseMillis=200"

// 需要反射的類別
@RegisterForReflection
public record OrderEvent(Long orderId, String type, String customerId, Instant timestamp) {}

// 需要序列化的類別
@RegisterForReflection(serialization = true)
public class LegacyDTO implements Serializable {
    // ...
}

# 完整建置流程
./mvnw clean verify

# 跳過測試（僅用於快速驗證編譯）
./mvnw clean package -DskipTests

# 含品質檢查的建置
./mvnw clean verify -Pquality-checks

# Native 建置
./mvnw clean package -Pnative -Dquarkus.native.container-build=true

# 產生 Maven Wrapper
mvn wrapper:wrapper -Dmaven=3.9.9

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

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

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

jobs:
  build-and-test:
    runs-on: ubuntu-latest
    services:
      postgres:
        image: postgres:16
        env:
          POSTGRES_DB: testdb
          POSTGRES_USER: test
          POSTGRES_PASSWORD: test
        ports:
          - 5432:5432
        options: >-
          --health-cmd pg_isready
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5

    steps:
      - uses: actions/checkout@v4

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

      - name: Build and Test
        run: ./mvnw clean verify -B
        env:
          QUARKUS_DATASOURCE_JDBC_URL: jdbc:postgresql://localhost:5432/testdb
          QUARKUS_DATASOURCE_USERNAME: test
          QUARKUS_DATASOURCE_PASSWORD: test

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

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

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

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

      - name: OWASP Dependency Check
        run: ./mvnw org.owasp:dependency-check-maven:check -B

      - name: Generate SBOM
        run: ./mvnw org.cyclonedx:cyclonedx-maven-plugin:makeAggregateBom -B

      - name: Upload SBOM
        uses: actions/upload-artifact@v4
        with:
          name: sbom
          path: target/bom.json

  build-image:
    runs-on: ubuntu-latest
    needs: [build-and-test, security-scan]
    if: github.ref == 'refs/heads/main'
    permissions:
      contents: read
      packages: write

    steps:
      - uses: actions/checkout@v4

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

      - name: Build Application
        run: ./mvnw 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 Image
        uses: docker/build-push-action@v6
        with:
          context: .
          file: src/main/docker/Dockerfile.jvm
          push: true
          tags: |
            ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ github.sha }}
            ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:latest

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

# 在 CI 中分層測試
- name: Unit Tests
  run: ./mvnw test -pl :order-service -B

- name: Integration Tests
  run: ./mvnw verify -pl :order-service -Pit -B

- name: Native Tests (optional, on schedule)
  run: ./mvnw verify -Pnative -B

<!-- pom.xml — OWASP Dependency Check -->
<plugin>
    <groupId>org.owasp</groupId>
    <artifactId>dependency-check-maven</artifactId>
    <version>10.0.4</version>
    <configuration>
        <failBuildOnCVSS>7</failBuildOnCVSS>
        <suppressionFiles>
            <suppressionFile>owasp-suppressions.xml</suppressionFile>
        </suppressionFiles>
    </configuration>
</plugin>

# 使用 Quarkus CLI 檢查可更新的依賴
quarkus update --dry-run

# Maven Versions Plugin
./mvnw versions:display-dependency-updates
./mvnw versions:display-plugin-updates

<!-- pom.xml -->
<plugin>
    <groupId>org.cyclonedx</groupId>
    <artifactId>cyclonedx-maven-plugin</artifactId>
    <version>2.9.1</version>
    <executions>
        <execution>
            <phase>package</phase>
            <goals>
                <goal>makeAggregateBom</goal>
            </goals>
        </execution>
    </executions>
    <configuration>
        <projectType>application</projectType>
        <schemaVersion>1.6</schemaVersion>
        <outputFormat>json</outputFormat>
        <outputName>sbom</outputName>
    </configuration>
</plugin>

# Trivy 容器掃描
- name: Container Scan
  uses: aquasecurity/trivy-action@master
  with:
    image-ref: my-registry/my-app:latest
    severity: 'CRITICAL,HIGH'
    exit-code: '1'

# GitLeaks Secret 掃描
- name: Secret Scan
  uses: gitleaks/gitleaks-action@v2
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

# 自訂 Profile
%staging.quarkus.datasource.jdbc.url=jdbc:postgresql://staging-db:5432/app
%staging.quarkus.log.level=INFO

# Kubernetes Rolling Back
kubectl rollout undo deployment/order-service -n production

# 回滾到特定版本
kubectl rollout undo deployment/order-service --to-revision=3

# 查看部署歷史
kubectl rollout history deployment/order-service

# blue-deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: order-service-blue
  labels:
    app: order-service
    version: blue
spec:
  replicas: 3
  # ...

# green-deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: order-service-green
  labels:
    app: order-service
    version: green
spec:
  replicas: 3
  # ...

# 切換 Service 指向
# service.yaml
apiVersion: v1
kind: Service
metadata:
  name: order-service
spec:
  selector:
    app: order-service
    version: green  # 切換至 green

# 使用 Kubernetes 原生方式
# 90% 流量到穩定版，10% 到 Canary
apiVersion: apps/v1
kind: Deployment
metadata:
  name: order-service-stable
spec:
  replicas: 9  # 90%
  # ...

apiVersion: apps/v1
kind: Deployment
metadata:
  name: order-service-canary
spec:
  replicas: 1  # 10%
  # ...

1. 收到告警
   → 檢查 Metrics Dashboard（Grafana）
   → 確認影響指標（錯誤率、延遲、吞吐量）

2. 定位問題
   → 檢查 Traces（Jaeger/Tempo）找出慢請求
   → 追蹤特定 TraceID 的完整呼叫鏈

3. 深入分析
   → 檢查 Logs（Kibana/Grafana Loki）
   → 篩選特定時間段、服務、錯誤等級
   → 關聯 TraceID 找到相關日誌

4. 修復與驗證
   → 實施修復
   → 確認 Metrics 恢復正常
   → 撰寫 Post-Mortem

## Service: Order Service
### 服務概述
- 負責訂單建立、查詢、狀態更新
- 依賴：PostgreSQL、Kafka、Keycloak

### 常見告警與處置
#### 告警：API 錯誤率 > 1%
1. 檢查 Grafana Dashboard → Order Service Panel
2. 查看近 10 分鐘日誌：kubectl logs -l app=order-service --tail=100
3. 檢查下游服務狀態（DB、Kafka）
4. 若 DB 異常：檢查連線池使用率
5. 若持續升高：考慮回滾最近部署

#### 告警：記憶體使用率 > 85%
1. 檢查 JVM Heap 使用率
2. 檢查是否有記憶體洩漏（Heap Dump）
3. 短期：增加 Pod 數量
4. 長期：分析記憶體使用模式

### 重要指令
- 查看 Pod 狀態：kubectl get pods -l app=order-service
- 查看日誌：kubectl logs -f deployment/order-service
- 手動擴展：kubectl scale deployment/order-service --replicas=5
- 回滾：kubectl rollout undo deployment/order-service

# 方式一：使用 Quarkus CLI（推薦）
quarkus update

# 方式二：使用 Maven Plugin
./mvnw quarkus:update

# 乾跑模式（僅顯示變更，不實際修改）
quarkus update --dry-run

# 使用 Quarkus BOM 統一管理版本
<quarkus.platform.version>3.35.3</quarkus.platform.version>

# Extension 版本由 BOM 統一管理，無需個別指定版本
<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-rest</artifactId>
    <!-- 版本由 BOM 管理 -->
</dependency>

<!-- 步驟一：替換 Extension -->
<!-- 舊版 -->
<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-resteasy</artifactId>
</dependency>
<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-resteasy-jackson</artifactId>
</dependency>

<!-- 新版 -->
<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-rest</artifactId>
</dependency>
<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-rest-jackson</artifactId>
</dependency>

// 大部分 JAX-RS 程式碼無需變更
// 但以下情況需注意：

// 1. 自訂 Filter / Interceptor
// 舊版：使用 JAX-RS ContainerRequestFilter
// 新版：使用 @ServerRequestFilter（更簡潔）
@ServerRequestFilter
public void filter(ContainerRequestContext context) {
    // ...
}

// 2. Exception Mapper
// 舊版：@Provider + ExceptionMapper<T>
// 新版：@ServerExceptionMapper（更簡潔）
@ServerExceptionMapper
public Response handleNotFound(NotFoundException e) {
    return Response.status(404).build();
}

Phase 1: 使用 Spring 相容層快速遷移
         → quarkus-spring-web
         → quarkus-spring-di
         → quarkus-spring-data-jpa

Phase 2: 逐步替換為 Quarkus 原生 API
         → @RestController → @Path
         → @Autowired → @Inject
         → Spring Data → Panache

Phase 3: 完全移除 Spring 相容層
         → 移除 quarkus-spring-* Extension

Phase 1: 分析現有系統
    → 識別領域邊界（DDD Bounded Context）
    → 分析模組間耦合度
    → 識別資料庫相依性

Phase 2: 模組化重構（仍在單體內）
    → 建立清晰的模組介面
    → 消除模組間的直接資料庫存取
    → 引入事件驅動（Application Events）

Phase 3: 抽取微服務
    → 從耦合度最低的模組開始
    → 使用 Strangler Fig Pattern
    → 建立 API Gateway / BFF

Phase 4: 完成遷移
    → 監控與調優
    → 移除舊系統中已遷移的模組
    → 建立統一的可觀測性

月 1-2: PoC + 團隊培訓
月 3-4: 第一個非核心服務上線
月 5-6: 2-3 個服務完成遷移
月 7-8: 核心服務開始遷移
月 9-12: 完成主要服務遷移，建立標準化流程

order-service/
├── pom.xml
├── src/
│   ├── main/
│   │   ├── java/com/example/order/
│   │   │   ├── OrderApplication.java          # (可選) 自訂啟動邏輯
│   │   │   ├── domain/                         # 領域層
│   │   │   │   ├── model/                      # Entity / Value Object
│   │   │   │   │   ├── Order.java
│   │   │   │   │   ├── OrderItem.java
│   │   │   │   │   └── OrderStatus.java
│   │   │   │   ├── service/                    # 領域服務
│   │   │   │   │   └── OrderDomainService.java
│   │   │   │   └── event/                      # 領域事件
│   │   │   │       └── OrderCreatedEvent.java
│   │   │   ├── application/                    # 應用層
│   │   │   │   ├── OrderService.java           # Use Case
│   │   │   │   ├── dto/                        # DTO
│   │   │   │   │   ├── CreateOrderRequest.java
│   │   │   │   │   └── OrderResponse.java
│   │   │   │   └── mapper/                     # 物件映射
│   │   │   │       └── OrderMapper.java
│   │   │   ├── infrastructure/                 # 基礎設施層
│   │   │   │   ├── persistence/                # 資料存取
│   │   │   │   │   └── OrderRepository.java
│   │   │   │   ├── messaging/                  # 訊息傳遞
│   │   │   │   │   └── OrderEventPublisher.java
│   │   │   │   └── external/                   # 外部服務
│   │   │   │       └── PaymentClient.java
│   │   │   └── web/                            # 表現層
│   │   │       ├── OrderResource.java          # REST 端點
│   │   │       └── OrderExceptionMapper.java   # 例外處理
│   │   └── resources/
│   │       ├── application.properties
│   │       ├── db/migration/                   # Flyway Migration
│   │       └── META-INF/resources/             # 靜態資源
│   └── test/
│       └── java/com/example/order/
│           ├── domain/
│           ├── application/
│           ├── infrastructure/
│           └── web/
└── src/main/docker/
    ├── Dockerfile.jvm
    └── Dockerfile.native-micro

// Input Port（由應用層定義）
public interface CreateOrderUseCase {
    OrderResponse createOrder(CreateOrderRequest request);
}

// Output Port（由領域層定義）
public interface OrderRepositoryPort {
    Order save(Order order);
    Optional<Order> findById(Long id);
}

public interface OrderEventPort {
    void publishOrderCreated(OrderCreatedEvent event);
}

// Adapter（由基礎設施層實作）
@ApplicationScoped
public class OrderPanacheRepository implements OrderRepositoryPort {
    @Override
    public Order save(Order order) {
        order.persist();
        return order;
    }

    @Override
    public Optional<Order> findById(Long id) {
        return Order.findByIdOptional(id);
    }
}

application.properties          ← 共用預設值
application-dev.properties      ← %dev Profile（Dev Services）
application-test.properties     ← %test Profile（Testcontainers）
application-staging.properties  ← %staging Profile（自訂）
application-prod.properties     ← %prod Profile（最小化，敏感值從外部注入）

# 生產環境敏感值從環境變數注入
quarkus.datasource.password=${DB_PASSWORD}
quarkus.oidc.credentials.secret=${OIDC_SECRET}

# 或從 Kubernetes Secret
quarkus.kubernetes-config.secrets.enabled=true
quarkus.kubernetes-config.secrets=order-service-secrets

quarkus create app com.example:order-service \
    --extension='rest,rest-jackson,hibernate-orm-panache,jdbc-postgresql,flyway,oidc,smallrye-health,micrometer-registry-prometheus,opentelemetry' \
    --java=21

@Entity
@Table(name = "orders")
public class Order extends PanacheEntity {

    @Column(name = "order_number", unique = true, nullable = false)
    public String orderNumber;

    @Column(name = "customer_id", nullable = false)
    public String customerId;

    @Enumerated(EnumType.STRING)
    @Column(nullable = false)
    public OrderStatus status = OrderStatus.PENDING;

    @Column(name = "total_amount", precision = 10, scale = 2)
    public BigDecimal totalAmount;

    @Column(name = "created_at")
    public Instant createdAt;

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

    @OneToMany(mappedBy = "order", cascade = CascadeType.ALL, orphanRemoval = true)
    public List<OrderItem> items = new ArrayList<>();

    @PrePersist
    void prePersist() {
        createdAt = Instant.now();
        updatedAt = createdAt;
        orderNumber = "ORD-" + UUID.randomUUID().toString().substring(0, 8).toUpperCase();
    }

    @PreUpdate
    void preUpdate() {
        updatedAt = Instant.now();
    }

    // Panache 自訂查詢
    public static List<Order> findByCustomer(String customerId) {
        return list("customerId", customerId);
    }

    public static List<Order> findByStatus(OrderStatus status) {
        return list("status", status);
    }
}

@ApplicationScoped
public class OrderService {

    @Inject
    OrderMapper mapper;

    @Transactional
    public OrderResponse createOrder(CreateOrderRequest request) {
        Order order = mapper.toEntity(request);
        order.totalAmount = order.items.stream()
                .map(item -> item.unitPrice.multiply(BigDecimal.valueOf(item.quantity)))
                .reduce(BigDecimal.ZERO, BigDecimal::add);
        order.persist();
        return mapper.toResponse(order);
    }

    public OrderResponse getOrder(Long id) {
        Order order = Order.findByIdOptional(id)
                .orElseThrow(() -> new NotFoundException("Order not found: " + id));
        return mapper.toResponse(order);
    }

    public List<OrderResponse> getOrdersByCustomer(String customerId) {
        return Order.findByCustomer(customerId).stream()
                .map(mapper::toResponse)
                .toList();
    }

    @Transactional
    public OrderResponse cancelOrder(Long id) {
        Order order = Order.findByIdOptional(id)
                .orElseThrow(() -> new NotFoundException("Order not found: " + id));
        if (order.status != OrderStatus.PENDING) {
            throw new IllegalStateException("Only PENDING orders can be cancelled");
        }
        order.status = OrderStatus.CANCELLED;
        return mapper.toResponse(order);
    }
}

@Path("/api/v1/orders")
@Produces(MediaType.APPLICATION_JSON)
@Consumes(MediaType.APPLICATION_JSON)
@RolesAllowed("user")
public class OrderResource {

    @Inject
    OrderService orderService;

    @POST
    public Response createOrder(@Valid CreateOrderRequest request) {
        OrderResponse response = orderService.createOrder(request);
        return Response.status(Response.Status.CREATED)
                .entity(response)
                .build();
    }

    @GET
    @Path("/{id}")
    public OrderResponse getOrder(@PathParam("id") Long id) {
        return orderService.getOrder(id);
    }

    @GET
    @Path("/customer/{customerId}")
    public List<OrderResponse> getOrdersByCustomer(
            @PathParam("customerId") String customerId) {
        return orderService.getOrdersByCustomer(customerId);
    }

    @PUT
    @Path("/{id}/cancel")
    public OrderResponse cancelOrder(@PathParam("id") Long id) {
        return orderService.cancelOrder(id);
    }
}

-- src/main/resources/db/migration/V1__create_orders.sql
CREATE TABLE orders (
    id          BIGSERIAL PRIMARY KEY,
    order_number VARCHAR(20) UNIQUE NOT NULL,
    customer_id  VARCHAR(50) NOT NULL,
    status       VARCHAR(20) NOT NULL DEFAULT 'PENDING',
    total_amount DECIMAL(10,2),
    created_at   TIMESTAMP WITH TIME ZONE,
    updated_at   TIMESTAMP WITH TIME ZONE
);

CREATE TABLE order_items (
    id          BIGSERIAL PRIMARY KEY,
    order_id    BIGINT REFERENCES orders(id),
    product_id  VARCHAR(50) NOT NULL,
    product_name VARCHAR(200),
    quantity    INT NOT NULL,
    unit_price  DECIMAL(10,2) NOT NULL
);

CREATE INDEX idx_orders_customer_id ON orders(customer_id);
CREATE INDEX idx_orders_status ON orders(status);

// 事件消費者
@ApplicationScoped
public class OrderEventConsumer {

    @Inject
    NotificationService notificationService;

    @Incoming("order-events")
    public CompletionStage<Void> processOrderEvent(Message<OrderEvent> message) {
        OrderEvent event = message.getPayload();

        return switch (event.type()) {
            case "ORDER_CREATED" -> notificationService
                    .sendOrderConfirmation(event)
                    .subscribeAsCompletionStage()
                    .thenCompose(v -> message.ack());
            case "ORDER_SHIPPED" -> notificationService
                    .sendShippingNotification(event)
                    .subscribeAsCompletionStage()
                    .thenCompose(v -> message.ack());
            case "ORDER_CANCELLED" -> notificationService
                    .sendCancellationNotification(event)
                    .subscribeAsCompletionStage()
                    .thenCompose(v -> message.ack());
            default -> {
                Log.warnf("Unknown event type: %s", event.type());
                yield message.ack();
            }
        };
    }
}

// 通知服務
@ApplicationScoped
public class NotificationService {

    @Inject
    Mailer mailer;

    @Inject
    NotificationRepository notificationRepo;

    public Uni<Void> sendOrderConfirmation(OrderEvent event) {
        return Uni.createFrom().item(event)
                .onItem().invoke(e -> {
                    Mail mail = Mail.withText(
                            e.customerEmail(),
                            "訂單確認 - " + e.orderNumber(),
                            String.format("您的訂單 %s 已成立，金額：%s",
                                    e.orderNumber(), e.totalAmount())
                    );
                    mailer.send(mail);
                })
                .onItem().invoke(e -> {
                    NotificationRecord record = new NotificationRecord();
                    record.orderId = e.orderId();
                    record.type = "ORDER_CONFIRMATION";
                    record.channel = "EMAIL";
                    record.sentAt = Instant.now();
                    record.persist();
                })
                .replaceWithVoid();
    }
}

# application.properties
mp.messaging.incoming.order-events.connector=smallrye-kafka
mp.messaging.incoming.order-events.topic=order-events
mp.messaging.incoming.order-events.group.id=notification-service
mp.messaging.incoming.order-events.value.deserializer=io.quarkus.kafka.client.serialization.ObjectMapperDeserializer
mp.messaging.incoming.order-events.failure-strategy=dead-letter-queue

quarkus.mailer.from=noreply@example.com
quarkus.mailer.host=smtp.example.com
quarkus.mailer.port=587
quarkus.mailer.start-tls=REQUIRED
quarkus.mailer.username=${SMTP_USERNAME}
quarkus.mailer.password=${SMTP_PASSWORD}

@Path("/api/v1/tenants")
@Authenticated
@Produces(MediaType.APPLICATION_JSON)
public class TenantResource {

    @Inject
    JsonWebToken jwt;

    @Inject
    SecurityIdentity identity;

    @Inject
    TenantService tenantService;

    @GET
    @Path("/profile")
    public TenantProfile getProfile() {
        String tenantId = jwt.getClaim("tenant_id");
        String email = jwt.getClaim("email");
        Set<String> roles = identity.getRoles();

        return new TenantProfile(tenantId, email, roles);
    }

    @GET
    @Path("/data")
    @RolesAllowed("tenant-admin")
    public List<TenantData> getTenantData() {
        String tenantId = jwt.getClaim("tenant_id");
        return tenantService.getDataByTenant(tenantId);
    }

    @POST
    @Path("/data")
    @RolesAllowed("tenant-admin")
    @Consumes(MediaType.APPLICATION_JSON)
    public Response createData(@Valid TenantDataRequest request) {
        String tenantId = jwt.getClaim("tenant_id");
        TenantData data = tenantService.createData(tenantId, request);
        return Response.status(Response.Status.CREATED).entity(data).build();
    }
}

@ApplicationScoped
public class TenantSecurityFilter {

    @Inject
    JsonWebToken jwt;

    @ServerRequestFilter(priority = Priorities.AUTHORIZATION + 1)
    public void enforceTenantIsolation(ContainerRequestContext context) {
        String tenantId = jwt.getClaim("tenant_id");
        if (tenantId == null || tenantId.isBlank()) {
            context.abortWith(
                Response.status(Response.Status.FORBIDDEN)
                    .entity(Map.of("error", "Missing tenant_id claim"))
                    .build()
            );
            return;
        }
        // 將 tenantId 放入 Request Context 供下游使用
        context.setProperty("tenantId", tenantId);
    }
}

# OIDC 設定
quarkus.oidc.auth-server-url=https://keycloak.example.com/realms/my-realm
quarkus.oidc.client-id=my-api
quarkus.oidc.credentials.secret=${OIDC_SECRET}
quarkus.oidc.token.issuer=https://keycloak.example.com/realms/my-realm

# 多租戶設定
quarkus.oidc.token.customizer-name=tenant-token-customizer

@Singleton
public class JacksonConfig implements ObjectMapperCustomizer {
    @Override
    public void customize(ObjectMapper objectMapper) {
        objectMapper.configure(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS, false);
        objectMapper.setSerializationInclusion(JsonInclude.Include.NON_NULL);
    }
}

quarkus.http.cors=true
quarkus.http.cors.origins=https://frontend.example.com
quarkus.http.cors.methods=GET,POST,PUT,DELETE
quarkus.http.cors.headers=Content-Type,Authorization

@GET
public PaginatedResponse<OrderResponse> list(
        @QueryParam("page") @DefaultValue("0") int page,
        @QueryParam("size") @DefaultValue("20") int size) {
    PanacheQuery<Order> query = Order.findAll();
    query.page(Page.of(page, size));
    List<OrderResponse> items = query.list().stream()
            .map(mapper::toResponse).toList();
    return new PaginatedResponse<>(items, query.count(), page, size);
}

# 檢查 Port 佔用（Windows）
netstat -ano | findstr :8080

# 檢查 Port 佔用（Linux/Mac）
lsof -i :8080

# 更換 Port
quarkus.http.port=8081

# 檢查 Extension 相容性
quarkus extension list

# 常見衝突：
# - quarkus-resteasy 與 quarkus-rest 不可並存
# - quarkus-hibernate-reactive 與 quarkus-hibernate-orm 需注意共存配置

# 詳細 Native 建置日誌
./mvnw package -Pnative -Dquarkus.native.additional-build-args="--verbose"

# OIDC 除錯日誌
quarkus.log.category."io.quarkus.oidc".level=DEBUG

# DB 除錯日誌
quarkus.log.category."org.hibernate.SQL".level=DEBUG
quarkus.log.category."org.hibernate.type.descriptor.sql".level=TRACE
quarkus.datasource.jdbc.detect-statement-leaks=true

# 建議的 Probe 設定（JVM 模式）
startupProbe:
  httpGet:
    path: /q/health/started
    port: 9000
  periodSeconds: 5
  failureThreshold: 12     # 最多等 60 秒
livenessProbe:
  httpGet:
    path: /q/health/live
    port: 9000
  initialDelaySeconds: 5
  periodSeconds: 10
readinessProbe:
  httpGet:
    path: /q/health/ready
    port: 9000
  initialDelaySeconds: 10
  periodSeconds: 10

1. 確認問題類型
   → 高延遲？高 CPU？高記憶體？

2. 檢查 Metrics
   → Grafana Dashboard
   → /q/metrics 端點

3. 分析 Traces
   → 找出慢的 Span
   → 確認瓶頸位置

4. 常見瓶頸
   → 資料庫查詢（開啟 SQL 日誌）
   → 外部 API 呼叫（設定 timeout）
   → 連線池不足（調整 pool size）
   → GC 壓力（分析 GC 日誌）

5. 工具
   → JFR（JVM Flight Recorder）
   → async-profiler
   → wrk / hey（HTTP 壓測）

# 取得 Heap Dump
jcmd <pid> GC.heap_dump /tmp/heap.hprof

# 分析工具
# - Eclipse MAT (Memory Analyzer Tool)
# - VisualVM
# - IntelliJ Profiler

# 常見記憶體問題
# 1. 連線池未關閉 → 檢查 DataSource 設定
# 2. 快取未設上限 → 設定 Cache 最大條目數
# 3. 大量 String 累積 → 檢查日誌或字串操作
# 4. Thread Local 洩漏 → 使用 Virtual Threads 時需注意

# 動態調整日誌等級（Dev Mode）
# 在 Dev UI → Configuration 中即時修改

# 依場景開啟日誌
# REST 請求
quarkus.log.category."io.quarkus.rest".level=DEBUG

# CDI
quarkus.log.category."io.quarkus.arc".level=DEBUG

# Hibernate
quarkus.log.category."org.hibernate".level=DEBUG

# OIDC
quarkus.log.category."io.quarkus.oidc".level=DEBUG

# Kafka
quarkus.log.category."io.smallrye.reactive.messaging".level=DEBUG

# 專案管理
quarkus create app com.example:my-app      # 建立新專案
quarkus create app --list                   # 列出可用範本
quarkus dev                                 # 啟動 Dev Mode
quarkus build                               # 建置專案
quarkus build --native                      # Native 建置

# Extension 管理
quarkus extension list                       # 列出可用 Extension
quarkus extension add rest                   # 加入 Extension
quarkus extension remove rest                # 移除 Extension
quarkus extension list --installed           # 列出已安裝 Extension

# 版本管理
quarkus update                               # 更新到最新版
quarkus update --dry-run                     # 預覽更新
quarkus version                              # 顯示版本

# 其他
quarkus info                                 # 顯示專案資訊
quarkus deploy                               # 部署到雲端

# 建置
./mvnw clean compile                         # 編譯
./mvnw clean test                            # 執行測試
./mvnw clean package                         # 打包
./mvnw clean verify                          # 完整驗證
./mvnw clean package -DskipTests             # 跳過測試打包
./mvnw clean package -Pnative                # Native 打包

# Quarkus 專用
./mvnw quarkus:dev                           # Dev Mode
./mvnw quarkus:test                          # Continuous Testing
./mvnw quarkus:info                          # 專案資訊
./mvnw quarkus:update                        # 更新 Quarkus
./mvnw quarkus:add-extension -Dextensions="rest,hibernate-orm-panache"
./mvnw quarkus:remove-extension -Dextensions="rest"

# 品質
./mvnw org.owasp:dependency-check-maven:check       # 依賴掃描
./mvnw org.cyclonedx:cyclonedx-maven-plugin:makeAggregateBom  # SBOM
./mvnw versions:display-dependency-updates           # 檢查依賴更新

./gradlew build                               # 建置
./gradlew test                                # 測試
./gradlew quarkusDev                          # Dev Mode
./gradlew build -Dquarkus.native.enabled=true # Native 建置

# ===== 基本設定 =====
quarkus.application.name=order-service
quarkus.application.version=1.0.0

# ===== HTTP =====
quarkus.http.port=8080
quarkus.http.cors=true
quarkus.http.cors.origins=https://frontend.example.com
quarkus.http.enable-compression=true

# ===== 資料庫 =====
quarkus.datasource.db-kind=postgresql
quarkus.datasource.jdbc.url=jdbc:postgresql://localhost:5432/orderdb
quarkus.datasource.username=app_user
quarkus.datasource.password=${DB_PASSWORD}
quarkus.datasource.jdbc.max-size=20

# ===== JPA =====
quarkus.hibernate-orm.database.generation=none
quarkus.hibernate-orm.log.sql=false

# ===== Flyway =====
quarkus.flyway.migrate-at-start=true

# ===== OIDC =====
quarkus.oidc.auth-server-url=https://keycloak.example.com/realms/my-realm
quarkus.oidc.client-id=order-service
quarkus.oidc.credentials.secret=${OIDC_SECRET}

# ===== 日誌 =====
quarkus.log.level=INFO
quarkus.log.console.json=true
quarkus.log.category."com.example".level=DEBUG

# ===== Health =====
quarkus.smallrye-health.ui.enable=true

# ===== Metrics =====
quarkus.micrometer.export.prometheus.enabled=true

# ===== OpenTelemetry =====
quarkus.otel.exporter.otlp.endpoint=http://otel-collector:4317
quarkus.otel.service.name=order-service

# ===== 管理端點 =====
quarkus.management.enabled=true
quarkus.management.port=9000

# ===== Kubernetes =====
quarkus.kubernetes.namespace=production
quarkus.kubernetes.replicas=3
quarkus.kubernetes.resources.requests.cpu=250m
quarkus.kubernetes.resources.requests.memory=256Mi
quarkus.kubernetes.resources.limits.cpu=1000m
quarkus.kubernetes.resources.limits.memory=512Mi

# ===== Virtual Threads =====
quarkus.virtual-threads.enabled=true

# ===== Dev Profile =====
%dev.quarkus.log.level=DEBUG
%dev.quarkus.log.console.json=false
%dev.quarkus.hibernate-orm.log.sql=true
%dev.quarkus.live-reload.instrumentation=true

# ===== Test Profile =====
%test.quarkus.log.level=WARN

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

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

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

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

jobs:
  # ========== 建置與測試 ==========
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-java@v4
        with:
          java-version: ${{ env.JAVA_VERSION }}
          distribution: temurin
          cache: maven
      - name: Build & Test
        run: ./mvnw clean verify -B
      - name: Upload Artifacts
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: build-artifacts
          path: |
            target/surefire-reports/
            target/quarkus-app/

  # ========== 安全掃描 ==========
  security:
    runs-on: ubuntu-latest
    needs: build
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-java@v4
        with:
          java-version: ${{ env.JAVA_VERSION }}
          distribution: temurin
          cache: maven
      - name: OWASP Dependency Check
        run: ./mvnw org.owasp:dependency-check-maven:check -B
      - name: SBOM Generation
        run: ./mvnw org.cyclonedx:cyclonedx-maven-plugin:makeAggregateBom -B
      - name: Secret Scan
        uses: gitleaks/gitleaks-action@v2
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

  # ========== 容器映像建置與推送 ==========
  publish:
    runs-on: ubuntu-latest
    needs: [build, security]
    if: github.ref == 'refs/heads/main'
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-java@v4
        with:
          java-version: ${{ env.JAVA_VERSION }}
          distribution: temurin
          cache: maven
      - name: Build Package
        run: ./mvnw package -DskipTests -B
      - name: Login to Registry
        uses: docker/login-action@v3
        with:
          registry: ${{ env.REGISTRY }}
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}
      - name: Build & Push Image
        uses: docker/build-push-action@v6
        with:
          context: .
          file: src/main/docker/Dockerfile.jvm
          push: true
          tags: |
            ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ github.sha }}
            ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:latest

FROM eclipse-temurin:21-jre-alpine
WORKDIR /app
COPY target/quarkus-app/ /app/
RUN addgroup -S appgroup && adduser -S appuser -G appgroup
USER appuser
EXPOSE 8080 9000
ENTRYPOINT ["java", \
    "-XX:MaxRAMPercentage=75.0", \
    "-XX:+UseG1GC", \
    "-jar", "/app/quarkus-run.jar"]

FROM quay.io/quarkus/quarkus-micro-image:2.0
WORKDIR /work/
COPY --chown=1001:root target/*-runner /work/application
RUN chmod 775 /work
USER 1001
EXPOSE 8080 9000
ENTRYPOINT ["./application", "-Dquarkus.http.host=0.0.0.0"]

# namespace.yaml
apiVersion: v1
kind: Namespace
metadata:
  name: order-system
---
# configmap.yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: order-service-config
  namespace: order-system
data:
  QUARKUS_HTTP_PORT: "8080"
  QUARKUS_LOG_LEVEL: "INFO"
  QUARKUS_LOG_CONSOLE_JSON: "true"
  QUARKUS_OTEL_EXPORTER_OTLP_ENDPOINT: "http://otel-collector:4317"
---
# secret.yaml
apiVersion: v1
kind: Secret
metadata:
  name: order-service-secrets
  namespace: order-system
type: Opaque
stringData:
  QUARKUS_DATASOURCE_PASSWORD: "change-me"
  QUARKUS_OIDC_CREDENTIALS_SECRET: "change-me"
---
# deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: order-service
  namespace: order-system
  labels:
    app: order-service
    version: v1
spec:
  replicas: 3
  selector:
    matchLabels:
      app: order-service
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxUnavailable: 1
      maxSurge: 1
  template:
    metadata:
      labels:
        app: order-service
        version: v1
    spec:
      containers:
        - name: order-service
          image: ghcr.io/my-org/order-service:latest
          ports:
            - name: http
              containerPort: 8080
            - name: management
              containerPort: 9000
          envFrom:
            - configMapRef:
                name: order-service-config
            - secretRef:
                name: order-service-secrets
          resources:
            requests:
              cpu: 250m
              memory: 256Mi
            limits:
              cpu: 1000m
              memory: 512Mi
          livenessProbe:
            httpGet:
              path: /q/health/live
              port: management
            initialDelaySeconds: 5
            periodSeconds: 10
          readinessProbe:
            httpGet:
              path: /q/health/ready
              port: management
            initialDelaySeconds: 10
            periodSeconds: 10
          startupProbe:
            httpGet:
              path: /q/health/started
              port: management
            periodSeconds: 5
            failureThreshold: 12
---
# service.yaml
apiVersion: v1
kind: Service
metadata:
  name: order-service
  namespace: order-system
spec:
  selector:
    app: order-service
  ports:
    - name: http
      port: 80
      targetPort: 8080
    - name: management
      port: 9000
      targetPort: 9000
---
# hpa.yaml
apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: order-service-hpa
  namespace: order-system
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: order-service
  minReplicas: 2
  maxReplicas: 10
  metrics:
    - type: Resource
      resource:
        name: cpu
        target:
          type: Utilization
          averageUtilization: 70