Jakarta EE 9 入门指南：如何创建 REST API

在“入门 Jakarta EE 9”系列的第二篇博客中，我们将带您了解 Jakarta REST API 的基本使用场景。REST 或 RESTful API 通常被用来表示通过 HTTP 进行数据传输，但很多人忽略了 REST 的核心概念之一——“以超媒体作为应用状态引擎”（Hypermedia as the Engine of Application State，简称 HATEOAS）。近年来，这项技术被广泛用于连接前端和后端系统。

Jakarta REST API 配置

与 Jakarta EE 的其他规范类似，使用 Jakarta REST API 只需将 Web API 的依赖项添加到项目中即可。这将为您提供编写 Jakarta EE 应用程序所需的所有类、接口和注解。在本例中，Payara Server 提供了所有必要的代码和实现，因此您可以创建一个仅包含应用程序代码的轻量级 WAR 文件。

Maven 配置

如果您使用 Maven 作为构建工具，可以在 pom.xml 文件中添加以下依赖项：

 jakarta.platform
 jakarta.jakartaee-web-api
 9.0.0
 provided

Gradle 配置

对于 Gradle 用户，可以在 build.gradle 文件中添加以下内容：

providedCompile 'jakarta.platform:jakarta.jakartaee-web-api:9.0.0'

配置 REST 引擎

配置 Jakarta REST 框架通常只需定义触发 REST 引擎处理的 URL 部分。例如，以下 Java 类定义了应用程序的基本 URI：

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

在上述代码中，@ApplicationPath 注解指定了所有资源 URI 的基础路径。在这个例子中，/api 将成为所有端点的基础 URL 部分。

创建简单的 REST API 端点

在配置好 Jakarta REST API 后，我们可以创建一个简单的 REST API 端点。以下是一个示例代码：

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

 @GET
 @Produces(MediaType.TEXT_PLAIN)
 public String sayHello() {
 return "Hello World";
 }
}

运行结果

将上述代码编译、打包并部署到 Payara Server 或 Payara Micro 后，您可以通过以下命令访问端点：

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

返回结果如下：

Hello World

URL 结构解析

• <主机名>：运行 Payara Server 的计算机主机名。
• <端口>：Payara Server 监听的端口，默认为 8080。
• <上下文根>：部署应用程序的上下文路径，默认为 WAR 文件名（不带扩展名）。
• <REST 配置>：@ApplicationPath 注解中定义的路径。
• <资源配置>：@Path 注解中定义的路径。

读取 URL 信息

在编写 API 端点时，解析客户端请求的 URL 信息非常重要。以下示例展示了如何读取 URL 的路径参数和查询参数：

@Path("/hello/{name}")
public class HelloResource {

 @GET
 @Produces(MediaType.TEXT_PLAIN)
 public String doGreeting(@PathParam("name") String name, @QueryParam("language") String language) {
 return "Hello " + name + " in " + language;
 }
}

在上述代码中：

• {name} 是路径参数，通过 @PathParam 注解映射到方法参数。
• language 是查询参数，通过 @QueryParam 注解映射到方法参数。

例如，访问以下 URL：

http://localhost:8080/rest/api/hello/Payara?language=en

将会调用 doGreeting("Payara", "en") 方法。

JSON 支持

在生产环境中，JSON 是最常用的数据格式。以下示例展示了如何返回 JSON 数据：

public class Person {
 private String name;
 private int age;

 // 必须包含无参构造函数
 public Person() {}

 // Getter 和 Setter 省略
}

@Path("/person")
public class PersonResource {

 @GET
 @Produces(MediaType.APPLICATION_JSON)
 public Person getPerson() {
 Person person = new Person();
 person.setName("Rudy");
 person.setAge(42);
 return person;
 }
}

访问以下 URL：

http://localhost:8080/rest/api/person

将返回如下 JSON 响应：

{
 "name": "Rudy",
 "age": 42
}

默认情况下，Jakarta REST 会自动序列化 Java 对象为 JSON 数据。

发送数据到服务器

除了从服务器获取数据外，您还可以通过 POST 请求向服务器发送数据。以下是一个示例：

@Path("/person")
public class PersonResource {

 @POST
 @Consumes(MediaType.APPLICATION_JSON)
 public Response createPerson(Person person) {
 // 处理接收到的 Person 数据
 return Response.status(Response.Status.CREATED).build();
 }
}

在上述代码中：

• @POST 注解指定了 HTTP 方法。
• @Consumes 注解指定了请求体的内容类型。

控制 HTTP 状态码

在实际开发中，您可能需要根据不同的业务逻辑返回不同的 HTTP 状态码。以下示例展示了如何实现：

@Path("/number")
public class NumberResource {

 @GET
 @Path("/{value}")
 public Response checkNumber(@PathParam("value") int value) {
 if (value % 2 == 0) {
 return Response.ok("Even number").build();
 } else {
 return Response.status(Response.Status.NOT_ACCEPTABLE).entity("Odd number").build();
 }
 }
}

在上述代码中：

• 如果数字是偶数，返回状态码 200（OK）。
• 如果数字是奇数，返回状态码 406（Not Acceptable）。

结论

Jakarta REST API 提供了一种简单高效的方式来构建 RESTful 服务。通过注解，您可以轻松配置 URL 路径、HTTP 方法、请求和响应的内容类型等。

本篇文章介绍了 Jakarta REST API 的基础知识，包括如何配置 REST 引擎、创建简单的端点、处理 JSON 数据以及控制 HTTP 状态码。在未来的文章中，我们将进一步探讨 Jakarta EE 的其他功能，例如数据验证和 CDI 服务注入。

原文链接: https://blog.payara.fish/getting-started-with-jakarta-ee-9-how-to-create-a-rest-api-with-jakarta-ee-9