Neo4j Java Driver v6 使用技能，面向在 Java/Kotlin 代码中连接 Neo4j（Aura 或自建）的场景。
【适用与不适用】 适用于搭建驱动、会话与事务，调试结果处理、错误恢复与连接池问题，以及异步（CompletableFuture）或响应式（Project Reactor / RxJava）访问。不适用于 Cypher 编写与优化、驱动版本升级、Spring Data Neo4j（@Node、@Relationship、Neo4jRepository），这些分别对应其他技能。
【依赖配置】 Maven：groupId org.neo4j.driver，artifactId neo4j-java-driver，示例版本 6.3.0。Gradle：implementation 'org.neo4j.driver:neo4j-java-driver:6.3.0'。最新版本可查中央仓库。版本要点：6.2.0（2026-06）支持 Neo4j UUID 类型与 Bolt 6.1，结果摘要含 QueryProfile；6.2.1（2026-08）修复 UUID 值的 Value#asObject()，Neo4j 2026.08 服务端内置 6.2.1、2026.07 内置 6.2.0；6.3.0（2026-09）提供属性加密预览（客户端信封加密，driver.propertyEncryption()）。服务端 UUID 类型与 uuid() 构造器随 Neo4j 2026.08 发布，连接这些服务端需驱动 >= 6.2.1。
【连接配置】 标准做法是不硬编码凭据，从环境变量读取 NEO4J_URI、NEO4J_USERNAME、NEO4J_PASSWORD、NEO4J_DATABASE，并可提供默认值。Spring Boot 可通过 @Value("${spring.neo4j.uri}") 或 application.properties 注入。
【驱动生命周期】 每个应用一个 Driver，线程安全但创建开销大，需 AutoCloseable 或 try-with-resources；创建后可调用 verifyConnectivity() 快速失败。URI 方案包括 neo4j://localhost（未加密、集群路由）、neo4j+s://（TLS+集群路由，Aura）、bolt://localhost:7687（未加密、单实例）、bolt+s://（TLS、单实例）。认证方式有 AuthTokens.basic、bearer、kerberos、none。
【API 选择】 driver.executableQuery() 为多数查询默认，支持自动重试、结果即时（eager）；session.executeRead/Write() 适合大结果与回调控制，支持自动重试与流式；session.beginTransaction() 适合跨方法或外部协调，不自动重试；session.run() 适合自管理事务的查询（CALL IN TRANSACTIONS），6.1+ 支持对幂等错误的单次立即重试，可按驱动或会话禁用。CALL { … } IN TRANSACTIONS 与 USING PERIODIC COMMIT 自管理事务，只能用 session.run()，executableQuery 与 executeRead/Write 会失败。
【托管事务】 Session 非线程安全，每请求/线程一个并及时关闭。回调内必须消费 Result（惰性游标随事务关闭，回调返回后读取会抛 ResultConsumedException），应先收集为 List。回调不得有副作用（可能重试），重试安全的写入应使用 MERGE 而非 CREATE。executeRead 路由到副本，executeWrite 路由到主节点。可用 TransactionConfig 设置超时与元数据（在 SHOW TRANSACTIONS 可见）。
【显式事务】 适用于跨方法或需外部协调、且不自动重试的场景；rollback() 是网络调用，应单独 try/catch 并用 addSuppressed 保留原异常。commit 抛出 ServiceUnavailableException 时存在提交不确定性，写入应设计为幂等（MERGE + 唯一约束）。
【错误处理与数据类型】 可捕获 ServiceUnavailableException、SessionExpiredException、TransientException、Neo4jException（code() 给 GQL 状态码）；托管事务自动重试 TransientException。Cypher 类型到 Java 访问器有对应表（asLong/asInt、asDouble、asString、asBoolean、asList、asMap、asNode、asRelationship、asLocalDate、asZonedDateTime、asUUID 等）。空值分两种情况：键存在但值为图 null 时 asString() 抛 Uncoercible；键缺失时返回 Value.NULL 哨兵，asString() 抛 NoSuchElementException。可选列应先 containsKey 检查，图 null 可用默认值重载。
【对象映射】 可将结果映射到 Java record/类，字段名与 RETURN 别名大小写敏感匹配；嵌套映射可返回 map 投影并对列表使用 COLLECT {}；Cypher 返回的额外属性会被忽略。
【性能模式】 始终指定数据库名以避免 home-db 往返；读取路由到副本；用 UNWIND 批量写入，参数只能是允许的叶子类型（String、Long/Integer/Short/Byte、Double/Float、Boolean、List、Map、null），自定义对象与 LocalDate 需先转换；循环写入应合并到单个事务；连接池默认 100，可用 withMaxConnectionPoolSize 与 withConnectionAcquisitionTimeout 调整。
【常见错误与检查清单】 资料列出常见错误及修复方式，如字符串拼接 Cypher（应始终用参数）、省略数据库名、每请求新建驱动、跨线程共享会话、回调返回 Result、管理事务回调有副作用、向 UNWIND 传自定义对象、图 null/缺失键上调用 asString()、裸 rollback、假设 commit 失败即未提交、在异步回调内阻塞、异步错误路径未关闭会话、循环内一次写一个事务、用 executeWrite 做读等。检查清单覆盖：启动创建并在关闭时销毁单一 Driver、创建后 verifyConnectivity()、每次指定数据库名、使用参数、回调内消费结果、回调无副作用、会话 try-with-resources、异步会话成功与错误路径均关闭、commit 的 ServiceUnavailable 按不确定处理、UNWIND 参数为 List<Map<String,Object>>、访问可选列前 containsKey。
【参考】 可按需加载 async-reactive.md（CompletableFuture、RxSession 与 Flux.usingWhen、死锁避免）、property-encryption.md（6.3.0+ 属性加密预览：信封配置、密钥封装服务 local/AWS KMS/Azure Key Vault/GCP KMS、密钥管理、AAD 加解密）、advanced-config.md（Config.builder 选项、TLS、通知过滤、会话级认证、用户模拟、跨会话书签、空间类型）。官方文档含 Java Driver 手册与 API 参考链接。