【业务功能篇48】后端接口开发的统一规范

这篇具有很好参考价值的文章主要介绍了【业务功能篇48】后端接口开发的统一规范。希望对大家有所帮助。如果存在错误或未考虑完全的地方,请大家不吝赐教,您也可以点击"举报违法"按钮提交疑问。

业务背景:日常工作中,我们开发接口时,一般都会涉及到参数校验、异常处理、封装结果返回等处理。而我们项目有时为了快速迭代,在这方面上有所疏忽,后续导致代码维护比较难,不同的开发人员的不同习惯,各式各样的接口返回,所以专门进行了一次业务整改,统一规范专项

如果每个后端开发在参数校验、异常处理等都是各写各的,没有统一处理的话,代码就不优雅,也不容易维护。所以,作为一名合格的后端开发工程师,我们需要统一校验参数,统一异常处理、统一结果返回,让代码更加规范、可读性更强、更容易维护。

接口统一响应对象返回

作为后端开发,我们项目的响应结果,需要统一标准的返回格式。一般一个标准的响应报文对象,有一下几个属性

  • code :响应状态码
  • message :响应结果描述
  • data:返回的数据

1)响应状态码一般用枚举表示:

包结构: com.xxx.common.core.domain.ResultCode

/**
 * 响应状态码
 **/
public enum ResultCode {

    /**操作成功**/
    SUCCESS("200","操作成功"),

    /**操作失败**/
    ERROR("500","操作失败"),;

    /**
     * 自定义状态码
     **/
    private String code;
    
    
    /**自定义描述**/
    private String message;

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

    public String getCode() {
        return code;
    }

    public String getMessage() {
        return message;
    }
}

2)因为返回的数据类型不是确定的,我们可以使用泛型,如下:

包结构:com.xxx.common.core.domain.BaseResponse

/**
 * 响应结果封装对象
 **/
public class BaseResponse<T> implements Serializable {

    private static final long serialVersionUID = 1901152752394073986L;

    /**
     * 响应状态码
     */
    private String code;


    /**
     * 响应结果描述
     */
    private String message;

    /**
     * 返回的数据
     */
    private T data;


    /**
     * 成功返回
     * @param data
     * @return: com.msb.hjycommunity.common.core.domain.BaseResponse<T>
     */
    public static <T> BaseResponse<T> success(T data){

        BaseResponse<T> response = new BaseResponse<>();
        response.setCode(ResultCode.SUCCESS.getCode());
        response.setMessage(ResultCode.SUCCESS.getMessage());
        response.setData(data);

        return response;
    }


    /**
     * 失败返回
     * @param message
     * @return: com.msb.hjycommunity.common.core.domain.BaseResponse<T>
     */
    public static <T> BaseResponse<T> fail(String message){

        BaseResponse<T> response = new BaseResponse<>();
        response.setCode(ResultCode.ERROR.getCode());
        response.setMessage(message);

        return response;
    }

    /**
     * 失败返回
     * @param message
     * @return: com.msb.hjycommunity.common.core.domain.BaseResponse<T>
     */
    public static <T> BaseResponse<T> fail(String code, String message){

        BaseResponse<T> response = new BaseResponse<>();
        response.setCode(code);
        response.setMessage(message);

        return response;
    }


    public String getCode() {
        return code;
    }

    public void setCode(String code) {
        this.code = code;
    }

    public String getMessage() {
        return message;
    }

    public void setMessage(String message) {
        this.message = message;
    }

    public T getData() {
        return data;
    }

    public void setData(T data) {
        this.data = data;
    }
}

3)测试

  • 创建user实体类
public class User {

    private String userId;

    private String username;
    
    public User() {
    
    }
    
    public User(String userId, String username) {
        this.userId = userId;
        this.username = username;
    }

    public String getUserId() {
        return userId;
    }

    public void setUserId(String userId) {
        this.userId = userId;
    }

    public String getUsername() {
        return username;
    }

    public void setUsername(String username) {
        this.username = username;
    }
}

 

  • 创建UserController
@RestController
@RequestMapping("/user")
public class UserController {

    @RequestMapping("/queryUserById")
    public BaseResponse<User> queryUserById(String userId){

        if(userId != null){
           return BaseResponse.success(new User(userId,"spike"));
        }else{
            return BaseResponse.fail("查询用户信息失败!");
        }
    }
}

 

  • 测试
http://localhost:8888/user/queryUserById?userId=1

//output
{
  "code": "200",
  "message": "操作成功",
  "data": {
    "userId": "1",
    "username": "tom"
  }
}

http://localhost:8888/user/queryUserById

//output
{
  "code": "500",
  "message": "查询用户信息失败!",
  "data": null
}

使用注解,统一参数校验

我们在实际的开发过程中经常会遇到需要对参数进行校验的情况,比如在需要用户输入手机号的时候他是不是真的输入了一个合法的手机号,在需要用户输入一个邮箱的时候他是不是真的输入了一个合法的邮箱,用户输入的内容是不是超出了长度限制等等。

当一个表单的数据较多的时候,单纯的数据校验代码就会占到很大的幅度,所以简化基础数据的校验可以省去我们很多的工作,让我们能更专注于功能的实现。

接下来我们一起看一下 springboot中参数校验(validation)的使用,首先导入依赖

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-validation</artifactId>
</dependency>

Validator可以非常方便的制定校验规则,并自动帮你完成校验。首先在入参里需要校验的字段加上注解,每个注解对应不同的校验规则,并可制定校验失败后的信息:


public class User {
    
    private String userId;

    @NotNull(message = "username 不能为空")
    private String username;
}

 

校验规则和错误提示信息配置完毕后,接下来只需要在接口需要校验的参数上加上@Validated注解,并添加BindResult参数即可方便完成验证:


@RestController
@RequestMapping("/user")
public class UserController {

    @RequestMapping("/addUser")
    public BaseResponse addUser(@Validated User user, BindingResult bindingResult){

        List<FieldError> fieldErrors = bindingResult.getFieldErrors();

        //如果参数校验失败,会将错误信息封装成对象组装在 BindingResult
        if(!fieldErrors.isEmpty()){
            return BaseResponse.fail(fieldErrors.get(0).getDefaultMessage());
        }

        return BaseResponse.success("OK");
    }
}

 

测试

http://localhost:8888/user/addUser?username="tom"

{
  "code": "500",
  "message": "userId 不能为空",
  "data": null
}

http://localhost:8888/user/addUser?username="tom"&userId=1

{
  "code": "200",
  "message": "操作成功",
  "data": "OK"
}

内置的校验注解有很多,罗列如下:

【业务功能篇48】后端接口开发的统一规范,业务场景实例问题,Java,Spring boot,java,springboot接口规范,springboot

统一异常处理

日常开发中,我们一般都是自定义统一的异常类

  • 自定义异常可以携带更多的信息。
  • 项目开发中经常是很多人负责不同的模块,使用自定义异常可以统一了对外异常展示的方式。
  • 自定义异常语义更加清晰明了,一看就知道是项目中手动抛出的异常。

自定义异常类, 所在包结构: com.xxx.common.core.exception.BaseException


/**
 * 基础异常
 **/
public class BaseException extends RuntimeException{


    /**
     * 错误码
     */
    private String code;


    /**
     * 错误消息
     */
    private String defaultMessage;

    public BaseException() {
    }

    public BaseException(String code, String defaultMessage) {
        this.code = code;
        this.defaultMessage = defaultMessage;
    }

    public String getCode() {
        return code;
    }

    public String getDefaultMessage() {
        return defaultMessage;
    }
}

 

在controller 层,我们来使用这个自定义异常:


@RequestMapping("/queryUser")
public BaseResponse queryUser(User user){

    //模拟查询失败抛出异常
    throw new BaseException("500","测试异常类!");
}

 

这块代码,没什么问题,但是如果在很多地方都抛出这个异常,我们处理起来就会比较麻烦。

这时我们可以借助注解@RestControllerAdvice,让代码更优雅。@RestControllerAdvice是一个应用于Controller层的切面注解,它一般配合@ExceptionHandler注解一起使用,作为项目的全局异常处理。示例代码如下:


/**
 * 全局异常处理器
 **/
@RestControllerAdvice
public class GlobalExceptionHandler {


}

我们有想要拦截的异常类型,比如想拦截BaseException类型,就新增一个方法,使用@ExceptionHandler注解修饰,并指定你想处理的异常类型,接着在方法内编写对该异常的操作逻辑,就完成了对该异常的全局处理! 


@RestControllerAdvice
public class GlobalExceptionHandler {

    /**
     * 基础异常
     * @param e
     * @return: com.xxx.common.core.domain.BaseResponse
     */
    @ExceptionHandler(BaseException.class)
    @ResponseBody
    public BaseResponse baseExceptionHandler(BaseException e){
        
        return BaseResponse.fail(e.getDefaultMessage());
    }

}

 

测试

http://localhost:8888/hejiayun/user/queryUser

{
  "code": "500",
  "message": "测试异常类!",
  "data": null
}

总结:整改的几个维度,但这里需要注意的是,全局异常设计,在个人看来并不一定是有效的,有时会封装过简单,还不易于排查代码问题。文章来源地址https://www.toymoban.com/news/detail-577275.html

  • 通过Validation 完成了方便的参数校验
  • 通过全局异常处理 + 自定义异常完成了异常操作的规范
  • 通过数据统一响应完成了响应数据的规范
  • 多个方面组装非常优雅的完成了后端接口的协调,让开发人员有更多的经历注重业务逻辑代码,轻松构建后端接口。

到了这里,关于【业务功能篇48】后端接口开发的统一规范的文章就介绍完了。如果您还想了解更多内容,请在右上角搜索TOY模板网以前的文章或继续浏览下面的相关文章,希望大家以后多多支持TOY模板网!

本文来自互联网用户投稿,该文观点仅代表作者本人,不代表本站立场。本站仅提供信息存储空间服务,不拥有所有权,不承担相关法律责任。如若转载,请注明出处: 如若内容造成侵权/违法违规/事实不符,请点击违法举报进行投诉反馈,一经查实,立即删除!

领支付宝红包 赞助服务器费用

相关文章

  • iOS16新特性 | 灵动岛适配开发与到家业务场景结合的探索实践

    作者:京东零售 姜海 灵动岛是苹果在iPhone 14 Pro和iPhone 14 Pro Max上首次提出的全新UI交互形式,创新性的让虚拟软件和硬件的交互变得更为流畅。当有来电、短信等通知时,灵动岛会变化形态,以便让用户能够更直观地接收到这些信息。 而在用户使用一些应用App,比如音乐,

    2023年04月12日
    浏览(38)
  • 告别混乱代码:这份 Spring Boot 后端接口规范来得太及时了!

    一个后端接口大致分为四个部分组成: 接口地址(url)、接口请求方式(get、post等)、请求数据(request)、响应数据(response) 。虽然说后端接口的编写并没有统一规范要求,而且如何构建这几个部分每个公司要求都不同,没有什么“一定是最好的”标准,但其中最重要的

    2024年02月11日
    浏览(72)
  • SpringBoot自定义starter开发:IP计数业务功能开发

    🙈作者简介:练习时长两年半的Java up主 🙉个人主页:程序员老茶 🙊 ps:点赞👍是免费的,却可以让写博客的作者开心好久好久😎 📚系列专栏:Java全栈,计算机系列(火速更新中) 💭 格言:种一棵树最好的时间是十年前,其次是现在 🏡动动小手,点个关注不迷路,感

    2024年04月16日
    浏览(36)
  • 实际开发中常用的设计模式--------策略模式(知识跟业务场景结合)-----小白也能看懂(通俗易懂版本)

    1.策略模式定义: 策略模式是一种行为型设计模式,它允许在运行时动态地改变对象的行为。策略模式将将每一个算法封装到具有共同接口的独立的类中,从而使得它们可以相互替换从而使得算法的变化不会影响到客户端 2.简单的策略模式示例代码: 在上述代码中,SortStra

    2024年02月13日
    浏览(51)
  • 辅助驾驶功能开发-功能规范篇(16)-2-领航辅助系统NAP-HMI人机交互

     书接上回 2.3.7HMI人机交互 2.3.7.1显示 (1)图标 序号 图标状态 (图形、颜色供参考) 含义说明 备注 1 辅助驾驶功能READY (允许激活) 2 辅助驾驶功能激活 3 辅助驾驶系统故障 4

    2024年02月08日
    浏览(41)
  • 业务需要咨询?开发遇到 bug 想反馈?开发者在线提单功能上线!

    大家是否遇到过下列问题—— 在开发的时候,遇到 bug 需要反馈… 有合作意向的时候,想更多了解业务和相关产品… 在接入的时候,需要得到专业技术支持… 别急,荣耀开发者服务平台在线提单功能上线了~ 处理问题分类说明:业务咨询、产品咨询、技术支持、问题 BUG 反馈

    2024年02月10日
    浏览(47)
  • 实际开发中常用的设计模式--------单例模式(知识跟业务场景结合)-----小白也能看懂(通俗易懂版本)

    1.定义 单例模式是一种创建型设计模式,它通过使用私有构造函数和静态方法来确保一个类只有一个实例,并且提供全局访问点来获取该实例。 通过使用单例模式,我们可以方便地管理全局唯一的对象实例,并且避免了多次创建相同类型的对象所带来的资源浪费问题 2.业务场

    2024年02月12日
    浏览(44)
  • Java开发面试题目场景业务提问第十六章:常问日常必备_JAVA_面试题集(含答案)【王大师】

    往期文章   第 十 章 日常_JAVA_面试题集10(含答案)  第十三章:日常_JAVA_面试题集13(含答案)  第十二章:日常_JAVA_面试题集12(含答案)  第十一章:日常_JAVA_面试题集11(含答案)  往期文章大全……

    2024年02月08日
    浏览(54)
  • 中文编程工具开发语言开发的实际案例:触摸屏点餐软件应用场景实例

    中文编程工具开发语言开发的实际案例:触摸屏点餐软件应用场景实例 软件特色: 1、功能实用,操作简单,不会电脑也会操作,软件免安装,已内置数据库。软件在关闭的时候,可以设置会员数据备份到U盘,数据本机备份一份,U盘备份一份,双重备份数据安全。 2、软件既

    2024年02月08日
    浏览(45)
  • Git使用统一规范

    统一的风格使我们在工作的时候无需考虑工作流程上该如何去做的问题,按照一个风格去做就好了 每个人风格不同,格式凌乱,查看很不方便 commit没有准确的message,后续难以追踪问题 强制Git每次commit,都按照指定风格写commmit message,否则不允许提交。 上面的提交包含三部

    2024年02月02日
    浏览(56)

觉得文章有用就打赏一下文章作者

支付宝扫一扫打赏

博客赞助

微信扫一扫打赏

请作者喝杯咖啡吧~博客赞助

支付宝扫一扫领取红包,优惠每天领

二维码1

领取红包

二维码2

领红包