1. 项目概述当代码仓库变成一座3D城市作为一名在开发一线摸爬滚打了十多年的程序员我敢说几乎每个开发者都经历过这样的时刻面对一个庞大、复杂、历史悠久的代码仓库即使有再清晰的目录树和再强大的IDE那种“只见树木不见森林”的迷失感依然会袭来。文件之间的依赖关系、模块的耦合度、代码的“活性”即近期修改频率这些抽象的概念很难通过平面的文件列表直观感知。于是一个想法在我脑子里冒了出来能不能换一种方式“看”代码不是看一行行文本而是像城市规划师俯瞰一座城市一样去审视我们的代码库。这个想法最终落地成了一个让我自己都兴奋不已的项目——用 Seed Evolving 算法将整个 Git 仓库“搓”成了一座可以走进去、甚至能“飞”进去探索的 3D 城市。这不仅仅是一个酷炫的可视化玩具。它的核心价值在于通过将代码的抽象属性如文件大小、修改频率、依赖关系映射为城市的直观属性如建筑高度、颜色、道路连接为我们理解复杂软件系统的宏观结构提供了一个前所未有的视角。你可以一眼看出哪个模块是“摩天大楼”核心且庞大哪个区域是“老城区”历史悠久但改动少哪些“街区”之间交通繁忙耦合紧密。所使用的技术栈核心是Three.js这是目前 Web 端 3D 可视化的首选利器而Seed Evolving则是我为生成这座“代码城市”的布局和形态而设计的一套算法逻辑。2. 核心思路与架构设计2.1 从抽象数据到具象城市的映射逻辑这个项目的本质是一个数据可视化问题但它的数据源和映射规则比常见的图表要复杂得多。我们的输入是一个 Git 仓库输出是一个动态的 3D 场景。关键在于如何建立一套合理的映射规则。我设计的核心映射关系如下文件 - 建筑每一个源代码文件如.js,.py,.java都对应城市中的一栋建筑。文件体积 - 建筑基底面积与层高文件越大代码行数越多建筑的占地面积和层数就越多。一个庞大的main.js可能是一座占地广、高耸入云的塔楼而一个工具类utils.js可能只是一栋小平房。提交历史活跃度 - 建筑颜色与材质通过git log分析文件近期的修改频率。频繁修改的文件其建筑会呈现暖色调如橙色、红色象征着“活跃”和“火热开发”长期未动的文件则用冷色调如蓝色、灰色表示像是“静默”的街区。文件依赖关系 - 城市道路与桥梁这是让城市“活”起来的关键。通过静态分析如 ES Module 的import/export CommonJS 的require或构建工具如 Webpack 的 stats获取文件间的依赖关系。两个文件如果存在依赖它们的建筑之间就会生成一条道路。依赖越强如调用次数多、耦合深道路可以更宽、或者甚至用高架桥、空中连廊来表现。目录结构 - 城市行政区划不同的源代码目录如/src/components,/src/utils,/tests会成为城市的不同区域。同一目录下的建筑会在空间上聚集区域之间可能有主干道或河流作为视觉分隔隔开。注意映射规则没有标准答案完全可以根据你想强调的维度进行调整。例如你可以把“代码复杂度”如圈复杂度映射为建筑表面的纹理复杂度或者把“测试覆盖率”映射为建筑周围的绿化率。2.2 技术选型为什么是 Three.js 和自定义算法在技术选型上我几乎没有犹豫就选择了Three.js。原因很直接它成熟、强大、社区活跃并且完全基于 WebGL能在浏览器中实现硬件加速的 3D 渲染无需任何插件。这意味着生成的城市可以直接通过一个链接分享给任何人无论他是前端、后端还是项目经理打开浏览器就能体验。相比于 Unity WebGL 或 Unreal EngineThree.js 更轻量与前端开发流程npm, bundler集成度更高调试也更方便。而Seed Evolving这个名字是我为这个项目的布局生成算法起的。它不是一个现成的库而是我设计的一套逻辑。“Seed”代表初始种子即从 Git 仓库中提取的原始数据文件列表、依赖图。“Evolving”代表演化过程其核心目标是将抽象的、图状的数据通过一个迭代优化的过程布局成一个在 3D 空间中既美观避免重叠、分布均匀又能反映数据关系依赖强的靠近的“城市平面图”。这个过程可以简单理解为初始化将所有“建筑”文件随机撒在一个平面上。作用力模拟借鉴力导向图Force-Directed Graph的思想但做了3D化扩展。排斥力所有建筑之间都存在斥力防止它们挤在一起。斥力大小与建筑体积相关大楼会把小楼“推”开。吸引力有依赖关系的建筑之间会产生引力让它们彼此靠近。引力强度与依赖的权重如调用次数成正比。区域约束力同一目录下的建筑会受到一个向“区域中心”的拉力保证它们能形成集群。迭代演化在每一帧或每个计算步骤中计算每个建筑受到的所有合力并据此移动一小段距离。同时引入一个模拟“摩擦”的阻尼系数让系统能量逐渐衰减最终达到一个稳定的布局状态。这个“演化”过程会持续数百甚至上千次迭代直到布局基本稳定。最终我们得到了每个建筑在3D世界中的(x, z)坐标y轴用于高度以及道路的连接信息。这个坐标数据就是构建 Three.js 场景的蓝图。3. 核心实现步骤拆解3.1 第一步数据提取与处理——城市的“人口普查”在动工建城之前你得先搞清楚城里有多少人、谁和谁有关系。对应到代码仓库我们需要一个“数据爬虫”。我写了一个 Node.js 脚本核心是调用Git 命令和进行文件分析// 示例使用 simple-git 库获取文件列表和日志 const simpleGit require(simple-git); const fs require(fs); const path require(path); async function analyzeRepo(repoPath) { const git simpleGit(repoPath); const status await git.status(); const allFiles status.files.map(f f.path); // 获取所有被跟踪的文件 const fileData []; for (const filePath of allFiles.filter(f f.endsWith(.js) || f.endsWith(.ts))) { // 过滤源代码文件 const stats fs.statSync(path.join(repoPath, filePath)); const lines fs.readFileSync(path.join(repoPath, filePath), utf-8).split(\n).length; // 获取该文件的近期提交记录计算活跃度 const log await git.log({ file: filePath, --max-count: 10 }); const recentCommitCount log.total; fileData.push({ path: filePath, sizeInBytes: stats.size, linesOfCode: lines, recentActivity: recentCommitCount, directory: path.dirname(filePath) }); } return fileData; }依赖分析是另一个难点。对于 JavaScript/TypeScript 项目我使用了babel/parser和babel/traverse来构建一个简单的 AST 分析器提取文件中的所有import语句从而构建出文件依赖图。对于其他语言可能需要寻找相应的解析器或利用 IDE 的索引文件。最终我们得到的是一个 JSON 结构的数据集包含了每栋“建筑”的属性和它们之间的“道路”蓝图。3.2 第二步布局生成——用 Seed Evolving 算法规划城市有了数据接下来就是用Seed Evolving算法来计算布局。这部分是纯计算逻辑可以在 Node.js 后端完成也可以放在前端 Web Worker 中避免阻塞UI。算法的核心循环伪代码如下class CityLayoutEngine { constructor(buildings, dependencies) { this.buildings buildings; // 建筑数组包含初始随机位置 this.dependencies dependencies; // 依赖关系数组 this.iteration 0; this.damping 0.95; // 阻尼系数让系统慢慢停下来 } evolve() { for (let building of this.buildings) { building.force.set(0, 0, 0); // 重置受力 } // 1. 计算建筑间的斥力 (类似电荷斥力) for (let i 0; i this.buildings.length; i) { for (let j i 1; j this.buildings.length; j) { const b1 this.buildings[i]; const b2 this.buildings[j]; const dir b2.position.clone().sub(b1.position); const distance dir.length(); if (distance 0) continue; dir.normalize(); // 斥力与建筑体积成正比与距离平方成反比 const repulseForce (b1.volume b2.volume) / (distance * distance); const force dir.multiplyScalar(-repulseForce); b1.force.add(force); b2.force.sub(force); // 作用力与反作用力 } } // 2. 计算依赖间的引力 for (let dep of this.dependencies) { const source this.getBuildingByPath(dep.source); const target this.getBuildingByPath(dep.target); if (!source || !target) continue; const dir target.position.clone().sub(source.position); const distance dir.length(); dir.normalize(); // 引力与依赖强度成正比与距离成正比胡克定律简化版 const attractForce dep.strength * distance; const force dir.multiplyScalar(attractForce); source.force.add(force); target.force.sub(force); } // 3. 应用力并更新位置 for (let building of this.buildings) { building.force.multiplyScalar(this.damping); // 应用阻尼 building.position.add(building.force); // 可选添加边界约束防止建筑飞出“地图” } this.iteration; } }你需要反复调用evolve()方法比如在一个requestAnimationFrame循环中直到所有建筑的位置变化小于一个阈值或者达到最大迭代次数。最终得到的building.position就是每个建筑的最终坐标。3.3 第三步Three.js 场景构建——从蓝图到摩天楼布局坐标有了现在就是用 Three.js 把城市“建”起来。这个过程非常像搭积木。初始化场景、相机、渲染器这是 Three.js 的标准开局。创建建筑遍历处理好的建筑数据根据其linesOfCode决定几何体大小。function createBuilding(data) { const width Math.sqrt(data.linesOfCode) * 0.5; // 面积与代码行数相关 const depth width * 0.8; const height data.linesOfCode * 0.05; // 高度也与代码行数相关 const geometry new THREE.BoxGeometry(width, height, depth); // 根据活跃度决定颜色 const color new THREE.Color(); const hue 0.6 - (data.recentActivity / 10) * 0.5; // 从蓝色(0.6)到红色(0.1) color.setHSL(hue, 0.8, 0.5); const material new THREE.MeshPhongMaterial({ color: color }); const building new THREE.Mesh(geometry, material); building.position.set(data.x, height / 2, data.z); // y坐标是高度的一半让建筑底部着地 building.userData data; // 把原始数据存进去方便后续交互 return building; }创建道路遍历依赖关系在源建筑和目标建筑之间创建一条3D的“道路”。这里我用的是CatmullRomCurve3来创建平滑的曲线然后用TubeGeometry生成管道状的路径看起来更像高架路或轻轨。function createRoad(buildingA, buildingB) { const start buildingA.position.clone(); const end buildingB.position.clone(); // 控制点让道路有弧度避免全是直线 const control start.clone().add(end).multiplyScalar(0.5); control.y 20; // 让道路拱起来 const curve new THREE.CatmullRomCurve3([start, control, end]); const geometry new THREE.TubeGeometry(curve, 20, 0.5, 8, false); const material new THREE.MeshBasicMaterial({ color: 0xcccccc }); const road new THREE.Mesh(geometry, material); return road; }添加灯光与天空盒没有光城市就是一片漆黑。我通常会添加一个AmbientLight环境光照亮整体再加几个DirectionalLight平行光模拟日光制造光影效果。一个简单的天空盒或渐变背景能极大提升场景的沉浸感。实现交互城市的灵魂在于探索。我实现了第一人称/飞行相机使用PointerLockControls或FlyControls让用户可以用 WASD 键在城中行走或飞行。建筑悬停高亮通过Raycaster检测鼠标指向高亮显示被指中的建筑并显示一个 Tooltip展示文件名、代码行数、最后修改日期等信息。点击聚焦点击一个建筑相机平滑移动到该建筑附近并突出显示与其有直接依赖关系的其他建筑和道路。3.4 第四步性能优化——让大城市也能流畅游览当仓库有上千个文件时城市会非常庞大直接渲染所有细节会导致帧率暴跌。必须进行优化细节层次LOD对于远处的建筑使用更简单的几何体甚至是一个立方体和更低分辨率的纹理。Three.js 有LOD对象可以方便实现。视锥体剔除这是 Three.js 内置的功能只渲染相机视野内的物体。但对于我们这种可能有很多小物体的场景确保它正确工作很重要。实例化网格如果有很多形状相同、材质相同但位置/大小不同的建筑比如许多小的工具函数文件使用InstancedMesh可以极大减少绘制调用。这是性能提升的关键。按需加载对于超大型仓库可以考虑将城市分块只加载和渲染用户当前所在的区域。后处理慎用阴影、抗锯齿SSAA、景深等后处理效果非常消耗性能。在性能吃紧时应优先保证流畅度可以降低阴影质量或关闭一些效果。4. 实操心得与避坑指南4.1 布局算法的调参是门艺术Seed Evolving 算法中的几个参数对最终城市面貌影响巨大需要反复调试斥力系数/引力系数这决定了城市的“密度”。斥力太强城市会变得非常稀疏建筑间距离很远引力太强所有建筑会挤成一团。我的经验是从一个较小的引力系数开始慢慢增加斥力系数直到达到一个平衡。阻尼系数这个值通常设置在0.9到0.99之间。它决定了系统“冷却”的速度。阻尼太小建筑会一直抖动停不下来阻尼太大系统收敛太快可能得不到最优布局。区域约束力强度这个力保证了同一目录下的建筑能聚在一起。强度太低目录结构在视觉上会失效强度太高可能会覆盖掉依赖关系产生的引力导致跨目录的依赖建筑无法靠近。我的技巧是让区域约束力随迭代次数衰减。在布局初期它较强以保证快速形成集群后期减弱让依赖引力能更精细地调整建筑位置。4.2 Three.js 交互与性能的平衡Raycaster 的性能在每一帧都对成百上千个物体进行射线检测是灾难性的。你需要做空间加速。我使用的是 Three.js 的Raycaster的intersectObjects方法但传入的是经过筛选的、可能出现在屏幕中央区域的物体列表而不是全部物体。更好的做法是使用八叉树Octree或 BVHBounding Volume Hierarchy进行管理Three.js 社区有一些相关的库。内存管理在 Three.js 中创建的几何体、材质、纹理如果不使用了必须手动调用dispose()方法释放内存。特别是在动态更新城市布局或切换仓库时否则会导致内存泄漏。一个良好的模式是为整个城市场景创建一个Object3D容器需要清空时遍历其所有子对象进行dispose然后remove所有子对象。相机控制体验第一人称相机在3D城市中移动时很容易卡进建筑内部或穿模。一个简单的解决方案是为相机添加一个碰撞检测。你可以用一个Raycaster从相机位置向移动方向发射射线检测与建筑的距离如果太近就阻止移动或进行滑动。4.3 数据映射的视觉编码陷阱颜色是强大的视觉编码工具但用不好会产生误导。不要过度使用颜色如果你同时用颜色表示“活跃度”又用另一种颜色表示“文件类型”用户会困惑。坚持一个核心维度用颜色表示。选择感知均匀的颜色空间Three.js 的Color默认使用 RGB但从视觉感知上HSL 或 HSV 空间更容易让我们选择一系列在亮度、饱和度上均匀变化的颜色。这就是为什么我在示例代码中用setHSL来根据活跃度生成从蓝到红的渐变。提供图例无论你觉得你的颜色映射多么直观一定要在界面的角落提供一个简单的图例说明“红色代表高活跃度蓝色代表低活跃度”。这是数据可视化的基本素养。5. 扩展想象这座“代码城市”还能做什么基础的城市浏览已经很有用但它的潜力远不止于此。这里有几个我实现或正在构思的扩展方向时间旅行连接 Git 历史让城市可以“时光倒流”。通过一个滑块选择不同的提交版本城市中的建筑会动态地出现、消失、变色、变形。你可以直观地看到新功能模块如何像新区一样拔地而起废弃的代码如何变成“废墟”。这是理解项目演进史的绝佳方式。“热力图”覆盖集成代码覆盖率数据如 Istanbul 的报告。在运行测试套件后将覆盖率数据映射到城市上。被充分测试的建筑发出绿光未被覆盖的建筑呈现红光。一眼就能看出测试的薄弱区域。问题追踪集成与 Jira、GitHub Issues 联动。将未解决的 Bug 或任务标记为城市上空漂浮的“乌云”或“警示标志”点击可以直接跳转到 issue 页面。让技术债务变得肉眼可见。架构异味检测与可视化将诸如“循环依赖”、“上帝类”、“过深继承”等架构问题通过特定的视觉符号标记出来。比如循环依赖可以渲染成一个在空中旋转的、连接了多个建筑的红色光环非常醒目。团队协作视角分析git blame数据将建筑的不同“面”或“楼层”染上不同作者的颜色。你可以立刻看出哪个模块是由谁主要负责的或者哪些文件是多人频繁交叉修改的“热点冲突区”。这个项目对我自己最大的启发是它改变了我和团队评审代码、理解系统的方式。以前看架构图是二维的、抽象的现在则是沉浸式的、具象的。当一个新同事加入项目我不再只是给他看文档和目录树我会说“来我带你逛逛我们的代码城市。” 这种体验远比任何文档都来得直接和深刻。最后一个小技巧在展示给非技术同事或项目经理时他们可能不关心依赖关系。你可以切换到一个“简化视图”只显示建筑高度代码规模和颜色活跃度并告诉他们“看这片‘高楼林立’的区域是我们的核心业务逻辑最近‘红得发烫’说明正在密集开发那边灰色的‘矮房区’是工具库很稳定。” 沟通效率瞬间提升。
用Seed Evolving算法与Three.js将代码仓库构建为3D可视化城市
1. 项目概述当代码仓库变成一座3D城市作为一名在开发一线摸爬滚打了十多年的程序员我敢说几乎每个开发者都经历过这样的时刻面对一个庞大、复杂、历史悠久的代码仓库即使有再清晰的目录树和再强大的IDE那种“只见树木不见森林”的迷失感依然会袭来。文件之间的依赖关系、模块的耦合度、代码的“活性”即近期修改频率这些抽象的概念很难通过平面的文件列表直观感知。于是一个想法在我脑子里冒了出来能不能换一种方式“看”代码不是看一行行文本而是像城市规划师俯瞰一座城市一样去审视我们的代码库。这个想法最终落地成了一个让我自己都兴奋不已的项目——用 Seed Evolving 算法将整个 Git 仓库“搓”成了一座可以走进去、甚至能“飞”进去探索的 3D 城市。这不仅仅是一个酷炫的可视化玩具。它的核心价值在于通过将代码的抽象属性如文件大小、修改频率、依赖关系映射为城市的直观属性如建筑高度、颜色、道路连接为我们理解复杂软件系统的宏观结构提供了一个前所未有的视角。你可以一眼看出哪个模块是“摩天大楼”核心且庞大哪个区域是“老城区”历史悠久但改动少哪些“街区”之间交通繁忙耦合紧密。所使用的技术栈核心是Three.js这是目前 Web 端 3D 可视化的首选利器而Seed Evolving则是我为生成这座“代码城市”的布局和形态而设计的一套算法逻辑。2. 核心思路与架构设计2.1 从抽象数据到具象城市的映射逻辑这个项目的本质是一个数据可视化问题但它的数据源和映射规则比常见的图表要复杂得多。我们的输入是一个 Git 仓库输出是一个动态的 3D 场景。关键在于如何建立一套合理的映射规则。我设计的核心映射关系如下文件 - 建筑每一个源代码文件如.js,.py,.java都对应城市中的一栋建筑。文件体积 - 建筑基底面积与层高文件越大代码行数越多建筑的占地面积和层数就越多。一个庞大的main.js可能是一座占地广、高耸入云的塔楼而一个工具类utils.js可能只是一栋小平房。提交历史活跃度 - 建筑颜色与材质通过git log分析文件近期的修改频率。频繁修改的文件其建筑会呈现暖色调如橙色、红色象征着“活跃”和“火热开发”长期未动的文件则用冷色调如蓝色、灰色表示像是“静默”的街区。文件依赖关系 - 城市道路与桥梁这是让城市“活”起来的关键。通过静态分析如 ES Module 的import/export CommonJS 的require或构建工具如 Webpack 的 stats获取文件间的依赖关系。两个文件如果存在依赖它们的建筑之间就会生成一条道路。依赖越强如调用次数多、耦合深道路可以更宽、或者甚至用高架桥、空中连廊来表现。目录结构 - 城市行政区划不同的源代码目录如/src/components,/src/utils,/tests会成为城市的不同区域。同一目录下的建筑会在空间上聚集区域之间可能有主干道或河流作为视觉分隔隔开。注意映射规则没有标准答案完全可以根据你想强调的维度进行调整。例如你可以把“代码复杂度”如圈复杂度映射为建筑表面的纹理复杂度或者把“测试覆盖率”映射为建筑周围的绿化率。2.2 技术选型为什么是 Three.js 和自定义算法在技术选型上我几乎没有犹豫就选择了Three.js。原因很直接它成熟、强大、社区活跃并且完全基于 WebGL能在浏览器中实现硬件加速的 3D 渲染无需任何插件。这意味着生成的城市可以直接通过一个链接分享给任何人无论他是前端、后端还是项目经理打开浏览器就能体验。相比于 Unity WebGL 或 Unreal EngineThree.js 更轻量与前端开发流程npm, bundler集成度更高调试也更方便。而Seed Evolving这个名字是我为这个项目的布局生成算法起的。它不是一个现成的库而是我设计的一套逻辑。“Seed”代表初始种子即从 Git 仓库中提取的原始数据文件列表、依赖图。“Evolving”代表演化过程其核心目标是将抽象的、图状的数据通过一个迭代优化的过程布局成一个在 3D 空间中既美观避免重叠、分布均匀又能反映数据关系依赖强的靠近的“城市平面图”。这个过程可以简单理解为初始化将所有“建筑”文件随机撒在一个平面上。作用力模拟借鉴力导向图Force-Directed Graph的思想但做了3D化扩展。排斥力所有建筑之间都存在斥力防止它们挤在一起。斥力大小与建筑体积相关大楼会把小楼“推”开。吸引力有依赖关系的建筑之间会产生引力让它们彼此靠近。引力强度与依赖的权重如调用次数成正比。区域约束力同一目录下的建筑会受到一个向“区域中心”的拉力保证它们能形成集群。迭代演化在每一帧或每个计算步骤中计算每个建筑受到的所有合力并据此移动一小段距离。同时引入一个模拟“摩擦”的阻尼系数让系统能量逐渐衰减最终达到一个稳定的布局状态。这个“演化”过程会持续数百甚至上千次迭代直到布局基本稳定。最终我们得到了每个建筑在3D世界中的(x, z)坐标y轴用于高度以及道路的连接信息。这个坐标数据就是构建 Three.js 场景的蓝图。3. 核心实现步骤拆解3.1 第一步数据提取与处理——城市的“人口普查”在动工建城之前你得先搞清楚城里有多少人、谁和谁有关系。对应到代码仓库我们需要一个“数据爬虫”。我写了一个 Node.js 脚本核心是调用Git 命令和进行文件分析// 示例使用 simple-git 库获取文件列表和日志 const simpleGit require(simple-git); const fs require(fs); const path require(path); async function analyzeRepo(repoPath) { const git simpleGit(repoPath); const status await git.status(); const allFiles status.files.map(f f.path); // 获取所有被跟踪的文件 const fileData []; for (const filePath of allFiles.filter(f f.endsWith(.js) || f.endsWith(.ts))) { // 过滤源代码文件 const stats fs.statSync(path.join(repoPath, filePath)); const lines fs.readFileSync(path.join(repoPath, filePath), utf-8).split(\n).length; // 获取该文件的近期提交记录计算活跃度 const log await git.log({ file: filePath, --max-count: 10 }); const recentCommitCount log.total; fileData.push({ path: filePath, sizeInBytes: stats.size, linesOfCode: lines, recentActivity: recentCommitCount, directory: path.dirname(filePath) }); } return fileData; }依赖分析是另一个难点。对于 JavaScript/TypeScript 项目我使用了babel/parser和babel/traverse来构建一个简单的 AST 分析器提取文件中的所有import语句从而构建出文件依赖图。对于其他语言可能需要寻找相应的解析器或利用 IDE 的索引文件。最终我们得到的是一个 JSON 结构的数据集包含了每栋“建筑”的属性和它们之间的“道路”蓝图。3.2 第二步布局生成——用 Seed Evolving 算法规划城市有了数据接下来就是用Seed Evolving算法来计算布局。这部分是纯计算逻辑可以在 Node.js 后端完成也可以放在前端 Web Worker 中避免阻塞UI。算法的核心循环伪代码如下class CityLayoutEngine { constructor(buildings, dependencies) { this.buildings buildings; // 建筑数组包含初始随机位置 this.dependencies dependencies; // 依赖关系数组 this.iteration 0; this.damping 0.95; // 阻尼系数让系统慢慢停下来 } evolve() { for (let building of this.buildings) { building.force.set(0, 0, 0); // 重置受力 } // 1. 计算建筑间的斥力 (类似电荷斥力) for (let i 0; i this.buildings.length; i) { for (let j i 1; j this.buildings.length; j) { const b1 this.buildings[i]; const b2 this.buildings[j]; const dir b2.position.clone().sub(b1.position); const distance dir.length(); if (distance 0) continue; dir.normalize(); // 斥力与建筑体积成正比与距离平方成反比 const repulseForce (b1.volume b2.volume) / (distance * distance); const force dir.multiplyScalar(-repulseForce); b1.force.add(force); b2.force.sub(force); // 作用力与反作用力 } } // 2. 计算依赖间的引力 for (let dep of this.dependencies) { const source this.getBuildingByPath(dep.source); const target this.getBuildingByPath(dep.target); if (!source || !target) continue; const dir target.position.clone().sub(source.position); const distance dir.length(); dir.normalize(); // 引力与依赖强度成正比与距离成正比胡克定律简化版 const attractForce dep.strength * distance; const force dir.multiplyScalar(attractForce); source.force.add(force); target.force.sub(force); } // 3. 应用力并更新位置 for (let building of this.buildings) { building.force.multiplyScalar(this.damping); // 应用阻尼 building.position.add(building.force); // 可选添加边界约束防止建筑飞出“地图” } this.iteration; } }你需要反复调用evolve()方法比如在一个requestAnimationFrame循环中直到所有建筑的位置变化小于一个阈值或者达到最大迭代次数。最终得到的building.position就是每个建筑的最终坐标。3.3 第三步Three.js 场景构建——从蓝图到摩天楼布局坐标有了现在就是用 Three.js 把城市“建”起来。这个过程非常像搭积木。初始化场景、相机、渲染器这是 Three.js 的标准开局。创建建筑遍历处理好的建筑数据根据其linesOfCode决定几何体大小。function createBuilding(data) { const width Math.sqrt(data.linesOfCode) * 0.5; // 面积与代码行数相关 const depth width * 0.8; const height data.linesOfCode * 0.05; // 高度也与代码行数相关 const geometry new THREE.BoxGeometry(width, height, depth); // 根据活跃度决定颜色 const color new THREE.Color(); const hue 0.6 - (data.recentActivity / 10) * 0.5; // 从蓝色(0.6)到红色(0.1) color.setHSL(hue, 0.8, 0.5); const material new THREE.MeshPhongMaterial({ color: color }); const building new THREE.Mesh(geometry, material); building.position.set(data.x, height / 2, data.z); // y坐标是高度的一半让建筑底部着地 building.userData data; // 把原始数据存进去方便后续交互 return building; }创建道路遍历依赖关系在源建筑和目标建筑之间创建一条3D的“道路”。这里我用的是CatmullRomCurve3来创建平滑的曲线然后用TubeGeometry生成管道状的路径看起来更像高架路或轻轨。function createRoad(buildingA, buildingB) { const start buildingA.position.clone(); const end buildingB.position.clone(); // 控制点让道路有弧度避免全是直线 const control start.clone().add(end).multiplyScalar(0.5); control.y 20; // 让道路拱起来 const curve new THREE.CatmullRomCurve3([start, control, end]); const geometry new THREE.TubeGeometry(curve, 20, 0.5, 8, false); const material new THREE.MeshBasicMaterial({ color: 0xcccccc }); const road new THREE.Mesh(geometry, material); return road; }添加灯光与天空盒没有光城市就是一片漆黑。我通常会添加一个AmbientLight环境光照亮整体再加几个DirectionalLight平行光模拟日光制造光影效果。一个简单的天空盒或渐变背景能极大提升场景的沉浸感。实现交互城市的灵魂在于探索。我实现了第一人称/飞行相机使用PointerLockControls或FlyControls让用户可以用 WASD 键在城中行走或飞行。建筑悬停高亮通过Raycaster检测鼠标指向高亮显示被指中的建筑并显示一个 Tooltip展示文件名、代码行数、最后修改日期等信息。点击聚焦点击一个建筑相机平滑移动到该建筑附近并突出显示与其有直接依赖关系的其他建筑和道路。3.4 第四步性能优化——让大城市也能流畅游览当仓库有上千个文件时城市会非常庞大直接渲染所有细节会导致帧率暴跌。必须进行优化细节层次LOD对于远处的建筑使用更简单的几何体甚至是一个立方体和更低分辨率的纹理。Three.js 有LOD对象可以方便实现。视锥体剔除这是 Three.js 内置的功能只渲染相机视野内的物体。但对于我们这种可能有很多小物体的场景确保它正确工作很重要。实例化网格如果有很多形状相同、材质相同但位置/大小不同的建筑比如许多小的工具函数文件使用InstancedMesh可以极大减少绘制调用。这是性能提升的关键。按需加载对于超大型仓库可以考虑将城市分块只加载和渲染用户当前所在的区域。后处理慎用阴影、抗锯齿SSAA、景深等后处理效果非常消耗性能。在性能吃紧时应优先保证流畅度可以降低阴影质量或关闭一些效果。4. 实操心得与避坑指南4.1 布局算法的调参是门艺术Seed Evolving 算法中的几个参数对最终城市面貌影响巨大需要反复调试斥力系数/引力系数这决定了城市的“密度”。斥力太强城市会变得非常稀疏建筑间距离很远引力太强所有建筑会挤成一团。我的经验是从一个较小的引力系数开始慢慢增加斥力系数直到达到一个平衡。阻尼系数这个值通常设置在0.9到0.99之间。它决定了系统“冷却”的速度。阻尼太小建筑会一直抖动停不下来阻尼太大系统收敛太快可能得不到最优布局。区域约束力强度这个力保证了同一目录下的建筑能聚在一起。强度太低目录结构在视觉上会失效强度太高可能会覆盖掉依赖关系产生的引力导致跨目录的依赖建筑无法靠近。我的技巧是让区域约束力随迭代次数衰减。在布局初期它较强以保证快速形成集群后期减弱让依赖引力能更精细地调整建筑位置。4.2 Three.js 交互与性能的平衡Raycaster 的性能在每一帧都对成百上千个物体进行射线检测是灾难性的。你需要做空间加速。我使用的是 Three.js 的Raycaster的intersectObjects方法但传入的是经过筛选的、可能出现在屏幕中央区域的物体列表而不是全部物体。更好的做法是使用八叉树Octree或 BVHBounding Volume Hierarchy进行管理Three.js 社区有一些相关的库。内存管理在 Three.js 中创建的几何体、材质、纹理如果不使用了必须手动调用dispose()方法释放内存。特别是在动态更新城市布局或切换仓库时否则会导致内存泄漏。一个良好的模式是为整个城市场景创建一个Object3D容器需要清空时遍历其所有子对象进行dispose然后remove所有子对象。相机控制体验第一人称相机在3D城市中移动时很容易卡进建筑内部或穿模。一个简单的解决方案是为相机添加一个碰撞检测。你可以用一个Raycaster从相机位置向移动方向发射射线检测与建筑的距离如果太近就阻止移动或进行滑动。4.3 数据映射的视觉编码陷阱颜色是强大的视觉编码工具但用不好会产生误导。不要过度使用颜色如果你同时用颜色表示“活跃度”又用另一种颜色表示“文件类型”用户会困惑。坚持一个核心维度用颜色表示。选择感知均匀的颜色空间Three.js 的Color默认使用 RGB但从视觉感知上HSL 或 HSV 空间更容易让我们选择一系列在亮度、饱和度上均匀变化的颜色。这就是为什么我在示例代码中用setHSL来根据活跃度生成从蓝到红的渐变。提供图例无论你觉得你的颜色映射多么直观一定要在界面的角落提供一个简单的图例说明“红色代表高活跃度蓝色代表低活跃度”。这是数据可视化的基本素养。5. 扩展想象这座“代码城市”还能做什么基础的城市浏览已经很有用但它的潜力远不止于此。这里有几个我实现或正在构思的扩展方向时间旅行连接 Git 历史让城市可以“时光倒流”。通过一个滑块选择不同的提交版本城市中的建筑会动态地出现、消失、变色、变形。你可以直观地看到新功能模块如何像新区一样拔地而起废弃的代码如何变成“废墟”。这是理解项目演进史的绝佳方式。“热力图”覆盖集成代码覆盖率数据如 Istanbul 的报告。在运行测试套件后将覆盖率数据映射到城市上。被充分测试的建筑发出绿光未被覆盖的建筑呈现红光。一眼就能看出测试的薄弱区域。问题追踪集成与 Jira、GitHub Issues 联动。将未解决的 Bug 或任务标记为城市上空漂浮的“乌云”或“警示标志”点击可以直接跳转到 issue 页面。让技术债务变得肉眼可见。架构异味检测与可视化将诸如“循环依赖”、“上帝类”、“过深继承”等架构问题通过特定的视觉符号标记出来。比如循环依赖可以渲染成一个在空中旋转的、连接了多个建筑的红色光环非常醒目。团队协作视角分析git blame数据将建筑的不同“面”或“楼层”染上不同作者的颜色。你可以立刻看出哪个模块是由谁主要负责的或者哪些文件是多人频繁交叉修改的“热点冲突区”。这个项目对我自己最大的启发是它改变了我和团队评审代码、理解系统的方式。以前看架构图是二维的、抽象的现在则是沉浸式的、具象的。当一个新同事加入项目我不再只是给他看文档和目录树我会说“来我带你逛逛我们的代码城市。” 这种体验远比任何文档都来得直接和深刻。最后一个小技巧在展示给非技术同事或项目经理时他们可能不关心依赖关系。你可以切换到一个“简化视图”只显示建筑高度代码规模和颜色活跃度并告诉他们“看这片‘高楼林立’的区域是我们的核心业务逻辑最近‘红得发烫’说明正在密集开发那边灰色的‘矮房区’是工具库很稳定。” 沟通效率瞬间提升。
