登录 / 注册
IT168技术开发频道
IT168首页 > 技术开发 > 技术开发技术 > 正文

基于SpringMVC的RESTful API设计

2015-06-26 00:00    it168网站原创  作者: 俞超 编辑: 崔月

  【IT168 技术】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错误代码有

基于SpringMVC的RESTful API设计

  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
作者简介
俞超:
软件开发工程师
任职于某大型IT外资企业,主要从事J2EE开发、架构设计工作。

标签: Java , Spring , openAPI , 软件架构
  • IT168企业级IT168企业级
  • IT168文库IT168文库

扫码送文库金币

编辑推荐
系统架构师大会
系统架构师大会
点击或扫描关注
IT168企业级微信关注送礼
IT168企业级微信关注送礼
扫描关注
首页 评论 返回顶部