自己动手写淘宝开放平台:Rop(将WebService REST进行到底!!)

http://www.iteye.com/topic/1121252

简介

最近在开发自己公司网站的开放API服务，较深入地研究了 TOP（Taobao Open Platform:淘宝开放平台 http://api.taobao.com ）。在接触过这么多的网站API中，发现TOP真的是做得非常不错，结构清晰明了，使用简单轻便。但是TOP没有开源，搞不到TOP的源码。所以只能“自己动手，丰衣足食”了。
我基于Spring MVC 3.0进行开发，居然3天就完工了，现在已经在公司中使用，大家的反映相当不错，现已整理了一份PPT文档，奉献给大家。同时，我将其命名为ROP（Rest Open Platform）,已经在github中发布，地址是：

https://github.com/itstamen/rop

iteye的Rop群组已经改变很大，最新消息请加入群中了解：http://rop.group.iteye.com/


欢迎大家讨论!
ROP的快速开发完成，其实是借力于Spring MVC灵活的扩展性和其提供了各种好用且强大的工具类，ROP基于Spring MVC，在处理流程上进行了重新的组织，但是在实现上基本上直接利用Spring提供的工具类和组件，所以实现并不太难。

5分钟快速入门

以下是基于ROP开发Web Service的简单例子：
例子说明：
根据userName/password/salary这三个属性创建一个新用户。
第1步：创建请求对象

Java代码

1. packagecom.sample.rop.request;
2. importcom.stamen.rop.RopRequest;
3. importorg.springframework.format.annotation.NumberFormat;
4. importjavax.validation.constraints.DecimalMax;
5. importjavax.validation.constraints.DecimalMin;
6. importjavax.validation.constraints.Pattern;
8. publicclassCreateUserRequestextendsRopRequest{
10. @Pattern(regexp="\\w{4,30}")//①通过JSR303注解指定验证规则
11. privateStringuserName;
13. @Pattern(regexp="\\w{6,30}")//②
14. privateStringpassword;
16. @DecimalMin("1000.00")
17. @DecimalMax("100000.00")
18. @NumberFormat(pattern="#,###.##")//③
19. privatelongsalary;
21. //getterandsetter...
22. }

①、②及③处通过JSR303注解指定请求参数的合法性规则，如果请求参数值违反了规则，ROP会产生相应的错误报文。

第2步：创建响应对象

Java代码

1. packagecom.sample.rop;
2. importcom.rop.RopResponse;
3. importjavax.xml.bind.annotation.XmlAccessType;
4. importjavax.xml.bind.annotation.XmlAccessorType;
5. importjavax.xml.bind.annotation.XmlAttribute;
6. importjavax.xml.bind.annotation.XmlRootElement;
7. @XmlAccessorType(XmlAccessType.FIELD)//①
8. @XmlRootElement(name="sampleRopResponse1")
9. publicclassCreateUserResponseimplementsRopResponse{
10. @XmlAttribute//②
11. privateStringuserId;
12. @XmlAttribute//③
13. privateStringcreateTime;
14. //getterandsetter...
15. }

①、②及③处通过JAXB（即JSR222 已经包含在JDK6中）的注解对响应对象的流化规则进行设置，ROP会自动将响应的对象流化成相应的响应报文，支持XML和JSON格式，仅需通过format的参数进行指定返回格式即可。

第3步：创建服务方法

Java代码

1. packagecom.sample.rop;
3. importcom.rop.ApiMethod;
4. importcom.sample.rop.request.CreateUserRequest;
5. importcom.sample.rop.response.CreateUserResponse;
6. importorg.springframework.stereotype.Service;
8. @Service//①服务方法所在的类必须标注成Bean
9. publicclassUserRestService{
11. @ApiMethod("sample.user.add")//②指定对应的API方法
12. publicRopResponseaddUser(CreateUserRequestrequest){
13. CreateUserResponseresponse=newCreateUserResponse();
14. //addcreaetnewuserhere...
15. response.setCreateTime("20120101010101");
16. response.setUserId("1");
17. returnresponse;
18. }
19. }

首先，服务方法所在的类必须标注成Bean,如①所示，然后在服务方法中标注ROP的@ApiMethod注解，如②所示，这里的
@ApiMethod(" sample.user.add ")表示，addUser(...)将处理?method= sample.user.add &...的服务请求。
处理方法的签名规约如下：

• 入参必须继承于RopRequest父类，也可以为空（无入参）；
• 返回值必须实现RopResponse接口，由于一般的服务方法都拥有错误的可能，因此一般直接使用RopResponse作为返回类型，这样不管是正确的响应对象，还是错误的响应对象，都可以满足签名的要求。

这样，所有服务端的开发工作就完成了！下面来写客户端调用的代码。

编写调用的客户端

由于现在ROP还没有提供客户端调用包，所以我们直接使用Spring的RestTemplate来写：

Java代码

1. packagecom.sample.rop;
3. importcom.rop.validation.DefaultRopValidator;
4. importorg.springframework.util.LinkedMultiValueMap;
5. importorg.springframework.util.MultiValueMap;
6. importorg.springframework.web.client.RestTemplate;
7. importjava.util.ArrayList;
9. publicclassUserRestServiceClient{
11. publicstaticvoidmain(String[]args){
12. RestTemplaterestTemplate=newRestTemplate();
13. MultiValueMap<String,String>form=newLinkedMultiValueMap<String,String>();
14. form.add("method","sample.user.add");//<--指定服务名
15. form.add("appKey","00001");//<--指定客户端应用的key,我们在rop.appSecret.properties
16. //中预定义了两个appKey,服务端可通过实现AppSecretManager
17. //定义自己的appKey管理策略。
18. form.add("v","1.0");
20. form.add("sessionId","test");//真实系统时，必须是真正的sessionId.
21. form.add("format","xml");
22. form.add("locale","en");
24. form.add("userName","tomson");
25. form.add("password","123456");
26. form.add("salary","2,500.00");
28. //对请求参数进行签名，对于"00001"appKey的密钥是"abcdeabcdeabcdeabcdeabcde"
29. Stringsign=DefaultRopValidator.sign(newArrayList<String>(
30. form.keySet()),form.toSingleValueMap(),
31. "abcdeabcdeabcdeabcdeabcde");
33. form.add("sign",sign);
35. //发送请求，调用服务
36. Stringresponse=restTemplate.postForObject(
37. "http://localhost:9080/router",form,String.class);
38. System.out.println("response:\n"+response);
39. }
40. }

这里的系统级参数，我们直接模仿TOP设计，说明如下：

No	parmName	paramType	required	desc
1.	method	String	Y	API method name(sample.user.add)
2.	appKey	String	Y	design to application's appKey，you can define in rop.appSecret.properties which is in classpath.
3.	v	String	Y	API version，now only support:1.0。
4.	sign	String	Y	API parameters's sing，Use SHA1 encryption algorithm
5.	sessionId	String	N	use's sessionId.you can provide a rest api so client can get it and maintain locally.
6.	format	String	N	Optional, designated response format. The default XML,currently support for an XML format, json
7.	locale	String	N	locale，such lick cn_ZH,en...

参见： http://open.taobao.com/doc/detail.htm?id=111
启用服务端的服务后，执行该测试，将返回：

Xml代码

1. <?xmlversion="1.0"encoding="utf-8"standalone="yes"?>
2. <sampleRopResponse1createTime="20120101010101"userId="1"/>

如果将format参数设置为json，则其返回的报文为：

Javascript代码

1. {"sampleRopResponse1":{"userId":"1","createTime":"20120101010101"}}

如果将salary参数改为"aaa",则将返回错误报文(假设format为xml)：

Xml代码

1. <?xmlversion="1.0"encoding="utf-8"standalone="yes"?>
2. <errorsolution="InvalidArguments"message="InvalidArguments"code="34">
3. <subErrors>
4. <subError>
5. <code>isv.parameters-mismatch:salary-and-aaa</code>
6. <message>incomingparametersalaryandaaadoesnotmatch,both
8. haveacertaincorrespondencebetween</message>
9. </subError>
10. </subErrors>
11. </error>