docs: consolidate runnable examples and publish v0.1.1 guides

This commit is contained in:
2026-09-24 21:27:25 +08:00
parent e29dec717f
commit 81e56bd633
124 changed files with 1430 additions and 281 deletions

View File

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