PHP SQLite3 怎么用扩展错误码定位唯一约束冲突

我在整理 SQLite 写入日志时遇到过一个很典型的误区：日志里明明有“约束失败”，却无法判断是唯一键、非空还是外键。只记录 lastErrorMsg() 时，程序拿到的通常是一段英文描述；更稳的做法是打开扩展错误码，再同时保存主错误码、扩展错误码和异常消息。唯一约束冲突的主码是 SQLITE_CONSTRAINT（数值 19），更具体的扩展码是 SQLITE_CONSTRAINT_UNIQUE（数值 2067）。

官方地址：https://www.php.net/manual/en/sqlite3.enableextendedresultcodes.php

错误码表：https://www.sqlite.org/rescode.html

在连接建立后调用 $db->enableExtendedResultCodes(true)，异常发生后用 lastErrorCode() 读取细分结果；为了兼容没有打开该开关的旧代码，日志还应保留 lastExtendedErrorCode()。

我先把 19 和 2067 放进同一张日志

SQLite 把错误码拆成两层：低位部分表示宽泛的主错误码，更高位补充具体原因。SQLITE_CONSTRAINT 只能说明某项约束被违反；SQLITE_CONSTRAINT_UNIQUE 才能把这次失败归类为唯一性约束冲突。PHP 手册的示例中，未启用扩展码时 lastErrorCode() 返回 19，启用后返回 2067。

因此，业务日志不应该只写“插入失败”。至少把连接、操作类型、主码、扩展码和 SQLite 返回的英文消息放在同一条事件里，后续才能区分唯一键、非空、外键等不同约束问题。

打开开关后，我不再只相信一段错误文本

enableExtendedResultCodes() 是连接对象的方法，默认参数是 true。它影响的是随后由 lastErrorCode() 报告的结果码；lastExtendedErrorCode() 不受这个开关影响，始终返回扩展结果码。这个差别适合用来兼容旧代码或做迁移期对照。

enableExtendedResultCodes(true)) {
    // 开关失败时不要继续假设 lastErrorCode() 一定足够具体。
    throw new RuntimeException('无法启用 SQLite 扩展错误码');
}

// 示例只表达诊断配置；真实写入应继续使用参数绑定。
$db->exec('CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, email TEXT UNIQUE)');
$db->close();

开关应该绑定到连接初始化，而不是只放在某个偶发的写入分支。这样同一个连接上的不同 SQL 操作都遵守相同的诊断口径。对我来说，最大的收获不是日志变长，而是把“人读的消息”和“程序用的分类键”分开了。

异常分支里，我会同时保存三类信息

如果项目开启了 enableExceptions(true)，写操作失败时可以从异常进入统一日志分支。异常消息适合给人看，数值错误码适合程序分类，lastExtendedErrorCode() 则能在连接配置变化时继续提供最细粒度的 SQLite 结果。诊断日志本身也是需要保护的运行资产：我会记录操作名和错误码，但不会把用户输入原文、完整 SQL 或连接路径无条件写入公共日志。

enableExceptions(true);
$db->enableExtendedResultCodes(true);
$db->exec('CREATE TABLE users (id INTEGER PRIMARY KEY, email TEXT UNIQUE)');
$db->exec("INSERT INTO users (email) VALUES ('dev@example.com')");

try {
    // 第二次写入故意使用相同 email，只用于说明冲突分类位置。
    $db->exec("INSERT INTO users (email) VALUES ('dev@example.com')");
} catch (Throwable $e) {
    // 消息用于人工排查，数字码用于稳定的机器分类。
    $primaryCode = $db->lastErrorCode();
    $extendedCode = $db->lastExtendedErrorCode();
    error_log(json_encode([
        'operation' => 'insert_user',
        'exception' => $e->getMessage(),
        'primary_code' => $primaryCode,
        'extended_code' => $extendedCode,
    ], JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES));
}

// 示例结束后关闭连接，避免长生命周期进程遗留资源。
$db->close();

我最后把 2067 作为分类键，不解析英文消息

应用层可以把扩展码 2067 单独归类为唯一约束冲突，把 19 保留为“约束失败但细分信息不足”。不要用 strpos($message, 'UNIQUE') 代替数值判断：错误消息是面向人的英文文本，可能随 SQLite 构建、驱动或上层包装变化；错误码才是适合路由、指标和重试策略的字段。

如果写入使用的是预处理语句，诊断逻辑不变：继续从发生失败的同一个 SQLite3 连接读取错误码。我的取舍是让 2067 进入指标和审计字段，让错误文本只服务人工排查；这样既能保留定位线索，也不会因为文案变化触发错误分支。本文只讨论错误分类，不延伸到如何设计唯一索引、如何合并重复数据，也不建议因为拿到 2067 就盲目重试同一条写入。

相关问题

为什么开启扩展码后还要记录 lastExtendedErrorCode()？ 因为后者不依赖开关，适合作为迁移期或公共诊断函数的兜底字段。

lastErrorMsg() 能不能作为唯一判断依据？ 不建议。它返回英文说明文本，适合日志阅读，程序分支应优先使用数值错误码。

只有 19 没有 2067 说明没有唯一约束吗？ 不能这样推断；它只说明当前读取到的是主错误码，或者细分码没有被当前诊断路径保留下来。