五倍直播間

Blogs - Sidebar


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 會前議程搶先看


## 為什麼用 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


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 小技巧，你的測試可以做得更好


大家好，今天要跟大家介紹我的瀏覽器會圖片辨識，一個瀏覽器套件（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) 課程唷 ❤️️
>

post-我的瀏覽器會圖片辨識

我的瀏覽器會圖片辨識


「我不是本科生，適合寫程式嗎？」這樣的討論，是每個轉職工程師的人心中，一定曾冒出來的問題。

其實像這樣非黑即白、非敵即友、非 true 即 false 的二分法命題很容易討論，也很容易討戰，特別是文人相輕，自古皆然，誰也不想自己學的專業被批得一文不值，所以只要立場不一樣很快就能戰起來。戰起來倒也不是壞事，只是到最後可能容易淪為戰文而失焦… 啊，扯遠了。

很多學生，或是在網路上很多人會敲我，問我說「現在還適合轉職工程師嗎？會不會太晚？我適合嗎？」坦白說，這些回應都應該要「個案回答」，但成為工程師這件事情上，還是有一些通則。就透過過年這段時間寫了篇文章，來跟大家分享我觀察到的通則。

從我的觀察中，無論原來的背景為何，只要通過這三個階段，就是一個「可以在求職市場上立足的工程師」。

先分享一下我的背景：我從事資訊相關行業近 20 年，為了謀生曾經寫過 ASP、Perl、PHP、Python、Flash(ActionScript)、Objective-C…等程式語言，最後落腳在 Ruby。曾辦幾大型的技術研討會，也曾在國內、外的技術研討會當過講者。自己出過兩本跟程式相關的書，有一本還賣得不錯，應該算是有資格談談這個議題（笑）。

最近寫文章很流行破題，先破個題，這三個階段分別是：

* 一、學習並熟悉至少一款程式語言。
* 二、善用開發工具解決問題，完成有用的專案。
* 三、多人協作，完成更大規模的專案。

# 記得當時年紀小
記得我高中時候，有一門叫「工藝課」的課，因為是普通高中，所以這種對升學沒直接幫助的課常會被移去做別的事，但我真正開始接觸電腦程式正是這個工藝課。

![post-轉職軟體工程師，你必須經歷的三個階段](//images.ctfassets.net/8er52l3j5u76/5jtoje9IADnucJ91BIZZaA/1e6f7480f1af1816781ba5ba21409caf/floppy-disk.jpg)

那是個還有大、小片軟碟機、家裡電腦有比較大容量的硬碟就可以在同學之間秋好一陣子的時代。當時學校教的是 QBASIC，但我完全不知道這到底要幹嘛，也不知道敲打那些指令有什麼用途，所以只好巴著當時班上幾位比較厲害的同學跟他們拷貝作業，改幾個字之後交差了事（那時候不要說什麼 Stack Overflow 可以抄了，連 Google 都還沒出生咧）。因此，在高中的時候，班上那些會寫程式的同學對我來說就跟神一樣的存在。講到這裡，我突然可以理解現在其它人看到我開 editor 在寫程式的感覺了。

附帶一提，那時候覺得可以用貼紙把磁碟片旁邊的孔貼起來就能防止資料寫入這件事好酷！

是說，作業交了之後，就沒再碰電腦了。運氣不錯，高中畢業後，大學勉強有個醫學院的後段班的科系可以讀。忘了什麼原因，差不多是大三還是大四開始學了 Photoshop，後來因為這項技能，被學校電算中心找去幫忙設計海報，然後就在那邊開始學著用寫學校的校務系統，就這樣誤打誤撞闖進程式設計的領域了，這也是我第一個寫有真正使用者會用的系統（就是學校的老師跟學生啦）。

回到前面提到的「我不是本科生，適合寫程式嗎？」這個題目，我寫程式近二十年來，除了自身成長之外（經驗值 & 體重），也近距離看過不少朋友從新手變成老手，我可以跟大家說，寫程式這件事情跟是不是本科生並沒有直接的關係（其實這本身就是個假命題？）

另外，從 2009 年開始從社群開始的社群分享，到後來的校園推廣、企業內訓及開班授課，這十年下來，我看到不少從完全新手或是非資工、資管科系畢業，變成現在在業界做得很好的朋友（當然也有更多失敗的例子），我有觀察這些朋友們的「成長軌跡」，分別是這三個階段：

* 一、學習並熟悉至少一款程式語言。
* 二、善用開發工具解決問題，完成有用的專案。
* 三、多人協作，完成更大規模的專案。

# 關於軟體工程師…

在開始討論「新手成長必要的軌跡」之前，我們先聊聊「軟體工程師」吧！所謂的軟體工程師，廣泛來說，就是在工作的時候，使用一種（多種）程式語言，撰寫電腦看得懂的指令，叫電腦幫我們工作，這樣的角色就叫軟體工程師。

很多人對工程師有很多誤解，例如：「不從小開始學程式，長大就學不會了」，或是覺得不是資訊相關科系畢業就沒辦法當軟體工程師。

工程師其實也有分領域，如果你的目標是進到 IC design house，若不是頂尖大學電機資工碩博士，我想是沒什麼機會。如果你的目標是成為大數據、人工智慧方面的專家，不具備數學、統計或演算法方面的背景知識，大概也沒什麼機會。

但如果是做出像 Dcard、活動通、Uber、honestbee…等網路服務的網站工程師，那就算不是相關科系畢業也是很有機會的。還有一些關於成為工程師的迷思，也讓我晚一點再跟大家說明！

轉職成微軟體工程師，沒有方向，要怎麼開始？
轉職必須經歷文章中提及的三個階段，你該如何進行？

✔ 一、學習並熟悉至少一款程式語言。<br/>
✔ 二、善用開發工具解決問題，完成有用的專案。<br/>
✔ 三、多人協作，完成更大規模的專案。

 想瞭解轉職更多內容歡迎參考：[https://ubin.io/75mLtf](https://ubin.io/75mLtf)

【轉職資訊】
[五倍紅寶石 X ASTRO 全端工程師實戰訓練營](https://ubin.io/EPDhLq)(立即點擊瞭解更多)

ASTRO 致力於帶領初學者在程式領域找到適合自己的職涯之路。透過教學與媒合，幫助學員拓展職涯眼界，在程式圈活躍發展。
對生活現況有所不滿、渴望自己有所成長嗎？五倍紅寶石擁有專業師資、完整技能培訓、跨國業界人脈，讓 ASTRO 帶你到你想要的高度！


post-轉職軟體工程師，你必須經歷的三個階段

轉職軟體工程師，你必須經歷的三個階段


接觸過設計或前端開發的人對 Hex Color Codes 應該都不陌生，只是大家更熟悉的名稱是 **十六進位色碼標示法**，例如 `#ffffff` 代表白色、`#333` 則是深灰色。但你知道如何把 `#333` 變成更淺的灰色嗎？Pantone 2019 年度代表色 *Living Coral* 的 `#FF6F61` 是怎麼來的？十六進位與六位數的色碼又是什麼關係？

「複製貼上就好了啊！Photoshop 檢色器打開點一點就有了，像是 [HSL Color Picker](http://hslpicker.com/) 的工具在網路上也有很多，為什麼要了解那六個數字代表什麼意思呢？」想像有一天睜開眼睛看到的世界不再是你所熟悉的顏色，或與你一起工作的夥伴有色覺辨認障礙，這時色碼就能作為有效的溝通方式。

## 淺談 RGB 與 Hex Color Codes 的關係

現行開發網頁有許多標示顏色的方法如 RGB、HSL、Hex 或直接使用顏色名稱，在討論 Hex Color Codes 必須先瞭解 RGB 的運作原理。我們知道 RGB 代表的是三原色光中的紅色（Red）綠色（Green）和藍色（Blue），是螢幕顯示主要採用的技術。在電腦中，RGB 分別以 0 ~ 255 依序來表示各自的強度，從全黑 `rgb（0,0,0）` 到全白 `rgb（255,255,255）` 之間依不同比例即可組合出各種顏色，HEX 也是相似的原理。

將 Hex code 拆成三個部分，兩個字元一組依序代表 R、G、B 的數值：

![post-別再只會複製貼上！帶你真正搞懂 Hex Color Codes](//images.ctfassets.net/8er52l3j5u76/3yD8Q7f47exAgRW7VqIEcl/8b962a63e07a5597378e24f60323eb2d/hex-color-1.jpg)

以 `#FF6F61` 為例，我們可以拆成 `FF, 6F, 61` 來看，這些組合正是所謂的**十六進位（hexadecimal）**，也是 **Hex** 的由來。十六進位就是由數字 0 到 9 加上字母 A 到 F 來表示，後者可視為數字 10 到 15。不同於二進位，十六進位可以用更少的位元表達相同的數值。為什麼使用十六進位而不是二進位或十進位呢？這要牽扯太多的歷史故事與數學計算，在這裡你只需要知道：

- 0 代表最低（如同 RGB 中的 0）
- 8 代表中間
- 9 之後是 A
- F 代表最高（如同 RGB 中的 255）

## 解析 Hex Color Codes

### Step 1

有了 RGB 與十六進位的基本認識後，讓我們開始來解析色碼吧！

回到 `#FF6F61`，按照 RGB 的概念可以簡化成 `#F66`，三個數值的寫法正是大家常見的**速記法（shorthand）**：當一個組合中位元重複時就能簡化成一個位元，如 `#FFF` 或 `#333`，而 `#F66` 實際上代表的是`#FF6666`。這裡只是先借用速記法的概念來幫助我們分析複雜的 Hex Color Codes。

透過 `#F66` 我們觀察到 `F` 是最高，`6` 則是中間偏低，對應到 RGB 就可以得到一個由「全紅色＋暗綠＋暗藍」所組成的顏色，與原本的顏色已經非常接近：

![post-別再只會複製貼上！帶你真正搞懂 Hex Color Codes](//images.ctfassets.net/8er52l3j5u76/2maVBqjlNegU0VyT7FdxJs/4a7fe39313fb6595df95a49fd2e193d2/hex-color-2.jpg)

建議大家可以簡單複習 [RGB 的成色原理](https://www.google.com/search?q=rgb+color+wheel)：主色（紅、綠、藍）是由一個高數值的主色加上另外兩個低數值的主色；次要色（黃、青、洋紅）是由兩個高數值的主色加上一個低數值的主色；中間色介於一個主色與一個次要色之間，由高數值的主色加上中間值的主色再加低數值的主色所組成。

這樣的概念可以幫助想像顏色的樣子，以剛剛提到的「正紅色＋暗綠＋暗藍」為例，可以解讀成「高數值的紅＋低數值的綠與藍」的粉紅色。

### Step 2

第一步驟解決了色彩三要素中的色相（Hue），接著來分析明度（Lightness）。

上面提到 0 代表最低，F 代表最高，正是大家熟悉的全黑 `#000` 和全白 `#FFF`，數值越高、明度越高，判讀每個數值的高低就能粗略地得到該顏色屬於亮色或暗色。`#F66` 由一個最高值（`F`）與兩個中間偏低值（`6`）所組成，加總後的明度介於中間偏亮，因此我們可以說它是一個適中的粉紅色。

值得注意的是，明度是一個相對抽象的概念，口語上不容易精準表達，但理解原理能幫助我們針對細節作調整。

### Step 3

最後是色彩三要素中的飽合度（Saturation）。飽和度是根據一個色碼的範圍來決定，即最高數值與最低數值的差距：差距越大、飽和度越高；差距越小，顏色則越混濁；當三個數值一樣時，就會呈現灰色。`#F66` 中最高值 `F` 與最低值 `6` 差了一倍以上，因此是飽和度高、明度適中的粉紅色。

事實上，飽和度需要更複雜的數學計算，但以範圍來判讀已經足夠讓我們了解色碼的飽合度。

目前為止，你已經對 Hex Color Codes 有了基本認識，並知道如何一步一步解析複雜的色碼。讓我們打鐵趁熱試試看：`#3A538C` 是什麼顏色？（解析附於文末）

### 魔鬼藏在細節裡

你沈浸在破解 Hex Color Codes 的喜悅中，如何複雜的色碼都難不倒你。正準備分享此文的時候，你突然發現文章從頭到尾都沒有提到的另外三個數字，難道它們一點作用都沒有嗎？這要如何解釋 `#FFF2F0` 根本不是白色而是粉白色呢？

腦筋動得快的讀者也許已經發現另外三個數值 `F`, `2`, `0` 用上述三步驟分析後會得到高飽和度的暗紅橘色，如果將這個紅橘色加一點到白色裡面，就會接近 `#FFF2F0` 呈現的粉白色。沒錯，這三個數值正是用來微調最終的顏色。我們可以將最終的顏色視為 90% 的第一組數值（奇數位）加上 10% 的第二組數值（偶數位）的結果。

## 結論

越來越多的框架和工具充斥在設計和開發的每個環節中，Photoshop, Illustrator, Sketch, Figma, Adobe XD 到 React, Webpack, Sass, Babel, Bootstrap ... etc. 這些工具讓我們以前所未有的速度與模式創造各式各樣改變世界的產品，卻也導致我們容易忽略類似 Hex Color Codes 這種微小的細節。

然而，透過 Hex Color Codes 學到的不僅僅是十六進位色碼本身，還有色彩三要素（HSL）與速記法（shorthand）。多數情況下，將 Hex Color Codes 簡化成只由三個數值組成的速記法並不會讓顏色失真太多，卻能大大提升判讀速度和記憶性，且易於調整。以 `#D92` 為例：

- 增加數值使其變亮：`#FB4`
- 降低數值使其變暗：`#C70`
- 縮減最高值（`D`）與最低值（`2`）的差距來降低飽和度：`#C94`

動手試試看吧！

## Review

首先，將 `#3A538C` 簡化成 `#358`：由低度的紅色、中度的綠色和高度的藍色組成，數值都偏低，且 `3` 和 `8` 的差距不大，是低飽和度的暗藍色。

接著分析 `#A3C`：由高度的紅色、低度的綠色和高度的藍色組成，數值兩高一低，且 `A` 和 `3` 有兩倍差距，是高飽和度的亮紫色。

因此，`#3A538C` 是低飽和度的暗藍色（比 `#358` 偏紅一點）。

---

>  👩‍🏫  __課務小幫手：__
>  
> ✨ 想掌握 HTML 觀念和原理嗎？
>
> 我們有開設 🪁 [HTML 網頁設計新手村](https://5xruby.tw/courses/html) 課程唷 ❤️️
>


技術文章