# HugeGraph Go 客户端快速入门

LLMS 索引： [llms.txt](/cn/llms.txt)

---

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

> 该模块仍在开发中。接口范围以 [`hugegraph-client-go/api/v1`](https://github.com/apache/hugegraph-toolchain/tree/master/hugegraph-client-go/api/v1) 下的源码为准。

## 环境要求

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

## 安装

在 Go module 项目中执行：

```shell
go get github.com/apache/hugegraph-toolchain/hugegraph-client-go
```

## 初始化客户端

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

`GraphSpace` 非空时，`Vertex` 和 Schema API（`Schema()`、`Propertykey`、`VertexLabel`、`EdgeLabel`）使用
`/graphspaces/{space}/graphs/{graph}/...` 路径；留空时使用旧版 `/graphs/{graph}/...` 路径。默认图空间填写 `DEFAULT`。
Gremlin 默认 aliases 也使用 `GraphSpace`，空值按 `DEFAULT` 处理。`Version()` 始终请求 `/versions`，不依赖图空间。

```go
package main

import (
	"fmt"
	"log"

	hugegraph "github.com/apache/hugegraph-toolchain/hugegraph-client-go"
)

func main() {
	client, err := hugegraph.NewCommonClient(hugegraph.Config{
		Host:       "127.0.0.1",
		Port:       8080,
		GraphSpace: "DEFAULT",
		Graph:      "hugegraph",
		Username:   "",
		Password:   "",
	})
	if err != nil {
		log.Fatal(err)
	}

	response, err := client.Version()
	if err != nil {
		log.Fatal(err)
	}
	defer response.Body.Close()

	fmt.Println(response.Versions.Version)
}
```

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

## 配置项

`hugegraph.Config` 包含以下字段：

| 字段 | 类型 | 说明 |
|---|---|---|
| `Host` | `string` | HugeGraph Server 的 IP 地址，不支持主机名 |
| `Port` | `int` | HugeGraph Server 的 REST 端口，取值 1 到 65535 |
| `GraphSpace` | `string` | `Vertex`、Schema API 和 Gremlin 默认 aliases 使用的图空间；默认空间填写 `DEFAULT` |
| `Graph` | `string` | Server 上配置的图名 |
| `Username` | `string` | Server 用户名，未启用认证时填空字符串 |
| `Password` | `string` | Server 密码，未启用认证时填空字符串 |
| `Transport` | `http.RoundTripper` | 自定义 HTTP transport，为 nil 时使用 `http.DefaultTransport` |
| `Logger` | `hgtransport.Logger` | 请求/响应日志，为 nil 时不记录日志 |

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

```go
import (
	"os"

	hugegraph "github.com/apache/hugegraph-toolchain/hugegraph-client-go"
	"github.com/apache/hugegraph-toolchain/hugegraph-client-go/hgtransport"
)

client, err := hugegraph.NewCommonClient(hugegraph.Config{
	Host:  "127.0.0.1",
	Port:  8080,
	Graph: "hugegraph",
	Logger: &hgtransport.ColorLogger{
		Output:             os.Stdout,
		EnableRequestBody:  true,
		EnableResponseBody: true,
	},
})
```

## 已实现的入口

`CommonClient` 当前公开以下入口：

| 入口 | 用途 |
|---|---|
| `Version()` | 查询服务端版本 |
| `Schema()` | 查询完整 Schema |
| `Propertykey` | `Create`、`GetAll`、`GetByName`、`UpdateUserdata`、`DeleteByName` |
| `VertexLabel` | `Create`、`GetAll`、`GetByName`、`UpdateUserdata`、`DeleteByName` |
| `EdgeLabel` | `Create`、`GetAll`、`DeleteByName` |
| `Vertex` | `Create`、`BatchCreate`、`UpdateProperties`（通过 `WithAction` 指定 `append` 或 `eliminate`） |
| `Gremlin` | `Get` 和 `Post`。`Post` 默认 `language` 为 `gremlin-groovy`，根据 `GraphSpace` 和 `Graph` 自动填充 `graph`/`g` aliases，并在 `Data` 中返回解析后的结果；`Get` 只返回状态码，并把原始响应打印到 stdout。 |

每个操作都通过挂在操作本身上的 `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）。

```go
resp, err := client.Gremlin.Post(
	client.Gremlin.Post.WithGremlin("g.V().limit(3)"),
)
if err != nil {
	log.Fatal(err)
}
defer resp.Body.Close()
if resp.StatusCode < 200 || resp.StatusCode >= 300 {
	log.Fatalf("HugeGraph returned HTTP %d", resp.StatusCode)
}
if resp.Data.Status.Code < 200 || resp.Data.Status.Code >= 300 {
	log.Fatalf("Gremlin returned status %d: %s", resp.Data.Status.Code, resp.Data.Status.Message)
}
fmt.Println(resp.Data.Result.Data)
```

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

完整调用方式可参考各 API 目录中的测试，例如 [`version_test.go`](https://github.com/apache/hugegraph-toolchain/blob/master/hugegraph-client-go/api/v1/version_test.go)、[`gemlin_test.go`](https://github.com/apache/hugegraph-toolchain/blob/master/hugegraph-client-go/api/v1/gremlin/gemlin_test.go) 和 [`vertexlabel_test.go`](https://github.com/apache/hugegraph-toolchain/blob/master/hugegraph-client-go/api/v1/vertexlabel/vertexlabel_test.go)。

---

反链：

- [客户端/SDK](/cn/docs/clients/client/)
- [Java 客户端](/cn/docs/clients/client/hugegraph-client/)
- [系统介绍](/cn/docs/introduction/)