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

[b][size=x-large] Rop概述[/size][/b]

Rop是Rapid Open Platform的简称，它不同于一般纯技术型的Web Service框架（如CXF，Jersey等），Rop致力于构建开放服务平台的框架，您可以使用Rop开发类似于淘宝开放服务平台这样的服务平台。Rop充分借鉴了当前大型网站的开放服务平台的设计思路，汲取了它们成功的实践经验，对开放服务平台的很多应用层领域问题给出了解决方案，开发者可以直接使用这些解决方案，也可以在此基础上进行个性化扩展。

[b][size=large]Rop功能架构[/size][/b]


CXF和Jersey是纯技术纯的Web Service框架，而在Rop中，Web Service只是核心，它提供了开发服务平台的诸多领域问题的解决方案：如应用认证、会话管理、安全控制、错误模型、版本管理、超时限制等。
下面通过图1了解一下Rop框架的整体结构：

[img]http://dl.iteye.com/upload/attachment/0071/9534/d90a06f7-274b-3ab1-b829-850a8983f337.jpg[/img]
[align=center]图1[/align]

从图1中，可以看到Rop所提供的大部分功能都是偏“应用层”的，传统技术型的Web Service框架是不会僭越到这些“应用层”的问题的。但是，在实际开发中，这些应用层的问题不但不可避免，而且非常考验开发者的设计经验，此外，这些工作还会占用较大的开发工作量。Rop力图让开发者从这些复杂的工作中解脱出来，让他们可以真正聚焦服务平台业务逻辑的实现上。

[b][size=large]Rop技术架构[/size][/b]

Rop在技术实现上充分借鉴了Spring MVC的框架设计理念和实现技术，首先RopServlet类似于Spring MVC的DispatcherServlet，是Rop的门面Servlet，负责截获HTTP服务请求转由Rop框架处理。具体技术架构通过图2描述：

[img]http://dl.iteye.com/upload/attachment/0071/9536/4be7da56-d8d9-392f-854b-672d5fdac86a.jpg[/img]
[align=center]图2[/align]

Rop的配置信息统一在Spring配置文件中通过rop Schema命名空间定义。ServiceRouter是Rop框架的核心，它负责协调各组件的交互并最终完成服务处理的工作。RopServlet在启动时会从Spring容器中搜索出ServiceRouter的Bean实例并注册之。

在服务请求到达后，RopServlet截获请求并转交给ServiceRouter处理，ServiceRouter将服务请求封装成一个的RopRequestContext对象，RopRequestContext包含了服务请求的所有信息。而后，ServiceRouter使用SecurityManager检查服务请求的安全性，只有通过了SecurityManager的安全检查，才会调用目标服务处理方法执行服务，否则将阻止请求并返回错误响应信息。

完成SecurityManager的安全检查后，ServiceRouter通过ServiceMethodAdapter对目标的服务方法发起调用。由于具体服务方法的签名各不相同，因此必须采用反射机制进行适配调用。当返回响应对象后，ServiceRouter使用RopMarshaller将响应对象编组为特定的响应报文返回给客户端。

您会发现Rop的顶级框架接口类在Spring MVC中都能找到对应的对象：RopServlet对应DispatcherServlet，ServiceMethodAdapter对应HandlerAdapter，RopMarshaller对应ViewResolver，而ServiceRouter承担了HandlerMapping和部分DispatcherServlet的角色。因此，如果您在学习Spring MVC的框架后，理解Rop框架的实现原理将变得非常轻松。

[b][size=x-large]使用Rop开发一个服务[/size][/b]

[b][size=large]将Rop项目克隆到本地[/size][/b]

由于Rop托管在github (www.github.com)中，为了获取最新的Rop项目，必须在您的系统中安装Git客户端软件，我们推荐使用msysgit，它能够让我们在Windows系统中像Linux一样使用Git。
从http://code.google.com/p/msysgit/下载并安装git客户端msysgit，然而在开始菜单中找到并打开Git Bash，在命令窗口运行如下命令：

[quote]cd /d/agileSpring/
git clone git@github.com:itstamen/rop.git[/quote]

第一行命令将当前工作目录移到某个系统目录下，需要注意的是：由于msysgit是在Windows中模拟的Linux环境，所以D:/对应为/d/。第二行命令，从github中克隆一个Rop项目到您本地机中。

[img]http://dl.iteye.com/upload/attachment/0071/9565/c5068321-a142-313a-8b85-b5e93e204a97.jpg[/img]

使用以下的Maven命令构建rop和rop-sample项目，打开DOS窗口，移到rop及rop-sample项目的pom.xml所在的目录，执行构建命令：
[quote]mvn clean install[/quote]
还可以通过如下Maven命令，启动rop-sample项目（首先移到rop-sample的pom.xml所在的目录）：
[quote]mvn jetty:run[/quote]
如果你不想下载最新的Rop项目，上面的过程就可以免除了，您直接在项目的pom.xml中引入Rop类包就可以了，如下所示：

 <dependency>
     <groupId>com.bookegou</groupId>
     <artifactId>rop</artifactId>
     <version>1.0</version>
 </dependency>

Rop的发布包已经发布到Maven的核心仓库中（org.sonatype.oss），因此你可以直接使用在pom.xml引用即可。

[b][size=large]开发一个服务方法[/size][/b]

rop-sample项目中有一个com.rop.sample.UserService的服务类，我们就通过这个服务类了解开发基于Rop的Web Service服务的过程。

UserService.java

package com.rop.sample;

import com.rop.RopRequest;
import com.rop.annotation.NeedInSessionType;
import com.rop.annotation.ServiceMethod;
import com.rop.annotation.ServiceMethodBean;
import com.rop.sample.response.LogonResponse;
import com.rop.session.SimpleSession;

//①标注Rop的注解，使UserService成为一个Rop的服务Bean
@ServiceMethodBean 
public class UserService {  

//②使该服务方法成为一个Web Service的方法。
@ServiceMethod(method = "user.getSession", version = "1.0",   
needInSession = NeedInSessionType.NO)
public Object getSession(LogonRequest request) {

	//创建一个会话
	SimpleSession session = new SimpleSession();
	session.setAttribute("userName",request.getUserName());
	request.getRequestContext().addSession("mockSessionId1", session);

	//返回响应
	LogonResponse logonResponse = new LogonResponse();
	logonResponse.setSessionId("mockSessionId1");
	return logonResponse;
}

由于ServiceMethodBean注解已经标注了Spring的@Service注解（即org.springframework.stereotype.Service），因此标注@ServiceMethodBean的类也相当于标注了@Service，Rop扩展Spring @Service的目的是为了引入新的功能特性。
在类方法处标注@ServiceMethod，即可将该方法发布成一个Rop的Web Service服务。@ServiceMethod注解拥有丰富的参数，value值是必须的，它用于指定服务方法名称，version用于指定服务方法的版本号，needInSession用于说明该服务方法是否要工作在会话环境中。更多参数的说明，详见本章后续内容，这里只要了解这么多就可以了。

由于任何一个服务方法都是由请求/响应对构成的，所以在Rop的服务方法的签名是有约定的：入参必须为RopRequest接口或其子类，出参可以是任何标注了JSR 222注解的对象。这种约定在一定程度上限制了方法签名的灵活性，但是由于Rop强烈建议对所有请求参数都做服务端校验，因此把参数封装成一个Java类并在类属性中标注JSR 303注解，就可以在参数绑定时实施数据校验了。来看一下LogonRequest的类：

LogonRequest.java

package com.rop.sample.request;
import com.rop.AbstractRopRequest;
import com.rop.annotation.IgnoreSign;
import javax.validation.constraints.Pattern;

public class LogonRequest extends AbstractRopRequest{

    @Pattern(regexp = "\\w{4,30}") 
    private String userName;

    @IgnoreSign
    @Pattern(regexp = "\\w{6,30}") 
    private String password;

    //get/setter
}

Rop采用“契约优于配置”的原则：请求参数按名称匹配的方式自动绑定到请求对象的属性上。在请求对象类中，Rop使用JSR 303(Bean Validation )注解描述请求参数的校验规则，如果请求参数值违反了校验规则，Rop将驳回服务请求，直接返回相应的错误报文给客户端。

服务方法必须返回一个响应对象，Rop框架会将其转换成响应报文。在这个例子中，如果服务正常执行，将返回一个LogonResponse的对象。LogonResponse类定义如下：

package com.rop.sample.response;

import javax.xml.bind.annotation.XmlAccessType;
import javax.xml.bind.annotation.XmlAccessorType;
import javax.xml.bind.annotation.XmlAttribute;
import javax.xml.bind.annotation.XmlRootElement;

@XmlAccessorType(XmlAccessType.FIELD)
@XmlRootElement(name = "logonResponse")
public class LogonResponse{

    @XmlAttribute
    private String sessionId;

    …
}

Rop使用JSR 222(即JAXB)注解描述响应类到响应报文的转换映射关系，响应对象最终将以响应报文的形式（XML或JSON）返回给客户端。

[b][size=large]如何在Spring中配置Rop[/size][/b]

Rop基于Spring框架工作，可以看成是一个Spring的子项目。Rop提供了一个扩展的Spring Schema命令空间，使用Rop Schema在Spring配置文件配置好Rop环境非常方便：

sampleRopApplicationContext.xml

<?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.bookegou.com/schema/rop"
       xsi:schemaLocation="http://www.springframework.org/schema/beans
       http://www.springframework.org/schema/beans/spring-beans-3.1.xsd
http://www.springframework.org/schema/context
       http://www.springframework.org/schema/context/spring-context-3.1.xsd

       http://www.bookegou.com/schema/rop    ①引入Rop Schema定义文件 
http://www.bookegou.com/schema/rop/rop-1.0.xsd">

    <!--② 扫描Spring Bean-->
    <context:component-scan base-package="com.rop.sample"/>

    <!--③启动Rop框架 -->
    <rop:annotation-driven/>
</beans>

首先，引入Rop的Schema命名空间，如①处所示。由于Rop的服务类必须是一个Bean，所以需要声明Spring的扫描器，将标注了Spring Bean注解的类加载为Spring容器中的Bean。由于@ServiceMethodBean注解本身标注了Spring的@Service，所以所有标注了@ServiceMethodBean的类也会自动成为Spring的Bean。最后，我们通过一个简单<rop:annotation-driven/>即可启动Rop框架，如③所示。

[b][size=large]在web.xml配置Rop[/size][/b]

由于客户端需要通过HTTP访问Rop服务，因此Rop必须依附于一个Web Servlet容器。和Spring MVC的DispatcherServlet类似，Rop提供了一个com.rop.RopServlet，在web.xml中配置好RopServlet，这样Rop就可以接收HTTP的服务请求了：

web.xml

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="http://java.sun.com/xml/ns/javaee"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://java.sun.com/xml/ns/javaee
		  http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"
         version="2.5">
    <context-param>
        <param-name>contextConfigLocation</param-name>
        <param-value>
            classpath*:sampleRopApplicationContext.xml
        </param-value>
    </context-param>

    <listener>
        <listener-class>org.springframework.web.context.ContextLoaderListener</listener-class>
    </listener>
    <listener>
        <listener-class>org.springframework.web.util.Log4jConfigListener</listener-class>
    </listener>

    <!--①定义一个RopServlet,并指定其映射的URL-->
    <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>
</web-app>

由于Rop是基于Spring工作的，因此首先必须在web.xml中配置一个Spring容器，然后再通过RopServlet指定Rop的工作的路径。

[quote]值得注意的是，Rop依赖于Spring框架而非Spring MVC框架，因此你的Web应用框架是可以自由选择的，如Struts、JSF等。[/quote]

[b][size=large]访问Rop服务[/size][/b]

在rop-sample项目中，我们已经配置maven-jetty-plugin插件，因此IDE的环境下可以直接运行这个插件：jetty->jetty:run 启动rop-sample项目。在控制台中，您将可以看到rop-sample启动的输出信息。（也可以在DOS窗口下执行 mvn jetty:run命令启动）

下面开发一个访问rop-sample服务的客户端程序：

package com.rop.sample;

import com.rop.client.CompositeResponse;
import com.rop.client.DefaultRopClient;
import com.rop.client.RopClient;
import com.rop.client.ClientRequest;
import com.rop.sample.request.LogonRequest;
import com.rop.sample.response.LogonResponse;
import org.testng.annotations.Test;
import static org.testng.Assert.*;

public class UserServiceClient {

    //①
    public static final String SERVER_URL = "http://localhost:8088/router"; 
    public static final String APP_KEY = "00001";
    public static final String APP_SECRET = "abcdeabcdeabcdeabcdeabcde";
    private RopClient ropClient = 
new DefaultRopClient(SERVER_URL, APP_KEY, APP_SECRET);

    @Test
public void createSession() {

        //②构造请求对象
        LogonRequest ropRequest = new LogonRequest();  
        ropRequest.setUserName("tomson");
        ropRequest.setPassword("123456");


        //③对服务发起调用并获取响应结果
        CompositeResponse response = ropClient.buildClientRequest()
                       .get(ropRequest, LogonResponse.class, "user.getSession", "1.0");

        assertNotNull(response);
        assertTrue(response.isSuccessful());
        assertNotNull(response.getSuccessResponse());
        assertTrue(response.getSuccessResponse() instanceof LogonResponse);
        assertEquals(((LogonResponse) response.getSuccessResponse()).getSessionId(), 
                     "mockSessionId1");
    }
}

大凡Web Service框架都会提供服务的客户端，DefaultRopClient即是Rop提供了客户端，您可以非常方便地通过DefaultRopClient以面向对象的方式访问服务获取响应对象，无需关心服务请求和响应报文的底层细节。
运行以上测试方法，通过报文抓取工具，我们可以看到“真实”的底层通信细节，如下图4所示：

[img]http://dl.iteye.com/upload/attachment/0071/9588/51e42976-158c-3412-9887-c7ba6bf31d3d.jpg[/img]

由此可见，DefaultRopClient会自动将LogonRequest请求对象拼装成一个请求URL，同时，在接收到响应报文后，会将响应报文反编组成一个响应对象。