官方推荐且唯一维护的Go驱动是neo4j-go-driver（github.com/neo4j/neo4j-go-driver/v5），非拼写倒置的neo4j-driver-go；安装须带/v5路径，连接需复用Driver实例、配合理超时与显式事务以保障稳定性和数据一致性。
Neo4j 驱动选型：用 neo4j-go-driver 还是 neo4j-driver-go？
官方推荐且唯一维护的 Go 驱动是 neo4j-go-driver（仓库地址 github.com/neo4j/neo4j-go-driver），不是拼写倒过来的 neo4j-driver-go——后者是旧版社区 fork，已停止更新，接入后大概率在 v5+ 服务端上连不上或报 Unsupported protocol version 错误。
安装命令必须用：
go get github.com/neo4j/neo4j-go-driver/v5/neo4j
注意 v5 路径段不能省，否则导入时会因模块版本不匹配导致编译失败。v5 驱动默认使用 Bolt 协议 v4.4，兼容 Neo4j 4.4–5.x；若服务端是 4.3 或更早，需显式降级协议版本（见下节）。
连接池与上下文超时怎么配才不崩？
微服务里最常踩的坑是把 neo4j.NewDriver 当成单次调用——它返回的是线程安全、带内置连接池的 Driver 实例，必须全局复用，绝不应在每次请求里新建。
立即学习“go语言免费学习笔记（深入）”；
初始化示例：
driver, err := neo4j.NewDriver(
"neo4j://localhost:7687",
neo4j.BasicAuth("neo4j", "password", ""),
func(config *neo4j.Config) {
config.MaxConnectionLifetime = 30 * time.Minute
config.MaxConnectionPoolSize = 100
config.ConnectionTimeout = 5 * time.Second
},
)
if err != nil {
log.Fatal(err)
}
defer driver.Close(context.Background()) // 服务退出时关闭MaxConnectionPoolSize 建议设为微服务并发 QPS 的 1.5–2 倍（比如压测峰值 60 QPS，这里设 100）；ConnectionTimeout 必须显式设，否则默认 30 秒，在 Kubernetes 环境下容易卡住 goroutine。
每个查询操作必须传入带 deadline 的 context.Context，例如：
ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second) defer cancel() _, err := session.Run(ctx, "MATCH (n) RETURN count(n)", nil)
漏掉 context 或 timeout 过长，会导致慢查询拖垮整个服务实例。
事务里怎么写 Cypher 才不丢数据？
Neo4j 的 ACID 保证只在显式事务内生效。直接用 session.Run 是自动提交的“自动事务”，不支持回滚，也不保证多语句原子性——比如先 CREATE 节点再 CREATE 关系，中间失败就会留下脏数据。
正确做法是手动开启事务：
tx, err := session.BeginTransaction(ctx)
if err != nil {
return err
}
defer tx.Close(ctx) // 注意：Close 不等于 Rollback！
<p>_, err = tx.Run(ctx, "CREATE (a:User {id: $id})", map[string]interface{}{"id": userID})
if err != nil {
tx.Rollback(ctx) // 必须显式 Rollback
return err
}</p><p>_, err = tx.Run(ctx, "MATCH (u:User {id: $id}) CREATE (u)-[:FOLLOWS]->(t:Tag {name: $tag})",
map[string]interface{}{"id": userID, "tag": "golang"})
if err != nil {
tx.Rollback(ctx)
return err
}</p><p>return tx.Commit(ctx) // 成功才 Commit关键点：tx.Close(ctx) 只是释放资源，不会 Rollback；必须在出错路径上明确调用 tx.Rollback(ctx)，否则事务残留可能锁表或耗尽连接。
另外，Cypher 中避免用 MERGE 替代 CREATE + ON CREATE SET 来做幂等写入——MERGE 在高并发下可能产生意外节点或关系，尤其当属性含动态值（如时间戳）时。
如何让 Golang 结构体自动映射到 Neo4j 节点？
驱动本身不提供 ORM，但可用 neo4j.MapRecordAs + 自定义 Unmarshal 方法做轻量映射。别依赖第三方 ORM 库（如 gogm），它们对嵌套结构、泛型支持差，且在 v5 驱动上常有字段丢失问题。
推荐模式：用 struct tag 标注字段名，查询后手动赋值：
type UserNode struct {
ID int64 `json:"id"`
Name string `json:"name"`
Tags []string `json:"tags"`
}
<p>// 查询返回 record，再逐字段解包
result, err := tx.Run(ctx, "MATCH (u:User) WHERE u.id = $id RETURN u", map[string]interface{}{"id": 123})
if err != nil { return err }
record, err := result.Single(ctx)
if err != nil { return err }</p><p>node := record.Get("u").(neo4j.Node)
user := UserNode{
ID: node.Props["id"].(int64),
Name: node.Props["name"].(string),
Tags: toStringSlice(node.Props["tags"]), // 自己写类型转换辅助函数
}注意：node.Props 是 map[string]interface{}，所有值都需类型断言；Neo4j 的 list 类型（如 tags）会转成 []interface{}，不能直接转 []string，必须遍历转换。
如果图谱查询频繁且结构固定，建议封装一个 ScanToStruct 工具函数，统一处理类型转换和空值 fallback，避免每处都写重复断言逻辑。
