# 創建異步方法 本指南將引導您創建對GitHub的異步查詢。 重點是異步部分，這是擴展服務時經常使用的功能。 ## 你會建立什么 您將構建一個查詢服務，該服務查詢GitHub用戶信息并通過GitHub的API檢索數據。 一種擴展服務的方法是在后臺運行昂貴的作業，并使用Java的Java等待結果 [`CompletableFuture`](https://docs.oracle.com/javase/8/docs/api/java/util/concurrent/CompletableFuture.html)界面。 Java的 `CompletableFuture` 是從常規的演變 `Future`。 它使流水線化多個異步操作并將它們合并為一個異步計算變得很容易。 ## 你需要什么 * 約15分鐘 * 最喜歡的文本編輯器或IDE * [JDK 1.8](http://www.oracle.com/technetwork/java/javase/downloads/index.html) 或更高版本 * [Gradle 4+](http://www.gradle.org/downloads) 或 [Maven 3.2+](https://maven.apache.org/download.cgi) * 您還可以將代碼直接導入到IDE中： * [彈簧工具套件（STS）](https://spring.io/guides/gs/sts) * [IntelliJ IDEA](https://spring.io/guides/gs/intellij-idea/) ## 如何完成本指南 像大多數Spring 一樣 [入門指南](https://spring.io/guides) ，您可以從頭開始并完成每個步驟，也可以繞過您已經熟悉的基本設置步驟。 無論哪種方式，您最終都可以使用代碼。 要 **從頭開始** ，請繼續進行“ [從Spring Initializr開始”](https://spring.io/guides/gs/async-method/#scratch) 。 要 **跳過基礎知識** ，請執行以下操作： * [下載](https://github.com/spring-guides/gs-async-method/archive/master.zip) 并解壓縮本指南的源存儲庫，或使用 對其進行克隆 [Git](https://spring.io/understanding/Git) ： `git clone [https://github.com/spring-guides/gs-async-method.git](https://github.com/spring-guides/gs-async-method.git)` * 光盤進入 `gs-async-method/initial` * 繼續 [創建GitHub用戶的表示形式](https://spring.io/guides/gs/async-method/#initial) 。 **完成后** ，您可以根據中的代碼檢查結果 `gs-async-method/complete`. ## 從Spring Initializr開始 如果您使用Maven，請訪問 [Spring Initializr](https://start.spring.io/#!type=maven-project&language=java&platformVersion=2.4.3.RELEASE&packaging=jar&jvmVersion=1.8&groupId=com.example&artifactId=asynch-method&name=asynch-method&description=Demo%20project%20for%20Spring%20Boot&packageName=com.example.asynch-method&dependencies=web) 以生成具有所需依賴項的新項目（Spring Web）。 以下清單顯示了 `pom.xml` 選擇Maven時創建的文件： ~~~ <?xml version="1.0" encoding="UTF-8"?> <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd"> <modelVersion>4.0.0</modelVersion> <parent> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-parent</artifactId> <version>2.4.3</version> <relativePath/> <!-- lookup parent from repository --> </parent> <groupId>com.example</groupId> <artifactId>asynch-method</artifactId> <version>0.0.1-SNAPSHOT</version> <name>asynch-method</name> <description>Demo project for Spring Boot</description> <properties> <java.version>1.8</java.version> </properties> <dependencies> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-test</artifactId> <scope>test</scope> </dependency> </dependencies> <build> <plugins> <plugin> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-maven-plugin</artifactId> </plugin> </plugins> </build> </project> ~~~ 如果您使用Gradle，請訪問 [Spring Initializr](https://start.spring.io/#!type=gradle-project&language=java&platformVersion=2.4.3.RELEASE&packaging=jar&jvmVersion=1.8&groupId=com.example&artifactId=asynch-method&name=asynch-method&description=Demo%20project%20for%20Spring%20Boot&packageName=com.example.asynch-method&dependencies=web) 以生成具有所需依賴項的新項目（Spring Web）。 您可以直接從 獲取具有必要依賴項的Gradle構建文件 [Spring Initializr](https://start.spring.io/#!type=gradle-project&language=java&platformVersion=2.4.2.RELEASE&packaging=jar&jvmVersion=11&groupId=com.example&artifactId=asynch-method&name=asynch-method&description=Demo%20project%20for%20Spring%20Boot&packageName=com.example.asynch-method&dependencies=web) 。 以下清單顯示了 `build.gradle`選擇Gradle時創建的文件： ~~~ plugins { id 'org.springframework.boot' version '2.4.3' id 'io.spring.dependency-management' version '1.0.11.RELEASE' id 'java' } group = 'com.example' version = '0.0.1-SNAPSHOT' sourceCompatibility = '1.8' repositories { mavenCentral() } dependencies { implementation 'org.springframework.boot:spring-boot-starter-web' testImplementation 'org.springframework.boot:spring-boot-starter-test' } test { useJUnitPlatform() } ~~~ ### 手動初始化（可選） 如果要手動初始化項目而不是使用前面顯示的鏈接，請按照以下步驟操作： 1. 導航到 [https://start.spring.io](https://start.spring.io) 。 該服務提取應用程序所需的所有依賴關系，并為您完成大部分設置。 2. 選擇Gradle或Maven以及您要使用的語言。 本指南假定您選擇了Java。 3. 單擊 **Dependencies，** 然后選擇 **Spring Web** 。 4. 點擊 **生成** 。 5. 下載生成的ZIP文件，該文件是使用您的選擇配置的Web應用程序的存檔。 如果您的IDE集成了Spring Initializr，則可以從IDE中完成此過程。 ## 創建GitHub用戶的表示形式 在創建GitHub查找服務之前，您需要定義將通過GitHub API檢索的數據的表示形式。 要對用戶表示建模，請創建一個資源表示類。 為此，請為普通的舊Java對象提供字段，構造函數和訪問器，如以下示例所示（來自 `src/main/java/com/example/asyncmethod/User.java`）顯示： ~~~ package com.example.asyncmethod; import com.fasterxml.jackson.annotation.JsonIgnoreProperties; @JsonIgnoreProperties(ignoreUnknown=true) public class User { private String name; private String blog; public String getName() { return name; } public void setName(String name) { this.name = name; } public String getBlog() { return blog; } public void setBlog(String blog) { this.blog = blog; } @Override public String toString() { return "User [name=" + name + ", blog=" + blog + "]"; } } ~~~ Spring使用 [Jackson JSON](https://wiki.fasterxml.com/JacksonHome) 庫將GitHub的JSON響應轉換為 `User`目的。 這 `@JsonIgnoreProperties`注釋告訴Spring忽略該類中未列出的任何屬性。 這樣可以輕松進行REST調用并生成域對象。 在本指南中，我們僅抓取 `name` 和 `blog` 用于演示的URL。 ## 創建GitHub查找服務 接下來，您需要創建一個查詢GitHub的服務以查找用戶信息。 以下清單（來自 `src/main/java/com/example/asyncmethod/GitHubLookupService.java`）顯示了如何執行此操作： ~~~ package com.example.asyncmethod; import org.slf4j.Logger; import org.slf4j.LoggerFactory; import org.springframework.boot.web.client.RestTemplateBuilder; import org.springframework.scheduling.annotation.Async; import org.springframework.stereotype.Service; import org.springframework.web.client.RestTemplate; import java.util.concurrent.CompletableFuture; @Service public class GitHubLookupService { private static final Logger logger = LoggerFactory.getLogger(GitHubLookupService.class); private final RestTemplate restTemplate; public GitHubLookupService(RestTemplateBuilder restTemplateBuilder) { this.restTemplate = restTemplateBuilder.build(); } @Async public CompletableFuture<User> findUser(String user) throws InterruptedException { logger.info("Looking up " + user); String url = String.format("https://api.github.com/users/%s", user); User results = restTemplate.getForObject(url, User.class); // Artificial delay of 1s for demonstration purposes Thread.sleep(1000L); return CompletableFuture.completedFuture(results); } } ~~~ 這 `GitHubLookupService` 類使用Spring的 `RestTemplate` 調用遠程REST點（api.github.com/users/），然后將答案轉換為 `User`目的。 Spring Boot自動提供一個 `RestTemplateBuilder` 使用任何自動配置位（即， `MessageConverter`). 該課程標有 `@Service` 注解，使其成為Spring組件掃描以檢測并添加到應用程序上下文的候選對象。 這 `findUser` 方法標記為Spring的 `@Async`注釋，指示它應在單獨的線程上運行。 該方法的返回類型為 [`CompletableFuture<User>`](https://docs.oracle.com/javase/8/docs/api/java/util/concurrent/CompletableFuture.html) 代替 `User`，這是任何異步服務的要求。 此代碼使用 `completedFuture` 返回一個方法 `CompletableFuture` 實例已經完成，并帶有GitHub查詢的結果。 創建本地實例 GitHubLookupService 類不允許 findUser異步運行的方法。 必須在 @Configuration 上課或由 @ComponentScan. GitHub API的時間可能有所不同。 為了在本指南的后面部分演示其好處，此服務增加了一秒鐘的額外延遲。 ## 使應用程序可執行 要運行示例，可以創建一個可執行jar。 春天的 `@Async`批注適用于Web應用程序，但是您無需設置Web容器即可看到其好處。 以下清單（來自 `src/main/java/com/example/asyncmethod/AsyncMethodApplication.java`）顯示了如何執行此操作： ~~~ package com.example.asyncmethod; import org.springframework.boot.SpringApplication; import org.springframework.boot.autoconfigure.SpringBootApplication; import org.springframework.context.annotation.Bean; import org.springframework.scheduling.annotation.EnableAsync; import org.springframework.scheduling.concurrent.ThreadPoolTaskExecutor; import java.util.concurrent.Executor; @SpringBootApplication @EnableAsync public class AsyncMethodApplication { public static void main(String[] args) { // close the application context to shut down the custom ExecutorService SpringApplication.run(AsyncMethodApplication.class, args).close(); } @Bean public Executor taskExecutor() { ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor(); executor.setCorePoolSize(2); executor.setMaxPoolSize(2); executor.setQueueCapacity(500); executor.setThreadNamePrefix("GithubLookup-"); executor.initialize(); return executor; } } ~~~ Spring Initializr創建了一個 AsyncMethodApplication為您上課。 您可以在從Spring Initializr下載的zip文件中找到它（在 src/main/java/com/example/asyncmethod/AsyncMethodApplication.java）。 您可以將該類復制到您的項目中，然后對其進行修改，或者從前面的清單中復制該類。 `@SpringBootApplication` 是一個方便注釋，它添加了以下所有內容： * `@Configuration`：將類標記為應用程序上下文的Bean定義的源。 * `@EnableAutoConfiguration`：告訴Spring Boot根據類路徑設置，其他bean和各種屬性設置開始添加bean。 例如，如果 `spring-webmvc` 在類路徑上，此注釋將應用程序標記為Web應用程序并激活關鍵行為，例如設置 `DispatcherServlet`. * `@ComponentScan`：告訴Spring在服務器中尋找其他組件，配置和服務 `com/example` 包，讓它找到控制器。 這 `main()` 方法使用Spring Boot的 `SpringApplication.run()`啟動應用程序的方法。 您是否注意到沒有一行XML？ 沒有 `web.xml`文件。 該Web應用程序是100％純Java，因此您無需處理任何管道或基礎結構。 這 [`@EnableAsync`](https://docs.spring.io/spring/docs/current/spring-framework-reference/html/scheduling.html#scheduling-annotation-support) 注釋打開了Spring的運行能力 `@Async`后臺線程池中的方法。 此類還自定義 `Executor`通過定義一個新的bean。 在這里，該方法被命名為 `taskExecutor`，因為這是 的 [Spring搜索 特定方法名稱](https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/scheduling/annotation/EnableAsync.html) 。 在我們的例子中，我們希望將并發線程的數量限制為兩個，并將隊列的大小限制為500個 [您還可以調整更多的內容](https://docs.spring.io/spring-framework/docs/current/spring-framework-reference/integration.html#scheduling-task-executor) 。 。 如果您未定義 `Executor` 豆，春天創造了一個 `SimpleAsyncTaskExecutor` 并使用它。 還有一個 [`CommandLineRunner`](https://docs.spring.io/spring-boot/docs/current/reference/htmlsingle/#boot-features-command-line-runner) 注入 `GitHubLookupService` 并調用該服務三次，以演示該方法是異步執行的。 您還需要一個類來運行應用程序。 你可以在 `src/main/java/com/example/asyncmethod/AppRunner.java`。 以下清單顯示了該類： ~~~ package com.example.asyncmethod; import org.slf4j.Logger; import org.slf4j.LoggerFactory; import org.springframework.boot.CommandLineRunner; import org.springframework.stereotype.Component; import java.util.concurrent.CompletableFuture; @Component public class AppRunner implements CommandLineRunner { private static final Logger logger = LoggerFactory.getLogger(AppRunner.class); private final GitHubLookupService gitHubLookupService; public AppRunner(GitHubLookupService gitHubLookupService) { this.gitHubLookupService = gitHubLookupService; } @Override public void run(String... args) throws Exception { // Start the clock long start = System.currentTimeMillis(); // Kick of multiple, asynchronous lookups CompletableFuture<User> page1 = gitHubLookupService.findUser("PivotalSoftware"); CompletableFuture<User> page2 = gitHubLookupService.findUser("CloudFoundry"); CompletableFuture<User> page3 = gitHubLookupService.findUser("Spring-Projects"); // Wait until they are all done CompletableFuture.allOf(page1,page2,page3).join(); // Print results, including elapsed time logger.info("Elapsed time: " + (System.currentTimeMillis() - start)); logger.info("--> " + page1.get()); logger.info("--> " + page2.get()); logger.info("--> " + page3.get()); } } ~~~ ### 建立可執行的JAR 您可以使用Gradle或Maven從命令行運行該應用程序。 您還可以構建一個包含所有必需的依賴項，類和資源的可執行JAR文件，然后運行該文件。 生成可執行jar使得在整個開發生命周期中，跨不同環境等等的情況下，都可以輕松地將服務作為應用程序進行發布，版本控制和部署。 如果您使用Gradle，則可以通過使用以下命令運行該應用程序 `./gradlew bootRun`。 或者，您可以通過使用以下命令構建JAR文件： `./gradlew build` 然后運行JAR文件，如下所示： ~~~ java -jar build/libs/gs-async-method-0.1.0.jar ~~~ 如果您使用Maven，則可以通過使用以下命令運行該應用程序 `./mvnw spring-boot:run`。 或者，您可以使用以下命令構建JAR文件： `./mvnw clean package` 然后運行JAR文件，如下所示： ~~~ java -jar target/gs-async-method-0.1.0.jar ~~~ 此處描述的步驟將創建可運行的JAR。 您還可以 構建經典的WAR文件 。 該應用程序顯示日志記錄輸出，顯示對GitHub的每個查詢。 在...的幫助下 `allOf` 工廠方法，我們創建一個數組 `CompletableFuture`對象。 通過調用 `join` 方法，可以等待所有 `CompletableFuture` 對象。 以下清單顯示了此示例應用程序的典型輸出： ~~~ 2016-09-01 10:25:21.295 INFO 17893 --- [ GithubLookup-2] hello.GitHubLookupService : Looking up CloudFoundry 2016-09-01 10:25:21.295 INFO 17893 --- [ GithubLookup-1] hello.GitHubLookupService : Looking up PivotalSoftware 2016-09-01 10:25:23.142 INFO 17893 --- [ GithubLookup-1] hello.GitHubLookupService : Looking up Spring-Projects 2016-09-01 10:25:24.281 INFO 17893 --- [ main] hello.AppRunner : Elapsed time: 2994 2016-09-01 10:25:24.282 INFO 17893 --- [ main] hello.AppRunner : --> User [name=Pivotal Software, Inc., blog=https://pivotal.io] 2016-09-01 10:25:24.282 INFO 17893 --- [ main] hello.AppRunner : --> User [name=Cloud Foundry, blog=https://www.cloudfoundry.org/] 2016-09-01 10:25:24.282 INFO 17893 --- [ main] hello.AppRunner : --> User [name=Spring, blog=https://spring.io/projects] ~~~ 請注意，前兩個調用發生在單獨的線程中（ `GithubLookup-2`, `GithubLookup-1`），第三個線程將被暫存，直到兩個線程之一可用為止。 要比較不使用異步功能所需的時間，請嘗試注釋掉 `@Async`注釋并再次運行服務。 總耗用時間應明顯增加，因為每個查詢至少要花費一秒鐘的時間。 您也可以調整 `Executor` 增加 `corePoolSize` 例如屬性。 本質上，任務花費的時間越長，同時調用的任務越多，使事情變得異步的好處就多。 權衡正在處理 `CompletableFuture`界面。 它增加了一個間接層，因為您不再直接處理結果。 ## 概括 恭喜你！ 您剛剛開發了一個異步服務，該服務使您可以一次擴展多個呼叫。