From 85cb4144b9fb1d79550e4697cebd0f0b61abd27c Mon Sep 17 00:00:00 2001
From: Himanshu Verma <himnshuverma10152006@gmail.com>
Date: Sat, 5 Sep 2026 23:52:45 +0530
Subject: [PATCH] doc(toolchain): sync client-go with master

Fix the GraphSpace and edge API claims, document Config fields and the
hgtransport loggers, and list the exact operations behind each entry point.
---
 .../quickstart/client/hugegraph-client-go.md  | 71 ++++++++++++++++---
 .../quickstart/client/hugegraph-client-go.md  | 71 ++++++++++++++++---
 2 files changed, 124 insertions(+), 18 deletions(-)

diff --git a/content/cn/docs/quickstart/client/hugegraph-client-go.md b/content/cn/docs/quickstart/client/hugegraph-client-go.md
index 4a89aa262..8e7b90f65 100644
--- a/content/cn/docs/quickstart/client/hugegraph-client-go.md
+++ b/content/cn/docs/quickstart/client/hugegraph-client-go.md
@@ -4,7 +4,7 @@ linkTitle: "Go 客户端"
 weight: 3
 ---
 
-HugeGraph Go Client 是 Toolchain 仓库中的 Go SDK，目前提供版本查询、Schema、顶点、边和 Gremlin API。
+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) 下的源码为准。
 
@@ -23,7 +23,9 @@ go get github.com/apache/hugegraph-toolchain/hugegraph-client-go
 
 ## 初始化客户端
 
-`NewCommonClient` 要求 `Host` 是 IP 地址；未启用认证时，用户名和密码留空。当前 Server 的图资源路径包含图空间，默认填写 `DEFAULT`。将 `GraphSpace` 留空只适用于仍使用 `/graphs/{graph}` 路径的旧版 Server。
+`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}` 路径。
 
 ```go
 package main
@@ -58,7 +60,44 @@ func main() {
 }
 ```
 
-`Version()` 返回的 `Versions` 包含 HugeGraph Server、Core、Gremlin 和 REST API 版本。若使用源码提供的 `NewDefaultCommonClient()`，默认连接 `127.0.0.1:8080` 下的 `hugegraph` 图，并使用 `admin`/`pa` 认证；生产代码通常应显式传入配置。
+`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` API 和 Gremlin 默认 aliases 使用；不需要时填空字符串 |
+| `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,
+	},
+})
+```
 
 ## 已实现的入口
 
@@ -68,10 +107,24 @@ func main() {
 |---|---|
 | `Version()` | 查询服务端版本 |
 | `Schema()` | 查询完整 Schema |
-| `Propertykey` | 管理 PropertyKey |
-| `VertexLabel` | 管理 VertexLabel |
-| `EdgeLabel` | 管理 EdgeLabel |
-| `Vertex` | 创建、批量创建和更新顶点属性 |
-| `Gremlin` | 通过 GET 或 POST 执行 Gremlin |
+| `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(...)`。
+
+```go
+resp, err := client.Gremlin.Post(
+	client.Gremlin.Post.WithGremlin("g.V().limit(3)"),
+)
+if err != nil {
+	log.Fatal(err)
+}
+fmt.Println(resp.StatusCode, resp.Data.Status.Code, 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) 和 [`vertexlabel_test.go`](https://github.com/apache/hugegraph-toolchain/blob/master/hugegraph-client-go/api/v1/vertexlabel/vertexlabel_test.go)。
+完整调用方式可参考各 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)。
diff --git a/content/en/docs/quickstart/client/hugegraph-client-go.md b/content/en/docs/quickstart/client/hugegraph-client-go.md
index aaeb72793..d2cf34653 100644
--- a/content/en/docs/quickstart/client/hugegraph-client-go.md
+++ b/content/en/docs/quickstart/client/hugegraph-client-go.md
@@ -4,7 +4,7 @@ linkTitle: "Go Client"
 weight: 3
 ---
 
-HugeGraph Go Client is the Go SDK in the Toolchain repository. It currently provides APIs for version queries, schemas, vertices, edges, and Gremlin.
+HugeGraph Go Client is the Go SDK in the Toolchain repository. It currently provides APIs for version queries, schemas (property keys, vertex labels, and edge labels), vertices, and Gremlin. An edge data API is not implemented yet.
 
 > This module is still under development. Refer to the source code under [`hugegraph-client-go/api/v1`](https://github.com/apache/hugegraph-toolchain/tree/master/hugegraph-client-go/api/v1) for the currently available interfaces.
 
@@ -23,7 +23,9 @@ go get github.com/apache/hugegraph-toolchain/hugegraph-client-go
 
 ## Initialize the Client
 
-`NewCommonClient` requires `Host` to be an IP address. Leave the username and password empty when authentication is disabled. Current server graph resource paths include a graph space; use `DEFAULT` for the default space. Leaving `GraphSpace` empty applies only to older servers that still use the `/graphs/{graph}` path.
+`NewCommonClient` requires `Host` to be an IP address and `Port` to be between 1 and 65535. The client always connects over plain HTTP. Leave the username and password empty when authentication is disabled; Basic Auth is sent only when both are set.
+
+`GraphSpace` is applied only by the `Vertex` API, which then calls `/graphspaces/{space}/graphs/{graph}/...`, and by the default Gremlin aliases (an empty value is treated as `DEFAULT`). The schema entry points and `Version()` always call `/graphs/{graph}/...` and `/versions`, regardless of `GraphSpace`. Use `DEFAULT` for the default space; leaving `GraphSpace` empty makes the `Vertex` API fall back to the `/graphs/{graph}` path used by older servers.
 
 ```go
 package main
@@ -58,7 +60,44 @@ func main() {
 }
 ```
 
-The `Versions` value returned by `Version()` includes the HugeGraph Server, Core, Gremlin, and REST API versions. The `NewDefaultCommonClient()` helper in the source connects to the `hugegraph` graph at `127.0.0.1:8080` with `admin`/`pa` authentication. Production code should normally pass an explicit configuration instead.
+The `Versions` value returned by `Version()` includes the HugeGraph Server, Core, Gremlin, and REST API versions. The `NewDefaultCommonClient()` helper in the source connects to the `hugegraph` graph at `127.0.0.1:8080` with `admin`/`pa` authentication and a `ColorLogger` that prints every request and response body. Production code should normally pass an explicit configuration instead.
+
+## Configuration Options
+
+`hugegraph.Config` has the following fields:
+
+| Field | Type | Description |
+|---|---|---|
+| `Host` | `string` | HugeGraph Server IP address. Host names are rejected. |
+| `Port` | `int` | HugeGraph Server REST port, 1 to 65535 |
+| `GraphSpace` | `string` | Graph space; only used by the `Vertex` API and the default Gremlin aliases. Set an empty string when not needed. |
+| `Graph` | `string` | Graph name configured on the server |
+| `Username` | `string` | Server username; empty string when authentication is disabled |
+| `Password` | `string` | Server password; empty string when authentication is disabled |
+| `Transport` | `http.RoundTripper` | Custom HTTP transport; `http.DefaultTransport` when nil |
+| `Logger` | `hgtransport.Logger` | Request/response logger; no logging when nil |
+
+The `hgtransport` package ships four loggers: `TextLogger` (plain text), `ColorLogger` (terminal colors), `CurlLogger` (runnable curl commands), and `JSONLogger` (JSON lines). Each has the same fields: `Output` (an `io.Writer`), `EnableRequestBody`, and `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,
+	},
+})
+```
 
 ## Available Entry Points
 
@@ -68,10 +107,24 @@ The `Versions` value returned by `Version()` includes the HugeGraph Server, Core
 |---|---|
 | `Version()` | Query the server version |
 | `Schema()` | Query the complete schema |
-| `Propertykey` | Manage property keys |
-| `VertexLabel` | Manage vertex labels |
-| `EdgeLabel` | Manage edge labels |
-| `Vertex` | Create vertices in single or batch mode and update vertex properties |
-| `Gremlin` | Execute Gremlin through GET or POST |
+| `Propertykey` | `Create`, `GetAll`, `GetByName`, `UpdateUserdata`, `DeleteByName` |
+| `VertexLabel` | `Create`, `GetAll`, `GetByName`, `UpdateUserdata`, `DeleteByName` |
+| `EdgeLabel` | `Create`, `GetAll`, `DeleteByName` |
+| `Vertex` | `Create`, `BatchCreate`, `UpdateProperties` (with `WithAction`: `append` or `eliminate`) |
+| `Gremlin` | `Get` and `Post`. `Post` defaults `language` to `gremlin-groovy`, fills the `graph`/`g` aliases from `GraphSpace` and `Graph`, and returns the parsed result in `Data`. `Get` only returns the status code and prints the raw response to stdout. |
+
+Each operation takes functional options named `With...` on the operation itself, for example `client.Gremlin.Post.WithGremlin(...)` or `client.Propertykey.GetByName.WithName(...)`.
+
+```go
+resp, err := client.Gremlin.Post(
+	client.Gremlin.Post.WithGremlin("g.V().limit(3)"),
+)
+if err != nil {
+	log.Fatal(err)
+}
+fmt.Println(resp.StatusCode, resp.Data.Status.Code, resp.Data.Result.Data)
+```
+
+> The `Vertex` operations take `model.Vertex[any]` values from the `internal/model` package. Go does not allow importing an `internal` package from another module, so at the moment the `Vertex` API can only be called from code inside the client module itself; its test file is also fully commented out.
 
-For complete usage, see the tests in each API directory, such as [`version_test.go`](https://github.com/apache/hugegraph-toolchain/blob/master/hugegraph-client-go/api/v1/version_test.go) and [`vertexlabel_test.go`](https://github.com/apache/hugegraph-toolchain/blob/master/hugegraph-client-go/api/v1/vertexlabel/vertexlabel_test.go).
+For complete usage, see the tests in each API directory, such as [`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), and [`vertexlabel_test.go`](https://github.com/apache/hugegraph-toolchain/blob/master/hugegraph-client-go/api/v1/vertexlabel/vertexlabel_test.go).