# 接口文档（主要接口）

以下文档覆盖 README 中“主要接口包括”的四项能力：测试连通、获取数据库信息、获取所有表及备注信息、获取表字段及备注信息。所有接口均遵循统一返回结构：

```json
{
  "success": true,
  "message": "描述信息",
  "data": { "具体数据" },
  "error": null
}
```

## 1. 测试能否连通数据库
- URL: `/api/v1/connections/test`
- Method: `POST`
- Content-Type: `application/json`
- 请求体参数（DatabaseConnection）:
  - db_type: string（mysql|oracle|sqlserver|postgresql）
  - host: string
  - port: number
  - username: string
  - password: string
  - database: string，可选
  - mode: string，可选（Oracle专用）
  - threaded: boolean，可选（Oracle专用）
  - extra_params: object，可选（附加参数）
- 请求示例:

```json
{
  "db_type": "mysql",
  "host": "127.0.0.1",
  "port": 3306,
  "username": "root",
  "password": "pass",
  "database": "test_db"
}
```

- 返回示例（成功）:

```json
{
  "success": true,
  "message": "数据库连通性测试成功",
  "data": {
    "ok": true,
    "db_type": "mysql",
    "connection_url": "mysql+pymysql://root:***@127.0.0.1:3306/test_db?charset=utf8mb4",
    "server_version": "8.0.36"
  },
  "error": null
}
```

- 返回示例（失败）:

```json
{
  "success": false,
  "message": "连接测试失败: 认证失败",
  "data": null,
  "error": "认证失败"
}
```

## 2. 获取数据库信息
- URL: `/api/v1/databases/info`
- Method: `GET`
- Query 参数:
  - connection_id: string（创建连接时生成的连接ID）
- 返回字段:
  - database_name: string
  - tables: string[]（所有表名）
  - table_count: number（表数量）
- 返回示例:

```json
{
  "success": true,
  "message": "获取数据库信息成功",
  "data": {
    "database_name": "test_db",
    "tables": ["users", "orders", "products"],
    "table_count": 3
  },
  "error": null
}
```

## 3. 获取数据库中所有的表和表备注信息
- URL: `/api/v1/tables/details`
- Method: `GET`
- Query 参数:
  - connection_id: string
- 返回字段:
  - tables: 数组，每项包含
    - table_name: string
    - table_comment: string|null
  - table_count: number
- 返回示例:

```json
{
  "success": true,
  "message": "获取表及备注信息成功",
  "data": {
    "tables": [
      { "table_name": "users", "table_comment": "用户信息表" },
      { "table_name": "orders", "table_comment": "订单表" },
      { "table_name": "products", "table_comment": "" }
    ],
    "table_count": 3
  },
  "error": null
}
```

说明：不同数据库的备注来源
- MySQL: INFORMATION_SCHEMA.TABLES.TABLE_COMMENT
- PostgreSQL: pg_class/obj_description
- SQL Server: sys.extended_properties('MS_Description')
- Oracle: user_tab_comments

## 4. 获取数据表中字段名和类型以及备注信息
- URL: `/api/v1/tables/columns`
- Method: `GET`
- Query 参数:
  - connection_id: string
  - table_name: string
- 返回字段:
  - table_name: string
  - columns: 数组，每项包含
    - column_name: string
    - data_type: string
    - is_nullable: string|boolean（不同库返回值格式略有差异）
    - column_default: string|null
    - column_comment: string|null
    - max_length: number|null
    - numeric_precision: number|null（部分库返回）
    - numeric_scale: number|null（部分库返回）
- 返回示例（MySQL样例）:

```json
{
  "success": true,
  "message": "获取字段信息成功",
  "data": {
    "table_name": "users",
    "columns": [
      {
        "column_name": "id",
        "data_type": "int",
        "is_nullable": "NO",
        "column_default": null,
        "column_comment": "主键ID",
        "max_length": null,
        "numeric_precision": 10,
        "numeric_scale": 0
      },
      {
        "column_name": "name",
        "data_type": "varchar",
        "is_nullable": "YES",
        "column_default": null,
        "column_comment": "用户名",
        "max_length": 255,
        "numeric_precision": null,
        "numeric_scale": null
      }
    ]
  },
  "error": null
}
```

说明：不同数据库的字段备注来源
- MySQL: INFORMATION_SCHEMA.COLUMNS.COLUMN_COMMENT
- PostgreSQL: col_description + format_type
- SQL Server: sys.extended_properties('MS_Description')
- Oracle: user_col_comments + user_tab_columns