用Restlet创建面向资源的服务

http://www.infoq.com/cn/articles/restlet-for-restful-service

 

Restlet项目（http://www.restlet.org）为“建立REST概念与Java类之间的映射”提供了一个轻量级而全面的框架。它可用于实现任何种类的REST式系统，而不仅仅是REST式Web服务；而且，事实证明它自从2005年诞生之时起，就是一个可靠的软件。

 

Restlet项目受到Servlet API、JSP（Java Server Pages）、HttpURLConnection及Struts等Web开发技术的影响。该项目的主要目标是：在提供同等功能的同时，尽量遵守Roy Fielding博士论文中所阐述的REST的目标。它的另一个主要目标是：提出一个既适于客户端应用又适于服务端的应用的、统一的Web视图。

 

Restlet的思想是：HTTP客户端与HTTP服务器之间的差别，对架构来说无所谓。一个软件应可以既充当Web客户端又充当Web服务器，而无须采用两套完全不同的APIs。

 

Restlet包括Restlet API和Noelios Restlet Engine（NRE）两部分，NRE是对Restlet API的一种参考实现。这种划分，使得不同实现可以具有同样的API。NRE包括若干HTTP服务器连接器（HTTP server connector），它们都是基于Mortbay的Jetty、Codehaus的AsyncWeb，以及Simple框架这些流行的HTTP Java开源项目的。它甚至提供一个适配器（adapter），使你可以在标准Servlet容器（如Apache Tomcat）内部署一个Restlet应用。

 

Restlet还提供两个HTTP客户端连接器（HTTP client connector）。它们一个是基于官方的HttpURLConnection类，一个是基于Apache的HTTP客户端库。还有一个连接器允许你容易地按REST风格通过XML文档来处理JDBC源（source）；此外，一个基于JavaMail API的SMTP连接器允许你发送内容为XML的Email。

 

Restlet API包括一些能够创建基于字符串、文件、流（stream）、通道（channel）及XML文档的表示（representation），它支持SAX、DOM及XSLT。使用FreeMaker或Apache Velocity模板引擎，你可以很容易地创建基于JSP式模板的表示（representations）。你甚至可以像普通Web服务器那样，用一个支持内容协商（content negotiation）的Directory类来返回静态文件与目录。

 

简单性（simplicity）和灵活性（flexibility）是贯穿整个框架的设计原则。Restlet API旨在把HTTP、URI及REST的概念抽象成一系列类（classes），同时又不把低层信息（如原始HTTP报头）完全隐藏起来。

 

基本概念

Restlet在术语上参照了Roy Fielding博士论文在讲解REST时采用的术语，如：资源（resource）、表示（representation）、连接器（connector）、组件（component）、媒体类型（media type）、语言（language），等等。这些术语你应该不会陌生。Restlet增加了一些专门的类（如Application、Filter、Finder、Router和Route），用以简化restlets的彼此结合，以及简化把收到的请求（incoming requests）映射为处理它们的资源。

图12-1：Restlet的类层次结构

抽象类Uniform及其具体子类Restlet，是Restlet的核心概念。正如其名称所暗示的，Uniform暴露一个符合REST规定的统一接口（uniform interface）。虽然该接口是按HTTP统一接口定义的，但它也可用于其他协议（如FTP和SMTP）。

handle是一个重要的方法，它接受两个参数：Request和Response。正如你可以从图12-1中看到的，每个暴露于网上的调用处理者（call handler）（无论作为客户端还是服务端）都是Restlet的一个子类——也就是说，它是一个restlets——并遵守这个统一接口。由于有统一接口，restlets可以非常复杂的方式组合在一起。

Restlet支持的每一个协议都是通过handle方法暴露的。这就是说，HTTP（服务器和客户端）、HTTPS、SMTP，以及JDBC、文件系统，甚至类加载器（class loaders）都是通过调用handle方法来操作的。这减少了开发者需掌握的APIs的数量。

过滤、安全、数据转换及路由是“通过把Restlet的子类链起来”进行处理的。Filters可以在处理下个restlet调用之前或之后进行处理。Filters实例的工作方式与Rails过滤器差不多，只不过Filters实例跟其他Restlet类一样响应handle方法，而不是具有一个专门的API。

一个Router restlet有许多附属的Restlet对象，它把每个收到的协议调用（incoming protocol call）路由给适当的Restlet处理器。路由（routing）通常是根据目标URI进行的。跟Rails不同的是，Restlet没有对资源层次结构（resource hierarchy）作URI规则限定，所以可以随意设置想要的URI，只要对Routers作相应编程就行了。

除了这一常见用途，Router还可用于其他用途。你可以用一个Router在多台远程机器之间以动态负载均衡的方式来转发调用。即使在这种复杂的情况下，它也一样响应Restlet的统一接口，并且可成为一个更大路由系统中的一个组件。VirtualHost类（Router的一个子类）使我们可以在同一台物理主机上运行多个具有不同域名的应用。在过去，你要引入一个前端Web服务器（如Apache的httpd）才能实现此功能；而用Restlet的话，它只是另一个响应统一接口的Router实现。

一个Application对象能够管理一组restlets，并提供常见的服务，比方说对压缩的请求进行透明解码，或者利用method查询参数在重载的POST（overloaded POST）之上实现PUT和DELETE请求。最后，Component对象可以包含并编配（orchestrate）一组Connectors、VirtualHosts及Applications（作为独立Java应用运行的，或者嵌入在一个更大系统（如J2EE环境）中的）。

在第6章，我向你介绍了“把一个问题划分为一组响应HTTP统一接口的资源”的步骤。在第7章，为了处理Ruby on Rails的简单化假设（simplifying assumptions），我对该步骤作了相应的调整。因为Restlet没有做简单化假设（simplifying assumptions），所以我们无须对此步骤进行修改。它可以实现任何REST式系统。如果你刚好想实现一个REST式面向资源的Web服务，可以按愿意的方式来组织和实现这些资源。Restlet确实提供了一些便于创建面向资源的应用的类。其中特别值得一提的是Resource类，它可作为你所有应用资源的基础。

我在本书中一直用URI模板作为一组URIs的简化表达（见第9章）。Restlet用URI模板来进行URI与资源的映射。假如用Restlet来实现第7章那个社会性书签服务的话，它也许要指定一个代表特定书签的URI：

/users/{username}/bookmarks/{URI}

你可以在把Resource子类附加到Router上时使用这种语法。假如你不相信真会这么好的话，可以等到下一节，那时我会实际实现部分书签服务。

编写Restlet客户端

在示例2-1中，你看到的是一个从Yahoo!搜索服务获取XML搜索结果的Ruby客户端。示例12-3是一个用Java参照Restlet 1.0实现的具有同样功能的客户端。要确保把以下JAR包写在你的classpath中，才能成功编译并运行接下来的例子：

• org.restlet.jar（Restlet API）
• com.noelios.restlet.jar （Noelios Restlet Engine核心）
• com.noelios.restlet.ext.net.jar （基于JDK的HttpURLConnection的HTTP客户端连接器）

这些JAR包可以在Restlet发布包中的lib目录里找到。要确保你的Java环境支持Java SE 5.0（或更高）版本。如果你确实需要的话，可以用Retrotranslator（http://retrotranslator. sourceforge.net/）轻易地把Restlet代码反移植（backport）到J2SE 4.0版上去。

示例12-3：Yahoo!搜索服务的一个Restlet客户端

// YahooSearch.java
import org.restlet.Client;
import org.restlet.data.Protocol;
import org.restlet.data.Reference;
import org.restlet.data.Response;
import org.restlet.resource.DomRepresentation;
import org.w3c.dom.Node;

/**
  * 用返回XML的Yahoo！搜索服务来搜索Web 
 */
public class YahooSearch {
    static final String BASE_URI = 
    "http://api.search.yahoo.com/WebSearchService/V1/webSearch";

    public static void main(String[] args) throws Exception {
        if (args.length != 1) {
            System.err.println("You need to pass a term to search");
        } else {
            // 获取一个资源，即一个包含搜索结果的XML文档
            String term = Reference.encode(args[0]);
            String uri = BASE_URI + "?appid=restbook&query=" + term;
            Response response = new Client(Protocol.HTTP).get(uri);
            DomRepresentation document = response.getEntityAsDom();

            // 用XPath找出数据结构中重要部分
            String expr = "/ResultSet/Result/Title";
            for (Node node : document.getNodes(expr)) {
                  System.out.println(node.getTextContent());
            }
        }
    }
} 

跟示例2-1一样，你可以在执行这个类时把一个搜索关键字作为命令行参数传给它。比如像下面这样：

$ java YahooSearch xslt
     XSL Transformations (XSLT) 
     The Extensible Stylesheet Language Family (XSL)
     XSLT Tutorial
          ...

该示例证明了“用Restlet从Web服务获取XML数据，并用标准工具处理它”是极其简单的事。Yahoo!资源的URI是用一个常量和用户提供的搜索关键字构造而成的。客户端连接器（client connector）是用HTTP协议来初始化的。XML文档是通过get方法获得的，该方法对应于HTTP统一接口的GET方法。当调用返回时，程序将得到一个DOM表示。跟前面的Ruby例子一样，XPath是对XML进行查询的最简单方式。

跟前面的Ruby例子一样，这个程序也忽略了XML文档里的XML名称空间（namespaces）。Yahoo!为整个文档采用名称空间urn:yahoo:srch，但我是直接引用标签的，比方说，我用ResultSet，而不是urn:yahoo:srch:ResultSet。前面的Ruby例子忽略名称空间，是因为Ruby的默认XML解析器不支持名称空间。Java的XML解析器支持名称空间，而且Restlet API令正确处理名称空间变得更加容易。虽然对上面那个简单例子来说，它们区别不大，但支持名称空间可以避免一些因名称空间而导致的微妙的问题。

当然，若一直用urn:yahoo:srch:ResultSet，是比较烦人的。Restlet API可以容易地把一个简短前缀跟一个名称空间进行关联，然后就可以在XPath表达式中使用这个简短前缀而不是整个名称空间了。示例12-4对示例12-3后半部分代码作了改动，它使用了带名称空间的Xpath，这样就不会把来自Yahoo!的ResultSet标签与来自其他名称空间的标签搞混了。

示例12-4：支持名称空间的文档处理代码

            DomRepresentation document = response.getEntityAsDom();

            // 把该名称空间与前缀‘y’关联起来
            document.setNamespaceAware(true);
            document.putNamespace("y", "urn:yahoo:srch");

            // 用XPath找出数据结构中重要部分
            String expr = "/y:ResultSet/y:Result/y:Title/text()";
            for (Node node : document.getNodes(expr)) {
                  System.out.println(node.getTextContent());
            }

示例2-15是Yahoo!搜索服务的另一个Ruby客户端。它请求的是JSON格式（而不是XML格式）的搜索数据。示例12-5是一个与之功能等价的Restlet客户端。它通过Restlet里的另两个JAR文件获取JSON支持：

• org.restlet.ext.json_2.0.jar（用于JSON的Restlet扩展）
• org.json_2.0/org.json.jar（JSON官方程序库）

示例12-5：Yahoo!的JSON搜索服务的一个Restlet客户端

// YahooSearchJSON.java
import org.json.JSONArray;
import org.json.JSONObject;
import org.restlet.Client;
import org.restlet.data.Protocol;
import org.restlet.data.Reference;
import org.restlet.data.Response;
import org.restlet.ext.json.JsonRepresentation;

/**
  * 用返回JSON的Yahoo！搜索服务来搜索Web 
 */
public class YahooSearchJSON {
    static final String BASE_URI =
    "http://api.search.yahoo.com/WebSearchService/V1/webSearch";

    public static void main(String[] args) throws Exception {
        if (args.length != 1) {
            System.err.println("You need to pass a term to search");
        } else {

            // 获取一个资源，即一个包含搜索结果的JSON文档
            String term = Reference.encode(args[0]);
            String uri = BASE_URI + "?appid=restbook&output=json&query=" + term;
            Response response = new Client(Protocol.HTTP).get(uri);
            JSONObject json = new JsonRepresentation(response.getEntity())
                     .toJsonObject();

            // 在JSON文档中寻找并显示标题
            JSONObject resultSet = json.getJSONObject("ResultSet");
            JSONArray results = resultSet.getJSONArray("Result");
            for (int i = 0; i < results.length(); i++) {
                 System.out.println(results.getJSONObject(i).getString("Title"));
            }
        }
    }
}

当你为Yahoo！的Web服务编写客户端时，可以选择表示格式（representation format）。Restlet核心API支持XML，另外还可以通过扩展支持JSON。正如你所预料的那样，这两个例子的区别仅仅在于对响应的处理上。JsonRepresentation类可以把响应实体主体（response entity-body）转换成一个JSONObject实例（而Ruby的JSON库是把JSON数据结构转换成一个本地数据结构）。该数据结构只能进行人工遍历，因为目前JSON中还没有类似XPath的查询语言。

编写Restlet服务

接下来的例子会稍微复杂一些。我将向你展示如何设计并实现一个服务端应用。在第7章，我用Ruby on Rails实现了一个书签管理应用，现在我用Restlet来重新实现其部分功能。为了简单起见，该应用只支持对用户及其书签进行安全的（safe）操作。

Java包结构是这样的：

org restlet
 example
     book
   rest
    ch7
       -Application
       -ApplicationTest
       -Bookmark
       -BookmarkResource
       -BookmarksResource
       -User
       -UserResource

也就是说，Bookmark等类都在org.restlet.example.book.rest.ch7包里。

我不打算在此展示完整的代码。如果需要，你可以去本书的官方网站（http://www.oreilly. com/catalog/9780596529260），那里提供了本书的所有示例程序代码。你也可以在restlet.org（http://www.restlet.org）上找到本例的完整代码。如果你已经下载了Restlet的话，那么也可以在src/org/restlet.example/org/restlet/example/book/rest目录里找到本节的示例代码。

我将从一些简单的代码开始。示例12-6是Application.main方法，它用来建立Web服务器，并开始处理请求。

示例12-6：Application.main方法：建立Web服务器

public static void main(String... args) throws Exception {
    // 用HTTP服务器连接器创建一个组件
    Component comp = new Component();
    comp.getServers().add(Protocol.HTTP, 3000);

    // 把应用附加到默认主机上，并启动
    comp.getDefaultHost().attach("/v1", new Application());
    comp.start();
}

资源与URI设计

由于Restlet未对资源设计作特别的限制，所以你完全可以根据ROA的设计原则来进行资源类（resource classes）及URIs的设计。在第7章，我要围绕“Rails的基于控制器的架构”来进行设计；而这里，我不需要围绕Restlet架构来进行设计。图12-2 展示了URI是如何经由Router映射到资源，再映射到下层restlet类的。

图12-2：社会性书签应用的Restlet架构

为了理解如何用Java代码实现这些映射，我们来看一下Application类及它的createRoot 方法（见示例12-7）。它跟示例7-3所示的Rails routes.rb文件在功能上是等价的。

示例12-7：Application.createRoot方法：实现URI模板到restlet的映射

public Restlet createRoot() {
    Router router = new Router(getContext());

    // 为用户资源增加路由
    router.attach("/users/{username}", UserResource.class);

    // 为用户的书签资源增加路由
    router.attach("/users/{username}/bookmarks", BookmarksResource.class);

    // 为书签资源增加路由
    Route uriRoute = router.attach("/users/{username}/bookmarks/{URI}",
                                       BookmarkResource.class);
    uriRoute.getTemplate().getVariables()
      .put("URI", new Variable(Variable.TYPE_URI_ALL));
}

在我创建一个Application对象（比如像示例12-6中的那样）时，这段代码便会运行。它会在资源类UserResource与URI模板“/users/(username)”之间建立起清晰而直观的映射关系。Router先拿请求的目标URI跟URI模板（URI templates）进行比较，然后把请求转发给一个新建的相应的资源类实例。模板变量的值被存放在请求的属性地图（attributes map）里（跟Rails例子中的params地图类似），以便于在Resource代码中使用。这既有效，又易于理解；当你事隔很久再回顾代码时，这很有帮助。

请求处理和表示

假定一个客户端向URI http://localhost:3000/v1/users/jerome发出GET请求。我有一个监听本地主机3000端口的Component对象，和一个隶属于 /v1 的Application对象。该Application有一个Router和一组Route对象，这些Route对象正等待着跟各个URI模板匹配的请求。 URI路径片段“/users/jerome”跟模板“/users/{username}”相匹配，而该模板的Route是与UserResource类（大致等价于Rails UsersController类）相关联的。

Restlet通过初始化一个新的UserResource对象，并调用它的handleGet方法来处理该请求。示例12-8是UserResource类的构造方法。

示例12-8：UserResource类的构造方法

/**
 * 构造方法
 *
 * @param context
 *           上级上下文
 * @param request
 *           要处理的请求
 * @param response
 *           要返回的响应
 */
 public UserResource(Context context, Request request, Response response) {
    super(context, request, response);
    this.userName = (String) request.getAttributes().get("username");
    ChallengeResponse cr = request.getChallengeResponse();
    this.login = (cr != null) ? cr.getIdentifier() : null;
    this.password = (cr != null) ? cr.getSecret() : null;
    this.user = findUser();

    if (user != null) {
        getVariants().add(new Variant(MediaType.TEXT_PLAIN));
    }
}

至此，这个架构已经建立了一个Request对象，它包含了我所需要的关于请求的所有信息。username属性来自URI，认证证书来自请求的Authorization报头。我还调用findUser方法来根据认证证书在数据库中查找用户（为节省篇幅，我就不在此展示findUser方法的代码了）。这些工作在第7章都是由Rails过滤器完成的。

在框架把一个UserResource实例化后，它会对资源对象调用适当的handle方法。HTTP统一接口中的每一个方法，都有一个对应handle方法。 在这个例子中，Restlet架构最后的任务是调用UserResource.handleGet。

由于我没有定义UserResource.handleGet这个方法，所以它将具有继承Resource. handleGet方法的行为。HandleGet的默认行为是找到最符合客户端要求的资源的表示。客户端通过内容协商（content-negotiation）来表达它的要求。Restlet通过Accept报头的值来决定返回哪个表示。由于这里只有一个表示格式，所以客户端的要求不起作用。这是由getVariants和getRepresentation方法处理的。由于在上述构造方法中把text/ plain定义为唯一支持的表示格式，所以我的getRepresentation方法的实现是很简单的（见示例12-9）。

示例12-9：UserResoure.getRepresentation：构造一个用户的表示

@Override
public Representation getRepresentation(Variant variant) {
    Representation result = null;

    if (variant.getMediaType().equals(MediaType.TEXT_PLAIN)) {
        // 创建一个文本表示
        StingBuilder sb=new StringBuilder();
        sb.append("------------\n");
        sb.append("User details\n");
        sb.append("------------\n\n");
        sb.append("Name:  ").append(this.user.getFullName()).append('\n');
        sb.append("Email: ").append(this.user.getEmail()).append('\n');
        result = new StringRepresentation(sb);
    }

    return result;
}

虽然这只是一个资源的一个方法，但其他资源，以及UserResource的其他HTTP方法的工作原理都差不多，比如：对用户的PUT请求将被路由给UserResource.handlePut，等等。正如我前面所提到的，这里的代码只是社会性书签应用所有代码的一部分；所以，如果你有兴趣进一步学习的话，可以去下载一个完整的示例代码来阅读。

现在，你应该了解Restlet架构是如何把收到的（incoming）HTTP请求路由给特定的Resource类，然后再路由给该类的特定方法了。你也应该知道如何由资源状态来构造表示（representations）了。一般，只要关注Application和Router代码一次就行，因为一个Router可用于你的所有资源。

编译、运行与测试

Application类实现了运行社会性书签服务的HTTP服务器。你需要在classpath中加入以下JAR文件：

• org.restlet.jar
• com.noelios.restlet.jar
• com.noelios.restlet.ext.net.jar
• org.simpleframework_3.1/org.simpleframework.jar
• com.noelios.restlet.ext.simple_3.1.jar
• com.db4o_6.1/com.db4o.jar

这些JAR包可以在Restlet发布包中的lib目录里找到。有两点需要注意：第一，Web服务器的实际工作是由一个非常紧凑的、基于Simple框架的HTTP服务器连接器来处理的；第二，我们是用强大的db4o对象数据库（而不是关系数据库）来存储领域对象（用户和书签）的。在编译好所有示例文件后，运行org.restlet.example.book.rest.ch7. Application，它将作为服务器的端点（endpoint）。

ApplicationTest类为服务提供了一个客户端接口。它采用上节描述的Restlet客户端类来添加和删除用户和书签。它是通过HTTP统一接口进行工作的：用PUT请求创建用户和书签，用DELETE请求删除用户和书签。

在命令行下运行ApplicationTest类，你将得到以下消息：

   Usage  depends  on  the  number  of  arguments:
-  Deletes  a  user                     :  userName,  password
-  Deletes  a  bookmark         :  userName,  password,  URI
-  Adds  a  new  user               :  userName,  password,  "full  name",  email
-  Adds  a  new  bookmark   :  userName,  password,  URI,  shortDescription,
                                                         longDescription,  restrict[true  /  false]

你可以用这个程序来添加一些用户，并增加一些书签。然后，你就可以在Web浏览器中通过访问适当的URI（如http://localhost:3000/v1/users/jerome等）来浏览用户书签的HTML表示了。

小结

Restlet项目在2007年初发布了1.0正式版。它只用了12个多月的开发时间。目前，该项目具有一个繁荣的开发与用户群体。Restlet邮件列表很友好，不论是新手，还是有经验的开发者，它都欢迎。作为该项目的创建者，Noelios咨询公司是主要的开发力量，他们也提供专业的支持计划与培训。

在本书编写之时，1.0版处于维护中，新的1.1版已经开始开发了。该项目计划将来把Restlet API提交给JCP（Java Community Process）。还有一个用于REST式Web服务的高层API，它已由Sun公司提交给JCP（JSR311）。这个高层API使得“把Java领域对象暴露为REST式资源”更加容易。这将是对Restlet API（尤其是其Resource类）的一个很好的补充。Noelios咨询公司是最初的专家组成员，他们将根据标准的进展来对Restlet引擎作相应的更新。

---

本文节选自博文视点出版公司即将推出的经典著作《RESTful Web Services中文版》中的第12章《REST式服务框架》。

《RESTful Web Services中文版》向读者介绍了什么是REST、什么是面向资源的架构（Resource-Oriented Architecture，ROA）、REST式设计的优点、REST式Web服务的真实案例分析、如何用各种流行的编程语言编写Web服务客户端、如何用三种流行的框架（Ruby on Rails、Restlet和Django）实现REST式服务等。不仅讲解REST与面向资源的架构（ROA）的概念与原理，还向读者介绍如何编写符合 REST风格的Web 2.0应用。本书详实、易懂，实战性强，提供了大量RESTful Web服务开发的最佳实践和指导，适合广大的Web开发人员、Web架构师及对Web开发或Web架构感兴趣的广大技术人员与学生阅读。

与此同时，博文视点还授权InfoQ中文站独家为大家提供额外的样章进行试读：欢迎下载第3章《REST式服务有什么不同》