neo4j-go-driver 执行带参数查询必须用 map[string]interface{} 绑定参数，禁用字符串拼接；返回值需按类型（node/path/map）正确解析；事务须显式 commit/rollback；连接池应调优 maxconnectionpoolsize 和 maxconnectionlifetime。
用 neo4j-go-driver 执行带参数的 Cypher 查询
Go 操作 Neo4j 的事实标准是官方维护的 neo4j-go-driver，不是第三方 ORM 或封装库。它不支持链式查询构造，所有逻辑都得靠拼 Cypher 字符串 + 参数绑定完成。
常见错误是直接字符串拼接变量，导致注入风险或类型错乱。比如把用户输入的 nodeID 直接插进 Cypher 里，一来可能被注入恶意语句，二来整数和字符串类型在 Neo4j 中行为不同（id(node) 返回整数，而 node.id 可能是字符串）。
- 必须用
session.Run()的第二个参数传map[string]interface{}，键名要和 Cypher 中的$param严格一致 - Cypher 中不要写
WHERE id(n) = $id然后传整数——Neo4j 的内部 ID 不稳定，生产环境应使用业务主键（如uuid或slug） - 如果查的是多个节点间路径，
MATCH (a)-[r*1..3]->(b)这种可变长关系要小心性能：没加LIMIT容易拖垮服务，尤其当图规模大时
处理嵌套结构返回值：Map 和 Record 的区别
Neo4j 返回的结果不是 JSON，而是 neo4j.Record 切片，每条 Record 的 Values 是 []interface{}，但实际内容可能是 map、slice、int64、string，甚至 nil —— 类型由 Cypher 的 RETURN 子句决定。
典型坑是直接对 record.GetByIndex(0) 做类型断言：v.(map[string]interface{})，结果 panic，因为 Neo4j Go driver 默认把节点、关系、路径这类结构序列化成自定义 struct（如 neo4j.Node），不是原始 map。
立即学习“go语言免费学习笔记（深入）”；
- 查单个节点用
record.GetByIndex(0).(neo4j.Node).Props拿属性 map - 查
RETURN {name: u.name, friends: size((u)-[:FRIEND]->())}这种匿名映射，才能得到map[string]interface{} - 查路径
RETURN p会返回neo4j.Path，需用p.Nodes()/p.Relationships()拆解，不能强转
事务中写入失败后手动回滚容易被忽略
neo4j-go-driver 的事务不是自动 commit/rollback 的。调用 tx.Run() 出错不会自动终止事务，必须显式调用 tx.Close() 或 tx.Rollback()，否则连接池里的 session 会被卡住，后续请求超时。
最简健壮写法是 defer + if err 判断：
tx, err := session.BeginTransaction()
if err != nil {
return err
}
defer tx.Close() // 注意：Close 不等于 Rollback！
<p>_, err = tx.Run("CREATE (n:User {id: $id})", map[string]interface{}{"id": userID})
if err != nil {
tx.Rollback() // 必须手动 rollback，否则下次复用该 tx 会 panic
return err
}
return tx.Commit()
-
tx.Close()在未 commit 且未 rollback 时，行为是 silent rollback，但文档不保证 —— 别依赖它 - 并发写同一节点（如两个 goroutine 同时
MERGE (u:User {id: $id})）可能触发唯一约束冲突，错误信息是"Neo.ClientError.Schema.ConstraintValidationFailed"，需捕获并重试或降级 - 批量插入别用循环多次
tx.Run()，改用UNWIND $data AS row CREATE ...单次提交，性能差 10 倍以上
连接池配置不当导致高延迟或连接耗尽
默认的 neo4j.NewDriver() 创建的连接池最大连接数是 100，但 Go 应用常跑在容器里，CPU 核数少，goroutine 多，很容易打满连接池。现象是请求卡在 session.NewRecordMessage()，日志里反复出现 "connection pool is full"。
真正起作用的不是 MaxPoolSize，而是 MaxConnectionLifetime 和 MaxConnectionPoolSize —— 后者才是控制上限的关键配置项。
- 设
MaxConnectionPoolSize: 50比默认 100 更稳妥，配合应用 QPS 调整（例如 100 QPS 通常配 20–30） - 一定要设
MaxConnectionLifetime: 1 * time.Hour，避免 DNS 变更后连接一直连着旧 IP - 别在 HTTP handler 里每次 new driver —— driver 是线程安全、长生命周期对象，全局复用一个就行
复杂点在于：Cypher 查询的「复杂关系」往往意味着多跳、带过滤、含聚合，这种查询没法靠加索引完全解决，得结合 EXPLAIN 看执行计划，确认是否用了 NodeByLabelScan 还是 NodeIndexSeek。没建对索引，再怎么调 Go 代码也没用。
