一、概述

在企业级微服务架构中,统一处理接口返回值和异常是保证系统稳定性和可维护性的关键。

本教程将详细介绍如何在知识库系统中实现网关层的统一封装。

1.1 统一封装的意义

优势说明应用场景
统一返回格式所有接口返回相同格式的JSON数据前端统一解析,减少适配成本
统一异常处理业务异常统一转换为标准格式避免异常信息泄露,提升用户体验
网关层处理在网关层统一处理响应格式业务服务专注业务逻辑,职责分离
完整日志记录记录请求响应完整日志问题排查、性能监控

1.2 技术架构

image - 2026-05-17T180558.989.png

技术栈:
├── 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/resources

2.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:run

6.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 完整调用链路

未命名绘图-第 5 页.drawio (1).png

8.2 核心设计要点

设计要点实现方式作用
分层异常处理业务抛异常→Common处理→Gateway封装职责分离,易于维护
内外部调用区分INNER-REQUEST头标识不同异常处理策略
流式响应处理flatMap+Mono.just包装确保数据正确传递
CORS统一管理网关配置+去重过滤器避免头重复问题
完整日志记录GlobalLogFilter便于问题排查

总结

本教程完整实现了网关层对接口返回值和异常的统一封装,主要特点包括:

✅ 统一返回格式 - 所有接口返回标准Result格式
✅ 统一异常处理 - 网关层统一处理业务异常
✅ 内外部调用区分 - 支持不同的异常处理策略
✅ CORS头去重 - 自动去除重复的CORS响应头
✅ 完整日志记录 - 记录请求响应的完整信息

适用场景:

  • 企业级微服务架构
  • Spring Cloud Gateway网关
  • 前后端分离项目
  • 需要统一API规范的系统

通过本教程的实现,可以大大提升系统的可维护性和用户体验,是生产环境推荐的最佳实践。

最后修改:2026 年 10 月 24 日
如果觉得我的文章对你有用,请随意赞赏