Neo4j连接失败主因是Driver未单例复用致连接池耗尽；Cypher查不到结果多因标签大小写/参数类型不匹配；关系遍历慢需建索引并限制递归深度；SDN保存失败常因@Id/@Relationship注解缺失或错位。
Neo4j 连接失败：Driver 未关闭导致连接池耗尽
Java 应用跑一阵就卡住或报 ConnectionPoolExhaustedException，大概率不是 Neo4j 服务挂了，而是 Driver 实例被反复创建却没关。Java 客户端的 Driver 是线程安全、长生命周期对象，应该单例复用，而不是每次查库都 GraphDatabase.driver() 一把。
- 全局只初始化一次
Driver，放在 Spring 的@Bean或静态工具类里，用完不调close() - 真正需要手动管理的是
Session和Transaction：用 try-with-resources 包裹session.beginTransaction()，否则事务卡住会拖垮整个连接池 - Spring Data Neo4j 6+ 默认启用响应式驱动（
ReactiveNeo4jClient），若项目没上 WebFlux，反而容易因线程模型错配引发超时——老项目优先选传统Neo4jClient
Cypher 查询返回空：参数传入方式不对或节点标签不匹配
写好 MATCH (u:User)-[r:FOLLOWS]->(t:User) WHERE u.id = $uid RETURN t，Java 里传了 Map.of("uid", 123) 却查不到结果？常见原因不是数据不存在，而是 Cypher 对大小写、空格、类型太敏感。
- 标签名必须完全一致：
User≠user，也不等于"User"（引号在 Cypher 里是字符串字面量，不是标签） - 参数值类型要和节点属性类型对齐：数据库里
id是字符串，Java 就别传Long；反过来，age: INTEGER字段不能传"25"字符串 - 用
session.run()时，别漏掉.list()或.single()触发执行——Cypher 语句只是构建了查询计划，不消费结果就不会真正发请求
关系遍历性能差：没加索引或用了 [:FOLLOWS*] 却不限制深度
查“我关注的人关注的人”写成 MATCH (me:User)-[:FOLLOWS*2..3]->(target) WHERE me.id = $id，数据量一过万就慢到超时。Neo4j 不是靠算力硬扫，它依赖索引 + 关系方向 + 深度控制来剪枝。
- 给高频查询字段建索引：
CREATE INDEX ON :User(id)，关系类型本身不用索引，但起点/终点的属性必须有 -
[:FOLLOWS*]是递归匹配，没上限等于全图扫描；生产环境必须写明范围，比如*1..2，且避免超过 3 层 - 如果只是查“二度关系”，更稳的方式是分两跳写：
MATCH (me:User)-[:FOLLOWS]->(f)-[:FOLLOWS]->(target)，让 planner 能走索引+关系遍历双优化
Spring Data Neo4j 保存失败：实体字段没加 @Id 或 @Relationship 注解错位
用 userRepository.save(new User()) 后数据库没新增节点，或者关系存不进去，十有八九是注解没对准位置。SDN 不靠约定，全靠显式声明。
立即学习“Java免费学习笔记（深入）”；
-
@Id必须标在主键字段上（比如String id），且该字段值不能为null；自增 ID 得配@GeneratedValue，但 Neo4j 本身不支持自增，得自己生成 UUID 或用 Snowflake -
@Relationship必须标在字段上，不是 getter 方法上；类型名要和 Cypher 里写的完全一致：type = "FOLLOWS"，不是"follows" - 双向关系（A→B 和 B←A）要分别用
@Relationship(direction = Relationship.Direction.INCOMING)标明，否则 SDN 只认一个方向
最常被忽略的是：Neo4j 的事务默认不自动回滚运行时异常。Java 里抛了 RuntimeException，但没在 @Transactional 方法里声明，或者用的是底层 Session 而非 Spring 管理的模板，数据就真写进去了——调试时得先清库再试，别信“应该没保存成功”。
