Golang轻量级ArangoDB数据库驱动插件库arangolite的使用

简介

Arangolite是一个轻量级的ArangoDB Go语言驱动库，专注于纯AQL查询。如果你需要更类似ORM的体验，可以参考AranGO项目。

安装

要安装Arangolite：

go get -u github.com/solher/arangolite/v2

基本用法

下面是一个完整的使用示例：

package main

import (
  "context"
  "fmt"
  "log"

  "github.com/solher/arangolite/v2"
  "github.com/solher/arangolite/v2/requests"
)

// 定义文档结构
type Node struct {
  arangolite.Document
}

func main() {
  ctx := context.Background()

  // 声明数据库配置
  db := arangolite.NewDatabase(
    arangolite.OptEndpoint("http://localhost:8529"),
    arangolite.OptBasicAuth("root", "rootPassword"),
    arangolite.OptDatabaseName("_system"),
  )

  // Connect方法做两件事：
  // 1. 如果需要则初始化连接(JWT认证)
  // 2. 检查数据库连接性
  if err := db.Connect(ctx); err != nil {
    log.Fatal(err)
  }

  // 创建一个新数据库
  err := db.Run(ctx, nil, &requests.CreateDatabase{
    Name: "testDB",
    Users: []map[string]interface{}{
      {"username": "root", "passwd": "rootPassword"},
      {"username": "user", "passwd": "password"},
    },
  })
  if err != nil {
    log.Fatal(err)
  }

  // 使用新创建的用户登录新数据库
  db.Options(
    arangolite.OptBasicAuth("user", "password"),
    arangolite.OptDatabaseName("testDB"),
  )

  // 创建一个"nodes"集合
  if err := db.Run(ctx, nil, &requests.CreateCollection{Name: "nodes"}); err != nil {
    log.Fatal(err)
  }

  // 声明一个带选项和绑定参数的AQL查询
  key := "48765564346"
  r := requests.NewAQL(`
    FOR n
    IN nodes
    FILTER n._key == @key
    RETURN n
  `, key).
    Bind("key", key).
    Cache(true).
    BatchSize(500) // 缓存功能在ArangoDB 2.7之前不可用

  // Run方法返回游标中所有页面的查询结果
  // 并将其解组到给定的结构中
  // 取消上下文会取消每个正在运行的请求
  nodes := []Node{}
  if err := db.Run(ctx, &nodes, r); err != nil {
    log.Fatal(err)
  }

  // Send方法给用户更多控制权，不跟踪游标
  // 它返回一个原始结果对象
  result, err := db.Send(ctx, r)
  if err != nil {
    log.Fatal(err)
  }
  nodes = []Node{}
  result.UnmarshalResult(&nodes)

  // 如果有更多结果，继续获取
  for result.HasMore() {
    result, err = db.Send(ctx, &requests.FollowCursor{Cursor: result.Cursor()})
    if err != nil {
      log.Fatal(err)
    }
    tmp := []Node{}
    result.UnmarshalResult(&tmp)

    nodes = append(nodes, tmp...)
  }

  fmt.Println(nodes)
}

文档和边

Arangolite提供了基本的文档和边结构：

// Document表示基本的ArangoDB文档
type Document struct {
  // 文档句柄。格式：':collection/:key'
  ID string `json:"_id,omitempty"`
  // 文档的修订令牌。每次更新时更改
  Rev string `json:"_rev,omitempty"`
  // 文档的唯一键
  Key string `json:"_key,omitempty"`
}

// Edge表示基本的ArangoDB边
type Edge struct {
  Document
  // 引用另一个文档。格式：':collection/:key'
  From string `json:"_from,omitempty"`
  // 引用另一个文档。格式：':collection/:key'
  To string `json:"_to,omitempty"`
}

事务

Arangolite提供了对Javascript ArangoDB事务的抽象层。

使用示例

t := requests.NewTransaction([]string{"nodes"}, nil).
  AddAQL("nodes", `
    FOR n
    IN nodes
    RETURN n
`).
  AddAQL("ids", `
    FOR n
    IN {{.nodes}}
    RETURN n._id
`).
  Return("ids")

ids := []string{}
if err := db.Run(ctx, ids, t); err != nil {
  log.Fatal(err)
}

图操作

AQL可用于查询图数据。要管理图，Arangolite提供了一些特定的请求：

• CreateGraph 创建图
• ListGraphs 列出可用图
• GetGraph 获取现有图
• DropGraph 删除图

使用示例

// 检查图是否存在
if err := db.Run(ctx, nil, &requests.GetGraph{Name: "graphName"}); err != nil {
  switch {
  case arangolite.IsErrNotFound(err):
    // 如果图不存在，创建一个新图
    edgeDefinitions := []requests.EdgeDefinition{
      {
        Collection: "edgeCollectionName",
        From:       []string{"firstCollectionName"},
        To:         []string{"secondCollectionName"},
      },
    }
    db.Run(ctx, nil, &requests.CreateGraph{Name: "graphName", EdgeDefinitions: edgeDefinitions})
  default:
    log.Fatal(err)
  }
}

// 列出现有图
list := &requests.GraphList{}
db.Run(ctx, list, &requests.ListGraphs{})
fmt.Printf("Graph list: %v\n", list)

// 销毁刚创建的图和相关集合
db.Run(ctx, nil, &requests.DropGraph{Name: "graphName", DropCollections: true})

错误处理

可以使用提供的测试器处理错误：

// IsErrInvalidRequest 当数据库返回400时返回true
func IsErrInvalidRequest(err error) bool {
  return HasStatusCode(err, 400)
}

// IsErrUnauthorized 当数据库返回401时返回true
func IsErrUnauthorized(err error) bool {
  return HasStatusCode(err, 401)
}

// IsErrForbidden 当数据库返回403时返回true
func IsErrForbidden(err error) bool {
  return HasStatusCode(err, 403)
}

// IsErrUnique 当错误号为1210(ERROR_ARANGO_UNIQUE_CONSTRAINT_VIOLATED)时返回true
func IsErrUnique(err error) bool {
  return HasErrorNum(err, 1210)
}

// IsErrNotFound 当数据库返回404或错误号为以下值时返回true：
// 1202 - ERROR_ARANGO_DOCUMENT_NOT_FOUND
// 1203 - ERROR_ARANGO_COLLECTION_NOT_FOUND
func IsErrNotFound(err error) bool {
  return HasStatusCode(err, 404) || HasErrorNum(err, 1202, 1203)
}

或者通过HasStatusCode和HasErrorNum方法手动处理。

贡献

目前，Arangolite中实现的ArangoDB HTTP API方法很少。幸运的是，通过实现Runnable接口可以很容易地添加你自己的方法。然后你可以使用常规的Run和Send方法。

// Runnable定义了可由Run和Send方法运行的请求
// Runnable库位于'requests'包中
type Runnable interface {
  // 请求体
  Generate() []byte
  // 发送请求的路径
  Path() string
  // 使用的HTTP方法
  Method() string
}

当你实现一些新功能时，请提交pull request，这样每个人都可以使用它。

许可证

MIT