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

Rop，即Rapid Open Platform,是一个参考淘宝开放平台（TOP Taobao Open Platform）的平台设计思路，充分借鉴Spring MVC的技术架构原理开发的一个快速服务开放平台开源框架项目，可以让您迅速构建成熟的SOA服务平台。它不同于传统的SOAP Web Service和Rest Web Service这些Web Service 技术型框架，Rop是一个应用型的Web Service平台框架，它不但可以方便快捷地开发一个个Web Service服务，还提供了服务平台领域问题的整体解决方案。因此,... 

传统的Web Service框架帮助你建造房子，而Rop框架帮助您建造城市。

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


错误模型概述 

对于服务开放平台来说，不管发生了什么错误，都必须返回相应的错误报文，以便客户端应用能够根据错误报文做出相应的响应。每个服务都可能存在各种错误，如服务参数不合法、访问权限不足、版本不正确、访问超限等等。如果需要开发者自行设计这套错误模型并处理所有这些错误，那将是一项艰巨的工程。 

Rop参考TOP建立了一个完整的错误模型，该错误模型拥有强大的表达能力和扩展性，很多错误自动于Rop负责处理，对于业务性的错误，开发者按错误模型构造即可。Rop将开发者从服务错误处理的荆棘丛中解放出来，从而可以将精力集中于具体的业务逻辑的处理上。 

Rop的错误模型分为主错误和子错误两个层级，每个错误报文都会对应一个主错误和若干个子错误，主错误描述错误的类型，子错误说明错误的原因。子错误根据责任归属可以划分为ISP(Internet Service Provider)和ISV(Independent Software Vendors)两种类型的错误。如下图所示：

 

ISP代表平台服务提供商一方，如服务内部异常、服务端数据库资源不可用等错误，其责任归属于ISP，这类错误称为ISP错误。ISP错误的错误编码以“isp.”为前缀，如isp.xxx-service-unavailable、isp.xxx-service-timeout等。 

ISV代表基于平台服务开发应用的开发者一方，这类错误产生的原因是由于开发者造成的。ISV错误的错误编码以“isv.”为前缀，如isv.invalid-permission、isv.missing-parameter:xxx等。 
当服务发生错误时，Rop将返回统一格式的错误报文，它由一个主错误和若干个子错误组成。下面即是一个完整的错误报文： 

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.invalid-paramete:salary">  
7.             <message>参数salary无效，格式不对、非法值、越界等</message>  
8.         </subError>  
9.         <subError code="isv.invalid-paramete:userName">  
10.             <message>参数userName无效，格式不对、非法值、越界等</message>  
11.         </subError>  
12.     </subErrors>  
13. </error>  

<error>代表主错误，它拥有一个对应编码，此外还包括错误消息及解决方法。subErrors元素中包含多个子错误，详细说明是哪些参数违反数据了校验规则，子错误的编码附带了违反校验规则的参数名，对定位错误非常有帮助。
系统级主错误编码  

Rop内置定义了一套和业务无关的错误代码体系，我们称这些错误为系统级错误。Rop在i18n/rop/error的国际化资源文件（目前提供了zh_CN和en两个国际化资源文件）中定义了系统级主错误及子错误。 

在Rop中，主错误都对应一个唯一的数字编码，目前共包括27个主错误，通过下表进行说明： 

表1 系统级主错误编码 

错误编码	错误说明	错误编码	错误说明	错误编码	错误说明
1	服务不可用	20	缺少sessionId参数	29	非法的版本参数
2	开发者权限不足	21	无效的sessionId参数	30	不支持的版本号
3	用户权限不足	22	缺少appKey参数	31	无效报文格式类型
4	图片上传失败	23	无效的appKey参数	32	缺少必选参数
5	HTTP方法被禁止	24	缺少签名参数	33	非法的参数
6	编码错误	25	无效签名	34	用户调用服务的次数超限
7	请求被禁止	26	缺少方法名参数	35	会话调用服务的次数超限
8	服务已经作废	27	不存在的方法名	36	应用调用服务的次数超限
9	业务逻辑出错	28	缺少版本参数	37	应用调用服务的频率超限

27个系统级错误可以划分为以下几类： 

• 系统级参数错误：这类错误是由于系统级请求参数缺失或不合法引起的，20~31都是这一类型的错误；
• 业务级参数错误：业务级参数缺失或不合法而引起的错误，如32和33；
• 服务访问超限错误：客户端的服务调用超过配额，34~37都是这一类型的错误；
• 权限不足错误：如2和3的错误都是开发者或应用用户的权限不足，造成服务无法访问的错误；
• 其它错误：以上类型之外的错误。

系统级子错误编码  

子错误的编码是一个格式化的层级编码串，如isp.xxx-service-unavailable、isv.xxx-not-exist:invalid-yyy等，其中xxx和yyy都是变量占位符，会根据具体的错误填写相应的值。 

每个子错误都对应一个主错误，而一个主错误可以对应多个子错误。子错误和主错误的映射关系在Rop的com.rop.validation.SubErrors中定义，SubErrors类拥有一个获取子错误对应主错误的静态方法： 

Java代码  

1. public static MainError getMainError(SubErrorType subErrorType, Locale locale)  

MainErrorType和SubErrorType的枚举类分别定义了系统级主错误和子错误的编码，主子错误的国际化信息都在i18n/rop/error的国际化资源文件中定义。 

ISP子错误编码  

Rop目前仅拥有两个ISP的子错误，它们对应的主错误编码为1，即Service Currently Unavailable主错误。这两个ISP子错误分别是： 

• isp.xxx-service-unavailable=调用后端服务{0}抛异常:{1}，服务不可用。\n异常信息:\n{2}
• isp.xxx-service-timeout = 调用{0}服务超时，该服务的超时限制为{1}秒，请和服务平台提供商联系

因服务平台原因产生的任何错误，如数据库连接不上，某个服务资源不可用，内部抛出异常等，都对应isp.xxx-service-unavailable的ISP子错误。其中子错误代码中的xxx会被替换成具体的服务名。如user.get服务对应的子错误码为：isp.user-get-service-unavailable。 

isp.xxx-service-unavailable的错误消息是带参数的格式化串，Rop会将引起错误的异常信息格式化到消息内容中。假设我们调用user.getSession服务方法，其内部抛出了IllegalArgumentException，则客户端将得到一个如下的错误报文： 

Xml代码  

1. <?xml version="1.0" encoding="utf-8" standalone="yes"?>  
2. <error code="1">  
3.     <message>Service Currently Unavailable</message>  
4.     <solution>Service Currently Unavailable</solution>  
5.     <subErrors>  
6.         <subError code="isp.user-getSession-service-unavailable">  
7.             <message>  
8. call the back-end service user.getSession thrown  
9. exception:java.lang.IllegalArgumentException, the service is unavailable.  
10.         exception info is :  
11. …  
12. </message>  
13.         </subError>  
14.     </subErrors>  
15. </error>  

详细的错误信息不但方便客户端应用的开发者进行问题的定位，还可以充分利用这些错误信息进行用户交互设计和业务逻辑的处理，有效提高服务开放平台的可编程能力。 

Rop允许设置服务执行的最大过期时间，即一个服务的执行超过指定限时后，直接返回错误报文，释放服务端资源，以平衡服务平台资源的利用。Rop默认不设置服务过期时间，可通过<rop:annotation-driven/>的service-timeout-seconds属性指定服务执行最大过期时间，单位为秒： 

Xml代码  

1. <rop:annotation-driven service-timeout-seconds="10"/>  

每个服务方法都可以定义自己的服务过期时间，以覆盖<rop:annotation-driven/>所定义的统一过期时间，来看一个例子： 

UserService.java:指定服务过期时间 

Java代码  

1. @ServiceMethod(method = "user.timeout", version = "1.0", timeout = 1) ①  
2. public RopResponse timeoutService(CreateUserRequest request) throws Throwable {  
3.     Thread.sleep(2000);  ②  
4.     CreateUserResponse response = new CreateUserResponse();  
5.     response.setCreateTime("20120101010102");  
6.     response.setUserId("2");  
7.     return response;  
8. }  

在①处通过@ServiceMethod的timeout属性为user.timeout服务方法指定的过期时间为1秒。在②处，我们故意让该服务方法睡眠2秒钟，以便超过服务方法过期时间的限制。客户端调用该服务方法后，则返回如下的错误报文： 

Xml代码  

1. <?xml version="1.0" encoding="utf-8" standalone="yes"?>  
2. <error code="1">  
3.     <message>服务不可用</message>  
4.     <solution>服务目前无法使用</solution>  
5.     <subErrors>  
6.         <subError code="isp.user-timeout-service-timeout">  
7.             <message>  
8. 调用user.timeout服务超时，该服务的超时限制为1秒，请和服务平台提供商联系。  
9. </message>  
10.         </subError>  
11.     </subErrors>  
12. </error>  

ISV子错误编码  

在实际应用中，开发者遇到更多的都会是ISV的错误。Rop定义了5个ISV子错误，说明如下： 

• isv.missing-parameter:xxx=缺少必要的参数{0}
• isv.parameters-mismatch:xxx-and-yyy=传入的参数{0}和{1}不匹配；
• isv.invalid-paramete:xxx=参数{0}无效，格式不对、非法值、越界等
• isv.invalid-permission=权限不够、非法访问
• isv.xxx-not-exist:invalid-yyy=根据{0}查询不到{1}

其中，前3个子错误都是由于业务级参数未能通过合法性校验而引起的。当请求参数对象的属性打上@NotNull的JSR 303注解时，即说明该请求参数是必须的，如果未提供该参数就会报出isv.missing-parameter:xxx子错误，其中xxx为具体的参数名。 

Rop将请求参数绑定到请求参数对象属性时，如果发生类型不匹配的错误（如将aaa赋给一个整型的属性），将返回isv.parameters-mismatch:xxx-and-yyy的子错误码，其中xxx为参数名，而yyy为请求参数的值。违反其它校验规则的统一返回isv.invalid-paramete:xxx的子错误，其中xxx为未通过校验的参数名。 

可以通过SecurityManager实现类开发服务权限管理逻辑，如果SecurityManager驳回服务的访问，则说明应用或用户的权限不足，不能访问某个受限平台服务，Rop将返回isv.invalid-permission的子错误， 
isv.xxx-not-exist:invalid-yyy子错误表示不存在对应某个ID的对象，如根据userId获取用户对象时，如果查不到对应的对象，则返回该子错误。以上我们介绍的4个ISV子错误，ROP都会自动产生，无需服务开发者关注。 
而isv.xxx-not-exist:invalid-yyy则需要服务开发者自己负责创建，可以通过Rop的NotExistErrorResponse对象产生该错误。来看一个rop-sample中的例子： 

代码清单 UserService.java:模拟返回CreateUserResponse响应 

Java代码  

1. @ServiceMethod(method = "user.get", version = "1.0", httpAction = HttpAction.GET)  
2. public RopResponse getUser(RopRequest request) throws Throwable {  
3.     String userId = request.getRopRequestContext().getParamValue("userId");  
4.     if("9999".equals(userId)){                                              ①  
5.         return new NotExistErrorResponse("user","userId","9999",  
6. request.getRopRequestContext().getLocale());  
7.     }else{  
8.         CreateUserResponse response = new CreateUserResponse();  
9.         //add creaet new user here...  
10.         response.setCreateTime("20120101010102");  
11.         response.setUserId(userId);  
12.         response.setFeedback("user.get");  
13.         return response;  
14.     }  
15. }  

NotExistErrorResponse构造函数的第1个入参为对象名，第2个入参为查询使用的属性名，第3个参数为查询的属性值。使用userId值为9999的请求参数调用该服务时，将返回如下的响应报文： 

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.user-not-exist:invalid-userId">  
9.             <message>cant find userId by 9999</message>  
10.         </subError>  
11.     </subErrors>  
12. </error>  

Rop所定义的子错误码其实是一个模式化串，Rop会根据具体的错误产生相应的编码。这些模式化的子错误码基本上涵盖了各种通用的错误，从模型设计角度上看，这个错误模型是收敛的。因此，使用Rop的平台开发者无需再为设计错误码而烦心了，直接使用这个错误模型即可，大大降低了服务平台设计的难度。 
业务级子错误编码  
系统级子错误模型是业务无关的通用性错误，在使用Rop开发您的服务平台时，一定会有很多业务相关的错误。如删除一个不允许删除的业务单据，在单据未通过审核时直接审批等等，这些业务相关的错误，称之为业务级子错误。 
Rop设计了一个通用的业务级子错误编码： isv.xxx-service-error:yyy，其中xxx为服务方法名(服务方法名的“.”替换成“-”)，而yyy为业务错误代码，一般由大写英文字符组成，来看几个具体的业务级子错误编码的示例： 

• isv.order-delete-service-error:ORDER_NOT_ALLOW_DELETE；
• isv.order-approve-service-error:ORDER_IS_NOT_AUDIT；
• isv.user-password-change-service-error:PASSWORD_TOO_SIMPLE；

由于业务级子错误是由服务平台开发者自己定义的，因此错误码及错误信息的国际化资源也必须由服务平台开发者提供。rop-sample的业务级子错误国际化资源位于rop-sample项目的i18n/rop/sampleRopError资源文件中。我们来看一下对应zh_CN的资源文件： 

引用

isv.user-add-service-error\:USER_NAME_RESERVED= {0} 是预留的用户,请选择其它的用户名.

sampleRopError_zh_CN.properties目前仅定义了一个业务级子错误，可以在该文件中定义任意多个错误。属性值可以使用{n}定义变量占位符，以便在运行其替换成具体的内容。 

在属性资源文件中，属性键名如果包含“:”或“=”的字符，必须使用转义符，即在其前面添加“\”字符。如果属性值一行编写不下，可以通过“\”进行分行。具体参见java.util.Properties类的JavaDoc的说明。 

必须在<rop:annotation-driven/>中指定业务级子错误资源文件的地址，以便Rop将其加载到框架中： 

Xml代码  

1. <rop:annotation-driven ext-error-base-name="i18n/rop/sampleRopError"/>  

所有业务级子错误对应的主错误码均为9（业务逻辑出错），Rop提供了一个用于构造业务级错误的响应类，即BusinessServiceErrorResponse，其构造方法如下所示： 

Java代码  

1. public BusinessServiceErrorResponse(String serviceName, String errorCode, Locale locale,   
2. Object... params)  

serviceName为服务方法，即method系统参数对应的值，如“user.get”。errorCode为业务错误代码，如ORDER_NOT_ALLOW_DELETE、ORDER_IS_NOT_AUDIT等，它将用于替换isv.xxx-service-error:yyy中的“yyy”。最后的params用于替换错误消息内容的{n}中。 

我们通过rop-sample的一个例子了解业务级子错误的具体使用方法： 

代码清单UserService.java:模拟返回CreateUserResponse响应 

Java代码  

1. @ServiceMethod(method = "user.add", version = "1.0")  
2. public RopResponse addUser(CreateUserRequest request) {  
3.     if (reservesUserNames.contains(request.getUserName())) {  
4.         return new BusinessServiceErrorResponse(  
5.           request.getRopRequestContext().getMethod(), "USER_NAME_RESERVED",  
6.           request.getRopRequestContext().getLocale(), request.getUserName());       ①  
7.     } else {  
8.         CreateUserResponse response = new CreateUserResponse();  
9.          response.setCreateTime("20120101010101");  
10.         response.setUserId("1");  
11.         return response;  
12.     }  
13. }  

user.add是一个用于注册新用户的服务，它需要保证新增的用户名不能使用预留的用户名，否则返回一个isv.user-add-service-error:USER_NAME_RESERVED的业务级错误。 
假设“jhon”是预留的用户名，如果调用user.add服务时，上传的userName参数是“jhon”，将返回如下的错误响应报文： 

Xml代码  

1. <?xml version="1.0" encoding="utf-8" standalone="yes"?>  
2. <error code="9">  
3.     <message>业务逻辑出错</message>  
4.     <solution>请了解服务调用的前置条件，检查是否满足业务逻辑</solution>  
5.     <subErrors>  
6.         <subError code="isv.user-add-service-error:USER_NAME_RESERVED">  
7.             <message>jhon 是预留的用户,请选择其它的用户名.</message>  
8.         </subError>  
9.     </subErrors>  
10. </error>  

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