Hanami::Model（已弃用）

重要通知

注意：Hanami::Model 是 Hanami 1.x 的持久化层。此库将不再接收任何更新。

对于 Hanami 2.x 的持久化层，请参阅 hanami/db

联系方式

主页：http://hanamirb.org
邮件列表：http://hanamirb.org/mailing-list
API 文档：http://rubydoc.info/gems/hanami-model
聊天：https://chat.hanamirb.org

Ruby 版本

Hanami::Model 仅支持 Hanami 1.x，以及 Ruby (MRI) 2.6 和 2.7。

安装

将以下行添加到你的应用程序的 Gemfile 中：

gem 'hanami-model'

然后执行：

$ bundle

或者自行安装：

$ gem install hanami-model

使用方法

此类提供了一个 DSL 来配置连接。

require 'hanami/model'
require 'hanami/model/sql'

class User < Hanami::Entity
end

class UserRepository < Hanami::Repository
end

Hanami::Model.configure do
  adapter :sql, 'postgres://username:password@localhost/bookshelf'
end.load!

repository = UserRepository.new
user       = repository.create(name: 'Luca')

puts user.id # => 1

found = repository.find(user.id)
found == user # => true

updated = repository.update(user.id, age: 34)
updated.age # => 34

repository.delete(user.id)

概念

实体

一个由其身份定义的模型领域对象。参见 Eric Evans 的"领域驱动设计"。

实体是应用程序的核心，实现了部分领域逻辑。它是一个小巧、内聚的对象，表达了连贯且有意义的行为。

它只处理一个与应用程序领域相关的责任，而不关心诸如持久化或验证等细节。

这种简单的设计允许开发者专注于行为，或者说消息传递，这是面向对象编程的精髓。

require 'hanami/model'

class Person < Hanami::Entity
end

仓库

一个在实体和持久化层之间进行调解的对象。它提供了一个标准化的 API 来查询和执行数据库命令。

仓库是与存储无关的，所有的查询和命令都委托给当前的适配器。

这种架构有几个优点：

应用程序依赖于标准 API，而不是低级细节（依赖倒置原则）
应用程序依赖于稳定的 API，即使存储发生变化也不会改变
开发者可以推迟存储决策
将持久化逻辑限制在低层
多个数据源可以在应用程序中轻松共存

当一个类继承自 Hanami::Repository 时，它将获得以下接口：

#create(data) – 为给定的数据（或实体）创建一条记录
#update(id, data) – 通过设置给定的数据（或实体）来更新对应于给定 id 的记录
#delete(id) – 删除对应于给定 id 的记录
#all - 从关系中获取所有实体
#find - 通过主键从关系中获取一个实体
#first - 从关系中获取第一个实体
#last - 从关系中获取最后一个实体
#clear - 删除关系中的所有记录

关系是一组同质的记录。 对于 SQL 数据库来说，它对应于一个表，对于 MongoDB 来说，它对应于一个集合。

所有的查询都是私有的。这个决定迫使开发者定义意图明确的 API，而不是在仓库外部泄露存储 API 细节。

看看下面的代码：

ArticleRepository.new.where(author_id: 23).order(:published_at).limit(8)

这是糟糕的，原因有很多：

调用者对仓库的内部机制有深入的了解。
调用者在多个抽象层次上工作。
它没有表达明确的意图，只是一系列方法的链式调用。
调用者不容易被独立测试。
如果我们改变存储，我们被迫改变调用者的代码。

有一个更好的方法：

require 'hanami/model'

class ArticleRepository < Hanami::Repository
  def most_recent_by_author(author, limit: 8)
    articles.where(author_id: author.id).
      order(:published_at).
      limit(limit)
  end
end

这是一个巨大的改进，因为：

调用者不知道仓库如何获取实体。
调用者工作在单一的抽象层次上。它甚至不知道记录的存在，只与实体打交道。
它表达了明确的意图。
调用者可以很容易地被独立测试。只需要存根这个方法即可。
如果我们改变存储，调用者不会受到影响。

映射

Hanami::Model 可以自动映射关系的列和实体的属性。当使用 sql 适配器时，必须在调用 Hanami::Model.load! 之前引入 hanami/model/sql，以确保关系正确加载。

然而，在某些情况下，列名和属性名可能不匹配（主要是在遗留数据库中）。

require 'hanami/model'

class UserRepository < Hanami::Repository
  self.relation = :t_user_archive

  mapping do
    attribute :id,   from: :i_user_id
    attribute :name, from: :s_name
    attribute :age,  from: :i_age
  end
end

注意： 仅当由于命名不匹配导致自动映射失败时，才应使用此功能。

约定

仓库必须以实体命名，在实体类名后加上 "Repository"（例如 Article => ArticleRepository）。

线程安全

Hanami::Model 在运行时是线程安全的，但在加载过程中不是。映射器在内部编译一些代码，因此请确保在应用程序启动之前安全地加载它。

Mutex.new.synchronize do
  Hanami::Model.load!
end

当在 Hanami 应用程序中使用 Hanami::Model 时，这是不必要的。

功能

时间戳

如果实体具有以下访问器：:created_at 和 :updated_at，它们将在实体被持久化时自动更新。

require 'hanami/model'
require 'hanami/model/sql'

class User < Hanami::Entity
end

class UserRepository < Hanami::Repository
end

Hanami::Model.configure do
  adapter :sql, 'postgresql://localhost/bookshelf'
end.load!

repository = UserRepository.new

user = repository.create(name: 'Luca')

puts user.created_at.to_s # => "2016-09-19 13:40:13 UTC"
puts user.updated_at.to_s # => "2016-09-19 13:40:13 UTC"

sleep 3
user = repository.update(user.id, age: 34)
puts user.created_at.to_s # => "2016-09-19 13:40:13 UTC"
puts user.updated_at.to_s # => "2016-09-19 13:40:16 UTC"

配置

日志记录

为了记录数据库操作，你可以配置一个日志记录器：

Hanami::Model.configure do
  # ...
  logger "log/development.log", level: :debug
end

它接受以下参数：

stream：Ruby StringIO 对象 - 可以是 $stdout 或文件路径（例如 "log/development.log"）- 默认为 $stdout
:level：日志级别 - 可以是：:debug、:info、:warn、:error、:fatal、:unknown - 默认为 :debug
:formatter：日志格式化器 - 可以是：:default 或 :json - 默认为 :default

版本控制

Hanami::Model 使用语义化版本 2.0.0

贡献

Fork 项目 ( https://github.com/hanami/model/fork )
创建你的特性分支 (git checkout -b my-new-feature)
提交你的更改 (git commit -am 'Add some feature')
推送到分支 (git push origin my-new-feature)
创建新的 Pull Request

版权

本项目以前称为 Lotus（lotus-model）。