Rop开发手册(6):最简单的服务开放平台框架

目录
1.快速了解Rop
2.请求服务模型
3.应用授权及验证
4.服务会话管理
5.错误处理模型
6.响应报文控制
7.文件上传
8.服务安全控制
9.拦截器及事件体系
10.性能调优
11.开发客户端SDK
12.参考资料

分体式报文模型

服务开放平台对服务的处理结果统一由响应报文告之调用终端，不管服务处理正确与否，都必须对应一个响应报文。如果响应报文既要包含正确的业务响应报文，又要包括错误的响应报文，将增加服务响应报文格式的复杂度。由于Rop已经建立了一个可以描述所有类型错误的错误模型，因此错误响应报文的格式是统一的。业务服务的结果响应报文是业务相关的，也就是说，每个业务服务方法的正确业务响应报文是不一样的。

基于以上的分析，Rop将正确业务响应报文和错误处理响应报文独立开来，这样服务平台的开发者仅需设计正确的业务响应报文即可，错误响应报文直接由Rop提供。如果服务正确执行，返回正确的业务响应报文，否则返回Rop格式的错误响应报文。

响应报文定义

Rop的服务方法可以返回任何类型的对象，通过JSR 222注解进行对象流化定义。只要定义好响应类，并正确标注JSR 222注解，业务响应报文也就定义好了。

代码清单CreateUserResponse .java:服务响应的返回对象

package com.rop.sample.response;

import javax.xml.bind.annotation.*;

@XmlAccessorType(XmlAccessType.FIELD)           ①
@XmlRootElement(name = "createUserResponse")
public class CreateUserResponse{

    @XmlAttribute    ②
    private String userId;

    @XmlAttribute
    private String createTime;

    @XmlElement
    private Foo foo = new Foo();

    @XmlElement
    private String feedback;

…
}

在上节的addUser(CreateUserRequest request)服务方法中，如果一切服务执行正常，将返回一个CreateUserResponse的对象。

运行rop-sample项目的UserServiceRawClient#testAddUserByVersion1()测试方法，将看到如下的响应报文：

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<createUserResponse createTime="20120101010101" userId="1">
    <foo field2="2" field1="1"/>
    <feedback>hello</feedback>
</createUserResponse>

观察以上的输出报文，可以看到createTime和userId以元素属性的形式出现，而foo和feedback则以子元素的形式出现。

报文输出格式

默认情况下，Rop的响应报文是以XML的格式输出的。除XML之外，Rop还支持JSON格式的响应报文。您只要将format的系统级参数设置为json，就会返回JSON格式的响应报文了。

运行rop-sample项目的UserServiceRawClient#testAddUserWithJsonFormat()测试方法，您将看到如下的输出：
{"userId":"1","createTime":"20120101010101","foo":{"field1":"1","field2":"2"},"feedback":"hello"}
值得注意的是，当前Rop不支持混合使用XML和JSON的报文格式，也即请求和响应的数据格式要么采用XML，要么采用JSON。如果希望采用XML格式的请求参数值，那么响应的报文也必须是XML。

报文的国际化支持

Rop使用locale系统级参数指定本地化的信息，默认的locale值为zh_CN，服务平台将根据locale值的不同返回相应的本地化报文信息。由于错误报文是由Rop框架全权负责的，因此错误报文的国际化问题，Rop本身已经提供了解决方案。目前，Rop为系统级错误提供了zh_CN和en两个国际化资源文件。

运行rop-sample的UserServiceRawClient#testI18nErrorMessage()测试方法，该方法将发起两次对user.add服务方法的调用，其中请求参数都相同，唯有locale的值不同：第一次为locale=en，第二次为locale=zh_CN。第一次服务调用返回的错误响应报文为：

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<error code="33">
    <message>Invalid Arguments</message>
    <solution>
check the Required application parameter is valid(refer the subError message)
</solution>
    <subErrors>
        <subError code="isv.parameters-mismatch:salary-and-yyy">
            <message>
incoming parameter salary and aaa does not match, both have a certain correspondence between
</message>
        </subError>
    </subErrors>
</error>

第二次服务调用返回的错误响应报文：

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<error code="33">
    <message>非法的参数</message>
    <solution>请查看根据服务接口对参数格式的要求</solution>
    <subErrors>
        <subError code="isv.parameters-mismatch:salary-and-yyy">
            <message>传入的参数salary和aaa不匹配，两者有一定的对应关系</message>
        </subError>
    </subErrors>
</error>

正确的业务响应报文由服务平台开发者负责，因此国际化的工作也由服务平台开发者负责。在服务方法内部，可以通过request.getRopRequestContext().getLocale()获取请求参数locale对应的本地化对象，进而控制响应对象的国际化输出。如果服务开放平台没有国际化的需求，可以不关注locale参数。