在 Linux 上创建第一个 Java Service Fabric Reliable Actors 应用程序

项目
07/03/2023

借助本快速入门，只需几分钟即可在 Linux 开发环境中创建第一个 Azure Service Fabric Java 应用程序。完成后，即拥有一个在本地开发群集上运行的简单 Java 单一服务应用程序。

先决条件

开始之前，请安装 Service Fabric SDK、Service Fabric CLI、Yeoman，设置 Java 开发环境，并在 Linux 开发环境中设置开发群集。如果使用 Mac OS X，则可使用 Docker 在 Mac 上设置开发环境。

另请安装 Service Fabric CLI。

为 Java 安装和设置生成器

Service Fabric 提供基架工具，可以借助此类工具，使用 Yeoman 模板生成器从终端创建 Service Fabric Java 应用程序。如果尚未安装 Yeoman，请参阅 Service Fabric 入门（使用 Linux），获取有关如何设置 Yeoman 的说明。运行以下命令，安装用于 Java 的 Service Fabric Yeoman 模板生成器。

npm install -g generator-azuresfjava

基本概念

若要开始使用 Reliable Actors，只需了解几个基本概念：

执行组件服务。可以在 Service Fabric 基础结构中部署的 Reliable Services 中打包 Reliable Actors。执行组件实例在命名的服务实例中激活。
执行组件注册。与 Reliable Services 一样，Reliable Actor 服务也需要注册到 Service Fabric 运行时。此外，需要将执行组件类型注册到执行组件运行时。
执行组件接口。执行组件接口用于定义执行组件的强类型公共接口。在 Reliable Actor 模型术语中，执行组件接口用于定义执行组件可以理解并处理的消息类型。其他执行组件或客户端应用程序使用此执行组件接口将消息“发送”（异步方式）到此执行组件。 Reliable Actors 可实现多个接口。
ActorProxy 类。客户端应用程序使用 ActorProxy 类调用通过执行组件接口公开的方法。 ActorProxy 类提供两个重要功能：
- 名称解析：能够在群集中找到执行组件（查找托管它的群集节点）。
- 故障处理：例如，在需要将执行组件重新定位到群集中另一个节点的故障之后，它可以重试方法调用和重新解析执行组件的位置。

有必要提一下与执行组件接口有关的以下规则：

不能重载执行组件接口方法。
执行组件接口方法不能有输出参数、引用参数或可选参数。
不支持泛型接口。

创建应用程序

Service Fabric 应用程序包含一个或多个服务，每个服务都在提供应用程序功能时具有特定角色。有了在上一部分安装的生成器，就可以轻松地创建第一个服务，并在以后添加更多服务。此外，还可使用适用于 Eclipse 的插件创建、生成和部署 Service Fabric Java 应用程序。请参阅使用 Eclipse 创建和部署第一个 Java 应用程序。对于本快速入门，使用 Yeoman 创建具有单项服务的应用程序，该服务用于存储和获取获取计数器值。

在终端中，键入 yo azuresfjava。
为应用程序命名。
选择第一个服务的类型并将其命名。对于本教程，请选择“Reliable Actor 服务”。有关其他服务类型的详细信息，请参阅 Service Fabric 编程模型概述。

如果将应用程序命名为“HelloWorldActorApplication”，将执行组件命名为“HelloWorldActor”，则会创建以下基架：

HelloWorldActorApplication/
├── build.gradle
├── HelloWorldActor
│   ├── build.gradle
│   ├── settings.gradle
│   └── src
│       └── reliableactor
│           ├── HelloWorldActorHost.java
│           └── HelloWorldActorImpl.java
├── HelloWorldActorApplication
│   ├── ApplicationManifest.xml
│   └── HelloWorldActorPkg
│       ├── Code
│       │   ├── entryPoint.sh
│       │   └── _readme.txt
│       ├── Config
│       │   ├── _readme.txt
│       │   └── Settings.xml
│       ├── Data
│       │   └── _readme.txt
│       └── ServiceManifest.xml
├── HelloWorldActorInterface
│   ├── build.gradle
│   └── src
│       └── reliableactor
│           └── HelloWorldActor.java
├── HelloWorldActorTestClient
│   ├── build.gradle
│   ├── settings.gradle
│   ├── src
│   │   └── reliableactor
│   │       └── test
│   │           └── HelloWorldActorTestClient.java
│   └── testclient.sh
├── install.sh
├── settings.gradle
└── uninstall.sh

Reliable Actors 基本构建基块

前面所述的基本概念可以转化为 Reliable Actor 服务的基本构建块。

执行组件接口

包含执行组件的接口定义。此接口定义执行组件实现和调用执行组件的客户端所共享的执行组件协定，因此合理的做法是在独立于执行组件实现的某个位置定义接口，并且其他多个服务或客户端应用程序可以共享接口。

HelloWorldActorInterface/src/reliableactor/HelloWorldActor.java：

public interface HelloWorldActor extends Actor {
    @Readonly   
    CompletableFuture<Integer> getCountAsync();

    CompletableFuture<?> setCountAsync(int count);
}

执行组件服务

包含执行组件实现和执行组件注册代码。执行组件类实现执行组件接口。这是执行组件的工作位置。

HelloWorldActor/src/reliableactor/HelloWorldActorImpl：

@ActorServiceAttribute(name = "HelloWorldActorService")
@StatePersistenceAttribute(statePersistence = StatePersistence.Persisted)
public class HelloWorldActorImpl extends FabricActor implements HelloWorldActor {
    private Logger logger = Logger.getLogger(this.getClass().getName());

    public HelloWorldActorImpl(FabricActorService actorService, ActorId actorId){
        super(actorService, actorId);
    }

    @Override
    protected CompletableFuture<?> onActivateAsync() {
        logger.log(Level.INFO, "onActivateAsync");

        return this.stateManager().tryAddStateAsync("count", 0);
    }

    @Override
    public CompletableFuture<Integer> getCountAsync() {
        logger.log(Level.INFO, "Getting current count value");
        return this.stateManager().getStateAsync("count");
    }

    @Override
    public CompletableFuture<?> setCountAsync(int count) {
        logger.log(Level.INFO, "Setting current count value {0}", count);
        return this.stateManager().addOrUpdateStateAsync("count", count, (key, value) -> count > value ? count : value);
    }
}

执行组件注册

执行组件服务必须使用 Service Fabric 运行时中的服务类型注册。为了使执行组件服务能够运行执行组件实例，还必须向执行组件服务注册执行组件类型。 ActorRuntime 注册方法为执行组件执行此操作。

HelloWorldActor/src/reliableactor/HelloWorldActorHost：

public class HelloWorldActorHost {

private static final Logger logger = Logger.getLogger(HelloWorldActorHost.class.getName());

public static void main(String[] args) throws Exception {

        try {

            ActorRuntime.registerActorAsync(HelloWorldActorImpl.class, (context, actorType) -> new FabricActorService(context, actorType, (a,b)-> new HelloWorldActorImpl(a,b)), Duration.ofSeconds(10));
            Thread.sleep(Long.MAX_VALUE);
        } catch (Exception e) {
            logger.log(Level.SEVERE, "Exception occurred", e);
            throw e;
        }
    }
}

构建应用程序

Service Fabric Yeoman 模板包含 Gradle 的生成脚本，可用于从终端生成应用程序。 Service Fabric Java 依赖项从 Maven 提取。若要生成和使用 Service Fabric Java 应用程序，需确保已安装 JDK 和 Gradle。如果尚未安装，请参阅 Service Fabric 入门（使用 Linux），获取有关如何安装 JDK 和 Gradle 的说明。

若要生成并打包应用程序，请运行以下命令：

cd HelloWorldActorApplication
gradle

部署应用程序

生成应用程序后，可以将其部署到本地群集。

连接到本地 Service Fabric 群集（该群集必须已设置且正在运行）。
```
sfctl cluster select --endpoint http://localhost:19080
```
运行模板中提供的安装脚本可将应用程序包复制到群集的映像存储区、注册应用程序类型和创建应用程序实例。
```
./install.sh
```

部署生成的应用程序时，其方式与部署任何其他 Service Fabric 应用程序相同。如需详细的说明，请参阅相关文档，了解如何使用 Service Fabric CLI 管理 Service Fabric 应用程序。

这些命令的参数可以在应用程序包内的生成清单中找到。

应用程序部署完以后，请打开浏览器并导航到 Service Fabric Explorer，其地址为 http://localhost:19080/Explorer。然后，展开“应用程序”节点，注意现在有一个条目是用于应用程序类型，另一个条目用于该类型的第一个实例。

重要

必须将证书配置为向 Service Fabric 运行时验证应用程序，才能将应用程序部署到 Azure 中的安全 Linux 群集。这样可便于 Reliable Actors 服务与基础 Service Fabric 运行时 API 通信。若要了解详细信息，请参阅将 Reliable Services 应用程序配置为在 Linux 群集上运行。

启动测试客户端并执行故障转移

执行组件本身不执行任何操作，它们需要其他服务或客户端向其发送消息。执行组件模板包含简单的测试脚本，可用于与执行组件服务交互。

注意

测试客户端使用 ActorProxy 类与执行组件进行通信，执行组件必须在执行组件服务所在的群集内运行或共享相同的 IP 地址空间。可以在本地开发群集所在的计算机上运行测试客户端。但是，若要与远程群集中的执行组件进行通信，必须在处理与执行组件的外部通信的群集上部署网关。

使用监视实用工具运行脚本，查看执行组件服务的输出。测试脚本对角色调用 setCountAsync() 方法来递增计数器，对角色调用 getCountAsync() 方法来获取新的计数器值，并向控制台显示该值。

若为 MAC OS X，需要运行下面的附加命令，将 HelloWorldTestClient 文件夹复制到容器内的某位置。
```
 docker cp HelloWorldTestClient [first-four-digits-of-container-ID]:/home
 docker exec -it [first-four-digits-of-container-ID] /bin/bash
 cd /home
```
```
cd HelloWorldActorTestClient
watch -n 1 ./testclient.sh
```
在 Service Fabric Explorer 中，找到托管角色服务的主要副本的节点。在以下屏幕截图中，该节点是节点 3。主要服务副本处理读写操作。然后将服务状态更改向外复制到次要副本，该副本在下方屏幕截图中的节点 0 和节点 1 上运行。
在“节点”中，单击上一步找到的节点，然后从“操作”菜单中选择“停用(重启)” 。此操作重启运行主要服务副本的节点，并强制故障转移到在其他节点上运行的其中一个次要副本。该次要副本将提升为主要副本，并在其他节点上创建另一次要副本，然后主要副本开始执行读/写操作。节点重启时，请注意来自测试客户端的输出，并注意虽然发生故障转移，但计数器仍继续递增。

删除应用程序

使用模板中提供的卸载脚本可从群集的映像存储区删除应用程序实例、注销应用程序包并删除应用程序包。

./uninstall.sh

在 Service Fabric Explorer 中，可看到应用程序和应用程序类型不再显示在“应用程序”节点中。

Maven 上的 Service Fabric Java 库

Service Fabric Java 库已托管在 Maven 中。可以在项目的 pom.xml 或 build.gradle 中添加依赖项，以便使用 mavenCentral 提供的 Service Fabric Java 库。

执行组件

针对应用程序的 Service Fabric Reliable Actor 支持。

<dependency>
    <groupId>com.microsoft.servicefabric</groupId>
    <artifactId>sf-actors</artifactId>
    <version>1.0.0</version>
</dependency>

repositories {
    mavenCentral()
}
dependencies {
    compile 'com.microsoft.servicefabric:sf-actors:1.0.0'
}

服务

针对应用程序的 Service Fabric Reliable Services 支持。

<dependency>
    <groupId>com.microsoft.servicefabric</groupId>
    <artifactId>sf-services</artifactId>
    <version>1.0.0</version>
</dependency>

repositories {
    mavenCentral()
}
dependencies {
    compile 'com.microsoft.servicefabric:sf-services:1.0.0'
}

其他

传输

针对 Service Fabric Java 应用程序的传输层支持。不需向 Reliable Actor 或 Service 应用程序显式添加此依赖项，除非在传输层编程。

<dependency>
    <groupId>com.microsoft.servicefabric</groupId>
    <artifactId>sf-transport</artifactId>
    <version>1.0.0</version>
</dependency>

repositories {
    mavenCentral()
}
dependencies {
    compile 'com.microsoft.servicefabric:sf-transport:1.0.0'
}

Fabric 支持

针对 Service Fabric（与本机 Service Fabric 运行时通信）的系统级支持。不需向 Reliable Actor 或 Service 应用程序显式添加此依赖项。当你包括上述其他依赖项时，会自动从 Maven 提取此依赖项。

<dependency>
    <groupId>com.microsoft.servicefabric</groupId>
    <artifactId>sf</artifactId>
    <version>1.0.0</version>
</dependency>

repositories {
    mavenCentral()
}
dependencies {
    compile 'com.microsoft.servicefabric:sf:1.0.0'
}