在 Linux 上建立你的第一個 Java Service Fabric Reliable Actors 應用程式

這個快速入門工具能幫助你在 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 相關設定說明。執行以下指令以安裝 Java 的 Service Fabric Yeoman 範本產生器。

npm install -g generator-azuresfjava

基本概念

要開始學習 Reliable Actors，你只需要理解幾個基本概念：

演員服務。可靠行為者是包裝在可部署於 Service Fabric 基礎結構中的可靠服務中。演員實例會在命名的服務實例中被啟用。
演員登記。與可靠服務相同，可靠演員服務也需要在 Service Fabric 執行環境中註冊。此外，行為者類型也需要在行為者執行階段中註冊。
演員介面。行為者介面是用來定義行為者的強類型公開介面。在可靠演員模型術語中，演員介面定義了演員能理解並處理的訊息類型。演員介面被其他演員及用戶端應用程式用來「非同步」傳送訊息給演員。可靠演員可以實作多種介面。
ActorProxy 類別。 ActorProxy 類別被用戶端應用程式用來呼叫透過演員介面暴露的方法。 ActorProxy 類別提供兩個重要功能：
- 名稱解析：它能定位叢集中的演員（找到它所託管的叢集節點）。
- 失敗處理：例如，它可以在需要將行為者遷移至叢集中另一個節點的失敗發生後，重新嘗試方法叫用，並重新解析行為者位置。

以下關於演員介面的規則值得一提：

Actor 介面方法不能被重載。
演員介面方法不得有 out、ref 或可選參數。
不支援通用介面。

建立應用程式

服務織體應用程式包含一個或多個服務，每個服務在提供應用程式功能中扮演特定角色。你在上一節安裝的生成器，使您能輕鬆建立第一個服務，並且可以在之後輕鬆添加其他內容。你也可以使用 Eclipse 的外掛來建立、建置和部署 Service Fabric Java 應用程式。請參考使用 Eclipse 建立並部署你的第一個 Java 應用程式。為了快速開始，使用 Yeoman 建立一個包含單一服務的應用程式，該服務會儲存並取得計數值。

在終端機中，輸入 yo azuresfjava。
將應用程式命名為。
選擇你第一次服務的類型並命名它。在這個教學中，請選擇一個可靠的演員服務（Reliable Actor Service）。欲了解更多其他類型的服務，請參閱服務織體程式設計模型概述。

若將應用程式命名為「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

可靠角色的基本組件

前述的基本概念轉化為可靠演員服務的基本建構組件。

演員介面

此處包含演員的介面定義。這個介面定義了演員實作與呼叫該角色的客戶端共享的演員合約，因此通常在與演員實作分開的地方定義它是合理的，且可被多個其他服務或客戶端應用程式共享。

HelloWorldActorInterface/src/reliableactor/HelloWorldActor.java：

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

    CompletableFuture<?> setCountAsync(int count);
}

演員生涯

這裡包含你的演員實作和演員註冊程式碼。 actor 類別實作了 actor 介面。這正是演員發揮作用的地方。

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 執行環境中註冊為某個服務類型。為了讓 Actor Service 執行你的 Actor 實例，你的 Actor 類型也必須在 Actor Service 註冊。 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 Cluster (叢集必須已設定並正在執行)。
```
sfctl cluster select --endpoint http://localhost:19080
```
執行範本中提供的安裝腳本，將應用程式套件複製到叢集的映像儲存庫，註冊應用程式類型，並建立應用程式的實例。
```
./install.sh
```

部署已建置的應用程式與其他服務織體應用程式相同。請參閱使用服務架構 CLI 管理服務織體應用程式的文件，以獲得詳細說明。

這些指令的參數可在應用程式套件內產生的清單中找到。

應用程式部署完成後，打開瀏覽器並前往 Service Fabric Explorerhttp://localhost:19080/Explorer。然後，展開應用程式節點，並留意現在已有一個針對您應用程式類型的條目，以及另一個針對該類型第一個執行個體的條目。

這很重要

要將應用程式部署到 Azure 的安全 Linux 叢集，你需要設定憑證，以驗證你的應用程式與 Service Fabric 執行環境。這樣做能讓你的可靠角色服務與底層的 Service Fabric 執行階段 API 溝通。欲了解更多，請參閱「配置可靠服務應用程式以在 Linux 叢集上運行」。

啟動測試客戶端並執行故障轉移

演員不會自己做任何事。他們需要其他服務或客戶來發送訊息。演員範本包含一個簡單的測試腳本，你可以用來與演員服務互動。

備註

測試客戶端使用 ActorProxy 類別與演員通訊，演員必須與演員服務在同一叢集內運行，或共用相同的 IP 位址空間。你可以在與本地開發叢集同一台電腦上執行測試客戶端。然而，要與遠端叢集中的演員通訊，必須在叢集上部署一個閘道器，負責與演員的外部通訊。

用 watch 工具執行腳本，查看演員服務的輸出。測試腳本會呼叫 setCountAsync() 角色的方法來增加計數器，然後呼叫 getCountAsync() 角色的方法取得新的計數器值，並將該值顯示在主控台上。

對於 macOS 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 檔案總管中，你會看到應用程式及其應用程式類型不再出現在 應用程式 節點中。

Maven 上的 Service Fabric Java 函式庫

Service Fabric Java 函式庫已託管於 Maven 中。你可以在專案的 pom.xml 或 build.gradle 中加入依賴，以便使用來自 mavenCentral 的 Service Fabric Java 函式庫。

Actors

Azure Service Fabric 可靠角色支援您的應用程式。

<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'
}

Services

Service Fabric 為你的應用程式提供可靠服務支援。

<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'
}

其他

Transport

提供給 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'
}

布料支撐

用於 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'
}

下一步

意見反應

此頁面對您有幫助嗎？

上次更新時間： 2026-04-01