使用 entviz 可视化 Ent 数据模型：一条命令生成可分享的 ERD 与 SQL Schema-平芜编程栈

后端
ORM
代码生成

【免费下载链接】ent

An entity framework for Go

项目地址：https://gitcode.com/gh_mirrors/en/ent

entviz 是一个与 Ent 配套的轻量可视化工具：你只需在项目里运行一条 Go 命令，传入 Ent schema 所在目录，它就会分析你的数据模型，在 Atlas Playground 上生成一份可视化结果，并返回一个可分享的公开链接。本文将以 Ent 官方博客文档为核心，结合仓库内的真实 schema 与代码生成源码，讲解如何快速获得 Ent 应用底层数据库结构的 ERD 视图、SQL 文本与 Atlas HCL 表示。

为什么 Ent 应用需要「可视化」这一层

Ent 的核心思想是使用**图语义（graph semantics）**来构建应用数据模型：开发者不再直接定义表、列、关联表和外键，而是以节点（Node）与边（Edge）的方式描述实体及其关系。一个典型 schema 如下（取自本仓库 examples/start/ent/schema/user.go 的真实写法）：

package schema import ( "entgo.io/ent" "entgo.io/ent/schema/edge" "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.Int("age"). Positive(), field.String("name"). Default("unknown"), } } // Edges of the User. func (User) Edges() []ent.Edge { return []ent.Edge{ edge.To("cars", Car.Type), edge.From("groups", Group.Type). Ref("users"), } }

这种建模方式带来诸多好处：你可以通过直观的 API 轻松遍历（traverse）应用的数据图，也能自动生成 GraphQL 服务等。但随之而来的一个常见问题是：

虽然 Ent 可以把图数据库作为存储层，但绝大多数用户使用 MySQL、PostgreSQL、MariaDB 这类常见关系型数据库。在这些场景下，Ent 到底会为我的应用 schema 创建出什么样的实际数据库 schema？

无论你是刚接触 Ent、正在学习如何编写 schema 的新手，还是需要针对性能优化最终数据库 schema 的专家，能够直观地看到 Ent schema 背后对应的物理表结构，都是非常有价值的。这正是 entviz 解决的问题。

从旧版扩展到新版命令行工具

早在 2021 年 8 月，Ent 社区就分享过一款名为 entviz 的 Ent 扩展（参见仓库中的旧版博客 doc/website/blog/2021-08-26-visualizing-your-data-graph-using-entviz.md）。旧版 entviz 是一个entc扩展：把它加入entc.go的entc.Extensions(entviz.Extension{})后，每次执行go generate ./...，它都会在 ent 目录下生成一个名为schema-viz.html的静态 HTML 文件，内含实体关系图。由于它直接集成在 Ent schema 之上，无需连接数据库做 introspection，因此每次修改 schema 后重新生成即可获得最新图表。

2023 年，社区推出了一款同名的新工具（由 Pedro Henrique 开发），它是对同一问题的全新实现：不再依赖entc扩展机制，而是作为一个独立的 Go 程序，分析 Ent schema 后在Atlas Playground上创建可视化，并返回一个可分享的公开链接。

快速上手：一条命令获得可视化链接

新版 entviz 的用法极其简单，核心就是一条命令（来自原博客的 TL;DR）：

go run -mod=mod ariga.io/entviz ./path/to/ent/schema

其中：

./path/to/ent/schema是你要分析的 Ent schema 目录，即存放*_schema.go定义（如user.go、car.go）的位置；
-mod=mod表示允许 Go 工具链按需自动下载、更新模块依赖（在较新的 Go 版本中亦可用go run ariga.io/entviz@latest ./path/to/ent/schema的形式直接指定版本）。

运行后，工具会分析你的 Ent schema，在 Atlas Playground 上生成可视化，并输出类似如下的结果：

Here is a public link to your schema visualization: https://gh.atlasgo.cloud/explore/saved/60129542154

打开这个链接，你可以：

以ERD（实体关系图）的图形化方式查看 schema；
以SQL文本方式查看生成的建表语句；
以Atlas HCL文档方式查看 schema 的声明式表示。

换句话说，一次分析得到三种视图：适合人眼快速理解的图形，以及适合评审、存档和进一步迁移的文本形态。

用仓库中的真实 schema 做一次演练

为了让你对输出结果有直观预期，我们以本仓库 examples/start/ent/schema 目录下的三个实体为例（它们构成了一个经典的 O2M + M2M 图）：

实体	关键字段	边
`User`	`age`（`field.Int(...).Positive()`）、`name`（`field.String(...).Default("unknown")`）	`edge.To("cars", Car.Type)`；`edge.From("groups", Group.Type).Ref("users")`
`Car`	`model`、`registered_at`（`field.Time(...)`）	`edge.From("owner", User.Type).Ref("cars").Unique()`
`Group`	`name`（带`Match(regexp.MustCompile("[a-zA-Z_]+$"))`校验）	`edge.To("users", User.Type)`

详细定义可参考 examples/start/ent/schema/user.go、examples/start/ent/schema/car.go 与 examples/start/ent/schema/group.go。

对该目录运行：

go run -mod=mod ariga.io/entviz ./examples/start/ent/schema

entviz 会识别出User、Car、Group三个节点，以及User→Car（一对多）、User↔Group（多对多，通过Ref关联的正反两条边）等关系，最终在你拿到的公开链接中呈现对应的 ERD 与 SQL。你可以据此核对：User的age字段的Positive()约束在数据库层如何体现、Car.owner的外键列如何生成、Group↔User的关联表结构是什么样等细节。

背后的原理：Ent 的 schema 与代码生成体系

Ent 如何描述「节点与边」

从源码结构看，Ent 的数据模型定义体系分布在 schema 目录下：schema/edge/edge.go提供edge.To、edge.From等边构造器，schema/field/field.go提供field.String、field.Int、field.Time等字段构造器，schema/schema.go 定义ent.Schema接口（Fields()、Edges()、Indexes()、Mixin()等方法）。entviz 正是通过解析这些 schema 定义（而非连接数据库）来获得数据模型，因此它天然保持与源码同步，且无需任何数据库凭据。

entc 扩展机制（旧版 entviz 的立足点）

虽然新版 entviz 已改为独立命令行工具，但了解旧版的实现方式有助于理解 Ent 的扩展生态。Ent 的代码生成器entc提供了扩展接口entc.Extension（见 entc/entc.go#L210-L232），它由四部分组成：

type Extension interface { // Hooks holds an optional list of Hooks to apply // on the graph before/after the code-generation. Hooks() []gen.Hook // Annotations injects global annotations to the gen.Config object ... Annotations() []Annotation // Templates specifies a list of alternative templates // to execute or to override the default. Templates() []*gen.Template // Options specifies a list of entc.Options to evaluate on // the gen.Config before executing the code generation. Options() []Option }

entc.Extensions(...)会把每个扩展的 Hooks、Templates、Options、Annotations 合并进代码生成配置（entc/entc.go#L235-L251）。为了让第三方包不必实现全部方法，还提供了entc.DefaultExtension空实现（entc/entc.go#L261-L275），扩展只需嵌入它并覆写自己关心的部分。

旧版 entviz 就是利用Templates()注入一个名为entviz的模板，生成额外的entviz.go文件，其中通过//go:embed schema-viz.html内嵌可视化 HTML，并暴露ServeEntviz()方法作为 HTTP handler：

func main() { http.ListenAndServe("localhost:3002", ent.ServeEntviz()) }

这种「以模板生成附加文件、以扩展钩子挂载到生成流程」的模式，是 Ent 生态中 GraphQL 扩展、OpenAPI 扩展等众多第三方能力的通用范式。

新版 entviz 的定位差异

新版 entviz 不再介入entc的生成流程，而是独立读取并分析 Ent schema，将结果上传到 Atlas Playground 生成可分享链接。它的优势在于：

零配置：不需要修改entc.go，不需要额外的生成步骤；
即用即走：go run一次即可，适合临时查看、评审、分享；
多种视图：同一链接内可切换 ERD / SQL / Atlas HCL 三种展示形态；
公开链接：方便发到聊天工具或文档中与团队协作讨论 schema 变更。

适用场景与注意事项

结合原博客与仓库实际内容，entviz 主要适用于以下场景：

新成员快速理解项目数据模型：加入已有的大型代码库时，ER 图是理解数据模型最高效的入口之一；
核对 Ent 到关系数据库的映射：确认edge最终生成的外键、关联表、唯一约束是否符合预期；
评审与协作：把公开链接随 PR 或设计文档一同分享，让 schema 变更一目了然。

使用上需注意：

命令中-mod=mod（或@latest版本后缀）会触发依赖下载，请确保网络与 Go 模块代理配置正常；
生成的链接托管在 Atlas Playground（gh.atlasgo.cloud域名）上，属于外部服务，敏感数据模型请评估是否适合上传；
可视化反映的是Ent schema 声明的模型，与最终由迁移引擎实际执行的建表结果可能存在细微差异（如默认值、索引命名等），如需精确核对，可结合 migration 文档或仓库中的迁移示例（如 examples/migration/ent）交叉验证。

总结

从手工连库 introspection 生成 ER 图，到旧版 entviz 在go generate时输出本地 HTML，再到新版 entviz 一条命令生成可分享的在线可视化，Ent 生态在「数据模型可视化」这件事上的演进脉络非常清晰。对于任何使用 MySQL、PostgreSQL 等关系型数据库的 Ent 应用，go run -mod=mod ariga.io/entviz ./path/to/ent/schema都是一条值得收藏的命令——它能在几秒内让你看清整个数据模型的物理落地形态，无论用于学习、评审还是性能调优都极为实用。