docs: consolidate runnable examples and publish v0.1.1 guides

2026-09-24 21:27:25 +08:00
parent e29dec717f
commit 81e56bd633
124 changed files with 1430 additions and 281 deletions
--- a/examples/batch/README.md
+++ b/examples/batch/README.md
@@ -0,0 +1,30 @@
+# 批量与部分补交
+
+三项受理中两项成功、一项满额；原身份核对并只补交失败项。
+
+## 准备
+
+- Go 1.27.1、当前版本 Orbit；服务启动和初始化见[仓库 README](../../README.md#快速开始)。
+- 队列创建/配置和任务权限；使用允许创建新队列的示例凭据，不需要 Worker。
+- [示例总索引](../README.md)提供统一初始化和权限说明；完整字段、失败处理见[详细手册](../../docs/examples/batch.md)。
+
+## 运行
+
+以下命令从仓库根目录执行；凭据路径替换为实际初始化输出。
+
+```sh
+cd examples
+export ORBIT_URL=http://127.0.0.1:8080
+export ORBIT_CREDENTIALS_FILE="$PWD/../.local/development.credentials.json"
+go run ./batch
+```
+
+## 结果核对
+
+accepted=2 rejected=1；replayed=2；retried_items=1；unfinished=0。具体 ID 和统计值以本次运行为准。程序会核对上述关键条件，失败时打印错误并以非零状态退出。
+
+## 接入自己的项目
+
+阅读[main.go](main.go)中的客户端创建、请求及错误处理。业务项目通过 `go get git.yuntuo.hk/k2safe/orbit/sdk/go@v0.1.1` 引入 SDK，无需导入本示例包。
+
+示例运行会写入真实平台数据，应使用专用测试应用/队列。正常结束保留历史和审计；重复演示通常创建新身份，不能当作上次失败操作的恢复。真实业务应在第一次请求前持久化操作身份，网络结果不明时沿原身份核对。
--- a/examples/batch/main.go
+++ b/examples/batch/main.go
@@ -0,0 +1,122 @@
+// batch 演示批量部分受理、稳定身份核对和释放配额后仅补交失败项。
+package main
+
+import (
+	"context"
+	"crypto/rand"
+	"encoding/hex"
+	"encoding/json"
+	"fmt"
+	"os"
+	"time"
+
+	orbit "git.yuntuo.hk/k2safe/orbit/sdk/go"
+)
+
+func main() {
+	if err := run(); err != nil {
+		fmt.Fprintln(os.Stderr, err)
+		os.Exit(1)
+	}
+}
+func run() error {
+	token := os.Getenv("ORBIT_TOKEN")
+	if token == "" && os.Getenv("ORBIT_CREDENTIALS_FILE") != "" {
+		raw, err := os.ReadFile(os.Getenv("ORBIT_CREDENTIALS_FILE"))
+		if err != nil {
+			return fmt.Errorf("read credentials: %w", err)
+		}
+		var c struct {
+			Token string `json:"token"`
+		}
+		if json.Unmarshal(raw, &c) != nil {
+			return fmt.Errorf("invalid credentials file")
+		}
+		token = c.Token
+	}
+	api, err := orbit.NewClient(os.Getenv("ORBIT_URL"), orbit.Options{Token: token})
+	if err != nil {
+		return err
+	}
+	ctx, cancel := context.WithTimeout(context.Background(), 20*time.Second)
+	defer cancel()
+	var random [16]byte
+	if _, err := rand.Read(random[:]); err != nil {
+		return err
+	}
+	key := "batch-example-" + hex.EncodeToString(random[:])
+	q, err := api.CreateQueue(ctx, key+"-queue", orbit.CreateQueueRequest{Name: key, MaxConcurrency: 2, RatePerSecond: 10, MaxUnfinishedTasks: 2})
+	if err != nil {
+		return err
+	}
+	if _, err := api.ConfigureQueue(ctx, q.Queue.ID, key+"-pause", orbit.ConfigureQueueRequest{ExpectedRevision: q.Queue.Revision, Reason: "isolated batch acceptance example", Paused: true, MaxConcurrency: 2, RatePerSecond: 10, MaxUnfinishedTasks: 2}); err != nil {
+		return err
+	}
+	request := orbit.SubmitTasksRequest{}
+	// 演示运行生成独立身份；生产必须先将每项键与完整参数持久化到业务库，再发送。
+	for i := 0; i < 3; i++ {
+		payload := json.RawMessage(fmt.Sprintf(`{"source_ref":"objects/input-%d.txt","sequence":9007199254740993}`, i))
+		request.Items = append(request.Items, orbit.SubmitTasksItem{IdempotencyKey: fmt.Sprintf("%s-%d", key, i), Task: orbit.SubmitTaskRequest{QueueID: q.Queue.ID, Handler: "file.convert", HandlerVersion: "v1", PayloadVersion: "v1", Payload: payload, TaskTimeoutMS: 60000}})
+	}
+	first, err := api.SubmitTasks(ctx, request)
+	if err != nil {
+		return err
+	}
+	if first.Items[0].Status != orbit.BatchAccepted || first.Items[1].Status != orbit.BatchAccepted || first.Items[2].Status != orbit.BatchRejected || first.Items[2].Error.Code != "QUEUE_FULL" {
+		return fmt.Errorf("unexpected partial acceptance")
+	}
+	fmt.Println("accepted=2 rejected=1 code=QUEUE_FULL")
+	replay, err := api.SubmitTasks(ctx, request)
+	if err != nil {
+		return err
+	}
+	for i := 0; i < 2; i++ {
+		if replay.Items[i].Status != orbit.BatchAccepted || !replay.Items[i].Receipt.Deduplicated || replay.Items[i].Receipt.TaskID != first.Items[i].Receipt.TaskID {
+			return fmt.Errorf("batch replay changed identity")
+		}
+	}
+	if replay.Items[2].Status != orbit.BatchRejected || replay.Items[2].Error.Code != "QUEUE_FULL" {
+		return fmt.Errorf("backpressure changed unexpectedly")
+	}
+	fmt.Println("replayed=2 same_task_ids=true")
+	cancelTask := func(id string) error {
+		current, err := api.GetTask(ctx, id)
+		if err != nil {
+			return err
+		}
+		out, err := api.CancelTask(ctx, id, key+"-cancel-"+id, orbit.CancelTaskRequest{ExpectedRevision: current.Revision, Reason: "finish batch example"})
+		if err != nil {
+			return err
+		}
+		if out.Task.State != orbit.TaskCancelled {
+			return fmt.Errorf("expected confirmed cancellation")
+		}
+		return nil
+	}
+	if err := cancelTask(first.Items[0].Receipt.TaskID); err != nil {
+		return err
+	}
+	// 子批次索引重新从0开始；键和参数仍来自最初被拒项，不重新生成。
+	retry, err := api.SubmitTasks(ctx, orbit.SubmitTasksRequest{Items: request.Items[2:]})
+	if err != nil {
+		return err
+	}
+	if retry.Items[0].Status != orbit.BatchAccepted || retry.Items[0].Receipt.Deduplicated {
+		return fmt.Errorf("failed item was not independently accepted")
+	}
+	fmt.Println("retried_items=1 same_identity=true accepted=true")
+	for _, id := range []string{first.Items[1].Receipt.TaskID, retry.Items[0].Receipt.TaskID} {
+		if err := cancelTask(id); err != nil {
+			return err
+		}
+	}
+	final, err := api.GetQueue(ctx, q.Queue.ID)
+	if err != nil {
+		return err
+	}
+	if final.UnfinishedTasks != 0 {
+		return fmt.Errorf("unfinished tasks remain")
+	}
+	fmt.Printf("queue=%s paused=%t unfinished=%d\n", final.ID, final.Paused, final.UnfinishedTasks)
+	return nil
+}