用途
本技能用于在 Spring Boot 应用中使用 Spring Data Neo4j（SDN 7.x/8.x）访问 Neo4j 图数据库。适用场景包括：配置 Spring Boot 与 Neo4j 连接、编写 @Node 实体与 @Relationship/@RelationshipProperties 映射、定义 Neo4jRepository 或 ReactiveNeo4jRepository 接口、在仓储方法上使用 @Query 编写 Cypher、使用 Spring 投影、通过 Neo4jClient 或 Neo4jTemplate 执行自定义查询、在 Spring 应用中使用 Spring AI Neo4jVectorStore 做向量检索，以及事务管理、审计与乐观锁。
不适用场景：不使用 Spring 的原生 Java 驱动（应参考 neo4j-driver-java-skill）、Cypher 查询编写（neo4j-cypher-skill）、驱动版本升级（neo4j-migration-skill）、GDS 算法（neo4j-gds-skill）。
版本矩阵
资料提供如下对应关系：
- SDN 8.0.x：Spring Boot 3.3.x / 3.4.x，Spring Framework 6.2.x，Java 17+，Neo4j 5.15+
- SDN 8.1.x：Spring Boot 3.4.x+，Spring Framework 7.0.x，Java 17+，Neo4j 5.15+
- SDN 7.5.x：Spring Boot 3.2.x，Spring Framework 6.1.x，Java 17+，Neo4j 4.4+
使用 spring-boot-starter-data-neo4j 会同时引入 SDN 与驱动；使用 Spring Boot BOM 时无需显式指定 SDN 版本。
安装与配置
Maven 依赖为 org.springframework.boot:spring-boot-starter-data-neo4j；Gradle 使用 implementation 'org.springframework.boot:spring-boot-starter-data-neo4j'；响应式栈需额外加入 spring-boot-starter-webflux。
application.yml 标准配置包括 spring.neo4j.uri（默认 bolt://localhost:7687）、authentication.username、authentication.password，以及 spring.data.neo4j.database。Aura 需使用 TLS（uri 形如 neo4j+s://xxxx.databases.neo4j.io）。资料强调凭据应存放于 .env，不要硬编码，并确认 .env 已加入 .gitignore。
实体映射
涵盖内部生成 ID（@Id @GeneratedValue 的 Long 类型元素 ID）、UUID 业务键（generatorClass = GeneratedValue.UUIDStringGenerator.class，并配合 @Version 乐观锁）、用户自赋值键（无 @GeneratedValue）、多静态标签（primaryLabel 与 labels）以及运行时动态标签（@DynamicLabels）。@Property 可指定自定义属性名。
关系属性
当关系本身携带数据时使用 @RelationshipProperties，类中需包含 @RelationshipId（内部关系 ID，必填）与被 @TargetNode 标记的另一端实体。
仓储接口
Neo4jRepository 提供基础 CRUD 与派生查询（如 findByName、findByBirthYearBetween、findByNameContainingIgnoreCase、countByBirthYearGreaterThan、deleteByName）。@Query 支持绑定参数（$param，资料明确要求绝不拼接用户输入，始终使用 $paramName）、分页（value + countQuery 返回 Page）、以及返回关系丰富实体（RETURN m, collect(r), collect(p)）。分页排序可用 Pageable、Sort 及 findTop10ByOrderByNameAsc 等派生方法。
投影
支持闭合接口投影（可优化查询）、DTO record 投影（Java 17+ 推荐）、动态投影（方法接收 Class<T> 类型参数）以及使用 SpEL 的开放投影（会禁用查询优化）。
响应式与自定义实现
ReactiveNeo4jRepository 返回 Mono/Flux。资料明确要求不要在同一应用上下文中混用命令式与响应式数据库访问。当 @Query 不足时使用片段模式：定义自定义接口、以 Impl 结尾的实现类（内部使用 Neo4jClient），再由主仓储接口组合继承。Neo4jClient 支持绑定参数、fetchAs/mappedBy 映射、one/all/run 等操作。
事务
Neo4jTransactionManager 自动配置。@Transactional 应加在具体服务类而非接口上，可用 readOnly 提示只读；未显式限定符时不要与 JPA PlatformTransactionManager 混用。
Spring AI 向量存储
依赖为 org.springframework.ai:spring-ai-starter-vector-store-neo4j。application.yml 中配置 spring.ai.vectorstore.neo4j 的 initialize-schema（首次运行创建向量索引）、index-name、embedding-dimension（须与嵌入模型一致）、distance-type（cosine 默认或 euclidean）、label、embedding-property，并复用 spring.neo4j.* 连接配置，要求 Neo4j 5.15+。使用 VectorStore 的 add 存储文档，similaritySearch 支持 topK、similarityThreshold 及 filterExpression 元数据过滤。
关系加载规则
SDN 默认按配置深度（默认 1 跳）即时加载关联实体。更深图需显式 @Query 控制加载内容，且在 RETURN 中必须包含 collect(r), collect(p)，SDN 才能正确映射 @RelationshipProperties。
常见错误
资料列出映射异常（未扫描实体）、加载后关系为 null（深度不足）、N+1 查询、OptimisticLockingFailureException（并发写版本过期）、响应式与命令式混用的 IllegalStateException、投影字段为 null（getter 名不匹配）、@Query 返回关系为空（缺 collect）、删除有关系的节点失败（需 DETACH DELETE）、事务不回滚（@Transactional 加在接口上）等问题及对应修复方式。
检查清单要点
@Node 使用显式标签字符串；@Id @GeneratedValue 或业务键配合 @Version；@RelationshipProperties 含 @RelationshipId 与 @TargetNode；@Relationship 显式声明方向；@Query 使用 $paramName 且不拼接字符串；关系丰富查询返回 collect(r), collect(p)；application.yml 设置数据库名；业务键在数据库中存在唯一约束；@Transactional 加在具体服务类；不混用命令式与响应式；凭据使用环境变量；Spring AI 首次运行设置 initialize-schema: true。