支持任意SQL查询的PDO通用函数优化及代码问题排查

API 探路者

2026-10-1

现有代码存在的问题

全局依赖风险：使用global $pdo引入数据库实例，代码耦合度极高，无法支持多数据库连接场景，全局变量一旦被意外修改会直接导致函数异常，问题排查难度大
占位符参数判断逻辑bug：$placeholders默认值为false，当传入合法的空数组（无参数绑定的场景）时，if($placeholders)判定为假，若预处理语句存在占位符会直接导致执行失败
SQL类型判断不可靠：仅通过substr($query, 0, 1)取首字母判断是否为SELECT语句，遇到SQL开头带空格、注释、小写关键字的场景会完全判断错误，导致SELECT语句不返回结果集
SELECT结果处理逻辑缺陷：依赖rowCount()获取SELECT查询的结果数，但PDO官方明确说明rowCount()对SELECT语句的返回值不保证跨数据库兼容，部分驱动返回值不符合预期；查询无结果时fetch()会返回false，会被塞到结果数组中，调用方极易出现逻辑错误
错误信息误导：执行阶段的异常提示为「Connection failed」，和实际错误类型不符，排查问题时容易被误导
多余的stmt非空判断：开启了PDO::ERRMODE_EXCEPTION的情况下，prepare失败会直接抛异常，不会返回false，后面的if(!$stmt)判断完全多余

可优化调整点

改用依赖注入传入PDO实例，去除全局变量依赖，函数可复用性大幅提升，也支持多连接场景
调整$placeholders参数的默认值为空数组，直接传入execute即可，无需分支判断
优化SQL类型判断逻辑：先清除SQL开头的空白、注释，提取第一个关键字后转大写再做判断，兼容性更强
重构SELECT结果处理逻辑：统一使用fetchAll()返回二维数组，空查询直接返回空数组，格式统一，调用方可以直接通过count($data['result'])判断结果数量，兼容所有数据库驱动
优化错误提示信息，区分准备阶段、执行阶段的错误类型，便于排查
可新增针对INSERT/REPLACE语句的自增ID返回，方便业务获取插入后的主键值
可新增 fetch 模式参数，支持调用方自定义返回结果的格式（关联数组、索引数组、对象等）

优化后的参考代码

// 初始化PDO的部分保持不变
$pdo = new PDO($dsn, $user, $passwd);
$pdo->setAttribute(PDO::ATTR_DEFAULT_FETCH_MODE, PDO::FETCH_ASSOC);
$pdo->setAttribute(PDO::ATTR_EMULATE_PREPARES, false);
$pdo->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);

/**
 * 通用SQL查询执行函数
 * @param PDO $pdo 数据库连接实例
 * @param string $query 要执行的SQL语句
 * @param array $placeholders 预处理占位符对应的参数数组
 * @param int $fetchMode PDO结果集获取模式
 * @return array 包含执行结果/错误信息的数组
 */
function sql_query(PDO $pdo, string $query, array $placeholders = [], int $fetchMode = PDO::FETCH_ASSOC): array
{
    $data = [];

    // 提取SQL的首个关键字
    $cleanQuery = ltrim($query);
    $firstKeyword = strtoupper(strtok($cleanQuery, " \t\n\r\0\x0B"));

    try {
        $stmt = $pdo->prepare($query);
        $stmt->execute($placeholders);

        $data['count'] = $stmt->rowCount();

        // 针对返回结果集的语句处理
        if (in_array($firstKeyword, ['SELECT', 'SHOW', 'DESCRIBE', 'EXPLAIN'])) {
            $data['result'] = $stmt->fetchAll($fetchMode);
        }

        // 针对插入语句返回自增ID
        if (in_array($firstKeyword, ['INSERT', 'REPLACE'])) {
            $data['last_insert_id'] = $pdo->lastInsertId();
        }
    } catch (PDOException $e) {
        $data['error'] = sprintf('SQL执行失败: %s [SQL语句: %s]', $e->getMessage(), $query);
    }

    return $data;
}

内容的提问来源于stack exchange，提问作者Sam Arcos