Sinatra是Ruby生态中最具代表性的微型Web框架，诞生于2007年，至今依然保持着活跃的维护。它的设计哲学非常简单：用最少的代码完成Web开发中最核心的事情——接收请求、匹配路由、返回响应。一个最小的Sinatra应用只需要三行代码就能跑起来，这种极简风格让它在写内部工具、小型API、Webhook接收器这类场景时，效率远超Rails这样的全功能框架。本文将从基础概念、核心知识点、常见问题三个层面，把Sinatra讲透。
一、Sinatra是什么，和Rails有什么区别
要理解Sinatra的定位，先要明白Ruby Web开发的底层是Rack。Rack是Ruby的Web服务器接口标准，所有主流Ruby框架都构建在它之上。Sinatra本质上就是一层薄薄的路由分发器：它接收Rack传来的请求，根据你定义的路由规则找到对应的处理代码块，执行后把结果包装成HTTP响应返回。
Rails是全栈框架，自带ORM、迁移、视图、资产管道、约定优于配置的一整套体系，适合构建复杂的业务系统。Sinatra则几乎什么都没带，数据库要自己选，模板引擎要自己配，项目结构完全由你决定。这不是缺陷，而是刻意的取舍。官方给它的定位是DSL（领域专用语言），你可以把它理解为“带HTTP路由功能的Ruby脚本”。
两者并不冲突，很多团队会混合使用：主站用Rails，独立的轻量服务用Sinatra。一些知名的Ruby项目，比如Travis CI早期版本、GitHub内部的部分服务，都用过Sinatra。选择的标准很简单：如果项目需要快速验证想法、接口数量不多、不需要复杂的模型层，Sinatra是更轻快的选择。
二、核心知识点：路由、参数与过滤器
1. 安装与最小应用
安装只需要一条命令，推荐在项目目录下单独管理Gem依赖。创建一个文件app.rb，写入如下内容即可运行。
# 安装：gem install sinatra require 'sinatra' get '/' do 'Hello Sinatra!' end
启动方式有两种：直接执行ruby app.rb，Sinatra会内置服务器在4567端口启动；更规范的做法是写一个config.ru文件，用Rack标准方式启动，这样便于后续部署到Passenger、Puma等生产服务器。
2. 路由定义与匹配规则
Sinatra的路由是按HTTP动词加URL模式定义的，支持get、post、put、patch、delete等全部常见动词。URL中可以用冒号定义命名参数，参数值会存入params哈希。
get '/hello/:name' do
"你好, #{params['name']}"
end
# 通配符路由，splat的值是数组
get '/download/*.*' do |path, ext|
"下载文件: #{path}.#{ext}"
end
# 正则路由
get %r{/api/v(\d+)/users} do |ver|
"API版本: v#{ver}"
end
需要注意匹配顺序：Sinatra是从上到下依次匹配的，第一个命中的路由生效。如果你先定义了get '/posts/new'，再定义get '/posts/:id'，访问/posts/new时会正确命中前者。但如果顺序反过来，new会被当成:id捕获，这是新手最常踩的坑之一。同类路由中，具体的路径一定要放在带参数的路径前面。
3. 参数获取的三种方式
路由参数、查询字符串、表单数据最终都会合并进params，这让取值很方便，但也意味着可能被覆盖。更严谨的做法是区分来源。
post '/users' do
# 查询字符串：/users?debug=true
debug = request.params['debug']
# JSON请求体需要手动解析
body = JSON.parse(request.body.read)
"创建用户: #{body['name']}"
end
如果是JSON请求，Sinatra 2.0之后需要自己解析请求体，2.2版本起也提供了更友好的方式。文件上传则通过params['file'][:tempfile]拿到临时文件对象，直接用Ruby的文件IO读取即可。
4. 过滤器、helpers与钩子
过滤器分为前置和后置。before块在每次请求进入路由前执行，常用于鉴权、设置编码、记录日志；after块在响应完成后执行。helpers定义的方法可以在路由块和视图中直接调用，相当于框架层面的工具方法集合。
before '/admin/*' do
halt 401, '未授权' unless session[:user_id]
end
helpers do
def current_user
User.find(session[:user_id])
end
def json_response(data)
content_type :json
data.to_json
end
end
halt是中断请求的关键方法，可以立即返回指定的状态码和响应体，在错误处理和权限控制中非常有用。error块则用来集中处理异常，配合settings.environment可以在开发环境显示详细错误、生产环境只返回友好提示。
三、进阶用法：模块化应用、模板与部署
1. 经典风格与模块化风格
直接在顶层写路由叫经典风格，适合小脚本。当项目变大时，应该改用模块化风格，把应用定义成一个类，便于组织多个控制器、做单元测试和挂载中间件。
require 'sinatra/base'
class AppController < Sinatra::Base
configure :development do
set :show_exceptions, true
end
get '/' do
'模块化应用首页'
end
end
# config.ru
# run AppController
模块化风格还能通过继承扩展出多个子应用，比如定义一个AdminApp < Sinatra::Base，再用map在config.ru中把/admin路径映射过去，实现简单的路由分组效果。
2. 模板与静态文件
Sinatra默认支持ERB模板，也集成了Haml、Slim、Liquid等引擎。模板文件默认放在views目录，布局文件是layout.erb，也可以在渲染时指定别的布局或禁用布局。
get '/page/:id' do
@title = "页面 #{params['id']}"
erb :show, layout: :application # 指定布局
# erb :show, layout: false # 禁用布局
end
静态文件默认从public目录提供，通过set :public_folder, 'assets'可以修改目录。开发环境下模板和静态文件修改后刷新即生效，无需重启，这一点比很多框架方便。
3. 部署到生产环境
生产环境绝不建议直接ruby app.rb启动，因为内置的WEBrick性能和稳定性都不够。标准做法是用Puma或Unicorn配合Rackup，前面加Nginx做反向代理。数据库连接推荐使用Sequel或ActiveRecord独立引入，Sinatra 2.x对ActiveRecord的支持需要配合sinatra-activerecord扩展。
# Gemfile # gem 'sinatra' # gem 'puma' # 启动：RACK_ENV=production bundle exec puma -p 9292 config.ru
四、常见问题汇总
问题1：session为什么存不进数据？默认情况下session是启用的，但如果修改了session_secret或者跨域访问，会出问题。生产环境务必显式设置密钥：set :session_secret, ENV['SESSION_KEY']，并注意默认session是基于签名的Cookie，容量只有4KB左右，不适合存大量数据，需要时应换用Redis等服务端存储。
问题2：路由不生效，总是404？优先检查三点：一是同动词下是否有更早定义的路由抢占了匹配；二是POST请求是否被CSRF保护中间件拦截；三是模块化风格下是否忘记把新的子应用挂进config.ru。另外注意Sinatra默认不启用HEAD以外的隐式路由，写错HTTP动词不会自动降级到GET。
问题3：中文乱码怎么办？在before块中加content_type 'text/html', charset: 'utf-8'，同时确保源文件本身以UTF-8编码保存。返回JSON时用content_type :json，Rack会自动带上正确的字符集。
问题4：热重载不生效？生产环境代码不会热加载，这是正常行为。开发环境可以用sinatra/reloader扩展，在configure :development块中register Sinatra::Reloader并enable :reloader，修改文件后即可自动重载。
总体来说，Sinatra的学习曲线非常平缓，一个下午就能掌握全部常用功能。它的价值不在于替代Rails，而在于提供了一种“按需取用”的开发方式：你要多少，它给多少。理解了Rack、路由、过滤器这几个核心概念之后，再回头看Rails的中间件机制和路由系统，会有更清晰的认知，这也是很多Ruby老手推荐新人先玩Sinatra再学Rails的原因。
SinatraRuby Web框架Sinatra路由修改时间：2026-09-13 23:51:20