restful java python,教你 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 开发工具

然后，新建一个 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 依赖

io.springfox

springfox-swagger2

2.7.0

org.mybatis.spring.boot

mybatis-spring-boot-starter

2.1.2

mysql

mysql-connector-java

6.0.6

第 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 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 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 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 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 去测试，去一步步完善

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

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

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