使用 Grape 在 Ruby on Rails 中构建 RESTful API：简洁高效的 API 开发框架

一. 什么是 Grape？

Ruby on Rails 是一个功能强大的 Web 开发 框架，但在创建 API 时，开发者通常会选择更轻量化、更灵活的解决方案，而不是直接使用 Rails 控制器。这时，Grape 就成为了一个非常有吸引力的选择。Grape 是一种专为 Ruby 设计的 DSL（领域特定语言），用于构建 RESTful API。在本文中，我们将深入探讨 Grape 的特点、优势，以及如何将其集成到 Rails 应用中。

二. 为什么选择 Grape？

相比于主要为 Web 应用设计的 Rails 控制器，Grape 专为 API 开发而生，具有以下显著优势：

轻量灵活：Grape 针对 API 设计，比标准的 Rails 控制器更高效。
内置参数处理：支持强参数验证和类型转换，减少样板代码。
中间件与挂载：可以轻松集成到 Rails 应用中，也可作为独立 API 层运行。
版本控制：支持多个 API 版本（如 v1、v2 等）的轻松管理。
响应格式定制：支持 JSON、XML 等多种格式的响应。
身份验证支持：可以与 Devise、JWT 或 OAuth 等工具配合使用，轻松实现身份验证。

三. 在 Rails 应用中集成 Grape

1. 安装 Grape

首先，将 Grape 添加到 Rails 应用的 Gemfile 中：

gem 'grape'

然后运行以下命令安装 gem：

bundle install

2. 创建基本 API

在 Rails 项目中，创建一个新的目录 app/api，并在其中定义一个基本的 API 类。例如：

module API
 class Base < Grape::API
   prefix 'api'
 end
end

启动 Rails 服务器后，访问 http://localhost:3000/api/status，您应该会看到以下 JSON 响应：

{ "status": "API is running" }

四. 使用 Grape 实现 CRUD 操作

接下来，我们创建一个简单的 API 来管理书籍数据。

4. 定义书籍 API

在 app/api 目录下创建一个新的文件 books_api.rb，并定义 CRUD 操作：

module API
 class Books < Grape::API
   format :json

   resources :books do
     desc '获取所有书籍'
     get do
       Book.all
     end

     desc '根据 ID 获取书籍'
     params do
       requires :id, type: Integer, desc: '书籍 ID'
     end
     get ':id' do
       Book.find(params[:id])
     end

     desc '创建新书籍'
     params do
       requires :title, type: String, desc: '书名'
       requires :author, type: String, desc: '作者'
     end
     post do
       Book.create!(title: params[:title], author: params[:author])
     end
   end
 end
end

5. 挂载书籍 API

修改 base_api.rb 文件，将 Books API 挂载到主 API 中：

module API
 class Base < Grape::API
   mount API::Books
 end
end

6. 测试 API

启动 Rails 服务器后，可以使用 Postman 或 curl 测试以下端点：

GET /api/books：获取所有书籍。
GET /api/books/:id：根据 ID 获取特定书籍。
POST /api/books：创建新书籍（需提供 JSON 数据）。

五. 使用 Grape 实体优化 API 响应

Grape 提供了实体（Entity）功能，用于定义结构化的 JSON 响应。通过实体，我们可以避免直接暴露 ActiveRecord 模型的原始数据。例如：

module API
 module Entities
   class Book < Grape::Entity
     expose :id
     expose :title
     expose :author
   end
 end
end

在 API 中返回数据时，可以使用 present 方法应用实体：

get do
 present Book.all, with: API::Entities::Book
end

这样，客户端将收到格式化的响应，而不是原始的模型数据。

六. 访问 API 文档

Grape 支持与 Swagger 等工具集成，生成交互式 API 文档。安装 grape-swagger gem 后，只需几行代码即可启用文档功能：

gem 'grape-swagger'

在 base_api.rb 中添加以下代码：

add_swagger_documentation

重启 Rails 服务器后，访问 /swagger_doc 即可查看自动生成的 API 文档。

七. 总结

Grape 是一个轻量级且功能强大的 Ruby 框架，专为构建 RESTful API 而设计。通过其简洁的 DSL、强大的参数验证和版本控制支持，Grape 能够显著简化 API 开发流程。如果您正在寻找一个高效的 Rails 控制器替代方案，不妨尝试 Grape。

在开发过程中，您还可以结合开发任务管理系统KPI 来跟踪您的进展，并使用代码优化工具对低效代码进行问题解析和优化改写。此外，通过代码文档生成器为您的代码生成详细文档，确保开发团队能够高效协作。

在开发过程中，如果您需要优化代码质量或通过 AI 来帮助生成特定功能的代码，可以利用代码生成工具。此外，代码审查助手可以为您提供详细的代码审查和可执行反馈。

原文链接: https://gurzu.com/blog/building-restful-apis-with-grape-in-ruby-on-rails/