docs: consolidate runnable examples and publish v0.1.1 guides
This commit is contained in:
30
examples/resources/README.md
Normal file
30
examples/resources/README.md
Normal file
@@ -0,0 +1,30 @@
|
||||
# 队列配额与限速
|
||||
|
||||
制造队列积压背压，释放额度后以原身份补交，并验证受控执行。
|
||||
|
||||
## 准备
|
||||
|
||||
- Go 1.27.1、当前版本 Orbit；服务启动和初始化见[仓库 README](../../README.md#快速开始)。
|
||||
- 队列创建/配置权限；初始化时增加 --worker-access。
|
||||
- [示例总索引](../README.md)提供统一初始化和权限说明；完整字段、失败处理见[详细手册](../../docs/api/queues.md)。
|
||||
|
||||
## 运行
|
||||
|
||||
以下命令从仓库根目录执行；凭据路径替换为实际初始化输出。
|
||||
|
||||
```sh
|
||||
cd examples
|
||||
export ORBIT_URL=http://127.0.0.1:8080
|
||||
export ORBIT_CREDENTIALS_FILE="$PWD/../.local/development.credentials.json"
|
||||
go run ./resources
|
||||
```
|
||||
|
||||
## 结果核对
|
||||
|
||||
backpressure=QUEUE_FULL http=429；最终 unfinished=0、worker_drained=true。具体 ID 和统计值以本次运行为准。程序会核对上述关键条件，失败时打印错误并以非零状态退出。
|
||||
|
||||
## 接入自己的项目
|
||||
|
||||
阅读[main.go](main.go)中的客户端创建、请求及错误处理。业务项目通过 `go get git.yuntuo.hk/k2safe/orbit/sdk/go@v0.1.1` 引入 SDK，无需导入本示例包。
|
||||
|
||||
示例运行会写入真实平台数据，应使用专用测试应用/队列。正常结束保留历史和审计；重复演示通常创建新身份，不能当作上次失败操作的恢复。真实业务应在第一次请求前持久化操作身份，网络结果不明时沿原身份核对。
|
||||
150
examples/resources/main.go
Normal file
150
examples/resources/main.go
Normal file
@@ -0,0 +1,150 @@
|
||||
// resources 演示队列暂停、积压背压、幂等核对、释放空间与限速执行。
|
||||
package main
|
||||
|
||||
import (
|
||||
"context"
|
||||
"encoding/json"
|
||||
"errors"
|
||||
"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 path := os.Getenv("ORBIT_CREDENTIALS_FILE"); path != "" && token == "" {
|
||||
raw, err := os.ReadFile(path)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
var c struct {
|
||||
Token string `json:"token"`
|
||||
}
|
||||
if err := json.Unmarshal(raw, &c); err != nil {
|
||||
return err
|
||||
}
|
||||
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(), 25*time.Second)
|
||||
defer cancel()
|
||||
op, err := orbit.NewWorkerMessageID()
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
name := "resources." + op
|
||||
created, err := api.CreateQueue(ctx, "queue-"+op, orbit.CreateQueueRequest{Name: name, MaxConcurrency: 2, RatePerSecond: 1, MaxUnfinishedTasks: 2})
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
q := created.Queue
|
||||
configure := func(paused bool) error {
|
||||
out, err := api.ConfigureQueue(ctx, q.ID, fmt.Sprintf("configure-%s-%t", op, paused), orbit.ConfigureQueueRequest{ExpectedRevision: q.Revision, Reason: "resource control example", Paused: paused, MaxConcurrency: 2, RatePerSecond: 1, MaxUnfinishedTasks: 2})
|
||||
if err == nil {
|
||||
q = out.Queue
|
||||
}
|
||||
return err
|
||||
}
|
||||
if err := configure(true); err != nil {
|
||||
return err
|
||||
}
|
||||
in := orbit.SubmitTaskRequest{QueueID: q.ID, Handler: name, HandlerVersion: "v1", PayloadVersion: "v1", Payload: json.RawMessage(`{"object_ref":"objects/example","n":9007199254740993}`), TaskTimeoutMS: 20000, Retry: orbit.RetryPolicy{MaxAttempts: 1, AttemptTimeoutMS: 10000}}
|
||||
first, err := api.SubmitTask(ctx, "first-"+op, in)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
second, err := api.SubmitTask(ctx, "second-"+op, in)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
_, err = api.SubmitTask(ctx, "third-"+op, in)
|
||||
var rejected *orbit.APIError
|
||||
if !errors.As(err, &rejected) || rejected.Code != "QUEUE_FULL" {
|
||||
return fmt.Errorf("expected QUEUE_FULL, got %v", err)
|
||||
}
|
||||
fmt.Printf("backpressure=%s http=%d\n", rejected.Code, rejected.StatusCode)
|
||||
duplicate, err := api.SubmitTask(ctx, "first-"+op, in)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
if !duplicate.Deduplicated || duplicate.Task.ID != first.Task.ID {
|
||||
return errors.New("original receipt was not preserved")
|
||||
}
|
||||
if _, err := api.CancelTask(ctx, first.Task.ID, "cancel-"+op, orbit.CancelTaskRequest{ExpectedRevision: first.Task.Revision, Reason: "free one unfinished slot"}); err != nil {
|
||||
return err
|
||||
}
|
||||
// 明确 429 表示未受理；释放空间后仍使用第三个任务的原幂等键与原内容。
|
||||
third, err := api.SubmitTask(ctx, "third-"+op, in)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
fmt.Println("duplicate=true rejected_request_retried=true")
|
||||
w, err := orbit.NewWorker(api, orbit.WorkerOptions{QueueID: q.ID, Capacity: 2, ShutdownTimeout: 5 * time.Second, Handlers: []orbit.WorkerHandler{{Capability: orbit.WorkerCapability{Handler: name, HandlerVersion: "v1", PayloadVersion: "v1"}, Handle: func(ctx context.Context, e orbit.WorkerExecution) (json.RawMessage, error) {
|
||||
if err := ctx.Err(); err != nil {
|
||||
return nil, err
|
||||
}
|
||||
return e.Task.Payload, nil
|
||||
}}}})
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
run, stop := context.WithCancel(ctx)
|
||||
done := make(chan error, 1)
|
||||
go func() { done <- w.Run(run) }()
|
||||
waited := false
|
||||
defer func() {
|
||||
stop()
|
||||
if !waited {
|
||||
<-done
|
||||
}
|
||||
}()
|
||||
if err := configure(false); err != nil {
|
||||
return err
|
||||
}
|
||||
for _, id := range []string{second.Task.ID, third.Task.ID} {
|
||||
for {
|
||||
task, err := api.GetTask(ctx, id)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
if task.State == orbit.TaskSucceeded {
|
||||
fmt.Printf("task=%s state=%s attempts=%d\n", id, task.State, task.AttemptCount)
|
||||
break
|
||||
}
|
||||
if task.State == orbit.TaskFailed || task.State == orbit.TaskNeedsReview || task.State == orbit.TaskCancelled {
|
||||
return fmt.Errorf("unexpected task state: %s", task.State)
|
||||
}
|
||||
select {
|
||||
case <-ctx.Done():
|
||||
return ctx.Err()
|
||||
case <-time.After(80 * time.Millisecond):
|
||||
}
|
||||
}
|
||||
}
|
||||
q, err = api.GetQueue(ctx, q.ID)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
if q.UnfinishedTasks != 0 {
|
||||
return errors.New("queue still has unfinished work")
|
||||
}
|
||||
stop()
|
||||
err = <-done
|
||||
waited = true
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
fmt.Printf("unfinished=%d rate_per_second=%d worker_drained=true\n", q.UnfinishedTasks, q.RatePerSecond)
|
||||
return nil
|
||||
}
|
||||
Reference in New Issue
Block a user