用泛型方法封装类型安全的分页结果映射

Go 1.27 允许具体方法声明自己的类型参数，因此可以直接给 Page[T] 定义 Map[U]：输入是分页模型，输出是分页 DTO，编译器会检查转换函数的入参和返回类型，分页总数、页码和页大小则由容器统一复制。这个写法需要 Go 1.27；旧版本应继续使用包级泛型函数。

我以前在服务层反复写 Page[User] 到 Page[UserDTO] 的循环，最烦的并不是那几行转换代码，而是每个调用点都要手动复制 Total、PageNo 和 PageSize。泛型方法把这件事收回到分页类型本身后，调用代码更短，也不需要 any 和类型断言。

Go 1.27 官方说明：https://go.dev/doc/go1.27

最小配方：让分页容器自己完成映射

先定义一个只包含数据列表和分页元数据的通用容器。Map 声明新的类型参数 U，它与接收者上的 T 相互独立：T 表示原始元素，U 表示映射后的元素。

package pagination

import "fmt"

// Page 保存当前页数据和不会随元素类型变化的分页元数据。
type Page[T any] struct {
	Items    []T
	Total    int64
	PageNo   int
	PageSize int
}

// Map 将每个 T 转为 U；任一元素失败时返回带索引的错误，避免交付半成品。
func (p Page[T]) Map[U any](convert func(T) (U, error)) (Page[U], error) {
	items := make([]U, 0, len(p.Items))
	for i, item := range p.Items {
		mapped, err := convert(item)
		if err != nil {
			return Page[U]{}, fmt.Errorf("map page item %d: %w", i, err)
		}
		items = append(items, mapped)
	}

	// 元数据与元素类型无关，在容器内部统一复制可避免调用方遗漏字段。
	return Page[U]{
		Items:    items,
		Total:    p.Total,
		PageNo:   p.PageNo,
		PageSize: p.PageSize,
	}, nil
}

这里选择“遇错即失败”，而不是返回部分结果。对 API 分页来说，半页成功、半页失败通常很难解释；如果业务确实允许跳过坏数据，可以把策略作为另一个显式方法，而不要让一个 Map 同时承担两种语义。

一个真实调用：从 User 映射到 UserDTO

假设仓储层返回数据库模型，而接口层只暴露经过筛选的 DTO。转换函数既可以做字段重命名，也可以执行格式化和校验。

package userapi

import (
	"errors"
	"strconv"
)

type User struct {
	ID       int64
	Nickname string
	Email    string
}

type UserDTO struct {
	ID   string `json:"id"`
	Name string `json:"name"`
}

// ToDTO 只暴露接口需要的字段，并拒绝缺少昵称的异常记录。
func ToDTO(user User) (UserDTO, error) {
	if user.Nickname == "" {
		return UserDTO{}, errors.New("nickname is empty")
	}
	return UserDTO{
		ID:   strconv.FormatInt(user.ID, 10),
		Name: user.Nickname,
	}, nil
}

func BuildResponse(page Page[User]) (Page[UserDTO], error) {
	// U 可从 ToDTO 的返回类型推断为 UserDTO，调用点无需写类型断言。
	return page.Map(ToDTO)
}

如果转换函数经过多层包装，或者希望让阅读者一眼看出目标类型，也可以显式写成 page.Map[UserDTO](ToDTO)。两种写法都保持编译期类型检查：把 func(Order) OrderDTO 误传给 Page[User] 会直接编译失败。

为什么这个方法比 any 版本更稳

我见过的旧封装常把列表写成 []any，再由调用方逐项断言。这会把错误从编译期推迟到运行时，而且分页方法无法表达“输入是 User，输出一定是 UserDTO”。泛型方法保留了这条类型关系，编辑器补全和重构工具也能跟上。

对我来说，泛型方法最明显的收益不是少写一个函数名，而是让 API 读起来更自然：先拿到一个分页对象，再在对象上完成映射。相关能力收在 Page 的命名空间里，也减少了包级辅助函数越来越多的问题。

无错误转换可以做一个轻量变体

如果字段转换不可能失败，可以提供 MapValue，避免调用方为了满足签名机械地返回 nil。不要把两种版本都命名为 Map，Go 不支持方法重载。

// MapValue 适合纯字段投影，不负责校验或外部查询。
func (p Page[T]) MapValue[U any](convert func(T) U) Page[U] {
	items := make([]U, len(p.Items))
	for i, item := range p.Items {
		items[i] = convert(item)
	}

	// 保留原分页语义，只替换 Items 的元素类型。
	return Page[U]{
		Items:    items,
		Total:    p.Total,
		PageNo:   p.PageNo,
		PageSize: p.PageSize,
	}
}

我会把需要数据库查询、网络调用或复杂校验的转换留在有错误返回的版本里。分页映射如果暗中触发 N+1 查询，即便类型再安全，整体设计仍然会变差。

泛型方法的边界：接口、推断与复用

Go 1.27 支持的是具体方法声明类型参数。接口方法仍不能声明类型参数，泛型具体方法也不能拿来实现一个同名的普通接口方法。需要抽象分页映射行为时，通常应让接口描述非泛型业务动作，或保留包级泛型函数，而不是强行把 Map[U] 塞进接口。

// 不能这样定义：接口方法不能声明自己的类型参数。
// type Mapper interface {
//     Map[U any](func(User) U) Page[U]
// }

// 可以固定实例化目标类型，定义具体业务接口。
type UserPageMapper interface {
	ToDTOPage() (Page[UserDTO], error)
}

方法值和方法表达式仍然可用。复用特定目标类型的映射器时，可以先实例化方法，再传给其他函数。

// 先把 U 固定为 UserDTO，得到一个普通函数值。
mapper := page.Map[UserDTO]

// 后续可以按需选择具体转换函数。
dtoPage, err := mapper(ToDTO)
if err != nil {
	return err
}
_ = dtoPage

兼容旧版本时保留包级函数

如果库需要兼容 Go 1.26 或更早版本，不要在公共源码里直接加入泛型方法。等价的包级函数可以保留同样的类型安全，只是调用形式从 page.Map(ToDTO) 变成 MapPage(page, ToDTO)。

// MapPage 是 Go 1.18+ 可用的兼容写法，逻辑与泛型方法一致。
func MapPage[T, U any](p Page[T], convert func(T) (U, error)) (Page[U], error) {
	items := make([]U, 0, len(p.Items))
	for i, item := range p.Items {
		mapped, err := convert(item)
		if err != nil {
			return Page[U]{}, fmt.Errorf("map page item %d: %w", i, err)
		}
		items = append(items, mapped)
	}

	// 兼容版本仍由一个位置负责复制分页元数据。
	return Page[U]{Items: items, Total: p.Total, PageNo: p.PageNo, PageSize: p.PageSize}, nil
}

测试时重点检查三个不变量

分页映射的测试不需要很复杂，但应固定三个不变量：元素顺序不变、分页元数据不变、转换失败不会返回部分结果。

func TestPageMap(t *testing.T) {
	input := Page[User]{
		Items:    []User{{ID: 7, Nickname: "Ada"}},
		Total:    21,
		PageNo:   2,
		PageSize: 10,
	}

	// 使用真实转换函数，验证类型变化和元数据复制。
	got, err := input.Map(ToDTO)
	if err != nil {
		t.Fatal(err)
	}
	if got.Total != 21 || got.PageNo != 2 || got.PageSize != 10 {
		t.Fatalf("pagination metadata changed: %+v", got)
	}
	if len(got.Items) != 1 || got.Items[0].ID != "7" {
		t.Fatalf("unexpected mapped items: %+v", got.Items)
	}
}

采用这套写法前的清单

• 模块的 go 版本已经升级到 1.27，构建链和编辑器工具也支持泛型方法。
• Page[T] 的元数据字段有清晰语义，不会因元素类型变化而需要重新计算。
• 可能失败的转换返回 error，纯字段投影再使用无错误变体。
• 不要依赖泛型方法实现接口方法；需要接口时固定具体类型或使用包级函数。
• 转换函数不应悄悄制造逐项数据库查询，批量依赖应在映射前准备。
• 测试覆盖空页、正常页、转换失败和元数据保留。

相关问题

调用 Map 时必须显式写 UserDTO 吗？

通常不必。转换函数的返回类型足以让编译器推断 U；当包装层让推断不清晰时，可以显式写 Map[UserDTO]。

泛型方法能实现泛型接口吗？

Go 1.27 的接口方法不能声明自己的类型参数，泛型具体方法也不用于匹配普通接口方法。可以实例化接收者类型后实现非泛型方法，或改用包级泛型函数。

空页映射后应该返回 nil 切片还是空切片？

这取决于 API 的序列化约定。上面的实现会为非 nil 的输入创建空切片；如果必须保留 nil 语义，可在分配前判断 p.Items == nil。

Map 里适合访问数据库吗？

一般不适合。逐项访问数据库很容易形成 N+1 查询；更稳妥的做法是先批量加载依赖，再让转换函数只做内存映射。

这套封装最适合边界清楚的分页 DTO 转换：输入、输出和错误都能在类型签名里说清楚。它不是所有列表处理的万能抽象，但在 Go 1.27 项目里，用一个小而明确的 Map[U] 取代重复循环和 any，往往能让服务层代码更容易读、改和测试。