489 lines
13 KiB
Markdown
489 lines
13 KiB
Markdown
# MeNav 源代码目录
|
||
|
||
## 目录
|
||
|
||
- [架构概述](#架构概述)
|
||
- [目录结构](#目录结构)
|
||
- [生成端（generator）](#生成端generator)
|
||
- [运行时（runtime）](#运行时runtime)
|
||
- [辅助函数（helpers）](#辅助函数helpers)
|
||
- [模块化开发规范](#模块化开发规范)
|
||
- [职责单一性原则](#职责单一性原则)
|
||
- [文件大小规范](#文件大小规范)
|
||
- [命名规范](#命名规范)
|
||
- [依赖管理](#依赖管理)
|
||
- [开发指南](#开发指南)
|
||
- [添加新模块](#添加新模块)
|
||
- [修改现有模块](#修改现有模块)
|
||
- [测试要求](#测试要求)
|
||
|
||
## 架构概述
|
||
|
||
MeNav 采用**模块化架构**，将代码按职责拆分为独立的、可维护的模块。整体分为三个主要部分：
|
||
|
||
1. **生成端（generator）**：构建期代码，负责将配置转换为静态 HTML
|
||
2. **运行时（runtime）**：浏览器端代码，负责用户交互和动态功能
|
||
3. **辅助函数（helpers）**：Handlebars 模板辅助函数
|
||
|
||
### 架构原则
|
||
|
||
- ✅ **职责单一**：每个模块只负责一件事
|
||
- ✅ **高内聚低耦合**：模块内部紧密相关，模块间松散依赖
|
||
- ✅ **可测试性**：每个模块都可以独立测试
|
||
- ✅ **可维护性**：清晰的目录结构和命名规范
|
||
|
||
## 目录结构
|
||
|
||
```text
|
||
src/
|
||
├── generator.js # 生成端薄入口（14行）
|
||
├── generator/ # 生成端实现
|
||
│ ├── main.js # 主流程控制（301行）
|
||
│ ├── cache/ # 缓存处理
|
||
│ │ ├── articles.js # 文章缓存（159行）
|
||
│ │ └── projects.js # 项目缓存（135行）
|
||
│ ├── config/ # 配置管理
|
||
│ │ ├── index.js # 配置入口（61行）
|
||
│ │ ├── loader.js # 配置加载（89行）
|
||
│ │ ├── validator.js # 配置验证（90行）
|
||
│ │ ├── resolver.js # 配置解析（146行）
|
||
│ │ └── slugs.js # Slug 生成（43行）
|
||
│ ├── html/ # HTML 生成
|
||
│ │ ├── 404.js # 404 页面（94行）
|
||
│ │ ├── components.js # 组件生成（208行）
|
||
│ │ ├── fonts.js # 字体处理（155行）
|
||
│ │ └── page-data.js # 页面数据准备（161行）
|
||
│ ├── template/ # 模板引擎
|
||
│ │ └── engine.js # Handlebars 引擎（120行）
|
||
│ └── utils/ # 工具函数
|
||
│ ├── html.js # HTML 工具（17行）
|
||
│ ├── pageMeta.js # 页面元信息（101行）
|
||
│ └── sites.js # 站点处理（35行）
|
||
├── runtime/ # 运行时实现
|
||
│ ├── index.js # 运行时入口（18行）
|
||
│ ├── shared.js # 共享工具（142行）
|
||
│ ├── tooltip.js # 提示框（115行）
|
||
│ ├── app/ # 应用逻辑
|
||
│ │ ├── index.js # 应用入口（112行）
|
||
│ │ ├── routing.js # 路由管理（403行）
|
||
│ │ ├── search.js # 搜索功能（440行）
|
||
│ │ ├── searchEngines.js # 搜索引擎（25行）
|
||
│ │ ├── ui.js # UI 交互（181行）
|
||
│ │ └── search/
|
||
│ │ └── highlight.js # 搜索高亮（90行）
|
||
│ ├── menav/ # 扩展 API
|
||
│ │ ├── index.js # API 入口（70行）
|
||
│ │ ├── addElement.js # 添加元素（351行）
|
||
│ │ ├── updateElement.js # 更新元素（166行）
|
||
│ │ ├── removeElement.js # 删除元素（26行）
|
||
│ │ ├── getAllElements.js# 获取元素（11行）
|
||
│ │ ├── getConfig.js # 获取配置（25行）
|
||
│ │ └── events.js # 事件系统（34行）
|
||
│ └── nested/ # 嵌套书签
|
||
│ └── index.js # 嵌套功能（230行）
|
||
└── helpers/ # Handlebars 辅助函数
|
||
├── index.js # 辅助函数注册
|
||
├── formatters.js # 格式化函数
|
||
├── conditions.js # 条件判断
|
||
└── utils.js # 工具函数
|
||
```
|
||
|
||
## 生成端（generator）
|
||
|
||
### 生成端职责
|
||
|
||
将 YAML 配置文件转换为静态 HTML 网站。
|
||
|
||
### 生成端核心模块
|
||
|
||
#### config/ - 配置管理
|
||
|
||
- **loader.js**：从文件系统加载 YAML 配置
|
||
- **validator.js**：验证配置合法性，填充默认值
|
||
- **resolver.js**：解析配置，准备渲染数据
|
||
- **slugs.js**：为分类生成唯一标识符
|
||
|
||
#### html/ - HTML 生成
|
||
|
||
- **page-data.js**：准备页面渲染数据（处理 projects/articles/bookmarks 特殊逻辑）
|
||
- **components.js**：生成导航、分类、社交链接等组件
|
||
- **fonts.js**：处理字体链接和 CSS
|
||
- **404.js**：生成 404 页面
|
||
|
||
#### cache/ - 缓存处理
|
||
|
||
- **articles.js**：处理 RSS 文章缓存
|
||
- **projects.js**：处理 GitHub 项目缓存
|
||
|
||
#### template/ - 模板引擎
|
||
|
||
- **engine.js**：Handlebars 模板加载和渲染
|
||
|
||
#### utils/ - 工具函数
|
||
|
||
- **pageMeta.js**：获取页面元信息（git 时间戳等）
|
||
- **sites.js**：递归收集站点数据
|
||
- **html.js**：HTML 处理工具
|
||
|
||
### 生成端入口文件
|
||
|
||
- **generator.js**：薄入口，re-export `generator/main.js`
|
||
- **main.js**：主流程控制，协调各模块完成构建
|
||
|
||
## 运行时（runtime）
|
||
|
||
### 运行时职责
|
||
|
||
在浏览器中提供用户交互功能和扩展 API。
|
||
|
||
### 运行时核心模块
|
||
|
||
#### app/ - 应用逻辑
|
||
|
||
- **routing.js**：页面路由、URL 处理、页面切换
|
||
- **search.js**：搜索索引、搜索逻辑、搜索引擎切换
|
||
- **ui.js**：UI 交互（侧边栏、主题切换、滚动等）
|
||
- **searchEngines.js**：外部搜索引擎配置
|
||
|
||
#### menav/ - 扩展 API
|
||
|
||
提供 `window.MeNav` API，供浏览器扩展使用：
|
||
|
||
- **addElement.js**：添加站点/分类/页面
|
||
- **updateElement.js**：更新元素属性
|
||
- **removeElement.js**：删除元素
|
||
- **getAllElements.js**：获取所有元素
|
||
- **getConfig.js**：获取配置
|
||
- **events.js**：事件系统（on/off/emit）
|
||
|
||
#### nested/ - 嵌套书签
|
||
|
||
- **index.js**：嵌套书签功能（展开/折叠/结构管理）
|
||
|
||
### 运行时入口文件
|
||
|
||
- **index.js**：运行时入口，初始化所有模块
|
||
- **shared.js**：共享工具函数（URL 校验、class 清洗等）
|
||
- **tooltip.js**：站点卡片悬停提示
|
||
|
||
### 构建流程
|
||
|
||
运行时代码通过 `scripts/build-runtime.js` 打包：
|
||
|
||
- 入口：`src/runtime/index.js`
|
||
- 输出：`dist/script.js`（IIFE 格式，单文件）
|
||
- 工具：esbuild
|
||
|
||
## 辅助函数（helpers）
|
||
|
||
### 辅助函数职责
|
||
|
||
为 Handlebars 模板提供辅助函数。
|
||
|
||
### 辅助函数模块
|
||
|
||
- **formatters.js**：日期格式化、文本处理
|
||
- **conditions.js**：条件判断、逻辑运算
|
||
- **utils.js**：数组处理、对象操作、URL 校验
|
||
- **index.js**：注册所有辅助函数到 Handlebars
|
||
|
||
## 模块化开发规范
|
||
|
||
### 职责单一性原则
|
||
|
||
**定义**：一个模块应该只负责一件事情，只有一个改变的理由。
|
||
|
||
**判断方法**：
|
||
|
||
1. 能用一句话描述模块职责
|
||
2. 只有一个理由会修改这个模块
|
||
3. 函数/变量名清晰反映职责
|
||
|
||
**示例**：
|
||
|
||
✅ **好的拆分**：
|
||
|
||
```javascript
|
||
// config/loader.js - 只负责加载配置
|
||
function loadModularConfig(dirPath) { /* ... */ }
|
||
|
||
// config/validator.js - 只负责验证配置
|
||
function validateConfig(config) { /* ... */ }
|
||
|
||
// config/resolver.js - 只负责解析配置
|
||
function prepareRenderData(config) { /* ... */ }
|
||
```
|
||
|
||
❌ **不好的拆分**：
|
||
|
||
```javascript
|
||
// config.js - 职责混杂
|
||
function processConfig(config) {
|
||
// 加载、验证、解析、转换... 400 行代码
|
||
}
|
||
```
|
||
|
||
### 文件大小规范
|
||
|
||
**目标**：
|
||
|
||
- 源码文件：≤ 500 行
|
||
- 理想大小：100-300 行
|
||
- 入口文件：≤ 100 行（薄入口）
|
||
|
||
**超过 500 行时**：
|
||
|
||
1. 检查是否职责混杂
|
||
2. 拆分为多个子模块
|
||
3. 提取可复用的工具函数
|
||
|
||
**当前状态**：
|
||
|
||
- 最大文件：440 行（search.js）
|
||
- 平均文件：~130 行
|
||
- 33 个模块文件
|
||
|
||
### 命名规范
|
||
|
||
#### 文件命名
|
||
|
||
- 使用 kebab-case：`page-data.js`、`search-engine.js`
|
||
- 名称反映职责：`loader.js`、`validator.js`、`resolver.js`
|
||
- 入口文件：`index.js`
|
||
|
||
#### 函数命名
|
||
|
||
- 使用 camelCase：`loadConfig`、`validateConfig`
|
||
- 动词开头：`get`、`set`、`load`、`validate`、`prepare`
|
||
- 清晰描述功能：`preparePageData`、`assignCategorySlugs`
|
||
|
||
#### 目录命名
|
||
|
||
- 使用 kebab-case：`page-data/`、`search-engine/`
|
||
- 名称反映功能域：`config/`、`cache/`、`html/`
|
||
|
||
### 依赖管理
|
||
|
||
#### 导入规范
|
||
|
||
```javascript
|
||
// 1. Node 内置模块
|
||
const fs = require('node:fs');
|
||
const path = require('node:path');
|
||
|
||
// 2. 第三方依赖
|
||
const yaml = require('js-yaml');
|
||
|
||
// 3. 项目内部模块（相对路径）
|
||
const { loadConfig } = require('./config');
|
||
const { renderTemplate } = require('./template/engine');
|
||
```
|
||
|
||
#### 导出规范
|
||
|
||
```javascript
|
||
// 单个导出
|
||
module.exports = function initSearch(state, dom) { /* ... */ };
|
||
|
||
// 多个导出
|
||
module.exports = {
|
||
loadConfig,
|
||
validateConfig,
|
||
prepareRenderData,
|
||
};
|
||
```
|
||
|
||
#### 循环依赖
|
||
|
||
- ❌ 避免循环依赖
|
||
- ✅ 通过依赖注入解决
|
||
- ✅ 提取共享代码到独立模块
|
||
|
||
## 开发指南
|
||
|
||
### 添加新模块
|
||
|
||
#### 1. 确定模块位置
|
||
|
||
**生成端**（构建期代码）：
|
||
|
||
```text
|
||
src/generator/
|
||
├── cache/ # 缓存处理
|
||
├── config/ # 配置管理
|
||
├── html/ # HTML 生成
|
||
├── template/ # 模板引擎
|
||
└── utils/ # 工具函数
|
||
```
|
||
|
||
**运行时**（浏览器代码）：
|
||
|
||
```text
|
||
src/runtime/
|
||
├── app/ # 应用逻辑
|
||
├── menav/ # 扩展 API
|
||
└── nested/ # 嵌套书签
|
||
```
|
||
|
||
#### 2. 创建模块文件
|
||
|
||
```javascript
|
||
// src/generator/config/new-module.js
|
||
|
||
/**
|
||
* 模块描述
|
||
* @param {Object} param - 参数说明
|
||
* @returns {Object} 返回值说明
|
||
*/
|
||
function newFunction(param) {
|
||
// 实现逻辑
|
||
}
|
||
|
||
module.exports = {
|
||
newFunction,
|
||
};
|
||
```
|
||
|
||
#### 3. 更新入口文件
|
||
|
||
```javascript
|
||
// src/generator/config/index.js
|
||
const { newFunction } = require('./new-module');
|
||
|
||
module.exports = {
|
||
// ... 其他导出
|
||
newFunction,
|
||
};
|
||
```
|
||
|
||
#### 4. 添加测试
|
||
|
||
```javascript
|
||
// test/new-module.test.js
|
||
const { newFunction } = require('../src/generator/config/new-module');
|
||
|
||
test('newFunction 应该...', () => {
|
||
const result = newFunction(input);
|
||
expect(result).toBe(expected);
|
||
});
|
||
```
|
||
|
||
### 修改现有模块
|
||
|
||
#### 1. 理解模块职责
|
||
|
||
- 阅读模块注释
|
||
- 查看函数签名
|
||
- 理解依赖关系
|
||
|
||
#### 2. 保持职责单一
|
||
|
||
- 不要在模块中添加无关功能
|
||
- 如果功能不匹配，创建新模块
|
||
|
||
#### 3. 运行测试
|
||
|
||
```bash
|
||
npm test # 运行所有测试
|
||
npm run build # 验证构建
|
||
```
|
||
|
||
#### 4. 更新文档
|
||
|
||
- 更新函数注释
|
||
- 更新 README（如有必要）
|
||
|
||
### 测试要求
|
||
|
||
#### 单元测试
|
||
|
||
- 每个模块都应有对应的测试文件
|
||
- 测试覆盖核心功能路径
|
||
- 使用 Node.js 内置测试框架
|
||
|
||
#### 集成测试
|
||
|
||
- 测试模块间的协作
|
||
- 验证构建产物
|
||
- 检查扩展契约
|
||
|
||
#### 测试命令
|
||
|
||
```bash
|
||
npm test # 运行所有测试
|
||
npm run lint # 代码检查
|
||
npm run format:check # 格式检查
|
||
```
|
||
|
||
## 最佳实践
|
||
|
||
### 1. 先读后写
|
||
|
||
- 修改代码前，先用 Read 工具读取文件
|
||
- 理解现有逻辑再进行修改
|
||
|
||
### 2. 小步迭代
|
||
|
||
- 每次只改一个模块
|
||
- 改完立即测试
|
||
- 确认无误后再继续
|
||
|
||
### 3. 保持一致性
|
||
|
||
- 遵循现有的代码风格
|
||
- 使用相同的命名规范
|
||
- 保持目录结构一致
|
||
|
||
### 4. 文档同步
|
||
|
||
- 代码变更时更新注释
|
||
- 重要改动更新 README
|
||
- 保持文档与代码一致
|
||
|
||
### 5. 测试先行
|
||
|
||
- 修改前运行测试（确保基线）
|
||
- 修改后运行测试（验证功能）
|
||
- 新功能添加测试（保证质量）
|
||
|
||
## 常见问题
|
||
|
||
### Q: 如何判断代码应该放在哪个模块？
|
||
|
||
**A**: 问自己三个问题：
|
||
|
||
1. 这段代码的职责是什么？（加载/验证/解析/渲染...）
|
||
2. 它属于哪个功能域？（配置/缓存/HTML/模板...）
|
||
3. 它在构建期还是运行时执行？（generator/runtime）
|
||
|
||
### Q: 模块太大了怎么办？
|
||
|
||
**A**: 拆分步骤：
|
||
|
||
1. 识别模块中的不同职责
|
||
2. 为每个职责创建独立模块
|
||
3. 更新入口文件的导入/导出
|
||
4. 运行测试验证
|
||
|
||
### Q: 如何避免循环依赖？
|
||
|
||
**A**: 三种方法：
|
||
|
||
1. 提取共享代码到独立模块
|
||
2. 使用依赖注入
|
||
3. 重新设计模块边界
|
||
|
||
### Q: 什么时候应该创建新目录？
|
||
|
||
**A**: 当满足以下条件时：
|
||
|
||
1. 有 3 个以上相关模块
|
||
2. 这些模块属于同一功能域
|
||
3. 需要独立的入口文件（index.js）
|
||
|
||
## 参考资料
|
||
|
||
- [P2-1 模块化重构文档](../../docs/2025-12-29_修复清单.md#p2-1-文件过大)
|
||
- [职责单一性原则](https://en.wikipedia.org/wiki/Single-responsibility_principle)
|
||
- [Node.js 模块系统](https://nodejs.org/api/modules.html)
|