五倍直播間

Blogs - Sidebar


reCAPTCHA 是 Google 在 2009年收購一家叫 CAPTCHA 的公司，其服務的目的是為了辨認機器人與防止廣告垃圾訊息氾濫。

reCAPTCHA 問題的所需的文字圖片，首先會由 reCAPTCHA 計畫網站利用 Javascript API 取得，在終端使用者回答問題後，伺服器再連回 reCAPTCHA 計畫的主機驗證使用者的輸入是否正確 - [wiki](https://zh.wikipedia.org/wiki/ReCAPTCHA)。

---

reCAPTCHA 大致分為 3 種：

  - **v2 Checkbox**：「我不是機器人」核取方塊，網站上最常看到的一種，選取圖片或文字來做驗證。

  - **v2 Invisible**：隱形 reCAPTCHA 標記，在發送之前先在背景依照使用者滑鼠軌跡、瀏覽器資訊、Cookie等...判斷是否為機器人，如果判斷為是，則會跳出 v2 Checkbox 的驗證方式來做第二次驗證。

  - **v3**：以分數驗證要求，驗證完在後端可以得到驗證分數，區間為 0.0 ~ 1.0，分數越低則機器人的可能性越高，可以自行以分數高低，來決定是否要進行第二次驗證，例如：寄送 email、簡訊驗證或是使用 v2 Checkbox ...等。 

---

本次會實作以下幾個項目：

1. 實作 `v2 Checkbox` 在註冊帳號頁面
2. 實作 `reCAPTCHA v3` 在登入頁面
3. 實作 `reCAPTCHA v3` fallback validate

---

### 環境

- ruby 2.5.0
- Rails 5.2.3
- sqlite3 3.22.0

先準備一個擁有 Devise 登入頁面的專案：

[recaptcha-with-rails-devise-demo](https://github.com/treekey999/recaptcha-with-rails-devise-demo)

```shell
$ git clone https://github.com/treekey999/recaptcha-with-rails-devise-demo.git

$ cd recaptcha-with-rails-devise-demo

$ git checkout prepare_for_start # 切到已準備好環境的分支
$ git checkout -b my_practice # 在此建立一個 branch 並 checkout 過去

$ bundle
$ yarn
$ rails db:migrate
$ rails s
```

主要先準備了幾個前置作業：

- [devise setup](https://github.com/plataformatec/devise)：新增 User model
- [devise-bootstrap-views](https://github.com/hisea/devise-bootstrap-views)：簡易版 devise bootstrap layout 
- [dotenv rails](https://github.com/bkeepers/dotenv)：管理 env 變數，存放敏感資訊
- rails scaffold Todos title:string description: string user:reference

每一步驟都可以在 git commit 中找的到。

---

## 實作 v2 Checkbox 在註冊帳號頁面

#### 1. 註冊取得 `site_key` & `secret_key`

site key：前端用來跟 google recaptcha 取得 recaptcha token。

secret key：後端用來驗證從前端來的 recaptcha token。

[註冊： https://www.google.com/u/1/recaptcha/admin/create](https://www.google.com/u/1/recaptcha/admin/create)

![post-整合 reCAPTCHA 到你的專案上，搭配 rails、devise](//images.ctfassets.net/8er52l3j5u76/7dALxlRafm674rvmhVt4iY/99714ebd3cc3ee86f0a92b8c1597edad/recaptcha_register_1-f55797e2.jpg)

![posts-整合 reCAPTCHA 到你的專案上，搭配 rails、devise](//images.ctfassets.net/8er52l3j5u76/6IvsNyknUcudr8vM0QSBjp/142ab2593740b3ade193bcdb65ae98cc/recaptcha_register_2-3f8afb32.jpg)

回到專案下，把 `.env` 複製一份並命名為 `.env.local`，由於已經把 `.env.local` 加到 `.gitignore` 所以不會把敏感資訊推到 github 上。

剛剛註冊得到得 `site_key` 、`secret_key`，填到 v2 對應的 key 上，這時候你在 rails 就可以用 `ENV["RECAPTCHA_V2_CHECKBOX_SITE_KEY"]` 來取得內容。

```ruby
RECAPTCHA_V2_CHECKBOX_SITE_KEY="your_site_key......."
RECAPTCHA_V2_CHECKBOX_SECRET_KEY="your_secret_key......"

RECAPTCHA_V3_SITE_KEY=""
RECAPTCHA_V3_SECRET_KEY=""
```

#### 2. 安裝 gem

在 `Gemfile` 加上這一段，並做 `$ bundle`。

[https://github.com/ambethia/recaptcha](https://github.com/ambethia/recaptcha)

```ruby
gem 'recaptcha', git: "https://github.com/ambethia/recaptcha.git"
```

#### 3. overwrite devise user controller

匯出 devise controller。

```shell
$ rails g devise:controllers users
```

修改 `routes.rb` 告訴 devise `user/registrations` controller 要被覆寫。

```ruby
Rails.application.routes.draw do
  root 'todos#index'  
  resources :todos

  devise_for :users, controllers: {
    registrations: 'users/registrations',
  }
end
```

#### 4. 新增 before_action

修改 `app/controllers/users/registrations_controller.rb`，
在 create 的時候，要做 recaptcha 檢查，如果沒通過就 redirect_to 註冊頁面。

```ruby
class Users::RegistrationsController < Devise::RegistrationsController

  before_action :check_recaptcha_v2, only: [:create]

  ......

  private

  def check_recaptcha_v2
    valid = verify_recaptcha secret_key: ENV["RECAPTCHA_V2_CHECKBOX_SECRET_KEY"]

    if not valid
      redirect_to new_user_registration_path
    end
  end
end
```

此時如果去註冊帳號，就會發現被檔下來了。

![post-整合 reCAPTCHA 到你的專案上，搭配 rails、devise](//images.ctfassets.net/8er52l3j5u76/5vNUQxsP1bcqYjt3RbLQpp/6e66ecbdfb744f90f783e8e7843ad86f/registration_not_valid-b60fac7c.jpg)

##### 5. 加入 `recaptcha_tags` 到 register form

修改 `app/views/devise/registrations/new.html.erb` 24 行，
在 submit 前面加上 `recaptcha_tag`。

```ruby
  ......

  <div class="form-group">
    <%= recaptcha_tags site_key: ENV["RECAPTCHA_V2_CHECKBOX_SITE_KEY"] %>
  </div>

  <div class="form-group">
    <%= f.submit t('.sign_up'), class: 'btn btn-primary' %>
  </div>

  ......
```

如果一切都順利的話，可以看到表單上出現了 recaptcha 按鈕，並可以正確的送出表單 🎉 。

![post-整合 reCAPTCHA 到你的專案上，搭配 rails、devise](//images.ctfassets.net/8er52l3j5u76/7nPLvhMlD3SqYnaj7XBkSF/35eb53447023aad6897b4cd253cd7896/recaptcha_set_correct-f805b770.jpg)

可以看到帶了一個 `g-recaptcha-response` 的 params。

![post-整合 reCAPTCHA 到你的專案上，搭配 rails、devise](//images.ctfassets.net/8er52l3j5u76/1GvjV1DRbiIeoKMAtej7Fn/2528f9c4d740d2c7a051b95793467216/post_registration-66daecf3.jpg)

如果失敗，應該會看到這個畫面，應該檢查一下 `ENV` 的值有沒有正確、`.env.local` 有沒有正確 或 `recaptcha設定` 有沒有加 `localhost` 到 domain 清單裡面。

![post-整合 reCAPTCHA 到你的專案上，搭配 rails、devise](//images.ctfassets.net/8er52l3j5u76/1TmokX1MGArshGx79l3Iaw/62709fd8275852c25d7f56590f465096/recaptcha_setup_failure-f95be0e2.jpg)

---

## 實作 reCAPTCHA v3 在登入頁面

#### 1. 註冊 recaptcha 並選擇 v3，加到 `.env.local`

```ruby
RECAPTCHA_V2_CHECKBOX_SITE_KEY="your_site_key......."
RECAPTCHA_V2_CHECKBOX_SECRET_KEY="your_secret_key......"

RECAPTCHA_V3_SITE_KEY="your_v3_site_key......"
RECAPTCHA_V3_SECRET_KEY="your_v3_secret_key......"
```

#### 2. 修改 `routes.rb`，覆寫 `user/sessions` controller

```ruby
Rails.application.routes.draw do
  root 'todos#index'  
  resources :todos

  devise_for :users, controllers: {
    registrations: 'users/registrations',
    sessions: 'users/sessions',
  }
end
```

#### 3. user session controller 加入 before_action

修改 `app/controllers/users/sessions_controller.rb`。

分數為 `0.1` ~ `1.0` 之間，越低代表越可能是機器人，minimum_score 設為 `0.5`，表示低於 `0.5` 就會回傳 `false`。

```ruby
class Users::SessionsController < Devise::SessionsController

  before_action :check_recaptcha_v3, only: [:create]

  ......

  private

  def check_recaptcha_v3
    valid = verify_recaptcha(
      # action：當收到 recaptcha token 的時候要認哪一個名稱來做驗證
      #         與前端 form 表單呼應
      action: 'login',
      minimum_score: 0.5,
      secret_key: ENV["RECAPTCHA_V3_SECRET_KEY"],
    )

    if not valid
      redirect_to new_user_registration_path
    end
  end
end
```

#### 4. 加入 `recaptcha_v3` 到 login form

修改 `app/views/devise/sessions/new.html.erb` 22 行，
在 submit 前面加上 `recaptcha_v3`，`action` 必須跟 controller 驗證端命名一致。

```ruby
  ......

  <div class="form-group">
    <%= recaptcha_v3 action: 'login', site_key: ENV["RECAPTCHA_V3_SITE_KEY"] %>
  </div>

  <div class="form-group">
    <%= f.submit  t('.sign_in'), class: 'btn btn-primary' %>
  </div>

  ......
```

成功的話可以看到出現在該頁右下角的位置。

![post-整合 reCAPTCHA 到你的專案上，搭配 rails、devise](//images.ctfassets.net/8er52l3j5u76/1mGqpPFTyO52r6zZFl7AHh/de94835987ae042d0dcf7c9c0d509546/v3_correct-01406d9d.jpg)

可以看到帶了一個 `g-recaptcha-response`，並有剛剛設置的 action 名稱。

![post-整合 reCAPTCHA 到你的專案上，搭配 rails、devise](//images.ctfassets.net/8er52l3j5u76/3OACySAYiC01yR4NWrkEyP/2f83408ca4f119c707378329c2030b77/post_session-e1bc4aa3.jpg)

如果失敗，打開 js console 查看錯誤訊息。

![post-整合 reCAPTCHA 到你的專案上，搭配 rails、devise](//images.ctfassets.net/8er52l3j5u76/139ZyC2s4QG9t9y5Gd88Te/3cc76e34bf8333794cfd5c8375f73fc1/v3_failure-157bfb92.jpg)

#### 5. 加入 v3 驗證失敗的 fallback 驗證

修改 `app/controllers/users/sessions_controller.rb`

```ruby
class Users::SessionsController < Devise::SessionsController
  before_action :check_recaptcha_v3, only: [:create]
  # before_action :configure_sign_in_params, only: [:create]

  # GET /resource/sign_in
  def new
    # 把參數 `verify_v2` 存起來留給 view 使用
    @verify_v2 = params[:verify_v2] === 'true'
    super
  end

  ......

  private

  def verify_recaptcha_tags
    # 用來驗證 v2 recaptcha_tags (secret_key 不一樣)
    verify_recaptcha secret_key: ENV["RECAPTCHA_V2_CHECKBOX_SECRET_KEY"]
  end 

  def check_recaptcha_v3
    v3_valid = verify_recaptcha(
      # action：當收到 recaptcha token 的時候要認哪一個名稱來做驗證
      #         與前端 form 表單呼應
      action: 'login',
      minimum_score: 0.5,
      secret_key: ENV["RECAPTCHA_V3_SECRET_KEY"],
    )
    v2_valid = verify_recaptcha_tags unless v3_valid

    if v3_valid || v2_valid
      # 如果驗證成功要額外做什麼事...
    else
      # 驗證失敗, 導到登入頁面並帶一個 verify_v2=true 的參數
      redirect_to new_user_session_path(verify_v2: true)
    end
  end
end
```

修改 `app/views/devise/sessions/new.html.erb`

```ruby
  ......

  <div class="form-group">
    <% if @verify_v2 %>
      <%= recaptcha_tags site_key: ENV["RECAPTCHA_V2_CHECKBOX_SITE_KEY"] %>
    <% else %>
      <%= recaptcha_v3 action: 'login', site_key: ENV["RECAPTCHA_V3_SITE_KEY"] %>
    <% end %>
  </div>

  <div class="form-group">
    <%= f.submit  t('.sign_in'), class: 'btn btn-primary' %>
  </div>

  ......
```

由於無法完全模擬出分數很低的情況，所以可以直接在登入網址加上 `?verify_v2=true`，來測試用 v2 checkbox 與用 v3 可不可以成功登入。

---

#### 模擬機器人瀏覽

打開 js console，將 `User agent` 改成 `Googlebot/2.1`，recaptcha 就會認為這是機器人瀏覽，使用此情況最好是在浮動 IP 的網路上會比較好，recaptcha v3 會記錄你的 ip verify 次數。

但是這也沒辦法完全測試剛剛完成的 fallback 驗證，因為在進行 v2 checkbox 的過程中，他會吐出無窮盡的圖片給你點選。

![post-整合 reCAPTCHA 到你的專案上，搭配 rails、devise](//images.ctfassets.net/8er52l3j5u76/4dQj98cTmc0elmtxi3UmA/b601149f72421d38501cb8110844db84/simulate_low_score-7f4dfadc.jpg)

---

參考：

[https://github.com/ambethia/recaptcha](https://github.com/ambethia/recaptcha)

[https://developers.google.com/recaptcha/intro?hl=zh-TW](https://developers.google.com/recaptcha/intro?hl=zh-TW)

[react 版本 recaptcha](https://github.com/appleboy/react-recaptcha)

[google recaptcha demo](https://recaptcha-demo.appspot.com/)

---

>  👩‍🏫  __課務小幫手：__
>  
> ✨ 想掌握 Ruby on Rails 觀念和原理嗎？
>
> 我們有開設 🏓 [Ruby on Rails 實戰課程](https://5xruby.tw/courses/ruby-on-rails) 課程唷 ❤️️
>


post-整合 reCAPTCHA 到你的專案上，搭配 rails、devise

整合 reCAPTCHA 到你的專案上，搭配 rails、devise

在這裡淺談幾項 PM 路途中會用上的技能，希望能帶給要邁向 PM 之路的你一點共鳴。

專案管理聽起來是個很陌生的名詞，但其實生活上很容易遇到，
人生也可以譬喻成一個放大版的專案管理，
首先列出目標優先順序，訂定每一個項目的細節，再來分配資源，一個一個完成目標，遇到困難時要解決掉，解決不掉的問題要去問有經驗的人，這樣一看，還真有 87% 相似。

此篇會提到下述幾個軟技能：

## 筆記的重要性

>釐清眼前的一片霧霾，把思緒整理清楚，列出要記下的重點。

### 隨手筆記
>沒有整理過的筆記，時間久了再回去看時，是不是常冒出：“我這行是寫了什麼?” 的想法呢?

我並非擁有程式技術相關背景入門，剛進來五倍時，理所當然的呈現了手忙腳亂的概念 (XD)
與同事同行跟客戶開會，整場會議下來，滿腦思緒充滿了陌生的名詞，
那時候我只想到一件事：先把這些單詞記下來再說！

就算不知道這些單詞的正確拼音，但還是硬著頭皮寫下來，把前後文也紀錄下來，會議結束後再丟去 Google 一下，相信大部分都可以找到解答，再把它們一一記起來，前後文也記錄下來，是因為若真的找不到解答，要去請教主管或同事時，他們起碼還抓得出來你指的意思是什麼。

感謝我在吸收詞彙的路上，團隊的主管跟同事都非常熱心替我解答疑惑，還會把意思轉換成凡人如我都聽得懂的比喻，漸漸聽久之後，會發現這些詞彙不像一開始那麼陌生，當然在此同時，也得付出相對的努力去學習相關知識，同時俱進，非技術背景，總是會比別人多出一些不足，需要付出更多努力去追上。

畢竟在不懂這些意思的狀況下要去跟 RD 還有客戶開會，連自己都搞不清楚狀況，絕對是行不通的。 (哭)

### Agenda

>能在會議中找出關鍵性事項來討論，避免冗長的開會時間中，重點卻沒有幾個。

另外一個要提到的是 Agenda (會議流程)：

會議開始前，會在準備的 Agenda 中，列出待討論的事項、議題的細節等，有時候也會代入這一週工程師的進度簡短概述，讓工程師跟客戶能夠同步雙方進度。

開會過程中也可以在 Agenda 的各個項目下方備註討論進度或結果，某方面來說也算是筆記的一種，方便自己會議後整理。

主要是可以在會議過程中，__讓開發團隊與客戶能彼此認知到此次討論的重點__，避免想到什麼才討論什麼，最後會議結束，才發現手中還有一堆問題遺漏了。

筆記其實不只在會議紀錄這種動作可以使用，
在五倍上 Git 跟網頁設計相關課程時，課後整理筆記可以讓我思考上課來不及吸收(偶爾發生)的內容，也具有**重複學習，加深記憶**的功能。

## 管理的技術，博大精深
>PM 不只是居中的協調者，還要跟團隊有默契、一起制訂出一套標準的工作流程。

我們常聽到的開發方式有成千上萬種，其中耳熟能詳的莫過於瀑布式開發、敏捷式開發...等。
我們來簡單提及一下最近很出名的敏捷式開發：

#### 敏捷式開發：
>敏捷式開發 好耳熟喔⋯⋯所以那是什麼 ?

敏捷式開發有許多方法，其中較為靈巧、好活用的 scrum，迷人的特色在於衝刺週期 (sprint) 與 Stand up meeting ，適用於小團隊(3-8人左右)，當然還有 story point、 team member role ⋯⋯等特色，這裡就不一一詳細介紹。

* Sprint：你可以將每週設為一段衝刺期，大家列出這週自己能夠"徹底完成"的事情。

* Daily Stand-up Meeting：每天固定時間的站立式會議，

  會議只有簡短的10-15分鐘的站立時間，可以快速讓團隊成員了解彼此的進度，以及需要協助的問題、今天要完成的待辦事項等。

  會議中只需要簡短快速報告以下三點：

  * 昨天做了什麼？

  * 今天預計要做什麼？

  * 進行中有遇到什麼障礙無法解決？

透過這樣的簡短會議，使團隊溝通飽和度上升，也可以讓自己整理一下腦內思緒，有時成員自己瓶頸很久的問題，另一位成員知道更快解決的方法，也可以透過站立會議提出跟建議，讓整體效率與進度更加提升。

---

## 說話的溝通技巧與藝術

>管事很難，管人更難。
當意見雪花般的飄來：應該成為一個整合大家意見的人，而非夾心餅乾。

當 PM 時，除了要站在客戶那邊去思考，也要站在 RD 這邊用客戶的思考去延伸，客戶有時候會不太確定自己需要的是什麼 "需求"，提出的反而是客戶自己想到的 "規格"，

那 PM 的功能就要發揮了，幫客戶釐清：是什麼原因想要提出這個規格？或是在什麼情況下需要這個功能？跟客戶手拉手心連心將需求條件詳細的列出來，畢竟直接丟給 RD 一坨定義很模糊的項目，他們也不知道從何下手。(登愣)

溝通除了確保表達出自己的想法外，也得確保他人是**能完全理解你想表達的意思**，有時候覺得自己講的已經夠清楚了，但對方可能還是不太理解你的概念，

溝通時要用“聽者的角度”去思考，甚至對方理解你的概念之後，也可能對你的看法提出異議，這時候就需要彼此討論、說服、妥協退讓來達成共識。

上述情況可套用在跟 RD 、客戶、抑或一般生活對話當中，掌握住技巧，可以確保團隊是依循著同一個概念向前進的 。

團隊氣氛與默契掌握得好，才能在彼此需要支援的時候幫上一把，有共同意識一起將專案以最高效率去完成。

## 管理工具會是你的小助手

PM 的生活當然不是一個人單幹，你會需要幾項工具輔助你掌握團隊時程、進度。

耳熟能詳的像是：Trello、Redmine、Asana ....等，有些是免費提供，有些若是要設定為非公開，則需另外付費，有優有缺，大家可以依團隊跟客戶偏好與方便性去篩選。
另外 RD 較常使用到管理程式碼的 GitHub、GitLab ，也需要去熟悉。

找尋適合團隊的管理工具是極為重要的，若未善用好，會使專案的不確定性與變動性增加，也會無法追蹤好項目與進度，所以說除了選擇合適管理工具，也必須在管理的過程當中確認細節，確認哪些項目是需要修改，以及調整整體的管理方式，讓專案能夠維持在理想的進度上。

---

PM 的技能欄要討論的還很廣泛，除了上述提到的軟技能：管理方法與技術、說話的藝術等，後面還有未提及的專業知識、商業知識與市場知識技能等等⋯⋯，尤其是硬技能中必須持續鞭策自己增進的專業知識，連我自己也在路途中持續學習，在每一次經驗中吸收、學習讓整體更有效率，畢竟全方位的 PM 才能夠在團隊中發揮最大成效。

PM 做的不只是專案管理，實際上更像溝通的橋樑，一個專案實際上藏了許多細節，而我們的任務就是去挖出更多細節，更要在團隊與客戶關係中找出平衡點，掌握每個人的進度與情緒脈動，做好溝通，保持好相同認知度，而這些技能，都要一點一滴的累積，儲存在你的技能欄內。

post-PM 的技能欄，你知道該點哪些嗎？

PM 的技能欄，你知道該點哪些嗎？


Elixir 這個名字，對女生朋友來說也許比較熟悉一些，因為它是一款知名化妝品廠商所推出的某一種[保養品的品牌](https://www.shiseido.com.tw/brand.aspx?b=2#/new)，但我並沒有接廠商的業配而且自己也沒在用保養品，所以今天也不是要介紹這款保養品。

我第一次認識 Elixir 這個單字，其實是因為當年玩 Final Fantasy 這款遊戲時候，遊戲裡有一款叫做「エリクサー」的道具，使用後會恢復全部的 HP 跟 MP，而這個「エリクサー」其實就是從 Elixir 這個英文字轉變來的日文外來語。

這篇文章要介紹的，是一款名為 Elixir 的電腦程式語言。本文的目的並不是要告訴你 Elixir 有多好多棒、效能有多好多棒（雖然是事實），而僅介紹一些我認為這個程式語言讓我覺得寫起來很開心的地方，特別是對一個喜歡 Ruby 的人來說。

首先，學習一門新的程式語言，先不說別的，外表看得順眼是很重要的。Elixir 這款程式語言的 Logo 是一顆紫色的水滴：

![Elixir Logo](https://kaochenlong.com/images/2017/elixir-logo.png)

好吧，我個人覺得 Logo 還不錯看（我的看法啦）。

Elixir 是一款函數型的程式語言，跟其它物件導向的程式語言比起來，Elixir 沒有類別、沒有物件、沒有所謂的實體方法、類別方法，只有一般平鋪直敘的函數（Function）。

什麼是函數？我們國、高中的數學都應該看過這樣的東西：

```
f(x) = 3x + 2
```

這個一元一次方程式，就是一個函數。函數通常會有輸入值也有輸出值，以上面這個為例，它的「輸入值」是 `x`，「輸出值」是 `3x + 2`。

在 Elixir，函數是一等公民，甚至可以把函數傳給另一個函數當做一般的參數。不過少了我們平常習慣的物件導向的觀念，一開始真的有點不習慣，會不知道該把程式寫在哪邊比較好。

Elixir 這個程式語言可以介紹的內容很多，應該不是我這一篇文章就可以聊完的，更多關於這個程式語言的細節，請各位移駕至 [Elixir 的官網](https://elixir-lang.org/)，在這邊就一些我個人覺得有趣、好玩的語法跟大家分享。

## 好玩的語法

### Pipe Operator

也許你曾看過這樣的程式碼：

```
func1(func2(func3(super_function(best_function("I love you")))))

```

先不管這個 `func1`、`func2` 或是 `super_function` 是在幹嘛，像這樣洋蔥式或大腸包小腸式一層包一層的寫法，雖然仔細看還是能知道意思，但可讀性上就稍微沒那麼好。如果改成多行，可以變這樣：
```
tmp1 = best_function("I love you")
tmp2 = super_function(tmp1)
tmp3 = func3(tmp2)
tmp4 = func2(tmp3)
tmp5 = func1(tmp4)
```
老實說這樣寫也沒好多少，特別如果又像我這樣故意用一堆之後用不上的 temp 變數。

Elixir 可以直接這樣寫：
```
"I love you"
|> best_function
|> super_function
|> func3
|> func2
|> func1
```
Elixir 的 `|>` 這個 Operator，意思就是「把前一個 function 執行的結果，當做第一個參數傳入下一個 function」，所以下面這段 Elixir 範例：
```
"ruby is awesome!"
|> String.split
|> Enum.map(fn(x) -> String.capitalize(x) end)
|> Enum.join(" ")

# 得到 "Ruby Is Awesome!"
```

它做了「把字串接開」→「把每個元素的首字改大寫」→「把各個元素組回字串」。其中中間 `Enum.map/2` 那段可以再改成這樣：
```
"ruby is awesome!"
|> String.split
|> Enum.map(&(String.capitalize/1))
|> Enum.join(" ")
```
像這樣可以把前一個 function 執行的結果，一路往下一個 function 接下去，可以讓每個 function 的「任務」分得很清楚，隨時可以再增加或刪除，個人覺得這樣超有趣的！

### Metaprogramming

習慣 Ruby 之後，程式語言有沒有直接支援 Metaprogramming 的功能對我來說就會變得很重要。Elixir 直接就有支援 Metaprogramming：

其實我不太確定 Metaprogramming 該怎麼翻成中文比較適當，不過請大家先看看這張截圖：

![elixir](https://kaochenlong.com/images/2017/elixir_made_by_elixir.png)

從帳面上的數字看起來，放在 GitHub 的 Elixir 程式語言專案，有 89.7% 的內容是用 Elixir 這個程式語言寫的。咦？有覺得哪裡怪怪的嗎？也就是說這個程式語言，有將近九成的組成都是 Elixir 這個程式語言本身。用自己寫自己，我覺得這超酷的！

在 Elixir 要使用 Metaprogramming 的技巧，主要都是使用 `macro` 搭配 `quote` 跟 `unquote` 來撰寫：

再從 Metaprogramming Elixir 書上借個例子：
```
    defmodule Math do
      defmacro say({:+, _, [lhs, rhs]}) do
        quote do
          IO.puts "#{unquote(lhs)} 加 #{unquote(rhs)} 等於 #{unquote(lhs + rhs)}"
        end
      end

      defmacro say({:*, _, [lhs, rhs]}) do
        quote do
          IO.puts "#{unquote(lhs)} 乘以 #{unquote(rhs)} 等於 #{unquote(lhs * rhs)}"
        end
      end
    end
```
先不管其實這程式看起來怎麼樣（好啦，其實有點不太容易懂），但用起來的樣子像這樣：
```
$ iex math.exs
Erlang/OTP 20 [erts-9.1.2] [source] [64-bit] [smp:4:4] [ds:4:4:10] [async-threads:10] [hipe] [kernel-poll:false] [dtrace]
Interactive Elixir (1.5.2) - press Ctrl+C to exit (type h() ENTER for help)
iex(1)> require Math
Math
iex(2)> Math.say 1 + 2
1 加 2 等於 3
:ok
iex(3)> Math.say 2 * 3
2 乘以 3 等於 6
:ok
```
發生什麼事了？ 我先把 `1 + 2` 透過 `quote` 拆解成這樣：
```
iex(1)> quote do: 1 + 2
{:+, [context: Elixir, import: Kernel], [1, 2]}
```
這等於是直接在操作 AST（Abstract Syntax Tree）了，這超酷的。可以做到這種層級的操作，我想大概什麼功能都能寫得出來了。

其實在 Macro 在 Elixir 的應用非常廣，甚至後來有次無聊去翻 Elixir 的原始碼才發現，原來在 Elixir 裡，連 `if...else` 跟 `unless` 之類看起來像關鍵字的語法，就是用 Macro 的方式寫出來的：
```
    # 檔案位置：lib/elixir/lib/kernel.ex
    defmacro if(condition, clauses) do
      build_if(condition, clauses)
    end

    defp build_if(condition, do: do_clause) do
      build_if(condition, do: do_clause, else: nil)
    end

    defp build_if(condition, do: do_clause, else: else_clause) do
      optimize_boolean(
        quote do
          case unquote(condition) do
            x when x in [false, nil] -> unquote(else_clause)
            _ -> unquote(do_clause)
          end
        end
      )
    end

    defp build_if(_condition, _arguments) do
      raise ArgumentError,
            "invalid or duplicate keys for if, only \"do\" and an optional \"else\" are permitted"
    end
```
如果你仔細看上面這段原始碼，就會發現在 Elixir 的 `if ... else` 其實就是 `case ... when` 而已，這真的太有趣了 :)

對 Macro 有興趣的話，可以再參考官網上的[文件](https://elixir-lang.org/getting-started/meta/macros.html)。

### 其它我覺得有趣的...

#### 可以省略小括號

這對別的程式語言的人來說可能沒什麼感覺，但對寫習慣 Ruby 的人來卻是一大福音。

#### 有 REPL 可以用

REPL 是「Read-Eval-Print Loop」幾個字的縮寫，許多程式語言都有提供這樣的工具，以 Ruby 來說是 `irb`，而在 Elixir 則是 `iex`。在終端機環境下輸入 `iex` 指令後會進入互動式的環境，可以在這裡試驗或練習程式語法：

![iex](https://kaochenlong.com/images/2017/iex.png)

#### 跟 Ruby 的語法有像

這對已經習慣 Ruby 語法的人來說算是福音，但別誤會，即使從 Ruby 轉換到 Elixir 也不會是完全無痛，畢竟 Elixir 是一款函數式的程式語言，沒有物件導向的那些類別、物件的東西，這點需要花一點時間習慣。

## 小結
### 學 Elixir 可以幹嘛

學這個可以幹嘛喔？想幹嘛就幹嘛，學習本來就不需要為公司、不需要為長官、同事、不需要為別人，只為你自己，你自己覺得有趣最重要！

話是這樣說沒錯，但實際一點，你爸媽可能還是會想問你學這東西要幹嘛？學這個找得到工作嗎？

如果想要開發網站應用程式，有 [Phoenix](https://phoenixframework.org/) 這款 Web 開發框架可以用，Phoenix 較早版本跟 Ruby on Rails 有 87% 像，對現有的 Rails Developer 來說還算是滿友善的（但改版後長得有點不太一樣了）；另外想玩硬體，也有 [Nerves](https://nerves-project.org/) 可以研究一下。

### 聚會

目前 Elixir 在全世界的人口數還不算多，就我觀察，在台灣應該就只有一小群人在用。不過每個月都有[聚會](https://www.meetup.com/Taipei-Elixir-Erlang-Meetup-Group/)，目前也有自己專屬的 [Facebook 粉絲專頁](https://www.facebook.com/groups/elixir.tw/)。

![AD](https://kaochenlong.com/images/2017/elixir_ad.jpg)
圖片來源：[Shiseido 官網](https://www.shiseido.com.tw/)

借用該知名保養品品牌的宣傳台詞「遇見『水玉光』，遇見更好的自己」，小改一下變成：

> 遇見 Elixir，遇見更好的自己！

### 研討會

雖然在台灣的使用人口還不算多，但我們明年在辦 RubyConf Taiwan 的時候，會把 Elixir 也正式的納入議程（就說 Ruby 跟 Elixir 是好朋友了）

反正在國外的 RubyConf 也越來越多的 Elixir 議程，即然這樣，我們就光明正大把辦在一起吧！

![RubyElixirConf Taiwan](https://kaochenlong.com/images/2017/ruby-elixir-conf.png)

除了 Ruby 程式語言的老爸[松本行弘](https://twitter.com/yukihiro_matz)之外，也邀請到了 Elixir 的老爸 [José Valim](https://twitter.com/josevalim) 來擔任主題演講。

咦？說到底這篇竟然是 [Ruby X Elixir Conf](https://2018.rubyconf.tw/) 的業配文啊，可...可惡！

你看過 Elixir 嗎？如果沒有，現在讓你看看！

這是綠界的電子發票介接技術文件：[綠界科技股份有限公司 電子發票介接技術文件](https://www.ecpay.com.tw/Content/files/ecpay_004.pdf)

根據這份文件，我們可以做的事情有蠻多的，本文只介紹最最基本的功能：

- 開立發票
- 查詢發票明細

本文將會從建立一個新的 Rails App 開始，最後實作開發票和查詢發票明細的功能。

## 建立一個 Rails App

在 console 輸入以下指令：

```bash
rails new ecpay_invoice_demo
cd ecpay_invoice_demo
```

## 新增一個開發票的 service

在專案資料夾中的 `app/services/ecpay/invoice` 資料夾下，新增 `create_service.rb`，此時你應該會發現 app 資料夾下不存在 services 資料夾，你要自己新增資料夾。

在 `create_service.rb` 中加入以下程式碼：

```ruby
module Ecpay
  module Invoice
    class CreateService
      def initialize(params = {})
      end

      def run
        'yo'
      end
    end
  end
end
```

接著在 Rails console 下測試看看

```ruby
> Ecpay::Invoice::CreateService.new.run
# => "yo"
```

看到 yo 代表你做對了。

## 串接綠界API

在這裡我會直接使用綠界提供的測試環境做展示，所以不會實作切換環境的程式碼，以下是綠界的測試環境：

相關連結：

- 開立發票的API網址：[https://einvoice-stage.ecpay.com.tw/Invoice/Issue](https://einvoice-stage.ecpay.com.tw/Invoice/Issue)
- 綠界測試環境後台登入頁：[https://vendor-stage.ecpay.com.tw/Home/Index](https://vendor-stage.ecpay.com.tw/Home/Index)
- 綠界測試環境電子發票後台：[https://vendor-stage.ecpay.com.tw/Einvoice/Index](https://vendor-stage.ecpay.com.tw/Einvoice/Index)

綠界測試環境後台帳密

- 帳號：StageTest
- 密碼：test1234

API 串接參數

- MerchantID：2000132
- HashKey：ejCk326UnaZWKisg
- HashIV：q9jcZX8Ib9LM8wYk

我們只需要把正確的參數傳進正確的網址，就可以成功開立發票了，現在來修改一下我們的 service code：

```ruby
module Ecpay
  module Invoice
    class CreateService
      def initialize(params = {})
        @params = params
      end

      def run
        create(sample_params)
      end

      private

      def url
        'https://einvoice-stage.ecpay.com.tw/Invoice/Issue'
      end

      def sample_params
        {}
      end

      def create(params)
        uri = URI(url)
        # 送出 Post request 到綠界，並取得回應內容
        response = Net::HTTP.post_form(uri, params)
        response.body.force_encoding('UTF-8')
      end
    end
  end
end
```

目前的程式碼可以幫我們把 sample_params 傳到綠界，並且獲得回應內容。只要我們再將 sample_params 填入，整個開發票的功能就完成了。現在讓我們回到 Rails console 測試一下目前的程式跑起來是怎樣的結果：

```ruby
> Ecpay::Invoice::CreateService.new.run
 => "無效的MerchantID「商品編號為空白」"
```

我們成功獲得了來自綠界測試環境的錯誤訊息。

## 填入開發票的參數

修改開發票的參數 sample_params 如下：

```ruby
def sample_params
  # 基本參數
  {
    'TimeStamp' => Time.current.to_i.to_s,
    'MerchantID' => '2000132',
    'RelateNumber' => SecureRandom.hex(10), # 訂單編號
    'CustomerEmail' => 'service@5xruby.tw', # 客戶信箱
    'TaxType' => '1', # 課稅類別
    'InvType' => '07', # 字軌類別

  # 商品參數
    'SalesAmount' => 1900, #總金額
    'ItemCount' => '3|2', #商品數量
    'ItemPrice' => '300|500', #商品單價
    'ItemAmount' => '900|1000', #商品小計
    'ItemName' => '衣服|褲子', #商品名稱
    'ItemWord' => '件|件', #商品單位

  # 發票參數
    'Print' => '0', # 要列印嗎？ 0代表不要 1代表要
    'Donation' => '1', # 要捐嗎？ 0代表不要 1代表要
    'LoveCode' => '168001', # 要捐給誰，一個7字元的愛心碼
  }
end
```

試用一下

```ruby
> Ecpay::Invoice::CreateService.new.run
 => "InvoiceDate=&InvoiceNumber=&RandomNumber=&RtnCode=10200090&RtnMsg=CheckMacValue is null.&CheckMacValue=2F3E82F5A5C582BB0E1E5E34EE749F1A"
```
他傳回了一個 query string 來告訴我們發生了什麼事情，我們要關注的地方是 `RtnMsg`。這裡我特寫一下：

```ruby
RtnMsg=CheckMacValue is null.
```
## 計算 CheckMacValue

綠界的回應是說我們沒有傳遞 CheckMacValue 給綠界， CheckMacValue 的功能是用來確認雙方身分用的。我們會把我們要傳遞的參數加入綠界給我們的 HashKey 跟 HashIV，然後進行一個 hash 運算，就可以獲得 CheckMacValue 了。

CheckMacValue 的詳細計算流程如下：
- 將傳遞參數依照第一個英文字母，由 A 到 Z 的順序來排序(遇到第一個英名字母相同時，以第二個英名字母來比較，以此類推)，並且以&方式將所有參數串連。
- 參數最前面加上 HashKey、最後面加上 HashIV
- 將整串字串進行 URL encode
- 轉為小寫
- 使用 MD5 產生雜凑值
- 再轉大寫

由於綠界的 API Server 是用 ASP.NET 實作的，所以我們的 URL encode 的結果必須跟 ASP.NET 上的 URL encode 相同。不同的語言實作的 URL encode 的結果可能會有些微差異，所以我們需要針對這一點特別處理。

全部實作完之後的程式碼如下：
```ruby
require 'net/http'

module Ecpay
  module Invoice
    class CreateService
      def initialize(params = {})
        @params = params
      end

      def run
        create(sample_params)
      end

      private

      def url
        'https://einvoice-stage.ecpay.com.tw/Invoice/Issue'
      end

      def sample_params
        # 基本參數
        {
          'TimeStamp' => Time.current.to_i.to_s,
          'MerchantID' => '2000132',
          'RelateNumber' => SecureRandom.hex(10), # 訂單編號
          'CustomerEmail' => 'service@5xruby.tw', # 客戶信箱
          'TaxType' => '1', # 課稅類別
          'InvType' => '07', # 字軌類別

        # 商品參數
          'SalesAmount' => 1900, #總金額
          'ItemCount' => '3|2', #商品數量
          'ItemPrice' => '300|500', #商品單價
          'ItemAmount' => '900|1000', #商品小計
          'ItemName' => '衣服|褲子', #商品名稱
          'ItemWord' => '件|件', #商品單位

        # 發票參數
          'Print' => '0', # 要列印嗎？ 0代表不要 1代表要
          'Donation' => '1', # 要捐嗎？ 0代表不要 1代表要
          'LoveCode' => '168001', # 要捐給誰，一個7字元的愛心碼
        }
      end

      def create(params)
        params['CheckMacValue'] = compute_check_mac_value(params)
        uri = URI(url)
        # 送出 Post request 到綠界，並取得回應內容
        response = Net::HTTP.post_form(uri, params)
        response.body.force_encoding('UTF-8')
      end

      def compute_check_mac_value(params)
        # 先將參數備份
        params = params.dup

        # 某些參數需要先進行 url encode
        %w[CustomerName CustomerAddr CustomerEmail].each do |key|
          next if params[key].nil?
          params[key] = urlencode_dot_net(params[key])
        end

        # 某些參數不需要參與 CheckMacValue 的計算
        exclude_keys = %w[InvoiceRemark ItemName ItemWord ItemRemark]
        params = params.reject do |k, _v|
          exclude_keys.include? k
        end

        # 轉成 query_string
        query_string = to_query_string(params)
        # 加上 HashKey 和 HashIV
        query_string = "HashKey=ejCk326UnaZWKisg&#{query_string}&HashIV=q9jcZX8Ib9LM8wYk"
        # 進行 url encode
        raw = urlencode_dot_net(query_string)
        # 套用 MD5 後轉大寫
        Digest::MD5.hexdigest(raw).upcase
      end

      def urlencode_dot_net(raw_data)
        # url encode 後轉小寫
        encoded_data = CGI.escape(raw_data).downcase
        # 調整成跟 ASP.NET 一樣的結果
        encoded_data.gsub!('%21', '!')
        encoded_data.gsub!('%2a', '*')
        encoded_data.gsub!('%28', '(')
        encoded_data.gsub!('%29', ')')
        encoded_data
      end

      def to_query_string(params)
        # 對小寫的 key 排序
        params = params.sort_by do |key, _val|
          key.downcase
        end

        # 組成 query_string
        params = params.map do |key, val|
          "#{key}=#{val}"
        end
        params.join('&')
      end

    end
  end
end
```

試試看結果如何：

```ruby
> Ecpay::Invoice::CreateService.new.run
 => "InvoiceDate=2018-07-19 14:35:02&InvoiceNumber=FX30000137&RandomNumber=8833&RtnCode=1&RtnMsg=開立發票成功&CheckMacValue=D2AEB7BDE6F9ADA94831233A4D0FB2BC"
```

節錄重點：

```ruby
RtnMsg=開立發票成功
InvoiceNumber=FX30000137
```

發票開立成功了！而且我們獲得了發票號碼。

## 發票參數簡介

我把發票參數分為三類：

- 基本參數
- 商品參數
- 發票參數

### 基本參數
- TimeStamp：你的系統的目前時間，綠界會用來做 timeout 檢查
- MerchantID：商店代號，這是綠界發給你的參數
- RelateNumber：在你的電商系統上的訂單編號
- CustomerEmail：買家的mail，如果發票開立成功或中獎，這個信箱有可能會收到信
- TaxType：課稅類別，填 1 代表應稅，填 2 代表零稅率，填 3 代表免稅
- InvType：發票字軌類型，填 07 代表一般稅額， 填 08 代表特種稅額

### 商品參數
- SalesAmount：發票總金額
- ItemCount：商品數量，以 | 做為分隔符號
- ItemPrice：商品單價，以 | 做為分隔符號
- ItemAmount：商品小計，以 | 做為分隔符號
- ItemName：商品名稱，以 | 做為分隔符號
- ItemWord：商品單位，以 | 做為分隔符號

綠界會檢查商品小計的加總必須等於發票總金額

### 發票參數

#### 我要捐發票
如果你這張發票是要捐的，需要傳遞以下參數：

- Print：要列印這張發票嗎？填 0 代表不要，填 1 代表要
- Donation => 要捐嗎？填 0 代表不要，填 1 代表要
- LoveCode => 要捐給誰？填入愛心碼

其中 Print 傳 0，Donation 傳 1。

#### 我要印發票
如果你這張發票是要印的，需要傳遞以下參數：

- Print：1
- Donation：0
- CustomerName：客戶名稱
- CustomerAddr：客戶地址
- CustomerIdentifier：統一編號，此欄位為選填欄位

也就是說，如果你要印，就不能捐。如果你要打統編，就一定要印。即使你必須將客戶名稱跟地址傳給綠界，綠界還是不會幫你印發票寄給客戶。

所以當客戶選擇要印發票時，管理人員則必須要回到綠界電子發票後台去操作列印。

綠界電子發票列印頁網址：[https://vendor-stage.ecpay.com.tw/Einvoice/InvoicePrint](https://vendor-stage.ecpay.com.tw/Einvoice/InvoicePrint)

#### 我要存發票
如果你不捐，也不印，那麼你要找一個載具來儲存這張電子發票，載具相關參數如下：

- Print：0
- Donation：0
- CarruerType：載具類別，值可能為 1、2、3 其中之一
- CarruerNum：載具編碼

其中 CarruerType 的值的意義如下：

- 1：綠界科技電子發票載具
- 2：自然人憑證號碼
- 3：手機條碼

CarruerNum 的值會在 CarruerType 的值不同而改變其意義，特別的是當 CarruerType 為 1 時，CarruerNum 必須傳遞空字串。

## 微調程式碼

剛剛我們是使用測試資料來開發票，但真正要使用的時候，params 應該是要由外部傳入。

需要修改程式碼如下：

```ruby
def run
  create(@params)
end
```

再 parse 一下輸出：

```ruby
def create(params)
  params['CheckMacValue'] = compute_check_mac_value(params)
  uri = URI(url)
  # 送出 Post request 到綠界，並取得回應內容
  response = Net::HTTP.post_form(uri, params)
  body = response.body.force_encoding('UTF-8')
  CGI.parse(body).transform_values(&:first)
end
```

測試一下效果

```ruby
params = Ecpay::Invoice::CreateService.new.send(:sample_params)
Ecpay::Invoice::CreateService.new(params).run
 => {"InvoiceDate"=>"2018-07-19 17:11:18", "InvoiceNumber"=>"FX30000163", "RandomNumber"=>"5453", "RtnCode"=>"1", "RtnMsg"=>"開立發票成功", "CheckMacValue"=>"848B5BAF997E316617967BFC09079BA6"}
```

順利～
補充說明：在這邊我使用 `Ecpay::Invoice::CreateService.new.send(:sample_params)`，而不是寫 `Ecpay::Invoice::CreateService.new.sample_params` 是因為 `sample_params` 是 private 方法，不能直接從外部呼叫。

## 查詢發票明細

一樣，我們建立一個 Ecpay::Invoice::FindService，以下就直接來：

```ruby
require 'net/http'

module Ecpay
  module Invoice
    class FindService
      def initialize(relate_number)
        @relate_number = relate_number
      end

      def run
        find(build_params)
      end

      private

      def url
        'https://einvoice-stage.ecpay.com.tw/Query/Issue'
      end

      def build_params
        {
          'TimeStamp' => Time.current.to_i.to_s,
          'MerchantID' => '2000132',
          'RelateNumber' => @relate_number, # 訂單編號
        }
      end

      def find(params)
        params['CheckMacValue'] = compute_check_mac_value(params)
        uri = URI(url)
        # 送出 Post request 到綠界，並取得回應內容
        response = Net::HTTP.post_form(uri, params)
        body = response.body.force_encoding('UTF-8')
        CGI.parse(body).transform_values(&:first)
      end

      ...下略 compute_check_mac_value

    end
  end
end
```

其實只是修改網址跟換一下參數，查詢發票明細就完成了。現在讓我們來測試一下，測試流程如下：
- 產生測試參數
- 從參數中擷取出訂單編號 relate_number
- 使用參數開立一張發票
- 使用訂單編號做查詢

```ruby
params = Ecpay::Invoice::CreateService.new.send(:sample_params)
relate_number = params["RelateNumber"]
Ecpay::Invoice::CreateService.new(params).run
Ecpay::Invoice::FindService.new(relate_number).run
 => {"IIS_Award_Flag"=>"", "IIS_Award_Type"=>"", "IIS_Carruer_Num"=>"", "IIS_Carruer_Type"=>"", "IIS_Category"=>"B2C", "IIS_Check_Number"=>"", "IIS_Clearance_Mark"=>"", "IIS_Create_Date"=>"2018-07-19 17:14:46", "IIS_Customer_Addr"=>"", "IIS_Customer_Email"=>"service@5xruby.tw", "IIS_Customer_ID"=>"", "IIS_Customer_Name"=>"", "IIS_Customer_Phone"=>"", "IIS_Identifier"=>"0000000000", "IIS_Invalid_Status"=>"0", "IIS_IP"=>"118.163.124.163", "IIS_Issue_Status"=>"1", "IIS_Love_Code"=>"168001", "IIS_Mer_ID"=>"2000132", "IIS_Number"=>"FX30000167", "IIS_Print_Flag"=>"0", "IIS_Random_Number"=>"9234", "IIS_Relate_Number"=>"f633510627a2eddeea0c", "IIS_Remain_Allowance_Amt"=>"", "IIS_Sales_Amount"=>"1900", "IIS_Tax_Amount"=>"0", "IIS_Tax_Rate"=>"0.050", "IIS_Tax_Type"=>"1", "IIS_Turnkey_Status"=>"", "IIS_Type"=>"07", "IIS_Upload_Date"=>"", "IIS_Upload_Status"=>"0", "InvoiceRemark"=>"", "ItemAmount"=>"900|1000", "ItemCount"=>"3|2", "ItemName"=>"衣服|褲子", "ItemPrice"=>"300|500", "ItemRemark"=>"", "ItemTaxType"=>"", "ItemWord"=>"件|件", "PosBarCode"=>"10708FX300001679234", "QRCode_Left"=>"FX3000016710707199234000000000000076c0000000053538851KIjD/jYtIwQXOONltIuFzA==:**********:2:2:1:", "QRCode_Right"=>"**衣服:3:300:褲子:2:500","RtnCode"=>"1", "RtnMsg"=>"查詢發票成功", "CheckMacValue"=>"20F155F2A8CDB994B4EB7B949D98FD9E"}
```

查詢發票成功！值得一提的是發票號碼的 key 變成 `IIS_Number` 了呢～由於篇幅的關係，今天就講到這裡。

因為本次的教學其實根本沒講到 Rails，所以你們要自己實作自己的 Controller 和 Model，並且傳遞正確的參數進入 Service。記得如果想要使用正式環境，就要修改Url、HashKey、HashIV 那些東西哦～重構什麼的自己來齁～

對了，在綠界的測試環境裏只能使用綠界的測試帳號，所以你無法使用你自己註冊的綠界帳號去打綠界的測試環境。你問我「其實綠界有提供 SDK，為什麼你不用？」嗯... 這個不好說阿，但這是一個很棒的問題。

還有，我把程式碼都放在 [github](https://github.com/etrex/ecpay_invoice_demo) 上了，想要的話就拿去吧。

---

>  👩‍🏫  __課務小幫手：__
>  
> ✨ 想掌握 Ruby on Rails 觀念和原理嗎？
>
> 我們有開設 🏓 [Ruby on Rails 實戰課程](https://5xruby.tw/courses/ruby-on-rails) 課程唷 ❤️️
>

post-Rails 串接 Ecpay 電子發票，就是這麼簡單/cover

Rails 串接 Ecpay 電子發票，就是這麼簡單


大家好，一年（其實是 16 個月）一度的 [RubyConf Taiwan 2019](https://2019.rubyconf.tw) 即將在兩個月後的 7.26 - 27 日於張榮發國際會議中心召開，作為活動的主辦人與議程委員，在此想跟大家介紹一下本次大會的主題。

### Keynote：

今年一共有 4 場 Keynote，講者分別是

1. Matz (@yukihiro_matz)：未定
1. Aaron Patterson (@tenderlove)：The View Is Clear from Here

	繼 2015 再次來台的 @tenderlove 這次預定發表的是和 Rails view engine 相關的題目，當我們在下 `render` 的時候，究竟 Rails 是怎樣生成最終的 html，這中間到底經過了哪些步驟，以及歷代 Rails 中又進行了哪些優化，這些都是在我們寫 Rails 進行效能優化調整來說非常需要了解的知識，也讓我想到前年 Taipei.rb 羅泓武發表的「[從原始碼了解 Rails template rendering](https://www.facebook.com/ruby.taiwan/videos/10155077911778937/)」這個主題。

1. c9s (@c9s)：Virtual Machines: their common parts and what makes them special

	終於讓我邀請到 c9s 了（感動），其實 RubyConf Taiwan 一直以來都有請其他語言的強者大大交流的慣例，這次 c9s 將為我們帶來對近年流行的腳本語言之間設計的差異的主題，也可以參考他之前在 FB 上的 [PO 文](https://www.facebook.com/photo.php?fbid=10156401137051715&set=a.120173376714&type=3&theater)。

1. Samuel Williams (@ioquatix)：The Journey to One Million

	可能對國內 Rubyist 來講不太廣為人知的 Samuel 除了是 Ruby Committer ，也是新一代 non-block I/O 庫 [async](https://rubygems.org/gems/async) 以及在此之上建立的新 Web Application Server [falcon](https://rubygems.org/gems/falcon) 的作者，預計他將會在 Keynote 中演講 Fiber 的運用方式以及展示如何用 Falcon 達成 100k 同時 Websocket 連線的紀錄，大家也可以先看一下他在 RubyKaigi 的議程 [slide](https://www.codeotaku.com/journal/2018-11/fibers-are-the-right-solution/index) 了解一下。

### 一般議程：

今年從將近 70 份的投稿中選出了 20 份的一般議程，以下是基於個人理解（與偏見）對各議程主題的介紹。

1.	蒼時弦也：從 Enumerator 看 Ruby 的迭代器

	講者從原始碼開始一步步了解我們在 Ruby 每天使用的 `each` 方法並試圖用 Ruby 實作出來，像這樣的理解過程除了增進對 Ruby 的理解外，也可以應用在我們日常的開發上，像是什麼場合要對 ActiveRecord 物件集合（collection）進行一般陣列操作，怎樣的方式可以減少 N+1 查詢等，當我們比較了解背後實作方式的時候，就能在不同場合下做出相對較優的判斷，所以這就是我們需要理解實作方式的理由，也是這個主題的價值。

1.	Joel Hawksley：Rethinking the View Layer with Components

	講者是 GitHubber，主題是講者在改善 GitHub 本體的過程中，發現 Rails 的 view 功能雖然好用而且功能強大，不過同時也造成了測試不好寫、跑的慢（因為只能整合測試）以及幾乎無法有 Test Coverage 等問題；在無法將架構改成 React 或 Vue.js 等前後端分離的前提下，借鏡 React 的 component 概念將之實作在 Rails 的 ActionView 上的過程，同時這個實作也已經應用在部份 GitHub 的功能上。

1.	Jenna Blumenthal：Event Sourcing for Everyone

	這個主題是在講述作者從零開始建立一組名為「Event Sourcing」的 Service Object 機制來將改變物件狀態 = 資料內容的變化，以及追蹤資料變動的紀錄，甚至可以從紀錄還原資料操作等；在近年 Ruby 圈的開發模式逐漸傾向 Service Object 的趨勢下，這個主題適合想要學習建立 Service Object 思維模式的開發者參考。

1.	Kuniaki Igarashi：Road to white mages

	延續上一次講者在 RubyConf Taiwan 2015 的[演講](https://www.youtube.com/watch?v=VVain__fKm8&list=PLhKZ4RWngmpDVKgAH_p_X7gtLSGsvmMJj&index=8)，這次將主題放在如何用 Ruby 內建的功能 TracePoint 或是外部工具 DTrace 等去搜尋「這個 method 是哪裡來的」之類的問題進而幫助我們開發與 debug。

1.	Shinsuke Imai：Reliable distribution system with Ruby x IoT

	講者是日本知名線上食譜社群 Cookpad 的工程師，講題是由講者在 Cookpad 建立讓消費者向小農直接購買食材並集運到指定據點的服務[Cookpad-Mart](https://cookpad-mart.com/) 時，為了解決「使用者從網路上下單，在食材生產者端列印購物清單」需求而建立了一組讓小農端可以隨時自動列印購買清單的器材組，其中包括熱感應印表機、Raspberry Pi 以及無線路由器等，並使用 CRuby 建立了可以自動列印、控管分佈在不同小農家的這些服務組件的程式，和敝司自產的開源 IOT Framework -- [Tamashii](https://tamashii.io/) 有異曲同工之妙；雖然講者也曾在其它場合[分享](https://speakerdeck.com/shinsuke_imai/reliable-label-printer-system?slide=17)過相關主題，不過這次將會是第一次從技術面出發的分享。

1.	Yuji Yokoo：Developing Dreamcast games with mruby

	主題是在研究如何 hack 20 多年前發售的 Dreamcase（DC）主機上用 mruby 寫出可以執行的遊戲，過程包括建構針對 DC 主機的 CPU cross-compiling 環境、從模擬器到用 serial cable 傳輸程式到主機等等的過程；身為一位懷舊電玩愛好者對這個主題不可能不興奮，講者也釋出了這部[影片](https://vimeo.com/335686570)展示在 DC 上給大家參考。

1.	Vipul A M：What's new in Rails 6?

	由於正逢 Rails 6 發佈，因此有一個個這樣的主題也是非常合理的，講者本人也是第 27 名的 Rails Contributor 與 Committer。

1.	The future of library dependency management of Ruby：Shibata Hiroshi

	在 Ruby 2.6 中，Ruby Core Team 正式的把 Bundler 合併到 CRuby repo，作者是主導這一過程的 Ruby Committer，同時近期在 Bundler 1 -> 2 的過程中因為相容性問題導致許多人（包括我）遇到一些困擾，例如 Gemfile 突然「被升級」之類的狀況，講者將在此次講題中說明這些事件的原因、如何應對以及相關的未來計劃等等。

1.	Delton Ding：Protect Your Copyrighted Ruby Code in Distribution

	我們都知道 Ruby 是一個直譯型語言（Interpreted Language）並且具有像 meta-programing 之類執行期動態加載的相關功能，因此無法像編譯型語言可以用二進位執行檔方式散佈執行程式，作者試圖找出一套能讓 Ruby 程式在某些前提下可以安全地散佈的方案。

1.	Bernie Chiu：Let's Scale Ruby Applications with Love

	作者分享在 Shopline 時調整效能達成部份 API Endpoint 有一倍以上效能提升的過程，對於 Rails 效能調整有興趣者必看！

1.	Matias Korhonen：Ruby like it's 1995

	這其實是個相對偏趣味性的題目，作者嘗試用現在的硬體來編譯 1995 年誕生的 CRuby 0.95。

1.	Charles Oliver Nutter：Scalable Applications with JRuby

	講者是 2014 的 Keynote，實質的 JRuby 之父，今年以一般講者的身份登台，在台灣雖然使用 JRuby 的人應該不會很多，不過以個人經驗來說 JRuby 其實是效能非常好，可以突破 GVL 限制又可以使用幾乎所有 Java Lib 的好東西（除了啟動速度以外），講者將講解近年 JRuby 在效能面與相容面的改善，以及未來計劃等。

1.	Wen-Chuan Lin：開拓者們建立鐵道的辛酸血淚史 Building Rails with Trailblazer, The Good, Bad and Ugly. 

	雖然大家幾乎已經把 Ruby 和 Rails 綁在一起，但其實 Trailblazer 也是近年非 Rails Web Framework 裡的後起之秀，講者所在的公司也是極少數在真實產品環境中應用 Trailblazer 的例子，相信這場分享能為大家帶來新的啟發。

1.	John Lin：Automatic Differentiation for Ruby

	這是一個數學與 AI 的題目，也是講者在 RubyKaigi 的 [LT](https://youtu.be/B2NTL_J62JE?t=670) 的延伸。

1.	Soutaro Matsumoto：Ruby with types

	近期 Ruby 圈最重要的新聞莫過於就是即將在 Ruby 3 登場的 type checker 功能，講者作為主導此一計劃的 CRuby Committer，將為大家帶來此一計劃的進程以及 3 大 type checker 實作的解說。

1.	Samuel Giddins：Making CocoaPods Fast(er) with Modern Ruby Tooling

	有在寫 iOS 的人應該都有在使用 CocoaPods 這個等同 Bundler 之於 Ruby 的工具，作者作為 CocoaPods 的 Lead Developer 將在這次演講中分享 CocoaPods 團隊在近年讓 CocoaPods 安裝單一套件的處理時間從 3 分鐘變成 90 秒的改善過程。

1.	Tse-Ching Ho：Suit up for frontend and backend development

	敝司的與專案開發的客人洽談時，常常會聽到「Rails 不適合前後端分離架構」的說法，但事實上我們已經有數個成功使用前後端分離的專案了；講者澤清為敝司長年的盟軍與戰友，具備非常充份的 Rails 前後端分離的實戰經驗，內容會偏重在如何建立一個可立即運用在日常開發工作上的 Rails 前後端分離的專案架構，對於這方面有興趣的人務必要來聽聽看。

1.	Li-Fong Lin：Running and observing Rails application on GKE

	講者為國內最大 GCP 代理商 iKala 的 Engineering VP，iKala = LiveHouse 具有多年直播平台維運開發經驗，這次分享將帶來如何在 GCP 與 GKE 平台上用最適合的方式建立 Rails App 用的 Docker Image、k8s 設定與使用 GCP 的 Profiling 功能調校效能等實戰經驗，對 GCP 有興趣或正在使用的朋友不可錯過。

1.	Luka Huang：Using AWS Lambda with Ruby on a large-scale system

	自從 AWS 在去年底宣佈 Lambda 支援 Ruby 之後，可說是為 Rubyist 們開啟了一個新世界，講者基於把上線產品加入 Lambda 的實戰經驗，講解我們該在怎樣的場合以及如何在 AWS Lambda 上寫 Ruby 應用，可說是非常熱門的主題。

1.	Kazuma Furuhashi：Charty - Visualizing your data in Ruby

	這場講題由獲得了 [Ruby Association Grant 2018](https://www.ruby.or.jp/en/news/20181106) 獎項的圖表生成工具 [Charty](https://github.com/red-data-tools/charty) 的作者帶來關於為何製作、如何設計以及實戰應用這套工具等議題，其實 Ruby 的世界一直不乏圖表產生的工具，不過功能往往不太全面，這套基於 Python matplotlib 的工具看起來完成度非常高，作者也將提及真實世界的應用範例，像這類結合異種語言產生的工具或新語言也是近年 Ruby 圈的發展趨勢之一，值得大家關注。

### 結語：

在 RubyConf Taiwan 即將邁入第一個 10 年的當下，我們來總結一下今年的選稿方向：

1.	「第一手」講者的重要性

	大家可以發現近年的 RubyConf Taiwan 常常會出現許多具有 Ruby / Rails Committer 身份的講者，或是某些知名開源專案核心作者，第一手資訊的人在會場對大家的意義就是：當你有問題時可以直接問他，甚至可能現場就幫你改好了，這也是所謂 CDD（Conference-Driven Development）一詞的意義。

1.	Ruby 3x3

	由於 Matz 訂下了 Ruby 3x3（3.0 版要比 2.0 快 3 倍）的目標，因此近年的 Ruby 發展計劃與 RubyKaigi 的主題也都圍繞著這個方向進行，繼去年的 JIT 之後，今年又推出了 type checker 與 Bundler 整合等發展方向，幸運的是剛好這些方向的主持者都有出現在今年的議程上，讓大家能在台灣獲得這些第一手訊息。

1.	Happy Hacking

	除了工作之外，我們也可以看到一些偏向趣味化的主題，讓大家在工作之餘也能用 Ruby 玩一些有趣的東西。

讓我們期待兩個月後的大會吧！

post-RubyConf Taiwan 2019 會前議程搶先看

RubyConf Taiwan 2019 會前議程搶先看


FactoryBot（前身為 FactoryGirl）為知名軟體方案解決公司 ThoughtBot 所開發，其用途非常地單純，就是讓使用者可以輕鬆地生產測試用資料。

而使用 FactoryBot 的方式也相當簡單。只要安裝了 Gem 並新增一個 Factory，就可以產生資料。

> Factory 長這個樣子

```ruby
FactoryBot.define do
  factory :user do
    first_name "John"
    last_name  "Doe"
    admin false
  end
end
```

然而雖然 FactoryBot 相當好入門，但是當你在規劃 Factories 的時候，有一些細節必須要注意，否則在未來程式變得複雜化的同時，在測試上恐怕會衍生出許多不必要的麻煩。

1.避免指定非必要欄位

非必要欄位有可能是自動生成的欄位（有 Default 值，例如 created_at），或是不影響資料庫保存的欄位（不需要驗證、可以為 Null 的欄位），倘若這些資料在測試中佔有重要的一環，則使用 trait 來指定。

舉例來說，假設你有個測試要找出加入超過兩年以上的 User，那麼可以寫成這個樣子：

```ruby
  FactoryBot.define do
    factory :user do
      first_name "John"
      last_name "doe"

      trait :old do 
      joined_at 2.years.ago
      end
   end
```

最忌諱的就是在限制 Unique 的欄位直接賦值，千萬不要這麼做！因為當你未來要在一個 Test Case 裡面生成兩筆以上的資料的話，就會產生驗證錯誤而無法儲存資料。

```ruby
# 請不要這麼做
  FactoryBot.define do
  factory :user do
    first_name "John"
    last_name "doe"
    id_number 'E1222333444' #unique column
  end
end
```

2.指定有限制欄位有方法

倘若我們真的有需要在 Unique 的欄位賦值，有什麼好方法嗎？你會有以下幾種做法。

- 手動賦值
  如果只是偶爾需要賦值的情況下，我會建議直接在生產資料的時候手動賦值，例如 `FactoryBot.create(:user, id_number: 'E1222333444')`，如此一來比較容易掌握生成的資料。

- 利用 Sequences
  這是 FactoryBot 所提供的一個方法，可以以 auto incremental 的方式產生資料。

```ruby
FactoryBot.define do
  factory :user do
    first_name "John"
    last_name "doe"
    # 第一個參數是欄位名稱，第二個參數則是起始的數值。
    sequence(:id_number, '01') { |n| "E12223334#{n}" }
  end
end
```

如此一來，每當用 FactoryBot 產生 User 的時候，他就會自動生成不重複的 `id_number`，會從 `E1222333401`, `E1222333402` 這樣的形式來新增。

不過這樣的做法會有一個問題，假設 `id_number` 有限制其字元數必定為 11，那麼當我們生產到第一百個 user 的時候，它的數值就會變成 `E12223334100`，會多出一個字元。為了避免這樣的情況，我們可以使用 Ruby 的 `#cycle` method，將它改成這樣子：

`sequence(:id_number, ('01'..'99').cycle) { |n| "E12223334#{n}" }`

如此一來，當生產到第一百個 User 的時候，它就會自動迴圈變回 E12223333401 了。

1.善用 Trait 讓你的資料更淺顯易懂

上面有提到利用 trait 來指定非必要欄位，你也可以用 Trait 來讓你的程式碼可讀性更高。舉例來說，我們有一個欄位叫做 `status` 用來記錄會員的帳號狀態，那麼在定義 Factory 的時候便可以利用 trait 來標示這些狀態。

```ruby
FactoryBot.define do
  factory :user do
    first_name "John"
    last_name "doe"
  end

  trait :active { status 'active' }
  trait :trial { status 'trial' }
  trait :retired { status 'retired' }
  trait :suspended { status 'suspended' }
end
```

這樣的做法不僅讓你的 Factory 變得乾淨，同時當你在生成資料的時候，也可以一目瞭然。特別是當你的測試非常需要各種不同的狀態下變動時，能夠更清楚明白測試的目標和內容。

2.搭配 Faker 隨機生產資料
Faker 是對於命名能力缺乏的工程師的一種救贖。它的能力作用就是生產隨機資料，從一般的信用卡卡號和人物的人名，到權力遊戲和 Pokemon 的角色，它都可以幫你生出來，用來瘩配 FactoryBot 生產測試資料，可謂妙不可言。

不過，當使用 Faker 搭配 FactoryBot 的時候，有些事情必須要注意。首先是在寫 Factory 的時候，我們必須用 block 來賦值給欄位，假設我們用參數的方式賦值的話，他只會隨機產生出其中一個結果，意味著如果你的欄位是 unique 的話，產生第二筆以上資料就會發生錯誤。

```ruby
FactoryBot.define do
  factory :user do
    first_name "John"
    last_name "doe"
    # 會重複出現一樣的公司名稱
    company_name Faker::Company.name
  end
end

FactoryBot.define do
  factory :user do
    first_name "John"
    last_name "doe"
    # 無論產生幾筆資料都是隨機的
    company_name { Faker::Company.name }
  end
end
```

另外一點則是，有些 Faker 內的 Seed 是有限的，遇到欄位是 Unique 的情況下必須謹慎使用 Faker，否則在建立愈多資料的情況，愈有可能隨機到相同的值造成資料庫的寫入錯誤。因為這種問題有隨機性，也比較難除錯，因此要盡可能避免這樣的狀況，當你發現某個測試常常出現這樣的情況，那就乾脆地手動賦值吧！

## 小結

FactoryBot 是個功能單純而且容易操作的套件，不過針對愈複雜的測試情況和應用也有著相當進階的功能，在這篇文章中提出一些初始規劃 Factory 時應該避免或者注意的地方，希望拋磚引玉能讓更多人知道 FactoryBot 的好處及妙用。

---

>  👩‍🏫  __課務小幫手：__
>  
> ✨ 想掌握 Ruby on Rails 觀念和原理嗎？
>
> 我們有開設 🏓 [Ruby on Rails 實戰課程](https://5xruby.tw/courses/ruby-on-rails) 課程唷 ❤️️
>

post/規劃 FactoryBot 小技巧，你的測試可以做得更好-cover

規劃 FactoryBot 小技巧，你的測試可以做得更好


## 為什麼用 Ransack
在網站中提供搜尋、篩選與排序功能在現在的網站中已是基本需求，畢竟大家的耐心，在 Ruby on Rails 中，由於採用了 ActiveRecord 作為 ORM 框架的緣故，要快速的組出 Search Query 並非難事。

基本上只要搭配上 Form Object 與 Query Object 模式，要優雅的完成好維護的搜尋模組還算是容易，但當你想要快速完成搜尋功能的時候，Ransack 絕對是你的好夥伴。

## 基本使用
### Basic Configuration
Ransack 的基本設定極其簡單，只要安裝完後基本上就可以使用了。

- 首先，在你的 Gemfile 中加入：

```ruby
# Gemfile
gem 'ransack'
```

- 接著在 Terminal 中執行

```shell
bundle install
```

- 完成了之後打開 Console，你就可以盡情的使用 `ransack` 提供的 Matchers 來組合出搜尋語句了，範例如下：
    - 找出使用者名字是 y 開頭的使用者：(使用 `start` matcher )

    ```ruby
    >> query = User.ransack(name_start: 'y')
    #=> Ransack::Search<class: User, base: Grouping <conditions: [Condition <attributes: ["name"], predicate: start, values: ["y"]>], combinator: and>>
    >> query.result
    #=> User Load (0.5ms)  SELECT "users".* FROM "users" WHERE "users"."login_name" ILIKE 'y%'
    ```

    - 上述的簡單範例中，我們可以看到 Ransack 幫我們在 ActiveRecord Model 中擴充了 `.ransack`  方法，只要在其中傳入查詢參數就行了
    - 呼叫 `ransack` 後，回傳的是一個 `Ransack::Search` 實體，可以看到我們輸入的查詢條件都已經被成功解析，預設使用 `AND` 來合併不同的查詢條件。
    - 對 `Ransack::Search` 實體呼叫 `#result` 就能得到查詢結果
    - `ransack` 方法接受的查詢參數是一個 `Hash`，`Hash` 的 `key` 形式為 `AttrName_MatcherName`。可以同時使用多個查詢條件，如：
        - 找出標題含有 `Bitcoin` 或 `Ethereum` 關鍵字、並且超過 5,000 點閱率的文章

          ```ruby
          >> query = Blog.ransack(title_cont_any: ['bitcoin', 'Ethereum'], view_count_gt: 5000)
          #=> Ransack::Search<class: Blog, base: Grouping <conditions: [Condition <attributes: ["title"], predicate: cont, values: ["bitcoin"]>, Condition <attributes: ["view_count"], predicate: gt, values: [500]>], combinator: and>>
          >> query.result
          #=> SELECT `blogs`.* FROM `blogs` WHERE (`blogs`.`title` LIKE '%bitcoin%' OR `blogs`.`title` LIKE '%Ethereum%') AND `blogs`.`view_count` > 5000
          ```

    - 當然查詢策略可以自行決定要用 `AND` 來確保符合所有查詢條件才返回結果；或用 `OR` 來指定只要任一條件符合就返回結果，這部分可透過 combinator 的設定來達成 (combinator 的設定可用 `m` 為別名)，如：
        - 尋找標題或是內文有 Bitcoin 關鍵字的文章

         ```ruby
         >> query = Blog.ransack(title_cont: 'Bitcoin', content_cont: 'Bitcoin', m: :or)
         #=> Ransack::Search<class: Blog, base: Grouping <conditions: [Condition <attributes: ["title"], predicate: cont, values: ["Bitcoin"]>, Condition <attributes: ["content"], predicate: cont, values: ["Bitcoin"]>], combinator: or>>
         >> query.result
         #=> Blog Load (12.6ms)  SELECT `blogs`.* FROM `blogs` WHERE ` `blogs`.`title` LIKE '%Bitcoin%' OR `blogs`.`content` LIKE '%Bitcoin%'
         ```

- Ransack 提供了超過五十個預先定義好的 Matchers，透過欄位與 Matchers 的結合幾乎已經可以完成所有常見的查詢，這邊就不嘗試一一列舉了，更詳細的文件請參見[官方 README 關於 Search Matchers](https://github.com/activerecord-hackery/ransack#search-matchers) 的篇幅。

### Association Filter
除了對 Model 物件本身的屬性進行查詢之外，Ransack 同時也支援了對關聯物件屬性的查詢，例如：
- 找出作者名字是 `Yusheng`，且標題含有 `Rails` 關鍵字的部落格文章

```ruby
>> query = Blog.ransack(author_name_eq: 'Yusheng', title_cont: 'Rails')
#=> Ransack::Search<class: Blog, base: Grouping <conditions: [Condition <attributes: ["author_name"], predicate: matches, values: ["Yusheng"]>, Condition <attributes: ["title"], predicate: cont, values: ["Rails"]>], combinator: and>>
>> query.result
#=> Blog Load (0.5ms)  SELECT `blogs`.* FROM `blogs` LEFT OUTER JOIN `authors` ON `authors`.`id` = `blogs`.`author_id` WHERE `authors`.`name` LIKE 'Yusheng' AND `blogs`.`title` LIKE '%Rails%'
```

- 這邊可以看到當我對 Blog 身上的 Author 關聯做查詢時，Ransack 會自動 `LEFT OUTER JOIN` Author 資料，並在一個 Query 中完成整個查詢。

### Scope Filter
除了上述的基本屬性搜尋、關聯屬性查詢外，Ransack 也支援透過 Model Scope 來做查詢，假設在 Model 中我們有一個 Scope `:published_since` 定義如下：

```ruby
# app/models/blog.rb
class Blog
  # ...
  scope :published_since, -> (date) { where(published: true).where('published_date <= ?', date) }
  # ... 
end
```

此時我們可以透過 `:published_since` 這個 scope 來做查詢，如：

```ruby
>> Blog.ransack(published_since: Date.today).result
#=> Blog Load (6.1ms)  SELECT `blogs`.* FROM `blogs` WHERE `blogs`.`published` = 1 AND (published_date < '2018-05-01')
```

- 這邊要特別注意的是，預設上 Ransack 必須要將可用於搜尋的 Scope 加入 `.ransackable_scopes` 白名單中，否則會被 Ransack 直接忽略，詳細可以看下面關於 Ransack Authorization 的部分。

### Built-in Form Helper
Ransack 除了對 ActiveRecord Model 擴充了 `ransack` 方法，給了我們一個好用的查詢介面之外，同時他也提供了我們 FormHelper 的擴充，讓我們可以輕易的在 View 當中建出搜尋表單。例如為上述的部落格搜尋建出表單：

```erb
# app/views/blogs/index.html.erb
# ...
<%= search_form_for @q do |f| %>
  <%= f.label :title_cont %>
  <%= f.search_field :title_cont %>

  <%= f.label :content_cont %>
  <%= f.search_field :content_cont %>

  <%= f.label :author_name_cont %>
  <%= f.search_field :author_name_cont %>

  <%= f.submit %>
<% end %>
# ...
```

之後你只需要在 `BlogController` 進行類似如下的設定，搜尋功能就這麽簡單地完成了。

```ruby
def index
  @q = Blog.ransack(params[:q])
  @blogs = @q.result
end
```

- 如果你跟我一樣是 SimpleForm 的愛好者，Ransack 當然也有對 SimpleForm 提供支援，詳情可以看[官方建議的設定方式](https://github.com/activerecord-hackery/ransack#using-simpleform)。

- Ransack 預設使用 `params[:q]` 來存放查詢條件，如果你需要客製、或是你在同一個頁面有多個對於不同資源的搜尋表單，可以進一步閱讀 [Ransack Wiki 中的 Configuration 條目](https://github.com/activerecord-hackery/ransack/wiki/Configuration)來了解如何對 `:search_key` 進行設定。

### Sort Links Helpers
除了搜尋之外，Ransack 也提供了 Toggler Sort Order 的功能，例如我想要提供一個連結，讓使用者可以將部落格文章依照發布日期排序，這時就可以借助 Ransack 提供的 `sort_link` 方法：

```erb
<%= sort_link(@q, :publish_date, '發布日期', default_order: :desc) %>
```

當使用者按下該連結時，就會在依照發布日期 升冪 / 降冪 排序中切換。

### Alias
上述部落格搜尋的範例中，實務上我們可能只會提供一個部落格關鍵字搜索的欄位給使用者，只要部落格標題、或內文含有該關鍵字就將結果返回，這時我們的 Query 可能如下：

```ruby
Blog.ransack(title_or_content_cont: 'Rails')
```

但 `:title_or_content_cont` 這 Key Name 實在又臭又長，這時可以透過 `ransack_alias` 來為查詢屬性設定別名。

```ruby
# app/models/blog.rb
class Blog
  # ...
  ransack_alias :article, :title_or_content
  # ...
end
```

此時你就可以用 `:article_cont` 來處理剛剛的搜尋，例如：

```ruby
Blog.ransack(article_cont: 'Rails').result
```

## Authorization
上述大致上講了 Ransack 的 基本查詢用法，但有些時候我們會不希望某些敏感屬性可被使用者查詢、或是只允許某些具有特定權限的使用者可以查詢，Ransack 也提供了四個方法讓我們針對需求進行設定：
### `ransackable_attributes`
- 定義可被作為搜尋條件的欄位，若查詢欄位不在此列表中，該查詢條件會被自動無視
- 預設所有欄位皆可被搜尋
- 原本的實作如下：

```ruby
def ransackable_attributes(auth_object = nil)
  column_names + _ransackers.keys
end
```

- 所以，假設 User 物件可被一般用戶搜尋的欄位僅包括 Email, Name 等，可在 User Model 中覆寫該類別方法，如：

```ruby
# app/models/user.rb
class User
  # ...
  def self.ransackable_attributes(auth_object = nil)
    if auth_object == :admin
      super
    else
      super & %w(email name)
    end
  end
  # ...
end
```

- 接著在 Controller 中你可以透過傳入 `auth_object` 來決定該使用者有權搜索的欄位

```ruby
# app/controllers/users_controller.rb
class UsersController < ActionController::Base
  # ...
  def index
    @q = User.ransack(params[:q], auth_object: current_user.role.to_sym)
    @users = @q.result  
  end
  # ...
end
```

### `ransackable_associations`：
- 定義可作為搜尋條件的關聯
- 預設返回該 Model 所擁有的所有關聯
- 原本的實作如下：

```ruby
def ransackable_associations(auth_object = nil)
  reflect_on_all_associations.map { |a| a.name.to_s }
end
```

### `ransortable_attributes`：
- 定義可作為排序條件的欄位
- 預設所有的欄位皆可被用做排序
- 原本的實作如下：

```ruby
def ransortable_attributes(auth_object = nil)
  ransackable_attributes(auth_object)
end
```

### `ransackable_scopes`：
- 定義可作為搜尋條件的 Model Scope
- 預設返回空陣列，所以若希望 Model Scope 可被用於搜尋，必須於 Model 覆寫該方法、加入白名單中
- 原本的實作如下

```ruby
def ransackable_scopes(auth_object = nil)
  []
end
```

## Advanced Usage
上面講了 Ransack 的常用的功能及設定，但很多時候因為想要使用特定資料庫提供的方法、或是想要 Custom Query 作為查詢條件時該怎麼辦呢？

除了基本的 Matchers、Scope、Association 可被用作搜尋外，Ransack 也提供了自訂 Predicate、Ransaker 的方法讓你去擴充查詢條件，由於 Ransack 實作上是使用了 Arel 的 Predicate 來組合出查詢語句，只要對 Arel 有基本了解就可以任意的對 Ransack 的 Predicate 進行擴充、或是新增 Ransacker 來擴充可查詢條件。

以下簡單示範在使用 MySQL 資料庫的情況下，為查詢擴充 Case Insensitive Search (如：Postgres 的 `ILIKE`)：

在 MySQL 中，要進行 Case Insensitive Search 的 Query 大致如下：

```sql
SELECT `blogs`.* FROM `blogs` WHERE (lower(blogs.title) LIKE '%bitcoin%')
```

- 首先，必須要先透過 SQL 方法將要查詢的欄位轉換成小寫
- 送入的查詢值也必須要轉換成小寫
- 如此不管查詢的值大小寫與資料庫內記錄是否完全符合，只要拼法一樣便可以成功返回結果

### Ransacker
可以理解成可查詢條件的擴充，此例中，我們要將 title、content 欄位轉換為小寫好進行 Case Insensitive Search。

一般來說，Ransacker 被預期回傳 Arel 節點來搭配 Predicate 方法 (Matchers) 一起使用。

```ruby
# app/models/blog.rb
class Blog
  # ...
  ransacker :lower_title do
    Arel.sql('lower(title)')
  end

  ransacker :lower_content do
    Arel.sql('lower(content)')
  end
  # ...
end
```

到這邊，我們已經透過剛剛新增的 ransacker 搭配 Matchers 進行查詢：

```ruby
Blog.ransack(lower_title_cont: 'bitcoin').result
#=> SELECT `blogs`.* FROM `blogs` WHERE (lower(blogs.title) LIKE '%bitcoin%')
```

但是這樣還有一點小缺憾，如果使用者丟進來的查詢條件是 `Bitcoin`，就會無法正確的達成 Case Insensitive Search，我們可以透過 Custom Predicate 來修正這個問題。

### Custom Predicates
可以想成自訂的 Matchers，其中 Formatter 可以將收到的查詢條件進行轉換，此例中我們預期不論使用者丟進來的查詢條件大小寫形式如何，一律轉換為小寫去做轉換

擴充 Predicate 的方式是對 Ransack 進行設定，一般來說我們會在 Initializers 裡面完成設定：

```ruby
# config/initializers/ransack.rb
Ransack.configure do |config|
  config.add_predicate :cont_downcase,
                       arel_predicate: :matches,
                       formatter: proc { |v| "%#{v.to_s.downcase}%" },
                       validator: proc { |v| v.present? },
                       compounds: true,
                       type: :string
end
```

- `arel_predicate` 必須要是一個合格的 Arel Predicates，完整的列表可以參閱 [Arel 文件](https://www.rubydoc.info/github/rails/arel/master/Arel/Predications)
- `validator` 內的條件若不符合，該查詢條件會被直接忽略

至此，我們可以順利的在 MySQL 中達成 Case Insensitive Search 的功能：

```ruby
Blog.ransack(lower_title_cont_downcase: 'BITCOIN').result
#=> SELECT `blogs`.* FROM `blogs` WHERE (lower(blogs.title) LIKE '%bitcoin%')
```

## 小結
使用 Ransack 作為 Database Search 的解決方案，不僅設定 / 使用容易，由於背後使用 Arel 來組出查詢語句的關係，也擁有極強的擴充能力。雖然現在有許多人喜歡用 ElasticSearch 來完成搜尋功能，但是基本的篩選、查詢功能使用 Ransack 便已足矣，若沒有需要 Fuzzy Search、中文斷詞的功能，實在無需多開服務浪費機器的效能。

Ransack 不但有簡單易用的介面、也考量到了權限、可擴充性、I18n 等基本要求，算是一個相當完善的解決方案，同時文件完整、也處於積極的維護狀態中，下次若要實作搜尋功能不妨可以考慮看看。

---

>  👩‍🏫  __課務小幫手：__
>  
> ✨ 想掌握 Ruby on Rails 觀念和原理嗎？
>
> 我們有開設 🏓 [Ruby on Rails 實戰課程](https://5xruby.tw/courses/ruby-on-rails) 課程唷 ❤️️
>

post-使用 Ransack 幫你完成後端搜尋與 Sorting/cover

使用 Ransack 幫你完成後端搜尋與 Sorting


大家好，今天要跟大家介紹我的瀏覽器會圖片辨識，一個瀏覽器套件（Chrome Extension）與圖片辨識（OCR API）結合的故事。OCR 是 Optical Character Recognition 的簡稱，簡單說就是圖片辨識的技術，主要目標是可以辨識圖片上的文字，我們的目標是瀏覽器會圖片辨識，讓我們可以將當前畫面上的文字複製出來，這邊的想像是，瀏覽器打開圖片後點選瀏覽器套件，接著圖片上的文字出現在我們的套件上，就可以將文字複製到別的地方了，所以做一個 Chrome Extension 串接圖片辨識 OCR API 就可以達成！

這邊共有兩個重點，一個是 Chrome Extension 的製作，另一個是串接 OCR API 的過程。

接下來我們直接開始動手做 -

## 實作 Chrome Extension 串接 OCR API

### Step 1

根據 [Google 官網](https://developer.chrome.com/extensions/getstarted)，首先我們需要一個叫做 `manifest.json` 的檔案，新增一個資料夾並在該資料夾下新增 `manifest.json` 檔案內容如下：

```json
{
  "manifest_version": 2,
  "name": "我的瀏覽器會圖片辨識",
  "description": "我的瀏覽器會圖片辨識",
  "version": "1.0.0",
  "icons": {
    "16": "icon.png",
    "48": "icon.png",
    "128": "icon.png"
  },
  "browser_action": {
    "default_icon": "icon.png",
    "default_popup": "popup.html"
  },
  "permissions": [
    "tabs"
  ]
}
```
這邊定義你的 Chrome Extension 的名稱、描述、版本、圖片、會用到的權限等等，並將圖片 `icon.png` 放到相同的資料夾底下，這邊試做我三種大小用同一張圖片，大家可以再針對不同大小選用適當的圖片唷。

### Step 2

開始製作要做的內容，首先先新增一個 `popup.html` 到你的資料夾下，檔案內容如下：

```html
<!DOCTYPE html>
<html>
  <head>
    <title>我的瀏覽器會圖片辨識</title>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <style type="text/css">
      body {
        margin: 10px;
        min-width: 400px;
      }

      h1 {
        font-size: 15px;
      }

      #popup {
        display: flex;
        align-items: center;
        justify-content: space-between;
      }
    </style>
    <script src="popup.js"></script>
  </head>
  <body>
    <h1>我的瀏覽器會圖片辨識</h1>
    <div id="popup">
      <span>選擇圖片上要轉換成文字的語言</span>
      <select id="select">
        <option selected disabled hidden value=''>請選擇</option>
        <option value="eng">英文</option>
        <option value="cht">中文</option>
      </select>
    </div>
    <hr>
    <div id="result"></div>
  </body>
</html>
```
這裡是點選你的 Chrome Extension 後會跳出來的畫面，我們先做兩種語言可以點選的按鈕。

### Step 3

開始串接 OCR API，在寫程式碼前我們會需要能夠串接 API 的 Key，故前往 [Free OCR API](https://ocr.space/ocrapi) 點選 **Register for free API Key**，註冊並帳號認證成功後會收到 **OCR.SPACE Free OCR API: Your free OCR API key** 的 email，我們的 API Key 就在 mail 內，接著我們在相同資料夾下新增 `popup.js`，檔案內容如下：

```javascript
document.addEventListener('DOMContentLoaded', () => {

  const select = document.querySelector('#select');
  const result = document.querySelector('#result');

  // 當使用者選取語言時
  select.addEventListener('change', (event) => {
    const language = select.value;

    // 抓取當前網址
    chrome.tabs.getSelected((tab) => {
      const tablink = tab.url;

      // 準備需要傳遞給 OCR API 的參數
      const formData = new FormData();
      formData.append('url', tablink);
      formData.append('language', language);
      formData.append('apikey', 'your-api-key');

      const url = 'https://api.ocr.space/parse/image';

      // 對 OCR API 發送請求
      fetch(url, {
        method: 'POST',
        body: formData

      // 用 json() 解讀回傳的資訊
      }).then(response => response.json())
        .then((jsonData) => {

          // 存取我們需要的資訊
          const parsedResults = jsonData['ParsedResults'];
          const errorMessage = jsonData['ErrorMessage'];

          // 如果回傳的結果不是空的
          if (parsedResults != null) {

            // 獲得每一個結果的詳細內容
            parsedResults.forEach((value) => {
              let exitCode = value['FileParseExitCode'];
              let parsedText = value['ParsedText'];
              let errorMessage = value['ErrorMessage'];

              // 如果分析回來的文字是空的，用 -1 表示
              if (parsedText === '') {
                exitCode = -1;
              }

              // 分析回來的情況 1 表示成功，其他情況顯示錯誤訊息
              switch (+exitCode) {
                case -1:
                  result.innerHTML = 'Error: parsed text is blank';
                  break;
                case 1:
                  result.innerHTML += parsedText;
                  break;
                default:
                  result.innerHTML = 'Error: ' + errorMessage;
                  break;
              }
            });

          // 其他錯誤情況
          } else {
            result.innerHTML = 'Error: ' + errorMessage;
          }

        // 如果打 API 有錯誤，則將錯誤印在 console 上
        }).catch((err) => {
          console.log('Error:', err);
      })
    });
  });
});
```
其中 `your-api-key` 請輸入在 [Free OCR API](https://ocr.space/ocrapi) 註冊得到的 API Key，這份檔案就是我們打 API 的主要內容，當使用者選取一種語言時，我們將需要的參數(`formData`)，含當前的網址、選取的語言、API Key 打去 Free OCR API 並將收到的結果放在畫面上，這邊只示範瀏覽器網址是圖片的情況，其中 `exitCode` 可以在 [Free OCR API](https://ocr.space/ocrapi) 看到有幾種定義，這邊先只考慮傳進來是 1 成功的情況，並自訂 -1 有成功傳進來但是傳進來是空值的情況，其他不成功的情況直接抓錯誤訊息顯示， `console.log('Error:', err)` 方便開發時查看錯誤。

### Step 4

最後我們的資料夾結構會是這樣：

```
chrome-extension-with-ocr-api
├── icon.png
├── manifest.json
├── popup.html
└── popup.js
```
接下來我們要把它放到自己的瀏覽器上，到 Chrome Extension 將右上角開發人員模式打開，重新整理後點選左上角 **載入未封裝項目**，選取剛剛完成的資料夾，接著看到你的 `icon.png` 出現在瀏覽器網址的旁邊就大功告成囉！現在可以用看看自己的 Chrome Extension 了！可以在 Google 搜尋一張網路上的圖片，點選在新分頁中開啟圖片，接著點選網址旁邊 `icon.png` 的小圖示，就可以開始用看看了。

### 最後結果如下：

![post-我的瀏覽器會圖片辨識](//images.ctfassets.net/8er52l3j5u76/vDGMw6M9Tf8K4dqEn0s0K/5885b6e71f27e5faec27141d11c3f3f4/ezgif-2-ba525ab6424e-smaller.gif)

## 總結

* 除了文章中示範的 [Free OCR API](https://ocr.space/ocrapi) 以外還有其他像是 [Google Cloud Vision API](https://cloud.google.com/vision/docs/ocr)、[Microsoft Azure Computer Vision API](https://docs.microsoft.com/zh-tw/azure/cognitive-services/computer-vision/quickstarts/ruby-print-text) 也都有提供 OCR 的技術，這邊大家也都可以練習看看唷，希望這篇文章可以激發大家的想法，發揮創意做出屬於自己的瀏覽器套件！
* 目前線上有一個叫做 [Copyfish](https://github.com/A9T9/Copyfish) 的瀏覽器套件就是用 OCR API 做的，可以參考看看。
* 最後的程式碼放到 [GitHub](https://github.com/cindyliu923/chrome-extension-with-ocr-api)，提供大家參考。
* 另外想用 Ruby 玩玩看串接 Free OCR API 也可以參考 [ocr_space](https://github.com/suyesh/ocr_space)。

---

>  👩‍🏫  __課務小幫手：__
>  
> ✨ 想掌握 JavaScript 觀念和原理嗎？
>
> 我們有開設 📒 [JavaScript / jQuery 前端開發入門實戰](https://5xruby.tw/courses/javascript) 課程唷 ❤️️
>

五倍紅寶石・專業程式教育機構

ASTRO Camp

線上課程

實體課程

技術文章

五倍消息

技術文章

整合 reCAPTCHA 到你的專案上，搭配 rails、devise

PM 的技能欄，你知道該點哪些嗎？

你看過 Elixir 嗎？如果沒有，現在讓你看看！

Rails 串接 Ecpay 電子發票，就是這麼簡單

RubyConf Taiwan 2019 會前議程搶先看

規劃 FactoryBot 小技巧，你的測試可以做得更好

使用 Ransack 幫你完成後端搜尋與 Sorting

我的瀏覽器會圖片辨識

訂閱文章

電話 | (02) 2331-5247

信箱 | [email protected]

地址 | 10046 台北市中正區衡陽路 7 號 5 樓

專業課程

ASTRO Camp

線上課程

實體課程

關於我們

關於五倍紅寶石

聯絡我們

媒體報導

加入我們

部落格

技術文章

五倍消息

幫助與政策

常見問題

隱私權政策

服務條款