Spring Boot接口通用返回值设计与实现最佳实践

一、核心返回值模型设计（增强版）

package com.chat.common;


import com.chat.util.I18nUtil;
import com.chat.util.TraceUtil;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.Getter;

import java.io.Serializable;

/**
 * 功能: 通用响应实体（支持泛型、链路追踪、国际化）
 * 作者: 沙琪马
 * 日期: 2025/5/21 20:08
 */

@Data
@AllArgsConstructor
public class Result<T> implements Serializable {

    private static final long serialVersionUID = 1L;

    private int code;               // 业务状态码
    private String message;         // 国际化消息
    private T data;                 // 数据内容
    private String traceId;         // 链路追踪ID
    private long timestamp;         // 响应时间戳

    // ========== 构造器 ==========

    public Result() {
        this.timestamp = System.currentTimeMillis();
    }


    // ========== 静态构造器 ==========

    public static <T> Result<T> success(T data) {
        return new Result<T>()
                .code(ResultCode.SUCCESS.getCode())
                .message(I18nUtil.getMessage("success", "操作成功"))
                .data(data)
                .traceId(TraceUtil.getTraceId());
    }

    public static <T> Result<T> failure(ResultCode resultCode) {
        return new Result<T>()
                .code(resultCode.getCode())
                .message(I18nUtil.getMessage(resultCode.getMessageKey(), resultCode.getDefaultMessage()))
                .traceId(TraceUtil.getTraceId());
    }

    public static <T> Result<T> failure(int code, String message) {
        return new Result<T>()
                .code(code)
                .message(message)
                .traceId(TraceUtil.getTraceId());
    }

    // ========== Fluent API ==========

    public Result<T> code(int code) {
        this.code = code;
        return this;
    }

    public Result<T> message(String message) {
        this.message = message;
        return this;
    }

    public Result<T> data(T data) {
        this.data = data;
        return this;
    }

    public Result<T> traceId(String traceId) {
        this.traceId = traceId;
        return this;
    }

}

设计亮点：

内置时间戳字段用于客户端调试
支持国际化消息模板
使用Builder模式提升可读性
实现Serializable接口支持序列化

配套：`ResultCode` 枚举（推荐）

package com.chat.common;

import lombok.AllArgsConstructor;
import lombok.Getter;

/**
 * 功能:
 * 作者: 沙琪马
 * 日期: 2025/5/21 20:09
 */
@Getter
@AllArgsConstructor
public enum ResultCode {
    SUCCESS(200, "success", "操作成功"),
    FAIL(500, "error", "服务异常"),
    UNAUTHORIZED(401, "unauthorized", "未授权"),
    FORBIDDEN(403, "forbidden", "无权限访问"),
    NOT_FOUND(404, "not_found", "资源不存在");

    private final int code;
    private final String messageKey;
    private final String defaultMessage;

}

✅ 工具类建议（可选）：

国际化工具类 `I18nUtil`

package com.chat.util;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.MessageSource;
import org.springframework.context.i18n.LocaleContextHolder;
import org.springframework.stereotype.Component;

/**
 * 功能: 国际化工具类
 * 作者: 沙琪马
 * 日期: 2025/5/21 20:19
 */
@Component
public class I18nUtil {

    private static MessageSource messageSource;

    @Autowired
    public I18nUtil(MessageSource source) {
        I18nUtil.messageSource = source;
    }

    public static String getMessage(String key, String defaultMsg) {
        return messageSource.getMessage(key, null, defaultMsg, LocaleContextHolder.getLocale());
    }
}

链路追踪工具类 `TraceUtil`

package com.chat.util;

import java.util.UUID;

/**
 * 功能: 链路追踪工具类
 * 作者: 沙琪马
 * 日期: 2025/5/21 20:19
 */
public class TraceUtil {


    private static final ThreadLocal<String> traceIdHolder = new ThreadLocal<>();

    public static String getTraceId() {
        String traceId = traceIdHolder.get();
        if (traceId == null) {
            traceId = UUID.randomUUID().toString();
            traceIdHolder.set(traceId);
        }
        return traceId;
    }

    public void setTraceId(String traceId) {
        traceIdHolder.set(traceId);
    }

    public void clear() {
        traceIdHolder.remove();
    }
}

二、分页查询标准化响应（增强版）

public class PageResult<T> {
    private int pageNum;         // 当前页码
    private int pageSize;        // 每页数量
    private long total;          // 总记录数
    private int pages;           // 总页数
    private List<T> records;     // 当前页数据
    private boolean hasNext;     // 是否有下一页
    private boolean hasPrevious; // 是否有上一页
    
    // 根据MyBatis PageHelper自动转换
    public static <T> PageResult<T> fromPage(Page<T> page) {
        return new PageResult<T>()
            .pageNum(page.getPageNum())
            .pageSize(page.getPageSize())
            .total(page.getTotal())
            .pages(page.getPages())
            .records(page.getResult())
            .hasNext(page.getPageNum() < page.getPages())
            .hasPrevious(page.getPageNum() > 1);
    }
}

三、全局响应处理（增强版）

@RestControllerAdvice
public class GlobalResponseHandler implements ResponseBodyAdvice<Object> {

    @Autowired
    private Tracer tracer; // Sleuth全链路追踪
    
    @Override
    public boolean supports(MethodParameter returnType, 
                           Class<? extends HttpMessageConverter<?>> converterType) {
        return !returnType.getParameterType().equals(Result.class) 
            && !returnType.hasMethodAnnotation(IgnoreWrap.class);
    }

    @Override
    public Object beforeBodyWrite(Object body, MethodParameter returnType,
                                 MediaType selectedContentType,
                                 Class<? extends HttpMessageConverter<?>> selectedConverterType,
                                 ServerHttpRequest request, 
                                 ServerHttpResponse response) {
        
        // 处理特殊类型
        if (body instanceof String) {
            return JsonUtil.toJson(Result.success(body));
        }
        
        // 自动注入Trace ID
        String traceId = tracer.currentSpan().context().traceId();
        
        return Result.success(body)
            .traceId(traceId);
    }
}

关键功能：

支持@IgnoreWrap注解跳过自动包装
集成Sleuth实现全链路追踪
自动处理文件下载等特殊场景

四、全局异常处理（增强版）

@RestControllerAdvice
public class GlobalExceptionHandler {
    
    private static final Map<Class<? extends Exception>, ResultCode> EXCEPTION_MAPPING = 
        ImmutableMap.<Class<? extends Exception>, ResultCode>builder()
            .put(BusinessException.class, ResultCode.BUSINESS_ERROR)
            .put(UnauthorizedException.class, ResultCode.UNAUTHORIZED)
            .put(MethodArgumentNotValidException.class, ResultCode.PARAM_ERROR)
            .build();

    @ExceptionHandler(Exception.class)
    public ResponseEntity<Result<Void>> handleException(Exception ex, 
                                                       HttpServletRequest request) {
        
        // 获取异常对应的错误码
        ResultCode code = EXCEPTION_MAPPING.getOrDefault(ex.getClass(), 
                                                       ResultCode.SYSTEM_ERROR);
        
        // 构建错误响应
        Result<Void> result = Result.failure(code.getCode(), ex.getMessage())
            .traceId((String) request.getAttribute("traceId"));
        
        // 设置HTTP状态码
        return ResponseEntity
            .status(code.getHttpStatus())
            .body(result);
    }
    
    // 处理参数校验异常
    @ExceptionHandler(MethodArgumentNotValidException.class)
    public Result<Void> handleValidationException(MethodArgumentNotValidException ex) {
        String message = ex.getBindingResult().getAllErrors().stream()
            .map(DefaultMessageSourceResolvable::getDefaultMessage)
            .collect(Collectors.joining("; "));
        return Result.failure(ResultCode.PARAM_ERROR.getCode(), message);
    }
}

状态码枚举示例：

public enum ResultCode {
    SUCCESS(200, 200, "操作成功"),
    PARAM_ERROR(400, 400, "参数校验失败"),
    UNAUTHORIZED(401, 401, "未授权"),
    BUSINESS_ERROR(500, 200, "业务异常");

    private final int code;      // 业务状态码
    private final int httpStatus;// HTTP状态码
    private final String desc;   // 描述

    // 构造方法...
}

五、Swagger集成（增强版）

@Configuration
@EnableOpenApi
public class SwaggerConfig {

    @Bean
    public OpenAPI springShopOpenAPI() {
        return new OpenAPI()
            .components(new Components()
                .addSchemas("Result", new ObjectSchema()
                    .addProperty("code", new IntegerSchema())
                    .addProperty("message", new StringSchema())
                    .addProperty("data", new ObjectSchema().nullable(true))
                )
            .info(new Info()
                .title("API文档")
                .version("v1.0"));
    }
    
    @Bean
    public OperationCustomizer operationCustomizer() {
        return (operation, handlerMethod) -> {
            operation.getResponses().addApiResponse("200", 
                new ApiResponse().description("OK")
                    .content(new Content().addMediaType(
                        MediaType.APPLICATION_JSON_VALUE,
                        new MediaType().schema(new Schema().$ref("#/components/schemas/Result")))));
            return operation;
        };
    }
}

六、高级功能扩展

6.1 国际化支持

# messages.properties
success=Success
error.param=Parameter error: {0}

public class I18nUtil {
    private static final MessageSource messageSource;
    
    public static String getMessage(String code, Object... args) {
        return messageSource.getMessage(code, args, LocaleContextHolder.getLocale());
    }
}

6.2 监控指标埋点

@Aspect
@Component
public class ResponseMetricsAspect {
    
    @Autowired
    private MeterRegistry registry;
    
    @AfterReturning(pointcut = "@within(org.springframework.web.bind.annotation.RestController)", 
                   returning = "result")
    public void recordSuccess(Result<?> result) {
        registry.counter("api.response", "code", String.valueOf(result.getCode())).increment();
    }
    
    @AfterThrowing(pointcut = "@within(org.springframework.web.bind.annotation.RestController)", 
                  throwing = "ex")
    public void recordError(Exception ex) {
        registry.counter("api.error", "type", ex.getClass().getSimpleName()).increment();
    }
}

七、最佳实践总结

特性	实现方案	优势
统一响应格式	`ResponseBodyAdvice`全局处理	减少重复代码，强制规范
异常标准化	`@ExceptionHandler`统一捕获	快速定位问题，提升接口健壮性
全链路追踪	Sleuth集成	日志聚合分析，快速排查问题
接口文档集成	OpenAPI自定义Schema	提升文档可读性，降低沟通成本
国际化支持	MessageSource动态解析	支持多语言环境
监控指标	Micrometer埋点	实时掌握接口健康状态