在 RESTful 应用程序中定义资源的 URI 模式

具象状态传输 (REST) 服务依赖于处理资源。RESTful 服务的资源可寻址,并且 URL 是在 REST 中实现可寻址性的主要方法。

开始之前

标识应用程序中要作为 RESTful 服务呈示的资源。

关于此任务

URL 用来指定资源的位置。服务器与客户机之间的交互依赖于向 URL 发出 HTTP 操作。定义 URL 模式至关重要,这是因为,URL 通常具有很长的生存期,因此客户机在最初发现资源之后的很长时间内都可以直接对该资源进行寻址。

在 Web 浏览器中输入地址时,通常使用 URL,例如 http://www.ibm.com/http://www.example.com/bookstore/books/ISBN123。虽然 URL 不必被用户理解,但是,RESTful 服务以可理解的模式来提供逻辑 URL 有助于提高客户机应用程序开发者的工作效率。

RESTful 客户机使用 URL 来维护资源。每个资源都必须具有自己的唯一 URL。某些 URL 模式具有追加了唯一标识的集合路径。例如,您可以使用 http://www.example.com/bookstore/books 作为集合资源 URL,使用 http://www.example.com/bookstore/books/ISBN123 作为唯一的书籍资源 URL,并可以使用 http://www.example.com/bookstore/books/ISBN123/authors 来检索用于描述 ISBN123 作者的集合资源。

应用程序开发者必须谨慎地考虑 URL 的详细程度,这是因为,它会影响应用程序的用法以及性能。例如,可以包括书籍的作者信息作为书籍资源的组成部分,也可以将作者信息定义为具有自己的 URL(在书籍资源中引用此 URL)的独特资源。根据资源的复用情况,为作者信息定义独立的资源可能效率更高,这样,该作者编写另一书籍时,就可以在书籍资源的超链接中引用该作者信息资源。

向客户机提供初始 URL 之后,将可以通过解析当前资源来发现后续的相关请求。在书籍示例中,对 http://www.example.com/bookstore/books/ 发出的 GET 请求将检索书籍 URL 列表,该列表可能包含 http://www.example.com/bookstore/books/ISBN123

由于系统依赖于资源可用,因此 URL 的生存期通常较长。因为 HTTP 具有用于执行重定向的内置状态码,例如 301 永久移动代码和 307 临时重定向代码,所以使用了高速缓存的用户和客户机通常先复用先前发现的 URL。另外,您可以考虑在 URL 模式中包括版本标识,例如 http://www.example.com/bookstore/v2/books/ISBN123。就像使用 Java™ 代码来定义接口时涉及的规划一样,由于 URL 模式的生存期较长,因此您务必谨慎地选择 URL 模式。

在 Java API for RESTful Web Services (JAX-RS) 中,必须对 Java 类文件或 Java 方法添加 @Path 注释以定义资源的相对 URL。您可以使用 JAX-RS 子资源定位器和子资源方法来定义资源。请使用 URL 中的参数(例如路径参数或矩阵参数)来标识资源。

@Path 注释中的值定义资源的完整 URL 的相对部分。基本 URL 从域、端口、应用程序模块上下文根以及应用程序模块的 web.xml 文件中的任何 URL 模式映射派生。例如,如果域是 www.example.com,端口是 9060,模块上下文根是 example,Servlet URL 模式是 store/*,那么 @Path 注释的值将是 /bookstore/books。完整的 URL 是:http://www.example.com:9060/example/store/bookstore/books

过程

  1. 在应用程序中标识资源的类型。 假定您有两类资源,即具有以下类定义的 BooksCollection 和单个 Book 对象:
    public class BooksCollection {
        public BooksCollection() {
            /* no argument constructor */
        }
    
    }
    
    public class Book {
        public Book(String ISBN) {
            /* This constructor has an argument that will be annotated with a JAX-RS annotation.
             See the JAX-RS specification for information on valid constructors. */
        }
    }
    根据 JAX-RS 规范的定义,在缺省情况下,将为每个请求创建资源实例。对于要创建资源实例的 JAX-RS 运行时环境,必须使用不带参数的构造函数或者只包含带有 JAX-RS 注释的参数的构造函数。
  2. 对每个资源类添加 @javax.ws.rs.Path 注释。  对于每个 @javax.ws.rs.Path 注释,将值设置为应用程序的基本 URL 后的 URL 部分。
    /*
     * BooksCollection.java
     * This Java class represents the books collection URL at /bookstore/books.
     */
    @javax.ws.rs.Path("/bookstore/books/")
    public class BooksCollection {
    
    }
    在完成应用程序之后,您可以通过访问 http://<host_name>:<port>/<context_root>/<servlet_path>/bookstore/books 来使用资源。对于此 URL,请指定上下文根值作为上下文模块后面的 URL 部分。请指定 Servlet 路径作为 web.xml 文件(如果它存在)中的任何 URL 模式。
  3. (可选)确定资源是否需要将部分 URL 作为参数。 如果资源需要将部分 URL 用作参数(例如标识),那么您可以使用包含正则表达式的 @javax.ws.rs.Path 注释。然后,可以在资源构造方法或资源方法中添加 @javax.ws.rs.PathParam 注释。
    /*
     * Book.java represents individual books.
      */
    @javax.ws.rs.Path(“/bookstore/books/{bookID}”)
    public class Book {
       public Book(@javax.ws.rs.PathParam("bookID") String ISBN) {
    
       }
    }
    http://<host_name>:<port>/<context_root>/<servlet_path>/bookstore/books/ISBN_number 发出 HTTP 请求时,将创建 Book 实例并将 ISBN_number 传递给构造函数的 ISBN 参数。

    有关其他可能的参数的更多信息,请阅读“在 RESTful 应用程序中定义资源请求的参数”。

  4. 创建 javax.ws.rs.core.Application 子类,以便对 JAX-RS 运行时环境定义哪些类是 JAX-RS 应用程序的组成部分。 资源类将在 getClasses() 方法中返回;例如:
    public class BookApplication extends javax.ws.rs.core.Application {
        public Set<Class<?>> getClasses() {
            Set<Class<?>> classes = new HashSet<Class<?>>();
            classes.add(BooksCollection.class);
            classes.add(Book.class);
            return classes;
        }
    }

    通过定义 javax.ws.rs.core.Application 子类,它的方法所返回的类将向 JAX-RS 运行时环境注册。配置 web.xml 文件时,您必须指定 javax.ws.rs.core.Application 子类作为 Servlet 或过滤器的参数。有关更多信息,请参阅“为 JAX-RS 应用程序配置 web.xml 文件”。

结果

您已创建用于标识 RESTful 服务的资源的 URL。通过在应用程序设计阶段提早考虑 URL 模式问题,RESTful 服务能够长时间地提高其可用性和价值。

下一步做什么

位于所定义的 URL 处的资源存在。但是,该资源还没有任何用于处理 HTTP 方法操作(例如 GET、POST、PUT 或 DELETE)的方法。请参阅“为 RESTful 应用程序定义资源方法”以进一步了解如何使用受支持的 HTTP 方法来定义资源的功能。


指示主题类型的图标 任务主题



时间戳记图标 最近一次更新时间: last_date
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=cord&product=was-nd-mp&topic=twbs_jaxrs_defresource_uri
文件名:twbs_jaxrs_defresource_uri.html