# httpSQLiteDB

**Repository Path**: gdndzzk/httpLevelDB

## Basic Information

- **Project Name**: httpSQLiteDB
- **Description**: 基于SQLite,https://github.com/Koishi-Satori/net_safeio的替代品
- **Primary Language**: Unknown
- **License**: WTFPL
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-09-20
- **Last Updated**: 2025-09-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Net SafeIO HTTP Server (Python + SQLite + FastAPI)

这是一个基于 Python + SQLite + FastAPI 重新实现的 Net SafeIO HTTP 服务器，作为原始 Kotlin + Netty 版本的替代品。它提供高稳定性、低占用的数据存储服务，具有平台无关性。

## 功能特性

- 数据合并（Merge）- 通过 `/write_data` 接口
- 数据覆写（Override）- 通过 `/override` 接口
- 数据查询（Read）- 通过 `/read_data` 接口
- 单个数据项查询 - 通过 `/get/{key}` 接口
- 单个数据项删除 - 通过 `/delete/{key}` 接口
- 支持从 JSON 文件迁移数据
- 完全兼容原始 API 接口
- 自动生成 Swagger UI 文档
- **新增：WebUI 界面** - 通过浏览器访问 `http://localhost:[port]` 进行数据管理

## 系统要求

- Python 3.7 或更高版本
- pip 包管理器

## 安装依赖

```bash
pip install -r requirements.txt
```

## 启动参数

| 参数 | 长格式   | 描述                               | 示例                      |
| ---- | -------- | ---------------------------------- | ------------------------- |
| -p   | --port   | 设置绑定的端口号                   | `-p 1145`               |
| -d   | --dir    | 设置数据存储目录                   | `-d "./data"`           |
| -f   | --file   | 设置初始JSON文件路径，用于数据迁移 | `-f "ifp_data.json"`    |
| -e   | --export | 设置导出JSON文件路径，用于数据导出 | `-e "export_data.json"` |

## 启动命令

```bash
python app.py [参数]
```

### 示例

1. 使用默认参数启动：

```bash
python app.py
```

2. 指定端口和数据目录：

```bash
python app.py -p 8080 -d "./mydata"
```

3. 从现有 JSON 文件迁移数据：

```bash
python app.py -f "ifp_data.json"
```

4. 导出数据到 JSON 文件：

```bash
python app.py -e "export_data.json"
```

## WebUI 界面

项目现在提供了一个直观的WebUI界面，您可以通过浏览器轻松管理数据。

### 访问方式

启动服务器后，在浏览器中访问 `http://localhost:[port]` 即可打开WebUI界面。

### WebUI 功能

- **数据展示**：以表格形式展示所有键值对数据
- **添加/更新数据**：通过表单添加新的键值对或更新现有数据
- **查询数据**：根据键查询特定数据
- **编辑数据**：直接在表格中编辑现有数据
- **删除数据**：删除单个键值对或清空所有数据
- **批量操作**：
  - 导出数据为JSON文件
  - 从JSON文件导入数据
- **响应式设计**：适配不同屏幕尺寸的设备

## API 接口

### 基础信息

- **基础 URL**: `http://localhost:[port]`
- **数据格式**: JSON
- **编码**: UTF-8
- **传输数据**: 必须为由 `table<string, string>` 序列化来的 JSON
- **返回数据**: JSON 格式
- **Swagger UI**: `http://localhost:[port]/docs`
- **WebUI**: `http://localhost:[port]`

### 1. 读取数据

**接口地址**: `/read_data`

**请求方法**: GET

**请求参数**: 无

**响应示例**:

```json
{
  "key1": "value1",
  "key2": "value2"
}
```

**响应状态码**:

- 200 OK: 成功
- 500 INTERNAL_SERVER_ERROR: 内部错误

### 2. 合并数据

**接口地址**: `/write_data`

**请求方法**: POST

**请求头**:

```
Content-Type: application/json
```

**请求体**:

```json
{
  "key1": "value1",
  "key2": "value2"
}
```

**功能说明**:

- 将新数据与现有数据合并
- 如果键已存在，则更新其值
- 如果键不存在，则添加新的键值对
- 保留数据库中所有未在请求中提及的现有数据

**响应示例**:

```
ok
```

**响应状态码**:

- 200 OK: 成功
- 400 BAD_REQUEST: 请求格式错误（如非 JSON 格式）
- 500 INTERNAL_SERVER_ERROR: 内部错误
- 507 INSUFFICIENT_STORAGE: IO 错误

### 3. 获取单个数据项

**接口地址**: `/get/{key}`

**请求方法**: GET

**路径参数**:
- `key`: 要查询的键

**响应示例**:

```json
{
  "key1": "value1"
}
```

**响应状态码**:

- 200 OK: 成功
- 404 NOT_FOUND: 键不存在
- 500 INTERNAL_SERVER_ERROR: 内部错误

### 4. 删除单个数据项

**接口地址**: `/delete/{key}`

**请求方法**: DELETE

**路径参数**:
- `key`: 要删除的键

**响应示例**:

```
ok
```

**响应状态码**:

- 200 OK: 成功
- 404 NOT_FOUND: 键不存在
- 500 INTERNAL_SERVER_ERROR: 内部错误

### 5. 覆写数据

**接口地址**: `/override`

**请求方法**: POST

**请求头**:

```
Content-Type: application/json
```

**请求体**:

```json
{
  "key1": "value1",
  "key2": "value2"
}
```

**功能说明**:

- 完全替换数据库中的所有数据
- 删除数据库中所有未在请求中提及的现有数据
- 仅保留请求中提供的数据

**响应示例**:

```
ok
```

**响应状态码**:

- 200 OK: 成功
- 400 BAD_REQUEST: 请求格式错误（如非 JSON 格式）
- 500 INTERNAL_SERVER_ERROR: 内部错误
- 507 INSUFFICIENT_STORAGE: IO 错误

### 接口区别说明

**`/write_data`（合并数据）与 `/override`（覆写数据）的区别**:

1. **数据保留方式**:

   - `/write_data`: 保留数据库中所有现有数据，只更新或添加请求中的数据
   - `/override`: 完全替换数据库中的所有数据，只保留请求中的数据
2. **使用场景**:

   - `/write_data`: 适用于需要添加新数据或更新部分数据的场景
   - `/override`: 适用于需要完全重置数据的场景
3. **示例对比**:

   假设数据库中已有数据：

   ```json
   {
     "name": "Player1",
     "score": "100",
     "level": "5"
   }
   ```

   发送请求：

   ```json
   {
     "score": "150",
     "items": "sword"
   }
   ```

   使用 `/write_data` 后，数据库内容为：

   ```json
   {
     "name": "Player1",    // 保留
     "score": "150",       // 更新
     "level": "5",         // 保留
     "items": "sword"      // 新增
   }
   ```

   使用 `/override` 后，数据库内容为：

   ```json
   {
     "score": "150",       // 仅保留请求中的数据
     "items": "sword"      // 仅保留请求中的数据
   }
   ```

## 数据存储

- 默认存储目录: `./data`
- 数据库类型: SQLite
- 数据格式: 键值对（Map<String, String>）

## 数据迁移

本版本支持从原始 JSON 文件迁移数据到 SQLite：

1. 准备 JSON 文件（格式与原始版本兼容）：

```json
{
  "key1": "value1",
  "key2": "value2"
}
```

2. 使用 `-f` 参数启动服务器：

```bash
python app.py -f "path/to/your/data.json"
```

3. 服务器会自动读取 JSON 文件并将数据导入到 SQLite 中

## 数据导出

本版本支持将 SQLite 数据导出到 JSON 文件：

1. 使用 `-e` 参数导出数据：

```bash
python app.py -e "path/to/export/data.json"
```

2. 程序会自动读取 SQLite 中的所有数据并导出到指定的 JSON 文件中
3. 导出完成后程序会自动退出，不会启动服务器

注意：导出功能可以与其他参数一起使用，但如果只使用导出参数，程序会在导出完成后退出。

## 错误处理

所有接口在遇到错误时会返回相应的 HTTP 状态码和简短的错误信息：

- `bad json`: JSON 解析错误
- `io error`: 文件 IO 错误
- `internal error`: 内部服务器错误
- `bad request content: requires json type`: 请求内容类型错误
- `non-full content`: 请求内容不完整

## 部署建议

建议将 API 部署到本地，然后使用 `localhost:[port]` 作为 `api_url`。

## 示例使用流程

### 使用WebUI

1. **启动服务器**:

   ```bash
   python app.py -p 1145 -d ./data
   ```
2. **打开WebUI**:

   在浏览器中访问 `http://localhost:1145`
3. **使用WebUI进行数据管理**:
   - 添加/更新数据：填写键和值，点击"保存"按钮
   - 查询数据：在查询表单中输入键，点击"查询"按钮
   - 编辑数据：在数据表格中点击"编辑"按钮
   - 删除数据：在数据表格中点击"删除"按钮
   - 导出数据：点击"导出数据"按钮
   - 导入数据：点击"导入数据"按钮并选择JSON文件

### 使用API接口

1. **从json文件迁移数据并启动服务器**:

   ```bash
   python app.py -p 1145 -d ./data -f my_data.json
   ```
2. **导出数据**:

   ```bash
   python app.py -e exported_data.json
   ```
3. **写入数据** (使用 curl):

   ```bash
   curl -X POST -H "Content-Type: application/json" -d '{"player_name":"Player1","score":"100","level":"5"}' http://localhost:1145/write_data
   ```
4. **读取数据** (使用 curl):

   ```bash
   curl http://localhost:1145/read_data
   ```
5. **获取单个数据项** (使用 curl):

   ```bash
   curl http://localhost:1145/get/player_name
   ```
6. **删除单个数据项** (使用 curl):

   ```bash
   curl -X DELETE http://localhost:1145/delete/player_name
   ```
7. **覆写数据** (使用 curl):

   ```bash
   curl -X POST -H "Content-Type: application/json" -d '{"player_name":"Player1","score":"150","level":"6"}' http://localhost:1145/override
   ```

## 注意事项

1. 所有数据键值对必须是字符串类型，非字符串类型需要先序列化为字符串
2. 服务器会自动创建数据目录（如果不存在）
3. 合并操作（`/write_data`）会保留原有数据并添加新数据，如果键已存在则更新值
4. 覆写操作（`/override`）会完全替换原有数据
5. 导出操作（`-e` 参数）会将当前数据库中的所有数据导出到指定的 JSON 文件中
6. 建议在生产环境中使用适当的错误处理和重试机制
7. SQLite 数据库存储在指定的数据目录下的 `sqlite.db` 文件中

## 项目结构

```
httpLevelDB/
├── app.py                 # 主应用入口
├── static/               # WebUI静态文件
│   ├── index.html        # WebUI主页
│   ├── css/
│   │   └── style.css     # WebUI样式
│   └── js/
│       └── script.js     # WebUI交互逻辑
├── Util/
│   └── sqliteDict.py      # SQLite字典封装
├── requirements.txt       # 依赖包列表
├── README.md             # 项目文档
└── data/                 # 数据存储目录（自动创建）
    └── sqlite.db         # SQLite数据库文件
```