构建 Apache Wink REST 服务（2）

look_w

数据设计每个 RESTful 接口必须决定支持它的客户机使用哪种具象。Apache Wink 1.0 可以支持 XML、JSON、HTML 和 Atom 等，这个示例使用 JSON，因为这是一种流行的格式，而且 Ajax 应用程序很容易使用 JavaScript 代码。 是一个采用 JSON 格式的交易状态示例。               
清单 3. JSON 字符串形式的交易状态响应

1 2 3 4 5 6

{ "RESULT":19,"PNREF":"V19A2A1A7CC5", "RESPMSG":"Original transaction ID not found: V19A2A192BE9", "AUTHCODE":null,"CVV2MATCH":null,"AVSADDR":null, "AVSZIP":null,"IAVS":null,"CARDSECURE":null }

HTTP 方法设计最后，必须决定使用哪些 HTTP 方法操作资源及其功能。一定要坚持这些 HTTP 方法的正规用法，不要偏离规范。例如，GET 应该是安全的只读幂等（idempotent）调用，它不应该以任何方式更改资源的状态。违反这条原则会增加复杂性，给客户机带来混乱。在这个示例中，因为希望对单一交易的状态执行只读查询，显然应该使用 GET 方法，使用的 URI 模式见 。               
清单 4. 交易服务示例 URI 模式

1	/transactions{id}

每个 GET 调用返回一个 JSON 格式的字符串，这是查询的交易的状态数据，见 。               
清单 5. 包含交易 ID 的 GET 请求

1	GET /transactions/V19A2A192BE9 HTTP/1.1

但是，这种查询交易状态的模型有一个问题：服务无法验证查询交易的用户是否确实是交易的所有者。为了解决这个问题，允许客户机在 URI 中作为查询参数传递登录凭证，见 。               
清单 6. 在查询字符串中包含安全凭证的 GET 请求       

1 2 3

GET /transactions/V19A2A192BE9?user=winktest&vendor=winktest     &partner=PayPal&pwd=wink123 HTTP/1.1

Apache Wink 服务实现Apache Wink 服务实现为 POJO（即普通的 Java 类），它使用 JAX-RS 注释把 HTTP 请求映射到 Java 方法。在默认情况下，服务可以是单实例的，也可以为每个请求创建服务实例。在这个示例中，通过创建 TransactionResource 类实现 Apache Wink RESTful 服务。它解析状态查询请求，验证用户凭证，调用 Payflow 网关服务，然后以 JSON 对象的形式返回交易的状态。 给出 TransactionResource 类的代码片段。               
清单 7. Apache Wink 服务 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

package org.openengine.wink.example.payflow;     import ...;           @Path("/transactions")     public class TransactionResource {              @GET     @Path("{pnref}")     @Produces(MediaType.APPLICATION_JSON)     public JSONObject doInquiry(@PathParam("pnref") String pnref,                   @QueryParam("user") String userName,                 @QueryParam("vendor") String vendorName,                 @QueryParam("partner") String partnerName,                 @QueryParam("pwd") String password) {         try {             return getTxnStatus(pnref,         userName, vendorName,         partnerName, password);               } catch (JSONException e) {         throw new WebApplicationException         (Response.Status.INTERNAL_SERVER_ERROR);         }     }     ....

@javax.ws.rs.Path 注释指出这个类是 JAX-RS 服务。所有 JAX-RS 服务都需要这个注释。@Path 注释的值 /transactions 指出交易服务的 URI 的相对路径。
@GET 注释指出这个方法本身映射到的 HTTP 动词。方法级 @Path 注释的值相对于主 URI 指定子根。方法级 @Path 和 @PathParam 中的 {pnref} 表示交易的惟一 ID。例如，如果 URI 是 /transactions/V19A2A192BE9，V19A2A192BE9 字符串会被注入 getTxnStatus 方法的 {pnref} 参数中。               
@javax.ws.rs.QueryParam 注释与 @PathParam 相似，但是它把各个 URI 查询参数注入 Java 参数中，见 。               
清单 8. 包含查询参数的 URI

1	/transactions/V19A2A192BE9?user=winktest&vendor=winktest&partner=PayPal&pwd=wink123