后端ORM代码生成【免费下载链接】entAn entity framework for Go项目地址https://gitcode.com/gh_mirrors/en/ent点击查看免费下载本篇技术指南以 EntAn entity framework for Go官方文档doc/md/features.md为主体围绕其核心主题——代码生成 Feature Flags特性开关机制展开。你将掌握如何通过 CLI 或gen包按需启用/停用框架内置的高级生成能力包括隐私层、EntQL 动态过滤、命名边、行级锁、自定义 SQL 修饰器、原生 SQL 执行、Upsert 与全局唯一 ID 等并理解每个特性的底层实现原理与适用场景从而在真实项目中精准组合这些能力。什么是 Feature FlagsEnt 框架提供了一系列可通过开关flag启用或移除的代码生成特性code-generation features。这些特性不是默认全部生成的而是像插件一样只有当你显式声明需要时代码生成器entc才会把对应的 API 与模板输出到目标包中。这种设计保证了基础生成的轻量、可控也让高级能力如隐私层、锁、Upsert按需加载互不干扰。从源码层面看每个特性都是一个gen.Feature结构体实例定义在 entc/gen/feature.go。该结构体包含以下字段字段含义Name特性唯一名称即 CLI 中--feature接受的值如privacy、sql/upsertStage特性成熟度阶段见下方说明Default是否默认启用当前所有公开特性默认均为falseDescription特性描述Templates/GraphTemplates特性附带的模板用于扩展或覆盖默认代码生成输出cleanup关闭特性时清理旧生成文件如privacy/目录、entql.go的回调AllFeatures变量集中列出了全部 13 个公开特性而featureMultiSchemasql/multischema是仅供内部使用的私有特性。特性的Stage分为四档定义于同一文件中Experimental仍在开发、处于集成环境测试中的特性如entql、namedges、bidiedges、sql/lock、sql/modifier、sql/execquery、sql/upsert、sql/globalid、schema/snapshotAlpha初步开发完成、已在团队基础设施上测试但 API 可能发生破坏性变更如privacy、interceptBeta已加入官方文档、预期无破坏性变更如sql/multischemaStable稳定运行、可放心生产使用目前仅sql/schemaconfig。如何启用 Feature Flags特性开关可以通过两种方式提供CLI 命令行参数或gen包的配置参数。方式一CLI 参数在生成代码时通过--feature标志传入一个或多个特性名称逗号分隔go run -modmod entgo.io/ent/cmd/ent generate --feature privacy,entql ./ent/schema上述命令为./ent/schema下的 schema 生成代码同时启用privacy隐私层与entql动态过滤两个特性。--feature标志最终会被解析并映射到 entc/gen/feature.go 中对应的gen.Feature常量。方式二Go 程序gen包如果你使用entc.Generate以编程方式驱动代码生成通常放在一个// build ignore的生成脚本中则在gen.Config.Features字段中列出所需的特性// build ignore package main import ( log text/template entgo.io/ent/entc entgo.io/ent/entc/gen ) func main() { err : entc.Generate(./schema, gen.Config{ Features: []gen.Feature{ gen.FeaturePrivacy, gen.FeatureEntQL, }, Templates: []*gen.Template{ gen.MustParse(gen.NewTemplate(static). Funcs(template.FuncMap{title: strings.ToTitle}). ParseFiles(template/static.tmpl)), }, }) if err ! nil { log.Fatalf(running ent codegen: %v, err) } }此外entc/entc.go 还提供了entc.FeatureNames(names ...string)这一函数式选项可直接按特性名称启用err : entc.Generate(./schema, gen.Config{}, entc.FeatureNames(privacy, entql))FeatureNames内部遍历gen.AllFeatures将名称匹配的特性追加到cfg.Features中。模板引擎如何感知特性开关特性开关不仅决定生成哪些文件还会影响共享模板的内容。gen.Config暴露了FeatureEnabled(name string) (bool, error)方法见 entc/gen/graph.go它被设计为模板函数可在自定义模板中做条件渲染{{- with $.FeatureEnabled privacy }} {{/* 仅在启用 privacy 时输出的内容 */}} {{- end }}框架自带的模板大量使用了这一机制例如 entc/gen/template/dialect/sql/feature/modifier.tmpl 中会同时判断sql/lock与sql/modifier是否启用来决定生成哪些 SQL 构建器方法entc/gen/template/dialect/sql/feature/schemaconfig.tmpl 则根据sql/schemaconfig与sql/multischema的状态生成不同的连接配置代码。特性清单13 项能力的逐一解析Auto-Solve Merge Conflicts自动解决合并冲突schema/snapshot选项会指示entc在内部包中保存一份最新 schema 的快照并在用户的 schema 无法构建例如多人并行开发导致合并冲突时自动使用该快照解决冲突让代码生成流程不至于中断。启用方式--feature schema/snapshot从实现上看见 entc/entc.go 的mayRecover逻辑当代码生成遇到packages.Error或构建错误且schema/snapshot特性开启时框架会先检查 schema 目录本身然后通过internal.Snapshot.Restore()从internal/schema.go快照恢复。该特性的GraphTemplates定义了internal/schema.go的输出模板见 entc/gen/feature.go 中FeatureSnapshot定义。Privacy Layer隐私层隐私层允许你为数据库中实体的查询与变更操作配置隐私策略是构建多租户、数据隔离应用的关键能力。启用方式--feature privacy启用后生成的代码会包含privacy包你可以为每个实体定义EvalQuery/EvalMutation规则。完整的策略写法与规则组合请参阅 隐私层文档。该特性的cleanup回调会删除privacy目录因此关闭特性后重新生成即可干净地移除相关代码。EntQL FilteringEntQL 动态过滤entql选项为不同的查询构建器提供运行时通用、动态的过滤能力你可以在运行时构造任意复杂度的过滤表达式而不必为每种过滤条件都写死代码。启用方式--feature entql这一能力在多租户multi-tenancy场景下尤其常用配合隐私层可以动态拼装租户级过滤条件具体用法可参阅 隐私层文档中的多租户章节。启用后生成的entql.go提供了Filter接口可将动态构造的谓词直接应用到查询上如user.Query().Where(entql.Filter(...))。值得注意的是该特性在 entc/gen/feature.go 中被标记为Experimental且cleanup会直接删除entql.go文件。Named Edges命名边namedges选项为使用自定义名称预加载边eager-load提供 API。默认情况下边预加载使用的是边在 schema 中定义的名称启用该特性后你可以在预加载时为边指定别名例如user.Query().WithNamedPets(admin...)。启用方式--feature namedges配合 Eager Loading 文档 中的预加载模式命名边让你能够在一次查询中按不同条件多次预加载同一条边例如同时加载宠物与管理员宠物。其模板实现在 entc/gen/template/dialect/sql/feature/namedges.tmpl 中。Bidirectional Edge Refs双向边引用bidiedges选项指导 Ent 在预加载 O2M/O2O一对多/一对一边时设置双向引用即子实体加载后其引用父实体的指针也会被反向填充方便在内存中双向遍历对象图。启用方式--feature bidiedges从模板实现看见 entc/gen/template/dialect/sql/feature/namedges.tmplbidiedges生效的条件是边存在反向引用$e.Ref且该引用是唯一的$e.Ref.Unique。注意使用标准库encoding/json.MarshalJSON的用户应在调用json.Marshal前断开循环引用否则双向引用会导致 JSON 序列化无限递归。Schema Config多库 Schema 配置sql/schemaconfig选项允许你为模型传入备选的 SQL 数据库名。当你的模型不都存放在同一个数据库、而是分散在不同 schema 下时这一特性非常有用。启用方式--feature sql/schemaconfig启用后ent.Open会获得一个新的AlternateSchema选项将每个实体映射到指定 schemac, err : ent.Open(dialect, conn, ent.AlternateSchema(ent.SchemaConfig{ User: usersdb, Car: carsdb, })) c.User.Query().All(ctx) // SELECT * FROM usersdb.users c.Car.Query().All(ctx) // SELECT * FROM carsdb.cars该特性是当前唯一标记为Stable的公开特性见 entc/gen/feature.go 中FeatureSchemaConfig。其GraphTemplates负责生成internal/schemaconfig.go文件而生成的客户端代码会通过internal/schemaconfig包将表名重写为指定 schema 下的完整限定名。模板中还与内部的sql/multischema特性联动见 schemaconfig.tmpl。Row-level Locks行级锁sql/lock选项允许使用 SQL 的SELECT ... FOR {UPDATE | SHARE}语法配置行级锁定用于在事务中防止并发更新同一行数据。启用方式--feature sql/lock启用后查询构建器会获得ForUpdate与ForShare方法tx, err : client.Tx(ctx) if err ! nil { log.Fatal(err) } tx.Pet.Query(). Where(pet.Name(name)). ForUpdate(). Only(ctx) tx.Pet.Query(). Where(pet.ID(id)). ForShare( sql.WithLockTables(pet.Table), sql.WithLockAction(sql.NoWait), ). Only(ctx)ForUpdate用于悲观更新锁ForShare配合sql.WithLockTables锁定指定表与sql.WithLockAction如sql.NoWait不等待锁释放直接报错可实现更细粒度的并发控制。该特性的模板实现在 lock.tmpl 中并且与sql/modifier共享构建器的部分生成逻辑。Custom SQL Modifiers自定义 SQL 修饰器sql/modifier选项允许为构建器附加自定义 SQL 修饰函数在语句执行前对其进行改写。启用方式--feature sql/modifier启用后查询与更新构建器都会获得Modify方法。下面通过官方文档中的 7 个示例完整演示其能力。示例 1替换 Select 列client.Pet. Query(). Modify(func(s *sql.Selector) { s.Select(SUM(LENGTH(name))) }). IntX(ctx)生成 SQLSELECT SUM(LENGTH(name)) FROM pet选择并扫描动态值AppendSelect / AppendSelectAs / Value如果使用 SQL 修饰器需要扫描 schema 定义之外的动态值如聚合或自定义排序字段可以对sql.Selector应用AppendSelect/AppendSelectAs之后通过每个实体上定义的Value方法读取这些值const as name_length // Query the entity with the dynamic value. p : client.Pet.Query(). Modify(func(s *sql.Selector) { s.AppendSelectAs(LENGTH(name), as) }). FirstX(ctx) // Read the value from the entity. n, err : p.Value(as) if err ! nil { log.Fatal(err) } fmt.Println(Name length: %d %d, n, len(p.Name))示例 2追加聚合列并扫描到结构体var p1 []struct { ent.Pet NameLength int sql:length } client.Pet.Query(). Order(ent.Asc(pet.FieldID)). Modify(func(s *sql.Selector) { s.AppendSelect(LENGTH(name)) }). ScanX(ctx, p1)生成 SQLSELECT pet.*, LENGTH(name) FROM pet ORDER BY pet.id ASC注意结构体字段上的sql:length标签它指定了扫描结果列与结构体字段的映射关系而内嵌ent.Pet让结果同时拥有实体的全部字段。示例 3分组聚合统计var v []struct { Count int json:count Price int json:price CreatedAt time.Time json:created_at } client.User. Query(). Where( user.CreatedAtGT(x), user.CreatedAtLT(y), ). Modify(func(s *sql.Selector) { s.Select( sql.As(sql.Count(*), count), sql.As(sql.Sum(price), price), sql.As(DATE(created_at), created_at), ). GroupBy(DATE(created_at)). OrderBy(sql.Desc(DATE(created_at))) }). ScanX(ctx, v)生成 SQLSELECT COUNT(*) AS count, SUM(price) AS price, DATE(created_at) AS created_at FROM users WHERE created_at x AND created_at y GROUP BY DATE(created_at) ORDER BY DATE(created_at) DESC这里展示了如何利用sql.As、sql.Count、sql.Sum等辅助函数构建聚合查询并直接扫描到自定义结构体中。示例 4LEFT JOIN 关联聚合var gs []struct { ent.Group UsersCount int sql:users_count } client.Group.Query(). Order(ent.Asc(group.FieldID)). Modify(func(s *sql.Selector) { t : sql.Table(group.UsersTable) s.LeftJoin(t). On( s.C(group.FieldID), t.C(group.UsersPrimaryKey[1]), ). // Append the users_count column to the selected columns. AppendSelect( sql.As(sql.Count(t.C(group.UsersPrimaryKey[1])), users_count), ). GroupBy(s.C(group.FieldID)) }). ScanX(ctx, gs)生成 SQLSELECT groups.*, COUNT(t1.group_id) AS users_count FROM groups LEFT JOIN user_groups AS t1 ON groups.id t1.group_id GROUP BY groups.id ORDER BY groups.id ASC示例 5更新语句中使用 SQL 表达式Modify同样适用于更新构建器*sql.UpdateBuilderclient.User.Update(). Modify(func(s *sql.UpdateBuilder) { s.Set(user.FieldName, sql.Expr(fmt.Sprintf(UPPER(%s), user.FieldName))) }). ExecX(ctx)生成 SQLUPDATE users SET name UPPER(name)示例 6自增 ID 表达式client.User.Update(). Modify(func(u *sql.UpdateBuilder) { u.Set(user.FieldID, sql.ExprFunc(func(b *sql.Builder) { b.Ident(user.FieldID).WriteOp(sql.OpAdd).Arg(1) })) u.OrderBy(sql.Desc(user.FieldID)) }). ExecX(ctx)生成 SQLUPDATE users SET id id 1 ORDER BY id DESC示例 7JSON 列追加元素结合sqljson包可以在更新时向 JSON 列的数组追加元素client.User.Update(). Modify(func(u *sql.UpdateBuilder) { sqljson.Append(u, user.FieldTags, []string{tag1, tag2}, sqljson.Path(values)) }). ExecX(ctx)生成 SQLUPDATE users SET tags CASE WHEN (JSON_TYPE(JSON_EXTRACT(tags, $.values)) IS NULL OR JSON_TYPE(JSON_EXTRACT(tags, $.values)) NULL) THEN JSON_SET(tags, $.values, JSON_ARRAY(?, ?)) ELSE JSON_ARRAY_APPEND(tags, $.values, ?, $.values, ?) END WHERE id ?该语句利用CASE分支处理了字段不存在与字段已存在两种追加场景相关辅助函数定义在 dialect/sql/sqljson/sqljson.go 中。SQL Raw API原生 SQL 执行sql/execquery选项允许使用底层驱动的ExecContext/QueryContext方法直接执行语句。启用方式--feature sql/execquery启用后ent.Client与ent.Tx都会暴露ExecContext方法方便在事务中执行原生 SQL// From ent.Client. if _, err : client.ExecContext(ctx, TRUNCATE t1); err ! nil { return err } // From ent.Tx. tx, err : client.Tx(ctx) if err ! nil { return err } if err : tx.User.Create().Exec(ctx); err ! nil { return err } if _, err : tx.ExecContext(SAVEPOINT user_created); err ! nil { return err } // ...警告通过ExecContext/QueryContext执行的语句不经过 Ent可能会绕过应用中的基础层例如 hooks、隐私权限校验与验证器。请务必仅在明确知晓风险的情况下使用。Upsert冲突处理sql/upsert选项允许使用 SQL 的ON CONFLICT/ON DUPLICATE KEY语法配置插入或更新upsert与批量 upsert逻辑。启用方式--feature sql/upsert启用后创建构建器会获得OnConflict、OnConflictColumns、UpdateNewValues等方法// Use the new values that were set on create. id, err : client.User. Create(). SetAge(30). SetName(Ariel). OnConflict(). UpdateNewValues(). ID(ctx) // In PostgreSQL, the conflict target is required. err : client.User. Create(). SetAge(30). SetName(Ariel). OnConflictColumns(user.FieldName). UpdateNewValues(). Exec(ctx) // Bulk upsert is also supported. client.User. CreateBulk(builders...). OnConflict( sql.ConflictWhere(...), sql.UpdateWhere(...), ). UpdateNewValues(). Exec(ctx) // INSERT INTO users (...) VALUES ... ON CONFLICT WHERE ... DO UPDATE SET ... WHERE ...OnConflictColumns用于指定冲突判定列PostgreSQL 中必填UpdateNewValues表示用本次 create 时设置的新值覆盖旧记录。完整的 Upsert API含Ignore、DoNothing、UpdateIgnore等请参阅 CRUD 文档中的 Upsert 章节。Globally Unique ID全局唯一 ID默认情况下SQL 主键每张表都从 1 开始自增这意味着不同类型的多个实体可能共享相同的 ID。这与 AWS Neptune节点 ID 为 UUID不同。如果你的应用对接 GraphQL要求对象 ID 全局唯一这种默认行为会产生冲突。启用全局唯一 ID 支持--feature sql/globalid工作原理Ent 迁移会为每个实体表分配一个132即 4294967296范围的 ID 空间并将该信息与生成的代码一同存储internal/globalid.go。例如类型A的 ID 范围为[1, 4294967296)类型B的范围为[4294967296, 8589934592)依此类推。若启用该选项可能的表总数上限为 65535因为2^32 × 65535 2^48同时受数据库自增起始值类型限制从源码结构看该上限源于 ID 段划分方案。从源码实现看entc/gen/globalid.go 中的IncrementStartAnnotation函数负责为图中每个节点分配递增起始值已有节点保持既有范围新节点取当前最高范围值 32再 1 后左移 32 位作为新的起始值并写入internal/globalid.go。该函数还会校验所有范围都是132的整数倍且互不重叠否则报错。配合schema/snapshot特性时ResolveIncrementStartsConflict会通过接受远端版本的方式自动解决internal/globalid.go的合并冲突。警告如果你过去使用的是migrate.WithGlobalUniqueID(true)迁移选项请在切换到新的sql/globalid特性前阅读 globalid.mdx 中的迁移指南。特性开关的底层机制与生命周期模板条件生成特性开关的核心价值在于按需生成。FeatureEnabled方法entc/gen/graph.go遍历allFeatures查找特性名然后在Config.Features列表中判断该特性是否被显式启用。这个判断贯穿整个模板渲染过程查询构建器的模板会根据sql/modifier是否启用决定是否生成Modify方法见 builder/query.tmplSQL 特性模板lock.tmpl、modifier.tmpl、upsert.tmpl、execquery.tmpl、namedges.tmpl、schemaconfig.tmpl各自用FeatureEnabled控制对应 API 的生成schema/snapshot与sql/globalid则通过GraphTemplates生成internal/schema.go与internal/globalid.go等独立文件。关闭特性时的清理每个特性还可以定义cleanup回调当你从项目中移除某个特性开关并重新生成时框架会自动删除该特性此前生成的产物。例如privacy→ 删除privacy/目录entql→ 删除entql.gosql/schemaconfig→ 删除internal/schemaconfig.gosql/globalid→ 删除internal/globalid.goschema/snapshot→ 删除internal/schema.go若目录为空则一并删除。这一机制见 entc/gen/feature.go 的remove辅助函数保证了特性启停之间的代码干净切换不会残留陈旧生成物。启用方式对照特性名称CLI 标志成熟度核心作用schema/snapshot--feature schema/snapshotExperimentalschema 快照、自动解决合并冲突privacy--feature privacyAlpha查询/变更的隐私策略层entql--feature entqlExperimental运行时通用动态过滤namedges--feature namedgesExperimental自定义名称预加载边bidiedges--feature bidiedgesExperimentalO2M/O2O 边双向引用sql/schemaconfig--feature sql/schemaconfigStable为模型指定备选 schemasql/lock--feature sql/lockExperimental行级锁FOR UPDATE/SHAREsql/modifier--feature sql/modifierExperimental自定义 SQL 修饰器sql/execquery--feature sql/execqueryExperimental原生 ExecContext/QueryContextsql/upsert--feature sql/upsertExperimentalON CONFLICT / ON DUPLICATE KEYsql/globalid--feature sql/globalidExperimental全局唯一 ID132 段分配结语Feature Flags 是 Ent 框架按需取用、渐进增强设计哲学的集中体现基础 CRUD 代码保持轻量而隐私、过滤、锁、聚合、原生 SQL、Upsert 与全局唯一 ID 等高级能力都通过统一的开关机制按需生成。理解 entc/gen/feature.go 中的特性定义与FeatureEnabled模板机制不仅能帮你精准组合这些能力还能在编写自定义模板与扩展extension.md时让生成代码随特性开关自动适配。建议在项目中从sql/globalid配合 GraphQL与privacy配合多租户入手逐步探索sql/modifier带来的 SQL 层自由度。赞分享后端ORM代码生成【免费下载链接】entAn entity framework for Go项目地址https://gitcode.com/gh_mirrors/en/ent点击查看免费下载相关推荐Redisson分布式ID生成高性能全局唯一ID策略Redisson分布式ID生成高性能全局唯一ID策略 在分布式系统中全局唯一ID的生成是一个常见需求。传统数据库自增ID在分布式环境下会遇到并发冲突、性能瓶后端缓存数据库客户端分布式20分钟跑通 faster-whisper 的 Windows CUDA 加速从驱动到第一句转写20分钟跑通 faster whisper 的 Windows CUDA 加速从驱动到第一句转写 一份两小时的会议录音下班前要出文字稿第二天还有十段访谈音人工智能语音本地部署UNICORN Binance WebSocket API安全配置API密钥管理与用户数据流保护UNICORN Binance WebSocket API安全配置API密钥管理与用户数据流保护 UNICORN Binance WebSocket API是上一篇JavaParser内存管理优化大型项目解析性能的终极指南下一篇Python Video Stabilization未来展望计算机视觉技术的创新应用创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
