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

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

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

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

  本文内容：

  

  统一返回参数形式

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

1. {
2.   "code": 200000,
3.   "message": "成功",
4.   "data": {
5.     "id": 1,
6.     "userName": "tiange",
7.     "password": "123456",
8.     "phone": "18257160375",
9.     "gender": 0,
10.     "status": 0,
11.     "createTime": "2024-05-17 20:24:40"
12.   }
13. }

复制代码

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

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

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

复制代码

如许前端开辟人员在得到返回值后，根据状态码就可以知道，大概什么错误，再根据message相关的信息形貌，可以快速定位。
  由于我们业务体系中可能会又大量的code，以是，我们对此做一个改良。

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

复制代码

对此，我们还可以进一步细分，好比402开头的是用户相关的 、403开头又是xxx的，.....
  如许后期如果又什么题目，如许就能快速定位到详细模块中。
  统一返回

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

1. /**
2.  * {@code @description:} 返回结果马甲
3.  *
4.  * @author tianwc 公众号：Java后端技术全栈
5.  * 在线刷题 1200+java面试题和1000+篇技术文章：<a href="https://woaijava.cc/">博客地址</a>
6.  * {@code @date:} 2024-07-28 15:12
7.  * {@code @version:} 1.0
8.  */
9. @Data
10. public class Result implements Serializable {
11.     private Integer code;
12.     private String message;
13.     private Object data;
15.     public Result(Integer code, String message, Object data) {
16.         this.code = code;
17.         this.message = message;
18.         this.data = data;
19.     }
21.     public static Result success() {
22.         return new Result(ResultCode.SUCCESS.getCode(), ResultCode.SUCCESS.getMessage(), null);
23.     }
25.     public static Result success(Object data) {
26.         return new Result(ResultCode.SUCCESS.getCode(), ResultCode.SUCCESS.getMessage(), data);
27.     }
29.     public static Result fail(ResultCode resultCode) {
30.         return new Result(resultCode.getCode(), resultCode.getMessage(), null);
31.     }
32.     public static Result fail(int code, String message) {
33.         return new Result(code, message, null);
34.     }
35. }

复制代码

我们界说了常用的四种格式。
  详细使用如下：
  我们在Service层和实现层：

1. public interface UserInfoService extends IService<UserInfo> {
2.     Result findByCondition(UserInfoReqDto userInfoReqDto);
3. }

复制代码

1. @Service
2. public class UserInfoServiceImpl extends ServiceImpl<UserInfoMapper, UserInfo> implements UserInfoService {
4.     @Override
5.     public Result findByCondition(UserInfoReqDto userInfoReqDto) {
6.         Wrapper<UserInfo> wrapper = Wrappers.<UserInfo>lambdaQuery()
7.                 .eq(UserInfo::getUserName, userInfoReqDto.getUserName())
8.                 .eq(UserInfo::getPassword, userInfoReqDto.getPassword());
9.         
10.         return Result.success(this.baseMapper.selectList(wrapper));
11.     }
12. }

复制代码

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

1. @RestController
2. @RequestMapping("/user/info")
3. public class UserInfoController {
5.     @Resource
6.     private UserInfoService userInfoService; 
8.     @GetMapping("/condition")
9.     public Result findByCondition(UserInfoReqDto userInfoReqDto) {
10.         return userInfoService.findByCondition(userInfoReqDto);
11.     }
12. }

复制代码

执行：
   

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

复制代码

   返回：

1. {
2.   "code": 200000,
3.   "message": "成功",
4.   "data": [
5.     {
6.       "id": 1,
7.       "userName": "tiange",
8.       "password": "123456",
9.       "phone": "18257160375",
10.       "gender": 0,
11.       "status": 0,
12.       "createTime": "2024-05-17T20:24:40.000+00:00"
13.     }
14.   ]
15. }

复制代码

前端根据我们但会的code判定是否需要取data字段。
  统一非常处理

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

  我们自界说一个业务非常：BusinessException

1. /**
2.  * @author tianwc  公众号：java后端技术全栈、面试专栏
3.  * @version 1.0.0
4.  * @date 2024-07-28 15:12
5.  * 在线刷题 1200+java面试题和1000+篇技术文章：<a href="https://woaijava.cc/">博客地址</a>
6.  * <p>
7.  * 自定义业务异常
8.  */
9. @Getter
10. public class BusinessException extends RuntimeException {
11.     /**
12.      * http状态码
13.      */
14.     private Integer code;
16.     private Object object;
18.     public BusinessException(String message, Integer code, Object object) {
19.         super(message);
20.         this.code = code;
21.         this.object = object;
22.     }
23.     public BusinessException(String message, Integer code) {
24.         super(message);
25.         this.code = code;
26.     }
28.     public BusinessException(ResultCode resultCode) {
29.         super(resultCode.getMessage());
30.         this.code = resultCode.getCode();
31.         this.object = resultCode.getMessage();
32.     }
34.     public BusinessException(ResultCode resultCode, String message) {
35.         this.code = resultCode.getCode();
36.         this.object = message;
37.     }
39.     public BusinessException(String message) {
40.         super(message);
41.     }
43. }

复制代码

非常处理：GlobalAdvice

1. @RestControllerAdvice
2. @Slf4j
3. public class GlobalAdvice {
5.     @ExceptionHandler(Exception.class)
6.     public Result doException(Exception e) {
8.         log.error("统一异常处理机制，触发异常 msg ", e);
9.         String message = null;
10.         int errorCode = ResultCode.FAIL.getCode();
11.         //自定义异常
12.         if (e instanceof BusinessException) {
13.             BusinessException exception = (BusinessException) e;
14.             message = exception.getMessage();
15.             errorCode = exception.getCode();
16.         } else if (e instanceof HttpRequestMethodNotSupportedException) {
17.             message = "不支持GET/POST方法";
18.         } else if (e instanceof NoHandlerFoundException) {
19.             message = "请求接口不存在";
20.         } else if (e instanceof MissingServletRequestParameterException) {
21.             errorCode = ResultCode.PARAMETER_IS_NULL.getCode();
22.             message = String.format("缺少必要参数[%s]", ((MissingServletRequestParameterException) e).getParameterName());
23.         } else if (e instanceof MethodArgumentNotValidException) {
24.             BindingResult result = ((MethodArgumentNotValidException) e).getBindingResult();
25.             FieldError error = result.getFieldError();
26.             errorCode = ResultCode.PARAMETER_IS_NULL.getCode();
27.             message = error == null ? ResultCode.PARAMETER_ERROR.getMessage() : error.getDefaultMessage();
28.         } else if (e instanceof BindException) {
29.             errorCode = ResultCode.PARAMETER_IS_NULL.getCode();
30.             message = ((BindException) e).getFieldError().getDefaultMessage();
31.         } else if (e instanceof IllegalArgumentException) {
32.             errorCode = ResultCode.PARAMETER_IS_NULL.getCode();
33.             message = e.getMessage();
34.         }
35.         return Result.fail(errorCode, message);
36.     }
37. }

复制代码

使用：

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

复制代码

体系非常

  假设体系非常：

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

复制代码

执行：

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

复制代码

返回结果：

1. {
2.   "code": 500000,
3.   "message": "系统异常",
4.   "data": null
5. }

复制代码

参数校验

  添加pom依赖

1. <!--参数验证-->
2. <dependency>
3.     <groupId>org.springframework.boot</groupId>
4.     <artifactId>spring-boot-starter-validation</artifactId>
5. </dependency>

复制代码

请求参数：

1. @Data
2. @AllArgsConstructor
3. @NoArgsConstructor
4. public class UserInfoReqDto {
5.     @NotBlank(message = "姓名不能为空")
6.     private String userName;
8.     @NotBlank(message = "密码不能为空")
9.     private String password;
10. }

复制代码

其他相关注解：
  注解作用@NotNull判定包装类是否为null@NotBlank判定字符串是否为null大概是空串(去掉首尾空格)@NotEmpty判定聚集是否为空@Length判定字符的长度(最大大概最小)@Min判定命值最小值@Max判定命值最大值@Email判定邮箱是否正当  controller层添加注解@Validated

1. @RestController
2. @RequestMapping("/user/info")
3. public class UserInfoController {
5.     @Resource
6.     private UserInfoService userInfoService; 
8.     @GetMapping("/condition")
9.     public Result findByCondition(@Validated UserInfoReqDto userInfoReqDto) {
10.         return userInfoService.findByCondition(userInfoReqDto);
11.     }
12. }

复制代码

末了在统一非常处理里处理。
  执行：

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

复制代码

返回：

1. {
2.   "code": 404002,
3.   "message": "密码不能为空",
4.   "data": null
5. }

复制代码

执行：

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

复制代码

返回：

1. {
2.   "code": 404002,
3.   "message": "姓名不能为空",
4.   "data": null
5. }

复制代码

集成mybatis-plus

  添加依赖

1. <!--mybatis-plus 依赖-->
2. <dependency>
3.     <groupId>com.baomidou</groupId>
4.     <artifactId>mybatis-plus-boot-starter</artifactId>
5.     <version>${mybatis-plus.version}</version>
6. </dependency>
7. <!--mysql依赖-->
8. <dependency>
9.     <groupId>mysql</groupId>
10.     <artifactId>mysql-connector-java</artifactId>
11.     <scope>runtime</scope>
12. </dependency>

复制代码

数据库信息设置：

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

复制代码

mybatis-plus设置：

1. @Configuration
2. @MapperScan(basePackages = "com.tian.dao.mapper")
3. public class DataSourceConfig {
5.     @ConfigurationProperties(prefix = "spring.datasource")
6.     @Bean
7.     public DataSource dataSource() {
8.         return DataSourceBuilder.create().build();
9.     }
11.     @Bean
12.     public MybatisPlusInterceptor mybatisPlusInterceptor() {
13.         MybatisPlusInterceptor interceptor = new MybatisPlusInterceptor();
14.         //分页插件
15.         interceptor.addInnerInterceptor(new PaginationInnerInterceptor());
16.         //注册乐观锁插件
17.         interceptor.addInnerInterceptor(new OptimisticLockerInnerInterceptor());
18.         return interceptor;
19.     }
21.     @Bean
22.     public SqlSessionFactory sqlSessionFactory(DataSource dataSource, MybatisPlusInterceptor interceptor) throws Exception {
23.         MybatisSqlSessionFactoryBean ssfb = new MybatisSqlSessionFactoryBean();
24.         ssfb.setDataSource(dataSource);
25.         ssfb.setPlugins(interceptor);
26.         //到哪里找xml文件
27.         ssfb.setMapperLocations(new PathMatchingResourcePatternResolver()
28.                 .getResources("classpath*:mapper/*.xml"));
29.         return ssfb.getObject();
30.     }
31. }

复制代码

实体类：

1. @TableName(value = "user_info")
2. @Data
3. public class UserInfo {
4.     /**
5.      * 主键ID
6.      */
7.     @TableId(value = "id")
8.     private Long id;
10.     /**
11.      * 姓名
12.      */
13.     @TableField(value = "user_name")
14.     private String userName;
16.     /**
17.      * 密码
18.      */
19.     @TableField(value = "password")
20.     private String password;
21.     /**
22.      * 手机号
23.      */
24.     @TableField(value = "phone")
25.     private String phone;
26.     /**
27.      * 性别，0：女，1：男
28.      */
29.     @TableField(value = "gender")
30.     private Integer gender;
31.     /**
32.      * 状态，0：正常，1：已注销
33.      */
34.     @TableField(value = "status")
35.     private Integer status;
36.     /**
37.      * 注册时间
38.      */
39.     @TableField(value = "create_time")
40.     private Date createTime;
42.     @TableField(exist = false)
43.     private static final long serialVersionUID = 1L;
44. }

复制代码

mapper：

1. public interface  UserInfoMapper extends BaseMapper<UserInfo> {
2. }

复制代码

service部门代码参照前面的代码来。
  执行

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

复制代码

返回

1. {
2.   "code": 200000,
3.   "message": "成功",
4.   "data": [
5.     {
6.       "id": 1,
7.       "userName": "tiange",
8.       "password": "123456",
9.       "phone": "18257160375",
10.       "gender": 0,
11.       "status": 0,
12.       "createTime": "2024-05-17T20:24:40.000+00:00"
13.     }
14.   ]
15. }

复制代码

到这里我们的项目就成功把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设置

1. @Configuration   //加入到容器里面
2. @EnableSwagger2 //开启Swagger
3. public class SwaggerConfig {
5.     @Bean
6.     public Docket docket() {
7.         return new Docket(DocumentationType.SWAGGER_2)
8.                 .apiInfo(apiInfo())
9.                 .select()
10.                 .apis(RequestHandlerSelectors.basePackage("com.tian.controller"))
11.                 .build();
12.     }
13.     private ApiInfo apiInfo(){
14.         Contact contact = new Contact("web项目demo", "https://www.woaijava.cc/", "251965157@qq.com");
15.         return new ApiInfo(
16.                 "web项目demo的API文档",
17.                 "练手所用",
18.                 "v1.0",
19.                 "https://www.woaijava.cc/",
20.                 contact,
21.                 "Apache 2.0",
22.                 "http://www.apache.org/licenses/LICENSE-2.0",
23.                 new ArrayList());
24.     }
26. }

复制代码

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

1. @RestController
2. @RequestMapping("/user/info")
3. @Api(value = "用户信息接口",tags = "用户信息")
4. public class UserInfoController {
6.     @Resource
7.     private UserInfoService userInfoService;
9.     @GetMapping("/{id}")
10.     @ApiOperation(value = "根据id查询用户信息", notes = "根据id查询用户信息"
11.             ,produces = "application/json",consumes = "application/json")
12.     @ApiImplicitParams({
13.             @ApiImplicitParam(name="id",value="用户id",required = true,dataType = "Integer")
14.     })
15.     public Result findById(@PathVariable("id") Integer id) {
16.         return Result.success(userInfoService.getById(id));
17.     }
19.     @GetMapping("/condition")
20.     @ApiOperation(value = "根据条件查询用户信息")
21.     public Result findByCondition(@Validated UserInfoReqDto userInfoReqDto) {
22.         return userInfoService.findByCondition(userInfoReqDto);
23.     }
24. }

复制代码

1. @Data
2. @AllArgsConstructor
3. @NoArgsConstructor
4. @ApiModel(value="用户信息查询条件")
5. public class UserInfoReqDto {
6.     @NotBlank(message = "姓名不能为空")
7.     @ApiModelProperty(value="姓名")
8.     private String userName;
10.     @NotBlank(message = "密码不能为空")
11.     @ApiModelProperty(value="密码")
12.     private String password;
13. }

复制代码

结果

  启动项目，访问：
   

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

复制代码

   

     
   

     
   

     
    也到这里，我们就根本形成了一个完整的demo级后端项目。
  代码已上传到知识星球：
  

  

  

其他推荐

  

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

  

充电桩项目如何部署？

  

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

  

背八股文，不妨实行这招！

免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！更多信息从访问主页：qidao123.com:ToB企服之家，中国第一个企服评测及商务社交产业平台。