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

image

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 项目

image

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

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

image

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

image

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

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

image

第 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 为例，并新建一个数据库、设计一个表，表的结构如下：

image

修改配置文件 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("/v1") 用于将请求路径映射到整个类上

然后，利用 @RequestMapping 定义具体的路径及请求的方式，这里将需要暴露出去的接口都通过方法展示出来

以查询某一条记录为例，通过参数 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

image

5. 最后

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

我已经将文中全部源码上传到公众号后台，关注公众号「 AirPython 」后回复「 rest1 」即可获得全部源码

下一篇文章将讲解 Python 中搭建 RESTful API 正确的姿势

如果你觉得文章还不错，请大家点赞分享下。你的肯定是我最大的鼓励和支持。

推荐阅读

行为驱动开发：一篇文章带你用 Python 玩转 BDD

推荐几款优质 Chrome 摸鱼插件，带你畅快划水

用 Python 分析微信群聊记录，是怎样一种体验？