如何构建 Marketplace 插件

概述

本指南提供了构建、测试和准备 QuickNode Marketplace 的任何类型插件的技术过程的分步演练。 它是准备开始实施的开发人员的核心技术资源。

你将做什么

• 了解为 QuickNode Marketplace 开发插件
• 准备提交表单所需的特定配置详细信息
• 实现必需的健康检查端点
• 在本地测试你的插件，以确保它已准备好提交

前提条件

本指南假定你已完成初始的引导步骤。 在开始之前，你应该已完成：

1. 一个 QuickNode Marketplace 合作伙伴帐户。 如果你没有合作伙伴帐户，请按照我们的Marketplace 入门指南中的步骤申请一个。
2. 选择你的插件类型。 你应该知道是要构建 JSON-RPC、REST 还是外部插件。
3. 选择身份验证方法。 你应该熟悉可用的选项，并制定一个实施计划。 有关详细回顾，请参阅我们的身份验证指南。

已有现有的 API 或服务？

如果你有想要在 Marketplace 上列出的现有服务，那么这个过程更多的是关于集成，而不是从头开始构建。 你可以通过本指南找到更直接的路径。

你的主要关注点将是：

• 选择正确的身份验证方法：如果你的 API 已经使用了密钥，你可以使用更简单的方法，例如基于标头的身份验证，如果它是公共服务，则可以使用无需身份验证。 查看我们的身份验证指南以确认最适合的方法。
• 准备配置详细信息：收集插件类型所需的 URL、参数和其他详细信息。
• 营销和业务详细信息：前往营销和业务详细信息指南，准备你的列表信息，例如标题、描述、屏幕截图、图标资源和定价计划。

步骤 1：设置你的开发环境

你可以使用你喜欢的任何语言或框架来构建你的插件，只要它满足 Marketplace 的要求（身份验证、健康检查和预配置流程，如果适用）。 QuickNode 不会将你锁定到特定的技术栈中，因此请选择你最熟悉的工具。

对于想要快速入门的开发人员，我们提供了已经包含以下内容的入门模板：

• 预配置 API 身份验证方法 (已包含 HTTP Basic Auth 以保护预配置端点)
• 健康检查端点
• 具有使用 JSON Web Tokens (JWT) 的单点登录 (SSO) 的仪表板视图
• 自定义 RPC 方法的示例实现

可用的入门存储库：

• Python
• JavaScript
• Ruby
• Go
• Ruby on Rails

这些模板主要围绕 RPC 方法插件设计。 如果你正在构建 REST 或外部插件，你仍然可以使用它们作为参考，或者实现你自己的技术栈，只要你遵循所需的模式。

安装 QuickNode Marketplace CLI

QuickNode Marketplace CLI 是一个必不可少的工具，用于模拟从 QuickNode 到你的本地开发服务器的请求。

它允许你在你的本地开发环境中或服务器上直接测试你的插件的功能，包括：

• 健康检查端点
• 预配置端点（如果适用）
• RPC 方法（如果适用，包括不同的计划、网络、链等）
• 仪表板视图的 SSO 实现

要安装 CLI，请按照以下步骤操作：

1. 克隆存储库。

git clone https://github.com/quiknode-labs/qn-marketplace-cli.git
cd qn-marketplace-cli

2. 如果你还没有安装 go，请先安装。 你可以使用 macOS 或 Linux 上的 Homebrew，或者从 Go 网站 下载二进制文件。

brew install go

3. 构建 CLI。

go build -o bin/qn-marketplace-cli

4. 导航到 bin 目录并运行 CLI。

cd go/bin/
./qn-marketplace-cli help

步骤 2：实现你的插件的核心逻辑

这是你编写服务的主要代码的地方。 在下面，你将找到每个插件类型的实现指南，以及你应该为提交表单准备的特定详细信息列表。

• RPC
• REST
• 外部

RPC 插件

JSON-RPC 插件使用自定义 RPC 方法扩展了 QuickNode 的功能。 你的服务器将处理 JSON-RPC 2.0 请求负载。 这些插件允许开发人员创建专门的 JSON-RPC 端点（例如，qn_fetchTokenBalance），这些端点可以执行超出标准 JSON-RPC 方法的任务。

高级主题：RPC 请求如何被代理

要更深入地了解 QuickNode 的基础设施如何处理并将请求转发到你的服务，请参阅我们的详细指南：我们如何代理 RPC 请求。

示例实现

你的代码必须解析传入的请求，识别 method，执行你的逻辑，并返回有效的 JSON-RPC 2.0 响应。

// Express.js 中的 JSON-RPC 处理程序示例
router.post('/rpc', async (request, response) => {
    // 直接处理请求 - 不需要身份验证
    const { method, params } = request.body

    // 你的服务逻辑在这里
    const result = processRequest(method, params)

    response.json({
        jsonrpc: '2.0',
        result: result,
        id: request.body.id
    })
})

根据你选择的身份验证方法，你可能需要实现额外的逻辑来验证传入的请求。 查看我们的身份验证和预配置指南以获取更多详细信息和示例。

准备提交的信息

在构建时，请随时准备以下配置详细信息以用于提交表单：

• 方法名称：你的自定义方法的名称（例如，qn_fetchTokenBalance）。

• 参数详细信息：对于你的方法接受的每个参数，你将需要：

  • 名称（例如，address）
  • 数据类型（例如，string）
  • 示例值（例如，0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B）
  • 描述（例如，用户的以太坊地址。）

• 上游服务 URL：你的 RPC 服务的完整 URL 主机地址（例如，https://api.yourservice.com/rpc）。

• 最大重试次数：QuickNode 在失败时应重试请求的次数。

REST 插件

REST 插件提供标准的、基于资源的 API 端点。 你将定义路由以处理常见的 HTTP 方法，例如 GET、POST、PUT 和 DELETE。

示例实现

你的代码必须定义必要的路由并相应地处理传入的请求。 这是一个 GET 路由的示例，该路由获取Token的价格：

// Express.js 中的 GET 路由示例
app.get('/v1/prices/:token', (req, res) => {
  const { token } = req.params;
  // 你的逻辑来获取Token的价格
  const data = {
    token: token,
    price: '3000.00',
    currency: 'USD'
  };
  res.json(data);
});

准备提交的信息

在构建时，请随时准备以下配置详细信息以用于提交表单：

• HTTP 方法：该路径的方法（例如，GET、POST）。
• REST API URL：特定路径的完整上游 URL（例如，https://api.yourservice.com/v1/prices）。
• 描述：对端点作用的清晰解释（例如，"获取受支持Token的最新价格。"）。
• 示例 URL：一个完整的、可执行的 URL，其中包含真实的示例值，而不是用户的占位符，示例用户可以测试（例如，https://api.yourservice.com/v1/prices/ETH）。
• 示例查询字符串：如果端点接受查询参数，请提供一个示例（例如，currency=EUR&exchange=coinbase）。

外部插件

外部插件将 QuickNode 连接到外部服务或应用程序。 这些可以是托管在 QuickNode 之外的 API，也可以是通过单点登录 (SSO) 访问的 Web 应用程序。

实现

主要开发任务是处理 SSO JWT 流程。 当用户访问你的插件时，QuickNode 会将他们重定向到你的应用程序，并在 JWT 中携带一些信息。 你的应用程序必须验证此Token才能验证用户身份。

SSO 集成通过三个主要步骤完成：

1. 秘钥设置：你创建一个秘钥，该秘钥将用于签名和验证 JSON Web Tokens (JWT)。 此秘钥已安全存储，并在你的插件应用程序过程中与 QuickNode 共享。

2. QuickNode 生成 JWT：当用户选择你的插件的登录到仪表板时，QuickNode 会生成一个 JWT，其中包含用户的详细信息（例如，电子邮件、姓名、组织和 QuickNode ID）。 QuickNode 使用共享秘钥对该Token进行签名，并将其发送到你的仪表板 URL（例如，https://yourservice.com/dashboard/jwt?jwt=eyJhbGciOi...）。

3. JWT 验证和登录：你的应用程序使用共享秘钥验证 JWT，提取用户数据，并授予用户访问其仪表板的权限。 验证后，用户将被重定向到你的应用程序门户。

高级主题：SSO 的工作原理

有关 SSO 工作原理的详细指南，请参阅我们的Marketplace 合作伙伴的 SSO 工作原理指南。

准备提交的信息

对于外部插件，你应该为你的用户准备清除说明。

• 入门说明：编写清晰的、分步指南，该指南将在用户启用你的插件后显示给用户。 这应该解释如何访问他们的仪表板或在哪里找到他们新预配置的 API 密钥。

步骤 3：实现健康检查端点

QuickNode 使用健康检查端点主动监视你的插件的可用性。 你需要提供一个端点（例如，/healthcheck 或 /healthz），该端点返回服务的当抢跑状态。

你的健康检查端点必须是公开可访问的，并且不需要任何身份验证。 QuickNode 将向此 URL 发送一个简单的 GET 请求。

如果你的服务运行状况良好，则端点必须返回 200 OK HTTP 响应代码，并带有以下 JSON 正文：

{
  "status": "ok"
}

除了 200 OK 之外的任何响应都将被视为服务降级，并且 QuickNode 将暂时停止允许新用户安装你的插件，直到问题解决。 我们的入门存储库提供了一个健康检查端点，你可以将其用作起点。

步骤 4：配置身份验证

保护你的插件至关重要。 根据你在先决条件阶段选择的方法，你现在将在你的代码中实现它。

如前所述，我们的入门代码已预先配置了预配置 API 方法。 如果你使用的是其他方法，则需要添加逻辑来验证凭据。 请参阅身份验证指南以获取示例实现。

如果你的插件不需要身份验证，则可以跳过此步骤。

步骤 5：实现仪表板（可选）

虽然不是必需的，但你可以为你的插件提供一个仪表板。 仪表板可以为客户提供一个位置来查看分析、管理设置或访问高级功能。

• 外部插件 几乎总是需要仪表板，因为用户通常需要用于 API 密钥、分析或自定义服务的界面。

• RPC 和 REST 插件 不需要仪表板，但是如果你想提供附加值（例如，查询历史记录、使用情况监视、引导说明），你仍然可以提供一个仪表板。

仪表板使用带有 JWT 的 SSO 对用户进行身份验证。 基本上，QuickNode 使用用户详细信息对 JWT 进行签名，并将其发送到你的仪表板 URL，你可以在其中验证它并让用户登录。

有关构建和集成仪表板的完整演练，请参阅相关的课程部分。 另外，请查看我们的Marketplace 合作伙伴的 SSO 工作原理指南以获取更多详细信息。

步骤 6：使用 CLI 测试你的插件

在提交之前，请使用 Marketplace CLI 模拟来自 QuickNode 的请求，并在本地测试你的插件。

你可以运行以下命令来浏览所有可用的命令：

./qn-marketplace-cli help

或通过运行以下命令，获取有关特定命令的帮助：

./qn-marketplace-cli <command> --help

测试健康检查

验证你的健康检查端点是否可以公开访问并返回 200 OK。

./qn-marketplace-cli healthcheck --url http://localhost:3030/healthcheck

测试预配置 API

如果已实现预配置 API，请使用 pudd 命令确认所有生命周期流程都正常运行。

./qn-marketplace-cli pudd \
  --base-url http://localhost:3030 \
  --basic-auth <base64-encoded-credentials>

将 <base64-encoded-credentials> 替换为你的 Base64 编码的 username:password。 例如，username:password 编码为 dXNlcm5hbWU6cGFzc3dvcmQ=。

测试 RPC 方法

如果你的插件公开了 JSON-RPC 方法，请测试请求和参数是否得到正确处理。

./qn-marketplace-cli rpc \
  --rpc-url http://localhost:3030/rpc \
  --rpc-method qn_fetchTokenBalance \
  --rpc-params "[\"0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B\"]" \
  --basic-auth <base64-encoded-credentials> \
  --plan starter \
  --chain=ethereum \
  --network=mainnet

测试 SSO（仪表板集成）

如果你的插件包含仪表板，请使用已签名的 JWT 测试 SSO 登录流程。

./qn-marketplace-cli sso \
  --url http://localhost:3030/provision \
  --jwt-secret <sso-jwt-secret> \
  --basic-auth <base64-encoded-credentials> \
  --plan starter \
  --name "Sergen" \
  --org "My Org" \
  --email test@test.com

如果你需要公开你的本地服务器以进行测试，请使用隧道工具（如 ngrok）。 在 CLI 命令中将 http://localhost:3030 替换为你的 ngrok URL。

后续步骤：准备发布

现在，你已成功在本地构建和测试了你的插件。 你的代码已完成，并且你的集成已准备好进入下一阶段。

下一步是准备你的插件的营销和业务详细信息，包括其标题、描述、屏幕截图和图标资产。 这些元素可确保你的插件以清晰的方式呈现，并对 Marketplace 中的潜在客户具有吸引力。

要继续，请前往营销和业务详细信息指南，你将在其中学习创建符合 QuickNode Marketplace 标准的引人注目的列表的最佳实践。

我们 ❤️ 反馈！

如果你有任何反馈或新主题的要求，请告诉我们。 我们很乐意听到你的消息。

• 原文链接： quicknode.com/guides/mar...
• 登链社区 AI 助手，为大家转译优秀英文文章，如有翻译不通的地方，还请包涵～