ArangoDB 作为多模 NoSQL 数据库，在微服务架构中越来越常见。不过，Go 客户端驱动的选型、初始化、图查询、事务处理，这些环节稍有不慎就会埋下坑。下面直接梳理几个关键要点，帮你避开那些常见的“半夜告警”。
ArangoDB 驱动选哪个？go-driver 还是 arangodb-go-driver？
官方推荐且维护活跃的是 github.com/arangodb/go-driver（常被简称为 go-driver），不是那个早已归档的 arangodb-go-driver。后者自 2021 年起停止更新，用它连 3.10+ 版本的 ArangoDB，大概率会触发 400 Bad Request 或认证失败，直接翻车。
安装命令必须用：
go get github.com/arangodb/go-driver@v1.5.0
注意版本号：v1.5.0 支持 ArangoDB 3.10–3.11；如果用的是 3.12+，至少需要 v1.6.0。不指定版本容易拉到旧版，导致 driver.NewConnection 初始化失败或者 ctx deadline exceeded —— 这种问题排查起来很头疼。
如何安全初始化 client 并复用连接池？
ArangoDB 的 Go driver 默认启用连接池，但必须手动传入 context 控制超时，否则网络抖动时 goroutine 会卡死，雪崩效应就来了。千万别在 handler 里每次 new client —— 它本身线程安全，全局单例即可，省心又高效。
- 用
driver.NewConnection创建连接，而不是driver.NewHTTPConnection（后者已弃用，别踩） - 设置
connection.SetAuthentication时，密码明文传参开发环境没问题，但生产环境建议从os.Getenv("ARANGO_PASSWORD")读取，别硬编码 - 务必调用
client.Database(ctx, "mydb")获取 db 实例，然后反复复用这个 db 对象，而不是每次调用client.Database—— 每次都会走 HTTP 请求校验，性能损耗巨大
典型初始化片段：
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)defer cancel()conn, err := driver.NewConnection(driver.ConnectionConfig{ Endpoints: []string{"http://localhost:8529"},})if err != nil { /* handle */ }client, err := driver.NewClient(driver.ClientConfig{ Connection: conn,})if err != nil { /* handle */ }db, err := client.Database(ctx, "inventory")// 后续所有 collection / query 操作复用 db
Graph 查询怎么写才不踩坑？AQL 中的 bindVars 必须用 map[string]interface{}
微服务里常要查图关系（比如用户→订单→商品），直接拼 AQL 字符串是高危操作：既容易引来 AQL 注入，又难调试，出了问题连自己都看不懂。ArangoDB 要求 bindVars 必须是 map[string]interface{}，不能是 struct 或 map[string]string。
常见错误：
- 传
struct{UserID string}给WithBindVars→ 报错invalid type for bind parameter - bindVars key 缺少
@前缀 → 查询返回空结果，无报错，排查起来很烧脑 - 用
fmt.Sprintf拼接 AQL → 用户输入带引号会破坏语法，直接报错或者数据泄露
正确写法示例：
aql := "FOR v IN 1..2 OUTBOUND @startVertex knows RETURN v"cursor, err := db.Query(ctx, aql, map[string]interface{}{ "@startVertex": "users/123",})
事务怎么保证跨 collection 一致性？用 transaction API 而非 AQL BEGIN/COMMIT
ArangoDB 的 AQL 事务（BEGIN TRANSACTION）仅限单个查询内，无法跨多个 db.Collection 操作。微服务中常见“扣库存 + 写订单 + 发消息”这类多 collection 更新，必须用 driver 提供的 db.Transaction，这才是正道。
关键约束：
- 事务函数体内不能调用
db.Collection外部方法，所有操作必须通过传入的driver.TransactionContext—— 这个设计是为了保证事务的原子性 - 事务超时由
driver.TransactionConfig.Timeout控制，默认 60s，微服务建议设为 5–10s，别让事务长时间占用资源 - 如果事务内调用其他 service，会导致分布式事务问题——ArangoDB 事务只管自己引擎内操作，跨服务的还得另想办法
事务体必须是纯函数，例如：
err := db.Transaction(ctx, func(ctx context.Context, trx driver.TransactionContext) error { col := trx.Collection("inventory") doc, _ := col.Document(ctx, "item-001", &item{}) item.Stock -= 1 _, err := col.UpdateDocument(ctx, "item-001", item) return err}, driver.TransactionConfig{Timeout: 5 * time.Second})
图遍历深度、事务嵌套、AQL 中 FULLTEXT 索引字段类型匹配——这些细节不写进初始化代码，上线后就变成半夜告警的根源。提前规划好，后面才能睡得安稳。
