ContiNew

切换日光/暗黑模式

响应处理 ​

最后更新: 3 天前
实践版本: v4.0.0

cnadmin 对响应处理进行了统一封装，包括：统一响应数据结构、统一异常处理等，旨在简化开发流程并提升API的一致性和可维护性。

配置说明 ​

本项目依赖 ContiNew Starter continew-starter-web，其提供了 Spring Web 轻量扩展优化，详情请查阅 starter 对应文档。该模块主要提供以下功能：

  • 跨域支持：通过配置文件快速启用和定制跨域过滤器（CorsFilter）
  • 统一响应处理：基于 Graceful Response 实现响应数据封装、异常处理和错误码管理
  • Query 参数转换器：Date、LocalDate、LocalTime、LocalDateTime、BaseEnum 类型参数自动转换
  • 服务器优化：默认使用 Undertow 替代 Tomcat，提供更优性能；支持全局禁用不安全 HTTP 请求方法

统一响应数据结构 ​

我们采用 Graceful Response 进行统一的响应数据封装，接口只需直接返回数据即可被自动封装为标准响应结构。这有助于保持 API 响应格式的一致性，并简化前端数据处理逻辑。

使用示例 ​

以下是一个简单的控制器示例，展示了如何返回数据：

TestController.java
java
@GetMapping("/{id}")
public UserDetailResp get(@PathVariable Long id) {
    // 直接返回业务数据，框架会自动封装为统一响应结构
    return userService.get(id);
}

返回的 JSON 结构如下：

json
{
    "code": "0",      // 响应码：0表示成功
    "msg": "ok",      // 响应消息
    "success": true,  // 是否成功
    "timestamp": 1755240981618,  // 时间戳
    "data": {         // 业务数据
        ...
    }
}

排除响应封装 ​

如果你不需要封装响应结构（例如：下载数据接口），可以添加 @ExcludeFromGracefulResponse 注解来排除：

DownloadController.java
java
@ExcludeFromGracefulResponse
@GetMapping("/download")
public ResponseEntity<Resource> downloadFile() {
    // 直接返回文件资源，不进行响应封装
    Resource resource = new ClassPathResource("example.pdf");
    return ResponseEntity.ok()
            .header(HttpHeaders.CONTENT_DISPOSITION, "attachment; filename=example.pdf")
            .body(resource);
}

自定义响应配置 ​

Graceful Response 提供了灵活的自定义响应配置。下方为 cnadmin 默认的全局响应配置，你可根据需要自行调整：

application.yml
yaml
--- ### 全局响应配置
continew-starter.web.response:
  # 自定义失败 HTTP 状态码（默认：200，建议业务和通信状态码区分）
  default-http-status-code-on-error: 200
  # 自定义成功响应码（默认：0）
  default-success-code: 0
  # 自定义成功提示（默认：ok）
  default-success-msg: ok
  # 自定义失败响应码（默认：1）
  default-error-code: 1
  # 自定义失败提示（默认：error）
  default-error-msg: error
  # 是否将原生异常错误信息填充到状态信息中
  origin-exception-using-detail-message: false
  # 响应类全名（配置后 response-style 将不再生效）
  response-class-full-name: top.continew.starter.web.model.R

提示：我们已在 continew-starter-web 中默认提供了 top.continew.starter.web.model.R 响应结构并封装部分常用方法。如果无法满足需求或需要自定义结构，请参考该类进行定制。

统一异常处理 ​

cnadmin 采用 Graceful Response 结合自定义异常处理器的方式进行统一异常拦截处理，确保 API 错误响应的一致性和友好性。异常处理代码位于 continew-common 模块的 config/exception 包下，你可以根据需要自行增加或删减异常处理。

全局异常处理器 ​

GlobalExceptionHandler（全局异常处理器） 处理以下异常类型：

异常类型描述
BaseException自定义异常
BusinessException业务异常
BadRequestException自定义验证异常-错误请求
MissingServletRequestParameterException方法参数缺失异常，例如：@RequestParam 参数缺失
BindException、MethodArgumentNotValidException参数校验不通过异常，例如：@NotBlank 等
MethodArgumentTypeMismatchException方法参数类型不匹配异常，例如：@RequestParam 参数类型不匹配
HttpMessageNotReadableExceptionHTTP 消息不可读异常
例如：
1.@RequestBody 缺失请求体
2.@RequestBody 实体内参数类型不匹配
3.请求体解析格式异常
MultipartException文件上传异常-超过上传大小限制
NoHandlerFoundException请求 URL 不存在异常
HttpRequestMethodNotSupportedException不支持的 HTTP 请求方法异常

SaToken 异常处理器 ​

GlobalSaTokenExceptionHandler（全局 SaToken 异常处理器） 处理以下认证和授权异常：

异常类型描述
NotLoginException未登录或登录过期异常
NotPermissionException权限不足异常
NotRoleException角色不匹配异常

参考资料 ​

  1. Graceful Response 项目主页：https://doc.feiniaojin.com/graceful-response/home.html
  2. ContiNew Starter Web 文档：https://continew.top/starter/module/web.html