RESTful API

SpringBoot实现restful API

• Controller的请求和URL的重构
• Controller的响应重构
• 前后端分离后的用户认证和鉴权

Restful API请求设计规范（最佳实践）

• URI使用名词，尽量使用复数，如/order
• URI使用嵌套表示关联关系，如/users/1/orders/3
• 使用正确的HTTP方法，如GET、POST、PUT、PATCH、DELETE等
• 不符合CRUD的方法，使用POST+动词、查询字符串中带action字段或设计子资源三种方式中某种形式

Controller的请求和URL重构

Controller的请求和URL重构

• 使用@RequestParam注解获取URL中的查询参数值；

• 使用@RequestBody注解获取POST或PUT中的对象值；

• 使用@PathVariable注解获取URL中的参数值。
  参数校验
  @Validation和@Vaild注解

• @Validation注解是Spring Framework中提供的验证机制，是JSR-303规范的一个变种，可以使用在类型、方法和方法参数上，但不能使用在类的成员属性上。

• @valid注解是Hibernate框架提供的验证机制，复合JSR-303规范，比@Validation更强大，可以使用在类的成员属性上，所以也支持嵌套验证。

• Spring Framework中默认使用@Validation注解进行参数验证，SpringBoot集成了两种注解，可以选择使用。

参数校验

先要引入依赖jar包

 <dependency>
            <groupId>javax.validationgroupId>
            <artifactId>validation-apiartifactId>
            <version>1.1.0.Finalversion>
        dependency>

@Vaild注解常用验证

注解名	说明
@NotNull和@Null	不能为空和必须为空
@AssertTrue和@AssertFalse	必须为true或false
@Digits	必须为数字
@Max和@Min	指定整数的最大值和最小值
@Length	指定字符串的最小和最大长度
@NotEmpty	不能为空（包括null、字符串长度为0、集合大小为0）
@NotBlank	不能为空（包括null、字符串首位空格后为0）
@Email	必须为Email格式
@Pattern	符合正则表达式要求

Constraint 详细信息

注解名	说明
@Valid	被注释的元素是一个对象，需要检查此对象的所有字段值
@Null	被注释的元素必须为 null
@NotNull	被注释的元素必须不为 null
@AssertTrue	被注释的元素必须为 true
@AssertFalse	被注释的元素必须为 false
@Min(value)	被注释的元素必须是一个数字，其值必须大于等于指定的最小值
@Max(value)	被注释的元素必须是一个数字，其值必须小于等于指定的最大值
@DecimalMin(value)	被注释的元素必须是一个数字，其值必须大于等于指定的最小值
@DecimalMax(value)	被注释的元素必须是一个数字，其值必须小于等于指定的最大值
@Size(max, min)	被注释的元素的大小必须在指定的范围内
@Digits (integer, fraction)	被注释的元素必须是一个数字，其值必须在可接受的范围内
@Past	被注释的元素必须是一个过去的日期
@Future	被注释的元素必须是一个将来的日期
@Pattern(value)	被注释的元素必须符合指定的正则表达式
@Email	被注释的元素必须是电子邮箱地址
@Length	被注释的字符串的大小必须在指定的范围内
@NotEmpty	被注释的字符串的必须非空
@Range	被注释的元素必须在合适的范围内
@NotBlank	被注释的字符串的必须非空
@URL(protocol=,host=, port=,regexp=, flags=)	被注释的字符串必须是一个有效的url
@CreditCardNumber	被注释的字符串必须通过Luhn校验算法，银行卡，信用卡等号码一般都用Luhn计算合法性

@Valid
public class Admin {

    @NotNull(message = "id不能为空")
    private int id;

    @NotNull(message = "用户名不能为空")
    private String username;

    @NotNull(message = "密码必填")
    private String password;

    @Email(message = "Email格式不符合要求")
    private String email;
    
}

Controller的响应重构

请求数据的获取

• 使用@RequestParam注解获取URL中的查询参数值
• 使用@RequestBody注解获取POST或PUT中的对象值
• 使用@PathVariable注解获取URL中的参数值

响应的基本要求

• 状态码
• 错误码
• 数据封装

 {
	"status": 500,
	"code": 50010,
	"message": "当前登录用户和过多"
}

{
	“status”：200，
	"datas"：
		{
			"account": {
				"username": "admin",
				"email": "[email protected]",
				"age": 18
			}
		}
}

关于VO、DTO、DO、DAO、PO等对象

• VO：有两种解释，Value Object和View Object，一般指的是View Object，即用于返回给前端进行View显示的对象
• DTO：数据传输对象，Data Transfer Object，一般用于业务逻辑层和控制器层的数据传输，对后端数据进行一定程度的封装，主要目的是提高传输效率和隐藏实现
• DO：领域对象，Domain Object，一般指的是业务逻辑层使用的对象，符合业务需求，和数据库中的表基本对应，ORM中的O指的就是DO
• PO：持久化对象，Persistence Object，完全ORM中使用的对象，和数据库表完全对应

响应数据的JSON序列化

• RESTful API规范中要求API的响应均需序列化JSON。

• 目前常用的第三方JSON序列化组件有fastjson、jackson和Gson等

• Gson是Google推出的JSON序列化工作，jackson是Apache上的一个开源工具，fastjson是阿里巴巴推出的JSON工具

• SpringBoot中默认使用Gson和jackson作为JSON序列化工具

• fastjson具有性能较好的优势

• SpringBoot中在Controller类或方法上增加@ResponseBody注解，即自动完成响应数据的JSON序列化

响应的基本要求设计

@Controller
public class AdminAPIController{
	@Autowired
	private AdminService adminService；
	
	@GetMapping（"/admin/{id}"）
	@ResponseBody
	public Admin getAdminById（@PathVariable int id）{
		Admin admin = adminService.findAdmin(id);
		System.out.println(admin);
		return admin;
	}
}
//使用@ResponseBody会返回一个对象，该对象会响应给前端一个json数据

统一响应的设计

package com.example.DTO;

import java.io.Serializable;

public class ServerResponse<T> implements Serializable {
    private int status;
    private String msg;
    private T data;

    public ServerResponse() {
    }

    public ServerResponse(int status, String msg, T data) {
        this.status = status;
        this.msg = msg;
        this.data = data;
    }

    public int getStatus() {
        return status;
    }

    public void setStatus(int status) {
        this.status = status;
    }

    public String getMsg() {
        return msg;
    }

    public void setMsg(String msg) {
        this.msg = msg;
    }

    public T getData() {
        return data;
    }

    public void setData(T data) {
        this.data = data;
    }
}

全局异常处理
使用@ControllerAdvice和@ExceptionHandler注解
@ControllerAdvice注解会在controller执行的时候执行，切面的设计
@ExceptionHandler会在发生指定异常时捕获

import org.springframework.beans.factory.annotation.Value;

@ControllerAdvice
public class GlobalExceptionAdvice {
    @ExceptionHandler(Value=Exception.class)
    @ResponseBody
    public ServerResponse<ExceptionResponse> handleException(Exception e){
        //1.获取Exception e中捕获的异常
        ...
        //2.创建ServerResponse对象，里边保存异常对象泛型
        ServerResponse<ExceptionResponse> ServerResponse =  new ServerResponse<ExceptionResponse>();
        //3.将Exception e获取的异常信息添加到ServerResponse对象中存储，最终返回
        ...
        return ServerResponse;
    }
}