springboot編寫自定義模塊并使用 · springboot官方文檔中文版

# 創建一個多模塊項目本指南向您展示了如何使用Spring Boot創建一個多模塊項目。該項目將具有一個庫jar和使用該庫的主應用程序。您還可以使用它來查看如何自行構建庫（即不是應用程序的jar文件）。 ## 你會建立什么您將設置一個庫jar，它公開簡單的“ Hello，World”消息服務，然后將該服務包含在使用庫作為依賴項的Web應用程序中。 ## 你需要什么 ## 如何完成本指南像大多數Spring 一樣 [入門指南](https://spring.io/guides) ，您可以從頭開始并完成每個步驟，也可以繞過您已經熟悉的基本設置步驟。無論哪種方式，您最終都可以使用代碼。要 **從頭開始** ，繼續 [創建根項目](https://spring.io/guides/gs/multi-module/#scratch) 。要 **跳過基礎知識** ，請執行以下操作： * [下載](https://github.com/spring-guides/gs-multi-module/archive/master.zip) 并解壓縮本指南的源存儲庫，或使用對其進行克隆 [Git](https://spring.io/understanding/Git) ： `git clone [https://github.com/spring-guides/gs-multi-module.git](https://github.com/spring-guides/gs-multi-module.git)` * 光盤進入 `gs-multi-module/initial` * 繼續 [創建圖書館項目](https://spring.io/guides/gs/multi-module/#initial) 。 **完成后** ，您可以根據中的代碼檢查結果 `gs-multi-module/complete`. 首先，您設置一個基本的構建腳本。在使用Spring構建應用程序時，可以使用任何喜歡的構建系統，但是使用所需的代碼 [Gradle](http://gradle.org) 和 [Maven](https://maven.apache.org) 此處包含。如果您都不熟悉，請參閱 [使用Gradle](https://spring.io/guides/gs/gradle) 或 [構建Java項目使用Maven構建Java項目](https://spring.io/guides/gs/maven) 。 ## 創建一個根項目本指南分步介紹了如何建立兩個項目，其中一個是對另一個項目的依賴。因此，您需要在一個根項目下創建兩個子項目。但首先，在頂層創建構建配置。對于Maven，您將需要 `pom.xml` 和 `<modules>` 列出子目錄： ~~~ <?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> <groupId>org.springframework</groupId> <artifactId>gs-multi-module</artifactId> <version>0.1.0</version> <packaging>pom</packaging> <modules> <module>library</module> <module>application</module> </modules> </project> ~~~ 對于Gradle，您將需要一個 `settings.gradle` 包括相同的目錄： ~~~ rootProject.name = 'gs-multi-module' include 'library' include 'application' ~~~ 并且（可選）您可以添加一個空白 `build.gradle` （以幫助IDE識別根目錄）。 ### 創建目錄結構在要用作根目錄的目錄中，創建以下子目錄結構（例如，使用 `mkdir library application` 在\* nix系統上）： ~~~ └── library └── application ~~~ 在項目的根目錄中，您將需要建立一個構建系統，本指南將向您展示如何使用Maven或Gradle。 ## 創建圖書館項目這兩個項目之一用作另一個項目（應用程序）將使用的庫。 ### 創建目錄結構在 `library` 目錄中，創建以下子目錄結構（例如，通過使用 `mkdir -p src/main/java/com/example/multimodule/service` 在\* nix系統上）： ~~~ └── src └── main └── java └── com └── example └── multimodule └── service ~~~ 現在，您需要配置一個構建工具（Maven或Gradle）。在這兩種情況下，請注意， Spring Boot插件 **沒有** 庫項目中根本使用。該插件的主要功能是創建一個可執行文件“über-jar”，而我們既不需要庫又不需要庫。盡管未使用Spring Boot Maven插件，但您確實想利用Spring Boot依賴項管理，因此可以通過使用 `spring-boot-starter-parent`從Spring Boot作為父項目。一種替代方法是將依賴項管理作為物料導入 [清單（BOM）](https://maven.apache.org/guides/introduction/introduction-to-dependency-mechanism.html#Importing_Dependencies) 到 `<dependencyManagement/>`的部分 `pom.xml` 文件。 ### 設置圖書館項目對于Library項目，您無需添加依賴項。基礎的 `spring-boot-starter` 依賴關系提供了您所需的一切。您可以直接從獲取具有必要依賴項的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=multi-module-library&name=multi-module-library&description=Demo%20project%20for%20Spring%20Boot&packageName=com.example.multi-module-library) 。以下清單顯示了 `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/>  </parent> <groupId>com.example</groupId> <artifactId>multi-module-library</artifactId> <version>0.0.1-SNAPSHOT</version> <name>multi-module-library</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</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=multi-module-library&name=multi-module-library&description=Demo%20project%20for%20Spring%20Boot&packageName=com.example.multi-module-library) 。以下清單顯示了 `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' testImplementation 'org.springframework.boot:spring-boot-starter-test' } ~~~ #### 調整圖書館項目如果您是從以下位置生成“圖書館”項目的 `start.spring.io` 它將包含構建系統的包裝器腳本（ `mvnw` 或者 `gradlew`取決于您所做的選擇）。您可以將該腳本及其關聯的配置移至根目錄： ~~~ $ mv mvnw* .mvn .. $ mv gradlew* gradle .. ~~~ Library項目沒有使用main方法的類（因為它不是應用程序）。因此，您必須告訴構建系統不要嘗試為Library項目構建可執行的jar。（默認情況下，Spring Initializr會生成可執行項目。）要告訴Maven不為Library項目構建可執行的jar，必須從以下位置刪除以下代碼塊： `pom.xml` 由Spring Initializr創建： ~~~ <build> <plugins> <plugin> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-maven-plugin</artifactId> </plugin> </plugins> </build> ~~~ 以下清單顯示了最終的 `pom.xml` 庫項目的文件： ~~~ <?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/>  </parent> <groupId>com.example</groupId> <artifactId>library</artifactId> <version>0.0.1-SNAPSHOT</version> <name>multi-module-library</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</artifactId> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-test</artifactId> <scope>test</scope> </dependency> </dependencies> </project> ~~~ 要告訴Gradle不為Library項目構建可執行的jar，必須將以下代碼塊添加到 `build.gradle` 由Spring Initializr創建： ~~~ bootJar { enabled = false } jar { enabled = true } ~~~ 這 `bootJar` 任務嘗試創建一個可執行jar，這需要一個 `main()`方法。因此，您需要禁用 `bootJar` 任務并啟用 `jar` 任務（創建普通的jar而不是可執行的jar）。以下清單顯示了最終的 `build.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() } bootJar { enabled = false } jar { enabled = true } dependencies { implementation 'org.springframework.boot:spring-boot-starter' testImplementation 'org.springframework.boot:spring-boot-starter-test' } ~~~ ## 創建服務組件圖書館將提供 `MyService`應用程序可以使用的類。以下清單（來自 `library/src/main/java/com/example/multimodule/service/MyService.java`）顯示 `MyService` 班級： ~~~ package com.example.multimodule.service; import org.springframework.boot.context.properties.EnableConfigurationProperties; import org.springframework.stereotype.Service; @Service @EnableConfigurationProperties(ServiceProperties.class) public class MyService { private final ServiceProperties serviceProperties; public MyService(ServiceProperties serviceProperties) { this.serviceProperties = serviceProperties; } public String message() { return this.serviceProperties.getMessage(); } } ~~~ 要使其在標準Spring Boot習慣用法中具有可配置性（帶有 `application.properties`），您還可以添加一個 `@ConfigurationProperties`班級。這 `ServiceProperties` 類（來自 `library/src/main/java/com/example/multimodule/service/ServiceProperties.java`）滿足以下需求： ~~~ package com.example.multimodule.service; import org.springframework.boot.context.properties.ConfigurationProperties; @ConfigurationProperties("service") public class ServiceProperties { /** * A message for the service. */ private String message; public String getMessage() { return message; } public void setMessage(String message) { this.message = message; } } ~~~ 您不必這樣做。一個庫可能只提供純Java API，而沒有Spring功能。在這種情況下，使用該庫的應用程序將需要自行提供配置。 ## 測試服務組件您將要為庫組件編寫單元測試。如果您將可重用的Spring配置作為庫的一部分提供，則可能還需要編寫一個集成測試，以確保該配置可以正常工作。為此，您可以使用JUnit和 `@SpringBootTest`注解。以下清單（來自 `library/src/test/java/com/example/multimodule/service/MyServiceTest.java`）顯示了如何執行此操作： ~~~ package com.example.multimodule.service; import static org.assertj.core.api.Assertions.assertThat; import org.junit.jupiter.api.Test; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.boot.autoconfigure.SpringBootApplication; import org.springframework.boot.test.context.SpringBootTest; @SpringBootTest("service.message=Hello") public class MyServiceTest { @Autowired private MyService myService; @Test public void contextLoads() { assertThat(myService.message()).isNotNull(); } @SpringBootApplication static class TestConfiguration { } } ~~~ 在前面的清單中，我們已經配置了 service.message 通過使用的默認屬性進行測試 @SpringBootTest注解。我們不建議放置 application.properties 在庫中，因為在運行時與使用該庫的應用程序可能會發生沖突（只有一個 application.properties從classpath加載）。你可以放 application.properties 在測試類路徑中，但不將其包含在jar中（例如，通過將其放置在 src/test/resources). ## 創建應用程序項目 Application項目使用Library項目，該項目提供了其他項目可以使用的服務。 ### 創建目錄結構在里面 `application` 目錄中，創建以下子目錄結構（例如，帶有 `mkdir -p src/main/java/com/example/multimodule/application` 在\* nix系統上）： ~~~ └── src └── main └── java └── com └── example └── multimodule └── application ~~~ 除非要通過以下方式在庫中包含所有Spring組件，否則請不要使用與庫相同的包（或庫包的父級）。 `@ComponentScan` 在應用程序中。 ### 設置應用程序項目對于Application項目，您需要Spring Web和Spring Boot Actuator依賴項。您可以直接從獲取具有必要依賴項的Maven構建文件 [Spring Initializr](https://start.spring.io/#!type=maven-project&language=java&platformVersion=2.4.2.RELEASE&packaging=jar&jvmVersion=11&groupId=com.example&artifactId=multi-module-application&name=multi-module-application&description=Demo%20project%20for%20Spring%20Boot&packageName=com.example.multi-module-application&dependencies=web,actuator) 。以下清單顯示了 `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/>  </parent> <groupId>com.example</groupId> <artifactId>multi-module-application</artifactId> <version>0.0.1-SNAPSHOT</version> <name>multi-module-application</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-actuator</artifactId> </dependency> <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.2.RELEASE&packaging=jar&jvmVersion=11&groupId=com.example&artifactId=multi-module-application&name=multi-module-application&description=Demo%20project%20for%20Spring%20Boot&packageName=com.example.multi-module-application&dependencies=web,actuator) 。以下清單顯示了 `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-actuator' implementation 'org.springframework.boot:spring-boot-starter-web' testImplementation 'org.springframework.boot:spring-boot-starter-test' } ~~~ 您可以刪除 `mvnw` 和/或 `gradlew` 包裝器及其關聯的配置文件： ~~~ $ rm -rf mvnw* .mvn $ rm -rf gradlew* gradle ~~~ #### 添加庫依賴 Application項目需要依賴Library項目。您需要相應地修改您的應用程序構建文件。對于Maven，添加以下依賴項： ~~~ <dependency> <groupId>com.example</groupId> <artifactId>library</artifactId> <version>${project.version}</version> </dependency> ~~~ 以下清單顯示了成品 `pom.xml` 文件： ~~~ <?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/>  </parent> <groupId>com.example</groupId> <artifactId>multi-module-application</artifactId> <version>0.0.1-SNAPSHOT</version> <name>multi-module-application</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-actuator</artifactId> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> <dependency> <groupId>com.example</groupId> <artifactId>library</artifactId> <version>${project.version}</version> </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，添加以下依賴項： ~~~ implementation project(':library') ~~~ 以下清單顯示了成品 `build.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-actuator' implementation 'org.springframework.boot:spring-boot-starter-web' implementation project(':library') testImplementation 'org.springframework.boot:spring-boot-starter-test' } ~~~ ## 編寫申請應用程序中的主要類可以是 `@RestController` 使用 `Service`從庫中渲染一條消息。以下清單（來自 `application/src/main/java/com/example/multimodule/application/DemoApplication.java`）顯示了這樣的類： ~~~ package com.example.multimodule.application; import com.example.multimodule.service.MyService; import org.springframework.boot.SpringApplication; import org.springframework.boot.autoconfigure.SpringBootApplication; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RestController; @SpringBootApplication(scanBasePackages = "com.example.multimodule") @RestController public class DemoApplication { private final MyService myService; public DemoApplication(MyService myService) { this.myService = myService; } @GetMapping("/") public String home() { return myService.message(); } public static void main(String[] args) { SpringApplication.run(DemoApplication.class, args); } } ~~~ `@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，因此您無需處理任何管道或基礎結構。因為 `DemoApplication` 在不同的包裝內（ `com.example.multimodule.application`）比 `MyService` ( `com.example.multimodule.service`), `@SpringBootApplication`無法自動檢測到它。有多種方法可以使MyService生效： * 直接將其導入 `@Import(MyService.class)`. * 使用以下命令從包中獲取所有內容 `@SpringBootApplication(scanBasePackageClasses={…?})`. * 通過名稱指定父包： `com.example.multimodule`。（本指南使用此方法）如果您的應用程序還使用JPA或Spring Data，則 @EntityScan 和 @EnableJpaRepositories （和相關）批注僅繼承其基本包 @SpringBootApplication未明確指定時。也就是說，一旦您指定 scanBasePackageClasses 或者 scanBasePackages，您可能還必須明確使用 @EntityScan 和 @EnableJpaRepositories 顯式配置其程序包掃描。 ## 創建 `application.properties` 文件您需要在以下位置的庫中提供有關該服務的消息 `application.properties`。在源文件夾中，您需要創建一個名為 `src/main/resources/application.properties`。以下清單顯示了一個可以工作的文件： ~~~ service.message=Hello, World ~~~ ## 測試應用通過啟動應用程序來測試端到端結果。您可以在IDE中啟動應用程序，也可以使用命令行。應用程序運行后，請在瀏覽器中訪問客戶端應用程序，網址為： `[http://localhost:8080/](http://localhost:8080/)`。在那里，你應該看到 `Hello, World` 反映在回應中。如果您使用Gradle，則以下命令（實際上是依次執行兩個命令）將首先構建庫，然后運行應用程序： ~~~ $ ./gradlew build && ./gradlew :application:bootRun ~~~ 如果使用Maven，則以下命令（實際上是依次執行兩個命令）將首先構建庫，然后運行應用程序： ~~~ $ ./mvnw install && ./mvnw spring-boot:run -pl application ~~~ ## 概括恭喜你！您已經使用Spring Boot創建了可重用的庫，然后使用該庫來構建應用程序。