wurenzhi
136c2fa579
- 新增文档模板和导航结构 - 实现服务器基础API路由和控制器 - 添加扩展插件配置和前端框架 - 引入多租户和权限管理模块 - 集成日志和数据库配置 - 添加核心业务模型和类型定义
395 lines
9.2 KiB
Markdown
395 lines
9.2 KiB
Markdown
# AI 友好项目结构设计指南
|
||
|
||
> 本指南适用于所有项目，帮助 AI 快速理解模块职责、依赖关系和业务流程
|
||
|
||
---
|
||
|
||
## 1. 项目总体设计原则
|
||
|
||
### 1.1 模块化
|
||
- 每个模块（Module）单一职责，明确功能边界
|
||
- 避免跨模块调用深层内部函数，只通过接口或导出函数进行通信
|
||
|
||
### 1.2 层级清晰
|
||
- **分层原则（Layered Architecture）**：
|
||
- `core` 核心逻辑
|
||
- `service` 服务/业务逻辑
|
||
- `controller` 控制层/路由层
|
||
- `ui` 界面或前端组件
|
||
- AI 能通过路径快速推断模块职责
|
||
|
||
### 1.3 依赖方向一致
|
||
- 只允许高层模块依赖低层模块，禁止低层模块依赖高层模块
|
||
- 可用 `PROJECT_MAP.md` 来可视化依赖关系，帮助 AI 理解边界
|
||
|
||
### 1.4 明确接口（Interface）
|
||
- 每个模块导出统一接口，并在模块目录下放置 `module_info.md` 描述：
|
||
- 功能
|
||
- 输入/输出
|
||
- 调用约束
|
||
|
||
---
|
||
|
||
## 2. 推荐项目结构
|
||
|
||
```
|
||
project-root/
|
||
├─ core/ # 核心模块，最低依赖层
|
||
│ ├─ utils/ # 公共工具函数
|
||
│ │ ├─ string_utils.js
|
||
│ │ └─ array_utils.js
|
||
│ └─ constants.js
|
||
├─ service/ # 业务逻辑层
|
||
│ ├─ userService/
|
||
│ │ ├─ index.js
|
||
│ │ └─ module_info.md
|
||
│ └─ orderService/
|
||
│ ├─ index.js
|
||
│ └─ module_info.md
|
||
├─ controller/ # 控制层
|
||
│ ├─ userController.js
|
||
│ └─ orderController.js
|
||
├─ ui/ # 前端组件层
|
||
│ ├─ components/
|
||
│ └─ pages/
|
||
├─ docs/ # 项目文档
|
||
│ ├─ core/
|
||
│ ├─ service/
|
||
│ ├─ controller/
|
||
│ ├─ ui/
|
||
│ ├─ architecture/
|
||
│ ├─ README.md
|
||
│ └─ _nav.yaml
|
||
└─ package.json
|
||
```
|
||
|
||
---
|
||
|
||
## 3. AI 友好文件规范
|
||
|
||
### 3.1 模块信息文件（module_info.md）
|
||
|
||
**每个模块必须包含**：
|
||
|
||
```markdown
|
||
# UserService 模块
|
||
## 功能
|
||
- 用户信息管理
|
||
- 登录/注册逻辑
|
||
- 用户权限验证
|
||
## 接口
|
||
- `createUser(data: UserData): Promise<User>`
|
||
- `getUserById(id: string): Promise<User>`
|
||
- `validateUserCredentials(username: string, password: string): Promise<boolean>`
|
||
## 依赖
|
||
- core/utils
|
||
- core/constants
|
||
## 被调用方
|
||
- controller/userController
|
||
## 示例
|
||
```javascript
|
||
import { createUser } from './userService';
|
||
const newUser = await createUser({ username: 'Alice', password: '1234' });
|
||
console.log(newUser);
|
||
```
|
||
```
|
||
```
|
||
|
||
### 3.2 输入输出映射文件（*_io.yaml）
|
||
|
||
**每个服务模块建议包含**：
|
||
|
||
```yaml
|
||
module: userService
|
||
inputs:
|
||
- source: controller/userController.createUser
|
||
type: UserData
|
||
- source: controller/userController.getUser
|
||
type: { id: string }
|
||
outputs:
|
||
- destination: controller/userController.sendUserCreatedResponse
|
||
type: User
|
||
- destination: controller/userController.sendUserResponse
|
||
type: User
|
||
```
|
||
|
||
### 3.3 项目文档文件
|
||
|
||
| 文件 | 用途 |
|
||
|------|------|
|
||
| `PROJECT_MAP.md` | 模块依赖关系可视化 |
|
||
| `PROJECT_RULES.md` | 编码和依赖规范 |
|
||
| `ARCHITECTURE.md` | 架构说明 |
|
||
| `FEATURE_MAP.md` | 功能模块映射 |
|
||
| `CALL_MAP.md` | 业务调用链 |
|
||
| `_nav.yaml` | 结构化文档路由 |
|
||
|
||
---
|
||
|
||
## 4. 文档路由优化
|
||
|
||
### 4.1 分层路由结构
|
||
|
||
```
|
||
docs/
|
||
├─ core/
|
||
│ └─ utils.md
|
||
├─ service/
|
||
│ ├─ userService.md
|
||
│ └─ orderService.md
|
||
├─ controller/
|
||
│ ├─ userController.md
|
||
│ └─ orderController.md
|
||
├─ architecture/
|
||
│ ├─ PROJECT_MAP.md
|
||
│ ├─ PROJECT_RULES.md
|
||
│ ├─ FEATURE_MAP.md
|
||
│ └─ CALL_MAP.md
|
||
├─ README.md # 索引页
|
||
└─ _nav.yaml # 结构化路由文件
|
||
```
|
||
|
||
### 4.2 统一文档结构
|
||
|
||
每个模块文档保持相同的结构：
|
||
1. 功能
|
||
2. 接口
|
||
3. 输入输出
|
||
4. 依赖
|
||
5. 被调用方
|
||
6. 示例
|
||
|
||
### 4.3 跨文档引用
|
||
|
||
使用相对链接引用依赖模块：
|
||
|
||
```markdown
|
||
## 依赖
|
||
- [core/utils](../core/utils.md)
|
||
- [userService](../service/userService.md)
|
||
```
|
||
|
||
---
|
||
|
||
## 5. 可视化工具
|
||
|
||
### 5.1 依赖图生成
|
||
|
||
**生成脚本（generate_mermaid.js）**：
|
||
|
||
```javascript
|
||
const fs = require('fs');
|
||
const path = require('path');
|
||
const yaml = require('js-yaml');
|
||
|
||
const NAV_FILE = path.join(__dirname, 'docs/_nav.yaml');
|
||
const OUTPUT_FILE = path.join(__dirname, 'docs/DEPENDENCY_GRAPH.md');
|
||
|
||
// 读取 _nav.yaml
|
||
const navContent = fs.readFileSync(NAV_FILE, 'utf-8');
|
||
const navData = yaml.load(navContent);
|
||
|
||
// 用于存储 Mermaid 节点和依赖
|
||
let nodes = [];
|
||
let edges = [];
|
||
|
||
// 遍历模块生成节点
|
||
navData.forEach(moduleGroup => {
|
||
moduleGroup.docs.forEach(doc => {
|
||
const moduleName = `${moduleGroup.module}/${doc.name}`;
|
||
nodes.push(moduleName);
|
||
|
||
// 尝试读取 module_info.md 获取依赖
|
||
const modulePath = path.join(__dirname, 'docs', moduleGroup.module, `${doc.name}.md`);
|
||
if (fs.existsSync(modulePath)) {
|
||
const mdContent = fs.readFileSync(modulePath, 'utf-8');
|
||
const depMatches = [...mdContent.matchAll(/## 依赖\s*([\s\S]*?)(?:##|$)/g)];
|
||
if (depMatches.length) {
|
||
const depText = depMatches[0][1];
|
||
const depLines = depText.split('\n').map(l => l.trim()).filter(Boolean);
|
||
depLines.forEach(depLine => {
|
||
// 解析 Markdown 链接 [模块](路径)
|
||
const match = depLine.match(/\[([^\]]+)\]/);
|
||
if (match) {
|
||
const depModule = match[1].replace(/\//g, '/');
|
||
edges.push({ from: moduleName, to: depModule });
|
||
}
|
||
});
|
||
}
|
||
}
|
||
});
|
||
});
|
||
|
||
// 生成 Mermaid 文件
|
||
let mermaidContent = '```mermaid\nflowchart TD\n';
|
||
|
||
// 添加节点
|
||
nodes.forEach(node => {
|
||
const safeNode = node.replace(/\//g, '_');
|
||
mermaidContent += ` ${safeNode}[${node}]\n`;
|
||
});
|
||
|
||
// 添加边
|
||
edges.forEach(edge => {
|
||
const fromNode = edge.from.replace(/\//g, '_');
|
||
const toNode = edge.to.replace(/\//g, '_');
|
||
mermaidContent += ` ${fromNode} --> ${toNode}\n`;
|
||
});
|
||
|
||
mermaidContent += '```';
|
||
|
||
// 写入文件
|
||
fs.writeFileSync(OUTPUT_FILE, mermaidContent, 'utf-8');
|
||
console.log('✅ DEPENDENCY_GRAPH.md 已生成');
|
||
```
|
||
|
||
### 5.2 调用链生成
|
||
|
||
**升级版脚本**：同时生成依赖图和调用链
|
||
|
||
---
|
||
|
||
## 6. AI 友好特性
|
||
|
||
### 6.1 模块边界清晰
|
||
- 每个模块都有 `module_info.md` + `io_map.yaml`
|
||
- 明确的输入输出和依赖关系
|
||
|
||
### 6.2 依赖透明化
|
||
- `PROJECT_MAP.md` 和 `FEATURE_MAP.md` 让 AI 快速理解依赖和功能分类
|
||
- 可视化依赖图帮助识别循环依赖
|
||
|
||
### 6.3 调用链可视化
|
||
- `CALL_MAP.md` 让 AI 理解业务流程
|
||
- Mermaid 图表直观展示调用关系
|
||
|
||
### 6.4 标准化接口
|
||
- 所有函数和模块都有明确输入输出类型
|
||
- 统一的文档结构便于 AI 解析
|
||
|
||
### 6.5 示例代码
|
||
- `examples/` 提供最小调用示例，方便 AI 理解使用方式
|
||
|
||
---
|
||
|
||
## 7. 最佳实践
|
||
|
||
### 7.1 命名规范
|
||
- 模块名：小写短横线（kebab-case）
|
||
- 函数名：驼峰命名（camelCase）
|
||
- 类名：大驼峰命名（PascalCase）
|
||
- 常量：全大写（UPPER_CASE）
|
||
|
||
### 7.2 文件大小限制
|
||
- 单文件：≤ 2000 行
|
||
- 单函数：≤ 120 行
|
||
- 模块：≤ 10 文件
|
||
|
||
### 7.3 依赖规则
|
||
- 高层模块可以依赖低层模块
|
||
- 低层模块不能依赖高层模块
|
||
- 同级模块可以相互依赖，但要避免循环依赖
|
||
|
||
### 7.4 文档维护
|
||
- 新增模块时更新 `_nav.yaml`
|
||
- 修改依赖时更新 `PROJECT_MAP.md`
|
||
- 保持文档与代码同步
|
||
|
||
---
|
||
|
||
## 8. 工具推荐
|
||
|
||
### 8.1 依赖分析工具
|
||
- **JS/TS**: `madge`、`dependency-cruiser`
|
||
- **Python**: `pydeps`
|
||
|
||
### 8.2 文档生成工具
|
||
- **Markdown**: VS Code + Markdown Preview Enhanced
|
||
- **Mermaid**: 支持流程图和时序图
|
||
|
||
### 8.3 代码质量工具
|
||
- **ESLint**: 代码风格检查
|
||
- **Prettier**: 代码格式化
|
||
- **TypeScript**: 类型检查
|
||
|
||
---
|
||
|
||
## 9. 模板文件
|
||
|
||
### 9.1 模块信息模板（module_info.md）
|
||
|
||
```markdown
|
||
# {模块名} 模块
|
||
## 功能
|
||
- 功能1
|
||
- 功能2
|
||
- 功能3
|
||
## 接口
|
||
- `method1(param1: type): returnType`
|
||
- `method2(param1: type, param2: type): returnType`
|
||
## 输入输出
|
||
- 输入: 来源和类型
|
||
- 输出: 目标和类型
|
||
## 依赖
|
||
- [依赖模块1](路径)
|
||
- [依赖模块2](路径)
|
||
## 被调用方
|
||
- 调用方1
|
||
- 调用方2
|
||
## 示例
|
||
```javascript
|
||
// 使用示例
|
||
```
|
||
```
|
||
```
|
||
|
||
### 9.2 输入输出模板（*_io.yaml）
|
||
|
||
```yaml
|
||
module: {模块名}
|
||
inputs:
|
||
- source: 来源模块.方法
|
||
type: 输入类型
|
||
outputs:
|
||
- destination: 目标模块.方法
|
||
type: 输出类型
|
||
```
|
||
|
||
### 9.3 导航模板（_nav.yaml）
|
||
|
||
```yaml
|
||
- module: core
|
||
docs:
|
||
- name: utils
|
||
path: core/utils.md
|
||
- name: constants
|
||
path: core/constants.md
|
||
- module: service
|
||
docs:
|
||
- name: userService
|
||
path: service/userService.md
|
||
- name: orderService
|
||
path: service/orderService.md
|
||
```
|
||
|
||
---
|
||
|
||
## 10. 总结
|
||
|
||
AI 友好项目结构的核心是：
|
||
|
||
1. **清晰的模块边界**：每个模块有明确的职责和接口
|
||
2. **一致的依赖方向**：高层依赖低层，避免循环
|
||
3. **标准化的文档**：统一结构，便于 AI 解析
|
||
4. **可视化的依赖关系**：帮助 AI 理解整体架构
|
||
5. **示例代码**：方便 AI 学习使用方式
|
||
|
||
通过这套结构，AI 可以：
|
||
- 快速理解模块职责和依赖关系
|
||
- 避免循环依赖和架构混乱
|
||
- 定位问题和辅助重构
|
||
- 生成符合项目规范的代码
|
||
|
||
---
|
||
|
||
*本指南适用于所有项目，可根据具体项目需求进行调整。* |