meilisearch-go 是纯客户端库，需先运行 Meilisearch 实例；安装用 go get github.com/meilisearch/meilisearch-go，初始化需匹配 masterKey，异步写入须调 WaitForTask 等待完成，搜索前需配置 searchableAttributes，中文分词默认启用 jieba，并发写入应控制 batch 大小并避免 goroutine 冲突。
直接上手就能用，不需要额外配置文件或启动服务端——meilisearch-go 是纯客户端库，只负责发请求；你得先确保本地或远程有个 Meilisearch 实例在跑，否则所有操作都会报 connection refused 或 401 Unauthorized。
怎么装 client 并连上正在运行的 Meilisearch？
别跳过验证步骤：很多「连不上」的问题其实只是服务根本没起来。
-
go get github.com/meilisearch/meilisearch-go就够了，不用加-u（除非你要强制更新到最新版） - 确认 Meilisearch 已运行：
curl http://localhost:7700/health返回{"status":"available"}才算成功 - 初始化 client 时，
meilisearch.New("http://localhost:7700", meilisearch.WithAPIKey("masterKey"))中的masterKey必须和启动时传的--master-key=xxx一致；如果用 Docker 启动，环境变量是MEILI_MASTER_KEY - 开发阶段建议关掉 API key 验证（仅限本地）：
./meilisearch --master-key=""，这样初始化 client 可以省略WithAPIKey
添加文档时为什么数据没进索引？
不是调了 AddDocuments 就完事了——Meilisearch 默认异步写入，返回的是任务 ID，不是写入结果。
- 直接调
index.AddDocuments(docs)只会返回一个Task对象，docs还没真正落盘 - 必须显式等任务完成：
task, _ := index.AddDocuments(docs); index.WaitForTask(task.TaskUID)，否则后续搜索可能查不到 -
WaitForTask默认超时 5 秒，如果文档量大或机器慢，建议传自定义超时：index.WaitForTask(task.TaskUID, meilisearch.WithTimeout(30*time.Second)) - ID 字段必须是
int或string类型，float64或nil会导致整个 batch 失败且无明确错误提示
搜索返回空结果，但文档明明加进去了
常见原因不是代码写错，而是索引字段没被识别为可搜索字段——Meilisearch 不会自动推断 schema。
Golang Uber Dig
下载
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
立即学习“go语言免费学习笔记（深入）”；
- 默认只对
id字段建索引，其他字段如title、content要手动设为 searchable：index.UpdateSearchableAttributes([]string{"title", "content"}) - 中文搜索需确认是否启用了中文分词：Meilisearch v1.8+ 默认启用
jieba，但若你用的是旧版或自定义 build，要检查GET /indexes/{name}/settings返回里"searchableAttributes"和"rankingRules"是否合理 - 搜索时大小写敏感，默认不开启
typoTolerance，搜"philoudelphia"这种拼错词不会匹配"Philadelphia"，得加参数：&meilisearch.SearchRequest{TypoTolerance: true} - 刚加完文档就搜，可能因延迟没刷新，加个
time.Sleep(100 * time.Millisecond)纯属掩耳盗铃；正确做法是等WaitForTask完成后再搜
并发写入时报错 “task queue is full” 怎么办？
这是 Meilisearch 服务端限制，不是 client 的锅。v1.9 默认队列长度是 100，批量导入时很容易撞上。
- 服务端调大队列：
./meilisearch --task-queue-size=1000（Docker 用MEILI_TASK_QUEUE_SIZE=1000） - client 侧拆分大 batch：单次
AddDocuments不要超过 1000 条，按 100~500 条一组提交，并串行等待每个 task 完成 - 别用 goroutine 并发调
AddDocuments——不同 goroutine 提交的任务共享同一个队列，反而更容易堵死 - 如果只是初始化索引，用
UpdateDocuments替代AddDocuments更安全，它支持 upsert 语义，重复 ID 不报错
最常被忽略的一点：Meilisearch 的 index 不是数据库表，没有事务、没有外键、不保证最终一致性——它是个倒排索引快照。任何对 schema 的调整（比如改 searchableAttributes）都只影响之后新增的文档，已有文档不会自动重索引。需要手动触发 index.UpdateSettings 后再调 index.SwapIndex 或重建索引才能生效。
