企业官网建设流程全解析

1. 为什么“只取需要的字段”是ES查询优化的第一课

刚接触 Elasticsearch 那会儿，我习惯性地用GET index/_search一把梭，返回什么就接什么。直到有一次线上接口响应时间从 80ms 飙到 1.2s，排查半天才发现：一个存了商品详情、评论快照、日志上下文的大文档，每次查询都把整条_source拉回来，网络传输和 JSON 反序列化把服务端和客户端两头都拖垮了。后来把返回字段从几十个砍到 6 个，P99 直接掉回 90ms 以内。这件事让我彻底明白一个道理——在 Elasticsearch 里，控制返回字段不是“锦上添花”，而是查询性能优化的基本功。

所谓“查询返回指定的 Elasticsearch 文档字段”，说白了就是：我发起一次搜索或文档读取请求，但只想要文档里的某几个字段，而不是整条_source全量返回。它解决的核心问题是减少不必要的数据传输、降低序列化开销、控制敏感字段外泄。这个能力在三种场景下尤其关键：一是宽表型索引（一个文档上百个字段，业务只关心其中几个）；二是大字段索引（文档里塞了长文本、base64 图片、嵌套对象）；三是对外提供 API 时，需要屏蔽内部字段（比如成本价、内部标记、审计信息）。

适合谁来参考这篇内容？我的判断是：只要你在用 ES 做查询，不管是通过 REST API、Java 客户端、Python 客户端还是其他语言封装，都应该掌握字段过滤的几种写法。新手可以把它当成必学清单，老手可以对照检查自己有没有踩过“全量返回”的坑。下面我会从设计思路、核心语法、实操过程到排查技巧，把这件事讲透。

2. 字段过滤的整体设计与方案选型

2.1 三种过滤手段的定位差异

很多人以为“指定返回字段”只有一种写法，其实 ES 提供了至少三种不同层次的过滤手段，它们作用的位置和效果完全不同，选错了要么没效果，要么性能反而更差。

第一种是_source过滤，也就是在查询体里用"_source": ["field1", "field2"]或"_source": {"includes": [...], "excludes": [...]}。它作用在文档存储层，ES 在读取文档时只解析并返回你指定的字段。这是最常用、最直观的方式，也是本文的重点。

第二种是stored_fields，它读取的是 mapping 中显式设置"store": true的字段。默认情况下 ES 的字段是不单独存储的，只存在_source里，所以stored_fields只有在建索引时特意配置过才有意义。它的优势是读取路径更短，但灵活性差，改字段要重建索引。

第三种是docvalue_fields，它读取的是列式存储的 doc values，主要用于排序和聚合场景。它返回的是字段的 doc values 值，格式和_source里的原始 JSON 可能不一致（比如日期会变成时间戳），一般不用来替代_source过滤。

我的经验是：90% 的场景用_source过滤就够了，stored_fields只在极端性能敏感且字段固定的场景才考虑，docvalue_fields基本是聚合调试时才用。下面重点讲_source过滤。

2.2 为什么_source过滤能省资源

要理解它为什么快，得先知道 ES 存文档的结构。ES 底层用 Lucene，文档写入时，原始 JSON 会被完整存成_source字段（本质是一个二进制大字段），同时各个字段被索引成倒排索引。查询命中后，ES 需要把_source读出来，解析成 JSON 返回。

如果你不指定字段，ES 会把整个_source读出来、完整解析、完整序列化返回。而指定了_source过滤后，ES 在解析阶段就只提取你需要的字段，跳过了无关字段的解析和序列化。对于宽文档，这个差距非常明显。我实测过一个 200+ 字段、单文档约 40KB 的索引，只取 5 个字段时，响应体从 40KB 降到 1.2KB，服务端 CPU 在解析环节的占用下降约 60%。

注意：_source过滤减少的是解析和传输开销，但磁盘上读取_source二进制的 IO 并没有减少（因为整个_source是作为一个整体存储的）。所以它对“磁盘 IO 瓶颈”帮助有限，对“网络和 CPU 瓶颈”帮助巨大。这一点很多人搞混，以为指定字段就能少读磁盘，其实不是。

2.3 方案选型的决策逻辑

我在实际项目里总结了一个简单的决策流程：先问“这个字段需要建索引时单独存储吗”，如果不需要，直接上_source过滤；如果这个字段超大且查询频率极高、又不需要原始 JSON 格式，才考虑store: true+stored_fields。至于docvalue_fields，除非我在做聚合结果核对，否则不碰。

还有一个容易忽略的点：过滤字段的列表最好由业务层统一维护，而不是散落在各个查询里。我见过一个项目，同一个索引在不同接口里返回字段各不相同，后来加了一个敏感字段，结果漏改了一个接口导致数据外泄。后来我们改成在配置中心维护“字段白名单”，所有查询从白名单取字段，才算根治。

3. 核心语法与实操要点拆解

3.1_source的四种写法与适用场景

_source过滤的写法比想象中灵活，我把它归纳成四种，每种都有明确的适用场景。

第一种：数组简写。最常用的形式，直接列出要返回的字段：

GET /products/_search { "query": { "match": { "title": "无线耳机" } }, "_source": ["title", "price", "stock"] }

这种写法适合字段少、固定的场景。缺点是只能“包含”，不能“排除”。

第二种：includes/excludes 对象写法。当字段很多、只想排除少数几个时，这种写法更省事：

GET /products/_search { "query": { "match_all": {} }, "_source": { "includes": ["title", "price", "specs.*"], "excludes": ["specs.internal_code", "cost_price"] } }

注意specs.*这种通配符，它能匹配嵌套对象下的所有子字段。这个特性在处理动态 mapping 的嵌套结构时特别好用，因为嵌套字段名可能不固定。

第三种：通配符模式。上面已经用到，单独强调一下：*匹配任意字符，?匹配单个字符。比如"user.*"能取到user.name、user.age等所有子字段。但通配符有性能代价，ES 需要遍历字段名做匹配，字段特别多时会有额外开销，能明确列出就别用通配符。

第四种：完全禁用_source。设置"_source": false，返回结果里就没有_source字段了。这种一般配合stored_fields或docvalue_fields使用，或者你只关心_id和命中数量。我一般只在“只统计数量、不需要文档内容”的场景才这么干。

3.2 嵌套字段与对象字段的过滤陷阱

这是踩坑重灾区。假设文档结构是这样的：

{ "order_id": "A001", "customer": { "name": "张三", "phone": "138****", "address": { "city": "杭州", "detail": "某街道" } } }

如果你想只返回customer.name，写"_source": ["customer.name"]行不行？行，但返回结构会变。ES 会返回{"customer": {"name": "张三"}}，而不是扁平的{"customer.name": "张三"}。这个结构变化如果客户端没处理好，很容易解析报错。

更麻烦的是nested类型字段。如果customer是nested类型，_source过滤依然能工作，但要注意：_source过滤是在文档级别生效的，它不会因为你的 query 只命中了某个 nested 子对象就只返回那个子对象。也就是说，如果文档里有 5 个 nested 子对象，你过滤了字段，返回的仍是全部 5 个子对象里你指定的字段。想只返回命中的那个 nested 对象，得用inner_hits，这是另一个话题了。

实操心得：涉及嵌套结构时，我建议先在测试环境用一条真实文档验证返回结构，确认客户端解析逻辑能兼容，再上生产。我吃过一次亏，客户端按扁平 key 取值，结果 ES 返回嵌套结构，直接空指针。

3.3 字段过滤与_source元数据的取舍

有个细节值得单独说：_source过滤不影响_id、_index、_score这些元字段，它们始终返回（除非你显式关闭）。但如果你用了"_source": false，又想拿_id，没问题，_id在元数据里，照样返回。

另外，ES 7.x 之后支持在 mapping 里设置"_source": {"enabled": false}，整个索引都不存_source。这种索引查询极快、极省空间，但代价是你无法再用_source过滤取字段，只能用stored_fields。所以除非你非常确定字段固定且不需要更新，否则别轻易关_source。我一般只在纯日志、只追加不更新的场景才考虑。

4. 完整实操过程与关键环节实现

4.1 环境准备与测试数据构造

为了让你能直接复现，我先给一套完整的测试流程。假设你已经有一个可访问的 ES 实例（本地或测试集群均可），版本 7.x 或 8.x 都适用。

先建一个测试索引，故意设计成宽文档，方便观察过滤效果：

PUT /demo_products { "mappings": { "properties": { "title": { "type": "text" }, "price": { "type": "double" }, "stock": { "type": "integer" }, "cost_price": { "type": "double" }, "internal_code": { "type": "keyword" }, "description": { "type": "text" }, "specs": { "properties": { "color": { "type": "keyword" }, "weight": { "type": "double" }, "internal_note": { "type": "text" } } } } } }

然后插入一条文档：

POST /demo_products/_doc/1 { "title": "无线蓝牙耳机", "price": 299.0, "stock": 1200, "cost_price": 85.0, "internal_code": "SKU-INTERNAL-001", "description": "这是一段很长的商品描述，实际生产中可能有几千字……", "specs": { "color": "黑色", "weight": 45.5, "internal_note": "供应商内部备注，不应对外" } }

4.2 对比实验：全量返回 vs 字段过滤

先跑一次全量查询，观察返回体大小：

GET /demo_products/_search { "query": { "match": { "title": "耳机" } } }

返回里_source包含全部 7 个顶层字段加嵌套的specs。你可以用curl -w "%{size_download}"或者浏览器开发者工具看响应体大小。

再跑一次字段过滤：

GET /demo_products/_search { "query": { "match": { "title": "耳机" } }, "_source": ["title", "price", "stock"] }

返回的_source只剩三个字段。在字段少的时候差距不明显，但你可以把description换成几 KB 的长文本，再插入 100 条文档，用size: 100查询对比，响应体大小差距会非常直观。我实测过一个类似结构，100 条文档全量返回约 2.3MB，过滤后约 180KB，差了 12 倍。

4.3 排除敏感字段的实战写法

生产环境更常见的需求是“排除”而非“包含”。比如对外 API 必须屏蔽cost_price和internal_code，同时specs.internal_note也不能出现。写法如下：

GET /demo_products/_search { "query": { "match_all": {} }, "_source": { "excludes": ["cost_price", "internal_code", "specs.internal_note"] } }

这种“黑名单”式写法在字段多、敏感字段少的时候最省心。但它的风险是：新增敏感字段时容易漏加。所以我的做法是双保险——既在查询层用 excludes，又在索引层把真正敏感的字段单独放到一个不对外暴露的索引或字段前缀下，从源头隔离。

4.4 在客户端代码里落地字段过滤

REST API 只是验证手段，真正落地要在客户端代码里。以 Python 客户端为例：

from elasticsearch import Elasticsearch es = Elasticsearch("http://localhost:9200") resp = es.search( index="demo_products", query={"match": {"title": "耳机"}}, source=["title", "price", "stock"], size=20 ) for hit in resp["hits"]["hits"]: src = hit["_source"] print(src.get("title"), src.get("price"))

Java 客户端（RestHighLevelClient 或新版 Java API Client）里对应的是SearchSourceBuilder.fetchSource(includes, excludes)：

SearchSourceBuilder builder = new SearchSourceBuilder(); builder.query(QueryBuilders.matchQuery("title", "耳机")); builder.fetchSource(new String[]{"title", "price", "stock"}, null);

注意fetchSource的第一个参数是 includes，第二个是 excludes，传null表示不设置。如果两个都传，ES 会先应用 includes 再应用 excludes，也就是 excludes 优先级更高。

实操心得：在客户端封装一层“字段白名单”工具方法，把业务字段列表集中管理。我一般会写一个buildSourceFilter(String scene)，根据场景返回不同的字段数组，避免每个查询各写各的。

5. 常见问题与排查技巧实录

5.1 指定了字段却还是返回全部

这是最高频的问题。原因通常有三个：一是_source写在了错误的位置，比如写到了query里面而不是和query平级；二是客户端 SDK 有默认行为覆盖了你的设置，比如某些封装库默认fetchSource(true)；三是你查的是_msearch批量接口，字段过滤要写在每个子查询体里，写在最外层无效。

排查方法：先用最原始的curl直接打 REST API，排除客户端干扰。如果 curl 正常、客户端不正常，那就是 SDK 的问题，去查它的fetchSource相关配置。

5.2 通配符过滤没生效

"_source": ["specs.*"]有时候取不到嵌套字段，常见原因是字段名拼写和实际 mapping 不一致，或者嵌套层级比你想的深。比如实际是specs.detail.color，你写specs.*只能取到specs下一级，取不到specs.detail下的。解决办法是用GET /demo_products/_mapping先确认字段全路径，再写通配符。

另外，ES 对_source过滤的通配符支持在不同版本间有细微差异，7.x 早期版本对多层通配符支持不完善。如果遇到诡异问题，先确认版本，必要时升级或改用显式字段列表。

5.3 过滤后字段顺序和类型变化

_source过滤返回的字段顺序不保证和 mapping 顺序一致，也不保证和 includes 数组顺序一致。客户端如果依赖字段顺序解析（比如按位置取值），会出问题。正确做法是按 key 取值，别依赖顺序。

类型方面，_source返回的是原始 JSON 类型，和 mapping 里定义的类型可能不同。比如 mapping 里是date，_source里可能是字符串；mapping 里是keyword，_source里可能是数字。这是正常的，因为_source存的是写入时的原始值。如果你需要 mapping 转换后的值，得用docvalue_fields或fields参数（ES 7.10+ 支持fields选项）。

5.4 常见问题速查表

5.5 几个我踩过的坑

第一个坑：以为_source过滤能减少磁盘读取。前面说过，_source是整体存储的，过滤只省解析和传输。如果你的瓶颈是磁盘 IO，得从分片设计、冷热分离入手，别指望字段过滤。

第二个坑：在_msearch里把_source写到外层。_msearch的每个子请求是独立的查询体，字段过滤必须写在每个子请求里，写在外层会被忽略，而且不报错，特别隐蔽。

第三个坑：用_source: false后又想取字段。关了_source就只能靠stored_fields，而stored_fields要求建索引时设置store: true，事后改 mapping 需要重建索引。所以关_source前一定要想清楚。

第四个坑：字段白名单没同步更新。新增字段后忘了加到白名单，导致接口返回缺字段，前端报错。后来我们把白名单做成配置化，加字段时走配置变更流程，才算规范。

6. 进阶技巧：字段过滤与查询性能的协同优化

6.1 结合fields参数获取格式化值

ES 7.10 之后引入了fields参数，它和_source过滤是互补的。_source返回原始值，fields返回经过 mapping 处理的值（比如日期格式化、keyword 原值）。如果你既要原始字段又要格式化值，可以两个一起用：

{ "query": { "match_all": {} }, "_source": ["title", "price"], "fields": ["create_time", "specs.color"], "format": "yyyy-MM-dd" }

这样_source给你原始 JSON，fields给你格式化后的日期。注意fields对text类型字段默认不返回（因为 text 会被分词），需要字段设置store或用docvalue_fields。

6.2 大文档场景的分页与字段裁剪组合

当索引里文档很大、又要分页时，字段过滤要和size、from配合。我的经验是：分页查询一定要做字段裁剪，因为每页返回的文档数乘以单文档大小，很容易把响应体撑爆。比如size: 100、单文档 40KB，一页就是 4MB，网关很容易超时。裁剪到 1KB，一页才 100KB，稳得多。

如果分页很深（from很大），还要考虑search_after替代from/size，避免深度分页的性能问题。字段过滤和search_after不冲突，可以一起用。

6.3 字段过滤在数据导出场景的应用

做数据导出时，字段过滤更是刚需。导出通常要拉大量文档，如果全量返回，内存和网络都扛不住。我的做法是：导出时用_source过滤只取必要字段，配合scroll或search_after分批拉取，每批size控制在 1000 以内，边拉边写文件，避免一次性加载到内存。

这里有个细节：导出场景下_source过滤的字段列表最好和导出模板绑定，模板改字段列表跟着改，避免导出字段和模板对不上。

6.4 监控字段过滤的实际效果

优化有没有效果，得用数据说话。我一般会监控两个指标：一是接口响应体大小（用网关或客户端埋点），二是 ES 查询的took时间和节点 CPU。字段过滤上线后，响应体大小应该明显下降，took时间在宽文档场景下也会下降。如果响应体降了但took没降，说明瓶颈不在解析，得往别处找。

最后分享一个小技巧：在测试环境用_source过滤前后各跑 100 次查询，取 P50 和 P99 对比，比单次测试靠谱得多。我一般用简单的脚本循环调用，把结果打到 CSV 里再分析，几分钟就能得出结论。

这套字段过滤的玩法，我从最初只会写数组简写，到后来能根据场景灵活选 includes/excludes、通配符、fields组合，中间踩的坑基本都写在上面的排查表里了。核心就一句话：别让 ES 返回你不需要的东西，这一条能解决大半的查询性能问题。