什么是 Polkadot API，如何选择合适的 API？

快速决策指南：你应该使用哪个 Polkadot API？

在深入细节之前，这里有一个实用的方法来决定哪个客户端库适合你的项目。Polkadot 生态系统有三个主要的 JavaScript/TypeScript API，选择取决于你的优先级：类型安全、维护状态，以及你是否想使用轻客户端或远程 RPC 端点。

如果你正在开始一个新项目，Polkadot-API 是生态系统的推荐选择。它现代、完全类型化，并为轻客户端而构建。如果你正在维护一个已经使用 Polkadot.js 的现有应用，你可以继续使用，但要注意它处于维护模式。如果你更喜欢不同的 API 风格，Dedot 是一个可靠的替代方案。

对于 RPC 端点，你可以使用公共端点，但对于生产环境，请考虑像 OnFinality 这样可靠的 RPC 提供商。OnFinality 提供 Polkadot RPC 端点 以及许多其他网络，并提供 定价 以满足你的需求。

什么是 Polkadot API？

Polkadot API 是一组库和接口，允许开发者与 Polkadot 和基于 Substrate 的链进行交互。它提供了查询链状态、提交交易和监听事件的方法。API 抽象了底层的 JSON-RPC 调用，处理数据的编码和解码，以便你可以专注于构建应用程序。

有几种实现，每种都有自己的理念和功能。最突出的是 Polkadot-API（通常称为 papi）、Polkadot.js API 和 Dedot。了解它们的差异对于为你的项目选择合适的工具至关重要。

Polkadot-API (papi)：现代、类型安全的选择

Polkadot-API 是一个相对较新的库套件，设计时遵循“轻客户端优先”的理念。它基于新的 JSON-RPC 规范，并利用 Smoldot 等轻客户端的强大功能。这意味着你可以在浏览器中运行节点，减少对中心化 RPC 端点的依赖。

主要功能包括：

• 完全类型化的 API：类型和文档从链上元数据生成，因此你的 IDE 为每个操作提供自动完成和类型检查。
• 对存储读取、常量、交易、事件和运行时调用的一流支持：你可以获得用于所有链交互的全面 API。
• 多连接：你可以同时连接到多个链，这对于跨链应用很有用。
• 运行时升级兼容性：生成多个描述符并执行兼容性检查，为运行时更新做好准备。
• 轻量：主包小于 50kB，并使用动态导入来保持你的 dApp 快速。
• 原生 BigInt：使用 JavaScript 的原生 BigInt 而不是大型 BigNumber 库。
• Promise 和 Observable API：选择适合你编码风格的风格。

以下是如何使用 Polkadot-API 查询账户余额的快速示例：

import { createClient } from "polkadot-api";
import { getSmProvider } from "polkadot-api/sm-provider";
import { startFromWorker } from "polkadot-api/smoldot/from-worker";
import { chainSpec } from "polkadot-api/chains/polkadot";

const smoldot = startFromWorker(new Worker("./smoldot.js"));
const chain = await smoldot.addChain({ chainSpec });
const client = createClient(getSmProvider(chain));

const api = client.getTypedApi();
const balance = await api.query.System.Account.getValue("ADDRESS");
console.log(balance);

此示例使用轻客户端，但你也可以使用 polkadot-api/ws-provider 中的 getWsProvider 连接到远程 RPC 端点。

Polkadot.js API：遗留标准

Polkadot.js API 多年来一直是标准。它提供了围绕 JSON-RPC 调用的易用包装器，并处理所有编码和解码。然而，它现在处于维护模式，不再积极开发。官方 Polkadot 开发者文档建议新项目使用 Polkadot-API 或 Dedot。

尽管如此，许多现有项目仍然依赖它。如果你正在处理遗留代码库，你可能需要使用它。以下是一个基本示例：

const { ApiPromise, WsProvider } = require("@polkadot/api");

async function main() {
  const provider = new WsProvider("wss://rpc.polkadot.io");
  const api = await ApiPromise.create({ provider });

  const balance = await api.query.system.account("ADDRESS");
  console.log(balance.toHuman());
}

main();

请注意，Polkadot.js API 根据链的元数据动态生成其接口。它提供三个主要类别：api.consts、api.query 和 api.tx。

Dedot：TypeScript 优先的替代方案

Dedot 是另一个积极维护的 TypeScript 优先 API。它旨在提供比 Polkadot.js 更符合人体工程学和类型安全的体验。它支持轻客户端和远程 RPC 端点。如果你更喜欢不同的 API 设计，Dedot 值得考虑。

RPC 端点：公共与私有

使用任何 Polkadot API 时，你需要一个 RPC 端点来连接。公共端点（如 wss://rpc.polkadot.io）是免费的，但通常有速率限制，并且可能不适合生产环境。对于生产应用程序，你应该使用提供更高吞吐量、存档数据和更好正常运行时间的专用 RPC 提供商。

OnFinality 提供可靠且可扩展的 Polkadot RPC 端点。你还可以查看 支持的网络 以查看所有可用的链。有关定价详情，请访问 RPC 定价。

如何连接到 Polkadot RPC 端点

无论你选择哪个 API 库，你都需要配置端点。以下是一个使用 Polkadot-API 和 WebSocket 提供程序的示例：

import { createClient } from "polkadot-api";
import { getWsProvider } from "polkadot-api/ws-provider";

const client = createClient(getWsProvider("wss://rpc.polkadot.io"));
const api = client.getTypedApi();

// 现在你可以查询链状态
const header = await api.query.System.Number.getValue();
console.log("当前区块号：", header);

对于 Polkadot.js，你可以使用前面所示的 WsProvider。始终确保你的端点支持 WebSocket 以进行实时订阅。

常见陷阱和故障排除

使用 Polkadot API 时，你可能会遇到问题。以下是一些常见问题及其解决方法：

• 连接错误：如果你使用公共端点，它可能被限流或宕机。切换到可靠的提供商或使用轻客户端。
• 类型不匹配：如果你使用 Polkadot-API，请确保你拥有正确的链规格，并在运行时升级后更新描述符。
• 交易失败：检查错误消息，并确保你有足够的余额支付费用。正确使用 api.tx 方法。
• 性能问题：对于繁重的查询，请考虑使用存档节点或专用基础设施。

关键要点

• Polkadot API 对于与基于 Polkadot 的链进行交互至关重要。
• Polkadot-API 是新项目的现代、类型安全且积极维护的选择。
• Polkadot.js API 处于维护模式；仅用于遗留项目。
• Dedot 是一个可行的替代方案，具有 TypeScript 优先的设计。
• 为生产工作负载选择像 OnFinality 这样可靠的 RPC 提供商。

常见问题解答

Polkadot-API 和 Polkadot.js API 有什么区别？

Polkadot-API 是一个现代、完全类型化且轻客户端优先的库，而 Polkadot.js API 较旧、动态类型化且处于维护模式。新项目应优先选择 Polkadot-API。

我可以将轻客户端与 Polkadot-API 一起使用吗？

是的，Polkadot-API 是为轻客户端构建的，允许你在浏览器中运行节点，而无需依赖远程 RPC 端点。

生产环境应该使用哪个 RPC 端点？

对于生产环境，请使用像 OnFinality 这样可靠的 RPC 提供商，以确保高可用性和性能。不建议将公共端点用于生产工作负载。

Polkadot.js API 是否已弃用？

它处于维护模式，意味着不再积极开发。它仍然有效，但鼓励新项目使用 Polkadot-API 或 Dedot。

如何在 Polkadot-API 和 Dedot 之间选择？

两者都积极维护且类型安全。Polkadot-API 更侧重于轻客户端，是生态系统的推荐选择。Dedot 提供了不同的 API 风格；你可以评估两者，看看哪个更适合你的项目。