db_view/service/internal/common/databases/interfaces.go

package databases

import (
	"context"
	_ "dbview/service/internal/common/databases/drivers/mysql"
	"dbview/service/internal/common/databases/meta"
)

// Connection 基础连接接口
type Connection interface {
	Close() error
}

// MetadataReader 查询相关接口（复核并统一命名）
type MetadataReader interface {
	// GetRootObjects 获取实例下的根对象（如MySQL的库、Oracle的用户/表空间）
	// connID：数据库连接ID（关联连接配置），用于从连接池或配置中定位连接
	// connInfo：用于错误提示/上下文（例如显示在日志中），不用于建立连接
	// page/pageSize：分页参数（根对象可能较多，如多租户场景的上千个库）
	// 新增参数 fetch: 当 fetch==false 时，仅返回总数和每个可用类型（作为 GenericObject 的 Type 字段），不读取具体条目
	GetRootObjects(ctx context.Context, connID string, connInfo string, page, pageSize int, fetch bool) ([]meta.GenericObject, int64, error)

	// GetChildObjects 获取父对象下的子对象（如库下的表、表下的字段）
	// parentName：父对象的 Name 字段（来自 GenericObject.Name），例如库名或表名。
	// 注意：此接口不兼容原来的 parentID 点分格式，调用方应传入父对象的 Name（例如 dbName）并在必要时通过 filter 提供额外上下文（例如 filter["db"]）
	// filter：筛选条件（如按类型过滤"table"、"view"）
	// 新增参数 fetch: 当 fetch==false 时，仅返回总数和可用的子对象类型（作为 GenericObject 的 Type 字段），不读取具体条目
	// GetChildObjects 使用结构化路径定位父对象并返回其子对象
	// path: 从根到父对象的完整路径（见 meta.ObjectPath）
	// childType: 可选，若指定仅返回该子类型（例如 "column"、"index"）
	GetChildObjects(ctx context.Context, path meta.ObjectPath, childType string, page, pageSize int, fetch bool) ([]meta.GenericObject, int64, error)

	// GetObjectDetails 获取单个对象的详情（含子对象，如包含字段、索引的表详情）
	// 注意：不再兼容旧的 dotted objectID 格式。
	// objectName: 对象的展示名（GenericObject.Name），例如表名或视图名
	// objectType: 对象类型（table/view/procedure 等）
	// parentName: 父对象的 Name（例如数据库名），用于在驱动层定位对象
	// fetch: 当 fetch==false 时，仅返回对象的基础元信息（例如类型、名称、统计等），不展开或加载子对象的详细列表（例如列、索引）。
	// GetObjectDetails 使用结构化路径定位目标对象并返回详情（含子对象）
	// path: 从根到目标对象的完整路径（见 meta.ObjectPath）
	GetObjectDetails(ctx context.Context, path meta.ObjectPath, fetch bool) (meta.GenericObject, error)
}

// MetadataDeleter 删除相关接口：前端会传来名称/类型/父级等信息，驱动应返回匹配的对象列表和数量（注意：此方法仅返回匹配项，默认不直接执行 DROP）
type MetadataDeleter interface {
	// DescribeDeleteTemplate 返回指定对象的删除模板，用于前端显示删除确认和影响预览。
	// path: 目标对象的路径，用于确定上下文。
	DescribeDeleteTemplate(ctx context.Context, path meta.ObjectPath) (meta.ObjectTemplate, error)

	// DeleteRootObjects 接受一个 ObjectOperationRequest（前端会传入 Object.Name/Object.Type/Options 等）
	// 返回 ObjectOperationResponse，包含匹配到的对象数与可选的生成 SQL（默认不直接执行删除，除非 Options 指定执行）
	DeleteRootObjects(ctx context.Context, req meta.ObjectOperationRequest) (meta.ObjectOperationResponse, error)

	// DeleteChildObjects 接受 ObjectOperationRequest（其中 Object.ParentID 指定父对象，Object.Name/Type 指定匹配规则）
	// 返回 ObjectOperationResponse，包含匹配到的子对象及数量与生成的 SQL（默认不直接执行删除）。
	DeleteChildObjects(ctx context.Context, req meta.ObjectOperationRequest) (meta.ObjectOperationResponse, error)
}

// MetadataCreater 提供创建（Create）相关的能力。
// 新的设计采用"模板查询 + 预览/执行"工作流：
// 1) 前端先调用 DescribeCreateTemplate 获取指定对象类型在给定父上下文下的表单模板（字段定义、约束、示例等）。
// 2) 前端根据模板渲染表单并收集用户填入的数据，调用 CreateObject 进行预览（execute=false）或执行（execute=true）。
// 该接口为破坏性变更（不兼容旧的 CreaterRootObjects/CreaterChildObjects 设计）。
type MetadataCreater interface {
	// DescribeCreateTemplate 返回某个对象类型在给定路径上下文下的创建模板，用于前端动态生成表单。
	// path: 目标对象的路径，最后一个元素表示要创建的对象类型，前面的元素表示父上下文。
	// 例如：创建表时路径为 [{"type":"database","name":"mydb"}]，表示在mydb数据库下创建表。
	DescribeCreateTemplate(ctx context.Context, path meta.ObjectPath) (meta.ObjectTemplate, error)

	// CreateObject 接受前端填好的属性并执行预览或实际创建，取决于 req.Execute。
	// 当 req.Execute==false 时，仅执行校验并返回生成的 SQL（preview）；当 true 时尝试执行（需谨慎，可能不可回滚）。
	CreateObject(ctx context.Context, req meta.CreateObjectRequest) (meta.CreateObjectResponse, error)
}

// MetadataUpdater 提供修改（Update）相关的能力。
// 设计采用“模板查询 + 预览/执行”工作流：
// 1) 前端先调用 DescribeUpdateTemplate 获取指定对象的修改模板（字段定义、当前值、约束等）。
// 2) 前端根据模板渲染表单并收集用户填入的数据，调用 UpdateObject 进行预览（execute=false）或执行（execute=true）。
type MetadataUpdater interface {
	// DescribeUpdateTemplate 返回指定对象的修改模板，用于前端动态生成表单。
	// path: 目标对象的路径，用于确定上下文和当前值。
	DescribeUpdateTemplate(ctx context.Context, path meta.ObjectPath) (meta.ObjectTemplate, error)

	// UpdateObject 接受前端填好的属性并执行预览或实际修改，取决于 req.Execute。
	// 当 req.Execute==false 时，仅执行校验并返回生成的 SQL（preview）；当 true 时尝试执行（需谨慎，可能不可回滚）。
	UpdateObject(ctx context.Context, req meta.UpdateObjectRequest) (meta.UpdateObjectResponse, error)
}

// MetadataRefresher 提供按对象刷新元数据的能力（例如在驱动层重新加载某对象缓存）
type MetadataRefresher interface {
	RefreshObject(ctx context.Context, objectID string) error
}

// MetadataInfo 提供数据库级别的额外元信息查询，例如数据库支持的关键字列表
type MetadataInfo interface {
	// GetMetadataInfo 返回目标数据库的元信息（例如支持的关键字、字段类型等），供语法高亮/自动完成和能力检测使用。
	// - ctx: 上下文控制
	// 注意：驱动层通常不需要传入 connID；实现类应自行管理连接上下文。
	GetMetadataInfo(ctx context.Context) (meta.MetadataCapabilities, error)
}

// DataReader 数据读取接口：对路径指向的对象（通常为 table / view）执行数据查询
// 设计原则：大道至简 + 可增量扩展。保持单方法 + 请求对象聚合参数。
// 必选参数：
//   - ctx: 取消/超时控制
//   - connID: 连接标识（与连接池/配置绑定）
//   - path: 目标对象路径（最后一段通常为 table/view 名称）
//   - req: 查询参数结构（列选择/过滤/排序/分页/是否统计总数/是否流式等）
//
// 返回：QueryResult（列元信息 + 行数据 + 可选统计）
type DataReader interface {
	// QueryData 执行数据查询并返回结果。
	// 参数说明：
	//   ctx  ：上下文控制（取消/超时），由调用方传入。
	//   path ：目标对象的结构化路径（最后一段通常为表或视图名称）。
	//   req  ：查询请求参数（列选择、过滤、排序、分页等）。
	// 不需要传入 connID，连接由上层通过实现类的构造或其它注入方式确定。
	// 返回：QueryResult（包含列元信息、行数据、统计信息等）。
	QueryData(ctx context.Context, path meta.ObjectPath, req meta.DataQueryRequest) (meta.QueryResult, error)
}

// DataExecutor SQL执行接口：执行各种类型的SQL语句（SELECT、INSERT、UPDATE、DELETE、CREATE、DROP等）
// 设计原则：支持各种SQL类型，统一执行入口，提供执行结果和影响统计。
type DataExecutor interface {
	// ExecuteSQL 执行SQL语句并返回结果。
	// 参数说明：
	//   ctx  ：上下文控制（取消/超时），由调用方传入。
	//   path ：目标对象的结构化路径（用于确定数据库连接）。
	//   sql  ：要执行的SQL语句。
	//   params：参数化查询的参数列表（可选）。
	// 返回：ExecuteResult（包含执行结果、影响行数、最后插入ID等）。
	ExecuteSQL(ctx context.Context, path meta.ObjectPath, sql string, params []interface{}) (meta.ExecuteResult, error)
}