4. Schema 进阶：索引、唯一约束、默认值函数、存储选项、注释与文档

在掌握了 Ent Schema 的基础字段与关系定义后，本章将深入探讨生产环境中不可或缺的进阶特性。这些特性直接决定了数据库表结构的性能、数据完整性以及可维护性。我们将逐一解析索引策略、唯一约束、动态默认值、存储引擎选项以及 Schema 级注释与文档的工程化实践。

4.1 索引：从单字段到复合覆盖

索引是查询性能的基石。Ent 通过 Indexes() 方法提供声明式索引定义，支持单字段索引、复合索引以及部分索引（PostgreSQL 特有）。

4.1.1 单字段与复合索引

// ent/schema/user.go
func (User) Indexes() []ent.Index {
    return []ent.Index{
        // 单字段索引
        index.Fields("email"),
        // 复合索引：先按 status 排序，再按 created_at 排序
        index.Fields("status", "created_at"),
    }
}

4.1.2 部分索引（PostgreSQL）

// 仅索引 status = 'active' 的行
func (User) Indexes() []ent.Index {
    return []ent.Index{
        index.Fields("email").
            Annotations(entsql.PartialIndex("WHERE status = 'active'")),
    }
}

4.2 唯一约束：保证数据完整性

唯一约束确保字段或字段组合的值在表中全局唯一。Ent 通过 Unique() 方法在字段级别声明，或在 Indexes() 中声明唯一复合索引。

4.2.1 字段级唯一约束

func (User) Fields() []ent.Field {
    return []ent.Field{
        field.String("email").
            Unique(),  // 单字段唯一
        field.String("phone").
            Unique().
            Optional(), // 可选但唯一
    }
}

4.2.2 复合唯一约束

func (User) Indexes() []ent.Index {
    return []ent.Index{
        index.Fields("tenant_id", "username").
            Unique(),  // 租户内用户名唯一
    }
}

4.3 默认值函数：动态填充

Ent 支持在字段上设置静态默认值或动态默认值函数。动态默认值在记录创建时由数据库或 Ent 生成器计算。

func (Order) Fields() []ent.Field {
    return []ent.Field{
        field.Time("created_at").
            Default(time.Now),  // Go 层默认值
        field.Time("updated_at").
            Default(time.Now).
            UpdateDefault(time.Now), // 更新时自动刷新
        field.String("status").
            Default("pending"),
        field.UUID("id", uuid.UUID{}).
            DefaultFunc(uuid.New),  // 应用层生成 UUID
    }
}

4.4 存储选项：引擎、字符集与表注释

Ent 通过 entsql 注解提供数据库级别的存储选项控制，包括存储引擎、字符集、表空间等。

4.4.1 常用存储选项

func (User) Annotations() []schema.Annotation {
    return []schema.Annotation{
        entsql.Annotation{
            Table:     "sys_users",       // 自定义表名
            Charset:   "utf8mb4",         // 字符集
            Collation: "utf8mb4_unicode_ci", // 排序规则
            Engine:    "InnoDB",          // 存储引擎
        },
    }
}

4.4.2 字段级存储选项

func (User) Fields() []ent.Field {
    return []ent.Field{
        field.String("description").
            SchemaType(map[string]string{
                dialect.MySQL:    "text",
                dialect.Postgres: "varchar(2000)",
            }), // 不同数据库使用不同类型
        field.String("avatar").
            Optional().
            Annotations(entsql.Annotation{
                Size: 512, // 字段大小限制
            }),
    }
}

4.5 注释与文档：Schema 即文档

Ent 支持在 Schema 级别和字段级别添加注释，这些注释会同步到数据库表/字段的 COMMENT 中，同时也可以生成 API 文档。

4.5.1 表级与字段级注释

func (User) Annotations() []schema.Annotation {
    return []schema.Annotation{
        entsql.Annotation{
            Table: "sys_users",
            WithComments: true,
        },
    }
}

func (User) Fields() []ent.Field {
    return []ent.Field{
        field.String("email").
            Comment("用户登录邮箱，全局唯一"),
        field.String("status").
            Comment("账户状态：active / inactive / banned"),
        field.Time("created_at").
            Comment("记录创建时间，由数据库自动填充"),
    }
}

func (User) Edges() []ent.Edge {
    return []ent.Edge{
        edge.To("posts", Post.Type).
            Comment("用户发布的文章列表"),
    }
}

4.5.2 生成文档注释

Ent 支持通过 --feature sql/annotation 生成带注释的 DDL，也可以结合 entc 模板生成 Markdown 文档。

# 生成带注释的迁移 SQL
go run -mod=mod entgo.io/ent/cmd/entc generate ./ent/schema \
    --feature sql/annotation

# 生成的 DDL 示例
CREATE TABLE `sys_users` (
    `id` bigint(20) NOT NULL AUTO_INCREMENT COMMENT '主键ID',
    `email` varchar(255) NOT NULL COMMENT '用户登录邮箱，全局唯一',
    `status` varchar(50) NOT NULL DEFAULT 'active' COMMENT '账户状态',
    `created_at` datetime NOT NULL COMMENT '记录创建时间',
    PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='系统用户表'

4.6 综合示例：用户订单 Schema

以下是一个综合运用上述特性的 Schema 示例：

// ent/schema/order.go
package schema

import (
    "time"
    "github.com/google/uuid"
    "entgo.io/ent"
    "entgo.io/ent/schema/field"
    "entgo.io/ent/schema/index"
    "entgo.io/ent/schema/edge"
    "entgo.io/ent/schema/annotation"
    "entgo.io/contrib/entgql"
    "github.com/99designs/gqlgen/graphql"
)

// Order 订单表
func (Order) Annotations() []schema.Annotation {
    return []schema.Annotation{
        entsql.Annotation{
            Table:     "t_orders",
            Engine:    "InnoDB",
            Charset:   "utf8mb4",
            Collation: "utf8mb4_unicode_ci",
            WithComments: true,
        },
        entgql.QueryField(),
    }
}

func (Order) Fields() []ent.Field {
    return []ent.Field{
        field.UUID("id", uuid.UUID{}).
            DefaultFunc(uuid.New).
            Comment("订单唯一标识"),
        field.String("order_no").
            Unique().
            MaxLen(32).
            Comment("业务订单号，全局唯一"),
        field.Enum("status").
            Values("pending", "paid", "shipped", "completed", "cancelled").
            Default("pending").
            Comment("订单状态"),
        field.Float("total_amount").
            Positive().
            Comment("订单总金额，单位：元"),
        field.Time("created_at").
            Default(time.Now).
            Comment("创建时间"),
        field.Time("updated_at").
            Default(time.Now).
            UpdateDefault(time.Now).
            Comment("最后更新时间"),
    }
}

func (Order) Indexes() []ent.Index {
    return []ent.Index{
        index.Fields("status", "created_at").
            Comment("按状态和时间查询的复合索引"),
        index.Fields("order_no").
            Unique(),
    }
}

func (Order) Edges() []ent.Edge {
    return []ent.Edge{
        edge.From("owner", User.Type).
            Ref("orders").
            Unique().
            Required().
            Comment("订单所属用户"),
        edge.To("items", OrderItem.Type).
            Comment("订单包含的商品项"),
    }
}

4.7 进阶特性关系图

下图展示了 Schema 进阶特性之间的依赖与协作关系：

4.8 工程落地检查清单