[关闭]
@levinzhang 2016-12-16T15:40:23.000000Z 字数 5521 阅读 423

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

Posted by Greg Brown on Aug 31, 2016

摘要：

HTTP-RPC是一个开源的Java框架，它返回的结果默认是JSON，但是我们也可以借助CTemplate系统，使其响应为自定义的标记语言。在本文中，Greg Brown展现了如何以注解的方式自动化地将Web服务的结果响应为任意的标记类型（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。

参数会通过查询字符串或类似于HTML表单那样的请求体的方式来提供。结果通常会返回JSON格式，当然不返回任何值的操作也是支持的。

例如，如下的请求将会得到两个数字的和，这两个数字分别是通过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）”所提供的值替换掉：

服务方法返回的值代表了数据字典。通常来讲，这会是一个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文档。

关于作者

Greg Brown是一名软件工程师，在咨询、产品以及开源开发方面有着20年以上的经验。他目前的关注点在于移动应用和REST服务。

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

添加新批注
在作者公开此批注前，只有你和作者可见。
回复批注