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;         // 链路追踪IDprivate 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;@Autowiredpublic 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> {@Autowiredprivate Tracer tracer; // Sleuth全链路追踪@Overridepublic boolean supports(MethodParameter returnType, Class<? extends HttpMessageConverter<?>> converterType) {return !returnType.getParameterType().equals(Result.class) && !returnType.hasMethodAnnotation(IgnoreWrap.class);}@Overridepublic 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 IDString 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 {@Beanpublic 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"));}@Beanpublic 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 {@Autowiredprivate 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埋点	实时掌握接口健康状态