📚 课程目录第2章 Ent错误处理基础

2. Ent 错误处理基础：Go 语言错误处理惯例、Ent 错误类型概览、错误断言的基本概念

在深入 Ent 框架的错误处理之前，必须先理解 Go 语言本身的错误处理哲学。Ent 的设计高度遵循 Go 惯例，同时针对数据库操作的特殊性，构建了一套结构化的错误类型体系。本章将建立错误处理的理论基础，并介绍“错误断言”这一核心实战技巧。

2.1 Go 语言错误处理惯例

Go 语言没有异常机制，错误通过返回值显式传递。这是 Ent 错误处理的底层逻辑。

错误即值：错误是实现了 error 接口的值，可被赋值、传递、比较。
显式检查：每次函数调用后，开发者必须检查 err != nil。
哨兵错误：使用 var ErrXxx = errors.New("...") 定义包级错误常量，调用方通过 == 比较。
错误包装：使用 fmt.Errorf("context: %w", err) 或 errors.Join 保留错误链。

  关键惯例：Ent 完全遵循“错误即值”和“显式检查”原则。所有数据库操作（Create、Query、Update、Delete）均返回 error 作为最后一个返回值。

// Go 错误处理标准模式
result, err := client.User.
    Create().
    SetName("Alice").
    Save(ctx)
if err != nil {
    // 处理错误
    return err
}
// 使用 result

2.2 Ent 错误类型概览

Ent 将数据库操作中可能出现的错误归纳为几种核心类型。理解这些类型是进行精确错误断言的前提。

错误类型	对应常量/结构体	典型场景
约束违反	`ent.ConstraintError`	唯一索引冲突、外键约束失败
记录未找到	`ent.NotFoundError`	Query 时 ID 不存在、First 无结果
乐观锁冲突	`ent.OptimisticLockError`	并发更新时版本号不匹配
验证错误	`ent.ValidationError`	字段值不符合 Schema 定义的校验规则
通用操作错误	`*ent.OpError`	连接断开、SQL 语法错误、事务提交失败

这些错误类型均实现了 error 接口，同时提供了额外的上下文信息，例如触发错误的操作（Op）、字段名（Field）、具体的数据库错误（Err）等。

实战提示：不要直接使用 err.Error() 字符串匹配来判断错误类型。数据库驱动的错误信息可能因版本或方言（MySQL vs PostgreSQL）而变化。应始终使用 Ent 提供的类型断言函数。

2.3 错误断言的基本概念

“错误断言”是指将通用的 error 接口值，通过类型断言或辅助函数，转换为具体的 Ent 错误类型，从而获取结构化错误信息的过程。

Ent 为每种错误类型提供了对应的断言函数，这些函数是错误处理的核心工具。

import "entgo.io/ent/dialect/sql/sqlgraph"

// 断言是否为约束违反错误
if ent.IsConstraintError(err) {
    // 处理唯一键冲突等
}

// 断言是否为记录未找到错误
if ent.IsNotFound(err) {
    // 处理查询无结果
}

// 断言是否为乐观锁冲突
if ent.IsOptimisticLockError(err) {
    // 处理并发更新冲突
}

// 断言是否为验证错误
if ent.IsValidationError(err) {
    // 处理字段校验失败
}

这些断言函数内部使用 errors.As 或 errors.Is 遍历错误链，即使错误被多次包装，也能正确识别。

常见误区：不要使用 switch err.(type) 直接进行类型断言。因为错误可能被 fmt.Errorf 包装，原始类型会被隐藏。始终使用 Ent 提供的 Is* 函数或 errors.As 配合具体类型。

2.4 错误断言实战模式

在实际代码中，错误断言通常与 switch 或 if-else 链结合，实现精细化的错误处理分支。

// 实战模式：基于错误类型的多分支处理
err := client.User.
    Create().
    SetEmail("duplicate@example.com").
    Save(ctx)

switch {
case ent.IsConstraintError(err):
    // 唯一约束冲突，提示用户邮箱已注册
    log.Printf("约束违反: %v", err)
    return fmt.Errorf("邮箱已被使用")

case ent.IsValidationError(err):
    // 字段校验失败，返回具体字段错误
    var verr *ent.ValidationError
    errors.As(err, &verr)
    log.Printf("字段 %s 校验失败: %v", verr.Field, verr.Err)
    return fmt.Errorf("输入数据不合法")

case ent.IsNotFound(err):
    // 理论上 Create 不会触发 NotFound，此处仅为示例
    log.Printf("记录未找到: %v", err)
    return fmt.Errorf("操作失败")

default:
    // 其他未知错误，记录日志并返回通用错误
    log.Printf("未知数据库错误: %v", err)
    return fmt.Errorf("系统内部错误，请稍后重试")
}

  最佳实践：在 API 层或服务边界进行错误断言，将 Ent 的底层错误转换为业务友好的错误信息。不要在 DAO 层内部直接处理并吞掉错误，应向上传递以便上层统一处理。

2.5 错误断言与错误链

当使用 fmt.Errorf("context: %w", err) 包装错误后，原始错误类型仍然可以通过 errors.As 或 Ent 的断言函数访问。这是 Ent 错误处理能够跨越多个抽象层的关键。

// 服务层包装错误
func CreateUser(ctx context.Context, client *ent.Client) (*ent.User, error) {
    user, err := client.User.
        Create().
        SetEmail("test@example.com").
        Save(ctx)
    if err != nil {
        // 包装错误，保留原始类型
        return nil, fmt.Errorf("创建用户失败: %w", err)
    }
    return user, nil
}

// 调用方仍然可以断言
user, err := CreateUser(ctx, client)
if ent.IsConstraintError(err) {
    // 即使被包装，也能正确识别
    log.Println("约束违反，可能是邮箱重复")
}

这种机制使得错误处理可以在不丢失类型信息的前提下，逐层添加上下文，最终在顶层进行统一断言和处理。