简介面向需要在Java应用中集成Elasticsearch的开发人员这是一份讲解Elasticsearch Java API实操使用的PDF文档。文档基于JDK 1.6 u29与Elasticsearch 0.20.2 RTF版本涵盖环境搭建、Maven依赖配置和Java客户端通信的核心流程。与网上零散独立的示例不同作者结合自身摸索整理出较完整的调用demo通过TransportClient建立集群连接使用XContentBuilder创建索引并定义映射覆盖字段类型字符串/日期、分析器选择、日期格式以及TTL、timestamp等元字段配置同时演示插入文档、关闭客户端等常见操作并给出二次扩展的参考方向如索引别名、更复杂的查询与更新。读者可按文档顺序配置双节点集群环境理解多网卡IP绑定、集群名称设置等易错点后再将示例迁移到自己的项目中。资源为1个PDF压缩包约34KB已有92人学习适合入门Elasticsearch Java API、希望获得完整实操路径的开发者。1. 从一份老 PDF 说起Elasticsearch Java API 的完整调用链搜索引擎项目做久了你会发现网上那些 Elasticsearch Java API 的例子绝大多数是东拼西凑的有人只贴 TransportClient 连接有人只讲 Mapping 怎么建真正能把「建索引、写数据、查数据、删数据」串成一条完整链路拿出来跑通的例子极少。这份名为《Elasticsearch 的 Java API 使用》的 PDF 演示恰恰补上了这个缺口。它基于 ES 0.20.2-RTF 版本用 JDK 1.6 和 Windows 7 环境把从 Maven 依赖、elasticsearch.yml 配置、TransportClient 双节点连接到带 TTL 和 _timestamp 的 Mapping、写入带自定义字段的文档、boolQuery 组合搜索的完整代码全给出来了。适合两类人一类是维护老系统、正在跟 ES 0.2x 时代代码死磕的 Java 工程师另一类是刚接触 ES Java API、想找个「能一次跑通」的参考实现、而不是看碎片代码拼逻辑的新手。下面我把这份 PDF 里的关键点拆开结合实操经验讲透。2. 环境与依赖JDK 1.6、Maven 坐标和 RTF 版集群配置2.1 为什么是 0.20.2-RTF版本选型和 RTF 的意义PDF 里明确写着使用 ElasticSearch(0.20.2)-RTF 版本。RTF 是当年网上流传的一个「Ready-To-Fly」整合包把 ES 核心、常用插件、中文分词等预装好解压就能跑。在实际维护老项目时你大概率碰不到官方原版 0.20.2而是某个团队内部改造过的发行包。这种包的好处是省去手动装插件、调分词的麻烦坏处是你不知道它里面被塞了什么东西排查问题时要多留个心眼。版本选型上0.20.2 对应的 Elasticsearch Java API 跟后来的 1.x、2.x 差异巨大。最典型的就是 Settings 构建方式老版本用ImmutableSettings.settingsBuilder().put(...).build()新版本已经完全换成了Settings.builder()。如果你拿 5.x/7.x 的教程去套 0.20.2第一行代码就编译不过。所以这份 PDF 的参考价值不在于「跟上时代」而在于给还在用 0.2x 的存量系统提供一份能对齐的代码。2.2 Maven 依赖与类冲突的边界PDF 里给出的 Maven 坐标是dependency groupIdorg.elasticsearch/groupId artifactIdelasticsearch/artifactId version0.20.2/version /dependency这里有个关键点这个坐标是 ES 自身不是 transport client 的独立包。0.20.2 时代还没有拆出transport模块所有客户端类都在这一个 jar 里。所以你引入它就能用TransportClient、ImmutableSettings这些类。要注意的是依赖树里可能带出lucene-core、jts等传递依赖如果你的项目里已经存在其他版本的 Lucene需要先排除。常见的处理方式是dependency groupIdorg.elasticsearch/groupId artifactIdelasticsearch/artifactId version0.20.2/version exclusions exclusion groupIdorg.apache.lucene/groupId artifactIdlucene-core/artifactId /exclusion /exclusions /dependency排除的前提是你的项目里已经有明确更高版本的 Lucene并且确认 API 兼容。否则别乱排除老版本很容易因为 Lucene 版本不一致而出现NoSuchMethodError。2.3 elasticsearch.yml 实测配置cluster.name 与 network.hostPDF 里在 ES 的config/elasticsearch.yml中改了两处我按自己搭双节点环境时的习惯整理成完整的最小配置cluster.name: wallyCluster network.host: 192.168.1.232 http.port: 9200 transport.tcp.port: 9300第一行是把默认集群名elasticsearch改成自定义的wallyCluster。集群名的匹配是客户端能连上节点的第一道门槛两端不一致就直接报NoNodeAvailableException。第二行network.host绑定对外服务 IPPDF 里特意提到「我用的机子有多个网卡所以指定了」。如果你只有单网卡不写这行也能正常用但绑定后可以避免 ES 选错网卡导致客户端连不上。另外注意http.port默认 9200 是 HTTP REST 接口transport.tcp.port默认 9300 是客户端 TCP 通信端口。Java API 用的是 9300不是 9200。3. 连接集群TransportClient 的 settings、sniff 与双节点实战3.1 TransportClient 与 NodeClient 的选型PDF 中明确用了TransportClient注释里也写了「得到访问 es 的客户端我们使用 Transport Client」。在 0.20.2 时代连接 ES 有两种方式TransportClient通过 TCP 9300 端口与集群通信NodeClient则是在你的 JVM 里启动一个 ES 节点实例来加入集群。绝大多数 Web 应用选TransportClient因为它轻量、不占多余资源也不会把你的应用 JVM 卷进 ES 集群的选举逻辑。只有当你的应用和 ES 节点紧密部署、需要共享数据目录时NodeClient 才有优势。普通业务系统老老实实用 TransportClient。3.2 settings 里 cluster.name 和 client.transport.sniff 的作用构建 TransportClient 时PDF 写了一个关键配置块Settings settings ImmutableSettings.settingsBuilder() .put(client.transport.sniff, true) .put(cluster.name, wallyCluster) .build();client.transport.sniff翻译过来是「嗅探」作用是让客户端启动时连接你显式指定的节点然后自动发现集群里的其他节点并把它们也加入连接池。这样哪怕你只手动加了两个节点的地址客户端也能感知到后续扩容出来的第三个、第四个节点。0.20.2 里sniff默认是false所以你不开它就只会连你写死的地址。cluster.name前面已经说过必须与 yml 里的配置完全一致。注意老版本里这行配置是client.transport.sniff到了新版本变成了client.transport.sniff仍然保留但很多类已经移到transport模块里了。3.3 双节点地址与 TCP 端口 9300 的绑定完整代码Client client new TransportClient(settings) .addTransportAddress(new InetSocketTransportAddress(192.168.1.232, 9300)) .addTransportAddress(new InetSocketTransportAddress(192.168.1.65, 9300));这段代码把两个节点的 9300 端口都加了进来。InetSocketTransportAddress接收主机名和端口这里用的是内网 IP。如果两个 ES 节点不在同一网段或者防火墙没放行 9300/TCP后续actionGet()就会抛ConnectTransportException。我在实际项目里就吃过一次亏节点 A 和节点 B 都启动了但.bat窗口闪退一查是另一个程序占了 9300 端口。所以双节点环境下先确认端口被正确监听再写客户端代码。4. 写数据前先定 MappingTTL、时间戳、字段类型怎么用 Java 声明4.1 为什么先建 Mapping避免 ES 自动映射的坑PDF 里的buildIndexSysDm()本质上是在做「先定义表结构」这件事。ES 允许你在写入第一条文档时自动推断字段类型但自动推断的结果常常不是你想要的比如价格字段被映射成long而不是double或者日期字段识别成字符串。更麻烦的是如果索引里已经存在某个字段类型你再想改就基本只能重建索引。所以生产环境必须像 PDF 演示的那样先prepareCreate(productindex)再addMapping最后才写数据。4.2 _ttl 与 _timestamp 的开关和默认值Mapping 里最容易被忽略的是_ttl和_timestamp这两个元字段。PDF 用了一大段注释来解释它们我直接拆开讲。XContentBuilder mapping XContentFactory.jsonBuilder() .startObject() .startObject(we3r) .startObject(_ttl) .field(enabled, true) .field(default, 5m) .field(store, yes) .endObject() .startObject(_timestamp) .field(enabled, true) .field(store, no) .field(index, not_analyzed) .endObject() .startObject(properties) // ... 字段定义 .endObject() .endObject() .endObject();_ttl是「存活时间」开启后每条文档都可以设置一个过期时长到期后 ES 会自动删除。default: 5m表示默认 5 分钟后面的d/h/m/s分别对应天、小时、分钟、秒。store设为yes是把 TTL 值单独存储方便查询时看到剩余时间但会让索引占更多空间。_timestamp则是写入时自动打上的时间戳store: no意味着不单独存这个字段值但你仍然可以在查询时按它排序或过滤因为它是元数据结构的一部分。4.3 properties 里 string、double、boolean、date 的声明properties下定义的是你真正要用的业务字段相当于创建数据库表字段。PDF 里给了一个很典型的组合.startObject(properties) .startObject(title).field(type, string).field(store, yes).endObject() .startObject(description).field(type, string).field(index, not_analyzed).endObject() .startObject(price).field(type, double).endObject() .startObject(onSale).field(type, boolean).endObject() .startObject(type).field(type, integer).endObject() .startObject(createDate).field(type, date).field(format, YYYYMMddhhMMSS).endObject() .endObject()这段代码有几个值得注意的细节。title字段开了store: yes这样查询结果里能直接返回原始字段值而不是仅仅返回_source。description设置了index: not_analyzed意思是这个字段不进行分词适合做精确匹配或聚合。price用double保证小数精度。createDate是date类型format用的是YYYYMMddhhMMSS。注意这个格式是 ES 0.20.2 里约定的java.text.SimpleDateFormat 的YYYY和 ES 里的YYYY语义并不完全一致实际使用时建议改成自定义格式串或者统一用yyyy-MM-dd HH:mm:ss字符串。5. 避坑集群名不一致、TTL 不生效、日期格式被拒等 5 个常见问题5.1 集群名必须完全一致客户端连不上的头号原因现象TransportClient创建时没报错但一旦执行搜索或写入就抛NoNodeAvailableException日志里还带一堆failed to connect或connect_timeout。原因客户端的cluster.name和服务端elasticsearch.yml里的cluster.name不一致。解决两端统一改成同一个名字并且检查配置文件里是否有多余空格或尾随注释。我在模拟项目X里就见过cluster.name: wallyCluster后面多了个空格结果客户端连了一上午没找到节点。5.2 TTL 单位是毫秒setTTL(8000) 不是 8 秒现象调用setTTL(8000)后以为文档 8 秒后被删但等了几分钟它还在。原因IndexRequestBuilder.setTTL()接收的是毫秒数8000 毫秒是 8 秒。但如果你把 Mapping 里的default设成了5m5 分钟则单条写入的显式 TTL 应该覆盖默认值。实际中如果集群里节点时钟不一致TTL 判断也会有偏差。解决写入时用setTTL(8000)并在 Mapping 里确认_ttl.enabled是true否则这个参数会被静默忽略。5.3 createDate 格式YYYYMMddhhMMSS 与 Java 返回值的匹配现象文档写入时报MapperParsingException提示failed to parse date。原因Java 端TimeHelper.getCurrentTime()返回的字符串格式大概率是yyyy-MM-dd HH:mm:ss但 Mapping 里声明的是YYYYMMddhhMMSS两边对不上。解决把 Mapping 里的format改成yyyy-MM-dd HH:mm:ss或者自己用DateTimeFormatter转成YYYYMMddhhMMSS样式的字符串。ES 解析日期只认你声明的format别指望它自动猜。5.4 sniff 与防火墙9300 通了但 9200 不通的误解现象开了client.transport.sniff后客户端偶尔能连上但请求时好时坏。原因sniff 开启后客户端会去连接集群返回的其他节点如果这些节点对你所在网段的 9300 端口没开放或者安全组只放行了最初配置的那个 IP就会导致新发现的节点连不上。解决要么把所有 ES 节点的 9300 端口都放行要么把 sniff 关掉只保留固定的地址列表。PDF 里特意写了两个 IP目的就是演示这种双节点直连的写法。5.5 老版本 API 与新版 5.x/7.x 的兼容性现象把这份代码原封不动搬到 ES 7.x 项目发现TransportClient类直接不存在ImmutableSettings也编译报错。原因从 ES 5.x 开始TransportClient被标记废弃7.x 移除了。解决如果你维护的是老系统老老实实用 PDF 里的 0.20.2 版本如果是在新项目里改成官方推荐的RestHighLevelClient代码模型完全不同。常见的做法是写一个EsClientFactory接口内部用反射或 profile 切换方式隔离版本差异这样后续升级时改动面能小一些。6. 搜索实战与验证技巧BoolQuery、主键读取和 head 插件6.1 从 prepareSearch 到 SearchResponse 的完整查询链PDF 里exm()方法展示了删、查主键、搜三个阶段。这里我把搜索部分单独拎出来因为它最容易写错SearchRequestBuilder builder client.prepareSearch(productindex) .setTypes(prindextype) .setSearchType(SearchType.DEFAULT) .setFrom(0) .setSize(50); QueryBuilder qb2 QueryBuilders.boolQuery() .must(new QueryStringQueryBuilder(万里).field(description)) .should(new QueryStringQueryBuilder(3).field(dfsfs)) .must(QueryBuilders.termQuery(dfsfs, 里)); builder.setQuery(qb2); SearchResponse responsesearch builder.execute().actionGet();prepareSearch的参数是索引名可以传多个。setTypes限定文档类型。SearchType.DEFAULT表示使用默认搜索执行策略实际按 QUERY_THEN_FETCH 处理。setFrom(0)和setSize(50)对应分页注意 size 最大值默认受index.max_result_window限制老版本是 10000。execute().actionGet()是同步等待如果改成execute()不带actionGet则拿不到结果这是新手最容易犯的错。6.2 boolQuery、QueryStringQueryBuilder 与 termQuery 的配合这段查询结构很典型boolQuery相当于 SQL 里的 AND/OR/NOT 组合条件。must是必须满足should是尽量满足相当于 OR。QueryStringQueryBuilder适合做用户输入的自由文本搜索内部会走分词termQuery(dfsfs, 里)则是精确匹配不分词。所以当你用termQuery去匹配一个被分词的字段时经常查不到结果。PDF 里故意把dfsfs这个未在 Mapping 中定义的字段也放进查询就是为了演示 ES 默认对该字段做分词后的行为差异。实际开发中我一般会建议把所有无需分词的字段都明确设为not_analyzed避免这种「玄学」查不到结果的问题。6.3 用 head 插件组织查询串并验证返回结构PDF 最后提到建议用 ES 插件 head 来查看集群即时信息。head 插件的价值有两个一是直观看到索引、分片、文档数二是可以在它的查询面板里手动输入 JSON 查询串验证你写出来的 QueryBuilder 到底对应什么 DSL。比如上面那段 boolQuery在 head 里大概长这样{ query: { bool: { must: [ { query_string: { query: 万里, fields: [description] } }, { term: { dfsfs: 里 } } ], should: [ { query_string: { query: 3, fields: [dfsfs] } } ] } }, from: 0, size: 50 }把这段 JSON 贴到 head 的查询框里能直接看到返回命中数和每条_source。这里有个血泪经验head 面板里返回的字段顺序和 JavaSearchHit.getSourceAsString()一样都是按_source原样输出但如果你在 Mapping 里对某字段设了store: yes它会出现在单独的fields节点里而不是_source。我当初排查一个「取了半天字段是 null」的问题最后发现是_source和store字段并存导致的读取路径差异。从那以后我每次用 ES Java API 写查询都会强制先在 head 里跑一遍 DSL确认返回结构后再去写getSourceAsString的解析逻辑。希望帮到你。本文还有配套的精品资源点击获取