一、概述
在企业级微服务架构中,统一处理接口返回值和异常是保证系统稳定性和可维护性的关键。
本教程将详细介绍如何在知识库系统中实现网关层的统一封装。
1.1 统一封装的意义
| 优势 | 说明 | 应用场景 |
|---|---|---|
| 统一返回格式 | 所有接口返回相同格式的JSON数据 | 前端统一解析,减少适配成本 |
| 统一异常处理 | 业务异常统一转换为标准格式 | 避免异常信息泄露,提升用户体验 |
| 网关层处理 | 在网关层统一处理响应格式 | 业务服务专注业务逻辑,职责分离 |
| 完整日志记录 | 记录请求响应完整日志 | 问题排查、性能监控 |
1.2 技术架构

技术栈:
├── Spring Boot 3.2
├── Spring Cloud Gateway
├── Spring WebFlux (响应式编程)
├── FastJSON2 (JSON处理)
└── Lombok (简化代码)二、环境准备
2.1 创建公共模块目录结构
在项目根目录执行以下命令创建目录结构:
# 创建kb-common模块目录
mkdir -p kb-common/src/main/java/com/knowledge/base/common/result
mkdir -p kb-common/src/main/java/com/knowledge/base/common/exception
mkdir -p kb-common/src/main/java/com/knowledge/base/common/util
mkdir -p kb-common/src/main/java/com/knowledge/base/common/feign
mkdir -p kb-common/src/main/resources2.2 检查父POM配置
确保根项目的 pom.xml 中包含以下依赖管理:
<properties>
<java.version>21</java.version>
<spring-boot.version>3.2.0</spring-boot.version>
<spring-cloud.version>2023.0.0</spring-cloud.version>
<fastjson2.version>2.0.43</fastjson2.version>
<lombok.version>1.18.30</lombok.version>
</properties>
<dependencyManagement>
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-dependencies</artifactId>
<version>${spring-boot.version}</version>
<type>pom</type>
<scope>import</scope>
</dependency>
<dependency>
<groupId>org.springframework.cloud</groupId>
<artifactId>spring-cloud-dependencies</artifactId>
<version>${spring-cloud.version}</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>三、修改公共模块(kb-common)
3.1 配置kb-common的pom.xml
创建 kb-common/pom.xml:
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<parent>
<groupId>com.knowledge.base</groupId>
<artifactId>knowledge-base-backend</artifactId>
<version>1.0.0-SNAPSHOT</version>
</parent>
<artifactId>kb-common</artifactId>
<packaging>jar</packaging>
<name>Knowledge Base Common Module</name>
<description>公共基础模块(统一返回、异常处理、工具类)</description>
<dependencies>
<!-- Spring Boot Web -->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<!-- Spring Boot Validation -->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-validation</artifactId>
</dependency>
<!-- Spring Cloud OpenFeign -->
<dependency>
<groupId>org.springframework.cloud</groupId>
<artifactId>spring-cloud-starter-openfeign</artifactId>
</dependency>
<!-- Apache Commons -->
<dependency>
<groupId>org.apache.commons</groupId>
<artifactId>commons-lang3</artifactId>
</dependency>
<!-- FastJSON2 -->
<dependency>
<groupId>com.alibaba.fastjson2</groupId>
<artifactId>fastjson2</artifactId>
<version>${fastjson2.version}</version>
</dependency>
<!-- Lombok -->
<dependency>
<groupId>org.projectlombok</groupId>
<artifactId>lombok</artifactId>
<version>${lombok.version}</version>
<scope>provided</scope>
</dependency>
</dependencies>
</project>3.2 创建统一返回结果类
创建 kb-common/src/main/java/com/knowledge/base/common/result/Result.java:
package com.knowledge.base.common.result;
import com.fasterxml.jackson.annotation.JsonInclude;
import lombok.Data;
import java.io.Serializable;
/**
* 统一响应结果封装类
*
* <p>按照阿里巴巴Java开发规范设计,所有接口返回统一格式的响应结果</p>
*
* @param <T> 数据类型
* @author 苏三
* @since 1.0.0
*/
@Data
@JsonInclude(JsonInclude.Include.NON_NULL)
public class Result<T> implements Serializable {
private static final long serialVersionUID = 1L;
/**
* 响应码
*/
private Integer code;
/**
* 响应消息
*/
private String message;
/**
* 响应数据
*/
private T data;
/**
* 时间戳
*/
private Long timestamp;
/**
* 私有构造方法
*/
private Result() {
this.timestamp = System.currentTimeMillis();
}
/**
* 私有构造方法
*
* @param code 响应码
* @param message 响应消息
* @param data 响应数据
*/
private Result(Integer code, String message, T data) {
this.code = code;
this.message = message;
this.data = data;
this.timestamp = System.currentTimeMillis();
}
/**
* 成功返回(无数据)
*
* @param <T> 数据类型
* @return 统一响应结果
*/
public static <T> Result<T> success() {
return new Result<>(ResultCode.SUCCESS.getCode(), ResultCode.SUCCESS.getMessage(), null);
}
/**
* 成功返回(有数据)
*
* @param data 数据
* @param <T> 数据类型
* @return 统一响应结果
*/
public static <T> Result<T> success(T data) {
return new Result<>(ResultCode.SUCCESS.getCode(), ResultCode.SUCCESS.getMessage(), data);
}
/**
* 成功返回(自定义消息)
*
* @param message 消息
* @param <T> 数据类型
* @return 统一响应结果
*/
public static <T> Result<T> success(String message) {
return new Result<>(ResultCode.SUCCESS.getCode(), message, null);
}
/**
* 成功返回(自定义消息和数据)
*
* @param message 消息
* @param data 数据
* @param <T> 数据类型
* @return 统一响应结果
*/
public static <T> Result<T> success(String message, T data) {
return new Result<>(ResultCode.SUCCESS.getCode(), message, data);
}
/**
* 失败返回(默认错误)
*
* @param <T> 数据类型
* @return 统一响应结果
*/
public static <T> Result<T> error() {
return new Result<>(ResultCode.ERROR.getCode(), ResultCode.ERROR.getMessage(), null);
}
/**
* 失败返回(自定义消息)
*
* @param message 错误消息
* @param <T> 数据类型
* @return 统一响应结果
*/
public static <T> Result<T> error(String message) {
return new Result<>(ResultCode.ERROR.getCode(), message, null);
}
/**
* 失败返回(自定义错误码和消息)
*
* @param code 错误码
* @param message 错误消息
* @param <T> 数据类型
* @return 统一响应结果
*/
public static <T> Result<T> error(Integer code, String message) {
return new Result<>(code, message, null);
}
/**
* 失败返回(使用结果码枚举)
*
* @param resultCode 结果码枚举
* @param <T> 数据类型
* @return 统一响应结果
*/
public static <T> Result<T> error(ResultCode resultCode) {
return new Result<>(resultCode.getCode(), resultCode.getMessage(), null);
}
/**
* 根据条件返回成功或失败
*
* @param flag 条件标识
* @param <T> 数据类型
* @return 统一响应结果
*/
public static <T> Result<T> status(boolean flag) {
return flag ? success() : error();
}
}3.3 创建返回状态码枚举
创建 kb-common/src/main/java/com/knowledge/base/common/result/ResultCode.java:
package com.knowledge.base.common.result;
import lombok.AllArgsConstructor;
import lombok.Getter;
/**
* 返回状态码枚举
*
* @author 苏三
* @since 1.0.0
*/
@Getter
@AllArgsConstructor
public enum ResultCode {
/**
* 成功
*/
SUCCESS(200, "success"),
/**
* 系统错误
*/
ERROR(500, "系统异常,请联系管理员"),
/**
* 参数错误
*/
PARAM_ERROR(400, "参数错误"),
/**
* 未授权
*/
UNAUTHORIZED(401, "未授权,请先登录"),
/**
* 禁止访问
*/
FORBIDDEN(403, "禁止访问"),
/**
* 资源不存在
*/
NOT_FOUND(404, "资源不存在"),
/**
* 业务异常
*/
BUSINESS_ERROR(10000, "业务异常");
/**
* 状态码
*/
private final Integer code;
/**
* 消息
*/
private final String message;
}3.4 创建业务异常类
创建 kb-common/src/main/java/com/knowledge/base/common/exception/BusinessException.java:
package com.knowledge.base.common.exception;
import com.knowledge.base.common.result.ResultCode;
import lombok.Getter;
/**
* 业务异常类
*
* <p>用于处理业务逻辑中的异常情况,按照阿里巴巴Java开发规范设计</p>
*
* @author 苏三
* @since 1.0.0
*/
@Getter
public class BusinessException extends RuntimeException {
private static final long serialVersionUID = 1L;
/**
* 错误码
*/
private final Integer code;
/**
* 错误消息
*/
private final String message;
/**
* 构造方法
*
* @param message 错误消息
*/
public BusinessException(String message) {
super(message);
this.code = ResultCode.ERROR.getCode();
this.message = message;
}
/**
* 构造方法
*
* @param code 错误码
* @param message 错误消息
*/
public BusinessException(Integer code, String message) {
super(message);
this.code = code;
this.message = message;
}
/**
* 构造方法
*
* @param resultCode 结果码枚举
*/
public BusinessException(ResultCode resultCode) {
super(resultCode.getMessage());
this.code = resultCode.getCode();
this.message = resultCode.getMessage();
}
/**
* 构造方法
*
* @param message 错误消息
* @param cause 原因
*/
public BusinessException(String message, Throwable cause) {
super(message, cause);
this.code = ResultCode.ERROR.getCode();
this.message = message;
}
/**
* 构造方法
*
* @param resultCode 结果码枚举
* @param cause 原因
*/
public BusinessException(ResultCode resultCode, Throwable cause) {
super(resultCode.getMessage(), cause);
this.code = resultCode.getCode();
this.message = resultCode.getMessage();
}
}3.5 创建断言工具类
创建 kb-common/src/main/java/com/knowledge/base/common/util/AssertUtil.java:
package com.knowledge.base.common.util;
import com.knowledge.base.common.exception.BusinessException;
import com.knowledge.base.common.result.ResultCode;
import org.springframework.util.StringUtils;
import java.util.Collection;
import java.util.Map;
import java.util.Objects;
/**
* 断言工具类
*
* <p>参考susan-mall-cloud的AssertUtil实现</p>
* <p>提供业务参数校验,校验失败时抛出BusinessException</p>
*
* @author 苏三
* @since 1.0.0
*/
public class AssertUtil {
/**
* 断言表达式为true
*
* @param expression 表达式
* @param message 错误消息
*/
public static void isTrue(boolean expression, String message) {
if (!expression) {
throw new BusinessException(ResultCode.PARAM_ERROR.getCode(), message);
}
}
/**
* 断言表达式为false
*
* @param expression 表达式
* @param message 错误消息
*/
public static void isFalse(boolean expression, String message) {
if (expression) {
throw new BusinessException(ResultCode.PARAM_ERROR.getCode(), message);
}
}
/**
* 断言对象为null
*
* @param object 对象
* @param message 错误消息
*/
public static void isNull(Object object, String message) {
if (Objects.nonNull(object)) {
throw new BusinessException(ResultCode.PARAM_ERROR.getCode(), message);
}
}
/**
* 断言对象不为null
*
* @param object 对象
* @param message 错误消息
*/
public static void notNull(Object object, String message) {
if (Objects.isNull(object)) {
throw new BusinessException(ResultCode.PARAM_ERROR.getCode(), message);
}
}
/**
* 断言字符串有长度
*
* @param text 字符串
* @param message 错误消息
*/
public static void hasLength(String text, String message) {
if (StringUtils.isEmpty(text)) {
throw new BusinessException(ResultCode.PARAM_ERROR.getCode(), message);
}
}
/**
* 断言字符串有内容(非空字符串)
*
* @param text 字符串
* @param message 错误消息
*/
public static void hasText(String text, String message) {
if (!StringUtils.hasText(text)) {
throw new BusinessException(ResultCode.PARAM_ERROR.getCode(), message);
}
}
/**
* 断言集合不为空
*
* @param collection 集合
* @param message 错误消息
*/
public static void notEmpty(Collection<?> collection, String message) {
if (collection == null || collection.isEmpty()) {
throw new BusinessException(ResultCode.PARAM_ERROR.getCode(), message);
}
}
/**
* 断言Map不为空
*
* @param map Map
* @param message 错误消息
*/
public static void notEmpty(Map<?, ?> map, String message) {
if (map == null || map.isEmpty()) {
throw new BusinessException(ResultCode.PARAM_ERROR.getCode(), message);
}
}
/**
* 断言数组有内容
*
* @param array 数组
* @param message 错误消息
*/
public static void notEmpty(Object[] array, String message) {
if (array == null || array.length == 0) {
throw new BusinessException(ResultCode.PARAM_ERROR.getCode(), message);
}
}
/**
* 断言状态(通用断言)
*
* @param state 状态
* @param message 错误消息
*/
public static void state(boolean state, String message) {
if (!state) {
throw new BusinessException(message);
}
}
}3.6 创建全局异常处理器
创建 kb-common/src/main/java/com/knowledge/base/common/exception/GlobalExceptionHandler.java:
package com.knowledge.base.common.exception;
import com.knowledge.base.common.result.Result;
import com.knowledge.base.common.result.ResultCode;
import jakarta.servlet.http.HttpServletRequest;
import lombok.extern.slf4j.Slf4j;
import org.apache.commons.lang3.StringUtils;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.security.access.AccessDeniedException;
import org.springframework.validation.BindException;
import org.springframework.validation.FieldError;
import org.springframework.web.bind.MethodArgumentNotValidException;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestControllerAdvice;
import org.springframework.web.context.request.RequestAttributes;
import org.springframework.web.context.request.RequestContextHolder;
import org.springframework.web.context.request.ServletRequestAttributes;
import java.util.Objects;
import java.util.stream.Collectors;
/**
* 全局异常处理器
*
* <p>参考susan-mall-cloud的GlobalExceptionHandler实现</p>
* <p>主要功能:</p>
* <ul>
* <li>统一处理所有业务服务的异常</li>
* <li>区分内部服务调用和外部API调用</li>
* <li>内部调用返回ResponseEntity(保留HTTP状态码)</li>
* <li>外部调用返回统一的Result格式(HTTP 200 + 业务错误码)</li>
* </ul>
*
* @author 苏三
* @since 1.0.0
*/
@Slf4j
@RestControllerAdvice
public class GlobalExceptionHandler {
/**
* 统一异常处理入口
*/
@ExceptionHandler(Throwable.class)
public Object handleException(Throwable e) {
String requestInfo = getRequestInfo();
RequestAttributes requestAttributes = RequestContextHolder.getRequestAttributes();
// 检查是否为内部服务调用
if (Objects.nonNull(requestAttributes)) {
ServletRequestAttributes servletRequestAttributes = (ServletRequestAttributes) requestAttributes;
HttpServletRequest request = servletRequestAttributes.getRequest();
if (StringUtils.isNotEmpty(request.getHeader("INNER-REQUEST"))) {
return handleInternalException(e, requestInfo);
}
}
// 外部API调用
return handleExternalException(e, requestInfo);
}
/**
* 处理内部服务调用的异常
* <p>内部服务调用返回ResponseEntity,保留HTTP状态码</p>
*/
private Object handleInternalException(Throwable e, String requestInfo) {
if (e instanceof BusinessException) {
BusinessException businessException = (BusinessException) e;
log.error("内部调用业务异常:{} code={} msg={}", requestInfo, businessException.getCode(), businessException.getMessage(), e);
return ResponseEntity.status(businessException.getCode()).body(businessException.getMessage());
}
log.error("内部调用异常:{}", requestInfo, e);
return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).body(e.getMessage());
}
/**
* 处理外部API调用的异常
* <p>外部API调用返回统一的Result格式,HTTP状态码统一为200</p>
*/
private Object handleExternalException(Throwable e, String requestInfo) {
if (e instanceof BusinessException) {
BusinessException businessException = (BusinessException) e;
log.error("业务异常:{} code={} msg={}", requestInfo, businessException.getCode(), businessException.getMessage(), e);
return Result.error(businessException.getCode(), businessException.getMessage());
} else if (e instanceof AccessDeniedException) {
log.warn("权限异常:{} msg={}", requestInfo, e.getMessage(), e);
return Result.error(HttpStatus.FORBIDDEN.value(), "无权限访问,请联系系统管理员");
} else if (e instanceof MethodArgumentNotValidException) {
MethodArgumentNotValidException ex = (MethodArgumentNotValidException) e;
String errorMsg = ex.getBindingResult().getFieldErrors().stream()
.map(FieldError::getDefaultMessage)
.collect(Collectors.joining(", "));
log.error("参数校验异常:{} {}", requestInfo, errorMsg);
return Result.error(ResultCode.PARAM_ERROR.getCode(), errorMsg);
} else if (e instanceof BindException) {
BindException ex = (BindException) e;
String errorMsg = ex.getBindingResult().getFieldErrors().stream()
.map(FieldError::getDefaultMessage)
.collect(Collectors.joining(", "));
log.error("参数绑定异常:{} {}", requestInfo, errorMsg);
return Result.error(ResultCode.PARAM_ERROR.getCode(), errorMsg);
} else if (e instanceof IllegalArgumentException) {
log.error("非法参数异常:{} {}", requestInfo, e.getMessage(), e);
return Result.error(ResultCode.PARAM_ERROR.getCode(), e.getMessage());
}
log.error("系统异常:{} msg={}", requestInfo, e.getMessage(), e);
return Result.error(ResultCode.ERROR);
}
/**
* 获取请求信息
*/
private static String getRequestInfo() {
RequestAttributes attrs = RequestContextHolder.getRequestAttributes();
if (attrs instanceof ServletRequestAttributes) {
HttpServletRequest req = ((ServletRequestAttributes) attrs).getRequest();
String method = req.getMethod();
String uri = req.getRequestURI();
String query = req.getQueryString();
String ip = req.getRemoteAddr();
String fullUri = query == null ? uri : uri + "?" + query;
return "method=" + method + " uri=" + fullUri + " ip=" + ip;
}
return "";
}
}3.7 创建Feign拦截器配置
创建 kb-common/src/main/java/com/knowledge/base/common/feign/FeignInterceptorConfig.java:
package com.knowledge.base.common.feign;
import feign.RequestInterceptor;
import feign.RequestTemplate;
import org.springframework.boot.autoconfigure.condition.ConditionalOnClass;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
/**
* Feign请求拦截器配置
*
* <p>为服务间调用添加INNER-REQUEST头,标识为内部调用</p>
* <p>参考susan-mall-cloud的Feign配置,实现服务间调用的特殊处理</p>
*
* @author 苏三
* @since 1.0.0
*/
@Configuration
@ConditionalOnClass(RequestInterceptor.class)
public class FeignInterceptorConfig {
/**
* Feign请求拦截器Bean
*/
@Bean
public RequestInterceptor feignInterceptor() {
return new FeignInterceptor();
}
/**
* Feign请求拦截器实现类
*/
public static class FeignInterceptor implements RequestInterceptor {
private static final String INNER_REQUEST_HEADER = "INNER-REQUEST";
@Override
public void apply(RequestTemplate template) {
// 添加内部调用标识
template.header(INNER_REQUEST_HEADER, "true");
}
}
}四、配置网关服务(kb-gateway)
4.1 配置kb-gateway的pom.xml
确保 kb-gateway/pom.xml 包含以下依赖:
<dependencies>
<!-- 公共模块 -->
<dependency>
<groupId>com.knowledge.base</groupId>
<artifactId>kb-common</artifactId>
</dependency>
<!-- Spring Cloud Gateway -->
<dependency>
<groupId>org.springframework.cloud</groupId>
<artifactId>spring-cloud-starter-gateway</artifactId>
</dependency>
<!-- FastJSON2 -->
<dependency>
<groupId>com.alibaba.fastjson2</groupId>
<artifactId>fastjson2</artifactId>
<version>${fastjson2.version}</version>
</dependency>
<!-- Lombok -->
<dependency>
<groupId>org.projectlombok</groupId>
<artifactId>lombok</artifactId>
<version>${lombok.version}</version>
<scope>provided</scope>
</dependency>
</dependencies>4.2 创建全局日志过滤器
创建 kb-gateway/src/main/java/com/knowledge/base/gateway/filter/GlobalLogFilter.java:
package com.knowledge.base.gateway.filter;
import lombok.extern.slf4j.Slf4j;
import org.springframework.cloud.gateway.filter.GatewayFilterChain;
import org.springframework.cloud.gateway.filter.GlobalFilter;
import org.springframework.core.Ordered;
import org.springframework.http.server.reactive.ServerHttpRequest;
import org.springframework.http.server.reactive.ServerHttpResponse;
import org.springframework.stereotype.Component;
import org.springframework.web.server.ServerWebExchange;
import reactor.core.publisher.Mono;
/**
* 全局日志过滤器
*
* <p>记录所有请求和响应的完整日志信息</p>
* <p>包括请求方法、URI、远程地址、响应状态码、执行时间等</p>
*
* @author 苏三
* @since 1.0.0
*/
@Slf4j
@Component
public class GlobalLogFilter implements GlobalFilter, Ordered {
private static final String START_TIME_ATTR = "startTime";
@Override
public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {
ServerHttpRequest request = exchange.getRequest();
// 记录开始时间
exchange.getAttributes().put(START_TIME_ATTR, System.currentTimeMillis());
// 记录请求日志
String method = request.getMethod().name();
String uri = request.getURI().getPath();
String queryParams = request.getURI().getQuery();
String fullUri = queryParams == null ? uri : uri + "?" + queryParams;
String remoteAddr = request.getRemoteAddress() != null ?
request.getRemoteAddress().getAddress().toString() : "unknown";
log.info("请求 => Method: {}, URI: {}, RemoteAddress: {}",
method, fullUri, remoteAddr);
return chain.filter(exchange).then(Mono.fromRunnable(() -> {
Long startTime = exchange.getAttribute(START_TIME_ATTR);
if (startTime != null) {
long executeTime = System.currentTimeMillis() - startTime;
ServerHttpResponse response = exchange.getResponse();
log.info("响应 => StatusCode: {}, Time: {}ms",
response.getStatusCode(), executeTime);
}
}));
}
@Override
public int getOrder() {
return -100; // 高优先级,最先执行
}
}4.3 创建统一响应过滤器
创建 kb-gateway/src/main/java/com/knowledge/base/gateway/filter/UnifiedResponseFilter.java:
package com.knowledge.base.gateway.filter;
import com.alibaba.fastjson2.JSON;
import com.alibaba.fastjson2.JSONObject;
import lombok.extern.slf4j.Slf4j;
import org.reactivestreams.Publisher;
import org.springframework.cloud.gateway.filter.GatewayFilterChain;
import org.springframework.cloud.gateway.filter.GlobalFilter;
import org.springframework.core.Ordered;
import org.springframework.core.io.buffer.DataBuffer;
import org.springframework.core.io.buffer.DataBufferFactory;
import org.springframework.core.io.buffer.DataBufferUtils;
import org.springframework.http.HttpHeaders;
import org.springframework.http.MediaType;
import org.springframework.http.server.reactive.ServerHttpResponse;
import org.springframework.http.server.reactive.ServerHttpResponseDecorator;
import org.springframework.stereotype.Component;
import org.springframework.web.server.ServerWebExchange;
import reactor.core.publisher.Flux;
import reactor.core.publisher.Mono;
import java.nio.charset.StandardCharsets;
import java.util.ArrayList;
import java.util.List;
/**
* 统一响应过滤器
*
* <p>参考susan-mall-cloud的AuthFilter实现,统一处理响应体封装</p>
* <p>主要功能:</p>
* <ul>
* <li>拦截后端服务响应,确保响应格式统一</li>
* <li>处理分段传输的数据</li>
* <li>自动包装非标准格式的响应</li>
* <li>记录完整的响应日志</li>
* </ul>
*
* @author 苏三
* @since 1.0.0
*/
@Slf4j
@Component
public class UnifiedResponseFilter implements GlobalFilter, Ordered {
@Override
public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {
ServerHttpResponse originalResponse = exchange.getResponse();
DataBufferFactory bufferFactory = originalResponse.bufferFactory();
ServerHttpResponseDecorator decoratedResponse = new ServerHttpResponseDecorator(originalResponse) {
@Override
public Mono<Void> writeWith(Publisher<? extends DataBuffer> body) {
if (body instanceof Flux) {
String contentType = getDelegate().getHeaders().getFirst(HttpHeaders.CONTENT_TYPE);
// 只处理JSON格式的响应
if (contentType != null && contentType.contains(MediaType.APPLICATION_JSON_VALUE)) {
Flux<? extends DataBuffer> fluxBody = Flux.from(body);
// 处理分段传输的数据
return super.writeWith(fluxBody.buffer().flatMap(dataBuffers -> {
List<String> list = new ArrayList<>();
dataBuffers.forEach(dataBuffer -> {
try {
byte[] content = new byte[dataBuffer.readableByteCount()];
dataBuffer.read(content);
list.add(new String(content, StandardCharsets.UTF_8));
} catch (Exception e) {
log.error("读取响应字节流异常:{}", e.getMessage(), e);
}
});
// 释放原始数据缓冲区
DataBufferUtils.release(dataBuffers);
String responseData = String.join("", list);
log.info("网关转发响应: URI={}, Status={}, Response={}",
exchange.getRequest().getURI(),
getStatusCode(),
responseData);
// 包装响应数据
String wrappedResponse = wrapResponse(responseData);
byte[] uppedContent = wrappedResponse.getBytes(StandardCharsets.UTF_8);
// 更新Content-Length
getDelegate().getHeaders().setContentLength(uppedContent.length);
// 返回新的数据缓冲区
return Mono.just(bufferFactory.wrap(uppedContent));
}));
}
}
return super.writeWith(body);
}
@Override
public Mono<Void> writeAndFlushWith(Publisher<? extends Publisher<? extends DataBuffer>> body) {
return writeWith(Flux.from(body).flatMapSequential(p -> p));
}
};
return chain.filter(exchange.mutate().response(decoratedResponse).build());
}
/**
* 包装响应数据
* <p>如果响应数据已经是标准格式,则直接返回;否则包装为标准格式</p>
*
* @param responseData 原始响应数据
* @return 包装后的响应数据
*/
private String wrapResponse(String responseData) {
try {
// 尝试解析为JSON
Object json = JSON.parse(responseData);
if (json instanceof JSONObject) {
JSONObject obj = (JSONObject) json;
// 检查是否已经包含code和message字段(标准Result格式)
if (obj.containsKey("code") && obj.containsKey("message")) {
return responseData;
}
}
} catch (Exception ignored) {
// JSON解析失败,说明不是标准格式,需要包装
}
// 包装为标准Result格式
JSONObject result = new JSONObject();
result.put("code", 200);
result.put("message", "success");
result.put("data", JSON.parse(responseData));
result.put("timestamp", System.currentTimeMillis());
return result.toJSONString();
}
@Override
public int getOrder() {
return -2; // 较高优先级
}
}4.4 创建网关全局异常处理器
创建 kb-gateway/src/main/java/com/knowledge/base/gateway/handler/GatewayGlobalExceptionHandler.java:
package com.knowledge.base.gateway.handler;
import com.fasterxml.jackson.core.JsonProcessingException;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.knowledge.base.common.result.Result;
import io.netty.channel.ConnectTimeoutException;
import lombok.extern.slf4j.Slf4j;
import org.springframework.boot.web.reactive.error.ErrorWebExceptionHandler;
import org.springframework.core.annotation.Order;
import org.springframework.core.io.buffer.DataBuffer;
import org.springframework.http.HttpStatus;
import org.springframework.http.MediaType;
import org.springframework.http.server.reactive.ServerHttpResponse;
import org.springframework.stereotype.Component;
import org.springframework.web.server.ResponseStatusException;
import org.springframework.web.server.ServerWebExchange;
import reactor.core.publisher.Mono;
import java.nio.charset.StandardCharsets;
import java.util.concurrent.TimeoutException;
/**
* 网关全局异常处理器
*
* <p>统一处理网关层和后端服务的异常,返回统一格式的错误响应</p>
*
* @author 苏三
* @since 1.0.0
*/
@Slf4j
@Order(-1)
@Component("gatewayGlobalExceptionHandler")
public class GatewayGlobalExceptionHandler implements ErrorWebExceptionHandler {
private final ObjectMapper objectMapper = new ObjectMapper();
@Override
public Mono<Void> handle(ServerWebExchange exchange, Throwable ex) {
ServerHttpResponse response = exchange.getResponse();
if (response.isCommitted()) {
return Mono.error(ex);
}
// 设置响应头
response.getHeaders().setContentType(MediaType.APPLICATION_JSON);
// 根据异常类型生成错误响应
Result<?> result;
HttpStatus status;
if (ex instanceof ResponseStatusException rse) {
status = (HttpStatus) rse.getStatusCode();
result = Result.error(status.value(), rse.getReason());
} else if (ex instanceof ConnectTimeoutException || ex instanceof TimeoutException) {
status = HttpStatus.GATEWAY_TIMEOUT;
result = Result.error(status.value(), "后端服务响应超时,请稍后重试");
} else if (ex instanceof java.net.ConnectException) {
status = HttpStatus.BAD_GATEWAY;
result = Result.error(status.value(), "后端服务不可用,请检查服务状态");
} else {
log.error("网关异常: ", ex);
status = HttpStatus.INTERNAL_SERVER_ERROR;
result = Result.error(status.value(), "系统异常: " + ex.getMessage());
}
response.setStatusCode(status);
try {
String responseBody = objectMapper.writeValueAsString(result);
DataBuffer buffer = response.bufferFactory()
.wrap(responseBody.getBytes(StandardCharsets.UTF_8));
return response.writeWith(Mono.just(buffer));
} catch (JsonProcessingException e) {
log.error("JSON序列化失败", e);
return Mono.error(ex);
}
}
}4.5 创建网关配置类
创建 kb-gateway/src/main/java/com/knowledge/base/gateway/config/GatewayConfig.java:
package com.knowledge.base.gateway.config;
import org.springframework.cloud.gateway.filter.GlobalFilter;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.Ordered;
import org.springframework.web.cors.CorsConfiguration;
import org.springframework.web.cors.reactive.CorsWebFilter;
import org.springframework.web.cors.reactive.UrlBasedCorsConfigurationSource;
import reactor.core.publisher.Mono;
/**
* 网关配置类
*
* <p>配置网关全局过滤器,路由配置在 application.yml 中</p>
*
* @author 苏三
* @since 1.0.0
*/
@Configuration
public class GatewayConfig {
/**
* 配置CORS过滤器
*
* @return CorsWebFilter
*/
@Bean
public CorsWebFilter corsFilter() {
CorsConfiguration config = new CorsConfiguration();
// 允许的源(不能使用通配符*,因为allowCredentials=true)
// 开发环境:允许本地开发服务器
config.addAllowedOriginPattern("http://localhost:3000");
config.addAllowedOriginPattern("http://localhost:5173");
config.addAllowedOriginPattern("http://localhost:5174");
config.addAllowedOriginPattern("http://127.0.0.1:3000");
config.addAllowedOriginPattern("http://127.0.0.1:5173");
config.addAllowedOriginPattern("http://127.0.0.1:5174");
// 允许携带凭证(Cookie等)
config.setAllowCredentials(true);
// 允许的HTTP方法
config.addAllowedMethod("GET");
config.addAllowedMethod("POST");
config.addAllowedMethod("PUT");
config.addAllowedMethod("DELETE");
config.addAllowedMethod("OPTIONS");
config.addAllowedMethod("PATCH");
// 允许的请求头
config.addAllowedHeader("*");
// 暴露的响应头
config.addExposedHeader("Content-Disposition");
config.addExposedHeader("Authorization");
config.addExposedHeader("Set-Cookie");
// 预检请求缓存时间(秒)
config.setMaxAge(3600L);
UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource();
source.registerCorsConfiguration("/**", config);
return new CorsWebFilter(source);
}
/**
* 全局认证过滤器
*
* @return AuthFilter
*/
@Bean
public GlobalFilter authFilter() {
return new AuthFilter();
}
/**
* 认证过滤器
*/
public static class AuthFilter implements GlobalFilter, Ordered {
@Override
public Mono<Void> filter(
org.springframework.web.server.ServerWebExchange exchange,
org.springframework.cloud.gateway.filter.GatewayFilterChain chain) {
// 这里可以添加JWT验证逻辑
// 目前放行所有请求
return chain.filter(exchange);
}
@Override
public int getOrder() {
return -100; // 高优先级
}
}
}4.6 创建WebFlux配置类
创建 kb-gateway/src/main/java/com/knowledge/base/gateway/config/GatewayWebFluxConfig.java:
package com.knowledge.base.gateway.config;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.codec.ServerCodecConfigurer;
import org.springframework.web.reactive.config.WebFluxConfigurer;
/**
* 网关WebFlux配置
*
* <p>确保网关能够正确处理JSON响应体</p>
*
* @author 苏三
* @since 1.0.0
*/
@Configuration
public class GatewayWebFluxConfig implements WebFluxConfigurer {
@Override
public void configureHttpMessageCodecs(ServerCodecConfigurer configurer) {
// 配置消息编码器,确保响应体能够正确处理
configurer.defaultCodecs().maxInMemorySize(16 * 1024 * 1024); // 16MB
}
}4.7 创建CORS响应头去重过滤器
创建 kb-gateway/src/main/java/com/knowledge/base/gateway/config/CorsResponseHeaderFilter.java:
package com.knowledge.base.gateway.config;
import lombok.extern.slf4j.Slf4j;
import org.springframework.cloud.gateway.filter.GatewayFilterChain;
import org.springframework.cloud.gateway.filter.GlobalFilter;
import org.springframework.core.Ordered;
import org.springframework.http.HttpHeaders;
import org.springframework.stereotype.Component;
import org.springframework.web.server.ServerWebExchange;
import reactor.core.publisher.Mono;
import java.util.ArrayList;
import java.util.List;
import java.util.stream.Collectors;
/**
* CORS响应头去重过滤器
*
* <p>参考susan-mall-cloud项目的CORS解决方案</p>
* <p>去除后端服务设置的重复CORS头,确保只有网关层设置的CORS头返回给客户端</p>
*
* @author 苏三
* @since 1.0.0
*/
@Slf4j
@Component
public class CorsResponseHeaderFilter implements GlobalFilter, Ordered {
private static final String ANY = "*";
@Override
public int getOrder() {
// 在NettyWriteResponseFilter之后执行,确保在响应头处理完后执行去重
return org.springframework.cloud.gateway.filter.NettyWriteResponseFilter.WRITE_RESPONSE_FILTER_ORDER + 1;
}
@Override
public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {
return chain.filter(exchange).then(Mono.fromRunnable(() -> {
try {
if (exchange.getResponse().isCommitted()) {
return;
}
HttpHeaders headers = exchange.getResponse().getHeaders();
if (headers == null || headers.isEmpty()) {
return;
}
headers.entrySet().stream()
.filter(kv -> kv != null && kv.getKey() != null && kv.getValue() != null && kv.getValue().size() > 1)
.filter(kv -> (HttpHeaders.ACCESS_CONTROL_ALLOW_ORIGIN.equals(kv.getKey())
|| HttpHeaders.ACCESS_CONTROL_ALLOW_CREDENTIALS.equals(kv.getKey())
|| HttpHeaders.VARY.equals(kv.getKey())))
.forEach(kv -> {
try {
if (HttpHeaders.VARY.equals(kv.getKey())) {
List<String> varyValue = kv.getValue().stream().distinct().collect(Collectors.toList());
headers.put(kv.getKey(), varyValue);
log.debug("CORS头去重处理: {} -> {}", kv.getKey(), varyValue);
} else {
List<String> value = new ArrayList<>();
if (kv.getValue().contains(ANY)) {
value.add(ANY);
} else {
value.add(kv.getValue().get(0));
}
headers.put(kv.getKey(), value);
log.debug("CORS头去重处理: {} -> {}", kv.getKey(), value);
}
} catch (Exception e) {
log.error("处理CORS头时发生异常: key={}, value={}", kv.getKey(), kv.getValue(), e);
}
});
} catch (Exception e) {
log.error("CORS响应头去重处理发生异常", e);
}
}));
}
}4.8 配置网关CORS设置
CORS配置已经在 GatewayConfig.java 中通过 CorsWebFilter 完成,无需在 application.yml 中额外配置。
如果需要调整允许的访问源,请修改 GatewayConfig.java 中的 corsFilter() 方法。
五、配置用户权限服务
5.1 配置Spring Security(禁用CORS)
修改 kb-user-auth/src/main/java/com/knowledge/base/userauth/config/SecurityConfig.java:
package com.knowledge.base.userauth.config;
import lombok.extern.slf4j.Slf4j;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.HttpMethod;
import org.springframework.security.config.annotation.method.configuration.EnableMethodSecurity;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
import org.springframework.security.config.annotation.web.configurers.AbstractHttpConfigurer;
import org.springframework.security.config.http.SessionCreationPolicy;
import org.springframework.security.crypto.bcrypt.BCryptPasswordEncoder;
import org.springframework.security.crypto.password.PasswordEncoder;
import org.springframework.security.web.SecurityFilterChain;
/**
* Spring Security配置类
*
* <p>配置安全策略和认证规则</p>
* <p>注意:CORS由网关统一处理,业务服务不再配置CORS</p>
*
* @author 苏三
* @since 1.0.0
*/
@Slf4j
@Configuration
@EnableWebSecurity
@EnableMethodSecurity
public class SecurityConfig {
/**
* 配置安全过滤链
*
* @param http HttpSecurity
* @return SecurityFilterChain
* @throws Exception 异常
*/
@Bean
public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
http
// 禁用CSRF(使用JWT不需要CSRF保护)
.csrf(AbstractHttpConfigurer::disable)
// 配置会话管理(无状态)
.sessionManagement(session -> session
.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
// 禁用CORS(由网关统一处理)
.cors(org.springframework.security.config.Customizer.withDefaults())
// 配置授权规则
.authorizeHttpRequests(auth -> auth
// 登录和注册接口放行
.requestMatchers("/auth/login", "/auth/register", "/auth/auth/**").permitAll()
// 公开API放行
.requestMatchers("/public/**").permitAll()
// WebSocket放行
.requestMatchers("/ws/**").permitAll()
// 健康检查放行
.requestMatchers("/actuator/**").permitAll()
// Swagger文档放行
.requestMatchers("/doc.html", "/swagger-resources/**", "/v3/api-docs/**", "/webjars/**").permitAll()
// 测试端点放行
.requestMatchers("/auth/test", "/auth/test-error").permitAll()
// OPTIONS预检请求放行(CORS重要配置)
.requestMatchers(HttpMethod.OPTIONS, "/**").permitAll()
// 其他请求需要认证
.anyRequest().authenticated()
);
return http.build();
}
/**
* 配置密码编码器
*
* @return PasswordEncoder
*/
@Bean
public PasswordEncoder passwordEncoder() {
return new BCryptPasswordEncoder();
}
}六、测试验证
6.1 启动服务
按顺序启动以下服务:
# 1. 启动Nacos(如果使用)
cd nacos/bin
./startup.sh -m standalone
# 2. 编译所有模块
mvn clean install -DskipTests
# 3. 启动用户权限服务
cd kb-user-auth
mvn spring-boot:run
# 4. 启动网关服务
cd kb-gateway
mvn spring-boot:run6.2 测试正常响应
使用curl测试登录接口:
curl -X POST http://localhost:8080/api/auth/auth/login \
-H "Content-Type: application/json" \
-d '{
"username": "admin",
"password": "123456"
}'预期返回:
{
"code": 200,
"message": "success",
"data": {
"token": "mock-token-123456",
"username": "admin"
},
"timestamp": 1715905600000
}6.3 测试业务异常
curl -X POST http://localhost:8080/api/auth/auth/login \
-H "Content-Type: application/json" \
-d '{
"username": "test",
"password": "wrong"
}'预期返回:
{
"code": 10000,
"message": "用户名或密码错误",
"data": null,
"timestamp": 1715905600000
}6.4 查看网关日志
成功调用的日志示例:
2026-05-17 16:10:12.324 [parallel-1] INFO c.k.base.gateway.filter.GlobalLogFilter - 请求 => Method: POST, URI: /api/auth/auth/login, RemoteAddress: /127.0.0.1:50786
2026-05-17 16:10:12.852 [reactor-http-nio-2] INFO c.k.base.gateway.filter.UnifiedResponseFilter - 网关转发响应: URI=/api/auth/auth/login, Status=200 OK, Response={"code":200,"message":"success",...}
2026-05-17 16:10:13.116 [reactor-http-nio-2] INFO com.knowledge.base.gateway.filter.GlobalLogFilter - 响应 => StatusCode: 200 OK, Time: 791ms八、架构
8.1 完整调用链路

8.2 核心设计要点
| 设计要点 | 实现方式 | 作用 |
|---|---|---|
| 分层异常处理 | 业务抛异常→Common处理→Gateway封装 | 职责分离,易于维护 |
| 内外部调用区分 | INNER-REQUEST头标识 | 不同异常处理策略 |
| 流式响应处理 | flatMap+Mono.just包装 | 确保数据正确传递 |
| CORS统一管理 | 网关配置+去重过滤器 | 避免头重复问题 |
| 完整日志记录 | GlobalLogFilter | 便于问题排查 |
总结
本教程完整实现了网关层对接口返回值和异常的统一封装,主要特点包括:
✅ 统一返回格式 - 所有接口返回标准Result格式
✅ 统一异常处理 - 网关层统一处理业务异常
✅ 内外部调用区分 - 支持不同的异常处理策略
✅ CORS头去重 - 自动去除重复的CORS响应头
✅ 完整日志记录 - 记录请求响应的完整信息
适用场景:
- 企业级微服务架构
- Spring Cloud Gateway网关
- 前后端分离项目
- 需要统一API规范的系统
通过本教程的实现,可以大大提升系统的可维护性和用户体验,是生产环境推荐的最佳实践。