Manticore Search 中 HTTP 响应字段 _id 到 id 的标准化改造

在 Manticore Search 7.0.1 版本中，开发团队对 HTTP API 响应中的文档标识符字段进行了重要调整。本文将详细介绍这一变更的技术背景、实施过程以及需要注意的兼容性问题。

变更背景

在数据库系统中，文档标识符是核心概念之一。Manticore Search 原先在多个 HTTP 端点（包括 insert、update、replace 和 delete）的响应中使用 _id 字段来表示文档标识符。这种命名方式虽然常见，但在某些客户端自动生成代码的场景下可能引发问题。

主要变更内容

开发团队决定将响应中的 _id 字段统一改为 id，这一变更主要基于以下考虑：

1. 提高 API 一致性：统一字段命名规范，减少开发者认知负担
2. 客户端兼容性：避免某些自动生成客户端代码时的命名冲突问题
3. 标准化：遵循更通用的 REST API 设计惯例

实施细节

变更涉及以下核心端点：

• /insert
• /update
• /replace
• /delete

这些端点的响应格式从原来的：

{
  "_id": 123,
  "status": "success"
}

变更为：

{
  "id": 123,
  "status": "success"
}

兼容性处理

值得注意的是，团队对 Elasticsearch 兼容端点（/_doc 和 /_create）做了特殊处理。虽然内部实现也改为使用 id，但为了保持与 Elasticsearch API 的兼容性，这些端点的响应仍然返回 _id 字段。这种设计体现了团队在标准化和兼容性之间的平衡考量。

影响范围

这一变更属于破坏性变更（breaking change），意味着：

1. 所有直接解析响应中 _id 字段的客户端代码都需要相应调整
2. 二进制 API 协议版本也随之更新
3. 相关客户端库（如 Go 客户端）需要同步更新

最佳实践建议

对于使用 Manticore Search 的开发人员，建议：

1. 检查现有代码中对响应字段的解析逻辑
2. 更新到最新版本的客户端库
3. 对于同时使用标准端点和 Elasticsearch 兼容端点的应用，注意区分两种响应格式

这一变更虽然带来短期适配成本，但从长期来看将提高 API 的一致性和可维护性，为开发者提供更好的使用体验。