docs: refine Go connector page (#11753)

* docs: refine Go connector page

* docs: refine Go connector page

* docs: refine Go connector page

* docs: refine Go connector page

docs-cn/14-reference/03-connector/go.mdx

@@ -4,135 +4,153 @@ sidebar_label: Go
 title: Go Connector
 ---
 
-## 安装准备
+## 总体介绍
 
-Go 连接器支持的系统有：
+driver-go 实现 Go [database/sql](https://golang.org/pkg/database/sql/) 包的 TDengine 驱动程序，同时提供通过本地的客户端驱动程序直接与服务端程序 taosd 进行订阅、 schemaless 写入和 stmt 功能。
 
-| **CPU 类型** | x64（64bit） |          |          | aarch64  | aarch32    |
-| ------------ | ------------ | -------- | -------- | -------- | ---------- |
-| **OS 类型**  | Linux        | Win64    | Win32    | Linux    | Linux      |
-| **支持与否** | **支持**     | **支持** | **支持** | **支持** | **支持** |
+Go 连接器的源码托管在 github。项目名称：driver-go。欢迎 [贡献源码](https://github.com/taosdata/driver-go) 或 [报告问题](https://github.com/taosdata/driver-go/issues)。
 
-安装前准备：已安装好 TDengine 应用驱动，参考[安装连接器驱动步骤](/reference/connector)。
+## 支持的平台
 
-## 示例程序
+| **CPU 类型** | x64（64bit） |        |        | aarch64 | aarch32 |
+|------------|------------|--------|--------|---------|---------|
+| **OS 类型**  | Linux      | Win64  | Win32  | Linux   | Linux   |
+| **支持与否**   | **支持**     | **支持** | **支持** | **支持**  | **支持**  |
 
-使用 Go 连接器的示例代码请参考 [https://github.com/taosdata/TDengine/tree/develop/examples/go](https://github.com/taosdata/TDengine/tree/develop/examples/go) 以及[视频教程](https://www.taosdata.com/blog/2020/11/11/1951.html)。
+## 版本支持
 
-示例程序源码也位于安装目录下的 examples/go/taosdemo.go 文件中。
+|   分支    |                      功能                       | 建议 taosd 版本 |
+|:-------:|:---------------------------------------------:|:-----------:|
+| master  |    database/sql（cgo）、订阅、schemaless写入、stmt     | 2.2.0.0 及以上 |
+| develop | database/sql（cgo & REST）、订阅、schemaless写入、stmt | 2.4.0.4及以上  |
 
-:::tip
-建议 Go 版本是 1.13 及以上，并开启模块支持：
-:::
+## 支持的特性
 
-```sh
-go env -w GO111MODULE=on
-go env -w GOPROXY=https://goproxy.io,direct
-```
+### 本地连接
 
-在 taosdemo.go 所在目录下进行编译和执行：
+`本地连接` 指连接器通过本地的客户端驱动程序直接与服务端程序 taosd 建立连接。
 
-```sh
-go mod init taosdemo
-go get github.com/taosdata/driver-go/taosSql
-# use win branch in Windows platform.
-#go get github.com/taosdata/driver-go/taosSql@win
-go build
-./taosdemo -h fqdn -p serverPort
-```
+* database/sql (cgo 模式)
+* 订阅
+* schemaless
+* stmt
 
-## Go 连接器的使用
+### REST 连接
 
-TDengine 提供了 GO 驱动程序包`taosSql`。`taosSql` 实现了 GO 语言的内置接口 `database/sql/driver`。用户只需按如下方式引入包就可以在应用程序中访问 TDengine。
+REST 连接指连接器通过 taosAdapter 组件提供的 REST API 建立与 taosd 的连接。
 
-```go
-import (
-  "database/sql"
-  _ "github.com/taosdata/driver-go/v2/taosSql"
-)
-```
+`develop` 分支使用 `http client` 实现了 `database/sql` 接口。
 
-:::tip
-下划线与双引号之间必须有一个空格。
+## 安装步骤
 
-:::
+### 安装前的准备
 
-`taosSql` 的 v2 版本进行了重构，分离出内置数据库操作接口 `database/sql/driver` 到目录 `taosSql`；订阅、 stmt 等其他功能放到目录 `af`。
+* taos本地的客户端
+* Go 1.14 及以上
+* GCC 4.8.5 及以上
 
-## 常用 API
+配置好环境变量，检查命令：
 
-- `sql.Open(DRIVER_NAME string, dataSourceName string) *DB`
+* ```go env```
+* ```gcc -v```
 
-  该 API 用来打开 DB，返回一个类型为\*DB 的对象，一般情况下，DRIVER_NAME 设置为字符串 `taosSql`，dataSourceName 设置为字符串 `user:password@/tcp(host:port)/dbname`，如果客户想要用多个 goroutine 并发访问 TDengine, 那么需要在各个 goroutine 中分别创建一个 sql.Open 对象并用之访问 TDengine。
+### 使用 go get 安装
 
-  **注意**： 该 API 成功创建的时候，并没有做权限等检查，只有在真正执行 Query 或者 Exec 的时候才能真正的去创建连接，并同时检查 user/password/host/port 是不是合法。另外，由于整个驱动程序大部分实现都下沉到 taosSql 所依赖的 libtaos 动态库中。所以，sql.Open 本身特别轻量。
+`go get -u github.com/taosdata/driver-go/v2@develop`
 
-- `func (db *DB) Exec(query string, args ...interface{}) (Result, error)`
+## 建立连接
 
-sql.Open 内置的方法，用来执行非查询相关 SQL
+### DSN
 
-- `func (db *DB) Query(query string, args ...interface{}) (*Rows, error)`
+数据源名称具有通用格式，例如 [PEAR DB](http://pear.php.net/manual/en/package.database.db.intro-dsn.php)，但没有类型前缀（方括号表示可选）：
 
-sql.Open 内置的方法，用来执行查询语句
+``` text
+[username[:password]@][protocol[(address)]]/[dbname][?param1=value1&...&paramN=valueN]
+```
 
-- `func (db *DB) Prepare(query string) (*Stmt, error)`
+完整形式的 DSN：
 
-  sql.Open 内置的方法，Prepare creates a prepared statement for later queries or executions.
+```text
+username:password@protocol(address)/dbname?param=value
+```
 
-- `func (s *Stmt) Exec(args ...interface{}) (Result, error)`
+### 建立本地连接
 
-  sql.Open 内置的方法，executes a prepared statement with the given arguments and returns a Result summarizing the effect of the statement.
+_taosSql_ 通过 cgo 实现了 Go 的 `database/sql/driver` 接口。只需要引入驱动就可以使用[`database/sql`](https://golang.org/pkg/database/sql/)的接口。
 
-- `func (s *Stmt) Query(args ...interface{}) (*Rows, error)`
+使用 `taosSql` 作为 `driverName` 并且使用一个正确的 [DSN](#DSN) 作为 `dataSourceName`，DSN 支持的参数：
 
-  sql.Open 内置的方法，Query executes a prepared query statement with the given arguments and returns the query results as a \*Rows.
+* configPath 指定 taos.cfg 目录
 
-- `func (s *Stmt) Close() error`
+示例：
 
-  sql.Open 内置的方法，Close closes the statement.
+```go
+package main
 
-## 其他代码示例
+import (
+    "database/sql"
+    "fmt"
 
-[Consume Messages from Kafka](https://github.com/taosdata/go-demo-kafka) 是一个通过 Go 语言实现消费 Kafka 队列写入 TDengine 的示例程序，也可以作为通过 Go 连接 TDengine 的写法参考。
+    _ "github.com/taosdata/driver-go/v2/taosSql"
+)
 
-## Go RESTful 的使用
+func main() {
+    var taosUri = "root:taosdata/tcp(localhost:6030)/"
+    taos, err := sql.Open("taosSql", taosUri)
+    if err != nil {
+        fmt.Println("failed to connect TDengine, err:", err)
+        return
+    }
+}
+```
 
-### 引入
+### 建立 REST 连接
 
-```go restful
-import (
-  "database/sql"
-  _ "github.com/taosdata/driver-go/v2/taosRestful"
-)
-```
+_taosRestful_ 通过 `http client` 实现了 Go 的 `database/sql/driver` 接口。只需要引入驱动就可以使用[`database/sql`](https://golang.org/pkg/database/sql/)的接口。
 
-`go.mod ` 的文件 require 块使用  github.com/taosdata/driver-go/v2 develop  之后执行  `go mod tidy `
+使用 `taosRestful` 作为 `driverName` 并且使用一个正确的 [DSN](#DSN) 作为 `dataSourceName`，DSN 支持的参数：
 
-`sql.Open `的 driverName 为  `taosRestful`
+* `disableCompression` 是否接受压缩数据，默认为 true 不接受压缩数据，如果传输数据使用 gzip 压缩设置为 false。
+* `readBufferSize` 读取数据的缓存区大小默认为 4K（4096），当查询结果数据量多时可以适当调大该值。
 
-### DSN
+示例：
 
-格式为：
+```go
+package main
 
-数据库用户名:数据库密码@连接方式(域名或 ip:端口)/[数据库][?参数]
+import (
+    "database/sql"
+    "fmt"
 
-样例：
+    _ "github.com/taosdata/driver-go/v2/taosRestful"
+)
 
-`root:taosdata@http(localhost:6041)/test?readBufferSize=52428800`
+func main() {
+    var taosUri = "root:taosdata/http(localhost:6041)/"
+    taos, err := sql.Open("taosRestful", taosUri)
+    if err != nil {
+        fmt.Println("failed to connect TDengine, err:", err)
+        return
+    }
+}
+```
 
-参数：
+## 示例程序
 
-`disableCompression` 是否接受压缩数据，默认为 true 不接受压缩数据，如果传输数据使用 gzip 压缩设置为 false。
+使用 Go 连接器的示例代码请参考：
 
-`readBufferSize` 读取数据的缓存区大小默认为 4K(4096)，当查询结果数据量多时可以适当调大该值。
+* [示例程序](https://github.com/taosdata/TDengine/tree/develop/examples/go)
+* [视频教程](https://www.taosdata.com/blog/2020/11/11/1951.html)。
 
 ### 使用限制
 
-由于 RESTful 接口无状态所以 `use db` 语法不会生效，需要将 db 名称放到 SQL 语句中，如：`create table if not exists tb1 (ts timestamp, a int)`改为`create table if not exists test.tb1 (ts timestamp, a int)`否则将报错`[0x217] Database not specified or available`。
+由于 REST 接口无状态所以 `use db` 语法不会生效，需要将 db 名称放到 SQL 语句中，如：`create table if not exists tb1 (ts timestamp, a int)`改为`create table if not exists test.tb1 (ts timestamp, a int)`否则将报错`[0x217] Database not specified or available`。
+
+也可以将 db 名称放到 DSN 中，将 `root:taosdata@http(localhost:6041)/` 改为 `root:taosdata@http(localhost:6041)/test`，此方法在 TDengine 2.4.0.5 版本的 taosAdapter 开始支持。当指定的 db 不存在时执行 `create database` 语句不会报错，而执行针对该 db 的其他查询或写入操作会报错。
 
-也可以将 db 名称放到 DSN 中，将 `root:taosdata@http(localhost:6041)/` 改为 `root:taosdata@http(localhost:6041)/test`，此方法在 TDengine 2.4.0.5 版本的 taosAdapter 开始支持。当指定的 db 不存在时执行 `create database` 语句不会报错，而执行针对该 db 的其他查询或写入操作会报错。完整示例如下：
+完整示例如下：
 
-```go restful demo
+```go
 package main
 
 import (
@@ -182,30 +200,142 @@ func main() {
 
 ### 常见问题
 
-- 无法找到包`github.com/taosdata/driver-go/v2/taosRestful`
+* 无法找到包 `github.com/taosdata/driver-go/v2/taosRestful`
+
+将 `go.mod` 中 require 块对`github.com/taosdata/driver-go/v2`的引用改为`github.com/taosdata/driver-go/v2 develop`，之后执行 `go mod tidy`。
+
+* database/sql 中 stmt 相关接口崩溃
+
+REST 不支持 stmt 相关接口，建议使用`db.Exec`和`db.Query`。
+
+* 使用 `use db` 语句后执行其他语句报错 `[0x217] Database not specified or available`
+
+在 REST 接口中 SQL 语句的执行无上下文关联，使用 `use db` 语句不会生效，解决办法见上方使用限制章节。
+
+* 使用 taosSql 不报错使用 taosRestful 报错 `[0x217] Database not specified or available`
+
+因为 REST 接口无状态，使用 `use db` 语句不会生效，解决办法见上方使用限制章节。
+
+* 升级 `github.com/taosdata/driver-go/v2/taosRestful`
+
+将 `go.mod` 文件中对 `github.com/taosdata/driver-go/v2` 的引用改为 `github.com/taosdata/driver-go/v2 develop`，之后执行 `go mod tidy`。
+
+* `readBufferSize` 参数调大后无明显效果
+
+`readBufferSize` 调大后会减少获取结果时 `syscall` 的调用。如果查询结果的数据量不大，修改该参数不会带来明显提升，如果该参数修改过大，瓶颈会在解析 JSON 数据。如果需要优化查询速度，需要根据实际情况调整该值来达到查询效果最优。
+
+* `disableCompression` 参数设置为 `false` 时查询效率降低
+
+当 `disableCompression` 参数设置为 `false` 时查询结果会使用 `gzip` 压缩后传输，拿到数据后要先进行 `gzip` 解压。
+
+* `go get` 命令无法获取包，或者获取包超时
+
+设置 Go 代理 `go env -w GOPROXY=https://goproxy.cn,direct`。
+
+## API
+
+全部 API 见 [driver-go 文档](https://pkg.go.dev/github.com/taosdata/driver-go/v2)
+
+### 常用 API
+
+#### `database/sql`
+
+* `sql.Open(DRIVER_NAME string, dataSourceName string) *DB`
+
+该 API 用来打开 DB，返回一个类型为 \*DB 的对象。
+
+**注意**： 该 API 成功创建的时候，并没有做权限等检查，只有在真正执行 Query 或者 Exec 的时候才能真正的去创建连接，并同时检查 user/password/host/port 是不是合法。
+
+* `func (db *DB) Exec(query string, args ...interface{}) (Result, error)`
+
+`sql.Open` 内置的方法，用来执行非查询相关 SQL。
+
+* `func (db *DB) Query(query string, args ...interface{}) (*Rows, error)`
+
+`sql.Open` 内置的方法，用来执行查询语句。
+
+#### 高级功能
+
+af 包封装了订阅、stmt 等 TDengine 高级功能。
+
+* `af.Open(host, user, pass, db string, port int) (*Connector, error)`
+
+该 API 通过 cgo 创建与 taosd 的连接。
+
+* `func (conn *Connector) Close() error`
+
+关闭与 taosd 的连接。
+
+* `func (conn *Connector) StmtExecute(sql string, params *param.Param) (res driver.Result, err error)`
+
+stmt 单行插入。
+
+* `func (conn *Connector) StmtQuery(sql string, params *param.Param) (rows driver.Rows, err error)`
+
+stmt 查询，返回 `database/sql/driver` 包的 `Rows` 结构。
+
+##### 订阅
+
+* `func (conn *Connector) Subscribe(restart bool, topic string, sql string, interval time.Duration) (Subscriber, error)`
+
+订阅数据。
+
+* `func (s *taosSubscriber) Consume() (driver.Rows, error)`
+
+消费订阅数据，返回 `database/sql/driver` 包的 `Rows` 结构。
+
+* `func (s *taosSubscriber) Unsubscribe(keepProgress bool)`
+
+取消订阅数据。
+
+##### schemaless 写入
+
+* `func (conn *Connector) InfluxDBInsertLines(lines []string, precision string) error`
+
+写入 influxDB 行协议。
+
+* `func (conn *Connector) OpenTSDBInsertTelnetLines(lines []string) error`
+
+写入 OpenTDSB telnet 协议。
+
+* `func (conn *Connector) OpenTSDBInsertJsonPayload(payload string) error`
+
+写入 OpenTSDB json 协议。
+
+##### 批量 stmt 插入
+
+* `func (conn *Connector) InsertStmt() *insertstmt.InsertStmt`
+
+初始化 stmt。
+
+* `func (stmt *InsertStmt) Prepare(sql string) error`
+
+预处理 sql 语句。
+
+* `func (stmt *InsertStmt) SetTableName(name string) error`
 
-  将 `go.mod` 中 require 块对`github.com/taosdata/driver-go/v2`的引用改为`github.com/taosdata/driver-go/v2 develop`，之后执行 `go mod tidy`。
+设置表名。
 
-- stmt 相关接口崩溃
+* `func (stmt *InsertStmt) SetSubTableName(name string) error`
 
-  RESTful 不支持 stmt 相关接口，建议使用`db.Exec`和`db.Query`。
+设置子表名。
 
-- 使用 `use db` 语句后执行其他语句报错 `[0x217] Database not specified or available`
+* `func (stmt *InsertStmt) BindParam(params []*param.Param, bindType *param.ColumnType) error`
 
-  在 RESTful 接口中 SQL 语句的执行无上下文关联，使用 `use db` 语句不会生效，解决办法见上方使用限制章节。
+绑定多行数据。
 
-- 使用 taosSql 不报错使用 taosRestful 报错 `[0x217] Database not specified or available`
+* `func (stmt *InsertStmt) AddBatch() error`
 
-  因为 RESTful 接口无状态，使用 `use db` 语句不会生效，解决办法见上方使用限制章节。
+添加到批处理。
 
-- 升级 `github.com/taosdata/driver-go/v2/taosRestful`
+* `func (stmt *InsertStmt) Execute() error`
 
-  将 `go.mod` 文件中对 `github.com/taosdata/driver-go/v2` 的引用改为 `github.com/taosdata/driver-go/v2 develop`，之后执行 `go mod tidy`。
+执行 stmt。
 
-- readBufferSize 参数调大后无明显效果
+* `func (stmt *InsertStmt) GetAffectedRows() int`
 
-  readBufferSize 调大后会减少获取结果时 syscall 的调用。如果查询结果的数据量不大，修改该参数不会带来明显提升，如果该参数修改过大，瓶颈会在解析 JSON 数据。如果需要优化查询速度，需要根据实际情况调整该值来达到查询效果最优。
+获取受影响行数。
 
-- disableCompression 参数设置为 false 时查询效率降低
+* `func (stmt *InsertStmt) Close() error`
 
-  当 disableCompression 参数设置为 false 时查询结果会 gzip 压缩后传输，拿到数据后要先进行 gzip 解压。
+结束 stmt。