dababase-etl-python/docs/doc.md

接口文档（主要接口）

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

{
  "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，可选（附加参数）
• 请求示例:

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

• 返回示例（成功）:

{
  "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
}

• 返回示例（失败）:

{
  "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（表数量）
• 返回示例:

{
  "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
• 返回示例:

{
  "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样例）:

{
  "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