告别“兼容模式”：Easysearch 有了自己的官方 Python 客户端

用过 Easysearch 的 Python 开发者大概都经历过同一个小尴尬：明明用的是 Easysearch，requirements.txt 里却得写着 elasticsearch==7.10.1。兼容是兼容，但心里总觉得有点别扭——版本锁死、包名错位、新特性跟不上。

现在，这个问题被官方解决了。INFINI Labs 上线了官方 Python 客户端 easysearch-py，包名就叫 easysearch，Apache 2.0 协议开源。不用再靠 elasticsearch-py 的兼容模式连 Easysearch 了。

它是什么

easysearch-py 基于 elasticsearch-py 7.10.1 衍生，由 INFINI Labs 开发。换句话说：API 你已经会用了，迁移成本几乎为零，只是导入路径和维护方变了。

官方建议：

新项目：直接用 easysearch
老项目：继续用 elasticsearch==7.10.1 兼容连接也没问题，两者 API 调用方式完全一致

3 分钟上手

安装

1	pip install easysearch

需要 async/await 支持的：

1	pip install "easysearch[async]"

建立连接

from easysearch import Easysearch

es = Easysearch(
    ["https://localhost:9200"],
    http_auth=("admin", "your_password"),
    verify_certs=False,      # 开发环境；生产请配置 CA 证书
    timeout=30,
    max_retries=3,
    retry_on_timeout=True,
)

print(es.info())

生产环境推荐用 CA 证书：

from ssl import create_default_context

context = create_default_context(cafile="/path/to/root-ca.pem")
es = Easysearch(
    ["https://easysearch-host:9200"],
    ssl_context=context,
    http_auth=("admin", "your_password"),
    timeout=30,
)

写入与搜索

# 单条写入
es.index(index="articles", id=1, body={
    "title": "Easysearch 入门",
    "content": "分布式搜索引擎快速上手",
    "tags": ["搜索", "教程"],
    "views": 100,
})

# 全文搜索
resp = es.search(index="articles", body={
    "query": {"match": {"title": "Easysearch"}}
})
for hit in resp["hits"]["hits"]:
    print(f'{hit["_score"]:.2f}  {hit["_source"]["title"]}')

批量写入

from easysearch.helpers import bulk

actions = [
    {"_index": "articles", "_id": i, "_source": {"title": f"文章 {i}", "views": i * 10}}
    for i in range(2, 102)
]
success, errors = bulk(es, actions)
print(f"成功写入 {success} 条")

Bool 组合查询与聚合

# 组合查询
es.search(index="articles", body={
    "query": {
        "bool": {
            "must":   [{"match": {"title": "文章"}}],
            "filter": [{"range": {"views": {"gte": 500}}}],
        }
    },
    "sort": [{"views": "desc"}],
    "size": 5,
})

# 聚合
es.search(index="articles", body={
    "size": 0,
    "aggs": {
        "tag_count": {"terms": {"field": "tags.keyword"}},
        "avg_views": {"avg": {"field": "views"}},
    },
})

用了它有什么好处

对从 elasticsearch-py 过来的同学，感知最明显的是这几点：

包名对得上。 用的是 Easysearch，import 自然应该是 easysearch，语义清晰，读代码的人一眼就懂。
不用再锁死 7.10.1。 Elastic 官方客户端在新版本里加入了严格的服务端版本校验，连非 Elastic 发行版会告警甚至拒连；官方客户端彻底绕过这个问题。
特性同步及时。 Easysearch 有自己的增强（压缩、审计、国密、跨集群复制等），官方客户端能第一时间跟进，不用等上游项目。
自主可控。 由 INFINI Labs 维护，中文社区响应快，合规场景下也更踏实。

其他继承自上游的能力也一个不少：自动节点发现、持久连接、负载均衡、失败惩罚、SSL、HTTP 认证、线程安全、插件化架构。