当前位置: 首页 > 工具软件 > Grape > 使用案例 >

Grape简介

凤昊东
2023-12-01

什么是Grape

Grape是Ruby中的一个类REST API框架,被设计用于运行在Rack上或弥补已有的web应用框架(比如Rails或者Sinatra),Grape提供了一个简单的DSL用于方便的开发RESTful APIs。Grape支持common conventions,包括多种格式,子域/前缀限制,内容协商,版本控制等。

安装

通过gem安装:

gem install grape

基本用法

你的应用一般要继承自Grape::API,下面的例子暂时了Grape中常用的一些特性:

#config.ru 内容
require "grape"

module Twitter
  class API < Grape::API
    version 'v1', using: :header, vendor: 'twitter'
    format :json
    prefix :api

    helpers do
      def current_user
        @current_user ||= User.authorize!(env)
      end

      def authenticate!
        error!('401 Unauthorized', 401) unless current_user
      end
    end

    resource :statuses do
      desc 'Return a public timeline.'
      get :public_timeline do
        Status.limit(20)
      end

      desc 'Return a personal timeline.'
      get :home_timeline do
        authenticate!
        current_user.statuses.limit(20)
      end

      desc 'Return a status.'
      params do
        requires :id, type: Integer, desc: 'Status id.'
      end
      route_param :id do
        get do
          Status.find(params[:id])
        end
      end

      desc 'Create a status.'
      params do
        requires :status, type: String, desc: 'Your status.'
      end
      post do
        authenticate!
        Status.create!({
          user: current_user,
          text: params[:status]
        })
      end

      desc 'Update a status.'
      params do
        requires :id, type: String, desc: 'Status ID.'
        requires :status, type: String, desc: 'Your status.'
      end
      put ':id' do
        authenticate!
        current_user.statuses.find(params[:id]).update({
          user: current_user,
          text: params[:status]
        })
      end

      desc 'Delete a status.'
      params do
        requires :id, type: String, desc: 'Status ID.'
      end
      delete ':id' do
        authenticate!
        current_user.statuses.find(params[:id]).destroy
      end
    end
  end
end

run Twitter::API

安装

Rack

上面的例子创建了一个简单的Rack应用,将上面的内容放在config.ru文件中,通过如下命令启动:

rackup -o 0.0.0.0

在我的环境中直接执行rackup之后,在其他机器上无法访问
现在可以访问如下路径:

GET /api/statuses/public_timeline
GET /api/statuses/home_timeline
GET /api/statuses/:id
POST /api/statuses
PUT /api/statuses/:id
DELETE /api/statuses/:id

所有的GET选项,Grape也会自动应答HEAD/OPTIONS选项,但是其他路径,只会应答OPTIONS选项。

脱离Rails使用ActiveRecord

如果你想在Grape中使用ActiveRecord,你要保证ActiveRecord的连接池处理正确。保证这一点的最简单的方式是在安装你的Grape应用前使用ActiveRecord的ConnectionManagement中间件:

use ActiveRecord::ConnectionAdapters::ConnectionManagement

run Twitter::API

结合Sinatra(或者其他框架)

如果使用Grape的同时想结合使用其他Rack框架,比如Sinatra,你可以很简单的使用Rack::Cascade:

# Example config.ru

require 'sinatra'
require 'grape'

class API < Grape::API
  get :hello do
    { hello: 'world' }
  end
end

class Web < Sinatra::Base
  get '/' do
    'Hello world.'
  end
end

use Rack::Session::Cookie
run Rack::Cascade.new [API, Web]

Rails

把所有的API文件都放置到app/api路径下,Rails期望一个子文件夹能够匹配一个Ruby模块,一个文件名能够匹配一个类名。在我们的例子中,Twitter::API的路径和文件名应该是app/api/twitter/api.rb。
修改application.rb:

config.paths.add File.join('app', 'api'), glob: File.join('**', '*.rb')
config.autoload_paths += Dir[Rails.root.join('app', 'api', '*')]

修改config/routes:

mount Twitter::API => '/'

另外,如果使用的Rails是4.0+,并且使用了ActiveRecord默认的model层,你可能会想使用 hashie-forbidden_attributes gem包。该gem去使能model层strong_paras的安全特性,允许你使用Grape自己的参数校验。

# Gemfile
gem 'hashie-forbidden_attributes'

Modules

在一个应用内部你可以mount多个其他应用的API实现,它们不需要是不同的版本,但是可能是同一接口的组件:

class Twitter::API < Grape::API
  mount Twitter::APIv1
  mount Twitter::APIv2
end

你也可以挂在到一个路径上,就好像在被mount的API内部使用了prefix一样:

class Twitter::API < Grape::API
  mount Twitter::APIv1 => '/v1'
end

版本控制

版本信息可以通过四种方式提供:

:path、:header、:accept_version_header、:param

默认的方式是:path。

path

version 'v1', using: :path

通过这种方式,URL中必须提供版本信息:

curl http://localhost:9292/v1/statuses/public_timeline
version 'v1', using: :header, vendor: 'twitter'

现在,Grape仅支持如下格式的版本控制信息:

vnd.vendor-and-or-resource-v1234+format

最后的-和+之间的所有信息都会被解释为版本信息(上面的版本信息就是v1234)。
通过这种方式,用户必须通过HTTP的Accept头传递版本信息:

curl -H Accept:application/vnd.twitter-v1+json http://localhost:9292/statuses/public_timeline

默认的,如果没有提供Accept头信息,将会使用第一个匹配的版本,这种行为和Rails中的路径相似。为了规避这个默认的行为,可以使用:strict选项,该选项被设置为true时,如果没有提供正确的Accept头信息,会返回一个406错误。
当提供了一个无效的Accept头时,如果:cascade选项设置为false,会返回一个406错误。否则,如果没有其他的路径匹配,Rack会返回一个404错误。

Accept-Version Header

version 'v1', using: :accept_version_header

使用该方式时,用户必须在HTTP头中提供Accept-Version信息:

curl -H "Accept-Version:v1" http://localhost:9292/statuses/public_timeline

默认的,如果没有提供Accept头信息,将会使用第一个匹配的版本,这种行为和Rails中的路径相似。为了规避这个默认的行为,可以使用:strict选项,该选项被设置为true时,如果没有提供正确的Accept头信息,会返回一个406错误。
当提供了一个无效的Accept头时,如果:cascade选项设置为false,会返回一个406错误。否则,如果没有其他的路径匹配,Rack会返回一个404错误。

Param

version 'v1', using: :param

使用这种方式,用于必须在URL字符串或者请求的body中提供版本信息:

curl http://localhost:9292/statuses/public_timeline?apiver=v1

参数名称默认是“apiver”,你也可以通过:parameter 选项指定:

version 'v1', using: :param, parameter: 'v'
curl http://localhost:9292/statuses/public_timeline?v=v1

描述方法

你可以为API方法和名称空间添加一个描述:

desc 'Returns your public timeline.' do
  detail 'more details'
  params  API::Entities::Status.documentation
  success API::Entities::Entity
  failure [[401, 'Unauthorized', 'Entities::Error']]
  named 'My named route'
  headers XAuthToken: {
            description: 'Valdates your identity',
            required: true
          },
          XOptionalHeader: {
            description: 'Not really needed',
            required: false
          }

end
get :public_timeline do
  Status.limit(20)
end
  • detail
    更详细的描述。
  • params
    直接从一个Entity定义参数。
  • success: (former entity) The Entity to be used to present by default this route
  • failure: (former http_codes) A definition of the used failure HTTP Codes and Entities
  • named: A helper to give a route a name and find it with this name in the documentation Hash
  • headers: A definition of the used Headers

转载于:https://www.cnblogs.com/cuimiemie/p/6442680.html

 类似资料: