Spring-Boot-开发REST接口最佳实践

HTTP动词与SQL命令对应

从服务器获取资源，可一个或者多个，对应SQL命令中的SELECT
GET /users
获取服务器上的所有的用户信息
GET /users/ID
获取指定ID的用户信息

POST

在服务器上创建一个新资源，对应SQL命令中的CREATE
POST /users
创建一个新的用户

在服务器上更新一个资源，客户端提供改变后的完整资源，对应SQL命令中的UPDATE
PUT /users/ID
更新指定ID的用户的全部信息

DELETE

从服务器上删除一个资源，对应SQL命令中的DELETE
DELETE /users/ID
删除指定ID的用户信息

PATCH

在服务器更新一个资源的部分属性，对应SQL命令中的UPDATE
PATCH /users/ID
更新指定ID的用户的某个属性

URL中的约定

URL中名词使用复数形式

URL中的名称是使用单数还是使用复数的问题，争议由来已久。URL中的名词一般对应数据库中的表，表中存储的是同类数据，在实践中我是强制使用复数形式，看上去更舒服些。

/users
/users/1
/roles
/roles/1

至于一些不规则的、不可数的名词就见仁见智吧。

/heroes
/heroes/1
/people
/people/1
/foots
/foots/1
/feet
/feet/1

版本

讲版本号加入到URL中以应对不兼容的和破坏性的更改。发布新API时，客户端可以自如的迁移到新API，不会因调用完全不同的新API而陷入窘境。使用直观的“V”前缀来表示后面的数字是版本号，不需要次级版本号，不应该频繁的发布API版本。

/edu/v1/users
/edu/v1/roles

对可选的、复杂的参数使用查询字符串

为了让URL更小、更简洁，为资源设置一个基本URL，讲可选的、复杂的参数用查询字符串表示。

/edu/v1/users?enabled=1&roleid=1

提供分页信息

一次性返回数据库中的所有的资源不是一个好主意，因此需要提供分页机制。通常使用数据库中众所周知的参数offset和limit

/edu/v1/users?enabled=1&offset=1&limit=15

如果客户端没有传递这些参数，则应使用默认值，通常offset=0，limit=10。

非资源请求使用动词

有时API调用并不涉及资源，在这种情况下，服务器执行一个操作病将结果返回给客户端。

/edu/v1/calc?p=100

考虑特定资源和跨资源搜索

提供对特定止缘的搜索很容易，只需要使用相应的资源集合，并将搜索字符串附加到查询参数中即可。

/edu/v1/users?username=李庆海

如果需要对所有资源提供全局搜索，则需要使用其他方法。

/edu/v1/search?key=李庆海

响应结果

使用小驼峰命名法作为属性标识符

通常，RESTful Web服务将被JavaScript编写的客户端使用。客户端会将JSON响应转换为JavaScript对象，然后调用其属性。因此，最好遵循JavaScript代码通用规范。

person.year_of_birth // 不推荐，违反JavaScript代码通用规范   
person.YearOfBirth // 不推荐，JavaScript构造方法命名   
person.yearOfBirth // 推荐

提供分页信息

返回结果比较多时，应提供分页信息。

{   
  "page": 0,   
  "size": 10,   
  "total": 3465,   
  "obj": [   
       
  ]   
}

Spring MVC开发REST接口

常用注解

@RestController

@RestController是@ResponseBody和@Controller的组合注解。

@RequestMapping

此注解即可以作用在控制器的某个方法上，也可以作用在此控制器类上。当控制器在类级别上添加@RequestMapping注解时，这个注解会应用到控制器的所有处理器方法上。处理器方法上的@RequestMapping注解会对类级别上的@RequestMapping的声明进行补充。

@PostMapping

组合注解，是@RequestMapping(method = RequestMethod.POST)的缩写。

@PutMapping

组合注解，是@RequestMapping(method = RequestMethod.PUT)的缩写。

@PatchMapping

组合注解，是@RequestMapping(method = RequestMethod.PATCH)的缩写。

@DeleteMapping

组合注解，是@RequestMapping(method = RequestMethod.DELETE)的缩写。

@GetMapping

组合注解，是@RequestMapping(method = RequestMethod.GET)的缩写。

@PathVariable

获取url中的数据。

@RequestParam

获取请求参数的值。

REST接口及Swagger 编写API文档示例

关于Swagger的使用可参考Spring Boot 项目中使用Swagger2。方法体中的代码不重要，重要的是方法的签名以及与HTTP动词的映射。

import java.util.Date;
import javax.persistence.EntityNotFoundException;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.data.domain.Page;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PatchMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
import cn.com.infcn.jianshu.Service.UserService;
import cn.com.infcn.jianshu.exception.BizException;
import cn.com.infcn.jianshu.exception.LoginNameOrPasswordErrorException;
import cn.com.infcn.jianshu.exception.ResourceExistsException;
import cn.com.infcn.jianshu.model.User;
import cn.com.infcn.jianshu.util.JsonResult;
import io.swagger.annotations.Api; 
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;

/**
 * 系统用户Controller
 * 
 * @author 李庆海
 *
 */
@Api(value = "系统用户接口", tags = "系统管理")
@RestController
@RequestMapping("/v3/edu/users")
public class UserController {

    @Autowired
    private UserService userService;

    /**
     * 添加用户，注册
     * 
     * @param loginName
     *            登录账号
     * @param userName
     *            用户名称
     * @param password
     *            登录密码
     * @param roleId
     *            用户角色
     * @return
     * @throws ResourceExistsException
     */
    @ApiOperation(value = "添加用户")
    @PostMapping("/")
    public JsonResult create(
            @ApiParam(name = "loginName", value = "登录账号", required = true) @RequestParam(required = true) @RequestBody String loginName,
            @ApiParam(name = "userName", value = "用户名称", required = true) @RequestParam(required = true) @RequestBody String userName,
            @ApiParam(name = "password", value = "登录密码", required = true) @RequestParam(required = true) @RequestBody String password,
            @ApiParam(name = "roleId", value = "用户角色编号", required = true) @RequestParam(required = true) @RequestBody String roleId)
            throws ResourceExistsException {
        boolean exists = this.userService.exists(loginName);
        if (exists) {
            throw new ResourceExistsException(loginName);
        }
        User user = userService.create(loginName, password, userName, roleId);
        return JsonResult.success(user);
    }

    /**
     * 用户凭借登录账号和登录密码进行登录
     * 
     * @param loginName
     *            登录账号
     * @param password
     *            登录密码
     * @throws EntityNotFoundException
     */
    @ApiOperation(value = "根据用户编号查询用户信息")
    @GetMapping("/login")
    public JsonResult login(
            @ApiParam(name = "loginName", value = "登录账号", required = true) @RequestParam(required = true) String loginName,
            @ApiParam(name = "password", value = "登录密码", required = true) @RequestParam(required = true) String password)
            throws LoginNameOrPasswordErrorException {
        User user = this.userService.login(loginName, password);
        if (null == user) {
            throw new LoginNameOrPasswordErrorException();
        }
        return JsonResult.success(user);
    }

    /**
     * 根据用户编号查询用户信息
     * 
     * @param id
     *            用户编号
     * @throws EntityNotFoundException
     */
    @ApiOperation(value = "根据用户编号查询用户信息")
    @GetMapping("/{id}")
    public JsonResult read(
            @ApiParam(name = "id", value = "用户编号，主键", required = true) @PathVariable(required = true) String id)
            throws EntityNotFoundException {
        User user = this.userService.getOne(id);
        return JsonResult.success(user);
    }

    /**
     * 账户注销，不删除用户的数据
     * 
     * @param userId
     *            用户编号
     * @return
     */
    @ApiOperation(value = "注销账户")
    @PatchMapping("/{id}")
    public JsonResult cancel(
            @ApiParam(name = "id", value = "用户编号，主键", required = true) @PathVariable(required = true) String id)
            throws EntityNotFoundException {
        this.userService.cancel(id);
        return JsonResult.success();
    }

    /**
     * 重置密码
     * 
     * @param id
     *            用户编号
     * @param password
     *            新登录密码
     * @return
     */
    @ApiOperation(value = "重置密码")
    @PatchMapping("/")
    public JsonResult updatePassword(
            @ApiParam(name = "id", value = "用户编号，主键", required = true) @RequestParam(required = true) String id,
            @ApiParam(name = "password", value = "新登录密码", required = true) @RequestParam(required = true) String password) {
        this.userService.updatePassword(id, password);
        return JsonResult.success();
    }

    /**
     * 多条件组合查询
     * 
     * @param userName
     *            用户名称
     * @param roleId
     *            用户角色
     * @param start
     *            开始日期
     * @param end
     *            结束日期
     * @param page
     *            分页，从0开始
     * @param size
     *            每页的行数，默认10
     * @return
     * @throws BizException
     */
    @ApiOperation(value = "用户信息查询")
    @GetMapping("/")
    public JsonResult query(
            @ApiParam(name = "userName", value = "用户名称，查询关键词", required = false) @RequestParam(required = false) String userName,
            @ApiParam(name = "roleId", value = "用户角色编号", required = false) @RequestParam(required = false) String roleId,
            @ApiParam(name = "start", value = "用户角色编号", required = false) @RequestParam(required = false) Date start,
            @ApiParam(name = "end", value = "用户角色编号", required = false) @RequestParam(required = false) Date end,
            @ApiParam(name = "page", value = "分页，第几页，从1开始", defaultValue = "1", required = true) @RequestParam(defaultValue = "1", required = true) int page,
            @ApiParam(name = "size", value = "每页的行数，正整数", defaultValue = "10", required = true) @RequestParam(defaultValue = "10", required = true) int size)
            throws BizException {
        Page<User> datas = this.userService.findDatas(userName, roleId, start, end, page, size);
        if (null == datas || null == datas.getContent() || datas.getContent().isEmpty()) {
            throw new BizException("用户不存在");
        }
        return JsonResult.success(datas);
    }

}

Swagger2接口文档效果图

Swagger2REST接口文档效果图.png

Spring-Boot-开发REST接口最佳实践

HTTP动词与SQL命令对应

URL中的约定

URL中名词使用复数形式

版本

对可选的、复杂的参数使用查询字符串

提供分页信息

非资源请求使用动词

考虑特定资源和跨资源搜索

响应结果

使用小驼峰命名法作为属性标识符

提供分页信息

Spring MVC开发REST接口

常用注解

@RestController

@RequestMapping

@PostMapping

@PutMapping

@PatchMapping

@DeleteMapping

@GetMapping

@PathVariable

@RequestParam

REST接口及Swagger 编写API文档示例

Swagger2接口文档效果图

推荐阅读更多精彩内容