IT技术社区_专业开发者平台_最新编程教程与解决方案 -沐辰社区

Spring Boot实现统一返回格式案例

wen java案例 1

本文目录导读：

Spring Boot实现统一返回格式案例

  1. 项目结构
  2. 统一返回结果类实现
  3. 实体类
  4. Controller层示例
  5. Service层示例（带异常处理）
  6. 配置类（可选）
  7. 主启动类
  8. 测试用例
  9. 在Controller中使用Service
  10. 响应示例
  11. Maven依赖
  12. 使用说明

我来为您提供一个完整的Spring Boot统一返回格式的实现案例。

项目结构

src/main/java/com/example/demo/
├── DemoApplication.java
├── common/
│   ├── Result.java           // 统一返回结果类
│   ├── ResultCode.java       // 返回状态码枚举
│   └── GlobalExceptionHandler.java  // 全局异常处理器
├── controller/
│   └── UserController.java
├── service/
│   ├── UserService.java
│   └── impl/
│       └── UserServiceImpl.java
├── entity/
│   └── User.java
└── config/
    └── WebMvcConfig.java    // Web配置（可选）

统一返回结果类实现

1 状态码枚举类

package com.example.demo.common;
import lombok.Getter;
/**
 * 返回状态码枚举
 */
@Getter
public enum ResultCode {
    SUCCESS(200, "操作成功"),
    ERROR(500, "操作失败"),
    PARAM_ERROR(400, "参数错误"),
    UNAUTHORIZED(401, "未认证"),
    FORBIDDEN(403, "无权限"),
    NOT_FOUND(404, "资源不存在"),
    // 业务相关错误码
    USER_NOT_EXIST(1001, "用户不存在"),
    USER_ALREADY_EXIST(1002, "用户已存在"),
    PASSWORD_ERROR(1003, "密码错误"),
    USERNAME_ERROR(1004, "用户名错误"),
    // 系统错误码
    SYSTEM_ERROR(5000, "系统异常"),
    DATABASE_ERROR(5001, "数据库异常");
    // 状态码
    private final Integer code;
    // 返回消息
    private final String message;
    ResultCode(Integer code, String message) {
        this.code = code;
        this.message = message;
    }
}

2 统一返回结果类

package com.example.demo.common;
import lombok.Data;
import java.io.Serializable;
/**
 * 统一返回结果类
 */
@Data
public class Result<T> implements Serializable {
    private static final long serialVersionUID = 1L;
    /**
     * 状态码
     */
    private Integer code;
    /**
     * 返回消息
     */
    private String message;
    /**
     * 返回数据
     */
    private T data;
    /**
     * 时间戳
     */
    private Long timestamp;
    public Result() {
        this.timestamp = System.currentTimeMillis();
    }
    /**
     * 成功返回结果
     */
    public static <T> Result<T> success() {
        return success(null);
    }
    /**
     * 成功返回结果
     */
    public static <T> Result<T> success(T data) {
        Result<T> result = new Result<>();
        result.setCode(ResultCode.SUCCESS.getCode());
        result.setMessage(ResultCode.SUCCESS.getMessage());
        result.setData(data);
        return result;
    }
    /**
     * 成功返回结果（自定义消息）
     */
    public static <T> Result<T> success(String message, T data) {
        Result<T> result = new Result<>();
        result.setCode(ResultCode.SUCCESS.getCode());
        result.setMessage(message);
        result.setData(data);
        return result;
    }
    /**
     * 失败返回结果
     */
    public static <T> Result<T> error() {
        return error(ResultCode.ERROR);
    }
    /**
     * 失败返回结果（自定义信息）
     */
    public static <T> Result<T> error(String message) {
        return error(ResultCode.ERROR.getCode(), message);
    }
    /**
     * 失败返回结果（使用枚举）
     */
    public static <T> Result<T> error(ResultCode resultCode) {
        return error(resultCode.getCode(), resultCode.getMessage());
    }
    /**
     * 失败返回结果（自定义状态码和消息）
     */
    public static <T> Result<T> error(Integer code, String message) {
        Result<T> result = new Result<>();
        result.setCode(code);
        result.setMessage(message);
        return result;
    }
}

3 业务异常类

package com.example.demo.common;
import lombok.Getter;
/**
 * 业务异常类
 */
@Getter
public class BusinessException extends RuntimeException {
    private final Integer code;
    private final String message;
    public BusinessException(String message) {
        super(message);
        this.code = ResultCode.ERROR.getCode();
        this.message = message;
    }
    public BusinessException(ResultCode resultCode) {
        super(resultCode.getMessage());
        this.code = resultCode.getCode();
        this.message = resultCode.getMessage();
    }
    public BusinessException(Integer code, String message) {
        super(message);
        this.code = code;
        this.message = message;
    }
}

4 全局异常处理器

package com.example.demo.common;
import lombok.extern.slf4j.Slf4j;
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 javax.validation.ConstraintViolation;
import javax.validation.ConstraintViolationException;
import java.util.stream.Collectors;
/**
 * 全局异常处理器
 */
@Slf4j
@RestControllerAdvice
public class GlobalExceptionHandler {
    /**
     * 处理业务异常
     */
    @ExceptionHandler(BusinessException.class)
    public Result<?> handleBusinessException(BusinessException e) {
        log.error("业务异常：{}", e.getMessage());
        return Result.error(e.getCode(), e.getMessage());
    }
    /**
     * 处理参数校验异常（@RequestBody）
     */
    @ExceptionHandler(MethodArgumentNotValidException.class)
    public Result<?> handleMethodArgumentNotValidException(MethodArgumentNotValidException e) {
        String message = e.getBindingResult().getFieldErrors().stream()
                .map(FieldError::getDefaultMessage)
                .collect(Collectors.joining(", "));
        log.error("参数校验异常：{}", message);
        return Result.error(ResultCode.PARAM_ERROR.getCode(), message);
    }
    /**
     * 处理参数绑定异常
     */
    @ExceptionHandler(BindException.class)
    public Result<?> handleBindException(BindException e) {
        String message = e.getBindingResult().getFieldErrors().stream()
                .map(FieldError::getDefaultMessage)
                .collect(Collectors.joining(", "));
        log.error("参数绑定异常：{}", message);
        return Result.error(ResultCode.PARAM_ERROR.getCode(), message);
    }
    /**
     * 处理参数校验异常（@RequestParam）
     */
    @ExceptionHandler(ConstraintViolationException.class)
    public Result<?> handleConstraintViolationException(ConstraintViolationException e) {
        String message = e.getConstraintViolations().stream()
                .map(ConstraintViolation::getMessage)
                .collect(Collectors.joining(", "));
        log.error("参数约束异常：{}", message);
        return Result.error(ResultCode.PARAM_ERROR.getCode(), message);
    }
    /**
     * 处理其他未知异常
     */
    @ExceptionHandler(Exception.class)
    public Result<?> handleException(Exception e) {
        log.error("系统异常：", e);
        return Result.error(ResultCode.SYSTEM_ERROR.getCode(), ResultCode.SYSTEM_ERROR.getMessage());
    }
}

实体类

package com.example.demo.entity;
import lombok.Data;
import javax.validation.constraints.Email;
import javax.validation.constraints.NotBlank;
import javax.validation.constraints.NotNull;
import javax.validation.constraints.Size;
@Data
public class User {
    private Long id;
    @NotBlank(message = "用户名不能为空")
    @Size(min = 2, max = 20, message = "用户名长度必须在2-20之间")
    private String username;
    @NotBlank(message = "密码不能为空")
    @Size(min = 6, max = 20, message = "密码长度必须在6-20之间")
    private String password;
    @Email(message = "邮箱格式不正确")
    private String email;
    @NotNull(message = "年龄不能为空")
    private Integer age;
}

Controller层示例

package com.example.demo.controller;
import com.example.demo.common.Result;
import com.example.demo.entity.User;
import org.springframework.web.bind.annotation.*;
import javax.validation.Valid;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
@RestController
@RequestMapping("/api/users")
public class UserController {
    /**
     * 模拟用户数据
     */
    private static final Map<Long, User> USER_MAP = new HashMap<>();
    static {
        User user1 = new User();
        user1.setId(1L);
        user1.setUsername("zhangsan");
        user1.setPassword("123456");
        user1.setEmail("zhangsan@example.com");
        user1.setAge(25);
        USER_MAP.put(1L, user1);
        User user2 = new User();
        user2.setId(2L);
        user2.setUsername("lisi");
        user2.setPassword("123456");
        user2.setEmail("lisi@example.com");
        user2.setAge(30);
        USER_MAP.put(2L, user2);
    }
    /**
     * 查询所有用户
     * GET /api/users
     */
    @GetMapping
    public Result<List<User>> list() {
        List<User> users = new ArrayList<>(USER_MAP.values());
        return Result.success(users);
    }
    /**
     * 根据ID查询用户
     * GET /api/users/{id}
     */
    @GetMapping("/{id}")
    public Result<User> getUserById(@PathVariable Long id) {
        User user = USER_MAP.get(id);
        if (user == null) {
            return Result.error("用户不存在");
        }
        return Result.success(user);
    }
    /**
     * 创建用户
     * POST /api/users
     */
    @PostMapping
    public Result<User> create(@Valid @RequestBody User user) {
        // 模拟创建用户
        Long id = (long) (USER_MAP.size() + 1);
        user.setId(id);
        USER_MAP.put(id, user);
        return Result.success("创建用户成功", user);
    }
    /**
     * 更新用户
     * PUT /api/users/{id}
     */
    @PutMapping("/{id}")
    public Result<User> update(@PathVariable Long id, @Valid @RequestBody User user) {
        if (!USER_MAP.containsKey(id)) {
            return Result.error("用户不存在");
        }
        user.setId(id);
        USER_MAP.put(id, user);
        return Result.success("更新用户成功", user);
    }
    /**
     * 删除用户
     * DELETE /api/users/{id}
     */
    @DeleteMapping("/{id}")
    public Result<?> delete(@PathVariable Long id) {
        if (!USER_MAP.containsKey(id)) {
            return Result.error("用户不存在");
        }
        USER_MAP.remove(id);
        return Result.success("删除用户成功");
    }
}

Service层示例（带异常处理）

package com.example.demo.service;
import com.example.demo.common.BusinessException;
import com.example.demo.common.ResultCode;
import com.example.demo.entity.User;
import org.springframework.stereotype.Service;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
@Service
public class UserService {
    private static final Map<Long, User> USER_MAP = new HashMap<>();
    static {
        User user1 = new User();
        user1.setId(1L);
        user1.setUsername("zhangsan");
        user1.setPassword("123456");
        user1.setEmail("zhangsan@example.com");
        user1.setAge(25);
        USER_MAP.put(1L, user1);
    }
    /**
     * 查询所有用户
     */
    public List<User> findAll() {
        return new ArrayList<>(USER_MAP.values());
    }
    /**
     * 根据ID查询用户
     */
    public User findById(Long id) {
        User user = USER_MAP.get(id);
        if (user == null) {
            throw new BusinessException(ResultCode.USER_NOT_EXIST);
        }
        return user;
    }
    /**
     * 创建用户
     */
    public User create(User user) {
        // 检查用户名是否已存在
        boolean exists = USER_MAP.values().stream()
                .anyMatch(u -> u.getUsername().equals(user.getUsername()));
        if (exists) {
            throw new BusinessException(ResultCode.USER_ALREADY_EXIST);
        }
        Long id = (long) (USER_MAP.size() + 1);
        user.setId(id);
        USER_MAP.put(id, user);
        return user;
    }
    /**
     * 更新用户
     */
    public User update(Long id, User user) {
        if (!USER_MAP.containsKey(id)) {
            throw new BusinessException(ResultCode.USER_NOT_EXIST);
        }
        user.setId(id);
        USER_MAP.put(id, user);
        return user;
    }
    /**
     * 删除用户
     */
    public void delete(Long id) {
        if (!USER_MAP.containsKey(id)) {
            throw new BusinessException(ResultCode.USER_NOT_EXIST);
        }
        USER_MAP.remove(id);
    }
}

配置类（可选）

package com.example.demo.config;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.CorsRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
@Configuration
public class WebMvcConfig implements WebMvcConfigurer {
    /**
     * 配置跨域（如有需要）
     */
    @Override
    public void addCorsMappings(CorsRegistry registry) {
        registry.addMapping("/**")
                .allowedOrigins("*")
                .allowedMethods("GET", "POST", "PUT", "DELETE", "OPTIONS")
                .allowedHeaders("*")
                .maxAge(3600);
    }
}

主启动类

package com.example.demo;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
@SpringBootApplication
public class DemoApplication {
    public static void main(String[] args) {
        SpringApplication.run(DemoApplication.class, args);
    }
}

测试用例

package com.example.demo;
import com.example.demo.common.Result;
import com.fasterxml.jackson.databind.ObjectMapper;
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.web.servlet.AutoConfigureMockMvc;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.http.MediaType;
import org.springframework.test.web.servlet.MockMvc;
import org.springframework.test.web.servlet.MvcResult;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.*;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.*;
@SpringBootTest
@AutoConfigureMockMvc
class DemoApplicationTests {
    @Autowired
    private MockMvc mockMvc;
    @Autowired
    private ObjectMapper objectMapper;
    @Test
    void testGetUserById() throws Exception {
        mockMvc.perform(get("/api/users/1"))
                .andExpect(status().isOk())
                .andExpect(jsonPath("$.code").value(200))
                .andExpect(jsonPath("$.message").value("操作成功"))
                .andExpect(jsonPath("$.data.username").value("zhangsan"));
    }
    @Test
    void testGetUserNotExist() throws Exception {
        mockMvc.perform(get("/api/users/999"))
                .andExpect(status().isOk())
                .andExpect(jsonPath("$.code").value(500))
                .andExpect(jsonPath("$.message").value("用户不存在"));
    }
    @Test
    void testCreateUser() throws Exception {
        String userJson = "{\"username\":\"wangwu\",\"password\":\"123456\",\"email\":\"wangwu@example.com\",\"age\":28}";
        mockMvc.perform(post("/api/users")
                .contentType(MediaType.APPLICATION_JSON)
                .content(userJson))
                .andExpect(status().isOk())
                .andExpect(jsonPath("$.code").value(200))
                .andExpect(jsonPath("$.data.username").value("wangwu"));
    }
    @Test
    void testCreateUserValidation() throws Exception {
        // 测试参数校验
        String invalidUserJson = "{\"username\":\"w\",\"password\":\"123\",\"email\":\"invalid-email\",\"age\":-1}";
        mockMvc.perform(post("/api/users")
                .contentType(MediaType.APPLICATION_JSON)
                .content(invalidUserJson))
                .andExpect(status().isOk())
                .andExpect(jsonPath("$.code").value(400));
    }
}

在Controller中使用Service

package com.example.demo.controller;
import com.example.demo.common.Result;
import com.example.demo.entity.User;
import com.example.demo.service.UserService;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;
import javax.validation.Valid;
import java.util.List;
@RestController
@RequestMapping("/api/users")
public class UserController {
    @Autowired
    private UserService userService;
    /**
     * 查询所有用户
     */
    @GetMapping
    public Result<List<User>> list() {
        return Result.success(userService.findAll());
    }
    /**
     * 根据ID查询用户
     */
    @GetMapping("/{id}")
    public Result<User> getUserById(@PathVariable Long id) {
        return Result.success(userService.findById(id));
    }
    /**
     * 创建用户
     */
    @PostMapping
    public Result<User> create(@Valid @RequestBody User user) {
        return Result.success("创建用户成功", userService.create(user));
    }
    /**
     * 更新用户
     */
    @PutMapping("/{id}")
    public Result<User> update(@PathVariable Long id, @Valid @RequestBody User user) {
        return Result.success("更新用户成功", userService.update(id, user));
    }
    /**
     * 删除用户
     */
    @DeleteMapping("/{id}")
    public Result<?> delete(@PathVariable Long id) {
        userService.delete(id);
        return Result.success("删除用户成功");
    }
}

响应示例

成功响应：

{
    "code": 200,
    "message": "操作成功",
    "data": {
        "id": 1,
        "username": "zhangsan",
        "password": "123456",
        "email": "zhangsan@example.com",
        "age": 25
    },
    "timestamp": 1700000000000
}

失败响应：

{
    "code": 1001,
    "message": "用户不存在",
    "data": null,
    "timestamp": 1700000000000
}

Maven依赖

<dependencies>
    <!-- Spring Boot Web -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <!-- Validation -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-validation</artifactId>
    </dependency>
    <!-- Lombok -->
    <dependency>
        <groupId>org.projectlombok</groupId>
        <artifactId>lombok</artifactId>
        <optional>true</optional>
    </dependency>
    <!-- Test -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-test</artifactId>
        <scope>test</scope>
    </dependency>
</dependencies>

使用说明

应用场景：

  1. 前后端分离：统一接口返回格式，方便前端处理
  2. API设计：统一错误码和消息格式
  3. 异常处理：统一异常捕获和转换

优势：

  1. 统一规范：所有接口返回格式一致
  2. 错误处理：全局异常处理，避免重复代码
  3. 可维护性：状态码和消息集中管理
  4. 扩展性：易于添加新的返回类型和状态码

注意事项：

  1. 状态码规划：合理规划业务状态码，避免冲突
  2. 异常处理：根据业务需求选择合适的异常处理方式
  3. 参数校验：结合@Valid实现参数验证
  4. 日志记录：在异常处理器中添加日志，便于问题排查

这个实现方案涵盖了统一返回格式的完整实现，包括正常返回、异常处理、参数校验等场景,您可以根据实际需求进行调整和扩展。

上一篇Spring Boot实现全局异常处理案例

下一篇Spring Boot整合Elasticsearch案例

相关文章

抱歉，评论功能暂时关闭!