Spring 4 建立REST API

什么是REST

• 全称：表述性状态转移 (Representational State Transfer), 将资源的状态以最适合客户端或服务端的形式从服务器端转移到客户端（或者反过来）。
• 面向资源，而不是面向行为
• 资源经过URL进行识别和定位，
• 通常URL中都使用名词，不使用动词
• 对资源采起的行为使用HTTP方法来定义，如GET, POST, DELETE, PUT

Spring MVC REST API示例

以用户增删改查为例，设计 REST API.

这里，咱们主要关注Spring Mvc中的Controller的设计：

UserController类：

@RestController
@RequestMapping(value = "/users")
public class UserController extends BaseController
{
    @Autowired
    private IUserService userService;
    ...
}

这里使用了@RestController注解，Spring将会为该Controller的全部处理方法应用消息转换功能，所以咱们能够没必要为每一个方法都添加@ResponseBody。

Spring支持多种资源表述形式(JSON/XML/HTML...)，不过通常使用JSON形式。

查询全部用户

对应请求的URL示例（无分页）:http://localhost:8080/webbf/users

对应的URL示例（有分页）:http://localhost:8080/webbf/users?offset=0&limit=10

使用的HTTP方法：GET

若是查询不到用户，返回状态码204，No Content

不然，返回状态码200, OK，返回的数据类型为 application/json;charset=utf-8

    @RequestMapping(method = RequestMethod.GET, produces = "application/json; charset=utf-8")
    public ResponseEntity<List<User>> getUserList(
        @RequestParam(value = "offset", defaultValue = "0") long offset,
        @RequestParam(value = "limit", defaultValue = MAX_LONG_AS_STRING) long limit)
    {
        Map<String, Object> param = new HashMap<String, Object>();
        param.put("offset", offset);
        param.put("limit", limit);
        List<User> userList = userService.query(param);
        if (userList.size() == 0)
        {
            return new ResponseEntity<List<User>>(HttpStatus.NO_CONTENT);
        }
        return new ResponseEntity<List<User>>(userList, HttpStatus.OK);
    }

查询单个用户

对应请求的URL示例:http://localhost:8080/webbf/users/1

使用的HTTP方法：GET

若是查询不到用户，返回状态码404，Not Found

不然，返回状态码200, OK，返回的数据类型为 application/json;charset=utf-8

    @RequestMapping(value = "/{id}", method = RequestMethod.GET, produces = "application/json; charset=utf-8")
    public ResponseEntity<User> getUserById(@PathVariable Long id)
    {

        User user = userService.findById(id);
        if (user == null)
        {
            return new ResponseEntity<User>(HttpStatus.NOT_FOUND);
        }
        return new ResponseEntity<User>(userService.findById(id), HttpStatus.OK);
    }

删除用户

对应请求的URL示例:http://localhost:8080/webbf/users/1

使用的HTTP方法：DELETE

若是查询不到被删除的用户，返回状态码404，Not Found

不然，删除成功，返回状态码204, No Content

    @RequestMapping(value = "/{id}", method = RequestMethod.DELETE, produces = "application/json; charset=utf-8")
    public ResponseEntity<User> deleteUser(@PathVariable Long id)
    {
        User user = userService.findById(id);
        if (user == null)
        {
            return new ResponseEntity<User>(HttpStatus.NOT_FOUND);
        }
        userService.deleteUser(id);
        return new ResponseEntity<User>(HttpStatus.NO_CONTENT);
    }

保存用户

对应请求的URL示例:http://localhost:8080/webbf/users

请求体：

{
    "name":"1",
    "address":"aa"
}

Content-Type: application/json

使用的HTTP方法：POST

响应的body为新建立的用户；

响应头的Location：http://localhost:8080/webbf/users/60

//若是用户已存在，返回状态码，409, Conflict

保存成功，返回状态码201, Created，返回的数据类型为 application/json;charset=utf-8

    @RequestMapping(method = RequestMethod.POST, consumes = "application/json; charset=utf-8")
    public ResponseEntity<User> saveUser(@RequestBody User user, UriComponentsBuilder ucb)
    {

        // if (userService.isUserExist(user)) {
        // System.out.println("A User with name " + user.getName() +
        // " already exist");
        // return new ResponseEntity<User>(user, HttpStatus.CONFLICT);
        // }
        User saved = userService.saveUser(user);

        HttpHeaders headers = new HttpHeaders();
        URI locationUri = ucb.path("/users/").path(String.valueOf(saved.getId())).build().toUri();
        headers.setLocation(locationUri);

        ResponseEntity<User> responseEntity = new ResponseEntity<User>(saved, headers,
            HttpStatus.CREATED);
        return responseEntity;
    }

修改用户

对应请求的URL示例:http://localhost:8080/webbf/users/1

请求体：

{
    "name":"1",
    "address":"aa"
}

Content-Type: application/json

使用的HTTP方法：PUT

响应的body为新建立的用户；

若是查询不到被修改的用户，返回状态码404，Not Found

保存成功，返回状态码201, Created，返回的数据类型为 application/json;charset=utf-8

    @RequestMapping(value = "/{id}", method = RequestMethod.PUT, consumes = "application/json; charset=utf-8")
    public ResponseEntity<User> updateUser(@PathVariable("id") long id, @RequestBody User user)
    {
        User currentUser = userService.findById(id);

        if (currentUser == null)
        {
            return new ResponseEntity<User>(HttpStatus.NOT_FOUND);
        }

        currentUser.setId(id);
        currentUser.setName(user.getName());
        currentUser.setAddress(user.getAddress());

        userService.updateUser(currentUser);
        return new ResponseEntity<User>(currentUser, HttpStatus.OK);
    }

 异常处理

请求中发生异常，返回500 Internal Server Error。

    @ExceptionHandler(Exception.class)
    @ResponseBody
    public ResponseEntity<Exception> handleException(HttpServletRequest request, Exception e)
    {
        logger.error("Request FAILD, URL = {} method = {}", request.getRequestURI(), request.getMethod());
        logger.error(e.toString(), e);
        return new ResponseEntity<Exception>(e, HttpStatus.INTERNAL_SERVER_ERROR);
    }

前端测试工具

由于我喜欢用fireFox, 因此我用restclient测试工具测试 REST API:

chrom的话，能够使用Postman。

修改用户测试

 

 新增用户测试

查询单个用户

前端AJAX调用 REST API 示例

查询用户

      $.ajax({
         async: false,
          type : "get",
          url : "/webbf/users",
          data: {},
          datatype : 'json',
          
          success : function(data,textStatus) {
            this.trigger({userList:data});
          }.bind(this),
          
          error: function(jqXHR, textStatus, errorThrown) {
            alert(jqXHR.status + ' ' + jqXHR.responseText);
          }

        });

删除用户

      $.ajax({
         async: false,
          type : "delete",
          url : "/webbf/users/" + userId,
          data: {},
          datatype : 'json',
          success : function(data) {

              alert("删除成功");
              this.getAllUser();
 
          }.bind(this),
          
          error: function(jqXHR, textStatus, errorThrown) {
            alert(jqXHR.status + ' ' + jqXHR.responseText);
          }
        });

新增用户

      $.ajax({
         async: false,
         contentType: "application/json; charset=utf-8",
          type : "post",
          url : "/webbf/users",
          data: JSON.stringify({name:userName,address:address}),
          datatype : 'json',
          success : function(data) {

              alert("操做成功");
              this.openAddModal(false);
              this.getAllUser();
  
          }.bind(this),
          
          error: function(jqXHR, textStatus, errorThrown) {
            alert(jqXHR.status + ' ' + jqXHR.responseText);
          }
        });

参考资料

Spring in action 4