跳转到主要内容

如何使用Jakarta EE构建RESTful Web服务

这篇指南将提供给您如何使用 Jakarta EE建立 RESTful web service 程序的相关指导.

我们首先概述一下我们将要做哪些工作，以便使用 Jakarta EE, 建立RESTful web service程序.

我们将建立一个服务，该服务在 http://localhost:8080/restfulservice/hello 接收一个HTTP GET1 请求。

这个请求返回一个带有JSON数据的响应，其内容如下：

{"text": "Hello from Jakarta EE"}

之后可以根据我们的需要进行定制和改进。

OK，我们已经明确了我们的需求，您将按照以下步骤开始编程。

建立开发环境

  • 安装Java开发工具包(JDK). 要确定是 Java SE 8 或者 更高版本 (我们已经用Java SE 8, Java SE 11 and Java SE 17进行了测试). 您可以从Adoptium 选择您需要的软件发行版.
  • 按照支持Jakarta EE的应用服务器. 可以下载Jakarta EE兼容产品.
  • 安装 Maven 3 或更高版本

我们可以使用SDKMan 安装以上所列的程序，我们可以按照指南 的内容了解各个步骤内容.

如何完成这个指南的内容

在这个入门指南里，您可以使用对应Jakarta EE的Eclipse Starter完成每一步，也可以跳过您已经了解的一些基本的设置步骤。您也可以使用IDE，或者使用我们熟悉的 Maven archetypes通过选择一个相应的工程完成以上工作。

使用对应Jakarta EE的Eclipse Starter建立一个新的工程

我们将按照一下步骤使用对应Jakarta EE的Eclipse Starter：

  1. 导航选择start.jakarta.ee.建立应用的所有基本依赖。Starter的当前版本仅支持Maven. 将来我们可以Gradle and Maven.
A screenshot of the Generate a Jakarta EE Project form with fields filled out. More details on how to go through the form below.

  1. 从选项中选择Jakarta EE需要版本.到目前选项包括Jakarta EE 8, Jakarta 9.1, and Jakarta 10. 您可以从平台中选择Jakarta EE profile,Core, or Web. However, 通常，未来保险起见，您可以选择默认选项.

  2. 之后选择该工程的Group, Artifact and Version.

  3. 做完以上工作，下面的文本框让您拷贝一个命令。打开终端，粘贴这个命令文本，并纸执行

mvn archetype:generate -DarchetypeGroupId=org.eclipse.starter -DarchetypeArtifactId=jakartaee10-minimal -DarchetypeVersion=1.1.0 -DgroupId=org.eclipse.rest -DartifactId=rest-service -Dprofile=web-api -Dversion=1.0.0-SNAPSHOT -DinteractiveMode=false

这个命令将给我们提供工程结构和代码样例，我们可以构建代码并执行。

让我们浏览一下代码结构

当我们打开生成的代码，我们将看到如下代码结构：

.
├── pom.xml
└── src
    ├── main
    │   └── java
    │       └── org
    │           └── eclipse
    │               └── restfulservice
    │                   ├── ApplicationConfig.java
    │                   └── resources
    │                       ├── Hellorecord.java
    │                       └── RestResource.java
    ├── resources
    │   └── META-INF
    │       └── beans.xml
    └── webapp

在这个代码结构中，除开其他的类和设置文件，我们对两个类尤其关注： RestResource.java 和HelloRecord.java.

我们首先打开 RestResource.java文件。

package org.eclipse.restfulservice.resources;

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

@Path("hello")
public class RestResource {

    @GET
    @Produces(MediaType.APPLICATION_JSON)
    public HelloRecord hello(){
        return new HelloRecord("Hello from Jakarta EE");
    }
}

这里定义了一个RESTful web服务，当一个 GET 请求到 "/hello"访问点，这个服务返回 RestResource 的一个 JSON 表示。

 jakarta.ws.rs.Path 注解在一个用户提供的URL地址与处理请求的 Java 类之间建立联系.  jakarta.ws.rs.GET 注解让我们要使用 HTTP GET 方法访问我们的访问点。jakarta.ws.rs.Produces 注解允许您规定访问应答的格式。在这个例子中，通过转换 HelloRecord对象生成一个 JSON2 应答。

 hello() 方法返回一个 HelloRecord对象，这是Java 16新提供的记录类（record class ）。

package org.eclipse.restfulservice.resources;

public record HelloRecord(String text) {
}

如果您使用了低版本的java，您可以把它转换成传统的POJO3 。

package org.eclipse.restfulservice.resources;

public final class HelloRecord {
  private final String text;

  public HelloRecord(String text) {
    this.text = text;
  }

  public String text() {
    return text;
  }
}

从CLI运行工程

在这个工程结构并没有包括运行时容器，这样做的优点是我们可以有很多运行时容器选择，兼容 Jakarta EE的清单运行时容器详见 这里找到。

我们在这个指南里使用了WildFly。

为此，我们在 pom.xml 文件中增加一个plugin元素.

<plugin>
  <groupId>org.wildfly.plugins</groupId>
  <artifactId>wildfly-maven-plugin</artifactId>
  <version>2.1.0.Beta1</version>
  <executions>
    <execution>
      <phase>install</phase>
      <goals>
        <goal>deploy</goal>
      </goals>
    </execution>
  </executions>
</plugin>

在 pom.xml文件的plugin区域中要包含以上所示的plugin内容。

 wildfly-maven-plugin 用来部署、重新部署、反部署或者运行 Jakarta EE 应用。也可以执行CLI命令. 这个plugin的完整配置可以查看这里: WildFly Maven Plugin – Introduction.

有很多个方法配置一个本地的WildFly实例，部分配置的例子查看这里: WildFly Maven Plugin – Run Example.

但是，本指南使用的是默认配置，这已经足够了。

特别地，我们主要关注 wildfly:run CLI 命令，让我们从命令行运行以下命令:

mvn clean package wildfly:run

以上命令将构建应用并部署到Wildfly，如果 Wildfly 没安装，它将下载下载并运行Wildfly，之后部署war文件.

一旦应用运行起来，我们在终端上将看到以下输出:

[INFO] Scanning for projects...
[INFO]
[INFO] ------------------in< org.eclipse:restfulservice >---------------------
[INFO] Building restfulservice 1.0.0-SNAPSHOT
[INFO] --------------------------------[ war ]---------------------------------
[INFO]
.....
skipped the log for brevity 
.....
03:35:02,323 INFO [org.jboss.resteasy.resteasy_jaxrs.i18n] (ServerService Thread Pool -- 32) RESTEASY002225: Deploying jakarta.ws.rs.core.Application: class org.eclipse.restfulservice.ApplicationConfig
03:35:02,346 INFO [org.wildfly.extension.undertow] (ServerService Thread Pool -- 32) WFLYUT0021: Registered web context: '/restfulservice' for server 'default-server'
03:35:02,365 INFO [org.jboss.as.server] (management-handler-thread - 1) WFLYSRV0010: Deployed "restfulservice.war" (runtime-name : "restfulservice.war")

让我们测试这个服务

现在服务已经运行了，让我们访问 http://localhost:8080/restfulservice/hello.
它将返回以下内容:

{ "text": "Hello from Jakarta EE" }

要不，我们可以在命令行使用 curl:

curl -v http://localhost:8080/restfulservice/hello

*   Trying 127.0.0.1:8080...
* Connected to localhost (127.0.0.1) port 8080 (#0)
> GET /restfulservice/hello HTTP/1.1
> Host: localhost:8080
> User-Agent: curl/7.86.0
> Accept: */*
>
* Mark bundle as not supporting multiuse
< HTTP/1.1 200 OK
< Connection: keep-alive
< Content-Type: application/json
< Content-Length: 32
< Date: Sun, 18 Dec 2022 08:45:51 GMT
<
* Connection #0 to host localhost left intact
{"text":"Hello from Jakarta EE"}%

我们看一下URL结构。

http://<hostname>:<port>/<context-root>/<REST-config>/<resource-config>

在这里我们分析一下URL 格式:

Hostname: WildFly 服务器安装的机器名。

Port: WildFly 服务器监听的HTTP请求的端口. 这个端口缺省为 8080 , 但这是可以配置的。

Context-root: 进行部署的应用的根路径，默认是部署的WAR文件的文件名（不包括扩展名）。但是当文件部署完成后.这个值可以修改。

REST-config: 该值对应工程中 @ApplicationPath 注解，缺省为空，表示为 / 。我们可以在 ApplicationConfig 类中进行简单配置.

Resource-config: 该值定义在Java类的 @Path 注解. 这我们这个例子中, "/hello" is  由RestResource 类处理.

如果我们想改变 REST-config ,比如 改为"/api", 我们可以参照以下例子在 @ApplicationPath 注解中进行修改:

import jakarta.ws.rs.ApplicationPath;
import jakarta.ws.rs.core.Application;

@ApplicationPath("/api")
public class ApplicationConfig extends Application {    
}

完成如上修改后，如果我们要再次运行应用，我们要把curl命令按照如下进行修改:

curl -v http://localhost:8080/restfulservice/api/hello

结论

恭喜! 您已经学会了如何使用Jakarta EE开发一个 RESTful web 服务。

  1. HTTP GET 是一种由万维网支持的HTTP请求方法。它请求指定资源的表现形式。其一般形式为：GET /path/to/resource HTTP/1.1
  2. JSON - 它代表 JavaScript Object Notation（JavaScript对象表示法）。JSON 是一种用于存储和传输数据的文本格式。
  3. POJO - 简单Java对象（译注：即普通JavaBeans，是为了避免和EJB混淆所创造的简称）

返回顶部