📚 第一章：Quarkus 简介与环境搭建

1.1 Quarkus 概述

1.1.1 什么是 Quarkus

Quarkus 是一个为 Kubernetes 和云原生环境优化的全栈 Java 框架，专为 GraalVM 和 OpenJDK HotSpot 设计。它被称为”超音速亚原子 Java”（Supersonic Subatomic Java），因为它能够显著减少应用的启动时间和内存占用。

1.1.2 Quarkus 的核心特性

graph TB
    A[Quarkus 核心特性] --> B[快速启动]
    A --> C[低内存占用]
    A --> D[原生镜像支持]
    A --> E[开发者友好]
    A --> F[云原生优化]
    A --> G[标准兼容]
    
    B --> B1[毫秒级启动]
    B --> B2[热重载]
    
    C --> C1[最小化运行时]
    C --> C2[优化内存使用]
    
    D --> D1[GraalVM 原生镜像]
    D --> D2[容器优化]
    
    E --> E1[实时编码]
    E --> E2[统一配置]
    
    F --> F1[Kubernetes 集成]
    F --> F2[微服务架构]
    
    G --> G1[Jakarta EE 标准]
    G --> G2[MicroProfile 规范]

1.1.3 Quarkus vs 传统 Java 框架

特性	Quarkus	Spring Boot	传统 Java EE
启动时间	< 100ms	2-5s	10-30s
内存占用	13MB	100-200MB	200-500MB
原生镜像	✅ 原生支持	⚠️ 实验性	❌ 不支持
热重载	✅ 毫秒级	✅ 秒级	❌ 需重启
云原生	✅ 优化	✅ 支持	⚠️ 部分支持
学习曲线	📈 中等	📈 中等	📈 陡峭

1.2 Quarkus 架构原理

1.2.1 编译时优化

Quarkus 的核心理念是将传统运行时的工作转移到编译时完成：

sequenceDiagram
    participant Dev as 开发者
    participant QC as Quarkus 编译器
    participant RT as 运行时
    participant App as 应用
    
    Dev->>QC: 编写代码
    QC->>QC: 依赖注入分析
    QC->>QC: 配置处理
    QC->>QC: 反射分析
    QC->>QC: 代码生成
    QC->>RT: 优化后的字节码
    RT->>App: 快速启动

1.2.2 扩展机制

Quarkus 通过扩展（Extensions）提供功能：

// 扩展示例：自动配置数据源
@BuildStep
DataSourceBuildItem createDataSource(DataSourceConfig config) {
    // 编译时创建数据源配置
    return new DataSourceBuildItem(config.url, config.driver);
}

1.3 环境搭建

1.3.1 系统要求

• JDK: 17 或更高版本（推荐 JDK 21）
• 构建工具: Maven 3.8.1+ 或 Gradle 7.5+
• IDE: IntelliJ IDEA、VS Code 或 Eclipse
• 内存: 最少 4GB RAM（推荐 8GB+）
• 操作系统: Windows、macOS 或 Linux

1.3.2 安装 JDK

Windows 安装

# 使用 Chocolatey 安装
choco install openjdk17

# 或下载安装包
# 访问 https://adoptium.net/ 下载

macOS 安装

# 使用 Homebrew 安装
brew install openjdk@17

# 设置环境变量
echo 'export PATH="/opt/homebrew/opt/openjdk@17/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Linux 安装

# Ubuntu/Debian
sudo apt update
sudo apt install openjdk-17-jdk

# CentOS/RHEL
sudo yum install java-17-openjdk-devel

# 验证安装
java -version
javac -version

1.3.3 安装构建工具

Maven 安装

# 下载并解压 Maven
wget https://archive.apache.org/dist/maven/maven-3/3.9.6/binaries/apache-maven-3.9.6-bin.tar.gz
tar -xzf apache-maven-3.9.6-bin.tar.gz

# 设置环境变量
export MAVEN_HOME=/path/to/apache-maven-3.9.6
export PATH=$MAVEN_HOME/bin:$PATH

# 验证安装
mvn -version

Gradle 安装

# 使用 SDKMAN 安装
curl -s "https://get.sdkman.io" | bash
sdk install gradle 8.5

# 验证安装
gradle -version

1.3.4 IDE 配置

IntelliJ IDEA 配置

1. 安装 Quarkus 插件

   File → Settings → Plugins → 搜索 "Quarkus" → 安装
   

2. 配置 JDK

   File → Project Structure → Project → Project SDK → 选择 JDK 17+
   

3. 配置 Maven

   File → Settings → Build Tools → Maven → Maven home path
   

VS Code 配置

// .vscode/settings.json
{
    "java.home": "/path/to/jdk-17",
    "java.configuration.runtimes": [
        {
            "name": "JavaSE-17",
            "path": "/path/to/jdk-17"
        }
    ],
    "extensions.recommendations": [
        "redhat.vscode-quarkus",
        "vscjava.vscode-java-pack"
    ]
}

1.4 创建第一个 Quarkus 应用

1.4.1 使用 Maven 创建项目

# 使用 Quarkus Maven 插件创建项目
mvn io.quarkus.platform:quarkus-maven-plugin:3.6.0:create \
    -DprojectGroupId=com.example \
    -DprojectArtifactId=hello-quarkus \
    -DclassName="com.example.GreetingResource" \
    -Dpath="/hello" \
    -Dextensions="resteasy-reactive"

# 进入项目目录
cd hello-quarkus

1.4.2 项目结构分析

hello-quarkus/
├── pom.xml                     # Maven 配置文件
├── src/
│   ├── main/
│   │   ├── java/
│   │   │   └── com/example/
│   │   │       └── GreetingResource.java  # REST 端点
│   │   ├── resources/
│   │   │   ├── application.properties     # 应用配置
│   │   │   └── META-INF/
│   │   │       └── resources/
│   │   │           └── index.html         # 静态页面
│   │   └── docker/
│   │       ├── Dockerfile.jvm             # JVM 镜像
│   │       └── Dockerfile.native          # 原生镜像
│   └── test/
│       └── java/
│           └── com/example/
│               ├── GreetingResourceTest.java      # 单元测试
│               └── NativeGreetingResourceIT.java  # 集成测试
└── target/                     # 构建输出目录

1.4.3 核心文件解析

pom.xml 配置

<?xml version="1.0"?>
<project xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 
         https://maven.apache.org/xsd/maven-4.0.0.xsd" 
         xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <modelVersion>4.0.0</modelVersion>
  
  <groupId>com.example</groupId>
  <artifactId>hello-quarkus</artifactId>
  <version>1.0.0-SNAPSHOT</version>
  
  <properties>
    <compiler-plugin.version>3.11.0</compiler-plugin.version>
    <maven.compiler.release>17</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.6.0</quarkus.platform.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>
    <!-- Quarkus RESTEasy Reactive -->
    <dependency>
      <groupId>io.quarkus</groupId>
      <artifactId>quarkus-resteasy-reactive</artifactId>
    </dependency>
    
    <!-- Quarkus Arc (CDI) -->
    <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>
      <!-- Quarkus Maven 插件 -->
      <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>
            </goals>
          </execution>
        </executions>
      </plugin>
      
      <!-- Maven 编译插件 -->
      <plugin>
        <artifactId>maven-compiler-plugin</artifactId>
        <version>${compiler-plugin.version}</version>
        <configuration>
          <compilerArgs>
            <arg>-parameters</arg>
          </compilerArgs>
        </configuration>
      </plugin>
      
      <!-- Maven Surefire 插件 -->
      <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>
            <maven.home>${maven.home}</maven.home>
          </systemPropertyVariables>
        </configuration>
      </plugin>
      
      <!-- Maven Failsafe 插件 -->
      <plugin>
        <artifactId>maven-failsafe-plugin</artifactId>
        <version>${surefire-plugin.version}</version>
        <executions>
          <execution>
            <goals>
              <goal>integration-test</goal>
              <goal>verify</goal>
            </goals>
            <configuration>
              <systemPropertyVariables>
                <native.image.path>${project.build.directory}/${project.build.finalName}-runner</native.image.path>
                <java.util.logging.manager>org.jboss.logmanager.LogManager</java.util.logging.manager>
                <maven.home>${maven.home}</maven.home>
              </systemPropertyVariables>
            </configuration>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
  
  <!-- 原生镜像构建配置 -->
  <profiles>
    <profile>
      <id>native</id>
      <activation>
        <property>
          <name>native</name>
        </property>
      </activation>
      <properties>
        <skipITs>false</skipITs>
        <quarkus.package.type>native</quarkus.package.type>
      </properties>
    </profile>
  </profiles>
</project>

GreetingResource.java

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 RESTEasy Reactive";
    }
}

application.properties

# 应用基本配置
quarkus.application.name=hello-quarkus
quarkus.application.version=1.0.0

# HTTP 服务器配置
quarkus.http.port=8080
quarkus.http.host=0.0.0.0

# 开发模式配置
quarkus.live-reload.instrumentation=true

# 日志配置
quarkus.log.level=INFO
quarkus.log.console.enable=true
quarkus.log.console.format=%d{HH:mm:ss} %-5p [%c{2.}] (%t) %s%e%n

# 健康检查配置
quarkus.smallrye-health.ui.enable=true

1.5 运行和测试应用

1.5.1 开发模式运行

# 启动开发模式（热重载）
./mvnw compile quarkus:dev

# 或者使用 Gradle
./gradlew quarkusDev

开发模式特性： - 🔥 热重载: 代码修改后自动重新编译 - 🚀 快速启动: 通常在 1-2 秒内启动 - 🔍 开发 UI: 访问 http://localhost:8080/q/dev/ - 📊 健康检查: 访问 http://localhost:8080/q/health/

1.5.2 测试应用

# 访问应用端点
curl http://localhost:8080/hello
# 输出: Hello from RESTEasy Reactive

# 查看应用信息
curl http://localhost:8080/q/info

# 健康检查
curl http://localhost:8080/q/health

1.5.3 单元测试

// GreetingResourceTest.java
package com.example;

import io.quarkus.test.junit.QuarkusTest;
import org.junit.jupiter.api.Test;

import static io.restassured.RestAssured.given;
import static org.hamcrest.CoreMatchers.is;

@QuarkusTest
class GreetingResourceTest {
    
    @Test
    void testHelloEndpoint() {
        given()
          .when().get("/hello")
          .then()
             .statusCode(200)
             .body(is("Hello from RESTEasy Reactive"));
    }
}

运行测试：

# 运行所有测试
./mvnw test

# 运行特定测试
./mvnw test -Dtest=GreetingResourceTest

1.6 构建和打包

1.6.1 JVM 模式打包

# 构建 JVM 应用
./mvnw clean package

# 运行打包后的应用
java -jar target/quarkus-app/quarkus-run.jar

1.6.2 原生镜像构建

安装 GraalVM

# 使用 SDKMAN 安装 GraalVM
sdk install java 21.0.1-graal
sdk use java 21.0.1-graal

# 验证安装
java -version
native-image --version

构建原生镜像

# 构建原生镜像
./mvnw clean package -Dnative

# 运行原生镜像
./target/hello-quarkus-1.0.0-SNAPSHOT-runner

性能对比：

模式	启动时间	内存占用	文件大小
JVM	~1.5s	~100MB	~15MB
Native	~0.05s	~13MB	~50MB

1.7 开发工具和插件

1.7.1 Quarkus CLI

# 安装 Quarkus CLI
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

# 使用 CLI 创建项目
quarkus create app com.example:my-app

# 添加扩展
quarkus ext add hibernate-orm-panache

# 启动开发模式
quarkus dev

1.7.2 IDE 插件功能

IntelliJ IDEA Quarkus 插件

• 🎯 项目向导: 图形化创建 Quarkus 项目
• 🔧 代码补全: 配置属性和注解补全
• 🐛 调试支持: 断点调试和热重载
• 📝 模板支持: 代码模板和片段

VS Code Quarkus 扩展

// launch.json 调试配置
{
    "version": "0.2.0",
    "configurations": [
        {
            "type": "java",
            "name": "Quarkus Dev",
            "request": "launch",
            "mainClass": "io.quarkus.runner.GeneratedMain",
            "args": "dev",
            "vmArgs": "-Dquarkus.args=dev"
        }
    ]
}

1.8 常见问题和解决方案

1.8.1 端口冲突

# application.properties
# 修改默认端口
quarkus.http.port=8081

1.8.2 内存不足

# 增加 JVM 内存
export MAVEN_OPTS="-Xmx2g"
./mvnw compile quarkus:dev

1.8.3 热重载不工作

# application.properties
# 启用实时重载
quarkus.live-reload.instrumentation=true
quarkus.live-reload.watched-resources=src/main/resources/**

1.8.4 原生镜像构建失败

# 检查 GraalVM 版本
native-image --version

# 增加构建内存
export MAVEN_OPTS="-Xmx4g"
./mvnw clean package -Dnative

1.9 实践练习

1.9.1 练习1：创建个人信息 API

创建一个返回个人信息的 REST 端点：

@Path("/profile")
public class ProfileResource {
    
    @GET
    @Produces(MediaType.APPLICATION_JSON)
    public Profile getProfile() {
        return new Profile("张三", 25, "软件工程师");
    }
    
    public static class Profile {
        public String name;
        public int age;
        public String job;
        
        public Profile(String name, int age, String job) {
            this.name = name;
            this.age = age;
            this.job = job;
        }
    }
}

1.9.2 练习2：添加健康检查

@ApplicationScoped
public class CustomHealthCheck implements HealthCheck {
    
    @Override
    public HealthCheckResponse call() {
        return HealthCheckResponse.up("Custom Health Check");
    }
}

1.9.3 练习3：配置管理

# application.properties
app.greeting.message=Hello from Quarkus!
app.greeting.suffix=Have a nice day!

@ConfigProperty(name = "app.greeting.message")
String greetingMessage;

@ConfigProperty(name = "app.greeting.suffix")
String greetingSuffix;

1.10 本章小结

1.10.1 核心概念回顾

1. Quarkus 特性

   • 快速启动和低内存占用
   • 原生镜像支持
   • 开发者友好的热重载
   • 云原生优化

2. 环境搭建

   • JDK 17+ 安装和配置
   • Maven/Gradle 构建工具
   • IDE 插件安装

3. 项目创建

   • 使用 Maven 插件创建项目
   • 项目结构理解
   • 基本配置文件

4. 开发模式

   • 热重载功能
   • 开发 UI 界面
   • 调试和测试

1.10.2 技术要点

• 编译时优化: Quarkus 的核心优势
• 扩展机制: 模块化功能组织
• 配置管理: 统一的配置方式
• 测试支持: 完整的测试框架

1.10.3 最佳实践

1. 开发环境

   • 使用最新的 JDK 版本
   • 配置充足的内存
   • 安装合适的 IDE 插件

2. 项目结构

   • 遵循 Maven 标准目录结构
   • 合理组织包结构
   • 分离配置和代码

3. 开发流程

   • 充分利用热重载功能
   • 编写单元测试
   • 定期构建和测试

1.10.4 下一章预告

下一章我们将深入学习 Quarkus 的依赖注入和配置管理，包括： - CDI（Contexts and Dependency Injection）基础 - Bean 的生命周期管理 - 配置文件和属性注入 - 环境特定配置

---

恭喜！ 🎉 您已经成功搭建了 Quarkus 开发环境并创建了第一个应用。继续下一章的学习，深入掌握 Quarkus 的核心功能！