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:服务响应的返回对象 

Java代码  

1. package com.rop.sample.response;  
2.   
3. import javax.xml.bind.annotation.*;  
4.   
5. @XmlAccessorType(XmlAccessType.FIELD)           ①  
6. @XmlRootElement(name = "createUserResponse")  
7. public class CreateUserResponse{  
8.   
9.     @XmlAttribute    ②  
10.     private String userId;  
11.   
12.     @XmlAttribute  
13.     private String createTime;  
14.   
15.     @XmlElement  
16.     private Foo foo = new Foo();  
17.   
18.     @XmlElement  
19.     private String feedback;  
20.   
21. …  
22. }  

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

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

Xml代码  

1. <?xml version="1.0" encoding="utf-8" standalone="yes"?>  
2. <createUserResponse createTime="20120101010101" userId="1">  
3.     <foo field2="2" field1="1"/>  
4.     <feedback>hello</feedback>  
5. </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代码  

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

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

Xml代码  

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

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

转自:http://stamen.iteye.com/blog/1654635