4. 索引命名与数据契约设计

跨团队共享数据时，真正容易出问题的往往不是查询语法，而是“名字对不上、字段含义不一致、版本悄悄变了”。索引命名与数据契约，就是把口头约定固化成可校验、可演进的规则。本节围绕四个可落地的约定展开：索引命名、字段映射、版本管理、生命周期。

一、索引命名：让名字自带语义

共享索引的命名应能回答三个问题：谁的数据、什么内容、哪个版本。推荐采用“域-实体-环境-版本”的分段结构，用连字符分隔，全部小写，避免大写与下划线混用。例如：

order-center-orders-prod-v2
order-center-orders-staging-v2
user-profile-events-prod-v1

其中 order-center 是数据域（团队/系统），orders 是实体，prod 是环境，v2 是契约版本。别名（alias）是共享的关键：消费方只读别名 order-center-orders，写入方通过别名切换指向具体版本索引。这样版本升级时消费方无需改代码。命名中禁止出现日期作为唯一区分（如 orders-20240601），日期应交给索引生命周期管理（ILM）的滚动策略处理，而不是写进契约名。

二、字段映射：契约的核心是类型与语义

字段映射不只是 text 还是 keyword，更要约定字段的业务含义、是否可空、单位与枚举值。共享契约应明确：字段名、类型、是否必填、示例值、枚举范围。例如订单共享契约中，order_id 为 keyword 且必填，amount 为 scaled_float 且单位为“分”，status 为 keyword 且枚举为 created/paid/shipped/closed。类型一旦确定，禁止在同一版本内变更，因为 Elasticsearch 不允许对已有字段改类型，只能通过新版本索引重建。

三、版本管理：用别名做无感切换

版本号放在索引名末尾，别名指向当前版本。升级流程为：创建 v2 索引并写入新映射 → 双写或回填数据 → 校验文档数与抽样字段 → 将别名从 v1 原子切换到 v2。切换命令示例：

POST /_aliases
{
  "actions": [
    { "remove": { "index": "order-center-orders-prod-v1", "alias": "order-center-orders" } },
    { "add":    { "index": "order-center-orders-prod-v2", "alias": "order-center-orders" } }
  ]
}

版本号递增规则：新增可选字段为次版本（v1→v1.1 可仍用同一索引，因 ES 支持动态新增字段）；删除字段、改类型、改语义为主版本（v1→v2，必须新索引）。契约文档中要写明每个版本的变更点与兼容性说明。

四、生命周期：数据从热到冷的约定

共享数据必须约定保留多久、何时降冷、何时删除。用 ILM 策略绑定索引模板，例如热阶段 7 天、温阶段 30 天、冷阶段 90 天、之后删除。消费方需知道：超过 90 天的数据不可查，因此对账类查询要限定时间范围。生命周期策略也应写入契约，避免消费方误以为数据永久可用。

五、契约文档示例

把上述约定写成一份可交付的契约文档，字段与规则如下表所示，团队可直接复制填写。

落地时建议把契约文档纳入代码仓库，与索引模板、ILM 策略一起版本化。每次变更走评审，消费方确认兼容性后再切换别名。这样跨团队共享就从“靠记忆和口头约定”变成“靠契约和自动化校验”，协作成本显著降低。