Cloud Foundry Java Client 技术文档

1. 安装指南

Maven 依赖

要在 Maven 项目中使用 Cloud Foundry Java Client，需要在 pom.xml 文件中添加以下依赖：

<dependencies>
    <dependency>
        <groupId>org.cloudfoundry</groupId>
        <artifactId>cloudfoundry-client-reactor</artifactId>
        <version>latest.RELEASE</version>
    </dependency>
    <dependency>
        <groupId>org.cloudfoundry</groupId>
        <artifactId>cloudfoundry-operations</artifactId>
        <version>latest.RELEASE</version>
    </dependency>
</dependencies>

如果需要使用快照版本，还需要添加 Spring 快照仓库：

<repositories>
    <repository>
        <id>spring-snapshots</id>
        <name>Spring Snapshots</name>
        <url>https://repo.spring.io/snapshot</url>
        <snapshots>
            <enabled>true</enabled>
        </snapshots>
    </repository>
</repositories>

Gradle 依赖

在 Gradle 项目中，依赖配置如下：

dependencies {
    compile 'org.cloudfoundry:cloudfoundry-client-reactor:<latest>.RELEASE'
    compile 'org.cloudfoundry:cloudfoundry-operations:<latest>.RELEASE'
}

同样，如果需要使用快照版本，需要添加 Spring 快照仓库：

repositories {
    maven { url 'https://repo.spring.io/snapshot' }
}

2. 项目的使用说明

项目结构

Cloud Foundry Java Client 项目分为以下几个组件：

• cloudfoundry-client：映射到 Cloud Foundry REST API 的接口、请求和响应对象。该项目没有实现，因此无法单独连接到 Cloud Foundry 实例。
• cloudfoundry-client-reactor：cloudfoundry-client 项目的默认实现，基于 Reactor Netty 的 HttpClient。
• cloudfoundry-operations：对应于 Cloud Foundry CLI 操作的 API 和实现。该项目构建在 cloudfoundry-client 之上，因此只有一个实现。

版本兼容性

• 5.x 版本兼容 Spring Boot 2.4.x - 2.6.x。
• 4.x 版本使用 Spring Boot 2.3.x。

3. 项目API使用文档

CloudFoundryClient, DopplerClient, UaaClient 构建器

最低级别的 API 构建块是 ConnectionContext 和 TokenProvider。这些类型旨在在客户端实例之间共享，并带有开箱即用的实现。可以通过构建器来实例化它们：

DefaultConnectionContext.builder()
    .apiHost(apiHost)
    .build();

PasswordGrantTokenProvider.builder()
    .password(password)
    .username(username)
    .build();

在 Spring 应用程序中，可以将它们封装在 bean 定义中：

@Bean
DefaultConnectionContext connectionContext(@Value("${cf.apiHost}") String apiHost) {
    return DefaultConnectionContext.builder()
        .apiHost(apiHost)
        .build();
}

@Bean
PasswordGrantTokenProvider tokenProvider(@Value("${cf.username}") String username,
                                         @Value("${cf.password}") String password) {
    return PasswordGrantTokenProvider.builder()
        .password(password)
        .username(username)
        .build();
}

CloudFoundryClient, DopplerClient, 和 UaaClient 是接口，每个接口都有一个基于 Reactor 的实现。可以通过构建器来实例化它们：

ReactorCloudFoundryClient.builder()
    .connectionContext(connectionContext)
    .tokenProvider(tokenProvider)
    .build();

ReactorDopplerClient.builder()
    .connectionContext(connectionContext)
    .tokenProvider(tokenProvider)
    .build();

ReactorUaaClient.builder()
    .connectionContext(connectionContext)
    .tokenProvider(tokenProvider)
    .build();

在 Spring 应用程序中，可以将它们封装在 bean 定义中：

@Bean
ReactorCloudFoundryClient cloudFoundryClient(ConnectionContext connectionContext, TokenProvider tokenProvider) {
    return ReactorCloudFoundryClient.builder()
        .connectionContext(connectionContext)
        .tokenProvider(tokenProvider)
        .build();
}

@Bean
ReactorDopplerClient dopplerClient(ConnectionContext connectionContext, TokenProvider tokenProvider) {
    return ReactorDopplerClient.builder()
        .connectionContext(connectionContext)
        .tokenProvider(tokenProvider)
        .build();
}

@Bean
ReactorUaaClient uaaClient(ConnectionContext connectionContext, TokenProvider tokenProvider) {
    return ReactorUaaClient.builder()
        .connectionContext(connectionContext)
        .tokenProvider(tokenProvider)
        .build();
}

CloudFoundryOperations 构建器

CloudFoundryOperations 层提供了更高级别的抽象，适合大多数用户使用。可以通过构建器来实例化 DefaultCloudFoundryOperations：

DefaultCloudFoundryOperations.builder()
    .cloudFoundryClient(cloudFoundryClient)
    .dopplerClient(dopplerClient)
    .uaaClient(uaaClient)
    .organization("example-organization")
    .space("example-space")
    .build();

在 Spring 应用程序中，可以将它封装在 bean 定义中：

@Bean
DefaultCloudFoundryOperations cloudFoundryOperations(CloudFoundryClient cloudFoundryClient,
                                                     DopplerClient dopplerClient,
                                                     UaaClient uaaClient,
                                                     @Value("${cf.organization}") String organization,
                                                     @Value("${cf.space}") String space) {
    return DefaultCloudFoundryOperations.builder()
            .cloudFoundryClient(cloudFoundryClient)
            .dopplerClient(dopplerClient)
            .uaaClient(uaaClient)
            .organization(organization)
            .space(space)
            .build();
}

CloudFoundryOperations API

一旦获得了 CloudFoundryOperations 的引用，就可以开始调用 Cloud Foundry 实例的 API。以下是一个简单的示例，列出用户所属的所有组织：

cloudFoundryOperations.organizations()
    .list()
    .map(OrganizationSummary::getName)
    .subscribe(System.out::println);

CloudFoundryClient API

cloudfoundry-operations 实现构建在 cloudfoundry-client API 之上。以下是 Organizations.list() 方法的实现示例：

cloudFoundryClient.organizations()
    .list(ListOrganizationsRequest.builder()
        .page(1)
        .build())
    .flatMapIterable(ListOrganizationsResponse::getResources)
    .map(resource -> OrganizationSummary.builder()
        .id(resource.getMetadata().getId())
        .name(resource.getEntity().getName())
        .build());

4. 项目安装方式

项目的安装方式主要是通过 Maven 或 Gradle 添加依赖来实现。具体步骤请参考 安装指南 部分。