xDev Asia

Quarkus CLI と JDK 21+ のインストール、プロジェクトの作成、開発モードのライブリロード、開発 UI ダッシュボード、開発サービス、継続的テスト。

Quarkus マイクロサービス: 基本から運用まで

パート 1: Quarkus プラットフォームとプロジェクトのセットアップ

xdev.asia

はじめに

Quarkus の最大の強みの 1 つは 開発者エクスペリエンス (DX) です。開発モードでは、コードを変更→保存→結果がすぐに実行されます。 Dev Services は、構成を行わなくても PostgreSQL、Kafka、Keycloak を自動的に開始します。 Dev UI は、拡張機能を管理するための直感的なダッシュボードを提供します。継続的テストでは、コードが変更されるたびにテストが自動的に実行されます。

環境設定

JDK 21+

# SDKMAN (khuyến nghị)
sdk install java 21.0.4-tem

# Hoặc download từ Adoptium
# https://adoptium.net/

# Verify
java --version
# openjdk 21.0.4 2024-07-16 LTS

Quarkus CLI

# macOS (Homebrew)
brew install quarkusio/tap/quarkus

# Linux / macOS (SDKMAN)
sdk install quarkus

# Linux (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

# Verify
quarkus version
# 3.34.x

Docker (開発サービス用)

# Docker Desktop hoặc Podman
docker --version
# Docker version 27.x

# Quarkus hỗ trợ cả Podman
podman --version

最初のプロジェクトを作成する

Quarkus CLI

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

cd product-service

プロジェクトの構造

product-service/
├── mvnw                          # Maven wrapper
├── pom.xml                       # Dependencies & plugins
├── src/
│   ├── main/
│   │   ├── docker/               # Dockerfiles (JVM, Native, Legacy)
│   │   │   ├── Dockerfile.jvm
│   │   │   ├── Dockerfile.native
│   │   │   └── Dockerfile.native-micro
│   │   ├── java/com/xdev/ecommerce/
│   │   │   └── GreetingResource.java
│   │   └── resources/
│   │       ├── application.properties  # Configuration
│   │       └── META-INF/
│   │           └── resources/          # Static files (index.html)
│   └── test/
│       └── java/com/xdev/ecommerce/
│           ├── GreetingResourceTest.java
│           └── GreetingResourceIT.java   # Integration test (native)
└── .mvn/                         # Maven wrapper config

pom.xml — Quarkus BOM

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>io.quarkus.platform</groupId>
            <artifactId>quarkus-bom</artifactId>
            <version>3.34.2</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

<dependencies>
    <dependency>
        <groupId>io.quarkus</groupId>
        <artifactId>quarkus-rest-jackson</artifactId>
    </dependency>
    <dependency>
        <groupId>io.quarkus</groupId>
        <artifactId>quarkus-hibernate-orm-panache</artifactId>
    </dependency>
    <dependency>
        <groupId>io.quarkus</groupId>
        <artifactId>quarkus-jdbc-postgresql</artifactId>
    </dependency>
    <!-- ... -->
</dependencies>

開発モード — ライブコーディング

quarkus dev
# hoặc
./mvnw quarkus:dev

ホットリロードはどのように機能しますか?

┌─────────────────────────────────────────────┐
│  Developer thay đổi code → Save file        │
│              │                               │
│              ▼                               │
│  Quarkus detect file change                  │
│              │                               │
│              ▼                               │
│  Re-compile class đã thay đổi (incremental) │
│              │                               │
│              ▼                               │
│  Re-deploy application (trong cùng JVM)      │
│              │                               │
│              ▼                               │
│  Next HTTP request nhận code mới (~200ms)    │
└─────────────────────────────────────────────┘

Spring DevTools との違い:

JVM を再起動しないでください - 変更されたクラスのみをリロードします
依存関係の変更をサポート (再起動せずに新しい拡張機能を追加)
構成の変更もすぐにリロードされます

開発モードコマンド

開発モードの実行中に、次のキーを押します。

Press [h] for more options>

[r] - Re-run all tests
[o] - Toggle test output
[s] - Force restart
[w] - Open Dev UI in browser
[d] - Disable/Enable live reload
[h] - Show this help
[q] - Quit

開発サービス — ゼロ構成インフラストラクチャ

Dev Services は、Quarkus の キラー 機能です。外部サービス (データベース、メッセージブローカー、認証サーバー) を必要とする拡張機能を追加すると、Quarkus は Testcontainers を使用して 自動的にコンテナ を起動します。

仕組み

┌─────────────────────────────────────────────┐
│  quarkus dev                                 │
│              │                               │
│              ▼                               │
│  Detect jdbc-postgresql extension            │
│  → No datasource URL configured             │
│  → Auto-start PostgreSQL container           │
│              │                               │
│  Detect quarkus-oidc extension               │
│  → No OIDC server configured                │
│  → Auto-start Keycloak container             │
│              │                               │
│  Detect kafka extension                      │
│  → No bootstrap servers configured           │
│  → Auto-start Kafka container (Redpanda)     │
│              │                               │
│  Inject connection URLs automatically        │
└─────────────────────────────────────────────┘

application.properties (開発モード)

# KHÔNG cần cấu hình gì cho dev mode!
# Dev Services tự start PostgreSQL, Keycloak, Kafka

# Chỉ cần config cho production
%prod.quarkus.datasource.db-kind=postgresql
%prod.quarkus.datasource.jdbc.url=jdbc:postgresql://db:5432/products
%prod.quarkus.datasource.username=${DB_USER}
%prod.quarkus.datasource.password=${DB_PASS}

PostgreSQL の開発サービス

# Tùy chỉnh Dev Services (tùy chọn)
quarkus.datasource.devservices.image-name=postgres:16
quarkus.datasource.devservices.port=5433
quarkus.datasource.devservices.db-name=product_db
quarkus.datasource.devservices.volumes."/path/to/init.sql"=/docker-entrypoint-initdb.d/init.sql

Keycloak の開発サービス

# Auto-start Keycloak 26.x
quarkus.oidc.devservices.realm-path=dev-realm.json
quarkus.oidc.devservices.port=8180
quarkus.oidc.devservices.roles.alice=admin,user
quarkus.oidc.devservices.roles.bob=user

開発 UI — 開発ダッシュボード

アクセス http://localhost:8080/q/dev-ui 開発モードが実行されている場合:

開発 UI 機能

タブ	機能
拡張機能	インストールされている拡張機能のリスト、ドキュメントへのリンク
構成	すべての構成プロパティをリアルタイムで表示/編集
エンドポイント	すべての REST エンドポイントをリストする
開発サービス	コンテナのステータスが実行中
Swagger UI	API を直接テストする
休止状態 ORM	エンティティの表示、HQL/SQL クエリの実行
スモールライヘルス	健康状態をチェック
継続的なテスト	リアルタイムのテスト結果

継続的なテスト

Quarkus は、コードが変更されるたびにテストを 自動的に 実行します。

# Bật Continuous Testing trong Dev Mode
# Nhấn [r] để chạy tất cả tests

# Hoặc configure trong application.properties
quarkus.test.continuous-testing=enabled
# enabled | paused | disabled

テストのライフサイクル

┌──────────────────────────────────────────┐
│  Code change detected                     │
│          │                                │
│          ▼                                │
│  Identify affected tests                  │
│          │                                │
│          ▼                                │
│  Run ONLY affected tests (smart filter)   │
│          │                                │
│          ▼                                │
│  Display results in terminal              │
│  ✅ 5 passed | ❌ 1 failed | ⏭️ 3 skipped │
└──────────────────────────────────────────┘

マルチモジュールプロジェクトの構造

マイクロサービスシステムの場合、マルチモジュール Maven プロジェクト を使用します。

ecommerce-platform/
├── pom.xml                     # Parent POM
├── common/                     # Shared DTOs, utils
│   ├── pom.xml
│   └── src/
├── product-service/            # Microservice 1
│   ├── pom.xml
│   └── src/
├── order-service/              # Microservice 2
│   ├── pom.xml
│   └── src/
├── payment-service/            # Microservice 3
│   ├── pom.xml
│   └── src/
├── notification-service/       # Microservice 4
│   ├── pom.xml
│   └── src/
└── docker-compose.yml          # Local environment

親 POM

<project>
    <groupId>com.xdev.ecommerce</groupId>
    <artifactId>ecommerce-platform</artifactId>
    <version>1.0.0-SNAPSHOT</version>
    <packaging>pom</packaging>

    <modules>
        <module>common</module>
        <module>product-service</module>
        <module>order-service</module>
        <module>payment-service</module>
        <module>notification-service</module>
    </modules>

    <properties>
        <quarkus.platform.version>3.34.2</quarkus.platform.version>
        <java.version>21</java.version>
        <maven.compiler.source>${java.version}</maven.compiler.source>
        <maven.compiler.target>${java.version}</maven.compiler.target>
    </properties>

    <dependencyManagement>
        <dependencies>
            <dependency>
                <groupId>io.quarkus.platform</groupId>
                <artifactId>quarkus-bom</artifactId>
                <version>${quarkus.platform.version}</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
        </dependencies>
    </dependencyManagement>
</project>

演習

JDK 21、Quarkus CLI、Docker をローカルマシンにインストールします
プロジェクトの作成 product-service 拡張子付き: rest-jackson、 hibernate-orm-panache、 jdbc-postgresql、 flyway、 smallrye-health
走る quarkus dev Dev Services が PostgreSQL コンテナを自動的に起動することを確認します。
次の場所で開発 UI にアクセスします。 /q/dev-ui — タブを探索する
新しいエンドポイントを作成し、ファイルを保存して、ライブリロードが機能するかどうかをテストします。
Eコマースプラットフォーム用のマルチモジュールプロジェクト構造を作成する

概要

Quarkus CLI を使用してプロジェクトを迅速に作成 quarkus create app
開発モード JVM を再起動せずにライブリロード
Dev Services は PostgreSQL、Kafka、Keycloak を自動的に開始します — 設定不要
開発 UI ダッシュボードは拡張機能、エンドポイント、リアルタイム構成を管理します
継続的テスト は、コードが変更されると自動的にテストを実行します
マイクロサービスシステムに適したマルチモジュールプロジェクト

次の記事: Quarkus REST を使用してプロフェッショナルな RESTful API を構築する。

レッスン 2: Quarkus プロジェクトの作成 — CLI、開発モード、開発 UI、ライブ コーディング

はじめに

環境設定

JDK 21+

Quarkus CLI

Docker (開発サービス用)

最初のプロジェクトを作成する

Quarkus CLI

プロジェクトの構造

pom.xml — Quarkus BOM

開発モード — ライブコーディング

ホットリロードはどのように機能しますか?

開発モードコマンド

開発サービス — ゼロ構成インフラストラクチャ

仕組み

application.properties (開発モード)

PostgreSQL の開発サービス

Keycloak の開発サービス

開発 UI — 開発ダッシュボード

開発 UI 機能

継続的なテスト

テストのライフサイクル

マルチモジュールプロジェクトの構造

親 POM

演習

概要

レッスン 2: Quarkus プロジェクトの作成 — CLI、開発モード、開発 UI、ライブコーディング