Rop开发手册(5):最简单的服务开放平台框架
Rop相关资源：
1.github:https://github.com/itstamen/rop
2.群组：http://rop.group.iteye.com/
目录
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)两种类型的错误。如下图所示：
[img]http://dl.iteye.com/upload/attachment/0072/7375/6baa1f54-0640-3f6a-9fa6-09c12e40f22d.jpg[/img]
图1
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 version="1.0" encoding="utf-8" standalone="yes"?><error code="33"> <message>非法的参数</message> <solution>请查看根据服务接口对参数格式的要求</solution> <subErrors> <subError code="isv.invalid-paramete:salary"> <message>参数salary无效，格式不对、非法值、越界等</message> </subError> <subError code="isv.invalid-paramete:userName"> <message>参数userName无效，格式不对、非法值、越界等</message> </subError> </subErrors></error>
<error>代表主错误，它拥有一个对应编码，此外还包括错误消息及解决方法。subErrors元素中包含多个子错误，详细说明是哪些参数违反数据了校验规则，子错误的编码附带了违反校验规则的参数名，对定位错误非常有帮助。
系统级主错误编码
Rop内置定义了一套和业务无关的错误代码体系，我们称这些错误为系统级错误。Rop在i18n/rop/error的国际化资源文件（目前提供了zh_CN和en两个国际化资源文件）中定义了系统级主错误及子错误。
在Rop中，主错误都对应一个唯一的数字编码，目前共包括27个主错误，通过下表进行说明：
表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 version="1.0" encoding="utf-8" standalone="yes"?><error code="1"> <message>Service Currently Unavailable</message> <solution>Service Currently Unavailable</solution> <subErrors> <subError code="isp.user-getSession-service-unavailable"> <message>call the back-end service user.getSession thrownexception:java.lang.IllegalArgumentException, the service is unavailable. exception info is :…</message> </subError> </subErrors></error>
详细的错误信息不但方便客户端应用的开发者进行问题的定位，还可以充分利用这些错误信息进行用户交互设计和业务逻辑的处理，有效提高服务开放平台的可编程能力。
Rop允许设置服务执行的最大过期时间，即一个服务的执行超过指定限时后，直接返回错误报文，释放服务端资源，以平衡服务平台资源的利用。Rop默认不设置服务过期时间，可通过<rop:annotation-driven/>的service-timeout-seconds属性指定服务执行最大过期时间，单位为秒：
<rop:annotation-driven service-timeout-seconds="10"/>
每个服务方法都可以定义自己的服务过期时间，以覆盖<rop:annotation-driven/>所定义的统一过期时间，来看一个例子：
UserService.java:指定服务过期时间
@ServiceMethod(method = "user.timeout", version = "1.0", timeout = 1) ①public RopResponse timeoutService(CreateUserRequest request) throws Throwable {Thread.sleep(2000); ②CreateUserResponse response = new CreateUserResponse();response.setCreateTime("20120101010102");response.setUserId("2");return response;}在①处通过@ServiceMethod的timeout属性为user.timeout服务方法指定的过期时间为1秒。在②处，我们故意让该服务方法睡眠2秒钟，以便超过服务方法过期时间的限制。客户端调用该服务方法后，则返回如下的错误报文：
<?xml version="1.0" encoding="utf-8" standalone="yes"?><error code="1"> <message>服务不可用</message> <solution>服务目前无法使用</solution> <subErrors> <subError code="isp.user-timeout-service-timeout"> <message>调用user.timeout服务超时，该服务的超时限制为1秒，请和服务平台提供商联系。</message> </subError> </subErrors></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响应
@ServiceMethod(method = "user.get", version = "1.0", httpAction = HttpAction.GET)public RopResponse getUser(RopRequest request) throws Throwable {String userId = request.getRopRequestContext().getParamValue("userId");if("9999".equals(userId)){ ①return new NotExistErrorResponse("user","userId","9999",request.getRopRequestContext().getLocale());}else{CreateUserResponse response = new CreateUserResponse();//add creaet new user here...response.setCreateTime("20120101010102");response.setUserId(userId);response.setFeedback("user.get");return response;}}NotExistErrorResponse构造函数的第1个入参为对象名，第2个入参为查询使用的属性名，第3个参数为查询的属性值。使用userId值为9999的请求参数调用该服务时，将返回如下的响应报文：
<?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.user-not-exist:invalid-userId"> <message>cant find userId by 9999</message> </subError> </subErrors></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的资源文件：
<rop:annotation-driven ext-error-base-name="i18n/rop/sampleRopError"/>
所有业务级子错误对应的主错误码均为9（业务逻辑出错），Rop提供了一个用于构造业务级错误的响应类，即BusinessServiceErrorResponse，其构造方法如下所示：
public BusinessServiceErrorResponse(String serviceName, String errorCode, Locale locale, 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响应
@ServiceMethod(method = "user.add", version = "1.0")public RopResponse addUser(CreateUserRequest request) {if (reservesUserNames.contains(request.getUserName())) { return new BusinessServiceErrorResponse( request.getRopRequestContext().getMethod(), "USER_NAME_RESERVED", request.getRopRequestContext().getLocale(), request.getUserName()); ①} else {CreateUserResponse response = new CreateUserResponse(); response.setCreateTime("20120101010101");response.setUserId("1");return response;}}user.add是一个用于注册新用户的服务，它需要保证新增的用户名不能使用预留的用户名，否则返回一个isv.user-add-service-error:USER_NAME_RESERVED的业务级错误。
假设“jhon”是预留的用户名，如果调用user.add服务时，上传的userName参数是“jhon”，将返回如下的错误响应报文：
<?xml version="1.0" encoding="utf-8" standalone="yes"?><error code="9"> <message>业务逻辑出错</message> <solution>请了解服务调用的前置条件，检查是否满足业务逻辑</solution> <subErrors> <subError code="isv.user-add-service-error:USER_NAME_RESERVED"> <message>jhon 是预留的用户,请选择其它的用户名.</message> </subError> </subErrors></error>