Go SDK

使用 Go SDK 从已认证的业务服务记录事件。Core 仅依赖 Go 标准库；下载包不包含 Gin 适配器。

接入前向项目负责人获取测试环境的 endpoint 和公开 projectKey，并确认所选 SDK 包与宿主运行环境兼容。

1. 安装

从 Go SDK 下载页取得 server-go-1.0.0-offline.zip 离线集成包，解压后将归档中的 proxy/ 路径替换为本机绝对路径：

bash

GOPROXY=file:///absolute/path/to/proxy GOSUMDB=off go get github.com/track-business/track-business-sdk-go@v1.0.0

Go 运行环境最低为 1.22。该包通过离线文件模块代理交付；坐标不表示公共 Go Proxy 已发布。宿主项目的其他依赖仍由宿主现有依赖管理流程提供。

2. 初始化并记录首个事件

在服务启动时创建并复用一个 Client。示例从环境变量读取 ProjectKey。

package analytics

import (
	"os"

	server "github.com/track-business/track-business-sdk-go"
)

func NewClient() (*server.Client, error) {
	return server.NewClient(server.Options{
		Endpoint:   "https://collector.example.com/v1/events/batch",
		ProjectKey: os.Getenv("TRACK_PROJECT_KEY"),
	})
}

func Record(analytics *server.Client, authenticatedUserID string) bool {
	return analytics.Track(server.TrackInput{
		EventName: "sdk_integration_check",
		Identity:  server.Identity{UserID: authenticatedUserID},
		Properties: map[string]any{
			"source": "go-docs",
		},
	})
}

示例使用合成测试事件。正式接入时按业务定义替换事件名与属性；authenticatedUserID 来自宿主认证结果，不能直接信任客户端 Header 或请求字段。

Track 返回值只表示 SDK 是否接纳本次调用，不表示网络发送或 Collector 已确认。默认队列是有界内存队列，不是崩溃恢复保证或事务 Outbox。与业务事务必须一致的事件应由宿主事务 Outbox/WAL 管理。

默认队列最多容纳 1000 条事件，SDK 每 5 秒调度一次后台发送，达到 100 条时也会唤醒发送；发送间隔不是送达时限。队列已满时新事件无法入队，应关注返回值和队列满计数。

3. 有界关闭并验证接收

宿主收到 SIGTERM/SIGINT 后，先停止接收请求并等待在途处理完成，再以有截止时间的 Context 调用 Close(ctx)。不要在每个请求中调用 Flush。

import (
	"context"
	"time"

	server "github.com/track-business/track-business-sdk-go"
)

func Shutdown(analytics *server.Client) {
	shutdownCtx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
	defer cancel()

	result, err := analytics.Close(shutdownCtx)
	if err != nil {
		// 记录脱敏关闭状态，不输出事件、身份、凭据或原始错误内容。
	}
	if result.Unresolved > 0 {
		// 未决事件需按“未确认”处理，不可报告为已接收。
	}
	if result.Rejected > 0 {
		// 记录本次关闭中被拒绝事件的脱敏计数。
	}
}

在测试环境触发事件，并通过接收端的查询或诊断核对记录。未决事件按未确认处理。详见数据校验。

关闭结果只反映本次关闭处理的事件；运行期间也应关注累计诊断，以发现此前后台发送的失败或拒绝。

请求 Context 与停机顺序

一个项目的 Client 可被多个 goroutine 复用，但每次事件仍显式携带可信业务身份。通过 TrackContext 传入当前请求的 Context；派生后台任务时由宿主决定需要保留的上下文与取消边界，不依赖隐式全局身份。请求结束后，后续无请求 Context 的事件不能继承旧请求属性。

停机时先停止接纳新请求或任务并等待已有处理，再停止领取新的 Outbox 记录，最后使用带截止时间的新 Context 调用 Close。不要复用已取消的 HTTP 请求 Context。err != nil 或 Unresolved > 0 都按未确认处理；自定义 Transport 可能不响应取消，不能仅凭等待超时转移文件 Store 所有权。内存队列不提供强杀恢复保证。

事务事件的提交未知与租约处理见Go 宿主事务 Outbox。

可选 Gin 适配

需要请求 Context 属性时，宿主先完成认证和 Consent 判断。Gin 适配模块当前没有独立 Go 发布包；若所用交付包含该模块，应按交付包附带的说明接入。身份仍由宿主认证结果显式传入。

更多身份、队列和日志交接边界见服务端 SDK 概览。

Go SDK ​

1. 安装 ​

2. 初始化并记录首个事件 ​

3. 有界关闭并验证接收 ​

请求 Context 与停机顺序 ​