145 lines
6.1 KiB
Markdown
145 lines
6.1 KiB
Markdown
# Node.js项目架构规范
|
||
|
||
`Node.js` `项目架构` `AI开发` `代码规范` `模块化`
|
||
|
||
# nodejs-project-arch
|
||
|
||
**面向 AI 辅助开发的 Node.js 项目架构规范。**
|
||
|
||
这是一个 [OpenClaw](https://openclaw.ai) / AI 智能体技能，用于强制执行模块化文件结构，将每个文件控制在足够小的体积，使 AI 能够在不超出上下文窗口的情况下读取和编辑。
|
||
|
||
## ✨ 为什么需要它？
|
||
|
||
当 AI 智能体处理大型单文件代码库时，问题会迅速暴露：
|
||
|
||
| 场景 | 每次读取的 Token 数 | 上下文占用（200K） |
|
||
|------|----------------|-----------------|
|
||
| 3000 行的 `server.js` | ~40K | 20% |
|
||
| 200 行的模块 | ~2.7K | 1.3% |
|
||
|
||
**结论：** 拆分文件意味着在上下文压缩前可完成 **10-15 轮高效操作**，而单体文件只能完成 3-5 轮。这相当于每次文件读取节省了 **70-93% 的 Token**。
|
||
|
||
## 📐 核心规则
|
||
|
||
- **单文件 ≤ 400 行** / `index.html` ≤ 200 行 / `server.js` 入口 ≤ 100 行
|
||
- **所有可调参数**存入 `config.json`——运行时加载，可通过管理后台编辑
|
||
- **后端：** `routes/` 按业务域划分，`services/` 存放共享逻辑，`db.js` 负责数据库初始化
|
||
- **前端：** HTML 仅保留骨架，JS/CSS 分离存放于 `public/` 目录下
|
||
- **每个项目**都包含 `admin.html` + `routes/admin.js`，用于配置热重载和统计信息
|
||
|
||
## 🎮 支持的项目类型
|
||
|
||
| 类型 | 识别信号 | 参考文档 |
|
||
|------|---------|---------|
|
||
| **H5 游戏** | Canvas、Phaser、Matter.js、游戏循环、精灵图 | [references/game.md](references/game.md) |
|
||
| **数据工具** | 爬虫、采集器、调度器、数据同步、数据分析 | [references/tool.md](references/tool.md) |
|
||
| **内容/工具类** | 生成器、库、发布工具、文件处理 | [references/tool.md](references/tool.md) |
|
||
| **看板/监控** | 图表、实时数据、告警、指标 | [references/tool.md](references/tool.md) |
|
||
| **API 服务** | REST 接口、中间件、微服务 | [references/tool.md](references/tool.md) |
|
||
| **SDK/库** | 共享模块、构建步骤、多消费者 | [references/sdk.md](references/sdk.md) |
|
||
|
||
## 📁 典型目录结构
|
||
|
||
```
|
||
project-name/
|
||
server.js ← 入口文件，仅挂载路由（<100 行）
|
||
config.json ← 所有可调参数（管理后台可编辑）
|
||
db.js ← 数据库初始化 + 工具函数
|
||
routes/
|
||
auth.js ← 认证路由
|
||
game.js ← 核心游戏/业务路由
|
||
admin.js ← 管理员 API（配置增删改查、统计信息）
|
||
services/ ← 共享业务逻辑
|
||
public/
|
||
index.html ← 纯 HTML 骨架（<200 行）
|
||
admin.html ← 管理后台
|
||
css/style.css
|
||
js/ ← 按职责拆分，每个文件 <400 行
|
||
assets/
|
||
```
|
||
|
||
## 🚀 安装方式
|
||
|
||
### OpenClaw 用户
|
||
|
||
将技能复制到你的智能体技能目录：
|
||
|
||
```bash
|
||
# 克隆并复制
|
||
git clone https://github.com/abczsl520/nodejs-project-arch.git
|
||
cp -r nodejs-project-arch ~/.agents/skills/
|
||
|
||
# 或者如果你安装了 clawhub：
|
||
# clawhub install nodejs-project-arch
|
||
```
|
||
|
||
当你要求 AI 智能体执行以下操作时，该技能会自动激活：
|
||
- 创建新的 Node.js 项目
|
||
- 重构大型单文件代码库
|
||
- 拆分超大文件
|
||
|
||
### 手动参考
|
||
|
||
直接浏览参考文档：
|
||
- [游戏架构](references/game.md) —— 基于 Canvas/Phaser 的 H5 游戏
|
||
- [工具架构](references/tool.md) —— 数据工具、看板、API 服务
|
||
- [SDK 架构](references/sdk.md) —— 共享库与 SDK
|
||
|
||
## 📖 文档
|
||
|
||
完整文档可在 [Wiki](https://github.com/abczsl520/nodejs-project-arch/wiki) 上查阅：
|
||
|
||
- [首页](https://github.com/abczsl520/nodejs-project-arch/wiki) —— 概览
|
||
- [安装指南](https://github.com/abczsl520/nodejs-project-arch/wiki/Installation) —— 配置步骤
|
||
- [游戏架构](https://github.com/abczsl520/nodejs-project-arch/wiki/Game-Architecture) —— H5 游戏规范
|
||
- [工具架构](https://github.com/abczsl520/nodejs-project-arch/wiki/Tool-Architecture) —— 非游戏项目规范
|
||
- [SDK 架构](https://github.com/abczsl520/nodejs-project-arch/wiki/SDK-Architecture) —— 库/SDK 规范
|
||
- [配置模式](https://github.com/abczsl520/nodejs-project-arch/wiki/Config-Pattern) —— 通用 config.json 模式
|
||
- [管理后台](https://github.com/abczsl520/nodejs-project-arch/wiki/Admin-Dashboard) —— 管理面板规范
|
||
- [Token 节省分析](https://github.com/abczsl520/nodejs-project-arch/wiki/Token-Savings) —— Token 节省效果分析
|
||
|
||
## 🔧 快速示例：config.json 模式
|
||
|
||
```javascript
|
||
// server.js —— 加载并提供配置
|
||
const config = JSON.parse(fs.readFileSync('./config.json', 'utf8'));
|
||
|
||
app.get('/api/config', (req, res) => {
|
||
const safe = { ...config };
|
||
delete safe.admin;
|
||
res.json(safe);
|
||
});
|
||
|
||
// 管理员热重载
|
||
app.post('/admin/config', requireAdmin, (req, res) => {
|
||
fs.writeFileSync('./config.json.bak', fs.readFileSync('./config.json'));
|
||
fs.writeFileSync('./config.json', JSON.stringify(req.body, null, 2));
|
||
Object.assign(config, req.body);
|
||
res.json({ ok: true });
|
||
});
|
||
```
|
||
|
||
## 📊 真实场景 Token 节省数据
|
||
|
||
| 场景 | 优化前 | 优化后 | 节省比例 |
|
||
|------|--------|-------|---------|
|
||
| 读取游戏功能代码 | ~40K Token | ~2.7K Token | **93%** |
|
||
| 单轮开发（读取→编辑→验证） | ~52K Token | ~4K Token | **92%** |
|
||
| 4 轮 SDK 开发会话 | ~196K Token | ~69K Token | **65%** |
|
||
| 大型数据工具模块 | ~84K Token | ~8K Token | **90%** |
|
||
|
||
## 🧬 project-arch 家族的一员
|
||
|
||
该技能实现了 [project-arch-core](https://github.com/abczsl520/project-arch-core) 中针对 Node.js 的专项模式——project-arch-core 是面向 AI 辅助开发的语言无关架构原则集合。
|
||
|
||
| 技能 | 语言 | 状态 |
|
||
|------|------|------|
|
||
| **project-arch-core** | 通用原则 | ✅ 基础版 |
|
||
| **nodejs-project-arch**（本项目） | Node.js / Express | ✅ 已发布 |
|
||
| [react-project-arch](https://github.com/abczsl520/react-project-arch) | React / Vite | ✅ 已发布 |
|
||
| python-project-arch | Python | 🔲 欢迎社区贡献 |
|
||
| go-project-arch | Go | 🔲 欢迎社区贡献 |
|
||
|
||
## 许可证
|
||
|
||
MIT |