皇上，还记得我吗?我就是1999年那个Linux伊甸园啊-----24小时滚动更新开源资讯，全年无休！

使用模板将Web服务的结果转换为标记语言

2017-03-23 分类：开源资讯 评论(0)

作者 Greg Brown ，译者 张卫滨 

核心要点

  • HTTP-RPC是一个开源的框架，用来在Java中构建REST服务；
  • 同一个代码库，可以服务于Web、移动和桌面客户端；
  • 默认提供了JSON响应数据；
  • 通过使用模板，支持基于HTML的资源表述；
  • 同时还可以生成XML、CSV等格式。

Web服务是一种实现应用逻辑的方式，能够通过HTTP进行远程访问。它们允许分布式的客户端与服务端的功能进行交互，这些客户端通常可能是异构的，服务还经常会用来为移动应用提供后端API。但是，它们在实现的时候，往往会采用与应用程序Web前端相独立的软件栈，这样的话，就会导致额外的开发和维护成本。

模板是一种将数据与展现分离的方法。它们能够输出针对特定数据结构的格式，不过模板与数据本身是相互独立的，这样就为两者的责任画出了清晰的界限。在MVC术语中，模板代表了视图，而数据结构代表了模型。Web服务担任了控制器的角色，接受调用者的输入，生成模型数据并将模板用到模型上，从而产生最终的结果。

使用HTTP-RPC框架实现的Web服务会有相应的输出，我们可以借助CTemplate系统（也叫作Mustache）所编写的模板将输出转换为HTML。这样的话，一个应用可以同时服务于Web和移动客户端，提升了同一个代码库的使用效率，显著降低总体的开发成本。

HTTP-RPC

HTTP-RPC是一个开源框架，用于简化基于REST的应用开发。它允许开发人员创建和访问基于HTTP的服务，在这个过程中采用了一种便利的、类似于RPC隐喻的做法，同时又保持了REST的基本原则，如无状态和统一资源访问。关于HTTP-RPC的更多信息，我之前的文章进行更为全面的介绍。

HTTP-RPC服务要通过HTTP动作来进行访问，比如对目标资源的GET或POST请求。目标是通过路径来进行指定的，路径代表了资源的名称，通常会使用一个名词来组成URL，比如/calendar或/contacts。

例如，如下的请求将会得到两个数字的和，这两个数字分别是通过a和b这两个查询参数指定的：

GET /math/sum?a=2&b=4

服务将会在响应中返回6这个值。

样例服务

WebService类是一个用于HTTP-RPC Web服务的基础抽象类。我们定义服务操作的方式就是为某个具体的服务实现添加公开方法。

@RPC注解用来标记某个方法可以进行远程访问。这个注解会为方法关联一个HTTP动作和资源路径。当服务发布之后，所有带有注解的公开方法将会自动允许远程执行。

例如，如下的类可以用于实现我们前文所述的简单加法操作：

public class MathService extends WebService {
    @RPC(method="GET", path="sum")
    public double getSum(double a, double b) {
        return a + b;
    }
}

如下的方法展示了另外一个样例，它会计算一个集合的简单统计值：

@RPC(method="GET", path="statistics")
public Map<String, ?> getStatistics(List<Double> values) {
    int count = values.size();

    double sum = 0;

    for (double value : values) {
        sum += value;
    }

    double average = sum / count;

    return mapOf(
        entry("count", count), 
        entry("sum", sum), 
        entry("average", average)
    );
}

针对该URL的GET请求就会调用这个方法，我们可以传递一个参数列表，包含了1，3，5这几个值：

/math/statistics?values=1&values=3&values=5

返回给调用者的结果就像如下所示：

{
  "count": 3, 
  "sum": 9.0,
  "average": 3.0
}

CTemplate

HTTP-RPC Web服务产生的数据通常都会以JSON的格式返回，在有些场景下，如果能以不同的格式返回给调用者的话，那样会更加便利。例如，返回HTML形式的内容以支持基于浏览器的客户端应用。HTTP-RPC原生就支持CTemplate系统所定义的模板，这样的话就允许对方法所产生的结果进行任意的转换。

CTemplate定义了一组“记号（marker）”，在处理模板的时候，这些记号会被“数据字典（data dictionary）”所提供的值替换掉：

  • {{_variable_}}——从数据字典中获取一个变量注入到输出中；
  • {{#_section_}}…{{/_section_}}——定义一个重复性的内容区域；
  • {{>include}}——引入其他模板所指定的内容；
  • {{!_comment_}}——为模板的内容提供文本化的信息。

服务方法返回的值代表了数据字典。通常来讲，这会是一个java.util.Map实例，它的key代表了字典所提供的值。

如果我们要展现getStatistics()方法的结果，那么以Web页面形式所提供的简单模板可能就会如下所示：

<html>
<head>
    <title>Statistics</title>
</head>
<body>
    <p>Count: {{count}}</p>
    <p>Sum: {{sum}}</p>
    <p>Average: {{average}}</p> 
</body>
</html>

需要注意的是，我们为“count”、“sum”和“average”值使用了变量记号。在执行期，这些记号将会被数据字典中相应的值所替换（也就是方法所返回的Map中的值），从而产生最终的输出。

模板注解

@Template注解用来将一个模板文档和方法关联到一起。这个注解的值代表了模板的类型和名称，这个模板会应用到方法的结果上。例如：

@RPC(method="GET", path="statistics")
@Template(name="statistics.html", mimeType="text/html")
public Map<String, ?> getStatistics(List<Double> values) { ... }

“name”元素指向了包含模板定义的文件，它通过相对于服务类型的资源路径来进行指定。

“contentType”元素指定了模板所产生的内容类型。HTTP-RPC会使用它来识别所请求的模板。在URL中，将所需MIME类型相关的文件扩展名与服务名称合并到一起，就能发起针对特定表述的请求。

添加上注解之后，对statistics.html的GET请求将会调用getStatistics()方法并在结果上使用模板，结果如下：

<html>
<head>
    <title>Statistics</title>
</head>
<body>
    <p>Count: 3.0</p>
    <p>Sum: 9.0</p>
    <p>Average: 3.0</p> 
</body>
</html>

输出结果可以通过如下命令查看，我们使用curl命令下载原始的JSON响应，然后使用mustache命令来应用模板：

curl -s "http://localhost/math/statistics?values=1&values=3&values=5" | mustache - statistics.html

HTTP-RPC使用模板的过程发生在服务端，并不需要在客户端进行处理。不过，在开发期，使用curl来对模板进行测试是一种很棒的方式。

实际样例

作为一个更为实际的样例，我们考虑如下的Web服务，它返回下面这个数据库表的SQL查询结果，这个表来源于BIRT的示例数据库：

CREATE TABLE Products (
  productCode VARCHAR(50) NOT NULL,
  productName VARCHAR(70) NOT NULL,
  productLine VARCHAR(50) NOT NULL,
  productScale VARCHAR(10) NOT NULL,
  productVendor VARCHAR(50) NOT NULL,
  productDescription TEXT NOT NULL,
  quantityInStock SMALLINT NOT NULL,
  buyPrice DOUBLE NOT NULL,
  MSRP DOUBLE NOT NULL,
  PRIMARY KEY (productCode)
);

如下所示的代码，展现了返回表内容的服务方法。ResultSetAdapter类能够从服务方法中高效地返回SQL查询的结果。这个类实现了List接口，让JDBC结果集中的每一行都以Map实例的形式进行展现，这样的话，数据非常适于序列化为JSON格式。HTTP-RPC能够确保在所有的数据写入完成后，数据集会正常关闭：

@RPC(method="GET")
@Template(name="products.html", contentType="text/html")
public ResultSetAdapter getProducts() throws SQLException {
    Statement statement = getConnection().createStatement();
    String sql = "SELECT * FROM Products";

    return new ResultSetAdapter(statement.executeQuery(sql));
}

服务方法所返回的原始JSON输出可能会如下所示，对于移动应用来说，使用这种类型的数据是非常便利的：

[
  {
    "productCode": "S10_1678",
    "productName": "1969 Harley Davidson Ultimate Chopper",
    "productLine": "Motorcycles",
    "productScale": "1:10",
    "productVendor": "Min Lin Diecast",
    "productDescription": "This replica features working kickstand...",
    "quantityInStock": 7932,
    "buyPrice": 48.81,
    "MSRP": 95.7
  },
  ...
]

下面所示的模板可以用来将结果转换为HTML，适用于在Web浏览器中展现。注意，在这里使用了“^html”修饰符（modifier），确保输出的内容经过了正常的HTML编码。关于修饰符的更多信息，可以参考项目的文档：

<html>
<head>
    <title>Product List</title>
</head>
<body>
    <table>
    {{#.}}<tr>
    <td>{{productCode:^html}}</td>
    <td>{{productName:^html}}</td>
    <td>{{productLine:^html}}</td>
    <td>{{productScale:^html}}</td>
    <td>{{productVendor:^html}}</td>
    <td>{{productDescription:^html}}</td>
    <td>{{quantityInStock}}</td>
    <td>{{buyPrice:format=currency}}</td>
    <td>{{MSRP:format=currency}}</td>
    </tr>{{/.}}
    </table>
</body>
</html>

输出的结果可能会像如下所示：

<html>
<head>
    <title>Product List</title>
</head>
<body>
    <table>
    <tr>
    <td>S10_1678</td>
    <td>1969 Harley Davidson Ultimate Chopper</td>
    <td>Motorcycles</td>
    <td>1:10</td>
    <td>Min Lin Diecast</td>
    <td>This replica features working kickstand...</td>
    <td>7932</td>
    <td>$48.81</td>
    <td>$95.70</td>
    </tr>
    ...
    </table>
</body>
</html>

小结

本文概要阐述了如何使用模板将REST服务的结果转换为HTML，在需要同时支持Web和移动客户端应用的情况下，这种方式能够显著减少开发成本。需要注意的是，模板并不局限于HTML，它们还能用来很便利地生成其他的数据表述形式，比如XML或CSV。

HTTP-RPC的最新版本可以在该地址下载。如果想了解更多信息的话，参见项目的README文档。

关于作者

使用模板将Web服务的结果转换为标记语言Greg Brown是一名软件工程师，在咨询、产品以及开源开发方面有着20年以上的经验。他目前的关注点在于移动应用和REST服务。

查看英文原文：Using Templates to Transform Web Service Results into Markup

转自 http://www.infoq.com/cn/articles/templates-with-http-rpc-java

 

相关推荐