JAX-RS

JAX-RS是JAVA EE6 引入的一个新技术。 JAX-RS即Java API for RESTful Web Services，是一个Java 编程语言的应用程序接口，支持按照表述性状态转移（REST）架构风格创建Web服务。像JDBC一样，JAX-RS只是一个规范，基于JAX-RS实现的框架有Jersey，RESTEasy，CXF等。

JSR311对应的是JAX-RS 1.x版本，JSR339对应2.0版本的规范。

JAX-RS 定义的 API 位于 javax.ws.rs 包中，其中一些主要的接口、标注和抽象类。

规范内容

JAX-RS提供了一些标注将一个资源类，一个POJOJava类，封装为Web资源。标注包括：

@Path，标注资源类或方法的相对路径
@GET，@PUT，@POST，@DELETE，标注方法是用的HTTP请求的类型
@Produces，标注返回的MIME媒体类型
@Consumes，标注可接受请求的MIME媒体类型
@PathParam，@QueryParam，@HeaderParam，@CookieParam，@MatrixParam，@FormParam,分别标注方法的参数来自于HTTP请求的不同位置，例如@PathParam来自于URL的路径，@QueryParam来自于URL的查询参数，@HeaderParam来自于HTTP请求的头信息，@CookieParam来自于HTTP请求的Cookie。

JAX-RS的实现

JAX-RS的实现包括：

Apache CXF，开源的Web服务框架。
Jersey，由Sun提供的JAX-RS的参考实现。
RESTEasy，JBoss的实现。
Restlet，由Jerome Louvel和Dave Pawson开发，是最早的REST框架，先于JAX-RS出现。
Apache Wink，一个Apache软件基金会孵化器中的项目，其服务模块实现JAX-RS规范

Resource 资源

示例代码

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28


@Path("/books")
public class BookResource {

    @GET
    @Consumes("text/plain")
    @Produces("text/plain")
    public String getHello(String message) {
        return message;
    }

    @GET
    public List<Book> getBooks() {...}

    @GET
    @Path("/{id}")
    public Book getBook(@PathParam("id") String id) {...}

    @POST
    public void addBook(Book book) {...}

    @PUT
    @Path("/{id}")
    public void editBook(@PathParam("id") String id, Book book) {...}

    @DELETE
    @Path("/book/{id}")
    public void removeBook(@PathParam("id") String id {...}
}

上传文件，单文件

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


// 字节数组
@POST
@Path("/upload")
@Consumes("text/plain")
public void uploadFile(byte[] files) {...}

// 字节流
@POST
@Path("/upload")
@Consumes("text/plain")
public void uploadFile(InputStream is) {...}

// 字符流
@POST
@Path("/upload")
@Consumes("text/plain")
public void uploadFile(Reader reader) {...}

// 文件对象
@POST
@Path("/upload")
@Consumes("text/plain")
public void uploadFile(File file) {...}

多文件上传，需要实现库才有支持，比如RESTeasy

1
2
3
4


// org.jboss.resteasy.plugins.providers.multipart.MultipartFormDataInput
@POST
@Consumes(MediaType.MULTIPART_FORM_DATA)
public void uploadFile(MultipartFormDataInput input) {...}

获取文件

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


@GET
@Produces("text/plain")
public byte[] getFile(@QueryParam("filepath") String path) {...}

@GET
@Produces("text/plain")
public StreamingOutput getFile(@QueryParam("filepath") String path) {...}

@GET
@Produces("text/plain")
public InputStream getFile(@QueryParam("filepath") String path) {...}

@GET
@Produces("text/plain")
public File getFile(@QueryParam("filepath") String path) {...}

@Path 路径

用于配置URI路径

支持变量，这些变量在运行时被替换，以便资源根据替换的URI响应请求。变量用{}表示。

可以用在类上，类里面的方法，相当于都有个父路径。

1

@Path("/users/{username}")

支持正则表达式

1

@Path("users/{username: [a-zA-Z][a-zA-Z_0-9]*}")

@GET，@PUT，@POST，@DELETE … HTTP方法

对应http的访问方法

默认情况下，如果未明确实现，JAX-RS运行时将自动支持HEAD和OPTIONS方法。

@Produces & @Consumes

指定MIME媒体类型

@Produces 表示返回客户端的类型 @Consumes 表示接收客户端的类型

@*Param 参数

@PathParam 取@Path中变量的参数如 /books/{id}
@QueryParam 取URL?后面的参数如 /books?author=xxx&country=xxx
@MatrixParam 取;分割的参数如 /books;author=xxx;country=xxx
@HeaderParam 取请求头里面的参数
@CookieParam 取请求Cookie的参数
@FormParam 取内容类型为"application/x-www-form-urlencoded"的参数

@DefaultValue 可以指定默认值

1
2
3
4


@GET
public String get(@DefaultValue("1") @QueryParam("page") int page,
                  @DefaultValue("10") @QueryParam("size") int size)
}

@BeanParam 可以聚合所有的参数

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


@POST("/{id}")
public void post(@BeanParam MyBeanParam beanParam) {
    ...
}

public class MyBeanParam {
    @PathParam("id")
    private String id;

    @QueryParam("page")
    @DefaultValue("1")
    private int page;

    @QueryParam("size")
    @DefaultValue("10")
    private int size;

    @HeaderParam("authorization")
    private String authorization;

    ...set ...get
}

@Context 上下文

可用于获取与请求或响应相关的上下文Java类型

1
2
3
4
5
6
7


// 获取uri信息
@GET
public String get(@Context UriInfo ui) {...}

// 获取访问信息
@GET
public String get(@Context Request request) {...}

使用servlet部署JAX-RS应用程序时，可以使用@Context使用 ServletConfig， ServletContext， HttpServletRequest 和 HttpServletResponse。

异常

通用异常

1

throw new WebApplicationException("error message", Response.Status.NOT_FOUND);

自带异常类

BadRequestException 400
NotAuthorizedException 401
ForbiddenException 403
NotFoundException 404
NotAllowedException 405
NotAcceptableException 406
NotSupportedException 415
InternalServerErrorException 500
ServiceUnavailableException 503

全局异常统一处理

1
2
3
4
5
6
7


@Provider
public class EntityNotFoundMapper implements ExceptionMapper<EntityNotFoundException> {
    @Override
    public Response toResponse(EntityNotFoundException e) {
        return Response.status(Response.Status.NOT_FOUND).build();
    }
}

过滤器 & 拦截器

@Priority(1000) 可设置优先级，请求优先最小，响应优先最大。

Filters

过滤器主要用于操纵请求和响应参数，例如HTTP头，URI和/或HTTP方法

请求过滤

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


@Provider
@PreMatching
public class BearerTokenFilter implements ContainerRequestFilter {
    @Override
    public void filter(ContainerRequestContext ctx) throws IOException {
        String authHeader = request.getHeaderString(HttpHeaders.AUTHORIZATION);
        if (authHeader == null) throw new NotAuthorizedException("Bearer");
        String token = parseToken(authHeader);
        if (verifyToken(token) == false) {
            throw new NotAuthorizedException("Bearer error=\"invalid_token\"");
        }
    }
    private String parseToken(String header) {...}
    private boolean verifyToken(String token) {...}
}

响应过滤

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


@Provider
public class CacheControlFilter implements ContainerResponseFilter {
    @Override
    public void filter(ContainerRequestContext req, ContainerResponseContext res) throws IOException {
        if (req.getMethod().equals("GET")) {
            CacheControl cc = new CacheControl();
            cc.setMaxAge(100);
            req.getHeaders().add("Cache-Control", cc);
        }
    }
}

Interceptor

拦截器主要用于通过操纵实体输入/输出流来操纵实体。

输入拦截

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


@Provider
public class GZIPEncoder implements WriterInterceptor {
    @Override
    public void aroundWriteTo(WriterInterceptorContext ctx) throws IOException, WebApplicationException {
        GZIPOutputStream os = new GZIPOutputStream(ctx.getOutputStream());
        ctx.getHeaders().putSingle("Content-Encoding", "gzip");
        ctx.setOutputStream(os);
        ctx.proceed();
        return;
    }
}

输出拦截

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


@Provider
public class GZIPDecoder implements ReaderInterceptor {
    @Override
    public Object aroundReadFrom(ReaderInterceptorContext ctx) throws IOException {
        String encoding = ctx.getHeaders().getFirst("Content-Encoding");

        if (!"gzip".equalsIgnoreCase(encoding)) {
            return ctx.proceed();
        }

        GZipInputStream is = new GZipInputStream(ctx.getInputStream());
        ctx.setInputStream(is);

        return ctx.proceed(is);
    }
}

Client API 客户端API

这是用于与RESTful Web服务通信的基于Java的流畅API。此标准API也是Java EE 7的一部分，旨在使使用HTTP协议公开的Web服务变得非常容易，并使开发人员可以简洁高效地实现可移植的客户端解决方案，这些解决方案利用了现有的和完善的客户端HTTP连接器实现。

示例

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


Client client = ClientBuilder.newBuilder()
                .readTimeout(5000, TimeUnit.MILLISECONDS)
                .register(new ClientInterceptor())
                .build();

String entity = client.target("http://example.com/rest")
            .path("resource")
            .queryParam("name", "John")
            .request(MediaType.TEXT_PLAIN_TYPE)
            .header("some-header", "true")
            .get(String.class);

1.创建和配置客户端实例

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19



// 最简单的创建
Client client = ClientBuilder.newClient();

// 注册过滤器、配置超时时间
Client client = ClientBuilder.newBuilder()
                .readTimeout(5000, TimeUnit.MILLISECONDS)
                .register(new ClientInterceptor())
                .build();

class ClientInterceptor implements ClientRequestFilter, ClientResponseFilter {
    @Override
    public void filter(ClientRequestContext requestContext) throws IOException {
    }

    @Override
    public void filter(ClientRequestContext requestContext, ClientResponseContext responseContext) throws IOException {
    }
}

2.定位网络资源

有了Client实例后，您可以从中创建一个WebTarget。

一个Client包含几个target(…)方法，即允许创建的 WebTarget实例。

1

WebTarget webTarget = client.target("http://example.com/rest");

3.识别WebTarget上的资源

假设我们有一个webTarget指向"http://example.com/rest"URI 的指针，该URI表示RESTful应用程序的上下文根，并且在URI上公开了一个资源 “http://example.com/rest/resource"。如前所述，WebTarget 实例可以用于派生其他Web目标。使用以下代码定义资源的路径。

1

WebTarget resourceWebTarget = webTarget.path("resource");

假设resource资源接受了用于GET，并定义了name字段的请求查询参数。

1

resourceWebTarget = resourceWebTarget.queryParam("name", "John");

假设resource资源路径中定义了一个{id}变量参数

1

resourceWebTarget = resourceWebTarget.resolveTemplate("id", id)

4.调用HTTP请求

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


// 定义资源返回的媒体类型
Invocation.Builder invocationBuilder = resourceWebTarget.request(MediaType.TEXT_PLAIN_TYPE)
                                                        .header("some-header", "true"); // 设置请求头
// get请求，同步
Response response = invocationBuilder.get();
// post请求，同步
Response response = invocationBuilder.post(Entity.json(json));

// 获取返回状态
System.out.println(response.getStatus());
// 获取返回数据
System.out.println(response.readEntity(String.class));

5.异步请求

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31


Client client = ClientBuilder.newClient();

// 1. Future GET请求 回调处理
Future<Response> future = client.target("http://foobar.com/orders/456")
                                .request()
                                .async()
                                .get();

client.target("http://foobar.com/orders/456")
      .request()
      .async()
      .get(new InvocationCallback<Order>() {
        @Override
        public void completed(Order o) {
            // 完成后做什么
        }

        @Override
        public void failed(Throwable throwable) {
            // 失败后做什么
        }
      });

// 2. CompletionStage
CompletionStage<Response> completionStage = client.target("http://foobar.com/orders/456")
                                                  .request()
                                                  .rx()
                                                  .get() // get请求
                                                //.delete(); // delete请求
                                                //.post(Entity.json(json)); // post请求的body
                                                //.put(Entity.json(json)); // put请求的body

RESTEasy实现例子

JBoss的实现

gradle

build.gradle

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


plugins {
    id 'java'
    id 'war'
    id 'org.gretty' version '3.0.2'
}

group = 'com.example'
version = '0.0.1-SNAPSHOT'
sourceCompatibility = '11'

repositories {
    jcenter()
    mavenCentral()
    mavenLocal()
}

dependencies {
    compileOnly group: 'org.projectlombok', name: 'lombok', version: '1.18.12'
    annotationProcessor group: 'org.projectlombok', name: 'lombok', version: '1.18.12'
    implementation group: 'org.jboss.resteasy', name: 'resteasy-jackson2-provider', version: '4.5.6.Final'
    implementation group: 'org.jboss.resteasy', name: 'resteasy-client', version: '4.5.6.Final'
    implementation group: 'javax.servlet', name: 'javax.servlet-api', version: '4.0.1'
}

settings.gradle

1

rootProject.name = 'demo'

项目结构

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


├── build.gradle
├── settings.gradle
└── src
    ├── main
    │   ├── java
    │   │   └── com
    │   │       └── example
    │   │           └── demo
    │   │               ├── HelloWorld.java
    │   │               ├── HelloWorldApplication.java
    │   │               └── HelloWorldResource.java
    │   └── webapp
    │       └── WEB-INF
    │           └── web.xml
    └── test
        └── java
            └── com
                └── example
                    └── demo
                        └── TestClient.java

java包类

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30


// HelloWorldApplication.java
public class HelloWorldApplication extends Application {

    @Override
    public Set<Class<?>> getClasses() {
        Set<Class<?>> s = new HashSet<>();
        s.add(HelloWorldResource.class);
        return s;
    }
}

// HelloWorldResource.java
@Path("/helloworld")
public class HelloWorldResource {

    @GET
    @Produces("application/json")
    public HelloWorld get(@QueryParam("name") String name) {
        return new HelloWorld(name);
    }
}

// HelloWorldResource.java
@Setter
@Getter
@AllArgsConstructor
@NoArgsConstructor
public class HelloWorld {
    private String name;
}

web.xml

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


<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">
    <filter>
        <filter-name>RESTEasy</filter-name>
        <filter-class>
            org.jboss.resteasy.plugins.server.servlet.FilterDispatcher
        </filter-class>
        <init-param>
            <param-name>javax.ws.rs.Application</param-name>
            <param-value>com.example.demo.HelloWorldApplication</param-value>
        </init-param>
    </filter>

    <filter-mapping>
        <filter-name>RESTEasy</filter-name>
        <url-pattern>/*</url-pattern>
    </filter-mapping>

</web-app>

启动

gradle启动

gradle -> tasks -> gretty -> appRun

访问

http://localhost:8080/demo/helloworld?name=helloword

测试

运行时先注释掉测试类，否则测试肯定不通过，导致运行不起来

TestClient.java

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


public class TestClient {

    @Test
    public void client() {
        Client client = ClientBuilder.newClient();
        HelloWorld helloWorld = client.target("http://localhost:8080/demo")
                .path("/helloworld")
                .queryParam("name", "test")
                .request()
                .get(HelloWorld.class);
        Assert.assertNotNull(helloWorld);
        Assert.assertEquals("test", helloWorld.getName());
    }
}

文章目录