异常教程

PHP mysqli_affected_rows() 函数（一文讲透）

更新时间:

💡一则或许对你有用的小广告

欢迎加入小哈的星球 ，你将获得：专属的项目实战(已更新的所有项目都能学习) / 1v1 提问 / Java 学习路线 / 学习打卡 / 每月赠书 / 社群讨论

  • 新开坑项目:《Spring AI 项目实战》 正在持续爆肝中，基于 Spring AI + Spring Boot 3.x + JDK 21...， 点击查看 ;
  • 《从零手撸：仿小红书（微服务架构）》 已完结，基于 Spring Cloud Alibaba + Spring Boot 3.x + JDK 17...，点击查看项目介绍 ;演示链接： http://116.62.199.48:7070 ;
  • 《从零手撸：前后端分离博客项目（全栈开发）》 2 期已完结，演示链接： http://116.62.199.48/ ;

截止目前， 星球 内专栏累计输出 90w+ 字，讲解图 3441+ 张，还在持续爆肝中.. 后续还会上新更多项目，目标是将 Java 领域典型的项目都整一波，如秒杀系统, 在线商城, IM 即时通讯，权限管理，Spring Cloud Alibaba 微服务等等，已有 3100+ 小伙伴加入学习 ，欢迎点击围观

前言：数据库操作中的状态反馈

在 PHP 开发中，与数据库交互是日常工作的核心内容之一。无论是增删改查（CRUD）操作，开发者都需要准确了解执行结果，例如：一条 SQL 语句究竟影响了多少行数据？是否需要根据结果调整后续逻辑？此时，mysqli_affected_rows() 函数便成为了一个不可或缺的工具。

本文将从基础概念出发，逐步深入讲解该函数的功能、使用场景、注意事项及实际案例。通过通俗易懂的比喻和代码示例，帮助编程初学者和中级开发者快速掌握这一工具，并理解其在实际开发中的重要性。

一、函数基础：定义与核心语法

1.1 函数定义与作用

mysqli_affected_rows() 是 PHP 中用于获取最近一次数据库操作（如 INSERT、UPDATE、DELETE）所影响的行数的函数。其返回值为整数，具体含义如下：

  • 正数：表示受影响的行数（例如：更新了 3 行数据）。
  • 0：表示操作未影响任何行（例如：执行了 UPDATE 但未匹配到符合条件的记录）。
  • -1：表示操作失败或未执行（例如：执行了 SELECT 语句，或发生语法错误）。

1.2 函数语法

mixed mysqli_affected_rows(mysqli $link)

  • 参数说明：
    $link 是由 mysqli_connect() 或 new mysqli() 创建的数据库连接对象。

  • 返回值类型：
    返回 int 或 null（当操作未执行时可能返回 null）。

1.3 形象比喻

可以将 mysqli_affected_rows() 想象为一个“交通信号灯”：

  • 绿灯（正数）：表示操作成功且影响了具体数量的数据。
  • 黄灯（0）：表示操作未产生实际效果（如更新条件不匹配）。
  • 红灯（-1 或 null）：表示操作失败或存在逻辑问题，需进一步排查。

二、核心使用场景

2.1 增删改操作中的典型应用

案例 1：更新用户信息

// 建立数据库连接  
$mysqli = new mysqli("localhost", "username", "password", "database");  

// 更新用户信息  
$sql = "UPDATE users SET age = 25 WHERE id = 101";  
if ($mysqli->query($sql)) {  
    $affected = $mysqli->affected_rows;  
    echo "受影响的行数：" . $affected;  
} else {  
    echo "操作失败：" . $mysqli->error;  
}

输出结果：

  • 如果用户 ID 101 存在，可能输出：受影响的行数：1。
  • 如果用户 ID 101 不存在，则输出 受影响的行数：0。

案例 2：删除无效订单

// 删除状态为 "invalid" 的订单  
$sql = "DELETE FROM orders WHERE status = 'invalid'";  
if ($mysqli->query($sql)) {  
    $affected = $mysqli->affected_rows;  
    echo "已删除 " . $affected . " 条无效订单";  
}

2.2 与事务的结合

在事务中使用 mysqli_affected_rows() 可以精确控制操作流程：

$mysqli->begin_transaction();  
try {  
    // 执行多个操作  
    $mysqli->query("UPDATE users SET balance = balance - 100 WHERE id = 1");  
    $mysqli->query("UPDATE users SET balance = balance + 100 WHERE id = 2");  

    // 检查是否所有操作均生效  
    if ($mysqli->affected_rows < 2) {  
        throw new Exception("事务失败，受影响行数不足");  
    }  
    $mysqli->commit();  
} catch (Exception $e) {  
    $mysqli->rollback();  
    echo "事务回滚：" . $e->getMessage();  
}

三、注意事项与常见问题

3.1 关键细节：仅适用于增删改操作

mysqli_affected_rows() 不适用于 SELECT 语句。例如：

$sql = "SELECT * FROM users WHERE age > 18";  
$mysqli->query($sql);  
echo $mysqli->affected_rows; // 输出：-1

原因：SELECT 操作不会修改数据，因此函数返回 -1。若需获取查询结果的行数，应使用 mysqli_num_rows() 函数。

3.2 事务与自动提交模式

默认情况下，MySQL 连接处于自动提交模式（autocommit = ON）。若使用事务，需显式关闭自动提交：

$mysqli->autocommit(false); // 关闭自动提交  
// ...执行事务操作...

否则，mysqli_affected_rows() 可能返回意外结果。

3.3 多次操作的覆盖问题

若连续执行多个 SQL 语句，需注意函数的“最近一次”特性：

$mysqli->query("UPDATE users SET age = 20"); // 影响 5 行  
$mysqli->query("DELETE FROM orders");         // 影响 10 行  
echo $mysqli->affected_rows; // 输出：10（最后一次操作的结果）

解决方案：在每次关键操作后立即调用函数，或保存结果到变量。

四、进阶技巧与最佳实践

4.1 结合错误处理

将 mysqli_affected_rows() 与错误信息结合，可提升调试效率：

if ($mysqli->query($sql)) {  
    $affected = $mysqli->affected_rows;  
    if ($affected === 0) {  
        echo "未找到匹配记录！";  
    } else {  
        echo "操作成功，影响 $affected 行。";  
    }  
} else {  
    echo "错误：" . $mysqli->error;  
}

4.2 批量操作的优化

在批量更新或删除时，通过 mysqli_affected_rows() 可快速验证操作范围：

// 批量更新用户状态  
$sql = "UPDATE users SET status = 'active' WHERE last_login > '2023-01-01'";  
$mysqli->query($sql);  
echo "成功激活 " . $mysqli->affected_rows . " 个用户";

4.3 与 mysqli_error() 的配合

函数本身不返回错误信息，但可通过 mysqli_error() 补充诊断：

if ($mysqli->query($sql)) {  
    // 处理成功逻辑  
} else {  
    $error = $mysqli->error;  
    echo "操作失败：$error";  
}

五、与其他函数的对比

5.1 与 mysqli_num_rows() 的区别

函数名适用场景返回值含义
mysqli_affected_rows()INSERT/UPDATE/DELETE影响的行数（增删改）
mysqli_num_rows()SELECT查询结果的行数（只读）

5.2 与 mysqli_store_result() 的关系

mysqli_store_result() 用于获取查询结果集，而 mysqli_affected_rows() 专注于操作状态反馈。二者通常在不同场景中使用。

六、结论：掌握状态反馈，提升代码健壮性

通过深入理解 PHP mysqli_affected_rows() 函数的功能与使用场景，开发者可以更精准地控制数据库操作流程。无论是验证更新是否生效、排查事务异常，还是优化批量操作逻辑，该函数都是实现健壮代码的重要工具。

建议在实际开发中：

  1. 始终检查返回值，避免“沉默失败”；
  2. 结合错误信息与日志，增强调试能力；
  3. 在复杂事务中合理利用函数反馈，确保数据一致性。

掌握这一工具后，开发者将能够更自信地应对数据库交互中的各种挑战。

最新发布

查看更多文章