ec21df7aa6
- 添加完整的项目结构，包括前端（Vue3 + Vite）、后端（Fastify）和基础设施配置 - 实现核心 GraphRAG 服务，集成 Neo4j 图数据库和 Qdrant 向量数据库 - 添加用户认证系统和管理员登录界面 - 提供 Docker 容器化部署方案和开发环境配置 - 包含项目文档、API 文档（Swagger）和测试脚本
117 lines
4.5 KiB
Markdown
117 lines
4.5 KiB
Markdown
|
||
## 开发规范
|
||
|
||
### 项目结构规范
|
||
|
||
project /
|
||
├── src / 程序源码文件目录
|
||
│ ├── config / 配置目录
|
||
│ │ ├── swagger.js swagger 配置文件
|
||
│ │ └── logger.js 日志配置文件
|
||
│ │
|
||
│ ├── controllers / 控制器目录
|
||
│ │ ├── *.controller.js 控制器文件
|
||
│ │ └── index.js 控制器索引文件
|
||
│ │
|
||
│ ├── models / 模型目录
|
||
│ │ ├── *.model.js 模型文件
|
||
│ │ └── index.js 模型索引文件
|
||
│ │
|
||
│ ├── routes / 路由目录
|
||
│ │ ├── *.route.js 路由文件
|
||
│ │ └── index.js 路由索引文件
|
||
│ │
|
||
│ ├── services / 服务目录
|
||
│ │ ├── *.service.js 服务文件
|
||
│ │ └── index.js 服务索引文件
|
||
│ └── server.js 服务器入口文件
|
||
│
|
||
├── docs / 用于存储AI提示文档
|
||
│ └── *.md 文档文件
|
||
│
|
||
├── .env 环境变量配置文件
|
||
├── package.json 项目依赖配置文件
|
||
├── .gitignore git 忽略文件配置
|
||
├── package-lock.json 项目依赖锁文件
|
||
└── README.md 项目说明文档
|
||
|
||
|
||
|
||
|
||
### controllers、models、routes 规范
|
||
|
||
- 每个目录下的文件都要符合命名规范
|
||
- 控制器文件：`*.controller.js`
|
||
- 模型文件：`*.model.js`
|
||
- 路由文件：`*.route.js`
|
||
|
||
并统一由index.js导出：
|
||
|
||
- controllers/index.js
|
||
- models/index.js
|
||
- routes/index.js
|
||
|
||
### swagger 规范
|
||
|
||
- 每个路由文件都要包含路由的详细信息，包括请求方法、路径、参数、响应等。
|
||
- 路由文件的注释要符合 swagger 规范，使用 jsdoc 格式。
|
||
- 每个模型文件都要包含模型的详细信息，包括属性、类型、是否必填等。
|
||
- 模型文件的注释要符合 swagger 规范，使用 jsdoc 格式。
|
||
|
||
### 运行与脚本
|
||
|
||
- 开发启动：`npm run dev`
|
||
- 普通启动：`npm run start`
|
||
- 文档入口：`/api-docs`
|
||
|
||
### 环境变量规范
|
||
|
||
- 使用 `dotenv` 加载 `.env`（入口：`src/server.js`）
|
||
- 变量约定：
|
||
- `PORT`：服务监听端口，默认 `3000`
|
||
- `APPLICATION_URL`：对外服务基址，用于 Swagger `servers`（未设置回退为 `http://localhost:${PORT}`）
|
||
- `LOG_LEVEL`：日志级别，默认 `info`（可选 `error|warn|info|debug`）
|
||
- 安全要求：不记录/提交敏感信息，`.gitignore` 已忽略 `.env` 与 `logs/`
|
||
|
||
### 日志规范
|
||
|
||
- 日志库：`winston`（配置：`src/config/logger.js`）
|
||
- 级别：`error`、`warn`、`info`、`debug`
|
||
- 输出：
|
||
- 控制台（彩色，便于开发）
|
||
- 文件：`logs/app.log`（综合）、`logs/error.log`（错误）
|
||
- 请求日志：在 `src/server.js` 统一中间件记录 `method path status 耗时`，错误 `>=500` 记 `error`，`>=400` 记 `warn`
|
||
- 全局错误处理：`src/server.js` 捕获未处理异常并输出结构化错误，响应 `500`
|
||
- 规范：避免日志中出现令牌、密钥、密码等敏感信息
|
||
|
||
### swagger-jsdoc 配置与注释规范
|
||
|
||
- 配置位置：`src/config/swagger.js`（`createSwaggerSpec(serverUrl)`）
|
||
- 扫描范围：`apis: ['src/**/*.js']`
|
||
- 路由注释：放在 `src/routes/*.route.js`，使用 `@openapi` JSDoc 块定义路径、方法、请求参数与响应
|
||
- 模型注释：可使用 `components/schemas` 定义结构体并在路由注释中引用
|
||
- 文档 UI：`swagger-ui-express` 挂载于 `/api-docs`
|
||
|
||
### 分层规范
|
||
|
||
- 路由（`routes`）只负责参数解析与转发，不直接书写异步业务逻辑
|
||
- 控制器（`controllers`）承载业务流程编排，必要时调用 `services`
|
||
- 服务（`services`）聚合外部 API、内部模块调用，保持可测试性
|
||
- 模型（`models`）声明数据结构（如后续有数据库或 DTO 定义）
|
||
- 统一导出：各层使用 `index.js` 聚合导出，便于维护与扫描
|
||
|
||
### 参考实现
|
||
|
||
- 路由聚合：`src/routes/index.js`
|
||
- 根路由与注释：`src/routes/root.route.js`
|
||
- 控制器：`src/controllers/root.controller.js`
|
||
- Swagger 配置：`src/config/swagger.js`
|
||
- 日志配置：`src/config/logger.js`
|
||
- 入口挂载：`src/server.js`
|
||
|
||
### 异步编程规范
|
||
- 所有异步操作都要使用 `async/await` 或 `Promise` 处理，避免回调地狱
|
||
- 控制器中调用服务时，要确保服务返回 `Promise`，并在控制器中 `await` 其结果
|
||
- 服务中调用外部 API 或数据库操作时，要确保返回 `Promise`，并在服务中 `await` 其结果
|
||
- 路由中处理异步操作时，要确保捕获异常并返回结构化错误响应
|
||
- 必须使用try...catch捕获异步操作中的异常，避免未处理异常导致服务崩溃 |