【Myself-Security】SpringMVC 开发 RESTFul API

RestFul API

一般的API都是什么样子的呢？

查询 /user/query?name=tom              GET
详情 /user/getInfo?id=1                GET
创建 /user/create?name=tom            POST
修改 /user/update?id=1&name=jay       POST
删除 /user/delete?id=1                 GET

那么我们希望的RESTFul API 是什么样子的呢？

查询    /user?name=tom             GET
详情    /user/1                    GET
创建    /user                      POST
修改    /user/1                    PUT
删除    /user/1                    DELETE

简单的说，RESTFul就是：
1、用URL描述资源
2、使用HTTP方法描述行为，使用HTTP状态码来表示不同的结果
3、使用json交互数据
4、RESTFul只是一种风格，并不是强制的标准

RESTFul 成熟度模型

Level0：使用Http作为传输方式
Level1：引入资源概念，每个资源都有对应的URL
Level2：使用HTTP方法进行不同的操作，使用HTTP状态码来表示不同的结果
Level3：使用超媒体，在资源的表达中包含了链接信息

编写第一个RESTFul API

首先我们先了解一些常用的注解

1、@RestController 标明此Controller提供RestAPI
2、@RequestMapping及其变体。映射http请求URL到java方法
3、@RequestParam 映射请求参数到java方法的参数
4、@PageableDefault指定分页参数默认值

直接拿出代码模块来讲解吧！

package com.myself.web.controller;

import com.fasterxml.jackson.annotation.JsonView;
import com.myself.dto.User;
import com.myself.dto.UserQueryCondition;
import org.apache.commons.lang3.builder.ReflectionToStringBuilder;
import org.apache.commons.lang3.builder.ToStringStyle;
import org.springframework.data.domain.Pageable;
import org.springframework.data.web.PageableDefault;
import org.springframework.web.bind.annotation.*;

import java.util.ArrayList;
import java.util.List;

/**
 * @author  MySelf
 * @create  2018/9/15
 * @desc User Controller 层
 **/
@RestController
@RequestMapping("/user")
public class UserController {

    /**
     * 获取用户列表
     * @RequestMapping(value = "/user", method = RequestMethod.GET)
     * @RequestParam(name = "username",required = false,defaultValue = "tom") String nickname
     * @param condition {@link UserQueryCondition}
     * @return {@link List}
     */
    @GetMapping()
    @JsonView(User.UserSimpleView.class)
    public List<User> query(UserQueryCondition condition,@PageableDefault(page = 2,size = 17,sort = "username,asc") Pageable pageable){
        //反射工具
        System.out.println(ReflectionToStringBuilder.toString(condition, ToStringStyle.MULTI_LINE_STYLE));

        System.out.println(pageable.getPageSize());
        System.out.println(pageable.getPageNumber());
        System.out.println(pageable.getSort());

        List<User> users = new ArrayList<>();
        users.add(new User());
        users.add(new User());
        users.add(new User());
        return users;
    }

    /**
     * 获取用户信息 正则校验参数必须为数字
     * @RequestMapping(value = "/user/{id:\\d+}", method = RequestMethod.GET)
     * @param idxxx {@link String}
     * @return {@link User}
     */
    @GetMapping("/{id:\\d+}")
    @JsonView(User.UserDetailView.class)
    public User getInfo(@PathVariable(name = "id") String idxxx){
        User user = new User();
        user.setUsername("tom");
        return user;
    }

}

User Bean 对象

package com.myself.dto;


import com.fasterxml.jackson.annotation.JsonView;

/**
 * @author  MySelf
 * @create  2018/9/15
 * @desc User Bean
 **/
public class User {

    /** 用户简单视图 */
    public interface UserSimpleView {}

    /** 用户详情视图 */
    public interface UserDetailView extends UserSimpleView {}

    /** 用户名 */
    private String username;

    /** 用户密码 */
    private String password;

    @JsonView(UserSimpleView.class)
    public String getUsername() {
        return username;
    }

    public void setUsername(String username) {
        this.username = username;
    }

    @JsonView(UserDetailView.class)
    public String getPassword() {
        return password;
    }

    public void setPassword(String password) {
        this.password = password;
    }
}

接下来我们就来讲解一些注解的使用点，其实看着注解也能大致了解了。

首先我们在接受参数时，可以使用@PathVariable映射url片段到java方法的参数，同时也支持在url声明中使用正则表达式，使用@JsonView控制json输出内容。

我们需要在Bean中声明对应的接口，并在值对象的get方法上指定视图，最后在Controller方法上指定视图即可。

还有就是，当我们在处理创建请求时，还要注意可以使用@RequestBody映射请求体到java方法参数，且要注意对日期类型参数的处理，也可以使用@Valid注解和BindingResult验证请求参数的合法性并处理校验结果。

本文是针对UncleCatMySelf/myself-security（基于Spring Security + Spring Social + Spring Security OAuth + REST服务开发的案例教程，Maven多模块开发）的GitHub项目的基础演进。

---

如果本文对你有所帮助，欢迎关注本人技术公众号，谢谢。