Better-SQLite3 中 JSON 函数处理整数类型的问题解析

问题现象

在使用 Better-SQLite3 库时，开发者发现当通过 JSON 相关函数（如 json_object 或 json_set）绑定整数参数时，输出结果会将整数转换为浮点数形式。例如，传入数字 1 会输出 1.0 而非预期的 1。

技术背景

这个现象的根本原因在于 JavaScript 和 SQLite 之间的类型系统差异：

1. JavaScript 的数字类型：JavaScript 使用 IEEE 754 双精度浮点数表示所有数字，没有真正的整数类型。即使开发者写的是 1，在底层也是以浮点数形式存储。

2. SQLite 的绑定机制：Better-SQLite3 在将 JavaScript 值绑定到 SQL 语句时，所有数字类型都会通过 sqlite3_bind_double 绑定为 REAL 类型。

3. JSON 序列化行为：SQLite 的 JSON 函数在序列化时会保留数值的原始表示形式。当 REAL 类型的 1.0 被序列化为 JSON 时，会保持 1.0 的形式。

解决方案

开发者可以采用以下几种方式来解决这个问题：

1. 使用 CAST 显式转换

在 SQL 查询中明确将参数转换为整数类型：

db.prepare(`SELECT json_object('timestamp', CAST(? AS INT))`).get(1)

2. 使用 BigInt 类型

JavaScript 的 BigInt 可以表示真正的整数：

db.prepare(`SELECT json_object('timestamp', ?)`).get(BigInt(1))

3. 预序列化 JSON 字符串

直接传入已序列化的 JSON 字符串：

db.prepare(`SELECT json(?)`).get(JSON.stringify({ timestamp: 1 }))

深入理解

这个现象实际上反映了在不同系统间进行数据交换时的类型转换挑战。虽然 JavaScript 开发者可能认为 1 是一个整数，但在底层它始终是双精度浮点数。SQLite 的 JSON 函数在序列化时会忠实反映这一类型信息。

对于需要精确整数表示的应用场景（如时间戳、ID 等），开发者应当特别注意这种隐式类型转换，并选择适当的解决方案来确保数据的一致性。

最佳实践建议

1. 对于需要严格整数表示的字段，建议在 SQL 查询中显式使用 CAST
2. 考虑在应用层进行 JSON 序列化，而不是依赖数据库的 JSON 函数
3. 文档化所有涉及数字类型的接口，明确预期行为
4. 在测试中特别验证数字类型的序列化行为

理解这些底层机制有助于开发者写出更健壮、可预测的代码，避免在数据持久化和序列化过程中出现意外的类型转换问题。