SDK 概览

官方 TypeScript 和 Python SDK——它们在纯 HTTPS 之上增加了什么、二者如何比较,以及在发布到 npm 和 PyPI 之前如何从源码构建它们。

两个官方 SDK 封装了公共 API:面向 TypeScript 和 JavaScript 的 @dcision/sdk,以及面向 Python 的 dcision。它们以安全重试运行决策、分派函数目的地、验证 webhook 签名,并读取你的账户和执行记录——两种语言的行为完全相同。

尚未发布——请从源码构建

@dcision/sdk 还没有发布到 npm,dcision 也还没有发布到 PyPI。请按下面的方式从 Dcision 仓库的检出副本构建它们。在本页说明它们已发布之前,npm 或 PyPI 上任何使用这些名称的包都不是来自 Dcision:请不要安装。

Build from source
# In a checkout of the Dcision repository — Node.js 22 and pnpm 10 for the workspace
pnpm install
pnpm --filter @dcision/sdk build        # TypeScript: builds packages/sdk/dist
pip install ./packages/sdk-python        # Python: installs into the active environment

然后用 npm install /path/to/dcision/packages/sdk 把 TypeScript 构建添加到你的项目——参见 TypeScript SDK 和 Python SDK。

它们增加了什么

  • 绝不会让决策运行两次的重试。每次 decide 调用都会发送一个 Idempotency-Key——你提供的,或者一个由其所有重试共用的新 UUID——并在网络错误、超时、429、502、503 和 504 时重试,遵循 Retry-After。如果第二个请求发现第一个仍在运行,它会等待第一个完成,而不是失败。
  • 函数目的地。按名称注册处理函数;SDK 会在决策之后按顺序调用它们。
  • Webhook 验证。一次调用即可以恒定时间检查 Dcision-Signature、时间戳和事件。
  • 类型化的响应和统一的错误类型。每个 API 字段都有类型,而每种失败——API 错误、网络错误、抛出异常的处理函数、无效签名——都是带有稳定 code 的 DcisionError。
  • 安全的默认设置。API 密钥在本地校验且从不打印;请求使用 https 且从不跟随重定向,因此密钥不会到达其他主机。

对比

TypeScriptPython
包@dcision/sdk(packages/sdk)dcision(packages/sdk-python)
运行时Node.js 20+、Bun、Deno、Cloudflare Workers、Vercel EdgePython 3.9+
依赖无——使用 fetch 和 Web Crypto无——仅标准库
客户端异步(promise)同步;在异步代码中使用 asyncio.to_thread
运行决策dcision.decide(slug, state, options)client.decide(slug, state, ...)
函数目的地functions、decision.dispatch()functions=、decision.dispatch()
WebhookverifyWebhook()、verifySignature()verify_webhook()、verify_signature()
账户和执行记录me()、executions.list()、executions.iterate()me()、executions.list()、executions.iterate()
每次尝试的超时30 秒30 秒
重试2 次(共 3 次尝试)2 次(共 3 次尝试)

不使用 SDK

API 只是一个携带 JSON 的 HTTPS POST,因此任何语言都可以使用:参见运行决策中的 cURL、JavaScript 和 Python 示例,以及幂等重试中带重试的完整客户端。CLI 覆盖终端和 CI——它同样需要从源码构建。

本页内容