Java SQLException SQLState 和 vendorCode 如何分层

在 JDBC 排查中，SQLException 里的 SQLState 和 vendorCode 不是二选一：前者适合先做跨驱动的错误分类，后者适合在确定数据库和驱动后定位厂商细节。生产代码可以按“异常类型 → SQLState → vendorCode → 异常链”的顺序处理，避免把某个数据库的数字错误码硬编码成所有数据库都能理解的规则。

官方地址：https://docs.oracle.com/en/java/javase/26/docs/api/java.sql/java/sql/SQLException.html

先分清 SQLState 与 vendorCode 的职责

getSQLState() 返回 SQLState，通常是五个字母数字字符；它的价值是让应用先回答“这是哪一类数据库错误”。getErrorCode() 返回厂商错误码，含义由驱动或底层数据源决定，适合回答“在这个数据库里具体是哪种错误”。

按 SQLState、vendorCode、异常类型建立判断层

比较实用的写法是先把“可迁移判断”和“驱动适配判断”分开。下面的示例只展示策略骨架，具体 SQLState 前缀和 vendorCode 数值应以目标数据库、驱动文档和现场日志为准。

static void classify(SQLException ex) {
    // SQLState 先做跨驱动的粗分类，避免把厂商码当成通用协议。
    String state = ex.getSQLState();
    int vendorCode = ex.getErrorCode();

    if (state != null && state.startsWith("23")) {
        // 约束或完整性冲突通常应返回业务错误，而不是盲目重试。
        record("constraint", state, vendorCode);
        return;
    }

    if (ex instanceof SQLTransientException) {
        // 瞬时异常仍要叠加幂等性、退避次数和连接状态判断。
        retryWithBackoff(state, vendorCode);
        return;
    }

    // 未识别的厂商细节进入适配表和人工排查，不静默吞掉异常。
    alertAndKeepChain(state, vendorCode, ex);
}

这里的关键不是把所有错误塞进几个分支，而是给每一层设边界：SQLState 负责归类，异常子类负责处理倾向，vendorCode 负责具体数据库的补充解释。即使某个驱动没有返回完整 SQLState，也不应因此把 vendorCode 当成跨数据库标准。

遍历 SQLException 异常链并保留关键字段

JDBC 驱动可能把多个数据库错误放在 nextException 链中，底层原因则可能挂在 cause。只打印第一条 getMessage()，常常会丢掉真正有用的约束名、服务器错误或连接原因。

static void logSqlExceptions(SQLException first) {
    // iterator() 可遍历 SQLException 及其链；逐项记录，便于按 state/code 检索。
    for (Throwable item : first) {
        if (item instanceof SQLException sql) {
            System.err.printf("sqlState=%s vendorCode=%d message=%s%n",
                    sql.getSQLState(), sql.getErrorCode(), sql.getMessage());
        } else {
            // 非 SQLException 的 cause 也保留，避免掩盖驱动底层原因。
            System.err.println("cause=" + item);
        }
    }
}

日志至少保留 SQLState、vendorCode、异常类型、操作名和脱敏后的参数摘要。不要把完整 SQL、密码或用户输入原样写入日志；字段脱敏属于日志层职责，不改变异常分层本身。

用驱动适配表验证重试与告警边界

最终处理动作应落在一张小型适配表上，而不是散落在业务代码里。适配表的键可以是“数据库类型 + 驱动主版本 + SQLState + vendorCode”，值则记录是否可重试、是否需要人工处理和对应官方文档。

验证时可以构造三类测试：同一 SQLState 换不同驱动，确认分类仍成立；同一 vendorCode 换数据库，确认适配表不会误匹配；异常带有 nextException 和 cause，确认日志没有丢链。这样“分层”才从代码结构变成可复查的行为。

相关问题

SQLState 为空时还能处理 SQLException 吗？

可以。先记录异常类型、vendorCode 和 cause，把该驱动标记为需要适配；不要用空值冒充某个标准类别。

vendorCode 能直接决定是否重试吗？

不能。它只提供厂商细节，重试还要看异常类型、事务是否可重放、请求是否幂等和连接状态。

为什么要遍历 nextException？

一次 JDBC 操作可能包含多个底层错误，后续异常可能带有真正的服务器提示或约束信息，只看第一条会丢失排障线索。