HugeGraph Go 客户端快速入门

HugeGraph Go Client 是 Toolchain 仓库中的 Go SDK，目前提供版本查询、Schema（PropertyKey、VertexLabel、EdgeLabel）、顶点和 Gremlin API。边数据 API 尚未实现。

该模块仍在开发中。接口范围以 hugegraph-client-go/api/v1 下的源码为准。

环境要求

• Go 1.19 或更高版本
• 可访问的 HugeGraph Server，默认示例地址为 http://127.0.0.1:8080

安装

在 Go module 项目中执行：

1go get github.com/apache/hugegraph-toolchain/hugegraph-client-go

初始化客户端

NewCommonClient 要求 Host 是 IP 地址，Port 在 1 到 65535 之间；客户端始终使用明文 HTTP 连接。未启用认证时，用户名和密码留空；只有两者都设置时才会发送 Basic Auth。

GraphSpace 只在 Vertex API（此时请求路径为 /graphspaces/{space}/graphs/{graph}/...）和 Gremlin 默认 aliases 中生效（空值按 DEFAULT 处理）。Schema 相关入口和 Version() 始终请求 /graphs/{graph}/... 和 /versions，与 GraphSpace 无关。默认图空间填写 DEFAULT；将 GraphSpace 留空时，Vertex API 会回退到旧版 Server 使用的 /graphs/{graph} 路径。

 1package main
 2
 3import (
 4	"fmt"
 5	"log"
 6
 7	hugegraph "github.com/apache/hugegraph-toolchain/hugegraph-client-go"
 8)
 9
10func main() {
11	client, err := hugegraph.NewCommonClient(hugegraph.Config{
12		Host:       "127.0.0.1",
13		Port:       8080,
14		GraphSpace: "DEFAULT",
15		Graph:      "hugegraph",
16		Username:   "",
17		Password:   "",
18	})
19	if err != nil {
20		log.Fatal(err)
21	}
22
23	response, err := client.Version()
24	if err != nil {
25		log.Fatal(err)
26	}
27	defer response.Body.Close()
28
29	fmt.Println(response.Versions.Version)
30}

Version() 返回的 Versions 包含 HugeGraph Server、Core、Gremlin 和 REST API 版本。若使用源码提供的 NewDefaultCommonClient()，默认连接 127.0.0.1:8080 下的 hugegraph 图，使用 admin/pa 认证，并挂载一个打印全部请求和响应体的 ColorLogger；生产代码通常应显式传入配置。

配置项

hugegraph.Config 包含以下字段：

hgtransport 包提供四种 logger：TextLogger（纯文本）、ColorLogger（终端彩色）、CurlLogger（可执行的 curl 命令）和 JSONLogger（JSON 行）。它们的字段相同：Output（io.Writer）、EnableRequestBody 和 EnableResponseBody。

 1import (
 2	"os"
 3
 4	hugegraph "github.com/apache/hugegraph-toolchain/hugegraph-client-go"
 5	"github.com/apache/hugegraph-toolchain/hugegraph-client-go/hgtransport"
 6)
 7
 8client, err := hugegraph.NewCommonClient(hugegraph.Config{
 9	Host:  "127.0.0.1",
10	Port:  8080,
11	Graph: "hugegraph",
12	Logger: &hgtransport.ColorLogger{
13		Output:             os.Stdout,
14		EnableRequestBody:  true,
15		EnableResponseBody: true,
16	},
17})

已实现的入口

CommonClient 当前公开以下入口：

每个操作都通过挂在操作本身上的 With... 函数式选项传参，例如 client.Gremlin.Post.WithGremlin(...) 或 client.Propertykey.GetByName.WithName(...)。

EdgeLabel.Create 的请求数据允许 Properties: nil 或空切片 []string{}，用于创建无属性的边标签。

类型化 API 返回的 err 表示参数校验、传输、响应读取或 JSON 解码错误。 HTTP 4xx/5xx 仍可能返回 err == nil，例如创建顶点时指定不存在的 label 会返回 HTTP 400。 读取结果数据前，请检查 response.StatusCode 是否属于 2xx。调用 Gremlin.Post 时，还需检查 response.Data.Status.Code 是否为成功的 Gremlin 协议状态码（2xx）。

 1resp, err := client.Gremlin.Post(
 2	client.Gremlin.Post.WithGremlin("g.V().limit(3)"),
 3)
 4if err != nil {
 5	log.Fatal(err)
 6}
 7defer resp.Body.Close()
 8if resp.StatusCode < 200 || resp.StatusCode >= 300 {
 9	log.Fatalf("HugeGraph returned HTTP %d", resp.StatusCode)
10}
11if resp.Data.Status.Code < 200 || resp.Data.Status.Code >= 300 {
12	log.Fatalf("Gremlin returned status %d: %s", resp.Data.Status.Code, resp.Data.Status.Message)
13}
14fmt.Println(resp.Data.Result.Data)

Vertex 相关操作的入参是 internal/model 包中的 model.Vertex[any]。Go 不允许从其他 module 导入 internal 包，因此目前 Vertex API 只能在客户端 module 内部调用；其测试文件也已全部注释。

完整调用方式可参考各 API 目录中的测试，例如 version_test.go、gemlin_test.go 和 vertexlabel_test.go。