Go Protocompile 编译多文件时怎样取消剩余任务

用 Go 的 github.com/bufbuild/protocompile 编译一组互相 import 的 proto 文件时，取消“剩余任务”的关键不是自己维护一组 goroutine，而是把调用方的 context.Context 直接传给 Compiler.Compile。当请求被取消或超过截止时间，编译调用会以错误返回，调用方再用 errors.Is 区分主动取消、超时和普通的语法或链接错误。

官方地址：https://github.com/bufbuild/protocompile

把 context 当作编译操作的生命周期入口：Resolver 负责读取主文件和依赖，Compiler 负责解析、链接等阶段；收到取消后，不要把未完整返回的 descriptor 当作成功结果，也不要把取消误报成协议文件本身有错。

• Compiler.Compile(ctx, files...) 是多文件编译的入口，传入的 context 应来自请求、任务或超时控制器。
• 取消只表达这次编译不再需要继续，不是对已经完成的内部工作做事务回滚。
• 错误判断要用 errors.Is，不要只比较错误字符串，也不要把所有失败都当成 context.Canceled。

Protocompile 的编译工作经过哪些阶段

Protocompile 是一个用 Go 编写的 Protocol Buffers 解析与链接引擎。它的根包提供 Compiler，把 Resolver 找到的源文件或中间表示转换成 fully-linked descriptors。对源代码输入来说，过程可以理解为解析 AST、生成未链接 descriptor proto、链接、解释选项以及生成 source code info。

多文件场景中，Resolver 不只读取你传给 Compile 的入口文件，还要按 import 找到它依赖的其他文件。因此，取消信号应该放在整个 Compile 调用的外层，而不是只包住某一个文件的读取。

先用 Resolver 组成一个带依赖的多文件示例

为了集中说明取消机制，下面用内存中的 map 作为源文件。SourceAccessorFromMap 可以把文件名映射到内容，SourceResolver 再把它作为 Compiler 的 Resolver。示例里 user.proto 依赖 common.proto，因此一次编译会触发多文件解析。

package main

import (
	"context"
	"errors"
	"fmt"
	"time"

	"github.com/bufbuild/protocompile"
)

func compileWithDeadline(ctx context.Context) error {
	// map 的键是 proto 文件名，值是对应的源文本；依赖通过 import 连接。
	sources := map[string]string{
		"common.proto": `syntax = "proto3";
package demo;

message Common {
  string trace_id = 1;
}`,
		"user.proto": `syntax = "proto3";
package demo;

import "common.proto";

message User {
  Common common = 1;
}`,
	}

	resolver := &protocompile.SourceResolver{
		// Accessor 需要能被并发调用；编译开始后不要再修改 sources。
		Accessor: protocompile.SourceAccessorFromMap(sources),
	}
	compiler := protocompile.Compiler{
		Resolver:      resolver,
		MaxParallelism: 4, // 限制本次编译使用的最大并行度。
	}

	files, err := compiler.Compile(ctx, "user.proto")
	if err != nil {
		// 先识别生命周期错误，再把其他错误交给上层记录 proto 位置。
		switch {
		case errors.Is(err, context.Canceled):
			return fmt.Errorf("compile canceled: %w", err)
		case errors.Is(err, context.DeadlineExceeded):
			return fmt.Errorf("compile timed out: %w", err)
		default:
			return fmt.Errorf("compile proto files: %w", err)
		}
	}

	// 只有 err 为 nil 时才把返回的 descriptor 集合交给后续代码。
	fmt.Printf("compiled files: %d\n", len(files))
	return nil
}

func main() {
	ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
	defer cancel() // 无论成功或失败，都释放定时器资源。
	if err := compileWithDeadline(ctx); err != nil {
		fmt.Println(err)
	}
}

这个示例有两个容易忽略的点。第一，SourceAccessorFromMap 使用传入的 map，编译开始后不要并发修改 map。第二，MaxParallelism 只是控制编译工作量，不是取消开关；取消仍然来自传给 Compile 的 context。

把请求取消或超时传到 Compile

如果编译发生在 HTTP 请求、队列任务或命令执行中，优先使用上游已经拥有的 context。HTTP handler 通常直接传入 r.Context()；后台任务可以在它上面叠加 WithTimeout。不要在函数内部无条件重新创建 context.Background()，否则上游取消无法到达 Protocompile。

func compileForRequest(parent context.Context, names []string) error {
	// 给单次编译增加硬截止时间，同时保留 parent 的主动取消。
	ctx, cancel := context.WithTimeout(parent, 1500*time.Millisecond)
	defer cancel()

	compiler := protocompile.Compiler{
		Resolver: &protocompile.SourceResolver{
			// 空 Resolver 使用当前工作目录读取 proto 文件；生产代码也可换成缓存 Resolver。
		},
	}
	_, err := compiler.Compile(ctx, names...)
	if err != nil {
		// 让调用方知道是取消/超时，其他错误仍保留原始链路。
		if errors.Is(err, context.Canceled) || errors.Is(err, context.DeadlineExceeded) {
			return err
		}
		return fmt.Errorf("compile %d proto files: %w", len(names), err)
	}
	return nil
}

传入多个文件名时，Compiler 会根据 Resolver 加载入口和依赖。父 context 已经结束时，调用应尽快以取消相关错误返回；编译进行到一半时，具体停止时刻还取决于当前阶段和内部任务边界，所以“取消”应理解为停止继续推进，而不是承诺瞬间终止每一条已经排队的工作。

取消、超时和普通编译错误怎样区分

取消后的错误处理要保留错误链。用 errors.Is 判断比字符串匹配可靠，因为上层可能为错误添加文件名、阶段或请求信息。主动调用 cancel() 通常对应 context.Canceled；超过 WithTimeout 或 WithDeadline 的时间对应 context.DeadlineExceeded；proto 语法错误、找不到 import 或符号链接失败，则应按普通编译错误处理。

func classifyCompileError(err error) string {
	if err == nil {
		return "success"
	}

	// errors.Is 能穿透 fmt.Errorf 的 %w 包装，避免丢失取消原因。
	switch {
	case errors.Is(err, context.Canceled):
		return "canceled"
	case errors.Is(err, context.DeadlineExceeded):
		return "deadline-exceeded"
	default:
		return "compile-error"
	}
}

返回分类后，取消和超时一般不需要按“坏 proto”报警，而是记录任务被谁取消、耗时多久以及是否触发重试；普通编译错误则应保留 Protocompile 提供的文件位置和诊断信息，方便修改源文件。

取消后怎样处理返回结果

Compile 的返回值是文件描述符集合和错误。只要错误不为 nil，就不能把集合当作完整编译结果写入缓存、交给代码生成器或替换旧版本 schema。最简单的规则是：成功路径只在 err == nil 时提交，取消和普通错误都走丢弃或记录分支。

多文件取消时的三个工程边界

不要在 Resolver 外部重复启动一套并发编译

Compiler 本身可以利用多个 CPU 核心处理大规模输入。调用方再为每个文件启动 goroutine，容易让依赖图被拆散，也会让取消、错误聚合和资源回收更复杂。需要调节吞吐时，先看 MaxParallelism 和 Resolver 的读取成本。

Resolver 必须能安全地被并发调用

一个编译操作可能并行调用 FindFileByPath。如果自定义 Resolver 共享了可变 map、文件游标或复用中的缓冲区，必须自行加锁或改成每次调用独立的读取对象。context 取消并不会替你修复 Resolver 的数据竞争。

取消不是回滚

取消表示这次调用不再需要继续；它不会把外部已经写入的日志、缓存或临时文件自动删除，也不会撤销你在 Resolver 中执行的副作用。把“descriptor 提交”放到 err == nil 的最后一步，才能让业务层拥有清晰的提交边界。

常见问题

只取消入口文件的读取可以吗？

不建议。入口文件的 import 依赖也属于一次 Compile 操作，应该把同一个 context 传给 Compiler，让整个调用共享生命周期。

超时后可以继续使用返回的 files 吗？

不要。只要返回了非 nil 错误，就按未完成处理；如果业务需要增量缓存，应另行设计可提交的成功单元，不能把取消路径当成完整编译成功。

怎样判断是用户取消还是系统超时？

用 errors.Is(err, context.Canceled) 和 errors.Is(err, context.DeadlineExceeded) 分开统计，并保留包裹错误。不要从错误字符串中猜原因。