expressgy/cursor-init
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
1195aa335e
cursor-init/tasks/archive/20250628-prd-架构优化.md
expressgy 2ee70e5d42 feat: 完成健康检查接口和Swagger文档完善 
✅ 健康检查功能：
- 实现完整的健康检查接口(/api/health, /api/health/detailed)
- 支持MySQL和Redis依赖状态检查
- 包含系统信息、性能指标监控
- 修复this上下文问题，确保服务方法正常调用
- 添加全面的健康检查测试用例

📝 Swagger文档优化：
- 创建全局响应Schema定义和错误码说明
- 完善API文档，包含详细的错误码表格
- 添加JWT认证说明和响应格式示例
- 增加全局组件、响应模板和示例
- 创建Swagger文档功能测试

🎯 任务完成：
- ✅ 5.0 健康检查接口 - 实现系统和依赖健康状态监控
- ✅ 7.0 Swagger文档完善 - 增加全局响应示例和错误码说明

📁 新增文件：
- src/controllers/health.controller.ts - 健康检查控制器
- src/services/health.service.ts - 健康检查服务层
- src/type/health.type.ts - 健康检查类型定义
- src/validators/health.response.ts - 健康检查响应验证
- src/validators/global.response.ts - 全局响应Schema定义
- src/tests/health.test.ts - 健康检查功能测试
- src/tests/redis.test.ts - Redis连接测试
- src/tests/swagger.test.ts - Swagger文档功能测试
2025-06-28 22:09:02 +08:00

4.0 KiB
Raw Blame History

架构优化 PRD

1. 引言/概述

本次架构优化旨在提升后端服务的可维护性、可观测性和健壮性。通过引入统一日志、全局错误处理和响应封装，规范接口行为，便于团队协作和后续扩展。新增 Redis 支持，为缓存、限流等功能打下基础。

2. 目标

  • 实现统一、可扩展的日志记录方案，支持分环境美化/存储/清理
  • 实现全局错误捕获与标准化响应，支持分环境详细度
  • 实现接口响应结构统一封装
  • 集成 Redis，支持缓存、限流等能力
  • 提升系统可观测性和异常可追溯性

3. 用户故事

  • 作为开发者，我希望所有接口出错时能收到统一格式的错误响应，便于前端处理和排查。
  • 作为运维，我希望能通过日志快速定位线上问题。
  • 作为开发者，我希望所有接口响应结构一致，便于前后端协作。
  • 作为开发者，我希望在开发环境下看到彩色美观的日志和详细错误堆栈。
  • 作为运维，我希望生产环境日志能自动分文件存储并定期清理。
  • 作为开发者，我希望能方便地使用 Redis 进行缓存、限流等操作。

4. 功能需求

  1. 日志记录器

    • 支持 info、warn、error、debug 等日志等级
    • 日志内容包含时间、等级、消息、上下文信息
    • 日志默认输出到控制台，后续可扩展到文件/远程
    • 关键操作、异常、接口请求需有日志
    • 每条请求日志包含唯一请求 id、method、url、状态码、耗时、IP、时间戳
    • dev 环境日志美化输出（带颜色）、控制台打印
    • prod 环境日志按天/小时分文件存储，支持定时清理历史日志
    • 日志格式美观，dev 环境带颜色区分 info/warn/error

  2. 全局错误处理器

    • 捕获所有未处理异常，返回统一 JSON 结构
    • 支持自定义业务异常类型
    • 错误日志自动记录
    • 错误响应结构需包含 code、message、data 字段
    • dev 环境异常响应包含详细堆栈，prod 环境仅输出友好错误信息

  3. 响应封装

    • 所有接口返回统一结构：{ code, message, data }
    • 支持自定义响应码和 message
    • 可扩展 traceId、耗时等字段

  4. 请求日志中间件

    • 记录 method、url、耗时、状态码、IP、请求 id
    • 日志链路追踪

  5. 健康检查接口

    • 提供 /health 路由，返回服务健康状态

  6. 配置中心优化

    • 所有配置集中到 config，支持多环境

  7. Redis 支持

    • 集成 Redis，配置集中管理
    • Redis 连接池、健康检查
    • 预留缓存、限流、会话等场景的基础能力

  8. 接口文档自动化完善

    • Swagger UI 增加全局响应示例、错误码说明

5. 非目标（范围之外）

  • 日志持久化到远程（本期仅本地文件）
  • 速率限制、权限控制等安全功能

6. 设计考虑

  • 日志、错误、响应封装均以中间件/插件方式实现，便于复用和扩展
  • 代码与注释规范保持一致
  • 目录结构建议：
    • src/middlewares/logger.ts
    • src/middlewares/error-handler.ts
    • src/utils/response.ts
    • src/config/redis.config.ts
  • 日志库建议用 pino/winston/simple 自研
  • 日志文件存储建议按天分目录，定时清理可用定时任务
  • 请求 id 可用 nanoid/uuid 生成，并通过中间件注入上下文
  • Redis 推荐用 bun:redis 原生或社区库

7. 技术考虑

  • 日志库选型、日志文件清理策略
  • 错误类型建议自定义 Error 类
  • 响应封装为工具函数或 Elysia 插件
  • Redis 连接池与健康检查实现

8. 成功指标

  • 100% 接口响应结构统一
  • 关键操作/异常均有日志
  • 错误响应无堆栈泄漏，信息友好
  • 日志分环境输出，生产环境日志可定期清理
  • Redis 连接稳定，健康检查通过

9. 待解决问题

  • 日志等级与格式细节
  • 错误码与 message 规范
  • 响应结构是否需 traceId、耗时等扩展字段
  • Redis 具体使用场景细化