索引 mapping 与代码对不上：一次不报错的静默失效排查
主题：代码与线上不一致的静默失效
先说结论
同一份东西有两个"事实来源" （代码里的期望 vs 线上实际），谁都不自动对齐 ------ 而它 不报错、不自愈，只在你走到某条特定路径时才暴露。
这类问题最可怕的地方是"能跑 "：功能看着正常，只是结果一直是错的。
定位它靠的不是读代码，而是三个决定性实验：
bash
① _analyze → 看分词对不对（确定性实验，重建成不成功它骗不了人）
② term vs match / term vs .keyword → 区分"是数据问题"还是"查询打错了字段形态"
③ _cat/plugins → 排除"最坏情况"（插件其实好好的，所以敢动手重建）一、问题：三个"看着像没数据"的症状
| 期望（代码里写的 mapping） | 线上实际 | 后果 |
|---|---|---|
dynamic: false |
未设置 → 默认 true |
字段类型由首个写入值决定，随时可能变 |
| 4 个文本字段用中文分词器 | 全是普通 text |
分词器根本没生效 |
品牌 / 分类 / 标签 是 keyword |
全是 text |
→ 品牌过滤恒 0 命中 |
补全字段是 completion |
text |
→ 补全接口恒返回空（异常被吞掉） |
向量字段 dense_vector(1024, cosine) |
完全没有该字段 | → 向量检索功能一开就废（还没到开的时机，所以没暴露） |
三个症状的共同特征：都表现为"没有数据"或"返回空"，而不是报错。
为什么不自愈 ：索引初始化器只在索引不存在时才创建 （if (exists) return），启动日志还老老实实打一行"索引已存在" ------ 这份漂移永远不会被自动修复。
二、排查：先备份现场，再上三个决定性实验
第一步是留证（事后能比对，出问题能说清"改了什么"）：
bash
curl -s localhost:9200/products_ai/_mapping > /tmp/mapping-before.json
curl -s localhost:9200/products_ai/_settings >> /tmp/mapping-before.json
curl -s localhost:9200/products_ai/_count | tee /tmp/count-before.txt实验 ①：分词到底是哪一套
bash
curl -s localhost:9200/products_ai/_analyze -H 'Content-Type: application/json' \
-d '{"field":"name","text":"小米手机"}'
# 结果：切出 4 个"单字" → 说明走的是默认分词器，中文分词器没生效实验 ②：是数据问题还是查询问题（这一步最有价值）
bash
term brandName="小米" → 0 命中
term brandName.keyword="小米" → 4 命中
match brandName="小米" → 4 命中⇒ 数据没问题，是查询打错了字段形态 ：term 查询不做分词 ，打在 text 字段上就永远匹配不到。这是"最强的证据形态"。
实验 ③：排除最坏情况
bash
curl -s localhost:9200/_cat/plugins
# → 中文分词插件已加载；显式指定该分词器时，切词正确（小米 / 手机）⇒ 原方案里"万一分词插件不可用"这个失败预案被实测排除 ，所以敢删索引重建。
顺带反推"是谁创建的" ：线上 settings 与代码期望一致，但 mapping 全空 ⇒ 说明当年那次创建带了 settings、没带 mappings （某个历史版本），而不是搜索引擎自动创建（自动创建时副本数会是默认值 1）。具体版本无法查明。
三、修复与验收
bash
docker compose stop <AI 服务> # ① 先停服务，避免"索引已删、服务还在查"的报错窗口
curl -X DELETE localhost:9200/products_ai # ② 删索引（向量字段维度建成后不可改 → 只能删了重建）
docker compose up -d <AI 服务> # ③ 重建 + 启动全量同步
# ★ 必须等启动完成：日志出现 "Started ...Application in" 才算起来（别靠固定 sleep）
# ★ 再看一行 "启动自动同步完成，共 N 条商品"| 验收项 | 修前 | 修后（实测） |
|---|---|---|
dynamic |
未设置（= true） | false |
| 4 个文本字段分词 | 4 个单字 | 小米 / 手机 正确成词 |
| 品牌/分类/标签 | text |
keyword |
| 向量字段 | 不存在 | dense_vector dims=1024 similarity=cosine |
| 补全字段 | text |
completion + 中文分词 |
term brandName="小米" |
0 | 4 |
| 补全接口 | 恒空 | prefix=小米 → 返回"小米 14" |
四、⭐ 更深一层：修 A 会牵动 B
重建后，品牌 / 分类 / 标签从 text 变成 keyword，而"多字段匹配查询"正包含这三个字段 → 从"部分匹配"变成"整值精确匹配"：
- 好处 ：品牌过滤（原本恒 0）开始生效；
- 风险 ：查询串若是"小米手机"，
keyword字段里的"小米"不再命中 → 召回可能变少； - ⇒ 重建后必须跟一次召回回归（对若干典型问题看结果集变化）。
本次实测未发生退化 （各关键词召回量正常），原因也值得记：语义文本字段里本身就写着"品牌：小米 | 分类：手机 | 标签：..."，品牌/分类的召回由它兜住了。
通用教训 ：修复"索引/契约不一致"时，修复清单里必须自带回归项 ------ 因为你改的是排序与召回的语义，不是改一行代码那么简单。
五、⭐ 另一种形态：同一字段两种含义
同一个排查里还挖出第二类"静默失效"------一个字段被两处代码赋予了两种含义：
- 秒杀商品记录里的
spu_id存的是秒杀侧自己的主键（前台详情、限购判断按它查）； - 而预热任务用的是商品侧的商品 id；
- 二者只在"碰巧相等"时 一致 → 存量数据里 4/12 个组合是错位的 ，4 个秒杀商品从来没有被预热过 ，靠凌晨对账任务写的永久缓存 key 偶然兜住了。
为什么难发现 ：① "能下单"（永久 key 兜住了）；② 只在新增/换批 时暴露；③ 用后台接口新增必然踩 ------ 后台会给记录生成雪花 id，于是 id ≠ spu_id → 预热永不命中。
记下来的硬约束 ：新增秒杀数据必须满足 "秒杀主键 = 秒杀 SKU 引用的商品 id = 商品表主键" 三值相等。
附带结论（很实用） ：想用 redis-cli 手工补线上 key，必须先确认它是模板写的 还是序列化写的：
| key 类型 | 能否手工写 | 原因 |
|---|---|---|
| 库存 key | ✅ 能 | 值是纯数字字符串 ，SET 兼容 |
| 随机码 key | ❌ 不能 | 值是 JDK 序列化的对象，手工写格式对不上 |
| 布隆/集合类 key | ❌ 不能 | 是 SET，成员也是序列化的字符串 |
六、踩坑清单
| 认知 / 坑 | 说明 |
|---|---|
| 🔑 "能跑" ≠ "对" | 三个症状全都"看着像没数据"：有兜底路径、接口没人用、靠永久 key 撑着 |
🔑 term vs term .keyword vs match 是分类神器 |
一次实验就能区分"数据问题"和"查询打错字段形态" |
| 🔑 先排除最坏情况再动手 | 用 _cat/plugins 确认插件可用，否则不敢删索引重建 |
| 🔑 反推"是谁创建的" | 看 creation_date 与 settings/mapping 是否自相矛盾 |
| ⚠️ 改 mapping 会改召回语义 | 部分匹配 → 整值匹配，必须跟回归 |
| ⚠️ 初始化逻辑"只创建不校验"= 漂移的水库 | if (exists) return ⇒ 必须有定期核对机制，别等报错 |
| ⚠️ 同一字段两种含义是设计债 | "三值相等"只是绕过去，不是修复；要不要修按纪律单独排期、不夹带 |
| ⚠️ 验收命令本身也要被验收 | 我用 grep -c 数单行 JSON，永远只返回 0/1，期望值写"4"是错的（实际出现 5 次）------ 所幸关键那条 _analyze 是确定性的，没被误导 |
七、一句总结
"不报错、不自愈、只在特定路径暴露"的问题，只能靠定期核对机制发现 ------ 而定位它的钥匙，是选对那几个"决定性实验"。
本文基于一个个人微服务电商演示项目的真实实施记录整理，涉及的环境信息已做脱敏处理。