Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

bring Chinese README up to speed, fixes #197

Signed-off-by: Konstantin Haase <konstantin.mailinglists@googlemail.com>
  • Loading branch information...
commit 781891bf126b20a2d2be716a2436e00a767c27d4 1 parent 1461f61
@nouse nouse authored rkh committed
Showing with 862 additions and 97 deletions.
  1. +862 −97 README.zh.rdoc
View
959 README.zh.rdoc
@@ -1,7 +1,9 @@
= Sinatra
-<i>注:本文档仅仅是英文版的翻译,会出现内容没有及时更新的情况发生。如有不一致的地方,请以英文版为准。</i>
+<i>注:本文档仅仅是英文版的翻译,会出现内容没有及时更新的情况发生。
+如有不一致的地方,请以英文版为准。</i>
-Sinatra是一个基于Ruby语言,以最小精力为代价快速创建web应用为目的的DSL(领域专属语言):
+Sinatra是一个基于Ruby语言,以最小精力为代价快速创建web应用为目的的DSL(
+领域专属语言):
# myapp.rb
require 'sinatra'
@@ -13,10 +15,12 @@ Sinatra是一个基于Ruby语言,以最小精力为代价快速创建web应用
安装gem然后运行:
gem install sinatra
- ruby rubygems myapp.rb
+ ruby -rubygems myapp.rb
在该地址查看: http://localhost:4567
+推荐同时运行<tt>gem install thin</tt>,Sinatra会优先选择thin作为服务器。
+
== 路由
在Sinatra中,一个路由是一个HTTP方法与URL匹配范式的配对。
@@ -38,11 +42,14 @@ Sinatra是一个基于Ruby语言,以最小精力为代价快速创建web应用
.. 消灭一些事物 ..
end
+ options '/' do
+ .. 满足一些事物 ..
+ end
+
路由按照它们被定义的顺序进行匹配。
第一个与请求匹配的路由会被调用。
-路由范式可以包括具名参数,
-可通过<tt>params</tt>哈希表获得:
+路由范式可以包括具名参数,可通过<tt>params</tt>哈希表获得:
get '/hello/:name' do
# 匹配 "GET /hello/foo" 和 "GET /hello/bar"
@@ -121,7 +128,7 @@ Sinatra是一个基于Ruby语言,以最小精力为代价快速创建web应用
=== 返回值
-一个路由代码块的返回值最少决定了返回给HTTP客户端的响应体
+路由代码块的返回值至少决定了返回给HTTP客户端的响应体
或者至少决定了在Rack堆栈中的下一个中间件。
大多数情况下,将是一个字符串,就像上面的例子中的一样。
但是其他值也是可以接受的。
@@ -144,6 +151,47 @@ Rack body对象或者HTTP状态码:
get('/') { Stream.new }
+=== 自定义路由匹配器
+
+如上显示,Sinatra内置了对于使用字符串和正则表达式作为路由匹配的支持。
+但是,它并没有只限于此。
+你可以非常容易地定义你自己的匹配器:
+
+ class AllButPattern
+ Match = Struct.new(:captures)
+
+ def initialize(except)
+ @except = except
+ @caputres = Match.new([])
+ end
+
+ def match(str)
+ @caputres unless @except === str
+ end
+ end
+
+ def all_but(pattern)
+ AllButPattern.new(pattern)
+ end
+
+ get all_but("/index") do
+ # ...
+ end
+
+请注意上面的例子可能超工程了,
+因为它也可以用更简单的方式表述:
+
+ get // do
+ pass if request.path_info == "/index"
+ # ...
+ end
+
+或者,使用消极向前查找:
+
+ get %r{^(?!/index$)} do
+ # ...
+ end
+
== 静态文件
静态文件是从 <tt>./public</tt> 目录提供服务。你可以通过设置<tt>:public</tt>
@@ -153,7 +201,7 @@ Rack body对象或者HTTP状态码:
请注意public目录名并没有被包含在URL之中。文件
<tt>./public/css/style.css</tt>是通过
-<tt>http://example.com/css/style.css</tt>地址访问
+<tt>http://example.com/css/style.css</tt>地址访问的
== 视图 / 模板
@@ -162,15 +210,15 @@ Rack body对象或者HTTP状态码:
set :views, File.dirname(__FILE__) + '/templates'
-请记住一件非常重要的事情,你只可以使用符号引用模板
+请记住一件非常重要的事情,你只可以通过符号引用模板
即使它们在子目录下
(在这种情况下,使用 <tt>:'subdir/template'</tt>)。
-你必须使用一个符号,因为渲染方法会直接地渲染
-任何传入的字符串
+你必须使用一个符号,
+因为渲染方法会直接地渲染任何传入的字符串
=== Haml模板
-需要引入haml gem/library以渲染 HAML 模板:
+需要引入 <tt>haml</tt> gem/library以渲染 HAML 模板:
# 你需要在你的应用中引入 haml
require 'haml'
@@ -206,7 +254,7 @@ Rack body对象或者HTTP状态码:
=== Erubis
-需要引入erubis gem/library以渲染 erubis 模板:
+需要引入 <tt>erubis</tt> gem/library以渲染 erubis 模板:
# 你需要在你的应用中引入 erubis
require 'erubis'
@@ -217,9 +265,20 @@ Rack body对象或者HTTP状态码:
渲染 <tt>./views/index.erubis</tt>
+使用Erubis代替Erb也是可能的:
+
+ require 'erubis'
+ Tilt.register :erb, Tilt[:erubis]
+
+ get '/' do
+ erb :index
+ end
+
+使用Erubis来渲染 <tt>./views/index.erb</tt>。
+
=== Builder 模板
-需要引入 builder gem/library 以渲染 builder templates:
+需要引入 <tt>builder</tt> gem/library 以渲染 builder templates:
# 需要在你的应用中引入builder
require 'builder'
@@ -232,7 +291,7 @@ Rack body对象或者HTTP状态码:
=== Nokogiri 模板
-需要引入 nokogiri gem/library 以渲染 nokogiri 模板:
+需要引入 <tt>nokogiri</tt> gem/library 以渲染 nokogiri 模板:
# 需要在你的应用中引入 nokogiri
require 'nokogiri'
@@ -245,7 +304,7 @@ Rack body对象或者HTTP状态码:
=== Sass 模板
-需要引入 haml gem/library 以渲染 Sass 模板:
+需要引入 <tt>haml</tt> 或者 <tt>sass</tt> gem/library 以渲染 Sass 模板:
# 需要在你的应用中引入 haml 或者 sass
require 'sass'
@@ -269,7 +328,7 @@ Rack body对象或者HTTP状态码:
=== Scss 模板
-需要引入 haml gem/library 来渲染 Scss templates:
+需要引入 <tt>haml</tt> 或者 <tt>sass</tt> gem/library 来渲染 Scss templates:
# 需要在你的应用中引入 haml 或者 sass
require 'sass'
@@ -293,7 +352,7 @@ Rack body对象或者HTTP状态码:
=== Less 模板
-需要引入 less gem/library 以渲染 Less 模板:
+需要引入 <tt>less</tt> gem/library 以渲染 Less 模板:
# 需要在你的应用中引入 less
require 'less'
@@ -306,7 +365,7 @@ Rack body对象或者HTTP状态码:
=== Liquid 模板
-需要引入 liquid gem/library 来渲染 Liquid 模板:
+需要引入 <tt>liquid</tt> gem/library 来渲染 Liquid 模板:
# 需要在你的应用中引入 liquid
require 'liquid'
@@ -324,7 +383,7 @@ Rack body对象或者HTTP状态码:
=== Markdown 模板
-需要引入 rdiscount gem/library 以渲染 Markdown 模板:
+需要引入 <tt>rdiscount</tt> gem/library 以渲染 Markdown 模板:
# 需要在你的应用中引入rdiscount
require "rdiscount"
@@ -336,7 +395,9 @@ Rack body对象或者HTTP状态码:
渲染 <tt>./views/index.markdown</tt>
(+md+ 和 +mkd+ 也是合理的文件扩展名)。
-在markdown中是不可以调用方法的,也不可以传递 locals给它。你因此一般会结合其他的渲染引擎来使用它:
+在markdown中是不可以调用方法的,也不可以传递 locals给它。
+你因此一般会结合其他的渲染引擎来使用它:
+
erb :overview, :locals => { :text => markdown(:introduction) }
@@ -345,9 +406,45 @@ Rack body对象或者HTTP状态码:
%h1 Hello From Haml!
%p= markdown(:greetings)
+既然你不能在Markdown中调用Ruby,你不能使用Markdown编写的布局。
+不过,使用其他渲染引擎作为模版的布局是可能的,
+通过传递<tt>:layout_engine</tt>选项:
+
+ get '/' do
+ markdown :index, :layout_engine => :erb
+ end
+
+这将会渲染 <tt>./views/index.md</tt> 并使用
+<tt>./views/layout.erb</tt> 作为布局。
+
+请记住你可以全局设定这个选项:
+
+ set :markdown, :layout_engine => :haml, :layout => :post
+
+ get '/' do
+ markdown :index
+ end
+
+这将会渲染 <tt>./views/index.markdown</tt> (和任何其他的 Markdown
+模版) 并使用 <tt>./views/post.haml</tt> 作为布局.
+
+也可能使用BlueCloth而不是RDiscount来解析Markdown文件:
+
+ require 'bluecloth'
+
+ Tilt.register 'markdown', BlueClothTemplate
+ Tilt.register 'mkd', BlueClothTemplate
+ Tilt.register 'md', BlueClothTemplate
+
+ get '/' do
+ markdown :index
+ end
+
+使用BlueCloth来渲染 <tt>./views/index.md</tt> 。
+
=== Textile 模板
-需要引入 RedCloth gem/library 以渲染 Textile 模板:
+需要引入 <tt>RedCloth</tt> gem/library 以渲染 Textile 模板:
# 在你的应用中引入redcloth
require "redcloth"
@@ -358,18 +455,41 @@ Rack body对象或者HTTP状态码:
渲染 <tt>./views/index.textile</tt>。
-在textile中是不可以调用方法的,也不可以传递 locals给它。你因此一般会结合其他的渲染引擎来使用它:
+在textile中是不可以调用方法的,也不可以传递 locals给它。
+你因此一般会结合其他的渲染引擎来使用它:
erb :overview, :locals => { :text => textile(:introduction) }
-请注意你也可以从其他模板中调用textile方法
+请注意你也可以从其他模板中调用+textile+方法
%h1 Hello From Haml!
%p= textile(:greetings)
+既然你不能在Textile中调用Ruby,你不能使用Textile编写的布局。
+不过,使用其他渲染引擎作为模版的布局是可能的,
+通过传递<tt>:layout_engine</tt>选项:
+
+ get '/' do
+ textile :index, :layout_engine => :erb
+ end
+
+这将会渲染 <tt>./views/index.textile</tt> 并使用
+<tt>./views/layout.erb</tt> 作为布局。
+
+请记住你可以全局设定这个选项:
+
+ set :textile, :layout_engine => :haml, :layout => :post
+
+ get '/' do
+ textile :index
+ end
+
+这将会渲染 <tt>./views/index.textile</tt> (和任何其他的 Textile
+模版) 并使用 <tt>./views/post.haml</tt> 作为布局.
+
=== RDoc 模板
-需要引入 RDoc gem/library 以渲染RDoc模板:
+需要引入 <tt>RDoc</tt> gem/library 以渲染RDoc模板:
# 需要在你的应用中引入rdoc/markup/to_html
require "rdoc/markup/to_html"
@@ -380,20 +500,43 @@ Rack body对象或者HTTP状态码:
渲染 <tt>./views/index.rdoc</tt>。
-在rdoc中是不可以调用方法的,也不可以传递 locals给它。你因此一般会结合其他的渲染引擎来使用它:
+在rdoc中是不可以调用方法的,也不可以传递locals给它。
+你因此一般会结合其他的渲染引擎来使用它:
erb :overview, :locals => { :text => rdoc(:introduction) }
-请注意你也可以从其他模板中调用rdoc方法
+请注意你也可以从其他模板中调用+rdoc+方法
%h1 Hello From Haml!
%p= rdoc(:greetings)
+既然你不能在RDoc中调用Ruby,你不能使用RDoc编写的布局。
+不过,使用其他渲染引擎作为模版的布局是可能的,
+通过传递<tt>:layout_engine</tt>选项:
+
+ get '/' do
+ rdoc :index, :layout_engine => :erb
+ end
+
+这将会渲染 <tt>./views/index.rdoc</tt> 并使用
+<tt>./views/layout.erb</tt> 作为布局。
+
+请记住你可以全局设定这个选项:
+
+ set :rdoc, :layout_engine => :haml, :layout => :post
+
+ get '/' do
+ rdoc :index
+ end
+
+这将会渲染 <tt>./views/index.rdoc</tt> (和任何其他的 RDoc
+模版) 并使用 <tt>./views/post.haml</tt> 作为布局.
+
=== Radius 模板
-需要引入 radius gem/library 以渲染 Radius 模板:
+需要引入 <tt>radius</tt> gem/library 以渲染 Radius 模板:
- # You'll need to require radius in your app
+ # 需要在你的应用中引入radius
require 'radius'
get '/' do
@@ -402,14 +545,14 @@ Rack body对象或者HTTP状态码:
渲染 <tt>./views/index.radius</tt>。
-因为你不能在Liquid 模板中调用 Ruby 方法 (除了 +yield+) ,
+因为你不能在Radius 模板中调用 Ruby 方法 (除了 +yield+) ,
你几乎总是需要传递locals给它:
radius :index, :locals => { :key => 'value' }
=== Markaby 模板
-需要引入markaby gem/library以渲染Markaby模板:
+需要引入<tt>markaby</tt> gem/library以渲染Markaby模板:
#需要在你的应用中引入 markaby
require 'markaby'
@@ -420,9 +563,15 @@ Rack body对象或者HTTP状态码:
渲染 <tt>./views/index.mab</tt>。
+你也可以使用嵌入的 Markaby:
+
+ get '/' do
+ markaby { h1 "Welcome!" }
+ end
+
=== Slim 模板
-需要引入 slim gem/library 来渲染 Slim 模板:
+需要引入 <tt>slim</tt> gem/library 来渲染 Slim 模板:
# 需要在你的应用中引入 slim
require 'slim'
@@ -435,8 +584,16 @@ Rack body对象或者HTTP状态码:
=== CoffeeScript 模板
-需要引入 coffee-script gem/library 并在路径中存在 `coffee` 二进制文件以渲染
-CoffeeScript 模板:
+需要引入 <tt>coffee-script</tt> gem/library 并至少满足下面条件一项
+以执行Javascript:
+
+* +node+ (来自 Node.js) 在你的路径中
+* 你正在运行 OSX
+* +therubyracer+ gem/library
+
+请察看 http://github.com/josh/ruby-coffee-script 获取更新的选项。
+
+现在你可以渲染 CoffeeScript 模版了:
# 需要在你的应用中引入coffee-script
require 'coffee-script'
@@ -447,13 +604,13 @@ CoffeeScript 模板:
渲染 <tt>./views/application.coffee</tt>。
-=== 内联模板字符串
+=== 嵌入模板字符串
get '/' do
haml '%div.title Hello World'
end
-渲染内联模板字符串
+渲染嵌入模板字符串
=== 在模板中访问变量
@@ -472,7 +629,7 @@ CoffeeScript 模板:
haml '%h1= foo.name', :locals => { :foo => foo }
end
-典型的使用情况是在别的模板中按照部分模板的方式来渲染
+典型的使用情况是在别的模板中按照局部模板的方式来渲染
=== 内联模板
@@ -515,27 +672,38 @@ CoffeeScript 模板:
end
如果存在名为"layout"的模板,该模板会在每个模板渲染的时候被使用。
-你可以通过传送 <tt>:layout => false</tt>来禁用。
+你可以单独地通过传送 <tt>:layout => false</tt>来禁用,
+或者通过<tt>set :haml, :layout => false</tt>来禁用他们。
get '/' do
haml :index, :layout => !request.xhr?
end
-== 辅助方法
+=== 关联文件扩展名
-使用顶层的 <tt>helpers</tt> 方法来定义辅助方法,
-以便在路由处理器和模板中使用:
+为了关联一个文件扩展名到一个模版引擎,使用
+<tt>Tilt.register</tt>。比如,如果你喜欢使用
++tt+ 作为Textile模版的扩展名,你可以这样做:
+
+ Tilt.register :tt, Tilt[:textile]
+
+=== 添加你自己的模版引擎
+
+首先,通过Tilt注册你自己的引擎,然后创建一个渲染方法:
+
+ Tilt.register :myat, MyAwesomeTemplateEngine
helpers do
- def bar(name)
- "#{name}bar"
- end
+ def myat(*args) render(:myat, *args) end
end
- get '/:name' do
- bar(params[:name])
+ get '/' do
+ myat :index
end
+渲染 <tt>./views/index.myat</tt>。察看 https://github.com/rtomayko/tilt
+来更多了解Tilt.
+
== 过滤器
前置过滤器在每个请求前,在请求的上下文环境中被执行,
@@ -560,6 +728,10 @@ CoffeeScript 模板:
puts response.status
end
+请注意:除非你显式使用 +body+ 方法,而不是在路由中直接返回字符串,
+消息体在后置过滤器是不可用的,
+因为它在之后才会生成。
+
过滤器可以可选地带有范式,
只有请求路径满足该范式时才会执行:
@@ -571,7 +743,63 @@ CoffeeScript 模板:
session[:last_slug] = slug
end
-== 挂起
+和路由一样,过滤器也可以带有条件:
+
+ before :agent => /Songbird/ do
+ # ...
+ end
+
+ after '/blog/*', :host_name => 'example.com' do
+ # ...
+ end
+
+== 辅助方法
+
+使用顶层的 <tt>helpers</tt> 方法来定义辅助方法,
+以便在路由处理器和模板中使用:
+
+ helpers do
+ def bar(name)
+ "#{name}bar"
+ end
+ end
+
+ get '/:name' do
+ bar(params[:name])
+ end
+
+=== 使用 Sessions
+
+Session被用来在请求之间保持状态。如果被激活,每一个用户会话
+对应有一个session哈希:
+
+ enable :sessions
+
+ get '/' do
+ "value = " << session[:value].inspect
+ end
+
+ get '/:value' do
+ session[:value] = params[:value]
+ end
+
+请注意 <tt>enable :sessions</tt> 实际上保存所有的数据在一个cookie之中。
+这可能不会总是做你想要的(比如,保存大量的数据会增加你的流量)。
+你可以使用任何的Rack session中间件,为了这么做,
+*不要*调用 <tt>enable :sessions</tt>,而是
+按照自己的需要引入你的中间件:
+
+ use Rack::Session::Pool, :expire_after => 2592000
+
+ get '/' do
+ "value = " << session[:value].inspect
+ end
+
+ get '/:value' do
+ session[:value] = params[:value]
+ end
+
+=== 挂起
要想直接地停止请求,在过滤器或者路由中使用:
@@ -593,7 +821,7 @@ CoffeeScript 模板:
halt 402, {'Content-Type' => 'text/plain'}, 'revenge'
-== 让路
+=== 让路
一个路由可以放弃处理,将处理让给下一个匹配的路由,使用 <tt>pass</tt>:
@@ -609,9 +837,222 @@ CoffeeScript 模板:
路由代码块被直接退出,控制流继续前进到下一个匹配的路由。
如果没有匹配的路由,将返回404。
-== 访问请求对象
+=== 触发另一个路由
+
+有些时候,+pass+ 并不是你想要的,你希望得到的是另一个路由的结果
+。简单的使用 +call+ 可以做到这一点:
+
+ get '/foo' do
+ status, headers, body = call request.env.merge("PATH_INFO" => '/bar')
+ [status, body.upcase]
+ end
+
+ get '/bar' do
+ "bar"
+ end
+
+请注意在以上例子中,你可以更加简化测试并增加性能,只要简单的移动
+ <tt>"bar"</tt>到一个被<tt>/foo</tt>
+和 <tt>/bar</tt>同时使用的helper。
+
+如果你希望请求被发送到同一个应用,而不是副本,
+使用 <tt>call!</tt> 而不是 <tt>call</tt>.
+
+察看 Rack specification 如果你想更多了解 <tt>call</tt>.
+
+=== 设定 消息体,状态码和消息头
+
+通过路由代码块的返回值来设定状态码和消息体不仅是可能的,而且是推荐的。
+但是,在某些场景中你可能想在作业流程中的特定点上设置消息体。
+你可以通过 +body+ 辅助方法这么做。
+如果你这样做了,
+你可以在那以后使用该方法获得消息体:
+
+ get '/foo' do
+ body "bar"
+ end
+
+ after do
+ puts body
+ end
+
+也可以传一个代码块给 +body+,它将会被Rack处理器执行(
+这将可以被用来实现streaming,参见“返回值”)。
+
+和消息体类似,你也可以设定状态码和消息头:
+
+ get '/foo' do
+ status 418
+ headers \
+ "Allow" => "BREW, POST, GET, PROPFIND, WHEN"
+ "Refresh" => "Refresh: 20; http://www.ietf.org/rfc/rfc2324.txt"
+ body "I'm a tea pot!"
+ end
+
+如同 +body+, 不带参数的 +headers+ 和 +status+ 可以用来访问
+他们你的当前值.
+
+=== 媒体类型
+
+当使用 <tt>send_file</tt> 或者静态文件的场合,你的媒体类型可能
+Sinatra并不理解。使用 +mime_type+ 通过文件扩展名来注册它们:
+
+ mime_type :foo, 'text/foo'
+
+你也可以通过 +content_type+ 辅助方法使用:
+
+ get '/' do
+ content_type :foo
+ "foo foo foo"
+ end
+
+=== 生成 URL
+
+为了生成URL,你需要使用 +url+ 辅助方法,
+例如,在Haml中:
+
+ %a{:href => url('/foo')} foo
+
+它会根据反向代理和Rack路由,如果有的话,来计算生成的URL。
+
+这个方法还有一个别名 +to+ (见下面的例子).
+
+=== 浏览器重定向
+
+你可以通过 +redirect+ 辅助方法触发浏览器重定向:
+
+ get '/foo' do
+ redirect to('/bar')
+ end
+
+任何额外的参数都会被以 +halt+相同的方式来处理:
+
+ redirect to('/bar'), 303
+ redirect 'http://google.com', 'wrong place, buddy'
+
+你可以方便的通过
+<tt>redirect back</tt>把用户重定向到来自的页面:
+
+ get '/foo' do
+ "<a href='/bar'>do something</a>"
+ end
+
+ get '/bar' do
+ do_something
+ redirect back
+ end
+
+为了传递参数给redirect,或者加入query:
+
+ redirect to('/bar?sum=42')
+
+或者使用session:
+
+ enable :session
+
+ get '/foo' do
+ session[:secret] = 'foo'
+ redirect to('/bar')
+ end
+
+ get '/bar' do
+ session[:secret]
+ end
+
+=== 缓存控制
+
+正确地设定消息头是恰当的HTTP缓存的基础。
-传入的请求对象可以在请求层(过滤器,路由,错误处理)通过 `request` 方法被访问:
+你可以方便的设定 Cache-Control 消息头,像这样:
+
+ get '/' do
+ cache_control :public
+ "cache it!"
+ end
+
+核心提示: 在前置过滤器中设定缓存.
+
+ before do
+ cache_control :public, :must_revalidate, :max_age => 60
+ end
+
+如果你正在用 +expires+ 辅助方法设定对应的消息头
+<tt>Cache-Control</tt> 会自动设定:
+
+ before do
+ expires 500, :public, :must_revalidate
+ end
+
+为了合适地使用缓存,你应该考虑使用 +etag+ 和 +last_modified+方法。.
+推荐在执行繁重任务*之前*使用这些helpers,
+他们会立刻发送响应,如果客户端在缓存中已经有了当前版本。
+
+ get '/article/:id' do
+ @article = Article.find params[:id]
+ last_modified @article.updated_at
+ etag @article.sha1
+ erb :article
+ end
+
+使用
+{weak ETag}[http://en.wikipedia.org/wiki/HTTP_ETag#Strong_and_weak_validation]
+也是有可能的:
+
+ etag @article.sha1, :weak
+
+这些辅助方法并不会为你做任何缓存,而是将必要的信息传送给你的缓存
+如果你在寻找缓存的快速解决方案,试试
+{rack-cache}[http://rtomayko.github.com/rack-cache/]:
+
+ require "rack/cache"
+ require "sinatra"
+
+ use Rack::Cache
+
+ get '/' do
+ cache_control :public, :max_age => 36000
+ sleep 5
+ "hello"
+ end
+
+=== 发送文件
+
+为了发送文件,你可以使用 <tt>send_file</tt> 辅助方法:
+
+ get '/' do
+ send_file 'foo.png'
+ end
+
+也可以带一些选项:
+
+ send_file 'foo.png', :type => :jpg
+
+可用的选项有:
+
+[filename]
+ 响应中的文件名,默认是真实文件的名字。
+
+[last_modified]
+ Last-Modified 消息头的值,默认是文件的mtime(修改时间)。
+
+[type]
+ 使用的内容类型,如果没有会从文件扩展名猜测。
+
+[disposition]
+ 用于 Content-Disposition,可能的包括: +nil+ (默认),
+ <tt>:attachment</tt> 和 <tt>:inline</tt>
+
+[length]
+ Content-Length 的值,默认是文件的大小。
+
+如果Rack处理器支持,Ruby进程除streaming以外的方式会被使用。
+如果你使用这个辅助方法,
+Sinatra会自动处理range请求。
+
+=== 访问请求对象
+
+传入的请求对象可以在请求层(过滤器,路由,错误处理)
+通过 <tt>request</tt> 方法被访问:
# 在 http://example.com/example 上运行的应用
get '/foo' do
@@ -628,14 +1069,15 @@ CoffeeScript 模板:
request.get? # true (其他动词也具有类似方法)
request.form_data? # false
request["SOME_HEADER"] # SOME_HEADER header的值
- request.referer # 客户端的referer 或者 '/'
+ request.referrer # 客户端的referrer 或者 '/'
request.user_agent # user agent (被 :agent 条件使用)
request.cookies # 浏览器 cookies 哈希
request.xhr? # 这是否是ajax请求?
request.url # "http://example.com/example/foo"
request.path # "/example/foo"
request.ip # 客户端IP地址
- request.secure? # false
+ request.secure? # false(如果是ssl则为true)
+ request.forwarded? # true (如果是运行在反向代理之后)
request.env # Rack中使用的未处理的env哈希
end
@@ -656,12 +1098,83 @@ CoffeeScript 模板:
"Hello #{data['name']}!"
end
+=== 附件
+
+你可以使用 +attachment+ 辅助方法来告诉浏览器响应
+应当被写入磁盘而不是在浏览器中显示。
+
+ get '/' do
+ attachment
+ "store it!"
+ end
+
+你也可以传递一个文件名:
+
+ get '/' do
+ attachment "info.txt"
+ "store it!"
+ end
+
+=== 查找模板文件
+
+<tt>find_template</tt> 辅助方法被用于在渲染时查找模板文件:
+
+ find_template settings.views, 'foo', Tilt[:haml] do |file|
+ puts "could be #{file}"
+ end
+
+这并不是很有用。但是在你需要重载这个方法
+来实现你自己的查找机制的时候有用。
+比如,如果你想支持多于一个视图目录:
+
+ set :views, ['views', 'templates']
+
+ helpers do
+ def find_template(views, name, engine, &block)
+ Array(views).each { |v| super(v, name, engine, &block) }
+ end
+ end
+
+另一个例子是为不同的引擎使用不同的目录:
+
+ set :views, :sass => 'views/sass', :haml => 'templates', :default => 'views'
+
+ helpers do
+ def find_template(views, name, engine, &block)
+ _, folder = views.detect { |k,v| engine == Tilt[k] }
+ folder ||= views[:default]
+ super(folder, name, engine, &block)
+ end
+ end
+
+你可以很容易地包装成一个扩展然后与他人分享!
+
+请注意 <tt>find_template</tt> 并不会检查文件真的存在,
+而是对任何可能的路径调用给入的代码块。这并不会带来性能问题,
+因为 +render+ 会在找到文件的时候马上使用 +break+ 。
+同样的,模板的路径(和内容)会在除development mode以外的场合
+被缓存。你应该时刻提醒自己这一点,
+如果你真的想写一个非常疯狂的方法。
+
== 配置
运行一次,在启动的时候,在任何环境下:
configure do
- ...
+ # setting one option
+ set :option, 'value'
+
+ # setting multiple options
+ set :a => 1, :b => 2
+
+ # same as `set :option, true`
+ enable :option
+
+ # same as `set :option, false`
+ disable :option
+
+ # you can also have dynamic settings with blocks
+ set(:css_dir) { File.join(views, 'css') }
end
只当环境 (RACK_ENV environment 变量) 被设定为
@@ -678,6 +1191,101 @@ CoffeeScript 模板:
...
end
+你可以使用 <tt>settings</tt> 获得这些配置:
+
+ configure do
+ set :foo, 'bar'
+ end
+
+ get '/' do
+ settings.foo? # => true
+ settings.foo # => 'bar'
+ ...
+ end
+
+=== 可选的设置
+
+[absolute_redirects] 如果被禁用,Sinatra会允许使用相对路径重定向,
+ 但是,Sinatra就不再遵守 RFC 2616标准
+ (HTTP 1.1), 该标准只允许绝对路径重定向。
+
+ 如果你的应用运行在一个未恰当设置的反向代理之后,
+ 你需要启用这个选项。注意 +url+ 辅助方法
+ 仍然会生成绝对 URL,除非你传入
+ +false+ 作为第二参数。
+
+ 默认禁用。
+
+[add_charsets] 设定 <tt>content_type</tt> 辅助方法会
+ 自动加上字符集信息的多媒体类型。
+
+ 你应该添加而不是覆盖这个选项:
+
+ settings.add_charsets << "application/foobar"
+
+[app_file] 主应用文件,用来检测项目的根路径,
+ views和public文件夹和内联模板。
+
+[bind] 绑定的IP 地址 (默认: 0.0.0.0)。
+ 仅对于内置的服务器有用。
+
+[default_encoding] 默认编码
+ (默认为 <tt>"utf-8"</tt>)。
+
+[dump_errors] 在log中显示错误。
+
+[environment] 当前环境,默认是 <tt>ENV['RACK_ENV']</tt>,
+ 或者 <tt>"development"</tt> 如果不可用。
+
+[logging] 使用logger
+
+[lock] 对每一个请求放置一个锁,
+ 只使用进程并发处理请求。
+
+ 如果你的应用不是线程安全则需启动。
+ 默认禁用。
+
+[method_override] 使用 <tt>_method</tt> 魔法以允许在旧的浏览器中在
+ 表单中使用 put/delete 方法
+
+[port] 监听的端口号。只对内置服务器有用。
+
+[prefixed_redirects] 是否添加 <tt>request.script_name</tt> 到
+ 重定向请求,如果没有设定绝对路径。那样的话
+ <tt>redirect '/foo'</tt> 会和
+ <tt>redirect to('/foo')</tt>起相同作用。默认禁用。
+
+[public] public文件夹的位置。
+
+[reload_templates] 是否每个请求都重新载入模板。
+ 在development mode和 Ruby 1.8.6 中被企业(用来
+ 消除一个Ruby内存泄漏的bug)。
+
+[root] 项目的根目录。
+
+[raise_errors] 抛出异常(应用会停下)。
+
+[run] 如果启用,Sinatra会开启web服务器。
+ 如果使用rackup或其他方式则不要启用。
+
+[running] 内置的服务器在运行吗?
+ 不要修改这个设置!
+
+[server] 服务器,或用于内置服务器的列表。
+ 默认是 ['thin', 'mongrel', 'webrick'], 顺序表明了
+ 优先级。
+
+[sessions] 开启基于cookie的sesson。
+
+[show_exceptions] 在浏览器中显示一个stack trace。
+
+[static] Sinatra是否处理静态文件。
+ 当服务器能够处理则禁用。
+ 禁用会增强性能。
+ 默认开启。
+
+[views] views 文件夹。
+
== 错误处理
错误处理在与路由和前置过滤器相同的上下文中运行,
@@ -738,17 +1346,6 @@ CoffeeScript 模板:
在运行在development环境下时,Sinatra会安装特殊的
<tt>not_found</tt> 和 <tt>error</tt> 处理器。
-== 媒体类型
-
-当使用 <tt>send_file</tt> 或者静态文件的适合,你的媒体类型可能
-Sinatra并不理解。使用 +mime_type+ 通过文件扩展名来注册它们:
-
- mime_type :foo, 'text/foo'
-
-你也可以通过 +content_type+ 辅助方法使用:
-
- content_type :foo
-
== Rack 中间件
Sinatra 依靠 Rack[http://rack.rubyforge.org/],
@@ -770,10 +1367,9 @@ Sinatra 让建立Rack中间件管道异常简单,
'Hello World'
end
-+use+ 的语义和在Rack::Builder[http://rack.rubyforge.org/doc/classes/Rack/Builder.html] DSL
-(在rack文件中最频繁使用)
-中定义的完全一样。例如,+use+ 方法
-接受 多个/可变 参数,包括代码块:
++use+ 的语义和在 Rack::Builder[http://rack.rubyforge.org/doc/classes/Rack/Builder.html]
+DSL(在rack文件中最频繁使用)中定义的完全一样。例如,+use+
+方法接受 多个/可变 参数,包括代码块:
use Rack::Auth::Basic do |username, password|
username == 'admin' && password == 'secret'
@@ -822,11 +1418,11 @@ Sinatra的测试可以使用任何基于Rack的测试程序库或者框架来编
== Sinatra::Base - 中间件,程序库和模块化应用
-把你的应用定义在顶层,对于微型应用这会工作得很好,但是在
-构建可复用的组件时候会带来客观的不利
+把你的应用定义在顶层,对于微型应用这会工作得很好,
+但是在构建可复用的组件时候会带来客观的不利
比如构建Rack中间件,Rails metal,带有服务器组件的简单程序库,
-或者甚至是Sinatra扩展。顶层的DSL污染了Object命名空间并
-假定了一个微型应用风格的配置 (例如, 单一的应用文件,
+或者甚至是Sinatra扩展。顶层的DSL污染了Object命名空间,
+并假定了一个微型应用风格的配置 (例如, 单一的应用文件,
./public 和 ./views 目录,日志,异常细节页面,等等)。
这时应该让 Sinatra::Base 走到台前了:
@@ -841,16 +1437,9 @@ Sinatra的测试可以使用任何基于Rack的测试程序库或者框架来编
end
end
-MyApp 类是一个独立的Rack组件,可以扮演
-Rack中间件,一个Rack应用,或者 Rails metal。你可以从rackup +config.ru文件
-+use+ 或者 +run+ 这个类;或者,
-直接控制作为程序库提供的服务器组件:
-
- MyApp.run! :host => 'localhost', :port => 9090
-
-Sinatra::Base子类可用的方法实际上就是
-通过顶层DSL可用的方法。大部分顶层应用可以通过两个改变
-转换成Sinatra::Base组件:
+Sinatra::Base子类可用的方法实际上就是通过顶层 DSL
+可用的方法。
+大部分顶层应用可以通过两个改变转换成Sinatra::Base组件:
* 你的文件应当引入 +sinatra/base+ 而不是 +sinatra+;
否则,所有的Sinatra的 DSL 方法将会被引进到
@@ -862,10 +1451,95 @@ Sinatra::Base子类可用的方法实际上就是
包含内置的服务器。参见 {选项和配置}[http://sinatra.github.com/configuration.html]
查看可用选项的具体细节和他们的行为。
+=== 模块化 vs. 传统的方式
+
+与通常的认识相反,传统的方式没有任何错误。
+如果它适合你的应用,你不需要转换到模块化的应用。
+
+和模块化方式相比只有两个缺点:
+
+* 你对每个Ruby进程只能定义一个Sinatra应用,如果你需要更多,
+ 切换到模块化方式。
+
+* 传统方式使用代理方法污染了 Object 。如果你打算
+ 把你的应用封装进一个 library/gem,转换到模块化方式。
+
+没有任何原因阻止你混合模块化和传统方式。
+
+如果从一种转换到另一种,你需要注意settings中的
+一些微小的不同:
+
+ Setting Classic Modular
+
+ app_file file loading sinatra nil
+ run $0 == app_file false
+ logging true false
+ method_override true false
+ inline_templates true false
+
+
+=== 运行一个模块化应用
+
+有两种方式运行一个模块化应用,使用
+<tt>run!</tt>来运行:
+
+ # my_app.rb
+ require 'sinatra/base'
+
+ class MyApp < Sinatra::Base
+ # ... app code here ...
+
+ # start the server if ruby file executed directly
+ run! if app_file == $0
+ end
+
+运行:
+
+ ruby my_app.rb
+
+或者使用一个 <tt>config.ru</tt>,允许你使用任何Rack处理器:
+
+ # config.ru
+ require 'my_app'
+ run MyApp
+
+运行:
+
+ rackup -p 4567
+
+=== 使用config.ru运行传统方式的应用
+
+编写你的应用:
+
+ # app.rb
+ require 'sinatra'
+
+ get '/' do
+ 'Hello world!'
+ end
+
+加入相应的 <tt>config.ru</tt>:
+
+ require 'app'
+ run Sinatra::Application
+
+=== 什么时候用 config.ru?
+
+以下情况你可能需要使用 <tt>config.ru</tt>:
+
+* 你要使用不同的 Rack 处理器部署 (Passenger, Unicorn,
+ Heroku, ...).
+* 你想使用一个或者多个 <tt>Sinatra::Base</tt>的子类.
+* 你只想把Sinatra当作中间件使用,而不是端点。
+
+<b>你并不需要切换到<tt>config.ru</tt>仅仅因为你切换到模块化方式,
+你同样不需要切换到模块化方式,
+仅仅因为要运行 <tt>config.ru</tt>.</b>
+
=== 把Sinatra当成中间件来使用
不仅Sinatra有能力使用其他的Rack中间件,任何Sinatra
-应用程序都可以反过来自身被当作中间件,被加在任何Rack断电前面
+应用程序都可以反过来自身被当作中间件,被加在任何Rack端点前面
这个端点可以是任何Sinatra应用,或者任何基于Rack的应用程序
(Rails/Ramaze/Camping/...)。
@@ -997,34 +1671,125 @@ Sinatra 应用可以被直接运行:
-o # 设定主机名 (默认是 0.0.0.0)
-e # 设定环境 (默认是 development)
-s # 限定 rack 服务器/处理器 (默认是 thin)
- -x # 打开互斥标记锁 (默认是 off)
+ -x # 打开互斥锁 (默认是 off)
+
+== 必要条件
+
+推荐在 Ruby 1.8.7, 1.9.2, JRuby 或者 Rubinius 上安装Sinatra。
+
+下面的Ruby版本是官方支持的:
+
+[ Ruby 1.8.6 ]
+ 不推荐在1.8.6上安装Sinatra,
+ 但是直到Sinatra 1.3.0发布才会放弃对它的支持。
+ RDoc 和 CoffeScript模板不被这个Ruby版本支持。
+ 1.8.6在它的Hash实现中包含一个内存泄漏问题,
+ 该问题会被1.1.1版本之前的Sinatra引发。
+ 当前版本使用性能下降的代价排除了这个问题。你需要把Rack降级到1.1.x,
+ 因为Rack >= 1.2不再支持1.8.6。
+
+[ Ruby 1.8.7 ]
+ 1.8.7 被完全支持,但是,如果没有特别原因,
+ 我们推荐你升级到 1.9.2 或者切换到 JRuby 或者 Rubinius.
+
+[ Ruby 1.9.2 ]
+ 1.9.2 被支持而且推荐。注意 Radius 和 Markaby
+ 模板并不和1.9兼容。不要使用 1.9.2p0, 它被已知会产生
+ segmentation faults.
+
+[ Rubinius ]
+ Rubinius 被官方支持 (Rubinius >= 1.2.2),
+ 除了Textile模板。
+
+[ JRuby ]
+ JRuby 被官方支持 (JRuby >= 1.5.6)。
+ 目前未知和第三方模板库有关的问题,
+ 但是,如果你选择了JRuby,请查看一下JRuby rack 处理器,
+ 因为 Thin web 服务器还没有在JRuby上获得支持。
+
+我们也会时刻关注新的Ruby版本。
+
+下面的 Ruby 实现没有被官方支持,
+但是已知可以运行 Sinatra:
+
+* JRuby 和 Rubinius 老版本
+* MacRuby
+* Maglev
+* IronRuby
+* Ruby 1.9.0 and 1.9.1
+
+不被官方支持的意思是,如果在不被支持的平台上有运行错误,
+我们假定不是我们的问题,而是平台的问题。
+
+Sinatra应该会运行在任何支持上述Ruby实现的操作系统。
-== 紧追前沿
-如果你喜欢使用 Sinatra 的最新鲜的代码,创建一个本地克隆
-, 把<tt>sinatra/lib</tt> 目录添加到
-<tt>LOAD_PATH</tt>后运行你的应用:
+== 紧追前沿
+如果你喜欢使用 Sinatra 的最新鲜的代码,请放心的使用 master
+分支来运行你的程序,它会非常的稳定。
cd myapp
git clone git://github.com/sinatra/sinatra.git
ruby -Isinatra/lib myapp.rb
-另一种方法是,你也可以在你的应用中,添加 <tt>sinatra/lib</tt> 目录到
-<tt>LOAD_PATH</tt>:
+我们也会不定期的发布预发布gems,所以你也可以运行
- $LOAD_PATH.unshift File.dirname(__FILE__) + '/sinatra/lib'
- require 'rubygems'
- require 'sinatra'
+ gem install sinatra --pre
- get '/about' do
- "I'm running version " + Sinatra::VERSION
- end
+来获得最新的特性。
+
+=== 通过Bundler
+如果你想使用最新的Sinatra运行你的应用,通过
+{Bundler}[http://gembundler.com/] 是推荐的方式。
+
+首先,安装bundler,如果你还没有安装:
+
+ gem install bundler
+
+然后,在你的项目目录下,创建一个 +Gemfile+:
+
+ source :rubygems
+ gem 'sinatra', :git => "git://github.com/sinatra/sinatra.git"
+
+ # 其他的依赖关系
+ gem 'haml' # 举例,如果你想用haml
+ gem 'activerecord', '~> 3.0' # 也许你还需要 ActiveRecord 3.x
+
+请注意在这里你需要列出你的应用的所有依赖关系。
+Sinatra的直接依赖关系 (Rack and Tilt) 将会,
+自动被Bundler获取和添加。
+
+现在你可以像这样运行你的应用:
+
+ bundle exec ruby myapp.rb
-在未来,要更新Sinatra源代码:
+=== 使用自己的
+创建一个本地克隆并通过 <tt>sinatra/lib</tt> 目录运行你的应用,
+通过 <tt>$LOAD_PATH</tt>:
- cd myproject/sinatra
+ cd myapp
+ git clone git://github.com/sinatra/sinatra.git
+ ruby -Isinatra/lib myapp.rb
+
+为了在未来更新 Sinatra 源代码:
+
+ cd myapp/sinatra
git pull
+=== 全局安装
+
+你可以自行编译 gem :
+
+
+ git clone git://github.com/sinatra/sinatra.git
+ cd sinatra
+ rake sinatra.gemspec
+ rake install
+
+如果你以root身份安装 gems,最后一步应该是
+
+ sudo rake install
+
== 更多
* {项目主页(英文)}[http://www.sinatrarb.com/] - 更多的文档,

0 comments on commit 781891b

Please sign in to comment.
Something went wrong with that request. Please try again.