neo4j驱动必须全局复用，不可在gin handler中每次新建；session.run需用显式构造的context.context而非*gin.context；事务须用writetransaction封装；节点数据需判空并手动转纯go类型；开发需配认证与7687端口。
用 Gin 配合 Neo4j 做后端服务，核心难点不在路由或 HTTP 层，而在于连接管理、事务生命周期和 Cypher 参数安全——Gin 本身不干预数据库操作，但它的 request-scoped context 和中间件机制，很容易和 neo4j-go-driver 的 session/tx 生命周期冲突。
为什么 neo4j.Driver 必须全局复用，不能每次请求新建
Neo4j Go 驱动内部维护连接池，neo4j.NewDriverWithContext 创建的 neo4j.Driver 是线程安全且可长期复用的。若在 Gin 的每个 handler 里都调 neo4j.NewDriverWithContext，会快速耗尽系统文件描述符，同时触发连接超时或 connection refused 错误。
- 正确做法：应用启动时初始化一次
driver，存入gin.Engine的engine.Set("driver", driver)或更推荐的依赖注入容器（如 wire） - 错误做法：在 handler 里写
driver, _ := neo4j.NewDriverWithContext(...)—— 每次请求新建驱动，连接池无法复用，且driver.Close()调用时机不可控 - 注意：
driver.VerifyConnectivity(ctx)只需在启动时校验一次，不要放在 handler 中反复调用
session.Run() 为何不能直接用 gin.Context 传参
Gin 的 *gin.Context 和 Neo4j 驱动要求的 context.Context 类型不同，不能混用。强行转换或透传会导致超时控制失效、cancel 信号丢失，甚至 session 卡死。
初始化并管理阿里云SDK Go 客户端，涵盖 sync.Once 单例、goroutine 安全、endpoint 与 region 配置、VPC 端点及调试。
- 必须显式构造 driver 所需的
context.Context：用ctx, cancel := context.WithTimeout(c.Request.Context(), 5*time.Second)，其中c是*gin.Context - 务必在 handler 返回前调
cancel()，否则可能泄漏 goroutine - 别写
session.Run(c, cypher, params)—— 编译不过；也别写session.Run(context.Background(), ...)—— 丢掉了 HTTP 请求的 cancel 能力 - session 关闭必须 defer：
defer session.Close(ctx)，且该ctx必须和session.Run用的是同一个（否则Close可能阻塞）
事务写入时 panic: "session is closed" 的真实原因
这个 panic 大多不是 session 真被关了，而是你在同一 session 上混用了 session.ReadTransaction 和 session.WriteTransaction，或者在事务函数内部提前 return 但没处理 tx 的生命周期。
- 绝对避免：在一个 session 内交替调
ReadTransaction和WriteTransaction—— Neo4j 驱动不允许，会静默关闭 session - 写操作唯一安全方式是
session.WriteTransaction(func(tx neo4j.Transaction) error { ... })，它自动 commit 或 rollback，你只需在函数内 return error - 别手写
tx := session.BeginTransaction()+tx.Commit()—— error 分支漏掉tx.Rollback()就卡死连接池 - 事务函数内不要 defer
tx.Close()——WriteTransaction已负责清理，重复 close 会 panic
Gin handler 中返回 Neo4j 节点数据时怎么避免 panic
Neo4j 返回的 neo4j.Node 不是 map，直接 JSON 序列化会 panic；字段取值不判空也会 panic。
- 取节点属性必须先判空：
if v, ok := record.Get("user"); ok && v != nil { node, isNode := v.(neo4j.Node); if isNode { props := node.Props() /* props 是 map[string]interface{}，但值仍是 driver 类型 */ } } - 把
node.Props()转成纯 Go 类型需手动遍历：字符串保留，int64转int，time.Time直接用，map[string]interface{}和[]interface{}递归转 - 别对
record.Get("name").(string)这种写法加 recover —— 它本就不该发生，说明 Cypher 字段名写错或没命中数据，应提前用record.Keys()检查字段存在性 - HTTP 返回建议封装一层结构体，而不是裸传
node.Props()，否则前端拿到的是嵌套 interface{}，难调试也难类型校验
最易被忽略的是：Neo4j 5.0+ 默认禁用 dbms.security.auth_enabled=false 的绕过认证，即使本地开发，也必须设密码并传 neo4j.BasicAuth；Docker 启动时只映射 7474 端口而漏掉 7687，Gin 服务永远连不上 —— 这类基础配置错误，比代码逻辑更常导致整块功能瘫痪。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
