RABL

RABL(Ruby API Builder Language)은 JSON, XML, MessagePack, PList 및 BSON을 생성하기 위한 Rails 및 Padrino Ruby 템플릿 시스템입니다. ActiveRecord의 'to_json' 메서드를 사용할 때, API 생성을 위한 더 표현적이고 강력한 솔루션이 필요하다고 느꼈습니다. 이는 특히 JSON 표현이 복잡하거나 데이터베이스에 정의된 정확한 스키마와 일치하지 않을 때 더욱 그렇습니다.

특히, 다음과 같은 기능을 쉽게 사용하고 싶었습니다:

• 객체의 데이터를 결합하여 이름이 지정된 임의의 노드 생성
• 메서드에 인수를 전달하고 결과를 하위 노드로 저장
• 부분 템플릿 렌더링 및 상속을 통한 코드 중복 감소
• 속성의 이름을 변경하거나 별칭을 지정하여 모델의 이름과 다르게 설정
• 하위 노드의 속성을 상위 노드에 추가
• 특정 조건이 충족된 경우에만 노드 포함

ActiveRecord의 'to_json' 메서드를 사용하여 JSON 응답을 생성해 본 사람이라면 누구나 이 제한적인 접근 방식의 고통을 느껴보았을 것입니다. RABL은 API 응답 생성에 완전히 새로운 접근 방식을 도입하여 이러한 문제를 해결하기 위해 만들어진 일반 템플릿 시스템입니다.

RABL의 핵심은 API 데이터 표현을 애플리케이션의 뷰 계층으로 미루어 MVC 원칙을 준수하는 것입니다. RABL에 대한 일반적인 오해에 대한 설명은 RABL 이해하기 가이드를 확인하시기 바랍니다. 이 가이드는 이 프로젝트에 대한 혼란을 해소하는 데 도움이 될 것입니다.

Breaking Changes

• v0.8.0(2013년 2월 14일 출시)에서는 multi_json 의존성을 제거하고 Oj(또는 JSON)을 json 파서로 사용합니다. 코드를 단순화하고 의존성을 하나 줄였지만 MultiJson에 대한 참조를 제거해야 할 수도 있습니다.

• v0.6.14(2012년 6월 28일 출시)에서는 RSpec으로 템플릿을 테스트할 때 render_views 사용이 필요합니다. 그렇지 않으면 컨트롤러는 ERB 템플릿과 마찬가지로 단순히 render 명령을 전달합니다.

설치

RABL을 gem으로 설치하세요:``` gem install rabl

또는 Gemfile에 추가하세요:```ruby
# Gemfile
gem 'rabl'
# Also add either `oj` or `yajl-ruby` as the JSON parser
gem 'oj'

하고 bundle install을 실행하여 의존성을 설치하세요.

Rails 2.3.8 (이상), Rails 3.X 또는 Padrino를 사용하는 경우 RABL은 설정 없이 작동합니다.

중요: Padrino를 사용할 때는 rabl 젬이 Gemfile에서 padrino 젬 뒤에 나열되어 있는지 확인하세요. 그렇지 않으면 Rabl이 템플릿 엔진으로 제대로 등록되지 않습니다.

Sinatra 또는 다른 tilt 기반 프레임워크에서는 간단히 등록하세요:```ruby Rabl.register!

and RABL이 초기화되어 사용할 준비가 됩니다. Sinatra와 함께 사용하려면 [시나트라 사용법](https://github.com/nesquena/rabl/wiki/Setup-for-Sinatra) 가이드를 확인하세요.

## 개요 ##

RABL을 사용하여 모든 Ruby 객체에서 JSON 및 XML 기반 API를 생성할 수 있습니다. RABL을 사용하면 데이터는 일반적으로 주로 모델(ORM에 구애받지 않음)에서 파생되며, API 출력의 표현은 간단한 Ruby DSL을 사용하여 뷰 템플릿 내에서 설명됩니다. 이렇게 하면 원하는 JSON 또는 XML에서 데이터를 분리하여 유지할 수 있습니다.

RABL을 설치한 후(위에서 설명됨) RABL 뷰 템플릿을 구성한 다음 컨트롤러(또는 라우트)에서 Sinatra, Padrino 또는 Rails 애플리케이션에서 템플릿을 매우 쉽게 렌더링할 수 있습니다. [Padrino](http://padrinorb.com)을 예로 들어, 블로그 게시물로 채워진 `Post` 모델이 있다고 가정할 때, 라우트를 생성하여 API 표현(JSON 및 XML 모두)을 렌더링할 수 있습니다.```ruby
# app/app.rb
get "/posts", :provides => [:json, :xml] do
  @user = current_user
  @posts = Post.order("id DESC")
  render "posts/index"
end

그러면 @posts의 API 출력을 표현하기 위해 다음과 같은 RABL 템플릿을 생성할 수 있습니다.```ruby

app/views/posts/index.rabl

collection @posts attributes :id, :title, :subject child(:user) { attributes :full_name } node(:read) { |post| post.read_by?(@user) }

다음 JSON 또는 XML을 `http://localhost:3000/posts.json`을 방문할 때 출력합니다.```js
[{  "post" :
  {
    "id" : 5, title: "...", subject: "...",
    "user" : { full_name : "..." },
    "read" : true
  }
}]

이것은 기본 개요이지만, 부분 템플릿(partials), 상속(inheritance), 사용자 정의 노드(custom nodes) 등 더 많은 내용이 있습니다. 아래에서 RABL의 전체 세부 정보를 읽어보세요.

Configuration

RABL은 작동을 위해 거의 또는 전혀 구성이 필요하지 않도록 설계되었습니다. 대부분의 시나리오에서 그렇지만, 필요에 따라 애플리케이션에서 다음과 같은 전역 설정을 지정할 수 있습니다 (이 블록은 완전히 선택 사항입니다):```ruby

config/initializers/rabl_init.rb

require 'rabl' Rabl.configure do |config|

Commented as these are defaults

config.cache_all_output = false

config.cache_sources = Rails.env != 'development' # Defaults to false

config.cache_engine = Rabl::CacheEngine.new # Defaults to Rails cache

config.perform_caching = false

config.escape_all_output = false

config.json_engine = nil # Class with #dump class method (defaults JSON)

config.msgpack_engine = nil # Defaults to ::MessagePack

config.bson_engine = nil # Defaults to ::BSON

config.plist_engine = nil # Defaults to ::Plist::Emit

config.include_json_root = true

config.include_msgpack_root = true

config.include_bson_root = true

config.include_plist_root = true

config.include_xml_root = false

config.include_child_root = true

config.enable_json_callbacks = false

config.xml_options = { :dasherize => true, :skip_types => false }

config.view_paths = []

config.raise_on_missing_attribute = true # Defaults to false

config.replace_nil_values_with_empty_strings = true # Defaults to false

end

각 옵션은 RABL 출력과 관련된 동작을 지정합니다. `include_json_root`가 비활성화되면 각 최상위 객체의 루트 노드가 출력에서 제거되며, `enable_json_callbacks`는 들어오는 요청에 'callback' 매개변수가 있는 경우 'jsonp' 스타일 콜백 출력을 지원합니다.

`include_child_root`가 false로 설정되면 응답의 하위 객체는 기본적으로 루트 노드를 포함하지 않습니다. 이를 통해 원하는 응답 구조를 더욱 세밀하게 조정할 수 있습니다.

`cache_engine`이 설정되면 `fetch` 메서드를 가진 클래스에 할당해야 합니다. 예제는 [기본 엔진](https://github.com/nesquena/rabl/blob/master/lib/rabl/cache_engine.rb)을 참조하십시오.

`perform_caching`이 `true`로 설정되면 캐싱을 수행합니다. Rails를 사용하는 경우 이 옵션을 무시해도 됩니다. Rails의 `config.action_controller.perform_caching`과 동일합니다.

`cache_sources`가 `true`로 설정되면 템플릿 조회가 캐시되어 성능이 향상됩니다. 캐시는 애플리케이션 내에서 `Rabl.reset_source_cache!`를 실행하여 수동으로 초기화할 수 있습니다.

`cache_all_output`이 `true`로 설정되면 컬렉션의 일부로 사용되는 각 개별 템플릿을 포함한 모든 템플릿이 별도로 캐시됩니다. 또한 child, glue 및 partial 내의 모든 것도 별도로 캐시됩니다. 단일 템플릿만 캐시하려면 아래 '캐싱' 섹션을 참조하십시오.

`escape_all_output`이 `true`로 설정되고 ActiveSupport를 사용할 수 있는 경우, 속성 출력은 [ERB::Util.html_escape](http://corelib.rubyonrails.org/classes/ERB/Util.html)를 사용하여 이스케이프됩니다. 사용자 정의 노드는 이스케이프되지 않으므로 `ERB::Util.h(value)`를 사용하십시오.

`view_paths`가 경로로 설정되면 이 뷰 경로가 애플리케이션 내의 모든 rabl 템플릿에 대해 확인됩니다. 특히 엔진에 Rabl을 포함하고 다른 Rails 앱 내에서 뷰 경로를 사용하는 경우 이 경로에 추가하십시오.

`raise_on_missing_attribute`가 `true`로 설정되면 Rabl이 존재하지 않는 속성을 렌더링하려고 할 때마다 RuntimeError가 발생합니다. 그렇지 않으면 속성이 단순히 생략됩니다. 개발 중에 이 값을 true로 설정하면 코드의 견고성을 높이는 데 도움이 될 수 있지만, 프로덕션 코드에서는 `true`를 사용하지 않는 것이 좋습니다.

`replace_nil_values_with_empty_strings`가 `true`로 설정되면 `nil`이며 일반적으로 응답에서 `null`로 표시되는 모든 값이 빈 문자열로 변환됩니다.

기본 JSON 인코딩 엔진으로 [oj](https://github.com/ohler55/oj)를 사용하려면 Gemfile에 다음을 추가하기만 하면 됩니다:```ruby
# Gemfile
gem 'oj'

그리고 RABL은 JSON 응답을 인코딩하기 위해 해당 엔진을 자동으로 사용합니다. 루비 데이터에서 JSON으로 변환하기 위한 dump 또는 encode 메소드를 정의하는 자신만의 커스텀 json_engine을 설정하세요:```ruby config.json_engine = ActiveSupport::JSON

### 형식 구성 ###

RABL은 MessagePack, BSON, Plist에 대한 구성을 지원합니다. 자세한 내용은 [형식 구성](https://github.com/nesquena/rabl/wiki/Configuring-Formats) 페이지를 확인하세요.

## 사용법 ##

### 객체 할당 ###

템플릿에서 사용할 데이터 객체를 선언하려면:```ruby
# app/views/users/show.json.rabl
object @user

또는 객체에 대한 별칭을 지정하십시오:```ruby object @user => :person

=> { "person" : { ... } }

또는 객체 컬렉션을 전달합니다:```ruby
collection @users
# => [ { "user" : { ... } } ]

또는 컬렉션의 루트 노드 레이블을 지정하십시오:```ruby collection @users => :people

=> { "people" : [ { "person" : { ... } } ] }

또는 컬렉션의 하위 레이블과 루트 레이블을 모두 지정할 수도 있습니다:```ruby
collection @users, :root => "people", :object_root => "user"
# => { "people" : [ { "user" : { ... } } ] }

그리고 이것은 렌더링을 위한 기본 데이터로 사용되거나, 객체 루트를 명시적으로 비활성화합니다:```ruby collection @users, :root => "people", :object_root => false

=> { "people" : [ { ... }, { ... } ] }

또한 응답의 최상위 레벨이 어떤 객체에도 직접 매핑되지 않는 특이한 경우가 있을 수 있습니다:```ruby
object false
node(:some_count) { |m| @user.posts.count }
child(@user) { attribute :name }

그러한 경우, 객체는 'false'로 할당될 수 있으며 노드는 자유롭게 구성될 수 있습니다.

Attributes