Springboot项目中如何设计一个规范的统一的Restful API 响应框架?

简介: Springboot项目中如何设计一个规范的统一的Restful API 响应框架?

一、设计

目前项目开发,都是基于前后端分离模式开发的,基于后端模板引擎那一套,可能已经不适用一些项目开发流程,和当下开发模式了,尤其在要写比较大型项目,前后端项目拆分,团队共同开发那是必不可少的

目前的前后端开发大部分数据的传输格式都是json,因此定义一个统一规范的数据格式有利于前后端的交互与UI的展示。

返回的统一接口形式应该包含这些内容

  1. 是否响应成功
  2. 响应状态码
  3. 状态码描述
  4. 响应数据
  5. 接口调用时间
  6. 其他标识符

按照这些我们可以定义统一的标准结果返回

二、响应枚举

前三者可以定义为 success,code,message

package com.tigerhhzz.springbootmybatisplusdemo.domain;
import lombok.Getter;
/**
 * @author tigerhhzz
 * @date 2023/5/10 9:28
 * 响应结果枚举
 */
@Getter
public enum ResultCodeEnum {
    SUCCESS(true, 200, "成功"),
    FAIL(false, 400, "请求失败"),
    NOT_FOUND(false, 404, "接口不存在"),
    FORBIDDEN(false, 403, "资源拒绝访问"),
    UNAUTHORIZED(false, 401, "未认证(签名错误)"),
    INTERNAL_SERVER_ERROR(false, 500, "服务器内部错误"),
    NULL_POINT(false, 200002, "空指针异常"),
    PARAM_ERROR(false, 200001, "参数错误");
    /**
     * 响应是否成功
     */
    private Boolean success;
    /**
     * 响应状态码
     */
    private Integer code;
    /**
     * 响应信息
     */
    private String message;
    ResultCodeEnum(Boolean success, Integer code, String message) {
        this.success = success;
        this.code = code;
        this.message = message;
    }
}

三、统一结果类

  • 外部返回调用类统一的结果方法 success,failure 因此构造器私有
  • 内置静态方法,直接返回对象
  • 便于自定义统一结果信息,使用链式编程,返回对象类本身 return this
  • 响应数据为json格式,可定义为JsonObject或Map形式
package com.tigerhhzz.springbootmybatisplusdemo.domain;
import java.util.HashMap;
import java.util.Map;
/**
 * @author tigerhhzz
 * @date 2023/5/10 9:31
 * 统一响应结果处理  使用链式编程 返回类本身
 */
public class CommonRespResult {
    private Boolean success;
    private Integer code;
    private String message;
    /**
     * 接口请求时间戳
     */
    private Long timestamp;
    private Map<String, Object> data = new HashMap<>();
    private CommonRespResult setSuccess(Boolean success) {
        this.success = success;
        return this;
    }
    private CommonRespResult setMessage(String message) {
        this.message = message;
        return this;
    }
    private CommonRespResult setData(Map<String, Object> data) {
        this.data = data;
        return this;
    }
    private CommonRespResult setCode(Integer code) {
        this.code = code;
        return this;
    }
    private CommonRespResult() {
    }
    private CommonRespResult(Long timestamp) {
        this.timestamp = timestamp;
    }
    /**
     * 通用返回成功
     *
     * @return
     */
    public static CommonRespResult success() {
        return new CommonRespResult(System.currentTimeMillis())
                .setSuccess(ResultCodeEnum.SUCCESS.getSuccess())
                .setCode(ResultCodeEnum.SUCCESS.getCode())
                .setMessage(ResultCodeEnum.SUCCESS.getMessage());
    }
    /**
     * 通用返回失败
     *
     * @return
     */
    public static CommonRespResult failure() {
        return new CommonRespResult(System.currentTimeMillis())
                .setSuccess(ResultCodeEnum.FAIL.getSuccess())
                .setCode(ResultCodeEnum.FAIL.getCode())
                .setMessage(ResultCodeEnum.FAIL.getMessage());
    }
    /**
     * 设置结果,形参为结果枚举
     *
     * @param result
     * @return
     */
    public static CommonRespResult setResult(ResultCodeEnum result) {
        return new CommonRespResult(System.currentTimeMillis())
                .setSuccess(result.getSuccess())
                .setCode(result.getCode())
                .setMessage(result.getMessage());
    }
    // 自定义返回数据
    public CommonRespResult data(Map<String, Object> map) {
        return this.setData(map);
    }
    // 通用设置data
    public CommonRespResult data(String key, Object value) {
        this.data.put(key, value);
        return this;
    }
    // 自定义状态信息
    public CommonRespResult message(String message) {
        return this.setMessage(message);
    }
    // 自定义状态码
    public CommonRespResult code(Integer code) {
        return this.setCode(code);
    }
    // 自定义返回结果
    public CommonRespResult success(Boolean success) {
        return this.setSuccess(success);
    }
}

四、控制层调用返回

package com.tigerhhzz.springbootmybatisplusdemo.controller;
import com.tigerhhzz.springbootmybatisplusdemo.domain.CommonRespResult;
import com.tigerhhzz.springbootmybatisplusdemo.domain.MBlog;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
import java.util.HashMap;
import java.util.Map;
/**
 * <p>
 *  前端控制器
 * </p>
 *
 * @author tigerhhzz
 * @since 2023-04-28
 */
@RestController
public class MBlogController {
    @GetMapping("/index")
    public CommonRespResult index() {
        Map m = new HashMap();
        m.put("name", "Tom");
        m.put("age", 25);
        m.put("sex", "男");
        return CommonRespResult.success().data(m);
    }
    @GetMapping("/home")
    public CommonRespResult home() {
        MBlog mBlog = new MBlog();
        mBlog.setContent("DFSDFSDFSDFSD");
        mBlog.setTitle("FFDSFD");
        return CommonRespResult.success().data("mBlog",mBlog).message("查询用户详情信息");
    }
    /**
     * 异常返回模拟
     *
     * @return
     */
    @GetMapping("/exception")
    public CommonRespResult exception() {
        Map m = null;
        m.put("name", "Jack");
        return CommonRespResult.success().data("user", m).message("查询用户详情信息");
    }
}

统一结果类的使用参考了mybatis-plus中Result对象的设计。

目录
打赏
0
1
1
0
40
分享
相关文章
|
6天前
|
聊聊你对SpringBoot框架的理解 ?
SpringBoot是Spring家族中流行的子项目,旨在简化Spring框架开发的繁琐配置。它主要提供三大功能:starter起步依赖简化依赖管理,自动配置根据条件创建Bean,以及内嵌Web服务器支持Jar包运行,极大提升了开发效率。
29 0
RESTful与GraphQL:电商API接口设计的技术细节与适用场景
本文对比了RESTful与GraphQL这两种主流电商API接口设计方案。RESTful通过资源与HTTP方法定义操作,简单直观但可能引发过度或欠获取数据问题;GraphQL允许客户端精确指定所需字段,提高灵活性和传输效率,但面临深度查询攻击等安全挑战。从性能、灵活性、安全性及适用场景多维度分析,RESTful适合资源导向场景,GraphQL则适用于复杂数据需求。实际开发中需根据业务特点选择合适方案,或结合两者优势,以优化用户体验与系统性能。
SpringBoot框架
Spring Boot 是 Spring 家族中最流行的框架,旨在简化 Spring 应用的初始搭建与开发。它通过自动配置、起步依赖和内嵌服务器三大核心功能,大幅减少配置复杂度,提升开发效率。开发者可快速构建独立运行的 Web 应用,并支持多种数据访问技术和第三方集成。
Spring 框架核心原理与实践解析
本文详解 Spring 框架核心知识,包括 IOC(容器管理对象)与 DI(容器注入依赖),以及通过注解(如 @Service、@Autowired)声明 Bean 和注入依赖的方式。阐述了 Bean 的线程安全(默认单例可能有安全问题,需业务避免共享状态或设为 prototype)、作用域(@Scope 注解,常用 singleton、prototype 等)及完整生命周期(实例化、依赖注入、初始化、销毁等步骤)。 解析了循环依赖的解决机制(三级缓存)、AOP 的概念(公共逻辑抽为切面)、底层动态代理(JDK 与 Cglib 的区别)及项目应用(如日志记录)。介绍了事务的实现(基于 AOP
基于 Spring Boot 框架开发 REST API 接口实践指南
本文详解基于Spring Boot 3.x构建REST API的完整开发流程,涵盖环境搭建、领域建模、响应式编程、安全控制、容器化部署及性能优化等关键环节,助力开发者打造高效稳定的后端服务。
111 1
Spring Cache缓存框架
Spring Cache是Spring体系下的标准化缓存框架,支持多种缓存(如Redis、EhCache、Caffeine),可独立或组合使用。其优势包括平滑迁移、注解与编程两种使用方式,以及高度解耦和灵活管理。通过动态代理实现缓存操作,适用于不同业务场景。
Go语言网络编程:使用 net/http 构建 RESTful API
本章介绍如何使用 Go 语言的 `net/http` 标准库构建 RESTful API。内容涵盖 RESTful API 的基本概念及规范,包括 GET、POST、PUT 和 DELETE 方法的实现。通过定义用户数据结构和模拟数据库,逐步实现获取用户列表、创建用户、更新用户、删除用户的 HTTP 路由处理函数。同时提供辅助函数用于路径参数解析,并展示如何设置路由器启动服务。最后通过 curl 或 Postman 测试接口功能。章节总结了路由分发、JSON 编解码、方法区分、并发安全管理和路径参数解析等关键点,为更复杂需求推荐第三方框架如 Gin、Echo 和 Chi。
SpringBoot框架常见的starter你都用过哪些 ?
本节介绍常见的Spring Boot Starter,分为官方(如Web、AOP、Redis等)与第三方(如MyBatis、MyBatis Plus)两类,用于快速集成Web开发、数据库、消息队列等功能。
24 0
从业务需求到技术栈:电商API选型RESTful还是GraphQL?这5个维度帮你决策
在数字经济时代,电商平台的竞争已延伸至用户体验与系统效能。作为连接前后端及各类服务的核心,API接口的架构设计至关重要。本文对比RESTful与GraphQL两大主流方案,从电商场景出发,分析两者的技术特性、适用场景与选型逻辑,帮助开发者根据业务需求做出最优选择。
第五章 Spring框架
第五章 Spring框架
AI助理

你好,我是AI助理

可以解答问题、推荐解决方案等