expressgy
2ee70e5d42
✅ 健康检查功能： - 实现完整的健康检查接口(/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文档功能测试
106 lines
4.0 KiB
Markdown
106 lines
4.0 KiB
Markdown
# 架构优化 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 具体使用场景细化
|