ravendb v5+无官方go sdk，必须手动构造http.client并配置tls、请求头与patch命令数组，且需自行实现节点故障转移；gorm不适用其文档模型。
Go 里初始化 RavenDB 客户端必须绕过 HTTP 基础库直连
RavenDB v5+ 不再提供官方 Go SDK，net/http 是唯一可靠入口。你不能像用 gorm 那样 Open() 一个连接池——RavenDB 的会话管理、证书校验、JSON 序列化策略都得自己控制。
常见错误是直接复用 http.DefaultClient：它默认不校验证书（开发环境看似能通），但上线后遇到自签名证书或 TLS 1.3 协商失败就静默超时；更糟的是它没有请求头自动注入能力，导致 Authorization 或 Raven-Client-Version 缺失，返回 401 Unauthorized 或 400 Bad Request。
- 必须显式构造
http.Client，并设置Transport.TLSClientConfig.InsecureSkipVerify = true（仅限本地调试） - 生产环境务必加载证书文件：
cert, _ := tls.LoadX509KeyPair("client.crt", "client.key")，再注入Transport.TLSClientConfig.Certificates - 所有请求必须带
Content-Type: application/json和Accept: application/json，否则 RavenDB 返回空响应或406 Not Acceptable
向 RavenDB 发送 PATCH 请求必须用命令数组，不是 JSON 对象
这是最容易踩坑的点：RavenDB 的 PATCH 接口不是 RFC 5789 意义上的部分更新，而是命令式补丁机制。传 {"title": "new"} 会触发 "could not figure out what to do" 错误。
正确结构是一个 JSON 数组，每个元素是操作指令对象：
[{"Type":"Set","Patch":{"Path":"title","Value":"new"}}]
支持的操作类型包括 Set、Unset、Increment、Copy、Move，路径支持嵌套字段如 "user.profile.name"。
- 用
bytes.NewBuffer包裹序列化后的命令数组，别用json.Marshal后直接拼字符串 - URL 必须含数据库名和文档 ID，形如
http://localhost:8080/databases/MyDB/docs/123，漏掉/databases/{db}/docs/路径段会返回404 - HTTP 方法必须是
PATCH，不是POST或PUT；某些反向代理（如 Nginx）默认禁用PATCH，需显式开启underscores_in_headers on
RavenDB 分布式部署下必须手动处理节点故障转移
RavenDB 集群本身支持自动故障转移，但 Go 客户端不会帮你重试或切换节点。如果你只硬编码一个 URL（比如 http://node1:8080），当该节点宕机时，所有请求立刻失败，不会自动跳转到 node2 或 node3。
可行方案是维护一个节点列表，配合健康检查轮询：
- 启动时并发请求各节点的
/admin/debug/cluster-state，过滤出State: "Healthy"的节点 - 写操作优先发往 Leader 节点（从
/admin/debug/cluster-state返回的Leader字段获取） - 读操作可随机选一个 Healthy 节点，但注意：RavenDB 默认启用强一致性读，跨节点读可能延迟高；若接受最终一致，加查询参数
?stale=false - 单个请求超时设为 5s，连续 3 次失败则从可用节点池中剔除该节点，10 秒后重新探测
GORM 无法替代 RavenDB 的文档模型能力
看到有人试图用 gorm 连 RavenDB，这是方向性错误。GORM 是关系型 ORM，依赖 SELECT/JOIN/FOREIGN KEY，而 RavenDB 是无 Schema 文档库，核心能力如嵌套对象索引、时间序列聚合、全文检索分词、变更订阅（Changes API）全都不在 GORM 覆盖范围内。
真正需要的是轻量封装：把 http.Client + json.Marshal + url.PathJoin 组合成几个函数，例如：
GetDoc(db, id string, target interface{}) errorPatchDoc(db, id string, commands []PatchCommand) errorQuery(db, query string, params url.Values, results interface{}) error
这些函数内部统一处理认证头、重试逻辑、错误映射（如把 404 转成 ErrDocumentNotFound），比强行套 ORM 更稳定、更易调试。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
