| # 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) |
|
|
