简介一套基于GraphHopper与Java SpringBoot构建的多途径点路径规划源码项目面向需要实现路径计算、途经点顺序优化等功能的Java开发者适用于物流配送、城市交通、户外导航等场景。项目借助GraphHopper图形处理引擎配合SpringBoot简化配置与部署流程可在多途经点场景下解算满足最短距离或最短时间等约束的候选路径。压缩包共23个文件约31.72MB以4个Java源文件为核心另有2个OSM街道地图数据、3个属性文件、1个JAR包以及Maven wrapper、Git忽略文件等工程辅助内容目录结构简练便于直接导入并定位关键模块。当前已有325人学习浏览。学习该资源可掌握GraphHopper与SpringBoot的集成方式理解地图数据、配置文件、路径计算及索引存储等模块之间的协作关系并基于现有骨架调整途经点策略扩展到实际路径规划业务中。1. 多途径点路径规划顺序不对算得再准也白搭做 Java SpringBoot 路径规划时很多人第一反应是把途经点按地址列表顺序一条条连起来。但实际跑过几轮真实数据就会发现这个顺序几乎永远不是最优解——配送路线、巡检点位、车辆调度里真正的耗时大头是先搞清楚“先去哪、后去哪”再计算“相邻两点间怎么走”。GraphHopper 是一个开源的 Java 路由引擎能基于 OSM 路网数据做最短路径、等时圈、逆地理编码而这份基于 GraphHopper 的 SpringBoot 多途径点路径规划设计源码解决了两个叠加问题途经点顺序怎么优化以及优化后整条路线怎么在路网上正确复现。适合正在做物流调度、外勤巡检、车辆路径规划相关后端开发的人直接拿来当脚手架。2. Java SpringBoot 工程结构GraphHopper 引擎选型与初始化方式2.1 为什么选 GraphHopper 而不是自研算法或在线 API自研最短路径算法不是不行而是代价太明显。你需要自己处理路网拓扑、道路单向限制、转弯cost、不同交通工具的禁行规则、地图匹配甚至还要维护一套足够细的路网数据。做巡检或配送系统时这些基础能力如果全部从零开始开发周期会拉得很长。在线 API 的问题是数据出域和请求配额。对内部系统来说把客户位置或车辆轨迹发到外部服务很多场景在合规和技术上都不好接受。GraphHopper 是纯 Java 实现的开源引擎加载 OSM 路网数据后全部在本地跑请求不出内网也不需要按次付费这个特性在项目里是硬加分项。GraphHopper 内置了 A*、双向 Dijkstra、ALT 等多种路由算法支持 foot、car、bike 等编码方式并且加载后的路网会生成一份只读快照多线程查询不会互相写坏数据。结合 SpringBoot 做接口层整体结构非常契合。2.2 工程目录与 Maven 核心依赖这份源码的目录结构不复杂核心模块就三层配置层、计算服务层、接口层。配置层负责读取路网文件路径、存储位置、编码方式计算服务层封装 GraphHopper 引擎实例接口层暴露 HTTP API。pom.xml 里关键依赖就三块不用堆一堆没用的包properties graphhopper.version保持与源码包内一致/graphhopper.version /properties dependencies dependency groupIdcom.graphhopper/groupId artifactIdgraphhopper-core/artifactId version${graphhopper.version}/version /dependency dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-test/artifactId scopetest/scope /dependency /dependencies注意 graphhopper-core 和 graphhopper-web 这两个模块的区别。web 模块自带一套完整的 HTTP 服务端但定制接口不方便塞进 SpringBoot 会感觉像在抢控制权。这里只用 core 模块把引擎当普通库注入到 Spring 容器里接口完全用 SpringMVC 自己控制。如果后续要用 isochrone等时圈或地图匹配功能再按需加 graphhopper-isochrone、graphhopper-map-matching 对应依赖不需要现在就全部引入。2.3 GraphHopper 引擎初始化与路网数据导入引擎初始化是整个项目里唯一一个“必须耐心等”的步骤。首次启动时GraphHopper 会读取.osm.pbf路网文件解析节点、边、道路属性构建存储索引这个过程根据路网大小可能持续几十秒到几分钟。初始化之后生成的索引会落在graph.location指定的目录里后续启动可直接复用不再重复解析。看这个初始化逻辑Configuration public class GraphHopperConfig { Bean public GraphHopper graphHopper() { GraphHopper hopper new GraphHopper(); hopper.setOSMFile(/data/osm/area.osm.pbf); hopper.setGraphHopperLocation(/data/gh-storage); hopper.setEncodedValueString(car_access, car_average_speed); hopper.setProfiles( new Profile(car).setVehicle(car).setWeighting(fastest) ); hopper.getRouterConfig().setMaxVisitedNodes(1_000_000); hopper.importOrLoad(); return hopper; } }参数含义逐条说清setOSMFile指定原始路网数据文件路径首次导入必须存在setGraphHopperLocation是索引文件的落盘目录这个目录一旦生成就不要手动删改setEncodedValueString声明需要写入图存储的属性car_access 表示该边是否允许汽车通行car_average_speed 表示通行速度这两个是路径计算的基础setProfiles里的 weighting 支持 fastest 和 shortest做配送路径通常选 fastest因为距离短的路线可能因为红绿灯和限速导致实际更慢importOrLoad()会判断存储目录里是否已有索引有就直接加载没有就构建所以重复启动不会重复解析。常见错误是路径写错时项目启动直接报错而超时时间和 OSM 解析进度都不够直观。我的习惯是先跑一次纯 Java 测试类单独初始化引擎复制一遍启动过程把日志里的loaded graph at ...和graph edge count这两行确认好再启动 SpringBoot 整体服务能省很多排查时间。2.4 Service 层封装与单实例复用GraphHopper 实例在 Spring 容器里应该是单例不要每次请求都 new 一个。引擎加载索引后整体占用内存较高多实例等于给自己制造 OOM 风险。Service 层只需要注入这个单例再封装出最基本的路线查询方法Service public class RouteService { private final GraphHopper graphHopper; public RouteService(GraphHopper graphHopper) { this.graphHopper graphHopper; } public GHResponse calculateRoute(ListGHPoint points) { GHRequest request new GHRequest(points); request.setProfile(car); request.setAlgorithm(AlgorithmOptions.DIJKSTRA_BI); return graphHopper.route(request); } }GHRequest 接收按顺序排列的坐标点列表这里的顺序非常关键之后做多途径点优化时所有优化结果都会从这一个方法入口进去。setProfile(car)必须和初始化时定义的 profile 名称一致写错会直接抛 ProfileNotFound 异常。DIJKSTRA_BI是双向 DijkstraGraphHopper 里默认的 fast 算法实际上是 A* 变体多途经点的局部路段计算用双向 Dijkstra 往往更稳不容易出现启发函数过估导致的意外绕路。3. 多途径点核心实现顺序求解与逐段路径拼接3.1 途经点数据结构与坐标预处理多途径点计算的第一步不是调算法而是清洗坐标数据。实际项目里拿到的坐标来源很杂可能是 Excel 里的经纬度、手机 GPS 上报的 WGS84 坐标甚至可能是手填的错误数据。起点写反、经纬度写反、坐标超出路网边界这些情况如果不在预处理阶段拦住后面计算出来的路径就是一条比直线更扭曲的无效路线。先定义一个干净的坐标点结构public class Waypoint { private String name; private double lat; private double lng; private boolean required; public GHPoint toGHPoint() { return new GHPoint(lat, lng); } }required 字段表示这个点是否必须经过。有些场景下某些点是软约束实在无法经过时可以跳过但绝大多数业务里所有点都是硬约束必须全部落在最终路径上。坐标校验的规则有三个纬度范围 -90 到 90经度范围 -180 到 180点与点之间距离不能太近小于 20 米的重复点直接合并所有点必须在路网数据覆盖的边界框内。第三点最容易漏假设你加载的是某个城市的路网却传入几百公里外的坐标GraphHopper 会把距离最近的路段当成匹配结果造成那种“起点明明在 A 城路径却从 B 城边缘开始”的诡异翻车。3.2 途经点顺序优化贪心初始化与 2-opt 迭代优化多途经点顺序问题本质上是 TSP旅行商问题的变体。途经点少于 8 个时直接暴力穷举所有排列选最小总距离是可行的一旦超过 10 个排列数指数级增长就不能再硬算了。常见做法是贪心算法先算一个初解再用 2-opt 局部搜索迭代收敛。我把这一整块逻辑封装成一个独立的顺序优化器public class RouteOptimizer { public ListWaypoint optimize(ListWaypoint waypoints) { ListWaypoint route new ArrayList(waypoints); route nearestNeighborInit(route); route twoOptImprove(route); return route; } private ListWaypoint nearestNeighborInit(ListWaypoint points) { ListWaypoint result new ArrayList(); SetInteger visited new HashSet(); int current 0; result.add(points.get(current)); visited.add(current); while (result.size() points.size()) { int next -1; double bestDist Double.MAX_VALUE; for (int i 0; i points.size(); i) { if (visited.contains(i)) continue; double d haversineDistance( points.get(current).getLat(), points.get(current).getLng(), points.get(i).getLat(), points.get(i).getLng()); if (d bestDist) { bestDist d; next i; } } result.add(points.get(next)); visited.add(next); current next; } return result; } private ListWaypoint twoOptImprove(ListWaypoint route) { boolean improved true; while (improved) { improved false; for (int i 1; i route.size() - 2; i) { for (int j i 1; j route.size() - 1; j) { double before segmentDistance(route, i - 1, i) segmentDistance(route, j, j 1); double after segmentDistance(route, i - 1, j) segmentDistance(route, i, j 1); if (after before - 1e-6) { reverseSegment(route, i, j); improved true; } } } } return route; } }这个优化器里有两个关键点。nearestNeighborInit是贪心最近邻初始化从第 0 个点开始每一步选择离当前点最近的未访问点加入路线复杂度从阶乘级降到了平方级能在 1 秒内生成一个不算差的初始解。twoOptImprove是核心优化步骤它的原理是选定路径中两个不相邻的边如果交换这两条边的连接方式使局部路径总长更短就把这两段之间的子路径反向翻转反复迭代直到无法改进。这里用 haversineDistance 计算的是球面直线距离而不是路网距离。原因很简单顺序优化的每个候选方案都要评估距离如果每评估一次都调 GraphHopper 算一遍完整路网路径查询次数会爆炸性能完全不现实。直线距离做初筛已经足够分出明显的优劣顺序。真正的路网校验只用在最终选定顺序后逐段调用 GraphHopper 拼接完整路径。3.3 按优化顺序拼接完整路网路径顺序确定后就要把相邻途经点两两配对逐段调用 GraphHopper 做路径计算再拼接成整条路线。拼接分段路径的核心诉求有两个保证每一段都走合法路网路径以及保证整条路径的几何表达连续。这里有一个容易忽略的技术细节GraphHopper 的分段路径结果里第一段的终点恰好是第二段的起点这个共享点会重复出现拼接时需要去重。如果不去重前端绘制轨迹时会看到某个途经点处出现一个不正常的“小分叉”。public GeoJsonRoute buildOptimizedRoute(ListWaypoint optimizedPoints) { Listdouble[] fullPath new ArrayList(); double totalDistance 0; long totalTime 0; for (int i 0; i optimizedPoints.size() - 1; i) { GHPoint from optimizedPoints.get(i).toGHPoint(); GHPoint to optimizedPoints.get(i 1).toGHPoint(); GHRequest request new GHRequest(from, to); request.setProfile(car); request.setAlgorithm(AlgorithmOptions.DIJKSTRA_BI); GHResponse response graphHopper.route(request); if (response.hasErrors()) { throw new IllegalStateException(路径计算失败: response.getErrors()); } ResponsePath path response.getBest(); PointList points path.getPoints(); for (int j (i 0 ? 0 : 1); j points.size(); j) { fullPath.add(new double[]{points.getLat(j), points.getLng(j)}); } totalDistance path.getDistance(); totalTime path.getTime(); } return buildRouteResult(fullPath, totalDistance, totalTime); }分段计算时for (int j (i 0 ? 0 : 1); j points.size(); j)这个细节决定了拼接质量。第一段路径从头取到尾后续每一段都从索引 1 开始目的是跳过上一段的最后一个点避免同一坐标重复出现在轨迹数组里。Path.getDistance() 返回的是该段路的真实路网行驶距离单位是米getTime() 返回预估耗时单位是毫秒。累计到 totalDistance 和 totalTime最后给前端返回一个完整的路径结果。3.4 响应结构与前端联动后端接口返回的 JSON 结构建议固定成下面这种格式前端拿到的数据足够完整又不冗余{ code: 0, data: { distanceMeters: 58362.4, timeMillis: 2430000, waypointOrder: [3, 0, 2, 1], path: [ [39.9115, 116.4521], [39.9120, 116.4528] ] } }waypointOrder 是原始途经点列表重新排序后的下标数组前端可以根据这个数组重新标注途经点编号在页面上很直观地看到优化前后的顺序差异。path 是轨迹坐标点数组可以直接喂给地图 SDK 画线。这一层设计还有一个小优化空间如果整条路线只有 2 到 5 个途经点可以不走贪心算法直接暴力枚举全排列取 GraphHopper 真实路网距离最小的一组。点少时真实路网距离和直线距离的排序偶尔不一致暴力枚举能拿到更精确的最优。我是用分支判断实现两种计算路径自动切换代码不复杂但很实用。4. 多途径点落地避坑绕路、内存、骑行模式与并发延迟4.1 坐标在路网边缘时出现的绕路和穿湖现象第一类常见翻车是某个途经点位于路网边界附近计算出来的路径直接出现长距离绕路甚至“横穿水面”的诡异线段。原因不在 GraphHopper 的算法本身而在于坐标匹配逻辑。GraphHopper 查找最近边时会基于空间索引找物理距离最近的边如果那个点正好落在路网裁剪边界外侧而距离最近的一条路是远处某条长路路径就会从那个匹配点硬拉一条长直线过去。解决方法是设置最大匹配距离超过阈值直接报错而不是静默匹配Snap conflict resolution doesnt require extra code, but the threshold check does. double maxSnapDistance 500; if (snap.distance maxSnapDistance) { throw new IllegalArgumentException(坐标点 wp.getName() 距离路网过远); }我一般把阈值设为 300 到 500 米。超过这个范围说明输入坐标可能本身有问题要么是经纬度写反要么是坐标落到了未覆盖的区域。提前暴露错误比中途生成一条离谱路径要好得多。4.2 启动时的内存与磁盘异常GraphHopper 导入较大路网时内存占用和磁盘占用都可能突然跳高尤其是用默认配置跑整个省份级别的数据16G 内存的机器会直接卡死。原因是 graph.location 目录里会生成大量索引文件同时 import 阶段需要大量堆内存做节点排序和边压缩。OSM 文件本身只有几百 MB构建后的索引文件可能膨胀到几个 GB。有些人拿到源码后直接启动日志停在同一行十几分钟以为程序死锁了。处理方式是在启动脚本里显式设置 JVM 堆内存参数并控制路网数据范围。如果你只需要某个城市内的路径规划就在导入前用 OSM 处理工具把数据裁剪到边界框内不要导入整个省或整个国家的数据。源码里默认配置我一般会调整成这样-Xms4g -Xmx8g如果数据量确实大机器内存又有限就选择减少编码器数量。只做汽车路径规划时不要同时初始化 foot 和 bike 编码器每个编码器都会额外占用内存和磁盘空间。这个用不到的功能就别开资源省得很实在。4.3 骑行模式比想象中更容易绕路项目里如果同时做了骑行路径规划很容易在测试阶段发现骑行结果明显绕路或干脆无法连通。同一对起终点驾车 5 公里骑行却给出了 14 公里的路径。原因是骑行模式下路网过滤器更严格。自行车在 OSM 路网里对部分道路类型不可通行天桥、隧道、高速路都进不去而数据源里如果自行车道标注不完善引擎会倾向性地选择绕大圈走可通行道路。还有一个让新手容易懵的点是骑行配置里默认禁用了部分步行骑行共用道导致结果看起来比预想的绕。遇到这个情况我一般会先检查 profile 名称是否写对GraphHopper 里 bike、mtb、racingbike 三种骑行模式用的道路过滤规则不同racingbike 对铺装路面要求更高。然后是导入时基础编码器必须包含 bike_access 和 bike_average_speed如果只初始化了 car_access骑行路径引擎能跑但在某些点上会生成非常奇怪的降级行为。数据源覆盖不完整时骑行路径体验差不是引擎问题需要先从数据源本身排查。4.4 高并发请求下的偶发延迟与 GC 停顿接口在压测或真实上线后可能会出现偶发的高延迟单看某一次请求又找不到明显的逻辑问题。这不是 GraphHopper 查询本身不够快而是引擎持有的大内存数据结构在高并发下触发了 GC 停顿。路网索引是只读的但节点对象和边对象数量巨大GC 时每次全堆扫描都很耗时。常规处理方式有三个。第一启动完成后先做预热发几条覆盖不同区域的路由请求让 JIT 编译热点代码同时触发首次数据加载。第二控制查询接口的并发量配合缓存做结果复用相同起终点组合的请求直接从缓存返回。第三把顺序优化计算和 GraphHopper 路径查询分离到不同线程池避免计算密集型的顺序优化阻塞路由查询。private final ExecutorService routePool Executors.newFixedThreadPool(8);线程数量和 CPU 核数保持一致不要开太多。GraphHopper 单实例并发查询本身是线程安全的但线程多了反而会因为上下文切换和内存带宽限制变慢8 到 16 个业务线程通常就是最优区间。4.5 路径结果里的掉头与折返路径计算完成后仔细查看轨迹会发现某个途经点附近出现了一次明显的掉头或折返前后两段路方向相反像是司机开过头再倒回来。这个问题从算法角度看不影响可达性但业务层面很不好接受。出现掉头通常是因为 GraphHopper 的算法允许 U-turn且 U-turn 的转弯成本设置得偏低。最常见原因是途经点匹配到了一条主干道中间的某条边算法为了从这个点顺路接上下一段路径做出了绕行返折比从前方路口掉头更“近”。优化方式是把 U-turn 成本调高同时给途经点指定期望方向request.setHeadings(List.of(90.0, 180.0, 270.0, 0.0)); request.setHeadTolerance(90.0);headings 数组对应每个途经点的期望朝向角0 表示向北90 向东180 向南270 向西。如果业务里不清楚每个点的朝向就不建议强行设置因为错误的朝向角会导致匹配点偏移更严重。最常见有效的处理是只用 U-turn 成本调节hopper.getRouterConfig().setUTurnCosts(60);这个参数的单位和 weighting 方案有关fastest 下每个 U-turn 相当于增加若干秒或等效延迟。调整到 60 之后多数不必要的掉头都会被代价惩罚掉终点处正常调头不受影响。5. 进阶验证用三种距离对比判断顺序优化是否真的生效很多人做完多途经点优化后只看前端轨迹“好像更顺了”但“更顺”没有量化依据。我建议每次改完逻辑都跑一遍三距离对比脚本用数字说服自己优化器确实在干活。三种距离分别是纯直线总距离按输入顺序经过所有点的路网总距离优化顺序后的路网总距离。对比逻辑很简单优化前的路网距离除以优化后的路网距离得到一个优化系数大于 1 说明优化有效数值越大越明显。optimized 58362.4 original 74215.1 straight_line 38420.0 ratio original / optimized print(f优化系数: {ratio:.2f}) print(f优化节省: {original - optimized:.1f} 米) print(f直线距离占比: {optimized / straight_line:.2f})这个脚本跑出来的数据能同时验证两件事。优化系数如果小于 1.05说明这组途经点的原始顺序已经比较好了2-opt 没有找到明显的更优排列这是正常的但如果多组数据都小于 1.05就要回头检查贪心初始化是不是出了问题比如起点固定逻辑写死导致初解质量太差。直线距离占比反映的是路网曲折度一般在 1.3 到 2.5 之间算正常高于 3 则说明数据中可能有跨区域长距离绕路需要回到数据检查步骤。还有一个进阶验证值得做把优化器生成的顺序和原始顺序分别请求完整路由对比两段的每段距离明细。因为优化器用的是直线距离排序少数情况下会出现“路网实际距离更短但直线距离更长”的相邻点替换暴力枚举点数少时可以补上这个精确校验。我第一次跑对比脚本时发现某组 12 个点的数据优化系数只有 1.03当时以为优化器有 bug。后来逐段检查才发现这组点本身排列已经接近最优说明优化器没有错误地破坏已有良好顺序。从那以后我每次拿到新路网或新数据集都会强制先跑一遍这组三距离对比再决定是否需要继续调参而不是依赖肉眼判断。这套方法配合这份源码用起来很顺手希望帮到你。本文还有配套的精品资源点击获取