自己动手写淘宝开放平台: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. package com.sample.rop.request;  
2. import com.stamen.rop.RopRequest;  
3. import org.springframework.format.annotation.NumberFormat;  
4. import javax.validation.constraints.DecimalMax;  
5. import javax.validation.constraints.DecimalMin;  
6. import javax.validation.constraints.Pattern;  
7.   
8. public class CreateUserRequest extends RopRequest {  
9.   
10. @Pattern(regexp = "\\w{4,30}")//① 通过JSR303注解指定验证规则  
11. private String userName;  
12.   
13. @Pattern(regexp = "\\w{6,30}")//②  
14. private String password;  
15.   
16. @DecimalMin("1000.00")  
17. @DecimalMax("100000.00")  
18. @NumberFormat(pattern = "#,###.##")//③  
19. private long salary;  
20.   
21. //getter and setter...  
22. }  

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

第2步：创建响应对象  

Java代码  

1. package com.sample.rop;  
2. import com.rop.RopResponse;  
3. import javax.xml.bind.annotation.XmlAccessType;  
4. import javax.xml.bind.annotation.XmlAccessorType;  
5. import javax.xml.bind.annotation.XmlAttribute;  
6. import javax.xml.bind.annotation.XmlRootElement;  
7. @XmlAccessorType(XmlAccessType.FIELD) //①  
8. @XmlRootElement(name = "sampleRopResponse1")  
9. public class CreateUserResponse implements RopResponse{  
10.     @XmlAttribute//②  
11.     private String userId;  
12.     @XmlAttribute//③  
13.     private String createTime;  
14.    //getter and setter...  
15. }  

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

第3步：创建服务方法  

Java代码  

1. package com.sample.rop;  
2.   
3. import com.rop.ApiMethod;  
4. import com.sample.rop.request.CreateUserRequest;  
5. import com.sample.rop.response.CreateUserResponse;  
6. import org.springframework.stereotype.Service;  
7.   
8. @Service//① 服务方法所在的类必须标注成Bean  
9. public class UserRestService {  
10.   
11.     @ApiMethod("sample.user.add")//②指定对应的API方法  
12.     public RopResponse addUser(CreateUserRequest request) {  
13.         CreateUserResponse response = new CreateUserResponse();  
14.         //add creaet new user here...  
15.         response.setCreateTime("20120101010101");  
16.         response.setUserId("1");  
17.         return response;  
18.     }  
19. }  

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

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

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

编写调用的客户端  

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

Java代码  

1. package com.sample.rop;  
2.   
3. import com.rop.validation.DefaultRopValidator;  
4. import org.springframework.util.LinkedMultiValueMap;  
5. import org.springframework.util.MultiValueMap;  
6. import org.springframework.web.client.RestTemplate;  
7. import java.util.ArrayList;  
8.   
9. public class UserRestServiceClient {  
10.   
11.     public static void main(String[] args) {  
12.         RestTemplate restTemplate = new RestTemplate();  
13.         MultiValueMap<String, String> form = new LinkedMultiValueMap<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");  
19.   
20.         form.add("sessionId", "test");//真实系统时，必须是真正的sessionId.  
21.         form.add("format", "xml");  
22.         form.add("locale", "en");  
23.   
24.         form.add("userName", "tomson");  
25.         form.add("password", "123456");  
26.         form.add("salary", "2,500.00");  
27.   
28.         //对请求参数进行签名，对于"00001" appKey的密钥是"abcdeabcdeabcdeabcdeabcde"  
29.         String sign = DefaultRopValidator.sign(new ArrayList<String>(  
30.                             form.keySet()), form.toSingleValueMap(),  
31.                             "abcdeabcdeabcdeabcdeabcde");  
32.   
33.         form.add("sign", sign);  
34.   
35.         //发送请求，调用服务  
36.         String response = 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. <?xml version="1.0" encoding="utf-8" standalone="yes"?>  
2. <sampleRopResponse1 createTime="20120101010101" userId="1"/>  

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

Javascript代码  

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

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

Xml代码  

1. <?xml version="1.0" encoding="utf-8" standalone="yes"?>  
2. <error solution="Invalid Arguments" message="Invalid Arguments " code="34">  
3.     <subErrors>  
4.         <subError>  
5.             <code>isv.parameters-mismatch:salary-and-aaa</code>  
6.             <message>incoming parameter salary and aaa does not match, both   
7.   
8. have a certain correspondence between</message>  
9.         </subError>  
10.     </subErrors>  
11. </error>