RESTful+统一响应体+API自动文档的SprinBoot项目

企业开发 2023-04-06 22:45:15 阅读次数: 0

一、项目要求

  • 实验环境：Idea+mysql+JDK+Tomcat+Maven
  • 将上一周个人作业用 RESTful 接口实现；（上周的SpringBoot+Mybatis+CRUD项目）
  • 配置统一响应体；
  • 配置Swagger，生成API自动文档；
  • 对 RESTful 接口用Postman进行测试，并将测试结果截图；

二、RESTful风格

1、前后端分离

随着互联网技术的发展和移动应用的广泛应用，要求前端开发必须与后端开发分离，实施工程化开发模式。Ajax技术使所有服务器端数据都可以通过异步交互获取。只要能从后台取得一个规范定义的RESTful风格接口，前后两端就可以并行完成项目开发任务。网页有网页的处理方式，APP有APP的处理方式，但无论哪种前端，所需的数据基本相同，后端仅需开发一套逻辑对外提供数据即可。

2、RESTful风格

统一的接口是RESTful风格的核心内容。RESTful定义了Web API接口的设计风格，非常适用于前后端分离的应用模式中。RESTful接口约束包含的内容有资源识别、请求动作和响应信息，即通过URL表明要操作的资源，通过请求方法表明要执行的操作，通过返回的状态码表明这次请求的结果。

3、设计规范

  • 协议：统一使用HTTPs协议或者HTTP协议其中一种
  • 域名：应该尽量将API部署在专用域名之下，如 https://xxx.xxx.com；
  • 版本：应该将API的版本号放入URL，如http://www.example.com/app/1.1/foo
  • 路径：只能有名词，不能有动词，而且所用的名词往往与数据库的表名对应，名词应该用复数
  • HTTP动词：GET(SELECT)、POST(INSERT)、PUT(UPDATE)、DELETE(DELETE)
  • 过滤信息：补充字段
  • 状态码：
  • 返回结果：code+msg+data（常用）

三、SpringBoot热部署

修改测试代码时，无需手动重启项目
在这里插入图片描述
在这里插入图片描述

四、统一格式的响应体

在前后端分离架构下，后端设计成 RESTful API的数据接口。接口中有时返回数据，有时又没有，还有的会出错，也就是返回结果不一致，客户端调用时非常不方便。实际开发中，一般设置统一响应体返回值格式，通过修改响应返回的JSON数据，让其带上一些固有的字段，如下所示:

{
    
    
 "code": 600,
 "msg": "success",
 "data": {
    
    
 "id": 1,
 "uname": "cc"
 "password":111
 }
}

五、统一异常处理

请添加图片描述

六、Swagger—API 接口文档自动生成工具

在实际开发中，常用Swagger-API接口文档自动生成工具，帮助项目自动生成和维护接口文档。Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格
的 Web 服务，它具有以下特点：

  • 及时性：接口变更后，Api文档同步自动更新；
  • 规范性：遵守RESTful风格，保证接口的规范性，如接口的地址，请求方式，参
    数及响应格式和错误信息；
  • 一致性：接口信息一致，不会因开发人员拿到的文档版本不一致而导致分歧；
  • 可测性：直接在接口文档上进行测试，可以在线测试Api接口，方便理解业务。

在pom.xml中加入Swagger依赖

<dependency>
 	<groupId>io.springfox</groupId>
 	<artifactId>springfox-swagger2</artifactId>
 	<version>2.9.2</version>
 </dependency>
 <dependency>
 	<groupId>io.springfox</groupId>
 	<artifactId>springfox-swagger-ui</artifactId>
 	<version>2.9.2</version>
 </dependency>


@Api注解：标记当前Controller的功能
@ApiOperation注解：用来标记一个方法的作用
@ApiImplicitParam注解：用来描述一个参数

在这里插入图片描述

七、项目完整代码

pom.xml

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.7.5</version>
        <relativePath/> <!-- lookup parent from repository -->
    </parent>
    <groupId>com.example</groupId>
    <artifactId>week11_20201000000</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <name>week11_20201000000</name>
    <description>week11_20201000000</description>
    <properties>
        <java.version>1.8</java.version>
    </properties>
    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <dependency>
            <groupId>org.mybatis.spring.boot</groupId>
            <artifactId>mybatis-spring-boot-starter</artifactId>
            <version>2.2.2</version>
        </dependency>

        <dependency>
            <groupId>com.mysql</groupId>
            <artifactId>mysql-connector-j</artifactId>
            <scope>runtime</scope>
        </dependency>
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <optional>true</optional>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>
    </dependencies>

    <build>
        <resources>
            <resource>
                <directory>src/main/java</directory>
                <includes>
                    <include>**/*.xml</include>
                </includes>
            </resource>
            <resource>
                <directory>src/main/resources</directory>
                <includes>
                    <include>**.*</include>
                </includes>
            </resource>
        </resources>

        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
                <configuration>
                    <excludes>
                        <exclude>
                            <groupId>org.projectlombok</groupId>
                            <artifactId>lombok</artifactId>
                        </exclude>
                    </excludes>
                </configuration>
            </plugin>
        </plugins>
    </build>

</project>

application.yml

spring:
  datasource:
    driver-class-name: com.mysql.cj.jdbc.Driver
    url: jdbc:mysql://localhost:3306/myschool?serverTimezone=Hongkong?characterEncoding=utf8&serverTimezone=GMT%2B8
    username: root
    password: 密码
  mvc:
    pathmatch:
      matching-strategy: ant_path_matcher

mybatis:
  mapper-locations: classpath:com/exmaple/mapper/*.xml    #指定sql配置文件的位置
  type-aliases-package: com.example.pojo      #指定实体类所在的包名
  configuration:
    log-impl: org.apache.ibatis.logging.stdout.StdOutImpl   #输出SQL命令

Student.java

package com.example.pojo;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;

@Data
@NoArgsConstructor //自动生成无参构造函数
@AllArgsConstructor
@ApiModel(description = "学生字段")
public class Student {
    
    
    @ApiModelProperty(value = "学生id",name = "id",example = "20201001111")
    private Long id;

    @ApiModelProperty(value = "学生名",name = "sname",example = "张三")
    private String sname;

    @ApiModelProperty(value = "专业",name = "dept",example = "软件工程")
    private String dept;

    @ApiModelProperty(value = "年龄",name = "age",example = "20")
    private int age;
}

StudentMapper.java

package com.example.mapper;

import com.example.pojo.Student;

import java.util.List;
import java.util.Map;

public interface StudentMapper {
    
    
    //1
    public List<Student> getAllStudentMap();

    //2
    public Student getStudentById(Long id);

    //3更新用户信息
    public int updateStudentByDynam(Map<Object,Object> mp);

    //4
    public int addStudent(Student student);

    //5
    public int deleteStudentById(Long id);

}

StudentMapper.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE mapper
PUBLIC "-//mybatis.org//DTD Mapper 3.0//EN"
"http://mybatis.org/dtd/mybatis-3-mapper.dtd">

<mapper namespace="com.example.mapper.StudentMapper">

	<!--1	-->
	<select id="getAllStudentMap" resultType="Student">
		SELECT * FROM student
	</select>

	<!--2	-->
	<select id="getStudentById" resultType="Student" parameterType="Long">
		SELECT * FROM student WHERE id=#{
    
    0}
	</select>

	<!--3	-->
	<update id="updateStudentByDynam"  parameterType="Map">
		update student
		<set>
			<if test="sname!=null">
				sname=#{
    
    sname},
			</if>
			<if test="dept!=null">
				dept=#{
    
    dept},
			</if>
			<if test="age!=null">
				age=#{
    
    age},
			</if>
			id=#{
    
    id}
		</set>
		where id=#{
    
    id}
	</update>

	<!--4	-->
	<insert id="addStudent" parameterType="Student">
		INSERT INTO student SET sname=#{
    
    sname},dept=#{
    
    dept},age=#{
    
    age}
	</insert>

	<!--5	-->
	<delete id="deleteStudentById" parameterType="Long">
		DELETE FROM student
		where id=#{
    
    id}
	</delete>


</mapper>

StudentService.java

package com.example.service;

import com.example.pojo.Student;

import java.io.IOException;
import java.util.List;
import java.util.Map;


public interface StudentService {
    
    

        //1
        public List<Student> getAllStudentMap();

        //2
        public Student getStudentById(Long id);

        //3更新用户信息
        public int updateStudentByDynam(Map<Object,Object> mp);

        //4
        public int addStudent(Student student);

        //5
        public int deleteStudentById(Long id);

}

StudentServiceImpl.java

package com.example.service.impl;


import com.example.mapper.StudentMapper;
import com.example.pojo.Student;
import com.example.service.StudentService;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;

import java.io.IOException;
import java.util.List;
import java.util.Map;

@Service
public class StudentServiceImpl implements StudentService {
    
    

    @Autowired
    private StudentMapper studentMapper;

    //根据id查询
    @Override
    public Student getStudentById(Long id){
    
    
        return studentMapper.getStudentById(id);
    }

    //根据id修改用户信息
    @Override
    public int updateStudentByDynam(Map<Object,Object> mp) {
    
    
        return studentMapper.updateStudentByDynam(mp);
    }

    @Override
    public int deleteStudentById(Long id){
    
    
        return studentMapper.deleteStudentById(id);
    }

    //查询用户
    public List<Student> getAllStudentMap() {
    
    
        return studentMapper.getAllStudentMap();
    }

    public int addStudent(Student student) {
    
    
        return studentMapper.addStudent(student);
    }

}

StudentController.java

package com.example.controller;

import com.example.exception.NotAllowedRegException;
import com.example.pojo.Student;
import com.example.service.StudentService;
import com.example.util.Response;
import com.example.util.ResponseResult;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.apache.ibatis.annotations.Update;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;

import java.io.IOException;
import java.util.List;
import java.util.Map;

@RestController //=@ResponseBody+@Controller
@Api(tags = "学生管理相关接口")
public class StudentController {
    
    
    @Autowired
    private StudentService studentService;

//    查找所有学生信息
    @GetMapping("/student")
    @ApiOperation("查询所有学生信息")
    public ResponseResult<List<Student>> selectstudentList(){
    
    
        List<Student> studentList = studentService.getAllStudentMap();
        return Response.createOkResp(studentList);
    }


    //根据学生id查找对应学生信息
    @GetMapping("/student/{id}")
    @ApiOperation("根据id查询学生信息")
    public ResponseResult<Student> selectStudentById(@PathVariable("id") Long id) {
    
    
        Student student = studentService.getStudentById(id);
        return Response.createOkResp(student);
    }

    //ok
    @PostMapping("/student")
    @ApiOperation("增加学生信息")
    public ResponseResult<Student> addStudent(Student student) {
    
    
        try {
    
    
            studentService.addStudent(student);
            return Response.createOkResp("添加成功");
        } catch (Exception e) {
    
    
            return Response.createFailResp("添加失败");
        }
    }


    @PutMapping("/student")
    @ApiOperation("更新学生信息")
    public ResponseResult<Student> updateStudentByDynam(@RequestBody Map<Object,Object> mp){
    
    
        System.out.println("mp: ");
        System.out.println(mp);
        int row = studentService.updateStudentByDynam(mp);
        System.out.println(row);
        try {
    
    
            studentService.updateStudentByDynam(mp);
            return Response.createOkResp("更新成功");
        } catch (Exception e) {
    
    
            return Response.createFailResp("更新失败");
        }
    }

    //    根据id删除学生记录 okk
    @DeleteMapping("/student/{id}")
    @ApiOperation("删除学生信息")
    public ResponseResult<Student> deleteStudentById(@PathVariable("id") Long id){
    
    
        studentService.deleteStudentById(id);
        return Response.createOkResp();

    }

    @PostMapping("/studentException")
    @ApiOperation("异常处理学生信息")
    public ResponseResult addStudentException(Student student) throws NotAllowedRegException {
    
    
        //如果添加的用户名是""，则抛出异常
        if(student.getSname().equals("张三"))
            throw new NotAllowedRegException();

        studentService.addStudent(student);
        return Response.createOkResp();
    }

}

GlobalExceptionHandle.java

package com.example.controller;

import com.example.exception.NotAllowedRegException;
import com.example.util.Response;
import com.example.util.ResponseResult;
import com.example.util.StatusCode;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestControllerAdvice;

/**定义一个全局处理异常类，来统一处理各种异常
 *
 */

//@RestController+@ControllerAdvice=@RestControllerAdvice
@RestControllerAdvice
public class GlobalExceptionHandler {
    
    

    //处理异常的方法1.  并确定接收的是哪种类型的异常
    @ExceptionHandler(Exception.class)
    public ResponseResult exceptionHandler(Exception e)
    {
    
    
        // 捕获到某个指定的异常，比如是 NotAllowedRegException 类型
        if(e instanceof  NotAllowedRegException )
           {
    
    
              //处理结束后 还是要返回统一相应结果类
              return Response.createFailResp(StatusCode.NOT_ALLOWRD_REG.code,"异常:当前用户不允许注册");
           }
        else
            {
    
    
                  //处理其它类型的异常 可以进入到不同的分支
                return Response.createFailResp();
            }
    }

    /*
    @ExceptionHandler(NullPointerException.class)
    public ResponseResult exceptionHandler(NullPointerException e) {

    }
    */
}

SwaggerConfig.java

package com.example.config;


import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

/**
 *  Swagger配置类
 */
@Configuration
public class SwaggerConfig {
    
    
    public static final String SWAGGER_SCAN_BASE_PACKAGE = "com.example";

    public static final String VERSION = "1.0.0";
    @Bean
    public Docket createRestApi() {
    
    
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage(SWAGGER_SCAN_BASE_PACKAGE))
                .paths(PathSelectors.any()) // 可以根据url路径设置哪些请求加入文档，忽略哪些请求
                .build();
    }

    private ApiInfo apiInfo() {
    
    
        return new ApiInfoBuilder()
                .title("我的第一个项目")   //设置文档的标题
                .description("*** API 接口文档")   // 设置文档的描述
                .version(VERSION)   // 设置文档的版本
                .contact(new Contact("****", "", "***@qq.com"))
                .termsOfServiceUrl("http://***.***.***")   // 配置服务网站，
                .build();
    }

}

NotAllowedRegException.java

package com.example.exception;

import lombok.Data;
import lombok.NoArgsConstructor;

/**
 *自定义一个异常类：不能注册
 */

@Data
@NoArgsConstructor
public class NotAllowedRegException extends  Exception {
    
    

    private int code;

    private String message;

    public NotAllowedRegException(String message)
    {
    
    
        super(message);
    }
}

Response.java

package com.example.util;

/**
 * 定义不同情景下，各种响应体返回的具体值
 *
 */
public class Response {
    
    

    private static String SUCCESS="success";

    private static String FAIL="fail";

    //创建不同场景下的返回结果对象

    //1.成功执行，没有要返回的数据
    public static <T> ResponseResult<T> createOkResp()
    {
    
    
           return new ResponseResult<T>(StatusCode.SUCCESS.code,SUCCESS,null);
    }

    //2.成功执行，需要返回数据
    public static <T> ResponseResult<T> createOkResp(T data)
    {
    
    
        return new ResponseResult<T>(StatusCode.SUCCESS.code,SUCCESS,data);
    }

    //3.成功执行，需要返回消息和数据
    public static <T> ResponseResult<T> createOkResp(String msg, T data)
    {
    
    
        return new ResponseResult<T>(StatusCode.SUCCESS.code,msg,data);
    }

    //4.成功执行，需要消息参数，无数据
    public static <T> ResponseResult<T> createOkResp(String msg)
    {
    
    
        return new ResponseResult<T>(StatusCode.SUCCESS.code,msg,null);
    }

    //1.失败执行
    public static <T> ResponseResult<T> createFailResp()
    {
    
    
        return new ResponseResult<T>(StatusCode.SERVER_ERROR.code,FAIL,null);
    }

    //2.失败执行
    public static <T> ResponseResult<T> createFailResp(String msg)
    {
    
    
        return new ResponseResult<T>(500,msg,null);
    }

    //3.其它失败执行
    public static <T> ResponseResult<T> createFailResp(int code, String msg)
    {
    
    
        return new ResponseResult<T>(code,msg,null);
    }

    //4.其他执行
    public static <T> ResponseResult<T> createResp(int code, String msg, T data)
    {
    
    
        return new ResponseResult<T>(code,msg,data);
    }

}

ResponseResult.java

package com.example.util;

import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;

/**
 * 定义响应结果的统一格式，这里定义响应结果由三个要素构成
 *
 */
@Data
@NoArgsConstructor
@AllArgsConstructor
public class ResponseResult<T> {
    
    
    //1.状态码
    private int code;
    //2.消息
    private String msg;
    //3.返回数据
    private  T  data;

}

StatusCode.java

package com.example.util;

/**
 *封装各种状态码
 */
public enum StatusCode {
    
    

    //定义枚举项,并调用构造函数
    //http定义好的状态码
     SUCCESS(200),
     SERVER_ERROR(500),
     URL_NOT_FOUND(404),

    //自定义的状态码
    NOT_ALLOWRD_REG(1001);

    //定义成员变量
    public int code;
    //构造方法
    private StatusCode(int code)
    {
    
    
        this.code=code;
    }

}

Week1120201000000Application.java

package com.example;

import org.mybatis.spring.annotation.MapperScan;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@EnableSwagger2
@SpringBootApplication
@MapperScan(basePackages ="com.example.mapper")
public class Week1120201000000Application {
    
    

    public static void main(String[] args) {
    
    
        SpringApplication.run(Week1120201000000Application.class, args);
    }

}

Week1120201000000ApplicationTests.java

package com.example.week11_20201000000;

import org.junit.jupiter.api.Test;
import org.springframework.boot.test.context.SpringBootTest;

@SpringBootTest
class Week1120201000000ApplicationTests {
    
    

    @Test
    void contextLoads() {
    
    
    }

}

八、运行测试

1、查询所有学生

GET
http://localhost:8080/student
在这里插入图片描述
在这里插入图片描述

在这里插入图片描述

2、根据id查询学生信息

GET
http://localhost:8080/student/20201001111
请添加图片描述
请添加图片描述

3、增加学生信息

POST
http://localhost:8080/student
请添加图片描述
请添加图片描述
请添加图片描述请添加图片描述

4、更新学生信息

PUT
http://localhost:8080/student
请添加图片描述

请添加图片描述
请添加图片描述
请添加图片描述

5、删除学生信息

DELETE
http://localhost:8080/student/20201005590
请添加图片描述
请添加图片描述
请添加图片描述

6、异常处理学生信息（如果添加的用户名是"张三"，则抛出异常）

POST
http://localhost:8080/studentException
请添加图片描述

7、启动项目，访问API在线文档页面

访问：http://localhost:8080/swagger-ui.html，即可看到接口文档信息

请添加图片描述
请添加图片描述

猜你喜欢

转载自blog.csdn.net/weixin_51293984/article/details/127897359
今日推荐
美国拟限制 AI 大模型出口中国和俄罗斯
苹果将与 OpenAI 达成协议，将 ChatGPT 应用于 iPhone
openKylin 社区生态委员会第六次会议圆满召开
阿里云正式发布通义千问 2.5
Python 3.13 发布首个 Beta：实验性自由线程模式和 JIT、改进交互式解释器
Stack Overflow 拿我的代码去训练 AI 大模型，还封了我的账号
Pop!_OS 的 COSMIC 桌面完成 App Store 上架工作
报告：Django 仍然是 74% 开发者的首选
《2024 年一季度互联网投融资运行情况》研究报告
15 年前上了“FFmpeg 耻辱柱”，今天他还得谢谢咱——腾讯QQPlayer一雪前耻？
TIOBE 5 月榜单：Fortran “复活”进入 Top 10
GCC 14.1 发布
周排行
NEFU 117 素数个数的位数
Closest Common Ancestors (Lca,tarjan)
ELK部署
【转载】Hive笔记整理（三）
SQL语句（一）基本表的定义
关于Java web开发中的MySQL的事务语句
MFC创建自定义窗体
如何用一句话激怒程序员？
《逆袭大学》文摘——9.4 基础和应用的平衡中找到大学的节奏
【spring源码分析】@Value注解原理
每日归档
更多
2024-05-11(38)
2024-05-10(38)
2024-05-09(35)
2024-05-08(42)
2024-05-07(14)
2024-05-06(40)
2024-05-05(0)
2024-05-04(7)
2024-05-03(19)
2024-05-02(0)

代码天地 © 2018 codetd.com

境外服务器   最新电视剧2022