expressgy
2518986557
✨ 新增功能设计文档： - M2基础用户系统数据库设计（12个核心表，RBAC权限模型） - M2基础用户系统接口设计（41个API接口，含排序功能） - 完整的项目需求文档和开发计划 📚 核心文档结构： - 数据库设计：支持树形结构、软删除、审计日志的完整用户权限体系 - 接口设计：包含认证、用户管理、角色权限、组织架构、字典标签等9大模块 - 排序功能：新增7个排序接口，支持拖拽和批量操作 - 项目规划：从MVP到完整生态的4阶段开发计划 🔧 技术栈确定： - 后端：Elysia + Bun.js + MySQL + Redis + Elasticsearch - 前端：Vue.js/React + TypeScript - 部署：Docker + Docker Compose - 测试：Vitest + 完整测试规范 📋 设计亮点： - 无外键约束设计，应用层维护数据完整性 - 树形结构支持（path、level字段优化查询） - 完整的权限继承机制和权限快照 - 支持root超级管理员和多级角色体系 - 标签系统和智能推荐功能 - 统一的响应格式和错误码规范 🎯 覆盖功能： - 用户认证与管理（注册、登录、权限控制） - RBAC角色权限体系（树形角色、权限继承） - 组织架构管理（多级组织、人员分配） - 数据字典与标签系统 - 完整的排序和数据导入导出功能 📈 文档规模： - 数据库设计：38KB，922行 - 接口设计：55KB，3024行 - 总计：约100KB的详细技术文档 🔄 配套更新： - 更新Elysia后端开发规范 - 完善健康检查控制器 - 统一项目代码规范和注释规范
144 lines
5.8 KiB
Plaintext
144 lines
5.8 KiB
Plaintext
---
|
||
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 后端服务的健壮性、安全性与可维护性。** |