Go interface 改成泛型后测试如何保持等价

Go 项目把一组 interface API 改成泛型后，测试最容易出现的误区是“旧测试能编译，迁移就等价”。真正要保持的是行为契约：相同输入得到相同输出，相同边界条件返回相同错误，空集合和 nil 的处理也不能悄悄变化。稳妥做法是保留原测试表，让 interface 版本和泛型版本同时接受这组样例，再逐步替换调用方。

官方资料：https://go.dev/doc/tutorial/generics

下面用一个“按键读取并转换值”的小例子说明迁移路径。泛型约束只声明实现确实需要的能力；测试负责比较行为，而不是比较两套代码的内部写法。

先把 interface 版本的行为写成测试表

假设旧 API 面向的是一个可以按键读取字符串的接口。测试表记录正常键、缺失键和空值三个边界，后面的泛型实现必须逐项保持这些结果。

package lookup

import (
	"errors"
	"testing"
)

var ErrMissing = errors.New("missing key")

// StringLookup 是旧调用方依赖的最小接口，只暴露行为契约。
type StringLookup interface {
	Get(string) (string, error)
}

// readName 代表迁移前的业务入口，测试只关心返回值和错误。
func readName(src StringLookup, key string) (string, error) {
	return src.Get(key)
}

type mapLookup map[string]string

// Get 保持旧接口的缺失键语义，不能用空字符串掩盖错误。
func (m mapLookup) Get(key string) (string, error) {
	v, ok := m[key]
	if !ok {
		return "", ErrMissing
	}
	return v, nil
}

func TestLookupContract(t *testing.T) {
	tests := []struct {
		name string
		key  string
		want string
		err  error
	}{
		{name: "命中", key: "name", want: "Go"},
		{name: "空值仍然成功", key: "empty", want: ""},
		{name: "缺失", key: "unknown", err: ErrMissing},
	}

	src := mapLookup{"name": "Go", "empty": ""}
	for _, tt := range tests {
		t.Run(tt.name, func(t *testing.T) {
			got, err := readName(src, tt.key)
			if !errors.Is(err, tt.err) || got != tt.want {
				t.Fatalf("got (%q, %v), want (%q, %v)", got, err, tt.want, tt.err)
			}
		})
	}
}

这里的重点不是接口本身，而是测试表把“空值成功”和“键不存在失败”分开了。迁移时如果泛型实现只返回一个值，或者把缺失键变成空字符串，编译器不会替你发现，等价性测试才会发现。

用泛型表达数据类型，用约束表达能力

泛型版本可以接收任意键和值类型，但它需要一个明确的查找能力。把能力写成约束后，调用方传入 map 或自定义容器都可以，测试仍然沿用同一份行为样例。

type Getter[K comparable, V any] interface {
	Get(K) (V, error)
}

// readGeneric 只依赖 Getter 的读取能力，不依赖具体容器类型。
func readGeneric[K comparable, V any](src Getter[K, V], key K) (V, error) {
	return src.Get(key)
}

type genericMap[K comparable, V any] map[K]V

// Get 让 map 适配泛型约束，并显式保留缺失键错误。
func (m genericMap[K, V]) Get(key K) (V, error) {
	v, ok := m[key]
	if !ok {
		var zero V
		return zero, ErrMissing
	}
	return v, nil
}

Go 官方泛型教程说明，类型参数的约束决定调用方可以传入哪些类型；约束不是运行时校验。这里用 comparable 约束键，是因为 map 查找需要可比较键；值使用 any，因为读取动作并不要求值支持加法或排序。

让同一组测试同时覆盖两种实现

迁移期不要复制一份“泛型专用测试”。可以把断言抽成泛型测试函数，再给它传入旧接口适配器和泛型容器。这样新增边界样例时，两条实现会自动收到相同的输入。

type lookupCase struct {
	name string
	key  string
	want string
	err  error
}

// assertLookupContract 比较公共行为，不比较实现细节。
func assertLookupContract[K comparable, V comparable](
	t *testing.T,
	read func(K) (V, error),
	cases []struct {
		name string
		key  K
		want V
		err  error
	},
) {
	t.Helper()
	for _, tc := range cases {
		t.Run(tc.name, func(t *testing.T) {
			got, err := read(tc.key)
			if !errors.Is(err, tc.err) || got != tc.want {
				t.Fatalf("got (%v, %v), want (%v, %v)", got, err, tc.want, tc.err)
			}
		})
	}
}

func TestImplementationsStayEquivalent(t *testing.T) {
	cases := []struct {
		name string
		key  string
		want string
		err  error
	}{
		{name: "命中", key: "name", want: "Go"},
		{name: "空值", key: "empty", want: ""},
		{name: "缺失", key: "unknown", err: ErrMissing},
	}

	old := mapLookup{"name": "Go", "empty": ""}
	newImpl := genericMap[string, string](old)
	assertLookupContract(t, old.Get, cases)
	assertLookupContract(t, newImpl.Get, cases)
}

两套实现现在共享同一组键和值。这里的泛型测试函数本身没有把旧接口“强行转换”为泛型；它只接收一个函数值，因此既能接收方法表达式，也能接收带适配逻辑的闭包，迁移边界更清晰。

按调用边界迁移，暂时保留适配层

当项目调用方很多时，不建议一次删除 interface。先让新泛型实现满足旧入口，再在包边界替换调用方；如果某个外部实现只实现了旧接口，就保留一个小适配器。适配器的测试应继续放在公共契约测试旁边，避免“新 API 有测试、旧插件没有测试”。

迁移完成前检查哪些容易漏掉的差异

测试通过后，还要专门检查以下边界：第一，泛型零值是否与旧接口返回值一致；第二，错误是否仍能被 errors.Is 识别；第三，接口里保存的 typed nil 是否与泛型容器的 nil 语义一致；第四，调用方依赖的方法集是否被约束准确表达；第五，类型推断失败的调用是否需要显式类型参数。

如果只改了类型签名而没有改变行为，测试应该成为迁移的护栏，而不是迁移之后才补的装饰。保留一轮并行期后，再根据依赖方数量删除旧接口，能让每次改动都能定位到具体契约，而不是在大范围重构后追查一串失败用例。

相关问题

泛型函数能完全替代 interface 吗？不能一概而论。泛型适合在编译期表达同一算法对多种类型的复用；interface 更适合运行时替换实现、插件边界或只关心方法集合的调用方。

迁移时需要复制两套测试吗？不需要。把输入、期望输出和错误写成共享测试表，再为两种实现提供相同形状的读取函数即可。

为什么泛型约束写得越宽不一定越好？约束越宽，函数能接受的类型越多，但也更难表达代码真正依赖的操作。优先写出最小能力集合，等新增用例证明需要时再扩展。