## 前言
在學習前端的的過程中，多少一定都有聽過 Webpack 這個名詞，而什麼是 Webpack 呢？當我聽到這個問題的時候，第一時間會先愣住，不知從何回答起，經過幾秒鐘的思考後，最後回答會是「它是一個模組打包工具」，不知道大家有沒有和我一樣呢？這個回答沒有錯，不過可能會有更多疑問，那模組又是什麼？為什麼需要打包？

這篇文章，將從模組化切入，來帶大家了解 Webpack 究竟幫我們做了多少事？
## 模組化
### 為什麼需要模組化設計?
試著回想我們最開始學習 JavaScript 的時候，我們會把程式碼寫在 HTML 檔案中，如下

```html
// index.html

<script>
    var a = 1

    function double(x){
        return 2 * x
    }

    double(a)
</script>
```

但隨著功能越來越多我們會把 `script` 裡面的內容獨立出來到一個 JS 檔中：

```html
// index.html

<script src="./main.js"></script>
```

```javascript
// main.js

var a = 1

function double(x){
    return 2 * x
}

double(a)

var b = 2

function square(x){
    return x * x
}

square(b)

var c = 4

function add(x, y){
    return x + y
}

add(c, b)
```

再來想像一下，當開發人員越來越多，功能也一直再新增，如果都繼續編寫同一個 JS 檔，當行數不再是 24 而是 1000，將變得非常難以閱讀及維護。為了避免這樣的情況發生，我們可以拆成多個 JS 檔，如下

```html
// index.html

<script src="./utils.js"></script>
<script src="./main.js"></script>
```
```javascript=
// utils.js

function double(x){
    return 2 * x
}

function square(x){
    return x * x
}

function add(x, y){
    return x + y
}
```

```javascript
//main.js

var a = 1
var b = 2
var c = 4

double(a)
square(b)
add(c, b)
```

目前我們雖然把程式碼分開了，但實際上它還是在同一個作用域下，其中的變數是會互相影響。例如，我新增了一個 utils2.js 檔，並宣告一個 `add` 函式，且實作內容和 utils.js 中的 `add` 函式不一樣，如下

```html
// index.html
<script src="./utils.js"></script>
<script src="./utils2.js"></script>
<script src="./main.js"></script>
```

```javascript
// utils.js

function add(x, y){
    return x + y
}
```

```javascript
// utils2.js

function add(x, y){
    return x + y + 4
}
```

```javascript
//main.js

var b = 2
var c = 4

console.log(add(c, b)) // 10
```
如果我們期望在 main.js 使用 `add` 函式會得到兩數之和，會因為 utils2.js 在 utils.js 後面載入，而覆蓋掉 utils.js 的函式宣告，最後導致結果出現不如預期。所以我們需要將 utils.js 與 utils2.js 這兩個檔案的內容各自獨立出來，互不干擾，而想要達到這樣的效果，我們可以使用 IIFE 來完成。

#### IIFE（立即呼叫函式 Immediately Invoked Functions）

```javascript
// utils.js

var moduleUtils = (function(){
    var author = 'Mr.A'

    return {
        add: function(x, y){
                return x + y
            },
        getAuthor: function(){
            return author
        }
    }
})()
```

```javascript
// utils2.js

var moduleUtils2 = (function(){
    var author = 'Mr.B'

    return {
        add: function(x, y){
                return x + y + 4
            },
        getAuthor: function(){
            return author
        }
    }
})()
```

```javascript
//main.js

var b = 2
var c = 4

console.log(moduleUtils.getAuthor()) // 'Mr.A'
console.log(moduleUtils.add(c, b)) // 6

console.log(moduleUtils2.getAuthor()) // 'Mr.B'
console.log(moduleUtils2.add(c, b)) // 10
```

透過立即呼叫函式的方式，建立作用域幫我們達到三點效果：
1. 解決變數或是函式命名上的衝突
2. 能夠建立私有變數與方法
3. 自由選擇要將哪些變數、方法暴露出去

因此，我們打算在 main.js 檔案中，取得變數 `author` 的值，只能透過 `moduleUtils.getAuthor()` 的方法。最值得注意的地方是，這樣子規劃，只能讀取而無法直接修改。這種模式就是最一開始模組化的概念，稱為模組模式。

這個模式看起來好像很完美了，但其實還是有一個小問題。假設 utils2.js 這個模組需要依賴 utils.js 的方法或是變數，我們就一定要注意 script 引入的先後順序，如下

```javascript
// utils.js

var moduleUtils = (function(){
    var author = 'Mr.A'

    return {
        getAuthor: function(){
            return author
        }
    }
})()

```

```javascript
// utils2.js

var moduleUtils2 = (function(module){
    var author = 'Mr.B'
    var authorFromUtils = module.getAuthor()

    return {
        getTwoAuthors: function(){
            return author + '_&_' + authorFromUtils
        }
    }
})(moduleUtils)
```

```javascript
//main.js

console.log(moduleUtils.getAuthor()) // 'Mr.A'
console.log(moduleUtils2.getTwoAuthors()) // 'Mr.B_&_Mr.A'
```
```htmlembedded=


<script src="./utils.js"></script>
<script src="./utils2.js"></script>  
<script src="./main.js"></script>
```
隨著相依性的檔案越來越多，專案的維護難度也會隨之提高。

综合以上，隨著前端專案規模越來越大，就越需要模組化的開發，來提升專案的維護性。隨著趨勢的發展，就有些模組化的規範相繼而出，而其中最為有名的就是 CommonJS。

## Node.js 與 CommonJS
Node.js 能夠讓 JavaScript 在 server 環境中執行，並採用了 CommonJS 模組規範。所以在 server 端來說，每個檔案都是獨立的作用域，且都有 `require` 函式和 `module` 物件。

1.`module` 物件
每個檔案都會有 `module` 物件，這個物件底下有一個 `exports` 的屬性，如果在這個檔案中有想要輸出的變數或是方法，可以透過賦值給 `exports` 來達成，如下

```javascript
// 只有單一值
var name = 'will'

module.exports = name
```

```javascript
// 多個值 第一種寫法
var name = 'will'

module.exports.name = name
module.exports.getName = function(){
    return name
}
```

```javascript
// 多個值 第二種寫法
var name = 'will'

function getName(){
    return name
}

module.exports = {
    name,
    getName
}
```

2.`require` 函式

當需要載入某檔案，取得 `module.exports` 的值時，會使用 `require` 函式尋找該檔案，如下

```javascript
// a.js
var name = 'will'

module.exports.name = name
module.exports.getName = function(){
    return name
}

// b.js
var aModule = require('./a.js')
aModule.getName() // will
```

了解 CommonJS 規範之後，我們就可以很輕鬆的將之前的範例改寫，如下

```javascript
// utils.js

var author = 'Mr.A'

function getAuthor(){
    return author
}

module.exports.getAuthor = getAuthor
```

```javascript
// utils2.js

var moduleUtils = require('./utils')

var author = 'Mr.B'
var authorFromUtils = moduleUtils.getAuthor()

function getTwoAuthors(){
    return author + '_&_' + authorFromUtils
}

module.exports.getTwoAuthors = getTwoAuthors
```

```javascript
//main.js
var moduleUtils = require('./utils')
var moduleUtils2 = require('./utils2')

console.log(moduleUtils.getAuthor()) // 'Mr.A'
console.log(moduleUtils2.getTwoAuthors()) // 'Mr.B_&_Mr.A'
```

這樣寫相較 IIFE 簡單多了，但別忘了改成這樣子，實際上是沒辦法在瀏覽器上執行的，只能在 Node.js 環境下執行。既然瀏覽器不支援，要怎麼樣才能在瀏覽器執行？我們可以借助其他工具，也就是 Webpack，它會將我們的模組翻譯成瀏覽器支援的寫法，並且打包成一個壓縮過的 JS 檔。

不過在介紹 Webpack 之前，相信有些人會有疑惑，在寫專案都沒有使用 `require` 或 `module.exports` ，都是用 ES6 的 `import` 和 `export` ，而且瀏覽器也有支援，那為什麼還需要 Webpack？ 在回答這個問題之前，先來認識一下 ES6 Module。

## ES6 Module
在 ES6 以前，沒有正式的模組化規範，所以有各種模組化的寫法，像是上面介紹的 CommonJS，或是 AMD (Asynchromous Module Definition 非同步模組定義)等等。而 ES6 出來之後，終於有了正式的規範，就是上面提到的 `import` 與 `export`，我們可以再把上面的例子用 ES6 Module 改寫，如下

```javascript
// utils.js

let author = 'Mr.A'

export function getAuthor(){
    return author
}
```

```javascript
// utils2.js

import { getAuthor } from './utils.js'

let author = 'Mr.B'
let authorFromUtils = getAuthor()

export function getTwoAuthors(){
    return author + '_&_' + authorFromUtils
}
```

```javascript
//main.js
import { getAuthor, author } from './utils.js'
import { getTwoAuthors } from './utils2.js'

console.log(getAuthor()) // 'Mr.A'
console.log(getTwoAuthors()) // 'Mr.B_&_Mr.A'
```

```html

<script src="./main.js" type="module"></script>
```

依照目前的使用情境，看起來都沒有什麼太大的問題，但假設我們想要使用別人的套件呢？或許我們可以使用 CDN 引入，但如果說這個套件也沒有 CDN，我們就只能透過 NPM 或 Yarn 這類型的套件管理工具來下載。

套件下載完畢後，會放到 node_modules 這個資料夾裡，這樣子我們引入的路徑就可能要改寫成 `'./node_modules/xxx/index.js'` 這樣子。假設哪天套件的入口點換了，整個專案有使用到這個套件的都需要改寫，這樣其實很不方便。除此之外，有些套件輸出是寫 `module.exports`，我們也沒辦法使用 `import` 來引入，因此這個時候，我們就需要藉由 Webpack 的幫助。

## Webpack 

### 初步認識 Webpack

在前面我們就有提到，Webpack 是一模組打包工具，不管我們是寫 CommonJS 又或是 ES6 Module 最終它會將我們的模組以及使用 NPM 安裝他人的模組一併打包成一個 JS 檔。接著讓我們來實際試試看如何使用 Webpack 打包。

如果上面的有跟著練習的話，目前的專案目錄會是這樣子

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

1.開啟終端機輸入下面兩行指令

```
npm init -y 
npm install webpack webpack-cli --save-dev
```
順利的話，就會看到我們的目錄新增了兩個檔案分別是 package.json 和 package-lock.json，以及 node_modules 的資料夾

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

2.打開 package.json 並在 scripts 底下新增指令

```javascript
// package.json
{
  "scripts": {
    "build": "webpack" 
  },
}
```

3.新增 webpack.config.js 檔案

```javascript
// webpack.config.js
module.exports = {
  mode: 'development', 
  entry: './main.js', // webpack 打包的起始檔案
  output: {
    path: __dirname, // 在這個 config 檔同層的目錄
    filename: 'bundle.js'// 打包輸出的檔名
  }
}
```

`mode` 這個屬性不寫的話預設會是 `production`，代表在生產環境下使用，所以會自動幫你壓縮以及優化。`development` 這個模式代表開發的時候，打包的速度較快。

最後在終端機下
```
npm run build
```
執行之後順利的話就會出現建置的成功訊息

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

接著修改我們 index.html，將 main.js 換成 bundle.js

```html

<script src="./bundle.js"></script>
```

打開瀏覽器 console 之後，就會順利看到我們在 main.js 檔 `console.log` 的結果

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

這樣我們就成功地使用 Webpack 來幫我們把模組打包，不過目前為止我們還沒嘗試安裝套件來使用，接下來我們來試著安裝 React 

```
npm install react react-dom
```

安裝成功後，就來試試看能不能使用 React，並在畫面上印出 Hello, Webpack and React，所以將檔案做一下修改

```html


<body>
  <div id="root"></div>

  <script src="./bundle.js"></script>
</body>
```

```javascript
//App.js

import React from "react"

function App() {
  return React.createElement('h1', {}, "Hello Webpack and React")
}

export default App
```

```javascript
//main.js

import { getAuthor, author } from './utils.js'
import { getTwoAuthors } from './utils2.js'
import App from './App.js'
import ReactDom from 'react-dom'
import React from 'react'

const appEl = React.createElement(App)
ReactDom.render(appEl, document.getElementById('root'))

console.log(getAuthor())
console.log(getTwoAuthors())
```

最後我們再重新 build 一次

```
npm run build
```

成功看一下建置的訊息會發現，Webpack 的確有去 node_modules ，將我們使用的套件模組一併打包

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

最後打開畫面，除了之前在 console 印出來的結果外，也可以看到 Hello, Webpack and React! 

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

### 強大的 Webpack

Webpack 打包 JS 模組只是它功能的冰山一角，如果有看過 [Webpack 官網](https://webpack.js.org/) 可以看到首頁的這張圖：

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

Webpack 把任何資源都當作模組，像是 CSS 或是圖片，我們都可以用 `import` 的方式把檔案給引入進來，如果不使用 Webpack 是沒辦法做到的。而為了支援這樣子的功能，Webpack 透過定義不同的 `loader` 來識別檔案類型並轉譯成瀏覽器看得懂的語法。例如 `babe-loader` 能夠幫助我們將 ES6 以上的新語法轉譯成 ES5。除此之外，還可以透過 `plugins` 來擴充 Webpack 的功能，像是壓縮 CSS 檔，或是打包過後自動產生 HTML 等等。

 ## 結語
到這邊相信大家對 Webpack 應該有個基礎的認識了，也瞭解到為什麼需要使用 Webpack。回過頭來看在使用 creat-react-app 以及 Vue CLI，我們能夠輕鬆的 `import` CSS 或圖片，背後都是因為有 Webpack 在處理。 

最後，如果想要更加瞭解 Webpack，可以參考[ 五倍紅寶石學院 ](https://campus.5xruby.tw/courses)的[ Webpack5 入門 ](https://campus.5xruby.tw/p/webpack5)線上課程。

從模組化帶你認識 Webpack - post

從模組化帶你認識 Webpack


[calc()][0] 是一個 CSS function 作用於屬性設定是數值的時候可以進行加減乘除的運算，例如： `<length> 長度`、`<frequency> 頻率`、`<angle> 角度`、`<time> 時間`、`<number> 數字`或者是 `<integer> 整數`這幾個屬性值都可以使用 `calc()`。

```css
/* property: calc(expression) */
/* 屬性: calc(運算式) */
width: calc(100% - 50px);
```

## calc() 語法

calc() 這個 function 需要傳入 1 個加減乘除的運算式，在設定 `width`、`height` 這種 \<length\> 相關的屬性時， 在不同單位間也可以進行運算，如剛剛上面的範例：`width: calc(100% - 50px);`。calc() 的運算式一樣是按照先乘除後加減進行計算，如果需要進行複雜的運算，在 calc() 裡面也可以再加入括號 `()`，就可以設為括號先決裡面的先算。

- `+`：加
- `-`：減
- `*`：乘。其中一個運算參數必須是數字 (number)
- `/`：除。除數必須是數字，除數不可為零，會造成 HTML 解析錯誤。

必須注意在使用 + 和 - 的時候，在前後一定要加上空白，不然會被誤為是給了個負值。* 和 / 可以不用加，但為了格式統一方便和閱讀建議還是加一下。

```css
width: calc(50% + 8px)
/* 意思是 50% 的寬度 + 上 8px */
width: calc(50% + -8px)
/* 意思是 50% 的寬度 + 上 -8px，也等於 '50% - 8px' */
```

## Example 應用範例

### 定位

calc() 可以用來定位，如下面所設定的 CSS，就能作出一個滿版的藍色 banner 區塊有固定 40px 的邊距，也是一種將區塊置中的寫法。

```css
.banner {
  position: absolute;
  left: calc(40px);
  width: calc(100% - 80px);
  background-color: #6C92AF;
  padding: 6px 0;
  text-align: center;
  color: #FFF;
}
```

```html
<div class="banner">Hello banner/div>
```

<p data-height="265" data-theme-id="light" data-slug-hash="PEgoZq" data-default-tab="css,result" data-user="fokayx" data-embed-version="2" data-pen-title="CSS_calc" class="codepen">See the Pen <a href="https://codepen.io/fokayx/pen/PEgoZq/">CSS_calc</a> by fokayx (<a href="https://codepen.io/fokayx">@fokayx</a>) on <a href="https://codepen.io">CodePen</a>.</p>
<script async src="https://production-assets.codepen.io/assets/embed/ei.js"></script>

### 根據父層容器尺寸自動調整尺寸

設定 width 或 height 屬性使用 calc() 計算的數字是 100% 的時候，會自動去抓父層容器的尺寸。例如：做 autocomplete 的時候，希望在輸入框下，出現和輸入框等寬的列表：

```css
.container1 {
  width: 30%;
}

input {
  width: 100%;
  padding-left: 1rem;
  padding-right: 1rem;
  padding-top: 1rem;
  padding-bottom: 1rem;
  margin: 0;
  border-left: 2px solid #6c92af;
  border-right: 2px solid #6c92af;
  border-top: 2px solid #6c92af;
  border-bottom: 2px solid #6c92af;
}

ul {
  background-color: #6c92af;
  margin: 0;
  padding: 0;
  width: calc(100% + 1rem + 1rem + 2px + 2px);
  color: #FFF;
  list-style: none;
}
```

```html
<div class="container1">
  <input placeholder='container1'/>
  <ul>
    <li>show item 1</li>
    <li>show item 2</li>
    <li>show item 3</li>
  </ul>
</div>
```

由於 CSS 在加上 border、padding 的時候都是從原本設定得尺寸再往外加，所以長出來的東西看起來的尺寸會比原本設定的 width 還要大，因此要做到 ul 和 input 等寬的結果，在 input 加上的 padding 和 border 在算 ul 的 width 的時候也要幫他算進去，所以 `ul { width: calc(100% + 1rem + 1rem + 2px + 2px); }` 指的是：符合父容器的 100% 寬度，加上 input 的 `padding-left: 1rem` 和 `padding-right: 1rem`，再加上 `border-left: 2px` 和 `border-right: 2px`。用 calc() 計算尺寸非常方便，即使不同單位也沒有問題。如：codepen 第一個區塊。

如果在 ul 有設定 border、padding，ul 自己也會長大，在 calc() 計算的時候就必須扣掉這部份，例如：codepen 第二個區塊。

```css
.container2 {
  width: 30%;
}

.container2 input {
  width: 100%;
  padding-left: 1rem;
  padding-right: 1rem;
  padding-top: 1rem;
  padding-bottom: 1rem;
  margin: 0;
  border-left: 2px solid #6c92af;
  border-right: 2px solid #6c92af;
  border-top: 2px solid #6c92af;
  border-bottom: 2px solid #6c92af;
}

.container2 ul {
  background-color: #6c92af;
  margin: 0;
  padding: 0;
  border: 1px solid #212c35;
  width: calc(100% + 1px + 1px);
  color: #FFF;
  list-style: none;
}
```

```html
<div class="container2">
  <input placeholder='container2'/>
  <ul>
    <li>show item 1</li>
    <li>show item 2</li>
    <li>show item 3</li>
  </ul>
</div>
```

<p data-height="265" data-theme-id="light" data-slug-hash="JMqyyP" data-default-tab="css,result" data-user="fokayx" data-embed-version="2" data-pen-title="css_calc_ex2" class="codepen">See the Pen <a href="https://codepen.io/fokayx/pen/JMqyyP/">css_calc_ex2</a> by fokayx (<a href="https://codepen.io/fokayx">@fokayx</a>) on <a href="https://codepen.io">CodePen</a>.</p>
<script async src="https://production-assets.codepen.io/assets/embed/ei.js"></script>

### 將 calc() 巢狀包入 CSS 變數中

只要用括號 () 包好包滿，就可以無限次使用 calc() 方法，會一層一層從括號裡面計算出來。

```css
.foo {
  --widthA: 100px;
  --widthB: calc(var(--widthA) / 2);
  --widthC: calc(var(--widthB) / 2);
  width: var(--widthC);
}
```

在上面這段程式碼裡面展開所有變數之後 widthC 就等於：

`--widthC: calc( calc( 100px / 2) / 2)`

所以 .foo 的 width 最後算出來的值就是 25px。

[0]: https://developer.mozilla.org/zh-TW/docs/Web/CSS/calc 'calc at mdn'

---

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


post-CSS： calc() 數值運算 / css calc xuemei

CSS： calc() 數值運算


相信大家小時候都學過四則運算。以 Ruby 進行四則運算時，**整數**的加法、減法、乘法相當單純：

```
> 1 + 2
=> 3

> 9 - 2
=> 7

> 3 * 2
=> 6
```

為什麼要強調整數呢…因為換成**浮點數**的話就會混進奇怪的東西 XD

```
> 0.1 + 0.2
=> 0.30000000000000004

> 0.3 - 0.1
=> 0.19999999999999998

> 0.1 * 0.2
=> 0.020000000000000004
```

簡單來說，由於電腦記憶體有限，**浮點數的 0.1** 和一般人腦認知的**小數點 0.1**有著極微妙的誤差。這是有名的「浮點數不精確問題」，不論任何程式語言都會遇到。不過今天的主題是除法，這部分就跳過吧。

## 那除法呢？
和加減乘法比起來，除法的花樣就多了。首先，從數學上來說，除法運算必然會產生**商數**和**餘數**：

```
被除數 = 商數 * 除數 + 餘數
# 14 = 4 * 3 + 2
```

因此，對人腦來說是簡單的 `x ÷ y`，對電腦來說就是黑人問號了：「所以你現在是想知道除數還是餘數還是什麼？」

### 我兩個都想知道，不行嗎？
可以喔！使用 `x.divmod(y)` 方法，可以同時取得商數和餘數：

```
> 14.divmod(3)
=> [4, 2]
```

### 我想知道商數

#### 總之先幫我隨便算一下吧
好喔，那就是最經典的 `x / y` 方法：

```
# 整數相除，得到整數的商數
> 14 / 3
=> 4

# 非整數相除，得到非整數的商數
> 14 / 3.0
=> 4.666666666666667
```

#### 就是要整數

使用 `x.div(y)` 方法，結果會轉為整數：

```
> 14.div(3)
=> 4

> 14.div(3.0)
=> 4
```

#### 浮點數錯了嗎？

使用 `x.fdiv(y)` 方法，結果會轉為浮點數：

```
> 14.fdiv(3)
=> 4.666666666666667

> 14.fdiv(3.0)
=> 4.666666666666667
```

#### 整數什麼的最討厭了

使用 `x.quo(y)` 方法，會得到更精確的商數：

```
# 整數相除，得到分數物件（Rational）
> 14.quo(3)
=> (14/3)

# 非整數相除，得到浮點數物件（Float）
> 14.quo(3.0)
=> 4.666666666666667
```

### 我想知道餘數

我們先從最單純的情況開始。

#### x, y 的正負值相同時

`x.modulo(y)` 和 `x.remainder(y)` 可以取得餘數：

```
> 14.modulo(3)
=> 2
> 14.remainder(3)
=> 2
```

兩邊同樣都是負數時也是一樣：

```
> -14.modulo(-3)
=> -2
> -14.remainder(-3)
=> -2
```

其中 `x.modulo(y)` 也可以寫成（比較常見的？） `x % y`，兩者意義是一樣的。

#### x, y 的正負值不同時

好，問題來了。當 `x` 和 `y` 的正負值不同時，也就是像是 `14 ÷ -3` 或 `-14 ÷ 3` 這樣的計算時，會發生什麼事情呢？

```
> 14.divmod(-3)
=> [-5, -1]
> 14.modulo(-3)
=> -1
> 14.remainder(-3)
=> 2
```

咦？為何同樣是取得餘數的 `x.modulo(y)` 和 `x.remainder(y)`，得到的結果卻是不一樣的呢？還記得剛才的除法復習嗎：

```
被除數 = 商數 * 除數 + 餘數
```

當被除數和除數的正負值不同時，例如 `14 ÷ -3`，按照數學上對餘數的定義（詳細請參考[維基百科](https://zh.wikipedia.org/wiki/%E4%BD%99%E6%95%B0)），以下兩個解法都是成立的！

```
14 = (-5) * (-3) + (-1)
14 = (-4) * (-3) + 2
```

這也就是說，在數學上，`14 ÷ -3` 的餘數同時有可能是 `-1` 和 `2`。因此，Ruby 同時提供了 `x.modulo(y)` 和 `x.remainder(y)` 兩種方法，以分別取得兩個不同解法所得到的餘數。

簡單地說，能使 `x = a * y + b` 成立的**最小商數解**`a`，與其搭配的餘數 `b` 就是 `x.modulo(y)` 會取得的值：

```
# 14 = (-5) * (-3) + (-1)
> 14.modulo(-3)
=> -1
```

而另一個解法所得到的餘數，就是 `x.remainder(y)` 的結果。它和被除數的正負值會是一致的：

```
＃ 14 = (-4) * (-3) + 2
> 14.remainder(-3)
=> 2
```

前述 `x.divmod(y)` 所取得的餘數，則是以 `x.modulo(y)` 的值為準。

### 特殊狀況

再補充一些和零有關的特殊狀況：

```
＃ 除數是零的話會噴錯
> 1 / 0
=> ZeroDivisionError

＃ 但可以是 0.0 XD
> 1 / 0.0
=> Infinity

# 被除數是零的話，怎麼除都會是零
> 0 / 3
=> 0

# 除非用 0.0 去除 XD
> 0 / 0.0
=> NaN
```

## 結語

以上是關於 Ruby 除法的介紹，雖然實用性應該很低（笑）想更深入理解 Ruby 的數學運算的話，可以參考官方文件的 [Numeric API](https://ruby-doc.org/core-2.4.0/Numeric.html)，還有很多不常用的冷門方法等大家去認識喔～

---

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

post- Ruby 冷知識：除法篇 / cover

Ruby 冷知識：除法篇


## 部署 Rails 你可能會需要用到...

在學習 Rails 部署的路上，你一定聽過 Nginx、 Passenger、 Capistrano 這幾個東西吧？這篇文章會依序介紹這幾個工具特色，以及常見功能！

> 學習 Rails 部署建議可以參考蒼時的 [系列教學文章](https://blog.frost.tw/tags/DevOps/)  
它會詳細帶著讀者一步一步在 DigitalOcean 的機器上部署 Rails 專案

部署大概像什麼樣子？大概像下面這張圖吧
![](https://i.imgur.com/TeWMZTB.png)

遠端伺服器可能是 GCP、AWS、DigitalOcean 這些機器，程式碼倉庫則是 GitHub、 Gitlab、Bitbucket 這些服務，部署過程就是讓遠端伺服器可以取得程式碼倉庫的程式碼，然後順利的把專案執行起來。其中我們會需要在遠端伺服器安裝 Passenger、Nginx 這兩個軟體，同時得用 Capistrano 讓部署自動化、更有效率！

--- 
### 目錄

* Nginx & Passenger
  * 為什麼是 Nginx 搭配 Passenger ?
  * Passenger 擅長什麼呢？
  * Passenger 常用指令：
  * Nginx 設定檔說明
  * 自己設定 Nginx 

* Capistrano
  * Capistrano 功能介紹
  * 部署架構 
  * 設定檔
  * 常用指令
* 結論

---

## Nginx & Passenger

Nginx 是一個 Web Server，它的功能是接受 http request 並回覆 http response ， Nginx 本身和 Ruby 沒有關係，通常使用 Nginx 時我們還會搭配 Passenger 這一個 App Server，它可以管理 Rails 的 process 數量，同時 App Server 符合 Rack 的規範所以可以跟符合 Rack 規範的 Web Application (例如 Rails 溝通)

> 在接下來的文章中，會使用三個名詞<br><br>
> Web Server 就是 Nginx<br><br>
> App Server 就是 Passenger<br><br>
> Web Application 就是 Rails App<br><br>
> 關於 Passenger 和 Nginx 的安裝可以參考 [這篇文章](https://blog.frost.tw/posts/2018/04/10/Getting-started-deploy-your-Ruby-on-Rails-Part-4/#more)

### 為什麼是 Nginx 搭配 Passenger ?

這是我一開始學習部署時一直弄不懂的地方，我原本的想像是伺服器上面除了有我的 Web Application 外，再來就是某個軟體來處理其他的事情。到底為什麼需要 Nginx 和 Passenger 兩樣工具的搭配才能完成這些工作呢？

Nginx 和 Apache 都是 Web Server，它們專攻處理靜態檔案還有 http request。一般來說 Web Server 會放在 App Server 還有 Web Application 之前，它可以直接接觸 Client 端送來的請求，但在它後面的 App Server 和 Web Application 卻不行，因為這樣的架構讓這些軟體可以更有效率的分工，也讓我們的伺服器更安全。

此外，Web Server 還能處理效能上的議題，譬如 slow client 問題，如果 Client 端處理 http request 的速度超慢，Server 這邊就可能得花許多時間在等待這個 Client ，這樣的等待是很浪費資源的，為了解決這類型效能問題，又不讓其他開發者浪費時間重複造輪子，最好的方式就是讓 Web Server 處理這些問題，讓 App Server 和 Web Application 處理他們擅長的，這就是為什麼我們會用到 Nginx 和 Passenger 這兩樣工具了！

### Passenger 擅長什麼呢？

Passenger 會根據流量來判斷現在應該開啟多少個 Web Application，同時它也像是 Web Application 還有 Web Server之間的橋樑，它可以用 Rack 跟 Web Application 溝通，也能處理 Web Server 傳來的 http request，另外 Passenger 在架構上相當彈性也穩定，下圖是 Passenger 的架構圖

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

圖片來源：www.phusionpassenger.com

Passenger 是由多個模組所組成的，包含在編譯 Nginx 時一起編譯的 Phusion Passenger module，以及負責管理、重啟其它模組的 Watchdog 等等，因為這樣的結構可以讓 Passenger 更加有彈性，只要 Watchdog 沒有壞掉它就能幫忙重啟其他模組。

由於這些模組都是由許多的 process 在運行，因此彼此之間的溝通，需要透過一個 instance directory 的目錄，來存放這些 process 之間彼此溝通需要的檔案，所以在 nginx.conf 裡面我們會設定 `passenger_instance_registry_dir` 告訴 Passenger 它的 instance directory 在哪裡，我們在使用 `passenger-status` 指令的時候也是透過這資料夾內的資料取得資訊的。

> 之前在用 Passenger 的時候常常會跑不起來卻不知道為什麼？
> 原來就是少了 `instance directory` 這個目錄！

關於這架構圖更詳細介紹可看[官方文件](https://www.phusionpassenger.com/documentation/Design%20and%20Architecture.html#_web_server_module)

### Passenger 常用指令：

要使用 passenger 的指令必須先將 passenger 的 bin 目錄放到路徑之下，我們可以看到 passenger 的 bin 目錄下有這些執行檔
```
passenger  passenger-config  passenger-install-apache2-module  passenger-install-nginx-module  passenger-memory-stats  passenger-status
```

> 這些執行檔也就是我們可以使用的指令唷！

其中我們常用的可能有這兩個

```
# 查詢 passenger 的狀態
passenger-status 

# 透過 passenger 重新啟動 Rails 
passenger-config restart-app
```

咦！那要在哪邊做 Passenger 的相關設定呢？還記得前面說到的跟 Nginx 一起編譯的  Phusion Passenger module 模組嗎？因為這樣的關係，我們在寫 Nginx 設定檔時也可以一起設定一些 Passenger 需要的東西，接下來可以來看看 Nginx 的設定檔

### Nginx 設定檔說明

Nginx 安裝好後會有 `nginx.conf` 這設定檔，我們可以直接在裡面做修改，或是用 `include site-enabled/*.conf;` 之類的方法把設定檔寫在其他地方，在這個範例我們會將設定檔寫在其他地方，所以在 `nginx.conf` 加上一行 `include site-enabled/*.conf;` 即可，同時也得在有 `nginx.conf` 檔案的目錄下新增 site-enabled 資料夾來放我們要的設定檔。

如果把 nginx.conf 的註解都拿掉的話，你的設定檔可能長這樣

```
# 註解0
worker_processes  1;

events {
    worker_connections  1024;
}

http {
    passenger_root /usr/local/passenger/passenger-5.3.3;
    passenger_ruby /usr/local/ruby-2.4.3/bin/ruby;
    include       mime.types;
    default_type  application/octet-stream;
    sendfile        on;
    keepalive_timeout  65;

    server {
        listen       80;
        server_name  localhost;
        location / {
            root   html;
            index  index.html index.htm;
        }
        error_page   500 502 503 504  /50x.html;
        location = /50x.html {
            root   html;
        }
    }

    # 這行是後來加上去的
    include site-enabled/*.conf;
}

```

在 nginx.conf 中可以看到 `http { ... }` 包起來的設定，在這裡面還會看到 ` server {...} ` 的結構，而我們的`include site-enabled/*.conf;` 會寫在 http 這個 block 內然後 server 這個 block 外，因為其實我們要寫的設定檔就是好幾個 `server {...}` ，這些層級之間的規定可以在 [Nginx 的文件](http://nginx.org/en/docs/beginners_guide.html
)中找到~

> 註解0

> 設定 Nginx 的 worker_processes 數量，Nginx 啟動方式是一個 master process 和多個 worker processes，master process 負責根據設定檔的設定來操作 worker processes，所以 worker processes 是真正在處理 http request 的 process！

### 自己設定 Nginx 

在看完 nginx.config 後我們使用以下指令來建立我們自己的設定檔

```
$ mkdir site-enabled
$ cd site-enabled
$ vim xxx.conf (xxx可換為你的設定檔名稱，通常會用網域名稱好區分)
```

完成後可以在 `xxx.conf` 中這樣寫，其中 `#` 為註解符號

```
#設定 Passenger 的 instance directory
passenger_instance_registry_dir /var/run/passenger-instreg;

#第一個 server 區塊
server {

    #監聽 port 80 （ http request ）
    listen 80; 

    #註解1，設定 server name 
    server_name dodeploy.tk;

    #註解2，將 http request 都轉給第二個 server 區塊
    return 301 https://dodeploy.tk$request_uri;
}

#第二個 server 區塊
server {

    #監聽 port 443 （ https request ）
    listen       443 ssl;

    server_name dodeploy.tk;

    #SSL 憑證相關設定
    ssl on;
    ssl_certificate      /etc/letsencrypt/live/dodeploy.tk/fullchain.pem;
    ssl_certificate_key  /etc/letsencrypt/live/dodeploy.tk/privkey.pem;

    #註解3
    location ~ /.well-known {
        allow all;
        root /opt/nginx/html;
    }

    #提供靜態檔案的放置目錄
    root /home/deploy/do_deploy.com/current/public;

    #啟動 Passenger
    passenger_enabled on;
}
```

> 註解1<br><br>
> 如果有需要，我們也可以讓多個 domain 都對應到這台機器，首先申請多個 domain name 都對應到我們機器的 IP，然後我們就可以用多個 server 的區塊分別接收到帶有不同網域名稱的 http 請求。

> 註解2<br><br>
> 我們的範例會將 HTTP 轉換成 HTTPS ，要完成這功能要設定多個 server 的區塊，第一個區塊監聽 port 80，也就是只接受 HTTP 請求，在接收到 HTTP 請求後再來就是 return 將請求交由監聽 https 的第二個區塊來處理

> 註解3<br><br>
> 在第二個區塊我們做了 SSL 的憑證的設定，另外 location 那一塊是為了讓遇到 ~/.well-known 開頭的頁面，都使用 /opt/nginx/html 這個目錄，如此一來就能夠讓 Certbot 把驗證用的檔案放在這裡面，讓 Let’s Encrypt 可以驗證到。

完成以上設定後，可以用以下指令檢查設定檔有沒有問題
```
sudo /opt/nginx/sbin/nginx -t
```

如果沒問題可以用以下指令重新啟動 Nginx ( 使用這指令需要設定 systemd 功能 )
```
sudo systemctl restart nginx
```

## Capistrano

### Capistrano 功能介紹

Capistrano 是自動化部屬的工具，如果少了 Capistrano 我們要部署遠端伺服器就得每個動作都自己來，如果有多台機器多個環境，就更會需要 Capistrano 來幫忙處理各種繁瑣的任務了！

Capistrano 支援 Multiple stages，stage 指的是環境( staging, production 之類的)，我們只需要定義一次部署的方式，就能將這樣的部署方式套用在多個環境，也就是將 Web Application 部署到不同環境卻不用重複寫相同的設定檔，只需要設定這些環境所不同的地方譬如 IP 位置就可以了！

Capistrano 也支援 Server roles，在一個環境下我們可能會定義多個 role，因為 Web Application 可能是由多個服務一起完成的，有跑 Web Application 、database 和 CronJob server 等等，每個 role 在部署時會有不同的流程，這些也可以透過定義什麼 role 需要執行甚麼來完成。

### 部署架構 

Capistrano 部署到機器後結構大概會如下

```
├── current -> /home/deploy/do_deploy.com/releases/20150120114500/
├── releases
│   ├── 20150080072500
│   ├── 20150090083000
│   ├── 20150100093500
│   ├── 20150110104000
│   └── 20150120114500
├── repo
│   └── <VCS related data>
├── revisions.log
└── shared
    └── <linked_files and linked_dirs>
```

Capistrano 在每次部署時都會產生一個新的資料夾在 releases 目錄下，新的資料夾裡面就是新版本的 code 而資料夾名稱也是用當時時間命名。所以 releases 目錄下就會有每次部署時程式碼。current 資料夾是目前最新版本的程式碼資料夾，他的來源其實就是用 symlink 指到 releases 資料夾中最新版本的程式資料夾！

在我們的專案中有一些資料我們可能希望他能在不同的 release 中都能使用同樣的資料，就譬如 `20150080072500`、`20150090083000` 等資料夾中的 log 目錄想用同一個，這時候我們會把 log 目錄放在 shared 資料夾中，同時一些敏感資料如 database.yml 或是 settings.yml 這些不會放在版本控制的檔案，也會放在 shared 資料夾中，要怎麼放進去呢？那就要在設定檔中設定啦！

### 設定檔

Capistrano 的相關檔案在專案中的位置如下：

```
├── Capfile
├── config
│   ├── deploy
│   │   ├── production.rb
│   │   └── staging.rb
│   └── deploy.rb
└── lib
    └── capistrano
            └── tasks
```
>設定檔部分會依序介紹 Capfile、deploy.rb、prdouction.rb 這三份檔案

Capfile 的設定會決定你的 Capistrano 可以使用哪些功能，這些功能也就是你能使用的 Capistrano 指令有哪些，以及在跑這些指令的時候會做什麼事。

將部分註解都拿掉，一份全新的 Capfile 設定檔可能長這樣

```
# Load DSL and set up stages
require "capistrano/setup"

# Include default deployment tasks
require "capistrano/deploy"

require "capistrano/scm/git"
install_plugin Capistrano::SCM::Git

# require "capistrano/bundler"
# require "capistrano/rails/assets"
# require "capistrano/rails/migrations"
# require "capistrano/passenger"

# Load custom tasks from `lib/capistrano/tasks` if you have any defined
Dir.glob("lib/capistrano/tasks/*.rake").each { |r| import r }
```
為了部署 Rails App 同時讓我們管理設定檔方便，我會在 Capfile 加上

```

require "capistrano/bundler"
require "capistrano/rails/assets"
require "capistrano/rails/migrations"
require "capistrano/passenger"
require 'capistrano/upload-config'
```

這樣我們就有了專門針對 Rails 部署設計的功能，至於到底會有什麼差別呢？我們可以在使用 cap production deploy 的時候知道，詳細情況會在常用指令介紹

---

接下來 deploy.rb 還有 production.rb 分別代表 global 的設定還有 stage specific 的設定，這是什麼意思呢？我們部署時可能有很多種環境，staging、production 等等之類的，如果有些設定是所有環境都套用的就是 global 的設定，如果是專門放在某個環境的就是 stage specific 的設定。其中 deploy.rb 裡面就是 global 的設定，而 config/deploy/ 這目錄下的 xxx.rb 就是 stage specific 的設定唷！

config/deploy.rb
> global 設定

```
lock "~> 3.10.1"

# 設定專案名稱
set :application, "do_deploy"

# 讓機器知道要到哪裡找我們的程式碼
set :repo_url, "git@github.com:shes50103/do_deploy.git"

# 放在 shared 中，那些不在版本控制中的檔案
append :linked_files, "config/database.yml", "config/secrets.yml", "config/settings.yml"

# 放在 shared 中，不同 release 之間共享的目錄
append :linked_dirs, "log", "tmp/pids", "tmp/cache", "tmp/sockets", "public/system"
```

config/deploy/production.rb
> stage specific  設定

```
# 設定部署 Rails 的模式
set :rails_env, :production

# 決定要部署版本控制庫的哪一個 branch
set :branch, 'master'

# 決定部署到遠端伺服器哪個地方，從絕對路徑寫起
set :deploy_to, '/home/deploy/do_deploy.com'

# 見下方說明
role :web, %w{deploy@178.128.xxx.xxx}
role :db, %w{deploy@178.128.xxx.xxx}
```
>其實如果你喜歡的話，把所有 deploy.rb 裡面的東西都丟到 production.rb 裡面也是跑得動的，問題就會是假如到時候想要部署 staging 的時候， staging.rb 也得寫一大堆東西

整個部署流程，我們需要在本地電腦用 ssh 連線到遠端伺服器，要連線上去需要有遠端伺服器的 IP 以及我們要連線上去的身份，在這裡我們使用一個叫做 `deploy` 的使用者連線上去，意思就是在遠端伺服器裡面有這麼一個使用者，同時他的`~/.ssh/authorized_keys` 裡面有我本地電腦 ssh 公鑰，這樣我才能連線上去！

此外，當我以 deploy 使用者連線上遠端伺服器後，我還需要在遠端伺服器中再連線到程式碼倉庫，所以我也必須把 deploy 使用者的公鑰放到程式碼倉庫才能完成部署。記得前面提到的 Capistrano 的特性 Server roles 嗎？這邊看到的 `role :web` 還有 `role :db` 就是我們在部署時指定的 role 唷！

誒！？
怎麼感覺只設定了一點點東西，其實設定檔還有很多其他參數可以調整，但都有預設值了，譬如

```
# Releases 目錄下最多保留五份程式碼
set :keep_releases, 5

# 預設版本控制是使用 Git
set :scm, :git
```

因為已經有預設值了，所以可以少設定很多東西，我們就特別對我們要設定參數調整即可！ 
更多詳細資料可以看[官方文件](https://capistranorb.com/documentation/getting-started/configuration/)

### 常用指令

完成設定檔後，我們總需要在終端機下指令來部署或是操作些什麼，要怎麼知道我們現在的設定能使用哪些指令呢？那就是下面這個

```
bundle exec cap -T
```

可以查詢目前 Capistrano 中能使用的指令，能使用的指令有哪些就取決於 Capfile 中 require 了多少東西，可以試試看把一些 require 的設定註解掉後再輸入一次 `bundle exec cap -T` 能使用的指令會變少

---

```
bundle exec cap production config:pull
bundle exec cap production config:push
```

要使用這兩個指令必須安裝 `gem 'capistrano-upload-config'` 以及在 Capfile 中加入 `require 'capistrano/upload-config'` ，這兩個指令就是把遠端伺服器中的 linked_files 檔案抓下來以及上傳上去

---

```
bundle exec cap production deploy:check
```

這個指令會幫忙檢查要部署的專案目錄( `deploy_to設定的那個` )、 linked_dirs 、 linked_files 這些是否存在，如果不存在它會幫我們把目錄的部分做出來，所以在部署專案的一開始都會使用這指令來幫我們把 shared 目錄建立好，這樣才能用 `cap production config:push` 將設定檔上傳上去！

---

接下來這個就是部署的指令啦！

```
bundle exec cap production deploy
```

到底會做什麼呢？取決於設定檔的寫法，如果 Capfile 有了這兩行

```
require "capistrano/setup"
require "capistrano/deploy"
```

在 deploy 的時候就會跑過以下步驟

```
git:wrapper
git:check
deploy:check:directories
deploy:check:linked_dirs
deploy:check:make_linked_dirs
git:clone
git:update
git:create_release
deploy:set_current_revision
deploy:symlink:linked_files
deploy:symlink:linked_dirs
deploy:symlink:release
deploy:cleanup
deploy:log_revision
```

如果要部署 Rails 這可能還不夠，我們會需要在 Capfile 內加上

```
require "capistrano/bundler"
require "capistrano/rails/assets"
require "capistrano/rails/migrations"
```

這樣在跑 deploy 的時候就能增加這幾個步驟

```
bundler:install
deploy:assets:precompile
deploy:assets:backup_manifest
deploy:migrate
deploy:migrating
```

> 這五個步驟會在 `deploy:symlink:linked_dirs` 和 `deploy:symlink:release` 之間

在使用 Capistrano 比較常卡關的問題可能就是有些步驟是只有特定的 role 才能執行，這時候就要另外設定，又或者是有些東西的安裝我們可能需要額外指定明確路徑，不然就會安裝在錯的地方。更詳細的部署流程可以參考[這裡](https://capistranorb.com/documentation/getting-started/flow/)

## 結論

在學習部署的過程中，儘管已經完整走完了部署的流程讓服務可以正常執行，但是對這些部署工具的掌握還是十分有限，有很多東西只知道出問題了要這樣做、要那樣試可能可以解決問題，但往往不是很清楚自己到底在幹嘛XD，所以趁這個機會整理了一下這些工具的使用方法。

---

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

thumb photo-1526639673778-1ed7ff390a4a

Rails 部署工具，原來是這樣


這是綠界的電子發票介接技術文件：[綠界科技股份有限公司 電子發票介接技術文件](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 電子發票，就是這麼簡單


# The ABC of Rails Engines

 > 本文內容主要參考自 http://guides.rubyonrails.org/engines.html

本文會以下列三個段落來介紹 Rails Engine 的基礎知識及用法

* Rails Engine 是什麼?
* 打造一個 Rails Engine
* 在主程式中使用 Rails Engine

## Rails Engine 是什麼？

Rails Engine 主要的目的是透過簡單易用的程式介面 (interface) 來提供主程式 (Host) 額外功能，筆者認為可以把主程式 (Host) 想像成原型機器人，Rails Engine 則可視為具有不同能力的裝甲，只要將具有特殊能力的裝甲，適當地裝備 (hook) 在原型機器人身上，就可以組裝出具有各式能力的裝甲機器人，而程式介面 (interface) 就是相同的裝甲可裝載在不同機器人上的關鍵，當然組裝不好時也會造成效能不佳或容易故障的問題，亦或是選用設計不佳的裝甲 (Rails Engine) 也可能影響原機體 (Host) 的正常運作。

由此可看得出來裝甲之裝載並非是絕對必要的，如果你的團隊有足夠的能力、時間及資源，當然可以將所需要的功能直接「內建」在原型機器人裡，所以裝甲的選用與團隊的現況有直接的關係。

雖然每個裝甲都有既定的能力，但這並非完全不能改動的，技術人員仍然可以依照實際的需求，調整強化 (override) 裝甲原本的行為，使得改良過後的裝甲更為適用，這是因為原型機器人 (Host) 的優先權高於機甲 (Rails Engine) 的關係。

這邊的原型機器人(Host/ a rails application) 是指透過 Rails 框架所建造出來的，而原型機器人基本上就是一個強化版本 (a supercharged engine)，因此 Rails applications 與 Rails Engines 且有很高的共通性，Rails engines 亦可看成是小型的應用程式 (miniature applications)。

## 打造一個 Rails Engine

要打造一個 Rails Engine 很簡單，只要透過 `rails plugin new` 指令就可以產生一個 engine 的雛形。 這邊要特別說明的是 Engines 與 Plugins 是很相似的，相同的是他們都有一個 `lib` 資料夾，也都是透過 `rails plugin new` 指所產生的，不同是當我們提及 engine 時，通常指的是一個完整的 plugin (full plugin)，需要在產生時傳入 `--full` 或 `--mountable` 參數。

指令如下:

* `rails plugin new YOUR_ENGINE_NAME --full` 或
* `rails plugin new YOUR_ENGINE_NAME --mountable`

下列比較表將以 **blorgh** 做為 engine name，主要以 `--full` 與 `--mountable` 參數所產生的 engines 為比較基準

|   |NO OPTION|`--full` | `--mountable` |
|---|--------|---------|---------------|
|app/ 資料夾|╳|〇|〇|
|bin/ 資料夾|〇|〇|〇|
|config/ 資料夾|╳|〇|〇|
|lib/ 資料夾|〇|〇|〇|
|test/ 資料夾|〇|〇|〇|
|config/<br>routes.rb|╳|Rails.application.routes.draw do<br>end|**Blorgh::Engine**.routes.draw do<br>end|
|lib/<br>blorgh/<br>engine.rb|╳|module Blorgh<br>&nbsp;&nbsp;class Engine < ::Rails::Engine<br>&nbsp;&nbsp;end<br>end|module Blorgh<br>&nbsp;&nbsp;class Engine < ::Rails::Engine<br>&nbsp;&nbsp;&nbsp;&nbsp;**isolate_namespace Blorgh**<br>&nbsp;&nbsp;end<br>end|
|app/<br>helpers/<br>**blorgh**/<br>application_helper.rb|╳|╳|module Blorgh<br>&nbsp;&nbsp;module ApplicationHelper<br>&nbsp;&nbsp;end<br>end|
|app/<br>views/<br>layouts/<br>**blorgh**/<br>application.html.erb|╳|╳|〇|
|app/<br>javascripts/<br>**blorgh**/<br>application.js|╳|╳|〇|
|app/<br>javascripts/<br>**blorgh**/<br>application.css|╳|╳|〇|
|app/<br>javascripts/<br>**blorgh**/<br>application_controller.rb|╳|╳|module Blorgh<br>&nbsp;&nbsp;class ApplicationController < ActionController::Base<br>&nbsp;&nbsp;&nbsp;&nbsp;protect_from_forgery with: :exception<br>&nbsp;&nbsp;end<br>end|
|test/<br>dummy/<br>config/<br>routes.rb|Rails.application.routes.draw do<br>end|Rails.application.routes.draw do<br>end|Rails.application.routes.draw do<br>&nbsp;&nbsp;**mount Blorgh::Engine => "/blorgh"**<br>end|

### 實作即將開始
### 這個 Rails Engine (blorgh) 將提供主程式 (host) 一個基本的部落格功能:

* 文章列表
* 新增文章
* 編輯文章
* 刪除文章
* 留言評論

> 此範例取自 [Getting Started with Engines](http://guides.rubyonrails.org/engines.html)

> 請使用 Rails 5.1+ 版本

#### Step1. 產生一個 mountable 的 rails engine 雛形

```ruby
$ rails plugin new blorgh --mountable
```

Engine 產生成功後，請切換到 blorgh 根目錄，找到 blorgh/blorgh.gemspec 檔案，將含有 `TODO` 的資訊進行修改，不然在後續的步驟中會出現 `blorgh/blorgh.gemspec is not valid. Please fix this gemspec. (Gem::InvalidSpecificationException)
The validation error was '"FIXME" or "TODO" is not a description'` 的錯誤訊息。

```ruby
# blorgh/blorgh.gemspec
# 這邊只是用來說明用的範例，請依照實際情況填寫

Gem::Specification.new do |s|
  s.name        = "blorgh"
  s.version     = Blorgh::VERSION
  s.authors     = [""]
  s.email       = [""]
  # 修改前
  # s.homepage    = "TODO"
  s.homepage    = "http://example.com"

  # 修改前
  # s.summary     = "TODO: Summary of Blorgh."
  s.summary     = "Summary of Blorgh."

  # 修改前
  # s.description = "TODO: Description of Blorgh."
  s.description = "Description of Blorgh."
  s.license     = "MIT"

  s.files = Dir["{app,config,db,lib}/**/*", "MIT-LICENSE", "Rakefile", "README.md"]

  s.add_dependency "rails", "~> 5.2.0"

  s.add_development_dependency "sqlite3"
end
```

#### Step2. 快速產出文章的 Scaffolding (CRUD)

```ruby
# engine 根目錄
$ bin/rails generate scaffold article title:string text:text
```

在 Engine 根目錄，輸入下列指令，執行 migration 以產生 blorgh_articles 資料表

```ruby
# engine 根目錄
$ bin/rails db:migrate
#=> 執行完畢會產生 blorgh_articles 資料表
```

請切換目錄到 `test/dummy` 底下，鍵入 `rails s` 啟動 rails server，在瀏覽器中輸入 http://localhost:3000/blorgh/articles 可看到具有CRUD功能的文章管理畫面，此時你應該已經可以新增、編輯、刪除文章，並在新增文章後可以看到文章列表。這邊的 test/dummy 其實是一個簡化版的 rails application，可讓我們在開發 engine 的時候用來測試之用，模擬日後 Engine 被掛入主程式的行為。

#### Step3. 指定 engine 首頁路徑

```ruby
# 在 config/routes.rb
Blorgh::Engine.routes.draw do
  resources :articles
  root to: "articles#index"
end
```

重啟 rails server 後，瀏覽 http://localhost:3000/blorgh 將會顯示文章列表頁面

#### Step4. 產生評論 (comments) 資源

```ruby
# engine 根目錄
$ bin/rails generate model Comment article_id:integer text:text

# engine 根目錄
$ bin/rails db:migrate

# => 達行完畢後會產生 blorgh_comments 資料表
# 這邊異動的是 test/dummy app
```

為了在文章下面顯示評論內容，需要在 app/views/blorgh/articles/show.html.erb 中的 `<%= link_to 'Edit'` 之前加上下列程式碼

```erb
<h3>Comments</h3>
<%= render @article.comments %>
```

由於一篇文章 (article) 可以有多則評論 (comments)，因此需要在 article model 中定義 `has_many :comments` 關聯

```ruby
# app/models/blorgh/article.rb
module Blorgh
  class Article < ApplicationRecord
    has_many :comments
  end
end
```

#### Step5. 加入可新增評論的表單

為了要可以新增評論，我們需要一個表單，在 app/views/blorgh 目錄中建立一個 comments 資料夾，並建立一個 _form.html.erb 的檔案，表單的程式碼如下

```erb
<h3>New comment</h3>
<%= form_with(model: [@article, @article.comments.build], local: true) do |form| %>
  <p>
    <%= form.label :text %><br>
    <%= form.text_area :text %>
  </p>
  <%= form.submit %>
<% end %>
```

將表單放在文章評論 `<%= render @article.comments %>` 的下方，要修改的檔案是 app/views/blorgh/articles/show.html.erb

```erb
<%= render "blorgh/comments/form" %>
```

我們已經在 model 中定義了關聯，還需要定義對應文章-評論的巢狀路由 (Nested Resources)，在 config/routes.rb 中修改路由如下

```ruby
# config/routes.rb
Blorgh::Engine.routes.draw do
  resources :articles do
    resources :comments
  end

  root to: "articles#index"
end
```

有了 model，也有了路由，我們還需要對應新增 comment 所需的控制器 (controller)，可透過下列指令建立一個空的控制器

```ruby
# engine 根目錄
$ bin/rails g controller comments
```

找到剛產生的控制器檔案 app/controllers/blorgh/comments_controller.rb，定義 create 方法，這個方法用以對應新增評論表單中的 POST 請求，程式碼如下

```ruby
# app/controllers/blorgh/comments_controller.rb
def create
  @article = Article.find(params[:article_id])
  @comment = @article.comments.create(comment_params)
  flash[:notice] = "Comment has been created!"
  redirect_to articles_path
end

private
  def comment_params
    params.require(:comment).permit(:text)
  end
```

最後一步我們需要在 app/views/blorgh/comments/ 新增一個 _comment.html.erb 用做評論呈現的畫面，這個畫面對應的是先前加入  app/views/blorgh/articles/show.html.erb 中的 `<%= render @article.comments %>` 部份，畫面所需的程式碼如下，代表的是「一則評論」的樣子

```erb
<%= comment_counter + 1 %>. <%= comment.text %>
```

目前 app/views/blorgh/articles/show.html.erb 中的程式碼應如下所示

```erb
<p id="notice"><%= notice %></p>

<p>
  <strong>Title:</strong>
  <%= @article.title %>
</p>

<p>
  <strong>Text:</strong>
  <%= @article.text %>
</p>

<h3>Comments</h3>
<%= render @article.comments %>
<%= render "blorgh/comments/form" %>

<%= link_to 'Edit', edit_article_path(@article) %> |
<%= link_to 'Back', articles_path %>
```

現在再次瀏覽任一篇文章時，應該可以在下面看見一個表單，輸入評論後按下 Create Comment，就可以看到評論已經被新增並顯示在該文章的下方了。

完成上述的步驟便可以完成一個可提供發文與評論留言的簡單部落格 Rails Engine

## 在主程式中使用 Rails Engine

首先我們先用 Rails 建立一各新的 Rails application (unicorn)

```ruby
$ rails new unicorn
```

#### Step1. 安裝 Engine

在主程式中使用 Rails Engine 的方式很簡單，你應該也不會太陌生，只要找到主程式的 Gemfile 檔案並加入下列描述即可

```ruby
# 由於我們開發的 Rails Engine 是在本機中，因此要使用 path 指定所在路徑
gem 'blorgh', path: '../the-abc-of-rails-engines/blorgh'
```

接著記得下在主程式的根目錄下 `bundle install` 安裝我們的 engine

#### Step2. 掛載 Engine
然後我們還需要在主程式的 config/routes.rb 中將 engine 掛進來，如此主程式才可以存取 engine 中的路由

```ruby
# config/routes.rb
# at: "/可依個人需求喜好命名"
mount Blorgh::Engine, at: "/blog"
```

#### Step3. 複製 Engine 的 migration 檔案
此指令可重覆執行，不會有重複複製的副作用(用以匯入 Engine 的 migration 檔案)

```ruby
# 在主程式的根目錄
$ bin/rails blorgh:install:migrations

# 會出現下列訊息，檔案時戳會略有不同
# => Copied migration 20180719154413_create_blorgh_articles.blorgh.rb from blorgh
# => Copied migration 20180719154414_create_blorgh_comments.blorgh.rb from blorgh
```

#### Step4. DB migrate

```ruby
# 在主程式的根目錄執行 migrate
$ bin/rails db:migrate

# => 產生 blorgh_articles 與 blorgh_comments 資料表
```

現在在主程式的根目錄中使用 `rails s` 指令啟動伺服器，並瀏覽 http://localhost:3000/blog 應該可以看見文章頁面，你此時應該已經可以新增、刪除、修改文章，還可以在文章下方新增評論了。

*如果沒有要針對 Engine 的既有行為做調整，基本上到這邊就可以告一個段落了。*

接下來要討論是如何讓 Engine 使用主程式所定義的類別，而為了滿足這個需求，我們還需要調整 Engine 最初的設計，這邊希望達成的主要目的是希望可以為文章增加作者的資訊，而這個「作者」類別是具有彈性，將由主程式來進行定義，也就是說在這個調整之後，要使用這個 Engine 的主程式，一律需要告訴 Engine「作者」代表的是主程式中的哪一個類別。

*文章與評論由 Engine 負責定義，作者則交給「主程式」來定義*

#### Step5. 在 Engine 中提供可由主程式定義「作者」類別的方法

修改 lib/blorgh.rb 的 Blorgh module 中加入下列程式碼

```ruby
# blorgh/lib/blorgh.rb
module Blorgh
  # 此類別存取子將開放給主程式定義「作者」類別之用
  mattr_accessor :author_class

  # 覆寫原本的 author_class getter 方法，使回傳值為常數物件
  def self.author_class
    @@author_class.constantize
  end
end
```

#### Step6. Article 的作者

在 article (app/models/blorgh/article.rb) 定義與作者的關聯及參照來源

```ruby
# app/models/blorgh/article.rb
module Blorgh
  class Article < ActiveRecord::Base
    # ... 略
    # 由於 Blorgh.author_class 會回傳常數物件，應轉型為字串
    belongs_to :author, class_name: Blorgh.author_class.to_s
    # ... 略
  end
end

```

#### Step7. 新增 author_id 到 article 中的 migration 檔案

```ruby
# engine 根目錄
$ bin/rails g migration add_author_id_to_blorgh_articles author_id:integer

# engine 根目錄
$ bin/rails db:migrate

# => 新增欄位 author_id 到 blorgh_articles 資料表
# 這邊異動的是 test/dummy app
```

#### Step8. 修改 article model 如下

```ruby
# app/models/blorgh/article.rb
module Blorgh
  class Article < ActiveRecord::Base

    # 新增 author_name 欄位供暫時存取之用
    attr_accessor :author_name

    has_many :comments
    belongs_to :author, class_name: Blorgh.author_class.to_s

    # 透過這個 callback 建立/修改文章所對應的作者 (Blorgh.author_class)
    before_validation :set_author

    private

    def set_author
      self.author = Blorgh.author_class.find_or_create_by(name: author_name)
    end
  end
end

```

#### Step9. 新增作者名稱欄位
在 Engine 中的文章表單中 (app/views/blorgh/articles/_form.html.erb) 的 :title 欄位前新增作者名稱欄位

```erb
  <div class="field">
    <%= form.label :author_name %><br>
    <%= form.text_field :author_name %>
  </div>
```

#### Step10. 允許 :author_name 參數的傳遞
在 Engine 的 app/controllers/blorgh/articles_controller.rb 中的私有方法 article_params 允許 :author_name 參數欄位的傳入

```ruby
# app/controllers/blorgh/articles_controller.rb
  def article_params
    params.require(:article).permit(:title, :text, :author_name)
  end
```

#### Step11. 顯示作者資訊
於 Engine 的 views/blorgh/articles/show.html.erb 中，在 "Title" 的上方加入作者的資訊

```erb
<p>
  <b>Author:</b>
  <%= @article.author&.name %>
</p>
```

#### Step12. 用 test/dummy 來測試

```ruby
# blorgh/test/dummy
# 新增 User 類別
$ rails g model user name:string

# blorgh/test/dummy
# 執行 db:migrate
$ bin/rails db:migrate

# => 新增 users 資料表

```

#### Step13. 定義「作者」

在 test/dummy/config/initializers 中新增一個 blorgh.rb 的檔案，並加入下列程式碼指定「作者」的類別

```ruby
# 這邊一定要使用「字串型態」的類別名穩，不可直接類別物件來定義，不然 Rails 會試圖去載入該類別並參考與其對應的資料表，如果此資料表還不存在時，將會造成不必要的問題
Blorgh.author_class = "User"
```

一樣透過 `rails s` 啟動 rails server，打開瀏覽器瀏覽 [http://localhost:3000/blorgh](http://localhost:3000/blorgh)
現在新增文章時應該可同時加上作者資訊，成功新增後亦可顯示作者資訊，但若要正常地編輯作者資訊，則還需要調整一下 Engine 裡 articles_controller 中 edit 方法，完整程式碼請參閱[這邊](https://github.com/spartchou/the-abc-of-rails-engines-engine/tree/master/practice/blorgh)。

如果可以讓 test/dummy 運作正常，那麼在[主程式中只要實作 Step12 及 Step13](https://github.com/spartchou/the-abc-of-rails-engines-main-app)，就可以達到一樣的效果了。

---

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


post-The ABC of Rails Engines / cover

The ABC of Rails Engines


在與 Sketch 相遇後，已經回不去用其他軟體設計網頁的我 ( hen 誇張 )，前陣子從公司的大大那邊聽聞 Google 發表了一個叫做「 Material Theme Editor 」的工具，而它竟然是今年五月份才發表的東西！就讓我來為大家稍微介紹一下這個還熱騰騰的新玩意吧～

**▸ 簡單來說，「 Material Theme Editor 」是什麼？**

一言以蔽之，這是「讓你快速製作自家品牌的 Material Design 風格 Sketch 套件」。( 也太拗口 )
有接觸網頁、APP設計的設計師應該多少都有聽聞過 Material Design，它是 Google 在 2014 年 6 月的Google I/O 大會發表的 Google 獨創的設計準則，在那之後也影響了非常多介面設計在對於扁平化、紙張特性、轉場動畫等方面的思考方向，在四年後的今天，我們仍然可以隨處看到 Material Design 的深遠影響。
而在基於 Material Design 準則下出生的 Material Theme Editor ，他除了有豐富的 Material Design 元件庫，還能夠使用非常簡單且所見即所得的介面調整整體風格與色系！是不是讓人很心動呢？馬上來看看要怎麼使用吧！

**▸ 下載～安裝～打開～**

下載網址：https://material.io/tools/theme-editor
安裝套件後在工具列選取 Plugins > Material > Open Theme Editor 打開 Material Theme Editor

![Material Theme Editor-安裝](//images.ctfassets.net/8er52l3j5u76/Y0YxX6fqipPecMkoBXeL5/966bd85b7ce5c18a2012ca4b637e8896/UNEvTxW.png)

**▸ 主題選擇**

打開 Material Theme Editor 後可以看到 Sketch 內出現了一個黑黑的小視窗，裡面有「 Baseline 」( 基本設計 ) 、「 Crane 」( 旅遊 ) 、「 Fortnightly 」( 新聞 ) 、「 Shrine 」( 購物 ) 四種主題可選擇，除了最基礎的 Material Design 元件以外，也有針對各個不同類別產品所設計的元件庫。

![Material Theme Editor-主題選擇](//images.ctfassets.net/8er52l3j5u76/6QVX7C3E6db9N5HQKWX965/70084222f7d72c1e8ddbb80e863c1d22/vKN7lHa.png)

選擇了任一主題後，可以看到有五個內建的頁面，分別是 Cover 、 Getting Started 、 Material Theme 、 Material Components 、 Symbols ， 其中 Material Theme 是主要範例介面的展示， Material Components 是所有元件的列表， Symbols 就是所有元件庫。

![Material Theme Editor-頁面](//images.ctfassets.net/8er52l3j5u76/57PrrEGHXnBeg4eWwZ1BAf/726a8aa77741e16318b55d547c48e02e/LFPa3WW.png)

**▸ 四大功能**

功能一：調色盤
在這個操控介面上，我們可以任意改變「主要」、「強調」、「背景」這三個顏色，點入任一色塊後，我們可以從 Custom 裡面任意選擇我們要的顏色，也可以從 Material 裡面 Material Design 提供的色盤去選取，選取顏色後會自動產生 Primary ( 主要 ) 、 Light ( 較亮 ) 、 Dark ( 較暗 ) 三種顏色。

![Material Theme Editor-調色盤](//images.ctfassets.net/8er52l3j5u76/23WZGxFbuK35Gwj9Dpnwel/85d23c3a7206fed6e9c007787a278dd3/AKgj2mX.png)

選好顏色以後，這些顏色就會套用在元件上各個對應的色彩設定，完全不需要再像以前一樣要一個個手動調整，是否很方便呢！

功能二：字型設定
在這個功能可以設定預設的字型，並可以對不同的標題字階層設定不同的粗細，但無法修改字體的大小。

![Material Theme Editor-字型設定](//images.ctfassets.net/8er52l3j5u76/ZbllVBWeJkacyLgFpRWHq/e314afc3458837354548c1b302bd9a47/2GlqOaF.png)

功能三：形狀設定
形狀設定中有「Curved」和「Angied」兩種模式， Curved 會是平滑的圓角，而 Angied 則會是切角的效果。

Curved
![Material Theme Editor-Curved](//images.ctfassets.net/8er52l3j5u76/75chekq5aOTUE6DTw5UPBE/78cff92c42347849ed53f2f406343515/XxHCO5z.png)

Angied
![Material Theme Editor-Angied](//images.ctfassets.net/8er52l3j5u76/4Vj7QqrmaRegbT7mYIWq54/7f24ae89bf54e7763137ff0d7b33d2b5/aRJqdTB.png)

功能四：Icon 設定
在這裡提供了五種不同風格的 Icon ，點選以後可以前往下載，下載以後是一套包含 16 種分類、超過上千種的 Icon，各種想得到想不到的 Icon 都有，非常方便！

![Material Theme Editor-Icon 設定](//images.ctfassets.net/8er52l3j5u76/4uyeZNP8VHnYprzKRpGGoC/a3f9dfbe5ed6d978373cf9a7500a2e67/GiPD3qK.png)

**▸ 最後**

附上官方的介紹影片，希望這篇介紹文能對大家有所幫助！

[https://www.youtube.com/watch?v=BLrgDgd_1c0](https://www.youtube.com/watch?v=BLrgDgd_1c0)


post-Material Design 新利器：Material Theme Editor / cover

Material Design 新利器：Material Theme Editor


之前曾經寫過一篇我們公司專案使用敏捷開發的案例，當時我們在預期的時間讓 MVP 的產品能夠上線，讓敏捷開發的價值得底被證明。不過這一次我想從另一個同樣是跑敏捷開發卻跑的不盡理想的專案中，重新探究敏捷開發的價值。

專案的背景是與國外企業的 RD 部門將部分的產品委外給我們開發，產品的規劃、設計由他們主導，我們只要負責好開發的部分，聽起來是非常單純的委外開發。但短短的半年期間，雙方經歷過多次的調整，才終於催生出產品進到使用者測試的階段。

### 溝通的高牆

敏捷開發宣言裡提到：個人與互動重於流程與工具

在最剛開始接下這專案時，負責管理我們的是客戶公司（以下簡稱Ａ社）的 Tech Lead 以及負責這個產品的 Product Manager、Product Owner，我們與其他 RD 的溝通幾乎是零。

我們走我們的 Scrum，他們走他們的 Scrum，只有 Tech Lead 和 PM 知道雙方在做什麼。
這樣延伸出來的主要問題是功能開發的速度會變的緩慢。

在一個有打算做跨部門的組織裡，要讓這件事情得以實現，我想還是需要讓對於同一功能再進行開發的相關人員有能夠溝通的管道，不然的話兩個團隊各做各的狀況其實還是一種 waterfall 的流程，只是裝上了敏捷開發流程的殼。

當時為了解決這個問題，Ａ社的新 CTO 在剛上任時找了我們幾位同事到他們公司一起共事幾天，和他們一起每日站立會議，確實與他們的工程師面對面的溝通時，許多之前需要等待很長時間回應的狀況就馬上等到解決，但由於我們終究不是駐點的團隊，這一次的面對面溝通只是暫時化解當時正在開發功能上的一些問題，並沒有真正解決之前溝通的高牆。

### 小小的調整，讓問題提早被發現

舉例來說我們當時遇到的狀況是開發功能的流程是固定的，功能設計與圖完稿後才會進到功能開發，我們沒有機會可以對設計圖上問題提出改善建議，必須要照圖開發，直到一個不正確的功能被開發完成後再重新由 Product Manager 開新需求進行調整，理想上這雖然是一個完整程序，但開發者及設計師就會面臨一種時常在打掉重練的挫敗感，對產品而言則是不停地在累積技術債。

![post-從失敗案例重新思考敏捷開發價值](//images.ctfassets.net/8er52l3j5u76/YZvwV2YPJmVMCYRNUDTjy/8d065402c363e2c7ede151388dcf0271/WSH7bjP.png)

後來，針對上面提到的情境我們做了一點溝通上的調整，使得一些邏輯面上的問題在交付給客戶之前就能得到解決，雖然說交付給客戶之後，有一定的機率客戶會要求修改或調整功能，但至少工程師們在開發過程中就發現的邏輯問題能夠在交付給客戶前就得到討論，減少一些未來開發上所累積的技術債。

![post-從失敗案例重新思考敏捷開發價值](//images.ctfassets.net/8er52l3j5u76/TNL6tqgGxTEmwTxMyxbkS/706a5061943dc3457d92b492cd8b6cef/nkTtpPC.png)

### 不再只有單一對話窗口，多團隊看板開發

除了剛才提到一點流程上的改變，在我們回國後，CTO 下了一個決策，我們從一開始的 Scrum 換成了 Kanban 的管理方式。
過去不同團隊做的事情如果會相互影響到，很難在各自的站立會議中發現，因此非常倚賴 Tech Lead 來同步溝通個團隊的狀況，導致開發速度一直都很緩慢，大家都互相的等來等去，而且還不知道到底等的是誰。

改成看板開發後，以這家公司規模（工程師在20位以內）還可以在同一時間一起開會，主要由 CTO 擔任會議主持人瀏覽看板，因為不同部門的正在負責的票都在同一個看板上，Ａ團隊的票被 B 團隊影響著的狀態就能夠在看板上一目瞭然。

解決了之前不同團隊對於進度瞭解上的高牆。

### 持續堅持站立會議

站立會議是大家耳熟能詳在 Scrum（敏捷軟體開發過程）中的一部份。

在專案的這段時間內，不論有沒有和客戶那邊一起站立會議，我們自己這邊則是一直都有進行著，我想除了同步彼此的進度狀況，發現專案的問題、進度的問題、技術的問題之外，我另外有個心得是覺得站立會議同時還是一個建立團隊默契及感情滿重要的會議。

這個專案中有過幾次工程師上的人力調整，除了全職的工程師外也有一些 Remote 工程師在我們的團隊當中，透過每日的站立會議，讓新進的工程師或是無法常常面對面對話的  Remote 工程師們都有一段時間和其他團隊成員對話、溝通，能夠幫助他們更快地融入團隊中，這點是我覺得站立會議在敏捷開發中的另一個價值。

在這專案中，客戶有客戶團隊自己的開發腳步，站在外包團隊的角度正好可以觀察到這些事情，更加讓我體會到敏捷開發絕對不是單單只有那些原則、圖表和方法，還會牽扯到組織的文化及管理。我想要做到資深的管理者（或說 Scrum Master）需要有效且精準地找出組織問題的癥結點並加以改善，才能夠讓敏捷開發一直保有他敏捷的優勢，而不是只是流於形式。

post-從失敗案例重新思考敏捷開發價值/cover

從失敗案例重新思考敏捷開發價值


## Multi-tenant 應用程式：讓人又愛又恨的 Apartment

隨著現在個人化網站的興起，許多網路服務都提供使用者自訂網站的功能。這些功能涵蓋許多面向，包含論壇、部落格與網路個人商店等。典型的自訂網站例子如 Wix 與 Weebly，個人商店則如 Shopmatic 與 Shopify 等等。在這些服務中，使用者可以在某些限度下自定網站的內容，建立屬於自己的資料，而不會與其他使用這個服務的使用者衝突。換句話說，不同的使用者使用同一個服務，但他們的資料卻是各自分離的，這便是最基本的 multi-tenant 的精神。由於以 multi-tenant 風格的網站建立越來越熱門，因此在各大網站開發框架上都有提供相關的開發工具可用。今天要跟各位讀者分享的，便是最常被用在 Rails 應用程式中的 multi-tenant 工具：`apartment`。

此篇文章中會大致介紹 `apartment` 這個套件如何使用，以及帶讀者建立一個簡單的 multi-tenant 部落格示範網站，並且提出一些使用 `apartment` 可能會遇到的問題。

## `apartment` 是什麼

`apartment`（[Github repo](https://github.com/influitive/apartment)）是 Ruby/Rails 圈最常用來製作 multi-tenant 的 gem。如同其英文「公寓」，`apartment` 可以讓我們蓋出公寓般的資料庫結構，每一戶的格局相同但卻都是獨立運行，互不影響。我們通常會把一戶單獨的使用者稱為一個「tenant」，也就是（公寓）的承租人。`apartment` 最大的特色是與 Rails 的 ActiveRecord 做了相當緊密的結合，使用者可以在指定了特定的 tenant 後，直接使用自己所熟悉的 ActiveRecord ORM（如部落格網站中取得所有文章的 ORM: `Article.all`，來取得只屬於自己 tenant 的資料），而不需要明確的加上 `where` 篩選條件（也就是不必用 `Article.where(tenant_id: 1)` 明確篩選自己的 `tenant_id`）。因為有著如此便利的特性，使得 `apartment` 經常被用來快速開發 multi-tenant 網站的原型。

底層資料庫的支援部分，`apartment` 最早先是以 PostgreSQL 為主要支援的資料庫，主要原因是因為 PostgreSQL 有「schema」的特性可以使用。`apartment` 會替每一個不同 tenant 各自開一個 schema，已達到資料隔離的功能。

後來版本的 `apartmemt` 也逐漸支援如 MySQL 等資料庫系統。不過基於穩定性與功能性因素，仍然建議大家使用 PostgreSQL 作為 `apartment` 底層的資料庫系統。因此，以下的情境都會假設使用者使用的資料庫是 PostgreSQL。

## `apartment` 的基本應用與例子

為了讓大家了解更近一步了解 multi-tenant 的應用程式運作，在這個章節中會帶讀者一步一步建立一個 multi-tenant 的部落格網站。以下環境是基於 `ruby 2.4.1` 與 `rails 5.1.4`

> **附註**：這個範例因為夠簡單，即使不需要使用 `apartment`，也可以輕易透過傳統的 `where` 條件來實作。`apartment` 帶來的好處在當網站中的 model 數量夠多時才會比較明顯（也比較讓人願意使用 `apartment`），但這裡基於示範的目的而刻意在這個迷你專案中使用 `apartment`。

首先我們先來定義一下這個迷你專案的功能。我們會製作一個具有登入功能的部落格網站，每一個使用者登入之後都可以對屬於自己的文章進行 CRUD （Create, Read, Update, Delete）操作，且無法干涉其他使用者的資料。

資料庫結構的部分如下圖，我們只會有兩個 model，分別是 `User` 與 `Article`。`User` 是存放登入用的使用者，同時也是文章的擁有者。使用者登入系統的部分我們會直接使用 `devise`（[Github repo](https://github.com/plataformatec/devise)）這一個套件來建立。至於 `Article` 則是每個使用者自己的文章，這個 model 會直接透過 Rails 的 Scaffold 功能直接建立。

在這個架構中，我們希望 `Article` 是每個使用者各自分開的，讓他們不能互相干擾。而 `User` 則是不根據 tenant 分開，因為這個 model 是給 `devise` 登入系統使用，因此是所有 tenant 之間共用的（稱為 `public` schema）。

大部分的欄位相信讀者都不陌生，幾個值得注意的是：`User` 有個特殊的欄位稱為 `tenant_name`，這是用來區別這一個使用者的 tenant，讓 `apartment` 知道該去哪一個 PostgreSQL schema 存取資料。至於存放在各 schema 中的表得（如 `Article`）則不需要傳統的 `user_id` 之類的欄位來記錄該文章屬於哪一個使用者。

![資料庫結構圖](https://i.imgur.com/1P7WJYc.png)

### 第一階段：建立沒有 multi-tenant 功能的一般專案

我們先由建立一個沒有 multi-tenant 功能的專案開始，先確保我們需要的每個零件都有正常運作。之後再來加入 `apartment` 來實現 multi-tenant 功能。

- 建立新專案

```text
rails new apartment-demo
```

- 修改 `Gemfile`，加入要用到的 gem，並且將資料庫 gem 改為 `pg`，並執行 `bundle`

```ruby
gem 'devise'
gem 'apartment'
gem 'pg'
# gem 'sqlite3' # 註解掉原本的 sqlite3
```

- 修改 `database.yml`，改為使用 PostgreSQL

```yml
default: &default
  adapter: postgresql
  pool: <%= ENV.fetch("RAILS_MAX_THREADS") { 5 } %>
  timeout: 5000

development:
  <<: *default
  database: apartment-demo-dev

test:
  <<: *default
  database: apartment-demo-test

production:
  <<: *default
  database: apartment-demo-production
```

- 建立資料庫

```text
rake db:create
```

- 初始化 `devise`，並產生 devise views

```text
rails g devise:install
rails g devise:views
```

- 修改 `application.html.erb`，新增登入登出的連結

<script src="https://gist.github.com/lctseng/a26520daa61946ca5d15fed9fdbca8de.js"></script>

- 使用 `devise` 建立 `User` model，並加入 tenant_name 的欄位，同時也產生 controllers 供未來修改使用

```text
rails g devise user tenant_name:string
rails g devise:controllers users -c=registrations
```

- 修改產生的 migration file，記得將 `tenant_name` 設定為 `null: false` 並加入 unique index

```ruby
class DeviseCreateUsers < ActiveRecord::Migration[5.1]
  def change
    create_table :users do |t|
      ## Database authenticatable
      t.string :email,              null: false, default: ""
      t.string :encrypted_password, null: false, default: ""

      ## Recoverable
      t.string   :reset_password_token
      t.datetime :reset_password_sent_at

      ## Rememberable
      t.datetime :remember_created_at

      ## Trackable
      t.integer  :sign_in_count, default: 0, null: false
      t.datetime :current_sign_in_at
      t.datetime :last_sign_in_at
      t.inet     :current_sign_in_ip
      t.inet     :last_sign_in_ip

      t.string :tenant_name, null: false

      t.timestamps null: false
    end

    add_index :users, :email,                unique: true
    add_index :users, :reset_password_token, unique: true

    add_index :users, :tenant_name, unique: true
  end
end
```

- 修改 `app/views/devise/registrations/new.html.erb`，新增欄位讓我們可以填寫 `tenant_name`

<script src="https://gist.github.com/lctseng/eb1664442c6ff06a12a525e50899d491.js"></script>

- 修改 `routes.rb`，讓 `devise` 使用我們自訂的 controllers

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

- 修改 `app/controllers/users/registrations_controller.rb`，使得我們可以更新 `tenant_name` 這個欄位

```ruby
class Users::RegistrationsController < Devise::RegistrationsController
  before_action :configure_sign_up_params, only: [:create]
  def configure_sign_up_params
    devise_parameter_sanitizer.permit(:sign_up, keys: [:tenant_name])
  end
end
```

- 建立 `Article` 的 Scaffold。注意我們並不需要 `user_id` 欄位。

```text
rails g scaffold article title:string content:text
```

- 在產生的 `app/controllers/articles_controller.rb` 上方加入權限控制

```ruby
before_action :authenticate_user!
```

- 執行 DB migrate，此時可能會看到 `apartment` 噴出的一些警告，目前可以暫時忽略

```text
rake db:migrate
```

- 設定 `routes.rb`，將網頁的首頁指向文章列表

```ruby
root to: 'articles#index'
```

到目前為止，讀者可以啟動 `rails server`，檢視 `devise` 與 Scaffold 是否可以正常運作。這邊我們先註冊兩個使用者 Alice 與 Bob，其 `tenant_name` 分別設置為 `alice` 與 `bob`。此時雖然有使用者驗證，但你會發現此時的 `Article` 並沒有根據使用者做區別，所有人的文章都混在一起。

### 第二階段：使用 `apartment` 將不同 tenant 的資料區隔開

有了基礎專案之後，接下來就是進行 `apartment` 相關的修改，使得不同使用者之間的資料完全區隔。

- 建立 `apartment` 設定檔：`config/initializers/apartment.rb`，並修改內容：

```ruby
Apartment.configure do |config|
  # 因為 Devise 登入只能放在同一個 schema，因此將之從 apartment 排除
  config.excluded_models = ["User"]
  # 告知 apartment 如何找出所有的 tenant_name 供 migration 使用，這裡我們使用 User model 同名的欄位 tenant_name
  config.tenant_names = lambda{ User.pluck(:tenant_name) }
end
```

- 手動替 `alice` 與 `bob` 建立各自的資料庫 schema。由於前一階段並沒有替這兩個 tenant 建立 schema，因此這邊透過   `rails console` 手動建立

```ruby
Apartment::Tenant.create('alice')
Apartment::Tenant.create('bob')
```

- 讓未來新註冊的使用者可以自動建立 schema，修改 `app/controllers/users/registrations_controller.rb`

```ruby
class Users::RegistrationsController < Devise::RegistrationsController
  def create
    super do |user|
      # 這個 block 將在使用者被建立後執行，因此我們可以從這裡取出 tenant_name 來建立 schema
      Apartment::Tenant.create(user.tenant_name)
    end
  end
end
```

- 修改`app/controllers/articles_controller.rb`，限制所有的資料都只能在當前登入的 tenant schema 底下操作（也就是資料隔離）

```ruby
class ArticlesController < ApplicationController
  # 注意這幾個 before_action 的順序
  before_action :authenticate_user! # 設定 devise 時加入的
  before_action :switch_tenant # 新加入
  before_action :set_article, only: [:show, :edit, :update, :destroy] # scaffold 產生的

  # 這個 before_action 將會根據當前的使用者切換至該使用者的 schema
  def switch_tenant
    Apartment::Tenant.switch! current_user.tenant_name
  end
end
```

完成了！沒錯，就這麼簡單。重新啟動 rails server 後，你會發現現在 alice 與 bob 所建立的 `Article` 已經完全隔離了。不但不會在列表中看到別人的文章，就算透過 `/articles/1` 這樣的路徑，也只能看到自己名下編號為1的文章而已，沒辦法看到其他使用者的。此時你如果建立第三個使用者 Carol，其 `tenant_name` 為 `carol`，你也會發現這個新建立的使用者完全與其他人資料隔離。

本範例專案的原始碼也可以在 [Github](https://github.com/lctseng/rails-apartment-demo) 上找到。

## 使用 `apartment` 可能會遭遇到的問題

從上面的專案中我們可以看到使用 `apartment` 建立 multi-tenant 應用程式是多麼容易的事情。那為什麼這篇文章的標題卻又說「又愛又恨」呢？原因是 `apartment` 天生設計上就有一個缺陷，那就是當 tenant 數量成長到一定程度時，會出現許多預想不到的副作用。

最簡單的例子就是 Database Migration。因為 `apartment` 把資料完全隔離，所以在進行 migration 時各個 schema 會別處理。因此，當你使用的 schema 數量越來越大時，最首先感覺到的變化就是進行 migration 的時間會拉長。

另一個問題是記憶體消耗與程式啟動時間。由於在 `rails 4.2.2` 之前版本的架構中，會在啟動時根據資料庫 schema 中的表格逐個建立一份對應的資料存在記憶體中。這是個相當消耗時間與記憶體的動作。這個問題在 `apartment` 的 Github repo 中有給予一個 [patch 後的 rails 版本](https://github.com/influitive/apartment#excessive-memory-issues-on-activerecord-4x)，可以稍微舒緩記憶體壓力。

最後一個問題是硬碟空間。在某些檔案系統中，單一磁區所能儲存的檔案數是有上限的。因此如果 schema 總數太高，會造成 PostgreSQL 建立過多的檔案導致碰撞到這個上限。雖然這個問題解法比較多元，且不同檔案系統對檔案數上限也不同，因此也不一定會被讀者的專案所遇到。但如果今天萬一遇到了，不像前面幾個問題可以透過升級記憶體或者等待更長時間來解決，而是必須進行立即的資料搬移。我們都知道資料搬移是一個相當繁重的過程，且過程中可能需要讓服務停機，其損失不可估計。

## 實際案例

筆者近期經手的專案就一次碰到了以上三個問題。曾經有一個 `apartment` 專案使用了超過十萬個 schema，除了 migration 幾乎快要一整天以外，每次啟動 server 或 console 都要花費十幾分鐘的時間，且 server 記憶體動輒就消耗到 10GB。最嚴重的是這個專案還曾經在 production 營運時撞到了檔案系統的檔案數上限，導致服務差點就要凍結。

最後，在筆者與該專案開發團隊的努力下，成功找出一勞永逸的方案，並僅花四小時的停機時間進行資料轉換與搬移。詳細過程與解決方案，筆者將會在今年四月底舉辦的 [Ruby X Elixir Conf Taiwan 2018](https://2018.rubyconf.tw/program#liang-chi-tseng) 中分享這些細節，歡迎各位讀者共襄盛舉！

---

原文刊載於 [Henry Tseng's Digital Space](https://lctseng.github.io/post/multi-tenant-apartment/)

---

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

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

ASTRO Camp

線上課程

短期課程

專欄文章

最新消息

從模組化帶你認識 Webpack

CSS： calc() 數值運算

Ruby 冷知識：除法篇

Rails 部署工具，原來是這樣

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

The ABC of Rails Engines

Material Design 新利器：Material Theme Editor

從失敗案例重新思考敏捷開發價值

Multi-tenant 應用程式：讓人又愛又恨的 Apartment

電話 | (02) 2331-5247

信箱 | [email protected]

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

專業課程

ASTRO Camp

線上課程

短期課程

關於我們

關於五倍紅寶石

聯絡我們

媒體報導

部落格

專欄文章

最新消息

幫助與政策

常見問題

隱私權政策

服務條款