RestEasy Get Started

RESTEasy是JBoss的一个开源项目，提供一套完整的框架帮助开发人员构建RESTful Web Service和RESTful Java应用程序。它是 Jakarta RESTful Web Services规范的一个完整实现，通过Http协议对外提供基于Java API的 RestFul Web Service。

Java EE 6 引入了对 JSR-311 的支持。JSR-311（JAX-RS：JavaAPI for RESTful Web Services）旨在定义一个统一的规范，使得 Java 程序员可以使用一套固定的接口来开发 REST 应用，避免了依赖于第三方框架。
2018 年初，Eclipse 将 Java EE 更名为 Jakarta EE，JAX-RS也就是现在的Jakarta RESTful Web Services。

网上想找一个RESTEasy的新手教程真的不是那么容易，大部分的文章都比较陈旧了，官方文档则是一本完善细致的工具手册，对于我这样的新手不是那么友好。其中resteasy-tutorial是唯一值得参考的。这篇文章的内容很简单，使用Tomcat运行一个RESTEasy的HelloWorld项目。需要用到的工具及RESTEasy如下所示：

1. Intellij IDEA
2. RESTEasy 4.5.2.Final
3. Tomcat 9.0.26

创建项目

使用Intellij创建一个基于Maven的项目 image.png

并引入RESTEasy所需要的依赖，如下所示

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>org.example</groupId>
    <artifactId>resteasy-demo</artifactId>
    <version>1.0-SNAPSHOT</version>

    <packaging>war</packaging>

    <properties>
        <resteasy.version>4.5.2.Final</resteasy.version>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    </properties>

    <dependencies>
        <dependency>
            <groupId>org.jboss.resteasy</groupId>
            <artifactId>resteasy-core</artifactId>
            <version>${resteasy.version}</version>
        </dependency>
        <dependency>
            <groupId>org.jboss.resteasy</groupId>
            <artifactId>resteasy-servlet-initializer</artifactId>
            <version>${resteasy.version}</version>
        </dependency>

        <dependency>
            <groupId>org.jboss.resteasy</groupId>
            <artifactId>resteasy-client</artifactId>
            <version>${resteasy.version}</version>
        </dependency>

        <dependency>
            <groupId>org.jboss.resteasy</groupId>
            <artifactId>resteasy-jaxb-provider</artifactId>
            <version>${resteasy.version}</version>
        </dependency>

    </dependencies>
</project>

对于Servlet的项目，是需要一个web.xml配置文件，用于声明哪个Servlet的实现类来处理哪个endpoint的请求，而resteasy-servlet-initializer依赖的引入帮助我们简化了这一步。RESTEasy提供了实现javax.server.ServletContainerInitializer接口的org.jboss.resteasy.plugins.servlet.ResteasyServletInitializer类。这个初始化类将在所有Servlet context初始化前被执行，可以用于映射servlets，filter和listener。
因此在src/main/webapp/WEB-INF/web.xml中可以不做任何配置：

<?xml version="1.0" encoding="UTF-8"?>
<web-app version="3.0" xmlns="http://java.sun.com/xml/ns/javaee"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://java.sun.com/xml/ns/javaee
     http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd">

    <display-name>RestEasy Example</display-name>

    <context-param>
        <param-name>resteasy.servlet.mapping.prefix</param-name>
        <param-value>/rest</param-value>
    </context-param>
</web-app>

这里添加的resteasy.servlet.mapping.prefix适用于在所有的请求前加一个前缀/rest，如果不需要这个前缀也可以忽略此配置。

Application

这个Application和SpringBoot中的@SpringBootApplication很相似。javax.ws.rs.core.Application是一个标准的JAX-RS类，用于提供部署时所需要的一些信息。

import javax.ws.rs.ApplicationPath;
import javax.ws.rs.core.Application;
import java.util.HashSet;
import java.util.Set;

@ApplicationPath("/rest")
public class RestEasyServices extends Application {
    private Set<Object> singletons = new HashSet<Object>();

    public RestEasyServices() {
        singletons.add(new MovieCrudService());
    }

    @Override
    public Set<Object> getSingletons() {
        return singletons;
    }
}

@ApplicationPath注解中的path和xml中定义的是相同的，用于给所有的endpoint添加一个前缀。这里我们重写了getSingletons，用于提供所有request的处理类，类似于SpringBoot中的Controller，在Restful的定义中，我们的每个request都是用于操作某种资源的，singletons.add(new MovieCrudService())中MovieCrudService就是这样的一个资源。

Resource

import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.core.Response;

@Path("/movies")
public class MovieCrudService {

    @GET
    @Path("/")
    public Response index() {
        return Response.status(200).entity("Hi").build();
    }
}

无需过多的解释，代码足够简单清晰，这个类提供了一个endpoint：.../rest/movies/，response就是一个文本Hi。

Deployment

这里使用的是Tomcat作为Servlet容器来运行这个服务，而这个Tomcat也是使用Intellij自带的 image.png 在Deployment的Tab下添加一个Artifact，也就是package后生成的war包 image.png

另外注意的一点是需要修改Application Context为/，至于Tomcat的Application Context的作用可以自行Google。

image.png

当配置完成后，便可通过Intellij来运行这个项目，运行后便可通过浏览器访问http://localhost:8082/rest/movies

image.png