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