restful api设计（10行代码构建RESTful）

威哥 2023-08-15 08:58:26 444

restful api设计（10行代码构建RESTful）@DeleteMapping@PostMapping@RestController@GetMapping@PutMapping

restful api设计（10行代码构建RESTful）(1)

作者：松哥

来源：牧码小子

广而告之：由于此订阅号换了个皮肤，系统自动取消了读者的公众号置顶。导致用户接受文章不及时。可以打开订阅号，选择置顶（标星）公众号，重磅干货，第一时间送达！

RESTful ，到现在相信已经没人不知道这个东西了吧！关于 RESTful 的概念，我这里就不做过多介绍了，传统的 Struts 对 RESTful 支持不够友好，但是 SpringMVC 对于 RESTful 提供了很好的支持，常见的相关注解有：

@RestController
@GetMapping
@PutMapping
@PostMapping
@DeleteMapping
@ResponseBody
...

这些注解都是和 RESTful 相关的，在移动互联网中，RESTful 得到了非常广泛的使用。RESTful 这个概念提出来很早，但是以前没有移动互联网时，我们做的大部分应用都是前后端不分的，在这种架构的应用中，数据基本上都是在后端渲染好返回给前端展示的，此时 RESTful 在 Web 应用中基本就没用武之地，移动互联网的兴起，让我们一套后台对应多个前端项目，因此前后端分离，RESTful 顺利走上前台。

Spring Boot 继承自 Spring SpringMVC， SpringMVC 中对于 RESTful 支持的特性在 Spring Boot 中全盘接收，同时，结合 JPA 和自动化配置，对于 RESTful 还提供了更多的支持，使得开发者几乎不需要写代码（很少几行），就能快速实现一个 RESTful 风格的增删改查。

接下来，松哥通过一个简单的案例，来向大家展示 Spring Boot 对于 RESTful 的支持。

实战

创建工程

首先创建一个 Spring Boot 工程，引入 Web、jpa、mysql、RestRepositories依赖：

restful api设计（10行代码构建RESTful）(2)

创建完成后，还需要锁定 MySQL 驱动的版本以及加入 Druid 数据库连接池，完整依赖如下：

<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-data-jpa</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-data-rest</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
<groupId>com.alibaba</groupId>
<artifactId>druid-spring-boot-starter</artifactId>
<version>1.1.10</version>
</dependency>
<dependency>
<groupId>mysql</groupId>
<artifactId>mysql-connector-Java</artifactId>
<scope>runtime</scope>
<version>5.1.27</version>
</dependency>
</dependencies>

配置数据库

主要配置两个，一个是数据库，另一个是 Jpa：

spring.datasource.type=com.alibaba.druid.pool.DruidDataSource
spring.datasource.username=root
spring.datasource.password=root
spring.datasource.url=jdbc:mysql:///test01
spring.datasource.driver-class-name=com.mysql.jdbc.Driver
spring.jpa.properties.hibernate.dialect=org.hibernate.dialect.MySQL57Dialect
spring.jpa.show-sql=true
spring.jpa.hibernate.ddl-auto=update
spring.jpa.database-platform=mysql
spring.jpa.database=mysql

这里的配置，和 Jpa 中的基本一致。

前面五行配置了数据库的基本信息，包括数据库连接池、数据库用户名、数据库密码、数据库连接地址以及数据库驱动名称。

接下来的五行配置了 JPA 的基本信息，分别表示生成 SQL 的方言、打印出生成的 SQL 、每次启动项目时根据实际情况选择是否更新表、数据库平台是 MySQL。

这两段配置是关于 MySQL JPA 的配置，没用过 JPA 的小伙伴可以参考松哥之前的 JPA 文章：http://www.javaboy.org/2019/0407/springboot-jpa.html

构建实体类

@Entity(name = "t_book")
public class Book {
@Id
@GeneratedValue(strategy = GenerationType.IDENTITY)
private Long id;
@Column(name = "book_name")
private String name;
private String author;
//省略 getter/setter
}
public interface BookRepository extends JpaRepository<Book Long> {
}

这里一个是配置了一个实体类 Book，另一个则是配置了一个 BookRepository ，项目启动成功后，框架会根据 Book 类的定义，在数据库中自动创建相应的表，BookRepository 接口则是继承自 JpaRepository ，JpaRepository 中自带了一些基本的增删改查方法。

好了，代码写完了。

啥？你好像啥都没写啊？是的，啥都没写，啥都不用写，一个 RESTful 风格的增删改查应用就有了，这就是 Spring Boot 的魅力！

测试

此时，我们就可以启动项目进行测试了，使用 POSTMAN 来测试（大家也可以自行选择趁手的 HTTP 请求工具）。

此时我们的项目已经默认具备了一些接口，我们分别来看：

根据 id 查询接口

http://127.0.0.1:8080/books/{id}

这个接口表示根据 id 查询某一本书：

restful api设计（10行代码构建RESTful）(3)

分页查询

http://127.0.0.1:8080/books

这是一个批量查询接口，默认请求路径是类名首字母小写，并且再加一个 s 后缀。这个接口实际上是一个分页查询接口，没有传参数，表示查询第一页，每页 20 条数据。

restful api设计（10行代码构建RESTful）(4)

查询结果中，除了该有的数据之外，也包含了分页数据：

restful api设计（10行代码构建RESTful）(5)

分页数据中：

size 表示每页查询记录数
totalElements 表示总记录数
totalPages 表示总页数
number 表示当前页数，从0开始计

如果要分页或者排序查询，可以使用 _links 中的链接。 http://127.0.0.1:8080/books?page=1&size=3&sort=id desc。

restful api设计（10行代码构建RESTful）(6)

添加

也可以添加数据，添加是 POST 请求，数据通过 JSON 的形式传递，如下：

restful api设计（10行代码构建RESTful）(7)

添加成功之后，默认会返回添加成功的数据。

修改

修改接口默认也是存在的，数据修改请求是一个 PUT 请求，修改的参数也是通过 JSON 的形式传递：

restful api设计（10行代码构建RESTful）(8)

默认情况下，修改成功后，会返回修改成功的数据。

删除

当然也可以通过 DELETE 请求根据 id 删除数据：

restful api设计（10行代码构建RESTful）(9)

删除成功后，是没有返回值的。

不需要几行代码，一个基本的增删改查就有了。

这些都是默认的配置，这些默认的配置实际上都是在 JpaRepository 的基础上实现的，实际项目中，我们还可以对这些功能进行定制。

查询定制

最广泛的定制，就是查询，因为增删改操作的变化不像查询这么丰富。对于查询的定制，非常容易，只需要提供相关的方法即可。例如根据作者查询书籍：

public interface BookRepository extends JpaRepository<Book Long> {
List<Book> findBookByAuthorContaining(@Param("author") String author);
}

注意，方法的定义，参数要有 @Param 注解。

定制完成后，重启项目，此时就多了一个查询接口，开发者可以通过 http://localhost:8080/books/search 来查看和 book 相关的自定义接口都有哪些：

restful api设计（10行代码构建RESTful）(10)

查询结果表示，只有一个自定义接口，接口名就是方法名，而且查询结果还给出了接口调用的示例。我们来尝试调用一下自己定义的查询接口：

restful api设计（10行代码构建RESTful）(11)

开发者可以根据实际情况，在 BookRepository 中定义任意多个查询方法，查询方法的定义规则和 Jpa 中一模一样。但是，这样有一个缺陷，就是 Jpa 中方法名太长，因此，如果不想使用方法名作为接口名，则可以自定义接口名：

public interface BookRepository extends JpaRepository<Book Long> {
@RestResource(rel = "byauthor" path = "byauthor")
List<Book> findBookByAuthorContaining(@Param("author") String author);
}

@RestResource 注解中，两个参数的含义：

rel 表示接口查询中，这个方法的 key
path 表示请求路径

这样定义完成后，表示接口名为 byauthor ，重启项目，继续查询接口：

restful api设计（10行代码构建RESTful）(12)

除了 rel和path两个属性之外，@RestResource中还有一个属性，exported表示是否暴露接口，默认为true，表示暴露接口，即方法可以在前端调用，如果仅仅只是想定义一个方法，不需要在前端调用这个方法，可以设置exported属性为false。

如果不想暴露官方定义好的方法，例如根据 id删除数据，只需要在自定义接口中重写该方法，然后在该方法上加@RestResource注解并且配置相关属性即可。

public interface BookRepository extends JpaRepository<Book Long> {
@RestResource(rel = "byauthor" path = "byauthor")
List<Book> findBookByAuthorContaining(@Param("author") String author);
@Override
@RestResource(exported = false)
void deleteById(Long aLong);
}

另外生成的 JSON 字符串中的集合名和单个 item的名字都是可以自定义的：

@RepositoryRestResource(collectionResourceRel = "bs" itemResourceRel = "b" path = "bs")
public interface BookRepository extends JpaRepository<Book Long> {
@RestResource(rel = "byauthor" path = "byauthor")
List<Book> findBookByAuthorContaining(@Param("author") String author);
@Override
@RestResource(exported = false)
void deleteById(Long aLong);
}