API接口返回参数设计的最佳实践

最新推荐文章于 2024-07-19 19:18:39 发布

不老北鼻

最新推荐文章于 2024-07-19 19:18:39 发布

阅读量2.3k

点赞数 1

文章标签： java 接口

本文链接：https://blog.csdn.net/weixin_45710229/article/details/119454141

版权

本文探讨了前后端分离项目中如何通过一套完善的接口规范，以统一的状态码、数据结构和错误提示，提升团队开发效率。介绍了IErrorCode接口、ResultCode枚举和CommonResult泛型类的实现，以及在用户登录接口中的具体应用实例。

摘要生成于 C知道，由 DeepSeek-R1 满血版支持，前往体验 >

一、背景

在前后端还没有分离前，通常程序员是又当爹又当娘，不管是前端还是后端都是一个人开发。所谓的接口规范也是百花齐放，各有各的一套。现在流行前后端分离的项目中，一套较好的后端接口规范能够提高团队开发的效率。

因此，本文主要针对接口返回参数，结合已有项目中总结出来的一套比较完善的规范。

二、接口返回参数介绍

接口包含三大要素：状态码，结果集、成功或错误的提示。

{
    "code":"状态码",
    "data":"结果集",
    "massage":"成功或错误的提示"
}

三、后台代码展示

IErrorCode 接口
ResultCode 枚举类
CommonResult 泛型类

/**
 * 封装API的错误码
 */
public interface IErrorCode {
    long getCode();

    String getMessage();
}

/**
 * 枚举了一些常用API操作码
 */
public enum ResultCode{
    SUCCESS(200, "操作成功"),
    UNAUTHORIZED(401, "暂未登录或token已经过期"),
    FORBIDDEN(403, "没有相关权限"),
    VALIDATE_FAILED(404, "参数检验失败"),
    FAILED(500, "操作失败");
    
    private long code;
    private String message;

    private ResultCode(long code, String message) {
        this.code = code;
        this.message = message;
    }

    public long getCode() {
        return code;
    }

    public String getMessage() {
        return message;
    }
}

/**
 * 返回通用结果集对象
 */
public class CommonResult<T> {
    private long code;
    private String message;
    private T data;

    protected CommonResult() {
    }

    protected CommonResult(long code, String message, T data) {
        this.code = code;
        this.message = message;
        this.data = data;
    }

    /**
     * 成功返回结果
     *
     * @param data 获取的数据
     */
    public static <T> CommonResult<T> success(T data) {
        return new CommonResult<T>(ResultCode.SUCCESS.getCode(), ResultCode.SUCCESS.getMessage(), data);
    }

    /**
     * 成功返回结果
     *
     * @param data 获取的数据
     * @param  message 提示信息
     */
    public static <T> CommonResult<T> success(T data, String message) {
        return new CommonResult<T>(ResultCode.SUCCESS.getCode(), message, data);
    }

    /**
     * 失败返回结果
     * @param errorCode 错误码
     */
    public static <T> CommonResult<T> failed(IErrorCode errorCode) {
        return new CommonResult<T>(errorCode.getCode(), errorCode.getMessage(), null);
    }

    /**
     * 失败返回结果
     * @param message 提示信息
     */
    public static <T> CommonResult<T> failed(String message) {
        return new CommonResult<T>(ResultCode.FAILED.getCode(), message, null);
    }

    /**
     * 失败返回结果
     */
    public static <T> CommonResult<T> failed() {
        return failed(ResultCode.FAILED);
    }

    /**
     * 参数验证失败返回结果
     */
    public static <T> CommonResult<T> validateFailed() {
        return failed(ResultCode.VALIDATE_FAILED);
    }

    /**
     * 参数验证失败返回结果
     * @param message 提示信息
     */
    public static <T> CommonResult<T> validateFailed(String message) {
        return new CommonResult<T>(ResultCode.VALIDATE_FAILED.getCode(), message, null);
    }

    /**
     * 未登录返回结果
     */
    public static <T> CommonResult<T> unauthorized(T data) {
        return new CommonResult<T>(ResultCode.UNAUTHORIZED.getCode(), ResultCode.UNAUTHORIZED.getMessage(), data);
    }

    /**
     * 未授权返回结果
     */
    public static <T> CommonResult<T> forbidden(T data) {
        return new CommonResult<T>(ResultCode.FORBIDDEN.getCode(), ResultCode.FORBIDDEN.getMessage(), data);
    }
    
    //文章为了代码的简洁性，参数的getter、setter不在列举出来，读者可在实践中补充