expressgy/cursor-init
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
621963f82c
cursor-init/tasks/prd-架构优化.md
expressgy 5b0b37ef78 chore: 项目初始化相关配置与文档归档优化 
- Prettier 配置迁移为 .prettierrc.cjs，解决 ESM/CJS 兼容问题
- 优化 package.json，补全元信息、整理依赖、完善 Bun 热更新脚本
- 归档项目初始化 PRD 与任务清单到 tasks/archive，并加日期前缀
- 同步代码风格与格式化配置，提升团队协作一致性

归档文件：tasks/archive/20240610-prd-项目初始化.md, tasks/archive/20240610-tasks-prd-项目初始化.md
2025-06-28 02:03:40 +08:00

4.1 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 具体使用场景细化