# Go SDK

`raise-go` 是 Raise 开放接口的 Go SDK。令牌、重试、幂等键和分页都由它处理。

- 模块：`github.com/21stware/raise-go`（包名 `raise`）
- 当前版本：0.7.7（2026-11-03）
- 要求：Go 1.26 及以上

## 安装

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

`raise-go` 发布在公共的 Go 模块代理上。连不上公共代理时，平台在开发者门户上也提供一个只读的模块代理：

```bash
export GOPROXY="https://dev.<你的域名>/dl/go,https://proxy.golang.org,direct"
```

平台的代理只有这个平台带的那个版本，通常是最新版。别的版本返回 404，`go` 命令会接着试 `GOPROXY` 里的下一个。只能用平台代理时，项目要用它提供的那个版本。

## 第一次调用

准备三样东西：客户端 ID、客户端密钥，以及开放接口的地址 `https://api.<你的域名>/open/v1`。商店应用还要写组织 ID。

```go title="main.go"
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` 的列表方法会自动翻页：

```go
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：

```go
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` 请求头验签：

```go
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` 生成的项目里，运行：

```bash
k3 sdk update
```

它会依次运行 `go get github.com/21stware/raise-go@latest` 和 `go mod tidy`。其他项目直接用 `go get` 升级。

## 下一步

- [SDK 总览](/developers/sdk/)
- [开发者文档](/developers/)：凭证、权限范围、各接口的说明。