基于 Neo4j 与 A* 的 OpenStreetMap 轻量路网路由服务

简介：这份面向Java开发者与图数据库学习者的Neo4jOSM项目，围绕Neo4j图数据库与OpenStreetMap开放地图数据，演示如何搭建一个轻量级路线规划服务。它适合想理解空间路网建模、OSM数据导入、Cypher最短路径查询及Java驱动调用的读者，也可作为物流导航、位置服务类应用的入门参考，技能层级偏向入门到中级。压缩包共35个文件，约314KB，以22个Java源码为主体，配合3个OSM示例数据、2个properties配置、2个Markdown说明以及Gradle Wrapper等构建文件，覆盖源码、测试、数据与构建配置。已有171人学习，说明其在小体量图数据库路由示例中具有一定参考价值。读者可据此梳理从OSM路网提取、节点与关系映射，到图模型构建、路线查询接口设计的完整链路，并借鉴项目结构组织、数据预处理方式与最小可运行服务的实现思路，体会图数据库处理空间关系的优势。

1. Neo4jOSM 到底在做什么：一张图把 OpenStreetMap 变成可查询的路网

上个月有人问我，手上只有一份几百兆的 OpenStreetMap 离线数据包，机器上又不想装重型路径规划引擎，能不能用 Java 写一个能返回两点之间路线的路由服务。Neo4jOSM 就是冲着这个场景来的：它把 OSM 的 node / way 关系翻译成 Neo4j 的节点和关系，起一个轻量 HTTP 服务，外面传经纬度进来，里面用图查询或者内存里的 A* 算出一条路径返回。你要做的二次开发，大概率是改权重、加通行限制、或者把单机改成能扛并发的样子。

它适合三类人：想跳过路网拓扑和空间索引这些前期工作，直接验证路线规划想法的人；想拿 OSM 数据练一遍图数据库建模和批量写入的人；以及手上有一个小范围城市数据、只需要几万到几百万条边的轻量场景。不适合全国级路网、不适合需要实时交通流的生产调度，这一点最好先接受，后面所有设计都是围绕“简单”做取舍的。

2. 技术栈与目录结构：Java 侧的四层拆分和 Neo4j 里的图模型

动手之前先把骨架想清楚。这个项目的依赖面其实很窄：一个 OSM 的 PBF 解析器负责读地图，一个 Neo4j 的 Java Driver 负责写图和查图，一个轻量 Web 框架负责暴露接口，剩下就是自己写的几何计算和搜索算法。常见的做法是用 osmosis 或者 osm4j 的 pbf 模块读数据，用 Javalin 或 Spark Java 起服务，把 Spring Boot 留给真正需要依赖注入和一堆 starter 的场合——路由服务的接口就三五个，没必要背那么重的容器。

2.1 依赖清单与选型理由

Maven 里真正关键的就三个坐标，其余都是日志和测试。下面这份是骨架，版本号我用占位符，具体锁到哪个版本以你本地私服或者中央仓库能拉到的为准，不要照抄字符串。

<properties> <maven.compiler.release>17</maven.compiler.release> </properties> <dependencies> <!-- OSM PBF 流式解析：一千万节点也不会一次性进堆 --> <dependency> <groupId>org.openstreetmap.osmosis</groupId> <artifactId>osmosis-pbf</artifactId> <version>${osmosis.version}</version> </dependency> <!-- 官方驱动，写图和查图都靠它 --> <dependency> <groupId>org.neo4j.driver</groupId> <artifactId>neo4j-java-driver</artifactId> <version>${neo4j.driver.version}</version> </dependency> <!-- 服务层：路由和 JSON 序列化 --> <dependency> <groupId>io.javalin</groupId> <artifactId>javalin</artifactId> <version>${javalin.version}</version> </dependency> <dependency> <groupId>com.fasterxml.jackson.core</groupId> <artifactId>jackson-databind</artifactId> <version>${jackson.version}</version> </dependency> </dependencies>

选 osmosis 而不是自己写 PBF 解码，是因为 PBF 是 protobuf 的块结构加 zlib 压缩，块边界、dense nodes 的 delta 编码这些细节自己处理容易翻车，而且跟路由逻辑完全无关。选官方 Driver 而不是 Spring Data Neo4j，是因为这个项目里只有两种查询：批量灌边和按 id 取邻居，用不到对象图映射那一层，多一层抽象反而看不清 Cypher 到底发了什么。Javalin 这类框架的好处是启动几百毫秒，改完代码重启不心疼。

2.2 目录结构：四层各管一段链路

我把代码分成 importer、routing、api、util 四层，这一层的划分不是审美，是为了让“灌数据”和“跑查询”可以分开部署——导入通常是一次性的重活，查询是长期跑着的轻活，混在一个进程里很容易在导入时把查询服务拖死。

neo4josm/ ├── pom.xml ├── src/main/java/com/example/neo4josm/ │ ├── App.java # 入口：装配配置 + 启动 HTTP │ ├── config/ │ │ └── AppConfig.java # 从 properties/env 读连接串和参数 │ ├── importer/ │ │ ├── PbfScanner.java # 第一遍：收集 way 引用的 nodeId │ │ ├── EdgeExtractor.java # 第二遍：把 way 展开成有向边 │ │ └── GraphWriter.java # 批量 UNWIND 写 Neo4j │ ├── routing/ │ │ ├── GraphLoader.java # 把邻接表预热进内存 │ │ ├── AStarRouter.java # 带启发函数的搜索 │ │ └── NearestNodeFinder.java # 经纬度吸附到最近路网节点 │ ├── api/ │ │ ├── RouteController.java # /route 与 /health │ │ └── dto/ # 请求响应体 │ └── util/ │ └── GeoMath.java # haversine、速度表 ├── src/main/resources/ │ ├── application.properties │ └── cypher/ │ ├── schema.cypher # 约束与索引 │ └── batch-edge.cypher # 批量写入语句 └── scripts/ ├── import.sh └── smoke.sh # 跑几条已知起终点的冒烟用例

importer和routing之间刻意不共享类，importer只负责产出边表，routing只认边表和图里的属性。这样你想把内存版 A* 换成 Cypher 版、或者反过来，改动范围是可控的。scripts/smoke.sh这个文件别省，它比任何文档都能告诉你“今天这次改动是不是把路网弄断了”。

2.3 Neo4j 侧的图模型：为什么节点和关系都要带属性

图模型决定了后面所有 Cypher 的写法。这里用的是最直白的一种：一个路网节点就是一个Node标签的图节点，带osmId、lat、lon和一个location点类型属性；两个节点之间的可通行路段是一条ROUTE关系，方向就是通行方向，属性带distance（米）、wayId、name、highway。

// 唯一约束是导入速度的命门，没有它 MERGE 会退化成全图扫描 CREATE CONSTRAINT node_osm_id IF NOT EXISTS FOR (n:Node) REQUIRE n.osmId IS UNIQUE; // 点索引让“找最近节点”不用扫全表（老版本没有这个语法就靠网格分桶） CREATE POINT INDEX node_location IF NOT EXISTS FOR (n:Node) ON (n.location);

参数说明：osmId是 OSM 原始节点 id，用它做唯一键才能保证 PBF 数据更新后可以增量重导；location存的是point({srid:4326, latitude:..., longitude:...})生成的几何点，Cypher 里可以直接用point.distance()算球面距离。注意distance属性单位统一成米，别一会儿米一会儿公里，血泪经验，混单位是这类项目最常见的隐蔽 bug。

之所以把边做成有向而不是无向，是因为 OSM 的oneway=yes单行道太常见，如果建无向边，查询时还得额外判断标签，反而更慢。代价是双向道路要写两条关系，边数大约翻倍，对中小范围的城市数据完全可以接受。

3. 数据导入链路：从 PBF 到边表的抽取与批量入库

导入是这个项目里最容易劝退人的一段。很多人第一次跑，要么内存直接爆，要么跑了四十分钟发现边数只有预期的一半。原因基本都是把“读 OSM”和“写图库”揉成了一趟：一边流式读 PBF，一边发 Cypher，网络往返把时间全吃掉了，而且中途失败没法续传。

3.1 两遍扫描：先收集引用，再展开边

PBF 里 way 只存节点 id 的引用，坐标在 node 记录里，而两者在文件里的顺序不保证先 node 后 way。所以常见做法是扫两遍：第一遍只收集“被可通行 way 引用到的 nodeId 集合”，第二遍读 node 时只保留这个集合里的坐标，最后按 way 的内部顺序两两成边。

public final class PbfScanner { // 只保留机动车可通行的道路类型，人行道、台阶按你的场景增删 private static final Set<String> ROUTABLE = Set.of( "motorway", "trunk", "primary", "secondary", "tertiary", "residential", "service", "unclassified"); // 第一遍：拿到所有“值得保留坐标”的节点 id public Set<Long> collectReferencedNodes(File pbf) throws Exception { Set<Long> referenced = new HashSet<>(1 << 22); try (OsmosisReader reader = new OsmosisReader(new FileInputStream(pbf))) { reader.setSink(new SinkAdapter() { @Override public void way(WayContainer container) { Way way = container.getEntity(); if (!isRoutable(way)) return; for (WayNode wn : way.getWayNodes()) { referenced.add(wn.getNodeId()); } } }); reader.run(); // 阻塞直到文件读完 } return referenced; } private boolean isRoutable(Way way) { Tag highway = way.getTagByName("highway"); if (highway == null || !ROUTABLE.contains(highway.getValue())) return false; // 明确标注不可通行或施工中的直接踢掉 return !"no".equals(way.getTagValue("access")); } }

逻辑说明：SinkAdapter是 osmosis 提供的空实现适配器，你只覆写关心的回调，其余实体（relation、bound）自动忽略，省得写一堆空方法。referenced用HashSet<Long>而不是Set<Long>的流式结构，是因为第二遍要用contains做高频判断，装箱开销换查询速度在这个量级下是值的。参数上1 << 22只是初始容量，四百万起步，避免反复扩容；真实数据里被引用的节点数大概是总节点数的 15% 到 30%，具体看你裁的多大地图。

第二遍把坐标补上，然后按 way 里节点的先后顺序成边，同时算距离和单行方向。

public List<Edge> extractEdges(File pbf, Set<Long> wanted) throws Exception { Map<Long, double[]> coords = new HashMap<>(wanted.size() * 2); List<Edge> edges = new ArrayList<>(); try (OsmosisReader reader = new OsmosisReader(new FileInputStream(pbf))) { reader.setSink(new SinkAdapter() { @Override public void node(NodeContainer container) { Node n = container.getEntity(); if (wanted.contains(n.getId())) { coords.put(n.getId(), new double[]{n.getLatitude(), n.getLongitude()}); } } @Override public void way(WayContainer container) { Way way = container.getEntity(); if (!isRoutable(way)) return; boolean oneway = "yes".equals(way.getTagValue("oneway")) || "true".equals(way.getTagValue("oneway")) || "motorway".equals(way.getTagValue("highway")); List<WayNode> wns = way.getWayNodes(); for (int i = 0; i + 1 < wns.size(); i++) { long from = wns.get(i).getNodeId(); long to = wns.get(i + 1).getNodeId(); double[] a = coords.get(from), b = coords.get(to); if (a == null || b == null) continue; // 跨边界缺失，跳过而不是报错 double meters = GeoMath.haversine(a[0], a[1], b[0], b[1]); edges.add(new Edge(from, to, way.getId(), meters, way.getTagValue("name"), way.getTagValue("highway"))); if (!oneway) { // 双向道路补一条反向边 edges.add(new Edge(to, from, way.getId(), meters, way.getTagValue("name"), way.getTagValue("highway"))); } } } }); reader.run(); } return edges; }

这段有两个容易写错的地方。一是coords.get()返回 null 时要跳过而不是抛异常，裁剪地图时必然有 way 指向边界外的节点，抛异常会让整趟导入前功尽弃。二是单行判断，除了oneway=yes，高速公路默认单行、junction=roundabout环岛也是单向，漏掉这些规则会让路线出现“逆行”，看着能走，实际不可通行。

3.2 批量写入：UNWIND 加事务分批，比逐条 MERGE 快一个量级

边抽出来之后是几十万到几百万条记录，绝不能用 Driver 逐条session.run。常见做法是按 5000 到 10000 条一批，用UNWIND $rows一次提交，每批一个事务，失败重试。

// batch-edge.cypher UNWIND $rows AS row MATCH (a:Node {osmId: row.from}) MATCH (b:Node {osmId: row.to}) CREATE (a)-[r:ROUTE {wayId: row.wayId}]->(b) SET r.distance = row.distance, r.name = row.name, r.highway = row.highway

这里用CREATE而不是MERGE，前提是边表在 Java 侧已经去重、导入脚本跑之前会先清空ROUTE关系。MERGE在关系上带属性时，Cypher 需要先按模式匹配再决定是否创建，几百万次匹配的开销很难看；如果你确实需要幂等重跑，那就给wayId建索引，或者干脆用MERGE (a)-[r:ROUTE {wayId: row.wayId}]->(b)之前先MATCH掉已存在的。

public void write(List<Edge> edges, int batchSize) { try (Driver driver = GraphDatabase.driver(URI, AuthTokens.basic(USER, PASS))) { driver.verifyConnectivity(); String cypher = Files.readString(Path.of("src/main/resources/cypher/batch-edge.cypher")); for (int i = 0; i < edges.size(); i += batchSize) { List<Map<String, Object>> rows = edges.subList(i, Math.min(i + batchSize, edges.size())) .stream() .map(e -> Map.<String, Object>of( "from", e.from(), "to", e.to(), "wayId", e.wayId(), "distance", e.meters(), "name", e.name() == null ? "" : e.name(), "highway", e.highway())) .toList(); // executeWrite 自带对可重试异常的退避重试，注意语句本身要幂等 driver.session().executeWrite(tx -> { tx.run(cypher, Map.of("rows", rows)).consume(); return null; }); log.info("written {}/{}", Math.min(i + batchSize, edges.size()), edges.size()); } } }

参数解释：batchSize我一般从 5000 起步，Neo4j 堆给到 4G 以上可以试 10000，再大事务日志压力会上来。Map.of不接受 null，所以name要做空串兜底，这种小坑第一次写必踩。executeWrite的重试语义要求你的语句可重入，如果用的是CREATE，重试可能产生重复边，所以要么保证写入前清空，要么改用带唯一键的MERGE。

导入完成后跑一条校验，确认边数和孤立节点数在合理范围：

MATCH ()-[r:ROUTE]->() RETURN count(r) AS edges; MATCH (n:Node) WHERE NOT (n)-[:ROUTE]-() RETURN count(n) AS isolated;

edges的数量级应该和你裁剪范围内道路总长度对得上，一条 10 公里的主干道大约几千条边。isolated如果是几万，说明坐标缺失或者 way 类型过滤太狠，路网被切碎了，这时候先别急着调路由算法，问题在数据侧。

4. 路由核心实现：A* 搜索、最近点吸附与 HTTP 接口

数据进图之后，剩下三件事：把用户传来的经纬度吸附到路网节点，算出一条路径，把路径转成 GeoJSON 返回。这个项目名字里带“简单”，意思就是它没打算做 contraction hierarchies 那种预处理，直接在图上搜。中小范围城市数据，A* 加一个像样的启发函数足够用了。

4.1 最近节点吸附：别写成全表扫描

用户点在地图上任意位置，最近的可能是小区内部路，也可能是高架桥下的辅路。最直接的做法是按球面距离取最近节点。

// 先按点索引圈定候选，再排序，避免 AllNodesScan MATCH (n:Node) WHERE point.distance(n.location, point({srid: 4326, latitude: $lat, longitude: $lon})) < $radius RETURN n.osmId AS osmId, n.lat AS lat, n.lon AS lon ORDER BY point.distance(n.location, point({srid: 4326, latitude: $lat, longitude: $lon})) ASC LIMIT 1

参数说明：$radius从 200 米起步，没命中就倍增到 800、3200，别一上来给 50000 米，那样索引基本失效。point()里的srid: 4326是 WGS84 经纬度坐标系，和 GPS 输出一致；如果你导入时忘了给location赋值，这条查询会返回空，报错信息还很不直观，所以导入后一定要抽样验证location不为 null。

老版本没有点索引的话，退化方案是建一个网格：把地图按 0.01 度切格子，节点属性里存gridX/gridY，查询时先算目标格子和周围 8 个格子，只在这些格子里找。这个土办法在百万级节点上依然好用，别嫌它不优雅。

4.2 A* 的启发函数：可采纳才有最优解

内存版搜索是这个项目的性能主力。启动时把ROUTE关系一次性拉进内存建邻接表，几十万条边大概占几百兆，比每次查询都走 Cypher 快两个数量级。

public List<Long> route(long start, long goal) { Map<Long, Double> gScore = new HashMap<>(); Map<Long, Long> cameFrom = new HashMap<>(); PriorityQueue<long[]> open = new PriorityQueue<>(Comparator.comparingDouble(a -> Double.longBitsToDouble(a[1]))); gScore.put(start, 0.0); open.add(new long[]{start, Double.doubleToLongBits(heuristic(start, goal))}); while (!open.isEmpty()) { long current = open.poll()[0]; if (current == goal) return rebuild(cameFrom, goal); for (Edge e : adj.getOrDefault(current, List.of())) { double tentative = gScore.get(current) + e.costSeconds(); if (tentative < gScore.getOrDefault(e.to(), Double.MAX_VALUE)) { cameFrom.put(e.to(), current); gScore.put(e.to(), tentative); // f = g + h，h 用直线距离除以最大速度，保证不高估 double f = tentative + heuristic(e.to(), goal); open.add(new long[]{e.to(), Double.doubleToLongBits(f)}); } } } return List.of(); // 不连通 } private double heuristic(long a, long b) { double meters = GeoMath.haversine(lat(a), lon(a), lat(b), lon(b)); return meters / MAX_SPEED_MPS; // 全网最高限速，取 130km/h 换算 }

逻辑说明：heuristic必须“可采纳”，也就是永远不高估真实代价，否则 A* 会返回次优路径，而且错得很隐蔽——你会觉得路线“有点绕”，但找不到原因。用全局最大速度归一化是最稳的写法。costSeconds()是边权，如果你用距离当权重，启发函数就换成纯距离，两者不能混用，混用是新手最典型的错误。

还有一个细节：PriorityQueue<long[]>里塞了重复节点（同一个点可能被多次入队），出队时要判断是否已经处理过，否则复杂度会退化。简单做法是加一个closed集合，出队时if (!closed.add(current)) continue;。

4.3 HTTP 接口与 GeoJSON 输出

接口层尽量薄，两个端点：/route和/health。前者接收起终点经纬度，返回坐标数组；后者给探活和压测用。

public class RouteController { private final NearestNodeFinder finder; private final AStarRouter router; public void register(Javalin app) { app.get("/route", ctx -> { double fromLat = Double.parseDouble(ctx.queryParam("fromLat")); double fromLon = Double.parseDouble(ctx.queryParam("fromLon")); double toLat = Double.parseDouble(ctx.queryParam("toLat")); double toLon = Double.parseDouble(ctx.queryParam("toLon")); long start = finder.nearest(fromLat, fromLon); // 吸附 long goal = finder.nearest(toLat, toLon); List<Long> path = router.route(start, goal); if (path.isEmpty()) { ctx.status(404).json(Map.of("error", "no path")); return; } ctx.json(Map.of( "type", "LineString", "coordinates", path.stream().map(router::coordOf).toList(), "nodes", path.size())); }); app.get("/health", ctx -> ctx.json(Map.of("status", "up", "nodes", router.nodeCount()))); } }

参数解释：坐标顺序在 GeoJSON 里是[lon, lat]，而大多数 Java 代码习惯lat, lon，这个顺序错了地图上会显示到南极洲附近，调试半天以为算法崩了。返回值里带nodes数量便于快速判断路径长度是否异常——一条 20 公里的路线返回 3 个节点，那基本是吸附到了两个隔断的路网。

服务启动时把图加载好，用App.java装配：

public static void main(String[] args) { AppConfig cfg = AppConfig.load(); // 读 properties 和环境变量 GraphLoader loader = new GraphLoader(cfg); loader.load(); // 一次性把邻接表灌进内存 Javalin app = Javalin.create(config -> config.http.defaultContentType = "application/json"); new RouteController(loader.finder(), loader.router()).register(app); app.start(cfg.port()); }

这个装配顺序有讲究：图加载必须落在app.start之前，否则第一条请求打进来时邻接表还是空的，返回 404，看着像“没有路径”，其实根本没数据。加载时长跟着边数走，百万边大约十几秒，启动慢一点但换来的是请求全部走内存。

5. 上线前的避坑与排查：五条血泪记录

下面这些坑，基本是照着“先能跑通、再谈性能”的顺序踩过来的。写在这里，是为了你在导入卡住或者查询报空的时候，能少走一遍我走过的路。

5.1 导入期：内存和重复边的两个大坑

现象：导入跑到 60% 左右进程被系统杀掉，日志里只有 GC 记录，没有任何业务异常。

原因：第二遍扫描时把整份地图的坐标都塞进了HashMap<Long, Double[]>。一个Double[]对象加上HashMap的节点开销，一千万节点轻松吃掉几个 G，堆再怎么调都不够。

解决：严格只缓存第一遍收集到的wanted集合里的坐标，并且HashMap初始容量按wanted.size() / 0.75 + 1给足，减少扩容时的对象抖动。数据量再大就退化成中间文件：第一遍写出nodeId,lat,lon的 CSV，第二遍用Map上限做 LRU，或者直接排序合并。

现象：重跑一次导入后边数翻倍，路由返回的路径开始出现奇怪的环。

原因：脚本没清空旧数据就重复执行，CREATE语句不检查已存在的关系，两条平行边都进了图。

解决：导入前统一执行一句清理并等待完成，再开始写。删关系是大事务，小内存实例上建议分批删，别一条语句删几千万条。

MATCH ()-[r:ROUTE]->() CALL { WITH r DELETE r } IN TRANSACTIONS OF 10000 ROWS; MATCH (n:Node) WHERE NOT (n)-[:ROUTE]-() DELETE n;

现象：导入完成，但地图上大片区域查不到路径，尤其是主干道交叉口附近。

原因：单行判断只看了oneway=yes，漏掉了oneway=-1（反向单行）、junction=roundabout和高速匝道，导致某条边方向反了，路网在关键节点被切断。

解决：把单行判定抽成一个方法，按highway、junction、oneway三个标签组合判断，oneway=-1时反向建边。导入后跑一遍连通性检查，从市中心一个节点出发能到达的节点数应该占绝大多数。

5.2 查询期：索引失效和参数类型的坑

现象：/route请求偶发超时，EXPLAIN一看是AllNodesScan，几百万节点全扫一遍。

原因：约束没有真正建上。常见的是属性名大小写不一致（代码里写osmId，建约束时写了osm_id），或者建约束的语句在当时那个库上因为数据重复直接失败了，脚本没检查返回值就继续往下跑。

解决：上线前固定跑一次SHOW CONSTRAINTS和SHOW INDEXES，人工确认名字和属性对得上。批量写入的代码里，用MATCH (a:Node {osmId: ...})走的是唯一索引，速度应该和点查一个量级，如果你发现导入慢得离谱，先怀疑索引没生效，而不是怀疑 driver。

现象：本地跑得好好的，部署后/route返回 500，日志里说参数类型不对。

原因：前端把经纬度当字符串传了，Double.parseDouble之外的地方（比如直接拼进 Cypher 的参数）类型变成了String，point.distance直接抛异常。

解决：在 Controller 层做一次显式收敛，queryParam拿到之后立刻Double.parseDouble，异常统一转 400 并带上字段名。别指望调用方守规矩，接口边界上做类型清洗的成本最低。

6. 二次开发：把权重、禁转和缓存接进现有骨架

这个项目的骨架留了三个明确的改造口子：边权、图模型、服务层。按价值排序，我建议先改权重，因为它对结果的影响最直接，改动量也最小。

边权从距离换成时间，只需要在Edge上加一个costSeconds，用速度表反推。速度表放在GeoMath或者单独的配置里，按highway类型取值，未知类型给一个保守值而不是 0——给 0 会让算法无脑穿小巷，这是很多人调完权重发现路线“变傻”的真正原因。

private static final Map<String, Double> KMH = Map.of( "motorway", 100.0, "trunk", 80.0, "primary", 60.0, "secondary", 50.0, "tertiary", 40.0, "residential", 30.0, "service", 15.0, "unclassified", 25.0); public double costSeconds() { double kmh = KMH.getOrDefault(highway, 20.0); // 兜底 20km/h，绝不返回 0 return meters / (kmh / 3.6); }

改完之后一定要拿固定用例回归。我一般准备 20 条起终点，记录优化前后的总时长和总距离，看趋势是否符合预期：高速优先的权重应该让总时长下降、总距离上升；如果两个指标同时变差，那大概率是速度表写反了或者某个类型的值填错。

转向限制是最值得做但最容易被低估的一项。OSM 里relation的restriction标签描述了“从某条 way 经某个节点不能转到另一条 way”，只建节点和边是表达不了的。常见做法是把“进入某条路段的动作”建模成单独的图节点，或者用 Neo4j 的关系属性在搜索时做状态判断——后者简单但会让 A* 的状态空间翻倍，得权衡。我的建议是：先把限制收集成一个Map<Long, Set<Long>>（进入 way → 禁止转出的 way），在AStarRouter展开邻居时过滤掉，改动十几行，效果立竿见影，等真扛不住了再上状态图。

验证方法上，别只靠肉眼看地图。写一个小脚本批量打接口，把返回的坐标串反解成道路名称序列，人工抽查前几条是否符合“先上主路再下匝道”的常识；再补几条边界用例：起终点重合、跨江只有一座桥、单行道逆行、跨数据裁剪边界。这四类用例覆盖了绝大多数翻车场景。

从那以后我每次动权重或者路网导入逻辑，都会先把那 20 条回归用例跑一遍，再去看地图上的线。算法本身很少出错，出错的基本都是数据侧的一行标签。希望帮到你。

本文还有配套的精品资源，点击获取