Go SDK
raise-go 是 Raise 开放接口的 Go SDK。令牌、重试、幂等键和分页都由它处理。
- 模块：
github.com/21stware/raise-go（包名raise） - 当前版本：0.7.7（2026-11-03）
- 要求：Go 1.26 及以上
安装
go get github.com/21stware/raise-goraise-go 发布在公共的 Go 模块代理上。连不上公共代理时，平台在开发者门户上也提供一个只读的模块代理：
export GOPROXY="https://dev.<你的域名>/dl/go,https://proxy.golang.org,direct"平台的代理只有这个平台带的那个版本，通常是最新版。别的版本返回 404，go 命令会接着试 GOPROXY 里的下一个。只能用平台代理时，项目要用它提供的那个版本。
第一次调用
准备三样东西：客户端 ID、客户端密钥，以及开放接口的地址 https://api.<你的域名>/open/v1。商店应用还要写组织 ID。
package main
import (
"context"
"fmt"
"log"
"os"
"github.com/21stware/raise-go"
)
func main() {
c := raise.New(os.Getenv("RAISE_CLIENT_ID"), os.Getenv("RAISE_CLIENT_SECRET"),
raise.WithBaseURL(os.Getenv("RAISE_BASE_URL")), // https://api.<你的域名>/open/v1
raise.WithTenant(os.Getenv("RAISE_TENANT")), // 商店应用必填
)
me, err := c.Platform.Whoami(context.Background())
if err != nil {
log.Fatal(err)
}
fmt.Println(me.Tenant, me.App, me.Scopes)
}第一次调用时，SDK 去换访问令牌。令牌按组织缓存，到期前 60 秒自动换新。
分页
带 All 的列表方法会自动翻页：
it := c.Tables.ListRowsAll(ctx, "orders", "all", nil)
for it.Next(ctx) {
fmt.Println(it.Item().ID)
}
if err := it.Err(); err != nil {
log.Fatal(err)
}错误
接口出错时返回 *raise.Error。按错误码分支，联系支持时带上请求 ID：
if err != nil {
var e *raise.Error
if errors.As(err, &e) && raise.IsCode(err, "scope_required") {
log.Println("应用没有被授予这个范围", e.Message, e.RequestID)
}
}遇到 429、5xx 和网络错误时自动重试，默认 3 次，可以用 raise.WithMaxRetries(n) 改。
Webhook 验签
用原始请求体和 X-Kwork-Signature 请求头验签：
ev, err := raise.VerifyWebhook(body, r.Header.Get("X-Kwork-Signature"), secret, 5*time.Minute)
if err != nil {
http.Error(w, "bad signature", 400)
return
}
log.Println(ev.Type, ev.ID)测试与正式
密钥前缀决定环境：kwo_test_ 只能调用测试企业，kwo_live_ 调用正式组织。SDK 不猜环境，打错一边时平台返回 wrong_environment。
升级
在用平台命令行工具 k3 生成的项目里，运行：
k3 sdk update它会依次运行 go get github.com/21stware/raise-go@latest 和 go mod tidy。其他项目直接用 go get 升级。