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文档功能测试
108 lines
4.8 KiB
Markdown
108 lines
4.8 KiB
Markdown
# 项目初始化 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. 功能需求
|
||
|
||
1. 项目初始化：
|
||
- 必须基于 Bun.js 和 Elysia 框架初始化项目。
|
||
- 必须采用 TypeScript。
|
||
2. 目录结构与规范：
|
||
- 必须采用 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）。
|
||
3. 数据库集成：
|
||
- 必须集成 MySQL 数据库，支持基础连接与操作。
|
||
- 数据库配置需通过环境变量管理。
|
||
4. 认证与鉴权：
|
||
- 必须集成 JWT 认证中间件，支持生成和校验 Token。
|
||
- 提供基础的登录接口示例。
|
||
5. API 文档：
|
||
- 必须集成 @elysiajs/swagger 插件，自动生成并暴露 Swagger UI。
|
||
- 所有接口需完整描述参数、返回值、错误码等。
|
||
6. 代码规范与工具：
|
||
- 必须集成 ESLint（含 TypeScript 规则）和 Prettier。
|
||
- 必须配置 Vitest 测试框架，支持单元和接口测试。
|
||
- 必须提供基础的 CI/CD 配置（如 GitHub Actions 示例）。
|
||
7. 示例接口：
|
||
- 提供一个基础的健康检查接口（/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>
|