在Ruby生态里操作Neo4j图数据库，neo4jrb提供了一套贴近ActiveRecord使用习惯的适配器。它把图里的节点抽象成带有属性的模型类，把关系抽象成模型之间的关联，让开发者可以用Ruby对象的方式完成大部分图操作，而不必频繁拼接Cypher查询。
一、环境准备与连接配置
使用neo4jrb之前，需要先确保本地或远程已经运行Neo4j服务，并且在Ruby项目中引入相关依赖。最基础的两个gem是neo4j和neo4j-ruby-driver，不过在常见开发中我们直接引用neo4j这个元包即可，它已经整合了neo4jrb的核心功能。
在Gemfile里添加下面这行后执行bundle install，就能把适配器装好。如果是纯Ruby脚本而非Rails工程，也可以直接用gem install neo4j来安装。
# Gemfile gem 'neo4j', '~> 10.0'
建立连接通常在应用启动阶段完成。neo4jrb通过Neo4j::Core::CypherSession连接数据库，可以指定Bolt协议地址、用户名和密码。下面是一段最基础的连接代码，把配置集中放在一个初始化方法里，方便后期维护。
require 'neo4j'
Neo4j::Core::CypherSession.open(
Neo4j::Core::CypherSession::ConnectionProfile.new(
url: 'bolt://127.0.0.1:7687',
username: 'neo4j',
password: 'your_password'
)
)
这种配置方式的优势在于与具体模型解耦，所有模型在定义时无需关心连接细节。如果是在Rails里，可以把上面代码放到config/initializers/neo4j.rb中，应用启动时自动生效。需要注意密码等敏感信息不要硬编码，应读取环境变量或密钥文件。
二、用neo4jrb定义节点模型
neo4jrb的模型定义方式与ActiveRecord非常相似。一个节点模型就是一个继承Neo4j::ActiveNode的类，在类内部用property声明属性，用has_many或has_one声明关系。这样节点在图里既是实体，也是可编程的Ruby对象。
例如我们要建模一个最简单的社交网络，里面有Person节点，每个人有name和age两个属性。下面代码展示了模型声明以及基础验证，验证规则沿用了ActiveModel的风格，降低学习成本。
class Person
include Neo4j::ActiveNode
property :name, type: String
property :age, type: Integer
validates :name, presence: true
validates :age, numericality: { greater_than: 0 }
has_many :out, :friends, type: :FRIEND, model_class: :Person
end
在上面的定义中，has_many指明了从当前节点向外延伸的FRIEND关系，并且关系另一端也是Person类。neo4jrb会自动帮你处理关系方向，查询朋友时直接调用person.friends就能拿到关联对象集合。类型参数type对应图里关系的实际名称，建议用大写明确区分。
除了基础属性，neo4jrb也支持唯一约束。可以通过index定义让某个属性在图中具备唯一性，这会在Neo4j底层创建约束，避免重复节点。比如希望name不能重复，可以写index :name, unique: true。这样在保存时会由数据库保证一致性，比应用层判断更可靠。
三、基础的增删改查操作
模型定义好后，最常用的就是CRUD。neo4jrb对这些操作做了封装，新建节点用create方法，查询用where或find，更新直接改属性后save，删除用destroy。整体写法和ActiveRecord几乎一致，老 Rails 开发者可以无缝切换。
下面示例演示如何创建一个Person并保存，同时处理验证失败的情况。如果age不合法，save会返回false，可以通过errors查看原因，这和ActiveRecord的行为完全相同。
person = Person.new(name: 'Alice', age: 30)
if person.save
puts "保存成功，节点ID：#{person.id}"
else
puts "保存失败：#{person.errors.full_messages.join(', ')}"
end
查询时可以用类方法where构造条件，neo4jrb会把它翻译成Cypher的MATCH语句。例如查找所有年龄大于25的人，并按名字排序，写法如下。注意返回的是可枚举的查询代理对象，不会立刻打数据库，直到真正遍历才执行。
results = Person.where(age: 25..Float::INFINITY).order(name: :asc)
results.each do |p|
puts "#{p.name} - #{p.age}"
end
更新操作也很直接，先查后改即可。删除则调用destroy，不仅会移除节点，还会清理掉相连的孤立关系，避免图里留下悬空边。如果需要批量删除，可以用Person.all.each(&:destroy)但更推荐用Cypher批量指令以提升性能。
四、关系与关联查询实战
图数据库真正的价值在关系。neo4jrb通过关联方法把关系变成一等公民。我们继续用Person的friends关联，演示如何建立关系以及做多层遍历。建立关系用<<操作符或者create关联方法都可以。
下面代码先创建两个人，再把他们设为朋友，最后查出其中一个人的所有朋友名字。neo4jrb在背后生成了正确的MATCH和MERGE语句，保证关系不会重复创建。
alice = Person.create(name: 'Alice', age: 30) bob = Person.create(name: 'Bob', age: 28) alice.friends << bob alice.save alice.friends.each do |friend| puts friend.name end
如果要做二度人脉分析，比如找出朋友的朋友，neo4jrb支持用关联链式调用或写原生Cypher。链式写法可读性高，但在深度大时建议用Cypher。示例如下，用query接口写一段两跳查询，性能更可控。
query = Person.where(name: 'Alice')
.query
.match('(p:Person)-[:FRIEND*2..2]->(fof:Person)')
.return(:fof)
results = query.pluck(:fof)
results.each { |n| puts n.name }
通过上面方式，你可以轻松实现推荐系统、权限传播、依赖分析等典型图场景。相比在关系数据库里用自连接甚至多次查询，neo4jrb配合Neo4j原生图存储，在关联深度增加时优势非常明显。
五、事务与数据一致性
在涉及多个节点和关系写入时，需要事务保证原子性。neo4jrb提供了Neo4j::Transaction包裹代码块，出现异常会自动回滚。对于Rails项目，它也能和现有事务机制协调，不过图事务与SQL事务是分开的。
下面例子展示在一个事务里创建两个人并建立关系，任何一步失败整体撤销，避免图数据出现半成品状态。
Neo4j::Transaction.run do tom = Person.create(name: 'Tom', age: 22) lily = Person.create(name: 'Lily', age: 24) tom.friends << lily raise '模拟失败' if tom.invalid? end
使用事务时需要注意，neo4jrb默认每个写操作都可能开启独立事务，显式用Transaction.run能把多个操作合并。对于高并发写入，还应考虑Neo4j本身锁机制，避免长事务占用资源。合理拆分批量任务，是图应用稳定的关键。
六、在Rails中的集成建议
如果是Rails应用，neo4jrb可以替代ActiveRecord成为主ORM，也可以作为辅存储。官方提供了neo4j-rails集成，让控制器和视图沿用原有习惯。建议在config/application.rb里关闭ActiveRecord，若只用Neo4j，能减少不必要的连接开销。
模型文件放在app/models下即可自动加载，关联与验证写法不变。Rails控制台里也能直接敲Person.count查看节点数。对于复杂报表，可以混用neo4jrb对象和原始Cypher，把灵活性与开发效率结合起来，这也是很多团队落地图数据库的实际路径。