Rails 使用 Rails 构建 API 实践

kayakjiang · 2015年05月31日 · 最后由 judi0713 回复于 2018年03月20日 · 46913 次阅读
本帖已被设为精华帖!

我是来鼓吹使用 Rails 写 API 的。

原文在此: https://labs.kollegorna.se/blog/2015/04/build-an-api-now/

原文有一个很大的缺陷就是读者无法按照它的步骤一步一步的去实现一个可以运行的 demo, 这对经验丰富的开发 者可能不算是一个问题,但是对刚刚接触这方面知识的新手来说却是一个很大的遗憾,软件开发方面的知识重在 实践,只有动手做了,才能对知识掌握地更加牢靠,才能更好地在工作中去使用这些知识, 所以我对原文的内容 做了一些补充修整,以期能够让读者边读边思考边实践。

原文的 demo 是一个类微博应用,为简单起见我们只使用 User 和 Micropost 模型, 并且我们不使用 ActiveModel::Serializer, 而是使用 Jbuilder 作为 json 模版。

首先建立一个项目: build-an-api-rails-demo

$ rails new build-an-api-rails-demo

加入第一个 API resource

BaseController

生成控制器:

# 我们不需要生成资源文件
$ bundle exe rails g controller api/v1/base --no-assets

app/controllers/api/v1/base_controller.rb,

class Api::V1::BaseController < ApplicationController
  # disable the CSRF token
  protect_from_forgery with: :null_session

  # disable cookies (no set-cookies header in response)
  before_action :destroy_session

  # disable the CSRF token
  skip_before_action :verify_authenticity_token

  def destroy_session
    request.session_options[:skip] = true
  end
end

在 BaseController 里我们禁止了 CSRF token 和 cookies

配置路由:

config/routes.rb,

namespace :api do
  namespace :v1 do
    resources :users, only: [:index, :create, :show, :update, :destroy]
    # 原文有 microposts, 我们现在把它注释掉
    # resources :microposts, only: [:index, :create, :show, :update, :destroy]
  end
end

Api::V1::UsersController

生成控制器:

# 我们不需要生成资源文件
$ bundle exe rails g controller api/v1/users --no-assets

app/controllers/api/v1/users_controller.rb,

class Api::V1::UsersController < Api::V1::BaseController
  def show
    @user = User.find(params[:id])

    # 原文使用 Api::V1::UserSerializer
    # 我们现在使用 app/views/api/v1/users/show.json.jbuilder
    # render(json: Api::V1::UserSerializer.new(user).to_json)
  end
end

app/views/api/v1/users/show.json.jbuilder,

json.user do
  json.(@user, :id, :email, :name,  :activated, :admin, :created_at, :updated_at)
end

User 模型和 users 表

$ bundle exe rails g model User

app/models/user.rb,

class User < ActiveRecord::Base
end

db/migrate/20150502072954_create_users.rb,

class CreateUsers < ActiveRecord::Migration
  def change
    create_table :users do |t|
      t.string :email
      t.string :name
      t.datetime :activated
      t.boolean :admin, default: false
      t.timestamps null: false
    end
  end
end

数据迁移:

$ bundle exe rake db:migrate

种子数据:

db/seeds.rb,

users = User.create([
                     {
                       email: 'test-user-00@mail.com',
                       name: 'test-user-00',
                       activated: DateTime.now,
                       admin: false
                     },
                     {
                       email: 'test-user-01@mail.com',
                       name: 'test-user-01',
                       activated: DateTime.now,
                       admin: false
                     }
                    ])

创建种子数据:

$ bundle exe rake db:seed

现在我们可以测试一下 api 是否正常工作, 我们可以先查看下相关 api 的路由,

$ bundle exe rake routes

输出:

      Prefix Verb   URI Pattern                      Controller#Action
api_v1_users GET    /api/v1/users(.:format)          api/v1/users#index
             POST   /api/v1/users(.:format)          api/v1/users#create
 api_v1_user GET    /api/v1/users/:id(.:format)      api/v1/users#show
             PATCH  /api/v1/users/:id(.:format)      api/v1/users#update
             PUT    /api/v1/users/:id(.:format)      api/v1/users#update
             DELETE /api/v1/users/:id(.:format)      api/v1/users#destroy

启动 rails 服务,

$ bundle exe rails s

使用 curl 请求 api,

$ curl -i http://localhost:3000/api/v1/users/1.json
{"user":{"id":1,"email":"test-user-00@mail.com","name":"test-user-00","activated":"2015-05-02T07:47:14.697Z","admin":false,"created_at":"2015-05-02T07:47:14.708Z","updated_at":"2015-05-02T07:47:14.708Z"}}

恭喜,我们的 api 工作正常!

增加认证(Authentication)

认证的过程是这样的: 用户把她的用户名和密码通过 HTTP POST 请求发送到我们的 API (在这里我们使用 sessions 端点来处理这个请求), 如果用户名和密码匹配,我们 会把 token 发送给用户。 这个 token 就是用来证明用户身份的凭证。然后在以后的每个请求中,我们都通过这个 token 来查找用户,如果没有找到用户则返回 401 错误。

给 User 模型增加 authentication_token 属性

$ bundle exe rails g migration add_authentication_token_to_users

db/migrate/20150502123451_add_authentication_token_to_users.rb

class AddAuthenticationTokenToUsers < ActiveRecord::Migration
  def change
    add_column :users, :authentication_token, :string
  end
end
$ bundle exe rake db:migrate

生成 authentication_token

app/models/user.rb,

class User < ActiveRecord::Base

 + before_create :generate_authentication_token

 + def generate_authentication_token
 +   loop do
 +     self.authentication_token = SecureRandom.base64(64)
 +     break if !User.find_by(authentication_token: authentication_token)
 +   end
 + end

 + def reset_auth_token!
 +   generate_authentication_token
 +   save
 + end

end

和原文相比,我给 User 模型增加了一个 reset_auth_token! 方法,我这样做的理由主要有以下几点:

  1. 我觉得需要有一个方法帮助用户重置 authentication token, 而不仅仅是在创建用户时生成 authenticeation token;

  2. 如果用户的 token 被泄漏了,我们可以通过 reset_auth_token! 方法方便地重置用户 token;

sessions endpoint

生成 sessions 控制器,

# 我们不需要生成资源文件
$ bundle exe rails g controller api/v1/sessions --no-assets

  create  app/controllers/api/v1/sessions_controller.rb
  invoke  erb
  create    app/views/api/v1/sessions
  invoke  test_unit
  create    test/controllers/api/v1/sessions_controller_test.rb
  invoke  helper
  create    app/helpers/api/v1/sessions_helper.rb
  invoke    test_unit

app/controllers/api/v1/sessions_controller.rb,

class Api::V1::SessionsController < Api::V1::BaseController

  def create
    @user = User.find_by(email: create_params[:email])
    if @user && @user.authenticate(create_params[:password])
      self.current_user = @user
      # 我们使用 jbuilder
      # render(
      #   json: Api::V1::SessionSerializer.new(user, root: false).to_json,
      #   status: 201
      # )
    else
      return api_error(status: 401)
    end
  end

  private

  def create_params
    params.require(:user).permit(:email, :password)
  end

end

现在我们还需要做一些原文没有提到的工作:

  1. 给 User 模型增加和 password 相关的属性;

  2. 给数据库中已存在的测试用户增加密码和 authentication token;

  3. 实现和 current_user 相关的方法;

  4. 实现 app/views/api/v1/sessions/create.json.jbuilder;

  5. 配置和 sessions 相关的路由;

给 User 模型增加和 password 相关的属性

在 Gemfile 里将 gem 'bcrypt' 这一行的注释取消

# Use ActiveModel has_secure_password
gem 'bcrypt', '~> 3.1.7'

app/models/user.rb,

class User < ActiveRecord::Base
  + has_secure_password
end

给 User 模型增加 password_digest 属性,

$ bundle exe rails g migration add_password_digest_to_users

db/migrate/20150502134614_add_password_digest_to_users.rb,

class AddPasswordDigestToUsers < ActiveRecord::Migration
  def change
    add_column :users, :password_digest, :string
  end
end
$ bundle install
$ bundle exe rake db:migrate

给数据库中已存在的测试用户增加密码和 authentication token

这个任务可以在 rails console 下完成,

首先启动 rails console,

$ bundle exe rails c

然后在 rails console 里执行,

User.all.each {|user|
  user.password = '123123'
  user.reset_auth_token!
}

实现和 current_user 相关的方法

app/controllers/api/v1/base_controller.rb,

class Api::V1::BaseController < ApplicationController

+ attr_accessor :current_user

end

实现 app/views/api/v1/sessions/create.json.jbuilder

app/views/api/v1/sessions/create.json.jbuilder,

json.session do
  json.(@user, :id, :name, :admin)
  json.token @user.authentication_token
end

配置和 sessions 相关的路由

Rails.application.routes.draw do

  namespace :api do
    namespace :v1 do
     + resources :sessions, only: [:create]
    end
  end

end

现在我们做一个测试看是否能够顺利地拿到用户的 token, 我们使用下面的用户作为测试用户:

{
  email: 'test-user-00@mail.com',
  name: 'test-user-00'
}
$ curl -i -X POST -d "user[email]=test-user-00@mail.com&user[password]=123123" http://localhost:3000/api/v1/sessions.json

{"session":{"id":1,"name":"test-user-00","admin":false,"token":"izrFiion7xEe2ccTj0v0mOcuNoT3FvpPqI31WLSCEBLvuz4xSr0d9+VI2+xVvAJjECIoju5MaoytEcg6Md773w=="}}

我们顺利地拿到了 token。

我们再做一个验证失败的测试。

我们使用一个错误的密码: fakepwd

curl -i -X POST -d "user[email]=test-user-00@mail.com&user[password]=fakepwd" http://localhost:3000/api/v1/sessions.json

糟糕系统出错了:

NoMethodError (undefined method `api_error' for #<Api::V1::SessionsController:0x007fead422c178>):
  app/controllers/api/v1/sessions_controller.rb:14:in `create'

原来我们没有实现 api_error 这个方法,那我们现在就实现 api_error 这个方法。

app/controllers/api/v1/base_controller.rb,

class Api::V1::BaseController < ApplicationController

 + def api_error(opts = {})
 +   render nothing: true, status: opts[:status]
 + end

end

继续测试:

curl -i -X POST -d "user[email]=test-user-00@mail.com&user[password]=fakepwd" http://localhost:3000/api/v1/sessions

HTTP/1.1 401 Unauthorized 
X-Frame-Options: SAMEORIGIN
X-Xss-Protection: 1; mode=block
X-Content-Type-Options: nosniff
Content-Type: text/plain; charset=utf-8
Cache-Control: no-cache
X-Request-Id: a5349b47-d756-4830-84f8-0653577f936d
X-Runtime: 0.319768
Server: WEBrick/1.3.1 (Ruby/2.1.2/2014-05-08)
Date: Sat, 02 May 2015 14:41:55 GMT
Content-Length: 0
Connection: Keep-Alive

此时服务器返回了 401 Unauthorized

Authenticate User

在前面的测试中,我们已经成功地拿到了用户的 token, 那么现在我们把 token 和 email 发给 API

看能否成功识别出用户。

首先在 Api::V1::BaseController 里实现 authenticate_user! 方法:

app/controllers/api/v1/base_controller.rb,

class Api::V1::BaseController < ApplicationController

+  def authenticate_user!
+    token, options = ActionController::HttpAuthentication::Token.token_and_options(request)

+    user_email = options.blank?? nil : options[:email]
+    user = user_email && User.find_by(email: user_email)

+    if user && ActiveSupport::SecurityUtils.secure_compare(user.authentication_token, token)
+      self.current_user = user
+    else
+      return unauthenticated!
+    end
+  end

end

ActionController::HttpAuthentication::Token 是 rails 自带的方法,可以参考 rails 文档 了解其详情。

当我们通过 user_email 拿到 user 后, 通过 ActiveSupport::SecurityUtils.secure_compare

对 user.authentication_token 和从请求头里取到的 token 进行比较,如果匹配则认证成功,否则返回

unauthenticated!。这里使用了 secure_compare 对字符串进行比较,是为了防止时序攻击(timing attack)

我们构造一个测试用例, 这个测试用例包括以下一些步骤:

  1. 用户登录成功, 服务端返回其 email, token 等数据

  2. 用户请求 API 更新其 name, 用户发送的 token 合法, 更新成功

  3. 用户请求 API 更新其 name, 用户发送的 token 非法, 更新失败

为了让用户能够更新其 name, 我们需要实现 user update API, 并且加入 before_action :authenticate_user!, only: [:update]

app/controllers/api/v1/users_controller.rb,

class Api::V1::UsersController < Api::V1::BaseController

+ before_action :authenticate_user!, only: [:update]

+ def update
+   @user = User.find(params[:id])
+   @user.update_attributes(update_params)
+ end

+ private

+ def update_params
+   params.require(:user).permit(:name)
+ end

end

app/views/api/v1/users/update.json.jbuilder,

json.user do
  json.(@user, :id, :name)
end

现在我们进行测试, 测试用户是:

{
  id: 1,
  email: 'test-user-00@mail.com',
  name: 'test-user-00',
  authentication_token: 'izrFiion7xEe2ccTj0v0mOcuNoT3FvpPqI31WLSCEBLvuz4xSr0d9+VI2+xVvAJjECIoju5MaoytEcg6Md773w=='
}
$ curl -i -X PUT -d "user[name]=gg-user" \
  --header "Authorization: Token token=izrFiion7xEe2ccTj0v0mOcuNoT3FvpPqI31WLSCEBLvuz4xSr0d9+VI2+xVvAJjECIoju5MaoytEcg6Md773w==, \
  email=test-user-00@mail.com" \
  http://localhost:3000//api/v1/users/1

{"user":{"id":1,"name":"gg-user"}}  

我们看到 user name 已经成功更新为 gg-user。

读者们请注意: 你们自己测试时需要将 token 换为你们自己生成的 token。

我们使用一个非法的 token 去请求 API, 看看会发生什么状况。

curl -i -X PUT -d "user[name]=bb-user" \
  --header "Authorization: Token token=invalid token, \
  email=test-user-00@mail.com" \
  http://localhost:3000//api/v1/users/1

服务器出现错误:

NoMethodError (undefined method `unauthenticated!' for #<Api::V1::UsersController:0x007fead6108d80>)

接下来我们实现 unauthenticated! 方法。

app/controllers/api/v1/base_controller.rb,

class Api::V1::BaseController < ApplicationController

+ def unauthenticated!
+   api_error(status: 401)
+ end

end

继续上面的测试:

curl -i -X PUT -d "user[name]=bb-user" \
  --header "Authorization: Token token=invalid token, \
  email=test-user-00@mail.com" \
  http://localhost:3000//api/v1/users/1

HTTP/1.1 401 Unauthorized 
X-Frame-Options: SAMEORIGIN
X-Xss-Protection: 1; mode=block
X-Content-Type-Options: nosniff
Content-Type: text/plain; charset=utf-8
Cache-Control: no-cache
X-Request-Id: 8cf07968-1fd0-4041-866a-ddea49af11d3
X-Runtime: 0.005578
Server: WEBrick/1.3.1 (Ruby/2.1.2/2014-05-08)
Date: Sun, 03 May 2015 05:51:52 GMT
Content-Length: 0
Connection: Keep-Alive  

服务器返回 401 Unauthorized, 并且 user name 没有被更新。

增加授权(Authorization)

上面的测试有个问题,就是当前登录的用户可以把其他用户的 name 更新,这个应该是不被允许的,所以我们 还需要增加一个权限认证的机制。在这里我们使用 Pundit 来 实现权限认证。

安装 pundit

Gemfile,

+ gem 'pundit'
$ bundle install

app/controllers/api/v1/base_controller.rb,

class Api::V1::BaseController < ApplicationController
  + include Pundit
end
$ bundle exe rails g pundit:install

create  app/policies/application_policy.rb

将 policies 目录放到 rails 的自动加载路径中:

config/application.rb,

module BuildAnApiRailsDemo
  class Application < Rails::Application
+    config.autoload_paths << Rails.root.join('app/policies')
  end
end

创建和 user 相关的权限机制

app/policies/user_policy.rb,


class UserPolicy < ApplicationPolicy

  def show?
    return true
  end

  def create?
    return true
  end

  def update?
    return true if user.admin?
    return true if record.id == user.id
  end

  def destroy?
    return true if user.admin?
    return true if record.id == user.id
  end

  class Scope < ApplicationPolicy::Scope
    def resolve
      scope.all
    end
  end

end

使用 UserPolicy

app/controllers/api/v1/users_controller.rb,

class Api::V1::UsersController < Api::V1::BaseController

  def update
    @user = User.find(params[:id])
+   return api_error(status: 403) if !UserPolicy.new(current_user, @user).update?
    @user.update_attributes(update_params)
  end

end

测试:

$ curl -i -X PUT -d "user[name]=gg-user" \
  --header "Authorization: Token token=izrFiion7xEe2ccTj0v0mOcuNoT3FvpPqI31WLSCEBLvuz4xSr0d9+VI2+xVvAJjECIoju5MaoytEcg6Md773w==, \
  email=test-user-00@mail.com" \
  http://localhost:3000//api/v1/users/2.json

HTTP/1.1 403 Forbidden 
X-Frame-Options: SAMEORIGIN
X-Xss-Protection: 1; mode=block

注意我们测试的 url 地址是 http://localhost:3000//api/v1/users/2, 也就是说我们在更新 id 为 2 的那个用户的 name。此时服务器返回的是 403 Forbidden。

pundit 提供了更简便的 authorize 方法为我们做权限认证的工作。


class Api::V1::UsersController < Api::V1::BaseController

  def update
    @user = User.find(params[:id])
    # return api_error(status: 403) if !UserPolicy.new(current_user, @user).update?
+   authorize @user, :update?
    @user.update_attributes(update_params)
  end

end

测试:


$ curl -i -X PUT -d "user[name]=gg-user" \
  --header "Authorization: Token token=izrFiion7xEe2ccTj0v0mOcuNoT3FvpPqI31WLSCEBLvuz4xSr0d9+VI2+xVvAJjECIoju5MaoytEcg6Md773w==, \
  email=test-user-00@mail.com" \
  http://localhost:3000//api/v1/users/2.json

此时服务器报 Pundit::NotAuthorizedError 错误,

Pundit::NotAuthorizedError (not allowed to update?

我们可以使用 rescue_from 捕捉 Pundit::NotAuthorizedError 这类异常。

class Api::V1::BaseController < ApplicationController

  include Pundit

+  rescue_from Pundit::NotAuthorizedError, with: :deny_access

+  def deny_access
+    api_error(status: 403)
+  end

end

测试:

$ curl -i -X PUT -d "user[name]=gg-user" \
  --header "Authorization: Token token=izrFiion7xEe2ccTj0v0mOcuNoT3FvpPqI31WLSCEBLvuz4xSr0d9+VI2+xVvAJjECIoju5MaoytEcg6Md773w==, \
  email=test-user-00@mail.com" \
  http://localhost:3000//api/v1/users/2

HTTP/1.1 403 Forbidden 
X-Frame-Options: SAMEORIGIN
X-Xss-Protection: 1; mode=block
X-Content-Type-Options: nosniff
Content-Type: text/plain; charset=utf-8

这次服务器直接返回 403 Forbidden

分页

我们现在要实现一个展示用户发的微博的 API, 如果用户的微博数量很多,那么我们应该用上分页。

建立 Micropost 模型

$ bundle exe rails g model Micropost

db/migrate/20150503131743_create_microposts.rb,

class CreateMicroposts < ActiveRecord::Migration
  def change
    create_table :microposts do |t|
      t.string :title
      t.text :content
      t.integer :user_id
      t.timestamps null: false
    end
  end
end

执行:

$ bundle exe rake db:migrate

为 id 为 1 的用户创建 100 条微博纪录:

lib/tasks/data.rake,

namespace :data do
  task :create_microposts => [:environment] do
    user = User.find(1)
    100.times do |i|
      Micropost.create(user_id: user.id, title: "title-#{i}", content: "content-#{i}")
    end
  end
end

执行:

$ bundle exe rake data:create_microposts

Api::V1::MicropostsController

执行:

$ bundle exe rails g controller api/v1/microposts --no-assets

配置路由:

config/routes.rb,

Rails.application.routes.draw do

  namespace :api do
    namespace :v1 do
 +    scope path: '/user/:user_id' do
 +      resources :microposts, only: [:index]
 +    end
    end
  end

end

此时和 microposts 相关的路由如下:

api_v1_microposts GET    /api/v1/user/:user_id/microposts(.:format) api/v1/microposts#index

我们使用 kaminari 这个 gem 进行分页。

安装 kaminari,

Gemfile

+ gem 'kaminari'

执行:

$ bundle install

app/models/user.rb

class User < ActiveRecord::Base

 + has_many :microposts

end

app/controllers/api/v1/microposts_controller.rb

class Api::V1::MicropostsController < Api::V1::BaseController

+  def index
+    user = User.find(params[:user_id])
+    @microposts = paginate(user.microposts)
+  end

end

app/controllers/api/v1/base_controller.rb

class Api::V1::BaseController < ApplicationController

  def paginate(resource)
    resource = resource.page(params[:page] || 1)
    if params[:per_page]
      resource = resource.per(params[:per_page])
    end

    return resource
  end

end

app/helpers/application_helper.rb

module ApplicationHelper

+  def paginate_meta_attributes(json, object)
+    json.(object,
+          :current_page,
+          :next_page,
+          :prev_page,
+          :total_pages,
+          :total_count)
+  end

end

app/views/api/v1/microposts/index.json.jbuilder,

json.paginate_meta do
  paginate_meta_attributes(json, @microposts)
end
json.microposts do
  json.array! @microposts do |micropost|
    json.(micropost, :id, :title, :content)
  end
end

测试:

$ curl -i -X GET http://localhost:3000/api/v1/user/1/microposts.json?per_page=3

{
    "paginate_meta": {
    "current_page":1,
    "next_page":2,
    "prev_page":null,
    "total_pages":34,
    "total_count":100
    },
    "microposts":[
    {"id":1,"title":"title-0","content":"content-0"},
    {"id":2,"title":"title-1","content":"content-1"},
    {"id":3,"title":"title-2","content":"content-2"}
    ]
}

API 调用频率限制(Rate Limit)

我们使用 redis-throttle 来实现这个功能。

Gemfile,

gem 'redis-throttle', git: 'git://github.com/andreareginato/redis-throttle.git'

执行,

$ bundle install

集成到 Rails 中:

config/application.rb,

# At the top of config/application.rb
+ require 'rack/redis_throttle'

class Application < Rails::Application
  # Limit the daily number of requests to 3
  # 为了测试我们把 limit 设置为 3
+ config.middleware.use Rack::RedisThrottle::Daily, max: 3
end

我们开始测试,请求 http://localhost:3000/api/v1/users/1 4次看会出现什么结果。

前面 3 次请求一切正常,

curl -i http://localhost:3000/api/v1/users/1

HTTP/1.1 200 OK 
X-Frame-Options: SAMEORIGIN
X-Xss-Protection: 1; mode=block
X-Content-Type-Options: nosniff
Content-Type: application/json; charset=utf-8
X-Ratelimit-Limit: 3
X-Ratelimit-Remaining: 0
Etag: W/"eb58510a43ebc583cf61de35b6d20093"
Cache-Control: max-age=0, private, must-revalidate
X-Request-Id: bbe7437b-ba6e-4cfd-a4ef-49eec4c611fd
X-Runtime: 0.014384
Server: WEBrick/1.3.1 (Ruby/2.1.2/2014-05-08)
Date: Thu, 07 May 2015 13:03:31 GMT
Content-Length: 199
Connection: Keep-Alive

{"user":{"id":1,"email":"test-user-00@mail.com","name":"gg-user","activated":"2015-05-02T07:47:14.697Z","admin":false,"created_at":"2015-05-02T07:47:14.708Z","updated_at":"2015-05-03T05:40:24.931Z"}}

我们注意服务器返回的两个响应头: X-Ratelimit-Limit 和 X-Ratelimit-Remaining,

X-Ratelimit-Limit 的值一直为3,表示请求的限制值,

而 X-Ratelimit-Remaining 每请求一次,其值会减 1, 直到为 0。

第 4 次请求出现 403 Forbidden, 这说明 redis-throttle 起到了其应有的作用。

curl -i http://localhost:3000/api/v1/users/1 

HTTP/1.1 403 Forbidden 
Content-Type: text/plain; charset=utf-8
Cache-Control: no-cache
X-Request-Id: fd646f00-a6a8-411d-b5e4-24856c63b078
X-Runtime: 0.002375
Server: WEBrick/1.3.1 (Ruby/2.1.2/2014-05-08)
Date: Thu, 07 May 2015 13:03:33 GMT
Content-Length: 35
Connection: Keep-Alive

403 Forbidden (Rate Limit Exceeded)

redis-throttle 的 redis 连接默认是 redis://localhost:6379/0, 你也可以通过设置环境变量

ENV['REDIS_RATE_LIMIT_URL'] 来改变 redis-throttle 的 redis 连接。

CORS

CORS 是 Cross Origin Resource Sharing 的缩写。简单地说 CORS 可以允许其他域名的网页通过 AJAX 请求你的 API。

我们可以使用 rack-cors gem 来帮助我们的 API 实现 CORS。

Gemfile,

+ gem 'rack-cors'

config/application.rb,

module BuildAnApiRailsDemo
  class Application < Rails::Application

+    config.middleware.insert_before 0, "Rack::Cors" do
+      allow do
+        origins '*'
+        resource '*', :headers => :any, :methods => [:get, :post, :put, :patch, :delete, :options, :head]
+      end
+    end

  end
end

Version 2 API

随着我们的业务发展,我们的 API 需要做较大的改变,同时我们需要保持 Version 1 API, 所以我们 开始开发 Version 2 API。

routes

config/routes.rb,

Rails.application.routes.draw do

  namespace :api do
    namespace :v1 do
      resources :users, only: [:index, :create, :show, :update, :destroy]
      # resources :microposts, only: [:index, :create, :show, :update, :destroy]
      resources :sessions, only: [:create]
      scope path: '/user/:user_id' do
        resources :microposts, only: [:index]
      end
    end

+    namespace :v2 do
+      resources :users, only: [:index, :create, :show, :update, :destroy]
+      resources :sessions, only: [:create]
+      scope path: '/user/:user_id' do
+        resources :microposts, only: [:index]
+      end
+    end

  end

end

controller

生成 API::V2::UsersController, 其他控制器的生成类似

$ bundle exe rails g controller api/v2/users --no-assets

app/controllers/api/v2/users_controller.rb,


class Api::V2::UsersController < Api::V1::UsersController

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

end

app/vies/api/v2/users/show.json.jbuilder,

json.user do
  json.(@user, :id, :email, :name,  :activated, :admin, :created_at, :updated_at)
end

测试:

$ curl -i http://localhost:3000/api/v2/users/1.json

{"user":{"id":1,"email":"test-user-00@mail.com","name":"gg-user","activated":"2015-05-02T07:47:14.697Z","admin":false,"created_at":"2015-05-02T07:47:14.708Z","updated_at":"2015-05-03T05:40:24.931Z"}}%    

文档

原文提到了下面的几种文档工具:

  1. swagger-railsswagger-docs

  2. apipie-rails

  3. slate

和原文一样,我也喜欢使用 slate 作为文档工具.

将 slate 集成到项目中

创建 docs 目录,

$ mkdir app/docs

集成 slate,

$ cd app/docs

$ git clone git@github.com:tripit/slate.git

$ rm -rf slate/.git

$ cd slate

$ bundle install

配置构建目录, app/docs/slate/config.rb


+ set :build_dir, '../../../public/docs/'

现在我们开始编写获取用户信息这个 API 的文档。

app/docs/slate/source/index.md,

---
title: API Reference

language_tabs:
  - ruby

toc_footers:
  - <a href='http://github.com/tripit/slate'>Documentation Powered by Slate</a>

includes:
  - errors

search: true
---

# 介绍

API 文档

# 获取用户信息

## V1

## HTTP 请求

`GET http://my-site/api/v1/users/<id>`

## 请求参数

参数名 | 是否必需 | 描述
-----| --------| -------
id   |  是      | 用户 id|

## 响应

\```json
{
  "user":
  {
    "id":1,
    "email":"test-user-00@mail.com",
    "name":"test-user-00",
    "activated":"2015-05-02T07:47:14.697Z",
    "admin":false,
    "created_at":"2015-05-02T07:47:14.708Z",
    "updated_at":"2015-05-02T07:47:14.708Z"
   }
}
\```

注意: index.md 范例里的json代码语法高亮部分有转义字符, 直接复制可能没法看到语法高亮效果, 在实际使用时需要将 ``` 前面的 '\' 符号去掉。

build 脚本

docs_build.sh,

#!/bin/bash

cd app/docs/slate

bundle exec middleman build --clean

build docs,

$ chmod +x docs_build.sh

$ ./docs_build.sh

可以通过 http://localhost:3000/docs/index.html 访问文档

给 API 文档添加访问控制

配置路由:

routes.rb,

+ get '/docs/index', to: 'docs#index'

建立相关控制器:

$ bundle exe rails g controller docs

app/controllers/docs_controller.rb,

class DocsController < ApplicationController

  USER_NAME, PASSWORD = 'doc_reader', '123123'

  before_filter :basic_authenticate

  layout false

  def index
  end

  private

  def basic_authenticate
    authenticate_or_request_with_http_basic do |user_name, password|
      user_name == USER_NAME && password == PASSWORD
    end
  end

end

同时我们需要把 public/docs/index.html 文件转移到 app/views/docs/ 目录下面, 我们

可以更改 docs_build.sh 脚本, 注意 docs_build.sh 应该放在项目的根目录下, 比如: /path/to/build-an-api-rails-demo/docs_build.sh,

#!/bin/bash

app_dir=`pwd`
cd $app_dir/app/docs/slate

bundle exec middleman build --clean

cd $app_dir

mv $app_dir/public/docs/index.html $app_dir/app/views/docs

重新 build 文档,

$ ./docs_build.sh

浏览器访问 http://localhost:3000/docs/index.html,

提示需要输入用户名和密码,我们输入正确的用户名(doc_reader)和密码(123123)后就可以正常访问文档了,

项目代码

build-an-api-rails-demo

感谢 @lazybios 同学提的5点建议,让本文变的更好。

感谢 @night_7th 提的注明 skip_before_filter :verify_authenticity_token 的建议.

共收到 195 条回复

#1楼 @rei 竟然有这么好的例子,感谢

文档方面我在用RAML(http://raml.org/) 感觉写起来比markdown方便

:plus1: 好全,学习了

#4楼 @suupic markdown 最大的好处是它本身的可读性对人类非常友好

思路是对的,没有必要为了写 API 而另准备一套服务器

:thumbsup:

:plus1:

赞!

Good! 正是我所需要的

请问楼主 generate_authentication_token 中为什么要用 loop 呢?

哦, 是要保证 token 的唯一性。。。

#13楼 @lithium4010 避免生成重复的 authentication_token

#6楼 @kayakjiang

RAML专门用来描述REST API, 可读性要比markdown好

之前用过slate,感觉markdown文件一大了书写和修改都十分头疼

RAML使用YAML语法,许多通用的属性可以嵌套引用,能省掉很多功夫 同时也支持内嵌markdown描述复杂的内容

也有一个webUI,raml文件拖进去就能跑,webUI还支持模拟请求 https://github.com/mulesoft/api-console

供参考

最近也在弄API, 好纠结, 最后还是用了grape来实现。

一开始也打算这么写, 后来看了下感觉代码量也没有少, 还往routes里增加了不少代码, 所以有人能够解释下这样写有什么好处不?

#16楼 @flingfox63 对啊,用 Grape 写,代码量也没有少,routes 的代码都移到 grape 里面,调用栈增加了,跟 Rails 的 Filter 和 Helper 不通用了,有人解释下 Grape 有什么好处么?

#17楼 @rei 据爱用 Grape 的人说,他们觉得用 Grape 就能控制住一切,Rails 太复杂,他们感觉控制不了。 我觉得,他们可能需要控制了 Ruby 解释器的代码~

#15楼 @suupic 看了下视频,RAML 的效果确实很惊艳,有机会试试

#16楼 @flingfox63 以后有机会还是试试用 Rails 写 API,其实写 API 和平时开发 web 是一样的,没有必要再引入其他的框架去单独写 API,另外 Rails 的路由非常棒,通过路由你能够了解一个复杂项目的脉络。

#17楼 @rei Grape 和rails api 都写过。Grape 也许是另一种舒适的代码体验

虽然正在用Grape,但早就习惯rails这一套,还是觉得rails用起来方便一些,效率也不会差多少。

很全,赞!

太好了,要什么来什么,正要找这样的文章就看到了,呵呵。

目前我用 Grape + Goliath 的组合。使用了 Activerecord, 然后和 Rails 共享 model 层的代码。扩展了Grape让它支持 html渲染,以便提供 API 文档页面,自己写了发布代码以便不要和 Rails发布产生交叉影响;单独使用了 whenever ,增加了几个类似 Rails里面的目录来放 rake task文件和 schedule 文件,让Api的后台脚本与Rails分开管理。这样 Rails就可以单独做后台管理,特别是发布和测试的时候,不会影响前端API;还可以随意增加Rails项目降低耦合度。

很棒, 支持了

文章很赞!

@suupic RAML貌似是个很不错的选择。

之前是用 swagger 在寫公司內部的 API 文檔,不過後來發現靜態 HTML 就足夠滿足需求,所以找了

https://github.com/kevinrenskers/raml2html https://www.npmjs.com/package/raml2html

雖然不是 gem,但相當好用,有需要的朋友可以參考下

写的很好,赞一个!

我觉得直接用ApplicationController还是太重了,可以继承ActionController::Metal,然后一个个把需要的东西包含进来,性能岂不是更好?

我现在的项目是rails+greap,当时写API时考虑过使用rails-api,直接rails,greap,3选一,最后让我确定用greap的理由是,后台啥的全是写rails,偶尔换换口味写写其他风格的代码,不是果断可以调节下么,而且greap的部分优势其实还是有目共睹的

33楼 已删除

不错不错

你有做spec controller 吗?

require 'rails_helper'
require 'awesome_print'

RSpec.describe Api::V1::UsersController, type: :controller do
  describe "GET #show" do
    before do
      @user = create :user
      @request.headers['Authorization'] = "Token token=#{@user.authentication_token}, email=#{@user.email}"  # 问题point
    end

    after do
      @request.headers['Authorization'] = nil
    end

    it "returns http success" do
      get :show, { id: @user.to_param, format: :json }
      ap response.body  # 此处有一个奇怪的反应,打印 "" 这个""不知从何处而来。原因是加入了@request.headers['Authorization'] = "xxx“的设置,去掉就正常返回。
      json_hash = JSON.parse(response.body)
      expect(json_hash['code']).to eq(200)
    end
  end
end

console log

""
F

Failures:

  1) Api::V1::UsersController GET #show returns http success
     Failure/Error: json_hash = JSON.parse(response.body)
     JSON::ParserError:
       A JSON text must at least contain two octets!
     # /home/yy/.rvm/gems/ruby-2.1.6/gems/json-1.8.2/lib/json/common.rb:155:in `initialize'
     # /home/yy/.rvm/gems/ruby-2.1.6/gems/json-1.8.2/lib/json/common.rb:155:in `new'
     # /home/yy/.rvm/gems/ruby-2.1.6/gems/json-1.8.2/lib/json/common.rb:155:in `parse'
     # ./spec/controllers/api/v1/users_controller_spec.rb:20:in `block (3 levels) in <top (required)>'
     # ./spec/support/database_cleaner.rb:10:in `block (3 levels) in <top (required)>'
     # /home/yy/.rvm/gems/ruby-2.1.6/gems/database_cleaner-1.4.1/lib/database_cleaner/generic/base.rb:15:in `cleaning'
     # /home/yy/.rvm/gems/ruby-2.1.6/gems/database_cleaner-1.4.1/lib/database_cleaner/base.rb:92:in `cleaning'
     # /home/yy/.rvm/gems/ruby-2.1.6/gems/database_cleaner-1.4.1/lib/database_cleaner/configuration.rb:86:in `block (2 levels) in cleaning'
     # /home/yy/.rvm/gems/ruby-2.1.6/gems/database_cleaner-1.4.1/lib/database_cleaner/configuration.rb:87:in `call'
     # /home/yy/.rvm/gems/ruby-2.1.6/gems/database_cleaner-1.4.1/lib/database_cleaner/configuration.rb:87:in `cleaning'
     # ./spec/support/database_cleaner.rb:9:in `block (2 levels) in <top (required)>'

database_cleaner config

RSpec.configure do |config|

  config.before(:suite) do
    DatabaseCleaner.strategy = :transaction
    DatabaseCleaner.clean_with(:truncation)
  end

  config.around(:each) do |example|
    DatabaseCleaner.cleaning do
      example.run
    end
  end

end

#35楼 @flowerwrong 没有,晚点试下你的代码

文中很多rake命令前面为何要加bundle exe?

#35楼 @flowerwrong 对你写的 spec 代码做了一些修改:

require 'spec_helper'
require 'awesome_print'

RSpec.describe Api::V1::UsersController, type: :controller do

  + render_views

end

加了一个 render_views, 这样 response.body 就不为空串了。

和请求头加不加 Authorization 没有关系。

render_views 的问题你可以参考 https://www.bountysource.com/issues/9210089-rails-test-log-says-my-templates-were-rendered-when-they-actually-weren-t

#38楼 @kayakjiang Thx. 😄 But for someone stepping in to a legacy code base, and adding regression tests, it was very surprising. I am very surprising.

太全了 学习了

学习了!

#26楼 @outman =0=请问要怎么扩展Grape让他可以渲染html?最近也碰到这个问题,但是没有找到解决办法,方便的话望告知~谢谢

好文,涨姿势

一个细节问题:

def reset_auth_token!
  generate_authentication_token
  save # 此处改为: save(validate: false) 会更好一点
end

最近在用Grape写API,发现rails中的 request.remote_ip 这种基本功能都没有试验成功。 对Grape是又爱又恨。

为什么要用 app/views/api/v1/users/show.json.jbuilder , 而不是直接render json

#45楼 @gazeldx 你可以在Nginx 里面配置: proxy_set_header X-Real-IP $remote_addr;
然后在Grape 里面用 headers['X-Real-Ip'] 就可以取到 remote ip 了。

#42楼 @lingxueyu 我是先扩展了它的formatter, 让它支持返回 html, 代码如下仅供参考:

module Grape
  module ContentTypes
    def self.content_types_for(from_settings)
      if from_settings.present?
        from_settings
      else
                ActiveSupport::OrderedHash[
                    :xml,  'application/xml',
                    :serializable_hash, 'application/json',
                    :json, 'application/json',
                    :binary, 'application/octet-stream',
                    :txt,  'text/plain',
                    :html,  'text/html'
            ]

      end
    end
  end
end

module Grape
  module Formatter
    module Html
      class << self
        def call(object, env)
        end
      end
    end
  end
end

Grape::Formatter::Base.formatters({html: Grape::Formatter::Html})

然后写一个专门的api接口来处理html渲染。模板引擎可以考虑使用ERB。比如

class Doc < Grape::API 
     format :html
     content_type :html, 'text/html'

     get '/path' do
       #render erb template
     end
end

最后你可以考虑把这个Api挂接到你的主Api里面。我主要是用来给前端开发人员提供 Api 文档。

#46楼 @feng88724 使用 jbuilder 模板,主要基于以下三点考虑:

  1. 经典的 MVC 模式, 即 Model-View-Controller;

    json.jbuilder 和 html.erb, html.haml 一样作为view 层

  2. 零代价使用 rails 提供的丰富的 helper 方法;

  3. json.jbuilder 模板有所见即所得的作用, 虽然代码可能会有点冗余,但是易于人类阅读;

比如:

json.user do
   json.(@user, :id, :email, :name,  :activated, :admin, :created_at, :updated_at)
end

和需要生成的 json 数据结构是一致的

{ 
   "user":{
      "id":1,
       "email":"test-user-00@mail.com",
       "name":"test-user-00",
       "activated":"2015-05-02T07:47:14.697Z",
       "admin":false,
       "created_at":"2015-05-02T07:47:14.708Z",
       "updated_at":"2015-05-02T07:47:14.708Z"
   }
}

赞一个!

#47楼 @outman 非常感谢。很可惜我尝试过后,依然没有成功。

这种 API 的验证应该考虑用 JWT 更好 http://jwt.io/

#52楼 @wahyd4 看了一下 JWT, 确实不错,赞

我的log出现 "Can't verify CSRF token authenticity"

可以直接用 gem 'rails-api', 剔除了 asset-pipeline 和 session 相关的功能。 授权用 jwt 处理,同时本地不需要存储 authentication_token 的。jwt 可以看这个,我现在的项目就是做 REST API 开发 https://ruby-china.org/topics/25080

#55楼 @yue Rails 剔除 asset-pipeline 和 session 用不了几行代码, jwt 不错,可以把 api authentication 这一块的逻辑标准化。 你说的 本地不需要存储 authentication_token 不太正确,你用 jwt encode 的那个 payload 其实就相当于一个 authentication_token

对于 api 这种需要高并发的 http 请求,建议还是逃离 rails,逃离 grape。基于简单的 rack http server 能直接把 rails 的并发秒成渣。 详情请阅读这篇文章 http://www.madebymarket.com/blog/dev/ruby-web-benchmark-report.html

另外我们自己做基于 eventmachine+rack 的 api framework 能轻易的达到每秒上千的并发。 rails 的并发性能实际上测试下来非常糟糕,差别在一个数量级。

#56楼 @kayakjiang 准确来说是 user 不需要 authentication_token 的属性,没有数据库的存储。

👍 很完整的示例,从里面学习到不少技巧啊。关于 API 集合分页,如果考虑使用 Link header 的话,推荐 api-pagination

#57楼 @join 我上一家公司曾经遇到这样一个事故,好几台部署了某个 java 服务的服务器经常内存耗尽导致服务崩溃, 开始以为是 rails 导致的因为上面也部署了一些 rails 应用,并且大家习惯上认为 rails 性能低下, 所以都去检查 rails 是不是出问题了,后来发现是 java 导致的, 事故的原因听其他同事讲是每来一个请求,java 都开一个线程去处理这个请求,但是这个请求后面有些写的很复杂很低效的 sql, 然后这个请求就一直耗着,线程一直挂着,内存也得不到释放,理论上只要机器支持, java 这个并发量可以做到很大,但是在这种情况下,这种所谓的数据上光鲜的大并发不但没有什么用还是有危害的,因为此时并发越多,挂住的线程越多,就会越快把服务器的内存搞光。我看了你提供的链接,说实话我认为这种温室里的性能测试没有什么价值.

另外我们自己做基于 eventmachine+rack 的 api framework 能轻易的达到每秒上千的并发 我很好奇你们是如何测试的,如果在真实的生产环境下你们测试能达到上千的并发,我觉的很了不起,如果你能提供代码(可以把涉及商业机密的代码去掉)或者写篇文章介绍下就更好了。

#58楼 @yue 是的,你写的那篇帖子,是我见到的第一篇有关jwt实际应用的帖子,👍,以后可以参考下。

#59楼 @reyesyang api-pagination 这个东西不错 👍, 我收获也很多 😄

63楼 已删除

写着写着有点没想通。

class Api::V1::BaseController < ApplicationController
  attr_accessor :current_user
end

module Api
  module V1
    class CinemasController < BaseController
      def index
        @user = current_user  # 此处为什么可以访问父类的current_user
      end
    end
  end
end

我换种方式试了下,不行,求解

class A
  attr_accessor :a
end

class B < A
  def b
    p a
  end
end

A.new.a = 5
B.new.b  # nil
65楼 已删除

#45楼 @gazeldx 你可以这样去取 remote_ip,request.env['HTTP_X_REAL_IP'] Grape 内部有一层包装,遇到类似问题,建议查看一下 Grape 的源代码。

之前关注过 Grape 写 API 的性能。与 Rails 相比,确实提升一点,主要提升在 Rails ActionDispatch::Routing 部分。但是,不论 Grape 还是 Rails,在处理 HTTP 请求方面,都很慢!一个 Grape 写的 Hello World API 并发量都很小。

对于创业初期的小项目,应该没有问题。已经有用户量的项目,需要考虑好,上线后的平行扩展,及时升级服务器硬件。

之前做的 AB 并发测试总结,写在一篇博客上了,感兴趣的朋友可以看一下。 PS:第一次冒充测试人员,做并发测试,应该有不少盲点,欢迎提意见。

另外,国外网友总结的一篇性能报告,非常值得一看: BTW:老外测试的硬件条件比较牛,所以,数据只能作为参考。

token防泄漏是个伪命题啊

#64楼 @flowerwrong 有点歪楼了。。。


A.new.a = 5 # 生成A实例 赋值成员变量a 然后该实例被抛弃
B.new.b     # 生成B实例 成员变量a尚未赋值 b方法打印a nil

如果测试的话


b = B.new
b.a = 5
b.b  # 5 

非常感谢楼主的分享👍 现在在工作中用apidocjs来写api文档,它以注释的形式和代码写在一起,觉得维护起来