From b815d7e701a7a435535d941268abdc492f93eeb7 Mon Sep 17 00:00:00 2001 From: yumoqing Date: Fri, 7 Nov 2025 16:47:22 +0800 Subject: [PATCH] bugfix --- aidocs/sor.md | 289 +------------------------------------------------- 1 file changed, 3 insertions(+), 286 deletions(-) diff --git a/aidocs/sor.md b/aidocs/sor.md index c159050..aca6797 100644 --- a/aidocs/sor.md +++ b/aidocs/sor.md @@ -34,7 +34,7 @@ ## 概述 -`SQLor` 提供了一个统一接口来执行 SQL 查询和命令，并通过命名参数 `${var}` 支持模板化 SQL。其主要特点包括： +`SQLor` 提供了一个统一接口来执行 SQL 查询和命令，并通过命名参数 `${var}$` 支持模板化 SQL。其主要特点包括： - 异步/同步双模式支持。 - 参数自动替换与安全绑定。 @@ -89,7 +89,7 @@ os.environ['NLS_LANG'] = 'SIMPLIFIED CHINESE_CHINA.UTF8' | 功能 | 描述 | |------|------| -| 参数化 SQL | 使用 `${var}` 占位符进行变量注入 | +| 参数化 SQL | 使用 `${var}$` 占位符进行变量注入 | | 异步支持 | 支持 `async/await` 模式运行 SQL | | 分页查询 | 自动生成分页 SQL（需子类实现模型） | | 排序与过滤 | 支持动态排序字段和条件表达式 | @@ -100,289 +100,6 @@ os.environ['NLS_LANG'] = 'SIMPLIFIED CHINESE_CHINA.UTF8' --- -## 主要类与方法说明 - -### `db_type_2_py_type(o)` - -将特定数据库类型转换为 Python 原生类型。 - -#### 参数 -- `o`: 数据库字段值 - -#### 返回值 -| 输入类型 | 输出 | -|--------|-------| -| `decimal.Decimal` | `float` | -| `datetime.datetime` | 字符串格式 `'YYYY-MM-DD HH:MM:SS'` | -| `datetime.date` | `'YYYY-MM-DD'` | -| 其他 | 原值 | - -#### 示例 -```python -db_type_2_py_type(decimal.Decimal('3.14')) → 3.14 -``` - ---- - -### `SQLorException` - -自定义异常类，封装 SQL 执行错误。 - -> ❗ 当前代码存在拼写错误：`__int__` 应为 `__init__`，且 `supper` 应为 `super`。 - -#### 属性 -- `response`: `"error"` -- `errtype`: `"SQLor"` -- `errmsg`: 异常消息字符串 - -#### 示例输出 -``` -errtype:SQLor,errmsg=database error... -``` - -> ✅ **建议修复**： -```python -class SQLException(Exception): - def __init__(self, **kvs): - super(SQLException, self).__init__(**kvs) - self.dic = { - 'response': 'error', - 'errtype': 'SQLor', - 'errmsg': str(self) - } - - def __str__(self): - return 'errtype:%s,errmsg=%s' % (self.dic['errtype'], self.dic['errmsg']) -``` - ---- - -### `setValues(params, ns)` - -从命名空间 `ns` 或系统环境变量中查找参数值。 - -#### 参数 -- `params`: 参数名（字符串） -- `ns`: 命名空间字典 - -#### 返回 -优先从 `ns` 中取值，若无则尝试 `os.getenv(params)`。 - ---- - -### `findNamedParameters(sql)` - -解析 SQL 字符串中的所有 `${...}` 形式的命名参数。 - -#### 示例 -```python -sql = "SELECT * FROM user WHERE id = ${uid}$ AND name = ${uname}$" -findNamedParameters(sql) -# 返回 ['${uid}$', '${uname}$'] -``` - ---- - -### `uniParams(params1)` - -去重保留唯一参数名列表。 - -#### 示例 -```python -uniParams(['${a}$', '${b}$', '${a}$']) → ['${a}$', '${b}$'] -``` - ---- - -### `readsql(fn)` - -读取指定文件路径的 SQL 文件内容（UTF-8 编码）。 - -#### 参数 -- `fn`: 文件路径 - -#### 返回 -文件内容字符串。 - ---- - -## `SQLor` 类 - -### 初始化 `__init__` - -#### 参数 -| 参数 | 默认值 | 说明 | -|------|--------|------| -| `dbdesc` | None | 数据库描述字典，至少含 `dbname` | -| `sqltp`, `sqlts` | `$[`, `]$` | 模板占位符开始/结束符号 | -| `sqlvp`, `sqlvs` | `${`, `}$` | 变量占位符开始/结束符号 | - -#### 初始化行为 -- 设置连接状态（`conn`, `cur`） -- 初始化元数据缓存 `metadatas` -- 创建 `ConditionConvert` 实例用于条件表达式处理 - ---- - -### 元数据管理 - -#### `setMeta(tablename, meta)` -保存表的元数据到内存缓存。 - -#### `getMeta(tablename)` -获取指定表的缓存元数据。 - -#### `removeMeta(tablename)` -清除指定表的元数据缓存。 - ---- - -### 连接与游标控制 - -#### `setCursor(async_mode, conn, cur)` -绑定数据库连接和游标对象。 - -#### `getConn()` -返回当前数据库连接对象。 - -#### `cursor()` -返回当前游标对象。 - ---- - -### 类型转换支持 - -#### `setConvertFunction(typ, func)` -注册用户自定义类型转换函数。 - -#### `convert(typ, value)` -调用注册的转换函数处理值。 - ---- - -### SQL 类型判断 - -#### `getSqlType(sql)` -判断 SQL 语句类型。 - -| 类型 | 条件 | -|------|------| -| `"qry"` | 以 `SELECT` 开头 | -| `"dml"` | `INSERT`, `UPDATE`, `DELETE` | -| `"ddl"` | 其他（如 `CREATE`, `DROP`） | - ---- - -### SQL 模板处理 - -#### `maskingSQL(org_sql, NS)` -将命名参数 `${var}$` 替换为 `?` 并生成参数列表。 - -##### 步骤 -1. 先替换 `$[...]$` 模板片段（如条件块） -2. 提取 `${var}$` 参数名 -3. 替换为 `?` 占位符 -4. 返回 `(标记后的SQL, 参数值列表)` - -##### 特殊变量 -- `__mainsql__`: 不参与参数绑定，用于嵌套 SQL 注入 - ---- - -### 执行方法 - -#### `execute(sql, value, callback, **kwargs)` -执行单条 SQL，支持回调逐行处理结果。 - -##### 流程 -- 调用 `runVarSQL` 执行 SQL -- 若是查询 (`qry`) 且有回调，则逐行调用 `callback(DictObject(row))` -- 若是 DML，标记 `dataChanged=True` - -#### `executemany(sql, values)` -批量执行 SQL（适用于 `INSERT` 等） - ---- - -### 分页与排序 - -#### `sortSQL(sql, NS)` -添加 `ORDER BY` 子句。 - -- 支持 `NS['sort']` 为字符串或列表 - -#### `pagingSQL(sql, paging, NS)` -构建分页 SQL，需配合 `pagingSQLmodel()` 使用。 - -> 默认为空，需由子类重写提供具体数据库分页语法（如 MySQL 的 `LIMIT OFFSET` 或 Oracle 的 `ROWNUM`） - -##### 参数 -- `pagename`: 页码参数名（默认 `'page'`） -- `rowsname`: 每页行数（默认 `'rows'`） -- `sortname`: 排序字段（可选） - -##### 示例 NS -```python -{ - 'page': 2, - 'rows': 20, - 'sort': 'id desc' -} -``` - -#### `recordCnt(sql)` -包装 SQL 查询总记录数： - -```sql -SELECT COUNT(*) rcnt FROM (your_sql) rowcount_table -``` - ---- - -### 过滤器支持 - -#### `filterSQL(sql, filters, NS)` -将一组条件过滤器合并进原 SQL。 - -每个 filter 是一个带 `${}` 的模板字符串，若其中变量未在 `NS` 中存在，则忽略此条件（替换为 `1=1`）。 - -最终生成： -```sql -SELECT * FROM (original_sql) filter_table WHERE f1 AND f2 ... -``` - ---- - -### Pivot 表格转换 - -#### `pivotSQL(tablename, rowFields, columnFields, valueFields)` -生成透视表 SQL。 - -##### 逻辑 -1. 查询 `columnFields` 的所有唯一值作为列头 -2. 使用 `CASE WHEN` 构造每列聚合 -3. 使用 `SUM` 聚合数值字段 - -##### 示例输出 -```sql -SELECT dept, - SUM(salary_0) salary_0, -- 北京 - SUM(salary_1) salary_1 -- 上海 -FROM ( - SELECT dept, - CASE WHEN city='北京' THEN salary ELSE 0 END AS salary_0, - CASE WHEN city='上海' THEN salary ELSE 0 END AS salary_1 - FROM employees -) GROUP BY dept; -``` - -#### `pivot(desc, ...)` -执行 pivot 查询并返回结果列表。 - ---- - -### 元数据查询方法 - #### `tables()` 返回数据库中所有表的列表。 @@ -592,4 +309,4 @@ def pagingSQLmodel(self): 📝 **版本**: v1.0 📅 **最后更新**: 2025-04-05 -👨‍💻 **作者**: Auto-generated Documentation Tool \ No newline at end of file +👨‍💻 **作者**: Auto-generated Documentation Tool