五倍直播間

Blogs - Sidebar


Stripe 是全球知名的線上金流服務，由於針對各種主流語言的支援度極高，加上清楚明瞭的開發者文件，使得 Stripe 也使許多知名公司，例如 Slack 以及 Booking.com 成為他們金流收費服務的使用者。遺憾的是，礙於法規緣故，目前在台灣仍然無法使用 Stripe 來處理境內交易。

在五倍紅寶石的期間，由於合作的公司使用 Stripe 作為他們的訂閱收費服務，因此筆者也有機會一探究竟 Stripe；然而，在 2019 年的 10 月，由於日本的消費稅進行全國性的調整，因此訂閱的收費也必須變更，卻也因此遇到了幾個麻煩，這篇文章將隱蔽合作公司的名稱及服務，闡述我們在更新訂閱稅率時遇到的一些問題。

也許是日本的服務經常使用 Stripe 來收費，針對稅率提升這個部分 Stripe 的官方文件有提出該如何調整消費稅率：https://support.stripe.com/questions/2019-10-1。簡單說一下作法：透過 API 在每個使用者的訂閱項目追加新的 Tax Object，並且利用 “upcoming invoice” 來確認是否有順利修改使用者在十月過後的消費稅。

由於更新稅率的時間點非常難以掌握，為了避免空窗期導致收取錯誤的消費稅額，因此我們執行兩次更新：第一次更新在九月三十以前，調整所有次回訂閱付款時間為十月以後的使用者稅率；而第二次則在十月一號當日進行所有使用者的調整。

倒上我們遇到了兩個狀況：取消訂閱的會員因為稅率提升而被重新訂閱，以及使用 Coupon 的會員遇到重複收費的情況。

## 明明取消了卻再次被收費？

十月的不久後我們便收到從客服的來信，有使用者表示他們明明已經取消了訂閱，卻又在十月的時候被收取了訂閱的費用。我們從後台清查，發現確實有數位使用者取消了訂閱之後，卻在更新稅率的時間點被重啟了訂閱。因此我們推測是更新稅率這個行為導致了預期外的結果。

正當我們清查程式碼以及 Stripe 後台時，我們發現了一件事情，Stripe 在 2018-02-28 的 API Patch Note 裡面提到：

```
Updating a subscription set to cancel on a future date no longer clears the cancellation status. In order to clear the cancellation status, specify `cancel_at_period_end=false` when updating a subscription.
```

這意味著原本只要更新訂閱的物件，將會恢復使用者的訂閱。但當下是 2019 年的十月，怎麼還會發生這件事情呢？接著我們便發現了，原來 Stripe 的 API 可以選擇不要升級版本！由於客戶的服務在早期就已經導入 Stripe，而開發其他功能的過程中也沒針對訂閱收費機制修改，因此我們並沒有發現 API 使用舊的版本。雖然說收費的功能一切正常，但很顯然參照最新的開發者文件來操作舊版的 API 是有風險的，即使我們一直都有關注 Client 端的版本升級，但卻遺漏了伺服器的 API 版本。

## Coupon 失效？怎麼一回事？

Stripe 提供了折價功能，可以輕鬆地在使用者的訂閱上賦予各種折扣，客戶也因為商業需求提供免費訂閱一個月的 Coupon Code 給使用者。在清查被恢復訂閱的使用者的時候，我們發現有部分使用者的 Coupon 失效了，甚至在次月的訂閱被收取了比單月訂閱還要高的費用。

在調閱使用者的發票的時候，我們發現這些使用者的發票中都被註記了一條額外的費用：”Remaining time on \[Plan Name\] after 30 Sep 2019“；沿著這條線索我們找到了 Stripe 的 Proration 欄目：

```
Prorations come into play when a customer receives service for only part of the billing cycle. There are several cases where this can occur, notably when upgrading or downgrading a subscription during the billing cycle. Proration is only applicable to licensed (per-seat) subscriptions, as they are billed in advance–at the start of each cycle.

When a customer’s plan changes during a billing cycle, a proration line item is applied on their next invoice. If a customer whose subscription is billed on the first of the month changes to a more expensive plan, they receive a credit for the unused portion of the old plan and are billed for only the remainder of the month for the new plan.
```

Proration 主要會發生在當你的使用者有不同 Plan 選擇的時候，在訂閱期間倘若使用者更改成不同費用的 Plan，那麼 Stripe 將會依照比例來計算使用者必須額外付出的費用或者是可以得到的退費。

然而，由於 Stripe 針對 Proration 的文件說明有些曖昧不明，當時我們並不曉得更改稅率也會造成 Proration，事實上，更改稅率不應該被算在 `upgrading or downgrading a subcription` 裡頭，因此我們認為，由於使用者利用 Coupon 的關係，在 Stripe 計算過程當中，它將使用 coupon 的使用者判斷為免費的 Plan 切換到付費的 Plan，因此額外加算了 Proration 須付出的費用。

這樣的問題也相當容易解決，當你確信修改使用者訂閱時，你不會想要去計算使用者是否應該獲得退費或額外繳費，可以將 Proration 的功能關閉，便不會造成這樣的遺憾發生。

```
Prorating the costs of plans is the default behavior but you can disable proration by setting proration_behavior to none when making a subscription change:
```

雖然為了這次消費稅更新我們詳閱了許多官方文件和部落格資料，但很顯然並不是官方文件都能涵括所有的狀況，有些部分是開發者方的疏忽（例如利用舊版的 API 版本），而有些則是特殊的情況造成意外的結果。而這次更新也給我一個教訓，當開發者在整合外部服務與自己的應用程式時，應該更謹慎地對待兩者之間的契合度，並且隨時準備面對意外的發生以進行應對。

後記：事實上在發生 Proration 超收費用的時候，我社的負責人有寫信向日方的 Stripe 客服人員詢問 Proration 發生的原因，然而來回信件數次之後似乎都沒有得到有用的資訊，因此我們無法得知 Proration 真實的發生原因，因此上面提及的只能是說是最接近的推論。

post-Oopsy! 一個頭兩個大的 Stripe 開發經驗 / cover

Oopsy! 一個頭兩個大的 Stripe 開發經驗

> Photo by [Jude Al-Safadi](https://unsplash.com/@judesaf?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText)

## 前言
為了增加資訊安全，很多線上服務如購物網站或銀行使用[二階段驗證](https://en.wikipedia.org/wiki/Help:Two-factor_authentication)加強保護使用者個資。目前市面上較知名提供簡訊寄送/驗證的服務有 Twilio（與 Authy 同公司）、Nexmo、Message Bird ... 等，提供的服務內容大同小異，各自也都有大型企業採用。

個人較為偏好 Authy 的主因是可以將使用者電話號碼在 Authy 平台註冊獨一的 `Authy ID` 而無需將電話號碼敏感資料儲存在自站。另外，除了完整的 API 說明與範例文件， Authy 提供多種語言的套件，有助於開發速度與便利性。

以下範例將使用 Authy 搭配 Rails 在會員註冊流程中加入簡訊二階段驗證，並且限制一手機號碼僅限一有效會員。大致流程是：

1. 使用者填寫 email、電話號碼
2. Authy API 判斷號碼是否有效，如是，註冊為 Authy User 並回傳 Authy ID
3. Authy API 寄送簡訊驗證碼至使用者電話
4. 使用者輸入驗證碼
5. Authy API 判斷驗證碼是否有效，如是，使用 email 與 Authy ID 建立 user

### Authy 環境設置
註冊 [Twilio](https://www.twilio.com/try-twilio) 後前往在 dashboard 底下的 `Authy` 、建立一新的應用程式後取得 API Key。因為使用簡訊驗證實作，非相關的預設設定建議一併更改掉，例如禁止使用電話通話與 Authy App 驗證。

![](https://i.imgur.com/LbryWfH.png)

### Rails 環境設置
起始一新的 Rails 專案後在 Gemfile 內加入 authy 與 simple_form 套件，別忘了下 `bundle` 指令安裝。

```ruby
# Gemfile

gem 'authy', '~> 2.7.5'
gem 'simple_form'
```

在 `config/initializer` 底下建立 `authy.rb`，並在 `api_key` 的部分貼上 Authy Production API Key（如上圖）。

Api key 建議使用 ENV 或 [Config](https://github.com/rubyconfig/config) 之類套件存取，不管怎麼做，別將 key 裸露在非相關的人看得到的地方。

```ruby
# config/initializer/authy.rb

Authy.api_uri = 'https://api.authy.com'
Authy.api_key = 'YOUR_API_KEY'
```
### 建立 users routes、model、controller
因本文主要介紹內容為二階段驗證，將大幅簡化 user 部分。如要完整的功能，建議使用 Rails 社群中廣為使用的套件 devise，相關設置請參考[devise](https://github.com/heartcombo/devise)與 [authy-devise](https://github.com/twilio/authy-devise)。

路徑部分只需要 index 頁面呈現所有成功建立的使用者。

```ruby
# config/routes.rb

Rails.application.routes.draw do
  resources :users, only: :index
end

```

建立 User model。

```
$ rails g model user email authy_id
$ rails db:migrate
```

在 User model 內加上 `presence` 與 `uniqueness` validation。當中 `authy_id` 也使用 `uniqueness` 是為了確保使用者無法使用同一號碼註冊多個帳號，在後面流程中會有相關說明。

```ruby
# app/models/user.rb

class User < ApplicationRecord
  validates :email, presence: true, uniqueness: true
  validates :authy_id, presence: true, uniqueness: true
end
```

Controller 與 View 的部分相當簡易，query 所有 users 並逐一印到 index 頁面。

``` ruby
# app/controllers/users_controller.rb

class UsersController < ApplicationController
  def index
    @users = User.all
  end
end

# app/views/users/index.html.erb

<% @users.each.with_index do |user, index| %>
  <div><%= "#{index + 1}: #{user.email}" %></div>
<% end %>
```

### 使用者輸入 email 與電話號碼
下一個步驟需要建立一個表單讓使用者填寫 email 與電話號碼，後端部分要處理的是檢查號碼是否有效並以該資料使用 Authy API 建立 Authy User 後發送簡訊驗證碼到該用戶號碼。由於不打算儲存電話號碼在資料庫內，使用 [form object](https://railsbook.tw/chapters/26-organize-your-code-advanced.html#form-object) 設計模式來處理，也便於驗證輸入資料正確性。

在 routes 內新增這個階段所需要的兩個路徑。 `/sms_auth/registration/new` 用來放置表單、 `/sms_auth/registration` 用來處理註冊 Authy User 與發送簡訊驗證碼。

``` ruby
#config/routes.rb

Rails.application.routes.draw do
  resources :users, only: :index

  namespace :sms_auth do
    resource :registration,
             controller: :registration,
             only: %i[new create]
  end
end

```

新增 `SmsRegistration`，三個屬性是註冊 Authy User 所需要的資料。當中 `country_code` 與 `cellphone` 除了檢查必填外，增加 validation 檢查使用者輸入的確定為整數。

``` ruby
# app/forms/sms_registration.rb

class SmsRegistration
  include ActiveModel::Model

  attr_accessor :email, :country_code, :cellphone

  validates :email, presence: true
  validates :country_code, presence: true, numericality: { only_integer: true }
  validates :cellphone, presence: true, numericality: { only_integer: true }
end
```

Controller create action 部分， `register_authy_user` 使用 Authy 套件的 `register_user` 方法，帶入使用者輸入的 email 與電話資料註冊 Authy User，Authy API 判斷號碼有效後會回傳 `id`。

在 Authy 端，如果一個號碼從來沒註冊過，Authy 會建立一個並回傳新的 ID。如果嘗試用已註冊過的號碼再次註冊，Authy 回傳第一次註冊的 ID。

確認 Authy User 註冊成功後，將回傳的 ID 與使用者輸入的 email 寫入 session 供後面建立使用者階段使用。最後，使用 authy 套件的方法 `request_sms` 傳送驗證碼後帶使用者前往簡訊驗證頁面。

``` ruby
# app/controllers/sms_auth/registration_controller.rb

module SmsAuth
  class RegistrationController < ApplicationController
    def new
      @registration = SmsRegistration.new
    end

    def create
      @registration = SmsRegistration.new(registration_params)

      if @registration.valid?
        register_authy_user(@registration)
        redirect_to new_sms_auth_verification_path
      else
        render :new
      end
    end

    private
    def register_authy_user(registration)
      authy = Authy::API
      response = authy.register_user(
        email: registration.email,
        country_code: registration.country_code,
        cellphone: registration.cellphone
      )

      if response.ok?
        session[:authy_id] = response.id.to_s
        session[:user_email] = registration.email
        authy.request_sms(id: response.id)
        return
      end

      redirect_to new_sms_auth_registration_path
      flash[:error] = '請確認手機號碼有效'
    end

    def registration_params
      params.require(:sms_registration).permit(:email, :country_code, :cellphone)
    end
  end
end
```

如果使用 simple_form 套件處理表單，需要稍微留意 `country_code` 的部分。simple_form 自動判斷 `country` 相關欄位命名應為 select 然後就抱怨 `undefined method 'country_select' for ...`。 相關討論請見其官方 [issue](https://github.com/heartcombo/simple_form/issues/757)。為了 demo 便利，在這直接將欄位設為 `as: :string` 改為一般文字輸入。

``` ruby
# app/views/sms_auth/registration/new.html.erb

<%= simple_form_for @registration, url: sms_auth_registration_url do |f| %>
  <%= f.input :email %>
  <%= f.input :country_code, as: :string %>
  <%= f.input :cellphone %>
  <%= f.submit '送出' %>
<% end %>
```

### 使用者輸入驗證碼與建立 User
到這個階段，測試用的手機號碼內應該已經收到一組七位數驗證碼（可在 Authy console內調整位數），尚未完成的部分為前端表單供輸入驗證碼，後端處理查詢驗證碼是否正確與最後建立 user。

在 routes.rb 內新增這個階段所需要的兩個路徑。 `/sms_auth/verification/new` 用來放置輸入驗證碼表單、 `/sms_auth/verification` 用來處理檢查驗證碼正確性與建立 user。

``` ruby
#config/routes.rb

Rails.application.routes.draw do
  resources :users, only: :index

  namespace :sms_auth do
    ... 略 ...

    resource :verification,
             controller: :verification,
             only: %i[new create]
  end
end
```

驗證碼表單內只需要一個 `pin_number` 欄位，一樣用 form object 方式處理。Validation 除了 `presence` 外檢查輸入值是否為七碼整數。

``` ruby
# app/forms/sms_verification.rb

class SmsVerification
  include ActiveModel::Model

  attr_accessor :pin_number

  validates :pin_number, presence: true
  validates :pin_number,
            numericality: {
              only_integer: true,
              message: 'PIN碼錯誤'
            }
  validates :pin_number,
            length: {
              is: 7,
              message: 'PIN碼錯誤'
            }
end

```

驗證 controller 部分，在 `verify_pin` 中使用 Authy 所提供的 `verify` 方法，帶入使用者輸入的驗證碼與前一個階段設置的 `session[:authy_id]` 值。如果 Authy 回覆該驗證碼無效，將使用者帶回驗證碼輸入頁並提示錯誤，若正確，使用 `session[:user_email]` 與 `session[:authy_id]` 建立 user。

這裡使用 `create!` 的用意是刻意在建立使用者時如果有重複 `eamil` 或 `authy_id` 的情況時的例外能夠使用 `rescue_from` 處理，要求使用者提供其他 email 或電話號碼，而不是 silent fail，另外也確保使用者無法使用一個手機號碼申請多個帳號。

``` ruby
# app/controllers/sms_auth/verification_controller.rb

module SmsAuth
  class VerificationController < ApplicationController
    rescue_from ActiveRecord::RecordInvalid do |_exception|
      redirect_to new_sms_auth_registration_path
      flash[:error] = 'Eamil 或號碼已由其他帳號使用'
    end

    def new
      @verification = SmsVerification.new
    end

    def create
      @verification = SmsVerification.new(verification_params)

      if @verification.valid?
        verify_pin(@verification)
        create_user
        redirect_to users_path
      else
        render :new
      end
    end

    private

    def verify_pin(verification)
      authy = Authy::API
      response = authy.verify(
        id: session[:authy_id],
        token: verification.pin_number
      )

      return if response.ok?

      redirect_to new_sms_auth_verification_path
      flash[:error] = '驗證碼無效'
    end

    def create_user
      User.create!(
        email: session[:user_email],
        authy_id: session[:authy_id]
      )
    end

    def verification_params
      params.require(:sms_verification).permit(:pin_number)
    end
  end
end
```

最後表單的部分。

``` ruby
# app/views/sms_auth/verification/new.html.erb

<%= simple_form_for @verification, url: sms_auth_verification_path do |f| %>
  <%= f.input :pin_number %>
  <%= f.submit '送出' %>
<% end %>
```

做到這裡，使用 Authy 實作二階段驗證的基本功能已經完成。然而，還有很多可以進一步優化的部分，例如：非 ok 的 Authy response 處理、將使用到 api 相關的 method 包裝成 service，以免 controller 越來越複雜肥大 ... 等。

最後，除了本文使用到的 Auhty 套件，如果會員系統使用的是 Devise，可以參考也是 Twilio 官方做的 [authy-devise](https://github.com/twilio/authy-devise) extension。

---

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

post-安安你好給電話嗎？使用 Authy 快速打造二階段驗證 / cover

安安你好給電話嗎？使用 Authy 快速打造二階段驗證


> Image by Johannes Plenio from Pixabay

## 前言
在這個科技日新月異的時代下，製作網頁的工具也是隨著時間演進下，不斷推陳出新。如果你曾經對於每天透過瀏覽器打開的網頁有一點的好奇心，會不會想要嘗試做一個自己專屬的網站呢？這時候我們就可以享受工具進步所帶來的效益了呢！這不是火箭科學，要進入無所不在的網頁世界，入門僅需要些許的耐心。讓我們以靜態網頁產生器為自己做出第一個網站吧！

## 靜態網頁
何謂[靜態網頁](https://en.wikipedia.org/wiki/Static_web_page)？可以理解為就像是書籍或雜誌一樣，一但從印刷廠出版了，內容就不太會更動。當我們這樣比喻時，我們所寫的網頁檔案（印刷品）一但被放到主機上（送出印刷廠）內容幾乎不會變了，除非印刷廠再次印製新的內容，再次派送刊物，讀者（瀏覽網頁的人）才會獲得新的內容。

## 動態網頁
那[動態網頁](https://en.wikipedia.org/wiki/Dynamic_web_page)呢？就像不是在聽預錄好的專輯（預製的網頁檔），而是現場表演。只是背後根據使用者的行為，負責動態產生內容的是一整組應用程式和系統，有可能會有更多的資料庫和服務在背後運行，並不斷動態即時產生新的內容。

## GatsbyJS
[GatsbyJS](https://www.gatsbyjs.org/) 是一套靜態網站生成器，主要使用程式語言 [JavaScript](https://zh.wikipedia.org/wiki/JavaScript) 的開源專案。前端框架則使用了時下熱門的 [ReactJS](https://zh-hant.reactjs.org/)。靜態網站生成器的工具通常會提供樣版設置的地方，可以快下載樣板後速進行套版。同時也會在本機運行一個伺服器即時對網頁的變動，編譯後反應內容讓我們可以看到變動後的內容。在有了以上基本概念後，讓我們開始從零建立我們的第一個靜態網頁吧。

## 開發環境準備
> 本文將以 MacOS 舉例，如果使用的是其他作業系統，只要確定有安裝到所需軟體即可。

首先我們會需要 [Xcode](https://apps.apple.com/tw/app/xcode/id497799835?mt=12) 這是蘋果官方提供的程式開發套件，裡面會有編譯程式的相關必要工具。可以在蘋果官方的 App Store 找到並下載安裝它。接著我們將使用 Mac 上的套件管理工具 [Homebrew](https://brew.sh/index_zh-tw) 下載相關工具以及 GatsbyJS。

* 安裝 Homebrew

請打開 Mac 內建的應用程式`終端機`(Terminal)並輸入下列指令下載並安裝 Homebrew :

```shell
/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
```

* 安裝 Node

[Node](https://nodejs.org/en/) 可以提供環境執行 Javascript 而無需透過瀏覽器，而 Gastby 是透過 Node 的打造的，所以我們需要先透過 Homebrew 安裝 Node。請在終端機輸入下列指令安裝：

```shell
brew install node
```

* 安裝 Gatsby

當我們安裝好 Node 後，我們將使用 Node 自帶的套件管理工具 [npm](https://zh.wikipedia.org/wiki/Npm) (Node Package Manager) 來安裝 Gatspy ，請在終端機輸入下列指令：

```shell
npm install -g gatsby-cli
```

使用 `npm install` 並給予參數 `-g` (global) 時，npm 會將套件安裝在 npm 預設的全域的路徑底下，而不是該專案的資料夾 node_modules 裡。

## 建立 Gatsby 專案
我們先選擇使用官方提供的 Hello World 啟動檔案，它會提供 Gatsby 所需必要的相關檔案。使用 Gatsby 提供的指令建立專案：

```shell
gatsby new hello-world https://github.com/gatsbyjs/gatsby-starter-hello-world
```

建立完成後，在終端機使用指令進入所建立的資料夾中：

```shell
cd hello-world
```

然後我們可以透過啟動本幾伺服器的指令來啟動伺服器：

```shell
gatsby develop
```

沒意外的話，這時候在瀏覽器中輸入網址 [http://localhost:8000/](http://localhost:8000/) 即可預覽這個專案透過 Gatsby 所建立的靜態網頁。此時左上角網頁應該會顯示 Hello World!

![Hellow World](https://i.imgur.com/OG3iWP6.png)

到這一步驟，我們確定有辦法透過 Gatsby Starter 的下載，然後透過運行伺服器去產生最終我們要的靜態網頁並在瀏覽器正常顯示。

## 使用部落格的 Starter
如果今天我們想要快速建立一個部落格呢？比較快的方式是使用官方網站上其他人做好的啟動包。我們可以在 [Gatsby Starters](https://www.gatsbyjs.org/starters?v=2) 上找到想要的啟動包。我們以 [Gatsby Starter Blog](https://www.gatsbyjs.org/starters/gatsbyjs/gatsby-starter-blog/) 為例。在終端機中回到你想下載該啟動包的位置然後輸入：

```shell
gatsby new gatsby-starter-blog https://github.com/gatsbyjs/gatsby-starter-blog
```
完成後我們輸入 `cd gatsby-starter-blog && gatsby develop` 進入資料夾且運行伺服器，然後到瀏覽器預覽。

![Blog](https://i.imgur.com/AYQl7QH.png)

## 專案結構
在 Gatsby 專案架構下我們最會有特定的資料夾放置相關的檔案。在進行指令 `gatsby develop` 它會去依照資料夾的內容去編譯並輸出瀏覽器可讀取的三種檔案，分別是：`HTML`、`Javascript` 和 `CSS`。也會將你的網站所需要的相關資源譬如圖片放置進最終的輸出資料夾，提供網頁去讀取。通常資料夾結構會長得像以下：

```
/
|-- /.cache
|-- /plugins
|-- /public
|-- /src
    |-- /pages
    |-- /templates
    |-- html.js
|-- /static
|-- gatsby-config.js
|-- gatsby-node.js
|-- gatsby-ssr.js
|-- gatsby-browser.js
```
* `.cache`：隱藏資料夾是 Gatsby 自動生成的快取，通常不會去修改內容。
* `plugins`：這是放置插件的地方，可以從 npm 安裝相關支援 Gatsby 的插件。
* `public`：是使用指令 `gatsby build` 後會將網站最終的輸出檔放置於此。
* `src`：這是 Source Code 的縮寫，放置主要撰寫網頁內容的地方。
  * `pages`：在這放置的 jsx 檔在最後輸出時會變成網頁網址的一個頁面，例如 `about.js` 在輸出網頁後可以透過 `你的網域名稱/about` 路徑進入這個頁面。
  * `templates`：這裡用來放置模板，例如部落格的每篇文章都使用同一個模板，適合放入於此。
* `static`：用來放置靜態資源例如圖片，在這個資料夾在輸出時不會被更動，而是直接會進入 public。

## 打包與部屬網站

在熟悉 ReactJS 基本的語法後，我們便有能力更動從 Starter 提供的樣板來改寫出我們個人化的網站內容。更進階的部分，研究如何使用已經被創造出的插件以實現某些功能，節省開發網站的時間。

假設我們已經撰寫網站內容完畢想要部署至某個空間時，我們需要在終端機使用指令：

```shell
gatsby build
```

這個指令會將網站所有內容打包輸出到 public 資料夾。部署方式是將資料夾的內容上傳到某個網頁服務空間。當瀏覽器透過網址訪問空間便能瀏覽網站。Gatsby 也提供了另一個指令讓我們在本機瀏覽部署版本的網頁內容：

```shell
gatsby serve
```

透過在瀏覽器網址輸入 [http://localhost:9000/](http://localhost:9000/) 便可以瀏覽 Gatsby 打包後的網站。

## 總結
在技術的進步下，我們透過 Gatsby 用熱門的前端框架 ReactJS 撰寫網站，並且打包在本機運行伺服器並開發除錯。Gatsby 也有插件可以整合自動部署，以達到開發、打包、測試、部署的流程整合。如果能運用生態系的資源豐富度，我們也可以更快速且更有效率的開發靜態網頁。

---

>  👩‍🏫  __課務小幫手：__
>  
> ✨ 想掌握 React 觀念和原理嗎？
>
> 我們有開設 💠 [React 全攻略入門班](https://5xruby.tw/courses/react) 課程唷 ❤️️
>


post-快打造靜態網站的利器？Gatsby！ / cover

快打造靜態網站的利器？Gatsby！


大家好，今天要來跟大家說明一個知道誰在敲打你家窗戶的方法！？我們在網路的世界中可以透過 API (Application Programming Interface) 與各種應用程式互相交流、溝通、傳遞各種訊息，而如何驗證身份就變成一件重要的事情，即我們不應該將所有的資料都裸奔，讓任何人都可以存取，所以在設計 Web API 的時候常常會需要考慮到授權或驗證的部分，那我們要如何確認誰有權限呢？要如何安全地傳遞訊息呢？接下來跟大家說明其中一種方式。

## JSON Web Token (JWT)

JWT 的全名是 `JSON Web Token`，是一種基於 JSON 的開放標準([RFC 7519](https://tools.ietf.org/html/rfc7519))，它定義了一種簡潔(compact)且自包含(self-contained)的方式，用於在雙方之間安全地將訊息作為 JSON 物件傳輸。而這個訊息是經過數位簽章(Digital Signature)，因此可以被驗證及信任。可以使用 `密碼`(經過 **HMAC** 演算法) 或用一對 `公鑰/私鑰`(經過 **RSA** 或 **ECDSA** 演算法) 來對 JWT 進行簽章。

> 註：
>  - RFC：記錄網際網路規範、協定、過程等的標準檔案。
>  - 簡潔(compact)：體積非常的小，可放在 URL 、 POST 參數或 HTTP Header 內發送請求，體積小意味著傳輸速度快。
>  - 自包含(self-contained)：payload 裡面就有所需要的資訊，不需要再重新 query database 的資料。
>  - [數位簽章(Digital Signature)](https://zh.wikipedia.org/wiki/%E6%95%B8%E4%BD%8D%E7%B0%BD%E7%AB%A0)：
>  - 演算法：[HMAC](https://zh.wikipedia.org/wiki/%E9%87%91%E9%91%B0%E9%9B%9C%E6%B9%8A%E8%A8%8A%E6%81%AF%E9%91%91%E5%88%A5%E7%A2%BC)、[RSA](https://zh.wikipedia.org/wiki/RSA%E5%8A%A0%E5%AF%86%E6%BC%94%E7%AE%97%E6%B3%95)、[ECDSA](https://en.wikipedia.org/wiki/Elliptic_Curve_Digital_Signature_Algorithm)

## 什麼情況適合使用 JWT

- **授權(Authorization)**：這是很常見 JWT 的使用方式，例如使用者從 Client 端登入後，該使用者再次對 Server 端發送請求的時候，會夾帶著 JWT，允許使用者存取該 token 有權限的資源。單一登錄(Single Sign On)是當今廣泛使用 JWT 的功能之一，因為它的成本較小並且可以在不同的網域(domain)中輕鬆使用。
- **訊息交換(Information Exchange)**：JWT 可以透過公鑰/私鑰來做簽章，讓我們可以知道是誰發送這個 JWT，此外，由於簽章是使用 header 和 payload 計算的，因此還可以驗證內容是否遭到篡改。

## JWT 的組成

1. **header**
2. **payload**
3. **signature/encryption data**

其中前兩個元素 header 和 payload 是特定結構的 JSON 物件，第三個部分取決於演算法是用來作簽章還是加密，如果是未加密的 JWT，則將其省略。JWT 可以被編碼成 JWS/JWE 簡潔的表現形式(Compact Serialization)。JWS 和 JWE 規範中定義了另一種序列化格式，稱為 JSON 序列化，這是一種非簡潔的表示形式，允許在同一 JWT 中使用多個簽章或接收者。

簡潔的序列化(The compact serialization)是對前兩個 UTF-8 字節的 JSON 元素（header 和 payload）以及進行簽章或加密的 data(不是 JSON 物件本身) 做 Base64 URL 安全編碼。三部分分別用一個 `.` 隔開，所以最後的結果會像這樣：

```rb
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.  # header
eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWV9.  # payload
TJVA95OrM7E2cBab30RMHrHDcEfxjoYZgeFONFh7HgQ  # signature
```

### Header

每個 JWT 都有一個 header(又稱為 JOSE header)，是一種對自我的聲明，無論 JWT 是簽章的還是加密的，這些聲明都表示了其所使用的演算法，通常也會表示要如何解析 JWT 的其餘部分。

根據 JWT 的類型，header 中可能必須包含更多字段。例如，加密的 JWT 攜帶有關用於密鑰加密和內容加密的加密演算法的訊息。對於未加密的 JWT，這些字段則不會存在。

**header** 內含：

1. 必要欄位：
  - **alg**：對此 JWT 進行簽章和(或)解密的主要演算法。對於未加密的 JWT，此聲明必須設置為 `none`。
2. 非必要欄位：
  - **typ**：JWT 本身的媒體類型。此參數僅助於將 JWT 與帶有 JOSE header 的其他對象混合使用的情況。實際上，這種情況很少發生。如果存在，則此聲明應設置為值 `JWT`。
  - **cty**：內容類型。大多數 JWT 攜帶特定的聲明以及任意數據作為其 payload 的一部分，在這種情況下，不得設置內容類型聲明。對於 payload 本身是 JWT 自己（巢狀 JWT）的實例，此聲明必須存在並帶有值 `JWT`，用來表示需要進一步處理巢狀的 JWT。而巢狀 JWT 很少見，因此 cty 聲明很少出現在 header 中。

所以說如果一個未加密的 JWT ，其 header 會是這樣：

```json
{
  "alg": "none"
}
```
經過編碼後為：`eyJhbGciOiJub25lIn0`

### Payload

```json
{
  "sub": "1234567890",
  "name": "John Doe",
  "admin": true
}
```

通常所有使用者有興趣的資訊都會被放在 payload 裡，另外，某些規範中定義的權利要求也可能存在。就像 header 一樣，payload 是一個 JSON 物件。儘管特定的權利要求具有明確的含義，但沒有權利要求是強制性的。JWT 規範指出應該忽略在實踐中無法理解的聲明。具有所附特定含義的權利要求被稱為 registered claims。

**Registered Claims** 包含：

  - **iss**：issuer 的簡稱，用字串(case-sensitive) 或 URI 表示這個 JWT 的唯一識別的發行方。
  - **sub**：subject 的簡稱，用字串(case-sensitive) 或 URI 表示這個 JWT 所夾帶的唯一識別訊息。
換句話說，此 JWT 中包含的聲明是關於對象的聲明。JWT 規範規定，此聲明在發行方的上下文中必須是唯一的，或者在不可能的情況下必須是全局唯一的。處理此聲明是特定於應用程序的。
  - **aud**：audience 的簡稱，用單字串(case-sensitive) 或 URI 或陣列表示這個 JWT 唯一識別的預期接收者。換句話說，當此聲明存在，則讀取此 JWT 中的數據的一方必須在 aud 中找到自己，或者無視 JWT 中包含的數據。與 iss 和 sub 要求的情況一樣，該權利要求是專用的。
  - **exp**：expiration(time) 的簡稱，一個用來表示特定日期和時間的數字，格式為 [POSIX](https://zh.wikipedia.org/wiki/%E5%8F%AF%E7%A7%BB%E6%A4%8D%E6%93%8D%E4%BD%9C%E7%B3%BB%E7%BB%9F%E6%8E%A5%E5%8F%A3) 定義的 `自紀元以來的秒數`，即 [UNIX時間](https://zh.wikipedia.org/wiki/UNIX%E6%97%B6%E9%97%B4)。此聲明設置了該 JWT 被視為無效的確切時間。一些實踐可能允許時間存在一定的偏差(考慮此 JWT 在到期日期後的幾分鐘內有效)。
  - **nbf**：not before (time) 的簡稱，`exp` 的相反，格式同 `exp`，當前時間和日期必須等於或晚於該日期和時間。一些實踐可能允許一定的偏差。
  - **iat**：issued at (time) 的簡稱，一個用來表示特定日期和時間的數字(格式同 `exp` 和 `nbf`)，即該 JWT 發行的時間。
  - **jti**：JWT ID 的簡稱，一個字串表示這個唯一識別的 JWT。此聲明可用於區分具有其他相似內容的 JWT (例如，防止重放)。取決於實現以確保唯一性。

所有的聲明，只要不在 registered claims 裡的，不是 private claims 就是 public claims。

**Private Claims**：

  是由 JWT 的使用者(消費者和生產者)定義的那些。換句話說，這些是用於特定情況的臨時聲明。因此，必須注意防止衝突(collisions)。

**Public Claims**：

  在 [IANA JSON Web Token](https://www.iana.org/assignments/jwt/jwt.xhtml) 聲明註冊表上註冊的聲明(用戶可以註冊其聲明，以防止衝突)，或者是使用抗衝突名稱命名的聲明(例如，在名稱前添加 namespace)。

## JSON Web Signatures(JWS)

**JSON Web Signatures(JWS)** 大概是 JWT 最廣泛使用的功能。通過將簡單的數據格式與定義明確的簽章演算法系列相結合，JWT 迅速成為在客戶端和中介之間安全共享數據的理想格式。

簽章的目的是允許一個或多個參與方建立 JWT 的真實性(authenticity)。真實性意味著 JWT 中包含的數據未被篡改。換句話說，可以執行簽章檢查的任何一方都可以依靠 JWT 提供的內容。需要強調的是，簽章不會阻止其他方讀取 JWT 中的內容。

檢查 JWT 簽章的過程稱為驗證(validation)或 token 驗證(validating a token)。當滿足 header 和 payload 中指定的所有限制時，token 被視為有效。這是 JWT 的一個非常重要的方面：要求實現檢查 JWT 其 header 和 payload(以及用戶要求的任何內容) 到指定的點。因此，即使 JWT 缺少簽章(如果 header 將 `alg` 聲明設置為 `none`)，它也可以被視為有效。另外，即使 JWT 具有有效的簽章，也可能由於其他原因而被視為無效(例如，根據 `exp claim`，它可能已經過期)。對具有簽章的 JWT 常見的攻擊手法，依賴於剝離其簽章，然後更改 header 以使其成為不安全的 JWT。用戶有責任確保根據自己的要求對 JWT 進行驗證。

> 註：具簽章的 JWT 定義於 JSON Web Signature spec, [RFC 7515](https://tools.ietf.org/html/rfc7515)。

### JWS 的組成：

我們在前面有提到 JWT 的組成，這邊複習一下，並關注於結構中簽章(signature)的部分。
一個具簽章的 JWT 有三個元素：`header`、`payload`、`signature`

```md
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.
eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWV9.
TJVA95OrM7E2cBab30RMHrHDcEfxjoYZgeFONFh7HgQ
```

前兩個 header 和 payload 經過 Base64 decode 後結果如下：

```json
{
  "alg": "HS256",
  "typ": "JWT"
}

{
  "sub": "1234567890",
  "name": "John Doe",
  "admin": true
}
```

具簽章的 JWT 攜帶第三部分：signature，在簡潔序列化形式(compact serialization form)中的最後一個 `.` 之後。
根據 JWS 規範，有幾種可用的簽章演算法，因此這些八位位組的解釋方式各不相同。JWS 規範要求所有符合標準的實現都支持單一演算法：

  - HMAC 使用 SHA-256，在 JWA 規範中稱為 HS256。

該規範還定義了一系列推薦演算法：

  - 使用 SHA-256 的 RSASSA PKCS1 v1.5，在 JWA 規範中稱為 RS256。
  - 使用 P-256 和 SHA-256 的 ECDSA，在 JWA 規範中稱為 ES256。

> 註：JWA 是 JSON Web Algorithms 規範 [RFC 7518](https://tools.ietf.org/html/rfc7518)

其他演算法：

  - HS384, HS512: SHA-384 and SHA-512 variations of the HS256 algorithm.
  - RS384, RS512: SHA-384 and SHA-512 variations of the RS256 algorithm.
  - ES384, ES512: SHA-384 and SHA-512 variations of the ES256 algorithm.
  - PS256, PS384, PS512: RSASSA-PSS + MGF1 with SHA256/384/512 variants.

> 由於演算法很多種這裡就不詳細說明了，大家有興趣可以從參考資料下載相關文件研究。

JWS 整個完整的產生流程(JWS Compact Serialization)：
![](https://i.imgur.com/jsX9jfv.png)
從流程圖可以看出 header 和 payload 跟先前提到的一樣就是 JSON 物件經過 Base64 編碼後的結果，而 signature 則是可以透過 secret 或 private key 對編碼後的 header 加上 payload 經過演算法完成簽章，再將簽章用 Base64 編碼後的結果。

接著讓我們動手用 ruby 簡易實作 JWS 看看：

```rb
require 'json'
require 'base64'
require 'openssl'

header = {
  "alg": "HS256",
  "typ": "JWT"
}

payload = {
  "sub": "1234567890",
  "name": "John Doe",
  "admin": true
}

encoded_header = Base64.urlsafe_encode64(JSON(header)) # Base64 編碼 header
encoded_payload = Base64.urlsafe_encode64(JSON(payload)) # Base64 編碼 payload
digest = OpenSSL::Digest::SHA256.new # 使用 SHA256 演算法
data = "#{encoded_header}.#{encoded_payload}"

# For HMAC-based signing algorithms:
signature = OpenSSL::HMAC.digest(digest, 'secret', data) # 透過 HMAC 演算法簽章
encoded_signature = Base64.urlsafe_encode64(signature).gsub('=', '') # Base64 編碼 signature
puts "HMAC-based JWT: #{encoded_header}.#{encoded_payload}.#{encoded_signature}"

# For public-key signing algorithms:
key = OpenSSL::PKey::RSA.new(2048) # 產生 RSA 公鑰/私鑰
signature = key.sign(digest, data) # 用 key 進行簽章
encoded_signature = Base64.urlsafe_encode64(signature).gsub('=', '') # Base64 編碼 signature
puts "public-key JWT: #{encoded_header}.#{encoded_payload}.#{encoded_signature}"
```

> 註：有興趣深入研究的朋友可以詳讀 [ruby-jwt](https://github.com/jwt/ruby-jwt) 的 source code。

另外，如果是具有公私鑰的簽章方式(例如，RSA 演算法)，私鑰可用於創建簽章訊息並驗證其真實性。相反，公鑰只能用於驗證簽章訊息的真實性。因此，該方案允許**一對多**的安全分發訊息。接收方可以通過保留與訊息關聯的公共密鑰的副本來驗證訊息的真實性，但是他們不能使用它創建新訊息，如下圖：
![](https://i.imgur.com/k7eLJOw.png)

而像是 `HMAC` 演算法這樣共享秘密(`secret`)簽章的方式，使用 HMAC + SHA-256，可以驗證訊息的任何一方也可以創建新訊息。如果合法用戶變為惡意用戶，則他可以修改訊息而無需其他方注意。用公鑰方案，變成惡意的用戶只能擁有他的公鑰，因此無法使用它創建新的簽章訊息。

## JSON Web Encryption(JWE)

JWS 提供了一種驗證數據的方法，而 **JSON Web Encryption(JWE)** 提供了一種使數據對第三方不透明的方法。在這種情況下，不透明意味著不可讀。
加密的 token 不能由第三方檢查。

儘管看起來加密提供了與驗證相同的保證，並具有使數據無法讀取的附加功能，但情況並非總是如此。要理解為什麼，首先需要注意的是，就像在 JWS 中一樣，JWE 本質上提供了兩種方案：共享秘密方案和公鑰/私鑰方案。

共享秘密方案通過讓各方知道共享秘密來起作用。擁有共享秘密的各方都可以加密和解密訊息。這類似於 JWS 中共享秘密的情況：擁有秘密的各方可以驗證並生成簽章 token。

但是，公鑰/私鑰方案的工作原理有所不同。在 JWS 中，擁有私鑰的一方可以簽章和驗證 token，而擁有公鑰的各方只能驗證那些 token，而在 JWE 中，擁有私鑰的一方是唯一可以解密 token 的一方。換句話說，公鑰持有者可以加密數據，但是只有持有私鑰的一方才能解密(和加密)該數據。實際上，這意味著在 JWE 中，持有公鑰的各方可以將新數據引入到交換中。相反，在 JWS 中，持有公鑰的各方只能驗證數據，而不能引入新數據。簡而言之，JWE 不能提供與 JWS 相同的保證，因此，它不能代替 JWS 在 token 交換中的作用。當使用公鑰/私鑰方案時，JWS 和 JWE 是互補的。

一種更簡單的理解方法是從生產者和消費者的角度進行思考。生產者可以對數據進行簽名或加密，因此消費者可以對其進行驗證或解密。對於 JWS，專用密鑰用於 JWS，而公用密鑰可用於對其進行驗證。生產者持有私鑰，而消費者持有公鑰。數據只能流動從私鑰持有者到公鑰持有者。相反，對於 JWE，使用公鑰對數據進行加密，而使用私鑰對數據進行解密。在這種情況下，數據只能從公鑰持有者流向私鑰持有者，即公鑰持有者是生產者，而私鑰持有者是消費者，比較表如下：

|   |JWS|JWE|
|---|---|---|
|Producer|Private-key|Public-key|
|Consumer|Public-key|Private-key|

即 JWE 與 JWS 使用相同 RSA 演算法，JWE 可以使用公鑰加密訊息，而這些訊息只能使用私鑰解密。這允許構建**多對一**的安全通信通道，如下圖：
![](https://i.imgur.com/9Z902kZ.png)

簽章和加密的流程比較圖如下：
![](https://i.imgur.com/v68jLOn.png)

> 註：加密的 JWT 定義於 JSON Web Encryption spec, [RFC 7516](https://tools.ietf.org/html/rfc7516)。

### JWE 的組成：

與具簽章和不安全的 JWT 相比，加密的 JWT 具有不同的表示形式：

```md
eyJhbGciOiJSU0ExXzUiLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0.
UGhIOguC7IuEvf_NPVaXsGMoLOmwvc1GyqlIKOK1nN94nHPoltGRhWhw7Zx0-kFm1NJn8LE9XShH59_
i8J0PH5ZZyNfGy2xGdULU7sHNF6Gp2vPLgNZ__deLKxGHZ7PcHALUzoOegEI-8E66jX2E4zyJKxYxzZIItRzC5hlRirb6Y5Cl_p-ko3YvkkysZIFNPccxRU7qve1WYPxqbb2Yw8kZqa2rMWI5ng8Otv
zlV7elprCbuPhcCdZ6XDP0_F8rkXds2vE4X-ncOIM8hAYHHi29NX0mcKiRaD0-D-ljQTPcFPgwCp6X-nZZd9OHBv-B3oWh2TbqmScqXMR4gp_A.
AxY8DCtDaGlsbGljb3RoZQ.
KDlTtXchhZTGufMYmOYGS4HffxPSUrfmqCHXaI9wOGY.
9hH0vgRfYgPnAHOd8stkvw
```

JWE 簡潔序列化(JWE Compact Serialization)包含五個元素，與 JWS 一樣，這些元素由點(`.`)分隔，並且包含在其中的數據是經過 Base64 編碼。

五個元素按照順序說明如下：

1. **The protected header**：類似 JWS 的 header。

2. **The encrypted key**：用於加密密文和其他加密數據的對稱密鑰。該密鑰是由用戶指定的實際加密密鑰加密後產生的。

3. **The initialization vector**：一些加密演算法需要的其他數據(通常是隨機的數據)。

4. **The encrypted data (ciphertext)**：加密的實際數據。

5. **The authentication tag**：該演算法產生的其他數據可用於驗證密文內容是否遭到篡改。

與簡潔序列化中的 JWS 及單一簽章一樣，JWE 支持簡潔形式的單一加密密鑰。

使用非對稱加密(公鑰/私鑰 加密)時，通常使用對稱密鑰執行實際的加密過程。而非對稱加密演算法通常具有很高的計算複雜度，因此對較長的數據序列(密文)進行加密並不是最理想的方式。想同時運用對稱(更快)和非對稱加密好處的一種方法是為對稱加密演算法生成一個隨機密鑰，然後使用非對稱演算算法對該密鑰進行加密。而這就是上面提到的第二個元素 `The encrypted key`。

一些加密演算法可以處理傳遞給它們的任何數據。如果密文被修改(即使沒有被解密)，演算法仍然可以對其進行處理。身份驗證標籤(`The authentication tag`)可以用來防止這種情況，本質上可以充當簽章。

> 註：關於使用加密演算法組成 JWE 的過程相對較複雜，這邊就不詳細說明了，有興趣的朋友可以詳細閱讀文末的參考資料。
> JWK 是 JSON Web Keys 規範 [RFC 7517](https://tools.ietf.org/html/rfc7517)，統一密鑰的表示格式允許輕鬆共享，並使密鑰有別於其他密鑰交換格式的複雜性。

## 總結

- JWS 和 JWE 是 JWT 的實作方式。
- JWA 和 JWK 是 JWT 中關於演算法和密鑰格式的規範。
- 目前普遍在用的 JWT 其實大多是 JWS，簡單說就是 Base64 Encode 過的 JSON + Signature。
- JWS 支援的 Signature 有單向跟雙向的，一般要用雙向(RS256)把公鑰跟私鑰分開，做驗證的時候才會相對安全，即發 Token 的 Server 跟 Client 用的是不同的 Key，兩邊都要驗證 JWT Signature 才能使用。
- JWS 只是有做簽章，其實是明碼傳輸，所以要注意不要放入太敏感的資料在其中，JWE 才是真正有作加密的方式。

## 參考資料

- [Introduction to JSON Web Tokens](https://jwt.io/introduction/)
- [JWT handbook](https://auth0.com/resources/ebooks/jwt-handbook)

---

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


post-是誰在敲打我窗？什麼是 JWT ？ / cover

是誰在敲打我窗？什麼是 JWT ？

post-GitLab Auto DevOps 深入淺出，自動部署，連設定檔不用？！

GitLab Auto DevOps 深入淺出，自動部署，連設定檔不用？！


大家好，新年快樂！對於現代 web 開發框架來說，登入驗證幾乎都有成熟的 library 可以使用，例如 Rails 可以搭配 Devise gem 快速的搭建一個會員登入的系統。但是如果在前後端分離的單頁式網頁（Single Page Application ，以下簡稱 SPA）上，該怎麼跟後端的 API server 好好說哈囉呢？

本文會先討論我們每天在接觸的一些網站基本原理：

- 一般網站如何實作登入
- Cookie、localStorage 與 sessionStorage
- API server 怎麼做身份登入驗證

接著會回到本文的重點

- SPA 該怎麼實作登入驗證
- Rails 和 SPA 怎麼做登入驗證

# 一般網站如何實作登入

一切的故事從這句話開始:「HTTP 是一個 stateless 的[協議](https://tools.ietf.org/html/rfc2616)」

因為每次的交談（ Request - Response）都是無狀態，所以狀態必須由 client 或 server 端來維持。因此簡單的來說透過瀏覽器登入網站的行為會有點像這樣：

![post-是誰在哈囉? 如何搞定 SPA 與 API Server 的登入驗證 / signin flow](//images.ctfassets.net/8er52l3j5u76/6S8JObWPj66FVgfgpKh4nW/5a8ef57bdaba39bf25e6f539eafcf06f/signin_flow.png)

1. 當使用者登入送出帳號密碼
2. Server 驗證帳密無誤，回傳一個「已登入」的通行證
3. 使用者瀏覽登入後的頁面，這時候就會夾帶著通行證一起發送
4. Server 確認通行證有效，然後回傳登入限定的內容

那麼這個通行證怎麽核發和保存呢？
最早的瀏覽器為了在無狀態的 HTTP 上讓 client 端可以保存這個通行證（保留登入狀態），所以發明了 cookie 這個東西。

## Cookie 可以由 Server 端設定

Server 回覆 response 給 client 的時候，可以在 response 內使用 `Set-Cookie` 來直接指定瀏覽器要設定的 cookie 內容:

```
HTTP/1.0 200 OK
Content-type: text/html
Set-Cookie: login_state=fred_is_login_passport

[page content]
```

瀏覽器收到 response 後，除了依照指示寫入 cookie，下次對這個 server 發送 request 的時候還會自動帶上這個 cookie，這樣一來就可以達到登入的狀態保存囉。

## 打開瀏覽器看看實際的狀況

我們來打開一個已經登入的 Facebook 網頁來觀察一下實際的行為。以 Chrome 為例，打開 `開發者模式` > `Application` > `Cookies` 下看看到底被設定了哪些 cookie

![post-是誰在哈囉? 如何搞定 SPA 與 API Server 的登入驗證 / facebook cookie](//images.ctfassets.net/8er52l3j5u76/54Y1C5dIHFkV4US6z42Lox/5dbe5238bb05192a83e42a982b36e666/facebook_cookie.png)

雖然不確定這些 cookie 個別的功能，但如果把他們全部清掉，Facebook 因為認不得我們所以就被登出了。

此外我們會發現 cookie 上有很多參數可以設定，他們都有各自的功能：

- `Expires/Max Age`：這條 cookie 存活的時間，過期的就不會被瀏覽器夾帶在 request 內。
- `SameSite`：限制瀏覽器不能跨站寄送 cookie
- `Secure`：只有在 HTTPS 連線下才會傳送給 server
- `HttpOnly`：開啟它會使瀏覽器執行的 JavaScript 沒辦法透過 `document.cookie` 來讀取到這條 cookie
- `Domain` 和 `Path`：定義 cookies 應該被送到哪些 url

（更多細節可參考 [MDN 的說明](https://developer.mozilla.org/zh-TW/docs/Web/HTTP/Cookies) )

# Cookie、localStorage 與 sessionStorage
除了 Cookie 之外，瀏覽器們接著又發展出了 localStorage 和 sessionStorage 來讓我們放東西，不過他們可以做到的事情不太一樣，先來個比較表吧：

|| Cookie | localStorage | sessionStorage
-------|------|----------------|-------------
Server 端設定 | O | X  | X
Client 端設定 | O | O  | O
Size | 4k | ~5mb | ~5mb
Request 自動夾帶| O | X | X
前端 js 易用性 | 差  | 好 | 好
保存期限| 可由server 端設定 max age, client 端生成的在關閉後就清空| 同源的網頁可以存取，關閉網頁重開後還會存在 | 關閉頁面後就不存在

瀏覽器對這些新夥伴也提供了好操作的 API 供使用，以 localStorage 為例：

```js
localStorage.setItem('myCat', 'Tom');
var cat = localStorage.getItem('myCat');
localStorage.removeItem('myCat');
localStorage.clear();
```

倒是最早發展的 cookie 卻沒有類似的 api 讓人使用，除非要自己[包裝](https://stackoverflow.com/questions/10484090/how-to-get-key-value-from-cookies-which-was-set-in-javascript-asp-net-mvc3)。一開始覺得這件事情也太奇怪，難道使用 cookie 就是老窮殘？

不過到後來我才了解到：「Cookie 其實是不太希望 client side 來操作的」

原因是因為假如我們的前端網頁如果很容易存取到這些資訊的話，相對的它也容易暴露在風險之中！例如 localStorage 和 sessionStorage 雖然容易在瀏覽器內使用 js 操作，但假如網站被植入惡意 js 程式碼，你放在 localStorage 上的東西就會被盜用了（這個手法叫做 XSS 攻擊）。因此像是一些 credential 的東西，其實是不適合放在 localStorage 和 sessionStorage 內。

# API Server 通常怎麼交換登入通行證

先不考慮 SPA 的場景下，API server 是怎麼做身份驗證呢？

比較常見的 API server 的登入流程：

(1) client 對 server 的登入 api 發送帳號密碼

```
POST /signin
Host: api.hello-who.com
Content-Type: application/json

{
  "username": "fred",
  "password": "fredsecretpassword"
}
```

(2) Server 端驗證後核發通行證（token），一般來說可能是用 json 格式回傳給 client

```
{ "token":"AbCdEf123456" }
```

(3) Client 端如果要存取限制的資源，就會把 token 夾帶在 request 的 `Authorization` Header 裡

```
GET /secret_cats
Host: api.hello-who.com
Authorization: Bearer AbCdEf123456
Content-Type: application/x-www-form-urlencoded
```

(4) Server 端會先驗證 `Authorization` header 內的 token 是否合法，再回傳請求的資源。

(5) 如果 Server 段驗證 token 不合法，則回傳 `401 - Unauthorized`

_（實際上可能會有很多的實作細節可以探討，例如 token 使用 JWT、驗證方式採用兩階段登入、oauth 2 等等的。）_

但如果這個方法套用在純前端的單頁式網頁上，就會遇到一個問題：

「瀏覽器端該如何保存這個回傳的 token 呢？」

前面我們已經提到，如果在 client side 設定 cookie、localStorage 和 sessionStorage 看起來似乎都不太安全，那該怎辦才好？

# SPA 該怎麼實作登入驗證

假如我們今天的 client 端是瀏覽器的情況下，較安全保存 credentail 的方式還是從 server 端透過 `Set-Cookie` 的方式來設定。

你以為這篇文章就這樣結束了嗎？

其實要能動，還有很多需要處理的細節...

## Same Origin Policy 的問題

瀏覽器都有實作同源政策，基於安全性考量它限制了兩個不同網域來源互動行為。要怎麼認定是否同源以及相關的規範可以參考[相關的資料](https://developer.mozilla.org/zh-TW/docs/Web/Security/Same-origin_policy)，這裡只簡單提到我們可能會遇到的問題：

> 瀏覽器的 api 請求與 server 不同源

如果你的 SPA 所在的 domain 跟 api server 是同一個網域當然是可以爽爽用... 但通常可能會是 SPA 所在的 url 是 `www.hello-who.com`，api server 的 url 是 `api.hello-who.com`，這種情況就不屬於同源了。
XMLHttpRequest（也就是俗稱 AJAX 啦）想要發送跨來源請求，是會被瀏覽器阻擋下來的。

通常要允許跨域的問題，要在 server 端設置一些允許跨域的 response header (CORS)

```
Access-Control-Allow-Origin: *
// 但這樣設定是裸奔啦，基本上不建議設全開
```
當瀏覽器知道你的 web server 是允許跨域存取的時候，就會幫你把 AJAX 的請求發出去

> cookie 同源的問題

cookie 依樣會有同源的問題需要處理。cookie 上可以設置 `Domain` 和 `Path`，這可讓瀏覽器知道他是作用在哪個網域上。所以說如果 API server 設定 cookie 的 Domain 是 `api.hello-who.com` 的話，前端網站 `www.hello-who.com` 再次發送請求的時候，原本那張 cookie 是不會被帶到發往 `api.hello-who.com` 的 request 上的。

## CSRF 的問題

Cross-site request forgery 跨站請求偽造的手法就是惡意網站用釣魚手法讓你送出你已經拿到 cookie 的網站請求。舉個例子：

![post-是誰在哈囉? 如何搞定 SPA 與 API Server 的登入驗證 / csrf](//images.ctfassets.net/8er52l3j5u76/6rUrrh6yG6Qu7EtDknzpfs/989dd99c2d144ff02fc3ea41d51f5b33/csrf.png)

*(Image credit: Venkatesh Sundar)*

1. 使用者已經登入了銀行網站
2. 駭客用社交攻擊手法讓你打開釣魚網站，該網站有偷偷嵌入銀行的 form 表單（例如說轉帳的表單）
3. 使用者在不知情的狀況下在釣魚網站對銀行送出這個 form 表單，因為也登入了銀行取得了 cookie，所以也會一併的帶上 cookie。
4. 駭客開心收到你的轉帳。

所以 cookie 被惡意網站內嵌的 form 表單偷渡了。

>ㄟㄟㄟ那說好的同源政策呢？

... 瀏覽器的同源政策只能限制 JavaScript 程式碼跨域的行為，對原生 html tag 卻沒效力！！！！！

（其實 cookie 上的 `SameSite` 的參數就是用來保護 csrf 的，但是因為蠻新的所以不確定所有的瀏覽器都有實作這段）

所以最常見的防護手法，就是 server 端先另外交給 client 端一個 `csrf token` （第二個通行證），server 端下次收到請求的話除了會驗證 cookie，也要驗證使用者有沒有帶上 csrf token。

## 盤點一下到底要我們要處理什麼事情

看來有很多細節要注意：

- SPA 登入後， Server 端要設定 cookie
- Server 端要設定 CORS
- SPA 和 server 要處理 cookie 跨域的問題
- SPA 和 server 要建立 csrf token 交換的機制

# Rails 和 SPA 怎麼做登入驗證

講了辣麼多，就來說說 Rails 怎麼蓋一個給 SPA 用的 api server 吧。

## 處理 cookie：Rails 的 Session store
Rails 有一個 `session` 方法來維持 client server 的 狀態，他預設的方式就是採用 cookies session storage 來存放，而且貼心的幫你加密（放在 `config/secrets.yml` 的那串東西，所以那串 key 請小心保存），簡單的說這還蠻符合我們希望透過 cookie 來發送通行證的想法，並且還送你一個加密功能，好棒棒！

所以我們要做的，當使用者成功透過 api 登入後，把可以辨識使用者的辨識碼寫入 session 內：

```rb
session[:user_id] = user.id
```

這裡用 user id 來代替，你可以依照使用情境自己產生 uniq token 或 jwt token。Rails server 會在這次的 response 加上 setCookie 回給使用者的瀏覽器。

如果你要驗證使用者有沒有登入，可以在 controller 上面加上一個驗證用的 before action 類似這樣：

```rb
def autenticate_spa_user!
  user_id = session[:user_id]
  @current_user = User.find(user_id)
  render unautorized_response if @current_user.nil?
end
```

## Protection From Forgery （處理 CSRF）

使用過 Rails 開發的人都知道它在一般網站的情境下預設提供了 [Protection From Forgery 的機制防範 CSRF](https://guides.rubyonrails.org/security.html#csrf-countermeasures)，但我們該怎麼把搬到 API 模式上來呢？
- Rails 有提供一個 `form_authenticity_token` 可以讓我們手動生成 token
- 透過 cookie 的方式來交換 CSRF token：cookie 可以很方便做 token 的傳遞，而 JavaScript 在處理 api request 的知名 library [axios](https://github.com/axios/axios) 有很方便的方法可以處理在 cookie 內的 CSRF token。

#### Rails 端的設定

實作上可以在直接在 ApplicationController 上直接加個 before_action：

```rb
class ApplicationController < ActionController
  before_action :set_csrf_cookie

private

  def set_csrf_cookie
    cookies['CSRF-TOKEN'] = form_authenticity_token
    # 'CSRF-TOKEN' 可以自己取別的名字
  end
end
```

> 這裡做了兩件事情。form_authenticity_token 實際上會亂數產生一組 token 並且在 Rails 內建立一個 `session[:_csrf_token]`，但是 Rails 下次並不會拿這個 session cookie 來直接驗證，而是要前端自己把 token 放在 request header 'X-CSRF-Token' 裡面打上來驗證。既然前端要使用，就必須另外塞 cookie 給它，這樣前端才可以透過 `document.cookie` 拿出來使用！

#### 前端 axios 的設定

設定前端 axios 發送 request 的時候可以帶上 csrf token：

```js
axios
  .get("/my-stuff", {
    headers: { "X-CSRF-Token": getCookie("CSRF-TOKEN") }
  })
  .then(response => {
    const myStuff = response.data;
    // render my stuff
  });
```

或者，可以直接指定為 default 值

```js
axios.defaults.xsrfCookieName = "CSRF-TOKEN";

axios.defaults.xsrfHeaderName = "X-CSRF-Token";

axios.defaults.withCredentials = true;
```

> 設定 withCredentials = true 目的是為了在發送 request 的時候可以讓瀏覽器帶上跨域的 cookie

## 開啟 Cross-Origin Resource Sharing（CORS 允許跨域）
為了讓解決跨域的問題（就是那個同源政策啦），我們要在 Rails 上設定 CORS

首先要安裝 rack-cors gem，它可以讓我們在 Rails 中設定 allow origins 的 response header。

請在 `Gemfile` 中新增這個 gem 然後記得下 `bundle install`：

```ruby
gem 'rack-cors'
```

接著新增一個 cors 使用的 initializer ，origins 請設定你的前端網域，

```ruby
# config/initializers/cors.rb
Rails.application.config.middleware.insert_before 0, Rack::Cors do
  allow do
    origins 'localhost:8080'
    # 如果要上 production 的話記得要換成 production site 網址

    resource '*',
      headers: :any,
      methods: [:get, :post, :put, :patch, :delete, :options, :head],
      credentials: true
  end
end

```

> 註：這裡常常有人很海派的把 `origins` 設為 wildcart (`*`)，除了這樣等於在外裸奔以外，如果 xhr 要交換 cookie（credentails: true）的狀況下，瀏覽器是會阻擋 wildcard orgins 帶上 cookie 的！

> 註：`credentials: true` 是為了跟 axios 設定 `.withCredentials = true;` 做搭配

#### 把 csrf 的 original check 關掉

雖然通過了瀏覽器的同源政策，但 Rail 的 protection from forgery 機制還是會去比對 origin，所以我們要在這份 initializer 下面多新增一個設定，把同源 csrf 檢查關閉：

```ruby
# config/initializers/cors.rb
# ...

Rails.application.config.action_controller.forgery_protection_origin_check = false
```

## Rails 在 API 模式下的設定

如果你的 rails 是透過 api 模式下長出來的（ `rails new my_api_server --api`）會少裝很多東西，包含我們需要的 Session 和 Cookie，所以要記得要補上：

```ruby
# application.rb
class Application < Rails::Application
  config.load_defaults 5.2

  config.api_only = true

  config.middleware.use ActionDispatch::Cookies
  config.middleware.use ActionDispatch::Session::CookieStore
end
```

另外如果你的 controller 是繼承 `ActionController::API` 的話，也要加上我們需要的 cookie 和 protect_from_forgery 功能：

```ruby
class ApplicationController < ActionController::API
  include ActionController::Cookies
  include ActionController::RequestForgeryProtection

  protect_from_forgery with: :exception

  # ...

end
```

## 前端使用 localStorage 來暫存登入狀態

雖然 Rails 在登入成功的時候會把登入狀態寫入 cookie，但因為這個 cookie 已經被設定 `HttpOnly`，其實前端沒辦法讀取。

我們可以在登入成功後在 localStorage 塞一個登入中的 flag，用來暫存登入狀態：

```js
axios
  .post("/session", { username, password })
  .then(response => {
    localStorage.setItem("loggedIn", true);
  })
```

>註：因為這個 flag 並不是特別的機密資訊，所以放在 localStorage 是沒什麼問題的

或者更近一步可以請 rails server 在登入成功後回傳 user name 之類的基本資訊，我們就可以暫存在 localStorge 加以利用。

```js
axios
  .post("/session", { username, password })
  .then(response => {
    localStorage.setItem("user", JSON.stringify(response.data));
  })
```

# 其他補充

> 簡單的 Devise token auth 範例

先前幫我們公司 [ASTRO camp](https://astro.5xruby.tw/) 的學員寫過一篇示範 Devise 使用 API 登入的文章：「[在 Rails API 中使用 Devise 驗證](https://www.spreered.com/rails_api_devise_login/)」，主要是手把手示範怎麼在已使用 Devise 的狀況下產生 token 以及核發 token，算是很粗淺的 tutorial。實際上還是建議依據 client 端的情況，設計較安全的驗證機制！

> jwt_sessions

因為礙於篇幅本篇沒討論 JWT 相關的機制，但如果在 rails 中想要使用，可以參考 [jwt_sessions](https://github.com/tuwukee/jwt_sessions) gem。如果你有看完本篇討論的內容，會發現 jwt_sessions 也實作了很多相關的機制（session cookie、csrf）。

# 小結

單頁式網頁 Single Page Application 是近年來前端大爆發的產物，但整篇下來我們其實都在探討以下的原理：

- HTTP stateless 的特性
- 在 HTTP 上如何保存 state：cookie、localStorage 和 sessionStorage 的比較
- 瀏覽器的同源政策
- 常見的攻擊手法：XSS, CSRF

藉由這個題目讓我們順便好好研究一下這些議題，瞭解 client 和 server 如何好好的說哈囉，新的一年也要開發出安全可靠的 web application！

>上面每一個主題仔細探究都可以寫一整篇文章，怕離題太多所以很多細節都只能稍微帶過，如有未盡深感抱歉。假如你是剛接觸網路開發的朋友，建議可以個別用這些關鍵字來做深入研究！

感謝收看，我們下次見～（揮手）

# 參考資料

- [Authentication in SPA (ReactJS and VueJS) the right way](https://medium.com/@jcbaey/authentication-in-spa-reactjs-and-vuejs-the-right-way-e4a9ac5cd9a3)
- [w3c-JavaScript Cookies](https://www.w3schools.com/js/js_cookies.asp)
- [w3c-HTML5 Web Storage](https://www.w3schools.com/html/html5_webstorage.asp)
- [開發者必備知識 - HTTP認證（HTTP Authentication）](https://carsonwah.github.io/http-authentication.html)
- [MDN - Same-origin policy](https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy)
- [和 CORS 跟 cookie 打交道](https://medium.com/d-d-mag/%E5%92%8C-cors-%E8%B7%9F-cookie-%E6%89%93%E4%BA%A4%E9%81%93-dd420ccc7399)
- [Using Rails Session Cookies for API Authentication](https://pragmaticstudio.com/tutorials/rails-session-cookies-for-api-authentication)

---

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


post-是誰在哈囉? 如何搞定 SPA 與 API Server 的登入驗證 / cover

是誰在哈囉? 如何搞定 SPA 與 API Server 的登入驗證


image via [Imaiges](https://www.imaiges.com)

上次的敝司的~~大頭目~~紅寶石鑑定商寫了 [你看過 Elixir 嗎？如果沒有，現在讓你看看！](https://5xruby.tw/posts/have-you-met-elixir)，介紹了 Elixir 這個語言許多有趣的特色。我想要接著來談這門語言另一個非常核心的元素：**Pattern matching**。

由於 Ruby (及新的 JavaScript ES6) 都有 destructive assignment，所以可以這樣指派變數：

```ruby
# Ruby
a, b = [1, 2]
#=> a 是 1， b 是 2
```

那如果我們這麼做， `a` 會是多少呢？

```ruby
a, a, b = [1, 2, 3]
```

答案是 `a` 是 `2`。因為 `a` 先被指派為 `1`，緊接著又被指派為 `2`。

上次文章中有提到過函數式編程 (functional programming) 裡的 **functional** 這個字，指的是數學上的函數。而在數學上，當你說 `y = ax + b` 時，那個等號 `=`，並不是我們在 Ruby, JavaScript 語言裡學到的指派。而是說**當輸入 x 時，y 會依函式的定義，計算出一個固定值**。一樣的 **x** 輸入，永遠會是一樣的結果。

如果我們在 Elixir 上試著寫出一樣的程式，會發生什麼事呢？
```elixir
[a, a, b] = [1, 2, 3]

\#=>  ** (MatchError) no match of right hand side value: [1,2,3]
```

Elixir 告訴你，「同學同學，`a` 不可能同時是 `1` 又是 `2`。~~你的數學老師在你後面，他非常火。~~」

## Pattern Matching: 找個辦法讓等號左右兩邊比對成功

但是如果我們把上面的例子改寫成這樣，Elixir 就會接受了：
```elixir
[a, a, b] = [1, 1, 3]

\#=> [1, 1, 3]
```

在 Elixir 中的等號，並不是單純的變數指派。而是 pattern matching，樣式比對：

> 把等號左邊的模式，跟右邊的值比對看看。如果有辦法找到讓等式成立的情況，那就幫你綁定變數。

而讓我們剛剛那個等式成真的方法，就是讓 `a` 綁定成 `1`，`b` 綁定成 `3`。

所以也可以這樣用：

```elixir
[a, 3, b] = [1, 2, 3]

\#=> ** (MatchError) no match of right hand side value: [1,2,3]

[a, 2, b] = [1, 2, 3]

\#=> [1,2,3]
```

### 串列比對與連續比對

```elixir
[head | tails] = [1, 2, 3, 4]

\#=> head 是 1，tails 是 [2, 3, 4]
```

`|` 是串列比對中切開首值及剩下的串列的方式，如同 LISP 中的 `car` 及 `cdr`。

而由於每個比對本身會是一個有回傳值的 **expression**，那麼可以**一直比下去**也是很合理的：
```elixir
[h | t] = [1, b, c, d] = [1, 2, 3, 4]

\#=> b = 2, c = 3, d = 4
\#=> h = 1, t = [2, 3, 4]
```

只要最右邊能求出**所有的值**，中間的比對都成功，那麼就可以一次綁定多個變數了。

### `_`： 我不在乎這個

在 pattern matching 時，常常會遇到你只想要確保一部份的值或是資料結構，而不在乎其它地方，就可以利用 `_`  來進行 pattern matching。 例如我只想要將串列中前兩個元素綁定成變數，後面有什麼干我 P 事，就可以這樣做：

```elixir
[a, b | _] = [1, 2, 3, 4, 5]

\#=> a = 1, b = 2
```

一個比對裡，可以使用多個 `_` 。如果覺得這樣讓程式很難讀，可以改成用**底線開頭的變數**，效果是一樣的。

```elixir
[first, _second, third | _tails] = [1, 2, 3, 4, 5]
#=> first = 1, third = 3
#=> 雖然可以用 _second 及 _tails 拿到值，但是 Elixir 會噴警告給你。
```

### `^`： 將變數求值進行比對

當某個變數已經被綁定好值了，你接著想要用這個值來進行比對，可以使用 Pin operator: `^`

```elixir
a = 0

[^a, b, 2 | _tails] = [0, 1, 2, 3, 4]

\#=> b = 1
```

## 函式的 pattern matching

除了等號之外，Elixir 函式定義的參數部份，也是個 pattern matching。

```elixir
defmodule Shape do
  def area({:square, w}), do: w * w
  def area({:circle, r}), do: r * r * 3.14
  def area({:rectangle, w, h}), do: w * h
end

Shape.area({:square, 5}) #=> 25
Shape.area({:circle, 10}) #=> 314
Shape.area({:rectangle, 5, 10}) #=> 50
```

在呼叫函式時，會由上而下用參數去比對函式的每一個區塊 (clause)，如果找到可以成功比對的，就進入該區塊執行。

### 還可以多加一點判斷

除了在函式宣告的參數部份比對之外，Elixir 還提供了[Guards](https://hexdocs.pm/elixir/master/guards.html) 來做稍微複雜一點的判斷：

```elixir
defmodule Alcohol do
  def check_age(_, age) when age < 18, do: "你年紀太小囉"
  def check_age(name, _), do: "歡迎，#{name}"
end
```

所以要寫出遞迴版本的費波那契數列，在 Elixir 裡就很簡單了：

```elixir
defmodule Fibonacci do
  def get(1) when n == 0 or n == 1, do: n
  def get(n), do: get(n - 1) + get(n - 2)
  def list(n), do: for x <- 0..n - 1, do: get(x)
end
```

## 小結
Pattern matching 在 Elixir (及許多函數式編程語言，如 Haskell) 中扮演了非常重要的角色。可以讓你寫出非常簡潔而且易懂的程式，而且會讓你開始習慣用**找出邊界情況**及**遞迴**的角度，來思考如何組織程式。

---

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

當然最後還是要廣告一下，今年四月 [Ruby X Elixir Conf Taiwan 2018](https://2018.rubyconf.tw/) 研討會，有邀請到 Elixir 的作者 [José Valim](https://twitter.com/josevalim)，還有許多精采的相關講題喔！我們近期也會舉辦相關的 Elixir 活動，就敬請持續關注我們的活動通知吧！

Happy hacking! 下次見。

post-等號究竟是什麼意思？ Elixir 裡的 pattern matching / cover

等號究竟是什麼意思？ Elixir 裡的 pattern matching


這是很多年前的事情了，當時看到別人的 Chrome 竟然會說話，讓我震驚了很久。但是花了很多年都沒有找到要怎麼做，不過最近因為一些關係，我終於知道了他的秘密！
<br>
<br>
首先，這不是鬼故事！這篇文章要討論的是 Web Speech API 這個由 Google 所提交的功能。主要就是做「語音轉文字」跟「文字轉語音」兩件事情，像是有在玩遊戲可能有用過 Discord 這種類似 Slack 的通訊軟體，裡面提供的朗讀功能應該就是透過這個 API 實作的。

## Web Speech API

在 Web Speech API 裡面其實只有兩個功能「語音轉文字」跟「文字轉語音」兩種。文字轉語音的功能可能比較常見，我們可以在像是在一些地方看到。

像是 Google 搜尋右邊的「麥克風」圖示，就是利用 Web Speech API 所製作的功能，讓我們可以利用講話的方式直接輸入搜尋的關鍵字。

![Google 搜尋的語音框](https://blog.frost.tw/images/my-chrome-can-speak/screenshot.png)

另外就是將文字念出來，也就是這篇文章要討論的內容。

## Hello World

那麼，要怎麼讓 Chrome （或者 Firefox 發出聲音呢？）

```js
var msg = new SpeechSynthesisUtterance('Hello World');
window.speechSynthesis.speak(msg);
```

首先，我們要產生出一個 `SpeechSynthesisUntterance` 物件，把要講的東西放進去。然後再透過 `speechSynthesis` 提供的 `speak` 把他唸出來。

```js
var msg = new SpeechSynthesisUtterance('世界你好！');
window.speechSynthesis.speak(msg);
```

當然，講中文也是完全沒有問題的。

> 主要是這個 API 預設會用作業系統（Ex. macOS 的 VoiceOver 功能）所以不管是哪個瀏覽器預設都會用同樣的聲音講話。

## 調整語音

因為作業系統中可能會針對各種國家的語言提供語音，所以同樣是中文，我們也可以從 `zh-TW` 切換到 `zh-HK` 讓他用廣東話的方式念出來。

```js
var voices = window.speechSynthesis.getVoices();
var msg = new SpeechSynthesisUtterance('世界你好！');
msg.voice = voices[35]; // 每台電腦/瀏覽器結果可能略有不同

window.speechSynthesis.speak(msg);
```

> 目前似乎只有 Safari 可以正常使用，其他瀏覽器不一定可以用。

另外就是 `SynthesisUtterance` 還有幾個參數可以玩。

* `pitch` - 語調 0 ~ 2 設定，越大音越高
* `volume` - 音量

## 小結

這個功能在某些應用情境，像是聊天機器人。或者類似 Discord 這種通訊軟體，算是很有用的。不過似乎很少人在討論，就算是 Google 查詢「Speech API」也還不一定會看到，不過作為一個有趣的小功能倒是值得一試。

> 印象中可以選擇男聲或者女聲，但是找不到。也許是 Chrome 裡面提供的語音包才有，不過目前 Chrome (66.0) 似乎切換語音不太正常，就暫時無法測試。

---

## 參考文章

* http://blog.zhusee.in/post/56286985943/web-speech-api-part-i-using-speech-synthesis-to-make-bro
* https://developers.google.com/web/updates/2014/01/Web-apps-that-talk-Introduction-to-the-Speech-Synthesis-API

原文刊載於[弦而時習之](https://blog.frost.tw/posts/2018/05/30/My-Chrome-can-speak/#more)


技術文章