Grape — 用 Ruby DSL 专写 REST API 的轻量框架

是什么

Grape 是一个 Ruby 写的 REST API 框架，跑在 Rack 上，可以独立部署，也能挂在 Rails / Sinatra 旁边专门吃 /api 这条路径。日常类比：如果 Rails 是装修齐全的精装公寓——浴室厨房客厅都给你配好；Sinatra 是空毛坯——你想挂幅画都得自己钉钉子；那 Grape 就是专做办公空间装修的”商业 SaaS 改造商”——它不管你住不住人，只管把”前台 / 会议室 / 接线员”这些办公用得到的工位给你一次配好。

最经典的”三行 API”长这样：

class API < Grape::API
  get :hello do
    { hello: 'world' }
  end
end

把它挂到 config.ru 里 run API，跑 rackup，访问 /hello 就拿到 {"hello":"world"}。没有 view、没有 asset、没有 helper，只有 API——这就是 Grape 的卖点。

为什么重要

不理解 Grape，下面这些事都没法解释：

• 为什么 Ruby 社区写纯 JSON API 时，会在 Rails 之外再搬一个框架——Rails 的 ERB / asset pipeline / cookie / session 在 API 场景全是负担
• 为什么”参数校验”这个看似小事，能让一个框架活 15 年——前端传错类型是 80% 后端 bug 的源头
• 为什么 API 版本策略（path / header / param）值得专门有 DSL 支持——线上 v1 / v2 共存是常态
• 为什么 FastAPI / NestJS 这些后来者的”声明式参数 + 类型转换”思路，跟 Grape 的 params do requires ... end 几乎一模一样

核心要点

Grape 的设计可以拆成 三块：

1. 类化 DSL：每个 API 是一个 class MyAPI < Grape::API，里面用 get / post / put / delete 声明路由。类比：像在白板上贴一摞便利贴——左边写”什么动词 + 什么路径”，右边写”怎么回复”。

2. params 块做参数校验：requires :id, type: Integer 一行就完成”必填 + 类型转换 + 错误响应”。请求进来如果 id 不是整数，直接 400 不进 handler。类比：像饭店门口的安检——不带身份证不让进，handler 里只见合法客人。

3. format / rescue_from / version 三件套：format :json 决定响应类型；rescue_from ArgumentError 集中处理异常；version 'v1', using: :path 切版本。类比：开 API 餐厅的”菜单格式 / 投诉处理台 / v1 v2 两个分店”。

三块加起来叫 Grape DSL——它没发明新东西，但把”写 API 这件事”的 80% 重复劳动压缩到了声明里。

实践案例

案例 1：三行起一个 API + Rack 挂载

api.rb：

require 'grape'
class API < Grape::API
  format :json
  get :hello do
    { hello: 'world' }
  end
end

config.ru：

require './api'
run API

跑 rackup，浏览器访问 http://localhost:9292/hello，拿到 JSON。整个工程没有数据库、没有路由文件、没有目录结构——这是 Grape 最低成本的 hello world。

案例 2：params 块自动校验 + 类型转换

class API < Grape::API
  format :json
  params do
    requires :id, type: Integer
    optional :tag, type: String, regexp: /\A[a-z]+\z/
  end
  get :user do
    { id: params[:id], tag: params[:tag] }
  end
end

逐部分解释：

• requires :id, type: Integer —— id 必填，前端传字符串 "42" 也会被自动转成整数 42
• regexp: /\A[a-z]+\z/ —— tag 如果传了，必须全小写英文字母
• 任何一条失败，Grape 直接返回 400 + 错误信息，handler 内部一行 if 都不用写

这是 Grape 比 Sinatra 多出的核心价值——校验逻辑被推到边界。

案例 3：挂在 Rails 旁边专做 /api 路径

config/routes.rb：

Rails.application.routes.draw do
  mount API => '/api'
  # 老 Rails 路由继续
  resources :posts
end

老 Rails 项目逐步对外开放 API 时，不需要重写——把新 API 写在 Grape 里，挂到 /api，老页面继续用 ERB。Rails 5 之后虽然有 --api 模式，但 Grape 的 DSL 仍然在”参数声明 / 版本管理”上更紧凑。

踩过的坑

1. mount 顺序：Rack::Cascade 时 Grape 必须放最后——Grape 对未匹配路由返回 404，Cascade 看到 404 就跳下一个 app，结果你期望的”API 不存在”变成了下一个 app 的 500 页。

2. route_param 优先级高于 params 里的同名 key：同时有 route_param :id 和 requires :id 时，handler 拿到的是路径段那个 id，params 里那个永远被覆盖——新人调试半小时找不到为什么。

3. Rails Zeitwerk autoloader 默认把 api 推断成 Api 不是 API：如果你类名写 class API < Grape::API，Rails 7 启动直接报常量找不到——必须在 config/initializers/inflections.rb 里加 inflect.acronym 'API'。

4. optional 参数的默认值也会过校验器：如果你给 optional :tag 设了不满足 regexp 的默认值，每次请求都会失败——错觉是用户传错了，其实是默认值自己错了。

适用 vs 不适用场景

适用：

• 纯 JSON / XML API 服务（移动端后端 / 小程序后端 / SaaS API）
• 老 Rails 项目逐步开放 API，但不想重写整个工程
• 多版本 API 共存（v1 / v2 同时在线）
• 团队习惯 Ruby 但又要面向第三方开发者，需要清晰的参数声明和自动文档（配 grape-swagger）

不适用：

• 全栈 web 应用（要 server-side 渲染 HTML / 表单 / cookie / session） → 用 Rails
• 极简 webhook 接收 / 内部小工具 → 用 Sinatra 三行更够
• 高并发 / 低延迟（Ruby GIL 限制） → 用 Go / Rust 系列（Gin / Axum）
• 需要 GraphQL 而不是 REST → 用 graphql-ruby

历史小故事（可跳过）

• 2010 年：Michael Bleigh 在 Intridea 团队想给 Rails 项目加 JSON API，嫌 Rails 太重，开源出 Grape 第一版。
• 2013-2015 年：移动端爆发，Ruby 社区大量”专做 API 的后端”项目用 Grape 起家，star 数破万。
• 2016 年：Rails 5 官方加入 --api 模式（生成轻量 Rails 应用），社区一度预测 Grape 会被取代。
• 2017-2026 年：Grape 因为 DSL 紧凑、参数声明强、grape-swagger 自动文档好用，没死，反而稳定迭代到现在。
• 教训：API 框架的护城河不是性能，是”参数声明语法 + 文档生成”这种贴近开发者日常的 DX。

学到什么

1. 专用框架打通用框架：Rails 强不代表它在每个细分场景都最优；写 API 时，专门为 API 设计的 DSL 比通用方案少 80% 模板代码
2. 校验推到边界：handler 内部不写 if 校验，而是用 params do requires ... end 声明在路由层，错误统一在边界返回
3. 挂载是个被低估的能力：Grape 能挂在 Rails / Sinatra 旁边，不强制全量迁移——这是它在老项目里活下来的关键
4. DSL 不是炫技：它把”高频重复劳动”压成声明，让人能专心写业务而不是写脚手架

延伸阅读

• 官方文档：ruby-grape.org（DSL 全表 + 各 helper 用法）
• 视频教程：GoRails — Building APIs with Grape（30 分钟从 0 到部署）
• 配套 gem：grape-swagger（自动生成 OpenAPI 文档）
• 对比文章：Grape vs Rails::API
• rails —— Grape 最常挂的宿主框架
• sinatra —— 比 Grape 更裸的 Ruby 极简框架

关联

• rails —— Ruby 全栈框架，Grape 经常挂在它的 /api 路径下做 API 子模块
• sinatra —— 同样基于 Rack 的极简框架，Grape 是它的”专做 API 升级版”
• hanami —— 另一个 Ruby web 框架，强调 Clean Architecture，与 Grape 思路不同
• fastapi —— Python 的 API 专用框架，“声明式参数 + 类型转换”思路与 Grape 几乎一致
• express —— Node.js 的极简框架，和 Sinatra 一样需要自己造校验，没有 Grape 这种 DSL
• fastify —— Node.js 带 schema 校验的框架，与 Grape 在”边界声明校验”理念上同源
• django —— Python 全栈框架，与 Rails 同位；Grape 在 Ruby 生态扮演”DRF for Django”那种角色

反向链接

• django —— Django — 全功能 batteries-included 的 Python web 框架
• express —— Express — Node.js 最经典的 Web 框架
• fastapi —— FastAPI — 用 Python 类型注解写 API
• fastify —— Fastify — 让 schema 替你写校验和序列化的 Node.js 框架
• hanami —— Hanami — Ruby 里既不是 Rails 也不是 Sinatra 的第三选择
• rails —— Ruby on Rails — 约定大于配置的全栈 Web 框架教科书
• sinatra —— Sinatra — 用 Ruby 三行代码起一个 web 服务