Nigel
/
mcp-swagger-server
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity
mcp-swagger-server/docs/nestjs-implementation-check...

7.8 KiB
Raw Blame History

NestJS 后端实施检查清单

🎯 项目目标

将现有的 Express 基础后端升级为企业级的 NestJS 架构，提供稳定、可扩展的 OpenAPI 到 MCP 转换服务。

✅ 第一阶段：项目搭建与基础配置 (预计：4-6小时)

🏗️ 项目初始化 (1小时)

  • 运行自动化脚本 
    .\scripts\setup-nestjs.ps1
  • 验证项目结构 
    packages/mcp-swagger-server-nestjs/
├── src/
├── test/
├── package.json
└── tsconfig.json

📦 依赖安装验证 (30分钟)

  • 核心 NestJS 依赖

    • @nestjs/core - 核心框架
    • @nestjs/common - 通用装饰器和工具
    • @nestjs/platform-express - Express 适配器

  • API 和文档依赖

    • @nestjs/swagger - Swagger 集成
    • @nestjs/config - 配置管理

  • 业务逻辑依赖

    • swagger-parser - OpenAPI 解析
    • @modelcontextprotocol/sdk - MCP 协议
    • class-validator & class-transformer - 验证和转换

  • 开发工具依赖

    • @nestjs/testing - 测试框架
    • jest - 单元测试
    • TypeScript 类型定义

⚙️ 基础配置 (2.5小时)

应用入口配置 (45分钟)

  • 修改 src/main.ts

    • 端口配置 (3322)
    • CORS 设置
    • 全局验证管道
    • Swagger 文档配置

  • 验证启动

    npm run start:dev
# 应该在 http://localhost:3322 启动
# Swagger 文档在 http://localhost:3322/docs

配置模块设置 (45分钟)

  • 创建 src/config/configuration.ts

    • 端口和 CORS 配置
    • API 超时和文件大小限制
    • Swagger 文档配置

  • 创建 src/config/validation.schema.ts

    • 环境变量验证规则
    • 配置值类型检查

应用模块架构 (45分钟)

  • 设计 src/app.module.ts
    • ConfigModule 导入
    • 各业务模块导入
    • 全局提供者配置

✅ 第二阶段：核心模块开发 (预计：2-3天)

📋 DTO 和类型定义 (4小时)

共享 DTO 创建

  • src/common/dto/api.dto.ts
    • InputSourceDto - 输入源定义
    • AuthDto - 认证信息
    • ConvertConfigDto - 转换配置
    • FilterConfigDto - 过滤选项
    • ApiResponseDto - 统一响应格式

API 请求 DTO

  • src/common/dto/request.dto.ts
    • ValidateRequestDto - 验证请求
    • PreviewRequestDto - 预览请求
    • ConvertRequestDto - 转换请求

API 响应 DTO

  • src/common/dto/response.dto.ts
    • ValidationResultDto - 验证结果
    • ApiPreviewDto - API 预览
    • McpConfigDto - MCP 配置结果

🔧 OpenAPI 处理模块 (8小时)

模块结构创建

  • src/modules/openapi/openapi.module.ts
    • 服务提供者配置
    • 控制器注册

核心服务实现

  • src/modules/openapi/openapi.service.ts
    • validateSpec() - OpenAPI 规范验证
    • parseSpecContent() - 内容解析
    • extractEndpoints() - 端点提取
    • previewApi() - API 预览生成

API 控制器

  • src/modules/openapi/openapi.controller.ts
    • POST /api/validate - 验证端点
    • POST /api/preview - 预览端点
    • Swagger 文档注解

单元测试

  • src/modules/openapi/openapi.service.spec.ts
    • 验证功能测试
    • 解析功能测试
    • 错误处理测试

🔄 转换服务模块 (6小时)

转换服务实现

  • src/modules/conversion/conversion.service.ts
    • convertToMcp() - 主转换方法
    • applyFilters() - 过滤器应用
    • optimizeEndpoints() - 端点优化
    • generateMcpTools() - MCP 工具生成

控制器实现

  • src/modules/conversion/conversion.controller.ts
    • POST /api/convert - 转换端点
    • 参数验证和错误处理

转换策略

  • src/modules/conversion/strategies/
    • default.strategy.ts - 默认转换策略
    • optimized.strategy.ts - 优化转换策略

🔌 MCP 协议模块 (4小时)

MCP 服务实现

  • src/modules/mcp/mcp.service.ts
    • generateMcpConfig() - 配置生成
    • validateMcpConfig() - 配置验证
    • 传输协议支持 (stdio, sse, streamable)

工具生成器

  • src/modules/mcp/tools/
    • tool-generator.service.ts - 工具生成逻辑
    • validation.helper.ts - 验证辅助函数

✅ 第三阶段：API 集成和测试 (预计：1-2天)

🔗 API 端点完整实现 (4小时)

端点功能验证

  • 验证端点 (POST /api/validate)

    • URL 输入支持
    • 文件输入支持
    • 文本输入支持
    • 认证头处理

  • 预览端点 (POST /api/preview)

    • API 信息提取
    • 端点列表生成
    • 统计信息计算

  • 转换端点 (POST /api/convert)

    • 完整转换流程
    • 配置选项应用
    • MCP 格式输出

错误处理和验证

  • 全局异常过滤器

    • src/common/filters/http-exception.filter.ts
    • 统一错误响应格式

  • 验证管道配置

    • 请求参数验证
    • 类型转换
    • 错误消息国际化

🧪 测试套件实现 (4小时)

单元测试

  • 服务层测试

    • OpenAPI 服务测试
    • 转换服务测试
    • MCP 服务测试

  • 控制器测试

    • API 端点测试
    • 参数验证测试
    • 错误处理测试

集成测试

  • 端到端测试
    • test/openapi.e2e-spec.ts
    • 完整请求流程测试
    • 真实 API 规范测试

测试覆盖率

  • 运行测试套件 
    npm run test         # 单元测试
npm run test:e2e     # 集成测试
npm run test:cov     # 覆盖率报告
  • 目标覆盖率 > 80%

✅ 第四阶段：前后端集成 (预计：1天)

🔌 前端集成 (4小时)

API 客户端更新

  • 修改 packages/mcp-swagger-ui/src/utils/api.ts
    • 更新 API 基础 URL (localhost:3322)
    • 移除 demo 模式
    • 添加真实 API 调用

类型定义同步

  • 共享类型定义
    • 复制 DTO 类型到前端
    • 确保前后端类型一致性

错误处理

  • 前端错误处理
    • API 错误捕获
    • 用户友好的错误消息
    • 网络错误重试机制

✅ 集成测试 (2小时)

完整流程测试

  • 上传 → 验证 → 预览 → 转换

    • 测试完整用户流程
    • 验证数据传递正确性

  • 边界情况测试

    • 大文件处理
    • 无效输入处理
    • 网络中断恢复

✅ 第五阶段：部署和文档 (预计：半天)

📦 部署准备 (2小时)

Docker 配置

  • 创建 Dockerfile

    • Node.js 基础镜像
    • 依赖安装
    • 应用构建

  • docker-compose.yml 更新

    • 后端服务配置
    • 环境变量设置
    • 端口映射

生产配置

  • 环境变量配置
    • .env.production
    • 日志级别配置
    • 性能优化设置

📚 文档更新 (1小时)

API 文档

  • Swagger 文档完善
    • 端点描述完整
    • 示例请求/响应
    • 错误代码说明

开发文档

  • 更新开发指南
    • NestJS 项目说明
    • 本地开发指引
    • 部署说明

🎯 验收标准

功能验收

  • ✅ 所有 API 端点正常工作
  • ✅ 前后端完整集成
  • ✅ 错误处理完善
  • ✅ 测试覆盖率 > 80%

性能验收

  • ✅ API 响应时间 < 3秒
  • ✅ 支持 10MB 以上文件
  • ✅ 并发处理能力 > 10 用户

代码质量验收

  • ✅ TypeScript 严格模式通过
  • ✅ ESLint 检查通过
  • ✅ 代码注释覆盖 > 70%

🚀 立即开始

第一步：运行搭建脚本

.\scripts\setup-nestjs.ps1

第二步：验证环境

cd packages\mcp-swagger-server-nestjs
npm run start:dev

第三步：开始开发 按照此检查清单逐步完成各个模块的开发和测试。

预计总开发时间：5-7 个工作日 预计代码质量：企业级标准 预计维护成本：低