2. Ent ORM 基础：Ent是什么、核心概念（Schema、Edge、Field）、Ent CLI安装与项目初始化

2.1 什么是 Ent？

Ent 是 Facebook（现 Meta）开源的一款 Go 实体框架（Entity Framework）。它不同于传统的 ORM（如 GORM、XORM）基于反射和运行时映射，Ent 采用代码生成（Code Generation）的方式，在编译期将 Schema 定义转化为类型安全的 Go 代码。

2.2 核心概念：Schema、Field、Edge

Ent 的三大核心概念构成了整个框架的基石。理解它们之间的关系是掌握 Ent 的关键。

2.2.1 Schema（模式）

Schema 是 Ent 中最核心的抽象，对应数据库中的一张表（Table）或图中的一个节点（Node）。每个 Schema 定义了一个实体类型，包含其字段、边、索引和注解。

// user.go - User Schema 定义
package schema

import (
    "entgo.io/ent"
    "entgo.io/ent/schema/field"
    "entgo.io/ent/schema/edge"
)

// User 对应数据库中的 users 表
type User struct {
    ent.Schema
}

func (User) Fields() []ent.Field {
    return []ent.Field{
        field.String("name").Unique(),
        field.Int("age").Positive(),
        field.Time("created_at").Default(time.Now),
    }
}

func (User) Edges() []ent.Edge {
    return []ent.Edge{
        edge.To("posts", Post.Type),
    }
}

2.2.2 Field（字段）

Field 定义实体的属性，对应数据库表中的列。Ent 提供了丰富的字段类型和修饰器。

2.2.3 Edge（边）

Edge 定义实体之间的关系，对应数据库中的外键关联或中间表。Ent 支持四种关系类型：

• O2O（One-to-One）：一对一关系，如 User ↔ Profile
• O2M（One-to-Many）：一对多关系，如 User → Posts
• M2O（Many-to-One）：多对一关系，如 Posts → User
• M2M（Many-to-Many）：多对多关系，如 User ↔ Groups

// Edge 定义示例
func (User) Edges() []ent.Edge {
    return []ent.Edge{
        // O2M: 一个用户有多篇文章
        edge.To("posts", Post.Type),

        // O2O: 一个用户有一个档案
        edge.To("profile", Profile.Type).Unique(),

        // M2M: 一个用户属于多个群组
        edge.From("groups", Group.Type).Ref("users"),
    }
}

2.3 Ent CLI 安装

Ent CLI 是代码生成的核心工具，负责读取 Schema 定义并生成类型安全的 Go 代码。

2.3.1 安装方式

# 方式一：使用 go install（推荐）
go install entgo.io/ent/cmd/ent@latest

# 方式二：使用 Docker
docker run --rm -v $(pwd):/app -w /app entgo/ent generate ./schema

# 验证安装
ent --version
# 输出示例：ent v0.13.1

2.3.2 常用命令

2.4 项目初始化实战

下面我们通过一个完整的示例，演示从零开始初始化一个 Ent 项目。

2.4.1 创建项目目录

mkdir ent-demo && cd ent-demo
go mod init ent-demo

2.4.2 安装依赖

# 安装 Ent 核心库
go get entgo.io/ent@latest

# 安装数据库驱动（以 SQLite 为例）
go get github.com/mattn/go-sqlite3

2.4.3 初始化 Schema

# 创建 User 和 Post 两个 Schema
ent init User Post

# 查看生成的文件结构
tree
# 输出：
# .
# ├── go.mod
# ├── go.sum
# └── ent
#     └── schema
#         ├── post.go
#         └── user.go

2.4.4 编写 Schema 定义

// ent/schema/user.go
package schema

import (
    "entgo.io/ent"
    "entgo.io/ent/schema/field"
    "entgo.io/ent/schema/edge"
)

type User struct {
    ent.Schema
}

func (User) Fields() []ent.Field {
    return []ent.Field{
        field.String("name").Unique().NotEmpty(),
        field.Int("age").Positive(),
        field.String("email").Optional(),
    }
}

func (User) Edges() []ent.Edge {
    return []ent.Edge{
        edge.To("posts", Post.Type),
    }
}

// ent/schema/post.go
package schema

import (
    "entgo.io/ent"
    "entgo.io/ent/schema/field"
    "entgo.io/ent/schema/edge"
)

type Post struct {
    ent.Schema
}

func (Post) Fields() []ent.Field {
    return []ent.Field{
        field.String("title").NotEmpty(),
        field.String("content").NotEmpty(),
        field.Time("created_at"),
    }
}

func (Post) Edges() []ent.Edge {
    return []ent.Edge{
        edge.From("author", User.Type).Ref("posts").Unique(),
    }
}

2.4.5 生成代码

# 生成类型安全的 Go 代码
ent generate ./ent/schema

# 查看生成后的目录结构
tree -L 2
# 输出：
# .
# ├── ent
# │   ├── client.go
# │   ├── config.go
# │   ├── ent.go
# │   ├── enttest
# │   ├── migrate
# │   ├── post.go
# │   ├── post_create.go
# │   ├── post_delete.go
# │   ├── post_query.go
# │   ├── post_update.go
# │   ├── schema
# │   ├── tx.go
# │   ├── user.go
# │   ├── user_create.go
# │   ├── user_delete.go
# │   ├── user_query.go
# │   └── user_update.go
# ├── go.mod
# └── go.sum

2.4.6 编写测试代码

// main.go
package main

import (
    "context"
    "fmt"
    "log"

    "ent-demo/ent"
    _ "github.com/mattn/go-sqlite3"
)

func main() {
    // 创建 Ent 客户端
    client, err := ent.Open("sqlite3", "file:ent.db?cache=shared&_fk=1")
    if err != nil {
        log.Fatalf("failed opening connection to sqlite: %v", err)
    }
    defer client.Close()

    // 自动迁移
    ctx := context.Background()
    if err := client.Schema.Create(ctx); err != nil {
        log.Fatalf("failed creating schema resources: %v", err)
    }

    // 创建用户
    user, err := client.User.Create().
        SetName("张三").
        SetAge(28).
        Save(ctx)
    if err != nil {
        log.Fatalf("failed creating user: %v", err)
    }
    fmt.Printf("创建用户成功: %v\n", user)

    // 创建文章并关联用户
    post, err := client.Post.Create().
        SetTitle("Ent ORM 入门").
        SetContent("本文介绍 Ent 的基本用法...").
        SetAuthor(user).
        Save(ctx)
    if err != nil {
        log.Fatalf("failed creating post: %v", err)
    }
    fmt.Printf("创建文章成功: %v\n", post)

    // 查询用户及其文章
    userWithPosts, err := client.User.Query().
        Where(user.NameEQ("张三")).
        WithPosts().
        Only(ctx)
    if err != nil {
        log.Fatalf("failed querying user: %v", err)
    }
    fmt.Printf("用户: %s, 文章数: %d\n", userWithPosts.Name, len(userWithPosts.Edges.Posts))
}

go run main.go
# 预期输出：
# 创建用户成功: User(id=1, name=张三, age=28, email=)
# 创建文章成功: Post(id=1, title=Ent ORM 入门, content=本文介绍 Ent 的基本用法..., created_at=2024-01-15 10:30:00)
# 用户: 张三, 文章数: 1

2.5 本章小结

• Ent 是什么：基于代码生成的 Go 实体框架，采用图模型，编译期保证类型安全。
• 核心概念：Schema（实体定义）、Field（属性）、Edge（关系）、Index（索引）、Annotation（注解）、Mixin（混入）。
• CLI 安装：通过 go install 安装，使用 ent init 初始化 Schema，ent generate 生成代码。
• 项目初始化：创建模块 → 安装依赖 → 定义 Schema → 生成代码 → 编写业务逻辑。