基于SpringMVC的RESTful API设计

REST(Representational State Transfer)描述了一种软件架构风格，相比SOAP和RPC更加简单明了，目前互联公司越来越流行提供RESTful形式的API供第三方调用。REST通过与标准的HTTP方法进行映射，能够完整地表述系统资源的各种形为。SpringMVC从3.0的开始增加了RESTful功能，因其快速简单、与Spring框架无缝集成等优点，被广大Java开发者奉为RESTful首选。本文基于SpringMVC3.2.5和maven讲解如何通过SpringMVC构造企业级应用基础的RESTful
API，对开发人员快速开发企业级项目集成有所帮助。

　　1. 基于Maven创建SpringMVC工程

　　Maven是一个项目管理工具，它包含了一个项目对象模型 (Project Object Model)，使用Maven能够快速完成Spring MVC工程的创建，而不必去逐个下载Spring MVC的依赖jar包。

　　Maven创建Spring MVC非常简单，主要包括以下几步：

　　1)创建工程

mvn archetype:generate

-DgroupId=com.ibm.cdl

-DartifactId=spirngmvc-restful

-DarchetypeArtifactId=maven-archetype-webapp

-DinteractiveMode=false

　　2)修改POM文件，内容如下：

　　略

　　3)基本框架已经生成，后续根据实际需求编辑RESTful API

　　2. Token认证机制

　　RESTful提供的API是无状态的，下一次调用请求与当前的调用请求是完全无关，但这就无法保证系统资源的安全性。Token机制就是用来解决无状态和安全性之间的矛盾。其实现机理主机如下：

　　1)用户发送用户名和密码(加密密码)，验证请求通过

　　2)服务器通过SSO服务判断用户名和密码是否正确

　　3)验证通过，返回Token及过期时间

　　4)后边所有请求在这段时间内携带这一Token即可使用其他API

@Controller

@RequestMapping("/admin/v1/")

public class AuthenticateAPI {

@Autowired

private UserService userService;

/**

* 用户授权验证

* @param param

* @return

*/

@RequestMapping(value="/tokens",method=RequestMethod.POST)

@ResponseBody

public String authenticate(@RequestBody String param){

try {

User user = JSON.parseObject(param, User.class);

Token token = userService.login(user);

if(token == null){

throw new CutomizedException(HttpStatus.UNAUTHORIZED, "User authenticate failed.");

}

TokenResponseEntity tokenResponseEntity = new TokenResponseEntity();

tokenResponseEntity.setEntity(token);

tokenResponseEntity.setHttpStatus(HttpStatus.OK);

tokenResponseEntity.setMessage("User authenticate successful.");

return JSON.toJSONStringWithDateFormat(tokenResponseEntity, "yyyy-MM-dd HH:mm:ss", SerializerFeature.WriteDateUseDateFormat);

}catch(JSONException e){

throw new CutomizedException(HttpStatus.BAD_REQUEST, "Bad request body.");

}catch (Exception e) {

throw new CutomizedException(HttpStatus.INTERNAL_SERVER_ERROR, "Server internal error");

}

}

}

　　3. Token验证

　　考虑到安全性，除了Token认证的API外，其他所有的请求都需要经过Token验证，SpringMVC提供的@ModelAttribute("tokenIdValidateResult")注解能够预先对所有方法进Token有效性的验证，一旦Token过期或者Token验证失败，则不允许调用方进行相关操作，具体实现过程如下：

/**

* All Method need to validate token id

* @param headers

* @return

*/

@ModelAttribute("tokenIdValidateResult")

public TokenValidateResult validateTokenId(@RequestHeader HttpHeaders headers){

String tokenId=headers.getFirst("X-Auth-Token");

Token searchToken = new Token();

searchToken.setTokenId(tokenId);

if(StringUtils.isEmpty(tokenId)){

return TokenValidateResult.TOKEN_EMPTY;

}

Token token=tokenService.findOneByExample(searchToken);

//Token not exists

if(token==null){

return TokenValidateResult.TOKEN_NOT_EXIST;

}

//Token 过期

if(token.getExpireTime().before(new Date())){

return TokenValidateResult.TOKEN_EXPIRED;

}

//Success

return TokenValidateResult.SUCCESS;

}

　　4. 创建资源

　　创建资源采用HTTP中的POST请求来实现。

　　创建Resource API示例：

@Controller

@RequestMapping(value="/resources/v1")

public class ResourceAPI {

@RequestMapping(method=RequestMethod.POST)

@ResponseBody

public ResourceResponseEntity createResource(@ModelAttribute("tokenIdValidateResult")TokenValidateResult tokenIdValidateResult,@RequestHeader HttpHeaders headers,@JsonParam ResourceReponseEntity resourceResponseEntity ) {

if(tokenIdValidateResult == TokenValidateResult.SUCCESS){

try {

String tokenId=headers.getFirst("X-Auth-Token");

Token searchToken = new Token();

searchToken.setTokenId(tokenId);

//TODO:创建Resource

return resourceResponseEntity;

} catch (Exception e) {

throw new CutomizedException(e);

}

}else{

//异常处理交给异常处理框架

throw new CutomizedException(HttpStatus.UNAUTHORIZED,"Token validte failed,ErrorCode:"+tokenIdValidateResult);

}

}

}

　　5. 更新资源属性

　　更新资源采用HTTP中的PUT请求来实现。具体实现如下：

@Controller

@RequestMapping(value="/resources/v1")

public class ResourceAPI {

@RequestMapping(value="/{id}",method=RequestMethod.PUT)

@ResponseBody

public ResourceResponseEntity createResource(@ModelAttribute("tokenIdValidateResult")TokenValidateResult tokenIdValidateResult,

@PathVariable Integer id,

@RequestHeader HttpHeaders headers,

@JsonParam Resource resource) {

if(tokenIdValidateResult == TokenValidateResult.SUCCESS){

try {

String tokenId=headers.getFirst("X-Auth-Token");

Token searchToken = new Token();

searchToken.setTokenId(tokenId);

//TODO:更新Resource

return resourceResposeEntity;

} catch (Exception e) {

throw new CutomizedException(e);

}

}else{

//异常处理交给异常处理框架

throw new CutomizedException(HttpStatus.UNAUTHORIZED,"Token validte failed,ErrorCode:"+tokenIdValidateResult);

}

}

}

　　6. 删除资源

　　删除资源采用HTTP中的DELETE请求来实现。具体实现如下：

@Controller

@RequestMapping(value="/resources/v1")

public class ResourceAPI {

@RequestMapping(value="/{id}",method=RequestMethod.DELETE)

@ResponseBody

public ResourceResponseEntity createResource(@ModelAttribute("tokenIdValidateResult")TokenValidateResult tokenIdValidateResult,

@PathVariable Integer id,

@RequestHeader HttpHeaders headers) {

if(tokenIdValidateResult == TokenValidateResult.SUCCESS){

try {

String tokenId=headers.getFirst("X-Auth-Token");

Token searchToken = new Token();

searchToken.setTokenId(tokenId);

//TODO:删除Resource

return resourceResposeEntity;

} catch (Exception e) {

throw new CutomizedException(e);

}

}else{

//异常处理交给异常处理框架

throw new CutomizedException(HttpStatus.UNAUTHORIZED,"Token validte failed,ErrorCode:"+tokenIdValidateResult);

}

}

}

　　7. 获取资源列表及单个资源信息

　　获取资源信息采用HTTP协议中的GET请求实现，具体实现如下：

@Controller

@RequestMapping(value="/resources/v1")

public class ResourceAPI {

@RequestMapping(method=RequestMethod.GET)

@ResponseBody

public ResourceResponseEntity createResource(@ModelAttribute("tokenIdValidateResult")TokenValidateResult tokenIdValidateResult,@RequestHeader HttpHeaders headers) {

if(tokenIdValidateResult == TokenValidateResult.SUCCESS){

try {

String tokenId=headers.getFirst("X-Auth-Token");

Token searchToken = new Token();

searchToken.setTokenId(tokenId);

//TODO:删除Resource列表

return resourceResposeEntity;

} catch (Exception e) {

throw new CutomizedException(e);

}

}else{

//异常处理交给异常处理框架

throw new CutomizedException(HttpStatus.UNAUTHORIZED,"Token validte failed,ErrorCode:"+tokenIdValidateResult);

}

}

@RequestMapping(value="/{id}",method=RequestMethod.GET)

@ResponseBody

public ResourceResponseEntity createResource(@ModelAttribute("tokenIdValidateResult")TokenValidateResult tokenIdValidateResult,

@PathVariable Integer id,

@RequestHeader HttpHeaders headers) {

if(tokenIdValidateResult == TokenValidateResult.SUCCESS){

try {

String tokenId=headers.getFirst("X-Auth-Token");

Token searchToken = new Token();

searchToken.setTokenId(tokenId);

//TODO:获取单个资源信息

return resourceResposeEntity;

} catch (Exception e) {

throw new CutomizedException(e);

}

}else{

//异常处理交给异常处理框架

throw new CutomizedException(HttpStatus.UNAUTHORIZED,"Token validte failed,ErrorCode:"+tokenIdValidateResult);

}

}

}

　　8. 异常处理

　　API在调用过程中总会出现各种各样的异常情况，Spring MVC提供了@ControllerAdvice以及ResponseEntityExceptionHandler类，专门用来自定义输出错误格式。只要在发生异常的地方将异常消息直接抛出，这样所有的异常都统一由自定义的异常处理类来处理，具体如下:

@ControllerAdvice

public class RestExceptionHandler extends ResponseEntityExceptionHandler {

@ExceptionHandler(value = { VMWareException.class })

public final ResponseEntity<?> handleVMWareException(VMWareException ex, WebRequest request) {

HttpHeaders headers = new HttpHeaders();

headers.setContentType(MediaType.parseMediaType(MediaTypes.TEXT_PLAIN_UTF_8));

return handleExceptionInternal(ex, ex.getMessage(), headers, ex.status, request);

}

@ExceptionHandler(value = { PowerException.class })

public final ResponseEntity<?> handlePowerException(PowerException ex, WebRequest request) {

HttpHeaders headers = new HttpHeaders();

headers.setContentType(MediaType.parseMediaType(MediaTypes.TEXT_PLAIN_UTF_8));

return handleExceptionInternal(ex, ex.getMessage(), headers, ex.status, request);

}

@ExceptionHandler(value = { UspException.class })

public final ResponseEntity<?> handleUspException(UspException ex, WebRequest request) {

HttpHeaders headers = new HttpHeaders();

headers.setContentType(MediaType.parseMediaType(MediaTypes.TEXT_PLAIN_UTF_8));

return handleExceptionInternal(ex, ex.getMessage(), headers, ex.status, request);

}

@ExceptionHandler(value = { KVMException.class })

public final ResponseEntity<?> handleKVMException(KVMException ex, WebRequest request) {

HttpHeaders headers = new HttpHeaders();

headers.setContentType(MediaType.parseMediaType(MediaTypes.TEXT_PLAIN_UTF_8));

return handleExceptionInternal(ex, ex.getMessage(), headers, ex.status, request);

}

}

　　这里的异常都封装了具体的HTTPStatus代码，这样第三方就能够清楚地知道调用时的出错类型，常见的HTTP错误代码有





　　9. 总结

　　本文主要讲解了如何通过Spring MVC封装RESTful API，包括Token的认证机制，封装资源的CRUD操作，异常处理等，对开发人员快速开发企业级项目集成有所帮助。

参考资料

1. http://www.ruanyifeng.com/blog/2011/09/restful.html
2. http://www.ruanyifeng.com/blog/2011/09/restful.html
3. http://jinnianshilongnian.iteye.com/blog/1866350