asynctask

package

v1.0.65 Latest Latest Go to latest Published: Oct 20, 2026 License: Apache-2.0 Imports: 7 Imported by: 0

Documentation ¶

Overview ¶

Package asynctask 封装"提交 → 渐进式退避轮询 → (可选) 下载"模式，复用给 doc export / sheet export / aitable export 三个产品。

设计要点：

调用方只需提供"提交"和"查询状态"两个回调，循环逻辑由本包处理
渐进式退避（1s/2s/5s/10s/15s/30s/30s...，可自定义）
默认 5 分钟超时，超时返回 jobId 让用户用 `... get --job-id <ID>` 续等
状态机统一：PROCESSING/PENDING → SUCCESS → 拿 downloadUrl ↓ FAILED → 返回 error
可选 PUT 下载：传入 OutputPath 时本包负责 HTTP GET 落盘

Index ¶

Variables
func Download(ctx context.Context, downloadURL, outputPath string) error
type FinalResult
- func Resume(ctx context.Context, jobID string, queryFn QueryFunc, opts Options) (FinalResult, error)
- func Submit(ctx context.Context, submitFn SubmitFunc, queryFn QueryFunc, opts Options) (FinalResult, error)
type Options
type QueryFunc
type QueryResult
type Status
type SubmitFunc

Constants ¶

This section is empty.

Variables ¶

View Source

var (
	// DefaultBackoff 是渐进式退避序列：1s/2s/5s/10s/15s/30s，之后稳定 30s。
	// 与悟空 wukong/products/aitable.go / doc.go 对齐。
	DefaultBackoff = []time.Duration{
		1 * time.Second,
		2 * time.Second,
		5 * time.Second,
		10 * time.Second,
		15 * time.Second,
		30 * time.Second,
	}

	// DefaultTimeout 是默认超时上限。
	DefaultTimeout = 5 * time.Minute
)

Functions ¶

func Download ¶

func Download(ctx context.Context, downloadURL, outputPath string) error

Download 把 downloadURL 的内容 GET 到本地 outputPath。单独抽出来便于调用方在不调 Submit 时也能复用（例如 sheet export 已有 jobId 的场景）。

Types ¶

type FinalResult ¶

type FinalResult struct {
	JobID       string
	Status      Status
	DownloadURL string
	Message     string
	Raw         map[string]any
	Attempts    int
	Elapsed     time.Duration
}

FinalResult 是 WaitWithBackoff 的最终返回。

func Resume ¶

func Resume(ctx context.Context, jobID string, queryFn QueryFunc, opts Options) (FinalResult, error)

Resume 接续轮询已知 jobID 的任务（提交步骤已完成）。用于 `... export get --job-id <ID>` 兜底命令。

func Submit ¶

func Submit(ctx context.Context, submitFn SubmitFunc, queryFn QueryFunc, opts Options) (FinalResult, error)

Submit 提交任务并轮询直到完成 / 失败 / 超时。

行为：

调用 submitFn 拿到 jobID
进入轮询循环：按 backoff 序列等待 → 调 queryFn → 检查状态
SUCCESS → 返回 FinalResult.Status = SUCCESS + downloadURL
FAILED → 返回 FinalResult.Status = FAILED + Message（不抛 error，让调用方决定）
PROCESSING/PENDING → 继续轮询
超过 Timeout → 返回 FinalResult.Status = TIMEOUT + JobID（调用方可提示用户用 ... get --job-id <ID>）
ctx 取消 → 返回带 ctx.Err() 的 error

type Options ¶

type Options struct {
	// Backoff 是页间退避序列（毫秒）。零值或空使用 DefaultBackoff。
	// 序列耗尽后保持最后一个间隔继续轮询。
	Backoff []time.Duration

	// Timeout 是整体轮询上限。零值使用 DefaultTimeout（5 分钟）。
	Timeout time.Duration

	// ProgressFn 是每轮查询后的进度回调（可选）。用于打印 "[2/30] processing..."
	// 之类的 stderr 提示。
	ProgressFn func(attempt int, status Status, elapsed time.Duration)
}

Options 控制 WaitWithBackoff 的行为。

type QueryFunc ¶

type QueryFunc func(ctx context.Context, jobID string) (QueryResult, error)

QueryFunc 是"查询任务状态"回调。

type QueryResult ¶

type QueryResult struct {
	Status      Status
	DownloadURL string
	Message     string
	Raw         map[string]any
}

QueryResult 是 QueryFunc 的返回。

Status 状态枚举
DownloadURL 服务端返回的下载链接（仅 SUCCESS 时有效）
Message 失败原因 / 进度描述
Raw 原始响应（用于调用方在最终输出里附带）

type Status ¶

type Status string

Status 表示异步任务的状态。

const (
	StatusProcessing Status = "PROCESSING"
	StatusPending    Status = "PENDING"
	StatusSuccess    Status = "SUCCESS"
	StatusFailed     Status = "FAILED"
	StatusTimeout    Status = "TIMEOUT" // 本地超时（非服务端状态）
)

type SubmitFunc ¶

type SubmitFunc func(ctx context.Context) (jobID string, err error)

SubmitFunc 是"提交任务"回调，返回 jobId 或 error。

Source Files ¶

View all Source files

asynctask.go

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL