Go 长任务接口怎么返回进度？SSE 流式推送的最小写法

Go 后端遇到报表导出、视频处理、批量导入这类长任务时，最差的体验是让用户点完按钮后一直盯着转圈。一个实用方案是把“提交任务”和“监听进度”拆开：提交接口返回任务 ID，页面再用 SSE 建立单向长连接，Go 服务按事件持续推送进度、状态和完成结果。这样不需要上 WebSocket，也能让用户看到任务正在推进。

用户任务：从等待转圈变成可见进度

先看一个典型场景：用户在后台点击“导出月度报表”，后端要查询数据、生成文件、写入对象存储，整个过程可能持续几十秒。如果前端只发一个普通 HTTP 请求，用户看到的通常是按钮 loading，网络稍差时还会误以为页面卡住。

SSE 更适合这种单向通知：浏览器发起一条接收通道，服务端不断发送文本事件。页面不用频繁轮询，也不需要维护双向通信协议。只要任务有阶段变化，就把进度发出来。

交互拆解：提交任务和监听进度分开

推荐把接口拆成两个：

• 提交任务：POST /api/report，返回 job_id。
• 监听进度：GET /api/report/stream?job_id=...，用 SSE 返回 progress、error、done 等事件。

这样拆的好处是边界清楚。提交任务只负责校验参数和创建任务；进度接口只负责读状态、推送事件、处理连接断开。用户刷新页面时，只要还记得 job_id，就可以重新连上进度流。

Go 组件实现：一个最小 SSE Handler

SSE 的响应格式很简单，核心是响应头和事件文本。Go 里要注意两点：响应头使用 text/event-stream，每次写完事件后调用 Flush() 把数据立刻推给客户端。

type Progress struct {
    ID       string `json:"id"`
    Status   string `json:"status"`
    Percent  int    `json:"percent"`
    FileURL  string `json:"file_url,omitempty"`
    Message  string `json:"message,omitempty"`
}

func streamReport(w http.ResponseWriter, r *http.Request) {
    flusher, ok := w.(http.Flusher)
    if !ok {
        http.Error(w, "stream unsupported", http.StatusInternalServerError)
        return
    }

    jobID := r.URL.Query().Get("job_id")
    if jobID == "" {
        http.Error(w, "missing job_id", http.StatusBadRequest)
        return
    }

    w.Header().Set("Content-Type", "text/event-stream; charset=utf-8")
    w.Header().Set("Cache-Control", "no-cache")
    w.Header().Set("Connection", "keep-alive")
    w.Header().Set("X-Accel-Buffering", "no")

    updates := watchProgress(r.Context(), jobID)
    for update := range updates {
        if err := writeSSE(w, "progress", update); err != nil {
            return
        }
        flusher.Flush()

        if update.Status == "done" || update.Status == "failed" {
            return
        }
    }
}

这里的 X-Accel-Buffering: no 主要是给 Nginx 这类代理一个提示：不要把流式响应攒起来再发。否则服务端明明每秒写一次，浏览器却半天收不到。

事件写入函数可以集中处理 JSON 编码和 SSE 格式：

func writeSSE(w io.Writer, event string, data Progress) error {
    payload, err := json.Marshal(data)
    if err != nil {
        return err
    }

    if _, err := fmt.Fprintf(w, "event: %s\n", event); err != nil {
        return err
    }
    if _, err := fmt.Fprintf(w, "data: %s\n\n", payload); err != nil {
        return err
    }
    return nil
}

页面接收：EventSource 怎么更新进度条

浏览器侧用 EventSource 建立连接即可。页面可以按事件类型更新进度条、状态文案和完成后的下载入口：

const source = new EventSource(`/api/report/stream?job_id=${jobId}`);

source.addEventListener("progress", (event) => {
  const data = JSON.parse(event.data);
  progressBar.value = data.percent;
  statusText.textContent = data.message || data.status;

  if (data.status === "done") {
    downloadLink.href = data.file_url;
    downloadLink.hidden = false;
    source.close();
  }

  if (data.status === "failed") {
    errorText.textContent = data.message || "任务失败";
    source.close();
  }
});

source.onerror = () => {
  statusText.textContent = "连接中断，正在尝试恢复";
};

这段代码只处理单向进度。如果页面还需要主动暂停、继续或取消任务，可以额外提供普通 HTTP 接口，例如 POST /api/report/cancel，不要把所有控制动作都塞进 SSE 通道。

体验细节：状态文本、心跳和重连

进度条不是唯一信息。用户真正关心的是“现在到了哪一步，还要不要等”。因此服务端事件最好带上状态文本：

{
  "id": "rpt_123",
  "status": "running",
  "percent": 60,
  "message": "正在生成 Excel 文件"
}

长连接还需要心跳。某些代理或网关会关闭长时间没有数据的连接，服务端可以定时发送注释行或 ping 事件：

func writePing(w io.Writer) error {
    _, err := fmt.Fprint(w, ": ping\n\n")
    return err
}

心跳不应该太频繁。后台管理系统里，10 到 30 秒一次通常就够了；如果业务进度本身很频繁，进度事件就已经起到保活作用。

性能检查：别把长连接做成资源黑洞

SSE 很轻，但不是免费。每个在线页面都会占用一个连接、一个 Handler 生命周期和少量内存。上线前至少检查四件事：

• 连接上限：网关、负载均衡、Go 服务自身的连接数是否够用。
• 写入节流：任务内部进度可能每处理一行就变一次，但页面不需要每毫秒刷新。可以按百分比变化或时间间隔合并。
• 代理缓冲：Nginx、CDN、内部网关是否会缓冲响应。
• 超时配置：读写超时、空闲超时不要把正常长连接提前切断。

如果任务量巨大，进度状态不要只存在内存里。可以放到 Redis、数据库或任务队列状态表，让用户刷新页面后还能继续查询。

边界状态：断开、取消和清理

SSE 最容易漏掉的是断开后的清理。浏览器关闭页面、网络断开、用户重新打开页面，都会导致服务端写入失败或 r.Context().Done() 被触发。Handler 必须及时退出，释放订阅通道和任务监听资源。

一个更完整的监听循环可以同时处理进度、心跳和取消：

func streamReport(w http.ResponseWriter, r *http.Request) {
    flusher, ok := w.(http.Flusher)
    if !ok {
        http.Error(w, "stream unsupported", http.StatusInternalServerError)
        return
    }

    w.Header().Set("Content-Type", "text/event-stream; charset=utf-8")
    w.Header().Set("Cache-Control", "no-cache")
    w.Header().Set("X-Accel-Buffering", "no")

    ctx := r.Context()
    jobID := r.URL.Query().Get("job_id")
    updates, stop := subscribeProgress(ctx, jobID)
    defer stop()

    heartbeat := time.NewTicker(15 * time.Second)
    defer heartbeat.Stop()

    for {
        select {
        case 

defer stop() 很关键。它表示无论是客户端断开、任务完成、写入失败，还是服务端主动返回，都要取消订阅。否则任务已经结束，后台却还留着无人消费的通道。

总结

Go 长任务接口要返回进度，SSE 是一个很顺手的方案：服务端实现成本低，浏览器原生支持，适合报表导出、批量处理、状态通知这类单向推送。推荐的结构是提交任务返回 job_id，再用 EventSource 监听进度。

真正要注意的是边界：响应头要正确，写完要 Flush()，代理不能缓冲，进度更新要节流，心跳要保活，客户端断开后要靠 r.Context() 和清理函数释放资源。把这些细节补齐后，用户看到的是明确进度，后端也不会因为长连接变成新的资源问题。