Go SDK

Go SDK 为 Go 应用程序提供了一个兼容 OpenFeature 的服务器提供商。它通过 HTTP 评估标志，并且不支持 Cloudflare Workers 绑定。

安装

使用 go get 安装：

go get github.com/cloudflare/flagship/sdks/go

设置

使用您的 Flagship 应用 ID、Cloudflare 账户 ID 以及具有 Flagship Evaluate 权限的 API 令牌来配置提供商。

package main

import (
	"context"
	"log"

	flagship "github.com/cloudflare/flagship/sdks/go"
	"github.com/open-feature/go-sdk/openfeature"
)

func main() {
	ctx := context.Background()

	provider, err := flagship.NewProvider(flagship.Options{
		AppID:     "<APP_ID>",
		AccountID: "<ACCOUNT_ID>",
		AuthToken: "<API_TOKEN>",
	})
	if err != nil {
		log.Fatal(err)
	}

	if err := openfeature.SetProviderAndWait(provider); err != nil {
		log.Fatal(err)
	}
	defer openfeature.Shutdown()

	client := openfeature.NewDefaultClient()
	evalCtx := openfeature.NewEvaluationContext("user-42", map[string]any{
		"plan": "enterprise",
	})

	enabled, err := client.BooleanValue(ctx, "new-checkout", false, evalCtx)
	if err != nil {
		log.Fatal(err)
	}

	log.Println("new-checkout:", enabled)
}

标志类型

Go SDK 支持所有 OpenFeature 服务器端标志类型。

enabled, _ := client.BooleanValue(ctx, "new-checkout", false, evalCtx)
variant, _ := client.StringValue(ctx, "homepage-hero", "control", evalCtx)
rate, _ := client.FloatValue(ctx, "sample-rate", 0.1, evalCtx)
limit, _ := client.IntValue(ctx, "upload-limit", 10, evalCtx)
config, _ := client.ObjectValue(ctx, "ui-config", map[string]any{"theme": "light"}, evalCtx)

当您需要理由 (reason)、变体 (variant)、元数据 (metadata) 或错误代码时，请使用 *ValueDetails 方法。

响应缓存

提供商可以缓存评估结果，以避免为重复的标志/上下文对进行网络往返。缓存默认处于关闭状态，通过设置 CacheTTL 启用：

provider, err := flagship.NewProvider(flagship.Options{
	AppID:        "<APP_ID>",
	AccountID:    "<ACCOUNT_ID>",
	AuthToken:    "<API_TOKEN>",
	CacheTTL:     30 * time.Second, // 值最多可能会过期这段时间
	CacheMaxSize: 1000,             // 超过这么多条目后进行 LRU 驱逐
})

每个缓存条目都由标志键、标志类型和完整的评估上下文作为键，因此不同的上下文永远不会共享一个缓存值。缓存命中的解析结果为 reason == openfeature.CachedReason。

禁用的标志、错误和类型不匹配永远不会被缓存。由于新鲜度是基于 TTL 的，因此 Flagship 中的标志更改在条目过期后才会生效。

缓存是每个提供商实例独有的，通过互斥锁保护以用于并发使用，并在 Shutdown 时被清除。

配置选项

Option	Description
`AppID`	Flagship 应用 ID。
`AccountID`	需要与 `AppID` 一起使用。
`BaseURL`	基本 URL 覆盖。默认为 `https://api.cloudflare.com`。
`AuthToken`	向每个请求添加 `Authorization: Bearer <token>`。
`Headers`	静态标头。显式的 `Authorization` 会覆盖 `AuthToken`。
`HeadersFactory`	动态每个请求的标头。值会覆盖 `Headers` 和 `AuthToken`。
`HTTPClient`	自定义 HTTP 客户端。
`Timeout`	每次尝试的超时时间。默认为 5 秒。
`Retries`	发生临时错误时的重试次数。默认为 1，最高上限为 10。
`DisableRetries`	设置为 `true` 时禁用重试。
`RetryDelay`	重试之间的延迟。默认为 1 秒，最高上限为 30 秒。
`CacheTTL`	当大于 0 时启用内存中响应缓存。缓存的值最多可能过期这么长的时间。
`CacheMaxSize`	最大缓存条目数。超出此限制后进行 LRU 驱逐。当设置了 `CacheTTL` 时，默认为 1000。
`Logging`	启用调试和错误日志记录。默认关闭。
`Logger`	可选的兼容 `slog` 的记录器。未设置时使用默认的 `slog` 记录器。
`Hooks`	提供商级别的 OpenFeature 钩子。

评估上下文

上下文属性作为 URL 查询参数发送。支持的值为字符串、数字类型、布尔值和 time.Time。nil 值将被跳过。映射 (maps)、切片 (slices)、结构体 (structs) 以及其他复杂值将通过 OpenFeature 返回 INVALID_CONTEXT，并且不会触发 HTTP 请求。