怎样使用PDOStatement::columnCount函数准确获取查询结果的列数？

gitbox 2025-06-09

一、PDOStatement::columnCount() 是什么？

PDOStatement::columnCount() 是 PDOStatement 对象中的一个方法，它返回与结果集中的列数相关的整数值。其原型如下：

public PDOStatement::columnCount(): int

当你执行一条 SQL 查询之后（尤其是 SELECT 语句），你可以调用此方法来获取结果集中包含多少列。

二、基本使用方法

来看一个最简单的使用示例：

<?php
$pdo = new PDO('mysql:host=localhost;dbname=test', 'user', 'password');
$stmt = $pdo->query('SELECT id, name, email FROM users');

$columnCount = $stmt->columnCount();

echo "列数为: " . $columnCount;
?>

上述代码执行完后将输出：

列数为: 3

这说明查询结果中包含了三个字段：id、name 和 email。

三、注意事项：必须执行查询后才能获取列数

一个常见的误区是尝试在查询未执行或执行非结果集查询（如 INSERT、UPDATE、DELETE）后调用 columnCount()。这是不正确的做法：

<?php
$stmt = $pdo->prepare('SELECT id, name FROM users WHERE id = :id');
// 未执行 -> columnCount 可能返回 0 或错误的值
echo $stmt->columnCount(); // 通常是 0
?>

为确保返回值准确，应始终在执行查询并获得结果集之后调用：

$stmt->execute([':id' => 1]);
echo $stmt->columnCount(); // 正确返回列数

四、columnCount() 的典型应用场景

1. 动态构建表格标题

假设你正在构建一个通用的数据库表浏览器工具，你需要根据查询结果动态生成 HTML 表格的标题行。可以使用 columnCount() 与 getColumnMeta() 搭配完成：

<?php
$stmt = $pdo->query('SELECT * FROM users');
$colCount = $stmt->columnCount();

echo "<table border='1'><tr>";
for ($i = 0; $i < $colCount; $i++) {
    $meta = $stmt->getColumnMeta($i);
    echo "<th>" . htmlspecialchars($meta['name']) . "</th>";
}
echo "</tr>";
?>

这将自动生成一个与查询结果对应的表头。

五、对比 rowCount() 和 columnCount()

很多初学者会混淆 rowCount() 和 columnCount()。二者的区别如下：

columnCount()：获取查询结果中的列数。
rowCount()：获取受影响的行数，但在 SELECT 查询中并非总是可靠。

若要获取 SELECT 查询返回的行数，应该使用 fetchAll() 或遍历结果集计数。

六、关于不同数据库的兼容性

columnCount() 的行为在各类数据库中基本一致，但某些驱动（如旧版的 SQLite 或某些 ODBC 驱动）可能会在执行前返回 0。因此，为获得准确值，应遵循以下规则：

确保执行过 execute() 或 query()；
使用支持元数据的驱动；
不要在无结果集的语句中调用此方法。

七、处理 REST API 输出字段信息

如果你在开发一个 REST API，希望返回每条记录的字段信息，可利用 columnCount() 自动生成字段列表，例如：

<?php
$stmt = $pdo->query('SELECT * FROM users');
$columns = [];
for ($i = 0; $i < $stmt->columnCount(); $i++) {
    $meta = $stmt->getColumnMeta($i);
    $columns[] = $meta['name'];
}

header('Content-Type: application/json');
echo json_encode([
    'columns' => $columns,
    'data' => $stmt->fetchAll(PDO::FETCH_ASSOC)
]);
?>

这在构建类似 https://gitbox.net/api/v1/table/users 这样的接口时尤为方便。