Postgres.js 中 JSONB 数组插入问题的解析与解决方案

Postgres.js 是一个流行的 Node.js PostgreSQL 客户端库，在使用过程中，开发者可能会遇到 JSONB 数组类型数据插入时出现转义字符串的问题。本文将深入分析这一现象的原因，并提供正确的解决方案。

问题现象

当开发者尝试向 PostgreSQL 数据库中插入包含 JSONB 数组类型的记录时，发现数组中的 JSON 对象被转义为字符串形式存储。例如：

const record = {
  status: "INACTIVE",
  items: [
    { market: "m1", outcome: false },
    { market: "m2", outcome: true }
  ]
};

实际插入数据库后，items 字段的值变为：

{"{\"market\": \"m1\", \"outcome\": false}","{\"market\": \"m2\", \"outcome\": true}"}

问题原因

这种现象的根本原因在于 Postgres.js 对 JSON 数据的处理机制。Postgres.js 会自动对传入的数据进行 JSON 序列化，但当开发者直接传递一个包含 JSON 数据的数组时，库无法区分这是否是一个需要特殊处理的 JSONB 数组字段。

PostgreSQL 的 JSONB 类型要求数据以特定的二进制格式存储，而 Postgres.js 需要明确的指示来处理这种类型的数据。

解决方案

正确的做法是明确指定 JSONB 数组字段的类型。Postgres.js 提供了类型提示功能，可以通过以下方式解决：

await sql`INSERT INTO foobar ${sql(record, { items: 'jsonb[]' })}`

或者，如果整个记录都包含 JSON 数据，可以使用更简洁的方式：

await sql`INSERT INTO foobar ${sql({ record }, 'record')}`

深入理解

Postgres.js 的设计哲学是尽可能保持简单直接。它自动处理大多数常见的数据类型转换，但对于 JSONB 这种特殊类型，需要开发者明确指定：

1. 自动序列化：Postgres.js 会自动对 JavaScript 对象进行 JSON 序列化
2. 类型提示：通过第二个参数提供类型信息，指导库如何处理特定字段
3. 避免双重转义：直接传递字符串化的 JSON 会导致双重转义问题

最佳实践

1. 始终为 JSONB 类型字段提供明确的类型提示
2. 避免手动对数据进行 JSON.stringify 处理
3. 对于复杂的嵌套结构，考虑使用 Postgres.js 的类型系统
4. 在定义表结构时，明确指定 JSONB 和 JSONB[] 类型的区别

总结

Postgres.js 提供了强大而灵活的数据类型处理能力，但需要开发者理解其工作原理。通过正确使用类型提示，可以确保 JSONB 数组数据按预期方式存储，避免转义字符串问题。这种设计既保持了库的简洁性，又提供了处理复杂数据类型的能力。