Go 泛型方法怎样为自定义类型设计链式 API

Go 1.27 之后，可以直接给具体类型的方法声明额外的类型参数。设计链式 API 时，最稳妥的分工是：让泛型类型 Chain[T] 保存当前元素类型，让 Filter 这类筛选方法保持 T，让 Map[R] 这类转换方法返回新的 Chain[R]。这样调用者能从左到右阅读，编译器也能从函数参数推导类型。

先把链式 API 的类型职责拆开

链式调用最容易失控的地方，是每个方法都随意改变内部类型。可以先固定一个小模型：构造函数负责创建 Chain[T]，同类型操作返回 Chain[T]，跨类型操作才引入新的 R。下面的代码把复制边界也放在类型里，避免调用方直接修改内部切片。

package main

import "fmt"

// Chain 保存当前阶段的值；T 由构造函数或上一步 Map 决定。
type Chain[T any] struct {
	values []T
}

// Of 复制输入切片，避免外部后续修改影响链路。
func Of[T any](values ...T) Chain[T] {
	return Chain[T]{values: append([]T(nil), values...)}
}

// Map 允许链路从 T 转换为 R，R 可从转换函数的返回值推导。
func (c Chain[T]) Map[R any](fn func(T) R) Chain[R] {
	out := make([]R, 0, len(c.values))
	for _, value := range c.values {
		// 转换函数只负责单个元素，集合容量由当前链路统一管理。
		out = append(out, fn(value))
	}
	return Chain[R]{values: out}
}

// Filter 只筛选元素，不改变链路的元素类型。
func (c Chain[T]) Filter(keep func(T) bool) Chain[T] {
	out := make([]T, 0, len(c.values))
	for _, value := range c.values {
		if keep(value) {
			out = append(out, value)
		}
	}
	return Chain[T]{values: out}
}

// Collect 返回副本，调用者可以安全地修改结果。
func (c Chain[T]) Collect() []T {
	return append([]T(nil), c.values...)
}

func main() {
	result := Of(1, 2, 3, 4).
		Filter(func(v int) bool { return v%2 == 0 }).
		Map(func(v int) string {
			// 这里把保留下来的数字转换成展示文本。
			return fmt.Sprintf("id=%d", v)
		}).
		Collect()
	fmt.Println(result) // [id=2 id=4]
}

这里的 Filter 没有额外类型参数，所以结果仍是 Chain[int]；Map 根据匿名函数的返回值把结果推进到 Chain[string]。链路中不需要反复写 Chain[int] 或 Chain[string]。

用 Map[R] 把跨类型转换放在方法上

如果只用 Go 1.18 的泛型函数，转换通常要写成嵌套调用，例如 Map(Map(source, f1), f2)。Go 1.27 的具体类型泛型方法可以把结果类型放在方法返回值中，调用改成自然的左到右顺序：

// Add 返回一个可复用的 int 转换函数。
func Add(delta int) func(int) int {
	return func(value int) int {
		// 闭包捕获 delta，调用方只关心输入和输出类型。
		return value + delta
	}
}

func demo() []string {
	return Of(1, 2, 3).
		Map(Add(10)).
		Map(func(value int) string {
			// 第二次 Map 将 int 变成最终展示值。
			return fmt.Sprintf("n=%d", value)
		}).
		Collect()
}

第一处 Map 推导出 R=int，第二处推导出 R=string。只有当转换函数本身的信息不足时，才需要显式写类型实参，例如 chain.Map[string](format)。把类型转换收敛到 Map，也能让每个方法的职责更容易测试。

保持类型的方法要控制副作用和边界

Filter、Take、Distinct 等方法通常不需要新的类型参数，返回 Chain[T] 即可。建议采用值接收者和新切片返回值，让每一步都像不可变快照；如果数据量很大，再单独提供明确命名的原地版本，不要让普通链式方法暗中共享底层数组。

接口和版本边界要提前写进设计说明

泛型方法属于具体类型的能力。Go 1.27 允许 func (c Chain[T]) Map[R any](...)，但接口仍不能声明带类型参数的方法，因此不能期待一个接口同时抽象出任意 Map[R]。需要接口时，把稳定的非泛型行为抽出来，例如只暴露 Len、CollectAny，或改用包级泛型函数。

项目应在 go.mod 中明确使用 go 1.27，并在 CI 中用同一工具链编译。若仍需兼容旧版本，把 Map 改为包级函数是更清晰的降级路径，不要保留一个无法编译的伪方法声明。

相关问题

Map 的类型参数一定要手写吗？

不一定。只要转换函数的参数和返回值包含足够的类型信息，编译器通常可以推导 R；无参数或信息不足的函数值才需要显式类型实参。

为什么 Filter 不设计成 Filter[R]？

筛选只决定保留哪些 T，不负责改变元素类型。把转换职责交给 Map[R]，调用链的返回类型会更直观。

旧 Go 版本怎样保留同样的语义？

把跨类型操作改成包级泛型函数，例如 Map[T, R](chain, fn)；代价是调用顺序不如方法链自然，但类型边界仍然清楚。