第40章:capcut-mate 客户端
capcut-mate 是独立的剪映草稿操控服务(第 48 章的部署拓扑中作为兄弟容器存在)。pkg/capcutmate 是它在 live-mixer 侧的薄客户端:四个业务端点(create_draft / add_videos / add_captions / gen_video)共享一个 HTTP 内核,外加每个请求的落盘审计与视频生成的轮询等待器。
流程
所有端点汇聚到 doJSONURL:序列化请求 → POST → 读取响应 → (可选)写审计记录 → 校验 HTTP 状态 → 反序列化。业务方法再叠加两层校验:业务码 code != 0 报错、关键字段为空(如 draft_url)报错。
flowchart TD
A[CreateDraft / AddVideos /<br/>AddCaptions] --> B[doJSON<br/>baseURL+path]
C[GenVideo / GenVideoStatus] --> D[doJSONURL<br/>genVideoBaseURL 或 baseURL]
B & D --> E[序列化 → POST → 读响应]
E --> F[writeRecord<br/>00N_endpoint.json]
F --> G{HTTP 2xx?}
G -- 否 --> H[错误含状态码与响应体]
G -- 是 --> I{code != 0 或关键字段空?}
I -- 是 --> J[业务错误]
I -- 否 --> K[返回强类型响应]
L[GenerateVideoAndWait] --> M[GenVideo 提交]
M --> N[循环 GenVideoStatus<br/>5s × 最多360次]
N --> O[completed → video_url<br/>failed → 错误信息<br/>未知状态 → 报错]
实现
双基址设计。Config.GenVideoBaseURL 允许视频生成接口走与草稿接口不同的根地址——生产环境中 gen_video 可能部署在带 GPU 的另一台机器(或需 API Key 的网关),genVideoEndpoint 在两个基址间做三元选择。BaseURL 缺省回落硬编码的 http://192.168.3.219:81(内网地址),组合根必会覆盖。
请求级审计落盘。writeRecord 把每次调用完整写入 recordDir(即 Session 的 RecordDir,staging/{task_id}/capcut_mate/),文件名 001_create_draft.json 序号递增。apiCallRecord 含 seq、UTC 时间戳、方法、路径、请求体、HTTP 状态、响应体。设计上的三个巧思:其一,传输层失败也落盘(_error 字段记录 Go 错误、status=0),网关 502 的 HTML 响应以 _raw_text 保留原文——非 JSON 响应正是生产排障最常缺的现场;其二,序号按目录已有文件数计算,同一任务从 001 起算、重试续号,天然形成时间线;其三,写记录失败被静默忽略(_ = c.writeRecord)——审计不能反过来破坏业务。
两层错误模型。HTTP 层错误带状态码与响应体全文;业务层错误带 code 与 message(capcut-mate 沿用本项目的 {code, message, data} 信封约定)。调用方从错误字符串即可区分"服务挂了"与"服务拒绝了这个请求"。
GenerateVideoAndWait 的状态机。提交后循环查询:completed 校验 video_url 非空再返回;failed 取 error_message,三级回退(error_message → message → 默认文案);pending/processing/空串继续等;未知状态直接报错——宁可失败也不把未定义状态当成功吞掉。轮询上限 360 次 × 5 秒 ≈ 30 分钟,与"视频生成是重活"的预期对齐。sleepWithContext 用 select+timer 实现可取消的 sleep,ctx 取消立即返回,不留悬挂 goroutine。
APIKey 的选择性要求:只有 GenVideo 校验 Key 非空(草稿接口免鉴权),与 capcut-mate 服务端的鉴权设计一致。
📌 设计决策
- 客户端内建审计而非中间件:recordDir 作为方法参数一路从 Session 传到 HTTP 内核,每个业务调用自己决定是否记录;比全局 HTTP 拦截器更精准(健康检查等噪音不会混入)。
- 非 JSON 响应不报错、先记录:网关 502 返回 HTML 时,HTTP 层错误已带原文,同时审计文件里有独立副本——两处现场互为备份。
- 未知状态显式失败:capcut-mate 未来新增状态(如 "paused")时,旧客户端会明确报错而非静默空转,暴露契约漂移。
- 轮询上限 30 分钟而非无限:给任务层的孤儿回收(20 分钟 stale 阈值)与用户预期一个确定边界;超时错误明确写"已尝试 N 次"。
代码示例
片段 1 展示 HTTP 内核与审计(摘自 capcutmate/client.go,节选):
// doJSONURL 向指定 URL 发送 JSON POST;recordPath 用于落盘记录中的 path 字段。
func (c *Client) doJSONURL(ctx context.Context, url, recordPath, name string, reqBody any, respBody any, recordDir string) error {
payload, err := json.Marshal(reqBody)
if err != nil {
return fmt.Errorf("序列化请求失败: %w", err)
}
httpReq, err := http.NewRequestWithContext(ctx, http.MethodPost, url, bytes.NewReader(payload))
if err != nil {
return fmt.Errorf("创建请求失败: %w", err)
}
httpReq.Header.Set("Content-Type", "application/json")
httpResp, err := c.http.Do(httpReq)
status := 0
if err != nil {
// 传输层失败也落盘,保留现场
_ = c.writeRecord(recordDir, name, recordPath, payload, 0, map[string]string{
"_error": err.Error()})
return fmt.Errorf("请求 capcut-mate %s 失败: %w", recordPath, err)
}
defer httpResp.Body.Close()
status = httpResp.StatusCode
respBytes, _ := io.ReadAll(httpResp.Body)
// 优先按 JSON 解析;失败则将原始文本写入记录,便于排查网关/502 问题。
var recordedResp any
if len(bytes.TrimSpace(respBytes)) == 0 {
recordedResp = map[string]string{
"_raw_text": ""}
} else if json.Valid(respBytes) {
recordedResp = json.RawMessage(respBytes)
} else {
recordedResp = map[string]string{
"_raw_text": string(respBytes)}
}
_ = c.writeRecord(recordDir, name, recordPath, payload, status, recordedResp)
if status < 200 || status >= 300 {
return fmt.Errorf("capcut-mate %s HTTP %d: %s", recordPath, status, strings.TrimSpace(string(respBytes)))
}
return json.Unmarshal(respBytes, respBody)
}
// writeRecord 将一次 API 调用写入 recordDir,文件名形如 001_create_draft.json。
// 序号按目录内已有记录文件数递增,保证同一 task 的 staging 目录从 001 起算。
func (c *Client) writeRecord(recordDir, name, path string, requestJSON []byte, httpStatus int, response any) error {
if strings.TrimSpace(recordDir) == "" {
return nil
}
if err := os.MkdirAll(recordDir, 0o755); err != nil {
return err
}
seq := 1
if entries, err := os.ReadDir(recordDir); err == nil {
seq = len(entries) + 1
}
rec := apiCallRecord{
Seq: seq, RecordedAt: time.Now().UTC().Format(time.RFC3339Nano),
Method: http.MethodPost, Path: path,
Request: json.RawMessage(requestJSON),
ResponseHTTPStatus: httpStatus, Response: json.RawMessage(respRaw),
}
data, _ := json.MarshalIndent(rec, "", " ")
return os.WriteFile(filepath.Join(recordDir, fmt.Sprintf("%03d_%s.json", seq, name)), data, 0o644)
}
片段 2 展示轮询等待器(摘自 capcutmate/gen_video.go,节选):
// GenerateVideoAndWait 提交视频生成并轮询直至完成/失败/超时,成功时返回 video_url。
func (c *Client) GenerateVideoAndWait(ctx context.Context, draftURL, recordDir string, onProgress VideoProgressCallback) (string, error) {
if _, err := c.GenVideo(ctx, draftURL, recordDir); err != nil {
return "", err
}
for i := 0; i < c.maxPolls; i++ {
if i > 0 {
if err := sleepWithContext(ctx, c.pollInterval); err != nil {
return "", err
}
}
statusResp, err := c.GenVideoStatus(ctx, draftURL, recordDir)
if err != nil {
return "", err
}
if onProgress != nil {
onProgress(statusResp.Progress, statusResp.Status)
}
switch strings.ToLower(strings.TrimSpace(statusResp.Status)) {
case GenVideoStatusCompleted:
videoURL := strings.TrimSpace(statusResp.VideoURL)
if videoURL == "" {
return "", fmt.Errorf("gen_video 完成但未返回 video_url")
}
return videoURL, nil
case GenVideoStatusFailed:
msg := strings.TrimSpace(statusResp.ErrorMessage)
if msg == "" {
msg = "视频生成失败"
}
return "", fmt.Errorf("gen_video 失败: %s", msg)
case GenVideoStatusPending, GenVideoStatusProcessing, "":
// 继续轮询。
default:
return "", fmt.Errorf("gen_video 未知状态: %s", statusResp.Status)
}
}
return "", fmt.Errorf("gen_video 轮询超时,已尝试 %d 次", c.maxPolls)
}
func sleepWithContext(ctx context.Context, d time.Duration) error {
timer := time.NewTimer(d)
defer timer.Stop()
select {
case <-ctx.Done():
return ctx.Err()
case <-timer.C:
return nil
}
}
小结
一个 HTTP 内核吃下四个端点;审计落盘把"调用过什么、返回过什么"变成任务级可回放的档案;轮询状态机用显式失败守住未知状态。这个包是"薄客户端做厚防御"的完整示范。
思考题
- 轮询记录也走
writeRecord——每 5 秒一条gen_video_status记录,30 分钟任务会产生约 360 个 JSON 文件。审计价值与文件膨胀如何权衡?你会只记录状态变化的"边沿"吗? writeRecord的序号依赖"目录文件数 + 1",若清理进程在轮询期间删掉部分记录,序号会重复——这是否是缺陷?如何用原子计数或时间戳命名规避?
项目信息
- GitHub仓库:Chyona/live-mixer