Rop重大升级周知
首先，非常感谢众多网友对Rop所提出的修改建议，你们的建议是我完善Rop框架的源动力！由于这次更改很大，所以我还是在这边发，后面请大家到Rop群组http://rop.group.iteye.com/中讨论，谢谢合作！
这段时间，对Rop进行了较大的调整和优化，这边出一个较完整的更改日志，说明如下：
[size=x-large]2012-06-12
1.新增了Rop的Spring Schema命令空间
可以通过rop命名空间配置Rop，如指定应用错误国际化资源地址、设置自定义的RopValidator,配置FormattingConversionService并添加自定义的转换器、注册拦截器，注册监听器，设置系统级参数的名称等，如下所示：
<?xml version="1.0" encoding="UTF-8" ?>
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:context="http://www.springframework.org/schema/context"
xmlns:rop="http://www.rop.com/schema/rop"
xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-3.1.xsd
http://www.rop.com/schema/rop http://www.rop.com/schema/rop/rop-1.0.xsd
http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context-3.1.xsd">
<!--① 扫描Web类包-->
<context:component-scan base-package="com.rop.sample">
<!-- 假设所有的服务方法都放在rop包下-->
<context:exclude-filter type="annotation" expression="org.springframework.stereotype.Controller"/>
</context:component-scan>
<!-- 配置一个Rop框架 -->
<rop:annotation-driven
rop-validator="ropValidator"
formatting-conversion-service="conversionService"
ext-error-base-name="i18n/rop/sampleRopError"
sign-enable="true"/>
<!--定义自定义的RopValiator，如appKey及密钥的管理器、会话管理器、服务安全访问管理器等-->
<bean id="ropValidator" class="com.rop.validation.DefaultRopValidator">
<property name="appSecretManager">
<bean class="com.rop.sample.SampleAppSecretManager"/>
</property>
<property name="securityManager">
<bean class="com.rop.sample.SampleSecurityManager"/>
</property>
<property name="sessionChecker">
<bean class="com.rop.sample.SampleSessionChecker"/>
</property>
</bean>
<!--设置自定义的类型转换服务，注册自定义的类型转换器-->
<bean id="conversionService" class="org.springframework.format.support.FormattingConversionServiceFactoryBean">
<property name="converters">
<set>
<!--将xxxx-yyyyyyy格式的电话转换为内部的Telephone对象-->
<bean class="com.rop.sample.request.TelephoneConverter"/>
</set>
</property>
</bean>
<!--注册拦截器，可配置多个-->
<rop:interceptors>
<bean class="com.rop.sample.ReservedUserNameInterceptor"/>
</rop:interceptors>
<!--注册监听器，可配置多具-->
<rop:listeners>
<bean class="com.rop.sample.SamplePostInitializeEventListener"/>
<bean class="com.rop.sample.SampleAfterDoServiceEventListener"/>
</rop:listeners>
<!--自定义method,appKey等这些系统级参数的参数名-->
<rop:sysparams format-param-name="messageFormat"/>
</beans>
这个RopServlet就变化很简单，自定义配置性的工作转换到Spring的rop schema中，RopServlet的配置简化为：
<servlet>
<servlet-name>rop</servlet-name>
<servlet-class>
com.rop.RopServlet
</servlet-class>
<load-on-startup>2</load-on-startup>
</servlet>
<servlet-mapping>
<servlet-name>rop</servlet-name>
<url-pattern>/router</url-pattern>
</servlet-mapping>
原来配置Rop的文件配置也移除了，统一在Spring的rop空间中来做。
2.支持异步调用
ApiMethob易名为ServiceMethod,该注解添加了多个属性，其中有一个timeout属性,当服务端的服务超过后，会返回相应的错误信息，如下所示：
@ServiceMethod(value = "user.timeout", version = "1.0", timeout = 1)
public RopResponse timeoutService(CreateUserRequest request) throws Throwable {
Thread.sleep(2000);
CreateUserResponse response = new CreateUserResponse();
//add creaet new user here...
response.setCreateTime("20120101010102");
response.setUserId("2");
return response;
}
这儿，我们设定timeoutService()服务方法的过期时间为1，如果过滤，将返回如下的错误报文：
response:<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<error solution="Service Currently Unavailable" message="Service Currently Unavailable" code="1">
<subErrors>
<subError message="connect to a remote service timeout Remote connection error" code="isp.remote-service-timeout"/>
</subErrors>
</error>
3.支持服务的多版本
@ServiceMethod添加了一个version属性，Rop将自动将method和version都匹配的请求路由到相应的服务方法中，如果找不到对应的版本，会报相应的错误，如下所示：
@ServiceMethodBean(value = "group1", title = "组1")
public class UserRestService {
private static final String USER_NAME_RESERVED = "USER_NAME_RESERVED";
private List reservesUserNames = Arrays.asList(new String[]{"tom", "jhon"});
@ServiceMethod(value = "user.add", version = "1.0")//② Let this method service the sample.user.add method
public RopResponse addUser(CreateUserRequest request) {
if (reservesUserNames.contains(request.getUserName())) { //如果注册的用户是预留的帐号，则返回错误的报文
return new ServiceErrorResponse(
request.getRequestContext().getMethod(), USER_NAME_RESERVED,
request.getRequestContext().getLocale(), request.getUserName());
} else {
CreateUserResponse response = new CreateUserResponse();
//add creaet new user here...
response.setCreateTime("20120101010101");
response.setUserId("1");
return response;
}
}
//版本为2.0的user.add
@ServiceMethod(value = "user.add", version = "2.0")
public RopResponse addUser2(CreateUserRequest request) {
if (reservesUserNames.contains(request.getUserName())) { //如果注册的用户是预留的帐号，则返回错误的报文
return new ServiceErrorResponse(
request.getRequestContext().getMethod(), USER_NAME_RESERVED,
request.getRequestContext().getLocale(), request.getUserName());
} else {
CreateUserResponse response = new CreateUserResponse();
//add creaet new user here...
response.setCreateTime("20120101010102");
response.setUserId("2");
return response;
}
}
}
以上服务为user.add定义了两个版本的方法。
4.支持HTTP请求方法限制(目前仅支持GET和POST)
@ServiceMethod添加了一个httpAction的属性，默认情况下不限定，如果设置后，只有HTTP请求是相应的方法时，才会路由到相应的服务方法中，返回直接驳回请求。如下所示：
@ServiceMethod(value = "user.get", version = "1.0", httpAction = HttpAction.GET)
public RopResponse getUser(CreateUserRequest request) throws Throwable {
String userId = request.getRequestContext().getParamValue("userId");
CreateUserResponse response = new CreateUserResponse();
//add creaet new user here...
response.setCreateTime("20120101010102");
response.setUserId(userId);
response.setFeedback("user.get");
return response;
}
假设使用POST HTTP 方法访问：
@Test
public void testGetUserWithPOST() {
RestTemplate restTemplate = new RestTemplate();
MultiValueMap<String, String> form = new LinkedMultiValueMap<String, String>();
form.add("method", "user.get");//<--指定方法名称
form.add("appKey", "00001");
form.add("v", "1.0");
form.add("sessionId", "mockSessionId1");
form.add("locale", "en");
form.add("userName", "tomson");
form.add("salary", "2,500.00");
//对请求参数列表进行签名
String sign = RopUtils.sign(new ArrayList<String>(
form.keySet()), form.toSingleValueMap(), "abcdeabcdeabcdeabcdeabcde");
form.add("sign", sign);
String response = restTemplate.postForObject(
"http://localhost:8088/router", form, String.class);
System.out.println("response:\n" + response);
assertTrue(response.indexOf("code=\"5\"") > -1);
}
将返回如下的错误信息：
<?xml version="1.0" encoding="utf-8" standalone="yes"?> <error solution="Use the correct HTTP method(GET or POST)" message="Http Action Not Allowed" code="5"/>
5.添加事件体系
支持Rop框架启动后，关闭前的事件，每个服务处理前处理后的事件；
以下是一个监听Rop框架初始化后事件的监听器：
public class SamplePostInitializeEventListener implements RopEventListener<AfterStartedRopEvent> {
@Override
public void onRopEvent(AfterStartedRopEvent ropRopEvent) {
System.out.println("execute SamplePostInitializeEventListener!");
}
@Override
public int getOrder() {
return 0; //To change body of implemented methods use File | Settings | File Templates.
}
}
要使事件启用，必须在Spring中配置好：
<rop:listeners>
<bean class="com.rop.sample.SamplePostInitializeEventListener"/>
</rop:listeners>
6.添加拦截器支持
可以对每个服务调用进行拦截，如果在拦截器中往RequestContext中设置RopResponse了，将阻止业务执行，直接返回，否则继续执行服务：
下面的拦截器，对user.add的方法进行拦截，并发现userName为jhonson（相当于说这是预留的用户名，不能添加这个用户）时，驳回请求，返回相应的错误报文：
package com.rop.sample;
import com.rop.AbstractInterceptor;
import com.rop.RequestContext;
import com.rop.sample.response.InterceptorResponse;
import org.springframework.stereotype.Component;
/**
* <pre>
* 该拦截器仅对method为“user.add”进行拦截，你可以在{@link #isMatch(com.rop.RequestContext)}方法中定义拦截器的匹配规则。
* 你可以通过{@link com.rop.RequestContext#getServiceMethodDefinition()}获取服务方法的注解信息，通过这些信息进行拦截匹配规则
* 定义。
* </pre>
*
* @version 1.0
*/
@Component
public class ReservedUserNameInterceptor extends AbstractInterceptor {
/**
* 在数据绑定后，服务方法调用前执行该拦截方法
* @param methodContext
*/
@Override
public void beforeService(RequestContext methodContext) {
System.out.println("beforeService ...");
if ("jhonson".equals(methodContext.getParamValue("userName"))) {
InterceptorResponse response = new InterceptorResponse();
response.setTestField("the userName can't be jhonson!");
//设置了RopResponse后，后续的服务将不执行，直接返回这个RopResponse响应
methodContext.setRopResponse(response);
}
}
/**
* 在服务执行完成后，响应返回前执行该拦截方法
* @param methodContext
*/
@Override
public void beforeResponse(RequestContext methodContext) {
System.out.println("beforeResponse ...");
}
/**
* 对method为user.add的方法进行拦截，你可以通过methodContext中的信息制定拦截方案
* @param methodContext
* @return
*/
@Override
public boolean isMatch(RequestContext methodContext) {
return "user.add".equals(methodContext.getMethod());
}
}
这样，将执行下面的测试时将返回由拦截器生产的响应报文：
/**
* 测试被拦截器阻截服务的情况 (user.add + 1.0）
*/
@Test
public void testAddUserWithInterceptorViolidateReservedUserName() {
RestTemplate restTemplate = new RestTemplate();
MultiValueMap<String, String> form = new LinkedMultiValueMap<String, String>();
form.add("method", "user.add");//<--指定方法名称
form.add("appKey", "00001");
form.add("v", "2.0");
form.add("sessionId", "mockSessionId1");
form.add("locale", "en");
form.add("userName", "jhonson");//这个用户名会被ReservedUserNameInterceptor拦截器驳回
form.add("salary", "2,500.00");
//对请求参数列表进行签名
String sign = RopUtils.sign(new ArrayList<String>(
form.keySet()), form.toSingleValueMap(), "abcdeabcdeabcdeabcdeabcde");
form.add("sign", sign);
String response = restTemplate.postForObject(
"http://localhost:8088/router", form, String.class);
System.out.println("response:\n" + response);
assertTrue(response.indexOf("the userName can't be jhonson!") > -1);
}
返回如下报文：
<?xml version="1.0" encoding="utf-8" standalone="yes"?> <createUserResponse testField="the userName can't be jhonson!"/>
7.可以将XML及JSON的请求数据绑定到请求对象中
如果需要使用XML请求数据，则format必须设置成xml,如果需要使用json，则format必须设置成json.
以下是一个带XML的请求：
@Test
public void testServiceXmlRequestAttr() {
RestTemplate restTemplate = new RestTemplate();
MultiValueMap<String, String> form = new LinkedMultiValueMap<String, String>();
form.add("method", "user.add");//<--指定方法名称
form.add("appKey", "00001");
form.add("v", "1.0");
form.add("sessionId", "mockSessionId1");
form.add("userName", "tomson");
form.add("salary", "2,500.00");
//address会正确绑定
form.add("address",
"<address zoneCode=\"0001\" doorCode=\"002\">\n" +
" <streets>\n" +
" <street no=\"001\" name=\"street1\"/>\n" +
" <street no=\"002\" name=\"street2\"/>\n" +
" </streets>\n" +
"</address>");
//对请求参数列表进行签名
String sign = RopUtils.sign(new ArrayList<String>(
form.keySet()), form.toSingleValueMap(), "abcdeabcdeabcdeabcdeabcde");
form.add("sign", sign);
String response = restTemplate.postForObject(
"http://localhost:8088/router", form, String.class);
System.out.println("response:\n" + response);
assertTrue(response.indexOf("<createUserResponse createTime=\"20120101010101\" userId=\"1\">") > -1);
}
来看一下服务端的
public class CreateUserRequest extends AbstractRopRequest {
@Pattern(regexp = "\\w{4,30}")
private String userName;
@IgnoreSign
@Pattern(regexp = "\\w{6,30}")
private String password;
@DecimalMin("1000.00")
@DecimalMax("100000.00")
@NumberFormat(pattern = "#,###.##")
private long salary;
@Valid
private Address address;//这个属性对象用于接受address请求参数的XML内容
...
}
来看一下Address的代码：
@XmlAccessorType(XmlAccessType.FIELD)
@XmlRootElement(name = "address")
public class Address {
@XmlAttribute
@Pattern(regexp = "\\w{4,30}")
private String zoneCode;
@XmlAttribute
private String doorCode;
@XmlElementWrapper(name = "streets")
@XmlElement(name = "street")
private List<Street> streets;
...
}
即也是采用和RopResponse一样的JAXB注解就可以了。
8.RopRequest和RopResponse都接口化
1)原来的RopRequest是一个类，系统级参数放在这个类中，现在移到RequestContext接口中，可以通过RopRequest#getRequestContext()访问这些系统级参数；
2）RequestContext对应每一个请求，它还包括以下接口方法：
//获取本次服务对应服务方法处的ServiceMethod注解的信息； ServiceMethodDefinition getServiceMethodDefinition(); //对应本次请求服务客户端传过来的所有参数列表 Map<String, String> getAllParams(); //可以获取客户端传过来的某个参数值 String getParamValue(String paramName); //获取原始的请求对象（目前都为HttpServletRequest对象） Object getRawRequestObject();
有了这个抽象，如果你的业务请求参数不需要合法性校验且数量很少，那么你就不要再为请求数据定义一个专门的请求类了，直接使用RopRequest作为服务方法的入参就可以了，如下所示：
//直接使用RopRequest对象作为入参
@ServiceMethod(value = "user.query", version = "1.0", httpAction = HttpAction.GET)
public RopResponse queryUsers(RopRequest request) throws Throwable {
//直接从参数列表中获取参数值
String userId = request.getRequestContext().getParamValue("userId");
CreateUserResponse response = new CreateUserResponse();
response.setCreateTime("20120101010102");
response.setUserId(userId);
response.setFeedback("user.query");
return response;
}
8.ServiceMethodBean
可以在服务类上打上这个注解就可以将其变成一个Bean了，此外它拥有和@Servicemethod类似的属性，如果一个服务类有拥有多个服务方法，这些服务方法都拥有一些相同的属性（如组名，TAG名等），那么可以在ServiceMethodBean中定义，方法处的@Servicemethod 将覆盖类处ServiceMethodBean的定义。
@ServiceMethodBean(value = "group1", title = "组1")
public class UserRestService {
@ServiceMethod(value = "user.add", version = "1.0")
public RopResponse addUser(CreateUserRequest request) {
...
}
//版本为2.0的user.add
@ServiceMethod(value = "user.add", version = "2.0")
public RopResponse addUser2(CreateUserRequest request) {
...
}
}
ServiceMethod比ServiceMethodBean多了方法名的属性，其它的属性ServiceMethodBean都有：
- value:组名，对应ServiceMethod的group
- title:组标识，对应ServiceMethod的groupTile
- TAG:tags
- timeout:过期时间，单位为秒
- httpAction：HTTP请求方法(GET,POST)
- needInSession：服务方法是否要工作于会话环境下（有些方法不需要会话，如获取软件的最新版本等），默认服务方法工作于会话环境下，如果没有会话将报错
- ignoreSign：方法是否要忽略签名，有些方法无需签名校验，默认要签名
- version：服务方法的版本号，如果你将不同版本的服务方法定义在不同类中，这个很有用
组、tags有什么用途呢？
它们可以访问你定义拦截器的拦截过滤规则，如果你的一个拦截器仅希望拦截每些服务方法，那么在制定拦截器的isMatch方法时，使用这些信息将非常方便。如下所示：
public boolean isMatch(RequestContext methodContext) {
if("group1".equals(methodContext.getServiceMethodDefinition().getMethodGroup())){
//do sth
}
}
9.请求数据签名的校验的启用和关闭
有些服务方法不需要签名校验，则可以方便地通过
@ServiceMethod(value = "service.method1",
ignoreSign = IgnoreSignType.NO)
public RopResponse service1() {
return new RopResponse() {
};
}
你也可以使整个Rop框架不启动签名校验（一般用于测试时使用）：
<rop:annotation-driven sign-enable="false"/>
这样它就会忽略服务方法处的设置，整体不启用签名校验了。
此外，如果你希望对某个服务方法的某些请求数据不签名（如图片数据这种），那么可以在请求对象类定义处使用@IgnoreSign，如下所示：
public class CreateUserRequest extends AbstractRopRequest {
@Pattern(regexp = "\\w{4,30}")
private String userName;
@IgnoreSign
@Pattern(regexp = "\\w{6,30}")
private String password;
@DecimalMin("1000.00")
@DecimalMax("100000.00")
@NumberFormat(pattern = "#,###.##")
private long salary;
@Valid
private Address address;
private String format;
private Telephone telephone;
}
这样，remark的请求参数就会忽略掉签名而仅对其它请求参数实施签名校验了（也即客户端在签名时不要将remark添加到SHA1(<secret><paramName><paramValue><secret>)的参数列表中进行签名了），客户端的调用如下所示：
@Test
public void testIngoreSignParamOfPassword() {
RestTemplate restTemplate = new RestTemplate();
MultiValueMap<String, String> form = new LinkedMultiValueMap<String, String>();
form.add("method", "user.add");//<--指定方法名称
form.add("appKey", "00001");
form.add("v", "1.0");
form.add("sessionId", "mockSessionId1");
form.add("userName", "tomsony");
form.add("salary", "2,500.00");
String sign = RopUtils.sign(new ArrayList<String>(
form.keySet()), form.toSingleValueMap(), "abcdeabcdeabcdeabcdeabcde");
form.add("sign", sign);
form.add("password", "123456"); //password无需签名，所以放在最后
String response = restTemplate.postForObject(
"http://localhost:8088/router", form, String.class);
System.out.println("response:\n" + response);
assertTrue(response.indexOf("<createUserResponse createTime=\"20120101010101\" userId=\"1\">") > -1);
}
10.服务方法不工作在会话环境下
有些方法在不需要会话的时候也能访问，如下载一张图片，检查软件的最新版本等服务，这时可以通过@ServiceMethod的needInSession来设置：
//版本为4.0的user.add:不需要会话
@ServiceMethod(value = "user.add", version = "4.0",needInSession = NeedInSessionType.NO)
public RopResponse addUser4(CreateUserRequest request) {
CreateUserResponse response = new CreateUserResponse();
//add creaet new user here...
response.setCreateTime("20120101010102");
response.setUserId("4");
return response;
}
以下测试方法在不提供sessionId系统级参数的情况下调用该服务方法：
@Test
public void testIngoreSession() {
RestTemplate restTemplate = new RestTemplate();
MultiValueMap<String, String> form = new LinkedMultiValueMap<String, String>();
form.add("appKey", "00001");
form.add("method", "user.add");//<--指定方法名称
form.add("v", "4.0");
form.add("userName", "tomsony");
form.add("salary", "2,500.00");
String sign = RopUtils.sign(new ArrayList<String>(
form.keySet()), form.toSingleValueMap(), "abcdeabcdeabcdeabcdeabcde");
form.add("sign", sign);
String response = restTemplate.postForObject(
"http://localhost:8088/router", form, String.class);
System.out.println("response:\n" + response);
assertTrue(response.indexOf("userId=\"4\"") > -1);
}