使用 Ruby on Rails 创建基础 API 驱动的应用程序

欢迎阅读本教程系列，本系列将带您学习如何使用 Ruby on Rails 构建 API 驱动的应用程序。本教程的目标是帮助您理解如何创建一个后端 API，使其能够与多个平台的应用程序进行交互。我们将探讨数据返回、路由、版本控制以及身份验证等主题。

一. 使用 API 模式创建 Rails 应用

在 Rails 5.2 版本之后，新增了 --api 模式，用于创建轻量级的 API 应用程序。通过运行以下命令，您可以快速启动一个新的 Rails 应用程序：

rails new band_api --api

此命令会生成一个默认返回 JSON 数据的应用程序。相比普通 Rails 应用，API 模式会移除与视图相关的组件，适合构建完全基于前端框架（如 React）的应用程序。当然，您也可以混合使用 API 模式和传统模式，根据需求返回 JSON 或 HTML 数据。

二. 创建资源

在本示例中，我们将构建一个 API 来管理乐队（Band）、乐队成员（Member）以及专辑（Album）。首先，创建一个乐队资源：

rails g scaffold Band name:string

接着，为乐队成员创建资源，并通过外键与乐队关联：

rails g model Member name:string band:references
rails db:migrate

确保模型设置正确：

# app/models/band.rb
class Band < ApplicationRecord
  has_many :members
end

# app/models/member.rb
class Member < ApplicationRecord
  belongs_to :band
end

生成的控制器会自动包含基本的 CRUD 操作：

# app/controllers/bands_controller.rb
class BandsController < ApplicationController
  before_action :set_band, only: [:show, :update, :destroy]

  # GET /bands
  def index
    @bands = Band.all
    render json: @bands
  end

  # GET /bands/:id
  def show
    render json: @band
  end

  # POST /bands
  def create
    @band = Band.new(band_params)
    if @band.save
      render json: @band, status: :created, location: @band
    else
      render json: @band.errors, status: :unprocessable_entity
    end
  end

  # PATCH/PUT /bands/:id
  def update
    if @band.update(band_params)
      render json: @band
    else
      render json: @band.errors, status: :unprocessable_entity
    end
  end

  # DELETE /bands/:id
  def destroy
    @band.destroy
  end

  private

  def set_band
    @band = Band.find(params[:id])
  end

  def band_params
    params.require(:band).permit(:name)
  end
end

通过 rails console 创建一些测试数据：

Band.create(name: "AC/DC")
Band.create(name: "The Beatles")

启动服务器后，访问 http://localhost:3000/bands 即可查看返回的 JSON 数据。

三. 使用 ActiveModelSerializers 优化 JSON 返回

为了更好地管理 JSON 数据，可以使用 active_model_serializers gem。首先，将其添加到项目中：

bundle add active_model_serializers

然后，生成一个序列化器：

rails g serializer Band

生成的文件位于 app/serializers/band_serializer.rb，初始内容如下：

class BandSerializer < ActiveModel::Serializer
  attributes :id, :name
  has_many :members
end

为成员创建对应的序列化器：

rails g serializer Member

# app/serializers/member_serializer.rb
class MemberSerializer < ActiveModel::Serializer
  attributes :id, :name
  belongs_to :band
end

通过这些序列化器，访问 http://localhost:3000/bands 时，您将看到包含乐队及其成员的完整 JSON 数据。

四. 使用 JSON:API 规范

为了让 JSON 数据更具可读性和一致性，可以采用 JSON:API 规范。active_model_serializers 支持该规范，只需添加以下配置：

# config/initializers/ams.rb
ActiveModelSerializers.config.adapter = :json_api

配置完成后，返回的数据将符合 JSON:API 推荐的格式，例如：

{
  "data": [
    {
      "type": "bands",
      "id": "1",
      "attributes": {
        "name": "AC/DC"
      },
      "relationships": {
        "members": {
          "data": [
            { "type": "members", "id": "1" }
          ]
        }
      }
    }
  ]
}

五. 路由与版本控制

在 API 应用中，路由和版本控制至关重要。以下是一个示例路由配置：

# config/routes.rb
Rails.application.routes.draw do
  namespace :api do
    namespace :v1 do
      resources :bands do
        resources :members
      end
    end

    namespace :v2 do
      resources :members
      resources :bands
    end
  end
end

通过为 API 添加命名空间和版本号，可以确保旧版本的兼容性，同时为新功能的开发提供灵活性。这种方式不仅便于调试，还能为团队协作提供清晰的结构。

通过本教程，您已经了解了如何使用 Ruby on Rails 创建基础 API，包括使用 API 模式、管理资源、优化 JSON 数据返回以及实现版本控制等内容。希望这些知识能为您的开发工作带来帮助！

AI工具推荐

在开发过程中，借助一些 代码优化工具 可以提升代码的执行效率和可维护性，帮助您构建更为高效的 API。更多工具如 代码审查助手 和 代码文档生成器，也能在项目开发中提供巨大的帮助，确保代码的质量与稳定性。

原文链接: https://webcrunch.com/posts/create-a-basic-api-with-ruby-on-rails