expressgy
5b0b37ef78
- Prettier 配置迁移为 .prettierrc.cjs，解决 ESM/CJS 兼容问题 - 优化 package.json，补全元信息、整理依赖、完善 Bun 热更新脚本 - 归档项目初始化 PRD 与任务清单到 tasks/archive，并加日期前缀 - 同步代码风格与格式化配置，提升团队协作一致性 归档文件：tasks/archive/20240610-prd-项目初始化.md, tasks/archive/20240610-tasks-prd-项目初始化.md
105 lines
4.1 KiB
Markdown
105 lines
4.1 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 具体使用场景细化 |