PHP PDO 事务中如何用 SAVEPOINT 局部回滚：批量导入的错误恢复

批量导入订单、商品或配置时，最麻烦的不是捕获异常，而是决定失败范围：一条脏数据是否要让整批数据全部回滚？PHP PDO 可以把一次大事务切成多个可恢复的小段，关键工具就是 MySQL 的 SAVEPOINT。遇到单条记录失败时回滚到保存点，其他已经通过校验的记录仍留在当前事务里，最后统一提交。

先把批量导入的回滚边界说清楚

假设导入接口一次接收 100 条商品记录。第 17 条因为 SKU 重复失败，业务通常有两种选择：严格模式下整批失败，宽松模式下跳过第 17 条并保存其余 99 条。SAVEPOINT 适合第二种模式，但它不是“每条记录自动开一个事务”，而是在同一个外层事务内留下可返回的位置。

这一区别很重要：如果连接断开、表结构错误或事务提交失败，仍然应该回滚整个事务；只有可预期的单条业务错误，才回滚到当前记录的保存点并继续。

准备一个能复现的 PDO 导入表

示例表使用唯一索引模拟常见的重复 SKU 错误。先确认 PDO 连接启用了异常模式，否则 execute() 的失败可能只返回 false，很难区分业务错误和连接故障。

CREATE TABLE import_items (
    id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    sku VARCHAR(64) NOT NULL UNIQUE,
    title VARCHAR(120) NOT NULL,
    created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
) ENGINE=InnoDB;

$pdo = new PDO(
    'mysql:host=127.0.0.1;dbname=demo;charset=utf8mb4',
    'demo_user',
    'demo_password',
    [
        PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
        PDO::ATTR_EMULATE_PREPARES => false,
    ]
);

表必须使用支持事务的 InnoDB。若表是 MyISAM，代码即使调用了 beginTransaction()，也无法获得预期的回滚效果。

用一个保存点包住一条记录

保存点名称不支持 PDO 参数绑定，因此不要把 SKU 或请求字段直接拼到名称里。下面用递增序号组成只含字母、数字和下划线的名称；真正写入表的数据仍然全部使用预处理参数。

$rows = [
    ['sku' => 'A-100', 'title' => '蓝色水杯'],
    ['sku' => 'A-100', 'title' => '重复水杯'],
    ['sku' => 'A-101', 'title' => '便携雨伞'],
];

$insert = $pdo->prepare(
    'INSERT INTO import_items (sku, title) VALUES (:sku, :title)'
);

$success = 0;
$failed = [];
$pdo->beginTransaction();

try {
    foreach ($rows as $index => $row) {
        $savepoint = 'row_' . $index;
        $pdo->exec('SAVEPOINT ' . $savepoint);

        try {
            $insert->execute([
                ':sku' => $row['sku'],
                ':title' => $row['title'],
            ]);
            $success++;
            $pdo->exec('RELEASE SAVEPOINT ' . $savepoint);
        } catch (PDOException $e) {
            $pdo->exec('ROLLBACK TO SAVEPOINT ' . $savepoint);
            $failed[] = [
                'index' => $index,
                'sku' => $row['sku'],
                'reason' => $e->getCode() === '23000' ? 'SKU重复' : '写入失败',
            ];
            $pdo->exec('RELEASE SAVEPOINT ' . $savepoint);
        }
    }

    $pdo->commit();
} catch (Throwable $e) {
    if ($pdo->inTransaction()) {
        $pdo->rollBack();
    }
    throw $e;
}

这个例子里第二条记录触发唯一索引冲突，只撤销第二条记录的动作。第一条和第三条仍会随最后的 commit() 一起落库。RELEASE SAVEPOINT 不是必须的，但及时释放无用保存点能让代码意图更清楚。

哪些错误应该继续，哪些错误必须整批回滚

不要为了“尽量导入”而吞掉所有异常。重复 SKU、字段业务校验失败这类可预期错误可以放入 $failed；连接断开、死锁、未知 SQL 错误则应抛出，让外层事务整体回滚。

本地验收：检查数据库和返回统计

运行脚本后，不要只看接口返回的成功数。用查询确认 import_items 中实际存在 A-100 和 A-101，并确认重复的第二条没有生成额外记录。

SELECT sku, title
FROM import_items
WHERE sku IN ('A-100', 'A-101')
ORDER BY sku;

接口响应可以返回 success=2、failed=1，并附上失败行的索引和 SKU。生产环境还应把事务耗时、批次号和数据库异常码写入结构化日志，方便判断是数据问题还是基础设施问题。

常见问题

SAVEPOINT 能不能跨请求继续使用？

不能。保存点只属于当前数据库连接和当前事务，请求结束或事务提交后就失效。

回滚到保存点后，前面的插入会消失吗？

不会。ROLLBACK TO SAVEPOINT 只撤销保存点之后的动作，保存点之前的操作仍留在外层事务中。

为什么保存点名称不能绑定 PDO 参数？

参数绑定用于值，不用于 SQL 标识符。保存点名称应由程序内部的安全序号生成，避免拼接外部输入造成语法或注入风险。

把局部容错留在明确的事务边界内

PHP PDO 的 SAVEPOINT 解决的是“单条记录失败后回到哪里”，并不替代整批事务的异常兜底。先区分可恢复的业务错误与必须停止的系统错误，再决定是否局部回滚；最后用数据库查询核对落库结果，这样批量导入的成功统计才有依据。