kotovalexarian-likes-github/sinatra
1
0
Fork 0
mirror of https://github.com/sinatra/sinatra synced 2023-03-27 23:18:01 -04:00
Code Releases Activity
sinatra/README.zh.md
ceclinux f47b178ef6 change all Fixnum to Integer in readmes
2018-11-07 16:02:10 +08:00

73 KiB
Raw Blame History

Sinatra

注：本文档是英文版的翻译，内容更新有可能不及时。如有不一致的地方，请以英文版为准。

Sinatra 是一门基于 Ruby 的领域专属语言，致力于轻松、快速地创建网络应用：

# myapp.rb
require 'sinatra'

get '/' do
  'Hello world!'
end

安装 Sinatra 这个 gem：

gem install sinatra

然后运行 myapp.rb 中的代码：

ruby myapp.rb

在该地址查看： http://localhost:4567

推荐运行 gem install thin 安装 Thin。这样，Sinatra 会优先选择 Thin 作为服务器。

目录

路由

在 Sinatra 中，一个路由分为两部分：HTTP 方法和 URL 匹配范式。每个路由都有一个要执行的代码块：

get '/' do
  .. 显示内容 ..
end

post '/' do
  .. 创建内容 ..
end

put '/' do
  .. 替换内容 ..
end

patch '/' do
  .. 修改内容 ..
end

delete '/' do
  .. 删除内容 ..
end

options '/' do
  .. 显示命令列表 ..
end

link '/' do
  .. 建立某种联系 ..
end

unlink '/' do
  .. 解除某种联系 ..
end

路由按照它们定义时的顺序进行匹配。第一个与请求匹配的路由会被调用。

路由范式可以包括具名参数，具名参数可以通过 params hash 访问：

get '/hello/:name' do
  # 匹配 "GET /hello/foo" 和 "GET /hello/bar"
  # params['name'] 的值是 'foo' 或者 'bar'
  "Hello #{params['name']}!"
end

也可以通过代码块参数访问具名参数：

get '/hello/:name' do |n|
  # 匹配 "GET /hello/foo" 和 "GET /hello/bar"
  # params['name'] 的值是 'foo' 或者 'bar'
  # n 存储 params['name'] 的值
  "Hello #{n}!"
end

路由范式也可以包含通配符参数， 参数值可以通过 params['splat'] 数组访问。

get '/say/*/to/*' do
  # 匹配 "GET /say/hello/to/world"
  params['splat'] # => ["hello", "world"]
end

get '/download/*.*' do
  # 匹配 "GET /download/path/to/file.xml"
  params['splat'] # => ["path/to/file", "xml"]
end

或者通过代码块参数访问：

get '/download/*.*' do |path, ext|
  [path, ext] # => ["path/to/file", "xml"]
end

通过正则表达式匹配路由：

get /\/hello\/([\w]+)/ do
  "Hello, #{params['captures'].first}!"
end

或者使用代码块参数：

get %r{/hello/([\w]+)} do |c|
  # 匹配 "GET /meta/hello/world"、"GET /hello/world/1234" 等
  "Hello, #{c}!"
end

路由范式可以包含可选参数：

get '/posts/:format?' do
  # 匹配 "GET /posts/" 和任意扩展 "GET /posts/json"、"GET /posts/xml" 等
end

路由也可以使用查询参数：

get '/posts' do
  # 匹配 "GET /posts?title=foo&author=bar"
  title = params['title']
  author = params['author']
  # 使用 title 和 author 变量；对于 /posts 路由来说，查询字符串是可选的
end

顺便一提，除非你禁用了路径遍历攻击防护（见下文），请求路径可能在匹配路由前发生改变。

你也可以通过:mustermann_opt选项定义Mustermann来匹配路由。

get '\A/posts\z', :mustermann_opts => { :type => :regexp, :check_anchors => false } do
  # matches /posts exactly, with explicit anchoring
  "If you match an anchored pattern clap your hands!"
end

它看起来像一个条件，但实际不是！这些选项将被合并到全局的mustermann_opts。

条件

路由可以包含各种匹配条件，比如 user agent：

get '/foo', :agent => /Songbird (\d\.\d)[\d\/]*?/ do
  "你正在使用 Songbird，版本是 #{params['agent'][0]}"
end

get '/foo' do
  # 匹配非 Songbird 浏览器
end

其它可以使用的条件有 host_name 和 provides：

get '/', :host_name => /^admin\./ do
  "管理员区域，无权进入！"
end

get '/', :provides => 'html' do
  haml :index
end

get '/', :provides => ['rss', 'atom', 'xml'] do
  builder :feed
end

provides 会搜索请求的 Accept 首部字段。

也可以轻易地使用自定义条件：

set(:probability) { |value| condition { rand <= value } }

get '/win_a_car', :probability => 0.1 do
  "You won!"
end

get '/win_a_car' do
  "Sorry, you lost."
end

对于一个需要提供多个值的条件，可以使用 splat：

set(:auth) do |*roles|   # <- 注意此处使用了 splat
  condition do
    unless logged_in? && roles.any? {|role| current_user.in_role? role }
      redirect "/login/", 303
    end
  end
end

get "/my/account/", :auth => [:user, :admin] do
  "Your Account Details"
end

get "/only/admin/", :auth => :admin do
  "Only admins are allowed here!"
end

返回值

路由代码块的返回值至少决定了返回给 HTTP 客户端的响应主体，或者至少决定了在 Rack 堆栈中的下一个中间件。大多数情况下，返回值是一个字符串，就像上面的例子中的一样。但是，其它类型的值也是可以接受的。

你可以返回任何对象，该对象要么是一个合理的 Rack 响应，要么是一个 Rack body 对象，要么是 HTTP 状态码：

  • 一个包含三个元素的数组: [状态 (Integer), 响应首部 (Hash), 响应主体 (可以响应 #each 方法)]
  • 一个包含两个元素的数组: [状态 (Integer), 响应主体 (可以响应 #each 方法)]
  • 一个响应 #each 方法，只传回字符串的对象
  • 一个代表状态码的数字

例如，我们可以轻松地实现流式传输：

class Stream
  def each
    100.times { |i| yield "#{i}\n" }
  end
end

get('/') { Stream.new }

也可以使用 stream 辅助方法（见下文描述）以减少样板代码并在路由中直接使用流式传输。

自定义路由匹配器

如上文所示，Sinatra 本身支持使用字符串和正则表达式作为路由匹配。但不限于此，你可以轻松地定义自己的匹配器：

class AllButPattern
  Match = Struct.new(:captures)

  def initialize(except)
    @except   = except
    @captures = Match.new([])
  end

  def match(str)
    @captures 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

静态文件

静态文件从 ./public 目录提供服务。可以通过设置:public_folder 选项设定一个不同的位置：

set :public_folder, File.dirname(__FILE__) + '/static'

请注意 public 目录名并没有包含在 URL 中。文件 ./public/css/style.css 可以通过 http://example.com/css/style.css 访问。

可以使用 :static_cache_control 设置（见下文）添加 Cache-Control 首部信息。

视图 / 模板

每一门模板语言都将自身的渲染方法暴露给 Sinatra 调用。这些渲染方法只是简单地返回字符串。

get '/' do
  erb :index
end

这段代码会渲染 views/index.erb 文件。

除了模板文件名，也可以直接传入模板内容：

get '/' do
  code = "<%= Time.now %>"
  erb code
end

渲染方法接受第二个参数，即选项 hash：

get '/' do
  erb :index, :layout => :post
end

这段代码会将 views/index.erb 嵌入在 views/post.erb 布局中并一起渲染（views/layout.erb 是默认的布局，如果它存在的话）。

任何 Sinatra 不能理解的选项都会传递给模板引擎。

get '/' do
  haml :index, :format => :html5
end

也可以为每种模板语言设置通用的选项：

set :haml, :format => :html5

get '/' do
  haml :index
end

在渲染方法中传入的选项会覆盖通过 set 设置的通用选项。

可用的选项：

locals
传递给模板文档的 locals 对象列表。对于 partials 很方便。例如：erb "<%= foo %>", :locals => {:foo => "bar"}
default_encoding
默认的字符编码。默认值为 settings.default_encoding。
views
存放模板文件的目录。默认为 settings.views。
layout
是否使用布局 (true 或 false)。 如果使用一个符号类型的值，则是用于明确使用的模板。例如： erb :index, :layout => !request.xhr?
content_type
由模板生成的 Content-Type。默认值由模板语言决定。
scope
渲染模板时的作用域。默认值为应用类的实例对象。如果更改此项，实例变量和辅助方法将不可用。
layout_engine
渲染布局所使用的模板引擎。用于不支持布局的模板语言。默认值为模板所使用的引擎。例如： set :rdoc, :layout_engine => :erb
layout_options
渲染布局的特殊选项。例如： set :rdoc, :layout_options => { :views => 'views/layouts' }

Sinatra 假定模板文件直接位于 ./views 目录。要使用不同的视图目录：

set :views, settings.root + '/templates'

需要牢记的一点是，你必须通过符号引用模板， 即使它们存放在子目录下 （在这种情况下，使用 :'subdir/template' 或 'subdir/template'.to_sym）。 如果你不使用符号，渲染方法会直接渲染你传入的任何字符串。

字面量模板

get '/' do
  haml '%div.title Hello World'
end

这段代码直接渲染模板字符串。

可选的模板语言

一些语言有多种实现。为了确定使用哪种实现（以及保证线程安全），你应该首先引入该实现：

require 'rdiscount' # 或 require 'bluecloth'
get('/') { markdown :index }

Haml 模板

依赖项 haml
文件扩展名 .haml
例子 haml :index, :format => :html5

Erb 模板

依赖项 erubis 或 erb (Ruby 标准库中已经包含)
文件扩展名 .erb, .rhtml or .erubis (仅用于 Erubis)
例子 erb :index

Builder 模板

依赖项 builder
文件扩展名 .builder
例子 builder { |xml| xml.em "hi" }

builder 渲染方法也接受一个代码块，用于内联模板（见例子）。

Nokogiri 模板

依赖项 nokogiri
文件扩展名 .nokogiri
例子 nokogiri { |xml| xml.em "hi" }

nokogiri 渲染方法也接受一个代码块，用于内联模板（见例子）。

Sass 模板

依赖项 sass
文件扩展名 .sass
例子 sass :stylesheet, :style => :expanded

SCSS 模板

依赖项 sass
文件扩展名 .scss
例子 scss :stylesheet, :style => :expanded

Less 模板

依赖项 less
文件扩展名 .less
例子 less :stylesheet

Liquid 模板

依赖项 liquid
文件扩展名 .liquid
例子 liquid :index, :locals => { :key => 'value' }

因为不能在 Liquid 模板中调用 Ruby 方法（除了 yield），你几乎总是需要传递 locals 对象给它。

Markdown 模板

依赖项 下列任一: RDiscount, RedCarpet, BlueCloth, kramdown, maruku
文件扩展名 .markdown, .mkd and .md
例子 markdown :index, :layout_engine => :erb

不能在 markdown 中调用 Ruby 方法，也不能传递 locals 给它。 因此，你一般会结合其它的渲染引擎来使用它：

erb :overview, :locals => { :text => markdown(:introduction) }

请注意你也可以在其它模板中调用 markdown 方法：

%h1 Hello From Haml!
%p= markdown(:greetings)

因为不能在 Markdown 中使用 Ruby 语言，你不能使用 Markdown 书写的布局。 不过，使用其它渲染引擎作为模板的布局是可能的，这需要通过传入 :layout_engine 选项。

Textile 模板

依赖项 RedCloth
文件扩展名 .textile
例子 textile :index, :layout_engine => :erb

不能在 textile 中调用 Ruby 方法，也不能传递 locals 给它。 因此，你一般会结合其它的渲染引擎来使用它：

erb :overview, :locals => { :text => textile(:introduction) }

请注意你也可以在其他模板中调用 textile 方法：

%h1 Hello From Haml!
%p= textile(:greetings)

因为不能在 Textile 中调用 Ruby 方法，你不能用 Textile 书写布局。 不过，使用其它渲染引擎作为模版的布局是可能的，这需要通过传递 :layout_engine 选项。

RDoc 模板

依赖项 RDoc
文件扩展名 .rdoc
例子 rdoc :README, :layout_engine => :erb

不能在 rdoc 中调用 Ruby 方法，也不能传递 locals 给它。 因此，你一般会结合其它的渲染引擎来使用它：

erb :overview, :locals => { :text => rdoc(:introduction) }

请注意你也可以在其他模板中调用 rdoc 方法：

%h1 Hello From Haml!
%p= rdoc(:greetings)

因为不能在 RDoc 中调用 Ruby 方法，你不能用 RDoc 书写布局。 不过，使用其它渲染引擎作为模版的布局是可能的，这需要通过传递 :layout_engine 选项。

AsciiDoc 模板

依赖项 Asciidoctor
文件扩展名 .asciidoc, .adoc and .ad
例子 asciidoc :README, :layout_engine => :erb

因为不能在 AsciiDoc 模板中直接调用 Ruby 方法，你几乎总是需要传递 locals 对象给它。

Radius 模板

依赖项 Radius
文件扩展名 .radius
例子 radius :index, :locals => { :key => 'value' }

因为不能在 Radius 模板中直接调用 Ruby 方法，你几乎总是可以传递 locals 对象给它。

Markaby 模板

依赖项 Markaby
文件扩展名 .mab
例子 markaby { h1 "Welcome!" }

markaby 渲染方法也接受一个代码块，用于内联模板（见例子）。

RABL 模板

依赖项 Rabl
文件扩展名 .rabl
例子 rabl :index

Slim 模板

依赖项 Slim Lang
文件扩展名 .slim
例子 slim :index

Creole 模板

依赖项 Creole
文件扩展名 .creole
例子 creole :wiki, :layout_engine => :erb

不能在 creole 中调用 Ruby 方法，也不能传递 locals 对象给它。 因此你一般会结合其它的渲染引擎来使用它：

erb :overview, :locals => { :text => creole(:introduction) }

注意你也可以在其它模板内调用 creole 方法：

%h1 Hello From Haml!
%p= creole(:greetings)

因为不能在 Creole 模板文件内调用 Ruby 方法，你不能用 Creole 书写布局文件。 然而，使用其它渲染引擎作为模版的布局是可能的，这需要通过传递 :layout_engine 选项。

MediaWiki 模板

依赖项 WikiCloth
文件扩展名 .mediawiki and .mw
例子 mediawiki :wiki, :layout_engine => :erb

在 MediaWiki 标记文件内不能调用 Ruby 方法，也不能传递 locals 对象给它。 因此你一般会结合其它的渲染引擎来使用它：

erb :overview, :locals => { :text => mediawiki(:introduction) }

注意你也可以在其它模板内调用 mediawiki 方法：

%h1 Hello From Haml!
%p= mediawiki(:greetings)

因为不能在 MediaWiki 文件内调用 Ruby 方法，你不能用 MediaWiki 书写布局文件。 然而，使用其它渲染引擎作为模版的布局是可能的，这需要通过传递 :layout_engine 选项。

CoffeeScript 模板

依赖项 CoffeeScript 以及一种 执行 JavaScript 的方式
文件扩展名 .coffee
例子 coffee :index

Stylus 模板

依赖项 Stylus 以及一种 执行 JavaScript 的方式
文件扩展名 .styl
例子 stylus :index

在使用 Stylus 模板之前，你需要先加载 stylus 和 stylus/tilt：

require 'sinatra'
require 'stylus'
require 'stylus/tilt'

get '/' do
  stylus :example
end

Yajl 模板

依赖项 yajl-ruby
文件扩展名 .yajl
例子 yajl :index, :locals => { :key => 'qux' }, :callback => 'present', :variable => 'resource'

模板文件的源码作为一个 Ruby 字符串被求值，得到的 json 变量是通过 #to_json 方法转换的：

json = { :foo => 'bar' }
json[:baz] = key

可以使用 :callback 和 :variable 选项装饰被渲染的对象：

var resource = {"foo":"bar","baz":"qux"};
present(resource);

WLang 模板

依赖项 WLang
文件扩展名 .wlang
例子 wlang :index, :locals => { :key => 'value' }

因为在 WLang 中调用 Ruby 方法不符合语言习惯，你几乎总是需要传递 locals 给 WLang 木板。 然而，可以用 WLang 编写布局文件，也可以在 WLang 中使用 yield 方法。

在模板中访问变量

模板的求值发生在路由处理器内部的上下文中。模板可以直接访问路由处理器中设置的实例变量。

get '/:id' do
  @foo = Foo.find(params['id'])
  haml '%h1= @foo.name'
end

或者，也可以显式地指定一个由局部变量组成的 locals 哈希：

get '/:id' do
  foo = Foo.find(params['id'])
  haml '%h1= foo.name', :locals => { :foo => foo }
end

locals 哈希典型的使用情景是在别的模板中渲染 partials。

带 yield 的模板和嵌套布局

布局通常就是使用了 yield 方法的模板。 这样的布局文件可以通过上面描述的 :template 选项指定，也可以通过下面的代码块渲染：

erb :post, :layout => false do
  erb :index
end

这段代码几乎完全等同于 erb :index, :layout => :post。

向渲染方法传递代码块对于创建嵌套布局是最有用的：

erb :main_layout, :layout => false do
  erb :admin_layout do
    erb :user
  end
end

代码行数可以更少：

erb :admin_layout, :layout => :main_layout do
  erb :user
end

当前，以下的渲染方法接受一个代码块：erb、haml、liquid、slim 和 wlang。 通用的 render 方法也接受。

内联模板

模板可以在源文件的末尾定义：

require 'sinatra'

get '/' do
  haml :index
end

__END__

@@ layout
%html
  = yield

@@ index
%div.title Hello world.

注意：在引入了 sinatra 的源文件中定义的内联模板会自动载入。 如果你在其他源文件中也有内联模板，需要显式调用 enable :inline_templates。

具名模板

可以使用顶层 template 方法定义模板：

template :layout do
  "%html\n  =yield\n"
end

template :index do
  '%div.title Hello World!'
end

get '/' do
  haml :index
end

如果存在名为 “layout” 的模板，该模板会在每个模板渲染的时候作为布局使用。 你可以为渲染方法传送 :layout => false 来禁用该次渲染的布局， 也可以设置 set :haml, :layout => false 来默认禁用布局。

get '/' do
  haml :index, :layout => !request.xhr?
end

关联文件扩展名

为了将一个文件扩展名到对应的模版引擎，要使用 Tilt.register。 比如，如果你喜欢使用 tt 作为 Textile 模版的扩展名，你可以这样做:

Tilt.register :tt, Tilt[:textile]

添加自定义模板引擎

首先，通过 Tilt 注册你自定义的引擎，然后创建一个渲染方法：

Tilt.register :myat, MyAwesomeTemplateEngine

helpers do
  def myat(*args) render(:myat, *args) end
end

get '/' do
  myat :index
end

这段代码将会渲染 ./views/index.myat 文件。 查看 https://github.com/rtomayko/tilt 以了解更多关于 Tilt 的信息。

自定义模板查找逻辑

要实现自定义的模板查找机制，你可以构建自己的 #find_template 方法：

configure do
  set :views, [ './views/a', './views/b' ]
end

def find_template(views, name, engine, &block)
  Array(views).each do |v|
    super(v, name, engine, &block)
  end
end

过滤器

before 过滤器在每个请求之前调用，调用的上下文与请求的上下文相同，并且可以修改请求和响应。 在过滤器中设置的变量可以被路由和模板访问：

before do
  @note = 'Hi!'
  request.path_info = '/foo/bar/baz'
end

get '/foo/*' do
  @note #=> 'Hi!'
  params['splat'] #=> 'bar/baz'
end

after 过滤器在每个请求之后调用，调用上下文与请求的上下文相同，并且也会修改请求和响应。 在 before 过滤器和路由中设置的实例变量可以被 after 过滤器访问：

after do
  puts response.status
end

请注意：除非你显式使用 body 方法，而不是在路由中直接返回字符串， 响应主体在 after 过滤器是不可访问的， 因为它在之后才会生成。

过滤器可以可选地带有范式， 只有请求路径满足该范式时才会执行：

before '/protected/*' do
  authenticate!
end

after '/create/:slug' do |slug|
  session['last_slug'] = slug
end

和路由一样，过滤器也可以带有条件：

before :agent => /Songbird/ do
  # ...
end

after '/blog/*', :host_name => 'example.com' do
  # ...
end

辅助方法

使用顶层的 helpers 方法来定义辅助方法， 以便在路由处理器和模板中使用：

helpers do
  def bar(name)
    "#{name}bar"
  end
end

get '/:name' do
  bar(params['name'])
end

也可以在多个分散的模块中定义辅助方法：

module FooUtils
  def foo(name) "#{name}foo" end
end

module BarUtils
  def bar(name) "#{name}bar" end
end

helpers FooUtils, BarUtils

以上代码块与在应用类中包含模块等效。

使用会话

会话用于在请求之间保持状态。如果激活了会话，每一个用户会话都对应一个会话 hash：

enable :sessions

get '/' do
  "value = " << session['value'].inspect
end

get '/:value' do
  session['value'] = params['value']
end

会话加密

为提高安全性，cookie 中的会话数据使用HMAC-SHA1进行加密。会话加密的最佳实践应当是像HMAC-SHA1这样生成大于或等于64字节 (512 bits, 128 hex characters)的随机值。应当避免使用少于32字节(256 bits, 64 hex characters)的随机值。应当使用生成器来创建安全的密钥，而不是拍脑袋决定。

默认情况下，Sinatra会生成一个32字节的密钥，但随着应用程序的每次重新启动，它都会发生改变。如果有多个应用程序的实例，使用Sinatra生成密钥，每个实例将有不同的密钥，这可能不是您想要的。

为了更好的安全性和可用性，建议生成安全的随机密钥，并将其存储在运行应用程序的每个主机上的环境变量中，以便所有应用程序实例都将共享相同的密钥。并且应该定期更新会话密钥。下面是一些创建64比特密钥的例子:

生成密钥

$ ruby -e "require 'securerandom'; puts SecureRandom.hex(64)"
99ae8af...snip...ec0f262ac

生成密钥(小贴士)

MRI Ruby目前认为sysrandom gem使用系统的随机数生成器要比用户态的OpenSSL好。

$ gem install sysrandom
Building native extensions.  This could take a while...
Successfully installed sysrandom-1.x
1 gem installed

$ ruby -e "require 'sysrandom/securerandom'; puts SecureRandom.hex(64)"
99ae8af...snip...ec0f262ac

从环境变量使用密钥

将Sinatra的SESSION_SECRET环境变量设置为生成的值。在主机的重新启动之间保存这个值。由于这样做的方法会因系统而异，仅供说明之用：

# echo "export SESSION_SECRET=99ae8af...snip...ec0f262ac" >> ~/.bashrc

应用的密钥配置

如果SESSION SECRET环境变量不可用，将把应用的随机密钥设置为不安全的。

关于sysrandom gem的更多用法:

require 'securerandom'
# -or- require 'sysrandom/securerandom'
set :session_secret, ENV.fetch('SESSION_SECRET') { SecureRandom.hex(64) }

会话配置

如果你想进一步配置会话，可以在设置 sessions 时提供一个选项 hash 作为第二个参数：

set :sessions, :domain => 'foo.com'

为了在 foo.com 的子域名间共享会话数据，可以在域名前添加一个 .：

set :sessions, :domain => '.foo.com'

选择你自己的会话中间件

请注意 enable :sessions 实际将所有的数据保存在一个 cookie 中。 这可能并不总是你想要的（cookie 中存储大量的数据会增加你的流量）。 你可以使用任何 Rack session 中间件：要达到此目的，不要使用 enable :sessions， 而是按照自己的需要引入想使用的中间件：

enable :sessions
set :session_store, Rack::Session::Pool

另一种选择是不要调用enable：sessions，而是像你想要的其他中间件一样加入你的中间件。

重要的是要注意，使用此方法时，默认情况下不会启用基于会话的保护。

还需要添加Rack中间件：

use Rack::Session::Pool, :expire_after => 2592000
use Rack::Protection::RemoteToken
use Rack::Protection::SessionHijacking

更多安全防护配置的信息。

中断请求

要想在过滤器或路由中立即中断一个请求：

halt

你也可以指定中断时的状态码：

halt 410

或者响应主体：

halt 'this will be the body'

或者同时指定两者：

halt 401, 'go away!'

也可以指定响应首部：

halt 402, {'Content-Type' => 'text/plain'}, 'revenge'

当然也可以使用模板：

halt erb(:error)

传递请求

一个路由可以放弃对请求的处理并将处理让给下一个匹配的路由，这要通过 pass 实现：

get '/guess/:who' do
  pass unless params['who'] == 'Frank'
  'You got me!'
end

get '/guess/*' do
  'You missed!'
end

执行 pass 后，控制流从该路由代码块直接退出，并继续前进到下一个匹配的路由。 如果没有匹配的路由，将返回 404。

触发另一个路由

有些时候，pass 并不是你想要的，你希望得到的是调用另一个路由的结果。 使用 call 就可以做到这一点:

get '/foo' do
  status, headers, body = call env.merge("PATH_INFO" => '/bar')
  [status, headers, body.map(&:upcase)]
end

get '/bar' do
  "bar"
end

请注意在以上例子中，你只需简单地移动 "bar" 到一个被 /foo 和 /bar 同时使用的辅助方法中， 就可以简化测试和增加性能。

如果你希望请求发送到同一个应用，而不是应用副本，应使用 call! 而不是 call。

如果想更多了解关于 call 的信息，请查看 Rack 规范。

设置响应主体、状态码和响应首部

推荐在路由代码块的返回值中设定状态码和响应主体。 但是，在某些场景下你可能想在别处设置响应主体，这时你可以使用 body 辅助方法。 设置之后，你可以在那以后使用该方法访问响应主体：

get '/foo' do
  body "bar"
end

after do
  puts body
end

也可以传递一个代码块给 body 方法， 它会被 Rack 处理器执行（这可以用来实现流式传输，参见“返回值”）。

与响应主体类似，你也可以设定状态码和响应首部：

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 方法可以访问它们的当前值。

响应的流式传输

有时你可能想在完全生成响应主体前返回数据。 更极端的情况是，你希望在客户端关闭连接前一直发送数据。 为满足这些需求，可以使用 stream 辅助方法而不必重新造轮子：

get '/' do
  stream do |out|
    out << "It's gonna be legen -\n"
    sleep 0.5
    out << " (wait for it) \n"
    sleep 1
    out << "- dary!\n"
  end
end

stream 辅助方法允许你实现流式 API 和 服务器端发送事件， 同时它也是实现 WebSockets 的基础。 如果你应用的部分（不是全部）内容依赖于访问缓慢的资源，它也可以用来提高并发能力。

请注意流式传输，尤其是并发请求数，高度依赖于应用所使用的服务器。 一些服务器可能根本不支持流式传输。 如果服务器不支持，传递给 stream 方法的代码块执行完毕之后，响应主体会一次性地发送给客户端。 Shotgun 完全不支持流式传输。

如果 :keep_open 作为可选参数传递给 stream 方法，将不会在流对象上调用 close 方法， 这允许你在控制流的下游某处手动关闭。该参数只对事件驱动的服务器（如 Thin 和 Rainbows）生效。 其它服务器仍会关闭流式传输：

# 长轮询

set :server, :thin
connections = []

get '/subscribe' do
  # 在服务器端的事件中注册客户端
  stream(:keep_open) do |out|
    connections << out
    # 清除关闭的连接
    connections.reject!(&:closed?)
  end
end

post '/:message' do
  connections.each do |out|
    # 通知客户端有条新消息
    out << params['message'] << "\n"

    # 使客户端重新连接
    out.close
  end

  # 确认
  "message received"
end

日志

在请求作用域下，logger 辅助方法会返回一个 Logger 类的实例：

get '/' do
  logger.info "loading data"
  # ...
end

该 logger 方法会自动参考 Rack 处理器的日志设置。 若日志被禁用，该方法会返回一个无关痛痒的对象，所以你完全不必担心这会影响路由和过滤器。

注意只有 Sinatra::Application 默认开启了日志，若你的应用继承自 Sinatra::Base， 很可能需要手动开启：

class MyApp < Sinatra::Base
  configure :production, :development do
    enable :logging
  end
end

为避免使用任何与日志有关的中间件，需要将 logging 设置项设为 nil。 然而，在这种情况下，logger 辅助方法会返回 nil。 一种常见的使用场景是你想要使用自己的日志工具。 Sinatra 会使用 env['rack.logger'] 的值作为日志工具，无论该值是什么。

媒体类型

使用 send_file 或者静态文件的时候，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://www.google.com/', 'wrong place, buddy'

用 redirect back 可以把用户重定向到原始页面：

get '/foo' do
  "<a href='/bar'>do something</a>"
end

get '/bar' do
  do_something
  redirect back
end

如果想传递参数给 redirect，可以用查询字符串：

redirect to('/bar?sum=42')

或者使用会话：

enable :sessions

get '/foo' do
  session['secret'] = 'foo'
  redirect to('/bar')
end

get '/bar' do
  session['secret']
end

缓存控制

正确设置响应首部是合理利用 HTTP 缓存的基础。

可以这样设定 Cache-Control 首部字段：

get '/' do
  cache_control :public
  "cache it!"
end

核心提示: 应当在 before 过滤器中设定缓存。

before do
  cache_control :public, :must_revalidate, :max_age => 60
end

如果你使用 expires 辅助方法设定响应的响应首部， 会自动设定 Cache-Control 字段：

before do
  expires 500, :public, :must_revalidate
end

为了合理使用缓存，你应该考虑使用 etag 或 last_modified 方法。 推荐在执行繁重任务之前使用这些辅助方法，这样一来， 如果客户端在缓存中已经有相关内容，就会立即得到响应：

get '/article/:id' do
  @article = Article.find params['id']
  last_modified @article.updated_at
  etag @article.sha1
  erb :article
end

也可以使用 weak ETag：

etag @article.sha1, :weak

这些辅助方法并不会为你做任何缓存，而是将必要的信息发送给你的缓存。 如果你正在寻找快捷的反向代理缓存方案，可以尝试 rack-cache：

require "rack/cache"
require "sinatra"

use Rack::Cache

get '/' do
  cache_control :public, :max_age => 36000
  sleep 5
  "hello"
end

使用 :statis_cache_control 设置（见下文）为静态文件添加 Cache-Control 首部字段。

根据 RFC 2616，如果 If-Match 或 If-None-Match 首部设置为 *，根据所请求的资源存在与否， 你的应用应当有不同的行为。 Sinatra 假设安全请求（如 GET）和幂等性请求（如 PUT）所访问的资源是已经存在的， 而其它请求（如 POST 请求）所访问的资源是新资源。 你可以通过传入 :new_resource 选项改变这一行为。

get '/create' do
  etag '', :new_resource => true
  Article.create
  erb :new_article
end

如果你仍想使用 weak ETag，可以传入一个 :kind 选项：

etag '', :new_resource => true, :kind => :weak

发送文件

为了将文件的内容作为响应返回，可以使用 send_file 辅助方法：

get '/' do
  send_file 'foo.png'
end

该辅助方法接受一些选项:

send_file 'foo.png', :type => :jpg

可用的选项有:

filename
响应中使用的文件名，默认是真实的文件名。
last_modified
Last-Modified 响应首部的值，默认是文件的 mtime （修改时间）。
type
Content-Type 响应首部的值，如果未指定，会根据文件扩展名猜测。
disposition
Content-Disposition 响应首部的值， 可选的值有： nil (默认)、:attachment 和 :inline
length
Content-Length 响应首部的值，默认是文件的大小。
status
将要返回的状态码。当以一个静态文件作为错误页面时，这很有用。 
如果 Rack 处理器支持的话，Ruby 进程也能使用除 streaming 以外的方法。
如果你使用这个辅助方法， Sinatra会自动处理 range 请求。

访问请求对象

传入的请求对象可以在请求层（过滤器、路由、错误处理器内部）通过 request 方法访问：

# 在 http://example.com/example 上运行的应用
get '/foo' do
  t = %w[text/css text/html application/javascript]
  request.accept              # ['text/html', '*/*']
  request.accept? 'text/xml'  # true
  request.preferred_type(t)   # 'text/html'
  request.body                # 客户端设定的请求主体（见下文）
  request.scheme              # "http"
  request.script_name         # "/example"
  request.path_info           # "/foo"
  request.port                # 80
  request.request_method      # "GET"
  request.query_string        # ""
  request.content_length      # request.body 的长度
  request.media_type          # request.body 的媒体类型
  request.host                # "example.com"
  request.get?                # true (其它动词也具有类似方法)
  request.form_data?          # false
  request["some_param"]       # some_param 参数的值。[] 是访问 params hash 的捷径
  request.referrer            # 客户端的 referrer 或者 '/'
  request.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 （如果是 ssl 则为 true）
  request.forwarded?          # true （如果是运行在反向代理之后）
  request.env                 # Rack 中使用的未处理的 env hash
end

一些选项，例如 script_name 或者 path_info 也是可写的：

before { request.path_info = "/" }

get "/" do
  "all requests end up here"
end

request.body 是一个 IO 或者 StringIO 对象：

post "/api" do
  request.body.rewind  # 如果已经有人读了它
  data = JSON.parse request.body.read
  "Hello #{data['name']}!"
end

附件

你可以使用 attachment 辅助方法来告诉浏览器响应应当被写入磁盘而不是在浏览器中显示。

get '/' do
  attachment
  "store it!"
end

你也可以传递给该方法一个文件名：

get '/' do
  attachment "info.txt"
  "store it!"
end

处理日期和时间

Sinatra 提供了一个 time_for 辅助方法，其目的是根据给定的值生成 Time 对象。 该方法也能够转换 DateTime、Date 和类似的类：

get '/' do
  pass if Time.now > time_for('Dec 23, 2012')
  "still time"
end

expires、last_modified 和类似方法都在内部使用了该方法。 因此，通过在应用中重写 time_for 方法，你可以轻松地扩展这些方法的行为：

helpers do
  def time_for(value)
    case value
    when :yesterday then Time.now - 24*60*60
    when :tomorrow then Time.now + 24*60*60
    else super
    end
  end
end

get '/' do
  last_modified :yesterday
  expires :tomorrow
  "hello"
end

查找模板文件

find_template 辅助方法用于在渲染时查找模板文件：

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

你可以很容易地封装成一个扩展，然后与他人分享！

请注意 find_template 并不会检查文件是否存在，而是为任何可能的路径调用传入的代码块。 这并不会导致性能问题，因为 render 会在找到文件的时候马上使用 break。 同样的，模板的路径（和内容）会在 development 以外的模式下被缓存。 你应该时刻提醒自己这一点， 如果你真的想写一个非常疯狂的方法的话。

配置

在启动时运行一次，在任何环境下都是如此：

configure do
  # 设置一个选项
  set :option, 'value'

  # 设置多个选项
  set :a => 1, :b => 2

  # 等同于 `set :option, true`
  enable :option

  # 等同于 `set :option, false`
  disable :option

  # 也可以用代码块做动态设置
  set(:css_dir) { File.join(views, 'css') }
end

只有当环境 (APP_ENV 环境变量) 被设定为 :production 时才运行：

configure :production do
  ...
end

当环境被设定为 :production 或者 :test 时运行：

configure :production, :test do
  ...
end

你可以用 settings 访问这些配置项：

configure do
  set :foo, 'bar'
end

get '/' do
  settings.foo? # => true
  settings.foo  # => 'bar'
  ...
end

配置攻击防护

Sinatra 使用 Rack::Protection 来抵御常见的攻击。你可以轻易地禁用该行为（但这会大大增加应用被攻击的概率）。

disable :protection

为了绕过某单层防护，可以设置 protection 为一个选项 hash：

set :protection, :except => :path_traversal

你可以传入一个数组，以禁用一系列防护措施：

set :protection, :except => [:path_traversal, :session_hijacking]

默认地，如果 :sessions 是启用的，Sinatra 只会使用基于会话的防护措施。 当然，有时你可能想根据自己的需要设置会话。 在这种情况下，你可以通过传入 :session 选项来开启基于会话的防护。

use Rack::Session::Pool
set :protection, :session => true

可选的设置

absolute_redirects
如果被禁用，Sinatra 会允许使用相对路径重定向。 然而这样的话，Sinatra 就不再遵守 RFC 2616 (HTTP 1.1), 该协议只允许绝对路径重定向。
如果你的应用运行在一个未恰当设置的反向代理之后，你需要启用这个选项。 注意 url 辅助方法仍然会生成绝对 URL，除非你传入false 作为第二参数。
默认禁用。
add_charset
设置 content_type 辅助方法会自动为媒体类型加上字符集信息。 你应该添加而不是覆盖这个选项: settings.add_charset << "application/foobar"
app_file
主应用文件的路径，用来检测项目的根路径， views 和 public 文件夹和内联模板。
bind
绑定的 IP 地址 (默认: 0.0.0.0，开发环境下为 localhost)。 仅对于内置的服务器有用。
default_encoding
默认编码 (默认为 "utf-8")。
dump_errors
在日志中显示错误。
environment
当前环境，默认是 ENV['APP_ENV']， 或者 "development" (如果 ENV['APP_ENV'] 不可用)。
logging
使用 logger。
lock
对每一个请求放置一个锁，只使用进程并发处理请求。
如果你的应用不是线程安全则需启动。默认禁用。
method_override
使用 _method 魔法，以允许在不支持的浏览器中在使用 put/delete 方法提交表单。
port
监听的端口号。只对内置服务器有用。
prefixed_redirects
如果没有使用绝对路径，是否添加 request.script_name 到重定向请求。 如果添加，redirect '/foo' 会和 redirect to('/foo') 相同。 默认禁用。
protection
是否启用网络攻击防护。参见上面的保护部分
public_dir
public_folder 的别名。见下文。
public_folder
public 文件存放的路径。只有启用了静态文件服务（见下文的 static）才会使用。 如果未设置，默认从 app_file 推断。
reload_templates
是否每个请求都重新载入模板。在开发模式下开启。
root
到项目根目录的路径。默认从 app_file 设置推断。
raise_errors
抛出异常（会停止应用）。 当 environment 设置为 "test" 时会默认开启，其它环境下默认禁用。
run
如果启用，Sinatra 会负责 web 服务器的启动。若使用 rackup 或其他方式则不要启用。
running
内置的服务器在运行吗？ 不要修改这个设置！
server
服务器，或用于内置服务器的服务器列表。顺序表明了优先级，默认顺序依赖 Ruby 实现。
sessions
使用 Rack::Session::Cookie，启用基于 cookie 的会话。 查看“使用会话”部分以获得更多信息。
show_exceptions
当有异常发生时，在浏览器中显示一个 stack trace。 当 environment 设置为 "development" 时，默认启用， 否则默认禁用。
也可以设置为 :after_handler， 这会在浏览器中显示 stack trace 之前触发应用级别的错误处理。
static
决定 Sinatra 是否服务静态文件。
当服务器能够自行服务静态文件时，会禁用。
禁用会增强性能。
在经典风格中默认启用，在模块化应用中默认禁用。
static_cache_control
当 Sinatra 提供静态文件服务时，设置此选项为响应添加 Cache-Control 首部。 使用 cache_control 辅助方法。默认禁用。
当设置多个值时使用数组： set :static_cache_control, [:public, :max_age => 300]
threaded
若设置为 true，会告诉 Thin 使用 EventMachine.defer 处理请求。
traps
Sinatra 是否应该处理系统信号。
views
views 文件夹的路径。若未设置则会根据 app_file 推断。
x_cascade
若没有路由匹配，是否设置 X-Cascade 首部。默认为 true。

环境

Sinatra 中有三种预先定义的环境："development"、"production" 和 "test"。 环境可以通过 APP_ENV 环境变量设置。默认值为 "development"。 在开发环境下，每次请求都会重新加载所有模板， 特殊的 not_found 和 error 错误处理器会在浏览器中显示 stack trace。 在测试和生产环境下，模板默认会缓存。

在不同的环境下运行，设置 APP_ENV 环境变量：

APP_ENV=production ruby my_app.rb

可以使用预定义的三种方法： development?、test? 和 production? 来检查当前环境：

get '/' do
  if settings.development?
    "development!"
  else
    "not development"
  end
end

错误处理

错误处理器在与路由和 before 过滤器相同的上下文中运行， 这意味着你可以使用许多好东西，比如 haml, erb, halt，等等。

未找到

当一个 Sinatra::NotFound 错误被抛出时，或者当响应的状态码是 404 时， 会调用 not_found 处理器：

not_found do
  'This is nowhere to be found.'
end

错误

在任何路由代码块或过滤器抛出异常时，会调用 error 处理器。 但注意在开发环境下只有将 show exceptions 项设置为 :after_handler 时，才会生效。

set :show_exceptions, :after_handler

可以用 Rack 变量 sinatra.error 访问异常对象：

error do
  'Sorry there was a nasty error - ' + env['sinatra.error'].message
end

自定义错误：

error MyCustomError do
  'So what happened was...' + env['sinatra.error'].message
end

当下面的代码执行时：

get '/' do
  raise MyCustomError, 'something bad'
end

你会得到错误信息：

So what happened was... something bad

或者，你也可以为状态码设置错误处理器：

error 403 do
  'Access forbidden'
end

get '/secret' do
  403
end

或者为某个范围内的状态码统一设置错误处理器：

error 400..510 do
  'Boom'
end

在开发环境下，Sinatra会使用特殊的 not_found 和 error 处理器， 以便在浏览器中显示美观的 stack traces 和额外的调试信息。

Rack 中间件

Sinatra 依赖 Rack, 一个面向 Ruby 网络框架的最小化标准接口。 Rack 最有趣的功能之一是支持“中间件”——位于服务器和你的应用之间的组件， 它们监控或操作 HTTP 请求/响应以提供多种常用功能。

Sinatra 通过顶层的 use 方法，让建立 Rack 中间件管道异常简单：

require 'sinatra'
require 'my_custom_middleware'

use Rack::Lint
use MyCustomMiddleware

get '/hello' do
  'Hello World'
end

use 的语义和在 Rack::Builder DSL (在 rackup 文件中最频繁使用)中定义的完全一样。例如，use 方法接受 多个/可变参数，以及代码块：

use Rack::Auth::Basic do |username, password|
  username == 'admin' && password == 'secret'
end

Rack 拥有有多种标准中间件，用于日志、调试、URL 路由、认证和会话处理。 根据配置，Sinatra 可以自动使用这里面的许多组件， 所以你一般不需要显式地 use 它们。

你可以在 rack、 rack-contrib 或 Rack wiki 中找到有用的中间件。

测试

可以使用任何基于 Rack 的测试程序库或者框架来编写Sinatra的测试。 推荐使用 Rack::Test：

require 'my_sinatra_app'
require 'minitest/autorun'
require 'rack/test'

class MyAppTest < Minitest::Test
  include Rack::Test::Methods

  def app
    Sinatra::Application
  end

  def test_my_default
    get '/'
    assert_equal 'Hello World!', last_response.body
  end

  def test_with_params
    get '/meet', :name => 'Frank'
    assert_equal 'Hello Frank!', last_response.body
  end

  def test_with_rack_env
    get '/', {}, 'HTTP_USER_AGENT' => 'Songbird'
    assert_equal "You're using Songbird!", last_response.body
  end
end

注意：如果你使用 Sinatra 的模块化风格，应该用你应用的类名替代 Sinatra::Application。

Sinatra::Base - 中间件、库和模块化应用

在顶层定义你的应用很适合微型项目， 但是在构建可复用的组件（如 Rack 中间件、Rails metal、带服务器组件的库或 Sinatra 扩展）时， 却有相当大的缺陷。 顶层 DSL 认为你采用的是微型应用风格的配置 (例如：唯一应用文件、 ./public 和 ./views 目录、日志、异常细节页面等）。 如果你的项目不采用微型应用风格，应该使用 Sinatra::Base：

require 'sinatra/base'

class MyApp < Sinatra::Base
  set :sessions, true
  set :foo, 'bar'

  get '/' do
    'Hello world!'
  end
end

Sinatra::Base 的子类可以使用的方法实际上就是顶层 DSL 中可以使用的方法。 大部分顶层应用可以通过两方面的改变转换为 Sinatra::Base 组件：

  • 你的文件应当引入 sinatra/base 而不是 sinatra； 否则，Sinatra 的所有 DSL 方法将会被导入主命名空间。

  • 把应用的路由、错误处理器、过滤器和选项放在一个 Sinatra::Base 的子类中。

Sinatra::Base 是一个白板。大部分选项（包括内置的服务器）默认是禁用的。 可以参考配置 以查看可用选项的具体细节和它们的行为。如果你想让你的应用更像顶层定义的应用（即经典风格）， 你可以继承 Sinatra::Applicaiton。

require 'sinatra/base'

class MyApp < Sinatra::Application
  get '/' do
    'Hello world!'
  end
end

模块化风格 vs. 经典风格

与通常的认识相反，经典风格并没有任何错误。 如果它适合你的应用，你不需要切换到模块化风格。

与模块化风格相比，经典风格的主要缺点在于，每个 Ruby 进程只能有一个 Sinatra 应用。 如果你计划使用多个 Sinatra 应用，应该切换到模块化风格。 你也完全可以混用模块化风格和经典风格。

如果从一种风格转换到另一种，你需要注意默认设置中的一些细微差别：

设置 经典风格 模块化风格 模块化风格
app_file 加载 sinatra 的文件 继承 Sinatra::Base 的文件 继承 Sinatra::Application 的文件
run $0 == app_file false false
logging true false true
method_override true false true
inline_templates true false true
static true File.exist?(public_folder) true

运行一个模块化应用

模块化应用的启动有两种常见方式，其中之一是使用 run! 方法主动启动:

# my_app.rb
require 'sinatra/base'

class MyApp < Sinatra::Base
  # ... 这里是应用代码 ...

  # 如果直接执行该文件，那么启动服务器
  run! if app_file == $0
end

执行该文件就会启动服务器：

ruby my_app.rb

另一种方式是使用 config.ru 文件，这种方式允许你使用任何 Rack 处理器：

# config.ru （用 rackup 启动）
require './my_app'
run MyApp

运行：

rackup -p 4567

使用 config.ru 运行经典风格的应用

编写你的应用:

# app.rb
require 'sinatra'

get '/' do
  'Hello world!'
end

添加相应的 config.ru：

require './app'
run Sinatra::Application

何时使用 config.ru？

下列情况，推荐使用 config.ru：

  • 部署时使用不同的 Rack 处理器 (Passenger、Unicorn、Heroku 等)。
  • 使用多个 Sinatra::Base 的子类。
  • 把 Sinatra 当作中间件使用，而非端点。

你不必仅仅因为想使用模块化风格而切换到 config.ru，同样的， 你也不必仅仅因为要运行 config.ru 而切换到模块化风格。

把 Sinatra 当作中间件使用

Sinatra 可以使用其它 Rack 中间件， 反过来，任何 Sinatra 应用程序自身都可以被当作中间件，添加到任何 Rack 端点前面。 此端点可以是任何 Sinatra 应用，或任何基于 Rack 的应用程序 (Rails/Ramaze/Camping/...)：

require 'sinatra/base'

class LoginScreen < Sinatra::Base
  enable :sessions

  get('/login') { haml :login }

  post('/login') do
    if params['name'] == 'admin' && params['password'] == 'admin'
      session['user_name'] = params['name']
    else
      redirect '/login'
    end
  end
end

class MyApp < Sinatra::Base
  # 中间件的执行发生在 before 过滤器之前
  use LoginScreen

  before do
    unless session['user_name']
      halt "Access denied, please <a href='/login'>login</a>."
    end
  end

  get('/') { "Hello #{session['user_name']}." }
end

创建动态应用

有时你希望在运行时创建新应用，而不必把应用预先赋值给常量。这时可以使用 Sinatra.new：

require 'sinatra/base'
my_app = Sinatra.new { get('/') { "hi" } }
my_app.run!

Sinatra.new 接受一个可选的参数，表示要继承的应用：

# config.ru (用 rackup 启动)
require 'sinatra/base'

controller = Sinatra.new do
  enable :logging
  helpers MyHelpers
end

map('/a') do
  run Sinatra.new(controller) { get('/') { 'a' } }
end

map('/b') do
  run Sinatra.new(controller) { get('/') { 'b' } }
end

当你测试 Sinatra 扩展或在自己的类库中使用 Sinatra 时，这非常有用。

这也让把 Sinatra 当作中间件使用变得极其容易：

require 'sinatra/base'

use Sinatra do
  get('/') { ... }
end

run RailsProject::Application

作用域和绑定

当前作用域决定了可以使用的方法和变量。

应用/类作用域

每个 Sinatra 应用都对应 Sinatra::Base 类的一个子类。 如果你在使用顶层 DSL (require 'sinatra')，那么这个类就是 Sinatra::Application， 否则该类是你显式创建的子类。 在类层面，你可以使用 get 或 before 这样的方法， 但不能访问 request 或 session 对象, 因为对于所有的请求，只有单一的应用类。

通过 set 创建的选项是类方法：

class MyApp < Sinatra::Base
  # 嘿，我在应用作用域！
  set :foo, 42
  foo # => 42

  get '/foo' do
    # 嘿，我已经不在应用作用域了！
  end
end

下列位置绑定的是应用作用域：

  • 应用类内部
  • 通过扩展定义的方法内部
  • 传递给 helpers 方法的代码块内部
  • 作为 set 值的 procs/blocks 内部
  • 传递给 Sinatra.new 的代码块内部

你可以这样访问变量域对象（应用类）：

  • 通过传递给 configure 代码块的对象 (configure { |c| ... })
  • 在请求作用域中使用 settings

请求/实例作用域

对于每个请求，Sinatra 会创建应用类的一个新实例。所有的处理器代码块都在该实例对象的作用域中运行。 在该作用域中， 你可以访问 request 和 session 对象， 或调用渲染方法（如 erb、haml）。你可以在请求作用域中通过 settings 辅助方法 访问应用作用域：

class MyApp < Sinatra::Base
  # 嘿，我在应用作用域!
  get '/define_route/:name' do
    # '/define_route/:name' 的请求作用域
    @value = 42

    settings.get("/#{params['name']}") do
      # "/#{params['name']}" 的请求作用域
      @value # => nil (并不是同一个请求)
    end

    "Route defined!"
  end
end

以下位置绑定的是请求作用域：

  • get、head、post、put、delete、options、patch、link 和 unlink 代码块内部
  • before 和 after 过滤器内部
  • 辅助方法内部
  • 模板/视图内部

代理作用域

代理作用域只是把方法转送到类作用域。 然而，它与类作用域的行为并不完全相同, 因为你并不能在代理作用域获得类的绑定。 只有显式地标记为供代理使用的方法才是可用的， 而且你不能和类作用域共享变量/状态。(解释：你有了一个不同的 self)。 你可以通过调用 Sinatra::Delegator.delegate :method_name 显式地添加方法代理。

以下位置绑定的是代理变量域：

  • 顶层绑定，如果你执行了 require "sinatra"
  • 扩展了 Sinatra::Delegator 这一 mixin 的对象内部

自己在这里看一下源码：Sinatra::Delegator mixin 已经 被扩展进了 main 对象。

命令行

可以直接运行 Sinatra 应用：

ruby myapp.rb [-h] [-x] [-e ENVIRONMENT] [-p PORT] [-o HOST] [-s HANDLER]

选项是：

-h # 显示帮助
-p # 设置端口号 (默认是 4567)
-o # 设定主机名 (默认是 0.0.0.0)
-e # 设置环境 (默认是 development)
-s # 声明 rack 服务器/处理器 (默认是 thin)
-x # 打开互斥锁 (默认是 off)

多线程

根据 Konstantin 的 [这个 StackOverflow 答案] [so-answer] 改写

Sinatra 本身并不使用任何并发模型，而是将并发的任务留给底层的 Rack 处理器（服务器），如 Thin、Puma 或 WEBrick。Sinatra 本身是线程安全的，所以 Rack 处理器使用多线程并发模型并无任何问题。这意味着在启动服务器时，你必须指定特定 Rack 处理器的正确调用方法。 下面的例子展示了如何启动一个多线程的 Thin 服务器：

# app.rb

require 'sinatra/base'

class App < Sinatra::Base
  get '/' do
    "Hello, World"
  end
end

App.run!

启动服务器的命令是：

thin --threaded start

[so-answer]: http://stackoverflow.com/questions/6278817/is-sinatra-multi-threaded/6282999#6282999)

必要条件

以下 Ruby 版本受官方支持:

Ruby 1.8.7
Sinatra 完全支持 1.8.7，但是，除非必要，我们推荐你升级或者切换到 JRuby 或 Rubinius。Sinatra 2.0 之前都不会取消对 1.8.7 的支持。Ruby 1.8.6 目前已不受支持。
Ruby 1.9.2
Sinatra 完全支持 1.9.2。 不要使用 1.9.2p0，它在运行 Sinatra 程序时会产生 segmentation faults 错误。 至少在 Sinatra 1.5 发布之前，官方对 1.9.2 的支持仍会继续。
Ruby 1.9.3
Sinatra 完全支持并推荐使用 1.9.3。请注意从更早的版本迁移到 1.9.3 会使所有的会话失效。 直到 Sinatra 2.0 发布之前，官方仍然会支持 1.9.3。
Ruby 2.x
Sinatra 完全支持并推荐使用 2.x。目前尚无停止支持 2.x 的计划。
Rubinius
Sinatra 官方支持 Rubinius (Rubinius >= 2.x)。推荐 gem install puma。
JRuby
Sinatra 官方支持 JRuby 的最新稳定版本，但不推荐在 JRuby 上使用 C 扩展。 推荐 gem install trinidad。

我们也在时刻关注新的 Ruby 版本。

以下 Ruby 实现不受 Sinatra 官方支持，但可以运行 Sinatra：

  • 老版本 JRuby 和 Rubinius
  • Ruby 企业版
  • MacRuby、Maglev、IronRuby
  • Ruby 1.9.0 和 1.9.1 （不推荐使用）

不受官方支持的意思是，如果仅在不受支持的 Ruby 实现上发生错误，我们认为不是我们的问题，而是该实现的问题。

我们同时也针对 ruby-head （MRI 的未来版本）运行 CI，但由于 ruby-head 一直处在变化之中， 我们不能作任何保证。我们期望完全支持未来的 2.x 版本。

Sinatra 应该会运行在任何支持上述 Ruby 实现的操作系统上。

如果你使用 MacRuby，你应该 gem install control_tower。

Sinatra 目前不支持 Cardinal、SmallRuby、BlueRuby 或其它 1.8.7 之前的 Ruby 版本。

紧跟前沿

如果你想使用 Sinatra 的最新代码，请放心使用 master 分支来运行你的程序，它是相当稳定的。

我们也会不定期推出 prerelease gems，所以你也可以运行

gem install sinatra --pre

来获得最新的特性。

通过 Bundler 使用 Sinatra

如果你想在应用中使用最新的 Sinatra，推荐使用 Bundler。

首先，安装 Bundler，如果你还没有安装的话：

gem install bundler

然后，在你的项目目录下创建一个 Gemfile：

source 'https://rubygems.org'
gem 'sinatra', :github => "sinatra/sinatra"

# 其它依赖
gem 'haml'                    # 假如你使用 haml
gem 'activerecord', '~> 3.0'  # 也许你还需要 ActiveRecord 3.x

请注意你必须在 Gemfile 中列出应用的所有依赖项。 然而， Sinatra 的直接依赖项 (Rack 和 Tilt) 则会被 Bundler 自动获取和添加。

现在你可以这样运行你的应用:

bundle exec ruby myapp.rb

使用自己本地的 Sinatra

创建一个本地克隆，并通过 $LOAD_PATH 里的 sinatra/lib 目录运行你的应用：

cd myapp
git clone git://github.com/sinatra/sinatra.git
ruby -I sinatra/lib myapp.rb

为了在未来更新 Sinatra 源代码：

cd myapp/sinatra
git pull

全局安装

你可以自行编译 Sinatra gem：

git clone git://github.com/sinatra/sinatra.git
cd sinatra
rake sinatra.gemspec
rake install

如果你以 root 身份安装 gems，最后一步应该是：

sudo rake install

版本

Sinatra 遵循语义化版本，无论是 SemVer 还是 SemVerTag。

更多资料