Spring Boot(三):搭建一个简单的RESTful接口项

作者: 爱宝宝n | 来源:发表于2019-04-23 17:42 被阅读12次

前言

用spingboot框架进行项目开发也有两年的时间了，之前都是一直在学习和积累经验；
最近突然想整理下关于springboot的一些之前学习到的知识和一些自己的见解；
之前在闲暇之余的时候已经写过两篇：
Spring Boot(一)：入门篇
 Spring Boot(二)：简单的初始配置
现在想和大家分享下如何构建一个简单的restful接口项目，希望对新手有所帮助。

一、开发准备

1.1数据库和表

首先，我们需要在自己的MySql数据库中中创建一个数据库和一张表
数据库的名称为 springboot，表名称为 user
脚本如下:

CREATE DATABASE `springbootDemo`;

USE `springbootDemo`;

DROP TABLE IF EXISTS `user`;

CREATE TABLE `user` (
  `user_id` int(11) NOT NULL AUTO_INCREMENT COMMENT 'id',
  `ni_name` varchar(10) DEFAULT NULL COMMENT '昵称',
  `sex` varchar(2) DEFAULT NULL COMMENT '性别',
  PRIMARY KEY (`user_id`)
) ENGINE=InnoDB AUTO_INCREMENT=12 DEFAULT CHARSET=utf8;

建议：
在resources下新建.sql文件来存放sql，
如下图：

sql.png

优点1:数据库文件通常较大，sql脚本较小且便于维护管理和迁移，因此通常把sql脚本放在项目文件夹下。
优点2:sql脚本也可以生成数据库文件，还可以清晰的看到表结构并加以修改，因此便于维护。
优点3:即使主机上没有数据库文件的话，也可以使用sql脚本生成。
优点4:两者都可以放在项目文件夹下，只是相比较而言，把sql脚本放在项目下是最合适和最好的
优点5:在.sql文件中写sql有联想功能，更加方便写sql;
优点6：可在项目其他加注解引用sql文件，可参考https://www.jb51.net/article/103468.htm

1.2 maven相关依赖

因为我们使用Maven创建的，所以需要添加SpringBoot的相关架包。
这里Maven的配置如下:
springBoot最核心的jar
spring-boot-starter ：核心模块，包括自动配置支持、日志和YAML；
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 http://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.1.4.RELEASE</version>
        <relativePath/> <!-- lookup parent from repository -->
    </parent>
    <groupId>com.example</groupId>
    <artifactId>demo</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <name>demo</name>
    <description>Demo project for Spring Boot</description>

    <properties>
        <java.version>1.8</java.version>
        <mybatis-spring-boot>1.2.0</mybatis-spring-boot>
        <swagger.version>2.9.2</swagger.version>
    </properties>


    <!-- 添加依赖 -->
    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter</artifactId>
        </dependency>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

        <!-- 热部署 -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-devtools</artifactId>
            <optional>true</optional>
            <scope>true</scope>
        </dependency>
        <!-- Spring Boot Mybatis 依赖 -->
        <dependency>
            <groupId>org.mybatis.spring.boot</groupId>
            <artifactId>mybatis-spring-boot-starter</artifactId>
            <version>${mybatis-spring-boot}</version>
        </dependency>

        <!-- MySQL 连接驱动依赖 -->
        <dependency>
            <groupId>mysql</groupId>
            <artifactId>mysql-connector-java</artifactId>
        </dependency>

        <!-- swagger相关 -->

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>${swagger.version}</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>${swagger.version}</version>
        </dependency>

        <!-- end swagger相关 -->

    </dependencies>

    <!-- 插件配置 -->
    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
                <configuration>
                    <!-- 没有该配置，devtools 热部署不生效 -->
                    <fork>true</fork>
                </configuration>
            </plugin>
        </plugins>
    </build>

</project>

二、项目工程说明

接下来就是正式开始开发项目了；

2.1项目结构图:

工程结构.png

首先确定工程结构，这里我就简单的说明下了。
com.example.demo.controller - Controller 层
com.example.demo.dao - 数据操作层 DAO
com.example.demo.model - 实体类
com.example.demo.service - 业务逻辑层
com.example.demo.config- config配置类
DemoApplication - 应用启动类
application.yml - 应用配置文件，应用启动会自动读取配置
application-test.yml - 测试环境
application-pro.yml - 生产环境
application-dev.yml - 开发环境

2.2 自定义配置文件

一般我们需要一些自定义的配置，例如配置jdbc的连接配置，在这里我们可以用 application.yml 和application-test.yml进行配置。数据源实际的配置以各位的为准。

  spring:
    profiles:
      active: test

application-test.yml配置：
server:
  port: 8080
spring:
  datasource:
    driver-class-name: com.mysql.cj.jdbc.Driver
    username: root
    password: root
    url: jdbc:mysql://localhost:3306/springBootdemo?characterEncoding=utf-8&useSSL=false

三、代码编写

在创建好相关工程目录之后，我们开始来编写相应的代码。

3.1 实体类编写

由于我们这里只是用于测试，只在数据库中创建了一张user表，所以这里我们就只创建一个User实体类，里面的字段对应user表的字段。
示例代码如下:

package com.example.demo.model;

/**
 * @author AxeLai
 * @date 2019-04-22 18:47
 */

public class User {
    /** 编号 */
    private int id;
    /** 姓名 */
    private String name;
    /** 年龄 */
    private String sex;

    public int getId() {
        return id;
    }

    public void setId(int id) {
        this.id = id;
    }

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public String getSex() {
        return sex;
    }

    public void setSex(String sex) {
        this.sex = sex;
    }
}

3.2 Dao层编写

用hibernate和mybatis进行处理数据层一般有两种方式实现与数据库实现CRUD：
第一种是xml的mapper配置。
第二种是使用注解，@Insert、@Select、@Update、@Delete 这些来完成。我使用的是第二种。

package com.example.demo.dao;

import com.example.demo.model.User;
import org.apache.ibatis.annotations.*;

import java.util.List;

@Mapper
public interface UserDao {
    /**
     * 用户数据新增
     */
    @Insert("insert into user(id,name,age) values (#{id},#{name},#{age})")
    void addUser(User user);

    /**
     * 用户数据修改
     */
    @Update("update user set name=#{name},sex=#{sex} where id=#{id}")
    void updateUser(User user);

    /**
     * 用户数据删除
     */
    @Delete("delete from user where id=#{id}")
    void deleteUser(int id);

    /**
     * 根据用户名称查询用户信息
     *
     */
    @Select("SELECT id,name,sex FROM user where name=#{name}")
    User findByName(@Param("name") String name);

    /**
     * 查询所有
     */
    @Select("SELECT id,name,sex FROM user")
    List<User> findAll();
}

说明:

mapper : 在接口上添加了这个注解表示这个接口是基于注解实现的CRUD。
Results: 返回的map结果集，property 表示User类的字段，column 表示对应数据库的字段。
Param:sql条件的字段。
Insert、Select、Update、Delete:对应数据库的增、查、改、删。

3.3 Service 业务逻辑层

代码如下：
接口：

package com.example.demo.service;

import com.example.demo.model.User;

import java.util.List;

public interface UserService {
    /**
     * 新增用户
     * @param user
     * @return
     */
    boolean addUser(User user);

    /**
     * 修改用户
     * @param user
     * @return
     */
    boolean updateUser(User user);


    /**
     * 删除用户
     * @param id
     * @return
     */
    boolean deleteUser(int id);

    /**
     * 根据用户名字查询用户信息
     * @param userName
     */
    User findUserByName(String userName);



    /**
     * 查询所有
     * @return
     */
    List<User> findAll();
}

实现类：

package com.example.demo.service.impl;

import com.example.demo.dao.UserDao;
import com.example.demo.model.User;
import com.example.demo.service.UserService;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;

import java.util.List;

/**
 * @author AxeLai
 * @date 2019-04-22 18:58
 */
@Service
public class UserServiceImpl implements UserService {
    @Autowired
    private UserDao userDao;


    @Override
    public boolean addUser(User user) {
        boolean flag=false;
        try{
            userDao.addUser(user);
            flag=true;
        }catch(Exception e){
            e.printStackTrace();
        }
        return flag;
    }

    @Override
    public boolean updateUser(User user) {
        boolean flag=false;
        try{
            userDao.updateUser(user);
            flag=true;
        }catch(Exception e){
            e.printStackTrace();
        }
        return flag;
    }

    @Override
    public boolean deleteUser(int id) {
        boolean flag=false;
        try{
            userDao.deleteUser(id);
            flag=true;
        }catch(Exception e){
            e.printStackTrace();
        }
        return flag;
    }

    @Override
    public User findUserByName(String userName) {
        return userDao.findByName(userName);
    }


    @Override
    public List<User> findAll() {
        return userDao.findAll();
    }

}

3.4 Controller 控制层

控制层这块和springMVC很像，但是相比而言要简洁不少。
说明:

-RestController：默认类中的方法都会以json的格式返回。
-RequestMapping: 接口路径配置。
-method : 请求格式。
-RequestParam: 请求参数。

具体实现如下:

package com.example.demo.controller;

import com.example.demo.model.User;
import com.example.demo.service.UserService;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;

import java.util.List;

/**
 * @author AxeLai
 * @date 2019-04-18 14:59
 */
@RestController
public class UserController {

    @Autowired
    private UserService userService;

    @RequestMapping(value = "/user", method = RequestMethod.POST)
    @ApiOperation(value = "新增用户")
    public boolean addUser( User user) {
        System.out.println("开始新增...");
        return userService.addUser(user);
    }

    @RequestMapping(value = "/user", method = RequestMethod.PUT)
    @ApiOperation(value = "更新用户信息")
    public boolean updateUser( User user) {
        System.out.println("开始更新...");
        return userService.updateUser(user);
    }

    @RequestMapping(value = "/user", method = RequestMethod.DELETE)
    @ApiOperation(value = "通过用户id删除用户信息")
    public boolean delete(@RequestParam(value = "userId", required = true) int userId) {
        System.out.println("开始删除...");
        return userService.deleteUser(userId);
    }


    @RequestMapping(value = "/user", method = RequestMethod.GET)
    @ApiOperation(value = "通过用户名查询用户信息")
    public User findByUserName(@RequestParam(value = "userName", required = true) String userName) {
        System.out.println("开始查询...");
        return userService.findUserByName(userName);
    }


    @RequestMapping(value = "/userAll", method = RequestMethod.GET)
    @ApiOperation(value = "查询所有用户信息")
    public List<User> findAll() {
        System.out.println("开始查询所有数据...");
        return userService.findAll();
    }

}

3.5 Application 主程序

package com.example.demo;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.boot.builder.SpringApplicationBuilder;
import org.springframework.boot.web.servlet.support.SpringBootServletInitializer;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

//启动swagger
@EnableSwagger2
@SpringBootApplication
public class DemoApplication  extends SpringBootServletInitializer {

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

    //导出是war包时  要加一下配置
    @Override
    protected SpringApplicationBuilder configure(SpringApplicationBuilder application) {
        return application.sources(DemoApplication.class);
    }
}

四、代码测试

代码编写完之后，我们进行接口的测试。
启动主程序Application 之后，一般来说接口测试有三种方法：

4.1、直接打开浏览器访问接口

如：查找所有用户信息则访问： http://localhost:8080/userAll，如果接口有参数则在地址后面用?加上参数名等于参数值，如：http://localhost:8080/user?userName=小东
结果如下图：

接口调试1.png

4.2、使用swagger进行接口测试

4.2.1、swagger调试方法一：使用第三方依赖

1、在pom.xml文件中添加第三方swagger依赖

<dependency> 
    <groupId>com.spring4all</groupId> 
    <artifactId>swagger-spring-boot-starter</artifactId> 
    <version>1.7.0.RELEASE</version> 
</dependency>

2、在Spring Boot项目的启动类上添加@EnableSwagger2注解，就可以直接使用啦。
3、还可以在application-test.yml文件中加入swagger的配置，下面是application-test.yml的配置

# 配置swagger
swagger:
  enabled: true #开启swagger
  title: "swagger"
  description: "swagger"
  version:  "v1.0"
  license:  "swagger"
  license-url: "swagger"
  terms-of-service-url: "swagger"
  contact:
    name: "swagger"
    email: "swagger"
    url: "swagger"
  base-package: "com.example.demo" #扫描的包
  base-path: "/**"  #base-path:/**注意是两个*，如果只写一个会导致requestmapping的/xxx/yyy不会生成文档

4.2.2、swagger调试方法二：使用官方依赖

1、在pom.xml文件中添加swagger相关依赖

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

第一个是API获取的包，第二是官方给出的一个ui界面。这个界面可以自定义，默认是官方的，对于安全问题，以及ui路由设置需要着重思考。
2、swagger的configuration
在目录config下新建SwaggerConfig类，配置如下：

package com.example.demo.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.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * swagger文档
 *
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.SWAGGER_2).groupName("swagger接口文档")
                .apiInfo(new ApiInfoBuilder().title("swagger接口文档")
                        .contact(new Contact("小赖联系邮箱", "", "2473379838@qq.com")).version("1.0").build())
                .select().paths(PathSelectors.any()).build();
    }
}

4.2.3、swagger的常用API

swagger的api有很多，这里我主要介绍两种最长用的，也是本人觉得最实用的两种；
1.api标记
Api 用在类上，说明该类的作用。可以标记一个Controller类做为swagger 文档资源，使用方式：
@Api(value = "UserController",description = "用户端")

api标识.png
2.ApiOperation标记
ApiOperation：用在方法上，说明方法的作用，每一个url资源的定义,使用方式：
@ApiOperation(value = "新增用户")

apiOp.png
更多的swaggerAPI文档可参考https://www.imooc.com/article/71842

4.2.4、swagger进行接口测试

配置完swagger,启动程序，在浏览器输入：localhost:8080/swagger-ui.html 即可进行接口调试；
如下图：

调试2.png

调试结果.png

4.3、使用postman工具进行接口的测试

工具下载地址：https://www.getpostman.com/downloads/
下载好和自己电脑匹配的相应版本后，第一次打开会让你登入邮箱、账号、密码之类的，直接关掉就好；
输入接口地址就可以直接测试；
测试结果如下:

postMaN.png

本人觉得在做代码测试或者和前端联调的时候，建议使用swagger;
因为：

·swagger的API文档非常明确；
· 测试的时候不需要再使用URL输入浏览器的方式来访问Controller；
·spring-boot与swagger的集成非常简单；
·是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务；
·还有一个我觉得最好的是是能实时同步api与文档，易于前后端联调；

学到这里，大家就都可以搭一个简单的springBoot项目了；更多的技术会在以后给大家分享；
学习使人进步，分享使人快乐！