Spring Cloud Connectors 中文文档参考手册中文版

介绍

Spring Cloud Connectors为在云平台上运行的基于JVM的应用程序提供了一个简单的抽象，可以在运行时发现绑定的服务和部署信息，并且支持将发现的服务注册为Spring bean。它基于插件模型，以便相同的编译应用程序可以在本地或任何多个云平台上进行部署，并通过Java服务提供程序接口（SPI）支持定制服务定义。

“连接器”项目提供即时支持，用于发现Heroku和Cloud Foundry云上的常见服务。它还包括一个基于属性的连接器，可以为开发和测试提供配置。

概念

核心连接器概念如下所述。

云连接器

一个特定于平台的界面，用于标识平台的存在并发现绑定到应用程序部署的任何服务。

服务连接器

表示与服务的运行时连接的对象（例如，javax.sql.DataSource）。

服务信息

有关底层服务的信息（如主机，端口和凭据）。

应用程序信息

有关应用程序和特定运行实例的信息。

子模块

该项目包含三个主要子模块。

Spring Cloud Connectors核心：核心图书馆与云不相关和Spring无关。它为喜欢手动访问云服务和应用程序信息的开发人员提供了编程入口点。它还为几个常用服务（数据库，消息队列）和基于SPI的扩展机制提供基本服务定义，用于贡献云和服务连接器。
Spring Cloud Spring服务连接器：将应用程序信息，云信息和发现的服务公开为Spring适合类型的bean的Spring库（例如，SQL服务将作为javax.sql.DataSource可选连接池）。
云连接器：
- Spring Cloud Cloud Foundry连接器：Cloud Foundry的连接器。
- Spring Cloud Heroku连接器：Heroku的连接器。
- Spring Cloud本地配置连接器：基于属性的连接器，用于在开发或测试期间手动提供配置信息。允许在应用程序部署的所有阶段使用相同的Spring Cloud Connectors配置接线。

入门

有关如何使用构建系统包含适当依赖关系的示例，请参见下文。

包括云连接器

包括您想要发现的每个云平台的连接器。包括多个连接器是完美的; 每个连接器将确定它是否应在特定环境中处于活动状态。

在Maven中，使用所需的工件版本替换${VERSION}：

<!-- To use Spring Cloud Connectors for development -->
<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-localconfig-connector</artifactId>
    <version>${VERSION}</version>
</dependency>

<!-- If you intend to deploy the app to Cloud Foundry -->
<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-cloudfoundry-connector</artifactId>
    <version>${VERSION}</version>
</dependency>

<!-- If you intend to deploy the app to Heroku -->
<dependency>
  <groupId>org.springframework.cloud</groupId>
  <artifactId>spring-cloud-heroku-connector</artifactId>
  <version>${VERSION}</version>
</dependency>

在Gradle中，用所需的版本替换${VERSION}：

dependencies {

    // To use Spring Cloud Connectors for development
    compile 'org.springframework.cloud:spring-cloud-localconfig-connector:${VERSION}'

    // If you intend to deploy the app to Cloud Foundry
    compile 'org.springframework.cloud:spring-cloud-cloudfoundry-connector:${VERSION}'

    // If you intend to deploy the app to Heroku
    compile 'org.springframework.cloud:spring-cloud-heroku-connector:${VERSION}'

}

Spring应用程序

如果您正在撰写Spring应用程序，则除了包含云连接器依赖项之外，还包括Spring服务连接器依赖项。

在Maven：

<dependency>
  <groupId>org.springframework.cloud</groupId>
  <artifactId>spring-cloud-spring-service-connector</artifactId>
  <version>${VERSION}</version>
</dependency>

在毕业：

dependencies {

    compile 'org.springframework.cloud:spring-cloud-spring-service-connector:${VERSION}'

}

然后使用Java配置或<cloud>命名空间，按照Spring配置中的Spring服务连接器文档中的说明进行操作。

非Spring应用程序

每个云连接器都包含spring-cloud-core依赖关系，因此只需要包含所需平台的连接器即可。然后按照使用Spring Cloud Connectors API的说明进行操作。

Spring Cloud Connectors核心

该核心库提供对应用程序和服务信息的编程访问。该库没有Spring依赖关系，可以在非Spring应用程序中使用。

该库需要Java 6或更新版本。这是云不可知的; 使用Java SPI，它支持可插拔云和服务连接器。除了本地提供的开发和测试配置之外，支持Cloud Foundry和Heroku可以开箱即用。

连接云端

注意	如果您在Spring应用程序中使用Spring Cloud Connectors，则应考虑自动注入Spring bean。

在运行时类路径中包含所需的云连接器，如主要文档中所述。
创建一个CloudFactory实例。创建CloudFactory实例有点贵，所以我们建议使用单例实例。如果您使用依赖注入框架（例如Spring），则为CloudFactory创建一个bean。
```
CloudFactory cloudFactory = new CloudFactory();
```
获取运行应用程序的环境的Cloud对象。
```
Cloud cloud = cloudFactory.getCloud();
```
请注意，您的类路径上必须有适合您的部署环境的CloudConnector。例如，如果要将应用程序部署到Cloud Foundry，则必须将Cloud Foundry连接器添加到类路径中。如果没有找到合适的CloudConnector，getCloud()方法将会抛出一个CloudException。

使用Cloud实例访问应用程序和服务信息并创建服务连接器。

// ServiceInfo has all the information necessary to connect to the underlying service
List<ServiceInfo> serviceInfos = cloud.getServiceInfos();

// Find the `ServiceInfo` definitions suitable for connecting to a particular service type
List<ServiceInfo> databaseInfos = cloud.getServiceInfos(DataSource.class);

// Alternatively, let Spring Cloud Connectors create a service connector for you
String serviceId = "inventory-db";
DataSource ds = cloud.getServiceConnector(serviceId, DataSource.class,
                                            null /* default config */);

Spring服务连接器

Spring服务连接器为Spring应用程序创建服务连接对象。它允许连接bean的Java或XML配置，目前通过javax.sql.DataSource，SMTP通过org.springframework.mail.MailSender，RabbitMQ通过Spring AMQP，以及MongoDB和Redis通过Spring支持MySQL和PostgreSQL等关系数据库。数据项目。它还支持连接到通用（例如，私有）服务。

有关此服务连接器的详细信息，请参阅Spring Cloud Spring服务连接器。

Cloud Foundry连接器

Cloud Foundry连接器发现绑定到在Cloud Foundry环境中运行的应用程序的服务。由于它以Cloud Foundry的标准格式消费了绑定的服务信息，它是提供者不可知的; 它目前知道应用程序监视，DB2，MongoDB，MySQL，Oracle，PostgreSQL，RabbitMQ，Redis，SMTP和SQL Server服务。

有关此云连接器的详细信息，请参阅Spring Cloud Cloud Foundry连接器。

Heroku连接器

Heroku连接器发现绑定到运行在Heroku中的应用程序的服务。它目前知道PostgreSQL（由{4}提供），MySQL（由ClearDB提供），Redis（由Redis To Go提供，Redis Cloud，RedisGreen，openredis和Heroku），MongoDB（由mLab提供） MongoHQ和MongoSoup）和RabbitMQ（由CloudAMQP提供）。它可以扩展到支持这些服务的其他提供商。

有关此云连接器的详细信息，请参阅Spring Cloud Heroku连接器。

本地配置连接器

此连接器可以在本地配置Spring Cloud Connectors服务以进行开发或测试。当前的实现只从Java属性读取。

快速开始

由于服务URI包含密码，不应存储在代码中，此连接器不会尝试从类路径中读取服务定义。您可以提供服务定义作为系统属性。

java -Dspring.cloud.database='mysql://user:pass@host:1234/dbname' -jar my-app.jar

您还可以通过设置spring.cloud.propertiesFile系统属性从配置属性文件提供服务定义：

java -Dspring.cloud.propertiesFile=/path/to/spring-cloud.properties -jar my-app.jar

或者通过在运行时类路径上提供引导属性文件spring-cloud-bootstrap.properties。该文件将仅对名为spring.cloud.propertiesFile的属性进行检查，其值将从系统属性内插。

spring.cloud.propertiesFile: ${user.home}/.config/myApp/spring-cloud.properties

系统属性或配置属性文件应包含以下格式的应用程序ID和所需的服务。

spring.cloud.appId:    myApp
; spring.cloud.{id}:   URI
spring.cloud.database: mysql://user:pass@host:1234/dbname

服务类型由URI方案决定。如果找到名为spring.cloud.appId的属性（在系统属性或配置属性文件中），连接器将激活。

物业来源

此连接器首先尝试具体读取系统属性和名为spring.cloud.propertiesFile的系统属性。如果系统属性不可读（如果安全管理器拒绝checkPropertiesAccess），则它们将被视为空。如果找到名为spring.cloud.propertiesFile的系统属性，则该文件将作为属性列表加载。

提供引导属性文件

为了避免使用配置属性文件的路径手动配置运行配置或测试跑步者，连接器可以读取运行时类路径中的模板文件名。该文件必须命名为spring-cloud-bootstrap.properties并位于classpath根目录下。为了安全起见，连接器不会尝试从文件中读取任何服务URI。如果连接器找到该文件，它将读取属性spring.cloud.propertiesFile，并使用系统属性中相应的值替换模式${system.property}。最有用的选项通常是${user.home}。

系统属性中指定的配置属性文件将覆盖类路径中可用的任何引导文件。

属性优先级

为了提供最大的配置灵活性，连接器将覆盖在运行时定义的系统属性的spring.cloud.propertiesFile文件中指定的任何属性（应用程序ID和服务定义）。如果覆盖服务ID，连接器将在WARN上记录消息。

激活连接器

Spring Cloud Connectors Core预计只有一个云连接器可以匹配运行时环境。此连接器通过属性的存在，在配置属性文件或名为spring.cloud.appId的系统属性中标识“本地云”。此属性将在ApplicationInstanceInfo中使用。

服务定义

如果连接器被激活，它将遍历与模式spring.cloud.{serviceId}匹配的键的所有可用属性。每个值被解释为服务的URI，并且从该方案确定服务的类型。支持每个标准UriBasedServiceInfo。

实例ID

此连接器创建一个用作实例ID的UUID，因为Java不提供用于可靠地确定主机名或PID的任何便携式机制。

扩展Spring Cloud Connectors

除了内置的服务和云支持外，还包括Spring服务连接器，Spring Cloud Connectors可以扩展到支持额外的云平台，云服务或应用程序框架。详见下文。

可扩展性概述

如“ 包含云连接器”部分所述，您的应用程序可以包括多个云平台的云连接器。Spring Cloud Connectors Core激活运行应用程序的平台的CloudConnector。该云连接器的ServiceInfoCreator类针对应用程序的服务创建ServiceInfo对象，ServiceConnectorCreator类使用ServiceInfo对象创建服务连接对象，以在应用程序中使用。

您可以通过以下三种方式扩展Spring Cloud Connectors：

云平台支持。开箱即用Spring Cloud Connectors支持Cloud Foundry和Heroku平台。您可以扩展Spring Cloud Connectors来为其他云平台和提供商提供支持。

Spring Cloud Connectors使用该CloudConnector界面提供云平台支持。特定云平台的CloudConnector实施负责检测应用程序在该云平台上运行的时间，从云平台获取有关应用程序的信息，以及获取有关应用程序绑定的服务的信息。
云服务支持。您可以扩展Spring Cloud Connectors以支持其他服务，包括特定于您自己的环境或应用程序的服务。

Spring Cloud Connectors使用两个接口来提供云服务支持：
- A ServiceInfo建立连接到服务所需的信息。在数据库服务的情况下，ServiceInfo实现可能包括主机，端口，数据库名称，用户名和密码的字段; 在Web服务的情况下，它可能包含URL和API密钥的字段。
- A ServiceInfoCreator根据云连接器收集的服务信息创建ServiceInfo对象。一个ServiceInfoCreator实现是专门针对云平台的。
应用框架支持。的Spring Cloud Spring服务连接器将创建服务连接器Spring数据的数据类型。您可以使用另一个框架来扩展Spring Cloud Connectors来提供服务连接对象。

Spring Cloud Connectors使用ServiceConnectorCreator接口提供框架支持。A ServiceConnectorCreator使用ServiceInfo对象提供的服务连接信息创建服务连接器。

添加云平台支持

要允许Spring Cloud Connectors检测新的云平台，请为平台添加云连接器。

云连接器确定应用程序是否在特定云中运行，标识应用程序信息（例如特定运行实例的名称和实例ID），并将绑定的服务（例如环境变量中暴露的URI）映射为ServiceInfo对象。

提示	有关示例，请参阅Cloud Foundry连接器和Heroku连接器。

Spring Cloud Connectors使用Java SPI来发现可用的连接器。

您的连接器类必须实现CloudConnector接口，其中包括三种方法：

boolean isInMatchingCloud()：确定连接器是否在其提供支持的云中运行。

Spring Cloud Connectors包含在应用程序中的每个云连接器上的核心呼叫isInMatchingCloud()，并激活响应true的第一个连接器。
ApplicationInstanceInfo getApplicationInstanceInfo()：返回有关正在运行的应用程序实例的信息。

一个ApplicationInstanceInfo必须提供实例ID（String）和应用程序标识（String）。可以根据需要将其他属性添加到Map，并通过getProperties()返回。
List<ServiceInfo> getServiceInfos()：为应用程序绑定的每个服务返回一个ServiceInfo对象。

如果没有任何服务被绑定到应用程序，getServiceInfos()可以返回一个空的List。

新的云连接器应在提供者配置文件META-INF/services/org.springframework.cloud.CloudConnector中列出完全限定的类名。

添加服务支持

要允许Spring Cloud Connectors发现新的服务类型，请创建一个ServiceInfo包含连接到服务所需信息的类。如果您可以通过URI指定服务，请UriBasedServiceInfo在调用super构造函数时扩展并提供URI方案。

以下课程会向helloworld://username:password@host:port/Bonjour提供HelloWorldService的信息。

public class HelloWorldServiceInfo extends UriBasedServiceInfo {
    public static final String URI_SCHEME = "helloworld";

  // Needed to support structured service definitions such as Cloud Foundry's
    public HelloWorldServiceInfo(String id, String host, int port, String username, String password, String greeting) {
    super(id, URI_SCHEME, host, port, username, password, greeting);
    }

    // Needed to support URI-based service definitions such as Heroku's
    public HelloWorldServiceInfo(String id, String uri) {
        super(id, uri);
    }
}

创建ServiceInfo类后，您将需要ServiceInfoCreator为每个要支持的云平台创建一个。如果您为Spring Cloud Connectors已经支持的云平台添加服务支持，则可能需要扩展相应的创建者基类。

Cloud Foundry

扩展CloudFoundryServiceInfoCreator。

Heroku

延长HerokuServiceInfoCreator。

本地配置

扩展LocalConfigServiceInfoCreator。

一个ServiceInfoCreator通常可以像实例化新的ServiceInfo的方法一样简单。

@Override
public HelloWorldServiceInfo createServiceInfo(String id, String uri) {
  return new HelloWorldServiceInfo(id, uri);
}

在您的云的ServiceInfoCreator基类的相应提供商配置文件中注册您的ServiceInfoCreator类。

Cloud Foundry

将创建者的完全限定类名添加到META-INF/services/org.springframework.cloud.cloudfoundry.CloudFoundryServiceInfoCreator。

Heroku

将您的创建者的完全限定类名添加到META-INF/services/org.springframework.cloud.heroku.HerokuServiceInfoCreator。

本地配置

将您的创建者的完全限定类名添加到META-INF/services/org.springframework.cloud.localconfig.LocalConfigServiceInfoCreator。

添加框架支持

要允许Spring Cloud Connectors为支持的云服务提供框架特定的服务对象，请为框架添加服务连接器。

服务连接器为云连接器发现的服务消耗ServiceInfo，并将其转换为适当的服务对象（例如在代表SQL数据库的服务定义的情况下为DataSource）。

提示	服务连接器可以紧密绑定到正在创建其服务对象的框架。例如，Spring服务连接器中的一些连接器创建由Spring数据定义的连接工厂，用于构建Spring数据模板。

你的连接器类必须实现ServiceConnectorCreator接口，它有三种方法：

SC create()：从给定的ServiceInfo和配置创建服务连接对象。
Class<SC> getServiceConnectorType()：返回要创建的连接对象的类型。
Class<?> getServiceInfoType()：返回类接受的类型ServiceInfo。

在提供者配置文件META-INF/services/org.springframework.cloud.service.ServiceConnectorCreator中列出完全限定的连接器类名。