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文档功能测试
4.8 KiB
4.8 KiB
项目初始化 PRD（Bun.js + Elysia API 服务）
1. 引言/概述
本项目旨在基于 Bun.js 下的 Elysia 框架，搭建一个高效、可维护的 API 服务后端。项目将集成 MySQL 数据库、JWT 用户认证、自动生成 Swagger API 文档，采用 TypeScript 进行开发，配备 Vitest 测试框架，并严格遵循 ESLint + Prettier 代码规范和团队注释规范。项目结构分层清晰，便于后续扩展和团队协作。
2. 目标
- 快速搭建可运行的 Elysia API 服务基础工程。
- 支持 MySQL 数据库连接与基础操作。
- 集成 JWT 认证中间件，支持用户登录鉴权。
- 自动生成并暴露 Swagger API 文档。
- 采用 TypeScript，保证类型安全。
- 集成 Vitest 测试框架，支持单元与接口测试。
- 配置 ESLint + Prettier，统一代码风格。
- 遵循团队目录结构与注释规范。
3. 用户故事
- 作为开发者，我希望有一个结构清晰、规范统一的 API 服务项目模板，便于快速开发和维护。
- 作为开发者，我希望能方便地连接和操作 MySQL 数据库。
- 作为开发者，我希望项目自带 JWT 认证能力，便于后续扩展用户系统。
- 作为开发者，我希望能通过 Swagger UI 查看和调试所有 API。
- 作为开发者，我希望有完善的测试和代码规范工具，保证代码质量。
4. 功能需求
- 项目初始化：
- 必须基于 Bun.js 和 Elysia 框架初始化项目。
- 必须采用 TypeScript。
- 目录结构与规范：
- 必须采用 rules 文件中最新推荐的分层目录结构：
├── src/ │ ├── controllers/ # 路由与业务入口 │ ├── services/ # 业务逻辑 │ ├── models/ # 数据模型与类型定义 │ ├── middlewares/ # 中间件 │ ├── plugins/ # Elysia 插件 │ ├── utils/ # 工具函数 │ ├── validators/ # 参数校验 │ ├── config/ # 配置文件 │ ├── type/ # 类型定义文件 │ └── app.ts # 应用入口 ├── tests/ # 测试用例 ├── public/ # 静态资源 ├── .env # 环境变量 ├── bun.lockb # Bun 依赖锁 ├── package.json └── README.md - 每个文件、类、方法、复杂逻辑必须有规范注释（参考注释规范 rules）。
- 必须采用 rules 文件中最新推荐的分层目录结构：
- 数据库集成：
- 必须集成 MySQL 数据库，支持基础连接与操作。
- 数据库配置需通过环境变量管理。
- 认证与鉴权：
- 必须集成 JWT 认证中间件，支持生成和校验 Token。
- 提供基础的登录接口示例。
- API 文档：
- 必须集成 @elysiajs/swagger 插件，自动生成并暴露 Swagger UI。
- 所有接口需完整描述参数、返回值、错误码等。
- 代码规范与工具：
- 必须集成 ESLint（含 TypeScript 规则）和 Prettier。
- 必须配置 Vitest 测试框架，支持单元和接口测试。
- 必须提供基础的 CI/CD 配置（如 GitHub Actions 示例）。
- 示例接口：
- 提供一个基础的健康检查接口（/api/health）。
- 提供一个带 JWT 认证的示例接口。
5. 非目标（范围之外）
- 不实现具体的业务功能（如用户注册、复杂业务逻辑等）。
- 不集成除 MySQL 外的其他数据库。
- 不实现前端页面，仅提供 API 服务。
- 不实现国际化、定时任务、第三方服务集成等高级功能。
6. 设计考虑
- 目录结构、注释风格、接口风格等均严格参考 rules 文件规范。
- 所有配置（如数据库、JWT 密钥等）均通过 .env 文件和 config 目录集中管理。
- API 路由统一前缀为 /api。
7. 技术考虑
- 使用 Bun.js 作为运行时，Elysia 作为主框架。
- MySQL 连接推荐使用官方或社区兼容库（如 bun-mysql、mysql2 等）。
- JWT 推荐使用 @elysiajs/jwt 插件。
- Swagger 推荐使用 @elysiajs/swagger 插件。
- 测试推荐使用 Vitest，接口测试可用 supertest/undici。
- 代码规范工具需支持 TypeScript。
8. 成功指标
- 项目可一键启动并通过健康检查接口返回正常。
- 能成功连接 MySQL 并进行基础操作。
- JWT 认证流程可用，接口能正确校验 Token。
- Swagger UI 能自动展示所有接口文档。
- 通过 Vitest 测试，覆盖率不低于 80%。
- 代码通过 ESLint 检查并格式化。
9. 待解决问题
- MySQL 连接库的最终选择（bun-mysql、mysql2 等）。
- JWT 密钥和安全配置的管理细节。
- CI/CD 工具链的具体实现细节（如是否接入特定平台）。
</rewritten_file>