---
description: 
globs: 
alwaysApply: true
---
# Elysia（Bun.js）后端开发规范

## 1. 项目结构

- 推荐目录结构如下，分层清晰，便于维护和扩展：
  ```
  ├── src/
  │   ├── controllers/   # 路由与业务入口
  │   ├── services/      # 业务逻辑
  │   ├── models/        # 数据模型与类型定义
  │   ├── 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 后端服务的健壮性、安全性与可维护性。**