SDK 结构

PaymentKit Node.js SDK 基于模块化的、面向资源的架构构建。此设计可确保与 PaymentKit API 不同部分的交互是一致、可预测且稳健的。SDK 的核心使用一个中央实用工具为每个 API 资源（如客户、产品等）生成方法，该工具处理与底层 PaymentKit Blocklet 的所有通信。

这种结构抽象了组件间通信的复杂性，使您能够专注于应用程序的业务逻辑。

资源工厂#

SDK 暴露的每个资源（例如 products、customers、subscriptions）都是由一个中央工厂生成的方法集合。这种工厂模式确保了所有 API 方法都具有一致的签名和行为。负责此功能的主要函数是 createResourceMethod 和 createResourceCreateMethod。

这些工厂接受一个定义 HTTP 方法和 API 路径的规范，并返回一个处理完整请求生命周期的异步函数。

以下是 products 资源内部构造的概念性展示：

import { createResourceMethod, createResourceCreateMethod } from './resource';

// 这是一个简化的示例，用以说明该模式。
const products = {
  // 创建新资源的方法
  create: createResourceCreateMethod({ method: 'POST', path: '/v1/products' }),

  // 用于检索、更新、列出和删除的方法
  retrieve: createResourceMethod({ method: 'GET', path: '/v1/products/{id}' }),
  update: createResourceMethod({ method: 'PUT', path: '/v1/products/{id}' }),
  list: createResourceMethod({ method: 'GET', path: '/v1/products' }),
  del: createResourceMethod({ method: 'DELETE', path: '/v1/products/{id}' }),
};

这种方法使得 SDK 易于维护和扩展，同时在所有 API 端点上提供统一的开发者体验。

自动组件处理#

在发送任何 API 请求之前，SDK 会自动确保 PaymentKit Blocklet 正在运行且可用。此过程由 ensureComponentRunning 实用工具管理。

当您调用 SDK 方法时：

1. SDK 首先检查 PaymentKit 组件的状态。
2. 如果组件未运行，它将等待其启动。
3. 一旦确认组件正在运行，API 请求就会被分派。
4. 如果组件启动失败，方法调用将抛出错误。

这个内置检查免去了您在应用程序代码中手动管理 PaymentKit 组件生命周期的负担，从而防止了常见错误和竞态条件。

所有通信最终都由 @blocklet/sdk 的 component.call 函数处理，该函数提供了安全、跨 Blocklet 通信的底层机制。

无缝环境管理#

资源工厂还会根据 SDK 当前的配置，自动将 livemode 参数注入到每个 API 请求中。无论您是在生产模式还是测试模式下操作，SDK 都会将正确的参数传递给 PaymentKit API，无需您付出任何额外努力。

这意味着您可以通过单个配置更改在不同环境之间切换，所有后续的 API 调用都将被正确路由。