148 lines
4.1 KiB
Markdown
148 lines
4.1 KiB
Markdown
# 跨数据库通用查询服务（基于 SQLAlchemy Core）
|
||
|
||
一个安全的 HTTP 服务，通过结构化 JSON 描述查询意图，后端自动转换为对应数据库的 SQL，无需手写 SQL，即可无缝切换 SQLite、PostgreSQL、MySQL 等数据库。
|
||
|
||
## 功能特点
|
||
|
||
- **跨数据库**：基于 SQLAlchemy Core 表达式语言，一套接口适配多种数据库
|
||
- **零 SQL 注入**：所有条件、值均通过 SQLAlchemy 参数绑定处理
|
||
- **统一 JSON 接口**：`action` + `table` + `conditions` 模式
|
||
- **支持增删改查**：select, insert, update, delete 全覆盖
|
||
- **单线程本地监听**：waitress + 127.0.0.1:8005，简单可靠
|
||
|
||
## 快速开始
|
||
|
||
### 安装依赖
|
||
```bash
|
||
pip install flask sqlalchemy waitress
|
||
# 根据需要安装数据库驱动，例如：
|
||
# pip install psycopg2-binary # PostgreSQL
|
||
# pip install pymysql # MySQL
|
||
```
|
||
|
||
### 启动服务（默认 SQLite）
|
||
```bash
|
||
python app.py
|
||
```
|
||
服务运行在 `http://127.0.0.1:8005`。
|
||
|
||
使用其他数据库：
|
||
```bash
|
||
export DATABASE_URL="postgresql://user:pass@localhost/dbname"
|
||
python app.py
|
||
```
|
||
|
||
**注意**：新接口依赖表已存在（通过反射获取结构）。首次使用时请先手动建表：
|
||
```bash
|
||
sqlite3 database.db "CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT, age INTEGER)"
|
||
```
|
||
|
||
## API 文档
|
||
|
||
### 请求格式
|
||
|
||
**端点**：`POST /execute`
|
||
**Content-Type**：`application/json`
|
||
|
||
```json
|
||
{
|
||
"action": "操作类型", // select | insert | update | delete
|
||
"table": "表名",
|
||
"columns": ["列1", "列2"], // select/insert 时可选
|
||
"values": { // insert/update 时必填
|
||
"列名": "值"
|
||
},
|
||
"where": { // 条件，支持组合操作符
|
||
"age": {"ge": 18, "lt": 60},
|
||
"name": "Alice"
|
||
},
|
||
"order_by": [{"column": "age", "desc": true}],
|
||
"limit": 10,
|
||
"offset": 0
|
||
}
|
||
```
|
||
|
||
### where 条件支持的运算符
|
||
|
||
| 运算符 | 说明 | 示例 |
|
||
|--------|------|------|
|
||
| 直接值 | 等于 | `"name": "Alice"` |
|
||
| eq | 等于 | `"age": {"eq": 30}` |
|
||
| ne | 不等于 | `"status": {"ne": "deleted"}` |
|
||
| gt | 大于 | `"score": {"gt": 80}` |
|
||
| ge | 大于等于 | `"score": {"ge": 60}` |
|
||
| lt | 小于 | `"price": {"lt": 100}` |
|
||
| le | 小于等于 | `"price": {"le": 200}` |
|
||
| like | 模糊匹配 | `"name": {"like": "%Smith%"}` |
|
||
| in | 包含于列表 | `"id": {"in": [1,2,3]}` |
|
||
|
||
多个条件自动使用 **AND** 连接。
|
||
|
||
### 响应格式
|
||
|
||
成功：
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": [ // 查询结果数组（insert/update/delete 时包含影响行数或 lastrowid）
|
||
{"id": 1, "name": "Alice"}
|
||
]
|
||
}
|
||
```
|
||
|
||
失败：
|
||
```json
|
||
{
|
||
"success": false,
|
||
"error": "错误描述"
|
||
}
|
||
```
|
||
|
||
## 使用示例（curl）
|
||
|
||
**插入**：
|
||
```bash
|
||
curl -X POST http://127.0.0.1:8005/execute \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"action":"insert","table":"users","values":{"name":"Bob","age":25}}'
|
||
```
|
||
|
||
**查询**：
|
||
```bash
|
||
curl -X POST http://127.0.0.1:8005/execute \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"action":"select","table":"users","where":{"age":{"gt":20}},"order_by":[{"column":"id","desc":true}],"limit":5}'
|
||
```
|
||
|
||
**更新**：
|
||
```bash
|
||
curl -X POST http://127.0.0.1:8005/execute \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"action":"update","table":"users","values":{"age":26},"where":{"name":"Bob"}}'
|
||
```
|
||
|
||
**删除**：
|
||
```bash
|
||
curl -X POST http://127.0.0.1:8005/execute \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"action":"delete","table":"users","where":{"id":{"in":[1,2]}}}'
|
||
```
|
||
|
||
## 安全机制
|
||
|
||
- 强制使用 SQLAlchemy 参数绑定，杜绝 SQL 注入。
|
||
- 仅反射已有表，无法创建或删除表（保证结构安全）。
|
||
- 所有异常自动回滚事务。
|
||
- 默认监听 `127.0.0.1`，仅本机可访问。
|
||
|
||
## 切换数据库
|
||
|
||
只需修改环境变量 `DATABASE_URL`，并安装对应驱动：
|
||
|
||
- SQLite：`sqlite:///database.db`
|
||
- PostgreSQL：`postgresql://user:pass@localhost/dbname` （需 `pip install psycopg2`）
|
||
- MySQL：`mysql+pymysql://user:pass@localhost/dbname` （需 `pip install pymysql`）
|
||
|
||
SQLAlchemy 会自动生成适配各数据库的 SQL 方言，无需修改接口调用。
|
||
|