MCP/database

Fork 0

zpc bd1e1201f1 12

2025-12-27 16:21:09 +08:00

15 KiB

Raw Permalink Blame History

v1.0.2 文件变更清单

本文档列出 v1.0.2 版本开发中所有需要创建、修改或删除的文件。

一、新增文件

1.1 驱动层文件

src/drivers/
├── database-driver.ts              # 驱动接口定义 [NEW]
├── driver-factory.ts               # 驱动工厂 [NEW]
├── types.ts                        # 驱动相关类型定义 [NEW]
├── index.ts                        # 驱动层统一导出 [NEW]
├── postgres/
│   ├── postgres-driver.ts         # PostgreSQL 驱动实现 [NEW]
│   └── index.ts                   # PostgreSQL 驱动导出 [NEW]
└── sqlserver/
    ├── sqlserver-driver.ts        # SQL Server 驱动实现 [NEW]
    ├── type-mappings.ts           # SQL Server 类型映射 [NEW]
    └── index.ts                   # SQL Server 驱动导出 [NEW]

预估代码量:

database-driver.ts: ~300 行 (接口定义)
driver-factory.ts: ~50 行
postgres-driver.ts: ~800 行
sqlserver-driver.ts: ~900 行
其他: ~200 行
总计: ~2250 行

1.2 测试文件

__tests__/
├── drivers/
│   ├── postgres-driver.test.ts    # PostgreSQL 驱动单元测试 [NEW]
│   └── sqlserver-driver.test.ts   # SQL Server 驱动单元测试 [NEW]
├── integration/
│   ├── postgres.test.ts           # PostgreSQL 集成测试 [NEW]
│   ├── sqlserver.test.ts          # SQL Server 集成测试 [NEW]
│   └── mixed-env.test.ts          # 混合环境测试 [NEW]
└── e2e/
    └── full-workflow.test.ts      # 端到端测试 [NEW]

预估代码量:

单元测试: ~400 行
集成测试: ~600 行
端到端测试: ~300 行
总计: ~1300 行

1.3 文档文件

docs/1.0.2版本需求/
├── 01-开发计划总览.md             # 已创建 ✅
├── 02-架构设计方案.md             # 已创建 ✅
├── 03-数据库差异对比表.md         # 已创建 ✅
├── 04-详细实施步骤.md             # 已创建 ✅
├── 05-文件变更清单.md             # 本文件 ✅
├── 06-SQL-Server配置指南.md       # 待创建 [NEW]
└── 07-迁移指南.md                 # 待创建 [NEW]

1.4 配置示例文件

config/
├── database.sqlserver.example.json    # SQL Server 配置示例 [NEW]
└── database.mixed.example.json        # 混合环境配置示例 [NEW]

1.5 脚本文件

scripts/
├── test-sqlserver-connection.ts       # SQL Server 连接测试脚本 [NEW]
└── migrate-config.ts                  # 配置迁移脚本 (可选) [NEW]

二、需要修改的文件

2.1 核心层文件

文件路径	变更类型	主要变更内容
`src/core/connection-manager.ts`	重构	1. 构造函数接收 `driver: DatabaseDriver` 2. 使用 `driver.createConnectionPool()` 3. 使用 `driver.supportsSearchPath()` 4. 使用 `driver.buildSetSchemaStatement()`
`src/core/query-runner.ts`	重构	1. 构造函数接收 `driver: DatabaseDriver` 2. 使用 `driver.execute()` 3. 使用 `driver.buildPaginatedQuery()` 4. 使用 `driver.buildExplainQuery()`
`src/core/metadata-browser.ts`	重构	1. 构造函数接收 `driver: DatabaseDriver` 2. 使用 `driver.buildListSchemasQuery()` 等 3. 使用 `driver.parseTableDefinition()`
`src/core/bulk-helpers.ts`	重构	1. 构造函数接收 `driver: DatabaseDriver` 2. 使用 `driver.buildBulkInsertStatement()` 3. 使用 `driver.buildBulkUpsertStatement()`
`src/core/diagnostics.ts`	重构	1. 构造函数接收 `driver: DatabaseDriver` 2. 使用 `driver.buildGetActiveConnectionsQuery()` 3. 使用 `driver.supportsDiagnostic()` 检查功能支持
`src/core/transaction-manager.ts`	小幅修改	1. 构造函数接收 `driver: DatabaseDriver` 2. 使用 `driver.buildBeginStatement()` 等
`src/core/index.ts`	重构	1. 重命名 `PostgresMcp` 为 `DatabaseMcp` 2. 构造函数接收 `driver` 参数 3. 保留 `PostgresMcp` 作为别名 (向后兼容)

预估代码变更量: ~1000 行修改

2.2 配置层文件

文件路径	变更类型	主要变更内容
`src/config/types.ts`	扩展	1. `EnvironmentConfig.type` 支持 `'sqlserver'` 2. 新增 `SqlServerConnection` 接口 3. 使用联合类型 `PostgresConnection \| SqlServerConnection`
`src/config/loader.ts`	小幅修改	1. 添加 SQL Server 配置验证 2. 验证不同数据库类型的特定字段
`src/config/env-resolver.ts`	无需修改	环境变量解析逻辑保持不变

预估代码变更量: ~150 行新增/修改

2.3 服务器入口文件

文件路径	变更类型	主要变更内容
`src/server.ts`	重要修改	1. 导入 `createDriver` 工厂函数 2. 根据环境配置创建驱动实例 3. 创建 `DatabaseMcp` 时传入驱动 4. 支持混合环境 (可选)

代码示例:

// 之前
import { PostgresMcp } from './core/index.js';
const pgMcp = new PostgresMcp(envConfigs);

// 之后
import { createDriver } from './drivers/driver-factory.js';
import { DatabaseMcp } from './core/index.js';

const firstEnvType = Object.values(envConfigs)[0].type;
const driver = createDriver(firstEnvType);
const dbMcp = new DatabaseMcp(envConfigs, driver);

预估代码变更量: ~100 行修改

2.4 工具层文件

文件路径	变更类型	主要变更内容
`src/tools/metadata.ts`	小幅修改	工具描述更新为数据库无关 (从 "PostgreSQL tables" → "Database tables")
`src/tools/query.ts`	小幅修改	同上
`src/tools/data.ts`	小幅修改	同上
`src/tools/diagnostics.ts`	小幅修改	同上,并添加功能支持检查
`src/tools/index.ts`	无需修改	工具注册逻辑保持不变

预估代码变更量: ~50 行修改 (主要是描述文本)

2.5 其他文件

文件路径	变更类型	主要变更内容
`package.json`	新增依赖	1. 添加 `"mssql": "^10.0.0"` 2. 添加 `"@types/mssql": "^9.1.0"` 3. 更新版本号为 `"1.0.2"`
`package-lock.json`	自动更新	npm install 后自动生成
`tsconfig.json`	无需修改	TypeScript 配置保持不变
`changelog.json`	新增条目	添加 v1.0.2 版本条目
`README.md`	更新	1. 更新功能列表 2. 添加 SQL Server 支持说明 3. 更新配置示例
`CLAUDE.md`	更新	1. 更新架构说明 2. 添加驱动层说明 3. 更新配置说明

三、不需要修改的文件

以下文件在 v1.0.2 开发中保持不变:

src/
├── audit/
│   └── audit-logger.ts           ✅ 无需修改 (与数据库无关)
├── auth/
│   └── token-auth.ts             ✅ 无需修改 (与数据库无关)
├── health/
│   └── health-check.ts           ✅ 可能小幅修改 (支持多驱动类型)
├── session/
│   └── session-manager.ts        ✅ 无需修改 (与数据库无关)
├── transport/
│   ├── unified-server.ts         ✅ 无需修改
│   ├── websocket-server-transport.ts  ✅ 无需修改
│   └── sse-server-transport.ts   ✅ 无需修改
└── core/
    ├── types.ts                  ✅ 无需修改
    └── utils.ts                  ⚠️ 可能需要移除 quoteIdentifier (改用驱动)

四、文件变更统计

4.1 按类型统计

变更类型	文件数量	预估代码行数
新增文件	24	~3550 行
修改文件	18	~1300 行修改
删除文件	0	0
总计	42	~4850 行

4.2 按模块统计

模块	新增文件	修改文件	代码行数
驱动层	8	0	~2250 行
核心层	0	7	~1000 行
配置层	2	2	~150 行
工具层	0	5	~50 行
测试层	6	0	~1300 行
文档层	7	2	N/A
脚本层	2	0	~100 行
其他	4	2	N/A
总计	29	18	~4850 行

五、版本控制建议

5.1 Git 分支策略

main
  ↓
develop (v1.0.2-dev)
  ├─ feature/driver-interface       # 驱动接口设计
  ├─ feature/postgres-driver         # PostgreSQL 驱动提取
  ├─ feature/core-refactor           # 核心层重构
  ├─ feature/sqlserver-driver        # SQL Server 驱动实现
  ├─ feature/config-extension        # 配置扩展
  ├─ feature/tests                   # 测试编写
  └─ feature/docs                    # 文档更新

5.2 提交规范

feat: 添加数据库驱动接口定义
refactor: 重构 ConnectionManager 使用驱动
feat: 实现 SQL Server 驱动
test: 添加 SQL Server 集成测试
docs: 更新架构设计文档

六、文件变更检查清单

阶段一完成检查

src/drivers/database-driver.ts 已创建
src/drivers/driver-factory.ts 已创建
src/drivers/postgres/postgres-driver.ts 已创建
src/core/connection-manager.ts 已重构
src/core/query-runner.ts 已重构
src/core/metadata-browser.ts 已重构
src/core/bulk-helpers.ts 已重构
src/core/diagnostics.ts 已重构
src/core/index.ts 已重构
src/server.ts 已更新
所有现有测试通过

阶段二完成检查

package.json 已添加 mssql 依赖
src/drivers/sqlserver/sqlserver-driver.ts 已创建
src/config/types.ts 已扩展
SQL Server 连接测试通过
SQL Server 基本 CRUD 测试通过

阶段三完成检查

SQL Server 所有元数据查询实现
SQL Server 批量操作实现
SQL Server 诊断功能实现
所有 MCP 工具支持 SQL Server
集成测试全部通过

阶段四完成检查

README.md 已更新
CLAUDE.md 已更新
changelog.json 已更新
docs/1.0.2版本需求/06-SQL-Server配置指南.md 已创建
docs/1.0.2版本需求/07-迁移指南.md 已创建
代码覆盖率 > 80%
性能测试报告完成

七、关键文件详细变更

7.1 src/core/connection-manager.ts

变更前:

import { Pool } from 'pg';

export class PostgresConnectionManager {
  private pools = new Map<string, Pool>();

  getPool(name: string): Pool {
    // ...
  }
}

变更后:

import { DatabaseDriver } from '../drivers/database-driver.js';

export class ConnectionManager {
  constructor(
    private configs: Record<string, EnvironmentConfig>,
    private driver: DatabaseDriver
  ) {}

  getPool(name: string): any {
    const pool = this.driver.createConnectionPool(config);
    // ...
  }
}

关键变更:

类名从 PostgresConnectionManager 改为 ConnectionManager
移除对 pg 库的直接依赖
构造函数新增 driver 参数
Pool 类型改为 any (驱动特定)

7.2 src/core/index.ts

变更前:

export class PostgresMcp {
  public readonly connections: PostgresConnectionManager;
  // ...

  constructor(configs: Record<string, EnvironmentConfig>) {
    this.connections = new PostgresConnectionManager(configs);
    // ...
  }
}

变更后:

export class DatabaseMcp {
  public readonly connections: ConnectionManager;
  // ...

  constructor(
    configs: Record<string, EnvironmentConfig>,
    driver: DatabaseDriver
  ) {
    this.connections = new ConnectionManager(configs, driver);
    // ...
  }
}

// 向后兼容
export class PostgresMcp extends DatabaseMcp {}

关键变更:

主类名从 PostgresMcp 改为 DatabaseMcp
构造函数新增 driver 参数
保留 PostgresMcp 作为别名

7.3 src/server.ts

变更前:

import { PostgresMcp } from './core/index.js';

const pgMcp = new PostgresMcp(envConfigs);
registerAllTools(mcpServer, pgMcp);

变更后:

import { createDriver } from './drivers/driver-factory.js';
import { DatabaseMcp } from './core/index.js';

// 检查是否所有环境都是同一类型
const firstEnvType = Object.values(envConfigs)[0].type;
const allSameType = Object.values(envConfigs).every(
  env => env.type === firstEnvType
);

if (!allSameType) {
  throw new Error('Mixed database types in environments not yet supported');
}

const driver = createDriver(firstEnvType);
const dbMcp = new DatabaseMcp(envConfigs, driver);
registerAllTools(mcpServer, dbMcp);

关键变更:

导入驱动工厂
根据环境类型创建驱动
实例化时传入驱动

八、风险文件清单

以下文件变更风险较高,需要特别注意:

文件	风险等级	风险描述	缓解措施
`src/core/connection-manager.ts`	🔴 高	核心连接管理,影响所有数据库操作	充分测试,保留备份
`src/core/query-runner.ts`	🔴 高	查询执行核心,影响所有查询	充分测试,保留备份
`src/core/metadata-browser.ts`	🟡 中	元数据查询,影响工具功能	单元测试覆盖
`src/server.ts`	🟡 中	服务器入口,影响启动流程	渐进式修改,保留回退路径
`src/config/types.ts`	🟢 低	配置类型,但影响面广	使用联合类型保持兼容

九、迁移和回滚计划

9.1 向前迁移

备份当前版本

git checkout -b backup-v1.0.1.03
git tag v1.0.1.03-backup

创建开发分支
```
git checkout -b develop-v1.0.2
```

逐步合并 feature 分支

git merge feature/driver-interface
git merge feature/postgres-driver
# ...

9.2 回滚计划

如果 v1.0.2 开发出现严重问题:

# 回滚到 v1.0.1.03
git checkout v1.0.1.03-backup

# 或保留部分改动
git revert <problematic-commit>

十、部署检查清单

部署前检查

所有测试通过 (npm test)
构建成功 (npm run build)
代码 lint 通过 (npm run lint)
文档完整
changelog 更新
package.json 版本正确
Docker 镜像构建成功
性能测试通过
安全扫描通过

部署后验证

PostgreSQL 环境正常
SQL Server 环境正常
健康检查端点返回正确
MCP 工具全部可用
审计日志正常
无内存泄漏
连接池正常工作

文档维护:

负责人: [待指定]
最后更新: 2024-12-27

15 KiB Raw Permalink Blame History

v1.0.2 文件变更清单

一、新增文件

1.1 驱动层文件

1.2 测试文件

1.3 文档文件

1.4 配置示例文件

1.5 脚本文件

二、需要修改的文件

2.1 核心层文件

2.2 配置层文件

2.3 服务器入口文件

2.4 工具层文件

2.5 其他文件

三、不需要修改的文件

四、文件变更统计

4.1 按类型统计

4.2 按模块统计

五、版本控制建议

5.1 Git 分支策略

5.2 提交规范

六、文件变更检查清单

阶段一完成检查

阶段二完成检查

阶段三完成检查

阶段四完成检查

七、关键文件详细变更

7.1 src/core/connection-manager.ts

7.2 src/core/index.ts

7.3 src/server.ts

八、风险文件清单

九、迁移和回滚计划

9.1 向前迁移

9.2 回滚计划

十、部署检查清单

部署前检查

部署后验证

15 KiB

Raw Permalink Blame History