📚 课程目录第2章 Ent 错误类型概览

2. Ent 错误类型概览：核心错误类型

在 Ent 驱动的 Go 应用中，数据库操作失败时返回的错误并非普通的 error 字符串，而是具有明确类型的结构化错误。理解这些错误类型是进行精准断言的前提。Ent 将常见数据库异常抽象为以下五种核心错误类型，它们均实现了 sqlgraph.Error 接口，并可通过 ent.IsXxx 系列函数进行断言。

2.1 错误类型体系总览

下表列出了 Ent 中最常用的五种错误类型、触发场景及断言函数，帮助你快速建立全局认知。

错误类型	触发场景	断言函数	典型 SQL 原因
NotFoundError	查询单个记录时未找到	`ent.IsNotFound(err)`	`SELECT ... WHERE id=? 返回 0 行`
NotSingularError	查询单个记录时返回多条	`ent.IsNotSingular(err)`	`SELECT ... WHERE ... 返回 >1 行`
ConstraintError	违反数据库约束	`ent.IsConstraintError(err)`	唯一索引冲突、外键失败、非空约束
ValidationError	Ent 内置字段校验失败	`ent.IsValidationError(err)`	字符串超长、枚举值非法、空值校验
PrivacyError	隐私策略拒绝操作	`ent.IsPrivacyError(err)`	权限检查未通过、数据访问被拦截

提示： 所有断言函数均位于 ent 包顶层，无需导入子包。断言函数内部通过类型断言或错误链遍历实现，对包装后的错误同样有效。

2.2 核心错误类型详解

2.2.1 NotFoundError

这是最常遇到的错误类型。当使用 QueryX().Only()、Get() 或 First() 方法且数据库中没有匹配记录时触发。该错误携带了被查询的实体类型和 ID 信息，便于日志记录。

// 典型触发代码
user, err := client.User.Get(ctx, 999)
if ent.IsNotFound(err) {
    // 业务逻辑：返回 404 或创建默认用户
    log.Printf("用户 999 不存在: %v", err)
    return nil, ErrUserNotFound
}

2.2.2 NotSingularError

当期望查询结果唯一（Only()），但实际返回多条记录时抛出。这通常意味着查询条件过于宽泛或数据存在重复。该错误会包含实际返回的行数，方便排查。

// 假设 email 字段未设置唯一索引
users, err := client.User.Query().Where(user.Name("张三")).Only(ctx)
if ent.IsNotSingular(err) {
    // 业务逻辑：返回 409 或提示用户数据异常
    log.Printf("查询到多个同名用户: %v", err)
    return nil, ErrMultipleUsersFound
}

2.2.3 ConstraintError

对应数据库层面的约束违反，是 CRUD 操作中最需要关注的错误类型。Ent 会尝试解析数据库驱动返回的错误码，将其统一为 ConstraintError。常见子类型包括：

唯一约束冲突：插入重复的邮箱、用户名等。
外键约束失败：引用了不存在的关联记录。
非空约束违反：向 NOT NULL 列插入 NULL 值。

// 唯一约束冲突示例
_, err := client.User.Create().SetEmail("duplicate@test.com").Save(ctx)
if ent.IsConstraintError(err) {
    // 业务逻辑：返回 409 并提示用户邮箱已被注册
    return nil, ErrEmailAlreadyExists
}

2.2.4 ValidationError

在数据到达数据库之前，Ent 的代码生成层会执行字段校验。例如：String 类型的 MaxLen 校验、Enum 类型的值范围校验、Required 字段的空值校验。这类错误不会真正执行 SQL，属于客户端校验失败。

// 假设 User.name 设置了 MaxLen(10)
_, err := client.User.Create().SetName("这是一个超过十个字符的名字").Save(ctx)
if ent.IsValidationError(err) {
    // 业务逻辑：返回 400 并提示字段校验失败
    log.Printf("字段校验失败: %v", err)
    return nil, ErrInvalidInput
}

2.2.5 PrivacyError

当 Ent 的隐私策略（Privacy Policy）拒绝当前操作时抛出。这是 Ent 在应用层实现的权限控制机制，常用于多租户隔离、软删除拦截等场景。该错误通常需要结合业务上下文处理。

// 假设已配置隐私策略：非管理员不能删除用户
_, err := client.User.DeleteOneID(1).Exec(ctx)
if ent.IsPrivacyError(err) {
    // 业务逻辑：返回 403 权限不足
    return nil, ErrPermissionDenied
}

2.3 错误类型关系与断言优先级

以下 SVG 图展示了 Ent 错误类型的继承关系及断言时的优先级顺序。注意：ConstraintError 和 ValidationError 可能同时存在于一次操作中，但断言时建议按“数据库层 → 应用层”的顺序检查。

2.4 错误类型对比速查

在实际编码中，不同错误类型对应不同的 HTTP 状态码和业务处理策略。以下对比表可帮助你在 API 层快速决策：

错误类型	推荐 HTTP 状态码	业务处理策略	是否重试
NotFoundError	404	返回资源不存在提示	否
NotSingularError	409 / 500	记录日志，提示数据异常	否
ConstraintError	409	提示用户输入冲突（如邮箱重复）	否
ValidationError	400	返回具体字段校验错误信息	否
PrivacyError	403	返回权限不足提示	否

注意： 不要将 ConstraintError 与 ValidationError 混淆。前者是数据库执行时抛出的，后者是 Ent 客户端代码在 SQL 执行前校验失败的。在错误处理中，建议先检查 ValidationError，再检查 ConstraintError，因为校验失败不会产生数据库开销。

2.5 错误类型获取与调试

除了使用断言函数，你还可以通过类型断言获取错误的具体实例，从而提取更多上下文信息：

// 获取 NotFoundError 的详细信息
if err != nil {
    var nfErr *ent.NotFoundError
    if errors.As(err, &nfErr) {
        fmt.Printf("未找到的实体类型: %s, ID: %v\n", nfErr.Table(), nfErr.ID())
    }
}

// 获取 ConstraintError 的详细信息
var cErr *ent.ConstraintError
if errors.As(err, &cErr) {
    fmt.Printf("违反的约束类型: %s, 详情: %s\n", cErr.ConstraintType(), cErr.Detail())
}