GitHub에서 이 파일을 읽지 마세요. 가이드는 https://guides.rubyonrails.org 에서 제공됩니다.

Ruby on Rails 가이드 작성 지침

이 가이드는 Ruby on Rails 가이드를 작성하기 위한 지침을 설명합니다. 이 가이드는 우아한 순환 구조로 자신을 따르며, 자신을 예시로 제공합니다.

이 가이드를 읽은 후에는 다음 내용을 알게 될 것입니다:

Rails 문서에서 사용되어야 할 규칙들
로컬에서 가이드를 생성하는 방법

1 Markdown

가이드는 GitHub Flavored Markdown으로 작성됩니다. Markdown에 대한 포괄적인 문서와 치트시트가 있습니다.

2 서문

각 가이드는 상단에 동기 부여 텍스트로 시작해야 합니다(파란색 영역의 짧은 소개글입니다). 서문은 가이드가 무엇에 대한 것이고 독자가 무엇을 배우게 될지 설명해야 합니다. 예시로 Routing 가이드를 참조하세요.

3 제목

모든 가이드의 제목은 h1 제목을 사용합니다; 가이드 섹션은 h2 제목을 사용합니다; 하위 섹션은 h3 제목을 사용합니다; 기타 등등. 생성된 HTML 출력은 <h2>로 시작하는 제목 태그를 사용한다는 점에 유의하세요.

죄송하지만 번역할 실제 내용이 제공되지 않았습니다. Rails 가이드 문서의 실제 내용을 공유해 주시면 번역을 도와드리겠습니다.

3.1 Sub Section을 그대로 한글로 번역해드리면 의미가 모호해질 수 있습니다. 원문을 공유해주시면 정확한 맥락을 파악하여 번역해드리겠습니다.

제목을 작성할 때는 전치사, 접속사, 내부 관사, "to be" 동사의 형태를 제외한 모든 단어를 대문자로 시작하세요:


#### Components 내부의 Assertion과 Job 테스팅
#### Middleware Stack은 Array임
#### 객체가 저장되는 시점은 언제인가?

```markdown
일반 텍스트와 동일한 인라인 서식을 사용하세요:

The :content_type option is used to specify the content type of the attachment. By default it is auto-detected from the URL, the local file type on disk, or specified content type header in an uploaded file. This option allows you to customize the content type. In this example, downloading an image file from a URL and saving it as a PDF:

:content_type 옵션은 attachment의 content type을 지정하는데 사용됩니다. 기본적으로 URL, 디스크의 로컬 파일 타입, 또는 업로드된 파일의 지정된 content type 헤더에서 자동으로 감지됩니다. 이 옵션을 사용하면 content type을 커스터마이즈할 수 있습니다. 다음 예시는 URL에서 이미지 파일을 다운로드하여 PDF로 저장하는 것입니다:

class User < ApplicationRecord
  has_one_attached :avatar do |attachable|
    attachable.content_type = "application/pdf"
  end
end

user.avatar.attach(io: HTTP.get("https://example.com/avatar.jpg"),
                  filename: "avatar.jpg")
user.avatar.content_type # => "application/pdf"

You can set content types with validation:

다음과 같이 validation과 함께 content type을 설정할 수 있습니다:

class User < ApplicationRecord
  has_one_attached :avatar do |attachable|
    attachable.content_type = "application/pdf" if attachable.content_type.include?("image/")
  end
end

user.avatar.attach(io: HTTP.get("https://example.com/avatar.jpg"),
                  filename: "avatar.jpg")
user.avatar.content_type # => "application/pdf"

user.avatar.attach(io: File.open("avatar.pdf"),
                  filename: "avatar.pdf",
                  content_type: "application/pdf")
user.avatar.content_type # => "application/pdf"

Notes, Tips and Warnings
------------------------

가끔은 한 문단이 좀 더 주목을 받을만 합니다. 예를 들어 흔한 오해를 명확히 하거나 애플리케이션이 중단될 수 있는 문제에 대해 경고하는 경우입니다.

문단을 강조하려면 `NOTE:`, `TIP:` 또는 `WARNING:`을 앞에 붙이세요:

문단을 강조하기 위해서는 NOTE, TIP 또는 WARNING을 사용하세요.

이것은 문단을 특별한 컨테이너로 감싸서 다음과 같은 결과를 만듭니다:

문단을 강조하기 위해 NOTE, TIP 또는 WARNING을 사용하세요.

3.2 참고

NOTE를 사용하여 주제와 맥락에 관련된 중요한 내용을 강조합니다. 이를 읽으면 해당 주제나 맥락을 이해하는 데 도움이 되거나, 중요한 항목을 명확히 할 수 있습니다.

예를 들어, locale 파일을 설명하는 섹션에는 다음과 같은 NOTE가 있을 수 있습니다:

새로운 locale 파일을 추가할 때는 서버를 재시작해야 합니다.

3.3 TIP

TIP은 해당 주제에 대한 추가 정보이지만, 이해에 반드시 필요한 것은 아닙니다. 다른 가이드나 웹사이트로 안내할 수 있습니다:

라우팅에 대해 더 자세히 알아보려면, 외부에서 보는 Rails 라우팅을 참조하세요.

또는 더 자세히 알아보기 위한 도움이 되는 명령어를 보여줄 수 있습니다:

generator에 대한 추가 도움말을 보려면, bin/rails generate --help를 실행하세요.

3.4 WARNING

WARNING은 애플리케이션을 망가뜨릴 수 있는 피해야 할 사항들에 사용하세요:

callback 메서드 내에서 update, save 또는 객체에 부작용을 일으키는 다른 메서드들의 사용을 자제하세요.

또는 애플리케이션의 보안을 손상시킬 수 있는 것들에 대해 경고하세요.

master key를 안전하게 보관하세요. master key를 커밋하지 마세요.

4 Links

설명이 포함된 링크를 사용하고 "여기" 및 "더 보기"와 같은 링크는 피하세요:

# BAD
[상세 내용](i18n.html)은 Rails Internationalization (I18n) API 문서를 참고하세요.

# GOOD
더 자세한 내용은 [Rails Internationalization (I18n) API 문서](i18n.html)를 참고하세요.

내부 링크에도 설명이 담긴 링크를 사용하세요:

# BAD
이것은 [아래](#multiple-callback-conditions)에서 다룰 것입니다.

# GOOD
이것은 아래에 있는 [multiple callback conditions 섹션](#multiple-callback-conditions)에서 다룰 것입니다.

4.1 API 연결하기

API(api.rubyonrails.org)로의 링크는 가이드 생성기에서 다음과 같은 방식으로 처리됩니다:

release tag를 포함하는 링크는 그대로 유지됩니다. 예를 들어:

ActiveRecord::Attributes::ClassMethods

attribute(name, cast_type = nil, **options) ⇒ Object

모델에 attribute를 정의합니다. 이것은 데이터베이스로부터의 데스크립터가 아닙니다. 대신, 모델에 attribute를 추가하거나 기존 attribute의 동작을 덮어쓸 때 사용됩니다.

class User < ActiveRecord::Base
  attribute :password, :string
end

위의 예시 코드는 User 객체에 password attribute를 추가합니다. attribute의 데이터 타입은 두 번째 파라미터에 의해 결정됩니다. 지원되는 타입은 아래와 같습니다:

:big_integer
:binary
:boolean
:date
:datetime
:decimal
:float
:integer
:string
:text
:time

attribute를 명시적으로 선언하면, 해당 attribute가 데이터베이스에 있는지 여부와 관계없이 객체에서 사용할 수 있습니다.

세 번째 옵션 파라미터를 통해 기본값을 지정할 수 있습니다:

class StoreProduct < ActiveRecord::Base
  attribute :status, :string, default: 'draft'
  store_accessor :status_info, :status
end

default 옵션으로는 값이나 람다를 넘길 수 있습니다:

class UnsubscribeToken < ActiveRecord::Base
  attribute :expired_at, :datetime, default: -> { Time.current + 1.day }
end

자신만의 타입을 만드는 것도 가능합니다. ActiveRecord::Type::Value을 상속하여 타입을 정의하고, 이를 등록하여 사용할 수 있습니다.

# app/types/money_type.rb
class MoneyType < ActiveRecord::Type::Integer
  def cast(value)
    if !value.kind_of?(Numeric) && value.include?('$')
      price_in_dollars = value.gsub(/\$/, '').to_f
      super(price_in_dollars * 100)
    else
      super
    end
  end
end

# config/initializers/types.rb
ActiveRecord::Type.register(:money, MoneyType)

# app/models/store_listing.rb
class StoreListing < ActiveRecord::Base
  attribute :price_in_cents, :money
end

store_listing = StoreListing.new(price_in_cents: '$10.00')
store_listing.price_in_cents # => 1000

ActiveRecord::Type::Value를 상속한 클래스는 다음과 같은 메소드를 오버라이드할 수 있습니다:

cast - 입력값을 적절한 루비 타입으로 변환
serialize - 데이터베이스에 저장하기 위해 값을 직렬화
deserialize - serialize의 반대

수정되지 않습니다.

릴리스 노트에서는 이를 사용해주세요. 생성되는 대상과 관계없이 해당하는 버전을 가리켜야 하기 때문입니다.

링크에 릴리스 태그가 포함되어 있지 않고 edge guides가 생성되는 경우, 도메인은 edgeapi.rubyonrails.org로 대체됩니다. 예를 들어,

ActionDispatch::Response

Response 객체는 controller action이나 middleware에 의해 생성되는 모든 HTTP 응답을 나타냅니다. Response 객체는 응답 헤더를 설정하고 body를 제공하는데 사용됩니다.

5 Status, header, body

HTTP Response는 세 가지 필수 요소로 구성됩니다:

Status
Header
Body

5.1 Status

사용 가능한 HTTP 상태 코드는 Status codes 정의에서 찾을 수 있습니다. Response 객체는 상태 코드의 숫자 값을 설정하는 것을 허용하지만, 이는 해당하는 HTTP 상태 메시지로 변환됩니다. 예를 들어:

response.status = 200  # => "200 OK"
response.status = 404  # => "404 Not Found"

5.2 Header

response.headers는 response의 헤더 값을 저장합니다. 헤더 이름은 대문자와 밑줄로 정규화되며, 중복된 헤더 항목은 병합됩니다(RFC2616에 따라). 문자열이 아닌 헤더 값은 문자열로 변환됩니다.

response.headers["PAGE_TITLE"] = "Index"

5.3 Body

Response body는 문자열 또는 문자열을 생성할 수 있는 객체여야 합니다. 기본적으로 body는 빈 문자열입니다.

6 Cookie와 Session

Cookie와 Session은 사용자의 현재 세션과 관련된 정보를 유지하는 데 사용됩니다. Cookie 데이터는 클라이언트 측에 저장되는 반면, Session 데이터는 서버 측에 유지됩니다.

Cookie를 설정하려면 cookies 메서드를 사용합니다:

cookies[:user_id] = "5"

6.2 Session Management

Session 데이터는 다음과 같이 관리될 수 있습니다:

session[:user_id] = "5"

7 렌더링과 리디렉션

7.1 Rendering Content

다양한 방법으로 콘텐츠를 렌더링할 수 있습니다:

render :xml => @post
render :json => @post
render :plain => "OK"

7.2 Redirects

리디렉션은 다음과 같이 수행됩니다:

redirect_to :action => "show"
redirect_to post_url(@post)

8 Content Type

Response의 Content-Type은 다음과 같이 설정할 수 있습니다:

response.content_type = "text/html"

9 Streaming

Response는 데이터를 스트리밍하는 것을 지원합니다:

self.response_body = @article.to_xml

Rails는 자동으로 올바른 Content-Length 헤더를 설정합니다.

becomes를 사용하면 매핑된 두 모델을 서로 전환할 수 있습니다.

이를 사용하기 위해선 mappings.rb와 같은 파일에 매핑을 먼저 구성해야 합니다:

class Bulb < ActiveRecord::Base
  def self.inheritance_column
    nil
  end

  belongs_to :hue
  has_many :locations
  has_many :serial_numbers

  mappings do
    map_to Lamp do
      attributes :type, :color, :brightness, :power, :serial
    end
  end
end

class Lamp < ActiveRecord::Base
  def self.inheritance_column  
    nil
  end

  belongs_to :shade
  has_many :serial_numbers
  has_many :rooms

  mappings do
    map_to Bulb do
      attributes :type, :color, :brightness, :power, :serial  
    end
  end
end

그런 다음 래핑된 모델간 변환을 수행할 수 있습니다:

bulb = Bulb.create!(serial: "0x000001", type: "LED", color: 'orange')
lamp = bulb.becomes(Lamp)
lamp.serial # => "0x000001"

ActionDispatch::Response

ActionDispatch::Response 객체는 웹 서버에 대한 응답을 캡슐화합니다. 기본적으로 Response 객체에는 3가지 속성이 있습니다:

header - Headers 객체로 응답 HTTP header를 포함합니다
body - 응답 본문을 포함합니다. HTML 템플릿의 내용이 기본값입니다
status - HTTP 상태 코드 (예: "200 OK", "404 Not Found")

10 예제

10.1 응답 상태 설정:

response.status = 404

response.headers["Content-Type"] = "application/json"

10.3 Response 본문 설정:

response.body = "Hello World!"

10.4 Response 본문 추가:

response.body << " From Rails!"

10.5 Response가 이미 보내졌는지 확인:

response.committed?

response.get_header("Set-Cookie")

10.7 컨텐츠 타입이 특정 MIME 타입과 일치하는지 확인:

response.media_type

10.8 전체 content-type header 가져오기:

response.content_type

response.set_cookie(cookie_name, cookie_options)

response.delete_cookie("cookie_name")

만약 link가 release tag를 포함하지 않고 release guides가 생성되고 있다면, Rails 버전이 주입됩니다. 예를 들어, v5.1.0 버전의 가이드를 생성하는 경우 link는

ActionDispatch::Response

본 클래스는 Rack::Response에 래핑되어 있으며 Rails 응답 처리를 위한 전체 인터페이스를 제공합니다.

11 응답 헤더 설정하기

응답 headerx를 설정하려면 헤더 accessor를 사용합니다:

response.headers["Cache-Control"] = "no-cache"

12 응답 Cookies 설정하기

응답 cookies를 설정하려면:

response.set_cookie("user_name", value: "david", path: "/")

삭제하려면:

response.delete_cookie("user_name", path: "/")

13 Content-Type 설정하기

응답 content type을 설정하려면:

response.content_type = "text/plain"

14 Status Code 설정하기

응답 status code를 설정하려면:

response.status = 404

15 응답 Body 설정하기

응답 body를 설정하려면:

response.body = "Hello"

becomes

이것은 내부적으로 to_model을 호출함으로써 객체를 다른 모델로 변환합니다. 이것은 ActionController::Parameters를 실제 모델로 변환할 때 유용합니다:

class Article
  def permitted_params(params)
    params.require(:article).permit(:name)
  end
end

params = ActionController::Parameters.new(article: { name: "Brave New World" })
article = Article.find(1)
article.permitted_params(params).becomes(Article)

ActionDispatch::Response

ActionDispatch::Response 객체는 client에게 데이터를 돌려보내는 response를 나타냅니다. ActionDispatch::Response 객체는 response의 header와 body를 포함합니다.

16 메서드들:

16.1 `#initialize(status = 200, header = {}, body = [])`

response 객체를 초기화합니다.

status - HTTP status code (기본값: 200)
header - response header로 사용될 hash
body - response body로 사용될 string array

$ bundle exec rake guides:generate

다음의 'or' 문자만 있어서 해당 텍스트를 한국어로 번역하면:

또는

$ bundle exec rake guides:generate:html

생성된 HTML 파일은 ./output 디렉토리에서 찾을 수 있습니다.

my_guide.md만 처리하려면 ONLY 환경변수를 사용하세요:

$ touch my_guide.md 
$ bundle exec rake guides:generate ONLY=my_guide

기본적으로 수정되지 않은 가이드는 처리되지 않기 때문에 실제로는 ONLY가 거의 필요하지 않습니다.

모든 가이드를 강제로 처리하려면 ALL=1을 전달하세요.

영어 이외의 언어로 가이드를 생성하려면 source 아래의 별도 디렉토리(예: source/es)에 보관하고 GUIDES_LANGUAGE 환경 변수를 사용할 수 있습니다:

$ bundle exec rake guides:generate GUIDES_LANGUAGE=es

생성 스크립트를 설정하기 위해 사용할 수 있는 모든 환경 변수를 보려면 다음을 실행하세요:

$ rake

19.2 Validation

생성된 HTML을 다음으로 검증해주세요:

$ bundle exec rake guides:validate

특히, 제목은 내용으로부터 ID가 생성되기 때문에 종종 중복이 발생합니다.

20 Kindle Guides

20.1 Generation

Kindle용 가이드를 생성하려면 다음 rake task를 사용하세요:

$ bundle exec rake guides:generate:kindle