vload

README

ValueLoader Package

这个包提供了一个灵活的值加载器，用于动态加载和填充结构体字段。主要用于批量加载关联数据，减少数据库查询次数，提高性能。

安装

使用以下命令安装：

go get gitee.com/virtual-moon/vload

版本要求

• Go 1.18 或更高版本 (需要泛型支持)

主要特性

• 支持泛型值获取器
• 类型安全的字段映射
• 支持多分组加载
• 自动类型推断
• 支持结构体和切片（包括指针切片）
• 零值字段自动跳过
• 灵活的分组机制
• 并发安全

主要组件

1. types.go

   • Pair: 字段映射对定义
   • Getter: 泛型值获取器
   • Loader: 值加载器结构

2. loader.go

   • AddMapping: 添加字段映射
   • Load: 主加载方法
   • 字段映射验证

3. utils.go

   • 值获取器调用
   • 键值收集
   • 值填充

4. quick.go

   • 快速加载方法
   • 数据加载实现

使用示例

基础用法 - 单一字段映射

// 支持结构体切片
var orders []Order
err := vload.LoadQuick(
    &orders,
    "GoodsId",   // 源字段（用于获取值的字段）
    "GoodsName", // 目标字段（用于填充值的字段）
    func(keys []int64) (map[int64]string, error) {
        // 实现值获取逻辑
        return namesMap, nil
    },
)

// 同样支持指针切片
var users []*User
err := vload.LoadQuick(
    &users,
    "DeptId",   // 源字段
    "DeptName", // 目标字段
    getDeptNames,
)

快速用法 - 同类型多字段映射

// 定义字段映射关系
fields := []vload.FieldPair{
    {Source: "UserId", Target: "UserName"},
    {Source: "CreatorId", Target: "CreatorName"},
    {Source: "UpdaterId", Target: "UpdaterName"},
}

// 使用简化版本，自动推断类型
err := vload.LoadQuickMulti(
    &orders,
    fields,
    func(keys []int64) (map[int64]string, error) {
        // 实现值获取逻辑：一次性获取所有用户名
        // keys 包含了所有 UserId、CreatorId 和 UpdaterId 的值
        names, err := db.QueryUserNames(keys)
        if err != nil {
            return nil, err
        }
        return names, nil
    },
)

// 使用完整版本，指定字段类型
err := vload.LoadQuickMultiWithType(
    &orders,
    fields,
    reflect.Int64,  // 源字段类型
    reflect.String, // 目标字段类型
    getUserNames,   // 值获取器
)

高级用法 - 多字段映射

loader := vload.New()

// 添加用户信息映射
loader.AddMapping("users", []vload.Pair{
    {
        SourceField: "UserId",   // 源字段
        TargetField: "UserName", // 目标字段
    },
}, getUserNames)

// 添加商品信息映射
loader.AddMapping("goods", []vload.Pair{
    {
        SourceField: "GoodsId",   // 源字段
        TargetField: "GoodsName", // 目标字段
    },
}, getGoodsNames)

// 执行加载
err := loader.Load(&data)

常见使用场景

1. 批量加载关联数据

   type Order struct {
       UserId    int64  // 源字段
       UserName  string // 目标字段
       GoodsId   int64  // 源字段
       GoodsName string // 目标字段
   }
   

2. 字段映射和转换

   type UserView struct {
       Code     string // 源字段
       UserInfo User   // 目标字段
   }
   

3. 多级数据填充

   type Department struct {
       ManagerId   int64  // 源字段
       ManagerName string // 目标字段
       ParentId    int64  // 源字段
       ParentName  string // 目标字段
   }
   

4. 系统统一处理 可在系统里创建一个通用统一的键值处理，如ERP系统，可以创建一个整个系统规范的字段加载器，有需要用到的数据可直接调用处理。

   var userLoad *vload.Loader
   var goodsLoad *vload.Loader
   
   func init() {
       userLoad = vload.New()
       userLoad.AddMapping("user", []vload.Pair{
           {SourceField: "CreatedId", TargetField: "CreatedBy"},
           {SourceField: "UpdatedId", TargetField: "UpdatedBy"},
           {SourceField: "CheckedId", TargetField: "CheckedBy"},
       }, func(keys []int64) (map[int64]string, error) {
           return GetUserNames(keys)
       })
   
       goodsLoad = vload.New()
       goodsLoad.AddMapping("goods", []vload.Pair{
           {SourceField: "GoodsId", TargetField: "GoodsName"},
       }, func(keys []int64) (map[int64]string, error) {
           return GetGoodsNames(keys)
       })
   }
   

   userLoad.Load(&orders)
   

   userLoad.Load(&orderDetails)
   

性能优化建议

1. 合理分组：相同数据源的字段放在同一组，减少查询次数
2. 使用合适的切片容量：预估数据量，避免频繁扩容
3. 实现高效的值获取器：可以使用缓存或批量查询优化性能

注意事项

1. 指定正确的字段类型：确保源字段和目标字段的类型匹配
2. 处理错误返回：值获取器返回的错误需要妥善处理
3. 避免循环依赖：设计映射关系时注意避免循环引用

贡献

欢迎提交 Issue 和 Pull Request 来改进这个包。

Documentation

Index

• func LoadQuick[K comparable, V any](data interface{}, sourceField string, targetField string, getter Getter[K, V]) error
• func LoadQuickMulti[K comparable, V any](data interface{}, fields []FieldPair, getter Getter[K, V]) error
• func LoadQuickMultiWithType[K comparable, V any](data interface{}, fields []FieldPair, sourceType reflect.Kind, ...) error
• func LoadQuickWithType[K comparable, V any](data interface{}, sourceField string, targetField string, ...) error
• type FieldPair
• type Getter
• type Loader
  • func New() *Loader
  • func (l *Loader) AddMapping(group string, pairs []Pair, getter interface{})
  • func (l *Loader) Load(data interface{}) error
• type Pair

Functions

func LoadQuick

func LoadQuick[K comparable, V any](
	data interface{},
	sourceField string,
	targetField string,
	getter Getter[K, V],
) error

LoadQuick 快速加载单一分组的值映射

func LoadQuickMulti

func LoadQuickMulti[K comparable, V any](
	data interface{},
	fields []FieldPair,
	getter Getter[K, V],
) error

LoadQuickMulti 快速加载多个字段的值映射

func LoadQuickMultiWithType

func LoadQuickMultiWithType[K comparable, V any](
	data interface{},
	fields []FieldPair,
	sourceType reflect.Kind,
	targetType reflect.Kind,
	getter Getter[K, V],
) error

LoadQuickMultiWithType 带类型指定的多字段快速加载方法

func LoadQuickWithType

func LoadQuickWithType[K comparable, V any](
	data interface{},
	sourceField string,
	targetField string,
	sourceType reflect.Kind,
	targetType reflect.Kind,
	getter Getter[K, V],
) error

LoadQuickWithType 带类型指定的快速加载方法

Types

type FieldPair

type FieldPair struct {
	Source string
	Target string
}

FieldPair 字段映射对

type Getter

type Getter[K comparable, V any] func([]K) (map[K]V, error)

Getter 泛型值获取器

type Loader

type Loader struct {
	// contains filtered or unexported fields
}

Loader 值加载器

func New

func New() *Loader

New 创建新的值加载器

func (*Loader) AddMapping

func (l *Loader) AddMapping(group string, pairs []Pair, getter interface{})

AddMapping 添加字段映射和对应的值获取器

func (*Loader) Load

func (l *Loader) Load(data interface{}) error

Load 加载数据

type Pair

type Pair struct {
	SourceField string       // 源字段名（用于获取值的字段）
	TargetField string       // 目标字段名（用于填充值的字段）
	SourceType  reflect.Kind // 源字段类型
	TargetType  reflect.Kind // 目标字段类型
	Group       string       // 分组标识，相同分组的字段会一起处理
}

Pair 定义字段映射对，用于指定源字段和目标字段