Ruby RESTful API开发

在本章中，我们将深入了解如何使用 Ruby 语言和相关的框架来构建 RESTful API。RESTful API 是一种设计风格，用于通过 HTTP 协议为客户端提供数据和服务。我们将重点讨论如何利用 Ruby on Rails 框架来创建高效、可扩展的 RESTful API。

安装与设置

在开始之前，确保你的系统上安装了 Ruby 和 Rails。你可以通过以下命令来检查是否已安装 Ruby 和 Rails：

ruby -v
rails -v

如果尚未安装，可以使用如下命令进行安装：

# 安装 Ruby
rvm install ruby
# 或者使用 Homebrew (macOS)
brew install ruby

# 安装 Rails
gem install rails

接下来，我们需要创建一个新的 Rails 应用程序。可以通过运行以下命令来实现：

rails new api_project --api
cd api_project

这里我们添加了 --api 参数，这将自动配置 Rails 应用程序以支持 API 开发，从而减少不必要的组件加载。

资源与路由

在 RESTful API 中，资源是应用程序的核心。资源代表现实世界中的对象或概念，例如用户、文章等。Rails 提供了一种简单的方式来定义这些资源及其关联的路由。

定义资源

让我们以用户为例，定义一个简单的用户资源。打开 config/routes.rb 文件，并添加以下内容：

Rails.application.routes.draw do
  resources :users
end

这将生成一系列标准的 RESTful 路由，包括创建、读取、更新和删除用户的操作。

自定义路由

有时，你可能需要自定义一些路由来满足特定需求。例如，你可能想要添加一个自定义的动作来处理用户的验证请求。可以在 routes.rb 中这样定义：

Rails.application.routes.draw do
  resources :users, only: [:index, :show, :create, :update] do
    collection do
      get 'authenticate'
    end
  end
end

这里的 collection 关键字允许我们在资源集合上定义额外的路由，而不会影响到现有的 CRUD 操作。

控制器

控制器负责处理来自客户端的请求，并返回适当的响应。在 Rails 中，每个资源通常对应一个控制器。我们可以使用 Rails 命令行工具来生成用户控制器：

rails generate controller Users

生成的控制器位于 app/controllers/users_controller.rb。我们可以根据需要修改这个文件，添加或修改动作。

动作示例

以下是一个简单的 UsersController 示例，展示如何处理用户列表的请求：

// www.javascriptcn.com code example
class UsersController < ApplicationController
  before_action :set_user, only: [:show, :update]

  # GET /users
  def index
    @users = User.all
    render json: @users
  end

  # GET /users/:id
  def show
    render json: @user
  end

  # POST /users
  def create
    @user = User.new(user_params)

    if @user.save
      render json: @user, status: :created
    else
      render json: { errors: @user.errors }, status: :unprocessable_entity
    end
  end

  private

  def set_user
    @user = User.find(params[:id])
  end

  def user_params
    params.require(:user).permit(:name, :email)
  end
end

模型

模型是应用程序中表示业务逻辑的部分，通常与数据库表相对应。在 Rails 中，可以通过生成器轻松地创建模型。例如，创建一个名为 User 的模型：

rails generate model User name:string email:string

然后运行迁移以创建相应的数据库表：

rails db:migrate

模型还可以包含验证逻辑，以确保数据的有效性。例如，在 User 模型中添加电子邮件验证：

class User < ApplicationRecord
  validates :name, presence: true
  validates :email, presence: true, uniqueness: true
end

视图与序列化

虽然 RESTful API 不依赖于视图层来呈现数据，但序列化仍然是一个重要部分，它将模型数据转换为 JSON 格式以便客户端消费。Rails 提供了 Active Model Serializers gem 来简化这一过程。

首先，你需要在 Gemfile 中添加 active_model_serializers 并运行 bundle install：

gem 'active_model_serializers', '~> 0.10.0'

然后，你可以为用户模型创建一个序列化器：

rails g serializer user

编辑生成的序列化器文件 app/serializers/user_serializer.rb，添加所需的字段：

class UserSerializer < ActiveModel::Serializer
  attributes :id, :name, :email
end

最后，在控制器中使用该序列化器：

// www.javascriptcn.com code example
class UsersController < ApplicationController
  ...

  # GET /users
  def index
    @users = User.all
    render json: @users, each_serializer: UserSerializer
  end

  ...
end

认证与授权

安全是任何 API 设计的关键组成部分。常见的认证方法包括 OAuth、JWT（JSON Web Tokens）等。这里我们简要介绍如何使用 JWT 来保护 API。

安装 JWT 相关库

首先，需要在 Gemfile 中添加 JWT 相关的 gem：

gem 'jwt'

然后运行 bundle install。

实现 JWT 认证

在控制器中实现 JWT 认证逻辑。首先创建一个帮助方法用于生成 JWT：

// www.javascriptcn.com code example
module JsonWebToken
  extend ActiveSupport::Concern

  SECRET_KEY = Rails.application.secrets.secret_key_base.to_s

  def self.encode(payload, exp = 24.hours.from_now)
    payload[:exp] = exp.to_i
    JWT.encode(payload, SECRET_KEY)
  end

  def self.decode(token)
    body = JWT.decode(token, SECRET_KEY)[0]
    HashWithIndifferentAccess.new body
  rescue
    nil
  end
end

接下来，创建一个中间件来拦截所有请求并验证 JWT：

// www.javascriptcn.com code example
class AuthenticateApiRequest
  def initialize(app)
    @app = app
  end

  def call(env)
    request = ActionDispatch::Request.new(env)
    token = request.headers['Authorization'].to_s.split(' ').last

    if token.present?
      begin
        decoded_token = JsonWebToken.decode(token)
        env['current_user'] = User.find(decoded_token[:user_id])
      rescue JWT::DecodeError => e
        return unauthorized_response(e.message)
      end
    end

    @app.call(env)
  end

  private

  def unauthorized_response(message)
    [401, {'Content-Type' => 'application/json'}, [{error: message}.to_json]]
  end
end

最后，在 config/application.rb 中启用这个中间件：

config.middleware.use AuthenticateApiRequest

现在，每当客户端发送带有有效 JWT 的请求时，服务器会解析 JWT 并将当前用户信息附加到请求环境中，从而实现基于 JWT 的认证。

总结

通过本章的学习，我们掌握了如何使用 Ruby on Rails 构建 RESTful API 的基本步骤。从环境搭建到资源定义、控制器实现以及模型验证，再到序列化和认证机制的引入，每一步都是构建健壮、安全的 API 所必需的。希望这些知识能帮助你在实际项目中更加自信地开发 RESTful API。