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