做这个Nodejs和vue的公共交通路线应用系统之前说实话我自己也犹豫过。地图App里随手一搜就能出路线为什么还要自己造一个轮子但真把这个项目完整走下来之后我发现它值得做的原因恰恰不在公交查询这个业务本身而在背后的全栈链路数据怎么建模、接口怎么设计、换乘算法怎么实现、地图怎么和前端框架配合。这套东西做完你对一个真实系统是怎么从零长出来的会有非常具体的体感。这篇就按我实际开发的顺序把从需求拆解到跑通全流程的完整过程写出来包括踩过的坑和最终采用的方案。1. 需求边界一个公交路线系统真正要解决什么很多人在动手前容易犯一个错误想做的功能太多。我这版一开始也列了十几个需求包括实时定位、车辆位置追踪、到站提醒、票价计算……结果越做越乱。后来重新梳理才把系统收敛成三个核心场景。1.1 用户视角下的三件事第一个场景是线路查询。用户想知道某条线路经过哪些站、首末班时间是什么。第二个场景是站点查询按名字搜一个公交站能告诉你有哪些线路停靠这里。第三个场景是换乘规划这是核心中的核心从A站到B站有哪几种坐法、分别要换几次车、大概经过多少站。为什么把范围收敛到这三个因为一个教学性质或在中小型城市落地的公交系统这三件事覆盖了用户百分之八十以上的使用频率。实时定位和车辆追踪需要硬件配合或者接入第三方地图的实时接口数据源不是你能控制的票价计算则涉及当地公交公司的定价策略不同城市甚至同一城市不同线路的规则都不同。把这些边界外的东西砍掉系统才能保持自给自足——数据放进本地JSON文件就能跑不依赖任何外部商用API。1.2 管理端的取舍很多同类项目喜欢加一个后台管理界面让管理员增删改查线路。我最终没有做独立后台而是用了一个更朴素的方案直接在数据文件中维护配合几个只读的校验接口。为什么这么选因为对这个体量的项目来说管理端的CRUD功能会占掉大约百分之三十的开发量但对核心业务没有任何贡献。如果一定要管理功能我建议做成简单的Node脚本用命令行交互来维护JSON数据而不是硬塞一个管理页面。提示把数据文件本身当成数据库通过脚本维护适合数据量在几千条以内的项目。数据量一旦上来再考虑换成MongoDB或MySQL但接口设计可以保持不变。1.3 系统角色与技术边界系统最终分为两个角色普通用户通过浏览器访问前端页面完成查询开发者通过Nodejs后端管理数据文件。前端只负责展示和交互后端只负责数据检索和换乘计算。这个清晰的分工让后面每一步都能独立测试是项目能顺利推进的基础。2. 选型复盘为什么偏偏是Nodejs配Vue技术选型不是越新越好要看谁更适合这个场景。我最终定了NodejsExpress做后端 Vue 3Vite构建做前端这个组合不是跟风每一半都有自己的理由。2.1 后端为什么用Nodejs而不是其他换乘规划本质上是图论算法的应用。Nodejs是JavaScript运行时处理这类计算逻辑写得顺手而且它的异步I/O模型在处理多个前端并发请求时非常从容。更重要的是一个团队如果前端已经用了Vue后端再用Nodejs前后端语言统一数据格式JSON天然一致联调时不用来回转换。对比过Java Spring Boot的方案。Spring Boot在大型企业项目里确实是标杆但放在这个系统里有点杀鸡用牛刀光搭建工程、写实体类和Mapper就要半天而Express只需要几十行代码就能把接口跑起来。Python Flask也考虑过但Flask在前后端语言一致性上输给了Nodejs——前端同事看不懂Python后端代码交流成本会上升。2.2 前端为什么选Vue 3而不是其他框架Vue 3的响应式系统和组件化开发特别适合这种页面状态多、交互逻辑强的应用。搜索页有输入框、结果列表、地图三个区域状态要联动地图上点了站点列表要跟着高亮这种联动在Vue里用reactive和computed就能优雅实现。没选React的原因更实际Vue的中文资料和社区生态对国内开发者更友好遇到问题搜解决方案快。项目用Vite构建开发环境启动速度比Webpack快很多——实际测试下来冷启动大约在300毫秒左右改代码后的热更新几乎是即时的。这个体感对开发效率影响很大等几秒刷新和瞬间刷新是完全不同的节奏。2.3 前后端分工模式前端采用标准SPA单页应用架构所有页面跳转由Vue Router控制后端完全不负责页面渲染只提供JSON接口。通信通过RESTful API完成前端通过axios发起请求。整个分工可以用下面这张表概括层级技术选型负责内容前端界面Vue 3 Vite页面路由、地图渲染、表单交互、结果展示前端状态Pinia 组件props搜索条件、路线结果、选中状态后端接口ExpressRESTful API、参数校验、数据检索数据处理Nodejs脚本换乘算法、数据文件维护数据存储JSON文件站点数据、线路数据、班次数据3. 环境准备的两个拦路虎PowerShell脚本策略与npm镜像配置这个项目开始前两步就会卡住很多人。我第一次在Windows上装完Nodejs兴冲冲地在终端敲npm -v结果弹出的是npm : 无法加载文件 C:\Program Files\nodejs\npm.ps1因为在此系统上禁止运行脚本。当时真的一头雾水后来才知道这是PowerShell执行策略在作怪。3.1 npm.ps1报错的根因与解法Windows默认的PowerShell执行策略是Restricted禁止运行任何脚本而npm在Windows上通过npm.ps1这个PowerShell脚本启动。解决方式有两种第一种以管理员身份打开PowerShell执行Set-ExecutionPolicy RemoteSigned这个命令的意思是本地写的脚本可以运行从网上下载的脚本必须经过数字签名才能运行。这是最平衡的安全策略既避免了完全放开的危险也不再拦着npm这类正规工具。第二种方式是不改全局策略直接在终端里改用npm.cmdnpm.cmd -v祭出这个命令之后问题立竿见影。不用管理员权限也不影响任何系统安全性。我一直到后期才切换回正常的npm命令因为执行过Set-ExecutionPolicy RemoteSigned后反而更顺手。注意如果终端是Windows PowerShell而非CMD有时候会出现外部命令无法识别的情况。这时候可以先输入cmd切换到命令行界面再执行npm命令。3.2 npm镜像源从龟速到秒下Nodejs装好后第一件头疼的事就是npm install特别慢经常等几分钟还在转圈。这不是网络问题是默认源指向国外。解决办法是切换到国内镜像源npm config set registry https://registry.npmmirror.com设置完可以检查一下npm config get registry输出https://registry.npmmirror.com就说明切换成功。切换之后下载Vue相关依赖包的速度从原来的几MB每秒直接翻倍npm install几秒到十几秒就能完成。还有一个细节在项目根目录建一个.npmrc文件写入registryhttps://registry.npmmirror.com这样即使换一台电脑克隆项目也能够自动使用国内镜像源——这个文件记得提交到Git。3.3 验证Nodejs与Vue脚手架Nodejs装好后终端执行node -v能显示版本号我开发时用的是18.x LTS版本npm -v能显示npm版本号。接下来创建Vue项目npm create vuelatest bus-frontend这里用的是官方提供的create-vue脚手架它会问你需不需要TypeScript、Router、Pinia等附加能力。对这个项目Router要选YesPinia可以选TypeScript按你队伍熟悉度来——我选择了JavaScript因为在数据格式灵活性和上手成本上更友好。项目创建之后进入目录安装依赖并启动cd bus-frontend npm install npm run dev浏览器访问http://localhost:5173看到Vue的欢迎页说明前端环境OK。后面在开发时我会把前端的API地址配置到一个单独的环境变量里这里先按下不表。4. 数据建模与接口设计站点、线路与搜索的语义数据层是整个系统的心脏。我当时花了最多时间想明白的不是怎么写接口而是数据到底怎么组织才能支持换乘计算这种图操作。4.1 数据怎么存JSON文件的抽象设计数据放在backend/data/busData.json里包含三张表stations站点、lines线路、lineStations线路与站点的关联关系。{ stations: [ { id: S001, name: 火车站, alias: [火车南站], latitude: 39.9042, longitude: 116.4074 }, { id: S002, name: 人民广场, alias: [], latitude: 39.9055, longitude: 116.4115 } ], lines: [ { id: L001, name: 1路, direction: 火车站-大学城, firstTime: 06:00, lastTime: 22:30 } ], lineStations: [ { lineId: L001, stationIds: [S001, S002, S003] } ] }这里有个设计细节值得说为什么把lineStations单独抽出来而不直接挂在line对象下因为一条线路的站点列表是明确有序的而且后续可能需要维护某条线路经过某个站点的反查索引查站点时想知道有哪些线路经过单独抽出来会比较灵活。站点表里专门设计了一个alias字段用来处理同站不同名的情况。比如市政府和市政府东其实是同一个站点的不同叫法这种数据在真实公交系统里很常见。检索时先按主名匹配match不上再去alias里找能显著提升搜索结果的质量。4.2 接口设计RESTful风格下的三个核心API后端接口我用Express实现总体上遵循RESTful风格获取线路列表app.get(/api/lines, (req, res) { const lines data.lines.map(line { const relation data.lineStations.find(rs rs.lineId line.id); return { ...line, stationCount: relation ? relation.stationIds.length : 0 }; }); res.json({ code: 0, data: lines }); });站点模糊搜索app.get(/api/stations, (req, res) { const { keyword } req.query; if (!keyword) { return res.status(400).json({ code: 400, message: keyword不能为空 }); } const result data.stations.filter(station { return station.name.includes(keyword) || station.alias.some(alias alias.includes(keyword)); }); res.json({ code: 0, data: result }); });换乘规划app.get(/api/route/search, (req, res) { const { from, to } req.query; if (!from || !to) { return res.status(400).json({ code: 400, message: from和to不能为空 }); } const fromStation matchStation(from); const toStation matchStation(to); if (!fromStation || !toStation) { return res.status(404).json({ code: 404, message: 未找到对应站点 }); } const routes findRoutes(fromStation.id, toStation.id); res.json({ code: 0, data: routes }); });接口统一返回{ code, data, message }格式code非0时前端能快速识别错误类型处理统一的toast提示。这种统一格式是我强烈建议所有项目都采用的——前端不用每次判断数据结构后端排查问题也更方便。4.3 参数校验与防御性编程接口这边最容易忽略的是参数校验。没有校验的接口前端传fromundefined或者from全是空格时后端直接500这在用户体验上非常糟糕。我写了一个简单的参数清洗函数function cleanKeyword(param) { if (!param || typeof param ! string) return ; return param.trim(); }每次拿到query参数先过一遍这个函数空字符串直接返回400。还有一个很实用的技巧是给所有API统一加了一个简易日志中间件app.use((req, res, next) { console.log([${new Date().toISOString()}] ${req.method} ${req.originalUrl}); next(); });这样每个请求进来在后台都会打一条日志联调阶段排查问题效率高很多。5. 换乘规划把公交网络抽象成图用BFS找最少换乘这是整个系统技术上最有分量的一块。选对算法之前先说清楚这个问题怎么抽象。5.1 公交网络为什么是图把每个公交站点看成图的一个节点同一线路相邻两个站点之间有一条边那整个城市的公交网络就变成了一张无向图公交车可以双向行驶。换乘的本质是什么在这张图上从起点站节点出发走到终点站节点中间经过的边经过了多条不同的线路换乘的次数就是路径中切换线路的次数。最少换乘路线这个需求要求的是换乘次数最少的路径而不是经过站点最少。这个目标在抽象时就不能只做节点到节点的BFS还要维护一个额外的维度——当前用的是哪条线路。5.2 BFS为什么能解决最少换乘BFS广度优先搜索天然是求最短路径的算法。在图里BFS从起点开始先走一步能到的所有节点再走两步能到的所有节点……第一次访问到终点时所用的步数一定是最少的。关键点在于怎么把换乘次数转化为步数。我的做法是扩展队列里的每一项时记录两个信息——当前节点和当前乘坐的线路ID。当从当前节点往邻居节点走时如果要走的边属于另一条线路就意味着换乘了一次步数加1如果仍属于同一条线路步数不变。其实我们并不需要最少数量的站数而在这里换乘数最少比站数最少更容易被BFS处理。所以就出现了双层级BFS第一层先做普通节点BFS找可达路径第二层在路径里计算换乘数然后按换乘数排序取最优。5.3 数据预处理构建邻接表和线路站点映射BFS需要一个邻接表每个站点能通过哪些线路到达哪些相邻站点。function buildGraph(stations, lines, lineStations) { const graph {}; stations.forEach(station { graph[station.id] []; }); lineStations.forEach(relation { const { lineId, stationIds } relation; for (let i 0; i stationIds.length - 1; i) { const from stationIds[i]; const to stationIds[i 1]; // 无向图两个方向都要加边 graph[from].push({ to, lineId }); graph[to].push({ from: to, lineId }); } }); return graph; }这里有个容易忽略的坑lineStations中的stationIds顺序是实际的行驶方向顺序但公交线路上相邻站点之间是可以双向通行的所以必须双向建边。漏掉一个方向会出现从A到B能查出来从B到A查不出来的诡异问题。5.4 BFS核心实现记录路径和线路切换点function findRoutes(fromId, toId) { const graph buildGraph(data.stations, data.lines, data.lineStations); const queue [{ stationId: fromId, lineId: null, path: [fromId], lines: [] }]; const visited new Set(); visited.add(${fromId}-null); const results []; while (queue.length 0) { const current queue.shift(); const { stationId, lineId, path, lines } current; if (stationId toId) { results.push({ path, lines, transfers: countTransfers(lines) }); continue; } const neighbors graph[stationId] || []; for (const neighbor of neighbors) { const key ${neighbor.to}-${neighbor.lineId}; if (visited.has(key)) continue; const nextLines lineId neighbor.lineId ? lines : [...lines, neighbor.lineId]; const newPath [...path, neighbor.to]; queue.push({ stationId: neighbor.to, lineId: neighbor.lineId, path: newPath, lines: nextLines }); visited.add(key); } } return results.sort((a, b) a.transfers - b.transfers); }visited如果只记录站点会漏掉换乘多次经过同一站点的方案记录站点ID-线路ID这个组合才能正确描述换乘。比如你在1路车经过了人民广场后来换2路又经过人民广场这在公交场景中是合法的。这个细节是我在测试时发现的初次实现只记录了stationId结果大量换乘方案被误杀。5.5 结果排序与实际体验BFS会一次性把所有路径都找出来这在站点多的城市里路径数量可能很多。我在返回之前加了一个排序和裁剪优先换乘次数少的其次经过站点少的最后最多返回5条。经过实测最少换乘路线在多数情况下都能在100毫秒内返回。这个性能在数据量几百个站点时完全够用。如果以后数据量扩大到几千个站点可能要考虑在BFS走完后直接只保留最优路径而不是全量收集。6. Vue路由与地图组件页面组织方式和Mapbox集成细节前端这部分我把精力集中在两件事上Vue Router怎么组织页面、Mapbox地图怎么跟Vue配合。6.1 页面路由四个页面四层职责这个系统的页面不算多我用Vue Router维护了一张清晰的路由表const routes [ { path: /, name: home, component: HomeView }, { path: /lines, name: lines, component: LineListView }, { path: /stations, name: stations, component: StationListView }, { path: /search, name: search, component: RouteSearchView } ];首页HomeView是指南性质的页面告诉用户可以做什么线路列表页展示所有线路站点列表页提供站点搜索换乘搜索页是核心包含搜索表单、结果列表和地图。需要注意的一点换乘搜索页的表单状态和地图状态是联动的不能简单用组件props传递。我用Pinia定义了一个routeStore存当前搜索条件、结果列表、地图选中的站点这样搜索结果组件和地图组件都可以直接从store中取数据避免了props逐层透传。6.2 Mapbox接入为什么选择Mapbox而非Leaflet地图库我最终选了Mapbox GL JS。Leaflet虽然更轻量、加载更快但它的底图样式相对朴素做出来的演示效果不如Mapbox。Mapbox在Vue里集成时有个常见方案使用vue-map-gl这个封装组件但我在实际情况中发现这个封装组件的API更新比较频繁反而直接使用Mapbox的原生JS SDK更稳定。具体做法是在index.html里通过CDN引入Mapbox GL JS的css和js文件在Vue组件中挂载时创建map实例。!-- index.html -- link hrefhttps://api.mapbox.com/mapbox-gl-js/v2.15.0/mapbox-gl.css relstylesheet / script srchttps://api.mapbox.com/mapbox-gl-js/v2.15.0/mapbox-gl.js/script在组件中import { onMounted, watch, ref } from vue; const map ref(null); const mapBoxToken 你的mapbox公钥; onMounted(() { map.value new mapboxgl.Map({ container: map-container, style: mapbox://styles/mapbox/streets-v12, center: [116.4074, 39.9042], zoom: 12 }); }); function drawLine(coordinates) { // 用GeoJSON LineString格式画线路 }6.3 地图上的线路绘制与站点标记站点标记用mapboxgl.Marker实现每条搜索到的换乘路线我会在地图上用不同颜色的线绘制出来。Mapbox的图层API要求GeoJSON格式需要把站点坐标转换成[经度, 纬度]数组。关键技巧是多个Source和Layer的管理。每次搜索时要清掉上一次的路线图层否则地图上会叠一大堆旧线。我封装了一个函数function clearRouteLayers() { const sourceIds [route-source-a, route-source-b, route-source-c]; sourceIds.forEach(sourceId { if (map.value.getSource(sourceId)) { map.value.removeLayer(${sourceId}-layer); map.value.removeSource(sourceId); } }); }地图初始化时同时给每个站点添加点击事件。点击Marker后弹出站点信息框同时把搜索结果列表中对应站点高亮。这个交互逻辑一开始想得很复杂最终拆成两个方法onMarkerClick和highlightStationInList中间通过Pinia的store传递选中状态。6.4 卡片列表与地图的双向联动搜索结果左侧是路线卡片列表右侧是地图。卡片上展示起点、终点、换乘次数、总站数和具体经过的线路名称。点击卡片时地图会把这条路线单独高亮其他路线变暗。这个效果用到的是Mapbox的Client高度状态watch(() routeStore.selectedRouteIndex, (newIndex) { updateLayersOpacity(newIndex); });地图图层绘制时给每条线路的LineString设置了不同的颜色属性切换选中时调整各layer的opacity。这个交互虽然代码量不大但给完整系统的体验提升非常明显。7. 前后端联调踩坑跨域、编码与异步竞态单独跑后端接口、单独跑前端页面都没问题一旦联调问题就一个一个冒出来了。这几个坑我花了一个下午才全部填平记录在这里。7.1 跨域问题前端5173访问后端3000被拦前端Vite开发服务器跑在5173端口后端Express跑在3000端口浏览器直接发起请求会报CORS错误Access to XMLHttpRequest at http://localhost:3000/api/... from origin http://localhost:5173 has been blocked by CORS policy最简单的解决方案是后端安装cors中间件npm install corsconst cors require(cors); app.use(cors());生产环境下不应该完全放开跨域我这是开发阶段图省事。正式部署时应该设置origin为前端域名白名单app.use(cors({ origin: [http://localhost:5173], methods: [GET, POST] }));7.2 中文传参的编码坑前端在URL上拼接中文参数比如from火车南站后端拿到的却是乱码。原因axios默认会将query参数进行URL编码而Express默认是UTF-8解码理论上不该乱码但实际项目中就是可能出问题。最稳妥的解法是在axios请求里显式指定参数序列化方式import axios from axios; const api axios.create({ baseURL: /api, paramsSerializer: params { return Object.keys(params) .map(key ${encodeURIComponent(key)}${encodeURIComponent(params[key])}) .join(); } });后端在get里接收query参数后再调用一次decodeURIComponent兜底const from decodeURIComponent(req.query.from || );这个组合能保证中文站名在前后端之间完整无损地传递。7.3 异步竞态搜索请求返回乱序用户在搜索框里输入火这个字后前端每敲一个字触发一次搜索请求。请求1发出后还没返回请求2又发出来了。由于网络延迟不确定请求2可能先返回请求1后返回最后页面展示的是请求1的旧结果。这就是典型的竞态问题。解决方案有几种我自己用的是AbortController加请求序号。let requestId 0; async function handleSearch(params) { const currentId requestId; const response await api.get(/route/search, { params }); if (currentId ! requestId) return; // 已经被更新的请求覆盖 routeStore.setResults(response.data.data); }另外在Vue组件的onUnmounted生命周期里可以调用abortController.abort()取消未完成的请求这样切换页面后请求不会继续干扰。7.4 地图异步初始化的顺序问题地图组件在页面挂载时创建map实例但如果此时搜索结果已经存在需要等高德或Mapbox的样式加载完成后再绘制路线线。这里要监听map的load事件map.value.on(load, () { if (routeStore.results.length) { drawAllRoutes(routeStore.results); } });负责Mapbox地图初始化的onMounted和负责绘制线路的watch不能同时在页面初始化时触发否则会在map尚未load完成时报错。我在在线路绘制函数里加了一层守卫if (!map.value || !map.value.isStyleLoaded()) { setTimeout(() drawAllRoutes(routes), 200); return; }这个等样式加载完成再绘制的机制也直接复用到后续添加Marker的场景。8. 从零启动到浏览器验证完整运行手册最后这部分我把整套系统跑起来的步骤整理成一份可以直接照做的手册包括前后端的启动顺序、环境变量配置和验证清单。8.1 目录结构速览public-transport-system/ ├── backend/ │ ├── data/ │ │ └── busData.json │ ├── server.js │ ├── package.json │ └── .npmrc ├── frontend/ │ ├── public/ │ ├── src/ │ │ ├── api/ │ │ ├── components/ │ │ ├── router/ │ │ ├── stores/ │ │ ├── views/ │ │ └── main.js │ └── package.json └── start.bat前后端完全分离互不依赖。后端只暴露接口前端只做展示。start.bat是我放在桌面的一键启动脚本双击就能同时拉起前后端。8.2 后端启动步骤cd backend npm install node server.js后端默认监听3000端口终端输出Server is running on http://localhost:3000说明启动成功。可以用浏览器直接访问接口验证curl http://localhost:3000/api/route/search?from火车站to人民广场返回JSON格式的路线数据说明接口正常。8.3 前端启动步骤cd frontend npm install npm run dev浏览器访问http://localhost:5173。这里需要提醒一下Vite默认只监听localhost如果部署到服务器上还要在vite.config.js里配一下server.host: true。8.4 一键启动脚本桌面上的.bat文件对应的热搜词里有一条建一个.bat文件在桌面运行nodejs打开服我在项目收尾时确实做了这件事。在项目根目录创建一个start.bat内容如下echo off start cmd /k cd /d %~dp0backend node server.js start cmd /k cd /d %~dp0frontend npm run dev echo 系统已启动请访问 http://localhost:5173 pause第一行打开一个新的命令行窗口运行后端第二行打开另一个窗口运行前端。把这份.bat文件发送到桌面以后双击一下就能把整个系统拉起来。由于两个服务是在独立窗口中运行的关掉窗口服务就停了也不会残留进程。8.5 上线前的验证清单我每次跑完整系统前都会过一遍这份清单防止低级错误影响演示检查项预期结果出错时的处理方法后端启动终端显示3000端口监听检查3000端口是否被占用netstat -ano | findstr 3000前端启动浏览器打开5173端口出现首页检查5173端口占用可能是内存不足导致的线路列表显示所有线路和站数检查busData.json格式是否合法站点搜索输入火能匹配火车站检查后端matchStation函数是否使用includes换乘查询从火车站到人民广场返回路线检查BFS的visited集合是否记录lineId地图绘制路线在地图上正确显示检查Mapbox token是否有效检查坐标顺序8.6 扩展思路这个系统还能往哪里挖做完核心功能后我留了两个扩展方向在TODO里。第一个是数据源接入。当前数据是手写JSON真实运营线路多、数据量大以后可以爬取公交公司的公开数据通过脚本自动生成busData.json。为保证数据新鲜脚本可以定时执行每次跑完自动构建一次公交车数据。第二个是实时车辆位置。这个能力需要数据源或定位上报如果能接入物联网设备上报经纬度后端就可以提供/api/vehicle/status接口前端在地图上动态更新Marker位置。这一步涉及WebSocket或者轮询是把项目从静态查询升级为动态监控的一道分水岭。我个人在实际开发中最大的体会是这类全栈项目真正难的从来不是某个单一技术而是数据在前后端之间流转时的边界问题。谁负责清洗参数、谁负责校验合法性、谁负责处理异常、谁负责兜底显示这些问题一开始就定好后面联调会顺畅很多。如果你也在做类似的系统建议从最小可行版本开始先把一条线路、两个站点的查询跑通再逐步加数据、加功能、加地图。这个节奏能让你在每一步都有明确的正反馈也更容易坚持下去。
