145 lines
5.8 KiB
Plaintext
145 lines
5.8 KiB
Plaintext
---
|
||
description:
|
||
globs:
|
||
alwaysApply: true
|
||
---
|
||
# Elysia（Bun.js）后端开发规范
|
||
|
||
## 1. 项目结构
|
||
|
||
- 推荐目录结构如下，分层清晰，便于维护和扩展：
|
||
```
|
||
├── src/
|
||
│ ├── controllers/ # 路由与业务入口
|
||
│ ├── services/ # 业务逻辑
|
||
│ ├── models/ # 数据模型与类型定义
|
||
│ ├── middlewares/ # 中间件
|
||
│ ├── plugins/ # Elysia 插件
|
||
│ ├── utils/ # 工具函数
|
||
│ ├── validators/ # 参数校验，注意！！！所有的参数校验必须挡在此目录中，目录结构遵照路由结构
|
||
│ ├── config/ # 配置文件
|
||
│ ├── type/ # 类型定义文件
|
||
│ └── app.ts # 应用入口
|
||
├── tests/ # 测试用例
|
||
├── public/ # 静态资源
|
||
├── .env # 环境变量
|
||
├── bun.lockb # Bun 依赖锁
|
||
├── package.json
|
||
└── README.md
|
||
└── .git/ # Git版本控制目录，跟踪项目历史和协作
|
||
```
|
||
|
||
## 2. 代码风格
|
||
|
||
- 强制使用 ESLint + Prettier 统一代码风格，TypeScript 项目建议使用 `@typescript-eslint`。
|
||
- 文件、变量、函数、类命名采用小驼峰（camelCase），类名用大驼峰（PascalCase）。
|
||
- 严格类型检查，禁止使用 `any`，优先使用类型推断和类型声明。
|
||
- 每个文件、类、方法、复杂逻辑必须有规范注释（参考注释规范 rules）。
|
||
- 代码提交前必须通过 lint 检查和格式化。
|
||
|
||
## 3. 路由与接口设计
|
||
|
||
- 路由统一注册在 `controllers` 目录下，按业务模块拆分。
|
||
- 遵循 RESTful API 设计原则，接口资源命名清晰、语义化。
|
||
- 路由统一使用小写、短横线分隔（如 `/api/v1/user-info`）。
|
||
- GET 用于获取资源，POST 用于创建，PUT/PATCH 用于更新，DELETE 用于删除。
|
||
- 所有接口返回统一的数据结构，例如：
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"message": "success",
|
||
"data": {}
|
||
}
|
||
```
|
||
- 错误码、错误信息需文档化，便于前后端协作。
|
||
|
||
## 4. 参数校验
|
||
|
||
- 所有接口参数必须进行校验。
|
||
- 校验逻辑统一放在 `validators` 目录，便于复用和维护。
|
||
- 校验失败时返回标准错误响应，禁止直接抛出异常。
|
||
|
||
## 5. 中间件与插件
|
||
|
||
- 公共逻辑（如鉴权、日志、限流、CORS、错误处理等）必须通过中间件实现，统一注册在 `middlewares` 或 `plugins` 目录。
|
||
- 推荐使用 Elysia 官方和社区插件（如 `@elysiajs/cors`、`@elysiajs/jwt`、`@elysiajs/swagger` 等）。
|
||
- 自定义插件需有详细注释和文档。
|
||
|
||
## 6. 安全规范
|
||
|
||
- 禁止 SQL 注入、XSS、CSRF 等常见安全漏洞，使用 ORM/参数化查询。
|
||
- 重要接口需鉴权（如 JWT、Session），敏感操作需权限校验。
|
||
- 密码等敏感信息必须加密存储，严禁明文。
|
||
- 配置信息（如密钥、数据库连接）使用环境变量管理，严禁写死在代码中。
|
||
- 日志中不得记录敏感信息。
|
||
|
||
## 7. 错误处理
|
||
|
||
- 所有异常必须统一捕获和处理，返回标准错误响应。
|
||
- 推荐全局错误处理中间件，记录错误日志，便于排查问题。
|
||
- 错误响应结构示例：
|
||
```json
|
||
{
|
||
"code": 1001,
|
||
"message": "参数校验失败",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
## 8. 日志与监控
|
||
|
||
- 统一使用日志库（如 pino、winston），区分 info、warn、error 等级。
|
||
- 关键操作、异常、接口请求需有日志记录，便于排查问题。
|
||
- 推荐接入监控系统（如 Prometheus、ELK）。
|
||
|
||
## 9. 测试
|
||
|
||
- 必须编写单元测试和集成测试，覆盖核心业务逻辑。
|
||
- 推荐使用 Vitest（Bun 原生支持）、Jest 等测试框架。
|
||
- 新增功能需同步补充测试用例，CI 阶段自动跑测试。
|
||
- 测试代码与业务代码分离，统一放在 `tests` 目录。
|
||
|
||
## 10. 依赖与版本管理
|
||
|
||
- 依赖包需定期升级，避免使用过时或有安全漏洞的库。
|
||
- 使用 `bun.lockb` 锁定依赖版本。
|
||
- 不得将未使用的依赖、临时文件提交到仓库。
|
||
|
||
## 11. 持续集成与部署
|
||
|
||
- 推荐使用 CI 工具（如 GitHub Actions、GitLab CI）自动化测试、构建、部署。
|
||
- 生产环境部署需有回滚机制，避免单点故障。
|
||
- 环境变量、密钥等敏感信息通过 CI/CD 平台安全注入。
|
||
|
||
## 12. 文档与协作
|
||
|
||
- 所有接口、核心模块需有详细文档，推荐使用 OpenAPI/Swagger 自动生成接口文档（可用 `@elysiajs/swagger`）。
|
||
- 重要变更需在 README/CHANGELOG 中记录。
|
||
- 团队成员需遵守代码评审流程，确保代码质量。
|
||
- 项目根目录应有完整的 README，包含启动、开发、测试、部署等说明。
|
||
|
||
## 13. 其他最佳实践
|
||
|
||
- 代码与注释同步更新，避免注释失效。
|
||
- 复杂算法、业务逻辑、边界处理、特殊依赖等务必详细注释。
|
||
- 严禁在注释、日志、代码中出现密码、密钥、用户隐私等敏感信息。
|
||
- 推荐在项目根目录下提供注释模板和接口模板，便于新成员快速上手。
|
||
- 重要模块、核心业务建议将注释内容同步到项目文档，便于知识传承和查阅。
|
||
|
||
## 14. 模块引入
|
||
|
||
- 全部使用路径别名，如`@/app` `@/config/db.config`
|
||
- 注意更新 tsconfig.json bunfig.toml 等配置中关于路径别名的配置
|
||
|
||
## 15. 配置文件
|
||
|
||
- 配置请全部存放在config中,不要再其他文件使用process.env
|
||
- 除了密码，所有配置都需要有默认值
|
||
|
||
## 16. 类型文件
|
||
|
||
- 所有的类型定义全部放在公共位置，type文件夹下，**不允许在其他文件中定义**
|
||
|
||
---
|
||
|
||
**请所有开发者严格遵守以上规范，保障 Elysia 后端服务的健壮性、安全性与可维护性。** |