Ruby on Rails 构建 API 基础教程：从设计到开发

一. 什么是 API 及其作用

在进行 Web 开发 或接触技术领域时，你可能听说过 API 这个术语。API 是“应用程序接口”（Application Programming Interface）的缩写，指的是一种允许程序之间进行通信的 接口。在本文中，我们的程序将是一个 Web 应用程序，而 API 的作用是让其他 Web 应用程序能够轻松地与之交互。

举个例子，假设你想构建一个简单的网络应用程序，用于在 Twitter 上搜索包含特定关键字的推文。你可以通过使用 Twitter 的搜索 API来实现这一目标：向其服务器发送数据请求，然后在你的应用程序中处理或显示这些数据。目前市面上有大量的 API 可供开发者使用，它们可以提供电影时间、餐厅评论、社交媒体等各种数据。通常情况下，访问 API 是免费的，但可能会对请求数量设有限制。

从另一个角度来看，如果你有一些数据希望提供给其他开发者使用，或者你有一个 Web 应用程序希望在移动设备上提供服务，这些场景都非常适合通过构建自己的 API 来实现。

二. 遵循惯例

当你决定构建一个 API 时，首先需要对其工作方式做出一些设计决策。

数据格式化

Rails 应用程序通常以 HTML 格式向浏览器呈现数据，因为 HTML 是 Web 的基础语言。然而，HTML 并不是唯一的选择，尤其在构建 API时，它可能并不是最佳选择。HTML 的优势在于它能以人类易于阅读的方式展示数据，但计算机和人类的阅读方式不同，因此我们需要以更适合计算机处理的方式格式化数据。

在 Ruby 中，我们可以使用数组和哈希来组织数据。例如，JSON 是一种非常适合 API 的数据格式，因为它既轻量又易于计算机解析。

RESTful 设计

在开发 API 时，你可能会听到 REST 或 RESTful 这两个术语。REST（Representational State Transfer，表述性状态转移）是一种设计风格，它将 HTTP 动词映射到数据库的 CRUD 操作（创建、读取、更新和删除）。在 Rails 中，RESTful 开发有一套标准的操作，它们分别是：索引（index）、显示（show）、新建（new）、创建（create）、编辑（edit）、更新（update）和销毁（destroy）。

这些操作与 HTTP 请求方法的对应关系如下：

需要注意的是，新建（new）和编辑（edit）操作虽然生成表单页面，但并不会直接修改数据库，因此它们属于 GET 请求的范畴。

三. 构建 API 的基础

在构建 API 时，我们需要遵循一些基本原则和步骤。

返回 JSON 数据

假设我们有以下代码：

@peoples = People.all
render json: @peoples, only: [:id, :name]

返回的 JSON 数据可能如下：

[
 { "id": 1, "name": "David" },
 { "id": 2, "name": "Jamie" }
]

虽然这段 JSON 数据包含了每个对象的属性，但缺少顶层的标识符。如果我们添加一个顶层键，数据会更清晰：

{
 "people": [
 { "id": 1, "name": "David" },
 { "id": 2, "name": "Jamie" }
 ]
}

通过这种方式，接收端的应用程序可以更方便地解析和操作数据。

四. 开始构建 API

在构建 Rails API 时，与开发普通 Rails Web 应用程序有一些不同之处。以下是一些关键步骤：

使用 Rails API 模式

建议使用 rails-api gem 来生成一个轻量级的 Rails 应用程序。你可以通过以下命令安装和创建项目：

gem install rails-api
rails-api new APP_NAME

控制器的变化

在 API 控制器中，我们需要显式地指定返回 JSON 数据。例如，对于一个博客应用的 PostsController，其索引和显示操作可能如下：

def index
 render json: Post.all
end

def show
 render json: Post.find(params[:id])
end

相比普通 Rails 应用程序，这里需要明确告诉 Rails 渲染 JSON 数据，而不是默认的 HTML 视图。

以下是更多的控制器操作示例：

def create
 @post = Post.new(post_params)
 if @post.save
 render json: @post, status: :created, location: api_post_path(@post)
 else
 render json: @post.errors, status: :unprocessable_entity
 end
end

def update
 @post = Post.find(params[:id])
 if @post.update(post_params)
 head :no_content
 else
 render json: @post.errors, status: :unprocessable_entity
 end
end

def destroy
 @post = Post.find(params[:id])
 if @post.destroy
 head :no_content
 else
 render json: @post.errors, status: :unprocessable_entity
 end
end

private

def post_params
 # 定义允许的参数
end

使用序列化器

为了更好地控制 JSON 数据的结构，可以使用 ActiveModel::Serializer。例如：

mkdir app/serializers
touch app/serializers/post_serializer.rb

在 PostSerializer 中定义如下内容：

class PostSerializer < ActiveModel::Serializer
 attributes :id, :title, :body, :created_at, :updated_at
end

通过序列化器，我们可以清晰地定义返回数据的结构。

五. 结论

以上就是使用 Ruby on Rails 构建 API 的基础知识。通过这些步骤，你可以将一个普通的 Rails 应用程序转变为功能强大的 API，无论是用于支持移动端应用，还是为其他开发者提供数据访问接口。

此外，你还可以结合 JavaScript 框架（如 Ember 或 Angular）构建更具交互性的前端应用程序，将 Rails API 作为后端服务。

无论你的目标是什么，记住遵循 Rails 的惯例和文档，逐步完善你的 API。即使遇到问题，也不要气馁，这都是开发过程的一部分。

6. 提升代码质量与效率

在构建 API 的过程中，为了提升代码的性能与可维护性，可以使用代码优化工具，对低效代码进行问题解析并优化改写。

此外，使用代码文档生成器来生成符合标准的完整代码文档，可以帮助开发者更好地理解和维护代码。如果需要，可以借助代码审查助手来提供详细的代码审查并给出可执行反馈。

若要加速开发，可以使用代码生成工具，帮助你快速生成完成特定功能的代码段。

原文链接: https://launchacademy.com/blog/the-basics-of-building-an-api-in-ruby-on-rails