Railsのcsvダウンロードで直面する数々の問題を解決したらgemができた 〜csb gemの紹介〜

## はじめに: csvダウンロードの処理をちゃんと書くのって意外と面倒じゃないですか？

例えば「rails csv ダウンロード」で検索すると以下のようなサンプルコードがよく出てきます。

```ruby:posts_controller.rb
class PostsController < ApplicationController
  def index
    @posts = Post.all
  end
end
```

```index.csv.ruby
require 'csv'

CSV.generate do |csv|
  column_names = %w[投稿日 カテゴリ タイトル 本文]
  csv << column_names
  @posts.each do |post|
    column_values = [
      l(post.created_at.to_date),
      post.category.name,
      post.title,
      post.content,
    ]
    csv << column_values
  end
end
```

しかしこのサンプルコードでは次のような問題が解決出来ていません。

- Excelで開くと文字化けする
- レコード件数が大量にあった場合にメモリエラーやタイムアウトエラーが発生する可能性がある
- 列名と値の定義が離れているために、カラム数が増えてくると可読性が悪く保守性が低くなりがち
- CSV出力の条件が複雑化した場合にテストが書きにくい（system testで頑張るしかない）

この問題を解決するために、[csb](https://github.com/aki77/csb)というgemを作りました。
このgemは弊社[ソニックガーデン](https://www.sonicgarden.jp/)の複数のプロジェクトで1年以上、本番利用されてきた実績があります。

今回の記事ではこのgemの概要と使い方を紹介します。

## 何が出来るの？

- BOM付きUTF-8で出力することで、Excelでも文字化けせずに開ける
- 数十万件以上といった大量データの場合でも、ストリーミングダウンロードにすることでメモリエラーやタイムアウトエラーといったよく起こりがちなトラブルを防げる
- 可読性高くメンテナブルにエクスポート用の処理を書ける
- エクスポート用の処理を切り出しやすくなりテスタビリティが上がる

## 使い方

### インストール

```ruby:Gemfile
gem 'csb'
```

```
$ bundle install
```

### 基本

基本的には以下のようにコントローラでレコードをロードして、ビューにcsvの定義を書くといった流れになります。
これだけで自動的にストリーミングダウンロードとなります。

**ダウンロード元のビュー**

```haml:index.html.haml
= link_to 'CSVダウンロード', posts_path(format: :csv)
```

**CSV出力用コントローラ**

```ruby:posts_controller.rb
def index
  @posts = Post.preload(:category)
end
```

**CSV出力用ビュー**

```ruby:index.csv.csb
# csv.itemsにレコードを入れます（each可能であればActiveRecord::Relation以外のオブジェクトを入れることも出来ます）
csv.items = @posts

# 以下で各カラムを定義しています
csv.cols.add('投稿日') { |post| l(post.created_at.to_date) } # ブロックの場合引数にはレコードが渡ってきます
csv.cols.add('カテゴリー') { |post| post.category.name }
csv.cols.add('タイトル', :title) # 単純なメソッド呼び出しだけの場合はシンボルで書けます
csv.cols.add('本文', :content)
```

### 応用

#### 大量データの場合

ただし大量データの場合、上記の書き方だと全レコードのロードが完了してからストリーミング開始となってしまうため、メモリエラーやタイムアウトエラーが発生しやすくなりストリーミングのメリットを活かせません。
大量データの場合は以下のように`csv.items = @posts.find_each`と書いて、`csv.items`に`Enumerator`を渡すことでストリーミングのメリットを最大限に活かすことが可能となります。

```ruby:index.csv.csb
csv.items = @posts.find_each
csv.cols.add('投稿日') { |post| l(post.created_at.to_date) }
csv.cols.add('カテゴリー') { |post| post.category.name }
csv.cols.add('タイトル', :title)
csv.cols.add('本文', :content)
```

#### 大量データかつ`Decorator`と組み合わせる場合

大量データかつ、CSV出力用にデータを加工したいけど繰り返し同じ処理を書きたくないといったケースでは、専用の`Decoratorクラス`を用意することで以下のように書けます。（[draper](https://github.com/drapergem/draper)の例）

```ruby:index.csv.csb
csv.items = @posts.find_each.lazy.map(&:decorate)
csv.cols.add('投稿日') { |post| l(post.created_at.to_date) }
csv.cols.add('カテゴリー') { |post| post.category.name }
csv.cols.add('タイトル', :decorated_title)
csv.cols.add('本文', :content)
```

#### 特殊な出力

また外部システムとのcsv連携で時々発生する、以下のようなケースにも対応しています。

- 固定文字列を出力したい
- 中身は空でいいけど列は必須
- 同名のカラムが複数必要

```ruby:index.csv.csb
csv.items = @posts
csv.cols.add('固定文字列', 'Dummy') # 第二引数をシンボルではなく文字列にするとそのまま文字列として出力されます。
csv.cols.add('空文字列') # 第二引数を省略すると空文字となります。`csv.cols.add('空文字列', '')` と書くのと同じ。
csv.cols.add('複数カラム', :col1) # 同名カラムを複数定義することも可能です。（定義順に出力されます）
csv.cols.add('複数カラム', :col2)
```

#### Excelで文字化けせずに開きたい

以下のように出力文字コードをBOM付きUTF-8に設定することで、最近のExcelであればWindowsでもMacでも文字化けせずに開けるようになります。

```ruby:config/initializers/csb.rb
Csb.configure do |config|
  config.utf8_bom = true # default: false
end
```

#### ダウンロードするcsvファイル名を設定したい

古いブラウザの考慮が不要で、必ずリンク経由でのダウンロードであればaタグのdownload属性を利用するのがお手軽ですが（[参考リンク](http://html5.cyberlab.info/elements/text/a-download.html)）、view側でも以下のように指定可能となっています。（Rails6以降であれば日本語も問題ないはずです）

```ruby:index.csv.csb
csv.items = @posts
csv.filename = "posts_#{Time.current.to_i}.csv"

# ...
```

#### 非同期でcsv生成したい

ストリーミングダウンロードにすることでメモリエラーやタイムアウトエラーといったよく起こりがちなトラブルは防げますが、サーバ負荷を考慮してあえて非同期で処理したいといったケースもあるかと思います。
そのような場合も以下のように`Csb::Builder`クラスを利用することで、同様のロジックでcsv生成処理を記述することが出来ます。

```ruby:batch.rb
csv = Csb::Builder.new(items: posts)
csv.cols.add('投稿日') { |post| l(post.created_at.to_date) }
csv.cols.add('カテゴリー') { |post| post.category.name }
csv.cols.add('タイトル', :decorated_title)
csv.cols.add('本文', :content)
IO.write('posts.csv', csv.build) # csv.buildでcsv文字列が生成されます
```

#### テスト

複雑な条件によるcsv出力の場合は当然テストも必要となりますが、system testで条件別に検証というのは面倒ですよね。
そんな場合はcsv出力の定義だけをモデル等に書くことで、テスタビリティを上げることが出来ます。

```ruby:post.rb
def self.csb_cols
  Csb::Cols.new do |cols|
    cols.add('タイトル', :title)
    cols.add('本文', :content)
    cols.add('画像') { |post| post.image&.url }
  end
end
```

```ruby:index.csv.csb
csv.items = @posts
csv.cols = Post.csb_cols
```

```ruby:post_spec.rb
# requireすることでcol_pairs, as_tableメソッドが追加で定義されます
require 'csb/testing'

# 行単位でのテスト
context '画像が添付されている場合' do
  let(:image) { build(:image, url: 'https://example.test/example.jpg') }
  let(:post) { build(:post, title: 'Testing', content: 'hogehoge', image: image) }

  it '画像カラムにURLが出力されること' do
    expect(Post.csb_cols.col_pairs(post)).to eq [
      ['タイトル', 'Testing'],
      ['本文', 'hogehoge'],
      ['画像', 'https://example.test/example.jpg'],
    ]
  end
end

context '画像が添付されていない場合' do
  let(:post) { build(:post, title: 'Testing', content: 'hogehoge', image: nil) }

  it '画像カラムが空となること' do
    expect(Post.csb_cols.col_pairs(post)).to eq [
      ['タイトル', 'Testing'],
      ['本文', 'hogehoge'],
      ['画像', ''],
    ]
  end
end

# csv全体でのテスト
describe '.csb_cols' do
  let(:image) { build(:image, url: 'https://example.test/example.jpg') }
  let(:items) do
    [
      build(:post, title: 'Testing1', content: 'hogehoge', image: image),
      build(:post, title: 'Testing2', content: 'fugafuga', image: nil),
    ]
  end

  it '画像有無に関係なくcsv出力されること' do
    expect(Post.csb_cols.as_table(items)).to eq [
      ['タイトル', '本文', '画像'],
      ['Testing1', 'hogehoge', 'https://example.test/example.jpg'],
      ['Testing2', 'fugafuga', nil]
    ]
  end
end
```

## その他

### オプション例

```ruby:config/initializers/csb.rb
Csb.configure do |config|
  # デフォルトはfalseとなっているので注意してください。
  config.utf8_bom = true # default: false
  
  # 基本はデフォルトのままtrueでいいかと思いますが、大量データ配信が一切不要の場合はfalseとするほうがviewで発生するエラーに気付きやすいです。
  config.streaming = false # default: true

  # 何も設定しない場合、Bugsnag等のエラー検知ツールを入れていたとしてもストリーミング配信中のエラーは通知されないので注意が必要です。
  config.after_streaming_error = ->(error) do # default: nil
    Rails.logger.error(error)
    Bugsnag.notify(error)
  end
end
```

### gemの名前の由来

csv builderの略です。
gemの名前とviewの拡張子を揃えようとすると短い名前の方が嬉しいので、語呂が良くて（日本語での）発音も似ている`csb`となりました。

### リポジトリ

https://github.com/aki77/csb
良かったら使ってみてください。