官方推荐且维护活跃的是 github.com/arangodb/go-driver（即 go-driver），而非已归档的 arangodb-go-driver；后者自2021年起停止更新，连接ArangoDB 3.10+易触发400错误或认证失败。
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 —— 它本身线程安全，全局单例即可。
立即学习“go语言免费学习笔记（深入）”；
- 用
driver.NewConnection创建连接，而非driver.NewHTTPConnection（后者已弃用） - 设置
connection.SetAuthentication时，密码明文传参没问题，但生产环境建议从os.Getenv("ARANGO_PASSWORD")读取 - 务必调用
client.Database(ctx, "mydb")获取 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 操作复用 dbGraph 查询怎么写才不踩坑？AQL 中的 bindVars 必须用 map[string]interface{}
微服务里常要查图关系（比如用户→订单→商品），直接拼 AQL 字符串是高危操作：既易 SQL 注入，又难调试。ArangoDB 要求 bindVars 必须是 map[string]interface{}，不能是 struct 或 map[string]string。
Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。
常见错误：
- 传
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 索引字段类型匹配——这些细节不写进初始化代码，上线后就变成半夜告警的根源。
