2.6 KiB
SDK 独立发布门禁
SDK 位于独立 Go module git.yuntuo.hk/k2safe/orbit/sdk/go。它只能依赖 Go 标准库和显式锁定的 WebSocket 客户端，不引用 Orbit 服务端模型、存储实现、迁移代码或 MySQL 驱动。业务项目通过 SDK 接入，不需要把服务端仓库加入自己的 go.mod。
发布前检查
在仓库根目录执行：
GO=/path/to/go \
sh scripts/test-sdk-isolation.sh
门禁会强制 GOWORK=off，检查 go.mod 和完整依赖图，然后运行：
go test -race ./...go vet ./...go build ./...
成功输出示例：
{"sdk_module":"git.yuntuo.hk/k2safe/orbit/sdk/go","independent":true,"package_count":30,"forbidden_dependencies":0}
package_count 随示例增加而变化，不能作为兼容性版本号。门禁只证明源码在当前 Go 工具链下保持独立和可构建，不代表已经发布到远端模块代理，也不替代旧 SDK/新服务端和新 SDK/旧服务端的协议兼容矩阵。
协议版本、WebSocket 子协议、流程 schema 和数据库版本见兼容矩阵。发布候选还必须执行仓库根目录的 make protocol-check；它检查当前服务端、SDK 和机器可读 schema 是否仍在同一协议线，不把历史版本组合标记为已验证。
接入方式
首个接入版本为 v0.1.0，需要 Go 1.27.1 或更高版本。接入方应固定 SDK 版本，升级前先执行自己的接口和业务幂等回归：
go get git.yuntuo.hk/k2safe/orbit/sdk/go@v0.1.0
# 在业务代码导入 SDK 并添加调用后：
go mod tidy
go mod verify
仓库主分支为 main。服务端标签 v0.1.0 和独立 SDK 标签 sdk/go/v0.1.0 指向同一发布提交；Go 子模块标签必须包含 sdk/go/ 前缀，业务端的模块版本不带此前缀。已发布标签保持不可变，修复使用新的补丁版本。v0.1.0 用于开发与测试接入，正式生产仍需完成交付核对清单。
v0.1.0 已在仓库外的新业务 module、空模块缓存和 GOWORK=off 下通过公开远端下载、go mod tidy、编译、SDK HTTP smoke 和 go mod verify，解析版本精确为 v0.1.0 且不存在 Replace。发布提交、校验和与网络条件见远端验证报告。后续发布继续重复这一步，并按兼容矩阵验证旧/新组合。
本地联调可以临时添加 replace，但不能提交到业务项目的发布分支。SDK 不负责 TLS 终止、凭据托管、对象存储或外部副作用核查；这些边界仍由平台接口手册和接入方运行手册定义。