完成数据库文档编写

framework/core/infrastructure/database/database.go

@@ -12,9 +12,26 @@ import (
 	"time"
 )
 
+// Executor 数据库基础设施接口
 type Executor interface {
-	ExecuteRawSql(sql string, values ...any) ([]sql.Result, error)
-	ExecuteRawSqlTemplate(sql string, template map[string]any, values ...any) ([]sql.Result, error)
+	// ExecuteRawSql SQL执行接口
+	// 参数:
+	// - sql: SQL语句，可以使用预编译，需要填充的值用?占位
+	// - values: 预编译填充值
+	// 返回值:
+	// - SQL执行结果
+	// - 错误
+	ExecuteRawSql(sql string, args ...any) ([]sql.Result, error)
+
+	// ExecuteRawSqlTemplate SQL模板执行接口
+	// 参数:
+	// - sql: SQL语句模板，可以使用预编译，需要填充的值用?占位，可以使用Go模板构造SQL语句
+	// - template: 渲染SQL语句模板的模板参数
+	// - values: 预编译填充值
+	// 返回值:
+	// - SQL执行结果
+	// - 错误
+	ExecuteRawSqlTemplate(sql string, template map[string]any, args ...any) ([]sql.Result, error)
 }
 
 const (
@@ -22,6 +39,12 @@ const (
 	lastUpdatedTimeFieldName = "LastUpdatedTime"
 )
 
+// Transaction 执行事务
+// 参数:
+// - executor: 数据库基础设施接口
+// - txFunc: 事务函数
+// 返回值:
+// - 错误
 func Transaction(executor Executor, txFunc func(tx Executor) error) error {
 	if executor == nil {
 		return nil
@@ -47,6 +70,13 @@ func Transaction(executor Executor, txFunc func(tx Executor) error) error {
 	return nil
 }
 
+// InsertEntity 通过结构插入数据
+// 参数:
+// - executor: 数据库基础设施接口
+// - tableName: 表名
+// - es: 结构或结构slice(批量插入)，结构字段需要使用sqlmapping标注
+// 返回值:
+// - 错误
 func InsertEntity(executor Executor, tableName string, es any) error {
 	if executor == nil {
 		return errors.New("没有传递执行器")
@@ -169,6 +199,13 @@ func formInsertTableRow(fields []sql_mapping.Field, createTime time.Time) *sql.T
 	return tableRow
 }
 
+// DeleteEntity 通过结构删除数据
+// 参数:
+// - executor: 数据库基础设施接口
+// - tableName: 表名
+// - e: 结构，结构字段需要使用sqlmapping标注
+// 返回值:
+// - 错误
 func DeleteEntity(executor Executor, tableName string, e any) error {
 	if executor == nil {
 		return errors.New("没有传递执行器")
@@ -220,6 +257,13 @@ func DeleteEntity(executor Executor, tableName string, e any) error {
 	return nil
 }
 
+// UpdateEntity 通过结构更新数据
+// 参数:
+// - executor: 数据库基础设施接口
+// - tableName: 表名
+// - e: 结构，结构字段需要使用sqlmapping标注
+// 返回值:
+// - 错误
 func UpdateEntity(executor Executor, tableName string, e any) error {
 	if executor == nil {
 		return errors.New("没有传递执行器")
@@ -296,6 +340,12 @@ func UpdateEntity(executor Executor, tableName string, e any) error {
 	return nil
 }
 
+// Insert 插入数据
+// 参数:
+// - executor: 数据库基础设施接口
+// - executeParams: 插入数据参数
+// 返回值:
+// - 错误
 func Insert(executor Executor, executeParams *sql.InsertExecuteParams) error {
 	if executor == nil {
 		return errors.New("没有传递执行器")
@@ -318,6 +368,12 @@ func Insert(executor Executor, executeParams *sql.InsertExecuteParams) error {
 	return nil
 }
 
+// InsertBatch 批量插入数据
+// 参数:
+// - executor: 数据库基础设施接口
+// - executeParams: 批量插入数据参数
+// 返回值:
+// - 错误
 func InsertBatch(executor Executor, executeParams *sql.InsertBatchExecuteParams) error {
 	if executor == nil {
 		return errors.New("没有传递执行器")
@@ -345,6 +401,12 @@ func InsertBatch(executor Executor, executeParams *sql.InsertBatchExecuteParams)
 	return nil
 }
 
+// Delete 删除数据
+// 参数:
+// - executor: 数据库基础设施接口
+// - executeParams: 删除数据参数
+// 返回值:
+// - 错误
 func Delete(executor Executor, executeParams *sql.DeleteExecuteParams) error {
 	if executor == nil {
 		return errors.New("没有传递执行器")
@@ -367,6 +429,12 @@ func Delete(executor Executor, executeParams *sql.DeleteExecuteParams) error {
 	return nil
 }
 
+// Update 更新数据
+// 参数:
+// - executor: 数据库基础设施接口
+// - executeParams: 更新数据参数
+// 返回值:
+// - 错误
 func Update(executor Executor, executeParams *sql.UpdateExecuteParams) error {
 	if executor == nil {
 		return errors.New("没有传递执行器")
@@ -393,6 +461,14 @@ func Update(executor Executor, executeParams *sql.UpdateExecuteParams) error {
 	return nil
 }
 
+// Query 查询数据
+// 参数:
+// - executor: 数据库基础设施接口
+// - executeParams: 查询数据参数
+// 返回值:
+// - 查询结果
+// - 总数
+// - 错误
 func Query(executor Executor, executeParams *sql.QueryExecuteParams) ([]sql.Result, int64, error) {
 	if executor == nil {
 		return nil, 0, errors.New("没有传递执行器")
@@ -435,6 +511,13 @@ func Query(executor Executor, executeParams *sql.QueryExecuteParams) ([]sql.Resu
 	return results, int64(countTableRow[0]["count"].(float64)), nil
 }
 
+// QueryOne 查询单条数据
+// 参数:
+// - executor: 数据库基础设施接口
+// - executeParams: 查询单条数据参数
+// 返回值:
+// - 查询结果
+// - 错误
 func QueryOne(executor Executor, executeParams *sql.QueryOneExecuteParams) (sql.Result, error) {
 	if executor == nil {
 		return nil, errors.New("没有传递执行器")
@@ -461,6 +544,13 @@ func QueryOne(executor Executor, executeParams *sql.QueryOneExecuteParams) (sql.
 	return tableRows[0], nil
 }
 
+// Count 数据计数
+// 参数:
+// - executor: 数据库基础设施接口
+// - executeParams: 数据计数参数
+// 返回值:
+// - 数量
+// - 错误
 func Count(executor Executor, executeParams *sql.CountExecuteParams) (int64, error) {
 	if executor == nil {
 		return 0, errors.New("没有传递执行器")
@@ -483,6 +573,13 @@ func Count(executor Executor, executeParams *sql.CountExecuteParams) (int64, err
 	return int64(tableRows[0]["count"].(float64)), nil
 }
 
+// CheckExist 数据存在性检查
+// 参数:
+// - executor: 数据库基础设施接口
+// - executeParams: 数据存在性检查参数
+// 返回值:
+// - 是否存在
+// - 错误
 func CheckExist(executor Executor, executeParams *sql.CheckExistExecuteParams) (bool, error) {
 	if executor == nil {
 		return false, errors.New("没有传递执行器")
@@ -505,6 +602,13 @@ func CheckExist(executor Executor, executeParams *sql.CheckExistExecuteParams) (
 	return int64(tableRows[0]["count"].(float64)) > 0, nil
 }
 
+// CheckHasOnlyOne 数据唯一性检查
+// 参数:
+// - executor: 数据库基础设施接口
+// - executeParams: 数据唯一性检查参数
+// 返回值:
+// - 是否唯一
+// - 错误
 func CheckHasOnlyOne(executor Executor, executeParams *sql.CheckHasOnlyOneExecuteParams) (bool, error) {
 	if executor == nil {
 		return false, errors.New("没有传递执行器")
@@ -527,10 +631,27 @@ func CheckHasOnlyOne(executor Executor, executeParams *sql.CheckHasOnlyOneExecut
 	return int64(tableRows[0]["count"].(float64)) == 1, nil
 }
 
+// ExecuteRawSql SQL执行接口
+// 参数:
+// - executor: 数据库基础设施接口
+// - sql: SQL语句，可以使用预编译，需要填充的值用?占位
+// - args: 预编译填充值
+// 返回值:
+// - SQL执行结果
+// - 错误
 func ExecuteRawSql(executor Executor, sql string, args ...any) ([]sql.Result, error) {
 	return ExecuteRawSqlTemplate(executor, sql, nil, args...)
 }
 
+// ExecuteRawSqlTemplate SQL模板执行接口
+// 参数:
+// - executor: 数据库基础设施接口
+// - sql: SQL语句模板，可以使用预编译，需要填充的值用?占位，可以使用Go模板构造SQL语句
+// - template: 渲染SQL语句模板的模板参数
+// - args: 预编译填充值
+// 返回值:
+// - SQL执行结果
+// - 错误
 func ExecuteRawSqlTemplate(executor Executor, sql string, executeParams map[string]any, args ...any) ([]sql.Result, error) {
 	if executor == nil {
 		return nil, errors.New("没有传递执行器")

framework/core/infrastructure/database/error.go

@@ -6,14 +6,27 @@ import (
 )
 
 var (
+	// ErrDBRecordHasExist 数据库记录已存在
 	ErrDBRecordHasExist = errors.New("记录已存在")
+
+	// ErrDBRecordNotExist 数据库记录不存在
 	ErrDBRecordNotExist = errors.New("记录不存在")
 )
 
+// IsErrorDBRecordHasExist 检查错误是否是数据库记录已存在错误
+// 参数:
+// - err: 错误
+// 返回值:
+// - 是否是数据库记录已存在错误
 func IsErrorDBRecordHasExist(err error) bool {
 	return strings.Contains(err.Error(), "记录已存在")
 }
 
+// IsErrorDBRecordNotExist 检查错误是否是数据库记录不存在错误
+// 参数:
+// - err: 错误
+// 返回值:
+// - 是否是数据库记录不存在错误
 func IsErrorDBRecordNotExist(err error) bool {
 	return strings.Contains(err.Error(), "记录不存在")
 }

framework/core/infrastructure/database/operations/operations.go

@@ -144,18 +144,18 @@ func (op *Operations) AutoMigrate(tables ...Table) error {
 	return nil
 }
 
-func (op *Operations) ExecuteRawSql(sqlStr string, values ...any) ([]sql.Result, error) {
-	return op.ExecuteRawSqlTemplate(sqlStr, nil, values...)
+func (op *Operations) ExecuteRawSql(sqlStr string, args ...any) ([]sql.Result, error) {
+	return op.ExecuteRawSqlTemplate(sqlStr, nil, args...)
 }
 
-func (op *Operations) ExecuteRawSqlTemplate(sqlStr string, executeParams map[string]any, values ...any) ([]sql.Result, error) {
+func (op *Operations) ExecuteRawSqlTemplate(sqlStr string, executeParams map[string]any, args ...any) ([]sql.Result, error) {
 	parsedSql, err := template.ParseTemplateStringToString(sqlStr, executeParams)
 	if err != nil {
 		return nil, errors.New(err.Error())
 	}
 
 	tableRows := make([]map[string]any, 0)
-	err = op.db.Raw(parsedSql, values...).Scan(&tableRows).Error
+	err = op.db.Raw(parsedSql, args...).Scan(&tableRows).Error
 	if err != nil {
 		return nil, errors.New(err.Error())
 	}
@@ -178,7 +178,3 @@ func (op *Operations) ExecuteRawSqlTemplate(sqlStr string, executeParams map[str
 
 	return results, nil
 }
-
-func (op *Operations) ExecuteSql(_ string, _ map[string]any, _ ...any) ([]sql.Result, error) {
-	return make([]sql.Result, 0), nil
-}

framework/core/infrastructure/database/sql/condition.go

@@ -1,11 +1,15 @@
 package sql
 
+import "strings"
+
+// Conditions 数据库条件
 type Conditions struct {
 	queries []string
 	args    [][]any
 	err     error
 }
 
+// NewConditions 创建数据库条件
 func NewConditions() *Conditions {
 	return &Conditions{
 		queries: make([]string, 0),
@@ -13,106 +17,174 @@ func NewConditions() *Conditions {
 	}
 }
 
-func (conditions *Conditions) AddCondition(query string, values ...any) *Conditions {
+// AddCondition 添加条件
+// 参数:
+// - query: 条件语句，如: name LIKE ? AND age = ?
+// - args: 预编译值，如: foo, 10
+// 返回值:
+// - 数据库条件
+func (conditions *Conditions) AddCondition(query string, args ...any) *Conditions {
 	conditions.queries = append(conditions.queries, query)
-	conditions.args = append(conditions.args, values)
+	conditions.args = append(conditions.args, args)
 	return conditions
 }
 
-func (conditions *Conditions) Equal(columnName string, value any) *Conditions {
+// Equal 添加相等条件
+// 参数:
+// - columnName: 列名
+// - arg: 列值
+// 返回值:
+// - 数据库条件
+func (conditions *Conditions) Equal(columnName string, arg any) *Conditions {
 	if conditions.err != nil {
 		return conditions
 	}
 
 	conditions.queries = append(conditions.queries, "\""+columnName+"\" = ?")
-	conditions.args = append(conditions.args, []any{value})
+	conditions.args = append(conditions.args, []any{arg})
 	return conditions
 }
 
-func (conditions *Conditions) Like(columnName string, value string) *Conditions {
+// Like 添加LIKE条件
+// 参数:
+// - columnName: 列名
+// - arg: 列值
+// 返回值:
+// - 数据库条件
+func (conditions *Conditions) Like(columnName string, arg string) *Conditions {
 	if conditions.err != nil {
 		return conditions
 	}
 
 	conditions.queries = append(conditions.queries, "\""+columnName+"\" LIKE ?")
-	conditions.args = append(conditions.args, []any{value})
+	conditions.args = append(conditions.args, []any{arg})
 	return conditions
 }
 
-func (conditions *Conditions) In(columnName string, value any) *Conditions {
+// In 添加IN条件
+// 参数:
+// - columnName: 列名
+// - arg: 列值
+// 返回值:
+// - 数据库条件
+func (conditions *Conditions) In(columnName string, arg any) *Conditions {
 	if conditions.err != nil {
 		return conditions
 	}
 
 	conditions.queries = append(conditions.queries, "\""+columnName+"\" IN ?")
-	conditions.args = append(conditions.args, []any{value})
+	conditions.args = append(conditions.args, []any{arg})
 	return conditions
 }
 
-func (conditions *Conditions) NotIn(columnName string, value any) *Conditions {
+// NotIn 添加NOT IN条件
+// 参数:
+// - columnName: 列名
+// - arg: 列值
+// 返回值:
+// - 数据库条件
+func (conditions *Conditions) NotIn(columnName string, arg any) *Conditions {
 	if conditions.err != nil {
 		return conditions
 	}
 
 	conditions.queries = append(conditions.queries, "\""+columnName+"\" NOT IN ?")
-	conditions.args = append(conditions.args, []any{value})
+	conditions.args = append(conditions.args, []any{arg})
 	return conditions
 }
 
-func (conditions *Conditions) Not(columnName string, value any) *Conditions {
+// Not 添加不相等条件
+// 参数:
+// - columnName: 列名
+// - arg: 列值
+// 返回值:
+// - 数据库条件
+func (conditions *Conditions) Not(columnName string, arg any) *Conditions {
 	if conditions.err != nil {
 		return conditions
 	}
 
 	conditions.queries = append(conditions.queries, "\""+columnName+"\" != ?")
-	conditions.args = append(conditions.args, []any{value})
+	conditions.args = append(conditions.args, []any{arg})
 	return conditions
 }
 
-func (conditions *Conditions) LessThan(columnName string, value any) *Conditions {
+// LessThan 添加小于条件
+// 参数:
+// - columnName: 列名
+// - arg: 列值
+// 返回值:
+// - 数据库条件
+func (conditions *Conditions) LessThan(columnName string, arg any) *Conditions {
 	if conditions.err != nil {
 		return conditions
 	}
 
 	conditions.queries = append(conditions.queries, "\""+columnName+"\" < ?")
-	conditions.args = append(conditions.args, []any{value})
+	conditions.args = append(conditions.args, []any{arg})
 	return conditions
 }
 
-func (conditions *Conditions) LessThanAndEqual(columnName string, value any) *Conditions {
+// LessThanAndEqual 添加小于等于条件
+// 参数:
+// - columnName: 列名
+// - arg: 列值
+// 返回值:
+// - 数据库条件
+func (conditions *Conditions) LessThanAndEqual(columnName string, arg any) *Conditions {
 	if conditions.err != nil {
 		return conditions
 	}
 
 	conditions.queries = append(conditions.queries, "\""+columnName+"\" <= ?")
-	conditions.args = append(conditions.args, []any{value})
+	conditions.args = append(conditions.args, []any{arg})
 	return conditions
 }
 
-func (conditions *Conditions) GreaterThan(columnName string, value any) *Conditions {
+// GreaterThan 添加大于条件
+// 参数:
+// - columnName: 列名
+// - arg: 列值
+// 返回值:
+// - 数据库条件
+func (conditions *Conditions) GreaterThan(columnName string, arg any) *Conditions {
 	if conditions.err != nil {
 		return conditions
 	}
 
 	conditions.queries = append(conditions.queries, "\""+columnName+"\" > ?")
-	conditions.args = append(conditions.args, []any{value})
+	conditions.args = append(conditions.args, []any{arg})
 	return conditions
 }
 
-func (conditions *Conditions) GreaterThanAndEqual(columnName string, value any) *Conditions {
+// GreaterThanAndEqual 添加大于等于条件
+// 参数:
+// - columnName: 列名
+// - arg: 列值
+// 返回值:
+// - 数据库条件
+func (conditions *Conditions) GreaterThanAndEqual(columnName string, arg any) *Conditions {
 	if conditions.err != nil {
 		return conditions
 	}
 
 	conditions.queries = append(conditions.queries, "\""+columnName+"\" >= ?")
-	conditions.args = append(conditions.args, []any{value})
+	conditions.args = append(conditions.args, []any{arg})
 	return conditions
 }
 
+// Queries 获取所有查询条件语句
+// 参数: 无
+// 返回值:
+// - 查询条件
 func (conditions *Conditions) Queries() []string {
 	return conditions.queries
 }
 
+// Args 获取所有查询条件值
+// 参数: 无
+// 返回值:
+// - 查询条件值
 func (conditions *Conditions) Args() []any {
 	args := make([]any, 0)
 	for _, conditionArgs := range conditions.args {
@@ -121,3 +193,26 @@ func (conditions *Conditions) Args() []any {
 
 	return args
 }
+
+// And 获取构造的AND条件语句
+// 参数: 无
+// 返回值:
+// - 构造的AND条件语句
+func (conditions *Conditions) And() string {
+	if conditions.queries == nil || len(conditions.queries) == 0 {
+		return ""
+	}
+
+	stringBuilder := strings.Builder{}
+	stringBuilder.WriteString("WHERE ")
+
+	for i, query := range conditions.queries {
+		stringBuilder.WriteString(query)
+
+		if i != len(conditions.queries)-1 {
+			stringBuilder.WriteString(" AND ")
+		}
+	}
+
+	return stringBuilder.String()
+}

framework/core/infrastructure/database/sql/result.go

@@ -17,116 +17,14 @@ const (
 	resultTimeSecFormat   = "2006-01-02T15:04:05+08:00"
 )
 
-func ParseSqlResult(input any, output any) error {
-	return ParseSqlResultWithColumn(input, output, "")
-}
-
-func ParseSqlResultWithColumn(input any, output any, columnName string) error {
-	if input == nil {
-		return nil
-	}
-
-	if output == nil {
-		return nil
-	}
-
-	typeCheckErr := errors.New("可以接受的输出类型为指针或者slice的指针")
-	outputType := reflect.TypeOf(output)
-
-	if outputType.Kind() != reflect.Pointer {
-		return typeCheckErr
-	}
-
-	outputElemType := reflectutils.PointerTypeElem(outputType)
-
-	// 输出不是slice，直接用result赋值即可
-	if outputElemType.Kind() != reflect.Slice {
-		result, ok := input.(Result)
-		if !ok {
-			return errors.New("输出不是slice，输入需要是sql.Result")
-		}
-
-		return parseSqlSingle(result, output, columnName)
-	}
-
-	// 输出是slice，需要遍历处理
-	results, ok := input.([]Result)
-	if !ok {
-		return errors.New("输出是slice，输入需要是[]sql.Result")
-	}
-
-	outputEntities := reflect.MakeSlice(outputElemType, 0, 0)
-
-	for _, result := range results {
-		var outputEntityValue reflect.Value
-
-		// slice子类型判断
-		if outputElemType.Elem().Kind() == reflect.Pointer {
-			outputEntityValue = reflect.New(outputElemType.Elem().Elem())
-			err := parseSqlSingle(result, outputEntityValue.Interface(), columnName)
-			if err != nil {
-				return err
-			}
-		} else {
-			outputEntityValue = reflect.New(outputElemType.Elem()).Elem()
-			err := parseSqlSingle(result, outputEntityValue.Addr().Interface(), columnName)
-			if err != nil {
-				return err
-			}
-		}
-
-		outputEntities = reflect.Append(outputEntities, outputEntityValue)
-	}
-
-	outputElemValue := reflectutils.PointerValueElem(reflect.ValueOf(output))
-	outputElemValue.Set(outputEntities)
-
-	return nil
-}
-
-func parseSqlSingle(result Result, output any, columnName string) error {
-	outputValue := reflectutils.PointerValueElem(reflect.ValueOf(output))
-	outputKind := reflectutils.GroupValueKind(outputValue)
-
-	var oneResultValue any
-	if strutils.IsStringEmpty(columnName) {
-		for _, value := range result {
-			oneResultValue = value
-			break
-		}
-	} else {
-		value, ok := result[columnName]
-		if !ok {
-			return errors.New("列不存在")
-		}
-
-		oneResultValue = value
-	}
-
-	switch outputKind {
-	case reflect.String:
-		return reflectutils.AssignStringValue(oneResultValue, outputValue)
-	case reflect.Bool:
-		return reflectutils.AssignBoolValue(oneResultValue, outputValue)
-	case reflect.Int64:
-		return reflectutils.AssignInt64Value(oneResultValue, outputValue)
-	case reflect.Uint64:
-		return reflectutils.AssignUint64Value(oneResultValue, outputValue)
-	case reflect.Float64:
-		return reflectutils.AssignFloat64Value(oneResultValue, outputValue)
-	case reflect.Struct:
-		if outputValue.Type().Name() == "time.Time" {
-			return errors.New("不支持转换到time.Time，请使用Result.ColumnValueStringAsTime")
-		}
-
-		return sql_result.DefaultUsage(result, output, columnName)
-	default:
-		return errors.New("不支持的类型")
-	}
-}
-
+// Result 查询结果
 type Result map[string]any
 
+// ColumnValueStringAsTime 将string类型的列值转化为time.Time
+// 参数:
+// - columnName: 列名
+// 返回值:
+// - 转换为time.Time的列值
 func (result Result) ColumnValueStringAsTime(columnName string) time.Time {
 	value, ok := result[columnName].(string)
 	if !ok {
@@ -157,6 +55,11 @@ func (result Result) ColumnValueStringAsTime(columnName string) time.Time {
 	return t
 }
 
+// ColumnValueBool 以bool类型获取列值
+// 参数:
+// - columnName: 列名
+// 返回值:
+// - bool类型的列值
 func (result Result) ColumnValueBool(columnName string) bool {
 	value, err := reflectutils.ToBool(result[columnName])
 	if err != nil {
@@ -167,6 +70,11 @@ func (result Result) ColumnValueBool(columnName string) bool {
 	return value
 }
 
+// ColumnValueString 以string类型获取列值
+// 参数:
+// - columnName: 列名
+// 返回值:
+// - string类型的列值
 func (result Result) ColumnValueString(columnName string) string {
 	value, err := reflectutils.ToString(result[columnName])
 	if err != nil {
@@ -177,6 +85,11 @@ func (result Result) ColumnValueString(columnName string) string {
 	return value
 }
 
+// ColumnValueInt 以int类型获取列值
+// 参数:
+// - columnName: 列名
+// 返回值:
+// - int类型的列值
 func (result Result) ColumnValueInt(columnName string) int {
 	value, err := reflectutils.ToInt64(result[columnName])
 	if err != nil {
@@ -187,6 +100,11 @@ func (result Result) ColumnValueInt(columnName string) int {
 	return int(value)
 }
 
+// ColumnValueInt8 以int8类型获取列值
+// 参数:
+// - columnName: 列名
+// 返回值:
+// - int8类型的列值
 func (result Result) ColumnValueInt8(columnName string) int8 {
 	value, err := reflectutils.ToInt64(result[columnName])
 	if err != nil {
@@ -197,6 +115,11 @@ func (result Result) ColumnValueInt8(columnName string) int8 {
 	return int8(value)
 }
 
+// ColumnValueInt16 以int16类型获取列值
+// 参数:
+// - columnName: 列名
+// 返回值:
+// - int16类型的列值
 func (result Result) ColumnValueInt16(columnName string) int16 {
 	value, err := reflectutils.ToInt64(result[columnName])
 	if err != nil {
@@ -207,6 +130,11 @@ func (result Result) ColumnValueInt16(columnName string) int16 {
 	return int16(value)
 }
 
+// ColumnValueInt32 以int32类型获取列值
+// 参数:
+// - columnName: 列名
+// 返回值:
+// - int32类型的列值
 func (result Result) ColumnValueInt32(columnName string) int32 {
 	value, err := reflectutils.ToInt64(result[columnName])
 	if err != nil {
@@ -217,6 +145,11 @@ func (result Result) ColumnValueInt32(columnName string) int32 {
 	return int32(value)
 }
 
+// ColumnValueInt64 以int64类型获取列值
+// 参数:
+// - columnName: 列名
+// 返回值:
+// - int64类型的列值
 func (result Result) ColumnValueInt64(columnName string) int64 {
 	value, err := reflectutils.ToInt64(result[columnName])
 	if err != nil {
@@ -227,6 +160,11 @@ func (result Result) ColumnValueInt64(columnName string) int64 {
 	return value
 }
 
+// ColumnValueUint 以uint类型获取列值
+// 参数:
+// - columnName: 列名
+// 返回值:
+// - uint类型的列值
 func (result Result) ColumnValueUint(columnName string) uint {
 	value, err := reflectutils.ToUint64(result[columnName])
 	if err != nil {
@@ -237,6 +175,11 @@ func (result Result) ColumnValueUint(columnName string) uint {
 	return uint(value)
 }
 
+// ColumnValueUint8 以uint8类型获取列值
+// 参数:
+// - columnName: 列名
+// 返回值:
+// - uint8类型的列值
 func (result Result) ColumnValueUint8(columnName string) uint8 {
 	value, err := reflectutils.ToUint64(result[columnName])
 	if err != nil {
@@ -247,6 +190,11 @@ func (result Result) ColumnValueUint8(columnName string) uint8 {
 	return uint8(value)
 }
 
+// ColumnValueUint16 以uint16类型获取列值
+// 参数:
+// - columnName: 列名
+// 返回值:
+// - uint16类型的列值
 func (result Result) ColumnValueUint16(columnName string) uint16 {
 	value, err := reflectutils.ToUint64(result[columnName])
 	if err != nil {
@@ -257,6 +205,11 @@ func (result Result) ColumnValueUint16(columnName string) uint16 {
 	return uint16(value)
 }
 
+// ColumnValueUint32 以uint32类型获取列值
+// 参数:
+// - columnName: 列名
+// 返回值:
+// - uint32类型的列值
 func (result Result) ColumnValueUint32(columnName string) uint32 {
 	value, err := reflectutils.ToUint64(result[columnName])
 	if err != nil {
@@ -267,6 +220,11 @@ func (result Result) ColumnValueUint32(columnName string) uint32 {
 	return uint32(value)
 }
 
+// ColumnValueUint64 以uint64类型获取列值
+// 参数:
+// - columnName: 列名
+// 返回值:
+// - uint64类型的列值
 func (result Result) ColumnValueUint64(columnName string) uint64 {
 	value, err := reflectutils.ToUint64(result[columnName])
 	if err != nil {
@@ -277,6 +235,11 @@ func (result Result) ColumnValueUint64(columnName string) uint64 {
 	return value
 }
 
+// ColumnValueFloat32 以float32类型获取列值
+// 参数:
+// - columnName: 列名
+// 返回值:
+// - float32类型的列值
 func (result Result) ColumnValueFloat32(columnName string) float32 {
 	value, err := reflectutils.ToFloat64(result[columnName])
 	if err != nil {
@@ -287,6 +250,11 @@ func (result Result) ColumnValueFloat32(columnName string) float32 {
 	return float32(value)
 }
 
+// ColumnValueFloat64 以float64类型获取列值
+// 参数:
+// - columnName: 列名
+// 返回值:
+// - float64类型的列值
 func (result Result) ColumnValueFloat64(columnName string) float64 {
 	value, err := reflectutils.ToFloat64(result[columnName])
 	if err != nil {
@@ -296,3 +264,124 @@ func (result Result) ColumnValueFloat64(columnName string) float64 {
 
 	return value
 }
+
+// ParseSqlResult 解析查询结果
+// 参数:
+// - input: sql.Result或者[]sql.Result类型的查询结果
+// - output: 接收查询结果的指针，如果是结构，需要使用sqlresult tag标注字段
+// 返回值:
+// - 错误
+func ParseSqlResult(input any, output any) error {
+	return ParseSqlResultWithColumn(input, output, "")
+}
+
+// ParseSqlResultWithColumn 取查询结果列解析结果
+// 参数:
+// - input: sql.Result或者[]sql.Result类型的查询结果
+// - output: 接收查询结果的指针，如果是结构，需要使用sqlresult tag标注字段
+// - columnName: 获取的列名
+// 返回值:
+// - 错误
+func ParseSqlResultWithColumn(input any, output any, columnName string) error {
+	if input == nil {
+		return nil
+	}
+
+	if output == nil {
+		return nil
+	}
+
+	typeCheckErr := errors.New("可以接受的输出类型为指针或者slice的指针")
+	outputType := reflect.TypeOf(output)
+
+	if outputType.Kind() != reflect.Pointer {
+		return typeCheckErr
+	}
+
+	outputElemType := reflectutils.PointerTypeElem(outputType)
+
+	// 输出不是slice，直接用result赋值即可
+	if outputElemType.Kind() != reflect.Slice {
+		result, ok := input.(Result)
+		if !ok {
+			return errors.New("输出不是slice，输入需要是sql.Result")
+		}
+
+		return parseSqlSingle(result, output, columnName)
+	}
+
+	// 输出是slice，需要遍历处理
+	results, ok := input.([]Result)
+	if !ok {
+		return errors.New("输出是slice，输入需要是[]sql.Result")
+	}
+
+	outputEntities := reflect.MakeSlice(outputElemType, 0, 0)
+
+	for _, result := range results {
+		var outputEntityValue reflect.Value
+
+		// slice子类型判断
+		if outputElemType.Elem().Kind() == reflect.Pointer {
+			outputEntityValue = reflect.New(outputElemType.Elem().Elem())
+			err := parseSqlSingle(result, outputEntityValue.Interface(), columnName)
+			if err != nil {
+				return err
+			}
+		} else {
+			outputEntityValue = reflect.New(outputElemType.Elem()).Elem()
+			err := parseSqlSingle(result, outputEntityValue.Addr().Interface(), columnName)
+			if err != nil {
+				return err
+			}
+		}
+
+		outputEntities = reflect.Append(outputEntities, outputEntityValue)
+	}
+
+	outputElemValue := reflectutils.PointerValueElem(reflect.ValueOf(output))
+	outputElemValue.Set(outputEntities)
+
+	return nil
+}
+
+func parseSqlSingle(result Result, output any, columnName string) error {
+	outputValue := reflectutils.PointerValueElem(reflect.ValueOf(output))
+	outputKind := reflectutils.GroupValueKind(outputValue)
+
+	var oneResultValue any
+	if strutils.IsStringEmpty(columnName) {
+		for _, value := range result {
+			oneResultValue = value
+			break
+		}
+	} else {
+		value, ok := result[columnName]
+		if !ok {
+			return errors.New("列不存在")
+		}
+
+		oneResultValue = value
+	}
+
+	switch outputKind {
+	case reflect.String:
+		return reflectutils.AssignStringValue(oneResultValue, outputValue)
+	case reflect.Bool:
+		return reflectutils.AssignBoolValue(oneResultValue, outputValue)
+	case reflect.Int64:
+		return reflectutils.AssignInt64Value(oneResultValue, outputValue)
+	case reflect.Uint64:
+		return reflectutils.AssignUint64Value(oneResultValue, outputValue)
+	case reflect.Float64:
+		return reflectutils.AssignFloat64Value(oneResultValue, outputValue)
+	case reflect.Struct:
+		if outputValue.Type().Name() == "time.Time" {
+			return errors.New("不支持转换到time.Time，请使用Result.ColumnValueStringAsTime")
+		}
+
+		return sql_result.DefaultUsage(result, output, columnName)
+	default:
+		return errors.New("不支持的类型")
+	}
+}

framework/core/infrastructure/database/sql/sql_template.go

@@ -16,6 +16,7 @@ VALUES
     {{ $valuesClauses | join "," }}
 `
 
+// InsertExecuteParams 插入参数
 type InsertExecuteParams struct {
 	TableName string
 	*TableRow
@@ -47,6 +48,7 @@ func (params InsertExecuteParams) Map() (map[string]any, error) {
 	}, nil
 }
 
+// InsertBatchExecuteParams 批量插入参数
 type InsertBatchExecuteParams struct {
 	TableName     string
 	TableRowBatch []TableRow
@@ -89,6 +91,7 @@ WHERE
     {{ range .queries }} {{ . }} AND {{ end }} 1 = 1
 `
 
+// DeleteExecuteParams 删除参数
 type DeleteExecuteParams struct {
 	TableName string
 	*Conditions
@@ -118,6 +121,7 @@ WHERE
     {{ range .queries }} {{ . }} AND {{ end }} 1 = 1
 `
 
+// UpdateExecuteParams 更新参数
 type UpdateExecuteParams struct {
 	TableName string
 	*TableRow
@@ -157,6 +161,7 @@ WHERE
 {{ if .offset }}OFFSET {{ .offset }}{{ end }}
 `
 
+// QueryExecuteParams 查询参数
 type QueryExecuteParams struct {
 	TableName     string
 	SelectClauses []string
@@ -185,6 +190,7 @@ func (params QueryExecuteParams) Map() (map[string]any, error) {
 	}, nil
 }
 
+// QueryOneExecuteParams 单查询参数
 type QueryOneExecuteParams struct {
 	TableName     string
 	SelectClauses []string
@@ -208,6 +214,7 @@ WHERE
     {{ range .queries }} {{ . }} AND {{ end }} 1 = 1
 `
 
+// CountExecuteParams 计数参数
 type CountExecuteParams struct {
 	TableName string
 	*Conditions
@@ -220,6 +227,7 @@ func (params CountExecuteParams) Map() (map[string]any, error) {
 	}, nil
 }
 
+// CheckExistExecuteParams 存在性校验参数
 type CheckExistExecuteParams struct {
 	TableName string
 	*Conditions
@@ -233,6 +241,7 @@ func (params CheckExistExecuteParams) Map() (map[string]any, error) {
 	}, nil
 }
 
+// CheckHasOnlyOneExecuteParams 唯一性校验参数
 type CheckHasOnlyOneExecuteParams struct {
 	TableName string
 	*Conditions

framework/core/infrastructure/database/sql/table_row.go

@@ -1,11 +1,13 @@
 package sql
 
+// TableRow 数据库表行
 type TableRow struct {
 	columns []string
 	values  []any
 	err     error
 }
 
+// NewTableRow 创建数据库表行
 func NewTableRow() *TableRow {
 	return &TableRow{
 		columns: make([]string, 0),
@@ -13,6 +15,12 @@ func NewTableRow() *TableRow {
 	}
 }
 
+// Add 添加表行
+// 参数:
+// - column: 列名
+// - value: 列值
+// 返回值:
+// - 数据库表行
 func (tableRow *TableRow) Add(column string, value any) *TableRow {
 	if tableRow.err != nil {
 		return tableRow
@@ -24,10 +32,18 @@ func (tableRow *TableRow) Add(column string, value any) *TableRow {
 	return tableRow
 }
 
+// Columns 获取添加的列名
+// 参数: 无
+// 返回值:
+// - 添加的列名
 func (tableRow *TableRow) Columns() []string {
 	return tableRow.columns
 }
 
+// Values 获取添加的列值
+// 参数: 无
+// 返回值:
+// - 添加的列值
 func (tableRow *TableRow) Values() []any {
 	return tableRow.values
 }

framework/core/infrastructure/infrastructure.go

@@ -28,6 +28,7 @@ type CacheConfig struct {
 	} `json:"redis" yaml:"redis"`
 }
 
+// Infrastructure 基础设施结构
 type Infrastructure struct {
 	dbExecutor database.Executor
 	localCache cache.Cache
@@ -100,14 +101,26 @@ func DestroyInfrastructure(i *Infrastructure) {
 	return
 }
 
+// DBExecutor 获取数据库基础设施
+// 参数: 无
+// 返回值:
+// - 数据库基础设施的接口
 func (i Infrastructure) DBExecutor() database.Executor {
 	return i.dbExecutor
 }
 
+// LocalCache 获取本地缓存基础设施
+// 参数: 无
+// 返回值:
+// - 缓存基础设施的接口
 func (i Infrastructure) LocalCache() cache.Cache {
 	return i.localCache
 }
 
+// RedisCache 获取Redis缓存基础设施
+// 参数: 无
+// 返回值:
+// - 缓存基础设施的接口
 func (i Infrastructure) RedisCache() cache.Cache {
 	return i.redisCache
 }