Ruby + Sinatra 构建《沙丘》名言 API 全流程指南

一. 项目初始化与环境配置 🛠️

在本教程中，我们将学习如何使用 Ruby 和 Sinatra 构建一个简单的 API。通过这个项目，我们将创建一个以《沙丘》系列书籍中的经典引文为基础的 API，并逐步提升其功能，最终通过 Zuplo 增强 API 的性能和安全性。

1. 创建项目目录

a. 快速建文件夹

首先，创建一个名为 duneQuotes 的文件夹，并在其中添加一个名为 server.rb 的文件。为了简化项目结构，我们将所有代码保存在这个文件中。

2. 安装依赖

a. Bundle 一键装宝石

在项目目录中运行以下命令安装所需的 Ruby 宝石：

bundle install

3. 配置 MongoDB Atlas

a. 注册集群

注册一个 MongoDB Atlas 帐户。
创建一个新的数据库集群。
在项目目录中创建一个名为 mongoid.yml 的文件，配置与 MongoDB 的连接信息。

b. 示例配置

以下是 mongoid.yml 的示例配置：

development:
  clients:
    default:
      uri: mongodb+srv://<user>:<password>@<cluster>/?retryWrites=true&w=majority

💡 AI 助攻
想自动生成带环境变量的 mongoid.yml？用「代码生成」提示词，30 秒即可拿到模板，再交给「代码优化」砍掉硬编码，安全又优雅！

4. 定义集合

a. 模型代码

在 server.rb 文件中定义 MongoDB 集合（或文档）。例如：

class Quote
  include Mongoid::Document
  field :quote, type: String
  field :character, type: String
  index({ character: 'text' })
end

二. 构建 API 端点 🔗

1. 创建基础 API

a. 根路径返回所有名言

在 server.rb 中，使用 Sinatra 定义 API 的基础结构：

require 'sinatra'
require 'mongoid'

Mongoid.load!('mongoid.yml')

namespace '/api/v1' do
  get '/quotes' do
    content_type :json
    Quote.all.to_json
  end
end

2. 添加功能性端点

a. 按角色过滤

支持通过角色名称的部分匹配来筛选引文。

b. 数量限制

通过 limit 参数控制返回的记录数。

c. 单条查询

通过唯一 ID 获取特定引文。

d. 随机返回

提供一个随机引文的功能。

三. 填充数据 📚

1. 创建数据文件

a. YAML 示例

创建一个名为 Quotes.yaml 的文件，内容如下：

- quote: "Fear is the mind-killer."
  character: "Paul Atreides"
- quote: "The spice must flow."
  character: "Frank Herbert"

2. 加载数据

a. Ruby 脚本

编写一个脚本将 YAML 文件中的数据加载到数据库中：

require 'yaml'

quotes = YAML.load_file('Quotes.yaml')
quotes.each do |entry|
  Quote.create(entry)
end

运行脚本后，可以通过 MongoDB Shell 验证数据是否成功插入。

四. 测试与部署 🌐

1. 本地测试

a. 启动服务

启动服务器后，打开浏览器访问以下地址：

http://localhost:4567/api/v1/quotes

测试结果应返回所有引文的 JSON 数据。

2. 云端部署

a. GitHub 上传

将项目代码上传到 GitHub 仓库。

b. Render 部署

在 Render 上创建一个新的 Web 服务。
指定 GitHub 仓库和分支。
更新启动命令为 ruby server.rb。

c. 白名单配置

将 Render 提供的静态 IP 地址添加到 MongoDB Atlas 的网络访问白名单中。

部署完成后，您可以通过以下 URL 访问 API：

https://dunequotes.onrender.com/api/v1/quotes

五. 使用 Zuplo 增强 API 🛡️

1. 速率限制

a. 每分钟 2 次

在 Zuplo 的路由配置中添加速率限制策略，防止 API 被滥用。

2. API 密钥验证

a. 授权头校验

通过 Zuplo 配置 API 密钥验证，确保只有授权用户可以访问 API。

3. 开发者文档门户

a. 自动生成

Zuplo 自动生成开发者文档门户，便于用户了解 API 的使用方法和端点信息。

✅ AI 补救
把“速率限制中间件”写进注释太麻烦？用「代码文档生成器」提示词，自动在函数头部生成标准注释，提醒后续接入 Zuplo 策略，文档一键达标！

六. 总结与下一步 🎯

通过本教程，我们成功构建了一个基于 Ruby 和 Sinatra 的 API，并通过 Zuplo 增强了其功能和安全性。这种方法不仅适用于小型项目，也可以扩展到更复杂的应用场景。现在，您可以尝试将 API 部署到生产环境，并与世界分享您的成果！

原文链接: https://zuplo.com/blog/2025/01/07/how-to-build-an-api-with-ruby-and-sinatra