2. 环境搭建与项目初始化：Go 环境配置、安装 Ent CLI、创建第一个 Ent 项目、项目目录结构解析

本章是《Ent 工程落地实战课程》的基石。我们将从零开始，完成 Go 开发环境的配置、Ent CLI 的安装，并创建第一个 Ent 项目。通过解析标准项目目录结构，帮助你建立对 Ent 工程化布局的直观认知。所有操作均基于 Go 1.21+ 和 Ent v0.14+ 版本。

2.1 Go 环境配置与验证

Ent 是纯 Go 实现的 ORM 框架，因此一个稳定、版本正确的 Go 环境是首要前提。请确保你的开发机已安装 Go，并正确配置了环境变量。

2.1.1 安装与版本检查

访问 go.dev/dl 下载对应操作系统的安装包。安装完成后，打开终端执行以下命令验证：

go version
# 期望输出: go version go1.21.5 darwin/arm64 (版本号可能不同，但需 ≥ 1.21)

go env GOPATH
# 期望输出: /Users/yourname/go (或你的自定义路径)

go env GOROOT
# 期望输出: /usr/local/go (或你的安装路径)

# 在 ~/.bashrc 或 ~/.zshrc 中添加
export PATH=$PATH:$(go env GOPATH)/bin

2.1.2 Go Module 代理配置（可选但推荐）

为了加速依赖下载，建议配置 Go 模块代理：

go env -w GOPROXY=https://goproxy.cn,direct
go env -w GO111MODULE=on

2.2 安装 Ent CLI

Ent CLI（entc）是代码生成的核心工具。它负责读取 Schema 定义，并自动生成对应的 CRUD 代码、查询构造器以及数据库迁移文件。

2.2.1 使用 go install 安装

这是官方推荐的方式，确保 CLI 版本与项目依赖的 Ent 库版本一致：

go install entgo.io/ent/cmd/entc@latest

安装完成后，验证是否成功：

entc --version
# 期望输出: entc (version: v0.14.1) (或类似版本号)

2.2.2 版本对齐的重要性

2.3 创建第一个 Ent 项目

我们将创建一个名为 entdemo 的项目，使用 SQLite 作为初始数据库，以降低环境依赖。

2.3.1 初始化 Go Module 并添加依赖

mkdir entdemo
cd entdemo
go mod init entdemo

# 添加 Ent 核心库和 SQLite 驱动
go get entgo.io/ent@latest
go get github.com/mattn/go-sqlite3@latest

2.3.2 使用 Ent CLI 初始化 Schema 骨架

在项目根目录下执行：

entc init User

该命令会创建 ent/schema/user.go 文件，并生成基础的 ent/ 目录结构。此时，User Schema 只有一个默认的 ID 字段。

2.3.3 定义第一个 Schema 字段

编辑 ent/schema/user.go，添加 Name 和 Age 字段：

package schema

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

// User holds the schema definition for the User entity.
type User struct {
    ent.Schema
}

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

// Edges of the User.
func (User) Edges() []ent.Edge {
    return nil
}

2.3.4 生成代码

在项目根目录运行：

go generate ./ent

Ent CLI 会读取 ent/schema/ 下的所有文件，并在 ent/ 目录下生成对应的 client.go、user.go、user_create.go、user_query.go 等文件。

2.4 项目目录结构解析

一个典型的 Ent 项目目录结构如下。理解每个目录和文件的职责，是后续工程化实践的基础。

entdemo/
├── ent/                    # Ent 生成的代码目录（核心）
│   ├── client.go          # Ent 客户端，用于操作数据库
│   ├── schema/            # Schema 定义目录（开发者维护）
│   │   └── user.go        # User 实体的 Schema 定义
│   ├── migrate/           # 数据库迁移代码
│   │   └── main.go        # 迁移主程序入口
│   ├── user.go            # User 实体结构体定义
│   ├── user_create.go     # 创建 User 的查询构造器
│   ├── user_query.go      # 查询 User 的查询构造器
│   ├── user_update.go     # 更新 User 的查询构造器
│   ├── user_delete.go     # 删除 User 的查询构造器
│   └── enttest/           # 测试辅助代码
│       └── enttest.go
├── go.mod                 # Go Module 定义
├── go.sum                 # 依赖校验文件
└── main.go                # 应用入口（开发者编写）

2.5 验证项目：编写第一个主程序

在 main.go 中编写代码，连接 SQLite 数据库并创建一个 User 记录，验证整个链路是否通畅。

package main

import (
    "context"
    "fmt"
    "log"

    "entdemo/ent"
    "entdemo/ent/user"

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

func main() {
    // 连接 SQLite 数据库（文件模式）
    client, err := ent.Open("sqlite3", "file:entdemo.db?cache=shared&_fk=1")
    if err != nil {
        log.Fatalf("failed opening connection to sqlite: %v", err)
    }
    defer client.Close()

    // 自动迁移：根据 Schema 创建或更新表结构
    ctx := context.Background()
    if err := client.Schema.Create(ctx); err != nil {
        log.Fatalf("failed creating schema resources: %v", err)
    }

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

    // 查询刚才创建的用户
    u2, err := client.User.
        Query().
        Where(user.Name("张三")).
        Only(ctx)
    if err != nil {
        log.Fatalf("failed querying user: %v", err)
    }
    fmt.Printf("查询用户成功: ID=%d, Name=%s, Age=%d\n", u2.ID, u2.Name, u2.Age)
}

运行程序：

go run main.go

如果控制台输出类似以下内容，则说明环境搭建和项目初始化全部成功：

创建用户成功: User(id=1, name=张三, age=28)
查询用户成功: ID=1, Name=张三, Age=28

2.6 环境搭建与代码生成流程总览

下图展示了从 Schema 定义到生成可运行代码的完整流程，以及开发者在其中的角色。

2.7 常见问题与排查