BeRest

基于spring和jakarta.servlet的快速实现restful化API扩展

---

实现效果

一个只返回String的GET方式Controller：

@GetMapping("/hello")
public String hello() {
    return "hello world";
}

BeRest Simple模式下的返回值：

//默认配置
{
  "message": "hello world", //默认会将字符串返回值放入message
  "data": null 
} 

//全显配置
{
  "ID": "1921682235-1666451353-504573122",
  "status": 200,
  "message": "hello world",
  "data": null
}

返回Map的GET：

@GetMapping("/map")
public Map<Object, Object> map() {
    return Map.of("username", "admin", "userId", "1");
}

BeRest Simple模式下的返回值：

//默认配置
{
  "message": "success",
  "data": {
    "username": "admin",
    "userId": "1"
  }
}

//全显配置
{
  "ID": "1921682235-1666496947-1140019921",
  "status": 200,
  "message": "success",
  "data": {
    "username": "admin",
    "userId": "1"
  }
}

可以看到，BeRest扩展是无侵入式的
在Controller方法的返回值上进行二次封装
将返回值结构统一标准化

---

快速开始

基于Spring开箱即用，引入依赖后自动装填缺省配置
内置Simple和Standard两种模式
默认使用Simple模式

<dependency>
    <groupId>io.github.iamuv</groupId>
    <artifactId>berest</artifactId>
    <version>0.5.0</version>
</dependency>

gradle

implementation group: 'io.github.iamuv', name: 'berest', version: '0.5.0'

---

HTTP协议中的Status Code

返回值中的status字段与HTTP协议中的Status Code保持一致

Request Method: GET
Status Code: 200 OK

其余请求方式的默认的Status Code

Request Method: POST
Status Code: 201 Created

Request Method: PUT
Status Code: 201 Created

Request Method: DELETE
Status Code: 201 Created

当Controller的方法返回值为void时默认的Status Code

Request Method: GET
Status Code: 200 OK

Request Method: POST
Status Code: 201 Created

Request Method: PUT
Status Code: 204 No Content

Request Method: DELETE
Status Code: 205 Reset Content

配置文件中可以修改这七种情况下返回的默认Status Code

---

关于异常的处理

当业务失败或者出现异常情况时，用throw exception的方式来代替return
BeRest会捕获异常并封装为失败的返回值并重新修改HTTP协议中的Status Code

@GetMapping("/error")
public void error() {
    throw new NullPointerException();
}

Simple模式下的返回值

//默认配置
{
  "message": "500 Internal Server Error.",
  "data": "NullPointerException"
}

Standard模式下的返回值

//默认配置
{
  "success": false,
  "error": {
    "message": "500 Internal Server Error.",
    "description": "The server has encountered a situation it does not know how to handle.",
    "exception": "NullPointerException"
  },
  "timer": {
    "request": "2024-02-01T16:10:32.3767488",
    "response": "2024-02-01T16:10:32.408749",
    "duration": 32
  },
  "code": null,
  "message": "failure",
  "data": null
}

HTTP信息

Request Method: GET
Status Code: 500 Internal Server Error

获取异常中的信息

@GetMapping("/error")
public void error() {
    throw new NullPointerException("This is a null");
}

{
  "success": false,
  "error": {
    "message": "This is a null",
    "description": "The server has encountered a situation it does not know how to handle.",
    "exception": "NullPointerException"
  },
  "timer": {
    "request": "2024-02-01T16:32:25.1874356",
    "response": "2024-02-01T16:32:25.220435",
    "duration": 33
  },
  "code": null,
  "message": "failure",
  "data": null
}

自定义异常

@GetMapping("/error") 
public void error() throws StandardException {
    throw new StandardException("test error", "500.1", "This is a test of error ");
}

Standard模式下的返回值

{
  "success": false,
  "error": {
    "message": "test error",
    "description": "This is a test of error ",
    "exception": "StandardException"
  },
  "timer": {
    "request": "2024-02-01T18:54:26.2391619",
    "response": "2024-02-01T18:54:26.2671618",
    "duration": 28
  },
  "code": "500.1",
  "message": "failure",
  "data": null
}

---

对Spring的支持

已支持的异常：
ErrorResponse
BeansException
NestedRuntimeException
BindException

---

对JSR-303的支持

支持@Valid和Spring变种JSR-303的@Validated

class Entity {

    @NotEmpty
    @Size(message = "姓名长度必须在{min}到{max}之间", min = 8, max = 30)
    private String name;

    @Min(message = "年龄必须大于{value}", value = 18)
    private int age;

    @NotEmpty
    @Email
    private String email;
}

Request Method: PUT
Body:
{
  "name": "test",
  "age": 1,
  "email": "myemail"
}

Simple模式下的返回值

{
  "message": "年龄必须大于18;姓名长度必须在8到30之间;不是一个合法的电子邮件地址;",
  "data": [
    {
      "codes": [
        "Min.entity.age",
        "Min.age",
        "Min.int",
        "Min"
      ],
      "arguments": [
        {
          "codes": [
            "entity.age",
            "age"
          ],
          "arguments": null,
          "defaultMessage": "age",
          "code": "age"
        },
        18
      ],
      "defaultMessage": "年龄必须大于18",
      "objectName": "entity",
      "field": "age",
      "rejectedValue": 1,
      "bindingFailure": false,
      "code": "Min"
    },
    {
      "codes": [
        "Size.entity.name",
        "Size.name",
        "Size.java.lang.String",
        "Size"
      ],
      "arguments": [
        {
          "codes": [
            "entity.name",
            "name"
          ],
          "arguments": null,
          "defaultMessage": "name",
          "code": "name"
        },
        30,
        8
      ],
      "defaultMessage": "姓名长度必须在8到30之间",
      "objectName": "entity",
      "field": "name",
      "rejectedValue": "test",
      "bindingFailure": false,
      "code": "Size"
    },
    {
      "codes": [
        "Email.entity.email",
        "Email.email",
        "Email.java.lang.String",
        "Email"
      ],
      "arguments": [
        {
          "codes": [
            "entity.email",
            "email"
          ],
          "arguments": null,
          "defaultMessage": "email",
          "code": "email"
        },
        [

        ],
        {
          "arguments": null,
          "codes": [
            ".*"
          ],
          "defaultMessage": ".*"
        }
      ],
      "defaultMessage": "不是一个合法的电子邮件地址",
      "objectName": "entity",
      "field": "email",
      "rejectedValue": "myemail",
      "bindingFailure": false,
      "code": "Email"
    }
  ]
}