【转】REST on Rails指南

REST on Rails指南1：理解资源

这是来自http://www.softiesonrails.com的REST简明指南。

PART I

在理解REST on Rails之前，有必要先思考一下这个问题：浏览器是如何工作的？在开始使用Rails构建一个网站之前，我对这个问题是这么认为的：

• 首先我会在地址栏输入一个URL，或者点击一个链接
• 然后浏览器会发送一个HTTP请求，并获取响应中的HTML代码
• 最后我会看到经过浏览器渲染的页面

就这么多，我甚至不知道Form是如何工作的，我觉得它跟点击链接没什么不同。

但在现实世界里，HTTP协议有很严格的指令用于定义浏览器应该如何向服务器发送请求，HTTP同HTML完全是两码事，HTML只不过是一种 用于表现页 面内容的标记语言（Markup Language），而HTTP协议则允许浏览器从服务器获取各种类型的数据，HTML只是其中之一。事实上，HTTP协议定义了8中不同类型的请求，尽 管如此，我们最熟悉的可能还是下面两种：

• GET，通过GET请求可以获取Web上的资源，每一个资源都由URL来唯一标识。
• POST，通过发送一组数据到特定的URL来创建一个新资源。

PART II

你可能对我使用“资源”（Resource）这个词感到迷惑不解，事实上我第一次看到这个词时也跟你一样迷惑，但这正是REST的精髓所在，在REST的世界里，整个Web被看作一组资源的集合，而不是一张张的网页，这是什么意思呢？

昨天，我上当当买了几本书，又去维基百科查了几个词条，然后上新浪看了几条新闻，最后又在NBA网站上看了下骑士对马刺的比赛前瞻。

如果你想要理解REST，那么你就要转变你的思维，不要再认为以上这些东西都是一张张的网页，让我们以维基百科为例，我查阅的REST词条事实上并不是一张网页，它是一个资源，我们使用http://zh.wikipedia.org/wiki/ REST访问这个资源，并取得了它的HTML表示，之所以是HTML，是因为浏览器只只是这种方式。

我承认这有些费解，http://zh.wikipedia.org/wiki/  REST怎么可能不是网页呢？事实上，确实不是，它是一个使用URL进行标识的资源，当我使用浏览器来访问它时，我得到了它的HTML表示，但维基百科可能还提供其 他形式的表示，比如一个PDF，一张JPG图片或者别的什么东西，而我之所以得到一个HTML，是因为我的Firefox发送了一个GET请求，并明确的 告诉了服务器，给我一个HTML表示。

再举个更浅显些的例子，比如我向南方航空定了张机票，他们可以通过HTML在浏览器中跟我确认，也可以发短信给我，或者发一封Mail，当然也可以选择最稳妥的方式，打个电话告诉我。事实上就是一种资源，多种表示。

希望经过这番唠叨，你能够理解我所说的，我的机票订单不止是个网页，它是一个资源，当然我可以选择通过浏览器以HTML的方式来查看它。

 

PART III

一旦你接受了Web就是个巨大的资源集合，这些资源可以使用任意多的方式来表示，而HTML只是其中一种时，你离真正掌握REST已经不远了， 但在结束今 天的课程前，我还要在絮叨下：事实上，资源并不总是单个的东西，比如维基百科上介绍REST的文章，一张机票订单或者一堆NBA比赛数据，它也可以是一组 资源的集合，比如中国传统节日列表，你最好的朋友等等，它们都是资源。

现在，你应该已经理解了什么是资源，在下一节，我们将讲解如何通过HTTP来创建（Creation），读取（Reading），更新（Updating）和销毁（Destruction）一个资源。通过上一讲，我认为你树立了这个概念：即Web其实是一组资源而不是网页的集合（如果你还不这么认为，那请你先返回再次阅读第一讲）。这一讲我们将从另一个侧面来讲解为什么要有REST？

 

面向对象设计与分析

如果你曾经学习过面向对象程序设计，那么你很可能会这样开始构建你的新程序：

• 首先，你需要定义你的问题域——你的程序要解决什么问题
• 然后，你会定义一个类，这个类的名字一般是名词
• 接着你会为这个类定义一些方法，方法的名字一般是动词
• 最用，通过调用其它类的方法，你的这个类顺利完成了它的使命

这看起来不错，事实上我曾经这么干了好多年，这种名词加动词的编程方法被成为“RPC”（远程过程调用），虽然我不明白那个Remote（远程）是指什么，但RPC的确是构建面向对象软件的一个重要方法，不过这种方式却并不适合Web开发。

让我们回到远古，假设现在是1992年（或者Web出现之前的随便什么日子），假设有这样的三家公司，他们需要开发这样三种应用：书籍贩卖，机 票贩卖以及 卫星地图浏览。并且他们都遵照了面向对象的设计思想，同时出于长远考虑，他们都认为总有一天会有第三方的软件需要同他们的系统进行交互，因此，他们都实现 了他们各自的API。

现在，假设你的老板分配给你一个任务：为这三个系统设计一个统一的前端，你会怎么做呢？

我想你首先需要学习这三种完全不同的API，然后为每一个API设计一个UI控件，当用户操作UI控件时，对应的API就会被调用，你可能会通过你学到的一些设计模式知识来简化你的工作量，并使你的代码看起来尽可能酷一些。

 

无穷尽的API

当然这只是假设，但即使真的如此，在Web时代，你也不需要去学习那些无穷尽的糟糕API，你所要做的就是在你的电脑上安装一个浏览器，不是 吗？浏览器对 于你将要访问的网站一无所知，但它却能够准确的返回你想要的，你可以通过它购买音乐，预定机票，甚至从任意远的距离来欣赏你家的屋顶。

这很神奇，不是吗？但是让我们设想一下，如果每个网站都有它们自己的API会是什么样子？如果你想在Amazon买本书，浏览器必须知道如何调 用 Amazong.buy()，如果你想查看航班信息，那么浏览器需要知道如何调用UnitedAirlines.CheckFlights()，事实上， 这样通吃所有API的程序永远也不可能被开发出来。

所以这就决定了Web不可能是RPC式的，它只能是REST式的。

 

以资源为中心的设计

那么REST究竟是什么呢？按照维基百科的解释，REST是指Representational State Transfer。这是什么意思呢，简单的说，就是现在每个名词都不再拥有它们各自独一无二的动词了，在REST的世界里，所有名词拥有的动词都是一样 的，并且数量也很有限。换句话说，也就是所有的资源都提供了一组相同的API，这些API的实质就是允许随便什么客户端：

• 获取资源的某种表示
• 创建一个新资源
• 更新已存在的资源
• 销毁一个资源

等一下！那么究竟上面那个API可以让我“购买一本书”呢？搜索“下周二从纽约飞往洛杉矶的航班”又是哪个API完成的呢？

我们将在下一讲回答这个问题，但是如果你已经改变思维，不再认为”买书“就是一个网页，而是开始思考这其实是某个资源的创建，那么我想你其实应该已经知道答案了。

 

通过上一讲，我们明白了为什么Web需要按照REST的方式来设计，而不是传统的面向对象编程的RPC方式，这一讲我们将通过一个实例来演示如何进行REST方式的Web设计，也就是让我们的设计变的RESTful。

 

航空公司的需求

我们假设你为一家航空公司工作，你的任务是为他们设计一个航班管理系统，它的功能包括：

• 允许公司员工通过Web前端来输入航班信息。航班信息包括航班的起飞和降落城市，以及起飞时间等。
• 允许客户通过手机查询他的航班信息。
• 允许第三方通过我们提供的API来获取我们的航班信息。

很没有难度，不是吗？如果你是个急性子，你甚至可能都顾不上将你无懈可击的设计转换成UML，就已经在你IDE的编辑框里输入了如下字符：

class FlightSchedule
def CancelFlight
......

但是慢着，在REST的世界里，我们不再需要操心这些，我们需要做的只有一件事情：定义你的资源

是的，就这一件，因为REST已经为我们定义好了用于操作这些资源的方法。在这个例子里，我们首先会想到这几个资源：airports，airplanes，flights。当然可能还会有其它，但就让我们先从这几个开始吧！我们首先要做的就是为这些资源分配URL，原则只有一个：尽可能的简单明了。

• /airports，通过这个URL可以访问所有的机场资源
• /airplanes，通过这个URL可以访问所有的飞机资源
• /flights，通过这个URL可以访问所有航班资源

还有：

• /airports/pudong，通过这个URL可以获取浦东机场的相关信息
• /airplanes/ZJ3543，通过这个URL可以获取编号为ZJ3543的飞机信息
• /flights/451，通过这个URL咋可以了解到航班451的起飞，降落城市已经起飞时间等信息。

方法已经准备好了

一旦你定义好了你的资源，整个设计也就完成了，因为，REST已经为你准备好了以下四个方法（并且不再需要其它的了）：

• GET，获取资源
• POST，创建一个新资源
• PUT，更新已存在的资源
• DELETE，删除资源

通过HTTP调用这些方法

同样的，我们也不需要关心客户端如何来调用我们的方法，浏览器会帮我们搞定一切。如果你仅仅只是在地址栏敲了个地址，然后按了下回车，浏览器会生成一条HTTP消息，并通过它来调用你输入的URL所代表的资源的GET方法。如果你填写了一个表单，并点击了提交按钮，那么浏览器会将你填在表单中的信息组装成一条HTTP POST消息，并通过它来调用你想访问资源的POST方法。但不幸的是，由于HTML的限制，目前你无法通过浏览器来调用资源的PUT和DELETE方法，不过这不重要，GET和POST对我们已经足够了。好了，我们的基于REST的设计就这么完成了，下一讲，我们将演示如何使用Rest on Rails来快速优美的实现我们的设计。

 

通过上一讲我们了解到，RESTful设计的关键就是定义系统中的资源，这一讲我们将学习在Rails中，如何将请求路由到我们的资源，以及我们应该如何来处理它。

不过，有一点需要先说明：REST并不是Rails的一部分，在Rails出现之前，REST的概念已经存在很多年了，并且REST的应用也并不局限于Web，事实上，它也可以应用到其它各种应用软件的开发中。

 

资源就是控制器

在我们正式开始之前，我们需要首先明确，在Rails中，资源和model并不总是一对一的关系，有时资源仅仅只是你应用逻辑中的一个实体的抽 象，并不需要 映射到你的数据库。但资源跟控制器总是一对一的，也就是每个资源都必须有一个与它相对应的控制器，并且你需要重新理解控制器，现在控制器只是REST接口 的具体实现，它的全部作用就是根据客户的请求返回资源的某种表示（HTML，XML等）。

所以，就像第2章讲的，我们不在需要去设计那无穷尽的API了，现在我们的控制器只需要定义7个方法：

• show，处理针对单个资源的GET请求
• create，处理POST请求，并将创建一个新资源
• update，处理PUT请求，并更新指定的资源
• destroy，处理DELETE请求，销毁一个资源
• index，处理针对多个资源的GET请求
• new，GET请求，返回一个用于创建资源的表单，
• edit，GET请求，返回一个用于更新资源的表单

Rails 会帮助我们将用户的请求路由到某个合适的方法，当然，你并不需要实现这全部的7个方法，如果你的系统不允许用户创建和修改资源，那么你只需要实现 index和show方法就可以了。

不过更有可能的一种情况是你觉得这7个方法根本不够，你当然可以选择向控制器添加新的方法，但这其实是因为你的设计遗漏了一些资源，因为我建议，在你向控制器添加新方法之前，最好先重新考虑下你的设计。

方法已经定义好了，下一步的任务就是将用户的请求路由到指定的方法，在router.rb中，你可能会看到这样的路由：

map.connect '/airports/:action/:id', :controller = 'airports'

这条语句将映射/airports/open/45到airports控制器的open方法，你可以通过params[:id]获取URL中的 参数45。但是REST路由有些特殊，它需要同时考虑URL和请求的类型，因此同样是发往/airports/1的请求，如果是GET请求，它需要被路由 到airports的show方法，而DELETE请求则需要被路由到DELETE方法。

不过幸运的是，从Rails1.2开始，我们不再需要通过map.connect来手动的配置REST路由，map.resources会帮我们搞定一切：

map.resources 'airports'

这句话将创建如下的路由规则：

• 针对/airports/ 的POST请求将被路由到create方法
• 针对/airports/1 的GET请求将被路由到show方法
• 针对/airports/1的PUT请求被路由到update方法
• 针对/airports/1 的DELETE请求被路由到destroy方法
• 针对/airports/ 的GET请求被路由到index方法
• 针对/airports/new 的GET请求被路由到new方法
• 针对/airports/1;edit 的GET请求被路由到edit方法

注意：最后一条逗号分隔的URL看起来很丑陋，但它们在Rails1.2.3中是合法的，不过不用苦恼，它们将在Rails2.0中被去除

现在我们已经完成了URL的路由，下面我们需要做的就是实现这些方法：
不过先别着急着码代码，从Rails1.2开始，我们有了一个新的生成器（generator）：scaffold_resource，使用它我们可以很轻松的生成一个符合REST规范的Rails框架,它包含：

• 资源所对应的model
• 资源的migration文件
• 资源所对应的控制器，控制器已经包含了REST所需的7个方法的实现
• 这7个方法所对应的RHTML文件
• 一条映射用户请求的路由

让我们仍然从第三讲的例子开始，首先创建一个新程序，然后为它添加一个airport资源：

D:\study>rails REST
D:\study>cd REST
D:\study\REST>ruby script/generate scaffold_resource airport name:string designator:string
D:\study\REST>rake db:migrate
D:\study\REST>ruby script/server

修改database.yml文件，设置好你的数据库链接，然后执行：

现在定位你的浏览器到http://localhost:3000/airports/new,你应该已经可以创建一个新机场了，是不是很神奇？现在，让我们来看看airports_controller.rb，所有的东西都在那了。

你应该会在控制器代码中看到一些奇怪的respond_to块，这正是我们整个REST实现的关键所在，我们将在下一讲详细探讨respond_to的细节。

 

通过上一讲，我们已经对REST on Rails的基本框架有所了解，但是它是如何实现根据客户端的请求类型来返回不同类型的资源表示的呢？这就是我们这一讲所要讲的，秘密就在于respond_to。首先让我们来看看我们在上一讲中生成的airports控制器的代码：

class AirportsController < ApplicationController
  def index
    @airports = Airport.find :all
    respond_to do |format|
      format.html # do nothing, allow Rails to render index.rhtml
      format.js # do nothing, allow Rails to render index.rjs
      format.xml { render :xml => @airports.to_xml }
    end
  end
end

我们以index方法为例，其它方法的实现大同小异。第一行代码很容易理解，获取所有的机场信息，但是接下来的代码就比较费解了，而这也正是REST on Rails的关键所在，那个respond_to是做什么的呢？

我们知道，在HTTP协议中，客户端会在他们的HTTP首部包含一些元信息（meta-information)，这些元信息按照“字段：值” 的方式来组织，HTTP协议预定义了很多标准字段，其中的一个字段就是“Accept-type“,它代表发送请求的客户端能够支持或者说理解的资源表示 类型，如果没有为这个键指定值，服务端会认为客户端能够理解标准的HTML文档，当然，客户端可以为这个字段指定任意的符合MIME规范的类型值，假设客 户端设置这个字段为”Accept-Type: text/xml“，则服务端必须返回资源的XML表示。

所以respond_to事实上就是根据HTTP首部的Accept-Type字段来决定向客户端返回那种类型的资源表示，如果不使用respond_to，我们的实现可能会是这个样子：

class AirportsController < ApplicationController

  # Pretend that Rails will call our index action,
  # and will pass in the value of the Accept-Type header
  def index(client_format)
    @airports = Airport.find :all

    if client_format == “text/html”
      # TO DO: render the default template

    elsif client_format == “application/javascript”
      # TO DO: return some javascript

    elsif client_format == “application/xml” || client_format == “text/xml”
      # TO DO: return some XML back the client

    # … more elsif statements here for each MIME type you want to support
    end
  end
end

这很丑陋，不是吗？但它却相当直观，我想respond_to的作者可能最初也是这么写的，或者这段代码至少在他的脑海中闪现过，但立刻就被他否定了，因为它实在是太蹩脚了，所以他对这段代码进行了重整，于是有了respond_to。

但是Block内的代码看起来仍然比较古怪，事实上，如果我们理解了respond_to的设计思想，那么这段代码看起来就非常理所当然了。

respond_to基于这样的思想设计的，你不需要知道客户端的请求到底是那种类型，你只需要告诉Rails你准备支持那些类型的请求，Rails会自动帮你处理剩下的事情。

所以，这里我们告诉Rails，对于HTML和JS类型的请求，采用默认的实现，而对XML则使用我们在Block内提供的实现。

指南到这里就结束了，篇幅有限，我们只能对REST的基本概念和它在Rails中的简单实现做一个基本的介绍，REST on Rails的世界还有更多的东西等着你去探索。

我建议你尝试动手创建一个Rails应用，然后试试scaffold_resource生成器，阅读并试着理解生成的代码，然后尝试修改view和controller，事实上，比你想象的要简单的多，不是吗？

祝你好运同时期待你的反馈！