花10分钟写个漂亮的后端API接口模板！

avatar
作者
猴君
阅读量:0

你好，我是田哥

在这微服务架构盛行的黄金时段，加上越来越多的前后端分离，导致后端API接口规范变得越来越重要了。

比如：统一返回参数形式、统一返回码、统一异常处理、集成swagger等。

目的主要是规范后端项目代码，以及便于前端沟通联通以及问题的排查。

本文内容：

6708d887d7a7084b46cbe2e8fae9ee79.png

统一返回参数形式

目前主流的返回参数形式：

{   "code": 200000,   "message": "成功",   "data": {     "id": 1,     "userName": "tiange",     "password": "123456",     "phone": "18257160375",     "gender": 0,     "status": 0,     "createTime": "2024-05-17 20:24:40"   } }

code是接口返回编码，message是消息提示，data是具体返回数据内容。

返回码

返回码定义很重要，我们应该可以参考HTTP请求返回的状态码（下面是常见的HTTP状态码）：

200 - 请求成功 301 - 资源（网页等）被永久转移到其它URL 404 - 请求的资源（网页等）不存在 500 - 内部服务器错误

这样前端开发人员在得到返回值后，根据状态码就可以知道，大概什么错误，再根据message相关的信息描述，可以快速定位。

由于我们业务系统中可能会又大量的code，所以，我们对此做一个改良。

/**  * {@code @description:} 返回码  *  * @author tianwc 公众号：Java后端技术全栈  * 在线刷题 1200+java面试题和1000+篇技术文章：<a href="https://woaijava.cc/">博客地址</a>  * {@code @date:} 2024-07-28 15:10  * {@code @version:} 1.0  */ @Getter public enum ResultCode implements Serializable {     SUCCESS(200000, "成功"),      FAIL(500000, "系统错误，请稍后重试!"),      USER_NOT_EXIST(401000, "用户不存在"),     USER_CANCELLED(401001, "用户已注销"),     USER_ROLE_ERROR(401002, "用户角色不对"),      NOT_FOUND(404000, "接口不存在"),     PARAMETER_ERROR(404001, "参数有误"),     PARAMETER_IS_NULL(404002, "参数为空");      private final int code;     private final String message;      ResultCode(int code, String message) {         this.code = code;         this.message = message;     } }

对此，我们还可以进一步细分，比如402开头的是用户相关的 、403开头又是xxx的，.....

这样后期如果又什么问题，这样就能快速定位到具体模块中。

统一返回

我们可以专门写一个类来对返回数据进行包装。

/**  * {@code @description:} 返回结果马甲  *  * @author tianwc 公众号：Java后端技术全栈  * 在线刷题 1200+java面试题和1000+篇技术文章：<a href="https://woaijava.cc/">博客地址</a>  * {@code @date:} 2024-07-28 15:12  * {@code @version:} 1.0  */ @Data public class Result implements Serializable {     private Integer code;     private String message;     private Object data;      public Result(Integer code, String message, Object data) {         this.code = code;         this.message = message;         this.data = data;     }      public static Result success() {         return new Result(ResultCode.SUCCESS.getCode(), ResultCode.SUCCESS.getMessage(), null);     }      public static Result success(Object data) {         return new Result(ResultCode.SUCCESS.getCode(), ResultCode.SUCCESS.getMessage(), data);     }      public static Result fail(ResultCode resultCode) {         return new Result(resultCode.getCode(), resultCode.getMessage(), null);     }     public static Result fail(int code, String message) {         return new Result(code, message, null);     } }

我们定义了常用的四种格式。

具体使用如下：

我们在Service层和实现层：

public interface UserInfoService extends IService<UserInfo> {     Result findByCondition(UserInfoReqDto userInfoReqDto); }
@Service public class UserInfoServiceImpl extends ServiceImpl<UserInfoMapper, UserInfo> implements UserInfoService {      @Override     public Result findByCondition(UserInfoReqDto userInfoReqDto) {         Wrapper<UserInfo> wrapper = Wrappers.<UserInfo>lambdaQuery()                 .eq(UserInfo::getUserName, userInfoReqDto.getUserName())                 .eq(UserInfo::getPassword, userInfoReqDto.getPassword());                  return Result.success(this.baseMapper.selectList(wrapper));     } }

在controller层：我们会在controller层处理业务请求，并返回给前端 。

@RestController @RequestMapping("/user/info") public class UserInfoController {      @Resource     private UserInfoService userInfoService;       @GetMapping("/condition")     public Result findByCondition(UserInfoReqDto userInfoReqDto) {         return userInfoService.findByCondition(userInfoReqDto);     } }

执行：

GET http://localhost:8089/user/info/condition?userName=tiange&password=123456

返回：

{   "code": 200000,   "message": "成功",   "data": [     {       "id": 1,       "userName": "tiange",       "password": "123456",       "phone": "18257160375",       "gender": 0,       "status": 0,       "createTime": "2024-05-17T20:24:40.000+00:00"     }   ] }

前端根据我们但会的code判断是否需要取data字段。

统一异常处理

统一异常处理我们分业务异常、系统异常以及参数异常：

业务异常

我们自定义一个业务异常：BusinessException

/**  * @author tianwc  公众号：java后端技术全栈、面试专栏  * @version 1.0.0  * @date 2024-07-28 15:12  * 在线刷题 1200+java面试题和1000+篇技术文章：<a href="https://woaijava.cc/">博客地址</a>  * <p>  * 自定义业务异常  */ @Getter public class BusinessException extends RuntimeException {     /**      * http状态码      */     private Integer code;      private Object object;      public BusinessException(String message, Integer code, Object object) {         super(message);         this.code = code;         this.object = object;     }     public BusinessException(String message, Integer code) {         super(message);         this.code = code;     }      public BusinessException(ResultCode resultCode) {         super(resultCode.getMessage());         this.code = resultCode.getCode();         this.object = resultCode.getMessage();     }      public BusinessException(ResultCode resultCode, String message) {         this.code = resultCode.getCode();         this.object = message;     }      public BusinessException(String message) {         super(message);     }  }

异常处理：GlobalAdvice

@RestControllerAdvice @Slf4j public class GlobalAdvice {      @ExceptionHandler(Exception.class)     public Result doException(Exception e) {          log.error("统一异常处理机制，触发异常 msg ", e);         String message = null;         int errorCode = ResultCode.FAIL.getCode();         //自定义异常         if (e instanceof BusinessException) {             BusinessException exception = (BusinessException) e;             message = exception.getMessage();             errorCode = exception.getCode();         } else if (e instanceof HttpRequestMethodNotSupportedException) {             message = "不支持GET/POST方法";         } else if (e instanceof NoHandlerFoundException) {             message = "请求接口不存在";         } else if (e instanceof MissingServletRequestParameterException) {             errorCode = ResultCode.PARAMETER_IS_NULL.getCode();             message = String.format("缺少必要参数[%s]", ((MissingServletRequestParameterException) e).getParameterName());         } else if (e instanceof MethodArgumentNotValidException) {             BindingResult result = ((MethodArgumentNotValidException) e).getBindingResult();             FieldError error = result.getFieldError();             errorCode = ResultCode.PARAMETER_IS_NULL.getCode();             message = error == null ? ResultCode.PARAMETER_ERROR.getMessage() : error.getDefaultMessage();         } else if (e instanceof BindException) {             errorCode = ResultCode.PARAMETER_IS_NULL.getCode();             message = ((BindException) e).getFieldError().getDefaultMessage();         } else if (e instanceof IllegalArgumentException) {             errorCode = ResultCode.PARAMETER_IS_NULL.getCode();             message = e.getMessage();         }         return Result.fail(errorCode, message);     } }

使用：

@Service public class UserInfoServiceImpl extends ServiceImpl<UserInfoMapper, UserInfo> implements UserInfoService {      @Override     public Result findByCondition(UserInfoReqDto userInfoReqDto) {         if("admin".equals(userInfoReqDto.getUserName())){              //对于某些业务问题抛出自定义异常              throw new BusinessException(ResultCode.USER_ROLE_ERROR);         }         Wrapper<UserInfo> wrapper = Wrappers.<UserInfo>lambdaQuery()                 .eq(UserInfo::getUserName, userInfoReqDto.getUserName())                 .eq(UserInfo::getPassword, userInfoReqDto.getPassword());         return Result.success(this.baseMapper.selectList(wrapper));     } }
系统异常

假设系统异常：

@Service public class UserInfoServiceImpl extends ServiceImpl<UserInfoMapper, UserInfo> implements UserInfoService {      @Override     public Result findByCondition(UserInfoReqDto userInfoReqDto) {         if("123456".equals(userInfoReqDto.getPassword())){             throw new RuntimeException("你的系统异常了");         }         Wrapper<UserInfo> wrapper = Wrappers.<UserInfo>lambdaQuery()                 .eq(UserInfo::getUserName, userInfoReqDto.getUserName())                 .eq(UserInfo::getPassword, userInfoReqDto.getPassword());         return Result.success(this.baseMapper.selectList(wrapper));     } }

执行：

GET http://localhost:8089/user/info/condition?userName=tian&password=123456

返回结果：

{   "code": 500000,   "message": "系统异常",   "data": null }
参数校验

添加pom依赖

<!--参数验证--> <dependency>     <groupId>org.springframework.boot</groupId>     <artifactId>spring-boot-starter-validation</artifactId> </dependency>

请求参数：

@Data @AllArgsConstructor @NoArgsConstructor public class UserInfoReqDto {     @NotBlank(message = "姓名不能为空")     private String userName;      @NotBlank(message = "密码不能为空")     private String password; }

其他相关注解：

注解作用
@NotNull判断包装类是否为null
@NotBlank判断字符串是否为null或者是空串(去掉首尾空格)
@NotEmpty判断集合是否为空
@Length判断字符的长度(最大或者最小)
@Min判断数值最小值
@Max判断数值最大值
@Email判断邮箱是否合法

controller层添加注解@Validated

@RestController @RequestMapping("/user/info") public class UserInfoController {      @Resource     private UserInfoService userInfoService;       @GetMapping("/condition")     public Result findByCondition(@Validated UserInfoReqDto userInfoReqDto) {         return userInfoService.findByCondition(userInfoReqDto);     } }

最后在统一异常处理里处理。

执行：

GET http://localhost:8089/user/info/condition?userName=tian

返回：

{   "code": 404002,   "message": "密码不能为空",   "data": null }

执行：

GET http://localhost:8089/user/info/condition?password=123456

返回：

{   "code": 404002,   "message": "姓名不能为空",   "data": null }

集成mybatis-plus

添加依赖

<!--mybatis-plus 依赖--> <dependency>     <groupId>com.baomidou</groupId>     <artifactId>mybatis-plus-boot-starter</artifactId>     <version>${mybatis-plus.version}</version> </dependency> <!--mysql依赖--> <dependency>     <groupId>mysql</groupId>     <artifactId>mysql-connector-java</artifactId>     <scope>runtime</scope> </dependency>

数据库信息配置：

spring.datasource.driver-class-name=com.mysql.cj.jdbc.Driver spring.datasource.jdbc-url=jdbc:mysql://localhost:3306/user-center?useSSL=false&serverTimezone=UTC&useUnicode=true&characterEncoding=utf-8&allowPublicKeyRetrieval=true spring.datasource.username=root spring.datasource.password=123456

mybatis-plus配置：

@Configuration @MapperScan(basePackages = "com.tian.dao.mapper") public class DataSourceConfig {      @ConfigurationProperties(prefix = "spring.datasource")     @Bean     public DataSource dataSource() {         return DataSourceBuilder.create().build();     }      @Bean     public MybatisPlusInterceptor mybatisPlusInterceptor() {         MybatisPlusInterceptor interceptor = new MybatisPlusInterceptor();         //分页插件         interceptor.addInnerInterceptor(new PaginationInnerInterceptor());         //注册乐观锁插件         interceptor.addInnerInterceptor(new OptimisticLockerInnerInterceptor());         return interceptor;     }      @Bean     public SqlSessionFactory sqlSessionFactory(DataSource dataSource, MybatisPlusInterceptor interceptor) throws Exception {         MybatisSqlSessionFactoryBean ssfb = new MybatisSqlSessionFactoryBean();         ssfb.setDataSource(dataSource);         ssfb.setPlugins(interceptor);         //到哪里找xml文件         ssfb.setMapperLocations(new PathMatchingResourcePatternResolver()                 .getResources("classpath*:mapper/*.xml"));         return ssfb.getObject();     } }

实体类：

@TableName(value = "user_info") @Data public class UserInfo {     /**      * 主键ID      */     @TableId(value = "id")     private Long id;      /**      * 姓名      */     @TableField(value = "user_name")     private String userName;      /**      * 密码      */     @TableField(value = "password")     private String password;     /**      * 手机号      */     @TableField(value = "phone")     private String phone;     /**      * 性别，0：女，1：男      */     @TableField(value = "gender")     private Integer gender;     /**      * 状态，0：正常，1：已注销      */     @TableField(value = "status")     private Integer status;     /**      * 注册时间      */     @TableField(value = "create_time")     private Date createTime;      @TableField(exist = false)     private static final long serialVersionUID = 1L; }

mapper：

public interface  UserInfoMapper extends BaseMapper<UserInfo> { }

service部分代码参照前面的代码来。

执行

GET http://localhost:8089/user/info/condition?userName=tiange&password=123456

返回

{   "code": 200000,   "message": "成功",   "data": [     {       "id": 1,       "userName": "tiange",       "password": "123456",       "phone": "18257160375",       "gender": 0,       "status": 0,       "createTime": "2024-05-17T20:24:40.000+00:00"     }   ] }

到这里我们的项目就成功把mybatis-plus集成进来。

swagger

作为前后端分离项目，在团队开发中，一个好的 API 文档不但可以减少大量的沟通成本，还可以帮助一位新人快速上手业务。传统的做法是由开发人员创建一份 RESTful API文档来记录所有的接口细节，并在程序员之间代代相传。这种做法存在以下几个问题：

1）API 接口众多，细节复杂，需要考虑不同的HTTP请求类型、HTTP头部信息、HTTP请求内容等，想要高质量的完成这份文档需要耗费大量的精力；

2）难以维护。随着需求的变更和项目的优化、推进，接口的细节在不断地演变，接口描述文档也需要同步修订，可是文档和代码处于两个不同的媒介，除非有严格的管理机制，否则很容易出现文档、接口不一致的情况；

Swagger2 的出现就是为了从根本上解决上述问题。它作为一个规范和完整的框架，可以用于生成、描述、调用和可视化 RESTful 风格的 Web 服务：

  • 接口文档在线自动生成，文档随接口变动实时更新，节省维护成本；

  • 支持在线接口测试，不依赖第三方工具；

Swagger2 是一个规范和完整的框架，用于生成、描述、调用和可视化Restful风格的web服务，现在我们使用spring boot 整合它。作用：

  • 接口的文档在线自动生成；

  • 功能测试；

常用注解

注解描述
@Api将类标记为 Swagger 资源。
@ApiImplicitParam表示 API 操作中的单个参数。
@ApiImplicitParams允许多个 ApiImplicitParam 对象列表的包装器。
@ApiModel提供有关 Swagger 模型的其他信息。
@ApiModelProperty添加和操作模型属性的数据。
@ApiOperation描述针对特定路径的操作或通常是 HTTP 方法。
@ApiParam为操作参数添加额外的元数据。
@ApiResponse描述操作的可能响应。
@ApiResponses允许多个 ApiResponse 对象列表的包装器。
@Authorization声明要在资源或操作上使用的授权方案。
@AuthorizationScope描述 OAuth2 授权范围。
swagger配置
@Configuration   //加入到容器里面 @EnableSwagger2 //开启Swagger public class SwaggerConfig {      @Bean     public Docket docket() {         return new Docket(DocumentationType.SWAGGER_2)                 .apiInfo(apiInfo())                 .select()                 .apis(RequestHandlerSelectors.basePackage("com.tian.controller"))                 .build();     }     private ApiInfo apiInfo(){         Contact contact = new Contact("web项目demo", "https://www.woaijava.cc/", "251965157@qq.com");         return new ApiInfo(                 "web项目demo的API文档",                 "练手所用",                 "v1.0",                 "https://www.woaijava.cc/",                 contact,                 "Apache 2.0",                 "http://www.apache.org/licenses/LICENSE-2.0",                 new ArrayList());     }  }

我们就可以在对应业务代码中标注上swagger：

@RestController @RequestMapping("/user/info") @Api(value = "用户信息接口",tags = "用户信息") public class UserInfoController {      @Resource     private UserInfoService userInfoService;      @GetMapping("/{id}")     @ApiOperation(value = "根据id查询用户信息", notes = "根据id查询用户信息"             ,produces = "application/json",consumes = "application/json")     @ApiImplicitParams({             @ApiImplicitParam(name="id",value="用户id",required = true,dataType = "Integer")     })     public Result findById(@PathVariable("id") Integer id) {         return Result.success(userInfoService.getById(id));     }      @GetMapping("/condition")     @ApiOperation(value = "根据条件查询用户信息")     public Result findByCondition(@Validated UserInfoReqDto userInfoReqDto) {         return userInfoService.findByCondition(userInfoReqDto);     } }
@Data @AllArgsConstructor @NoArgsConstructor @ApiModel(value="用户信息查询条件") public class UserInfoReqDto {     @NotBlank(message = "姓名不能为空")     @ApiModelProperty(value="姓名")     private String userName;      @NotBlank(message = "密码不能为空")     @ApiModelProperty(value="密码")     private String password; }
效果

启动项目，访问：

http://localhost:8089/swagger-ui.html

460cc1a6aeb1268ecc68ea8f7515e25f.png


4e12687736a041ab678797bbe6459fcd.png


91f9b0baff32d98fac446d562459b6a3.png


也到这里，我们就基本形成了一个完整的demo级后端项目。

代码已上传到知识星球：

8913ac8e8c550b2e232fc5f26d127890.png

e4dd00849b46eb47b48f1f9554c0430d.png

其他推荐

2024年最新面试总结，请查收！

充电桩项目如何部署？

应届生不会写简历？手把手教你怎么写简历

背八股文，不妨尝试这招！

    相关阅读
    1. 如何查看和设置我的Android N设备的权限？
    2. 如何在安卓手机上自定义应用图标？
    3. 如何在安卓微信中同时听语音和查看图片？
    4. 华为哪些设备将支持升级至安卓7.0？
    5. 微信安卓软件中Q10功能有哪些独特之处？
    6. 安卓用户如何挑选最佳视频播放器应用？
    7. 安卓系统中用户文件目录的确切位置是什么？
    8. 小米4用户如何安全升级到安卓8.0系统？
    9. 如何成功将魅蓝5升级至安卓原生7.0版本？
    10. 16GB存储的安卓手机是否能满足日常需求？

    广告一刻

    为您即时展示最新活动产品广告消息，让您随时掌握产品活动新动态！