本地开发

• 1: IDE 支持
• 1.1: Visual Studio Code 与 Dapr 集成
• 1.1.1: Dapr Visual Studio Code 扩展概述
• 1.1.2: 如何操作：使用 Visual Studio Code 调试 Dapr 应用程序
• 1.1.3: 使用 Dev Containers 开发 Dapr 应用程序
• 1.2: IntelliJ
• 2: 多应用运行
• 2.1: Multi-App Run 概述
• 2.2: 操作指南：使用多应用运行模板文件
• 3: 操作指南：在 Dapr 应用中使用 gRPC 接口
• 4: Dapr SDK 中的序列化

1 - IDE 支持

1.1 - Visual Studio Code 与 Dapr 集成

1.1.1 - Dapr Visual Studio Code 扩展概述

用于本地开发的已弃用 Dapr Visual Studio Code 扩展 为用户提供了多种功能，以更好地管理其 Dapr 应用程序，并对所有支持的 Dapr 语言（包括 .NET、Go、PHP、Python 和 Java）的应用程序进行调试。

在 VSCode 中打开

功能

脚手架 Dapr 调试任务

Dapr 扩展帮助你使用 Visual Studio Code 的内置调试功能通过 Dapr 调试应用程序。

使用 Dapr: Scaffold Dapr Tasks 命令面板操作，你可以更新现有的 task.json 和 launch.json 文件，以便在开始调试时启动和配置 Dapr 边车。

1. 确保已为你的应用设置了启动配置。（了解更多）
2. 使用 Ctrl+Shift+P 打开命令面板
3. 选择 Dapr: Scaffold Dapr Tasks
4. 使用 F5 或通过运行视图运行你的应用和 Dapr 边车。

脚手架 Dapr 组件

将 Dapr 添加到应用程序时，你可能需要一个专用的组件目录，与作为 dapr init 一部分初始化的默认组件分离。

要创建包含默认 statestore、pubsub 和 zipkin 组件的专用组件文件夹，请使用 Dapr: Scaffold Dapr Components 命令面板操作。

1. 在 Visual Studio Code 中打开应用程序目录
2. 使用 Ctrl+Shift+P 打开命令面板
3. 选择 Dapr: Scaffold Dapr Components
4. 使用 dapr run --resources-path ./components -- ... 运行应用程序

查看正在运行的 Dapr 应用程序

应用程序视图显示在本地机器上运行的 Dapr 应用程序。

调用 Dapr 应用程序

在应用程序视图中，用户可以右键单击并通过 GET 或 POST 方法调用 Dapr 应用程序，可选择指定有效负载。

向 Dapr 应用程序发布事件

在应用程序视图中，用户可以右键单击并向正在运行的 Dapr 应用程序发布消息，指定主题和有效负载。

用户还可以向所有正在运行的应用程序发布消息。

其他资源

同时调试多个 Dapr 应用程序

使用 VS Code 扩展，你可以通过多目标调试同时调试多个 Dapr 应用程序。

社区通话演示

观看此视频了解如何使用 Dapr VS Code 扩展：

1.1.2 - 如何操作：使用 Visual Studio Code 调试 Dapr 应用程序

手动调试

开发 Dapr 应用程序时，通常使用 Dapr CLI 启动 daprized 服务，类似这样：

dapr run --app-id nodeapp --app-port 3000 --dapr-http-port 3500 app.js

将调试器附加到服务的一种方法是首先在命令行中使用正确参数运行 daprd，然后启动代码并附加调试器。虽然这是一个完全可接受的解决方案，但它确实需要一些额外的步骤，并且需要向可能想要克隆你的仓库并点击"播放"按钮开始调试的开发者提供一些指导。

如果你的应用程序是一组微服务，每个都有 Dapr 边车，在 Visual Studio Code 中一起调试它们将非常有用。本页面将使用 hello world 快速入门来展示如何配置 VSCode 以使用 VSCode 调试来调试多个 Dapr 应用程序。

前提条件

• 安装 Dapr 扩展。稍后你将使用它提供的 任务。
• 可选：克隆 hello world 快速入门

步骤 1：配置 launch.json

文件 .vscode/launch.json 包含 VS Code 调试运行的 启动配置。该文件定义了当用户开始调试时将启动什么以及如何配置。Visual Studio Code marketplace中提供了每种编程语言的配置。

在 hello world 快速入门的情况下，启动了两个应用程序，每个都有自己的 Dapr 边车。一个用 Node.JS 编写，另一个用 Python 编写。你会注意到每个配置都包含一个 daprd run preLaunchTask 和一个 daprd stop postDebugTask。

{
    "version": "0.2.0",
    "configurations": [
       {
         "type": "pwa-node",
         "request": "launch",
         "name": "Nodeapp with Dapr",
         "skipFiles": [
             "<node_internals>/**"
         ],
         "program": "${workspaceFolder}/node/app.js",
         "preLaunchTask": "daprd-debug-node",
         "postDebugTask": "daprd-down-node"
       },
       {
         "type": "python",
         "request": "launch",
         "name": "Pythonapp with Dapr",
         "program": "${workspaceFolder}/python/app.py",
         "console": "integratedTerminal",
         "preLaunchTask": "daprd-debug-python",
         "postDebugTask": "daprd-down-python"
       }
    ]
}

如果你使用的端口不是代码中内置的默认端口，请在 launch.json 调试配置中设置 DAPR_HTTP_PORT 和 DAPR_GRPC_PORT 环境变量。与 daprd tasks.json 中的 httpPort 和 grpcPort 匹配。例如，launch.json：

{
  // 设置非默认的 HTTP 和 gRPC 端口
  "env": {
      "DAPR_HTTP_PORT": "3502",
      "DAPR_GRPC_PORT": "50002"
  },
}

tasks.json：

{
  // 与 launch.json 中设置的端口匹配
  "httpPort": 3502,
  "grpcPort": 50002
}

每个配置都需要 request、type 和 name。这些参数帮助 VSCode 识别 .vscode/tasks.json 文件中的任务配置。

• type 定义使用的语言。根据语言的不同，它可能需要在 marketplace 中找到的扩展，例如 Python 扩展。
• name 是配置的唯一名称。当在项目中调用多个配置时，这用于复合配置。
• ${workspaceFolder} 是 VS Code 变量引用。这是在 VS Code 中打开的工作区路径。
• preLaunchTask 和 postDebugTask 参数指的是在启动应用程序之前和之后运行的程序配置。有关如何配置这些参数，请参阅步骤 2。

有关 VSCode 调试参数的更多信息，请参阅 VS Code 启动属性。

步骤 2：配置 tasks.json

对于 .vscode/launch.json 中定义的每个任务，在 .vscode/tasks.json 中必须存在相应的任务定义。

对于快速入门，每个服务都需要一个任务来使用 daprd 类型启动 Dapr 边车，以及一个使用 daprd-down 停止边车的任务。参数 appId、httpPort、metricsPort、label 和 type 是必需的。其他可选参数可用，请参阅此处的参考表。

{
    "version": "2.0.0",
    "tasks": [
        {
            "label": "daprd-debug-node",
            "type": "daprd",
            "appId": "nodeapp",
            "appPort": 3000,
            "httpPort": 3500,
            "metricsPort": 9090
        },
        {
            "label": "daprd-down-node",
            "type": "daprd-down",
            "appId": "nodeapp"
        },
        {
            "label": "daprd-debug-python",
            "type": "daprd",
            "appId": "pythonapp",
            "httpPort": 53109,
            "grpcPort": 53317,
            "metricsPort": 9091
        },
        {
            "label": "daprd-down-python",
            "type": "daprd-down",
            "appId": "pythonapp"
        }
   ]
}

步骤 3：在 launch.json 中配置复合启动

复合启动配置可以在 .vscode/launch.json 中定义，它是一组并行启动的两个或多个启动配置。可选地，可以指定 preLaunchTask 并在单独的调试会话开始之前运行。

对于此示例，复合配置是：

{
   "version": "2.0.0",
   "configurations": [...],
   "compounds": [
      {
        "name": "Node/Python Dapr",
        "configurations": ["Nodeapp with Dapr","Pythonapp with Dapr"]
      }
    ]
}

步骤 4：启动调试会话

现在，你可以在 VS Code 调试器中找到在上一步中定义的复合命令名称，以调试模式运行应用程序：

你现在正在使用 Dapr 调试多个应用程序！

Daprd 参数表

以下是 VS Code 任务支持的参数。这些参数等同于 daprd 参数，详见此参考：

相关链接

• Visual Studio Code 扩展概述
• Visual Studio Code 调试

1.1.3 - 使用 Dev Containers 开发 Dapr 应用程序

Visual Studio Code Dev Containers 扩展允许您使用独立的 Docker 容器作为完整的开发环境，而无需在本地文件系统中安装任何额外的软件包、库或工具。

Dapr 为 C# 和 JavaScript/TypeScript 提供了预构建的 Dev Containers；您可以选择适合您需求的容器，即可获得现成的开发环境。请注意，这些预构建的容器会自动更新到最新的 Dapr 版本。

我们还发布了一个 Dev Container 功能，可在任何 Dev Container 中安装 Dapr CLI。

设置开发环境

前置条件

• Docker Desktop
• Visual Studio Code
• VS Code Remote Development extension pack

使用 Dev Container 功能添加 Dapr CLI

您可以使用 Dev Container 功能 在任何 Dev Container 中安装 Dapr CLI。

为此，请编辑您的 devcontainer.json 并在 "features" 部分添加两个对象：

"features": {
    // 安装 Dapr CLI
    "ghcr.io/dapr/cli/dapr-cli:0": {},
    // 启用 Docker（通过 Docker-in-Docker）
    "ghcr.io/devcontainers/features/docker-in-docker:2": {},
    // 或者，使用 Docker-outside-of-Docker（使用主机上的 Docker）
    //"ghcr.io/devcontainers/features/docker-outside-of-docker:1": {},
}

保存 JSON 文件并（重新）构建承载您的开发环境的容器后，您将拥有 Dapr CLI（和 Docker）可用，并且可以通过在容器中运行以下命令来安装 Dapr：

dapr init

示例：为 Dapr 创建 Java Dev Container

这是一个基于官方 Java 17 Dev Container 镜像创建用于开发使用 Dapr 的 Java 应用程序的 Dev Container 示例。

将此内容放在项目中的 .devcontainer/devcontainer.json 文件中：

// 有关格式详细信息，请参阅 https://aka.ms/devcontainer.json。有关配置选项，请参阅
// README at: https://github.com/devcontainers/templates/tree/main/src/java
{
	"name": "Java",
	// 或使用 Dockerfile 或 Docker Compose 文件。更多信息：https://containers.dev/guide/dockerfile
	"image": "mcr.microsoft.com/devcontainers/java:0-17",

	"features": {
		"ghcr.io/devcontainers/features/java:1": {
			"version": "none",
			"installMaven": "false",
			"installGradle": "false"
		},
        // 安装 Dapr CLI
        "ghcr.io/dapr/cli/dapr-cli:0": {},
        // 启用 Docker（通过 Docker-in-Docker）
        "ghcr.io/devcontainers/features/docker-in-docker:2": {},
        // 或者，使用 Docker-outside-of-Docker（使用主机上的 Docker）
        //"ghcr.io/devcontainers/features/docker-outside-of-docker:1": {},
	}

	// 使用 'forwardPorts' 使容器内的端口列表在本地可用。
	// "forwardPorts": [],

	// 使用 'postCreateCommand' 在容器创建后运行命令。
	// "postCreateCommand": "java -version",

	// 配置特定于工具的属性。
	// "customizations": {},

	// 取消注释以 root 用户身份连接。更多信息：https://aka.ms/dev-containers-non-root。
	// "remoteUser": "root"
}

然后，使用 VS Code 命令面板（CTRL + SHIFT + P 或 Mac 上的 CMD + SHIFT + P），选择 Dev Containers: Rebuild and Reopen in Container。

使用预构建的 Dev Container（C# 和 JavaScript/TypeScript）

1. 在 VS Code 中打开您的应用程序工作区
2. 在命令面板中（CTRL + SHIFT + P 或 Mac 上的 CMD + SHIFT + P）键入并选择 Dev Containers: Add Development Container Configuration Files...
   
3. 键入 dapr 以过滤列表到可用的 Dapr 远程容器，并选择与您的应用程序匹配的语言容器。请注意，您可能需要选择 Show All Definitions...
   
4. 按照提示在容器中重新打开您的工作区。
   

示例

观看此视频，了解如何将 Dapr Dev Containers 与您的应用程序一起使用。

1.2 - IntelliJ

在开发 Dapr 应用程序时，通常使用 Dapr CLI 启动您的"Dapr 化"服务，类似这样：

dapr run --app-id nodeapp --app-port 3000 --dapr-http-port 3500 app.js

这会使用默认的组件 yaml 文件（在 dapr init 时创建），以便您的服务可以与本地 Redis 容器交互。这对刚入门来说很好，但如果您想将调试器附加到您的服务并单步调试代码呢？这是您可以不调用应用程序而使用 dapr cli 的地方。

将调试器附加到服务的一种方法是首先从命令行运行 dapr run --，然后启动代码并附加调试器。虽然这是一个完全可以接受的解决方案，但它确实需要一些额外的步骤（比如在终端和 IDE 之间切换），以及一些可能想要克隆您的仓库并点击"播放"按钮开始调试的开发者说明。

本文档解释如何直接从 IntelliJ 使用 dapr。作为先决条件，请确保您已通过 dapr init 初始化了 Dapr 的开发环境。

让我们开始吧！

将 Dapr 添加为"外部工具"

首先，在直接修改配置文件之前退出 IntelliJ。

IntelliJ 配置文件位置

对于 2020.1 及更高版本，工具的配置文件应位于：

• Windows
• Linux
• MacOS

%USERPROFILE%\AppData\Roaming\JetBrains\IntelliJIdea2020.1\tools\

$HOME/.config/JetBrains/IntelliJIdea2020.1/tools/

~/Library/Application\ Support/JetBrains/IntelliJIdea2020.1/tools/

对于 2019.3 或更早版本，配置文件位置不同。有关更多详细信息，请参阅此处。

如果需要，请更改路径中 IntelliJ 的版本。

在 <CONFIG PATH>/tools/External\ Tools.xml 中创建或编辑文件（如果需要，更改路径中的 IntelliJ 版本）。<CONFIG PATH> 取决于操作系统，如上所示。

添加新的 <tool></tool> 条目：

<toolSet name="External Tools">
  ...
  <!-- 1. 每个工具都有自己的 app-id，因此为每个要调试的应用程序创建一个 -->
  <tool name="dapr for DemoService in examples" description="Dapr sidecar" showInMainMenu="false" showInEditor="false" showInProject="false" showInSearchPopup="false" disabled="false" useConsole="true" showConsoleOnStdOut="true" showConsoleOnStdErr="true" synchronizeAfterRun="true">
    <exec>
      <!-- 2. 对于 Linux 或 MacOS 使用：/usr/local/bin/dapr -->
      <option name="COMMAND" value="C:\dapr\dapr.exe" />
      <!-- 3. 选择不与其他 daprd 命令条目冲突的应用程序、http 和 grpc 端口（placement 地址不应更改）。 -->
      <option name="PARAMETERS" value="run -app-id demoservice -app-port 3000 -dapr-http-port 3005 -dapr-grpc-port 52000" />
      <!-- 4. 使用 `components` 文件夹所在的文件夹 -->
      <option name="WORKING_DIRECTORY" value="C:/Code/dapr/java-sdk/examples" />
    </exec>
  </tool>
  ...
</toolSet>

（可选）您还可以为可以在许多项目中重用的边车工具创建新条目：

<toolSet name="External Tools">
  ...
  <!-- 1. 具有应用端口的应用程序的可重用条目。 -->
  <tool name="dapr with app-port" description="Dapr sidecar" showInMainMenu="false" showInEditor="false" showInProject="false" showInSearchPopup="false" disabled="false" useConsole="true" showConsoleOnStdOut="true" showConsoleOnStdErr="true" synchronizeAfterRun="true">
    <exec>
      <!-- 2. 对于 Linux 或 MacOS 使用：/usr/local/bin/dapr -->
      <option name="COMMAND" value="c:\dapr\dapr.exe" />
      <!-- 3. 提示用户 4 次（按顺序）：app id、app port、Dapr 的 http port、Dapr 的 grpc port。 -->
      <option name="PARAMETERS" value="run --app-id $Prompt$ --app-port $Prompt$ --dapr-http-port $Prompt$ --dapr-grpc-port $Prompt$" />
      <!-- 4. 使用 `components` 文件夹所在的文件夹 -->
      <option name="WORKING_DIRECTORY" value="$ProjectFileDir$" />
    </exec>
  </tool>
  <!-- 1. 没有 app-port 的应用程序的可重用条目。 -->
  <tool name="dapr without app-port" description="Dapr sidecar" showInMainMenu="false" showInEditor="false" showInProject="false" showInSearchPopup="false" disabled="false" useConsole="true" showConsoleOnStdOut="true" showConsoleOnStdErr="true" synchronizeAfterRun="true">
    <exec>
      <!-- 2. 对于 Linux 或 MacOS 使用：/usr/local/bin/dapr -->
      <option name="COMMAND" value="c:\dapr\dapr.exe" />
      <!-- 3. 提示用户 3 次（按顺序）：app id、Dapr 的 http port、Dapr 的 grpc port。 -->
      <option name="PARAMETERS" value="run --app-id $Prompt$ --dapr-http-port $Prompt$ --dapr-grpc-port $Prompt$" />
      <!-- 4. 使用 `components` 文件夹所在的文件夹 -->
      <option name="WORKING_DIRECTORY" value="$ProjectFileDir$" />
    </exec>
  </tool>
  ...
</toolSet>

创建或编辑运行配置

现在，为要调试的应用程序创建或编辑运行配置。可以在 main() 函数旁边的菜单中找到它。

现在，添加程序参数和环境变量。这些需要与上面"外部工具"中的条目定义的端口匹配。

• 本示例的命令行参数：-p 3000
• 本示例的环境变量：DAPR_HTTP_PORT=3005;DAPR_GRPC_PORT=52000

开始调试

完成上述一次性配置后，在 IntelliJ 中使用 Dapr 调试 Java 应用程序需要两个步骤：

1. 通过 IntelliJ 中的 Tools -> External Tool 启动 dapr。

2. 以调试模式启动您的应用程序。

总结

调试完成后，请确保在 IntelliJ 中同时停止 dapr 和您的应用程序。

注意：由于您使用 dapr run CLI 命令启动了服务，dapr list 命令将在当前使用 Dapr 运行的应用程序列表中显示来自 IntelliJ 的运行。

祝您调试愉快！

相关链接

• IntelliJ 配置目录位置的更改

2 - 多应用运行

2.1 - Multi-App Run 概述

假设您想在本地运行多个应用程序以进行联合测试，类似于生产环境的场景。Multi-App Run 允许您同时启动和停止一组应用程序，可以选择：

• 使用进程在本地/自托管环境中运行，或
• 通过构建容器镜像并部署到 Kubernetes 集群
  • 您可以使用本地 Kubernetes 集群或部署到云

Multi-App Run 模板文件描述了如何启动多个应用程序，就像您执行了多个单独的 CLI run 命令一样。默认情况下，此模板文件名为 dapr.yaml。

• Self-hosted
• Kubernetes

version: 1
apps:
  - appID: processor
    appDirPath: ../apps/processor/
    appPort: 9081
    daprHTTPPort: 3510
    command: ["go","run", "app.go"]
  - appID: emit-metrics
    appDirPath: ../apps/emit-metrics/
    daprHTTPPort: 3511
    env:
      DAPR_HOST_ADD: localhost
    command: ["go","run", "app.go"]

dapr run -k -f ./<your-preferred-file-name>.yaml

version: 1
common:
apps:
  - appID: nodeapp
    appDirPath: ./nodeapp/
    appPort: 3000
    containerImage: ghcr.io/dapr/samples/hello-k8s-node:latest
    containerImagePullPolicy: Always
    createService: true
    env:
      APP_PORT: 3000
  - appID: pythonapp
    appDirPath: ./pythonapp/
    containerImage: ghcr.io/dapr/samples/hello-k8s-python:latest

后续步骤

• 了解 Multi-App Run 模板文件结构及其属性
• 使用服务调用快速入门尝试自托管 Multi-App Run 模板
• 使用 hello-kubernetes 教程尝试 Kubernetes Multi-App Run 模板

2.2 - 操作指南：使用多应用运行模板文件

多应用运行模板文件是一个 YAML 文件，可用于一次运行多个应用程序。在本指南中，您将学习如何：

• 使用多应用模板
• 查看已启动的应用程序
• 停止多应用模板
• 构建多应用模板文件结构

使用多应用模板

您可以通过以下两种方式之一使用多应用模板文件：

通过提供目录路径执行

当您提供目录路径时，CLI 将尝试在目录中查找名为 dapr.yaml（默认名称）的多应用运行模板文件。如果未找到该文件，CLI 将返回错误。

执行以下 CLI 命令以读取多应用运行模板文件，默认名称为 dapr.yaml：

• Self-hosted
• Kubernetes

# 如果给定目录路径，模板文件需要默认命名为 `dapr.yaml`

dapr run -f <dir_path>

dapr run -f <dir_path> -k 

通过提供文件路径执行

如果多应用运行模板文件的名称不是 dapr.yaml，那么您可以向命令提供相对或绝对文件路径：

• Self-hosted
• Kubernetes

dapr run -f ./path/to/<your-preferred-file-name>.yaml

dapr run -f ./path/to/<your-preferred-file-name>.yaml -k 

查看已启动的应用程序

多应用模板运行后，您可以使用以下命令查看已启动的应用程序：

• Self-hosted
• Kubernetes

dapr list

dapr list -k 

停止多应用模板

随时使用以下任一命令停止多应用运行模板：

• Self-hosted
• Kubernetes

# 如果给定目录路径，模板文件需要默认命名为 `dapr.yaml`

dapr stop -f <dir_path>

dapr stop -f ./path/to/<your-preferred-file-name>.yaml

# 如果给定目录路径，模板文件需要默认命名为 `dapr.yaml`

dapr stop -f <dir_path> -k

dapr stop -f ./path/to/<your-preferred-file-name>.yaml -k 

模板文件结构

多应用运行模板文件可以包含以下属性。以下是一个示例模板，展示了配置了部分属性的两个应用程序。

• Self-hosted
• Kubernetes

version: 1
common: # 可选部分，用于在应用程序之间共享的变量
  resourcesPath: ./app/components # 任何在应用程序之间共享的 dapr 资源
  env:  # 任何在应用程序之间共享的环境变量
    DEBUG: true
apps:
  - appID: webapp # 可选
    appDirPath: .dapr/webapp/ # 必需
    resourcesPath: .dapr/resources # 已弃用
    resourcesPaths: .dapr/resources # 逗号分隔的资源路径。（可选）可按约定保留为默认值。
    appChannelAddress: 127.0.0.1 # 应用程序监听的网络地址。（可选）可按约定保留为默认值。
    configFilePath: .dapr/config.yaml # （可选）也可以按约定默认，如果未找到文件则忽略。
    appProtocol: http
    appPort: 8080
    appHealthCheckPath: "/healthz"
    command: ["python3", "app.py"]
    appLogDestination: file # （可选），可以是 file、console 或 fileAndConsole。默认为 fileAndConsole。
    daprdLogDestination: file # （可选），可以是 file、console 或 fileAndConsole。默认为 file。
  - appID: backend # 可选
    appDirPath: .dapr/backend/ # 必需
    appProtocol: grpc
    appPort: 3000
    unixDomainSocket: "/tmp/test-socket"
    env:
      DEBUG: false
    command: ["./backend"]

version: 1
common: # 可选部分，用于在应用程序之间共享的变量
  env:  # 任何在应用程序之间共享的环境变量
    DEBUG: true
apps:
  - appID: webapp # 可选
    appDirPath: .dapr/webapp/ # 必需
    appChannelAddress: 127.0.0.1 # 应用程序监听的网络地址。（可选）可按约定保留为默认值。
    appProtocol: http
    appPort: 8080
    appHealthCheckPath: "/healthz"
    appLogDestination: file # （可选），可以是 file、console 或 fileAndConsole。默认为 fileAndConsole。
    daprdLogDestination: file # （可选），可以是 file、console 或 fileAndConsole。默认为 file。
    containerImage: ghcr.io/dapr/samples/hello-k8s-node:latest # （可选）部署到 Kubernetes 开发/测试环境时要使用的容器镜像 URI。
    containerImagePullPolicy: IfNotPresent # （可选），如果本地不存在容器镜像则下载，否则使用本地镜像。
    createService: true # （可选）部署到开发/测试环境时为应用程序创建 Kubernetes 服务。
  - appID: backend # 可选
    appDirPath: .dapr/backend/ # 必需
    appProtocol: grpc
    appPort: 3000
    unixDomainSocket: "/tmp/test-socket"
    env:
      DEBUG: false

模板属性

• Self-hosted
• Kubernetes

3 - 操作指南：在 Dapr 应用中使用 gRPC 接口

Dapr 为本地调用实现了 HTTP 和 gRPC 两种 API。gRPC 适用于低延迟、高性能场景，并提供了基于 proto 客户端的语言集成。

在 Dapr SDK 文档中查看自动生成客户端的完整列表。

Dapr 运行时实现了一个 proto 服务，应用程序可以通过 gRPC 与其通信。

除了通过 gRPC 调用 Dapr 外，Dapr 还支持作为代理进行 gRPC 服务间调用。在 gRPC 服务调用操作指南中了解更多。

本指南演示如何使用 Go SDK 应用程序配置并通过 gRPC 调用 Dapr。

配置 Dapr 通过 gRPC 与应用程序通信

• Self-hosted
• Kubernetes

dapr run --app-protocol grpc --app-port 5005 node app.js

apiVersion: apps/v1
kind: Deployment
metadata:
  name: myapp
  namespace: default
  labels:
    app: myapp
spec:
  replicas: 1
  selector:
    matchLabels:
      app: myapp
  template:
    metadata:
      labels:
        app: myapp
      annotations:
        dapr.io/enabled: "true"
        dapr.io/app-id: "myapp"
        dapr.io/app-protocol: "grpc"
        dapr.io/app-port: "5005"
...

通过 gRPC 调用 Dapr

以下步骤展示如何创建 Dapr 客户端并调用其 SaveStateData 操作。

1. 导入包：

   package main
   
   import (
   	"context"
   	"log"
   	"os"
   
   	dapr "github.com/dapr/go-sdk/client"
   )
   

2. 创建客户端：

   // 仅用于此演示
   ctx := context.Background()
   data := []byte("ping")
   
   // 创建客户端
   client, err := dapr.NewClient()
   if err != nil {
     log.Panic(err)
   }
   defer client.Close()
   

   3. 调用 SaveState 方法：

   // 使用键 key1 保存状态
   err = client.SaveState(ctx, "statestore", "key1", data)
   if err != nil {
     log.Panic(err)
   }
   log.Println("data saved")
   

现在你可以探索 Dapr 客户端上的所有不同方法。

使用 Dapr 创建 gRPC 应用

以下步骤展示如何创建一个应用程序，该应用程序暴露一个可供 Dapr 通信的服务器。

1. 导入包：

   package main
   
   import (
   	"context"
   	"fmt"
   	"log"
   	"net"
   
   	"github.com/golang/protobuf/ptypes/any"
   	"github.com/golang/protobuf/ptypes/empty"
   
   	commonv1pb "github.com/dapr/dapr/pkg/proto/common/v1"
   	pb "github.com/dapr/dapr/pkg/proto/runtime/v1"
   	"google.golang.org/grpc"
   )
   

2. 实现接口：

   // server 是我们的用户应用程序
   type server struct {
        pb.UnimplementedAppCallbackServer
   }
   
   // EchoMethod 是一个简单的演示方法，用于调用
   func (s *server) EchoMethod() string {
   	return "pong"
   }
   
   // 当远程服务通过 Dapr 调用应用程序时，会调用此方法
   // 载荷包含一个用于标识方法的 Method、一组元数据属性和一个可选载荷
   func (s *server) OnInvoke(ctx context.Context, in *commonv1pb.InvokeRequest) (*commonv1pb.InvokeResponse, error) {
   	var response string
   
   	switch in.Method {
   	case "EchoMethod":
   		response = s.EchoMethod()
   	}
   
   	return &commonv1pb.InvokeResponse{
   		ContentType: "text/plain; charset=UTF-8",
   		Data:        &any.Any{Value: []byte(response)},
   	}, nil
   }
   
   // Dapr 将调用此方法以获取应用程序希望订阅的主题列表。在此示例中，我们告知 Dapr
   // 订阅一个名为 TopicA 的主题
   func (s *server) ListTopicSubscriptions(ctx context.Context, in *empty.Empty) (*pb.ListTopicSubscriptionsResponse, error) {
   	return &pb.ListTopicSubscriptionsResponse{
   		Subscriptions: []*pb.TopicSubscription{
   			{Topic: "TopicA"},
   		},
   	}, nil
   }
   
   // Dapr 将调用此方法以获取将调用应用程序的绑定列表。在此示例中，我们告知 Dapr
   // 使用名为 storage 的绑定调用我们的应用程序
   func (s *server) ListInputBindings(ctx context.Context, in *empty.Empty) (*pb.ListInputBindingsResponse, error) {
   	return &pb.ListInputBindingsResponse{
   		Bindings: []string{"storage"},
   	}, nil
   }
   
   // 每当从已注册绑定触发新事件时，都会调用此方法。消息携带绑定名称、载荷和可选元数据
   func (s *server) OnBindingEvent(ctx context.Context, in *pb.BindingEventRequest) (*pb.BindingEventResponse, error) {
   	fmt.Println("Invoked from binding")
   	return &pb.BindingEventResponse{}, nil
   }
   
   // 当消息已发布到已订阅的主题时，将触发此方法。Dapr 以 CloudEvents 0.3 信封发送已发布的消息。
   func (s *server) OnTopicEvent(ctx context.Context, in *pb.TopicEventRequest) (*pb.TopicEventResponse, error) {
   	fmt.Println("Topic message arrived")
           return &pb.TopicEventResponse{}, nil
   }
   

3. 创建服务器：

   func main() {
   	// 创建监听器
   	lis, err := net.Listen("tcp", ":50001")
   	if err != nil {
   		log.Fatalf("failed to listen: %v", err)
   	}
   
   	// 创建 grpc 服务器
   	s := grpc.NewServer()
   	pb.RegisterAppCallbackServer(s, &server{})
   
   	fmt.Println("Client starting...")
   
   	// 然后启动...
   	if err := s.Serve(lis); err != nil {
   		log.Fatalf("failed to serve: %v", err)
   	}
   }
   

   这会为你的应用程序在端口 50001 上创建一个 gRPC 服务器。

运行应用程序

• Self-hosted
• Kubernetes

dapr run --app-id goapp --app-port 50001 --app-protocol grpc go run main.go

其他语言

你可以将 Dapr 与 Protobuf 支持的任何语言一起使用，而不仅仅是当前可用的生成 SDK。

使用 protoc 工具，你可以为其他语言（如 Ruby、C++、Rust 等）生成 Dapr 客户端。

相关主题

• 服务调用构建块
• 服务调用 API 规范

4 - Dapr SDK 中的序列化

Dapr SDK 为两种用例提供序列化。首先，是通过请求和响应负载发送的 API 对象。其次，是需要持久化的对象。对于这两种情况，每种语言 SDK 都提供了默认的序列化方法。

服务调用

• .NET
• Java

    using var client = (new DaprClientBuilder()).Build();
    await client.InvokeMethodAsync("myappid", "saySomething", "My Message");

    DaprClient client = (new DaprClientBuilder()).build();
    client.invokeMethod("myappid", "saySomething", "My Message", HttpExtension.POST).block();

在上面的示例中，应用 myappid 接收到一个 saySomething 方法的 POST 请求，请求负载为 "My Message" — 由于序列化器会将输入的 String 序列化为 JSON，所以它被引号包裹。

POST /saySomething HTTP/1.1
Host: localhost
Content-Type: text/plain
Content-Length: 12

"My Message"

状态管理

• .NET
• Java

    using var client = (new DaprClientBuilder()).Build();
    var state = new Dictionary<string, string>
    {
      { "key": "MyKey" },
      { "value": "My Message" }
    };
    await client.SaveStateAsync("MyStateStore", "MyKey", state);

    DaprClient client = (new DaprClientBuilder()).build();
    client.saveState("MyStateStore", "MyKey", "My Message").block();

在此示例中，My Message 被保存。它没有被引号包裹，因为 Dapr 的 API 在发送前会在内部序列化字符串。

发布订阅

• .NET
• Java

    using var client = (new DaprClientBuilder()).Build();
    await client.PublishEventAsync("MyPubSubName", "TopicName", "My Message");

public async Task<IActionResult> HandleMessage(string message) 
{
  //ASP.NET Core 自动将 UTF-8 编码的字节反序列化为字符串
  return new Ok();
}

app.MapPost("/TopicName", [Topic("MyPubSubName", "TopicName")] (string message) => {
  return Results.Ok();
}

  DaprClient client = (new DaprClientBuilder()).build();
  client.publishEvent("TopicName", "My Message").block();

  @PostMapping(path = "/TopicName")
  public void handleMessage(@RequestBody(required = false) byte[] body) {
      // Dapr 的事件符合 CloudEvent 规范
      CloudEvent event = CloudEvent.deserialize(body);
  }

绑定

对于输出绑定，对象被序列化为 byte[]，而输入绑定按原样接收原始 byte[] 并将其反序列化为预期的对象类型。

• .NET
• Java

    using var client = (new DaprClientBuilder()).Build();
    await client.InvokeBindingAsync("sample", "My Message");

  [ApiController]
  public class SampleController : ControllerBase
  {
    [HttpPost("propagate")]
    public ActionResult<string> GetValue([FromBody] int itemId)
    {
      Console.WriteLine($"Received message:  {itemId}");
      return $"itemID:{itemId}";
    }
  }

app.MapPost("value", ([FromBody] int itemId) =>
{
  Console.WriteLine($"Received message: {itemId}");
  return ${itemID:{itemId}";
});

    DaprClient client = (new DaprClientBuilder()).build();
    client.invokeBinding("sample", "My Message").block();

  @PostMapping(path = "/sample")
  public void handleInputBinding(@RequestBody(required = false) byte[] body) {
      String message = (new DefaultObjectSerializer()).deserialize(body, String.class);
      System.out.println(message);
  }

它应该打印：

My Message

Actor 方法调用

Actor 方法调用的对象序列化和反序列化与服务方法调用的方式相同，唯一的区别是应用不需要反序列化请求或序列化响应，因为这一切都由 SDK 透明地完成。

对于 Actor 方法，SDK 仅支持具有零个或一个参数的方法。

• .NET
• Java

    var proxy = this.ProxyFactory.Create(ActorId.CreateRandom(), "DemoActor");
    await proxy.SayAsync("My message");

public Task SayAsync(string message) 
{
    Console.WriteLine(message);
    return Task.CompletedTask;
}

public static void main() {
    ActorProxyBuilder builder = new ActorProxyBuilder("DemoActor");
    String result = actor.invokeActorMethod("say", "My Message", String.class).block();
}

public String say(String something) {
  System.out.println(something);
  return "OK";
}

它应该打印：

    My Message

Actor 的状态管理

Actor 也可以具有状态。在这种情况下，状态管理器将使用状态序列化器对对象进行序列化和反序列化，并对应用透明地处理这些操作。

• .NET
• Java

public Task SayAsync(string message) 
{
    // 从键读取状态
    var previousMessage = await this.StateManager.GetStateAsync<string>("lastmessage");
    
    // 在序列化后为键设置新状态
    await this.StateManager.SetStateAsync("lastmessage", message);
    return previousMessage;
}

public String actorMethod(String message) {
    // 从键读取状态并反序列化为 String
    String previousMessage = super.getActorStateManager().get("lastmessage", String.class).block();

    // 在序列化后为键设置新状态
    super.getActorStateManager().set("lastmessage", message).block();
    return previousMessage;
}

默认序列化器

Dapr 的默认序列化器是一个 JSON 序列化器，具有以下预期：

1. 使用基本 JSON 数据类型以实现跨语言和跨平台兼容性：string、number、array、boolean、null 和另一个 JSON 对象。应用可序列化对象中的每个复杂属性类型（DateTime，例如），都应表示为 JSON 的基本类型之一。
2. 使用默认序列化器持久化的数据也应保存为 JSON 对象，无需额外的引号或编码。下面的示例展示了字符串和 JSON 对象在 Redis 存储中的样子。

redis-cli MGET "ActorStateIT_StatefulActorService||StatefulActorTest||1581130928192||message
"This is a message to be saved and retrieved."

redis-cli MGET "ActorStateIT_StatefulActorService||StatefulActorTest||1581130928192||mydata
{"value":"My data value."}

3. 自定义序列化器必须将对象序列化为 byte[]。
4. 自定义序列化器必须将 byte[] 反序列化为对象。
5. 当用户提供自定义序列化器时，应将其作为 byte[] 传输或持久化。持久化时，还要编码为 Base64 字符串。大多数 JSON 库原生支持此操作。

redis-cli MGET "ActorStateIT_StatefulActorService||StatefulActorTest||1581130928192||message
"VGhpcyBpcyBhIG1lc3NhZ2UgdG8gYmUgc2F2ZWQgYW5kIHJldHJpZXZlZC4="

redis-cli MGET "ActorStateIT_StatefulActorService||StatefulActorTest||1581130928192||mydata
"eyJ2YWx1ZSI6Ik15IGRhdGEgdmFsdWUuIn0="