Java JDBC 怎样读取批量插入生成键

Java JDBC 做批量插入时，如果主键由数据库生成，不能只调用 executeBatch() 就期待拿到一个主键数组。正确做法是：创建 PreparedStatement 时传入 Statement.RETURN_GENERATED_KEYS，执行批次后立即调用 getGeneratedKeys()，再像遍历普通结果集一样读取每一行生成键。

本文只讨论 JDBC 标准接口中的生成键选项和结果集遍历，不绑定某一种数据库方言。官方 API 文档可以从这里开始阅读：

官方文档：https://docs.oracle.com/en/java/javase/25/docs/api/java.sql/java/sql/Connection.html

生成键接口：https://docs.oracle.com/en/java/javase/25/docs/api/java.sql/java/sql/Statement.html

批量插入生成键的核心是两个动作：创建预编译语句时明确要求返回生成键，执行批次后用 getGeneratedKeys() 读取 ResultSet。至于每一行结果能否稳定对应输入记录，要再看 JDBC 驱动能力和你的业务映射策略。

先把批量插入的键返回契约说清楚

JDBC 不把生成键设计成 long[] 这样的固定返回值。getGeneratedKeys() 返回的是一个 ResultSet，因为数据库可能生成一个键，也可能生成多行键，还可能返回多个生成列。

因此，代码要按结果集处理：

• prepareStatement(sql, Statement.RETURN_GENERATED_KEYS)：向驱动声明希望读取自动生成键。
• executeBatch()：执行当前预编译语句中的批量参数。
• getGeneratedKeys()：取得本次语句执行所产生的键结果集。
• keys.next()：逐行移动游标，再用 getLong(1) 或列名读取具体值。

官方接口也提醒，是否支持自动生成键以及哪些语句可以返回生成键，部分行为由数据库和驱动决定。不能因为某一个驱动能返回结果，就把它当成所有数据库的统一保证。

用 PreparedStatement 声明需要生成键

最容易漏掉的是创建语句时的第二个参数。只写 connection.prepareStatement(sql)，再在执行后调用 getGeneratedKeys()，在部分驱动中会得到空结果或直接报告不支持。应当在创建时显式传入 Statement.RETURN_GENERATED_KEYS。

String sql = "INSERT INTO member (nickname, level) VALUES (?, ?)";

// 第二个参数明确要求驱动保留本次插入产生的键。
try (PreparedStatement statement = connection.prepareStatement(
        sql,
        Statement.RETURN_GENERATED_KEYS)) {
    // 每次绑定一组参数，再加入当前批次。
    statement.setString(1, "阿青");
    statement.setInt(2, 3);
    statement.addBatch();

    statement.setString(1, "小河");
    statement.setInt(2, 2);
    statement.addBatch();

    // 执行批量 INSERT；生成键要在同一个 statement 上读取。
    int[] counts = statement.executeBatch();
}

这里的 counts 是每个批次项的更新计数，不是生成键。不要把更新计数数组当作主键数组，它只能帮助你判断驱动报告了多少条更新结果。

执行批量插入并读取全部结果行

读取生成键时，应该紧跟在 executeBatch() 后面，并让 ResultSet 也由 try-with-resources 管理。下面的示例把每个生成键收集到列表中，示例中的表名和字段名只用于说明 JDBC 调用关系。

List generatedIds = new ArrayList();

// 事务边界由调用方控制；这里展示批次与生成键的同一条语句链路。
try (PreparedStatement statement = connection.prepareStatement(
        "INSERT INTO member (nickname, level) VALUES (?, ?)",
        Statement.RETURN_GENERATED_KEYS)) {
    for (MemberInput input : inputs) {
        // 先绑定当前记录，再放入批次，避免复用旧参数。
        statement.setString(1, input.nickname());
        statement.setInt(2, input.level());
        statement.addBatch();
    }

    // 空批次不会产生可读取的生成键，调用前先做业务判断。
    if (!inputs.isEmpty()) {
        statement.executeBatch();

        // 生成键是 ResultSet，必须通过 next() 逐行读取。
        try (ResultSet keys = statement.getGeneratedKeys()) {
            while (keys.next()) {
                // 第一列是常见约定；多生成列时应改用列名或明确索引。
                generatedIds.add(keys.getLong(1));
            }
        }
    }
}

遍历前不要默认结果集一定非空。驱动不支持生成键、表没有数据库生成列、语句不是可返回生成键的插入语句，或者驱动采用了自己的限制，都可能导致空结果或 SQLFeatureNotSupportedException。这些情况需要回到数据库和驱动文档处理，而不是用默认的 0 冒充主键。

把生成键与输入记录安全关联

如果你的业务只需要“拿到所有新主键”，上面的列表就够用。但如果下一步要把生成键写回内存中的输入对象，就必须先定义映射规则。很多实现会把第一个结果集行对应到第一个输入项、第二行对应第二个输入项，这在常用驱动上可能成立，但不应脱离驱动文档宣称为 JDBC 跨数据库保证。

更稳妥的做法有三种：

1. 确认目标数据库和 JDBC 驱动明确支持批量生成键，并把驱动版本、映射假设写入数据访问层说明。
2. 让每条输入记录携带业务侧唯一标识，插入后再通过唯一标识查询或关联，避免只依赖返回顺序。
3. 当严格一一对应比吞吐更重要时，按单条插入读取生成键；这是性能换确定性的选择。

如果要在批量读取后就地构造对象，可以把映射假设集中在一个小方法中，并在行数不符合预期时立即报错：

static List readGeneratedIds(
        PreparedStatement statement,
        int expectedCount) throws SQLException {
    List ids = new ArrayList(expectedCount);

    // 用 try-with-resources 确保键结果集及时释放。
    try (ResultSet keys = statement.getGeneratedKeys()) {
        while (keys.next()) {
            ids.add(keys.getLong(1));
        }
    }

    // 行数不一致时不要静默错配输入记录和主键。
    if (ids.size() != expectedCount) {
        throw new SQLException("生成键数量与输入批次不一致");
    }
    return ids;
}

这段检查不是为了证明每个驱动都按输入顺序返回，而是把“我需要一一对应”这个业务前提显式化。若目标驱动只返回部分键、返回额外生成列，或批次语义不同，应改用数据库专用返回语法或业务唯一标识方案。

用事务和边界检查收口实现

批量插入通常和后续写入存在同一业务事务。生成键已经读取，不等于事务已经提交；如果后续步骤失败，应回滚整个事务，并清理已经读入内存的临时键，避免调用方误以为这些键已经可用。

connection.setAutoCommit(false);
try (PreparedStatement statement = connection.prepareStatement(
        "INSERT INTO member (nickname, level) VALUES (?, ?)",
        Statement.RETURN_GENERATED_KEYS)) {
    for (MemberInput input : inputs) {
        // 参数绑定和 addBatch 必须在同一个 statement 生命周期内完成。
        statement.setString(1, input.nickname());
        statement.setInt(2, input.level());
        statement.addBatch();
    }

    if (inputs.isEmpty()) {
        // 空批次没有数据库动作，直接提交当前空事务并返回空列表。
        connection.commit();
        return List.of();
    }

    statement.executeBatch();
    List ids = readGeneratedIds(statement, inputs.size());

    // 只有后续业务也成功时才提交生成键对应的插入。
    connection.commit();
    return ids;
} catch (SQLException error) {
    // 回滚失败也应保留原始异常，避免丢失真正的数据库错误。
    try {
        connection.rollback();
    } catch (SQLException rollbackError) {
        error.addSuppressed(rollbackError);
    }
    throw error;
}

这段代码依赖调用方已有连接和事务管理，重点是顺序与边界：空批次不读取键，语句失败时不把部分列表当作成功结果，资源由 try-with-resources 关闭，回滚异常通过 suppressed exception 保留下来。

常见边界可以这样判断

小结

Java JDBC 读取批量插入生成键的最小路径是：创建 PreparedStatement 时传入 Statement.RETURN_GENERATED_KEYS，调用 executeBatch()，再通过 getGeneratedKeys() 遍历 ResultSet。真正容易出错的地方不在 getLong(1)，而在于把更新计数误当主键、把空结果当成 0、把驱动顺序当成统一标准，以及在事务失败后继续使用未提交的键。

相关问题

• 为什么 executeBatch() 的返回值不是生成键？它返回的是批次更新计数；生成键要通过同一个语句对象的 getGeneratedKeys() 读取。
• 必须使用 getLong(1) 吗？不必须。若驱动返回的生成列有明确列名，使用列名更容易表达意图；多列生成键也应明确列索引或列名。
• 所有数据库都保证批量生成键顺序吗？不能这样假设。应以目标数据库和 JDBC 驱动文档为准，严格映射时增加业务唯一标识或采用单条插入。
• 读取生成键后能马上提交吗？如果后续业务仍属于同一事务，应等后续操作成功后再提交；读取到键不等于事务已经提交。