教你 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=false3. 实现
具体实现 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
5. 最后
上面实现的 RESTful API，可以通过 CURL 或者 Postman 去测试，去一步步完善