pg-promise 中使用 `$1:list` 或 `${values:list}` 语法可安全、高效地将 javascript 数组展开为 sql 的 `in` 子句，但必须注意参数传递方式：需将数组**包装为单元素数组**或使用**命名参数对象**，否则仅首项生效。
在使用 PG-Promise 执行 SELECT ... WHERE column IN (...) 类型查询时，直接传入数组却只返回单条结果，是初学者最常见的误区之一。根本原因在于 PG-Promise 对参数数组的解析逻辑：当你传入 db.any(query, values)（其中 values 是一个字符串数组），PG-Promise 会将该数组视为「按位置映射 $1, $2, $3...」的参数列表，而非「一个待展开的集合」。因此，$1:list 实际只取 values[0]（即第一个字符串），导致 IN ('WH12345678') ——自然只匹配一条记录。
✅ 正确做法有两种，均能生成安全、防注入的 IN 表达式：
方法一：位置参数 + 单元素数组包装
将原始数组作为唯一元素放入新数组中，使 $1 指向整个数组：
const values = ["WH12345678", "WH22345678"]; const query = "SELECT * FROM pups WHERE workorder IN ($1:list)"; db.any(query, [values]) // 注意：这里是 [values]，不是 values .then(data => console.log(data)) .catch(err => console.error(err));
方法二：命名参数（更清晰、易维护）
利用模板字符串语法 ${name:list}，配合对象参数：
const values = ["WH12345678", "WH22345678"];
const query = "SELECT * FROM pups WHERE workorder IN (${values:list})";
db.any(query, { values }) // 传入对象，键名需与模板中一致
.then(data => console.log(data))
.catch(err => console.error(err));? 关键说明：
- :list 是 PG-Promise 内置的数组扩展格式化器，会自动为每个元素添加单引号并逗号分隔（如 'WH12345678','WH22345678'），且全程转义，杜绝 SQL 注入；
- 不要混用 $1:csv —— :csv 用于无引号的纯值列表（如数字 ID），而文本类型字段（如 workorder）必须用 :list 保证引号包裹；
- 错误写法 db.any(query, values)（未包装）会导致 $1 取数组首项，$2 取第二项……但查询中无 $2，故被忽略；
- 空数组 [] 会被 :list 安全处理为 NULL IS NOT NULL（即恒假），避免语法错误，建议业务层提前校验非空。
? 总结：始终记住——要展开数组，就必须让 PG-Promise 明确“这是一个待展开的集合”，而不是“一堆独立参数”。选择 [values] 或 {values} 任一方式，即可写出简洁、健壮、符合最佳实践的批量查询。
