【TD】支持使用组合来定义模型

[flycash]

需求分析

目前来说，我们仅仅支持最为简单的模型定义。但是在大多数场景下，用户会考虑使用组合来定义模型。例如常见的是公司有规范，所有的数据库表都必须有创建时间和更新时间。在这种情况下，最好的解决方案就是大家都组合一个公共的结构体，例如：

type BaseEntity struct {
    CreateTime uint64
    UpdateTime uint64
}

type User struct {
    Id int64
    BaseEntity
}

在这种情况下，我们认为User对应的表含有三个列：id, create_time 和 update_time。

场景分析

除了前面提到的这种最简单的组合形式以外，用户可能定义一些比较奇怪的组合形式。

指针组合

type User struct {
    BaseEntity
}

type UserV1 struct {
    *BaseEntity
}

目前我们不需要支持 UserV1 这种形态，即不支持使用指针的组合。目前想象不到在 ORM 场景中，有什么是必须要使用这种形态来解决的。

多重组合

type UserV2 struct {
    BaseEntity
    OtherEntity
}

这种虽然罕见，但是可以考虑支持。

嵌套组合

即组合套组合。

type BaseEntity struct {
    CreateTime uint64
    UpdateTime uint64
}

type User struct {
    BaseEntity
}

type Buyer struct {
    User
}

嵌套组合在复杂的企业级应用中可能会出现，所以可以考虑支持这种形态。那么结合前面多重组合，那么这种形态也是可以的：

type Buyer struct {
    User
    OtherEntity
}

字段冲突

在简单的模型定义里面，是不存在字段冲突的情况的，因为编译期会直接报错。但是在引入了组合之后，那么字段冲突就变可能了。冲突可能是内部结构体字段和外部结构体字段冲突，也可能是多重嵌套不同内部结构体之间的字段冲突。例如：

type BaseEntity struct {
	Id         int64
	CreateTime int64
	UpdateTime int64
}

// ID 冲突了
type User struct {
	Id uint64
	BaseEntity
}

或者：

type BaseEntity struct {
	Id         int64
	CreateTime int64
	UpdateTime int64
}

type OtherEntity struct {
	CreateTime uint64
}

type User struct {
	BaseEntity
	OtherEntity
}

在 eorm 中，组合被认为是同一张表，而同一张表是不允许出现重复列的。我们的选择是，如果碰到冲突列，我们会报错。等到将来综合用户反馈，再进一步考虑要不要放松这个限制。

忽略组合

某些时候用户希望忽略掉组合。例如说：

type User struct {
	BaseEntity
	OtherEntity `eorm:"-"`
}

组合与普通字段的区别

另外还有一点需要澄清，即组合和普通字段在模型定义上的不同语义：

type User struct {
    BaseEntity
}

type UserV3 struct {
    BaseEntity BaseEntity
}

关键在于，在使用组合的情况下，我们认为它们是同一张表；而定义成 UserV3 这种普通字段，我们认为它更加接近于关联关系，即一对多，多对一等。

功能需求

从前面的场景分析可以总结下来，我们需要做到的是：

• 支持组合，但是只支持普通的结构体组合，指针类型的组合不允许
• 支持多重组合
• 支持嵌套组合
• 在字段冲突的时候，返回错误
• 支持忽略组合

同样地，组合的内部结构体字段也可以使用eorm标签，用于定义列的别名等。

非功能需求

在引入组合之后，影响最大的就是性能，而且使用组合的性能必然比不使用组合的性能差。因为组合难免会引入递归计算之类的问题。很显然，这样会比普通的结构体消耗更多的 CPU 资源和内存资源。

行业方案

简单来说，支持组合应该算是 ORM 里面的标准。GORM，Beego ORM，ENT，Vitess 都支持组合，虽然他们从程度上来说各不相同。因为我们在场景分析里面已经做出了决定究竟要支持什么样的组合，所以这里就不必深入探究它们对组合的支持程度。

设计

支持组合主要影响的是

• 模型元数据解析
• 读写实例字段，也就是 Value 抽象

这两个部分可以看做是 eorm 的核心模块，因为相应的，CRUD 等各种查询也会间接收到影响。

详细设计

模型元数据解析

目前我们已经有了一个接口和一个实现：

type MetaRegistry interface {
	Get(table interface{}) (*TableMeta, error)
	Register(table interface{}, opts ...TableMetaOption) (*TableMeta, error)
}

type tagMetaRegistry struct {
	metas sync.Map
}

那么修改就局限于在它的Register方法。这个 Register 无可避免要使用递归来解析元数据：

// Register function generates a metadata for each column and places it in a thread-safe mapping to facilitate direct access to the metadata.
// And the metadata can be modified by user-defined methods opts
func (t *tagMetaRegistry) Register(table interface{}, opts ...TableMetaOption) (*TableMeta, error) {
	rtype := reflect.TypeOf(table)
	v := rtype.Elem()
	columnMetas, fieldMap, err := t.parseFields(v)
	if err != nil {
		return nil, err
	}
	tableMeta := &TableMeta{
		Columns:   columnMetas,
		TableName: underscoreName(v.Name()),
		Typ:       rtype,
		FieldMap:  fieldMap,
	}
	for _, o := range opts {
		o(tableMeta)
	}
	t.metas.Store(rtype, tableMeta)
	return tableMeta, nil
}

func (t *tagMetaRegistry) parseFields(v reflect.Type)  ([]*ColumnMeta,map[string]*ColumnMeta,error) {
	lens := v.NumField()
	columnMetas := make([]*ColumnMeta, 0, lens)
	fieldMap := make(map[string]*ColumnMeta, lens)
	for i := 0; i < lens; i++ {
		structField := v.Field(i)
		tag := structField.Tag.Get("eorm")
		var isKey, isAuto, isIgnore bool
		for _, t := range strings.Split(tag, ",") {
			switch t {
			case "primary_key":
				isKey = true
			case "auto_increment":
				isAuto = true
			case "-":
				isIgnore = true
			}
		}
		if isIgnore {
			// skip the field.
			continue
		}

		// 是组合
		if structField.Anonymous && structField.Type.Kind() == reflect.Struct {
			// 递归解析
			subColumns, subFieldMap, err := t.parseFields(structField.Type)
			// 检查列有没有冲突
		}

		columnMeta := &ColumnMeta{
			ColumnName:      underscoreName(structField.Name),
			FieldName:       structField.Name,
			Typ:             structField.Type,
			IsAutoIncrement: isAuto,
			IsPrimaryKey:    isKey,
		}
		columnMetas = append(columnMetas, columnMeta)
		fieldMap[columnMeta.FieldName] = columnMeta
	}
	return columnMetas, fieldMap, nil
}

要点是：

• Register 不再直接解析字段，而是依赖于 parseField 进行解析
• parseField 会遍历字段，如果一个字段是组合，那么就递归解析
• parseField 在递归解析组合的时候，会检测字段有没有冲突

Value 读字段

目前我们设计的Value接口，只含有一个方法：

// Value 是对结构体实例的内部抽象
type Value interface {
	// Field 访问结构体字段
	Field(name string) (interface{}, error)
}

并且只有一个基于反射的实现reflectValue。所以在支持组合之后要考虑如何读取到组合的字段，例如在模型定义为：

type BaseEntity struct {
    CreateTime uint64
    UpdateTime uint64
}

type User struct {
    Id int64
    BaseEntity
}

如果发起调用val.Field("CreateTime")，那么应该返回BaseEntity.CreateTime的值。

解决方案是引入祖先概念。在ColumnMeta里面新加一个字段：

type ColumnMeta struct {
        // ...
	Ancestors []string
}

那么reflecValue的取值逻辑就变成：

// reflectValue 基于反射的 Value
type reflectValue struct {
	val reflect.Value
	meta *model.TableMeta
}

// Field 返回字段值
func (r reflectValue) Field(name string) (interface{}, error) {
	columnMeta, ok := r.meta.FieldMap[name]
	if !ok {
		return nil, errs.NewInvalidColumnError(name)
	}

	val := r.val
	for _, ancestor := range columnMeta.Ancestors {
		//
		val = val.FieldByName(ancestor)
		if val == (reflect.Value {}) {
			return nil, errs.NewInvalidColumnError(name)
		}
	}

	val = val.FieldByName(name)
	if val == (reflect.Value {}) {
		return nil, errs.NewInvalidColumnError(name)
	}
	return val.Interface(), nil
}

相应地，要在前面的 parseFields里面加上相应的计算Ancestors的逻辑。

IgnoreFieldsOption

这个方法也要考虑支持忽略组合：

func IgnoreFieldsOption(fieldNames ...string) TableMetaOption {
	return func(meta *TableMeta) {
		for _, field := range fieldNames {
			// has field in the TableMeta
			if _, ok := meta.FieldMap[field]; ok {
				// delete field in columns slice
				for index, column := range meta.Columns {
					if column.FieldName == field {
						meta.Columns = append(meta.Columns[:index], meta.Columns[index+1:]...)
						break
					}
				}
                                // 要在这里删除所有 Ancestors 里面含有 field 的字段，包括从 Columns 和 FieldMap 里面删除
				// delete field in fieldMap
				delete(meta.FieldMap, field)
			}
		}
	}
}

测试

单元测试

单元测试要覆盖功能需求里面的场景：

• 支持组合，但是只支持普通的结构体组合，指针类型的组合不允许
• 支持多重组合
• 支持嵌套组合
• 在字段冲突的时候，返回错误
• 支持忽略组合

同时要考虑这些场景混合在一起：

• 多重组合和嵌套组合混合
• 嵌套组合，但是内部使用的是指针类型
• 多重组合 + 字段冲突
• 嵌套组合 + 字段冲突
• 忽略组合 + 字段冲突：即组合里面含有冲突字段，但是恰好这个组合是被忽略
• 使用 IgnoreFieldsOption 来忽略组合，那么组合内结构体的所有字段也会被同步忽略掉

集成测试

N/A。

基准测试

要对 Register 方法和 Field 进行基准测试，要考虑三种情况：

• 无组合，仅仅是简单结构体定义
• 组合
• 嵌套组合

模糊测试

需要对 Field 进行模糊测试。同样需要考虑三种情况：

• 无组合，仅仅是简单结构体定义
• 组合
• 嵌套组合

[flycash]

不考虑指针形态的组合，理由也是非常简单：

• 指针组合对 unsafe 操作不友好， eorm 计划提供的一个底层实现就是基于 unsafe 的
• 正常情况下，数据库模型上也用不到指针组合。应该说，目前我还没见到有什么场景是只能用指针组合的