Go Cmd.WaitDelay 怎么收住子进程：超时、管道关闭与退出状态

用 Go 启动外部程序时，进程已经退出并不代表 Wait 一定马上返回：如果标准输出或标准错误背后的管道仍被继承进程占着，调用方可能继续等。Cmd.WaitDelay 解决的是这段“退出后还没收尾”的等待，但它不负责替代 context 的业务超时。

把 context 用来决定“什么时候取消”，把 WaitDelay 用来限制“取消或退出后管道最多拖多久”，最后再用 errors.Is 区分 ErrWaitDelay 与真正的退出失败。

先准备一个能观察结果的小实验

实验只调用系统自带的 sh 和 printf，不修改文件、不连接网络。把输出接到 bytes.Buffer，可以先观察最常见的“进程正常结束、I/O 也正常收口”路径。

package main

import (
    "bytes"
    "context"
    "errors"
    "fmt"
    "io"
    "os/exec"
    "time"
)

func run(ctx context.Context, delay time.Duration) error {
    cmd := exec.CommandContext(ctx, "sh", "-c", "printf ready")
    var out bytes.Buffer
    cmd.Stdout = &out
    cmd.WaitDelay = delay
    err := cmd.Run()
    fmt.Printf("output=%q err=%v waitDelay=%v\n", out.String(), err, delay)
    if errors.Is(err, exec.ErrWaitDelay) {
        return fmt.Errorf("I/O 收尾超时: %w", err)
    }
    return err
}

func main() {
    ctx, cancel := context.WithTimeout(context.Background(), time.Second)
    defer cancel()
    if err := run(ctx, 200*time.Millisecond); err != nil {
        panic(err)
    }
}

运行后应看到 output="ready"，且 err=。这个结果只能说明本实验的进程和输出都按时结束，还不能证明所有外部程序都会及时关闭它们继承的描述符。

步骤一：先分清两种“超时”

CommandContext 绑定的是业务生命周期。ctx 到期后，Go 会请求结束关联进程；WaitDelay 从进程退出或 context 取消开始，限制内部等待管道和进程收尾的最长时间。两者放在一起，才覆盖“程序不退出”和“程序退出但管道不关”两类卡住。

ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
defer cancel()

cmd := exec.CommandContext(ctx, "sh", "-c", "printf start; sleep 1; printf done")
cmd.WaitDelay = 500 * time.Millisecond
out, err := cmd.Output()
switch {
case errors.Is(err, context.DeadlineExceeded):
    fmt.Println("业务超时", out)
case errors.Is(err, exec.ErrWaitDelay):
    fmt.Println("I/O 收尾超时", out)
case err != nil:
    fmt.Println("子进程失败", err)
default:
    fmt.Println("完成", string(out))
}

检查点是错误分类：ctx 到期通常先看 ctx.Err()，命令非零退出看 *exec.ExitError，只有等待收尾本身超时才匹配 exec.ErrWaitDelay。日志里把这三类状态分开，后续告警才不会把正常的外部程序错误和基础设施卡顿混为一谈。

步骤二：需要逐行读取时，先消费管道再 Wait

当程序使用 StdoutPipe 或 StderrPipe，不要启动命令后直接 Wait。正确顺序是建立管道、启动、读取到 EOF，最后调用 Wait。否则子进程输出较多时，写端可能因为缓冲区满而等待，而调用方又在等它退出。

cmd := exec.CommandContext(ctx, "sh", "-c", "printf 'line-1\nline-2\n'")
cmd.WaitDelay = 300 * time.Millisecond
pipe, err := cmd.StdoutPipe()
if err != nil { panic(err) }
if err := cmd.Start(); err != nil { panic(err) }

data, readErr := io.ReadAll(pipe)
waitErr := cmd.Wait()
fmt.Printf("bytes=%d readErr=%v waitErr=%v\n", len(data), readErr, waitErr)

这段代码需要补充 io 导入。成功时应看到 bytes=14、readErr=、waitErr=；输出已经读完，Wait 只需完成最后的进程状态回收。

步骤三：用一个明确的收口策略处理异常

业务函数可以把输出、退出状态和错误一起返回，而不是把所有错误都包装成“执行失败”。下面的判断顺序先识别收尾超时，再识别 context，再保留外部程序自身的退出信息。

func classify(ctx context.Context, err error) string {
    switch {
    case errors.Is(err, exec.ErrWaitDelay):
        return "wait-delay-expired"
    case errors.Is(ctx.Err(), context.DeadlineExceeded):
        return "context-deadline"
    case errors.Is(ctx.Err(), context.Canceled):
        return "context-canceled"
    case err != nil:
        var exitErr *exec.ExitError
        if errors.As(err, &exitErr) {
            return fmt.Sprintf("exit-status-%d", exitErr.ExitCode())
        }
        return "start-or-io-error"
    default:
        return "ok"
    }
}

检查结果应是稳定的分类字符串，而不是依赖某个操作系统的完整错误文本。WaitDelay 取值也要有依据：太短会把正常的输出收尾判成异常，太长则失去防卡住的意义；先用实际命令的 P95 收尾时间做基线，再留出少量余量。

常见问题

WaitDelay 能替代 context.WithTimeout 吗？

不能。前者管进程退出后的收尾窗口，后者表达业务允许等待多久。没有 context 时，命令可能长时间运行，WaitDelay 不会提前替你做业务取消。

为什么 WaitDelay 到期不一定代表子进程退出失败？

进程可能已经返回成功状态，只是 I/O 管道仍未关闭。此时错误是 exec.ErrWaitDelay，应单独记录为收尾超时。

使用 Output 还需要自己读取 StdoutPipe 吗？

通常不需要。Output 会负责收集标准输出；只有要边读边处理、限制内存或同时消费多个流时，才选择管道并自行安排读取顺序。

WaitDelay 设成零是什么意思？

零表示不设置额外的收尾等待限制。对简单命令问题不大，但对可能继承管道、需要可控退出的服务任务，应显式评估并设置一个合理值。

把结果纳入运行验收

这类调用的验收不应只看“有没有返回字符串”。至少记录四项：ctx 是否取消、子进程退出码、stdout/stderr 是否完整收口、错误是否匹配 exec.ErrWaitDelay。当外部程序偶发卡住时，这四项能直接告诉你是业务 deadline、命令自身失败，还是 I/O 关闭链路出了问题。