96 lines
3.7 KiB
Markdown
96 lines
3.7 KiB
Markdown
# 项目规则
|
||
|
||
## 项目背景
|
||
|
||
这是一个前后端分离的培训项目。
|
||
|
||
## 技术栈
|
||
|
||
- 前端：React 18、TypeScript、Vite
|
||
- 后端：Spring Boot 3.4.5、Java 21、MyBatis-Plus
|
||
- 数据库：MySQL 8
|
||
- 缓存：Redis
|
||
|
||
## 工作规则
|
||
|
||
- 所有文件使用 UTF-8 编码，避免中文乱码。
|
||
- 修改代码前，先阅读项目结构和相关文件。
|
||
- 修改前说明将影响哪些文件。
|
||
- 修改后给出启动命令和测试步骤。
|
||
- 不要把所有功能堆在一个页面或一个文件中。
|
||
- 建表或修改表结构时，补充完整的中文注释。
|
||
- 涉及删除文件、删除数据或清空数据库时，必须先二次确认，并提供操作日志和回滚说明。
|
||
|
||
## 环境
|
||
|
||
- 使用 `.env.example` 作为环境配置参考。
|
||
- 不要将密码、令牌或其他敏感信息写入代码、日志或提交内容。
|
||
|
||
## 前端规则
|
||
|
||
- 遵循现有组件、路由、状态管理和样式规范。
|
||
- 保持组件职责清晰，避免创建过大的组件。
|
||
- 修改用户界面时验证桌面端和移动端布局。
|
||
|
||
## 后端规则
|
||
|
||
- 类型名使用大驼峰，变量名和方法名使用小驼峰。
|
||
- 采用四层结构：`controller`、`service`、`mapper`、`domain`。
|
||
- `controller` 层声明接口，为前端提供 API。
|
||
- `service` 层声明业务接口，`impl` 子目录负责实现业务逻辑。
|
||
- `mapper` 层包含 Mapper 接口和 XML 文件，负责数据库操作。
|
||
- `domain` 层包含 POJO、DTO 等领域对象。
|
||
- 方法参数不要使用 `Map`；需要结构化参数时创建对应的 DTO 类。
|
||
- 使用 Lombok 的 `@RequiredArgsConstructor` 完成依赖注入。
|
||
|
||
## API 规范
|
||
|
||
- 接口路径使用版本前缀，例如 `/api/v1/`、`/api/v2/`；新增不兼容变更时升级主版本。
|
||
- 接口命名使用“动词 + 名词”表达操作和资源，例如 `POST /api/v1/users`。
|
||
- 接口成功响应统一使用以下结构：
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": {}
|
||
}
|
||
```
|
||
|
||
- 错误码集中定义并保持全局唯一；不要在业务代码中散落硬编码错误码和错误信息。
|
||
- 分页接口统一使用 `page`、`pageSize` 请求参数，并在响应中提供 `total` 总条数；分页数据放在 `data` 中。
|
||
- 需要认证的接口通过 `Authorization: Bearer <token>` 传递凭证。
|
||
- JSON 请求和响应使用 `Content-Type: application/json`，并根据实际内容设置 `Accept` 请求头。
|
||
- 新增接口时同步明确 HTTP 方法、路径、请求头、请求参数、响应结构、错误码和版本归属。
|
||
|
||
## 数据库规则
|
||
|
||
- 表名使用大写，多个单词之间使用下划线连接，例如 `USER_PROFILE`。
|
||
- 新建或修改表结构后，将最终建表语句保存到 `sql/<表名>.sql`。
|
||
- SQL 中为表和字段补充清晰的中文注释。
|
||
- 数据库写操作前先确认目标、范围、影响行数和回滚方式。
|
||
|
||
## 输出规范
|
||
|
||
- 使用标准代码格式。
|
||
- 完成时说明：修改了哪些文件、每个文件的变化、验证方法、是否涉及 SQL，以及风险和回滚方式。
|
||
|
||
## 通用约束
|
||
|
||
### 语言规范（不可变）
|
||
|
||
- 文档和代码注释必须使用中文。
|
||
- 变量名、函数名、类名和其他代码标识符仍使用英文，并遵循对应语言的命名规范。
|
||
|
||
### 可观测性与兜底
|
||
|
||
- 任务必须具备完整链路：任务 ID、关联引用和关键日志。
|
||
- 失败时必须提供明确的兜底提示，并支持合理的重试机制。
|
||
- 日志不得记录密码、令牌或其他敏感信息。
|
||
|
||
### 占位元素
|
||
|
||
- 图标或图片资源尚未确定时，使用占位 `div` 并添加 `TODO` 注释。
|
||
- 禁止使用临时 SVG、临时占位图服务或未授权的外部图片作为占位元素。
|
||
- 占位元素必须明确标记最终资源的替换位置。
|