企业官网建设流程全解析

上一篇把Cypher基础语法过了一遍，建节点、查关系、玩路径匹配都试过了。这篇就直接进入正题：怎么把Neo4j接到SpringBoot项目里，让Java代码能读写图数据。你可以把这篇理解为一张“从0到1跑通SpringBoot + Neo4j”的完整路线图，里面包含了依赖怎么配、实体怎么映射、Repository怎么写、事务怎么管，以及我实际调试过程中踩过的那几个坑。

这篇东西适合两类人：一类是刚接触图数据库、想在自己的SpringBoot项目里快速接入Neo4j的开发者；另一类是已经用Spring Data JPA做过关系型数据库开发，想搞清楚Spring Data Neo4j和它有什么异同的朋友。不管你是哪一类，看完之后至少能独立完成“建实体、写接口、存数据、查关系”这整条链路。

1. 为什么是SpringBoot整合Neo4j——先搞清楚要解决什么问题

1.1 图数据在Java项目里的“身份”问题

关系型数据库里，一张表对应一个Java类，一行记录对应一个对象，外键对应关联关系。这套映射被JPA做得非常成熟，大家也都很熟悉。但到了Neo4j这里，核心数据结构变了：节点（Node）和关系（Relationship）是图里的一等公民，关系不是外键那样的“引用”，而是有类型、有方向、有属性的一等实体。

比如要表示“张三演了《某电影》”这条信息，在关系型数据库里可能得两张表加一张关联表，查询的时候要JOIN三次；在Neo4j里就是一个Person节点、一个Movie节点、一条类型为ACTED_IN的关系。数据结构不同，Java对象怎么去映射它、查询接口怎么去组织它，自然也得换一套思路。

SpringBoot整合Neo4j，本质上就是要解决两件事：第一，让Java对象能方便地转换成图里的节点和关系，也就是对象图映射；第二，让Cypher查询能和Java方法调用对上，也就是数据访问层该长什么样。这两件事处理好了，你在业务代码里操作图数据就能像操作普通Java对象一样自然。

1.2 三种整合方案，怎么选

我在实际项目里试过几种接入方式，这里把主流的三条路线放在一起做个对比，方便你根据自己项目的情况选。

如果你只是想在服务里跑几条Cypher，拿回一个List

OGM这个方案我简单说一句：它是Spring Data Neo4j 5.x时代的底层实现，后来Spring Data Neo4j 6.x彻底重写，不再依赖OGM，而是直接基于官方Driver实现。所以新项目直接选Spring Data Neo4j就好，没必要再去绕OGM。

2. 项目初始化和依赖配置——版本坑可太多了

2.1 环境准备：先确认版本兼容矩阵

版本问题是我折腾这个整合踩过的第一个大坑。Spring Boot 2.x和3.x对Spring Data Neo4j的依赖版本完全不同，Java版本要求也不同，上来就写依赖很容易启动失败。

我建议你按照这个组合来配：

这里有个细节要说明：自Spring Boot 2.4之后，官方就提供了spring-boot-starter-data-neo4j这个Starter，它包含了Spring Data Neo4j和配套的Neo4j Java Driver。如果你的项目用的还是老版本的neo4j-java-driver-spring-boot-starter，那是社区维护的，和官方Starter在配置项上有差异，建议统一迁移到官方Starter上。

Neo4j服务端版本和Driver版本之间有比较强的绑定关系。Driver 4.4支持Neo4j 4.4服务端，Driver 5.x支持Neo4j 5.x服务端。如果你的服务端还是Neo4j 3.5这种老版本，强行用新Driver基本连不上或者莫名其妙报错。实操建议：先查一下你的Neo4j容器或服务端版本，再回头定SpringBoot版本，这个顺序别搞反。

2.2 依赖写法和配置文件

在pom.xml里加：

<dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-data-neo4j</artifactId> </dependency>

如果你用Maven管理项目，这一个依赖就够用了。Spring Boot的版本管理会自动带出配套的Spring Data Neo4j版本。

配置完依赖，再看application.yml。这里是最容易出问题的地方之一，因为Spring Data Neo4j 6.x之后的配置前缀是spring.neo4j，不再是spring.data.neo4j。不少老年间的教程还在用旧前缀，你照着抄会发现配置完全不生效。

spring: neo4j: uri: bolt://localhost:7687 authentication: username: neo4j password: your-strong-password pool: max-connection-pool-size: 100 connection-acquisition-timeout: 60s connection-timeout: 60s max-connection-lifetime: 5m

配置项说明：

连接池这块，我不建议按关系型数据库的习惯把值调得很大。Neo4j的Bolt连接是轻量的，但每个连接都会在服务器端占用一点资源。普通的微服务实例100个连接绰绰有余，开太多反而浪费。还有一点要注意，Neo4j是长连接协议，如果你在容器化环境里频繁重启服务，操作系统的TIME_WAIT连接会积压，适当把max-connection-lifetime调到5-10分钟，能有效减少这种情况。

3. 数据模型映射——从Cypher到Java对象的“翻译官”

3.1 节点实体定义：@Node和@Id怎么用

这一段是整个整合里最核心、也最容易出理解偏差的地方。我直接用一个电影演员的例子来讲，因为图数据天生适合做这种多对多关系的建模。

先定义一个Movie节点实体：

import org.springframework.data.neo4j.core.schema.Id; import org.springframework.data.neo4j.core.schema.Node; import org.springframework.data.neo4j.core.schema.Property; import org.springframework.data.neo4j.core.schema.Relationship; import org.springframework.data.neo4j.core.schema.GeneratedValue; import java.util.ArrayList; import java.util.List; @Node("Movie") public class Movie { @Id @GeneratedValue private Long id; @Property("title") private String title; @Property("releaseYear") private Integer releaseYear; private Double rating; @Relationship(type = "ACTED_IN", direction = Relationship.Direction.INCOMING) private List<Person> actors = new ArrayList<>(); public Movie() { } public Movie(String title, Integer releaseYear, Double rating) { this.title = title; this.releaseYear = releaseYear; this.rating = rating; } // getter / setter }

讲讲关键点：

@Node注解用来声明这是一个图节点实体。注解里的值对应Cypher里的节点标签。@Node("Movie")对应MATCH (m:Movie)里的Movie标签。

@Id标注的是映射到图内部ID的字段。这里有个新手特别容易纠结的点：图数据库的内部ID和业务ID不是一个东西，它类似物理行号，Neo4j官方也不建议在业务里长期依赖这个ID。所以Spring Data Neo4j提供了@GeneratedValue注解，让框架在创建新节点时自动分配一个Long类型的ID。如果你的业务里已经有唯一标识，比如ISBN、员工工号，我建议用@Property单独映射一个业务字段，再加唯一约束，而不是直接把业务字段顶到@Id上去。

@Property注解用来指定字段映射的图属性名。如果你不写，默认用Java字段名作为属性名。这里我建议显式写清楚，一是防止Java字段名调整时影响图结构，二是在多人协作时让人一眼看清图里实际的属性名。比如Movie实体里releaseYear字段，图里属性就叫releaseYear，Java里我也叫这个名，两者一致。

不过这里有个细节要提醒：图属性名是区分大小写的，MATCH的时候写成releaseyear就查不到。所以建议统一用一种命名风格，比如全小写或驼峰，写Cypher的时候前后保持一致。

3.2 关系映射：方向和解耦不要搞错

再定义一个Person实体：

@Node("Person") public class Person { @Id @GeneratedValue private Long id; @Property("name") private String name; @Relationship(type = "ACTED_IN", direction = Relationship.Direction.OUTGOING) private List<Movie> actedIn = new ArrayList<>(); public Person() { } public Person(String name) { this.name = name; } // getter / setter }

@Relationship注解是关系映射的关键。它有3个值要注意：type对应Cypher里关系的类型，direction对应关系的方向，然后这个字段的类型一般是同类型实体的List。

方向这里尤其容易混乱。Movie这边标注的direction是INCOMING，意思是“指向Movie这个节点的入边”，对应Cypher就是(movie)<-[:ACTED_IN]-(person)。Person这边标注的direction是OUTGOING，意思是“从Person出发的出边”，对应Cypher是(person)-[:ACTED_IN]->(movie)。两者描述的是同一条边，从不同端看方向不同。

这里要特别说明一个实操血泪教训：如果你像上面这样，在关系两端都维护了实体引用（Movie.actors和Person.actedIn），保存时两边都会尝试写这条关系。SDN在对集合做差异计算时，有时候会因为同一关系被两边重复维护而产生重复边。我自己就遇到过保存一次之后，Neo4j里出现了两条一模一样的ACTED_IN关系。

后来我的做法是：关系维护只在一边做。比如只在Movie端维护actors关系，Person端就只做查询展示用，把它标为只读或根本不维护。如果你确实需要双向引用，保存时一定要保证引用的是同一个Java对象（同一个内存地址，而不是两个相同ID的独立对象），这样才能让SDN识别出是同一组关系。

3.3 Repository定义：Spring Data家族的老配方

实体定义好了，数据访问层就简单了：

import org.springframework.data.neo4j.repository.Neo4jRepository; import org.springframework.data.neo4j.repository.query.Query; import org.springframework.data.repository.query.Param; import org.springframework.stereotype.Repository; import java.util.List; import java.util.Optional; @Repository public interface MovieRepository extends Neo4jRepository<Movie, Long> { Optional<Movie> findByTitle(String title); List<Movie> findByReleaseYearGreaterThan(Integer year); List<Movie> findByActorsName(String actorName); @Query("MATCH (m:Movie) WHERE m.releaseYear >= $minYear AND m.rating >= $minRating RETURN m ORDER BY m.rating DESC") List<Movie> findRecommendedMovies(@Param("minYear") int minYear, @Param("minRating") double minRating); @Query("MATCH (p:Person)-[:ACTED_IN]->(m:Movie) WHERE p.name = $name RETURN m") List<Movie> findMoviesByActorName(@Param("name") String name); }

这里有几个值得说的点。

Neo4jRepository是Spring Data Neo4j提供的核心接口，泛型参数是实体类型和ID类型。它自带了一批CRUD方法，比如save、findById、findAll、deleteById，这些在SDN里的实现都是基于底层Driver跑Cypher完成的，不是JPA那种自动SQL。

findByActorsName这种写法，是Spring Data的“方法名派生查询”。它会沿着实体的属性路径去解析，actors是Movie上的关系属性，再往下name是Person节点的属性。最终生成的Cypher相当于MATCH (m:Movie)-[:ACTED_IN]->(p:Person) WHERE p.name = ?。这种写法胜在可读性好，但有个缺点：方法名里一旦出现拼写错误或者路径不对，报错要到启动或首次调用时才会发现。

所以我更建议在复杂查询上直接使用@Query注解写Cypher，把控制权握在自己手里。比如上面findMoviesByActorName这个例子，我用@Query明确写死了MATCH路径，查询行为一目了然。

关于参数占位符，我要专门提一下：SDN 6.x支持$name和{name}两种写法，但我强烈建议新代码统一用$name。因为$是Cypher正式的标准参数语法，SDN默认走参数化查询，能有效防止Cypher注入，也方便Neo4j做查询缓存复用。

4. 实现一个完整的业务链路——从Service到Controller

4.1 Service层：事务和关系维护的边界

数据访问层定义好，接下来是Service。这里要重点讨论事务管理，因为SDN的懒加载机制、关系保存机制都依赖事务。

import org.springframework.stereotype.Service; import org.springframework.transaction.annotation.Transactional; import java.util.List; @Service public class MovieService { private final MovieRepository movieRepository; private final PersonRepository personRepository; public MovieService(MovieRepository movieRepository, PersonRepository personRepository) { this.movieRepository = movieRepository; this.personRepository = personRepository; } @Transactional(readOnly = true) public Movie findByTitle(String title) { return movieRepository.findByTitle(title).orElse(null); } @Transactional public Movie saveMovieWithActor(Movie movie, String actorName) { Person actor = personRepository.findByName(actorName).orElseGet(() -> { Person p = new Person(actorName); return personRepository.save(p); }); movie.getActors().add(actor); return movieRepository.save(movie); } @Transactional(readOnly = true) public List<Movie> findMoviesByActor(String actorName) { return movieRepository.findMoviesByActorName(actorName); } }

事务这块有几个坑值得展开说说。

第一个坑是Repository自带事务。Spring Data Neo4j的Repository的save、findById等在默认情况下是带事务包裹的，但如果你的Service方法里要连续做多次查询、然后再组装一个对象返回，没有@Transactional的话，每一次Repository调用都会独立开闭一个事务。如果中间涉及懒加载关系的访问，等事务关了再去访问关系属性，就会报错。所以在Service类上标注@Transactional，让整个业务方法共享一个事务，是更稳妥的做法。

第二个坑是@Transactional只对代理对象外部调用生效。同一个类内部通过this调用另一个@Transactional方法，事务注解不会生效，因为走的不是代理对象。如果你碰到“为什么我加了事务但还是报No session”这种问题，优先检查是不是类内部自调用。

第三个坑是关系保存的顺序。saveMovieWithActor这个方法里，我先把演员查出来或保存好，拿到一个带ID的Person对象，然后再把它加进Movie的actors集合。这样做的目的是保证SDN在保存Movie时，能识别出这个Person是已存在的节点，从而只创建关系、不重复创建节点。如果你直接new Person("新演员")塞进集合，SDN会帮你创建一个新的Person节点。这在某些场景确实是你要的，但如果你不小心new了一个名字已存在的演员，就会导致重复演员节点出现。这个小问题一旦数据量上去，靠Cypher去重会很痛苦。

4.2 Controller层：接口设计和Cypher的对应关系

import org.springframework.web.bind.annotation.*; import java.util.List; import java.util.Map; @RestController @RequestMapping("/api/movies") public class MovieController { private final MovieService movieService; public MovieController(MovieService movieService) { this.movieService = movieService; } @PostMapping public Movie createMovie(@RequestBody Movie movie) { return movieService.saveMovie(movie); } @PostMapping("/{movieId}/actors") public Movie attachActor(@PathVariable Long movieId, @RequestBody Map<String, String> body) { Movie movie = movieService.findById(movieId); if (movie == null) { throw new RuntimeException("电影不存在: " + movieId); } return movieService.saveMovieWithActor(movie, body.get("actorName")); } @GetMapping("/actor") public List<Movie> getMoviesByActor(@RequestParam String actorName) { return movieService.findMoviesByActor(actorName); } @GetMapping("/search") public List<Movie> searchMovies(@RequestParam String keyword) { return movieService.searchMoviesByKeyword(keyword); } }

Controller本身没什么特殊的，Neo4j不 care HTTP层用什么框架，你用Spring MVC也好、WebFlux也好，只要是SpringBoot项目都能接。真正的重点是：接口的参数和返回，最后都落到了图数据的读写上。

比如为电影添加演员这个接口，请求体传一个演员名，Service层里需要判断这个演员节点是否存在。这里就有两种思路：先查再建（像上面代码那样），或者直接用Cypher的MERGE去写，避免重复节点。用MERGE写会更优雅一些，不过需要你定义好唯一约束。比如在Person的name上加唯一约束，然后写一条MERGE Cypher，能省掉Java里的判断逻辑。这个可以在熟悉了基础写法之后再做优化。

4.3 自定义查询：把复杂图遍历放进Cypher

前面提到过可以用@Query写Cypher，我再补充一个稍微复杂一点的场景。比如要查“和某演员合作过的其他演员”，这种多跳查询在关系型数据库里要么递归CTE要么多次JOIN，在Neo4j里是一条很自然的Cypher：

@Query("MATCH (a:Person)-[:ACTED_IN]->(m:Movie)<-[:ACTED_IN]-(co:Person) " + "WHERE a.name = $actorName AND co.name <> $actorName " + "RETURN DISTINCT co") List<Person> findCoActors(@Param("actorName") String actorName);

这条Cypher的逻辑就是：找到这个演员演过的所有电影，再找到这些电影的其他演员，DISTINCT去重。这种多跳关系查询就是图数据库的主场，写起来非常自然。你在SpringBoot里用@Query把它包成一个Repository方法，业务层调起来和其他查询完全一样。

这种写法的好处是，你可以在Neo4j Browser里先把Cypher调通、调优，确认执行计划和结果都没问题，再把Cypher贴到@Query里。我自己的开发习惯也是这样：先Browser后代码，可以少写很多调试代码。

5. 常见问题与排查技巧实录

5.1 启动报错速查表

这里我把自己实际遇到过的启动期问题整理成了一张表，每个都是真实踩过坑的，不是抄文档。

第一个“连接不上”是最常见的。有一次我排查了半天，最后发现是Neo4j容器还没完全启动，SpringBoot服务启动太快了。所以如果你的服务在启动阶段就连不上Neo4j，不要只盯着配置，先等几秒或者加个重试机制。

还有一个很容易被忽略的点：Neo4j的默认bolt端口是7687，但如果你用Docker启动时端口映射没做好，比如只映射了7474（HTTP端口）却没映射7687，那Neo4j Browser打得开，但程序永远连不上。这个坑我至少见过三次了，每次都是“Browser能进，Java连不上”的诡异现象，最后都是端口映射问题。

5.2 运行期数据读写不一致问题

启动通过之后，真正开始调试业务接口时会遇到一些运行期问题，这里单独列几个。

第一个是懒加载异常。SDN 6.x默认关系是懒加载，如果你在一个没有事务的上下文里访问movie.getActors()，会有几率遇到类似“Failed to load relationship”的报错。解决办法就是在Service层标注@Transactional。

第二个是重复节点问题。前面提到过，关系两端都保存容易产生重复节点或重复边。我的排查建议是：在Neo4j Browser里执行MATCH (p:Person) RETURN p.name, count(*) GROUP BY p.name，检查有没有同名重复节点。如果有，说明你的保存逻辑里new了太多“伪新”对象。

第三个是更新时丢失属性。如果你先查出来一个Movie，修改其中个别字段再save，SDN会执行一个类似MERGE的更新逻辑。但如果你把一个字段設为null再save，不同版本的处理不太一样，有时候会把图里的属性覆盖为null。我的建议是：更新场景尽量在事务里先把实体完整查出来，只改要改的字段，不要给无关字段赋值。

第四个是类型转换问题。图属性没有严格类型约束，同一个属性在不同节点上可能是不同类型。比如你存的时候是整数releaseYear=2020，查询时用字符串"2020"去匹配，可能查不到。建议在实体字段类型上保持一致，并且Cypher里比较时用参数化类型。

5.3 用Neo4j Browser验证数据

这一步我要强烈推荐给所有新手：程序跑完接口后，要去Neo4j Browser里亲眼看一下图数据长什么样。Spring Data Neo4j帮你屏蔽了很多细节，你看到的是一堆Java对象和Repository方法，但底层实际发生的Cypher操作和你想象的未必一样。

比如保存一个带关系的Movie之后，在Browser里执行：

MATCH (m:Movie)-[r:ACTED_IN]-(p:Person) RETURN m.title, p.name, type(r), startNode(r), endNode(r)

看两方面：一是关系是不是预期的类型和方向，二是有没有重复关系。如果出现两条一样的ACTED_IN关系，就去检查实体里是不是两端都在维护集合。

我还会用这个命令看每个节点的属性名：

MATCH (m:Movie) RETURN keys(m) LIMIT 5

看属性名和Java字段名是否对得上，特别是那些加了@Property注解的字段。这一步能帮你快速发现字段名拼写不一致导致的查询结果为空的问题。

6. 我对这个整合方案的几点实操心得

最后分享几个比较主观但实际有用的经验，不是结论，只是我个人的体会。

如果项目里图查询特别复杂，比如要走很多跳、要做路径分析、要算最短路径之类，不要硬把逻辑塞进Repository。这时候更好的做法是，在Service层注入Neo4jClient或者Neo4jTemplate，直接用Cypher跑复杂查询，把结果映射成DTO。Spring Data Neo4j从6.x开始提供了Neo4jTemplate，你可以把它理解成JdbcTemplate的Neo4j版本，灵活性很高，适合复杂场景。Repository适合常用且相对固定的查询，复杂查询交给Template，这样代码层次更清晰。

生产环境里建议把Neo4j的密码通过环境变量或配置中心注入，不要写死在application.yml里。这个不用多说，属于基本功了。另外一个比较容易被忽略的点是Neo4j连接的健康检查。SpringBoot自带的HealthIndicator对Neo4j有支持，你可以通过引入spring-boot-starter-actuator，然后配置management.health.neo4j.enabled=true，这样在网关或监控面板里就能看到Neo4j的连接状态了。

在这个系列里我写到“（二）”，下一步大概率会聊聊SDN的关联查询优化、图投影（Projection）接口、以及Neo4jTemplate的进阶用法。如果你把这篇里的实体映射和Repository写法吃透了，那些内容基本上就是在此基础上做扩展，不会再有理解门槛了。