Ent框架中GraphQL突变操作的字段排除技巧

概述

在使用Ent框架的GraphQL生成工具时，开发者经常会遇到需要从突变(Mutation)操作中排除某些字段的需求。这些字段通常是用于系统内部管理的元数据字段，如创建时间(created_at)、更新时间(updated_at)和ID等，它们应该由系统自动维护而不允许通过API直接修改。

常见场景

在实际开发中，我们经常会定义一些基础字段作为Mixin混入到多个实体中。这些字段包括：

• 创建时间(create_time)：记录数据创建时间戳
• 更新时间(update_time)：记录最后更新时间戳
• ID：唯一标识符

这些字段通常具有以下特点：

1. 创建时间在记录创建时自动设置为当前时间，之后不可更改
2. 更新时间在记录创建和每次更新时自动设置为当前时间
3. ID由系统自动生成，不允许修改

解决方案

Ent框架提供了entgql.Skip注解来优雅地解决这个问题。开发者可以通过这个注解精确控制哪些字段应该从GraphQL的突变输入类型中排除。

基本用法

在字段定义中添加entgql.Skip注解，并指定要跳过的突变类型：

field.Time("create_time").
    Default(time.Now).
    Immutable().
    Annotations(
        entgql.Skip(entgql.SkipMutationCreateInput|entgql.SkipMutationUpdateInput),
        entgql.OrderField("CREATE_TIME"),
    ),

在Mixin中使用

对于混入多个实体的公共字段，可以在Mixin中统一配置：

func (CommonMixin) Fields() []ent.Field {
    return []ent.Field{
        field.Time("create_time").
            Default(time.Now).
            Immutable().
            Annotations(
                entgql.Skip(entgql.SkipMutationCreateInput|entgql.SkipMutationUpdateInput),
                entgql.OrderField("CREATE_TIME"),
            ),
        field.Time("update_time").
            Default(time.Now).
            UpdateDefault(time.Now).
            Immutable().
            Annotations(
                entgql.Skip(entgql.SkipMutationCreateInput|entgql.SkipMutationUpdateInput),
                entgql.OrderField("UPDATE_TIME"),
            ),
        field.UUID("id", uuid.Nil).
            Default(UUIDV7DefaultFn).
            Immutable().
            Annotations(
                entgql.Skip(entgql.SkipMutationCreateInput|entgql.SkipMutationUpdateInput),
            ),
    }
}

使用mixin.AnnotateFields

对于已经定义好的Mixin，可以使用mixin.AnnotateFields来添加注解：

func (T) Mixin() []ent.Mixin {
    return []ent.Mixin{
        mixin.AnnotateFields(
            mixin.Time{},
            entgql.Skip(entgql.SkipMutationCreateInput|entgql.SkipMutationUpdateInput),
        ),
    }
}

注意事项

1. 使用entgql.Skip只会从突变输入类型中排除字段，不会影响查询和排序功能
2. 与sensitive注解不同，被跳过的字段仍然会在查询结果中可见
3. 建议同时使用Immutable()来确保这些字段在业务逻辑层也无法被修改
4. 对于ID字段，除了跳过突变外，还应该设置合适的默认值生成函数

最佳实践

1. 将公共字段集中定义在Mixin中统一管理
2. 为时间戳字段设置合适的默认值和更新逻辑
3. 同时使用Immutable和Skip注解提供双重保护
4. 为排序常用的字段添加OrderField注解
5. 在文档中明确说明这些系统字段的行为

通过合理使用entgql.Skip注解，开发者可以构建出更加健壮和安全的GraphQL API，同时保持代码的整洁和一致性。