如何設計出漂亮的 Ruby APIs

2023-02-25 23:09:02Python013

如何設計出漂亮的 Ruby APIs,第1张

1.Argument Processing

Ruby 使用了 Symbols 和 Hash 来达到虚拟关键字参数(Pseudo-Keyword Arguments)。这种技巧被广泛应用在 Ruby 的函式库和 Rails 中，增加了阅读性，也很容易使用。

def blah(options)

puts options[:foo]

puts options[:bar]

end

blah(:foo =>"test", :bar =>"test")

Ruby 也可以将参数列当成阵列使用：

def sum(*args)

puts args[0]

puts args[1]

puts args[2]

puts args[3]

end

sum(1,2,3)

如此就可以设计出不固定参数列、十分弹性的 API。类似於 C++ 的 function overloading。在 Rails 中也十分常见这样的 API 设计，例如 link_to 就支援了两种用法：

# USAGE-1 without block

<% link_to 'Posts list', posts_path, :class =>'posts' %>

# USAGE-2 with block

<% link_to posts_path, :class =>'posts' do %>

Posts list

<% end %>

搭配虚拟关键字参数使用的话，可以参考 ActiveSupport#extract_options! 这个小技巧取出 Hash 值。

2. Code Blocks

程式区块(Block)是 Ruby 最重要的特色，除了拿来做迭代(Iteration)之外，也可以包装前後置处理(pre- and Post-processing)，一个最基本的例子就是开档了，一般程序式的写法如下：

f = File.open("myfile.txt", 'w')

f.write("Lorem ipsum dolor sit amet")

f.close

使用 Block 之後，我们可以将 f.close 包装起来，不需要明确呼叫。只要程式区块结束，Ruby 就会自动关档。程式一来因为缩排变得有结构，二来也确定档案一定会关闭(不然就语法错误了)

# using block

File.open("myfile.txt", 'w') do |f|

f.write("Lorem ipsum dolor sit amet")

end

另一个程式区块的技法，是用来当做回呼(Dynamic Callbacks)。在 Ruby 中，程式区块也是物件，於是我们可以将程式区块如透过”注册”的方式先储存下来，之後再依照需求找出来执行。例如在 Sinatra 程式中：

get '/posts' do

#.. show something ..

end

post '/posts' do

#.. create something ..

end

我们”注册”了两个回呼：一是当浏览器送出 GET ‘/posts’ 时，会执行 show something 的程式区块，二是 POST ‘/posts’ 时。

3. Module

模组(Module)是 Ruby 用来解决多重继承问题的设计。其中有一招 Dual interface 值得一提：

module Logger

extend self

def log(message)

$stdout.puts "#{message} at #{Time.now}"

end

Logger.log("test") # as Logger’s class method

class MyClass

include Logger

end

MyClass.new.log("test") # as MyClass’s instance method

Ruby 的 extend 作用是将模组混入(mix-in)进单件类别(singleton class)，於是 log 这个方法除了可以像一般的模组被混入 MyClass 中使用，也可以直接用 Logger.log 呼叫。

要将 Ruby 模组的混入成类别方法(class method)，也有一些常见的 pattern 模式，可以将模组设计可以同时混入实例方法(instance method)和类别方法，请参阅投影片范例。这在撰写 Rails plugin 时非常常用。

4. method_missing?

Ruby 的 Missing 方法是当你呼叫一个不存在的方法时，Ruby 仍然有办法处理。它会改呼叫 method_missing 这个方法，并把这个不存在的方法名称传进去当做参数。这个技巧在 Rails 的 ActiveRecord 中拿来使用：

class Person <ActiveRecord::Base

end

p1 = Person.find_by_name("ihower")

p2 = Person.find_by_name_and_email("ihower", "[email protected]")

其中 find_by_name 和 find_by_email 就是这样的方法。不过这个技巧不是万能丹，它的执行效率并不好，所以只适合用在你没办法预先知道方法名称的情况下。不过也不是没有补救之道，如果同样的方法还会继续呼叫到，你可以在 method_missing 之中用 define_method 或 class_eval 动态定义此方法，那麼下次呼叫就不会进来 method_missing，进而获得效能的改善。事实上，ActiveRecord::Base 的 method_missing 就是这麼做的。(感谢 BigCat 留言提醒我有此补救之道)

另一个 Missing 方法的绝妙 API 设计，是拿来构建 XML 文件：

builder = Builder::XmlMarkup.new(:target=>STDOUT, :indent=>2)

builder.person do |b|

b.name("Jim")

b.phone("555-1234")

b.address("Taipei, Taiwan")

end

# <person>

# <name>Jim</name>

# <phone>555-1234</phone>

# <address>Taipei, Taiwan</address>

# </person>

搭配了区块功能，就能用 Ruby 语法来写 XML，非常厉害。

5. const_missing

除了 method_missing，Ruby 也有 const_missing。顾名思义就是找不到此常数时，会呼叫一个叫做 const_missing 的方法。现实中的例子有 Rails 的 ActiveSupport::Dependencies，它帮助我们不需要先载入所有类别档案，而是当 Rails 碰到一个还不认识的常数时，它会自动根据惯例，找到该档案载入。

我们也可以利用这个技巧，针对特定的常数规则来处理。例如以下的程式会自动将 U 开头的常数，自动转译成 Unicode 码：

class Module

original_c_m = instance_method(:const_missing)

define_method(:const_missing) do |name|

if name.to_s =~ /^U([0-9a-fA-F]{4})$/

[$1.to_i(16)].pack("U*")

else

original_c_m.bind(self).call(name)

end

puts U0123 # ģ

puts U9999 # 香

6. Methods chaining

方法串接是一个很常见的 API 设计，透过将方法的回传值设成 self，我们就可以串接起来。例如：

[1,1,2,3,3,4,5].uniq!.reject!{ |i| i%2 == 0 }.reverse

# 5,3,1

7. Core extension

Ruby 的类别是开放的，可以随时打开它新增一点程式或是修改。即使是核心类别如 Fixnum 或是 Object(这是所有类别的父类别) 都一样。例如 Rails 就定义了一些时间方法在 Fixnum 里：

class Fixnum

def hours

self * 3600 # 一小时有多少秒

end

alias hour hours

end

Time.now + 14.hours

Ruby 的物件模型与元编程(Meta-programming)

在 Ruby 中，所有东西都是物件。甚至包括类别(class)本身也是物件。这个类别物件(class object)是一个叫做 Class 的类别所实例出来的物件。而所有的物件(当然也包括类别物件)，都有一个 metaclass (又叫做 singleton, eigenclass, ghost class, virtual class 等名字)。定义在 metaclass 里的方法，只有该物件能够使用，也就是 singleton method (单件方法)，只有该物件才有的方法。

了解什麼是 metaclass 是 Ruby 元编程的一个重要前提知识。Ruby 元编程最常用的用途，就是因应需求可以动态地定义方法，例如在 Rails ActiveRecord 中常见的 Class Macro 应用。

要能随心所欲动态定义方法的关键重点，就是 variable scope (变数的作用域) 了。例如以下我们透过 class_eval 和 define_method 帮 String 定义了一个 say 方法，注意到整个 variable scope 都是通透的，没有建立新的 scope：

name = "say"

var = "it’s awesome"

String.class_eval do

define_method(name) do

puts var

end

"ihower".say # it’s awesome

class_eval 可以让我们改变 method definition 区域(又叫做 current class)。除了本投影片，建议可以阅读 Metaprogramming in Ruby: It’s Allhe Self 和 Three implicit contexts in Ruby 这两篇文章深入了解 self 和 current class。

8. Class Macro (Ruby’s declarative style)

Class Macro 是 Ruby Meta-programming 非常重要的一个应用，例如在 Rails ActiveRecord 中：

class User <ActiveRecord::Base

validates_presence_of :login

validates_length_of :login,:within =>3..40

validates_presence_of :email

belongs_to :group

has_many :posts

end

Ruby on Rails 正在令整个 Web 开发领域受到震憾。让我们首先了解底层的技术：

Ruby 是一门免费的、简单的、直观的、可扩展的、可移植的、解释的脚本语言，用于快速而简单的面向对象编程。类似于 Perl，它支持处理文本文件和执行系统管理任务的很多特性。

Rails 是用 Ruby 编写的一款完整的、开放源代码的 Web 框架，目的是使用更简单而且更少的代码编写实际使用的应用程序。

作为一个完整的框架，这意味着 Rails 中的所有的层都是为协同工作而构造的，所以您不必自己再重复，可以完全只使用一门单一的语言。在 Rails 中，所有内容（从模板到控制流再到业务逻辑）都是用 Ruby 编写的。Rails 支持基于配置文件和注释的反射（reflection）和运行时扩展。

本文详细介绍了 Rails 的组成部分，并介绍了它的工作原理。

Rails 介绍

关于 Rails，首先需要理解的是它的模型/视图/控制器（model/view/controller，MVC）架构。虽然这种技术不是 Rails 所特有的 —— 甚至不是 Web 应用程序所特有的（相对于其他程序），但是 Rails 具有非常清晰而专一的 MVC 思维方式。如果您并不使用 MVC 方法，那么 Rails 的用处将大为降低（与遵循其模式的情况相比）。

模型

Rails 应用程序的模型部分主要是它所使用的底层数据库。实际上，在很多情形中 Rails 应用程序正是以一种受管理的方式对关系型数据库管理系统（RDBMS）中的数据执行操作的一个途径。

ActiveRecord 类是 Rails 的一个核心组成部分，它将关系型表映射为 Ruby 对象，使其成为控制器可以操作并能在视图中显示的数据。Rails 应用程序特别倾向于使用广为应用的 MySQL 数据库，不过也有与很多其他 RDBMS 的绑定，比如 IBM? DB2?。

如果您愿意，您可以添加 Ruby 代码来在应用程序模型中执行额外的验证，加强数据关联，或者触发其他操作。应用程序的 app/models/ 目录中的 Ruby 文件能够调用 ActiveRecord 的多种验证方法。不过，您也可以将模型代码留作一个存根，而只是依赖保存数据的 RDBMS 的约束。例如，我在这个示例中所开发的应用程序只包含这个骨架模型代码（至少在开始时是）：

清单 1. 骨架模型 app/models/contact.rb

class Contact <ActiveRecord::Base

end

控制器

控制器以其抽象形式执行应用程序的逻辑。也就是说，应用程序的 app/controllers/ 目录中的 Ruby 脚本能把模型数据导入为变量，保存回去，或对其进行修改和处理。不过，控制器不关心用户如何适当地显示或者输入数据。在通常的 MVC 模型中，这可以让用户能够以多种方式与同一控制器进行交互：本地 GUI， Web 界面，以及视力较弱的人使用的语音界面都可以与相同的控制器进行交互。

不过，Rails 不像那样非常通用；相反，它仅局限于在 Web 页中提供和收集数据。虽然如此，但是您可以修改那些 Web 页的布局 —— 颜色、字体、表格、样式表单，等等 —— 与控制器代码无关。

视图

Rails 视图是我们编写 Ruby 代码的地方。Rails 包含有一门用于 .rhtml 的非常好的模板语言，它将纯粹的 HTML 与嵌入的 Ruby 代码组合起来。 Rails 应用程序界面的最表层外观通常是由 CSS 样式表单控制的。.rhtml 格式是一种增强的 HTML。实际上，一个简单的 HTML 文件本身也是一个合法的 RHTML 模板，不过，不应该忽略 RHTML 为您提供的脚本控制。

RHTML 是真正的模板格式 —— 不仅是在 HTML 中嵌入代码的方式 —— 这是一种更为有效的方法。如果您熟悉 PHP，那么可以考虑 PHP 本身与 Smarty 模板之间的对照。也就是说，嵌入的脚本只是将代码与未被解释的 HTML 混合在一起；当需要向客户机输出某些内容时，代码部分仍要负责执行 print 语句。

与之不同的是，模板引擎向 HTML 添加了一组定制的标签，让您能够将条件、循环以及其他逻辑作为增强的 HTML 标记的一部分来表示。

回页首

生成代码

Rails 所提供的工具主要是一组代码生成器。相对于那些强迫我使用严格的工作空间和 IDE 的开发环境，我更喜欢这种方法。 Rails 不会妨碍您，但是却会为您省去大部分手工编程的工作 —— 或者，通过提供“可自由获得的”初步（first-pass）支架（scaffolding），至少帮助您轻松将需要手工编码的工作分为多个部分。

支架概念是 Rails 中的核心概念。非常简单的应用程序可能完全不用编码，让 Rails 在运行时动态地生成客户机 HTML 页面。第一遍生成代码时创建的只是粗略的支架；接下来您可以生成更详细的能够定制的控制器、视图和模型。不过在开始时不需要生成太多。

Rails 对其文件的组织是固定的而且非常普通的，不过这种组织相对严格。如果您试图强行使用其他文件和代码组织方式，那么您可能得付出努力去修改 Rails 环境。再者说，我找不到不使用 Rails 所提供的组织方式的理由；在大部分情况下，它“fits your brain”（Ruby 的支持者喜欢这样讲）。例如，如果您从头开始设计一个框架（至少如果您以“Ruby 方式”思考），那么这些目录名称及其组织可能与您的选择非常接近。

回页首

构建一个简单的应用程序

在 Ruby on Rails Web 站点上有一些教程，可以完整地引导您创建一个简单的 Rails 应用程序（见参考资料）。这里的示例程序与之类似，因为正确开始构建 Rails 应用程序的方式是确定的。由于此介绍的长度相对较短，所以我极力推荐那些较长的教程中的一篇，以使得您能够打好更为全面的基础。

示例应用程序是一个基本的通讯录。它演示了创建应用程序的一般步骤：

生成模型（在此步骤中创建 MySQL 数据库和表）。

生成应用程序（包括生成基本代码和目录）。

启动 Rails（并配置数据库的访问）。

创建一些内容（包括生成支架模型和控制器，并告知控制器去使用那个支架）。

我们将详细研究每一个步骤。

生成 AddressBook 模型

对于任何应用程序，您需要做的第一件事情是为它创建一个存放数据的数据库。技术上这个步骤不必最先进行，不过需要在早期完成；应该在编写任何应用程序代码（甚至是自动生成的代码）之前创建数据库，这应该是显然的。所以，让我们在 MySQL 数据库中创建一个数据库，并在此数据库中创建第一张表。（阅读其他文档以了解如何安装运行 MySQL 或其他 RDBMS。）

我们假定 MySQL 已经安装并且可用。

清单 2. 创建 MySQL 数据库和表

[~/Sites]$ cat AddressBook.sql

CREATE DATABASE IF NOT EXISTS AddressBook

USE AddressBook

CREATE TABLE IF NOT EXISTS contacts (

id smallint(5) unsigned NOT NULL auto_increment,

name varchar(30) NOT NULL default '',

created_on timestamp(14) NOT NULL,

updated_on timestamp(14) NOT NULL,

PRIMARY KEY (id),

UNIQUE KEY name_key (name)

) TYPE=MyISAM COMMENT='List of Contacts'

[~/Sites]$ cat AddressBook.sql | mysql

在这第一张表中有些地方需要注意。最重要的是每一张表都必须拥有一个 id 列，列名称就是 id。Rails 使用主键列 id 来完成各种记录保持和引用任务。域 created_on 和 updated_on 是不需要的，不过，如果您使用了它们，那么 Rails 会自动地“在后台”维护它们；在大部分情况下使用这些时间戳没有什么不好。所以，您还要添加的“真正” 数据就只是通讯录内容的名称。

另一个稍微古怪的方面是，Rails 为不同的内容使用单数和复数的名称。根据上下文，各种条目会被重命名为单数或复数形式。表的名称应该使用复数格式。我没有使用不规则复数单词的经验；datum 和 data 等单词可能会令 Rails 出现问题。

生成 AddressBook 应用程序

既然已经拥有了一个能够交互的数据库，就可以创建 AddressBook 应用程序了。第一个步骤是简单地运行 rails 来生成基本目录和支架代码：

清单 3. 生成基本代码和目录

[~/Sites]$ rails AddressBook

create

create app/apis

create app/controllers

create app/helpers

create app/models

create app/views/layouts

create config/environments

create components

[...]

create public/images

create public/javascripts

create public/stylesheets

create script

[...]

create README

create script/generate

create script/server

[...]

我删减了运行 rails 的输出；所忽略了那些行只是提醒您已经创建的各种文件和目录。在您的系统上试运行它，浏览生成的所有文件。我已经在代码中显示了一些最重要的文件和目录。

运行 Rails

创建了 AddressBook/ 目录和所需要的子目录后，您需要执行一次惟一的初始配置。首先，通过修改 YAML 配置文件来设置数据库，如下：

清单 4. 配置数据库访问

[~/Sites]$ cd AddressBook

[~/Sites/AddressBook]$ head -6 config/database.yml # after editing

development:

adapter: mysql

database: AddressBook

host: localhost

username: some_user

password: password_if_needed

最后，您需要提供数据。Rails 附带了它自己的单一功能的 Web 服务器，即 WEBrick，非常适用于我们的试验。您可能也会遵循 Ruby on Rails Web 站点上的说明来配置 Apache 或者其他服务器，以通过 FCGI（或者普通的 CGI，但是普通的 CGI 将会较慢）向 Rails 应用程序提供服务。

清单 5. 启动 WEBrick 服务器

[~/Sites/AddressBook]$ ruby script/server -d

=>Rails application started on http://0.0.0.0:3000

[2005-03-21 17:57:38] INFO WEBrick 1.3.1

[2005-03-21 17:57:38] INFO ruby 1.8.2 (2004-12-25) [powerpc-darwin7.8.0]

创建一些内容

要在 WEBrick 端口上看到一个欢迎页面，先前的步骤就足够了。例如，在我的本地系统中，现在可以访问 http://gnosis-powerbook.local:3000/。不过，为了操作定制数据库，需要生成稍微多一些代码。可以使用脚本 generate 来完成此任务，这个脚本创建在 AddressBook/ 应用程序目录中：

清单 6. 支架模型和控制器代码的生成

[~/Sites/AddressBook]$ ruby script/generate model contact

exists app/models/

exists test/unit/

exists test/fixtures/

create app/models/contact.rb

create test/unit/contact_test.rb

create test/fixtures/contacts.yml

[~/Sites/AddressBook]$ ruby script/generate controller contact

exists app/controllers/

exists app/helpers/

create app/views/contact