泛型方法组织链式API

我第一次把一组“转换后继续过滤”的 Go API 改成链式写法时，最明显的问题不是代码少了多少，而是类型变化藏在了一串普通函数里：MapList(MapList(values, f1), f2) 能工作，却要从最里层往外读。Go 1.27 为具体方法加入类型参数后，可以把跨类型转换收回到数据类型自己的方法集合里。

官方资料：https://go.dev/blog/generic-methods

这篇文章用一个小型 Chain[T] 说明怎么组织链式 API。核心原则是：接收者的 T 表示当前数据，方法的 R 只表示本次转换结果；过滤、取值等不改变元素类型的操作则保持普通方法。这样 API 读起来顺，类型边界也没有被藏掉。

Go 1.27 的泛型方法适合做具体类型的组织工具。它能让 Chain[int].Map[string] 变成自然的左到右表达式，但不能让这个具体类型自动满足一个“泛型接口方法”契约。

先把链式 API 的资产和风险分开

链式 API 真正要保护的是三件事：每一步的数据类型、转换函数的输入输出、以及调用方能看到的错误边界。旧式泛型函数把类型写在参数里，类型本身没有承担组织职责；新的方法写法把能力放回 Chain[T]，但并不意味着所有操作都应该加一个新的类型参数。

我会先画出一条最小链：Chain[int] 经过一个接收 int、返回 string 的函数，得到 Chain[string]；之后的过滤仍然只处理 string。这里 T 是接收者已经携带的类型，R 是当前方法新增的类型。两个角色混在一起，后面很容易出现“方法能调用，但读者看不出数据已经换型”的问题。

用 Map[R] 把转换留在类型内部

下面的实现只依赖切片，适合先看清类型流转。Map 的关键不是“把方法写长”，而是让返回值明确变成新的 Chain[R]。代码中的注释说明了接收者参数、方法参数和资源复制边界。

package main

import "fmt"

// Chain 把当前元素类型 T 绑定到链式数据上。
type Chain[T any] []T

// Map 允许本次转换引入新的结果类型 R，返回新的 Chain[R]。
func (c Chain[T]) Map[R any](fn func(T) R) Chain[R] {
	// 预先分配结果容量，避免转换过程中反复扩容。
	out := make(Chain[R], len(c))
	for i, value := range c {
		// fn 的输入固定为 T，输出固定为 R，边界由编译器检查。
		out[i] = fn(value)
	}
	return out
}

// Filter 不改变元素类型，因此只复用接收者的 T，不新增类型参数。
func (c Chain[T]) Filter(keep func(T) bool) Chain[T] {
	out := make(Chain[T], 0, len(c))
	for _, value := range c {
		if keep(value) {
			out = append(out, value)
		}
	}
	return out
}

// Values 返回普通切片，明确结束链式封装，避免调用方继续误用内部状态。
func (c Chain[T]) Values() []T {
	return append([]T(nil), c...)
}

func main() {
	// 这里的链条从 int 变成 string，再在 string 类型上过滤。
	result := Chain[int]{1, 2, 3, 4}.
		Map(func(n int) string { return fmt.Sprintf("ID-%d", n) }).
		Filter(func(s string) bool { return s != "ID-2" }).
		Values()

	fmt.Println(result)
}

调用方只需要关注每个箭头两端的类型：Chain[int] 的 Map 接收 func(int) string，返回 Chain[string]；接着 Filter 的回调自然就必须接收 string。如果把过滤回调写成 func(int) bool，错误会在调用处暴露，而不是等到运行时才发现。

不要为了“泛型”让每个方法都换型

我在实际整理接口时会把方法分成两类。第一类会改变元素类型，例如 Map[R]、未来可能出现的 FlatMap[R]；它们应该显式声明 R，让返回的类型变化可见。第二类只改变集合形状或筛选结果，例如 Filter、Take、Values，它们复用 T 就够了。

这也是一个安全边界：如果每个方法都设计成“任意类型进、任意类型出”，调用链会失去约束，错误处理、空值语义和数据契约都会变得模糊。方法名可以短，但类型变化不能隐身。对公开包来说，宁愿多保留一个清晰的普通方法，也不要为了追求链式外观把所有状态都塞进类型参数。

如果项目仍需要函数式的“从外向内”组合，也可以保留一个普通泛型函数作为适配层。泛型方法主要解决的是组织和可读性，不是要求整个包都改成方法调用。

检查接口、实例化和版本边界

这里最容易出现的误判是：看到 Map[R] 能实例化，就以为实例化后的方法可以让 Chain[T] 满足某个接口。Go 官方说明得很清楚：接口实现看的是类型的方法集合，不是某一次调用产生的“方法实例”。当前语法允许具体类型拥有泛型方法，但接口方法本身不能声明类型参数，所以两者不是同一种契约。

// Processor 只描述一个普通的、非泛型方法。
type Processor interface {
	Process() string
}

// Chain[T] 可以声明普通方法来满足类似的接口契约。
func (c Chain[T]) Process() string {
	return fmt.Sprintf("items=%d", len(c))
}

// Map[R] 的实例化只服务于具体调用，不会把泛型接口方法变出来。
var _ Processor = Chain[int]{}

发布前我会按四项检查：编译环境是否已经是支持该语法的 Go 1.27；转换方法是否明确写出 func(T) R；不换型的方法是否保持 Chain[T]；需要接口多态时，接口是否只依赖普通方法。尤其不要把示例里的 Map[string] 当成一个可以单独声明、再塞进接口的成员。

适合采用的场景

如果一个类型天然拥有连续的数据操作，例如列表转换、查询构造、解析结果整理，泛型方法能让能力靠近数据类型，链式调用也更符合阅读方向。若项目需要跨包的接口分发、插件替换或动态多态，则应把稳定能力收敛到普通接口方法，把泛型方法当作具体类型的便利 API。

我的取舍是：先用一个跨类型的 Map[R] 证明链条确实变清楚，再补两个不换型的普通方法，最后用接口断言守住公开契约。这样泛型方法承担组织职责，接口承担多态职责，两个边界都比较容易审计。

相关问题

Go 1.27 以前怎么写同样的转换？可以用普通泛型函数，例如 MapChain[T, R](Chain[T], func(T) R) Chain[R]，但多次转换通常要从内到外嵌套。

Map 的类型参数能省略吗？通常可以由回调参数和返回值推断；如果方法值脱离调用上下文，仍需要提供足够的类型信息。

泛型方法能直接实现泛型接口吗？不能把具体泛型方法实例化后当成接口方法；当前 Go 语法不允许接口方法声明类型参数，应改用普通接口方法或普通泛型函数。