作者：京东物流 覃玉杰

1. 简介

Graceful Response 是一个 Spring Boot 体系下的优雅响应处理器，提供一站式统一返回值封装、异常处理、异常错误码等功能。

使用 Graceful Response 进行 web 接口开发不仅可以节省大量的时间，还可以提高代码质量，使代码逻辑更清晰。

强烈推荐你花 3 分钟学会它！

Graceful Response 的 Github 地址： https://github.com/feiniaojin/graceful-response ，欢迎 star！

Graceful Response 的案例工程代码：https://github.com/feiniaojin/graceful-response-example.git

2. Spring Boot Web API 接口数据返回的现状

我们进行 Spring Boo Web API 接口开发时，通常大部分的 Controller 代码是这样的：

public class Controller {
    @GetMapping("/query")
    @ResponseBody
    public Response query(Parameter params) {

        Response res = new Response();
        try {
            //1.校验params参数，非空校验、长度校验
            if (illegal(params)) {
                res.setCode(1);
                res.setMsg("error");
                return res;
            }
            //2.调用Service的一系列操作
            Data data = service.query(params);
            //3.执行正确时，将操作结果设置到res对象中
            res.setData(data);
            res.setCode(0);
            res.setMsg("ok");
            return res;
        } catch (BizException1 e) {
            //4.异常处理：一堆丑陋的try...catch，如果有错误码的，还需要手工填充错误码
            res.setCode(1024);
            res.setMsg("error");
            return res;
        } catch (BizException2 e) {
            //4.异常处理：一堆丑陋的try...catch，如果有错误码的，还需要手工填充错误码
            res.setCode(2048);
            res.setMsg("error");
            return res;
        } catch (Exception e) {
            //4.异常处理：一堆丑陋的try...catch，如果有错误码的，还需要手工填充错误码
            res.setCode(1);
            res.setMsg("error");
            return res;
        }
    }
}

这段代码存在什么问题呢？真正的业务逻辑被冗余代码淹没，可读性太差。

真正执行业务的代码只有

Data data=service.query(params);

其他代码不管是正常执行还是异常处理，都是为了异常封装、把结果封装为特定的格式，例如以下格式：

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": 1,
    "name": "username"
  }
}

这样的逻辑每个接口都需要处理一遍，都是繁琐的重复劳动。

现在，只需要引入Graceful Response组件并通过@EnableGracefulResponse 启用，就可以直接返回业务结果并自动完成 response 的格式封装。

以下是使用 Graceful Response 之后的代码，实现同样的返回值封装、异常处理、异常错误码功能，但可以看到代码变得非常简洁，可读性非常强。

public class Controller {
    @GetMapping("/query")
    @ResponseBody
    public Data query(Parameter params) {
       return service.query(params);
    }
}

3. 快速入门

3.1 引入 maven 依赖

graceful-response已发布至 maven 中央仓库，可以直接引入到项目中，maven 依赖如下：

<dependency>
    <groupId>com.feiniaojin</groupId>
    <artifactId>graceful-response</artifactId>
    <version>2.0</version>
</dependency>

3.2 在启动类中引入@EnableGracefulResponse 注解

@EnableGracefulResponse
@SpringBootApplication
public class ExampleApplication {
    public static void main(String[] args) {
        SpringApplication.run(ExampleApplication.class, args);
    }
}

3.3 Controller 方法直接返回结果

• 普通的查询

@Controller
public class Controller {
    @RequestMapping("/get")
    @ResponseBody
    public UserInfoView get(Long id) {
        log.info("id={}", id);
        return UserInfoView.builder().id(id).name("name" + id).build();
    }
}

UserInfoView 的源码：

@Data
@Builder
public class UserInfoView {
    private Long id;
    private String name;
}

这个接口直接返回了 UserInfoView的实例对象，调用接口时，Graceful Response 将自动封装为以下格式：

{
  "status": {
    "code": "0",
    "msg": "ok"
  },
  "payload": {
    "id": 1,
    "name": "name1"
  }
}

可以看到UserInfoView被自动封装到 payload 字段中。

Graceful Response 提供了两种风格的 Response，可以通过在 application.properties 文件中配置 gr.responseStyle=1，将以以下的格式进行返回：

{
  "code": "0",
  "msg": "ok",
  "data": {
    "id": 1,
    "name": "name1"
  }
}

如果这两种风格也不能满足需要，我们还可以根据自己的需要进行自定义返回的 Response 格式。详细见本文 4.3 自定义 Respnse 格式。

• 异常处理的场景

通过 Graceful Response，我们不需要专门在 Controller 中处理异常，详细见 4.1 Graceful Response 异常错误码处理。

• 返回值为空的场景

某些 Command 类型的方法只执行修改操作，不返回数据，这个时候我们可以直接在 Controller 中返回 void，Graceful Response 会自动封装默认的操作成功 Response 报文。

@Controller
public class Controller {
    @RequestMapping("/void")
    @ResponseBody
    public void testVoidResponse() {
        //省略业务操作
    }
}

testVoidResponse方法的返回时 void，调用这个接口时，将返回：

{
  "status": {
    "code": "200",
    "msg": "success"
  },
  "payload": {}
}

3.4 Service 方法业务处理

在引入 Graceful Response 后，Service 层的方法的可读性可以得到极大的提升。

• 接口直接返回业务数据类型，而不是 Response，更具备可读性

public interface ExampleService {
    UserInfoView query1(Query query);
}

• Service 接口实现类中，直接抛自定义的业务异常，Graceful Response 将其转化为返回错误码和错误提示

public class ExampleServiceImpl implements ExampleService {
    @Resource
    private UserInfoMapper mapper;

    public UserInfoView query1(Query query) {
        UserInfo userInfo = mapper.findOne(query.getId());
        if (Objects.isNull(userInfo)) {
           //这里直接抛自定义异常，异常通过@ExceptionMapper修饰，提供异常码和异常提示
           throw new NotFoundException();
        }
        // 省略后续业务操作
    }
}

/**
 * NotFoundException的定义，使用@ExceptionMapper注解修饰
 * code:代表接口的异常码
 * msg:代表接口的异常提示
 */
@ExceptionMapper(code = "1404", msg = "找不到对象")
public class NotFoundException extends RuntimeException {

}

//Controller不再捕获处理异常
@RequestMapping("/get")
@ResponseBody
public UserInfoView get(Query query)) {
    return exampleService.query1(query);
}

当 Service 方法抛出 NotFoundException 异常时，接口将直接返回错误码，不需要手工 set，极大地简化了异常处理逻辑。

{
  "status": {
    "code": "1404",
    "msg": "找不到对象"
  },
  "payload": {}
}

验证：启动 example 工程后，请求http://localhost:9090/example/notfound

4. 进阶用法

4.1 Graceful Response 异常错误码处理

以下是使用 Graceful Response 进行异常、错误码处理的开发步骤。

• 创建自定义异常

通过继承 RuntimeException 类创建自定义的异常，采用 @ExceptionMapper注解修饰，注解的 code属性为返回码，msg属性为错误提示信息。

关于是继承 RuntimeException 还是继承 Exception，读者可以根据实际情况去选择，Graceful Response 对两者都支持。

@ExceptionMapper(code = "1007", msg = "有内鬼，终止交易")
public static final class RatException extends RuntimeException {

}

• Service 执行具体逻辑

Service 执行业务逻辑的过程中，需要抛异常的时候直接抛出去即可。由于已经通过@ExceptionMapper定义了该异常的错误码，我们不需要再单独的维护异常码枚举与异常类的关系。

//Service层伪代码
public class Service {
    public void illegalTransaction() {
        //需要抛异常的时候直接抛
        if (check()) {
            throw new RatException();
        }
        doIllegalTransaction();
    }
}

Controller 层调用 Service 层伪代码：

public class Controller {
    @RequestMapping("/test3")
    public void test3() {
        //Controller中不会进行异常处理，也不会手工set错误码，只关心核心操作，其他的统统交给Graceful Response
        exampleService.illegalTransaction();
    }
}

在浏览器中请求 controller 的/test3 方法，有异常时将会返回：

{
  "status": {
    "code": "1007",
    "msg": "有内鬼，终止交易"
  },
  "payload": {
  }
}

4.2 外部异常别名

案例工程 ( https://github.com/feiniaojin/graceful-response-example.git ) 启动后， 通过浏览器访问一个不存在的接口，例如 http://localhost:9090/example/get2?id=1

如果没开启 Graceful Response，将会跳转到 404 页面，主要原因是应用内部产生了 NoHandlerFoundException异常。如果开启了 Graceful Response，默认会返回 code=1 的错误码。

这类非自定义的异常，如果需要自定义一个错误码返回，将不得不对每个异常编写 Advice 逻辑，在 Advice 中设置错误码和提示信息，这样做也非常繁琐。

Graceful Response 可以非常轻松地解决给这类外部异常定义错误码和提示信息的问题。

以下为操作步骤：

• 创建异常别名，并用 @ExceptionAliasFor注解修饰

@ExceptionAliasFor(code = "1404", msg = "Not Found", aliasFor = NoHandlerFoundException.class)
public class NotFoundException extends RuntimeException {
}

code：捕获异常时返回的错误码

msg：异常提示信息

aliasFor：表示将成为哪个异常的别名，通过这个属性关联到对应异常。

• 注册异常别名

创建一个继承了 AbstractExceptionAliasRegisterConfig 的配置类，在实现的 registerAlias 方法中进行注册。

@Configuration
public class GracefulResponseConfig extends AbstractExceptionAliasRegisterConfig {

    @Override
    protected void registerAlias(ExceptionAliasRegister aliasRegister) {
        aliasRegister.doRegisterExceptionAlias(NotFoundException.class);
    }
}

• 浏览器访问不存在的 URL

再次访问 http://localhost:9090/example/get2?id=1 ,服务端将返回以下 json，正是在 ExceptionAliasFor 中定义的内容

{
  "code": "1404",
  "msg": "not found",
  "data": {
  }
}

4.3 自定义 Response 格式

Graceful Response 内置了两种风格的响应格式，可以在 application.properties 文件中通过gr.responseStyle进行配置

• gr.responseStyle=0，或者不配置（默认情况）

将以以下的格式进行返回：

{
  "status": {
    "code": "1007",
    "msg": "有内鬼，终止交易"
  },
  "payload": {
  }
}

• gr.responseStyle=1

将以以下的格式进行返回：

{
  "code": "1404",
  "msg": "not found",
  "data": {
  }
}

• 自定义响应格式

如果以上两种格式均不能满足业务需要，可以通过自定义去满足，Response

例如以下响应：

public class CustomResponseImpl implements Response {

    private String code;

    private Long timestamp = System.currentTimeMillis();

    private String msg;

    private Object data = Collections.EMPTY_MAP;

    @Override
    public void setStatus(ResponseStatus statusLine) {
        this.code = statusLine.getCode();
        this.msg = statusLine.getMsg();
    }

    @Override
    @JsonIgnore
    public ResponseStatus getStatus() {
        return null;
    }

    @Override
    public void setPayload(Object payload) {
        this.data = payload;
    }

    @Override
    @JsonIgnore
    public Object getPayload() {
        return null;
    }

    public String getCode() {
        return code;
    }

    public void setCode(String code) {
        this.code = code;
    }

    public String getMsg() {
        return msg;
    }

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

    public Object getData() {
        return data;
    }

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

    public Long getTimestamp() {
        return timestamp;
    }
}

注意，不需要返回的属性可以返回 null 或者加上@JsonIgnore注解

• 配置gr.responseClassFullName

将 CustomResponseImpl 的全限定名配置到 gr.responseClassFullName 属性。

gr.responseClassFullName=com.feiniaojin.gracefuresponse.example.config.CustomResponseImpl

注意，配置 gr.responseClassFullName 后，gr.responseStyle 将不再生效。

实际的响应报文如下：

{
    "code":"200",
    "timestamp":1682489591319,
    "msg":"success",
    "data":{

    }
}

如果还是不能满足需求，那么可以考虑同时自定义实现 Response 和 ResponseFactory 这两个接口。

5. 常用配置

Graceful Response 在版本迭代中，根据用户反馈提供了一些常用的配置项，列举如下：

• gr.printExceptionInGlobalAdvice 是否打印异常日志，默认为 false

• gr.responseClassFullName 自定义 Response 类的全限定名，默认为空。 配置 gr.responseClassFullName 后，gr.responseStyle 将不再生效

• gr.responseStyleResponse 风格，不配置默认为 0

• gr.defaultSuccessCode 自定义的成功响应码，不配置则为 0

• gr.defaultSuccessMsg 自定义的成功提示，默认为 ok

• gr.defaultFailCode 自定义的失败响应码，默认为 1

• gr.defaultFailMsg 自定义的失败提示，默认为 error