XTDB HTTP服务JSON查询格式变更解析

XTDB作为新一代的时序数据库，其2.x版本在HTTP服务接口上进行了多项优化和改进。近期用户在使用HTTP接口进行SQL查询时遇到了JSON解码错误的问题，这实际上反映了XTDB在接口设计上的一个重要变更。

问题现象分析

当用户通过Docker启动XTDB 2.x预发布版本后，尝试使用HTTP接口执行SQL查询时，系统返回了"Error decoding JSON"的错误信息。从错误日志中可以清晰地看到，系统无法识别请求体中的"query"字段，提示"Encountered an unknown key 'query'"。

技术背景

XTDB 2.x版本对HTTP接口进行了重构，特别是在查询请求的JSON格式上做了简化。在之前的版本中，SQL查询请求需要包裹在"query"字段中，格式如下：

{
  "query": {
    "sql": "SELECT * FROM docs"
  }
}

但在2.x版本中，XTDB团队优化了接口设计，使SQL查询可以直接放在顶层，不再需要额外的"query"包装层。新的正确格式应该是：

{
  "sql": "SELECT * FROM docs"
}

解决方案

对于遇到此问题的开发者，解决方案很简单：只需移除JSON中的"query"包装层，直接将SQL语句放在请求体顶层即可。例如：

curl -v --header "Content-Type: application/json" \
  --data '{"sql": "SELECT * FROM docs"}' \
  -XPOST http://localhost:6543/query

设计考量

这种变更体现了XTDB团队对API简洁性的追求。通过减少不必要的嵌套层级，使得接口更加直观和易于使用。同时，这也符合REST API设计的最佳实践，即保持请求体的扁平化结构。

兼容性建议

对于正在从旧版本迁移到XTDB 2.x的用户，需要注意这一变更可能会影响现有的客户端代码。建议在升级前：

1. 检查所有使用HTTP查询接口的代码
2. 更新请求体构造逻辑，移除"query"包装
3. 更新相关文档和测试用例

总结

XTDB 2.x在接口设计上的这一改进，虽然带来了短暂的兼容性问题，但从长远来看提高了API的易用性和可维护性。开发者在使用新版本时，应当注意查阅最新的接口文档，了解这些优化变更，以便更好地利用XTDB的强大功能。