企业官网建设流程全解析

简介：Neo4jOSM 是一套面向 Java 开发者与图数据库学习者的简单路由服务示例，围绕 Neo4j 与 OpenStreetMap 展开：将 OSM 路网数据预处理并导入图数据库，以节点和关系表达道路连接，再借助 Cypher 完成最短路径等查询，适合用来理解地理网络建模、空间数据转换与路线规划接口的基本实现。压缩包共 35 个文件，约 314KB，主体为 22 个 Java 源码，另有 3 个 OSM 数据文件、2 个 properties 配置、2 个 Markdown 文档，以及 Gradle 构建脚本、包装器、许可证和 pbf 数据等，兼顾源码阅读、环境搭建与数据试验。已有 171 人学习，体量轻便但结构完整。读者可从中获得路网解析与图模型搭建思路、Cypher 路径查询写法、基于 Java 的服务端组织方式，以及 Gradle 项目编译运行与二次定制的基础参考，适合作为图数据库地理应用入门与课程实践素材。

1. 一条 OD 查询背后的取舍：这个 Java 路由服务解决什么问题

假设你接到一个需求：输入起点和终点的经纬度，返回驾车距离、通行时间和实际经过的路段，每天还要批量算几万条 OD 对，并且整套东西必须能在内网离线跑。走第三方地图 API 这条路基本就堵死了，配额、费用、内网访问三座大山压下来。Neo4jOSM 这个项目干的就是这件事：把 OpenStreetMap 的公开路网数据清洗后导入 Neo4j 图数据库，再在 Java 侧把「最短路径」包成一个 HTTP 路由服务。路网天生就是图结构，路口是节点，路段是边，边上挂着长度、道路等级、单双向这些属性；图数据库存这种拓扑，比关系型表加递归查询舒服太多。它适合两类人：想在自己机器上把一套离线路径规划跑通的开发，以及要在路权、限行、车型这些自定义权重上做二次改造的人。

2. 技术选型与分层架构：三个组件各管一段

2.1 数据、存储、服务三层职责怎么切

这套东西真正落地的关键，不在于算法有多花哨，而在于把「谁负责什么」切干净。整个项目可以看成三段流水线：

第一段是数据侧，输入是.osm.pbf文件。这东西是 OpenStreetMap 的二进制导出格式，一个中等规模城区的数据通常在几百 MB 量级，全量数据是几十 GB，所以别一上来就啃全国数据，先切一块城区跑通再说。解析 PBF 的 Java 库有几个选择，常见做法是 osm4j 或者 osmosis，前者是纯 Java 的流式解析器，适合嵌到代码里；后者更偏命令行工具，可以先做一遍预处理把非道路数据过滤掉。

第二段是存储侧，也就是 Neo4j。选它而不是 PostGIS + pgRouting，主要是两个原因：一是 Cypher 表达路径查询非常自然，一段MATCH p = shortestPath(...)就把意图写清楚了；二是 Neo4j 的 GDS（Graph Data Science）库自带 Dijkstra、A*、Yen 这些最短路算法，而且是编译好的实现，不需要你在 Java 里手写优先队列。代价是要多维护一个数据库进程，以及 GDS 图投影这一层额外的概念。

第三段是服务侧，一个标准的 Spring Boot 应用，对外暴露/api/route之类的接口。它不存任何路网数据，只负责三件事：把用户传来的经纬度吸附到最近的路网节点、拼装 Cypher 调用图算法、把结果（总距离、节点序列、分段耗时）序列化成 JSON 返回。

这三段之间靠文件（CSV）和数据库连接解耦，好处是导入过程可以离线跑、可以重跑，服务重启不影响数据。坏处是数据一致性要靠流程保证——改了权重字段忘了重建图投影，这种坑我后面单独说。

2.2 图模型设计：节点、关系和属性字段怎么定

图模型是整个项目的地基，定错了后面很难改。这个项目里最小可用的模型长这样：

// 路网节点：一个路口或路段端点，location 用 Point 类型方便做空间检索 CREATE (n:OsmNode { osmId: 123456789, // OSM 原始 node id，作为业务主键 lat: 31.2304, // 纬度，保留一份冗余方便导出 lon: 121.4737, // 经度 location: point({latitude: 31.2304, longitude: 121.4737}) }); // 路段：从 A 节点指向 B 节点，属性决定它能不能走、走得快不快 MATCH (a:OsmNode {osmId: 1}), (b:OsmNode {osmId: 2}) CREATE (a)-[:ROAD { wayId: 987654321, // 对应 OSM 的 way id，便于回溯原始数据 distance: 128.6, // 长度，单位统一用米 highway: 'residential', // 道路等级，用于过滤和限速推断 name: '某某路', // 路名，返回给前端做文字指引 oneway: false, // 是否单行道 speedKph: 30 // 该路段的参考时速，时间权重的输入 }]->(b);

几个字段的取舍值得说一下。osmId用 Long 而不是 Neo4j 内部自增 id，是因为你要做增量更新——OSM 每周都在变，用业务主键才能对上号。location存成 Point 类型而不是两个 Double，是为了后面能建空间索引、能做point.distance()计算。distance单位锁死米，别一会儿米一会儿公里，血泪经验，混单位的代码 review 时根本看不出来。

关系方向这件事是新手最容易翻车的地方。OSM 里oneway=yes表示只能沿 way 的节点顺序行驶，oneway=-1是反向，oneway=no或者没有标签是双向。双向道路在导入时必须拆成两条有向的ROAD关系，否则 Dijkstra 从 B 回 A 会返回无路径。有人图省事在查询里用无向匹配-[:ROAD]-，能跑通，但单行道就失效了，属于给未来埋雷。

2.3 代码分层：importer、repository、service、controller

服务侧的代码我一般按四层摆：

osm-neo4j-router/ ├── importer/ # 离线导入模块，可以做成独立 main │ ├── PbfScanner.java # 两遍扫描 PBF，产出 nodes.csv / edges.csv │ └── CsvSchemaWriter.java # 按 neo4j-admin import 的 header 规范写文件 ├── graph/ # 图相关的基础设施 │ ├── Neo4jConfig.java # Driver Bean、连接池、数据库选择 │ └── GraphProjectionBoot.java # 启动时检查并创建 GDS 图投影 ├── repository/ │ ├── RouteRepository.java # 只负责跑 Cypher，返回原始结果 │ └── NodeSnapRepository.java # 坐标吸附查询 ├── service/ │ └── RouteService.java # 编排：吸附 → 求路 → 组装 → 降级 └── web/ └── RouteController.java # 参数校验、异常转 HTTP 状态码

把 importer 单独拎出来是个有意的设计：它依赖 PBF 解析库，包体积大、跑一次要几分钟到几十分钟，完全没必要打进 Web 服务的 jar 里。实际部署时 importer 做成一个带main的命令行工具，java -jar importer.jar --pbf xxx.osm.pbf --out ./csv，跑完再用neo4j-admin database import灌库。Web 服务那边只依赖neo4j-java-driver，冷启动两秒钟。

Repository 层只做一件事：把 Cypher 和参数丢给数据库，把结果映射成 record。业务判断（比如吸附失败要不要降级、路径为空返回什么）全部上浮到 Service。这么切的原因是图查询的返回结构经常变——GDS 2.x 的gds.shortestPath.dijkstra.stream和老的apoc.algo.dijkstra返回字段完全不一样，混在业务代码里改起来就是灾难。

3. 数据入库链路：从 .osm.pbf 到可查询的路由图

3.1 解析 PBF：过滤 highway 标签、处理单双向与节点去重

PBF 是顺序流，一个文件里 node 和 way 混着放，而且 way 只存节点 id 不存坐标。这意味着你没法一遍扫完就建图：读到 way 的时候，它引用的 node 可能还没出现（OSM 规范里 node 通常排在 way 前面，但不是强保证，压缩块顺序也不保证）。

常见做法是两遍扫描。第一遍只读 way，把带highway标签的挑出来，记录它引用的所有 node id 到一个LongOpenHashSet；第二遍只读 node，凡是在这个集合里的，把经纬度写出去。这样内存占用只跟「被道路引用的节点数」有关，一个城区大概几百万，用LongOpenHashSet存大概几十 MB，扛得住。

// 第一遍：扫 way，筛出道路并收集被引用的节点 id public void scanWays(Path pbf, Path wayOut, LongSet neededNodes) throws IOException { try (InputStream in = Files.newInputStream(pbf); BufferedWriter w = Files.newBufferedWriter(wayOut)) { // PbfIterator 的构造签名在不同 osm4j 版本略有差异，以本地 jar 为准 OsmIterator it = new PbfIterator(in, false, true); for (EntityContainer c : it) { if (c.getType() != EntityType.Way) continue; OsmWay way = (OsmWay) c.getEntity(); Map<String, String> tags = toMap(way.getTags()); String highway = tags.get("highway"); // 只保留机动车可通行的等级，人行道、步道、台阶一律丢掉 if (highway == null || !DRIVABLE.contains(highway)) continue; // 单双向判定：yes 正向单行，-1 反向单行，其余按双向处理 String onewayTag = tags.getOrDefault("oneway", "no"); int dir = "yes".equals(onewayTag) ? 1 : "-1".equals(onewayTag) ? -1 : 0; // 逐段写出边，双向道路在这里就拆成两条 for (int i = 0; i + 1 < way.getNumberOfNodes(); i++) { long from = way.getNodeId(i); long to = way.getNodeId(i + 1); neededNodes.add(from); neededNodes.add(to); if (dir >= 0) w.write(edgeLine(from, to, way, tags)); if (dir <= 0) w.write(edgeLine(to, from, way, tags)); } } } }

DRIVABLE这个集合我一般写成motorway, trunk, primary, secondary, tertiary, residential, service, unclassified这几档，外加*_link匝道。把footway、path、steps混进来，算出来的「驾车路径」会出现穿公园、翻天桥这种玄学结果。

单双向那段是重点。oneway=-1表示方向与 way 的节点顺序相反，不少人只判了yes，结果反向单行道被当成双向，路线看着能跑但其实违规。边写出去的时候顺便把distance算好——用 haversine 或者 Neo4j 侧point.distance都行，我更倾向在 Java 里算完存米数，导入后不用二次计算。

3.2 生成 CSV 与批量导入：neo4j-admin import 与 LOAD CSV 两条路

导入有两条路子，选哪条取决于数据量。

小数据（几十万边以内）用LOAD CSV最省事，不用停库，一条 Cypher 搞定：

// 注意用 CALL {} IN TRANSACTIONS 分批，否则单事务百万行直接 OOM LOAD CSV WITH HEADERS FROM 'file:///nodes.csv' AS row CALL { WITH row MERGE (n:OsmNode {osmId: toInteger(row.osmId)}) SET n.lat = toFloat(row.lat), n.lon = toFloat(row.lon), n.location = point({latitude: toFloat(row.lat), longitude: toFloat(row.lon)}) } IN TRANSACTIONS OF 10000 ROWS; // 边导入前必须先建唯一约束和索引，否则 MERGE 会全表扫 CREATE CONSTRAINT osm_node_id IF NOT EXISTS FOR (n:OsmNode) REQUIRE n.osmId IS UNIQUE;

IN TRANSACTIONS OF 10000 ROWS是 Neo4j 5 的写法，4.x 上语法不同。这个分批很关键，我见过直接LOAD CSV灌 300 万行边、堆内存 4G，跑到一半OutOfMemoryError，日志里还没什么有用信息，纯黑匣子。

大数据（千万边量级）就得用neo4j-admin database import，这是离线工具，要求数据库停机、目录为空，但速度快一个数量级，因为它绕过了事务和索引维护，直接写存储文件。它要求 CSV 带特定格式的 header：

# nodes.csv osmId:ID(OsmNode),lat:double,lon:double,:LABEL 1001,31.2304,121.4737,OsmNode # edges.csv :START_ID(OsmNode),:END_ID(OsmNode),distance:double,wayId:long,highway,speedKph:int,:TYPE 1001,1002,128.6,987654321,residential,30,ROAD

:ID(OsmNode)声明这是节点 id 空间，:START_ID/:END_ID引用同一空间，:LABEL和:TYPE是固定列。这套 header 语法比较挑剔，列顺序、类型标注、冒号位置错一个就报Invalid input，而且报错行号常常指不到真正的问题行，得靠二分法切文件定位。

3.3 建索引与图投影：给 GDS 准备一张可计算的图

数据进库之后还不能直接算最短路，得先做两件事。

第一件是建空间索引，服务于「经纬度吸附最近节点」这个高频操作：

// 点索引，让范围粗筛能走索引而不是全表扫 CREATE POINT INDEX osm_node_location IF NOT EXISTS FOR (n:OsmNode) ON (n.location);

第二件是建 GDS 图投影。GDS 的算法不直接跑在存储图上，而是跑在一张内存里的「投影图」上。投影图是快照，创建那一刻的节点、关系、属性就固定了，后面你再改存储图的distance，投影图不会自动更新——这是本项目最大的一个坑，第 5 章细说。

// 只投影 ROAD 关系，并把算法要用的权重属性带进去 CALL gds.graph.project( 'roadGraph', 'OsmNode', { ROAD: { type: 'ROAD', properties: ['distance', 'speedKph'] } } ) YIELD graphName, nodeCount, relationshipCount;

参数说明：第一个参数是投影图名字，后面所有算法调用都靠这个名字引用；第二个是节点标签；第三个是关系投影配置，properties里列出的属性才会被加载进内存，没列的属性算法里读不到。千万级边的情况下，把name这种字符串属性也投影进去会白白吃掉大量堆内存，只在需要返回文字指引时才投影。

投影建完后，可以用CALL gds.graph.list()确认节点边数量和内存占用，CALL gds.graph.drop('roadGraph')删掉重建。生产环境我一般把这段逻辑写进一个启动钩子：先gds.graph.exists判断，存在就跳过，不存在就 project，避免每次重启都重投影几千万条边。

4. 核心代码拆解：一次路由请求的完整链路

4.1 Driver 与配置：连接池、超时与 Session 用法

Neo4j 的 Java Driver 是长连接 + 连接池模型，官方建议整个应用共享一个Driver实例，不要每次请求 new 一个。Spring Boot 里做成单例 Bean 就行：

@Configuration public class Neo4jConfig { @Bean(destroyMethod = "close") public Driver neo4jDriver() { return GraphDatabase.driver( "bolt://127.0.0.1:7687", AuthTokens.basic("neo4j", "change-me"), // 连接池上限别拍脑袋给大，按并发量给，默认 100 已经够用 Config.builder() .withMaxConnectionPoolSize(50) .withConnectionAcquisitionTimeout(Duration.ofSeconds(5)) .withMaxTransactionRetryTime(Duration.ofSeconds(15)) .build() ); } }

三个参数值得解释。withMaxConnectionPoolSize控制同时能借出多少条连接，给太大数据库侧线程会被打满，给太小高并发下请求排队；withConnectionAcquisitionTimeout是借连接的超时，比查询超时更早触发，能快速失败而不是把 Tomcat 线程池拖死；withMaxTransactionRetryTime是遇到死锁或暂时性错误时的重试窗口，读多写少的场景其实影响不大，但保留着更稳。

写操作要用session.executeWrite，读用session.executeRead，Driver 会根据模式做路由（单机版没差别，集群版差别很大）。Session 用完必须关，用 try-with-resources，否则连接泄漏，跑一天之后所有请求开始超时。

4.2 Repository 层：Dijkstra 的 Cypher 怎么写

核心查询就这一条：

private static final String SHORTEST_PATH = """ MATCH (s:OsmNode {osmId: $startId}) MATCH (e:OsmNode {osmId: $endId}) CALL gds.shortestPath.dijkstra.stream('roadGraph', { sourceNode: s, targetNode: e, relationshipWeightProperty: 'distance' }) YIELD totalCost, nodeIds, costs, path RETURN totalCost, [n IN nodeIds | n.osmId] AS osmIds, costs, [r IN relationships(path) | r.name] AS roadNames """; public Optional<RouteResult> shortestPath(long startId, long endId) { try (Session session = driver.session(SessionConfig.forDatabase("neo4j"))) { return session.executeRead(tx -> { Result result = tx.run(SHORTEST_PATH, Map.of("startId", startId, "endId", endId)); if (!result.hasNext()) return Optional.empty(); Record r = result.next(); return Optional.of(new RouteResult( r.get("totalCost").asDouble(), r.get("osmIds").asList(Value::asLong), r.get("roadNames").asList(v -> v.isNull() ? "" : v.asString()) )); }); } }

逐段说。前两个MATCH用osmId唯一约束定位起终点，这一步必须走索引，不然每次请求都全表扫节点。gds.shortestPath.dijkstra.stream是 GDS 2.x 的过程名，第一个参数是投影图名，配置 Map 里sourceNode/targetNode直接传节点变量（GDS 内部会映射到投影图里的对应节点），relationshipWeightProperty指定用哪个属性当权重——想按时间算就把这里换成speedKph的倒数，但要注意权重必须是非负数。

返回字段里totalCost是权重累计值，权重是distance时单位就是米；nodeIds是投影图内部的节点 id，不是你的osmId，所以要用列表推导[n IN nodeIds | n.osmId]转回来；path是完整路径对象，relationships(path)能拿到沿途的边属性。stream模式和write模式的区别在于前者不写回数据库，路由服务要的是结果不是持久化，用stream对。

一个容易被忽略的点：如果起终点在路网上不连通（比如隔着一条没架桥的河，或者数据里缺了某段），这个查询返回空结果集，不会报错。Repository 返回Optional.empty()，Service 层要翻译成「无可用路径」而不是 500。

4.3 Service 与 Controller：坐标吸附、结果组装与错误处理

用户传的是经纬度，数据库里存的是节点，中间差一步「吸附」。这一步看起来简单，写好很难：

public long snapToNearestNode(double lat, double lon) { // 先按经纬度框粗筛，框的大小随纬度变化，这里给个约 500 米的经验值 double dLat = 0.005; double dLon = 0.005 / Math.max(0.2, Math.cos(Math.toRadians(lat))); String cypher = """ MATCH (n:OsmNode) WHERE n.lat >= $minLat AND n.lat <= $maxLat AND n.lon >= $minLon AND n.lon <= $maxLon AND n.location IS NOT NULL WITH n, point.distance(n.location, point({latitude: $lat, longitude: $lon})) AS d ORDER BY d ASC LIMIT 1 RETURN n.osmId AS osmId, d """; // ...执行并映射，查不到就抛 SnapFailedException 让上层决定降级策略 }

为什么不直接ORDER BY point.distance(...) LIMIT 1一把梭？因为那样是全表扫描 + 排序，百万节点下每次请求几百毫秒起步，并发一上来数据库就顶不住。先用经纬度范围做框筛，能把候选集压到几十上百个，再算精确距离排序。框的大小是个经验值，500 米在城区够用，郊区路网稀疏的地方可能框里一个点都没有，得做一次放大重试。

Controller 层做三件事：参数校验、异常映射、结果包装。

@GetMapping("/api/route") public ResponseEntity<?> route(@RequestParam double fromLat, @RequestParam double fromLon, @RequestParam double toLat, @RequestParam double toLon) { if (Math.abs(fromLat) > 90 || Math.abs(toLat) > 90) { return ResponseEntity.badRequest().body(Map.of("error", "纬度超出范围")); } try { return ResponseEntity.ok(routeService.route(fromLat, fromLon, toLat, toLon)); } catch (SnapFailedException e) { // 起终点吸附失败通常是坐标离路网太远，属于客户端问题 return ResponseEntity.unprocessableEntity().body(Map.of("error", "起终点不在路网覆盖范围内")); } catch (NoPathException e) { return ResponseEntity.ok(Map.of("reachable", false)); } }

NoPathException返回 200 带reachable: false而不是 404，是因为「两点之间确实没有驾车路径」是一个合法的业务结论，不是接口错误。前端拿到这个能正常展示「该地点不可驾车到达」，而 404 会被很多 HTTP 客户端当成网络异常处理。

Service 里还有个组装步骤：totalCost是总米数，要换算成耗时得按每段speedKph加权求和，不能拿总距离除以平均速度——一段高速加一段拥堵市区，平均出来的数字没有参考价值。逐段累加的实现就是拿costs数组和roadNames对齐遍历。

5. 避坑与排查：五个把服务跑挂的细节

5.1 环境启动顺序：数据库、插件、应用三件套

启动顺序错了会浪费很多时间。正确顺序是：先起 Neo4j 并确认 GDS 插件加载成功，再执行导入，再启动应用。GDS 是 Neo4j 的插件，要在neo4j.conf里配dbms.security.procedures.unrestricted=gds.*并把 jar 丢进plugins/目录，装完用RETURN gds.version()验一下。装不上插件时，应用能正常启动、能正常连库，只有调算法的那一刻才报Unknown function 'gds.shortestPath.dijkstra.stream'，很容易误判成依赖问题。

5.2 五条踩坑记录

现象一：A 到 B 有路径，B 到 A 返回空。原因是单行道方向处理反了，或者双向道路只建了一条有向边。最隐蔽的情况是oneway=-1被当成双向，正向能跑、反向也能跑，但路线实际违规，你不看原始数据根本发现不了。解决方式是在导入阶段就把双向道路拆成两条方向相反的边，并在数据库里抽查几条已知单行道的MATCH (a)-[:ROAD]->(b) RETURN a.osmId, b.osmId，确认没有反向边。

现象二：改了某段路的权重，算出来的路径完全没变。这是 GDS 图投影的缓存问题。投影图是内存快照，用 CypherSET r.distance = ...改的是存储图，投影图里还是老值。解决方式是改完属性后执行CALL gds.graph.drop('roadGraph')再重新 project，或者在应用侧写一个「权重版本号」机制，版本变化时强制重建投影。我见过有团队调了两天算法参数，其实一直是旧图在算。

现象三：起点吸附到了高架桥下面或者人行道上，路径出来绕一大圈。原因是最邻近节点只看了直线距离，没看这个节点挂的是什么等级的路。解决方式是在吸附查询里加过滤条件，只允许吸附到highway属于机动车等级的节点上，或者更彻底一点——吸附到最近的边而不是节点，这样能拿到准确的在路位置。城区高架密集的地方，这个坑几乎必踩。

现象四：LOAD CSV导入到一半 OOM，日志没有有用的堆栈。百万行 CSV 在单个事务里跑，Neo4j 会把整个事务的状态维护在堆里，堆一满直接挂。解决方式是用CALL {} IN TRANSACTIONS OF 10000 ROWS分批，或者干脆改用neo4j-admin database import离线导入。另外注意 Neo4j 的heap和pagecache要分开配，把 pagecache 配得太大会挤压堆空间，导入阶段反而更容易挂。

现象五：算出来的距离和实际导航差了一大截。先查单位。distance字段有的路段存米、有的存公里，混在一起累加出来的totalCost就是个无意义的数字。再查坐标系，拿经纬度直接当平面坐标算欧氏距离，在短距离上误差不明显，跨城区就开始飘。正确做法是用 haversine 或者point.distance，它内部按球面模型算，输出单位是米。这类问题排查时最有效的手段是拿几条已知真实距离的路段做基准，对不上就说明单位或算法有问题。

6. 二次开发：换权重、换算法、加约束的改造路线

6.1 权重重构：从公里数改成通行时间

这个项目最值钱的改造点就是把权重从距离换成时间。做法不复杂，但有两个细节必须一起改：

第一步，给每条ROAD边补一个travelSeconds属性，值等于distance / (speedKph * 1000 / 3600)，也就是米除以米每秒。speedKph不可能都有原始数据，OSM 里只有部分道路带maxspeed标签，其余得按highway等级给默认值——高速 100、主干道 60、次干道 40、支路 30、服务道路 20，这套默认值在城区场景够用。

第二步，重建图投影时把travelSeconds加进properties列表，查询里把relationshipWeightProperty换成它。只改查询不改投影，算法根本读不到这个属性，会直接报属性不存在。

再往深一层是转向代价。路口左转和直行的实际代价不一样，但边权重模型表达不了「转向」这种依赖前一条边的代价——它需要把状态从「节点」升级成「(节点, 入边)」的有向线图。真要做的话，导入阶段得额外生成TURN关系，把图规模放大两三倍，内存换精度，看场景值不值。

6.2 验证方法：三条对拍规则

改完权重最怕的是「看起来能跑，结果全错」。我的习惯是留三条对拍：

第三条尤其有用——它能一次性验证「投影重建是否生效」和「权重是否真的参与计算」这两件事。

6.3 一点个人习惯

有件事我踩过太多次，现在成了肌肉记忆：每次改完导入脚本或权重字段，先把投影图 drop 掉、单独跑一条三节点的最小图，确认totalCost和手算结果一致，再放全量数据进去。跳过这一步省下的十分钟，早晚会变成两小时的排查。希望帮到你。

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