bugfix
This commit is contained in:
parent
d3c9c060ea
commit
b815d7e701
287
aidocs/sor.md
287
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 |
|
| 异步支持 | 支持 `async/await` 模式运行 SQL |
|
||||||
| 分页查询 | 自动生成分页 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()`
|
#### `tables()`
|
||||||
返回数据库中所有表的列表。
|
返回数据库中所有表的列表。
|
||||||
|
|
||||||
|
|||||||
Loading…
x
Reference in New Issue
Block a user