该文档是 devtools-frontend 项目中关于模型(model)管理的开发指南,主题为在 front_end/models/ 目录下创建新模型或迁移既有模型,主要面向维护该前端代码库的开发者。
一、用途 提供一套标准流程,指导开发者把模型类放到统一的 front_end/models/ 位置,并完成构建、注册、导入导出调整与测试验证。
二、准备工作 开始前先对将被移动的代码运行现有测试(./dt test front_end/<old_location>)确认基线通过;再用 grep -r "ClassName" front_end/ 搜索类/文件的使用位置,评估重构影响范围。
三、文件结构 模型目录为 front_end/models/<model_name>/,名称必须小写。入口文件为桶文件 <model_name>.ts,用于导出模型公共 API;实现逻辑放在 <ClassName>.ts;单元测试放在同目录的 <ClassName>.test.ts。
四、构建配置(BUILD.gn) 每个模型目录需包含 BUILD.gn,并定义三个目标:devtools_module("<model_name>") 列出实现源文件(sources)与 TypeScript 依赖(ts_deps),非 TypeScript 依赖(如 CSS、资源)放入 deps,且不要把桶文件列入 sources;devtools_entrypoint("bundle") 定义桶文件(entrypoint = "<model_name>.ts"),其 ts_deps 必须依赖模块目标;ts_library("unittests") 列出测试文件与仅测试用依赖,其 ts_deps 必须依赖 :bundle。
五、全局注册 构建系统不会自动发现新模块,需在 config/gni/devtools_grd_files.gni 中手动登记:发布(bundled)构建把桶文件的 .js 路径加入 grd_files_bundled_sources;调试(unbundled)构建把其余实现文件的 .js 路径加入 grd_files_unbundled_sources;同时把该模型的 unittests 目标加入 front_end/BUILD.gn 的 deps 列表,否则测试不会运行。
六、导入导出重构 使用方改为从新入口导入,例如 import * as ModelName from '../../models/<model_name>/<model_name>.js';迁移时从原目录的桶文件中删除对应导出;模型目录内部文件之间使用相对路径互相导入,禁止经由本模型自己的桶文件导入。
七、验证清单 依次执行构建 autoninja -C out/Default、代码检查 ./dt lint、新模型测试 ./dt test front_end/models/<model_name>,并回归测试原位置 ./dt test front_end/<old_location>。
八、常见问题 循环依赖由内部文件引用自身桶文件引起;测试目标未加入 front_end/BUILD.gn 会导致测试存在但不执行;忘记移除旧位置的类或导出会让旧用法继续存在;把桶文件列入 devtools_module 的 sources 会导致重复定义错误。