Quick Start

本快速入门教程将介绍如何将 Spring Cloud Consul 用于服务发现和分布式配置。

This quick start walks through using Spring Cloud Consul for Service Discovery and Distributed Configuration.

首先，在机器上运行 Consul Agent。然后，您可以访问它并将其用作具有 Spring Cloud Consul 的服务注册表和配置源。

First, run Consul Agent on your machine. Then you can access it and use it as a Service Registry and Configuration source with Spring Cloud Consul.

Discovery Client Usage

要在应用程序中使用这些功能，可以将其构建为依赖于 spring-cloud-consul-core 的 Spring Boot 应用程序。添加依赖项最便捷的方法是使用 Spring Boot Starter：org.springframework.cloud:spring-cloud-starter-consul-discovery。我们建议使用依赖管理和 spring-boot-starter-parent。以下示例显示了一个典型的 Maven 配置：

To use these features in an application, you can build it as a Spring Boot application that depends on spring-cloud-consul-core. The most convenient way to add the dependency is with a Spring Boot starter: org.springframework.cloud:spring-cloud-starter-consul-discovery. We recommend using dependency management and spring-boot-starter-parent. The following example shows a typical Maven configuration:

pom.xml
<project>
<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>{spring-boot-version}</version>
    <relativePath/> <!-- lookup parent from repository -->
  </parent>

  <dependencies>
    <dependency>
      <groupId>org.springframework.cloud</groupId>
      <artifactId>spring-cloud-starter-consul-discovery</artifactId>
    </dependency>
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-test</artifactId>
      <scope>test</scope>
    </dependency>
  </dependencies>
  <dependencyManagement>
    <dependencies>
      <dependency>
        <groupId>org.springframework.cloud</groupId>
        <artifactId>spring-cloud-dependencies</artifactId>
        <version>${spring-cloud.version}</version>
        <type>pom</type>
        <scope>import</scope>
      </dependency>
    </dependencies>
  </dependencyManagement>
  <build>
    <plugins>
      <plugin>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-maven-plugin</artifactId>
      </plugin>
    </plugins>
  </build>
</project>

以下示例展示了一个典型的 Gradle 设置：

The following example shows a typical Gradle setup:

build.gradle
plugins {
  id 'org.springframework.boot' version ${spring-boot-version}
  id 'io.spring.dependency-management' version ${spring-dependency-management-version}
  id 'java'
}

repositories {
  mavenCentral()
}

dependencies {
  implementation 'org.springframework.cloud:spring-cloud-starter-consul-discovery'
  testImplementation 'org.springframework.boot:spring-boot-starter-test'
}
dependencyManagement {
  imports {
    mavenBom "org.springframework.cloud:spring-cloud-dependencies:${springCloudVersion}"
  }
}

现在，您可以创建标准的 Spring Boot 应用程序，例如以下 HTTP 服务器：

Now you can create a standard Spring Boot application, such as the following HTTP server:

@SpringBootApplication
@RestController
public class Application {

    @GetMapping("/")
    public String home() {
        return "Hello World!";
    }

    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }

}

当该 HTTP 服务器运行时，它将连接到在默认本地 8500 端口上运行的 Consul Agent。要修改启动行为，您可以使用 application.properties 更改 Consul Agent 的位置，如下例所示：

When this HTTP server runs, it connects to Consul Agent running at the default local 8500 port. To modify the startup behavior, you can change the location of Consul Agent by using application.properties, as shown in the following example:

spring:
  cloud:
    consul:
      host: localhost
      port: 8500

现在，您可以使用 DiscoveryClient、@LoadBalanced RestTemplate 或 @LoadBalanced WebClient.Builder 从 Consul 检索服务和实例数据，如下例所示：

You can now use DiscoveryClient, @LoadBalanced RestTemplate, or @LoadBalanced WebClient.Builder to retrieve services and instances data from Consul, as shown in the following example:

@Autowired
private DiscoveryClient discoveryClient;

public String serviceUrl() {
    List<ServiceInstance> list = discoveryClient.getInstances("STORES");
    if (list != null && list.size() > 0 ) {
        return list.get(0).getUri().toString();
    }
    return null;
}

Distributed Configuration Usage

要在应用程序中使用这些功能，可以将其构建为依赖于 spring-cloud-consul-core 和 spring-cloud-consul-config 的 Spring Boot 应用程序。添加依赖项最便捷的方法是使用 Spring Boot Starter：org.springframework.cloud:spring-cloud-starter-consul-config。我们建议使用依赖管理和 spring-boot-starter-parent。以下示例显示了一个典型的 Maven 配置：

To use these features in an application, you can build it as a Spring Boot application that depends on spring-cloud-consul-core and spring-cloud-consul-config. The most convenient way to add the dependency is with a Spring Boot starter: org.springframework.cloud:spring-cloud-starter-consul-config. We recommend using dependency management and spring-boot-starter-parent. The following example shows a typical Maven configuration:

pom.xml
<project>
<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>{spring-boot-version}</version>
    <relativePath/> <!-- lookup parent from repository -->
  </parent>

  <dependencies>
    <dependency>
      <groupId>org.springframework.cloud</groupId>
      <artifactId>spring-cloud-starter-consul-config</artifactId>
    </dependency>
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-test</artifactId>
      <scope>test</scope>
    </dependency>
  </dependencies>
  <dependencyManagement>
    <dependencies>
      <dependency>
        <groupId>org.springframework.cloud</groupId>
        <artifactId>spring-cloud-dependencies</artifactId>
        <version>${spring-cloud.version}</version>
        <type>pom</type>
        <scope>import</scope>
      </dependency>
    </dependencies>
  </dependencyManagement>
  <build>
    <plugins>
      <plugin>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-maven-plugin</artifactId>
      </plugin>
    </plugins>
  </build>
</project>

以下示例展示了一个典型的 Gradle 设置：

The following example shows a typical Gradle setup:

build.gradle
plugins {
  id 'org.springframework.boot' version ${spring-boot-version}
  id 'io.spring.dependency-management' version ${spring-dependency-management-version}
  id 'java'
}

repositories {
  mavenCentral()
}

dependencies {
  implementation 'org.springframework.cloud:spring-cloud-starter-consul-config'
  testImplementation 'org.springframework.boot:spring-boot-starter-test'
}
dependencyManagement {
  imports {
    mavenBom "org.springframework.cloud:spring-cloud-dependencies:${springCloudVersion}"
  }
}

现在，您可以创建标准的 Spring Boot 应用程序，例如以下 HTTP 服务器：

Now you can create a standard Spring Boot application, such as the following HTTP server:

@SpringBootApplication
@RestController
public class Application {

    @GetMapping("/")
    public String home() {
        return "Hello World!";
    }

    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }

}

该应用程序从 Consul 检索配置数据。

The application retrieves configuration data from Consul.

如果你使用 Spring Cloud Consul Config，则需要设置 spring.config.import 属性以便绑定到 Consul。你可以在 Spring Boot Config Data Import section 中阅读更多相关内容。

If you use Spring Cloud Consul Config, you need to set the spring.config.import property in order to bind to Consul. You can read more about it in the Spring Boot Config Data Import section.