2.4 应用案例说明

下面会通过程序案例源码的方式介绍Quarkus 的应用案例。

2.4.1 应用案例场景说明

后续案例的应用场景一般为一个或多个微服务场景，以一个完整的微服务为主，典型的案例应用场景对象关系如图2-37所示。

应用案例项目一般由 5 个类组成，分别是 ProjectMain、ProjectResource、ProjectService、Project和LoggingFilter类，其说明如表2-4所示。

在后续所有的案例中，ProjectMain 和 LoggingFilter 类的代码基本不变，而ProjectResource、ProjectService、Project 类总体上的功能、作用是相同的，内容也大同小异，但会根据具体应用场景做一些定制化的调整。

1.ProjectMain命令行应用类

ProjectMain 类主要用于调试，这样开发者可以在 IDE 开发工具中直接启动程序。在实际应用中，可以忽略这个类。ProjectMain类的代码如下：

2.LoggingFilter日志记录类

LoggingFilter类主要在IDE开发工具的控制台上记录日志，这样可以在IDE开发工具中直接观察调用信息。在实际应用中，可以忽略这个类。LoggingFilter类的代码如下：

2.4.2 应用案例简要介绍

Quarkus 应用案例简介及关键词如表2-5所示。

另外，有3种途径可以获取案例源码。

第1种途径是直接从网站获取源码打包文件，然后解压导入。

第2种途径是从 GitHub上获取，可以从 GitHub上克隆预先准备好的示例代码，命令如下：

第3种途径是从 Gitee上获取，可以从 Gitee上克隆预先准备好的示例代码，命令如下：

每个案例都是独立的应用程序，可以单独运行和验证，与其他案例没有依赖关系。

案例源码遵循Apache License、Version 2.0开源协议。

2.4.3 与应用案例相关的软件和须遵循的规范

1.必备软件

应用案例程序的运行可能需要安装以下软件、工具、框架，以便能进行正确的测试和验证。

(1)JDK 1.8

开发和执行应用程序，至关重要的是 Java 开发工具包（JDK）。本书案例所有项目中的代码使用JDK 1.8，编译成原生可执行程序时采用JDK 11。

(2)GraalVM

GraalVM 是 Java 虚拟机（JVM）的扩展，以支持更多的语言和几种执行模式。它支持大量的语言，除 Java 外，还支持其他基于 JVM 的语言（如 Groovy、Kotlin 等），也支持JavaScript、Ruby、Python、R和 C++语言。GraalVM包含一个新的高性能 Java编译器，可以在 HotSpot 虚拟机的即时（Just-in-Time，JIT）配置中使用，或者在底层虚拟机上的提前（AOT）配置中使用。GraalVM的一个目标是提高基于 Java虚拟机的语言性能，以匹配本地语言的性能。

当需要编译成原生可执行程序时，必须安装GraalVM。

(3)Eclipse IDE

Eclipse 是一个开放源码的项目，是著名的跨平台开源集成开发环境（IDE）。它是笔者在本书中主要使用的 IDE 开发工具。若后面没有特殊说明，都默认使用这个 IDE 工具。首选Eclipse的原因是，笔者已经用了差不多20年，比较熟悉。

(4)Maven 3.6.x

Maven 为案例项目提供了一个构建解决方案、共享库和插件平台。基于“约定优先于配置”原则，Maven提供了一个标准的项目描述和一些约定，例如标准的目录结构。通过基于插件的可扩展架构，Maven可以提供很多不同的服务。

本书所有案例全部由Maven来构建或打包。注意，要保证Maven的版本在3.6.x以上。

(5)cURL

cURL 是一个免费的开源命令行工具和库，可以使用各种协议（包括 HTTP）进行可靠的数据传输，并且已经被移植到多个操作系统上。

大部分应用案例验证都是通过cURL来调用和验证应用案例程序的服务实现的。

2.可选软件

可选软件是指在一些场景下构建、测试和验证应用程序所需的软件。

(1)Docker

Docker是基于 Go语言实现的开源项目。Docker的主要目标是“Build，Ship and Run Any App，Anywhere”，也就是通过对应用组件的封装、分发、部署、运行等生命周期的管理，使用户的应用程序及其运行环境能够做到“一次封装，到处运行”。

本书的案例在讲解一些基础软件（如数据库、消息中间件、授权软件等）的安装时会使用到 Docker。由于这些基础软件的镜像比较大，因此建议先下载下来，供后期使用。下载列表如下。

■ docker pull postgres:10.5

■ docker pull redis:5.0.6

■ docker pull mongo:4.0

■ docker pull strimzi/kafka:0.19.0-kafka-2.5.0

■ docker pull vromero/activemq-artemis:2.11.0-alpine

■ docker pull jboss/keycloak

(2)IntelliJ IDEA

IntelliJ IDEA 的简称是 IDEA，具有美观、高效等众多特点。IDEA 是 JetBrains 公司的产品。免费版只支持Java等少数语言。IntelliJ IDEA的Smart Code Completion和On-the-fly Code Analysis等功能可以提高开发者的工作效率，其还提供了对Web和移动开发的高级支持。

这是笔者的辅助IDE开发工具。该工具与Eclipse工具相比，各有优势。

(3)Postman

Postman 是一款功能强大的网页调试与发送网页 HTTP 请求的 Chrome 插件。方便加数据，查看响应，设置检查点/断言，能进行一定程度上的自动化测试。

本书在讲解Quarkus 使用安全认证的案例时，有些场景下采用的验证工具就是Postman。

(4)PostgreSQL

PostgreSQL 是一个免费的对象—关系型数据库服务器（ORDBMS），由加州大学伯克利分校计算机系开发并以 BSD 许可证发行。PostgreSQL 的口号是“世界上最先进的开源关系型数据库”。

本书在讲解Quarkus 使用关系型数据库的案例时，采用的关系型数据库就是PostgreSQL。（5）Redis

Redis（Remote Dictionary Server，远程字典服务）是一个高性能的开源键值数据库。这是一个开源的、使用 ANSI C语言编写的、支持网络、可基于内存也可持久化的日志型键值数据库，其提供了多种语言的API。

本书在讲解Quarkus 使用缓存数据库的案例时，采用的缓存数据库就是Redis。

(6)MongoDB

MongoDB 是一个基于分布式文件存储的数据库。它是介于关系型数据库和非关系型数据库之间的产品，是非关系型数据库中功能最丰富、最像关系型数据库的数据库。

本书在讲解 Quarkus 使用 NoSQL 数据库的案例时，采用的 NoSQL 数据库就是MongoDB。

(7)Apache Kafka

Apache Kafka是一个分布式数据流处理平台。它是一个可扩展的、容错的发布—订阅消息系统，可以实时发布、订阅、存储和处理数据流。

本书在讲解 Quarkus 使用分布式数据流消息系统的案例时，采用的分布式数据流消息系统就是Apache Kafka。

(8)Apache ActiveMQ Artemis

Apache ActiveMQ Artemis 是一个开源项目，旨在构建一个多协议、可嵌入、非常高性能的集群、异步消息传递系统。

本书在讲解 Quarkus 使用 JMS 消息中间件的案例时，采用的消息中间件就是 Apache ActiveMQ Artemis。

(9)Apache Eclipse Mosquitto

Apache Eclipse Mosquitto 是一个轻量级的开源消息代理，它实现了 MQTT 协议。Eclipse Mosquitto适用于从低功耗单板计算机到全套服务器的所有设备。

本书在讲解 Quarkus 使用 MQTT 消息中间件的案例时，采用的 MQTT 消息中间件就是Apache Eclipse Mosquitto。

(10)Keycloak

Keycloak是一个进行身份认证和访问控制的开源软件。Keycloak由Red Hat基金会开发，可以方便地给应用程序和安全服务添加身份认证。

本书在讲解Quarkus 使用安全认证的案例时，采用的开源认证服务器就是Keycloak。

（11）Kubernetes平台（可选）

Kubernetes 是来自 Google 云平台的开源容器集群管理系统。该系统可以自动地在一个容器集群中选择一个工作容器使用。Kubernetes 能提供一个以“容器为中心的基础架构”，满足在生产环境中运行应用的一些常见需求，其核心概念是Container Pod。

本书在讲解Quarkus 生成Kubernetes资源文件的案例时，会采用Kubernetes平台来验证案例。

（12）OpenShift平台（可选）

OpenShift是由Red Hat推出的一款对开源开发者开放的平台即服务（PaaS）。OpenShift通过为开发者提供语言、框架和云上的更多选择，使开发者可以构建、测试、运行和管理他们的应用。

本书在讲解 Quarkus 生成 OpenShift资源文件的案例时，会采用 OpenShift平台来验证案例。

（13）Knative平台（可选）

Knative是 Google公司开源的 Serverless架构方案，旨在提供一套简单、易用、标准化的Serverless方案，目前参与的公司主要有Google、Pivotal、IBM、Red Hat和SAP。

本书在讲解Quarkus 生成Knative资源文件的案例时，会采用Knative平台来验证案例。

3.案例遵循的规范

（1）Jakarta EE规范

多年来，Java EE 一直是企业应用程序的主要开发平台。为了加速面向云原生世界的业务应用程序开发，Oracle公司将 Java EE技术贡献给 Eclipse基金会，Java EE将以 Jakarta EE品牌继续发展。

Jakarta EE规范是一组使全球范围内的Java开发者都能够在云原生Java企业应用程序上工作的 Java 规范。这些规范是由著名的行业领导者制定的，他们向技术开发者和消费者灌输了信心。

Jakarta EE 规范可以是一个平台规范（完整或 Web 平台），也可以是一个单独的规范。所有 Jakarta EE 规范包括：①API 和规范文档——定义和描述规范；②技术兼容性工具包（TCK），这用于测试基于API和规范文档实现的代码。

Jakarta EE规范内容包括Jakarta EE Platform、Jakarta EE Web Profile、Jakarta Activation、Jakarta Annotations、Jakarta Authentication、Jakarta Authorization等40余个。

与本书的应用案例相关的规范有如下这些。

■ Jakarta EE Platform，定义了一个托管Jakarta EE应用程序的平台。

■ Jakarta Contexts and Dependency Injection，声明性依赖注入和支持服务。

■ Jakarta Dependency Injection，公共声明性依赖注入注解。

■ Jakarta JSON Binding，用于转换POJO与JSON文档的绑定框架。

■ Jakarta JSON Processing，用于解析、生成、转换和查询JSON文档的API。

■ Jakarta Messaging，通过松散耦合、可靠的异步服务传递消息。

■ Jakarta Persistence，持久性管理和对象/关系映射。

■ Jakarta RESTful Web Services，用于开发遵循REST模式的Web服务的API。

■ Jakarta Security，定义了创建安全应用程序的标准。

■ Jakarta Transactions，允许处理与X/Open XA规范一致的事务。

■ Jakarta WebSocket，用于WebSocket协议的服务器和客户端端点的API。

（2）Eclipse MicroProfile规范

Eclipse MicroProfile是一个开发Java微服务的基础编程模型，它致力于定义企业Java微服务规范，MicroProfile 提供了指标、API 文档、运行状况检查、容错、JWT、Open API 与分布式跟踪等能力，使用它创建的云原生微服务可以自由地部署在任何地方。Eclipse MicroProfile是由群供应商和社区成员开发的在微服务体系结构中使用 Java EE的新规范，这些规范可以被添加到将来的 Java EE 版本中。许多创新的“微服务”企业 Java 环境和框架已经存在于 Java生态系统中。这些项目正在创建新的特性和功能来解决微服务体系结构的问题——利用Jakarta EE/Java EE和非Jakarta EE技术。

MicroProfile 4.0（截至 2020 年 11 月 20 日）的规范有如下内容：CDI 2.0、Config 2.0、Fault Tolerance 3.0、Health 3.0、JWT RBAC 1.2、Metrics 3.0、Open API 2.0、Open Tracing 2.0、Rest Client 2.0等。还有两个规范在规划中，分别是MicroProfile Reactive Streams Operators和MicroProfile Reactive Messaging。

与本书的应用案例相关的规范标准有如下这些。

■ Config 2.0：提供一种独立于配置源的将配置数据中继到应用程序中的统一方法。

■ Fault Tolerance 3.0：容错，包括使微服务对网络或它们所依赖的其他服务的故障具有弹性的机制，例如定义远程服务调用的超时时间，在发生故障的情况下重试策略及设置回退方法。

■ Health 3.0：健康，报告服务是否健康。这对于像 Kubernetes 这样的调度程序来确定是否应终止一个应用程序（容器）并启动一个新应用程序来说非常重要。

■ JWT RBAC 1.2：JSON Web 令牌（JWT）是基于令牌的身份验证/授权系统，该系统允许基于安全令牌进行身份验证、授权。JWT传播定义了与Java EE样式基于角色的访问控制一起使用的JWT的互操作性和容器集成需求。

■ Metrics 3.0：指标，处理遥测数据及如何以统一的方式显示遥测数据。这包括来自底层Java虚拟机的数据及来自应用程序的数据。

■ Open API 2.0：一种记录数据模型和 REST API 的方法，以便机器可以读取它们并自动从该文档构建客户端代码。OpenAPI源自Swagger规范。

■ Open Tracing 2.0：一种跨一系列微服务的分布式调用跟踪机制。

■ MicroProfile Reactive Streams Operators：响应式流操作规范。

■ MicroProfile Reactive Messaging：响应式消息规范。

（3）UML规范

UML（Unified Modeling Language，统一建模语言）是一种标准语言，用于指定、可视化、构造和记录软件系统的软件组件。UML 由对象管理组（OMG）创建，其最初用来捕获复杂软件和非软件系统的行为，现在已经成为OMG的标准。

本书在绘制类图（Class Diagram）、序列图（Sequence Diagram）和通信图（Communication Diagram）的案例中都使用了UML 2.0规范（会有特别标注）。

2.4.4 应用案例的演示和调用

编程时采用不同的 IDE工具，处理方式稍微有一些不同。笔者主要采用 Eclipse作为 IDE工具，但不排除采用其他IDE工具。下面分别介绍不同的IDE工具打开项目的方式。

1.IDE为Eclipse工具时的用法

在Eclipse中导入Maven工程项目程序，然后进入如图2-38所示的开发编程界面。由于项目较多，在导入 Maven 程序的过程中，可能会有一定的等待时间，当然也可以导入单个项目。

在该 Eclipse 环境下，可以阅读、查看、运行、调试和验证各个案例项目。可以在 Eclipse中执行菜单命令来启动案例项目，也可以直接在案例程序目录中调用Quarkus 开发模式的命令。

2.IDE是IDEA工具时的用法

在IDEA中导入Maven工程项目程序，然后进入如图2-39所示的开发编程界面。

在该IntelliJ IDEA环境下，可以阅读、查看、运行、调试和验证各个案例项目。启动案例项目需要在案例程序目录中调用 Quarkus 开发命令。注意，IntelliJ IDEA可能不支持执行菜单命令来启动案例项目的方式。

2.4.5 应用案例的解析说明

为了便于理解，下面对应用案例做一些指导说明并介绍一些原则。若能明白这些指导说明和原则，就能更轻松、方便、高效地理解各个案例的核心含义。

1.每个案例的构成

每个案例基本都由介绍案例、编写案例和验证案例3个部分组成，但个别案例有一定的特殊性，比如可能会多一些扩展性说明和阐述。如讲解案例 031-quarkus-sample-orm-hibernate时，该案例代码只针对 PostgreSQL 数据库进行了配置，但也还会简单介绍如何配置其他关系型数据库，该案例代码只实现了基于Hibernate的ORM框架，但也还会增加其他一些ORM框架的解释。

2.每个案例都有对应的源码程序的编号

程序案例的命名方式是编号加上案例特征属性，如程序案例 020-quarkus-sample-rest-json中的 020是编号，而 quarkus-sample-rest-json是案例特征属性。案例特征属性表明该案例要实现的目标，如 quarkus-sample-rest-json表明这是一个基于 Quarkus 的实现了 REST和 JSON结合的程序。编号仅作为排序和归类使用，没有其他含义。在案例的具体讲解中，有可能会忽略编号。

3.每个案例的程序源码的构成元素

程序源码的构成元素包括配置文件、Java应用程序源码文件、资源文件等。

（1）所有案例都有配置文件。一般只有 application.properties 文件，不排除有些程序可能会有附加的配置文件。例如，与数据库操作相关的有数据初始化文件 import.sql，与安全相关的有用户认证文件等。

（2） Java 应用程序源码文件。一般程序基本上至少由 5 个类文件组成，分别是ProjectMain、ProjectResource、ProjectService、Project 和 LoggingFilter 类。特殊情况下，如WebSocket案例，仅有WebSocketMain和ChatSocket两个类文件。

（3）资源文件。资源文件包括页面文件（如 index.htm）、js 文件和一些其他资源文件。由于案例的验证都采用 cURL 工具进行输入，故很少使用页面来处理。特殊情况下，只有WebSocket案例，必须通过页面来验证。

在讲解案例的程序源码时，不会对每个源码文件都进行一一讲解。每个案例项目都会有一个“程序配置文件和核心类”说明，只针对其中核心的、重要的源码文件进行解析说明。对于要讲解的源码文件，为了篇幅不过长，会略去不重要或不必要的部分。本书中所列的源码文件内容以实现案例程序的源码文件为准。

4.验证程序时输入数据的格式可能有所不同

在验证程序的过程中，本书案例都采用 Windows 的命令行窗口作为输入终端，所以输入的数据格式都是按照Windows的命令行终端规范来编写的。但对于Bash Shell和PowerShell终端，有可能需要数据格式上的调整，这点需要注意，尤其是Maven和cURL工具的输入。

为了方便验证程序，每个程序都有一个 quarkus sample test cmd 文本文件，其中列出了需要的测试和验证命令。同时，在某些案例程序上，笔者也编写了一个针对该案例程序的批处理验证命令文件，该命令文件是用ANSI编码（非UTF-8编码）编写的，可支持中文输入。这样就可以一次性验证所有内容了。

5.绘制图形说明

为了尽快、准确、容易地理解案例，笔者为每个案例都配备了图示。图示分为静态图和动态图，一般案例都会有一张核心静态图，即应用架构图。对于案例的动态图，笔者会根据案例讲解的需要和方便读者理解，采用序列图、通信图、程序执行过程图或服务调用过程图等。

应用架构图是笔者为了清楚描述案例总体结构而创建的一种图示，下面以一个实际案例来进行说明，例如某个应用架构图如图2-40所示。

首先解释一下图2-40中各个编号的含义。

编号①是外部工具，笔者一般采用的是cURL工具。

编号②是该案例程序的边界，框内的内容都是案例程序的内容。

编号③是该案例程序的名称，例如图 2-40 中案例的名称是 quarkus-sample-reactive-sqlclient，实际上这也是案例的应用程序名（去掉了编号）。

编号④是该案例程序的程序文件，也就是程序源码。例如图 2-40 中的案例有ProjectResource 和 ProjectService 类文件，虽然还有 PgPool，但这是一个外部输入对象，其表现在程序源码文件中会是一个外部注入对象，故没有类文件。

编号⑤是该案例程序依赖的关键或核心框架或 Quarkus 扩展组件，由于任何一个案例程序依赖的框架和 Quarkus 扩展组件都非常多，因此在讲解时只会针对当前案例所讲述的内容列出相关内容，这部分内容一般不可见。笔者一般会在介绍基础知识或科普常识时简单介绍一下这些框架的内容及功能。例如图 2-40 中的案例所依赖的框架只列出了 SmallRye Mutiny 框架和Eclipse Vert.x框架，主要原因是这个案例主要讲解响应式编程的内容。

编号⑥是该案例程序验证或演示所需的外部组件，这也是前面介绍的与应用案例相关的软件。笔者在讲解案例时，会简单讲解外部组件的安装和初始化配置，让读者能够演示或验证案例程序。例如，图2-40中案例的外部组件就是PostgreSQL数据库。

另外，应用架构图对象之间有包含关系、依赖关系和流向（访问/返回）关系。

（1）如果是大框包含小框，表明是包含关系。例如图 2-40 中的 quarkus-sample-reactive-sqlclient程序和ProjectResource文件之间的关系。

（2）如果一条线两端都是圆球，表明两者存在依赖关系。例如图 2-40 中的 PgPool 和Eclipse Vert.x框架之间的关系。

（3）如果是单实线箭头，表明是调用（访问）关系。例如图 2-40 中的 ProjectResource 对于ProjectService就是调用（访问）关系。

（4）如果是单虚线箭头，表明是数据流向（返回）关系。例如图 2-40 中的 ProjectService对于ProjectResource就是数据流向（返回）关系。