Node-Postgres 查询结果类型解析：避免多语句查询导致的类型问题

在使用 Node.js 连接 PostgreSQL 数据库时，node-postgres 是一个非常流行的选择。然而，开发者在实际使用过程中可能会遇到一些类型系统相关的困惑，特别是在处理查询结果时。

查询结果类型的基本理解

根据 node-postgres 的官方文档，result.rows 的类型应该是 any[]，即一个包含任意类型元素的数组。每个元素代表查询结果中的一行数据，通常是一个对象，其属性对应数据库表的列名。

例如，执行简单的计数查询：

const result = await pool.query('SELECT COUNT(*) FROM users');
const count = parseInt(result.rows[0].count);

这种用法是完全正确的，类型系统也会如预期工作。

多语句查询的特殊情况

问题出现在当查询字符串中包含分号(;)时。分号在 SQL 中是语句分隔符，node-postgres 会将其解释为多语句查询。这种情况下，返回的结果结构会发生变化：

1. 对于单语句查询，rows 是 any[] 类型
2. 对于多语句查询，rows 变成了 any[][] 类型，即数组的数组

这就是为什么在查询字符串末尾添加分号会导致类型检查器报错的原因。虽然查询能够执行，但类型系统无法正确推断结果结构。

最佳实践建议

1. 避免不必要的分号：在单语句查询中，不需要在末尾添加分号。这是许多 SQL 客户端工具的习惯，但在编程接口中通常不需要。

2. 明确类型声明：如果确实需要处理多语句查询，应该明确声明类型：

// 单语句查询
const singleResult = await pool.query<{count: string}>('SELECT COUNT(*) FROM users');

// 多语句查询
const multiResult = await pool.query<[{count: string}, ...any[]]>('SELECT COUNT(*) FROM users; SELECT * FROM orders LIMIT 1');

3. 使用行提取辅助函数：创建类型安全的辅助函数来处理查询结果：

function getFirstRow<T>(result: QueryResult<T>): T | undefined {
  return result.rows[0];
}

const count = parseInt(getFirstRow(await pool.query('SELECT COUNT(*) FROM users'))?.count || '0');

类型系统的深层理解

node-postgres 的类型系统设计反映了 SQL 查询的实际情况。多语句查询确实会返回多个结果集，因此类型为 any[][] 是合理的。开发者需要理解这种映射关系，才能写出类型安全的数据库访问代码。

在 JavaScript 项目中，即使不使用 TypeScript，通过 JSDoc 注释也能获得类似的类型安全：

/**
 * @typedef {Object} CountResult
 * @property {string} count
 */

/** @type {Promise<import('pg').QueryResult<CountResult>>} */
const result = pool.query('SELECT COUNT(*) FROM users');

理解 node-postgres 的类型系统行为，能够帮助开发者写出更健壮、更易维护的数据库访问代码，避免潜在的类型相关错误。