Rop开发手册(1):最简单的服务开放平台框架
程序员文章站
2022-04-15 20:28:24
...
Rop概述
Rop是Rapid Open Platform的简称,它不同于一般纯技术型的Web Service框架(如CXF,Jersey等),Rop致力于构建开放服务平台的框架,您可以使用Rop开发类似于淘宝开放服务平台这样的服务平台。Rop充分借鉴了当前大型网站的开放服务平台的设计思路,汲取了它们成功的实践经验,对开放服务平台的很多应用层领域问题给出了解决方案,开发者可以直接使用这些解决方案,也可以在此基础上进行个性化扩展。
Rop功能架构
CXF和Jersey是纯技术纯的Web Service框架,而在Rop中,Web Service只是核心,它提供了开发服务平台的诸多领域问题的解决方案:如应用认证、会话管理、安全控制、错误模型、版本管理、超时限制等。
下面通过图1了解一下Rop框架的整体结构:
从图1中,可以看到Rop所提供的大部分功能都是偏“应用层”的,传统技术型的Web Service框架是不会僭越到这些“应用层”的问题的。但是,在实际开发中,这些应用层的问题不但不可避免,而且非常考验开发者的设计经验,此外,这些工作还会占用较大的开发工作量。Rop力图让开发者从这些复杂的工作中解脱出来,让他们可以真正聚焦服务平台业务逻辑的实现上。
Rop技术架构
Rop在技术实现上充分借鉴了Spring MVC的框架设计理念和实现技术,首先RopServlet类似于Spring MVC的DispatcherServlet,是Rop的门面Servlet,负责截获HTTP服务请求转由Rop框架处理。具体技术架构通过图2描述:
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框架的实现原理将变得非常轻松。
使用Rop开发一个服务
将Rop项目克隆到本地
由于Rop托管在github (www.github.com)中,为了获取最新的Rop项目,必须在您的系统中安装Git客户端软件,我们推荐使用msysgit,它能够让我们在Windows系统中像Linux一样使用Git。
从http://code.google.com/p/msysgit/下载并安装git客户端msysgit,然而在开始菜单中找到并打开Git Bash,在命令窗口运行如下命令:
第一行命令将当前工作目录移到某个系统目录下,需要注意的是:由于msysgit是在Windows中模拟的Linux环境,所以D:/对应为/d/。第二行命令,从github中克隆一个Rop项目到您本地机中。
使用以下的Maven命令构建rop和rop-sample项目,打开DOS窗口,移到rop及rop-sample项目的pom.xml所在的目录,执行构建命令:
还可以通过如下Maven命令,启动rop-sample项目(首先移到rop-sample的pom.xml所在的目录):
如果你不想下载最新的Rop项目,上面的过程就可以免除了,您直接在项目的pom.xml中引入Rop类包就可以了,如下所示:
Rop的发布包已经发布到Maven的核心仓库中(org.sonatype.oss),因此你可以直接使用在pom.xml引用即可。
开发一个服务方法
rop-sample项目中有一个com.rop.sample.UserService的服务类,我们就通过这个服务类了解开发基于Rop的Web Service服务的过程。
UserService.java
由于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
Rop采用“契约优于配置”的原则:请求参数按名称匹配的方式自动绑定到请求对象的属性上。在请求对象类中,Rop使用JSR 303(Bean Validation )注解描述请求参数的校验规则,如果请求参数值违反了校验规则,Rop将驳回服务请求,直接返回相应的错误报文给客户端。
服务方法必须返回一个响应对象,Rop框架会将其转换成响应报文。在这个例子中,如果服务正常执行,将返回一个LogonResponse的对象。LogonResponse类定义如下:
Rop使用JSR 222(即JAXB)注解描述响应类到响应报文的转换映射关系,响应对象最终将以响应报文的形式(XML或JSON)返回给客户端。
如何在Spring中配置Rop
Rop基于Spring框架工作,可以看成是一个Spring的子项目。Rop提供了一个扩展的Spring Schema命令空间,使用Rop Schema在Spring配置文件配置好Rop环境非常方便:
sampleRopApplicationContext.xml
首先,引入Rop的Schema命名空间,如①处所示。由于Rop的服务类必须是一个Bean,所以需要声明Spring的扫描器,将标注了Spring Bean注解的类加载为Spring容器中的Bean。由于@ServiceMethodBean注解本身标注了Spring的@Service,所以所有标注了@ServiceMethodBean的类也会自动成为Spring的Bean。最后,我们通过一个简单<rop:annotation-driven/>即可启动Rop框架,如③所示。
在web.xml配置Rop
由于客户端需要通过HTTP访问Rop服务,因此Rop必须依附于一个Web Servlet容器。和Spring MVC的DispatcherServlet类似,Rop提供了一个com.rop.RopServlet,在web.xml中配置好RopServlet,这样Rop就可以接收HTTP的服务请求了:
web.xml
由于Rop是基于Spring工作的,因此首先必须在web.xml中配置一个Spring容器,然后再通过RopServlet指定Rop的工作的路径。
访问Rop服务
在rop-sample项目中,我们已经配置maven-jetty-plugin插件,因此IDE的环境下可以直接运行这个插件:jetty->jetty:run 启动rop-sample项目。在控制台中,您将可以看到rop-sample启动的输出信息。(也可以在DOS窗口下执行 mvn jetty:run命令启动)
下面开发一个访问rop-sample服务的客户端程序:
大凡Web Service框架都会提供服务的客户端,DefaultRopClient即是Rop提供了客户端,您可以非常方便地通过DefaultRopClient以面向对象的方式访问服务获取响应对象,无需关心服务请求和响应报文的底层细节。
运行以上测试方法,通过报文抓取工具,我们可以看到“真实”的底层通信细节,如下图4所示:
由此可见,DefaultRopClient会自动将LogonRequest请求对象拼装成一个请求URL,同时,在接收到响应报文后,会将响应报文反编组成一个响应对象。
Rop是Rapid Open Platform的简称,它不同于一般纯技术型的Web Service框架(如CXF,Jersey等),Rop致力于构建开放服务平台的框架,您可以使用Rop开发类似于淘宝开放服务平台这样的服务平台。Rop充分借鉴了当前大型网站的开放服务平台的设计思路,汲取了它们成功的实践经验,对开放服务平台的很多应用层领域问题给出了解决方案,开发者可以直接使用这些解决方案,也可以在此基础上进行个性化扩展。
Rop功能架构
CXF和Jersey是纯技术纯的Web Service框架,而在Rop中,Web Service只是核心,它提供了开发服务平台的诸多领域问题的解决方案:如应用认证、会话管理、安全控制、错误模型、版本管理、超时限制等。
下面通过图1了解一下Rop框架的整体结构:
图1
从图1中,可以看到Rop所提供的大部分功能都是偏“应用层”的,传统技术型的Web Service框架是不会僭越到这些“应用层”的问题的。但是,在实际开发中,这些应用层的问题不但不可避免,而且非常考验开发者的设计经验,此外,这些工作还会占用较大的开发工作量。Rop力图让开发者从这些复杂的工作中解脱出来,让他们可以真正聚焦服务平台业务逻辑的实现上。
Rop技术架构
Rop在技术实现上充分借鉴了Spring MVC的框架设计理念和实现技术,首先RopServlet类似于Spring MVC的DispatcherServlet,是Rop的门面Servlet,负责截获HTTP服务请求转由Rop框架处理。具体技术架构通过图2描述:
图2
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框架的实现原理将变得非常轻松。
使用Rop开发一个服务
将Rop项目克隆到本地
由于Rop托管在github (www.github.com)中,为了获取最新的Rop项目,必须在您的系统中安装Git客户端软件,我们推荐使用msysgit,它能够让我们在Windows系统中像Linux一样使用Git。
从http://code.google.com/p/msysgit/下载并安装git客户端msysgit,然而在开始菜单中找到并打开Git Bash,在命令窗口运行如下命令:
引用
cd /d/agileSpring/
git clone git@github.com:itstamen/rop.git
git clone git@github.com:itstamen/rop.git
第一行命令将当前工作目录移到某个系统目录下,需要注意的是:由于msysgit是在Windows中模拟的Linux环境,所以D:/对应为/d/。第二行命令,从github中克隆一个Rop项目到您本地机中。
使用以下的Maven命令构建rop和rop-sample项目,打开DOS窗口,移到rop及rop-sample项目的pom.xml所在的目录,执行构建命令:
引用
mvn clean install
还可以通过如下Maven命令,启动rop-sample项目(首先移到rop-sample的pom.xml所在的目录):
引用
mvn jetty:run
如果你不想下载最新的Rop项目,上面的过程就可以免除了,您直接在项目的pom.xml中引入Rop类包就可以了,如下所示:
<dependency> <groupId>com.bookegou</groupId> <artifactId>rop</artifactId> <version>1.0</version> </dependency>
Rop的发布包已经发布到Maven的核心仓库中(org.sonatype.oss),因此你可以直接使用在pom.xml引用即可。
开发一个服务方法
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)返回给客户端。
如何在Spring中配置Rop
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框架,如③所示。
在web.xml配置Rop
由于客户端需要通过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的工作的路径。
引用
值得注意的是,Rop依赖于Spring框架而非Spring MVC框架,因此你的Web应用框架是可以*选择的,如Struts、JSF等。
访问Rop服务
在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所示:
由此可见,DefaultRopClient会自动将LogonRequest请求对象拼装成一个请求URL,同时,在接收到响应报文后,会将响应报文反编组成一个响应对象。