直接使用 github.com/algolia/algoliasearch-client-go/v4 即可完成核心集成，但需严格区分 Search-only 与 Admin API Key 权限、手动创建索引、调用 task.Wait() 确保写入完成，并正确配置 facetFilters 语法及 attributesForFaceting。
直接用 github.com/algolia/algoliasearch-client-go/v4 就能完成核心集成，不需要自己封装 HTTP 请求或处理签名——但必须注意 apiKey 权限类型、索引生命周期和错误重试逻辑，否则上线后搜不到数据或频繁 403。
初始化 client 时传错 apiKey 会静默失败
Algolia 要求搜索请求使用 Search-only API Key（只读），而写入索引要用 Admin API Key。如果在初始化 NewClient 时误用了 Search-only Key 去调用 Index.SaveObjects，会返回 permissionDenied 错误；反过来，用 Admin Key 做前端搜索虽能跑通，但属于严重安全风险。
- 检查后台 Dashboard → API Keys 页面，确认你复制的是带
search权限、不含admin或delete权限的 Key -
NewClient初始化本身不校验权限，错误只在首次调用写操作时暴露 - 开发期建议在
go test中加一个最小写入测试，比如index.SaveObjects([]interface{}{map[string]string{"objectID": "test", "title": "test"}})
Index 名称大小写敏感且不可临时创建
Algolia 不会在你第一次调用 client.InitIndex("my-index") 时自动建索引——它只是返回一个 Index 实例。如果该索引在 Dashboard 里不存在，后续所有写操作都会报 invalid index。
- 必须提前在 Algolia 控制台手动创建索引，名称要和代码中
InitIndex("xxx")的字符串完全一致（包括连字符、下划线、大小写） - 索引名不能含空格或特殊字符，推荐全小写 + 连字符，如
docs-zh-cn - 若用 Crawler 自动建索引，实际生成的索引名可能带
.tmp后缀，需等爬取完成再确认最终名称
SaveObjects 默认不等待写入完成
Index.SaveObjects 返回的是一个 *task.Task，不是写入结果。如果你不显式调用 task.Wait()，Go 程序可能在数据真正落库前就退出，导致“写了但查不到”。
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
立即学习“go语言免费学习笔记（深入）”；
- 调试阶段务必加上
err := task.Wait()，否则无法感知写入失败（例如字段类型冲突、配额超限） - 生产环境可异步处理，但需监听
task.Status()并记录失败任务 ID，用于重试 - 批量写入建议控制单次
SaveObjects的对象数 ≤ 1000，避免超时或内存压力
Search 时 facetFilters 语法容易写错
前端传来的过滤条件，比如 “只查中文文档”，要写成 facetFilters: []string{"language:zh-CN"}，而不是 "language=zh-CN" 或 ["language", "zh-CN"]。格式错会导致过滤失效，但请求仍成功返回全部结果。
- facet 字段必须在 Algolia 后台索引设置中已声明为
attributesForFaceting，否则过滤无效果 - 多条件用嵌套数组表示 AND 关系：
[]string{"category:blog", "status:published"}；OR 关系需写成[]string{"[category:blog,category:news]"} - 调试时可先在 Dashboard 的 Index → Search preview 中粘贴相同参数验证结果
最常被跳过的环节是：没确认索引是否已有 records，也没验证 facet 字段是否加入 attributesForFaceting。这两个点不手动点开 Dashboard 看一眼，光靠代码日志根本发现不了问题。
