删除文档

README.md

@@ -1,684 +1 @@
-# 数据服务SDK使用文档
-
-数据服务设计意图是要统一管理各类数据源，数据服务SDK主要用于对接数据服务，目前仅实现了对数据库中PostgresSQL的支持。
-
-## 数据库操作
-
-### 入门
-
-可以通过sql包实现数据库的增删改查操作，使用sdk前，需要通过datactl在数据服务中预先创建好对应的Namespace，DataSource和
-
-DataContainer资源，demo使用的资源yaml如下所示：
-
-```yaml
-kind: Namespace
-spec:
-  name: ns-sdk-demo
-
----
-
-kind: DataSource
-spec:
-  type: database
-  namespace: ns-sdk-demo
-  name: ds-sdk-demo
-  spec:
-    type: postgres
-    user_name: test
-    password: "123456"
-    address: "10.0.0.84"
-    port: "30432"
-    database: test
-    max_connections: 40
-    max_idle_connections: 10
-
----
-
-kind: DataContainer
-spec:
-  namespace: ns-sdk-demo
-  data_source: ds-sdk-demo
-  name: dc-sdk-demo
-  spec:
-    table_name: test.classes
-    columns:
-      - name: id
-        type: varchar(32)
-        comment: id
-        primary_key: true
-      - name: name
-        type: varchar(128)
-        comment: 班名
-        not_null: true
-      - name: student_num
-        type: integer
-        comment: 学生数量
-        default: 60
-      - name: created_time
-        type: "timestamp with time zone"
-        comment: 创建时间
-        not_null: true
-      - name: last_updated_time
-        type: "timestamp with time zone"
-        comment: 最近更新时间
-        not_null: true
-```
-
-```go
-package main
-
-import (
-	"fmt"
-	"git.sxidc.com/service-supports/ds-sdk/sdk"
-	"git.sxidc.com/service-supports/ds-sdk/sql"
-	"git.sxidc.com/service-supports/ds-sdk/sql/sql_tpl"
-	"strconv"
-	"time"
-)
-
-const (
-	token      = "数据服务管理员分配的token"
-	address    = "数据服务地址"
-	httpPort   = "数据服务http端口"
-	grpcPort   = "数据服务grpc端口"
-	namespace  = "ns-sdk-demo"
-	dataSource = "ds-sdk-demo"
-	tableName  = "test.classes"
-)
-
-type Class struct {
-	ID              string
-	Name            string
-	StudentNum      int
-	CreatedTime     time.Time
-	LastUpdatedTime time.Time
-}
-
-type ClassInfo struct {
-	ID              string    `mapstructure:"id"`
-	Name            string    `mapstructure:"name"`
-	CreatedTime     time.Time `mapstructure:"created_time"`
-	LastUpdatedTime time.Time `mapstructure:"last_updated_time"`
-}
-
-func main() {
-	err := sdk.InitInstance(token, address, httpPort, grpcPort, namespace, dataSource)
-	if err != nil {
-		panic(err)
-	}
-
-	defer func() {
-		err := sdk.DestroyInstance()
-		if err != nil {
-			panic(err)
-		}
-	}()
-
-	class := &Class{
-		ID:         "id" + strconv.Itoa(time.Now().Nanosecond()),
-		Name:       "test",
-		StudentNum: 10,
-	}
-
-	err = sql.InsertEntity(sdk.GetInstance(), tableName, class)
-	if err != nil {
-		panic(err)
-	}
-
-	tableRow, err := sql.QueryOne(sdk.GetInstance(), &sql_tpl.QueryOneExecuteParams{
-		TableName:     tableName,
-		SelectColumns: []string{"id", "name", "created_time", "last_updated_time"},
-		Conditions:    sql_tpl.NewConditions().Equal("id", class.ID),
-	})
-	if err != nil {
-		panic(err)
-	}
-
-	fmt.Println(tableRow)
-
-	classInfo := new(ClassInfo)
-	err = sql.ParseSqlResults(tableRow, classInfo)
-	if err != nil {
-		panic(err)
-	}
-
-	fmt.Println(classInfo)
-
-	err = sql.DeleteEntity(sdk.GetInstance(), tableName, class)
-	if err != nil {
-		panic(err)
-	}
-}
-```
-
-代码中定义了需要用到的各类常量以及结构，Class结构作为数据库持久化的实体使用，ClassInfo则是作为查询结果的接受实体使用。
-
-sdk会利用Class字段，将Class字段名称变为蛇形后作为表的列名使用，如果字段名称转换后是id(字段名称是ID，Id等)，就会被作为主键使用，还可以通过sdk的
-sqlmapping Tag对字段含义进行扩充，稍后会对sqlmapping Tag进行说明。对命名为CreatedTime和LastUpdatedTime的字段，在没有赋值的情况下，sdk会自动添加创建时间和更新时间。
-
-Demo中的ClassInfo并不是必须的，sdk所有数据查询命令返回的是sdk.SqlResult或者[]sdk.SqlResult类型的数据，sdk.SqlResult实际就是map[string]any，但是提供了更方便的取值函数，其中map的key是列名，value是列值，
-sdk对mapstructure包进行了封装，如果程序需要，可以将查询结果转到一个添加了mapstructure Tag的结构上。mapstructure Tag的使用可以查看文档：
-
-https://pkg.go.dev/github.com/mitchellh/mapstructure
-
-Demo的main函数中，首先初始化了sdk实例，然后执行了插入操作，单查询操作和删除操作。
-
-### 事务的使用
-
-sdk提供了事务操作，可以参考下面的代码：
-
-```go
-package main
-
-import (
-	"git.sxidc.com/service-supports/ds-sdk/sdk"
-	"git.sxidc.com/service-supports/ds-sdk/sql"
-	"strconv"
-	"time"
-)
-
-const (
-	token      = "数据服务管理员分配的token"
-	address    = "数据服务地址"
-	httpPort   = "数据服务http端口"
-	grpcPort   = "数据服务grpc端口"
-	namespace  = "ns-sdk-demo"
-	dataSource = "ds-sdk-demo"
-	tableName  = "test.classes"
-)
-
-type Class struct {
-	ID              string
-	Name            string
-	StudentNum      int
-	CreatedTime     time.Time
-	LastUpdatedTime time.Time
-}
-
-func main() {
-	err := sdk.InitInstance(token, address, httpPort, grpcPort, namespace, dataSource)
-	if err != nil {
-		panic(err)
-	}
-
-	defer func() {
-		err := sdk.DestroyInstance()
-		if err != nil {
-			panic(err)
-		}
-	}()
-
-	class := &Class{
-		ID:         "id" + strconv.Itoa(time.Now().Nanosecond()),
-		Name:       "test",
-		StudentNum: 10,
-	}
-
-	err = sdk.GetInstance().Transaction(func(tx *sdk.Transaction) error {
-		err = sql.InsertEntity(tx, tableName, class)
-		if err != nil {
-			panic(err)
-		}
-
-		err = sql.DeleteEntity(tx, tableName, class)
-		if err != nil {
-			panic(err)
-		}
-
-		return nil
-	})
-	if err != nil {
-		panic(err)
-	}
-}
-```
-
-使用事务仅需要调用sdk实例的Transaction函数即可，在事务函数中，将sql包函数的第一个参数(Executor接口)替换为tx即可，这样也方便于实现非事务操作向事务操作的转换，
-如果在事务函数中需要查询，则可以继续使用sdk实例进行查询当前数据库中的数据(不过查询不到事务前面步骤的结果，这里为了防止不必要错误的发生，tx没有提供查询的方法)。
-
-### sqlmapping Tag
-
-可以使用sqlmapping Tag对实体字段进行更多扩展，下面的例子使用了sqlmapping Tag:
-
-```go
-type Class struct {
-	ID              string
-	Name            string `sqlmapping:"updateClear;"`
-	StudentNum      int    `sqlmapping:"column:student_num;notUpdate;"`
-	CreatedTime     *time.Time
-	LastUpdatedTime time.Time
-	Ignored         string `sqlmapping:"-"`
-}
-```
-
-对Name字段添加了updateClear，这里允许将数据库的name列更新为零值(默认如果该字段是零值，则不执行更新)，对StudentNum字段添加了
-column和notUpdate两个sqlmapping Tag，column指定了该字段对应的数据库列，notUpdate则禁止了对student_num列的更新。Ignored字段则通过sqlmapping的
-'-' Tag标定为不进行持久化的字段。
-
-下面是sqlmapping Tag支持的所有Tag:
-
-| Tag         | 说明                                                                                           |
-|-------------|----------------------------------------------------------------------------------------------|
-| -           | 忽略该字段，不进行持久化(不对应任何数据库表列)                                                                     |
-| column      | 显式指定该字段对应的数据库表列，如column:foo                                                                  |
-| key         | 该列是否作为逻辑键(实际到底哪个字段为键，是由DataContainer定义确定的)使用，如果一个结构的多个字段使用了key，这几个字段将被作为联合键使用                |
-| notUpdate   | 不对该列进行更新操作                                                                                   |
-| updateClear | 允许将该列清空为零值                                                                                   |
-| aes         | 进行aes加密并传递aes的密钥，密钥长度为32字节，不能包含';'，也不能以'作为开始和结尾字符                                            |
-| joinWith    | 字段如果是[]string，可以指定join使用的分隔符，不能包含';'，默认是'::'，如果使用特殊字符，如'\n'，'\t'等，需要使用''包含分隔符，也就是说，分隔符不能使用'' |
-
-### sqlresult Tag
-
-可以使用sqlresult Tag将查询结果转化到实体上，sqlresult Tag:
-
-```go
-type Class struct {
-    ID                string
-    Name              string
-    StudentNum        int    `sqlresult:"column:student_num"`
-    GraduatedTime     time.Time
-    CreatedTime       *time.Time
-    LastUpdatedTime   time.Time
-    Ignored           string `sqlresult:"-"`
-    GraduatedTimeTest string `sqlresult:"column:graduated_time;parseTime:2006-01-02 15:04:05"`
-	HasStudent        bool   `sqlresult:"column:student_num"`
-}
-```
-
-对StudentNum字段添加了'column' Tag，column指定了该字段对应的数据库列。Ignored字段则通过sqlresult的'-' Tag标定为不进行持久化的字段。
-GraduatedTimeTest字段通过添加'column'和'parseTime'两个Tag，将graduated_time格式化为规定的时间类型。HasStudent则通过将字段定义为bool类型，
-借用了sqlresult Tag的副作用，检查student_num列是否为零值来生成bool值
-
-下面是sqlresult Tag支持的所有Tag:
-
-| Tag       | 说明                                                                                            |
-|-----------|-----------------------------------------------------------------------------------------------|
-| -         | 忽略该字段，不进行持久化(不对应任何数据库表列)                                                                      |
-| column    | 显式指定该字段对应的数据库表列，如column:foo                                                                   |
-| parseTime | 按照给定的时间格式化字符串格式化时间                                                                            |
-| aes       | 进行aes加密并传递aes的密钥，密钥长度为32字节，不能包含';'，也不能以'作为开始和结尾字符                                             |
-| splitWith | 字段如果是[]string，可以指定split使用的分隔符，不能包含';'，默认是'::'，如果使用特殊字符，如'\n'，'\t'等，需要使用''包含分隔符，也就是说，分隔符不能使用'' |
-
-### SQL语句执行
-
-sdk还提供了直接执行SQL语句的函数和方法，主要有两个：ExecuteRawSql和ExecuteSql。
-
-ExecuteRawSql执行一条SQL语句，该语句可以用Golang的模板编写，执行时可以通过传递执行参数渲染模板；
-ExecuteSql则执行一个SQL资源(提前在数据服务中创建)，也可以传递模板参数，还可以使用每一步SQL执行语句后的结果。
-
-### sql包说明
-
-```go
-type Executor interface {
-	ExecuteRawSql(sql string, executeParams map[string]any) ([]sdk.SqlResult, error)
-	ExecuteSql(name string, executeParams map[string]any) ([]sdk.SqlResult, error)
-}
-```
-
-SQL执行器接口定义，在sdk中，SDK和事务都实现了该接口
-
-```go
-func InsertEntity[T any](executor Executor, tableName string, e T) error
-```
-
-通过实体插入数据
-
-参数：
-
-executor: 执行器
-
-tableName: 要操作的表名
-
-e: 实体，需要持久化的字段应该都赋值
-
-返回值: 
-
-是否出现错误
-
-```go
-func DeleteEntity[T any](executor Executor, tableName string, e T) error
-```
-
-通过实体删除数据
-
-参数：
-
-executor: 执行器
-
-tableName: 要操作的表名
-
-e: 实体，仅赋值key字段即可
-
-返回值:
-
-是否出现错误
-
-```go
-func UpdateEntity[T any](executor Executor, tableName string, e T) error
-```
-
-通过实体更新数据
-
-参数：
-
-executor: 执行器
-
-tableName: 要操作的表名
-
-e: 实体，仅赋值key字段和需要更新的字段即可
-
-返回值:
-
-是否出现错误
-
-```go
-func Insert(executor Executor, executeParams *sql_tpl.InsertExecuteParams) error
-```
-
-通过简化的INSERT语句插入数据，简化的INSERT语句：
-
-```go
-const InsertTpl = `
-INSERT INTO
-    {{ .table_name }} ({{ .columns | join "," }})
-VALUES
-    ({{ .values | join "," }})
-`
-```
-
-参数：
-
-executor: 执行器
-
-executeParams: 插入操作需要的参数，如下所示
-
-```go
-type InsertExecuteParams struct {
-	TableName string
-	*TableRow
-}
-```
-
-TableRow可以通过sql_tpl中的NewTableRow()函数创建，其中Add方法可以用来添加列
-
-返回值:
-
-是否出现错误
-
-```go
-func Delete(executor Executor, executeParams *sql_tpl.DeleteExecuteParams) error
-```
-
-通过简化的DELETE语句删除数据，简化的DELETE语句：
-
-```go
-const DeleteTpl = `
-DELETE FROM
-    {{ .table_name }}
-WHERE
-    {{ range .conditions }} {{ . }} AND {{ end }} 1 = 1
-`
-```
-
-参数：
-
-executor: 执行器
-
-executeParams: 删除操作需要的参数，如下所示
-
-```go
-type DeleteExecuteParams struct {
-    TableName string
-    *Conditions
-}
-```
-
-Conditions可以通过sql_tpl中的NewConditions()函数创建，其中有各种条件可供使用，如Equal，Like等
-
-返回值:
-
-是否出现错误
-
-```go
-func Update(executor Executor, executeParams *sql_tpl.UpdateExecuteParams) error
-```
-
-通过简化的UPDATE语句更新数据，简化的DELETE语句：
-
-```go
-const UpdateTpl = `
-UPDATE
-    {{ .table_name }}
-SET
-    {{ .set_list | join "," }}
-WHERE
-    {{ range .conditions }} {{ . }} AND {{ end }} 1 = 1
-`
-```
-
-参数：
-
-executor: 执行器
-
-executeParams: 更新操作需要的参数，如下所示
-
-```go
-type UpdateExecuteParams struct {
-    TableName string
-    *TableRow
-    *Conditions
-}
-```
-
-TableRow可以通过sql_tpl中的NewTableRow()函数创建，其中Add方法可以用来添加列
-
-Conditions可以通过sql_tpl中的NewConditions()函数创建，其中有各种条件可供使用，如Equal，Like等
-
-返回值:
-
-是否出现错误
-
-```go
-func Query(executor Executor, executeParams *sql_tpl.QueryExecuteParams) ([]sdk.SqlResult, int64, error)
-```
-
-通过简化的SELETE语句查询数据，简化的SELETE语句：
-
-```go
-const QueryTpl = `
-SELECT
-    {{ if .select_columns }}{{ .select_columns | join "," }}{{ else }}*{{ end }} 
-FROM
-    {{ .table_name }}
-WHERE
-    {{ range .conditions }} {{ . }} AND {{ end }} 1 = 1 
-{{ if .limit }}LIMIT {{ .limit }}{{ end }}
-{{ if .offset }}OFFSET {{ .offset }}{{ end }}
-`
-```
-
-参数：
-
-executor: 执行器
-
-executeParams: 查询操作需要的参数，如下所示
-
-```go
-type QueryExecuteParams struct {
-    TableName     string
-    SelectColumns []string
-    *Conditions
-    PageNo   int
-    PageSize int
-}
-```
-
-Conditions可以通过sql_tpl中的NewConditions()函数创建，其中有各种条件可供使用，如Equal，Like等
-
-返回值:
-
-查询结果
-
-总数
-
-是否出现错误
-
-```go
-func QueryOne(executor Executor, executeParams *sql_tpl.QueryOneExecuteParams) (sdk.SqlResult, error)
-```
-
-通过简化的SELETE语句执行单查询
-
-参数：
-
-executor: 执行器
-
-executeParams: 查询操作需要的参数，如下所示
-
-```go
-type QueryOneExecuteParams struct {
-    TableName     string
-    SelectColumns []string
-    *Conditions
-}
-```
-
-Conditions可以通过sql_tpl中的NewConditions()函数创建，其中有各种条件可供使用，如Equal，Like等
-
-返回值:
-
-查询结果
-
-是否出现错误
-
-```go
-func Count(executor Executor, executeParams *sql_tpl.CountExecuteParams) (int64, error)
-```
-
-通过简化的COUNT语句执行计数，简化的COUNT语句
-
-```go
-const CountTpl = `
-SELECT
-    COUNT(*)
-FROM
-    {{ .table_name }}
-WHERE
-    {{ range .conditions }} {{ . }} AND {{ end }} 1 = 1
-`
-```
-
-参数：
-
-executor: 执行器
-
-executeParams: 计数操作需要的参数，如下所示
-
-```go
-type CountExecuteParams struct {
-    TableName string
-    *Conditions
-}
-```
-
-Conditions可以通过sql_tpl中的NewConditions()函数创建，其中有各种条件可供使用，如Equal，Like等
-
-返回值:
-
-计数结果
-
-是否出现错误
-
-```go
-func CheckExist(executor Executor, executeParams *sql_tpl.CheckExistExecuteParams) (bool, error)
-```
-
-通过简化的COUNT语句执行存在性检查
-
-参数：
-
-executor: 执行器
-
-executeParams: 检查操作需要的参数，如下所示
-
-```go
-type CheckExistExecuteParams struct {
-    TableName string
-    *Conditions
-}
-```
-
-Conditions可以通过sql_tpl中的NewConditions()函数创建，其中有各种条件可供使用，如Equal，Like等
-
-返回值:
-
-是否存在的结果
-
-是否出现错误
-
-```go
-func CheckHasOnlyOne(executor Executor, executeParams *sql_tpl.CheckHasOnlyOneExecuteParams) (bool, error)
-```
-
-通过简化的COUNT语句执行唯一性检查
-
-参数：
-
-executor: 执行器
-
-executeParams: 检查操作需要的参数，如下所示
-
-```go
-type CheckHasOnlyOneExecuteParams struct {
-    TableName string
-    *Conditions
-}
-```
-
-Conditions可以通过sql_tpl中的NewConditions()函数创建，其中有各种条件可供使用，如Equal，Like等
-
-返回值:
-
-是否唯一的结果
-
-是否出现错误
-
-```go
-func ExecuteRawSql(executor Executor, sql string, executeParams map[string]any) ([]sdk.SqlResult, error)
-```
-
-执行SQL语句
-
-参数：
-
-executor: 执行器
-
-sql: SQL语句，可以使用Golang模板语法编写
-
-executeParams: 检查操作需要的参数，如下所示
-
-返回值:
-
-执行结果，对于写操作，结果为空，对于读操作，为读出的数据
-
-是否出现错误
-
-```go
-func ExecuteSql(executor Executor, name string, executeParams map[string]any) ([]sdk.SqlResult, error)
-```
-
-执行SQL语句
-
-参数：
-
-executor: 执行器
-
-name: 数据服务的SQL资源名称
-
-executeParams: 检查操作需要的参数，如下所示
-
-返回值:
-
-执行结果，对于写操作，结果为空，对于读操作，为读出的数据
-
-是否出现错误
+# 数据服务SDK