教你 10 分钟构建一套 RESTful API 服务( 上 )

1. 前言

随着前后端分离和微服务的兴起，在后端开发中，RESTful API 几乎变成一种标配

RESTful API 是一套成熟的互联网应用程序设计风格及开发方式，其最重要的 3 个特征如下：

1、无状态，客户端与服务端之间的交互在请求之间是无状态的

2、统一接口，服务器和客户端的通信方法必须保持统一

3、基于资源，增删改查都是对于资源状态的改变

接下来，将分两篇文章，教大家用 Java 和 Python 快速构建一套 RESTful API

本篇将从 Java - RESTful API 开始，使用的技术栈是：SpringBoot + MyBatis + Swagger2

2. 准备

第 1 步，下载安装 IDEA 开发工具

https://www.jetbrains.com/idea/

然后，新建一个 Spring Boot 项目

第 2 步，输入包名，然后选择构建方式，其他保持默认即可

默认构建方式是：Maven，可以手动切换到 Gradle，本文以 Maven 为例

第 3 步，工程项目为 Web 项目，选择 Spring Boot 的版本及项目保存位置

第 4 步，按照功能，使用包名对项目进行分层

对项目进行分层，新建一些常用的包，包含：service、controller、domain 等

第 5 步，为工程添加 Maven 依赖

编写项目根目录下的 pom.xml 文件，新增对 MyBatis、Mysql、Swagger 的 Maven 依赖，重新构建，等待所有依赖下载完成

# pom.xml
# maven 依赖
<!--Swagger-->
<dependency>
     <groupId>io.springfox</groupId>
     <artifactId>springfox-swagger2</artifactId>
     <version>2.7.0</version>
</dependency>

<!--MyBatis-->
<dependency>
     <groupId>org.mybatis.spring.boot</groupId>
     <artifactId>mybatis-spring-boot-starter</artifactId>
     <version>2.1.2</version>
</dependency>

<!--MySql-->
<dependency>
     <groupId>mysql</groupId>
     <artifactId>mysql-connector-java</artifactId>
     <version>6.0.6</version>
</dependency>

第 6 步，配置数据库

在本机安装数据库，以 Mysql 为例，并新建一个数据库、设计一个表，表的结构如下：

修改配置文件 application.properties，配置对应的数据库信息，包含：地址、用户名、密码等

# application.properties
# 数据库配置信息
spring.datasource.url=jdbc:mysql://localhost:3306/dg?useSSL=false
spring.datasource.username=root
spring.datasource.password=root
spring.datasource.driver-class-name=com.mysql.cj.jdbc.Driver
spring.data.elasticsearch.client.reactive.use-ssl=false

3. 实现

具体实现 RESTful API 过程如下：

第 1 步，新建一个实体类 People，实体成员变量与上面表结构字段一一对应

package com.xingag.api.domain;
/***
 * 数据库映射对象
 */
public class People {
    private int id;
    private String name;
    private int age;
    private boolean extra;

    public People() {
    }

    public People(int id, String name, int age, boolean extra) {
        this.id = id;
        this.name = name;
        this.age = age;
        this.extra = extra;
    }

   // ... 省略成员变量的get/set方法
}

第 2 步，MyBatis 数据库映射

以 CRUD 为例，即：查询所有记录、查询某一条记录、插入一条记录、更新一条记录、删除一条记录

使用 MyBatis 的 4 个注解，包含：@Select、@Update、@Insert、@Delete 结合 SQL 语句，映射对应的方法，到达操作数据库的动作

// PeopleHandle.java
@Mapper
public interface PeopleHandle {

    /***
     * 查询数据表中的所有记录
     * 对应SQL：select * from people
     * @return
     */
    @Select("SELECT * FROM PEOPLE")
    List<People> getAllPeople();

    /***
     * 查询数据表中的某一条记录
     * @param id 查询的id
     * @return
     */
    @Select("SELECT * FROM PEOPLE where ID = #{id}")
    People getPeople(@Param("id") int id);

    /***
     * 插入一条数据
     * @param name 姓名
     * @param age  年龄
     * @param extra  其他
     * @return
     */
    @Insert("INSERT INTO PEOPLE(NAME,AGE,EXTRA) VALUES(#{name},#{age},#{extra})")
    int insertPeople(@Param("name") String name, @Param("age") int age, @Param("extra") boolean extra);


    /***
     * 更新一条记录（@UpdateProvider）
     * @param people 准备更新进去的数据
     * @return
     */
    @UpdateProvider(type = SqlProvider.class, method = "updatePeopleSql")
    int updatePeople(People people);

    /***
     * 删除某条记录（@Delete）
     * @param id 根据ID去删除一条记录
     * @return
     */
    @Delete("DELETE FROM PEOPLE WHERE ID = #{id}")
    int deletePeople(@Param("id") int id);
}

需要注意的是，更新操作借助了 MyBatis 里的 @UpdateProvider 注解，指向 SqlProvider 类的 updatePeopleSql 方法，动态生成 SQL，使用起来更加灵活

// SqlProvider.java
public class SqlProvider {

    /***
     * 使用MyBatis的SQL方法来更新sql语句
     *
     * @return
     */
    public String updatePeopleSql(People people) {

        //包含表名，要更新的字段，更新条件（id）
        //最后组装成新的SQL语句
        return new SQL() {{
            UPDATE("people");

            if (null != people.getName()) {
                SET("name=#{name}");
            }
            SET("age=#{age}");
            SET("extra=#{extra}");
            WHERE("id=#{id}");
        }}.toString();
    }
}

第 3 步，编写服务 Service

新建一个 PeopleService 接口，定义对外提供的方法

// PeopleService.java
/***
 * 对外提供的接口
 */
public interface PeopleService {
    //获取所有的数据
    List<People> getAllPeoples();

    //获取某一条记录
    People getOnePeople(int id);

    //更新一条记录
    boolean updatePeople(People people);

    //新增一条记录
    boolean addPeople(People people);

    //删除一条记录
    boolean delPeople(int id);
}

第 4 步，实现服务

新建服务实现类 PeopleServiceImp 使用 @Autowired 注解自动导入上面定义的数据库映射操作接口：PeopleHandle

@Service
public class PeopleServiceImp implements PeopleService {

    //导入
    @Autowired
    private PeopleHandle peopleHandle;
}

在服务类中，实现上面接口定义的功能

@Override
public List<People> getAllPeoples() {
     return peopleHandle.getAllPeople();
}

@Override
public People getOnePeople(int id) {
     return peopleHandle.getPeople(id);
}

@Override
public boolean updatePeople(People people) {
     return peopleHandle.updatePeople(people) > 0;
}

@Override
public boolean addPeople(People people) {
     return peopleHandle.insertPeople(people.getName(),people.getAge(),people.isExtra())>0;
}

@Override
public boolean delPeople(int id) {
     return peopleHandle.deletePeople(id)>0;
}

第 5 步，暴露接口 Controller

首先，新建一个文件 PeopleController，用于对外暴露接口

@RestController
@RequestMapping("/v1")
public class PeopleController {
    //...
}

其中，@RestController 相当于 @Controller + @ResponseBody，快速将一个对象进行序列化后进行返回

然后，利用 @RequestMapping 定义具体的路径及请求的方式，这里将需要暴露出去的接口都通过方法展示出来@RequestMapping("/v1") 用于将请求路径映射到整个类上

以查询某一条记录为例，通过参数 id，使用 PeopleService 查询到数据，返回即可。

PS：受限于篇幅，其他查询所有记录、更新、新增、删除的代码在文末获取源码

/***
 * 某一条记录
 * @param id
 * @return
 */
@ApiOperation(value = "查询某一条记录")
@RequestMapping(value = "/one/{id}", method = RequestMethod.GET)
public ApiResult getOnePeople(@ApiParam(name = "id", value = "主键id", required = true) @PathVariable int id) {
    People people = peopleService.getOnePeople(id);
    if (null != people) {
         return ApiResult.success(people);
     } else {
         return ApiResult.failure("数据不存在");
     }
 }

第 6 步，返回数据标准化

为了方便后期维护，最后将 REST API 接口的结果进行一次封装使用 Lombok 结合 swagger，将返回码、返回值等数据封装到方法内部进行返回，并根据代码自动生成接口文档

@Data
@ApiModel(value = "接口返回结果")
public class ApiResult<T> implements Serializable {

    private static final long serialVersionUID = -2953545018812382877L;

    /**
     * 返回码，200 正常
     */
    @ApiModelProperty(value = "返回码，200 正常", name = "code")
    private int code = 200;

    /**
     * 返回信息
     */
    @ApiModelProperty(value = "返回信息", name = "msg")
    private String msg = "成功";

    /**
     * 返回数据
     */
    @ApiModelProperty(value = "返回数据对象", name = "data")
    private T data;

    /**
     * 获取成功状态结果
     *
     * @param data 返回数据
     * @return
     */
    public static ApiResult success(Object data) {
        return success(data, null);
    }


    /**
     * 获取失败状态结果
     *
     * @param msg (自定义)失败消息
     * @return
     */
    public static ApiResult failure(String msg) {
        return failure(ResponseCode.FAIL.getCode(), msg, null);
    }
}

4. 可视化

运行项目后，Spring Boot 自带的 Tomcat 会以 8080 端口号运行

使用浏览器访问

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

由于项目中集成了 Swagger，这里可以很直观的看到定义好的 RESTful API

5. 最后

上面实现的 RESTful API，可以通过 CURL 或者 Postman 去测试，去一步步完善