Go 自建 types.Package 怎样标记已经完成的包信息

用 Go 自己拼装 go/types 的包信息时，最容易混淆的是“对象已经创建”和“包信息已经完整”这两件事。types.NewPackage 创建出的包默认还不是完成状态；你需要先补充包级作用域和显式导入关系，再调用 MarkComplete 写入完成标记，最后用 Complete 读取它。MarkComplete 不会自动扫描源码、导入依赖或补齐对象，它只是状态门禁。

官方文档：https://pkg.go.dev/go/types#Package。下面按“触发场景、信息准备、完成门禁、失败处理、状态复盘”的方式拆开，示例中的域名和对象都是虚构的说明数据。

先把 Package 当成一份待补全的包清单

在静态分析器、导出数据读取器或测试替身里，我们可能没有直接交给 types.Config.Check 的完整源码，而是需要先创建一个包容器。此时第一条规则是：NewPackage(path, name) 只解决身份和基础作用域，不代表包已经可以交给后续消费者。

Path 是导入路径，Name 是包名，Scope 是包级对象所在的作用域，Imports 则描述显式导入的包列表。把这几项分开记录，排查时就不会把“有路径”误认为“有声明”，也不会把“有导入列表”误认为“已经完成”。

把信息准备工作放进明确的流水线阶段

可以把自建包流程写成四段责任：先创建包，再向作用域放入需要的包级对象，同时设置导入关系，最后才决定是否关闭“待补全”状态。这里的“阶段”是调用方自己的工作流，不是 go/types 自动提供的流水线。

package main

import (
	"fmt"
	"go/token"
	"go/types"
)

func buildPackage() *types.Package {
	// NewPackage 只创建包身份和基础作用域，初始状态仍未完成。
	pkg := types.NewPackage("example.com/orders", "orders")

	// 只把本流程确定需要的包级对象放进作用域。
	_ = pkg.Scope().Insert(types.NewVar(
		token.NoPos, pkg, "OrderID", types.Typ[types.Int],
	))

	// 导入列表由调用方维护；列表元素应保持唯一。
	shared := types.NewPackage("example.com/shared", "shared")
	pkg.SetImports([]*types.Package{shared})

	// 所需声明与导入关系准备好后，才写入完成标记。
	pkg.MarkComplete()
	return pkg
}

func main() {
	pkg := buildPackage()
	// Complete 只读取标记，不会重新检查 Scope 或 Imports。
	fmt.Println(pkg.Path(), pkg.Name(), pkg.Complete())
}

这段最小写法的关键不在于打印结果，而在于职责顺序：Scope().Insert 负责补对象，SetImports 负责写导入关系，MarkComplete 负责把当前状态标记为完成。若你的数据源还没有整理完导出对象，就不要为了让 Complete() 返回 true 而提前调用它。

把 MarkComplete 放在最后一个门禁

官方源码对“完成”的定义很窄：包的作用域至少包含所有导出对象时，才可以视为 complete。这个定义给调用方一个很实用的门禁：把“对象是否已收齐”和“是否允许后续分析读取”放在同一处决策，但不要把门禁误解成验证器。

推荐的门禁规则是：先确认包级声明来源已经结束，再确认需要的直接导入已整理好，然后调用 MarkComplete。之后用 Complete 做状态读取。Complete 返回 false 时，说明调用方仍应把它当作不完整包处理；返回 true 只说明完成标记已被设置，并不替你检查每个自定义对象的业务正确性。

失败处理：不要把三个状态问题混成一个问题

第一类是过早标记。 如果作用域仍在增量填充，先调用 MarkComplete 会让后续代码看到一个“已完成”的包；而 MarkComplete 没有撤销方法，所以修复思路不是反复切换标记，而是把完成调用推迟到输入收敛的位置。

第二类是导入关系错误。 SetImports 的文档把保证元素唯一的责任交给调用方。重复导入项、把间接依赖当成直接依赖，都会让包关系报告失真；这与 Complete 的布尔状态是两件事，应分开记录。

第三类是对象缺失。 Scope() 能返回包级作用域，但不会告诉你自建流程是否已经把所有应有的导出对象放齐。工程上最好保存一份输入清单，把“期望对象集合”和“是否完成标记”作为两个字段输出，方便复盘。

用一个小状态报告完成复盘

自动化分析流程里，可以把 Path、Name、Complete、作用域大小和导入数量放进日志或调试结构。注意不要把此报告称为类型检查结果：它只反映你构造的 types.Package 容器当前暴露了哪些状态。

type packageReport struct {
	Path       string
	Name       string
	Complete   bool
	ScopeNames int
	ImportCount int
}

func report(pkg *types.Package) packageReport {
	// ScopeNames 只统计当前作用域中的对象名，不替代完整性证明。
	return packageReport{
		Path:        pkg.Path(),
		Name:        pkg.Name(),
		Complete:    pkg.Complete(),
		ScopeNames:  pkg.Scope().Len(),
		ImportCount: len(pkg.Imports()),
	}
}

速查一下：需要创建包身份时用 NewPackage；需要补充包级声明时操作 Scope；需要维护显式依赖时用 SetImports；只有在自建信息已经达到“至少具备所需导出对象”的边界后，才调用 MarkComplete；需要读取门禁状态时用 Complete。

常见问题

调用 NewPackage 后为什么 Complete 还是 false？ 因为新包默认是不完整的，创建对象不等于完成信息。

MarkComplete 会自动检查导入包吗？ 不会。导入列表和对象内容由调用方准备，MarkComplete 只写完成状态。

Complete 为 true 就代表类型检查通过了吗？ 不能这样推断。它是 Package 自身的完成标记，不是一次新的类型检查报告。

结论很简单：把 types.Package 当作一个需要显式收口的状态容器。先准备作用域和导入关系，再把 MarkComplete 放到最后一个门禁，后续只用 Complete 读取状态。这样既保留了自建流程的灵活性，也不会把“已标记完成”误写成“所有内容都被自动验证”。