# Sinatra 框架指南 > 适用于：Sinatra 3.x、Ruby 3.0+、REST API、微服务、原型语言指南：@.claude/skills/ruby-guide/SKILL.md ## 概述 Sinatra 是一种轻量级 DSL，用于在 Ruby 中构建 Web 应用程序和 API。它将 HTTP 动词直接映射到 Ruby 块，提供最少的仪式和最大的灵活性。 **在以下情况下使用 Sinatra：** * 构建微服务或中小型 API * 快速原型设计或概念验证工作 * 轻量级 webhooks、代理或内部工具 * 你想要最小的框架开销 **在以下情况下考虑替代方案：** * 你需要一个完整的MVC框架（使用Rails） * 您需要开箱即用的内置管理、ORM 和身份验证（使用 Rails） * 应用程序复杂度超过 10+ 路线模块（使用 Rails 或 Hanami） ## 护栏 ### Sinatra 特定指南 * 对生产应用程序使用模块化风格（`Sinatra::Base`） * 经典风格仅适用于脚本和原型 * 使用 `sinatra-contrib` 来支持 JSON、命名空间和重新加载器 * 使用Puma作为生产应用服务器 * 使用 Bundler 和 Gemfile 进行依赖管理 * 通过 `register` 和 `Sinatra::Namespace` 将路由分离到模块中 * 将助手提取到`app/helpers/`下的专用模块中 * 将服务对象用于业务逻辑（保持路由精简） ### 安全指南 * 切勿对秘密进行硬编码；通过 `dotenv` 使用环境变量 * 从“ENV”设置“session_secret”（不是生产中的随机回退） * 在处理之前验证所有用户输入 * 通过 ActiveRecord 或 Sequel ORM 使用参数化查询 * 使用“before”过滤器实施身份验证检查 * 在生产中使用带有适当 HSTS 标头的 HTTPS * 通过Rack中间件实现速率限制 * 限制性配置 CORS（生产环境中切勿使用“*”） ### 测试指南 * 使用 RSpec 和 `rack-test` 进行 HTTP 集成测试 * 使用“database_cleaner”在测试之间重置状态 * 测试每个端点的成功和错误路径 * 模拟外部服务（永远不要在测试中调用真实的 API） * 使用factory_bot进行测试数据设置 * 覆盖率目标：业务逻辑>80% ## 项目结构 ### 简单应用程序（仅限原型）我的应用程序/ ├── app.rb # 所有路由和配置 ├── config.ru # 机架配置 ├── Gemfile ├── public/ # 静态资产 ├── 视图/ # ERB/Haml 模板 │ ├── 布局.erb │ └── 索引.erb └── 规格/ └── app_spec.rb ### 模块化应用程序（生产）我的应用程序/ ├── config.ru # 机架入口点 ├── Gemfile ├── Rakefile # 数据库任务 ├── 应用程序/ │ ├── main.rb # Sinatra::基础应用程序类 │ ├──routes/ # 路由模块（每个资源一个） │ │ ├── auth.rb │ │ ├── 用户.rb │ │ └── posts.rb │ ├── models/ # ActiveRecord/Sequel 模型 │ │ ├── 用户.rb │ │ └── post.rb │ ├── services/ # 业务逻辑（无 Sinatra 导入） │ │ └── user_service.rb │ └── helpers/ # 可重用的帮助模块 │ ├── auth_helper.rb │ └── 响应_helper.rb ├── 配置/ │ ├── 数据库.yml │ └──environment.rb # 启动：dotenv、bundler、DB setup ├── 分贝/ │ └── 迁徙/ ├── 公开/ ├── 浏览量/ └── 规格/ ├── spec_helper.rb ├── 路线/ └── 型号/ 主要约定： * `app/main.rb` 包含 `Sinatra::Base` 子类并将所有内容连接在一起 * `app/routes/` 为每个资源保存一个模块，通过 `register` 注册 * `app/services/` 保存业务逻辑，没有框架耦合 * `app/helpers/` 包含通过 `helpers` DSL 包含的模块 * `config/environment.rb` 启动 dotenv、捆绑器和数据库连接 ## 路由 DSL Sinatra 将 HTTP 动词直接映射到 Ruby 块。参数通过 `:name` 符号捕获。 # 基本CRUD路由获取 '/users' { json users: User.all.map(&:to_h) } 获取 '/users/:id' { json 用户: find_user!.to_h } 发布 '/users' { create_user } 把 '/users/:id' { update_user } 删除“/users/:id”{delete_user} ### 路由参数 # 命名参数（在 params hash 中可用）获取 '/users/:id' 执行 user = User.find(params[:id]) json 用户：user.to_h 结束 # Splat（通配符）参数获取 '/files/*.*' 执行 # params['splat'] => ['路径/到/文件', 'ext'] 结束 # 查询参数获取“/搜索” # 参数[:q], 参数[:页] 结束 # 正则表达式路由获取 %r{/posts/(\d+)} 执行 |id| 帖子.find(id) 结束 ### 命名空间路由使用 `sinatra/namespace` 对具有共享前缀的路由进行分组。需要“sinatra/命名空间” 类 App < Sinatra::Base 注册 Sinatra:: 命名空间命名空间 '/api/v1' 执行命名空间 '/users' 执行获取 { json 用户: User.all.map(&:to_h) } 发布{创建用户} 获取 '/:id' 执行 json 用户：User.find(params[:id]).to_h 结束结束结束结束 ## 请求和响应 ### 读取请求数据 # JSON 主体（为了安全使用助手） def json_params @json_params ||= 开始正文 = request.body.read 身体.空？？ {} : JSON.parse(body, symbolize_names: true) 结束拯救 JSON::ParserError 停止 400，json（错误：'无效的 JSON'）结束 # 表单数据参数[:字段名称] # 标题 request.env['HTTP_AUTHORIZATION'] 请求内容类型 request.accept?('application/json') ### 响应模式 # JSON 响应（通过 sinatra/json）得到 '/health' 做 json 状态：'ok'，时间戳：Time.now.iso8601 结束 # 状态码发布'/用户'做用户 = User.create!(json_params) 状态 201 json 用户：user.to_h 结束 # 因错误而停止（立即停止执行）停止 404，json（错误：“未找到”）停止 401，json（错误：“未经授权”）停止 422，json（错误：user.errors.full_messages） # 重定向重定向“/登录” 重定向 '/users', 303 # 查看其他 # 标题 headers 'X-Custom-Header' => '值' 内容类型：json ## 助手定义路由和视图中可用的可重用方法。 # 在模块化风格中，定义辅助模块模块AuthHelper def 当前用户 @current_user ||= User.find_by(id: session[:user_id]) if session[:user_id] 结束 def require_login！暂停 401，json（错误：'未经授权'）除非 current_user 结束 def require_admin！需要登录！停止 403，json（错误：'禁止'）除非 current_user.admin？结束结束响应助手模块 def 分页（集合，每页：20）页面 = (params[:页面] || 1).to_i per = (params[:per_page] || per_page).to_i 总计 = 集合.count items = collection.offset((page - 1) * per).limit(per) { 项目：项目，元：{ 页：页，per_page：每，总计：总计 } } 结束结束 # 在应用程序中注册类 App < Sinatra::Base 助手 AuthHelper 帮助者 ResponseHelper 结束 ## 视图和模板 Sinatra 支持 ERB、Haml、Slim 和其他 Tilt 兼容的模板引擎。对于 JSON API，完全跳过视图并使用“json”帮助器。 # 渲染模板（在views/目录中查找）得到 '/' 做 @title = '家' erb :index # 渲染views/index.erb 结束 # 自定义布局获取“/admin”执行 erb：仪表板，布局：：admin_layout 结束通过“views/layout.erb”中的“<%= yield %>”使用模板继承。将逻辑排除在模板之外；使用路由中设置的帮助器和实例变量。 ## 错误处理 ### 错误处理程序类 App < Sinatra::Base # 命名错误处理程序 not_found 做 json 错误：“未找到” 结束错误做 json 错误：“内部服务器错误” 结束 # 捕获特定的异常错误 ActiveRecord::RecordNotFound 做状态404 json 错误：“找不到资源” 结束 |e| 错误 ActiveRecord::RecordInvalid 状态 422 json 错误：e.record.errors.full_messages 结束错误 JSON::ParserError 执行状态 400 json 错误：“无效的 JSON” 结束结束 ### 特定于环境的错误显示配置：开发做启用：显示异常启用：日志记录结束配置：生产做禁用：显示异常启用：raise_errors 结束 ## 过滤器使用“before”和“after”过滤器来处理横切关注点。类 App < Sinatra::Base # 在每个请求之前运行之前做 content_type :json 如果 request.accept?('application/json') 结束 # 作用域为路径前缀在 '/api/*' 之前内容类型：json 验证令牌！结束 # 在每个请求之后运行做完之后 response.headers['X-Request-Id'] = SecureRandom.uuid 结束结束 ## 模块化应用模式 ### 应用程序类 (app/main.rb) 需要“sinatra/base” 需要“sinatra/json” 需要“sinatra/命名空间” 类 App < Sinatra::Base 注册 Sinatra:: 命名空间配置做设置：服务器，：puma 设置 :root, File.dirname(__FILE__) set :views, proc { File.join(root, '..', 'views') } 启用：会话设置 :session_secret, ENV.fetch('SESSION_SECRET') 结束配置：开发做需要“sinatra/reloader” 注册 Sinatra::Reloader 启用：日志记录结束 Dir[File.join(__dir__, 'helpers', '*.rb')].each { |f|需要 f } 助手 AuthHelper、ResponseHelper Dir[File.join(__dir__, 'routes', '*.rb')].each { |f|需要 f } 注册路线::用户注册路由::验证 get('/health') { json status: 'ok' } not_found { json 错误: '未找到' } error { json error: '内部服务器错误' } 结束 ### 路由模块 (app/routes/users.rb) 模块路线模块用户 def self.注册（应用程序） app.namespace '/api/v1/users' 做获取 { json 用户: User.all.map(&:to_h) } get('/:id') { json user: User.find(params[:id]).to_h } 事后做用户 = User.create!(json_params) 状态 201 json 用户：user.to_h 救援 ActiveRecord::RecordInvalid => e 状态 422 json 错误：e.record.errors.full_messages 结束结束结束结束结束 ### 机架配置 (config.ru) 需要“捆绑器/设置” Bundler.require(:default, ENV.fetch('RACK_ENV', 'development')) require_relative '配置/环境' require_relative '应用程序/主' 运行应用程序 ## 命令参考 # 安装依赖项捆绑安装 # 运行开发服务器（自动重新加载）捆绑执行 ruby app.rb # 或者使用机架捆绑执行rackup -p 4567 # 运行测试捆绑执行 rspec Bundle exec rspec --format 文档 # 覆盖运行 Bundle exec rspec --格式化进度 --require simplecov # 数据库任务捆绑执行 rake db:create 捆绑执行 rake db:migrate 捆绑执行 rake db:rollback # 生产服务器捆绑执行 puma -C config/puma.rb # 控制台（交互式）捆绑执行 pry -r ./config/environment # 码头工人 docker build -t myapp 。 docker run -p 4567:4567 myapp ## 依赖关系宝石 |目的 ---|--- `西纳特拉` | Web 框架 DSL `sinatra-contrib` |扩展：JSON、命名空间、重新加载器美洲狮生产应用服务器 `耙子` |用于迁移的任务运行程序 `dotenv` |环境变量加载 `activerecord` / `sequel` |用于数据库访问的 ORM `pg` | PostgreSQL 适配器 `bcrypt` |密码散列（`has_secure_password`） `jwt` | JSON Web Token 身份验证 `rspec` |测试框架 `机架测试` | Rack 应用程序的 HTTP 请求助手 `database_cleaner-active_record` |测试之间的数据库清理 `factory_bot` |测试数据工厂 ## 高级主题有关详细代码示例和高级模式，请参阅： * [references/patterns.md]() \-- 数据库集成、身份验证（会话和 JWT）、Rack 中间件、测试模式、部署和 Sequel ORM 替代方案 ## 外部参考 * [Sinatra 文档]() * [Sinatra 食谱]() * [Sinatra GitHub]() * [Sinatra Contrib]() * [机架文档]()

西纳特拉

包含技能