Внимание: Этот документ является переводом Английской версии и может быть устаревшим
Sinatra — это предметно-ориентированный каркас (DSL) для быстрого создания функциональных веб-приложений на Ruby:
# myapp.rb
require 'sinatra'
get '/' do
'Hello world!'
end
Установите gem:
gem install sinatra
и запустите приложение с помощью:
ruby -rubygems myapp.rb
Результат можно увидеть: localhost:4567
Рекомендуется также установить thin, сделать это можно командой: gem install thin
. Thin - это более производительный и функциональный сервер для разработки приложений на Sinatra.
В Sinatra маршрут — это пара: <HTTP метод> и <шаблон URL>. Каждый маршрут ассоциирован с блоком кода, исполняемого внутри, пример:
get '/' do
.. что-то показать ..
end
post '/' do
.. что-то создать ..
end
put '/' do
.. что-то заменить ..
end
patch '/' do
.. что-то изменить ..
end
delete '/' do
.. что-то удалить ..
end
options '/' do
.. что-то ответить ..
end
Маршруты сверяются с запросом в порядке очередности их записи в файле приложения. По умолчанию, будет вызван первый совпавший с запросом маршрут.
Шаблоны маршрутов могут включать в себя параметры доступные в params
xэше:
get '/hello/:name' do
# соответствует "GET /hello/foo" и "GET /hello/bar",
# где params[:name] 'foo' или 'bar'
"Hello #{params[:name]}!"
end
Можно также использовать именные параметры в переменных блоков:
get '/hello/:name' do |n|
"Hello #{n}!"
end
Шаблоны маршрутов также могут включать splat (или ‘*’ маску, обозначающую любой символ) параметры доступные в массиве params[:splat]
:
get '/say/*/to/*' do
# соответствует /say/hello/to/world
params[:splat] # => ["hello", "world"]
end
get '/download/*.*' do
# соответствует /download/path/to/file.xml
params[:splat] # => ["path/to/file", "xml"]
end
Маршруты также могут содержать регулярные выражения:
get %r{/hello/([\w]+)} do
"Hello, #{params[:captures].first}!"
end
Или с параметром блока:
get %r{/hello/([\w]+)} do |c|
"Hello, #{c}!"
end
Маршруты могут включать различные условия совпадений, такие как user agent:
get '/foo', :agent => /Songbird (\d\.\d)[\d\/]*?/ do
"You're using Songbird version #{params[:agent][0]}"
end
get '/foo' do
# соответствует non-songbird браузерам
end
Другими доступными условиями являются host_name
и provides
:
get '/', :host_name => /^admin\./ do
"Admin Area, Access denied!"
end
get '/', :provides => 'html' do
haml :index
end
get '/', :provides => ['rss', 'atom', 'xml'] do
builder :feed
end
Вы можете задать собственные условия:
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
Возвращаемое значение блока маршрута ограничивается телом ответа, которое будет передано HTTP клиенту, или следующей “прослойкой” (middleware) в Rack стеке. Чаще всего это строка, как в примерах выше. Но и другие значения также приемлемы.
Вы можете вернуть любой объект, который будет либо корректным Rack ответом, объектом Rack body, либо кодом состояния HTTP:
-
массив с тремя переменными:
[status (Fixnum), headers (Hash), response body (должен отвечать на #each)]
; -
массив с двумя переменными:
[status (Fixnum), response body (должен отвечать на #each)]
; -
объект, отвечающий на
#each
, который передает только строковые типы данных в этот блок; -
Fixnum, представляющий код состояния HTTP.
Таким образом, мы легко можем создать поточный пример:
class Stream
def each
100.times { |i| yield "#{i}\n" }
end
end
get('/') { Stream.new }
Как показано выше, Sinatra поставляется со встроенной поддержкой строк и регулярных выражений в качестве шаблонов URL. Но и это еще не все. Вы можете легко определить свои собственные детекторы совпадений (matchers) для маршрутов:
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
:
set :public, File.dirname(__FILE__) + '/static'
Учтите, что имя директории со статическими файлами не включено в URL. Например, файл ./public/css/style.css
будет доступен как http://example.com/css/style.css
.
Шаблоны по умолчанию должны находиться в директории ./views
. Для использования другой директории шаблонов:
set :views, File.dirname(__FILE__) + '/templates'
Важно помнить, что вы всегда должны указывать шаблоны с помощью символов, даже если это подкаталог (в этом случае используйте :'subdir/template'
). Вы должны использовать символ, иначе методы рендеринга, отобразят просто переданную им строку.
haml
gem/библиотека необходима для рендеринга HAML шаблонов:
# Вам нужно будет подключить haml gem в приложении
require 'haml'
get '/' do
haml :index
end
Отобразит ./views/index.haml
.
Опции Haml могут быть установлены глобально через конфигурацию Sinatra, см. Опции и Конфигурация, и переопределены локально.
set :haml, :format => :html5 # :xhtml - Haml формат по умолчанию
get '/' do
haml :index, :format => :html4 # переопределен
end
# Вам нужно будет подключить erb в приложении
require 'erb'
get '/' do
erb :index
end
Отобразит ./views/index.erb
.
erubis
gem/библиотека необходима для рендеринга Erubis шаблонов:
# Вам нужно будет подключить Erubis в приложении
require 'erubis'
get '/' do
erubis :index
end
Отобразит ./views/index.erubis
.
Также возможно заменить Erb на Erubis:
require 'erubis'
Tilt.register :erb, Tilt[:erubis]
get '/' do
erb :index
end
Отобразит ./views/index.erb
с помощью Erubis.
builder
gem/библиотека необходима для рендеринга builder шаблонов:
# Вам нужно будет подключить builder в приложении
require 'builder'
get '/' do
builder :index
end
Отобразит ./views/index.builder
.
nokogiri
gem/библиотека необходима для рендеринга nokogiri шаблонов:
# Вам нужно будет подключить nokogiri в приложении
require 'nokogiri'
get '/' do
nokogiri :index
end
Отобразит ./views/index.nokogiri
.
haml
gem/библиотека необходима для рендеринга Sass шаблонов:
# Вам нужно будет подключить haml или sass в приложении
require 'sass'
get '/stylesheet.css' do
sass :stylesheet
end
Отобразит ./views/stylesheet.sass
.
Опции Sass могут быть установлены глобально через конфигурацию Sinatra, см. Опции и Конфигурация, и переопределены локально.
set :sass, :style => :compact # :nested - стиль Sass по умолчанию
get '/stylesheet.css' do
sass :stylesheet, :style => :expanded # переопределен
end
haml
gem/библиотека необходима для рендеринга Scss шаблонов:
# Вам нужно будет подключить haml или sass в приложении
require 'sass'
get '/stylesheet.css' do
scss :stylesheet
end
Отобразит ./views/stylesheet.scss
.
Опции Scss могут быть установлены глобально через конфигурацию Sinatra, см. Опции и Конфигурация, и переопределены локально.
set :scss, :style => :compact # :nested - стиль Scss по умолчанию
get '/stylesheet.css' do
scss :stylesheet, :style => :expanded # переопределен
end
less
gem/библиотека необходима для рендеринга Less шаблонов:
# Вам нужно будет подключить less в приложении
require 'less'
get '/stylesheet.css' do
less :stylesheet
end
Отобразит ./views/stylesheet.less
.
liquid
gem/библиотека необходима для рендеринга liquid шаблонов:
# Вам нужно будет подключить liquid в приложении
require 'liquid'
get '/' do
liquid :index
end
Отобразит ./views/index.liquid
.
Так как в Liquid шаблонах невозможно вызывать методы из Ruby (кроме yield
), то вы почти всегда будете передавать локальные переменные:
liquid :index, :locals => { :key => 'value' }
rdiscount
gem/библиотека необходима для рендеринга Markdown шаблонов:
# Вам нужно будет подключить rdiscount в приложении
require 'rdiscount'
get '/' do
markdown :index
end
Отобразит ./views/index.markdown
(md
и mkd
также являются допустимыми файловыми расширениями).
В Markdown невозможно вызывать методы или передавать локальные переменные. Следовательно, вам, скорее всего, придется использовать этот шаблон совместно с другим движком рендеринга:
erb :overview, :locals => { :text => markdown(:introduction) }
Заметьте, что вы можете вызывать метод markdown
из других шаблонов:
%h1 Hello From Haml!
%p= markdown(:greetings)
Вы не можете вызывать Ruby из Markdown, соответственно, вы не можете использовать лэйаут-шаблоны (layouts) на Markdown. Тем не менее, есть возможность использовать один движок рендеринга для шаблона, а другой для лэйаута (разметки) с помощью опции :layout_engine
:
get '/' do
markdown :index, :layout_engine => :erb
end
Отобразит ./views/index.md
с ./views/layout.erb
в качестве лэйаута (разметки).
Также вы можете задать такие опции рендеринга глобально:
set :markdown, :layout_engine => :haml, :layout => :post
get '/' do
markdown :index
end
Отобразит ./views/index.md
(и любой другой шаблон на Markdown) с ./views/post.haml
в качестве лэйаута (разметки).
Также возможно обрабатывать Markdown с помощью BlueCloth, а не RDiscount:
require 'bluecloth'
Tilt.register 'markdown', BlueClothTemplate
Tilt.register 'mkd', BlueClothTemplate
Tilt.register 'md', BlueClothTemplate
get '/' do
markdown :index
end
Отобразит ./views/index.md
с помощью BlueCloth.
RedCloth
gem/библиотека необходима для рендеринга Textile шаблонов:
# Вам нужно будет подключить redcloth в приложении
require 'redcloth'
get '/' do
textile :index
end
Отобразит ./views/index.textile
.
В Textile невозможно вызывать методы или передавать локальные переменные. Следовательно, вам, скорее всего, придется использовать этот шаблон совместно с другим движком рендеринга:
erb :overview, :locals => { :text => textile(:introduction) }
Заметьте, что вы можете вызывать метод textile
из других шаблонов:
%h1 Hello From Haml!
%p= textile(:greetings)
Вы не можете вызывать Ruby из Textile, соответственно, вы не можете использовать лэйаут-шаблоны на Textile. Тем не менее, есть возможность использовать один движок рендеринга для шаблона, а другой для лэйаута (разметки) с помощью опции :layout_engine
:
get '/' do
textile :index, :layout_engine => :erb
end
Отобразит ./views/index.textile
с ./views/layout.erb
в качестве лэйаута (разметки).
Также вы можете задать такие опции рендеринга глобально:
set :textile, :layout_engine => :haml, :layout => :post
get '/' do
textile :index
end
Отобразит ./views/index.textile
(и любой другой шаблон на Textile) с ./views/post.haml
в качестве лэйаута (разметки).
rdoc
gem/библиотека необходима для рендеринга RDoc шаблонов:
# Вам нужно будет подключить rdoc/markup/to_html в приложении
require 'rdoc/markup/to_html'
get '/' do
rdoc :index
end
Отобразит ./views/index.rdoc
.
В RDoc невозможно вызывать методы или передавать локальные переменные. Следовательно, вам, скорее всего, придется использовать этот шаблон совместно с другим движком рендеринга:
erb :overview, :locals => { :text => rdoc(:introduction) }
Заметьте, что вы можете вызывать метод rdoc
из других шаблонов:
%h1 Hello From Haml!
%p= rdoc(:greetings)
Вы не можете вызывать Ruby из RDoc, соответственно, вы не можете использовать лэйаут-шаблоны на RDoc. Тем не менее, есть возможность использовать один движок рендеринга для шаблона, а другой для лэйаута (разметки) с помощью опции :layout_engine
:
get '/' do
rdoc :index, :layout_engine => :erb
end
Отобразит ./views/index.rdoc
с ./views/layout.erb
в качестве лэйаута (разметки).
Также вы можете задать такие опции рендеринга глобально:
set :rdoc, :layout_engine => :haml, :layout => :post
get '/' do
rdoc :index
end
Отобразит ./views/index.rdoc
(и любой другой шаблон на RDoc) с ./views/post.haml
в качестве лэйаута (разметки).
radius
gem/библиотека необходима для рендеринга Radius шаблонов:
# Вам нужно будет подключить radius в приложении
require 'radius'
get '/' do
radius :index
end
Отобразит ./views/index.radius
.
Так как в Radius шаблоне невозможно вызывать методы из Ruby (кроме yield
), то вы почти всегда будете передавать локальные переменные:
radius :index, :locals => { :key => 'value' }
markaby
gem/библиотека необходима для рендеринга Markaby шаблонов:
# Вам нужно будет подключить markaby в приложении
require 'markaby'
get '/' do
markaby :index
end
Отобразит ./views/index.mab
.
Вы также можете использовать внутристроковые Markaby шаблоны:
get '/' do
markaby { h1 "Welcome!" }
end
slim
gem/библиотека необходима для рендеринга slim шаблонов:
# Вам нужно будет подключить slim в приложении
require 'slim'
get '/' do
slim :index
end
Отобразит ./views/index.slim
.
Вам понадобится coffee-script
gem/библиотека и что-то одно из следующего списка, чтобы запускать JavaScript:
-
node
(из Node.js); -
вы можете использовать OS X (в которой есть встроенные средства для выполнения JavaScript);
-
therubyracer
gem/библиотека.
Подробнее смотрите на странице проекта.
Таким образом, вы можете использовать CoffeeScript шаблоны.
# Вам нужно будет подключить coffee-script gem в приложении
require 'coffee-script'
get '/application.js' do
coffee :application
end
Отобразит ./views/application.coffee
.
get '/' do
haml '%div.title Hello World'
end
Отобразит строку встроенного шаблона.
Шаблоны интерпретируются в том же контексте, что и обработчики маршрутов. Переменные экземпляра, установленные в процессе обработки маршрутов, будут доступны напрямую в шаблонах:
get '/:id' do
@foo = Foo.find(params[:id])
haml '%h1= @foo.name'
end
Либо установите их через хеш локальных переменных:
get '/:id' do
foo = Foo.find(params[:id])
haml '%h1= foo.name', :locals => { :foo => foo }
end
Это обычный подход, когда шаблоны рендерятся как части других шаблонов.
Шаблоны также могут быть определены в конце исходного файла:
require 'sinatra'
get '/' do
haml :index
end
__END__
Заметьте: вложенные шаблоны, определенные в исходном файле, который подключила 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
. Чтобы узнать больше о Tilt, смотрите github.com/rtomayko/tilt
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
-фильтрах, так как оно будет сгенерировано позднее.
Фильтры могут использовать шаблоны URL и будут интерпретированы только если путь запроса совпадет с этим шаблоном:
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
Сессия используется, чтобы сохранять состояние между запросами. Если эта опция включена, то у вас будет один хэш сессии на одну пользовательскую сессию:
enable :sessions
get '/' do
"value = " << session[:value].inspect
end
get '/:value' do
session[:value] = params[:value]
end
Заметьте, что при использовании enable :sessions
все данные сохраняются в cookies. Это может быть не совсем то, что вы хотите (например, сохранение больших объемов данных увеличит ваш трафик). В таком случае вы можете использовать альтернативную Rack “прослойку” (middleware), реализующую механизм сессий. Для этого *не надо* вызывать enable :sessions
, вместо этого следует подключить ее также как и любую другую “прослойку”:
use Rack::Session::Pool, :expire_after => 2592000
get '/' do
"value = " << session[:value].inspect
end
get '/:value' do
session[:value] = params[:value]
end
Для повышения безопасности данные сессии в куках подписываются секретным ключом. Секретный ключ генерируется Sinatra. Тем не менее, так как этот ключ будет меняться с каждым запуском приложения, вы, возможно, захотите установить ключ вручную, чтобы у всех экземпляров вашего приложения быд один и тот же ключ:
set :session_secret, 'super secret'
Если вы хотите больше настроек для сессий, вы можете задать их, передав хэш опций в параметр sessions
:
set :sessions, :domain => 'foo.com'
Чтобы незамедлительно прервать обработку запроса внутри фильтра или маршрута, используйте:
halt
Можно также указать статус при прерывании:
halt 410
Тело:
halt 'this will be the body'
И то, и другое:
halt 401, 'go away!'
Можно указать заголовки:
halt 402, {'Content-Type' => 'text/plain'}, 'revenge'
И, конечно, можно использовать шаблоны с halt
:
halt erb(:error)
Маршрут может передать обработку запроса следующему совпадающему маршруту, используя pass
:
get '/guess/:who' do
pass unless params[:who] == 'Frank'
'You got me!'
end
get '/guess/*' do
'You missed!'
end
Блок маршрута сразу же прерывается, и контроль переходит к следующему совпадающему маршруту. Если соответствующий маршрут не найден, то ответом на запрос будет 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.
Хорошим тоном является установка кода состояния HTTP и тела ответа в возвращаемом значении обработчика маршрута. Тем не менее, в некоторых ситуациях вам, возможно, понадобится задать тело ответа в произвольной точке потока исполнения. Вы можете сделать это с помощью метода-помощника body
. Если вы задействуете метод 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
, вызванные без аргументов, возвращают свои текущие значения.
В области видимости запроса метод logger
предоставляет доступ к экземпляру Logger
:
get '/' do
logger.info "loading data"
# ...
end
Этот логер автоматически учитывает ваши настройки логирования в Rack. Если логирование выключено, то этот метод вернет пустой (dummy) объект, поэтому вы можете смело использовать его в маршрутах и фильтрах.
Заметьте, что логирование включено по умолчанию только для Sinatra::Application
, а если ваше приложение – подкласс Sinatra::Base
, то вы, наверное, захотите включить его вручную:
class MyApp < Sinatra::Base
configure(:production, :development) do
enable :logging
end
end
Когда вы используете send_file
или статические файлы, у вас могут быть mime-типы, которые Sinatra не понимает по умолчанию. Используйте mime_type
для их регистрации по расширению файла:
mime_type :foo, 'text/foo'
Вы также можете использовать это в content_type
методе-помощнике:
get '/' do
content_type :foo
"foo foo foo"
end
Чтобы сформировать 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'
Вы также можете перенаправить пользователя обратно, на страницу с которой он пришел, с помощью redirect back
:
get '/foo' do
"<a href='/bar'>do something</a>"
end
get '/bar' do
do_something
redirect back
end
Чтобы передать какие-либо параметры вместе с перенаправлением, либо добавьте их в строку запроса:
redirect to('/bar?sum=42')
Либо используйте сессию:
enable :session
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
Для отправки файлов пользователю вы можете использовать метод send_file
:
get '/' do
send_file 'foo.png'
end
Этот метод имеет несколько опций:
send_file 'foo.png', :type => :jpg
Возможные опции:
- filename
-
имя файла, по умолчанию: реальное имя файла.
- last_modified
-
значение для заголовка Last-Modified, по умолчанию: mtime (время изменения) файла.
- type
-
тип файла, по умолчанию: предполагается по расширению файла.
- disposition
-
используется для заголовка Content-Disposition, возможные значения:
nil
(по умолчанию),:attachment
и:inline
. - length
-
значения для заголовка Content-Length, по умолчанию: размер файла.
Этот метод будет использовать возможности Rack сервера для отправки файлов, если они доступны, а в противном случае, будет напрямую отдавать файл из Ruby процесса. Метод send_file
также обеспечивает автоматическую обработку частичных (range) запросов с помощью Sinatra.
Объект входящего запроса доступен на уровне обработки запроса (в фильтрах, маршрутах, обработчиках ошибок) с помощью request
метода:
# приложение запущено на http://example.com/example
get '/foo' do
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.media_type # медиатип тела запроса
request.host # "example.com"
request.get? # true (есть аналоги для других методов HTTP)
request.form_data? # false
request["SOME_HEADER"] # значение заголовка SOME_HEADER
request.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 (true, если запрос сделан через SSL)
request.forwarded? # true (если сервер работает за обратным прокси)
request.env # "сырой" env хеш, полученный Rack
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
Для поиска шаблонов и их последующего рендеринга используется метод 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
Вы можете легко вынести этот код в расширение и поделиться им с остальными!
Заметьте, что <tt>find_template</tt не проверяет, существует ли файл на самом деле, а вызывает заданный блок для всех возможных путей. Дело тут не в производительности, дело в том, что render
вызовет break
, как только файл не будет найден. Содержимое и местонахождение шаблонов будет закэшировано, если приложение запущено не в режиме разработки (set :environment, :development). Вы должны помнить об этих нюансах, если пишите по-настоящему “сумашедший” метод.
Этот блок исполняется один раз при старте в любом окружении, режиме (environment):
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
Будет запущено, когда окружение (RACK_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
- absolute_redirects
-
если отключено, то Sinatra будет позволять использование относительных перенаправлений, тем не менее, Sinatra перестанет соответствовать RFC 2616 (HTTP 1.1), который разрешает только абсолютные перенаправления.
Включайте эту опцию, если ваше приложение работает за обратным прокси, который настроен не совсем корректно. Обратите внимание, метод
url
все равно будет генерировать абсолютные URL, если вы не передадитеfalse
вторым аргументом.Отключено по умолчанию.
- add_charsets
-
mime-типы, к которым метод
content_type
будет автоматически добавлять информацию о кодировке.Вам следует добавлять значения к этой опции вместо ее переопределения:
settings.add_charsets << "application/foobar"
- app_file
-
главный файл приложения, используется для определения корневой директории проекта, директорий с шаблонами и статическими файлами, вложенных шаблонов.
- bind
-
используемый IP-адрес (по умолчанию: 0.0.0.0). Используется только встроенным сервером.
- default_encoding
-
кодировка, если неизвестна (по умолчанию:
"utf-8"
). - dump_errors
-
отображать ошибки в логе.
- environment
-
текущее окружение, по умолчанию, значение
ENV['RACK_ENV']
или"development"
, еслиENV['RACK_ENV']
не доступна. - logging
-
использовать логер.
- lock
-
создает блокировку для каждого запроса, которая гарантирует обработку только одного запроса в текущий момент времени в Ruby процессе.
Включайте, если ваше приложение не потоко-безопасно (thread-safe). Отключено по умолчанию.
- method_override
-
использовать “магический” параметр
_method
, чтобы позволить использование PUT/DELETE форм в браузерах, которые не поддерживают эти методы. - port
-
порт, на котором будет работать сервер. Используется только встроенным сервером.
- prefixed_redirects
-
добавлять или нет параметр
request.script_name
к редиректам, если не задан абсолютный путь. Таким образом,redirect '/foo'
будет вести себя какredirect to('/foo')
. Отключено по умолчанию. - public
-
директория, откуда будут раздаваться статические файлы.
- reload_templates
-
перезагружать или нет шаблоны на каждый запрос. Включено в режиме разработки.
- root
-
корневая директория проекта.
- raise_errors
-
выбрасывать исключения (будет останавливать приложение).
- run
-
если включено, Sinatra будет самостоятельно запускать веб-сервер. Не включайте, если используете rackup или аналогичные средства.
- running
-
работает ли сейчас встроенный сервер? Не меняйте эту опцию!
- server
-
сервер или список серверов, которые следует использовать в качестве встроенного сервера. По умолчанию: [‘thin’, ‘mongrel’, ‘webrick’], порядок задает приоритет.
- sessions
-
включить сессии на основе кук (cookie).
- show_exceptions
-
показывать исключения/стек вызовов (stack trace) в браузере.
- static
-
должна ли Sinatra осуществлять раздачу статических файлов. Отключите, когда используете какой-либо веб-сервер для этой цели. Отключение значительно улучшит производительность приложения. Включено по умолчанию.
- views
-
директория с шаблонами.
Обработчики ошибок исполняются в том же контексте, что и маршруты, before
-фильтры, а это означает, что всякие прелести вроде haml
, erb
, halt
и т.д. доступны и им.
Когда выброшено исключение Sinatra::NotFound
, или кодом ответа является 404, то будет вызван not_found
обработчик:
not_found do
'This is nowhere to be found.'
end
Обработчик ошибок error
будет вызван, когда исключение выброшено из блока маршрута, либо из фильтра. Объект-исключение доступен как переменная sinatra.error
в Rack:
error do
'Sorry there was a nasty error - ' + env['sinatra.error'].name
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
Также вы можете установить обработчик ошибок для кода состояния HTTP:
error 403 do
'Access forbidden'
end
get '/secret' do
403
end
Либо набора кодов:
error 400..510 do
'Boom'
end
Sinatra устанавливает специальные not_found
и error
обработчики, когда приложение запущено в режиме разработки (окружение :development
).
Sinatra использует Rack, минимальный стандартный интерфейс для веб-фреймворков на Ruby. Одной из самых интересных для разработчиков возможностей Rack является поддержка “прослоек” (“middleware”) — компонентов, находящихся “между” сервером и вашим приложением, которые отслеживают и/или манипулируют HTTP запросами/ответами для предоставления различной функциональности.
В Sinatra очень просто использовать такие “прослойки” с помощью метода use
:
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
) их вручную.
Тесты для Sinatra приложений могут быть написаны с помощью библиотек, фреймворков, поддерживающих тестирование Rack. Rack::Test рекомендован:
require 'my_sinatra_app'
require 'test/unit'
require 'rack/test'
class MyAppTest < Test::Unit::TestCase
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::Test и класс Sinatra::TestHarness являются устаревшими, начиная с релиза 0.9.2.
Описание своего приложения самым простейшим способом (с помощью DSL верхнего уровня, как в примерах выше) работает отлично для крохотных приложений, но имеет множество недостатков, когда надо создать компоненты, такие как Rack middleware (“прослойки”), Rails metal, простые библиотеки с серверными компонентами, расширения Sinatra.
DSL верхнего уровня “загрязняет” пространство имен Object
и подразумевает стиль конфигурации микро-приложения (например, единый файл приложения, ./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 будут импортированы в глобальное пространство имен. -
Поместите все маршруты, обработчики ошибок, фильтры и опции в подкласс Sinatra::Base.
Sinatra::Base
— это чистый лист. Большинство опций, включая встроенный сервер, по умолчанию отключены. Смотрите Опции и Конфигурация для детальной информации об опциях и их поведении.
Вопреки всеобщему убеждению в классическом стиле (самом простом) нет ничего плохого. Если этот стиль подходит вашему приложению, вы не обязаны переписывать его в модульное приложение.
У классического стиля есть всего два недостатка относительно модульного:
-
У вас может быть только одно приложение Sinatra на Ruby процесс. Если вы планируете использовать больше, то переключайтесь на модульный стиль.
-
Приложения, использующие классический стиль, добавляют методы к Object. Если вы планируете поставлять свое приложение в виде библиотеки/gem, то переключайтесь на модульный стиль.
Не существует причин, по которым вы не могли бы смешивать модульный и классический стили.
Переходя с одного стиля на другой, примите во внимание следующие изменения в настройках:
Опция Классический Модульный
app_file файл с приложением nil
run $0 == app_file false
logging true false
method_override true false
inline_templates true false
Есть два общепринятых способа запускать модульные приложения: запуск напрямую с помощью 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
require 'my_app'
run MyApp
Запускаем:
rackup -p 4567
Файл приложения:
# app.rb
require 'sinatra'
get '/' do
'Hello world!'
end
И соответствующий config.ru
:
require 'app'
run Sinatra::Application
Вот несколько причин, по которым вы, возможно, захотите использовать config.ru
:
-
вы хотите разворачивать свое приложение на различных Rack-совместимых серверах (Passenger, Unicorn, Heroku, …);
-
вы хотите использовать более одного подкласса
Sinatra::Base
; -
вы хотите использовать Sinatra только в качестве “прослойки” Rack.
Совсем необязательно переходить на использование config.ru
лишь потому, что вы стали использовать модульный стиль приложения. И необязательно использовать модульный стиль, чтобы запускать приложение с помощью config.ru
.
Не только сам Sinatra может использовать “прослойки” Rack, но и любое Sinatra приложение само может быть добавлено к любому Rack endpoint в качестве “прослойки”. Этим endpoint (конечной точкой) может быть другое 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' and params[:password] = 'admin'
session['user_name'] = params[:name]
else
redirect '/login'
end
end
end
class MyApp < Sinatra::Base
# "прослойка" будет запущена перед фильтрами
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 приложение соответствует подклассу 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
.
Вы можете получить доступ к объекту области видимости (классу приложения) следующими способами:
-
через объект, переданный блокам конфигурации (
configure { |c| ... }
); -
settings
внутри области видимости запроса.
Для каждого входящего запроса будет создан новый экземпляр вашего приложения, и все блоки обработчика будут запущены в этом контексте. В этой области видимости вам доступны 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 блоков;
-
before/after фильтрах;
-
методах-помощниках;
-
шаблонах/отображениях.
Область видимости делегирования просто перенаправляет методы в область видимости класса. Однако, оно не полностью на 100% ведет себя как область видимости класса, так как у вас нету привязки к классу: только методы, явно помеченные для делегирования, будут доступны, а переменных/состояний области видимости класса не будет (иначе говоря, у вас будет другой self
объект). Вы можете непосредственно добавить методы делегирования, используя Sinatra::Delegator.delegate :method_name
.
У вас будет контекст делегирования внутри:
-
привязки верхнего уровня, если вы сделали
require 'sinatra'
; -
объекта, расширенного с помощью
Sinatra::Delegator
.
Посмотрите сами в код: тут Sinatra::Delegator примесь будет включена в глобальное пространство имен.
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 # включить мьютекс-блокировку (по умолчанию выключена)
Следующие версии Ruby официально поддерживаются:
- Ruby 1.8.7
-
1.8.7 полностью поддерживается, тем не менее, если вас ничто не держит на этой версии, рекомендуем обновиться до 1.9.2 или перейти на JRuby или Rubinius.
- Ruby 1.9.2
-
1.9.2 поддерживается и рекомендована к использованию. Заметьте, что Radius и Markaby пока несовместимы с 1.9.2. Не используйте 1.9.2p0, известно, что эта версия весьма не стабильна при использовании Sinatra.
- Rubinius
-
Rubinius официально поддерживается (Rubinius >= 1.2.3), всё, включая все языки шаблонов, работает.
- JRuby
-
JRuby официально поддерживается (JRuby >= 1.6.0). Нет никаких проблем с использованием альтернативных шаблонов. Тем не менее, если вы выбираете JRuby, то, пожалуйста, посмотрите на JRuby Rack-сервера, так как Thin не поддерживается полностью на JRuby. Поддержка расширений на C в JRuby все еще экспериментальная, что на данный момент затрагивает только RDiscount.
Ruby 1.8.6 больше не поддерживается.
Мы также следим за предстоящими к выходу версиями Ruby.
Следующие реализации Ruby не поддерживаются официально, но известно, что на них запускается Sinatra:
-
старые версии JRuby и Rubinius;
-
MacRuby, Maglev, IronRuby;
-
Ruby 1.9.0 и 1.9.1;
-
Ruby 1.8.6 с помощью backports.
То, что версия официально не поддерживается, означает, что, если что-то не работает на этой версии, а на поддерживаемой работает - это не наша проблема, а их.
Мы также запускаем наши CI-тесты на последней версии Ruby (предстоящий 1.9.3), но мы не можем ничего гарантировать, так как она постоянно развивается. Предполагается, что 1.9.3p0 будет поддерживаться.
Sinatra должна работать на любой операционной системе, в которой есть одна из указанных выше версий Ruby.
Если вы хотите использовать самый последний код Sinatra, не бойтесь запускать свое приложение вместе из master ветки Sinatra, она весьма стабильна.
Мы также время от времени выпускаем предварительные версии, так что вы можете делать так:
gem install sinatra --pre
Чтобы воспользоваться некоторыми самыми последними возможностями.
Если вы хотите запускать свое приложение с последней версией Sinatra, то рекомендуем использовать Bundler.
Сначала установите 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 и Tilt) Bundler автоматически скачает и добавит.
Теперь вы можете запускать свое приложение так:
bundle exec ruby myapp.rb
Создайте локальный клон репозитория и запускайте свое приложение с sinatra/lib
директорией в $LOAD_PATH
:
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
Если вы устанавливаете пакеты (gem) от пользователя root, то вашим последним шагом должна быть команда
sudo rake install
Sinatra использует Semantic Versioning, SemVer и SemVerTag.
-
Веб-сайт проекта - Дополнительная документация, новости и ссылки на другие ресурсы.
-
Участие в проекте - Обнаружили баг? Нужна помощь? Написали патч?
-
#sinatra on freenode.net