适用于云的 Spring Boot：REST API 开发

每日分享最新，最流行的软件开发知识与最新行业趋势，希望大家能够一键三连，多多支持，跪求关注，点赞，留言。

概述在 Spring Cloud 应用程序上下文中特别重要的 Spring Boot 框架功能。在本文中，我们将讨论与 API 开发相关的功能。

微服务应用程序可以通过两种主要方式相互交互：REST 服务和消息系统。REST 方法是最常见的，将在本文中进行处理。我们将看到 Spring Boot 如何通过使用一组有用的注释和一些隐式后台行为（例如将 模型 对象序列化为 JSON 格式）使 REST API 的开发过程变得相当简单。
另一个重要问题与 API 的文档和共享有关，我们将看到这些问题通过名为Swagger的解决方案得到有效解决。将 Swagger 与Spring Boot集成使我们能够从源代码生成文档，作为 Swagger JSON 文件，甚至可以使用 Web 用户界面浏览和管理所有公开的 REST 服务。

REST API 开发
为了使用 Spring Boot 开发 REST API，我们需要在 Maven POM 中添加以下依赖项：

org.springframework.boot
spring-boot-starter-web

通过这种方式，我们将项目描述为一个 Web 应用程序，默认包含一个嵌入式 tomcat Web 服务器。然后，利用一组特定的注释，我们可以定义我们的控制器，这些控制器旨在向外部世界公开 HTTP REST 服务。我们可以通过简单地用@RestController 注释一个类来定义它们。接下来的步骤是设置定义实现我们服务的类方法与通过 HTTP 调用执行它们所需的 URI 路径之间的对应关系所需的映射。我们在以下代码片段中看到一个示例：
@RestController
@RequestMapping("/library")
public class BookController {
@Autowired
private BookService bookService;
@GetMapping("/book")
public List findAll() {
return bookService.findAll();
}
@GetMapping("/book/{id}")
public Book findById(@PathVariable("id") String id) {
return bookService.findById(id);
}
@PostMapping("/book")
public Book add(@RequestBody Book book) {
return bookService.save(book);
}
@PutMapping("/book")
public Book update(@RequestBody Book book) {
return bookService.save(book);
}
@DeleteMapping("/book/{id}")
public void deleteByTitle(@PathVariable("id") String id) {
bookService.deleteById(id);
}
@GetMapping(value = "/book", params = {"author"})
public List findByAuthor(@RequestParam("author") String author) {
return bookService.findByAuthor(author);
}
}
这里我们用@RestController 和@RequestMapping("/library") 注释了一个类。@RequestMapping 注释为用于调用我们的服务的 HTTP 路径指定了一个前缀。然后为类公共方法配置其他注释，旨在实现 HTTP REST 经典调用：GET、POST、PUT、DELETE：
@GetMapping
@PostMapping
@PutMapping
@DeleteMapping
这些注解包含 HTTP 路径的最后部分以及一个或多个参数（如有需要）。@PathVariable注解用于映射URI路径中直接传递的参数，并定义在相应方法注解中的花括号内。映射查询参数，也就是说，那些在“？”之后传递的参数 URI 中的字符，则可以使用 @RequestParameter 批注代替，如上面代码片段中的findByAuthor 方法。
例如，要获取数据库中的所有书籍，我们可以使用以下方法（如果应用程序正在我们的本地计算机上运行），并调用 HTTP GET 方法：
http://localhost:8080/library/book
要获得具有特定 ID 的图书：
http://localhost:8080/library/book/
或者最后得到作者的书籍列表（查询参数的情况）
http://localhost:8080/library/book?author=<作者姓名>
注释提供了一种简单的方法来“转换”一组服务中 Java 类的内部实现，这些服务可以通过 HTTP 协议从外部世界调用。另一个非常有用的特性是 JSON 数据的序列化。例如，如果我们考虑上面代码片段中名为add的 POST 方法，我们会看到它采用 Book 类型的参数。但我们知道对该方法的调用实际上是由带有 JSON 正文的 HTTP 调用进行的。Spring Boot 使用名为Jackson的库自动将该 JSON 转换为 Book 对象。
上述特性是促进微服务开发的良好基础。进一步的步骤是拥有一种有效的方式来共享和交流我们的 REST 服务的结构。在下一节中，我们将讨论这个问题，介绍一个名为Swagger的解决方案。
API 文档和 Swagger 解决方案
在微服务场景中开发一个完整的系统，其中有许多应用程序与 REST API 进行交互，需要保持所涉及的 API 的一致性。Swagger 是一个解决方案，包含许多工具来应对这些问题。Swagger通过 JSON 规范描述 API。我们可以用 JSON 格式定义我们的服务，然后从中生成基本代码，或者从我们的代码中生成 JSON。在此处描述的与 Spring Boot 的集成中，我们将使用第二个选项。
在上一节中，我们描述了如何使用一组给定的输入和输出对象映射和格式来开发由 Spring Boot 应用程序公开的 REST 服务。如果我们考虑大局，我们的单个应用程序必须与许多其他应用程序交互，这些应用程序可能由其他团队开发，它们有自己的 REST 接口，我们理解记录和传达这些接口的结构是多么重要。
在 Web 应用程序的上下文中将 Swagger 集成到 Spring Boot 中，我们可以生成 REST 服务的 JSON 描述，可通过特定的 URL 路径访问。我们还将有一个可用的 Swagger Web UI，允许我们浏览服务定义并与它们交互。
如何在 Spring Boot 中集成 Swagger
为了执行集成（我们在示例中使用 Swagger 2），我们要做的第一件事是设置相关的规范，如以下 Maven POM 片段所示：

io.springfox

springfox-swagger2

2.7.0

io.springfox

springfox-swagger-ui

2.7.0

然后我们必须通过 @EnableSwagger2注释启用 Swagger。在下面的代码片段示例中，我们在一个特定的配置类（用@Configuration 标记）中执行此操作，并且在同一个类中，我们定义了一个类型为Docket的 bean 。在Docket bean 配置中，我们设置了一个组名、一组基本信息（如标题、描述）和一个带有正则表达式的Predicate 对象，以捕获我们希望 Swagger 读取的 REST 服务可用的 URL 路径，在我们的示例中，所有路径都以“库”为前缀。
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket postsApi() {
return new Docket(DocumentationType.SWAGGER_2).groupName("mygroup")
.apiInfo(apiInfo()).select().paths( regex("/library/.*")).build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder().title("REST API example")
.description("A minimal REST example with H2 in memory db as persistence layer")
.termsOfServiceUrl("http://codingstrain.com")
.license("REST API example License")
.licenseUrl("fake@gmail.com")
.version("1.0")
.build();
}
}
由于一个错误，我们还需要一个额外的配置，如下所示，假设我们使用的是 application.yaml 文件：

mvc:
pathmatch:
matching-strategy: ant_path_matcher

运行示例应用程序
您可以在以下 GitHub 链接中找到一个示例应用程序，其中包含前面部分中描述的所有配置：https ://github.com/mcasari/codingstrain.git 。您可以使用以下命令“git clone https://github.com/mcasari/codingstrain.git”将其安装为本地 git 存储库，并使用 Maven 从命令行或使用您喜欢的 IDE 编译和构建它。
您可以使用以下 Maven 命令“mvn spring-boot:run”运行它。由于它是一个 Spring Web 应用程序，它将与嵌入式 Web 服务器一起运行，默认情况下侦听8080端口。
我们可以使用 swagger 快速浏览甚至测试我们的 API。我们可以使用以下 URL 获取包含 API 定义的 JSON 文件：
http://localhost:8080/v2/api-docs?group=mygroup
从上面的 URL 可以看出，我们传递了一个名为group的查询参数，其值与我们在 Docket bean 配置中定义的组名称相对应。结果，我们获得了一个 JSON，它可以具有一些实用性，但不是我们所说的“用户友好”。作为更好的选择，我们可以通过以下地址使用 Swagger UI：
http://localhost:8080/swagger-ui.html
在下面的屏幕截图中，我们可以看到我们在屏幕上获得的内容。我们可以看到我们在应用程序中实现的所有 REST 服务，如果我们扩展它们，我们甚至可以与它们进行交互。例如，我们可以使用路径“/library/book”通过 HTTP POST 服务发布一本新书，或者使用以“ author” 为参数的可用 GET 方法获取作者的一本书。
招摇的用户界面
结论
在本文中，我们了解了 Spring Boot 如何简化 REST API 的开发。我们还看到集成像 Swagger 这样的解决方案如何改进服务定义的通信。这在微服务系统的上下文中尤为重要，在微服务系统中，我们有必须相互交互的独立应用程序，并且必须保持接口的一致性。
Spring Boot 还有另一个非常有用的功能，即所谓的Actuator依赖项，它提供了一组 HTTP 端点来监视、获取统计信息和管理生产环境中的应用程序。我们将在以下文章中介绍它：Spring Boot for Cloud - Actuator。