296 lines
9.1 KiB
Markdown
296 lines
9.1 KiB
Markdown
Flask Prompt Master 项目重构方案
|
||
|
||
上下文和目标
|
||
|
||
项目概况：D:/aaa/aitsc 是一个 Flask 应用程序，提供多种 AI 驱动的功能（提示词模板、饭菜规划、旅行攻略、会议
|
||
纪要、简历优化等）。项目采用蓝图架构，但随着功能增加出现了代码质量问题。
|
||
|
||
当前问题：
|
||
1. 安全漏洞：多个路由文件中存在硬编码的 API 密钥和数据库密码
|
||
2. 代码结构：routes.py 文件过大（1300+ 行），职责不单一
|
||
3. API 设计不一致：多种响应格式和错误处理方式
|
||
4. 认证系统碎片化：同时使用会话、令牌和微信认证
|
||
5. 配置管理混乱：新旧配置系统并存
|
||
6. 代码重复：相似功能间存在重复代码
|
||
|
||
重构目标：
|
||
1. 消除安全漏洞，移除所有硬编码的敏感信息
|
||
2. 提高代码可维护性，优化项目结构
|
||
3. 标准化 API 设计和错误处理
|
||
4. 集中化认证和授权系统
|
||
5. 实现关注点分离（业务逻辑与表现层分离）
|
||
|
||
重构方案概述
|
||
|
||
目标架构
|
||
|
||
flask_prompt_master/
|
||
├── app/ # 应用层（API/Web 路由）
|
||
├── core/ # 核心业务逻辑（服务层）
|
||
├── infrastructure/ # 基础设施（配置、数据库、外部服务）
|
||
├── shared/ # 共享组件（工具类、数据模型、常量）
|
||
├── tests/ # 测试套件
|
||
└── docs/ # 文档
|
||
|
||
核心改进
|
||
|
||
6. 安全加固：环境变量管理，JWT 认证，安全头部
|
||
7. API 标准化：统一响应格式，版本控制，OpenAPI 文档
|
||
8. 代码重组：服务层提取，仓库模式，依赖注入
|
||
9. 质量提升：测试覆盖率，CI/CD，代码质量工具
|
||
|
||
详细实施计划
|
||
|
||
阶段 1：安全加固与基础建设（第 1-2 周）
|
||
|
||
任务 1.1：消除硬编码敏感信息
|
||
|
||
- 优先级：高
|
||
- 文件：
|
||
- flask_prompt_master/routes.py:115 - 移除硬编码数据库密码
|
||
- config.py - 移除已弃用的硬编码配置
|
||
- 所有包含 sk-fdf7cc1c73504e628ec0119b7e11b8cc 的文件
|
||
- 方法：
|
||
a. 创建 .env.template 文件，列出所有需要的环境变量
|
||
b. 更新配置系统，从环境变量读取所有敏感信息
|
||
c. 添加配置验证，确保关键配置在启动时已设置
|
||
|
||
任务 1.2：实现统一认证中间件
|
||
|
||
- 优先级：高
|
||
- 方法：
|
||
a. 创建 auth/middleware.py 实现 JWT 认证中间件
|
||
b. 统一所有 API 的认证方式，逐步替换现有的多种认证系统
|
||
c. 添加角色和权限管理系统
|
||
d. 实现刷新令牌机制
|
||
|
||
任务 1.3：添加安全头部和请求验证
|
||
|
||
- 优先级：中
|
||
- 方法：
|
||
a. 实现安全中间件，添加 CSP、HSTS、XSS 防护等头部
|
||
b. 使用 Pydantic 创建请求数据验证模型
|
||
c. 实现全局请求验证中间件
|
||
|
||
阶段 2：API 标准化与文档（第 3-4 周）
|
||
|
||
任务 2.1：创建标准 API 响应格式
|
||
|
||
- 优先级：高
|
||
- 方法：
|
||
a. 创建 shared/api/responses.py 定义标准响应类
|
||
b. 实现成功响应：{success: true, data: {...}, meta: {...}}
|
||
c. 实现错误响应：{success: false, error: {...}, error_code: string}
|
||
d. 创建响应工具函数，统一所有路由的响应格式
|
||
|
||
任务 2.2：实现 API 版本控制
|
||
|
||
- 优先级：中
|
||
- 方法：
|
||
a. 创建 /api/v1/ 命名空间，所有新 API 使用此版本
|
||
b. 保留现有 /api/ 路由作为 v0 版本，逐步迁移
|
||
c. 实现版本路由中间件，支持通过 URL 或头部指定版本
|
||
d. 添加 API 弃用警告机制
|
||
|
||
任务 2.3：添加 OpenAPI 文档
|
||
|
||
- 优先级：中
|
||
- 方法：
|
||
a. 使用 Flask-Swagger 或 FastAPI-style 注解
|
||
b. 自动生成 API 文档，支持在线测试
|
||
c. 添加 API 使用示例和错误代码说明
|
||
|
||
阶段 3：代码重组与服务层提取（第 5-6 周）
|
||
|
||
任务 3.1：分解大型路由文件
|
||
|
||
- 优先级：高
|
||
- 文件：flask_prompt_master/routes.py（1300+ 行）
|
||
- 方法：
|
||
a. 按功能模块拆分：
|
||
- routes/prompt_routes.py - 提示词相关路由
|
||
- routes/auth_routes.py - 认证相关路由
|
||
- routes/history_routes.py - 历史记录路由
|
||
- routes/feature_routes.py - 各 AI 功能路由
|
||
b. 每个文件不超过 300 行，保持单一职责
|
||
c. 使用蓝图组织相关路由
|
||
|
||
任务 3.2：提取业务逻辑到服务层
|
||
|
||
- 优先级：高
|
||
- 方法：
|
||
a. 创建 services/ 目录，按领域划分服务类
|
||
b. 将路由中的业务逻辑移动到对应服务类
|
||
c. 服务类负责：业务规则验证、外部 API 调用、复杂数据处理
|
||
d. 路由只负责：请求解析、响应格式化、错误处理
|
||
|
||
任务 3.3：实现仓库模式
|
||
|
||
- 优先级：中
|
||
- 方法：
|
||
a. 创建 repositories/ 目录，按实体划分仓库类
|
||
b. 仓库类封装数据库操作，提供高层抽象接口
|
||
c. 路由和服务通过仓库访问数据，不直接使用 SQLAlchemy
|
||
d. 便于单元测试和数据库切换
|
||
|
||
阶段 4：测试与质量提升（第 7-8 周）
|
||
|
||
任务 4.1：提升测试覆盖率
|
||
|
||
- 优先级：中
|
||
- 方法：
|
||
a. 实现单元测试：服务层、仓库层、工具类
|
||
b. 实现集成测试：API 端点测试
|
||
c. 实现端到端测试：关键用户流程测试
|
||
d. 目标：测试覆盖率从 ~40% 提升到 80%+
|
||
|
||
任务 4.2：实现 CI/CD 流水线
|
||
|
||
- 优先级：中
|
||
- 方法：
|
||
a. 设置 GitHub Actions 或 GitLab CI
|
||
b. 自动化：代码检查、测试、构建、部署
|
||
c. 添加质量门禁：测试覆盖率、代码复杂度、安全扫描
|
||
|
||
任务 4.3：代码质量工具集成
|
||
|
||
- 优先级：低
|
||
- 方法：
|
||
a. 集成 black、isort、flake8 代码格式化
|
||
b. 添加 mypy 类型检查
|
||
c. 集成 pre-commit hooks 自动执行代码检查
|
||
|
||
阶段 5：部署优化与文档（第 9-10 周）
|
||
|
||
任务 5.1：优化 Docker 部署
|
||
|
||
- 优先级：低
|
||
- 方法：
|
||
a. 优化 Dockerfile，减少镜像大小
|
||
b. 实现多阶段构建
|
||
c. 添加健康检查端点
|
||
d. 优化生产环境配置
|
||
|
||
任务 5.2：实现监控和可观测性
|
||
|
||
- 优先级：中
|
||
- 方法：
|
||
a. 添加 Prometheus 指标收集
|
||
b. 实现结构化日志记录
|
||
c. 添加错误追踪和告警
|
||
d. 实现性能监控
|
||
|
||
任务 5.3：完善文档
|
||
|
||
- 优先级：低
|
||
- 方法：
|
||
a. 架构设计文档
|
||
b. API 使用文档
|
||
c. 部署和维护指南
|
||
d. 开发环境设置指南
|
||
|
||
风险缓解策略
|
||
|
||
技术风险
|
||
|
||
数据库迁移风险：
|
||
- 使用 Alembic 生成迁移脚本
|
||
- 在测试环境充分验证
|
||
- 准备回滚方案
|
||
API 兼容性风险：
|
||
- 使用功能开关控制新功能
|
||
- 保持向后兼容性至少一个版本周期
|
||
- 提供详细的迁移指南
|
||
性能回归风险：
|
||
- 重构前后进行性能基准测试
|
||
- 实施监控和告警
|
||
- 准备快速回滚机制
|
||
|
||
实施风险
|
||
|
||
团队知识差距：
|
||
- 结对编程和代码审查
|
||
- 详细的架构文档
|
||
- 定期知识分享会议
|
||
时间安排风险：
|
||
- 采用敏捷方法，每两周评估进度
|
||
- 优先处理高价值任务
|
||
- 保持灵活性，根据进展调整计划
|
||
|
||
关键文件路径
|
||
|
||
需要立即处理的安全问题
|
||
|
||
1. D:/aaa/aitsc/src/flask_prompt_master/routes/routes.py:115 - 硬编码数据库密码
|
||
2. D:/aaa/aitsc/config.py - 已弃用的硬编码配置
|
||
3. 所有包含硬编码 API 密钥的文件（搜索 sk-fdf7cc1c73504e628ec0119b7e11b8cc）
|
||
|
||
大型文件需要拆分
|
||
|
||
4. D:/aaa/aitsc/src/flask_prompt_master/routes/routes.py（1300+ 行）
|
||
5. D:/aaa/aitsc/src/flask_prompt_master/models/models.py（500+ 行）
|
||
|
||
新目录结构
|
||
|
||
6. src/flask_prompt_master/services/ - 服务层
|
||
7. src/flask_prompt_master/repositories/ - 仓库层
|
||
8. src/flask_prompt_master/shared/ - 共享组件
|
||
9. src/flask_prompt_master/api/ - API 相关组件
|
||
|
||
验证和测试策略
|
||
|
||
验证步骤
|
||
|
||
10. 安全验证：确保无硬编码敏感信息，所有配置通过环境变量管理
|
||
11. 功能验证：所有现有功能测试通过，API 响应格式一致
|
||
12. 性能验证：关键 API 端点响应时间无显著下降
|
||
13. 部署验证：生产环境部署成功，监控系统正常运行
|
||
|
||
测试计划
|
||
|
||
14. 单元测试：服务层、仓库层、工具类
|
||
15. 集成测试：API 端点、数据库操作
|
||
16. 端到端测试：关键用户流程（注册、登录、使用功能）
|
||
17. 性能测试：负载测试、压力测试
|
||
|
||
成功指标
|
||
|
||
量化指标
|
||
|
||
18. 零硬编码敏感信息
|
||
19. 测试覆盖率 80%+
|
||
20. 代码复杂度降低 30%
|
||
21. API 平均响应时间改善 20%
|
||
22. 缺陷修复时间减少 50%
|
||
|
||
质化指标
|
||
|
||
23. 新开发者上手时间减少 50%
|
||
24. 完整的架构和 API 文档
|
||
25. 开发者满意度提升
|
||
26. 部署信心增强
|
||
|
||
资源需求
|
||
|
||
团队配置
|
||
|
||
- 2-3 名高级开发工程师
|
||
- 兼职 QA 工程师
|
||
- 技术负责人（架构决策和代码审查）
|
||
|
||
时间安排
|
||
|
||
- 总时长：10 周（2.5 个月）
|
||
- 开发工作量：约 400-500 人时
|
||
- 每周进度评审和调整
|
||
|
||
工具和环境
|
||
|
||
- CI/CD 流水线
|
||
- 测试环境（开发、测试、预生产）
|
||
- 监控和告警系统
|
||
- 文档管理系统
|
||
|
||
---
|
||
注意：本重构计划采用渐进式方法，每个阶段都有明确的可交付成果和验证标准。建议从阶段 1
|
||
开始，确保安全基础稳固后再进行架构优化。 |