# SDK

Raise 开放接口提供 Go 和 TypeScript 两个服务端 SDK。它们替你换取访问令牌、在出错时重试、翻页、处理幂等键，你只需要写业务调用。

完整的开发者指南和接口参考见[开发者文档](/developers/)。

## 选哪一个

| SDK | 包名 | 当前版本 | 运行环境 | 怎么安装 |
|---|---|---|---|---|
| [Go SDK](/developers/sdk/go) | `github.com/21stware/raise-go` | 0.7.7 | Go 1.26 及以上 | 公共 Go 模块代理，或平台自带的模块代理 |
| [TypeScript SDK](/developers/sdk/typescript) | `@21stware/raise-sdk` | 0.7.7 | Node.js 18+、Deno、Bun、Cloudflare Workers | 从平台下载安装包，不在公共 npm 注册表 |

两个 SDK 一起发布，版本号相同。

**Go**

```bash
go get github.com/21stware/raise-go
```

**TypeScript**

```bash
npm install "https://dev.<你的域名>/dl/sdk/21stware-raise-sdk-0.7.7.tgz"
```

## 两个 SDK 共同的地方

- **令牌**：第一次调用时用你的客户端 ID 和密钥换取访问令牌，到期前 60 秒自动换新。
- **重试**：遇到 429、5xx 和网络错误时自动重试，默认最多 3 次。
- **分页**：列表接口有自动翻页的版本，循环取完全部结果。
- **环境**：密钥前缀决定环境。`kwo_test_` 开头的密钥只能用于测试企业，`kwo_live_` 开头的只能用于正式企业；拿错了，平台返回 `wrong_environment`。
- **Webhook 验签**：用原始请求体和签名头校验平台发来的事件。

> **注意**
>
> 客户端密钥只放在服务端。不要把它打进浏览器页面或小程序前端。

## 从平台下载

平台在开发者门户上提供一份 SDK 与套件包的下载列表，不用登录：

```bash
curl https://dev.<你的域名>/dl/sdk/
```

返回一个 JSON，列出每个 npm 安装包的名称、版本、文件名、大小、校验值和下载地址，以及平台模块代理里的 Go 模块版本。部署没有带这些包时返回 HTTP 404。

## 应用页面用的包

在 Raise 上开发应用时，应用的 React 页面用应用 SDK `@21stware/raise-app-sdk` 和套件包 `@21stware/raise-app-kit`。它们和服务端 SDK 一样从平台的下载列表安装，具体装法见[开发者文档](/developers/)。

## 更新记录

两个 SDK 各有自己的更新记录。接口本身的变更见开发者文档的变更日志。