orbit/docs/examples/subscriptions.md

订阅管理与幂等回执示例

状态：已提供 完整可运行源码。演示 HTTP 管理 SDK；完整结果消费、重连及持久化 Inbox 示例继续开发。协议与字段见 订阅接口。

前置和运行

需要 Go 1.27.1、已迁移到当前版本的 MySQL 8.4+ 和 Orbit 服务。使用新建专用开发命名空间，按环境注入 ORBIT_MYSQL_DSN；初始化显式开启事件权限：

go run ./cmd/orbit-migrate up
mkdir -p .local
chmod 700 .local
go run ./cmd/orbit-admin bootstrap \
  --application subscription-example --namespace default --environment development \
  --queue results --event-access --output .local/subscriptions.credentials.json
go run ./cmd/orbit

另一个终端从仓库根目录执行：

cd examples
ORBIT_URL=http://127.0.0.1:8080 \
  ORBIT_CREDENTIALS_FILE=../.local/subscriptions.credentials.json \
  go run ./subscriptions

也可设置 ORBIT_TOKEN 和 ORBIT_QUEUE_ID，环境值优先于凭据文件。生产接入使用 HTTPS；不要提交凭据文件或在命令行打印秘密。

调用链和输出

创建四类结果订阅 → 同键同内容再次创建 → 查询并按版本暂停 → 恢复 → 检查当前配置及队列订阅列表 → 最后暂停本次订阅。

subscription=<本次订阅ID> duplicate=true resumed_revision=3
final_enabled=false revision=4 pending=0

示例不会创建或执行业务任务，也没有消费者领取，因此不物化交付记录。结果日志仍由正常任务事务生成；此例验证管理调用、显式布尔控制和原幂等回执。

异常、重报与保留

• 缺少事件动作返回 PERMISSION_DENIED；已有普通凭据不会因新版本自动取得权限，应由有授权的管理流程签发所需权限。
• 名称/幂等内容冲突、预期版本过期、订阅数达到 64 均返回明确错误，SDK 不自动换键或覆盖版本。
• 网络超时不能证明没有提交。实际应用必须先持久化操作身份及原请求；按相同键和原版本核对。示例中的随机身份用于隔离每次演示，不是生产操作日志实现。
• 每次运行留下一个已暂停的独立订阅及审计；没有硬删除。重复运行会占用命名空间的订阅数量，应在专用可重建演示环境执行，不手工删除生产记录来绕过上限。
• 示例输出不包含凭据或交付秘密；异常非零退出。

make integration 会在一次性数据库、真实 Orbit 进程中执行这个例子。管理 SDK 集成还验证实际 30 秒交付租约到期后查询 EXPIRED、带版本追加预算、重新交付和确认；其中消息收发是测试辅助代码，正式消费 SDK 另行交付。