
Modern Web 的技術日新月異，但環境設定越來越繁瑣，組織程式也越來越不易，這對許多人而言，起手一個專案經常會是一個痛點，所以我想在接下來的 30 天裡介紹我的解法——打造一個結構健全、彈性、自動化、容易客製化、內建充足基礎設施（Infrastructure）的 Web 專案樣板。

我選擇 MongoDB、Expressjs、Reactjs、Nodejs 組成 MERN Stack 來實作 Boilerplate，目前已經有正常運作的版本，也有 [Demo Site](https://express-react-hmr-boilerplate.herokuapp.com/) 可以試玩，有興趣的讀者請參考我在 Github 的開源專案 [express-react-hmr-boilerplate](https://github.com/gocreating/express-react-hmr-boilerplate)。

## 為什麼要打造專案樣板呢？它能帶來什麼好處？

寫程式最忌諱重造輪子，能重複利用的東西最好都重複使用，而我寫了幾年 Web，深覺自己在網站開發上總是在不同專案間來回剪貼大量程式碼（也許此時的你也正在做著一樣的事情），最終，不同的專案裡充滿了大量重複的程式碼，Bug 也隨著複製程式碼散落到不同專案裡，想要維護卻發現束手無策，技術債越積越多...

對於這樣的問題，甚至說是痛點，我認為實作一套**半標準化**的樣板是一個不錯的解決方案，加上近來 Modern Web 的環境設定越來越複雜，不可能再用複製貼上的方式來管理，因此大約一年前的此時，我開始實作這麼一個 Boilerplate，至今我依然看好它，也覺得它的潛力越來越大，因為它確實解決了我的問題，我認為整體而言它帶給我以下幾個好處：

- 節省起始一個專案的時間
- 標準化繁瑣的環境設定
- 內建常見的功能與模組，也容易因應不同專案的需求進行客製化
- 程式碼集中在一個專案內維護

  搭配 Git 的操作，Clone 至不同專案的 Slave Boilerplate 也能追蹤 Master Boilerplate 的變動，統一解決 Bug，也統一增加 Feature，達到跨專案的程式碼重複使用。

## 多談**進階**，少談入門

我想談論的是內功，是心法，所以不希望把篇幅耗費在語法教學、工具操作等透過 Google 就可以學來的基本功上面，因此希望讀者們最好已經具備下列能力及知識：

- Git 操作
- Git Flow 的使用
- ES5 / ES6 語法
- JSX 語法
- React 元件寫法

廢話不多說了，咱們就開始ㄅ！

## 目錄

01. [Introduction](./01)
02. [File Organization](./02)
03. [Linting](./03)
04. [Automation](./04)
05. [Backend - Technique Stack](./05)
06. [Backend - Express](./06)
07. [Backend - MVC](./07)
08. [Frontend - Technique Stack](./08)
09. [Frontend - (React) & Flux & React-Redux](./09)
10. [Frontend - CSS Module](./10)
11. [Infrastructure - Introduction](./11)
12. [Infrastructure - Isomorphic API](./12)
13. [Infrastructure - Error Handling](./13)
14. [Infrastructure - Isomorphic Routing](./14)
15. [Infrastructure - Form](./15)
16. [Infrastructure - Authentication](./16)
17. [Infrastructure - Permission Control](./17)
18. [Infrastructure - i18n](./18)
19. [Infrastructure - Pagination](./19)
20. [Infrastructure - Mail Service](./20)
21. [Testing - Technique Stack](./21)
22. [Testing - 撰寫End-To-End API測試](./22)
23. [Testing - Travis](./23)
24. [Deploy - Technique Stack](./24)
25. [Deploy - Heroku](./25)
26. [Example - Start a new project](./26)
27. [Example - Todo List App](./27)
28. [Case Study - Customization for your own app](./28)
29. [Feature Works & Issues](./29)
30. [結語](./30)

## 開發哲學

開始 Coding 之前，我整理了 3 個與 Boilerplate 本身程式碼無關的開發哲學，我自己開發時會以這些原則來檢視我的程式碼，在此分享給各位讀者：

1. 你不是一個人，而是一個團隊

  言下之意就是，你寫的 Code 不是只有你一個人要用，變數命名請命一個大家看得懂的，能獨立抽出來的模組就抽出來，能共用的就共用，天曉得你的夥伴會不會哪天拿來用。所以身為團隊裡的一份子，產出的 Code 最好兼具可讀性、複用性、可維護性、高效率、可擴充性。

2. 專案有分 Development、Test 和 Production

  你的專案總有一天要推上線，不會無止境的處在開發階段，而是一個開發、測試、上線的週期，這和在學校寫作業交作業很不同。記得善用 `process.env.NODE_ENV` 讓你的程式在不同階段表現不同行為，例如 Error stack 只應該在 Development 環境下才顯示、Recaptcha 這種妨礙開發的東西應該要在 Production 時才 Turn on。所以開發 Feature 時，隨時想想這個 Feature 在 Development、Test、Production 三個環境下的表現分別是如何。

  產品必須經得起各種奧客的嚴苛測試，要耐得住使用者投機取巧，因此從 Boilerplate 層面開始，就必須要提供健全的 Infrastructure，才足以支撐後面建立在 Boilerplate 之上的不同專案。

3. Single Source of Truth（SSOT）

  真相只有一個，所以同一個值變數不要分兩個變數存，同一個 Data 不要分兩個欄位存，提高程式碼複用性也容易 Debug 降低維護成本。

  Boilerplate 本身就是 SSOT 的一個例子，真相是 Master Boilerplate，其他 Slave Boilerplate 都是假的，所以當 Slave 出現 Bug 時，只能修改那單一的來源：**Master**，再透過 Git 操作把修正 Bug 的更新套用到 Slave。


Day 01 - Introduction

為什麼要打造專案樣板呢？它能帶來什麼好處？


## 兩種主流做法[[1]][A Better File Structure For React/Redux Applications]

目前 React 相關的專案大多採用兩種目錄結構。

### 第一種：Feature-Based

```
user/
  User.js
  userActions.js
  userReducer.js
admin/
  Admin.js
  adminActions.js
  adminReducer.js
someProduct/
  SomeProduct.js
  someProductActions.js
  someProductReducer.js
```

### 第二種：Nature-Based

```
components/
  User.js
  Admin.js
  SomeProduct.js
actions/
  userActions.js
  adminActions.js
  someProductActions.js
reducers/
  index.js
  userReducer.js
  adminReducer.js
  someProductReducer.js
```

各位應該可以很直覺的看出兩者差異。

## Boilerplate 適用 Nature-Based

Feature-Based 比較符合模組化的精神，乍看之下似乎優於 Nature-Based 的作法，但現實中的專案不可能所有檔案都能完美按照 Feature 去歸類，因此這類的檔案在 Feature-Based 的結構下只能按照不同開發者的主觀來擺放，這主觀的擺法因人而異沒有標準，很容易破壞整體目錄結構。

Nature-Based 的結構就相對直覺，對一個剛加入專案的新人而言，甚至不用教學就能自己推測新增的檔案要擺在哪邊，我認為這樣的結構對於團隊是有利的，所以決定採用它。

## 考量 Isomorphic

我們使用的技術包含了 Nodejs 與 Reactjs，兩端的語法都是 Javascript，因此可以實現一個神奇的東西：Isomorphic。這個術語在 Modern Web 的領域指的是 Server-side 與 Client-side 共享同樣的程式碼片段（這邊我只先用一句話簡介，後面章節會有詳細的說明），例如表單的驗證，前後端都是一樣的檢驗邏輯，理論上只需要有一份共用的 Isomorphic Code，而不必前端寫一次，後端又寫一次。

為了避免開發時的混淆，我讓 Isomorphic 的程式碼獨立存放於 `common` 資料夾，而 Server-only 和 Client-only 的程式碼分別放在 `server` 與 `client` 資料夾，每個資料夾內有各自的 Nature-Based 檔案結構。

```
client/
  components/
  actions/
  reducers/
common/
  components/
  actions/
  reducers/
  utils/
server/
  models/
  components/
  actions/
  reducers/
  utils/
```

## 考量產品生命週期

從開發、測試到上線，每個階段都可能需要產生獨立的整份程式碼，所以我將專案最頂層的目錄分為 `src` 及 `build`。

```
build/
src/
  client/
  common/
  server/
```

## 完整目錄及檔案結構

實際上的專案還會加入許多的設定檔和相依模組，Code 也不會只有上面少少幾份，所以完整結構其實是長這樣的：

```
.git/
.deploy/           <-- 準備部署的檔案（設定檔、可執行檔、...）
node_modules/
configs/           <-- 專案設定
  env/             <-- 環境相關設定
  project/         <-- Web App 相關設定
build/             <-- 建置出來的可執行 Web
specs/             <-- Mocha 測試腳本
src/
  client/          <-- 只有 Client 端會使用的檔案
    index.js       <-- React App 的進入點
  common/          <-- 前後端共用的 檔案
    actions/       <-- 前後端共用的 Actions
    api/           <-- 前後端共用的 API
    components/    <-- 前後端共用的 元件
    constants/     <-- 前後端共用的 常數
    i18n/          <-- 前後端共用的 i18n 資料
    reducers/      <-- 前後端共用的 Reducers
    routes/        <-- 前後端共用的 元件路由規則
    utils/         <-- 前後端共用的 公用模組
  server/          <-- 只有 Server 端會使用的檔案
    api/           <-- 只有 Server 端會使用的 API
    components/    <-- 只有 Server 端會使用的 元件
    constants/     <-- 只有 Server 端會使用的 常數
    controllers    <-- 只有 Server 端會使用的 Controllers
    decorators/    <-- 只有 Server 端會使用的 Decorators
    middlewares/   <-- 只有 Server 端會使用的 Middlewares
    models/        <-- 只有 Server 端會使用的 Models
    routes/        <-- 只有 Server 端會使用的 路由規則
    utils/         <-- 只有 Server 端會使用的 公用模組
    index.js       <-- 注入開發環境所需的模組（如：babel-register）
    server.js      <-- Server 進入點
    app.js         <-- Express App 進入點
  public/          <-- 靜態檔案
.editorconfig
.eslintrc.json     <-- Eslint 設定檔
.gitignore
.travis.yml        <-- Travis 設定檔
gulpfile.js        <-- Gulp 腳本
LICENSE
package.json
README.md
```

這是 Boilerplate 的全貌，所以有些後面章節才會提到的東西目前還無法解釋清楚，請等候面章節的講解吧！另外沒解釋的部分可能是與我們的主題無關，或是太瑣碎不值得解釋，如有不懂處就請問問 Google 大神吧！

## 參考資料

1. [A Better File Structure For React/Redux Applications][A Better File Structure For React/Redux Applications]

[A Better File Structure For React/Redux Applications]: <http://marmelab.com/blog/2015/12/17/react-directory-structure.html>


Day 02 - File Organization

兩種主流做法[[1]][A Better File Structure For React/Redux Applications]


在撰寫程式碼時，通常會搭配所謂的 Linter 來控管程式碼的品質。再次強調我們的開發哲學：你不是一個人，而是一個團隊。透過 Linter 的協助，我們可以確保團隊中的每個人寫出來的程式碼風格幾乎一致，看起來就像出自同一個人的手，例如：變數命名必須遵守 Camel Case、if 條件式強迫加大括號、陳述式結尾強迫加分號、...，在我們的 Boilerplate 裡也內建了 Linting 的規則以及檢查指令。

## ESLint

目前有許多 JS 的 Linter，但 ESLint 最受好評，同時也是多數開源專案採用的選擇，我們的 Boilerplate 也是使用 ESLint。

筆者我其實一開始是使用 JSCS，用沒多久就跟風改用 ESLint 了，所以沒辦法替各位讀者做一個親身體會過的評比，我個人只對 ESLint 有個小小評論：Lint Rule 相較於 JSCS 瑣碎許多，可以訂定更細節的規則。根據網路文章的說法，ESLint 最晚釋出，主打 Pluggable 的特色，所以可以透過 Plgin 來支援 JSX 等特殊語法，另外它的 Lint 規則除了 Style 本身之外，還有一些規則是用來檢查 Syntax，這幾項應該是它成為主流的原因。

## 在 Atom 中使用 ESLint

Linter 好處多多，如果把 Linter 整合在編輯器內即時發現 Style 或 Syntax Error，那就更是如虎添翼了。我自己慣用編輯器是 Atom，所以就舉 Atom 當作例子，如果是使用 Sublime 或是 Webstorm 的朋友，也可以透過類似的方法來整合 ESLint。

1. 打開 Atom 安裝 Package 的頁面
2. 搜尋並安裝下面兩個 Packages
  - [linter](https://atom.io/packages/linter)
  - [linter-eslint](https://atom.io/packages/linter-eslint)
3. 重啟或重整 Atom

是的，就是如此靠北簡單，效果大致是這樣：

![03-1.png](/posts/2016-12-01-ithome-iron-man/03-1.png)

## Style Guide

每個團隊有各自偏好的 Style Guide，所以在 Boilerplate 中我無法直接訂定標準，因此僅簡單擴充 `standard`、`promise` 和 `react` 三套 Style Rules，所有設定檔皆在 `.eslint.json` 設定檔中。如果不知道自己需要什麼樣的 Style Guide，不妨參考各大軟體公司開放的或 Github 上公開的指南吧：[Airbnb JavaScript Style Guide](https://github.com/airbnb/javascript)、[Node.js Style Guide](https://github.com/felixge/node-style-guide)

## 規則解惑：max-len、comma-dangle 與 eol-last

有一些規則乍看之下可能會讓人無法理解，但又列在各種主流的 Style Guide 中，就讓我在此替各位解惑吧！

- max-len

  通常我們會將程式碼單行長度上限設為 80 或 120 字元，一方面提高可讀性，另一方面因為 Programmer 經常需要把編輯器畫面切割為左右兩半，80 ~ 120 字元的長度大約剛好可以占滿一邊的寬度，不必左右捲動就能看到程式碼全貌，增進 Coding 效率。

- comma-dangle[[1]][Why you should enforce Dangling Commas for Multiline Statements] & eol-last

  這兩個規則很奇妙，第一次看到的人一定會好奇，為什麼要在 Block 結尾補上多餘的逗號？為什麼要在檔尾補上多餘的換行？其實目的是增加 Code Review 的可讀性呀！！！

  當你沒加 Dangling Comma 時，Review 程式碼時會看到這個樣子：

  ![03-2.png](/posts/2016-12-01-ithome-iron-man/03-2.png)

  但若加了 Dngling Comma，就可以減少不必要的混淆：

  ![03-3.png](/posts/2016-12-01-ithome-iron-man/03-3.png)

  如果你能理解 comma-dangle 這條規則了，就可以類推到 eol-last 上，檔尾多餘的換行字元一樣是為了減少不必要的混淆。

## 針對部分程式碼忽略檢查

在部分極端情況下，你的程式碼被迫破壞 Lint Rule，例如你正在替某個頁面塞入又臭又長的假文方便觀看效果，或是你在註解裡附上了過長的網址，這些情境可能會違反 max-len 規則，因此你可能會需要讓 Linter 忽略這部分程式碼。實際作法請直接看範例吧：

```js
let {
  /* eslint-disable */
  // consume props owned by BsForm
  labelDimensions, fieldDimensions,
  /* eslint-enable */
  children,
  ...rest
} = this.props;
```

這是在 Boilerplate 中真正使用到的例子，我想抓出 rest 但不想要含有 labelDimensions 和 fieldDimensions 兩個 keys。如果不讓 Linter 忽略此行將會違反 no-unused-vars 規則，所以在這樣特殊的情境下，我強迫讓 Linter 忽略檢查此行程式碼。

## 參考資料

- [Why you should enforce Dangling Commas for Multiline Statements][Why you should enforce Dangling Commas for Multiline Statements]

[Why you should enforce Dangling Commas for Multiline Statements]: https://medium.com/@nikgraf/why-you-should-enforce-dangling-commas-for-multiline-statements-d034c98e36f8#.ct3po8ov7


Day 03 - Linting

規則解惑：max-len、comma-dangle 與 eol-last


所有良好的專案都需要健全的自動化系統在背後支撐，雖然實作自動化需要成本，但之後帶來的效益絕對會讓你一邊寫 Code 一邊笑到合不攏嘴。

## 何謂自動化？

我們提過專案的開發是有分 Development、Test 還有 Production 週期的，不同階段需要建置（Build）不同的檔案配置或環境，這些瑣碎的雜事傳統上是人工在 Terminal 上打出一系列的指令，包括編譯、轉譯、複製檔案、刪除中繼暫存檔、...等等，熟悉 Linux 的人可能會自己寫個 Shell Script 來執行這些例行性的流程，這就是**自動化**的精神。

再舉個例子，寫過 C 的人應該有 87% 知道 Makefile 這東西，只要把建置流程寫在 Makefile 內，再到 Terminal 輕鬆打下 `make` 四個字母，撲通一聲就產生可執行檔了。在這個例子中，make 的過程就是一種自動化。

## 為何專案需要自動化？

所以究竟為什麼要在專案中落實自動化呢？因為人為操作的過程有太多不謹慎，可能打錯指令，可能執行的流程顛倒了，還要浪費腦容量來背指令，身為一個工程師，怎麼可以容許自己做這麼蠢的事呢？另外，團隊的開發也是需要有一套共同的操作流程，不可能每一位團隊裡的成員都熟悉產品的建置流程，所以最好訂定一套一致的、語意明確的、簡易的自動化指令，例如要跑測試就統一執行 `npm test`，要部署程式就統一打 `gulp deploy`。

最後幫各位歸納一下自動化帶來的優點：

- 減少人為失誤
- 省時、省力、省腦容量
- 標準化團隊協作的流程

## Npm

前面所述是給各位一個大方向，現在我們回到 Node 的世界。大家所熟悉的 Npm 除了可以安裝套件之外，還有另一個重要功能，就是執行腳本。

馬上給各位一個實用的例子，請在你的任意 `package.json` 補上以下 `scripts` 的部分：

``` json
{
  ...
  "scripts": {
    "clean": "rm -rf ./build"
  },
  "devDependencies": {
    ...
  },
  "dependencies": {
    ...
  }
}
```

接著執行 `npm run clean` 就會自動執行對應的 `rm -rf ./build` 指令了。

而 npm 其實也內建了幾個快速指令對應到 package.json 中的 scripts，例如：`npm test` 對應到 scripts 中的 `test`；`npm start` 對應到 scripts 中的 `start`，其餘依此類推，完整對應的指令可以參考 Npm 官方文件 [npm-scripts](https://docs.npmjs.com/misc/scripts)。

實務上我們會把 scripts 拆的越細越好，一個 script 只專注完成一件工作，如果需要自動化執行一系列的大工作，就用 `&&` 將這些小工作串聯起來執行即可。一樣給各位一個實際用在 Boilerplate 中的例子：

``` json
{
  "scripts": {
    "test": "npm run lint && npm run mocha",
    "lint": "./node_modules/.bin/eslint --config=./.eslintrc.json ./src",
    "mocha": "mocha specs/index.js --timeout 10000",
  },
}
```

如此一來我只要執行 `npm test` 就可以自動檢查 Coding Style，接著執行 Mocha 的測試腳本了。

## 善用 Gulp，勿用 Grunt

利用 Npm 來實現自動化對於小專案是很足夠的，但對於 Boilerplate 則需要更進階的工具了，目前有兩套廣受好評的自動化工具：Gulp 與 Grunt。

先強調 Gulp 絕對遠勝於 Grunt。

Grunt 是 Configuration-Based，所以使用之前必須熟悉 Grunt 的設定檔結構，說難聽點就是我他媽要浪費腦容量記這雞八結構，而且可讀性之差讓我實在懶得吐槽，其次，Grunt 在處理某些複雜的操作時，必須要先建置出中繼檔案，說白話點就是它會製造**垃圾**，最後我最不能忍受的是，有少量需要高度客製化的流程過於複雜，已經超出 Configuration-Based 機制的極限了，所以根本就做不出來！做不出來！做不出來啊！

罵完了 Grunt 回來看看我們可愛又親切的 Gulp：

- Program-Based
- 可讀性高
- 容易擴充
- 使用 Streaming 搭配 pipe 語法，所以不會產生中繼檔案
- 無論多複雜的流程都能以優雅的方式寫成腳本

## 使用 Gulp

接著我們就直接看看 Gulp 的使用方式吧：

1. 在專案內建立一份 `gulpfile.js`
2. 以 JS 撰寫各種 Gulp Tasks
3. 執行 `gulp <task-name>`

### Gulp Task

Gulp 中最重要的元素就是 Gulp Task，它是一個個相依或獨立的**工作流程**，每一個 Gulp Task 寫法都是單純且一致的。

```js
gulp.task([dependencyTask1, dependencyTask2, ...], taskName, function() {
  // what this task is going to do
});
```

### 範例

讓我們來看個簡單的 gulpfile.js 範例（擷取自 [Boilerplate](https://github.com/gocreating/express-react-hmr-boilerplate/blob/dev/gulpfile.js)）：

``` js
var path = require('path');
var gulp = require('gulp');
var del = require('del');
var mergeStream = require('merge-stream');

var paths = {
  componentStyles: [
    './src/common/components/**/*.scss',
    './src/common/components/**/*.less',
    './src/common/components/**/*.styl',
    './src/common/components/**/*.css',
  ],
  statics: './src/public/**/*',
  targetDir: 'build',
};

// clean build files
gulp.task('clean', function() {
  return del.sync([
    paths.targetDir,
  ]);
});

// copy static files
gulp.task(['clean'], 'copy', function() {
  var staticTask = gulp
    .src(paths.statics)
    .pipe(gulp.dest(path.join(paths.targetDir, 'public')));
  var componentStyleTask = gulp
    .src(paths.componentStyles)
    .pipe(gulp.dest(path.join(paths.targetDir, 'common/components')));
  return mergeStream(staticTask, componentStyleTask);
});

gulp.task('default', function() {
  gulp.start('clean', 'copy');
});
```

當我執行 `gulp clean` 時，就會清除 build 資料夾；當我執行 `gulp copy` 時，會先確保 gulp clean 已經完成，接著才複製靜態檔案和各個 styles 檔案；當我執行 `gulp default` 時，會同時執行 gulp clean 及 gulp copy。另外，如果直接執行 `gulp` 而不指定 task name，預設就是執行 gulp default。

在本篇教學文中提到 Gulp 的目的不是要讓大家在本文中學會使用 Gulp，而是想讓讀者們知道有這樣的好工具，真正要學會它的話還是請上官網或者 Google 學習資源會比較有效率！

## Boilerplate 的自動化

在我們的 Boilerplate 中大量地使用了自動化，包括 Npm 及 Gulp，來完成以下的工作：

- 自動化 Linting
- 自動化 Build
- 自動化 Testing
- 自動化 Deploy

我傾向使用 Npm 實現 CLI 指令的自動化（例如 Linting），如有牽扯到複雜的流程或邏輯檢查時，再轉用 Gulp（例如 Build、Deploy）。

## 自動化的過程是痛苦的

乍看之下**自動化**百利無一害，但其實要在專案裡面套用自動化是需要經歷陣痛期的，你需要仔細看過 CLI Tool 的說明，或是 Gulp Plugin 要如何使用、如何設定、參數怎麼下，經歷這些過程時肯定會讓你感到挫折、感到煩燥。實做專案的自動化可能是個痛點，但我還是強烈建議各位讀者要扎扎實實地面對它，因為手動的成本真的太高昂了，長痛不如短痛！

## 筆者心情小補帖

還記得我剛接觸自動化時踩了一個大雷...

那時觀察 Open Source 界的風向發現大家都在用 Grunt，所以我也跟風先學 Grunt，不是我在亂蓋，但我真的是花了整整一個星期努力研究這糞物，瘋狂 Google 各種教學文卻一無所成，完全寫不出我想要的自動化流程。最後放棄 Grunt，隨手花了 30 分鐘看個 Gulp 官方介紹，X你X的我就這樣學會 Gulp 了，隨後花了 2 ~ 3 個小時就建出理想的流程...。至今每當我想起 Grunt 都還是覺得噩夢一場。


Day 04 - Automation


前面我們花了幾篇介紹概念性、原則性的東西，接下來我將整系列文章拆成 `Backend`、`Frontend` 還有 `Infrastructure` 三大面向來依序講解，所以今天就讓我們從 `Backend` 切入吧！

## 概觀

目前 Modern Web 的腳色劃分通常是把 Backend 定位成 API Server，Frontend 則是一些 Single Page Application（SPA），兩邊再透過 Ajax 的方式傳遞 Json 格式的訊息來互動。

在我們 Boilerplate 中的 Backend 除了當作 API Server 之外，也用於 React 元件的 Server Side Render（SSR），SSR 是因應 SPA 的興起而逐漸被重視的一項技術，之後在 Infrastructure 的部分我們會詳加介紹。

所以實作 API Server 需要怎麼樣的 Technique Stack 呢？在 Node 的生態系統中已經有很多出色的 Library 或 Framework，像是 Express、Koa、Hapi，但回頭想想 Boilerplate 的目的是要提供 General 的標準與解法，所以我還是比較傾向使用熱門的、大家熟知的模組，也就是 Express。

## Express

`Express` 是幾乎所有接觸 Node 網站開發的人都熟知的模組，可以很簡易且快速地架出 Web Server：

``` js
import express from 'express';

let app = express();
app.get('/path/to/anywhere', (req, res) => {
  res.json({
    hello: 'world',
  });
});

app.listen(3000, (err) => {
  console.log('app started');
});
```

當然這只是一段 Hello World 的範例，和實際的 Server 有很大一段落差，後面的兩篇我們再來談談怎麼樣組織出有彈性而且容易維護的 Express API Server。

## ORM 與 ODM

Backend 中有另一個重要的元素是資料庫，傳統上 PHP、Python、Ruby 較常使用關聯式資料庫（Relational Database），例如大家聽到爛掉的 MySQL，還有 MariaDB、PostgreSQL 等 SQL-Bsaed 的資料庫；但 Node 的生態中是以 JS 物件為基礎，資料儲存格式通常是 Json，所以慣例上是使用 MongoDB 這一類的 No-SQL 資料庫。

在實務上，我們不會直接使用原生寫法去存取資料庫，通常要使用 Node 存取 MongoDB 的話，還會再搭配所謂的 ORM（Object Relational Mapping）或是 ODM（Object Document Mapping），ORM 是針對 SQL-Bsaed 資料庫，ODM 是針對 No-SQL 資料庫，兩者意義是相同的，只是稱呼有些微差異而已。

ORM/ODM 是一種把資料庫操作抽象化的程式技巧，例如我們定義好 `User` 這個資料庫 Schema：

``` js
import mongoose from 'mongoose';

let UserSchema = new mongoose.Schema({
  name: String,
  email: {
    value: String,
    isVerified: Boolean,
    verifiedAt: Date,
  },
  password: String,
});

let User = mongoose.model('User', UserSchema);
```

接著就能以 Program-Based 的方式（而不是 Query-Based）來操作資料庫了：

``` js
User.findById(req.params.userId, (err, user) => {
  // 這邊使用 programming 的方式來更新物件
  user.name = req.body.newName;

  // 修改完成後存回資料庫
  user.save((err, user) => {
    console.log(user);
  });
});
```

多了這樣一層包裝，對效率多少會有影響，但是 ORM/ODM 帶來的效益對整個產品和整個團隊是遠勝過執行速度降低的成本，簡言之就是利大於弊：

- 方便

  如同上面範例所示，可以輕鬆地使用 Program-Based 的方式對資料進行任意操作，最後再使用 `save` 一次性寫回資料庫。

- 可以進行版本控制

  資料庫的結構一般是無法保存在 Source Code 裡的，但若使用了 ORM/ODM，自然就會把 Schema 寫入 Source Code 中，讓資料庫的結構也能被追蹤，減少環境設定的疏失。

- 安全

  通常 ORM/ODM 會內建一些文字的 Escape 機制，所以使用 SQL-Bsaed 資料庫的團隊就可以不用花心思去防止 Injection 之類的鳥事，進而把更多的時間專注在產品功能的開發。

## Mongoose

在我們的 Boilerplate 中使用的是 Mongoose，堪稱 Node 界家喻戶曉的 ODM 模組。其實上面的兩段範例程式就是 Mongoose 的實際使用方式，程式碼也是擷取自 [Boilerplate](https://github.com/gocreating/express-react-hmr-boilerplate/blob/dev/src/server/models/User.js)，它還包括了許多實用功能，像是欄位的驗證、虛擬欄位、自訂 Static Methods、自訂 Instance Methods 等等，詳細功能建議先 Google 教學文章來看，等到熟悉了再去啃官方文件。


Day 05 - Backend - Technique Stack


今天主題雖然是 Express，但我的重點其實是想放在 Express 的核心 `Middleware` 這個東西上面，因為它對程式的執行流程有很重大的影響，希望各位讀者看完本篇後，未來寫 Code 時都能好好善用 Middleware。

## Middleware

Middleware 的中文通常翻譯作「中間件」，不過我個人認為翻得不好，從中文字面無法領悟到背後的意義。假設我們有一個程式的執行流程是 A → B → C → D，進入點是 A，結束點是 D，而且後面執行的程式需要依賴前面執行的結果，在這個例子中，A、B、C 都可以算是 Middleware。

上面例子其實很抽象，我們轉換到 Web 的思維，當一個 Request 進到 Server，我們要做的事情可能依序包括：

1. 檢查使用者是否已經登入
2. 檢查使用者是否具有足夠權限瀏覽目前頁面
3. 解析 Header，取出 locale
4. 解析 Payload，取出使用者填寫的表單資料
5. 檢查 Recaptcha 值是否正確
6. 驗證表單資料
7. 將表單資料轉存資料庫，Server 回傳 Response

而這些流程還夾帶著後者依賴前者的關係：登入過的使用者才需要檢查權限，權限許可的使用者才能進行後續操作，解析 Payload 之後才能知道 Recaptcha 欄位填寫的值，才能驗證 Recaptcha，確認不是機器人後，再繼續往下驗證表單資料是否都符合格式，當前面的每一步都過關之後，才允許真正地將資料寫入資料庫。

每一個路由都要對應不同的執行流程，不同的路由又可能會有重複或雷同的執行流程，如果你對於實作這樣複雜繁瑣的 Server 程式已經感到頭暈目眩，請不要害怕！Middleware 就是為了這樣的情境而生的。你可以將上述的 7 個步驟拆成 7 個不同的 Middleware 模組，在不同路由中只需要載入不同的 Middleware 模組就可以達到複用的效果，同時又能輕鬆管理錯縱的執行流程。

## Express Middleware

直接舉一個 Boilerplate 中實際使用的例子：

``` js
app.get(
  '/api/users',
  authRequired,
  roleRequired([Roles.ADMIN]),
  userController.list
);
```

當使用者想要存取 `/api/users` 這個資源時，先經過 `authRequired` 這個 Middleware 檢查使用者是否已經登入，再經由 `roleRequired` 檢查使用者是否具有 Admin 權限，當前面兩個 Middlewares 都通過了，再透過 userController 來回傳結果給 Client 端。

Express 的 Middleware 是一個長這樣的 Function：

``` js
let authRequired = (req, res, next) => {
  if (!req.isAuth) {
    return res.json({
      error: '使用者未登入',
    });
  } else {
    return next();
  }
};
```

`req` 和 `res` 物件是 Express 處理 Request 和 Response 的機制，各位應該不陌生，而 `next` 是一個 Callback Function，也是掌控 Middleware 流程的核心，當我們呼叫 next 時可以進到下一個 Middleware。所以上面的例子中，當使用者還沒登入時，直接送回 Reject 訊息；當使用者是登入狀態時，我們呼叫 `next` 進入下一個 Middleware，繼續執行後續程式。這樣的寫法是不是很漂亮呢？

## Boilerplate 中的 Middleware

讀者們如果有興趣可以翻翻 Source Code 中的 [`/src/server/middlewares`](https://github.com/gocreating/express-react-hmr-boilerplate/tree/dev/src/server/middlewares) 資料夾，我們提供了大量的 Middlewares，有的是一次性的（如：initCookie），有的是按照 Request 需求選擇是否要使用（如：bodyParser、authRequired、roleRequired），有的則是對所有 Request 都使用（如：morgan）。

## 隨處可見的 Middleware

Middleware 的概念其實不只用於 Express 中，例如 Python 的著名架站框架 Django 就是以 Decorator 的形式來管理 Middleware，下例中的 `csrf_exempt` 和 `login_required` 就是 Middleware：

``` py
@csrf_exempt
@login_required
def apiWhiteListRenew(request):
    if request.method == 'POST':
        # ...
```

另一個例子是 Redux，在 Dispatch 每一個 Action 時，會先經過預先設定好的每一個 Redux Middleware，我就點到為止吧，再講下去就離題太遠了，另外，Redux 是狀態管理（State Management）的 Library，在後面的章節裡會再次提到。

## 犧牲效率，換取維護性與彈性

在程式語言中，便利通常是犧牲效率換來的，Middleware 也是如此。在 Express 依序進入 Middlewares 時，會產生內部管理必要的 Overhead，在一些探討效率的文章中通常會建議少用 Middleware，但筆者認為，Middleware 帶來的便利也是同等重要，一來程式碼有高度複用性，二來容易維護。若要在效率和便利之間取捨，我還是會選擇便利。


Day 06 - Backend - Express


前面了解了 Backend 所需的 API Server 和 Database，加上 Middleware 這個利器，接著就可以談論怎麼`組織` Express 程式，讓 Client、Express API Server、Database 三者互相溝通協調。

## MVC

MVC 是一種軟體架構模式，把軟體切割成三大元素：**M** odel、**V** iew、**C** ontroller。如果從 Express Web App 的角度來看，Server 收到 Request 後先比對路由，之後進入 Middlewares 及 Controller 所控制的執行流程，Middlewares 或 Controller 可能隨時操作 Mongoose 的 Model 來向資料庫存取資料，存取結束後進入下一個 Middleware，當所有 Middleware 都走過了，Controller 再把資料灌進 View 樣板中渲染（Render）出 Html。我們在 Boilerplate 中的 View 的部分是使用 React，但那又是另一門學問了，我們留待後面章節再來介紹。

## 組織模組

有了上述 MVC 概念後，我們來看看 Boilerplate 是怎麼拆解和組織架構的：

### 檔案結構

各位可以比對 [Day 02 - File Organization](./02) 中列出的完整架構，這裡只取出 server 資料夾的部分。

```
/src/server/
  models/
  controllers/
  middlewares/
  routes/
  app.js
```

`app.js` 是程式進入點，`models` 資料夾儲存 Model 相關的模組，`controllers` 資料夾儲存 Controller 相關的模組，其餘資料夾依此類推，各資料夾內可以建立各自的 `index.js` 來整合資料夾內的模組。

### 程式碼範例

程式進入點依序註冊 Middlewares 與 Routes，接著啟動 Server：

``` js
// src/server/app.js

import express from 'express';
import middlewares from './middlewares';
import routes from './routes';

let app = express();
middlewares({ app });
routes({ app });
app.listen(port, (err) => {
  console.log('Listening at port', port);
});
```

`middlewares/index.js` 統整 Middlewares：

``` js
// src/server/middlewares/index.js

import middleware1 from './middleware1';
import middleware2 from './middleware2';

export default ({ app }) => {
  app.use(middleware1);
  app.use(middleware2);
  // ...
};
```

每一個 Express Middleware 模組獨立寫成一份檔案：

``` js
// src/server/middlewares/middleware1.js
// src/server/middlewares/middleware2.js
// ...

export default (req, res, next) => {
  if (/* some condition */) {
    // send reject response
  } else {
    next();
  }
};
```

`routes/index.js` 一樣整合整個 App 的路由：

``` js
// src/server/routes/index.js

import apiRoutes from './api';
import anotherRoutes from './another';
import stillAnotherRoutes from './stillAnother';
import otherRoutes from './other';

export default ({ app }) => {
  apiRoutes({ app });
  anotherRoutes({ app });
  stillAnotherRoutes({ app });
  otherRoutes({ app });
  // ...
};
```

在 API 的路由中設定對應的 Middlewares 和 Controller：

``` js
// src/server/routes/api.js

import bodyParser from '../middlewares/bodyParser';
import todoController from '../controllers/todo';

export default ({ app }) => {
  app.get('/api/todos', todoController.list);
  app.post('/api/todos', bodyParser.json, todoController.create);
  app.put('/api/todos/:id', bodyParser.json, todoController.update);
  app.delete('/api/todos/:id', todoController.remove);
};

```

Controller 和 Mongoose Model 互動後取回資料，再以 Json 形式回應給 Client。我們的 Server 主要是用於提供 API 服務，所以此例中沒有給出 Render View 的範例寫法。

``` js
import Todo from '../models/Todo';

export default {
  list(req, res) {
    // ...
  },

  create(req, res) {
    // ...
  },

  update(req, res) {
    // ...
  },

  remove(req, res) {
    Todo.remove({_id: req.params.id}, (err) => {
      res.json({});
    });
  },
};
```

Model 部分的程式碼在此就不贅述，請參考 [Day 05 - Backend - Technique Stack](./05)。

值得一提的是，我們在這程式中用到了 ES6 的 Object Literal 技巧來傳遞 `app` 這個變數，這麼做的好處是保留彈性，日後我們想傳遞別的參數時，不必影響原有的程式架構。

至此，我們算是優雅地建立出 Backend 的服務了，Model、Controller、Middleware、Route、...皆有各自獨立的資料夾，如有必要，也可以建立資料夾內的 index.js，這樣日後要擴充模組時就十分容易，同時也維持了 MVC 的結構。


Day 07 - Backend - MVC


終於來到 Modern Web 近來最蓬勃發展的 Frontend 部份了！！本文會簡略帶過 Modern Web 的術語還有 Boilerplate 採用的 Frontend 技術，如果你已經熟知這個部份了，建議直接跳過 Frontend 部分，直接閱讀 Infrastructure 的部分。

## SPA，Single Page Application

傳統網頁做一個動作就必須要刷新整個頁面，Server 需要回傳整頁的 Html，速度慢，互動性差，而且對 Server 的負擔又重。而最近被大家熱議的 SPA 則不同以往，它只有單一的主頁面，剩餘的整個 App 都被打包成 Javascript，可以一次性載入整個 App，也可以採用 Lazy Loading 的方式，以 Ajax 的形式載入操作 App 所需的必要部分。

據筆者所知，BackboneJs、AngularJs 等 Framework / Library 撰寫的 App 都屬於 SPA，而最近興起的則有 ReactJs 與 VueJs。

## React

Boilerplate 的整個 Frontend 是由 React 貫串起來的，ReactJs 是由 Facebook 推出的 View Library，提醒各位讀者，它是專門處理 `View`，所以不像 AngularJs 可能還有 `Model` 和 `Controller`，React 也只是單純的輕量 Library，不是重型的 Framework。

筆者認為 React 之所以廣受好評是因為 `Write Once, Run Anywhere` 的精神，在 React 中有所謂 JSX 和元件化的語法，除了用來寫 Web App 之外，其實還能用來寫 Native 的手機 App，有興趣的人可以搜尋一下 `React Native`。

## Webpack

撰寫 SPA 時會使用到大量的 Javascript，而且為了方便維護，通常會將檔案切割成 Common JS 或 AMD JS 模組，但這並不被原生 JS 所支援，因此我們需要一套工具來把這些分散的模組串聯在一起，並且打包成原生 JS 可以處理的語法，甚至還要為了 Development 環境建立 Source Mapping，或是為了 Production 壓縮整份 JS。

基於上面種種原因，我們撰寫 SPA 時通常會搭配 Webpack 這套打包工具來建置可執行的 JS。Webpack 是目前最受歡迎的工具，但其實在 Modern Web 剛起步的階段，Browserify 這個工具也曾紅極一時，而目前我們的 Boilerplate 也是按照主流採用 Webpack。

## CSS Module

Webpack 基於 Loader 的技術讓我們不只可以 Import JS 檔案，還可以 Import CSS 檔案，稱之為 CSS Module，甚至還可以 Import 圖片檔、字型檔，只要 Loader 支援，你想 Import 什麼都可以。在 Boilerplate 中，我們已經實作了 CSS Module 的部分，可以 Import SASS 檔案，Webpack 的設定已經幫各位搞定，使用範例可以參考 [`HomePage`](https://github.com/gocreating/express-react-hmr-boilerplate/blob/dev/src/common/components/pages/HomePage/index.js) 元件的寫法：

``` js
// ...
import s from './styles.scss';

const HomePage = (props) => (
  <PageLayout>
    <p className={s.redBorder}>
      // ...
    </p>
  </PageLayout>
);

export default HomePage;
```


Day 08 - Frontend - Technique Stack


我們說過這是一系列進階文章，所以 React 的部分就不多提了，想入門的讀者再自行 Google。而 React 最精華的部分就屬它的 Data Flow —— `Flux`，今天就來了解一下它吧！

## Flux

React 只專注在 View 的部分，對於現實生活的應用顯然不敷使用，因為真實的應用除了視覺上的 UI 以外，還需要包裝商業邏輯、資料的讀取及寫入、...等雜七雜八的東西。因此，Facebook 內部還提出了 `Flux` 架構，Flux 最核心的精神就是「資料是單向流動」（One-way data flow）還有 「Single Source of Truth」（SSOT），網路上一定有講解得比我更清楚的文章，如果你嫌麻煩懶得找，我會在下方用我的話解釋。

Flux 的整體架構如下圖所示：

![09-1.png](/posts/2016-12-01-ithome-iron-man/09-1.png)

我們先看圖中的四大元素 `React Views`、`Actions`、`Dispatcher`、`Store`。`React Views` 大家顯然都很清楚它在幹嘛了；而 `Actions` 則是使用者操作 View 的過程中產生出來的互動，每一個 Action 都是純粹的 JS 物件；這些物件必須經過 `Dispatcher` Function 來派送給 Store 做進一步處理；`Store` 是所有 View 所需要用到的 Data 的唯一來源（SSOT），廣義來看的話，這相當於把 React 元件的 State 萃取出來放到 Store，所以當 Store 接收到不同的 Actions 時也會跟著變化；當 Store 產生變化，也就代表 State 改變，React Views 就會跟著重繪。

其中比較複雜的是 Action，現實應用中有可能使用者的某一個動作會觸發兩個以上的 Actions；又或者我們想寫入 Store 的 Data 還在 Server 上，需要先呼叫 API 把 Data 下載至 Client 端，才有辦法將 Data 包入 Action 物件派送出去。基於這些原因，我們實務上還會使用 `Action Creator` 來包裝 Actions，Action Creator 是一個 Function，回傳值是 Action 物件。有了 Action Creator，我們就能在內部執行 Web API Utils 來呼叫 Web API 了。

## React-Redux

Flux 只是一種架構，真正實作它的 Library 有許多個，而我們的 Boilerplate 選擇使用 React-Redux，詳細用法請見 [Github](https://github.com/reactjs/react-redux)。

## Redux

這邊我認為有必要補充說明一下，`Redux` 只是一套狀態管理的 Library，它和 React 或 Flux 並無關連，請不要將 Redux 誤以為是 Flux 的一種實作。Redux 的精神是將所有 State 都集中到一個 Root 節點上，從這個 Root 長出一棵 State Tree，並且使用了 Reducer 的概念，將這巨大的 State Tree 的 Sub Tree 傳遞至不同的 Reducer Function 來轉移 State。

所以 React-Redux 其實是利用 Redux 來管理 Flux 中的 Store，再外加兩個 API 來包裝成 Flux：

  - `<Provider />`

    Provider 元件 Expose 整顆 State Tree 到 Context 中的 `store` 變數。

  - connect

    connect 則是一個 HOC（Higher Order Component），接收 context 中的 store，再轉為 props 傳遞給被包裝的 Component。

再加上 Redux 本身是採用 Reducer 來簡化狀態管理，整體看來 React-Redux 簡直是 Flux 架構的首選。

## Boilerplate 中的 Redux

Redux 其實是貫串 Backend 與 Frontend，在 Boilerplate 中扮演著很重要的腳色，包括 Router、Authentication、Form 在內的許多 Infrastructures 都是靠著 Redux 組織起來的，後面介紹 Infrastructure 時就可以見識到它的威力了。


Day 09 - Frontend - (React) & Flux & React-Redux


借助 Webpack 的力量，我們可以在 SPA 大量使用 JS 開發的環境下，一樣使用 JS 的形式來 Import CSS。在 Webpack 的世界，所有 Import 的檔案都稱為 Module，因此我們 Import 的 CSS、LESS 或是 SASS 檔案就概稱為 CSS Module。

## 在 React 中使用 CSS

我們先拋開 CSS Module 來看看在 React 中使用 CSS 有哪些做法，後面再來選擇 Boilerplate 應該實作何種方法。

### 方法一：Style Prop

直接將 Style 寫成 JS 物件，當作 Component 的 prop 傳遞進去：

``` js
class ExampleComponent extends Component {
  render() {
    return (
      <div
        style={{
          border: '1px solid red',
        }}
      >
        foo bar
      </div>
    );
  }
}
```

### 方法二：Dynamic ClassName

將 CSS 獨立寫在外部檔案，再以 Module 形式載入，此方法必須搭配 Webpack 的設定。

``` css
/* styles.css */
.redBorder {
  border: 1px solid red;
}
```

``` js
import cx from 'classnames';
import styles from './styles.css';

class ExampleComponent extends Component {
  render() {
    let { className } = this.props;

    return (
      <div className={cx(styles.redBorder, className)}>
        foo bar
      </div>
    );
  }
}
```

為了避免不同 Component 之間的 className 互相衝突，一般在 Webpack 的設定中會將 `styles.css` 中的 class 重新命名，例如加上一段 hash，或是加上 Scope 名稱。所以上例中的 `redBorder` 經過 Webpack 的 Loader 轉換後可能會被重新命名為 `styles_redBorder_vgo`，其中 `styles` 是 Scope，`vgo` 則是一段 hash。

由於 className 是動態產生的，所以 assign 給 Component 時不能寫死成 `className="redBorder"`，必須要以變數方式傳遞：`className={styles.redBorder}`。

### 方法三：Fixed ClassName

第三種作法和方法二類似，只是 Webpack 的設定少了一點，使用固定的 className，不做重新命名。

通常這個寫法是用在 Library（例如：[react-dates](https://github.com/airbnb/react-dates)），因為元件的 className 是寫死的，所以我們可以不採用 Library 本身提供的預設樣式自己刻一套，如此才能保留 Library 的彈性。

``` css
/* styles.css */
.redBorder {
  border: 1px solid red;
}
```

``` js
import cx from 'classnames';
import './styles.css';

class ExampleComponent extends Component {
  render() {
    return (
      <div className={cx('redBorder', className)}>
        foo bar
      </div>
    );
  }
}
```

### 方法四：Styled Component

這個方法是最近出現的，筆者也還沒使用過，有興趣的讀者可以看看 [styled-components](https://github.com/styled-components/) 這一套 Library。

## 在 Boilerplate 中使用 CSS Module

我並不擅長前端，所以當初在規劃 Boilerplate 要如何整合 CSS 時並沒有做太多研究，而且開源界的風向也非常亂，前面提及的方法一至方法四都有人使用，當時就隨手挑了方法二 Dynamic ClassName 整合進 Boilerplate 中，而且還搭配了 `sass` 及 `webpack-isomorphic-tools` 一起使用。

其實越往後寫越發現方法三 Fixed ClassName 才是最佳解，所以在此跟各位讀者抱歉，我們的 Boilerplate 押錯了寶，選到了方法二，日後我應該會找個時間調整成方法三 QQ


Day 10 - Frontend - CSS Module


總算來到 Infrastructure 的部份了，前面用了 10 篇，也正好是 1/3 的篇幅，講解一些 General 的概念及架構，現在我要再用另外 1/3 的篇幅來告訴你我們的 Boilerplate 精華之處，其實這也是我撰寫這一系列文章的主要目的。

## 面對殘酷的現實世界

一個真正要上線的 Web App 要顧慮的事情真的很多，先從使用者的觀點來看：

- 要以最快的速度看見網站內容
- 要漂亮的處理各種異常或錯誤狀況，不要網站掛了結果畫面就一動也不動
- 要讓網站在 Google 排行榜上有名
- 要以最快的速度載入站內的其他連結
- 要有 FB 登入、Google 登入、各種社群登入
- 要有管理用的後台
- 要有多國語系

再從開發者的角度來看：

- 程式從 Backend 到 Frontend 的每個環節都會出現各種不同型態的錯誤，根本一團混亂不易管理
- Frontend 與 Backend 都要做表單驗證，一樣的邏輯卻要寫兩次，不易維護
- 要有防止被機器人灌爆的機制
- List 某個 Collection 時要有「分頁」的機制（要讓使用者能操作上一頁、下一頁、第一頁、最後一頁、...）
- 要防止各種安全議題
- 要處理寄信服務
- 要注意不同瀏覽器的相容性
- 要整合 Storage Server

除了上列這些功能性層面的東西，身為一個工程師，你還必須要掌控程式碼的品質，要有彈性、容易維護、容易測試、容易擴充，那些覺得寫網站很簡單的人真的是要嘛腦袋有洞，要嘛就是腦袋裝屎啦！

真的不得不說 Github 上面翻到的大多數 Boilerplate 根本都是在玩扮家家酒，Boilerplate 是用來節省開發時間的，是用來讓你開心工作、輕鬆維護的，結果這些來路不明的 Boilerplate 給出來的是什麼東西呢？Server 還真的是夠陽春的，只用來 Host 靜態檔案；表單連個 ReCaptcha 都沒有，隨便寫個 Bot 就打趴了；支援多國語系的更是少得可憐。咱們是要實戰，不是交作業啊！

對不起我抱怨完了。

所以我們的 Boilerplate 其實投入了大量的時間在實作上述的各種 `Infrastructure`，這些才是真實世界的 App 需要在乎的細節不是嗎？我已經幫各位讀者顧及全局，找出我認為是最佳解的架構及寫法，後續文章將會講解我是如何實作這些 Infrastructure，以及這樣的寫法有什麼樣的好處。如果讀者們不想浪費時間實作這些 Infrastructure，可以直接拿我們的 Boilerplate 來使用，如果你正在實作自己的 Boilerplate，也歡迎改良我的作法。

## Isomorphic

今天是 Infrastructure 的 Introduction，所以先來給各位讀者一顆震撼彈吧！今後我們會一直提到 `Isomorphic` 這個術語，不用急著開 Google 翻譯了，因為翻了你也是看不懂的，請直接閱讀 Airbnb 的這篇精采教學文：[Isomorphic JavaScript: The Future of Web Apps](http://nerds.airbnb.com/isomorphic-javascript-future-web-apps/)。

如果各位看完了還是「不明覺厲」，我會用我的理解來詮釋一遍。

![11-1.png](/posts/2016-12-01-ithome-iron-man/11-1.png)

Node 的世界前後端都是撰寫 JavaScript，因此讓我們可以衍伸出前後端共用程式碼的技巧，這其實已經反映在我們 Boilerplate 的檔案結構的 `client`、`common`、`server` 三個資料夾上了。Frontend 透過 Webpack 打包時，是取出 `client` 及 `common` 兩個資料夾中的程式碼；Backend 的 Server 執行時，是跑 `server` 及 `common` 兩個資料夾中的程式碼。所謂的共用並不全然是讓一樣的程式碼表現一樣的行為，而是一整包 common 程式各自表述，當程式碼跑在 Client 時，要表現出 A 行為，當程式碼跑在 Server 時，又要表現出 B 行為，實務上的程式其實會長成這樣：

``` js
if (process.env.BROWSER) {
  // client-side, do A
  document.getElementById(...);
} else {
  // server-side, do B
}
```

上圖擷取自 Airbnb 的教學文，我覺得它有助於視覺化 Isomorphic App 的概念，撰寫 Isomorphic 程式時隨時想想這張圖，可以有效地幫助思考。

## Isomorphic vs Universal

有的人可能除了聽過 Isomorphic，還聽過 `Universal`，其實兩者是不同的東西，但我認為沒有必要在此系列文章裡鑽這種牛角尖，你只要知道他們是不同的東西即可，但我在文章裡的用語為了方便還是會統稱為 `Isomorphic`。想要深入了解的讀者可以參考 [Isomorphism vs Universal JavaScript](https://medium.com/@ghengeveld/isomorphism-vs-universal-javascript-4b47fb481beb#.d8lozaufr) 一文。


Day 11 - Infrastructure - Introduction


這裡所謂的 API 指的是 Client 向 Server 的某一個 Path 發出 Request，比如說：

- `POST /todos`
- `GET /todos/9527`

初學者很可能用慣了 jQuery，`$.ajax` 用的很開心，於是就會寫成這副德性：

``` js
@connect(({ todo }) => ({ todo }))
class ExampleComponent extends Component {
  componentDidMount() {
    let { dispatch } = this.props;

    $.ajax({
      url: '/todos/9527',
      type: 'GET',
      dataType: 'json',
      success: (json) => {
        dispatch(setTodo(json.todo));
      },
    });
  }

  render() {
    return (
      <div>{this.props.todo.text}</div>
    );
  }
}
```

這樣的寫法我個人覺得太冗長，不夠簡潔，不夠優雅，不易管理也不易維護。

## ApiEngine

其實要對 Server 發出 Request 有很多種作法，每個人習慣使用的 Library 可能也不盡相同，例如前面例子中的 jQuery，或者是目前最新潮的 Fetch API，我把這些用來協助我們發送 Request 的 Agent 統稱為 `ApiEngine`。

為了因應每個人不同的習慣，我在 Boilerplate 中把 ApiEngine 獨立抽象成一個 Class，目前使用的核心 Package 是 [superagent](https://github.com/visionmedia/superagent)，這個 Class 有四個對應 HTTP Verb 的 Instance Methods：`get`、`post`、`put`、`del`。

``` js
export default class ApiEngine {
  get(path, { params, data, files } = {}) {
    // ...
  }

  post(path, { params, data, files } = {}) {
    // ...
  }

  put(path, { params, data, files } = {}) {
    // ...
  }

  del(path, { params, data, files } = {}) {
    // ...
  }
};
```

> 完整程式碼：[src/common/utils/ApiEngine.js](https://github.com/gocreating/express-react-hmr-boilerplate/blob/dev/src/common/utils/ApiEngine.js)

這樣做的好處是，習慣使用 jQuery 的人可以寫自己的一套 jQueryApiEngine Class，習慣使用 Fetch 的使用者也可以寫一個 FetchApiEngine Class，只要 Expose 共同的四個 Instance Methods，無論你是 jQuery、Fetch 還是 Superagent，日後呼叫 API 的寫法都將會是一致的，如此便兼顧了彈性與可維護性。

我在實作上把 `apiEngine` Instance 塞入 Flux 的 Store 中，搭配 `setApiEngine` 這個 Action Creator 來切換目前要使用的 ApiEngine：

``` js
let apiEngine = new ApiEngine();
store.dispatch(setApiEngine(apiEngine));
```

> 完整程式碼：[src/client/index.js](https://github.com/gocreating/express-react-hmr-boilerplate/blob/dev/src/client/index.js#L35-L36)

## Isomorphic API & Promise

經過了 ApiEngine 的包裝，實務上開 API 模組時還能夠再包裝成 Function，並且加上 RESTful 的語意：

``` js
export default (apiEngine) => ({
  list: ({ page }) => apiEngine.get('/api/todos', { params: { page } }),
  create: (todo) => apiEngine.post('/api/todos', { data: todo }),
  read: (id) => apiEngine.get(`/api/todos/${id}`),
  update: (id, todo) => apiEngine.put(`/api/todos/${id}`, { data: todo }),
  remove: (id) => apiEngine.del(`/api/todos/${id}`),
});
```

> 完整程式碼：[src/common/api/todo.js](https://github.com/gocreating/express-react-hmr-boilerplate/blob/dev/src/common/api/todo.js)

此外，每一個 API Function 都應該以 Promise 的形式來處理，這讓我們可以明確掌控非同步的流程、可以有一致的錯誤管理機制，而且最重要的是 Promise 在前後端都能跑，這就意味著它是 Isomorphic 的寫法，所以 **ApiEngine 中的四個 Instance Methods 回傳值必須是 Promise**。

### 如何在 Client 端使用 API

我們就直接重構文首的範例吧，順便讓讀者可以比較其中差異。

``` js
import { connect } from 'react-redux';
import todoAPI from '/common/api/todo';

@connect(({ apiEngine, todo }) => ({ apiEngine, todo }))
class ExampleComponent extends Component {
  componentDidMount() {
    let { dispatch, apiEngine } = this.props;

    todoAPI(apiEngine)
      .read(9527)
      .then((json) => {
        dispatch(setTodo(json.todo));
      });
  }

  render() {
    return (
      <div>{this.props.todo.text}</div>
    );
  }
}
```

### 如何在 Server 端使用 API 預載入 State

前面說到這種 API 寫法是 Isomorphic，所以看過 Client 端的例子再來看看 Server 端的用法：

``` js
export default {
  // ... other controllers
  fetchTodo: (req, res, next) => {
    todoAPI(req.store.getState().apiEngine)
      .read(req.params.todoId)
      .then((json) => {
        req.store.dispatch(setTodo(json.todo));
        next();
      });
  },
};

```

> 完整程式碼：[src/server/controllers/ssrFetchState.js](https://github.com/gocreating/express-react-hmr-boilerplate/blob/dev/src/server/controllers/ssrFetchState.js#L36-L49)

這個 Server 端的使用範例是用來搭配 SSR 的頁面，當你想要在 Server 上就先載入 Store 中的某些 State 時，就可能需要在 Server 先呼叫 API。這麼說也許有點抽象，實際應用例如：部落格的文章，如果搭配在 Server 端預載入 State，搜尋引擎就能夠爬到文章內容，這對 SEO 是非常有幫助的！

## 用 Action Creator 包裝 API

一些網路範例中甚至會把 API 的呼叫包入 Action Creator 中，這就必須搭配 [redux-thunk](https://github.com/gaearon/redux-thunk) 一起服用了，在 Boilerplate 載入語系時有使用到這樣的寫法，但再講解下去就有點偏離本文了，有興趣的讀者請見原始碼：[src/common/actions/intlActions.js](https://github.com/gocreating/express-react-hmr-boilerplate/blob/dev/src/common/actions/intlActions.js)。


Day 12 - Infrastructure - Isomorphic API

如何在 Server 端使用 API 預載入 State


## Isomorphic 錯誤處理

前後端可能發生的錯誤有千百種，為了方便維護，還有統一管理，我決定在 Isomorphic 的 Flux Store 中掛上 `errors` 陣列，無論是前端還是後端，發生了任何錯誤，只要 Dispatch Action 把錯誤送進 Reducer 集中處理即可。

### res.pushError() & res.errors()

為了讓錯誤處理更方便，我在 Express Server 上會搭配 2 個 Helpers 來運作，這些 Helpers 是在 [src/server/middlewares/mountHelper.js](https://github.com/gocreating/express-react-hmr-boilerplate/blob/dev/src/server/middlewares/mountHelper.js) 中掛在 res 物件上的，實際功能其實只是包裝 Dispatch Action 的動作。

`res.pushError()` 是用來把錯誤塞進 Error Queue 裡，Server 還不會送出 Response：

``` js
import Errors from './path/to/constants/Errors';

// ...
if (err) {
  res.pushError(Errors.ODM_VALIDATION, err);
}
```

當所有錯誤都被 Push 進到 Error Queue，可以呼叫 `res.errors()` 送出 Response。

``` js
import Errors from './path/to/constants/Errors';

// ...
if (err) {
  res.pushError(Errors.ODM_VALIDATION);
  res.pushError(Errors.ODM_OPERATION_FAIL);
  res.pushError(...);
  return res.errors();
}
```

從這兩個例子中還可以看到，我們集中管理了 `Errors` 物件：

``` js
import ErrorCodes from './ErrorCodes';

export default {
  // ...
  [ErrorCodes.PERMISSION_DENIED]: {
   code: ErrorCodes.PERMISSION_DENIED,
   status: 403,
   title: 'Permission Denied',
   detail: 'You are not allowed to access the resource.',
 },
  // ...
};
```

> 完整程式碼：[src/common/constants/Errors.js](https://github.com/gocreating/express-react-hmr-boilerplate/blob/dev/src/common/constants/Errors.js)


### API 的錯誤處理

前一篇教過各位以 Promise 的形式撰寫 API，但其實我刻意忽略了示範 API 的錯誤處理，怕混淆各位所以留到這篇說明。

API 的錯誤處理必須追朔到 ApiEngine 的撰寫，在 Expose 出來的 `get`、`post`、`put`、`del` 四個 Methods 回傳值都是 Promise，所以我們便能自訂什麼情況下要觸發 Promise 的錯誤，我是統一在 API Response 中使用 `errors` 這個 key 來儲存錯誤陣列，所以 ApiEngine 只要偵測到 `res.errors.length > 0` 就代表收到的 Response 發生錯誤了。

``` js
class ApiEngine {
  get(path, { params, data, files } = {}) => {
    return new Promise((resolve, reject) => {
      // ...
      request.end((err, { body } = {}) => {
        // Superagent 發生內部錯誤
        if (err) {
          return reject(body || err);
        }
        // API Server 回傳自訂錯誤
        if (body.errors && body.errors.length > 0) {
          return reject(body.errors);
        }
        return resolve(body);
      });
    });
  }
  // ...
}
```

> 完整程式碼：[src/common/utils/ApiEngine.js](https://github.com/gocreating/express-react-hmr-boilerplate/blob/dev/src/common/utils/ApiEngine.js)

了解 ApiEngine 的錯誤處理機制後，就可以搭配 pushError 把它套用在實際的 API 呼叫上了：

``` js
// Server 端用法
export default {
  // ...
  fetchTodo: (req, res, next) => {
    todoAPI(req.store.getState().apiEngine)
      .read(req.params.todoId)
      .catch(() => {
        res.pushError(Errors.STATE_PRE_FETCHING_FAIL, {
          detail: 'Cannot read todo',
        });
        next();
      })
      .then((json) => {
        req.store.dispatch(setTodo(json.todo));
        next();
      });
  },
};
```

``` js
// Client 端用法
componentDidMount() {
  let { dispatch, apiEngine } = this.props;

  todoAPI(apiEngine)
    .read(9527)
    .catch((err) => {
      dispatch(pushErrors(err));
      // 這行是必要的，否則即使錯誤發生了，一樣會繼續執行 then 的部分
      throw err;
    })
    .then((json) => {
      dispatch(setTodo(json.todo));
    });
}
```

## Server 端的錯誤處理

接下來讓我們看看 Server-Only 的錯誤該怎麼處理。

### Express Process Error

第一種狀況是 Server Process 本身發生了沒有處理到的 Error，或是 Promise 中發生例外狀況，利用 Node 本身的語法就能處理掉了，通常是直接重啟 Server，這樣才能確保可靠度。

``` js
process.on('uncaughtException', (err) => {
  process.exit(1);
});

process.on('unhandledRejection', (reason, p) => {
  throw reason;
});
```

> 完整程式碼：[src/server/app.js#L19-L26](https://github.com/gocreating/express-react-hmr-boilerplate/blob/dev/src/server/app.js#L19-L26)

### Express Request Error

另一種狀況是錯誤只發生在某一個 Request 上，參考 Express 文件的 [Error handling](http://expressjs.com/en/guide/error-handling.html) 寫法即可，另外，在 Boilerplate 中額外做了一件事情，我們把錯誤處理的行為區隔為 `production` 與 `non-production`，`production` 的環境下最好不要暴露 Error Stack，規避安全議題；`development` 與 `test` 環境下為了 Debug，所以可以顯示 Error Stack。

``` js
app.use((err, req, res, next) => {
  if (env !== 'production') {
    res.status(500).send(`<pre>${err.stack}</pre>`);
  } else {
    res.status(500).send('Service Unavailable');
  }
});
```

> 完整程式碼：[src/server/app.js#L56-L63](https://github.com/gocreating/express-react-hmr-boilerplate/blob/dev/src/server/app.js#L56-L63)

### Callback Error 與 handleError 模組

除了上述的幾種錯誤以外，Node 本身非同步的寫法必須經常處理 Callback 中的 Error，一般教學中都是直接 throw err：

``` js
doSomething((err, ...data) => {
  if (err) {
    throw err;
  }
  // ...
})
```

這般作法其實很粗糙，只是把 Error 送入前面提到的 `Express Request Error` Handler 中集中處理，這對一個 API Server 而言是明顯不合格的，為了更方便維護，還有為了在 Response 中更明確的知道錯誤發生在哪個環節，我在 Boilerplate 實做了 `handleError` 這個模組。

用法如下，直接把 handleError 包住原本的 Callback Function，並且消耗掉 Callback 的第一個 err 參數，所以在 Callback 中就不用再處理錯誤了。

``` js
import { handleSomeError } from '../decorators/handleError';

doSomething(handleSomeError(res)((...data) => {
  // ...
}))
```

使用上會把 res 物件傳遞進去，如此便能在錯誤發生時，透過 handleError 模組發送 Response。此模組廣泛用在 ODM 的操作上，請看以下例子：

``` js
import { handleDbError } from '../decorators/handleError';

export default {
  list(req, res) {
    User.paginate({ page: req.query.page }, handleDbError(res)((page) => {
      User
        .find({})
        .limit(page.limit)
        .skip(page.skip)
        .exec(handleDbError(res)((users) => {
          res.json({
            users: users,
            page: page,
          });
        }));
    }));
  },
};
```

> 完整程式碼：[src/server/controllers/user.js#L14-L28](https://github.com/gocreating/express-react-hmr-boilerplate/blob/dev/src/server/controllers/user.js#L14-L28)

每一次的 ODM 操作都可能發生錯誤，如果沒有透過 `handleError` 模組來簡化，程式碼的可讀性會非常差，那絕對會是一場災難。

## Client 端的錯誤處理

Client-Only 的錯誤處理只需要延用 res.pushError 使用到的 Actions 即可，只是在 Client 端沒有提供 Helper，要自己 Dispatch Actions。範例其實在上面已經出現過了，請見 `API 的錯誤處理` 的 Client 端使用範例。

### 使用 ErrorList 顯示錯誤

至於錯誤的顯示方式，每個開發者、每個應用都不相同，有的人習慣用 Bootstrap 的 Alert，有的人喜歡 Popup 提醒視窗，在 Boilerplate 中，我是用前者寫成一個 `ErrorList` 元件，在此不贅述了，請直接參考[原始碼](https://github.com/gocreating/express-react-hmr-boilerplate/blob/dev/src/common/components/utils/ErrorList.js)。


Day 13 - Infrastructure - Error Handling


為了實現 Isomorphic，我們的 Boilerplate 採用了 React-Router 來控制頁面的路由，另外還搭配了 [react-router-redux](https://github.com/reactjs/react-router-redux) 將路由狀態同步至 Store 中。

## Root Component

我們的 App 有數十個頁面，但最終必須要整合為一個 Root Component 才能掛在 React 的 Root Node 上面，因此 App 的雛形會用 `Router` 包住各個頁面的 `Route`，並且由於我們使用了 Redux，最外面還要再包一層 `Provider` 來注入 Store：

``` js
import React from 'react';
import { render } from 'react-dom';

// ...取得 render 所必需的變數

render(
  <Provider store={store}>
    <Router history={history}>
      <Route path="/" component={App}>
      <Route path="/another" component={AnotherApp}>
      // ...
    </Router>
  </Provider>
), document.getElementById('root'));
```

另外，我們的 App 實做了 i18n，使用的是 [react-intl](https://github.com/yahoo/react-intl) 這個模組，因此要再夾上一層 `LocaleProvider`：

``` js
render(
  <Provider store={store}>
    <LocaleProvider>
      <Router history={history}>
        <Route path="/" component={App}>
        <Route path="/another" component={AnotherApp}>
        // ...
      </Router>
    </LocaleProvider>
  </Provider>
), document.getElementById('root'));
```

這個 Render 順序是固定的，先有 Redux Store，才能注入 Locale，並且 Providers 的順序優先於整個 App，所以要先 Render Provider，其次才是 App 的 Router。

## Client Side Render

一般如果沒有搭配 SSR，只有純粹的 Client Side Render 的話，只需要像下方這麼寫即可：

``` js
render(
  <Provider store={store}>
    <Router history={history}>
      {routes}
    </Router>
  </Provider>
), document.getElementById('root'));
```

但是我們在 Boilerplate 中搭配了 Code Splitting 的技術（文末將會說明），這在 React-Router 上會產生一些 Issue [[1]][React-Router: 如果存在异步路由，服务器端和客户端都需要用 “match”] [[2]][React Router Example: Server Rendering Lazy Routes]，所以在 Client Side Render 時必須要再呼叫一次 `match`：

``` js
import { match } from 'react-router';

// ...取得 render 所必需的變數

match({
  history,
  routes,
}, (error, redirectLocation, renderProps) => {
  render(
    <Provider store={store}>
      <LocaleProvider>
        <Router
          history={history}
          {...renderProps}
        >
          {routes}
        </Router>
      </LocaleProvider>
    </Provider>
  , document.getElementById('root'));
});
```

> 完整程式碼：[src/client/index.js](https://github.com/gocreating/express-react-hmr-boilerplate/blob/dev/src/client/index.js)

## Server Side Render

Server Side 按照 React-Router 官方教學，本來就要使用 match，所以其實程式碼和 Client Side 相似：

``` js
match({
  routes,
  history: req.history,
}, (error, redirectLocation, renderProps) => {
  const finalState = req.store.getState();
  const markup = '<!doctype html>\n' + renderToString(
    <Html initialState={finalState}>
      <Provider store={req.store}>
        <LocaleProvider>
          <RouterContext {...renderProps} />
        </LocaleProvider>
      </Provider>
    </Html>
  );
  res.send(markup);
});
```

> 完整程式碼：[src/server/controllers/react.js](https://github.com/gocreating/express-react-hmr-boilerplate/blob/dev/src/server/controllers/react.js)

差別在於 Root Component 在 Provider 之外多包了一層 Server-Only 的元件 [`Html`](https://github.com/gocreating/express-react-hmr-boilerplate/blob/dev/src/server/components/Html.js)，因為 App Render 出來其實都只是 Html 的 Body，而非完整結構的 Html，但 Server 的 Response 理論上必須要是完整結構的 Html，所以此處使用了 `Html` 元件來產生完整 Html。

## Webpack Code Splitting & Lazy Loading [[3]][Code Splitting]

請別忘了我們一直以來都是在寫 SPA，整個 App 最終會被打包成一個 bundle.js，所以每當我們在 App 中多新增了一些 Route 或是 Component，打包出來的 bundle.js 就會變得越來越肥；另外，也許你寫出來的 App 裡有數十個 Components，但經常使用到的 Components 卻只有其中的兩三個，其餘的幾乎不會用到，但整個 App 已經被封裝起來了，無論是哪個使用者來操作 App 都得把整包 bundle.js 下載下來，非常浪費時間也浪費流量，第一次載入 App 時的體驗也會很糟。

### Code Splitting 設定

上述情境是 SPA 的通病，所以無論你是寫 Angular 還是 React，都會有這樣的問題，不過讀者們不必擔心，Webpack 有所謂 Code Splitting 的技術，能夠將 App 切割成不同模組，只要在 webpack config 的 output 設定 `chunkFilename` 就可以切割 bundle.js 了：

``` js
module.exports = {
  entry: '...',
  output: {
    path: '...',
    filename: 'bundle.js',
    chunkFilename: '[id].chunk.js', // <-- 加上這個設定
    publicPath: '...',
  },
};
```

> 完整程式碼：[configs/env/webpack.config.dev.js](https://github.com/gocreating/express-react-hmr-boilerplate/blob/dev/configs/env/webpack.config.dev.js)

### 使用 Code Splitting 實作頁面的 Lazy Loading

React-Router 提供了非同步載入 Component、IndexRoute 還有 ChildRoutes 的功能，搭配 Code Splitting 的設定，我們就能透過程式碼將切割點切在 Route 與 Route 之間，讓每一個 Route 都打包成獨立的 Chunk。所以當使用者在 Client Side 路由到某個頁面前，React-Router 會先以非同步的方式從 Server 下載即將進入的頁面的 Chunk，如此就能實現頁面的 Lazy Loading。

讓我們看看 Boilerplate 中是怎麼切割 HomePage、Todolist 相關頁面還有 NotFoundPage 的吧！

``` js
import '../utils/ensure-polyfill';
import AppLayout from '../components/layouts/AppLayout';

export default (store) => ({
  path: '/',
  component: AppLayout,
  getChildRoutes(location, cb) {
    require.ensure([], (require) => {
      cb(null, [
        require('./todo').default(store),
        require('./notFound').default(store),
      ]);
    });
  },
  getIndexRoute(location, cb) {
    require.ensure([], (require) => {
      cb(null, {
        component: require('../components/pages/HomePage').default,
      });
    });
  },
});
```

> 完整程式碼：[src/common/routes/index.js](https://github.com/gocreating/express-react-hmr-boilerplate/blob/dev/src/common/routes/index.js)

``` js
export default (store) => ({
  path: 'todo',
  getComponent(nextState, cb) {
    require.ensure([], (require) => {
      cb(null, require('../components/pages/todo/ListPage').default);
    });
  },
});
```

> 完整程式碼：[src/common/routes/todo.js](https://github.com/gocreating/express-react-hmr-boilerplate/blob/dev/src/common/routes/todo.js)

`getChildRoutes`、`getIndexRoute`、`getComponent` 是 React-Router 的非同步處理機制，我們在這裡面呼叫 `require.ensure` 來訂定切割點，require.ensure 在 Callback 中會傳入 `require` 參數，任何你想 Lazy Load 的模組請必須使用這個 require 載入。

require.ensure 是 Webpack 為了讓開發者實現 Code Splitting 而提供的 Function，不是 Node 內建的 Function，Client Side 是經由 Webpack 打包，所以可以順利執行 require.ensure，但 Server Side Render 時是使用 Node 在運行，Node 並不知道 require.ensure 是什麼東西，所以我們在使用它之前必須先進行 Polyfill，也就是第一段程式碼第一行的 `import '../utils/ensure-polyfill';`。

最後補充說明一下，React-Router 在官方 Github 中也提供了 [Huge Apps](https://github.com/ReactTraining/react-router/tree/master/examples/huge-apps) 範例，Boilerplate 中的寫法正是參考此範例而得的。

## 筆者心情小補帖

在我自己開發的一個實際專案中，一共切出了 34 個 Chunk：

![14-1.png](/posts/2016-12-01-ithome-iron-man/14-1.png)

這種 App 如果不用 Code Splitting　應該會很悲劇吧...

## 參考資料

1. [React-Router: 如果存在异步路由，服务器端和客户端都需要用 “match”][React-Router: 如果存在异步路由，服务器端和客户端都需要用 “match”]
2. [React Router Example: Server Rendering Lazy Routes][React Router Example: Server Rendering Lazy Routes]
3. [Code Splitting][Code Splitting]

[React-Router: 如果存在异步路由，服务器端和客户端都需要用 “match”]: http://www.jianshu.com/p/b3ff1f53faaf
[React Router Example: Server Rendering Lazy Routes]: https://github.com/ryanflorence/example-react-router-server-rendering-lazy-routes
[Code Splitting]: https://webpack.github.io/docs/code-splitting.html


Day 14 - Infrastructure - Isomorphic Routing

Webpack Code Splitting & Lazy Loading [[3]][Code Splitting]

使用 Code Splitting 實作頁面的 Lazy Loading


表單是網頁中非常重要的元素，但同時也非常複雜，複雜之處在於，對每一個表單欄位而言，都可能有屬於自己的資料驗證流程、驗證錯誤處理、可能會需要呼叫 API、可能需要 State 來控制 UI、可能會有巢狀的動態欄位；對一張表單而言，可能會需要拆開成數張小表單，寫成 Wizard 的形式。

簡單來說表單的毛病特別多，大家寫出來的邏輯和 UI 通通不一致，UI 和邏輯很難脫鉤，程式碼難以維護，不過在我們的 Boilerplate 中使用了 Redux-Form 將邏輯抽取至 Flux 中，UI 的部分則是筆者自己提出了 `Wrapper` 與 `Adapter` 的寫法，我認為這樣的組合和結構極好，容易維護、容易擴充、高度複用，同時還很容易調整 UI，這是我經過幾番重構程式碼嘔心瀝血得到的最佳作法，希望讀者們喜歡。

## Redux-Form

這裡先舉個登入表單當作例子，傳統寫法長這樣：

``` html
<form name="USER_LOGIN">
  信箱：<input name="email" type="text" />
  密碼：<input name="password" type="password" />
</form>
```

先來看看邏輯層面，如果改用 Redux-Form 幫我們把所有欄位的資料統整在 Store 裡面，便可以得到下方形式的 State：

``` js
// store.getState()
{
  // ...
  form: {
    USER_LOGIN: {
      email: 'xxx@gmail.com',
      password: 'somepassword',
    },
  },
  // ...
}
```

而 Redux-Form 也在 Props 中提供了 `initialize`、`change` 等各種 Function 可以操作表單或是某個特定欄位。

再來是 UI 部分，必須使用 Redux-Form 提供的 `Field` 元件包裝每一個欄位，最後透過 `reduxForm` 這個 HOC 來給定表單名稱、表單初始值、欄位驗證流程等表單相關的設定。

直接看看 Boilerplate 中的登入表單是怎麼寫的吧：

``` js
import React, { Component } from 'react';
import { connect } from 'react-redux';
import { Field, reduxForm } from 'redux-form';
import userAPI from '../../../api/user';
import { pushErrors } from '../../../actions/errorActions';
import { BsInput as Input } from '../../fields/adapters';
import {
  BsForm as Form,
  BsField as FormField,
} from '../../fields/widgets';

const validate = (values) => {
  const errors = {};

  if (!values.email) {
    errors.email = 'Required';
  }

  if (!values.password) {
    errors.password = 'Required';
  }

  return errors;
};

class LoginForm extends Component {
  constructor(props) {
    super(props);
    this.handleSubmit = this._handleSubmit.bind(this);
  }

  _handleSubmit(formData) {
    let { dispatch, apiEngine, change } = this.props;

    return userAPI(apiEngine)
      .login(formData)
      .catch((err) => {
        dispatch(pushErrors(err));
        throw err;
      })
      .then((json) => {
        if (json.isAuth) {
          // ...登入成功
        } else {
          change('password', '');
        }
      });
  }

  render() {
    const { handleSubmit, pristine, submitting, invalid } = this.props;

    return (
      <Form onSubmit={handleSubmit(this.handleSubmit)}>
        <Field
          name="email"
          component={FormField}
          label="Email"
          adapter={Input}
          type="text"
          placeholder="Email"
        />
        <Field
          name="password"
          component={FormField}
          label="Password"
          adapter={Input}
          type="password"
          placeholder="Password"
        />
        <button type="submit" disabled={pristine || submitting || invalid}>
          Login
        </button>
      </Form>
    );
  }
};

export default reduxForm({
  form: 'USER_LOGIN',
  validate,
})(connect(state => ({
  apiEngine: state.apiEngine,
  routing: state.routing,
}))(LoginForm));
```

> 完整程式碼：[src/common/components/forms/user/LoginForm.js](https://github.com/gocreating/express-react-hmr-boilerplate/blob/dev/src/common/components/forms/user/LoginForm.js)

這個範例除了展示如何使用 Redux-Form 建構登入表單元件之外，裡面還透露了幾個重點：

- 欄位驗證是 Program-Based 而不是 Configuration-Based，所以彈性非常高
- `_handleSubmit` 是有回傳值的，當回傳值是 Promise 時可以用來控制 props.submitting
- reduxForm 和 connect 兩個 HOC 並存時是可以運作的，而且順序關係必須是 reduxForm(connect(SomeComponent))

以上只是帶各位走過 Redux-Form 的冰山一角，其實它是個太強大的 Library，所以這邊的舉例只是給讀者們一個方向，目的不是要教會各位使用 Redux-Form，它本身的文件寫得非常詳盡，範例也很多元，所以各位千萬不要只看本篇文章粗略的示範，一定要抽空讀過官方文件，才能把這套 Library 活用。

## Field Wrapper & Field Adapter

前面講的是整張表單的建構，接著我們來看每一個欄位是怎麼撰寫的。就舉 Email 欄位為例，按照 Redux-Form 最基本的寫法，只需要給定 `name` 與 `component` 兩個屬性就可以使用：

``` js
<Field name="email" component="input" type="text" />
```

而多餘的 props 都會被傳進 component 中，所以上例其實可以假想展開成以下 Pseudo Code：

``` js
<Field name="email" component="input" type="text">
  <props.component name={props.name} {...props.rest} />
</Field>
```

但這樣的欄位實在太陽春了，沒有欄位標籤、沒有錯誤提示、沒有好看的 UI，不可能運用在實際的 App 中，所以我們重新設計一下欄位的 Pseudo Code，使用名為 `FormField` 的 Field Wrapper 包裝起來，並且原本的 `component="input"` 改寫為 `adapter="input"`：

``` js
<Field name="email" component={FormField} adapter="input" type="text">
  <props.component label="Email">
    <label>{props.label}</label>
    <props.adapter name={props.name} {...props.rest} />
    {props.error && (
      <HelpBlock>{props.error}</HelpBlock>
    )}
  </props.component>
</Field>
```

目前為止我們考慮的都是 `input` 形式的欄位，實際上還會有 checkbox、radio、select 等各式各樣的欄位形式，甚至還應該要能保留彈性擴充自訂的欄位，例如 reCaptcha、slider。我把這些自訂的欄位元件稱作 Field Adapter，也就是上面例子中的 `props.adapter` 屬性。

了解整體概念後，就可以建構實際的程式碼了：

``` js

let FormField = ({ label, adapter, meta, ...rest }) => {
  let Adapter = adapter;
  let isShowError = meta && meta.touched && meta.error;

  return (
    <div>
      <label>{label}</label>
      <Adapter {...rest} />
      {isShowError && (
        <HelpBlock>{meta.error}</HelpBlock>
      )}
    </div>
  )
};

let Input = ({ input, type, ...rest }) => (
  <input
    {...input}
    type={type}
    {...rest}
  />
);

let LoginForm = () => (
  // ...
  <Field
    name="email"
    component={FormField}
    label="Email"
    adapter={Input}
    type="text"
    placeholder="Email"
  />
);
```

其中 `input` 和 `meta` 兩個 props 是 Redux-Form 產生的，所以請各位參考官方文件。

這樣的設計把 UI 的彈性保留在 Field Wrapper（例子中的 `FormField` 元件）與 Field Adapter（例子中的 `Input` 元件）上，例如你可以實作 Material Design 版本的 Wrapper 和 Adapter：

``` js
import FormField from './MaterialFormField';
import Input from './MaterialInput';

let LoginForm = () => (
  // ...
  <Field
    name="email"
    component={FormField}
    label="Email"
    adapter={Input}
    type="text"
    placeholder="Email"
  />
);
```

除了 Input 之外，還可以擴充各式各樣的欄位，像是 reCaptcha：

``` js
let DemoForm = () => (
  // ...
  <Field
    name="someRecaptcha"
    component={FormField}
    label="Recaptcha"
    adapter={Recaptcha}
  />
);
```

> 完整程式碼：[src/common/components/forms/DemoForm.js](https://github.com/gocreating/express-react-hmr-boilerplate/blob/dev/src/common/components/forms/DemoForm.js)

我在 Boilerplate 寫了一個 Playground 可以試玩所有內建的欄位元件，歡迎各位到 Demo Site 的 [Form Elements](https://express-react-hmr-boilerplate.herokuapp.com/demo/form-element) 玩玩

## Isomorphic Form Validation

前面已經解決了撰寫表單可能遇到的大部分疑難雜症，現在只剩下表單驗證這個雞八的東西了。Redux-Form 已經內建了表單驗證的機制了，只要撰寫 `validate` Function 就可以控管各個欄位的 valid/invalid 狀態：

``` js
const validate = (values) => {
  const errors = {};

  if (!values.email) {
    errors.email = 'Required';
  }

  if (!values.password) {
    errors.password = 'Required';
  }

  return errors;
};

class LoginForm extends Component {
  // ...
};

export default reduxForm({
  form: 'USER_LOGIN',
  validate,
})(LoginForm);
```

但是這一切的驗證機制都只發生在前端啊！！！後端怎麼辦呢？如果有使用者故意繞過 UI 上的防護機制，直接對 API Server 發送惡意 Request，那豈不是還要在 Server 上重寫一份欄位驗證的機制嗎？

請別忘了我們一直以來強調的 Isomorphism，表單的驗證是可以寫成 Isomorphic 版本的！請見以下 Server 端的表單驗證處理是如何延用 `validate` Function 的：

``` js
export const validate = (values) => {
  // ...
}

class ExampleForm extends Component {
  // ...
};

export default reduxForm({
  form: 'EXAMPLE_FORM',
  validate,
})(ExampleForm);
```

首先我們把 `validate` Function `export` 出來。

``` js
// src/server/routes/api.js
app.post('/api/example/path',
  bodyParser.json,
  validate.form('EXAMPLE_FORM'),
  exampleController.create
);
```

接著在需要驗證的 API Path 加上 `validate.form()` 這個 Middleware，並且傳入表單名稱，讓 Middleware 知道要 Import 哪一張表單的 `validate` Function。

該 Middleware 寫法如下，把 Server 收到的欄位資料送入指定的 `validate` Function，接著再檢驗回傳值中是否夾帶錯誤訊息：

``` js
import validateErrorObject from '../utils/validateErrorObject';

export default {
  form: (formPath) => (req, res, next) => {
    let { validate } = require(`../../common/components/forms/${formPath}`);
    let errors = validate(req.body);

    if (!validateErrorObject(errors)) {
      res.pushError(Errors.INVALID_DATA);
      return res.errors();
    }
    next();
  },
};
```
> 完整程式碼：[src/server/middlewares/validate.js](https://github.com/gocreating/express-react-hmr-boilerplate/blob/dev/src/server/middlewares/validate.js)

如此一來，原本 Redux-Form 的寫法不必做太多調整，只需要把 `validate` Export 出去即可；同樣地，Server 也只需要補上一個 Middleware 就能進行 Server Side 的表單驗證，最重要的是，整個驗證邏輯只寫了一次，可說是完美落實了 Isomorphism。


Day 15 - Infrastructure - Form


## Passport

Authentication 是許多 Web 服務都會使用到的基本功能，但每個服務的需求可能又不太一樣，有的人只需要 Basic Auth，有的人需要 Local Auth，也有人需要 Social Auth，Boilerplate 其實不可能做到滿足所有需求，所以使用了 [Passport](https://github.com/jaredhanson/passport) 這套 Library 來統一`認證`這一個 Infrastructure。

## Token-Based Local Authentication & Jwt

雖說大家需要的認證需求都不太一樣，但大部分 Web 服務都還是會需要基本的站內註冊及登入登出，所以 Boilerplate 有幫各位實作了 Local Authentication 的功能。

許多實作 Local Authentication 的入門教學都是 Session-Based，但我個人非常排斥使用 Session，因為 HTTP 是一個 Stateless 的協定，而 Session 是個 Stateful 的東西，違反了 HTTP 本身的設計原則，而且當 Server Scale Up 時，還要有管理 Session 的機制，徒增營運上的困擾，所以不如打從一開始就棄用。

我們的 Boilerplate 採用的是 Token-Based 的 Authentication，這裡所謂的 Token 指的是 JWT（JSON Web Tokens），這是目前 Modern Web 中很熱門的認證方式，而且是 Stateless。因此實作上搭配 [passport-jwt](https://github.com/themikenicholson/passport-jwt) 這個 Passport Strategy，撰寫了 `passportInit` 這個 Middleware：

``` js
let cookieExtractor = (req) => {
  return req.store.getState().cookies.token;
};

export default (req, res, next) => {
  passport.use(new JwtStrategy({
    jwtFromRequest: cookieExtractor,
    secretOrKey: configs.jwt.authentication.secret,
  }, (jwtPayload, done) => {
    // this callback is invoked only when jwt token is correctly decoded
    User.findById(jwtPayload._id, handleDbError(res)((user) => {
      done(null, user);
    }));
  }));

  passport.initialize()(req, res, next);
};
```

> 完整程式碼：[src/server/middlewares/passportInit.js](https://github.com/gocreating/express-react-hmr-boilerplate/blob/dev/src/server/middlewares/passportInit.js)

由於 JWT 是夾帶在 Cookie 中，所以可以看到程式碼中使用了 `cookieExtractor`，從 Store 中的 cookies 讀取 Token。

另外我們還必須要有 `authRequired` 這樣的 Middleware 讓我們確保某些 API Path 只有已登入的使用者可以存取：

``` js
export default (req, res, next) => {
  passport.authenticate(
    'jwt',
    { session: false },
    handleError(res)((user, info) => {
      handlePassportError(res)((user) => {
        if (!user) {
          res.pushError(Errors.USER_UNAUTHORIZED);
          return res.errors();
        }
        req.user = user;
        next();
      })(info, user);
    })
  )(req, res, next);
};
```

> 完整程式碼：[src/server/middlewares/authRequired.js](https://github.com/gocreating/express-react-hmr-boilerplate/blob/dev/src/server/middlewares/authRequired.js)

如此就能透過 Middleware 輕鬆維護 API 的存取權限：

``` js
import authRequired from '../middlewares/authRequired';

export default ({ app }) => {
  // ...
  app.get('/api/users/me', authRequired, userController.readSelf);
  // ...
};
```

> 完整程式碼：[src/server/routes/api.js](https://github.com/gocreating/express-react-hmr-boilerplate/blob/dev/src/server/routes/api.js)

## Social Authentication

我認為使用 Passport 的最大好處就在於 Social Authentication 有一套標準的實作寫法，無論 Provider 是 Facebook、Twitter 還是 LinkedIn，只要套用對應的 Passport Strategy 就可以很容易實作 Social Authentication。

我們的 Boilerplate 實作了 Facebook 和 LinkedIn 兩個 Providers 的 Social Authentication，但寫法與概念都和 JWT 類似，就不在此細講程式碼，詳見 [src/server/middlewares/passportInit.js](https://github.com/gocreating/express-react-hmr-boilerplate/blob/dev/src/server/middlewares/passportInit.js)。


Day 16 - Infrastructure - Authentication


API Server 通常需要做到 2 種權限控制，第一是檢查使用者是否已經登入（Authentication），另一種是對已登入的使用者檢查是否具有足夠權限（Authorization），以 Express 的特性來看，在 Middleware 上面實作權限控制是最理想的，所以接下來將舉例兩個 Boilerplate 中實際用到的 Middlewares。

## authRequired

這個 Middleware 大家應該已經在前面的章節看過一兩次了，我們使用它來檢查 Request 中是否夾帶 JWT，如果有，則透過 Passport 的 JWT Strategy 取出目前 Request 的使用者：

``` js
const authRequired = (req, res, next) => {
  passport.authenticate(
    'jwt',
    { session: false },
    handleError(res)((user, info) => {
      handlePassportError(res)((user) => {
        if (!user) {
          res.pushError(Errors.USER_UNAUTHORIZED);
          return res.errors();
        }
        req.user = user;
        next();
      })(info, user);
    })
  )(req, res, next);
};
```

> 完整程式碼：[src/server/middlewares/authRequired.js](https://github.com/gocreating/express-react-hmr-boilerplate/blob/dev/src/server/middlewares/authRequired.js)

未經認證卻想要存取資源的使用者將會收到 `Errors.USER_UNAUTHORIZED`；經過認證的使用者的 Mongoose Model Instance 會被掛到 req 物件上，方便後續 Middleware 存取使用者資訊。

## roleRequired

這個 Middleware 相依於 `authRequired`，使用 `roleRequired` 之前一定要先使用 `authRequired`，因為我們要依賴 `authRequired` 掛到 req 上的 `user` 物件。

`roleRequired` 比對目前使用者的角色 `req.user.role` 是否包含在指定的角色 `requiredRoles` 中：

``` js
const roleRequired = (requiredRoles) => (req, res, next) => {
  if ((
    requiredRoles instanceof Array &&
    requiredRoles.indexOf(req.user.role) >= 0
  ) || (
    req.user.role === requiredRoles
  )) {
    next();
  } else {
    return res.errors([Errors.PERMISSION_DENIED]);
  }
};
```

權限不足者會收到 `Errors.PERMISSION_DENIED`；權限正確的使用者不作任何處理，直接呼叫 `next` 進入後續 Middlewares。

## 使用範例

有了以上權限控制的 Middlewares，就可以針對不同 API 實作不同的權限控管，例如只有已登入的 Admin 使用者才能存取 `/api/users` 這項資源：

``` js
import authRequired from '../middlewares/authRequired';
import roleRequired from '../middlewares/roleRequired';

// ...
app.get('/api/users',
  authRequired,
  roleRequired([Roles.ADMIN]),
  userController.list
);
```

> 完整程式碼：[src/server/routes/api.js](https://github.com/gocreating/express-react-hmr-boilerplate/blob/dev/src/server/routes/api.js)

## Nonce

在我們 Boilerplate 中還使用了一個有趣的東西 `Nonce`，這是網路安全領域中的術語，用來防止 Replay Attack。

Web Service 在某些情況下必須散播一次性的 Token，例如信箱驗證或是重設密碼，通常是讓使用者打開一串夾帶著 Token 的超連結，一旦驗證完成或是重設完成，該連結就應該要失效，也就是說該連結夾帶的 Token 是一次性的，不能被重複使用，所以我們在 Boilerplate 中必須要實作防護機制，這個機制正是利用 Nonce 來完成的。

以驗證信箱的功能為例，我們在資料庫中設有 `nonce.verifyEmail` 欄位，並且提供 `toVerifyEmailToken` 這個 Instance Method 產生驗證信箱的 Token，Token 中會包入 Nonce：

``` js
let UserSchema = new mongoose.Schema({
  // ...
  nonce: {
    verifyEmail: Number,
  },
});

UserSchema.methods.toVerifyEmailToken = function(cb) {
  const user = {
    _id: this._id,
    nonce: this.nonce.verifyEmail,
  };
  const token = jwt.sign(user, configs.jwt.verifyEmail.secret, {
    expiresIn: configs.jwt.verifyEmail.expiresIn,
  });
  return token;
};
```

> 完整程式碼：[src/server/models/User.js](https://github.com/gocreating/express-react-hmr-boilerplate/blob/dev/src/server/models/User.js)
> 註：Instance Method 不能使用 Arrow Function，因為我們要在內部使用到 `this`

### 產生 Nonce

當使用者註冊時，將 nonce.verifyEmail 設定為一個隨機數：

``` js
const user = User({
  name: req.body.name,
  // ...
  nonce: {
    verifyEmail: Math.random(),
  },
});
```

> 完整程式碼：[src/server/controllers/user.js](https://github.com/gocreating/express-react-hmr-boilerplate/blob/dev/src/server/controllers/user.js)

再依據此 Nonce 產生 Token 寄送驗證連結至註冊信箱：

``` js
let token = user.toVerifyEmailToken();

nodemailerAPI()
  .sendMail({
    to: user.email.value,
    subject: 'Email Verification',
    html: renderToString(
      <VerifyEmailMail token={token} />
    ),
  })
  .catch(err => { /* ... */ })
  .then(info => { /* ... */ });
```

> 完整程式碼：[src/server/controllers/mail.js](https://github.com/gocreating/express-react-hmr-boilerplate/blob/dev/src/server/controllers/mail.js)

### 驗證 Nonce

當使用者打開驗證連結後，要如何驗證 Token 是否被重複使用呢？我們只要將 Nonce 從 Token 中取出，並且和資料庫中儲存的 Nonce 比對就可以知道 Token 是第一次使用，還是被重複使用了：

``` js
const verifyUserNonce = (req, res, next) => {
  let { _id, nonce } = req.decodedPayload;
  User.findById(_id, handleDbError(res)((user) => {
    if (nonce !== user.nonce.verifyEmail) {
      return res.errors([Errors.TOKEN_REUSED]);
    }
    user.nonce.verifyEmail = -1;
    next();
  }));
};
```

> 完整程式碼：[src/server/middlewares/validate.js](https://github.com/gocreating/express-react-hmr-boilerplate/blob/dev/src/server/middlewares/validate.js)

驗證成功後，我們直接把 Nonce 清除為 -1（任何 Math.random() 無法產生的值皆可），如此一來，下一次如果收到夾帶同樣 Token 的 Request 時，Nonce 將會比對失敗，也就達到了防止 Replay Attack 的效果。


Day 17 - Infrastructure - Permission Control


講到 i18n 真的就是只有機掰兩個字可以形容，因為它實在是一個非常破壞程式整體結構的東西，雖然可以搭配現有 Library 讓程式稍微容易維護一點，但是，如何在網站 Scale Up 之後 Lazy Load 語言包？如何讓程式在支援 i18n 的情況下依然高效運作？如何在 Library 限制的架構下盡可能讓整個網站都支援 i18n？

根據我的經驗，最好打從一開始就讓整個 Web 支援 i18n，如果一開始直接寫死語系，後面想要轉為多國語系時幾乎是整個專案都要砍掉重新規劃架構，所以我們的 Boilerplate 也是直接內建部分 i18n，選用的 Library 是 React-Intl。

## React-Intl

[React-Intl](https://github.com/yahoo/react-intl) 是 Yahoo 公司推出的 React 多國語系 Library，裡面有非常多的 i18n 外加 l10n 的功能，同時它也是 React 社群中最熱門的 i18n 模組。

### 自訂的 LocaleProvider 元件

各位可以回顧一下 [Day 14 - Infrastructure - Isomorphic Routing](./14) 曾經提過在 Root Component 用到了 `LocaleProvider` 元件，這是我們在 Boilerplate 中包裝 React-Intl 的 `IntlProvider` 所使用的元件，這麼做的目的有兩個：

1. 搭配 Redux

  當 Client Side 頁面初始化或是 Server Side 收到 Request 時，我們透過 Dispatch Action 把 Locale 存入 Store 裡，也就是說 `IntlProvider` 的 `props.locale` 需要依賴 Redux，所以我們的 Boilerplate 額外寫了 `LocaleProvider` 來注入 Store 中的 locale。

2. 增加彈性

  另一方面我們也考慮到大家的 i18n 不一定會採用 React-Intl 來實作，所以我把替換 Library 的彈性保留在 `LocaleProvider` 中，才不至於需要同時更改 Client Side 與 Server Side 的 Root Component。大家可以參考底下 Client Side 與 Server Side 的寫法，是共用 `LocaleProvider` 的。

### Client Side

``` js
render(
  <Provider store={store}>
    <LocaleProvider>
      <Router
        history={history}
        onUpdate={logPageView}
        {...renderProps}
      >
        {routes}
      </Router>
    </LocaleProvider>
  </Provider>
, document.getElementById('root'));
```

> 完整程式碼：[src/client/index.js](https://github.com/gocreating/express-react-hmr-boilerplate/blob/dev/src/client/index.js)

### Server Side

``` js
const markup = '<!doctype html>\n' + renderToString(
  <Html
    initialState={finalState}
    assets={__webpackIsomorphicTools__.assets()}
  >
    <Provider store={req.store}>
      <LocaleProvider>
        <RouterContext {...renderProps} />
      </LocaleProvider>
    </Provider>
  </Html>
);
```

> 完整程式碼：[src/server/controllers/react.js](https://github.com/gocreating/express-react-hmr-boilerplate/blob/dev/src/server/controllers/react.js)

## Text Component

在我們的 Boilerplate 裡其實沒有使用到太多 React-Intl 的功能，多數情況下只有用到 `FormattedMessage` 元件，我們另外使用自訂的 `Text` 元件來包裝它，這同樣也是為了日後彈性考量，例如當你想要更換 i18n Library 或是甚至直接摘掉 Library 自己刻的話。不必把每個使用到 React-Intl 或 FormattedMessage 的元件都翻修過一次，只需要修改 Text 元件即可。


Day 18 - Infrastructure - i18n


試想今天你要提供一個 API `GET /api/users` 來列出 Server 上的所有 User，你會怎麼做？以交作業的心態，能動就好，挖靠哩，總共 5 行就寫完了：

``` js
app.get('/api/users', (req, res) => {
  User.find({}, (err, users) => {
    res.json({ users });
  });
})
```

但是你是否曾經考慮過當你的 User 有一萬個、十萬個、甚至百萬個？難道你要全部都列出來嗎？我們一直在強調 Scale Up 的彈性，所以在真實的 Web App 中一定要考量到 `Pagination` 這東西，我認為無論是 Backend 的 API 還是 Frontend 的 UI、Data Flow，從一開始 App 的建構就要把 `Pagination` 納入考量。

它很難寫，但是如果今天不寫，日後要在 App 中加上 Pagination 的話，基本上整個專案只能打掉重刻，留下一個還不清的技術債。

## Backend Pagination

Backend 要處理的分頁主要是針對 Mongoose 讀取的 Resources 切割，我個人認為 Github 上找到的 Mongoose Pagination Plugin 都不符合我的需求，這些 Plugin 只能拿到分頁後的最終結果，卻拿不到分頁過程運算所需的參數（例如總共幾筆、每頁幾筆、Skip 幾筆、...），這對 Backend 當然是很好寫，但是對 Frontend 而言將會是個苦力，最好的作法當然是兩邊均衡，所以我自己寫了 [Pagination Plugin](https://github.com/gocreating/express-react-hmr-boilerplate/blob/dev/src/server/models/plugins/paginate.js)，用法也和目前開源的模組不同，但我覺得有兼顧到 Backend 的彈性與 Frontend 的可維護性。

延續前述的 `GET /api/users`，用法如下：

``` js
import paginatePlugin from './plugins/paginate';

let UserSchema = new mongoose.Schema({
  name: String,
  // ...
});

UserSchema.plugin(paginatePlugin);
```

> 完整程式碼：[src/server/models/User.js](https://github.com/gocreating/express-react-hmr-boilerplate/blob/dev/src/server/models/User.js)

首先在 Schema 套用 Plugin。

``` js
User.paginate({ page: req.query.page }, handleDbError(res)((page) => {
  // ...
}));
```

接著就可以呼叫 Model 的 `paginate` Method，Callback 回傳參數是一個夾帶 Page 參數的資料結構，包括 Skip 了幾筆 Record、每頁 Limit 多少 Record、第一頁的 Page Id、目前頁面的 Page Id、最後一頁的 Page Id、總共有多少筆 Record：

``` js
page = {
  skip: 20,
  limit: 5,
  first: 1,
  current: 5,
  last: 9,
  total: 9,
}
```

完整用法可以傳入幾個 Options，並且利用得到的 Page 資料結構實作 Mongoose Query 的分頁：

``` js
export default {
  listByGender(req, res) {
    let condition = {
      gender: 'MALE',
    };
    User.paginate({
      page: req.query.page,
      perPage: 10,
      condition,
    }, handleDbError(res)((page) => {
      User
        .find(condition)
        .sort({ createdAt: 'desc' })
        .limit(page.limit)
        .skip(page.skip)
        .exec(handleDbError(res)((users) => {
          res.json({
            users: users,
            page: page,
          });
        }));
    }));
  },
};
```

> 完整程式碼：[src/server/controllers/user.js](https://github.com/gocreating/express-react-hmr-boilerplate/blob/dev/src/server/controllers/user.js)

## Frontend Pagination [[1]][Working with paginated API in redux]

SPA 的一個好處就是，我們可以 Cache 住 AJAX 拿到的 Data，但是 API 回傳的結果可能是不同 Resource 巢狀混合後的結果，如果再搭配 Pagination 的使用，Store 中的結構很容易凌亂不堪，變得難以維護。

### Normalizr

這時候就要介紹一個好東西了，[normalizr](https://github.com/paularmstrong/normalizr) 是一個把 API Response 正規化的模組，其強大之處在於把巢狀的結構按照給定的 Schema 打平，例如這樣的原始 Response：

``` js
[{
  id: 1,
  title: 'Some Article',
  author: {
    id: 1,
    name: 'Dan'
  }
}, {
  id: 2,
  title: 'Other Article',
  author: {
    id: 1,
    name: 'Dan'
  }
}]
```

可以被正規化成：

``` js
{
  result: [1, 2],
  entities: {
    articles: {
      1: {
        id: 1,
        title: 'Some Article',
        author: 1
      },
      2: {
        id: 2,
        title: 'Other Article',
        author: 1
      }
    },
    users: {
      1: {
        id: 1,
        name: 'Dan'
      }
    }
  }
}
```

詳細用法太繁瑣，不便在此處說明，請讀者們自行參考 Github 文件及教學，我們在 Store 中儲存的資料結構將會是經過 normalizr 正規化之後的結果。

### Action & Reducer [[2]][real-world example]

我們將正規化之後的 `entities` 儲存於 store.entity，正規化之後的 `result` 儲存於 store.pagination。

假設今天我們是要實作 Todo List 的 Frontend Pagination，那我們可以透過自訂的 `SET_ENTITIES` 這個 Action 來整併 entities，另外透過 `SET_PAGES` 這個 Action 來傳遞正規化之後的 API Response：

``` js
export const setTodos = (res) => (dispatch, getState) => {
  let normalized = normalize(res.todos, arrayOf(todoSchema));

  dispatch(setEntities(normalized));
  dispatch(setPages(Resources.TODO, res.page, normalized.result));
};
```

其中 `Resources.TODO` 是指定一個用來識別目前要針對哪個資源處理分頁所用的 Key；`res.page` 中的 `current` 可以告訴 Reducer 要將 `normalized.result` 儲存於哪一頁。

假設我們拿過了 page 1，接著拿完 page 2 並且呼叫了 `dispatch(setTodos(res))`，那麼 Store 中的 entity 和 pagination 應該分別是以下的狀態：

``` js
store.entity = {
  todos: {
    todo1: {
      id: 'todo1',
      text: 'todo #1',
    },
    todo1: {
      id: 'todo2',
      text: 'todo #2',
    },
    todo1: {
      id: 'todo3',
      text: 'todo #3',
    },
    todo1: {
      id: 'todo4',
      text: 'todo #4',
    },
  },
};

store.pagination = {
  todos: {
    page: {
      skip: 2,
      limit: 2,
      first: 1,
      current: 2,
      last: 9,
      total: 9,
    },
    pages: {
      1: {
        ids: [ 'todo1', 'todo2' ],
      },
      2: {
        ids: [ 'todo3', 'todo4' ],
      },
      ...  // and so on
    }
  },
};
```

paginationReducer 的程式碼也有點繁瑣，請直接參考原始碼：[src/common/reducers/paginationReducer.js](https://github.com/gocreating/express-react-hmr-boilerplate/blob/dev/src/common/reducers/paginationReducer.js)

### 取出 Paginated Data

架構部分已經明確，剩下的就只是如何把 Data 呈現在 Component 上，不過這部分通常是要看 App 的需求來撰寫，我們就只簡單提供了可以移動至上一頁、下一頁、第一頁、最後一頁的 [Todo List Demo](https://express-react-hmr-boilerplate.herokuapp.com/todo)，完全支援每一頁的 Server Side Render 和 Server Side State Fetching。

原理是在 mapStateToProps 中撈出目前頁面的 Todos，讓元件可以 Render 出來：

``` js
connect(({ pagination, entity }) => {
  let { page } = pagination.todos;
  let todoPages = pagination.todos.pages[page.current] || { ids: [] };
  let todos = todoPages.ids.map(id => entity.todos[id]);

  return {
    todos,
    page,
  };
})(ListPage)
```

Data 則是在頁面載入或者是當頁面切換的時候下載的，並且已經下載過的就 Cache 住：

``` js
class ListPage extends Component {
  // ...
  componentDidMount() {
    let { location } = this.props;
    this.fetchTodos(location.query.page || 1);
  }

  componentDidUpdate(prevProps) {
    let { page, todos } = this.props;

    if (todos.length === 0 && prevProps.page.current !== page.current) {
      this.fetchTodos(page.current);
    }
  }

  fetchTodos(page) {
    // ...
  }
  // ...
}
```

> 完整程式碼：[src/common/components/pages/todo/ListPage.js](https://github.com/gocreating/express-react-hmr-boilerplate/blob/dev/src/common/components/pages/todo/ListPage.js)

### 實作瀑布流效果

其實在前述的架構規劃下，我們不只能夠實作正常的上一頁、下一頁，因為載入過的 Data 會被 Cache 起來，所以我們可以利用這個特性實作出瀑布流。延續前例，只要把 `mapStateToProps`  稍作修改，變成撈出 `page.first` 至 `page.current` 的 todos 就完成 95% 了：

``` js
connect(({ pagination, entity }) => {
  let { page, pages } = pagination.todos;
  let todoIds = flatten(
    Object
      .keys(pages)
      .map(pageId => pages[pageId].ids)
  );
  let todos = todoIds.map(id => entity.todos[id]);

  return {
    todos,
    page,
  };
})(ListPage)
```

剩下的 5% 呢？只要把`下一頁`改成`載入更多`就完成了，實際上他們的功能是一模一樣的！

## 參考資料

- [Working with paginated API in redux][Working with paginated API in redux]
- [real-world example][real-world example]

[Working with paginated API in redux]: https://medium.com/@pierrecriulanscy/working-with-paginated-api-in-redux-be871818e444#.s54ufiwir
[real-world example]: https://github.com/reactjs/redux/blob/master/examples/real-world/


Day 19 - Infrastructure - Pagination

Frontend Pagination [[1]][Working with paginated API in redux]

Action & Reducer [[2]][real-world example]


無論是驗證信箱、重設密碼、寄送電子報、更新服務條款、...，即使再小的 Real World App 都必須要考量到寄信服務。如果自己架 Mail Server 明顯過於克難，現在通常都是直接採用第三方服務，例如：[Sendgrid](https://sendgrid.com/)，但是小弟沒有 $$ 玩不起這樣的服務，所以在 Boilerplate 中使用的是折衷作法，搭配 Nodemailer 這個 Library 利用 Gmail 來發信。

## Nodemailer

[Nodemailer](https://github.com/nodemailer/nodemailer) 是一個 Plugin-Based 的發信 Library，目前總共支援 36 種服務，包括 Gmail、Sendgrid、Amazon 的 SES。

在 Boilerplate 中我們把 Nodemailer 的原生寫法包裝成 [`nodemailerAPI`](https://github.com/gocreating/express-react-hmr-boilerplate/blob/dev/src/server/api/nodemailer.js)，保留日後擴充的彈性，目前只有 `sendMail` 這個 Method，使用方式如同我們呼叫 API 的一慣作法，回傳值是一個 Promise：

``` js
import Errors from '../../common/constants/Errors';
import nodemailerAPI from '../api/nodemailer';

export default {
  // ...
  sendResetPasswordLink(req, res) {
    let { user } = req;
    let token = user.toResetPasswordToken();

    nodemailerAPI()
      .sendMail({ /* nodemailer options */ })
      .catch((err) => {
        res.errors([Errors.SEND_EMAIL_FAIL]);
        throw err;
      })
      .then((info) => {
        res.json({
          email: info.envelope,
        });
      });
  },
};
```

> 完整程式碼：[src/server/controllers/mail.js](https://github.com/gocreating/express-react-hmr-boilerplate/blob/dev/src/server/controllers/mail.js)


## Gmail & Application Password

基於成本考量，我們目前是使用免費的 Gmail 服務，讀者可以依照自己喜好修改 [`nodemailerAPI`](https://github.com/gocreating/express-react-hmr-boilerplate/blob/dev/src/server/api/nodemailer.js)，套用自己熟悉的服務。

另外，使用 Gmail 要記得申請應用程式專用的密碼，否則當你的 App 丟到 Travis 跑測試，或是部署到 Heroku 正式上線時，很可能被 Google 誤判為有人從美國入侵你的帳號。應用程式密碼的申請需要先啟用兩階段驗證，接著才能申請，完整教學請看 Boilerplate 的 [README#Gmail](https://github.com/gocreating/express-react-hmr-boilerplate#gmail)

## 使用 Component 當作 View Templates

Nodemailer 的 Options 可以傳入 Html 作為信件內容，但是我們依然是運行在 MVC 的架構下，所以其實可以將 Html Option 抽取成獨立的元件，再呼叫 React-Dom 的 `renderToString` 產生 Html 即可：

``` js
import React from 'react';
import { renderToString } from 'react-dom/server';
import ResetPasswordMail from '../components/ResetPasswordMail';

nodemailerAPI()
  .sendMail({
    to: user.email.value,
    subject: 'Reset Password Request',
    html: renderToString(
      <ResetPasswordMail
        requestedAt={new Date()}
        token={token}
      />
    ),
  })
```

> 完整程式碼：[src/server/controllers/mail.js](https://github.com/gocreating/express-react-hmr-boilerplate/blob/dev/src/server/controllers/mail.js)


Day 20 - Infrastructure - Mail Service


目前 Boilerplate 的測試覆蓋率還很低，主要是因為筆者對這塊也不是很熟，但還是針對我所使用的測試工具 Mocha 和 Travis 做個開場吧！

## Mocha

[Mocha](https://mochajs.org/) 是針對非同步處理而設計的測試流程工具，在進行測試的過程中，可以接收一個 Callback 參數，當我們完成想進行的測試時，再呼叫 Callback Function 即可。

## Chai

[Chai](http://chaijs.com/) 是一套 Assertion Library，因為光有 Mocha 來控制流程是不足以進行測試的，我們還需要 Assertion Library 來協助判斷何種情況該視為異常、何種情況該視為正常。

## 使用範例

以 locale API 的測試為例，在 Boilerplate 中是這麼使用上述的兩個工具的：

``` js
import chai from 'chai';
import { apiEngine } from '../../utils';
import localeAPI from '../../../build/common/api/locale';
import Errors from '../../../build/common/constants/Errors';
let expect = chai.expect;

describe('#localeAPI', () => {
  describe('#read()', () => {
    it('should download valid locale', (done) => {
      localeAPI(apiEngine)
        .read('en-us')
        .then((json) => {
          expect(json.locale).to.equal(validLocale);
          expect(json.messages).to.be.an('object');
          done();
        });
    });

    it('should reject invalid locale', (done) => {
      // ...
    });
  });
});
```

> 完整程式碼：[specs/endToEnd/apis/locale.js](https://github.com/gocreating/express-react-hmr-boilerplate/blob/dev/specs/endToEnd/apis/locale.js)

本篇主要是工具的簡介，關於程式碼的詳細說明就留待下一篇介紹吧！

## Travis

[Travis](https://travis-ci.org/) 是一個線上整合測試的服務。每當我們進行一次 Commit，要如何確保前面寫好的功能不受影響？對單一開發者而言很簡單，只要在 Terminal 打上測試指令即可；但是對一個開發團隊而言呢？每個人的開發環境都不同，撰寫的 Feature 也不同，如何知道自己寫的程式是否影響到其他人寫的功能呢？這時候就需要 Travis 這樣的服務。Travis 可以 Hook 你的 Git Server（例如 Github），每當有新的 Commit 被 Push 到 Git Server，Travis 就會自動下載你的 Repo，接著按照自訂的腳本建置環境跑測試，哪一次 Commit 有無通過測試都可以在一目瞭然。詳細用法請參考 [Day 23 - Testing - Travis](#)


Day 21 - Testing - Technique Stack


各位是否還記得在 [Day 12 - Infrastructure - Isomorphic API](./12) 中，我們提出了 API 特殊寫法與用法，事實上這樣的寫法除了滿足 Isomorphism 之外，它還是一種可測試（Testable）的寫法，請見本文說明。

## Flow Part

從流程的觀點來看，我們要先描述目前要測試哪一個 API，還有要測試該 API 的哪些 Methods，例如我想測試 todoAPI 的 create() 和 list()：

``` js
describe('#todoAPI', () => {
  describe('#create()', () => {
    // ...
  });

  describe('#list()', () => {
    // ...
  });
});
```

在測試過程中我們會動到測試資料庫，所以開始測試的前後，我慣例上會先清空所有資料：

``` js
import Todo from '../../../build/server/models/Todo';

describe('#todoAPI', () => {
  before((done) => {
    Todo.remove({}, done);
  });

  describe('#create()', () => {
    // ...
  });

  describe('#list()', () => {
    // ...
  });

  after((done) => {
    Todo.remove({}, done);
  });
});
```

然後再 Import 待測試的 API，準備好假資料，照著平常呼叫 API 的寫法來使用即可：

``` js
import { apiEngine } from '../../utils';
import todoAPI from '../../../build/common/api/todo';
import async from 'async';
import Todo from '../../../build/server/models/Todo';

describe('#todoAPI', () => {
  let fakeTodos = [{
    text: 'this is a fake todo text',
  }, {
    text: 'foo',
  }, {
    text: '~bar~',
  }];

  before((done) => {
    Todo.remove({}, done);
  });

  describe('#create()', () => {
    it('should create todo', (done) => {
      async.eachSeries(fakeTodos, (fakeTodo, cb) => {
        todoAPI(apiEngine)
          .create(fakeTodo)
          .then((json) => {
            // ...
            cb();
          });
      }, done);
    });
  });

  describe('#list()', () => {
    it('should list todos', (done) => {
      todoAPI(apiEngine)
        .list({ page: 1 })
        .then((json) => {
          // ...
          done();
        });
    });
  });

  after((done) => {
    Todo.remove({}, done);
  });
});
```

由於測試資料可能會有很多筆，所以這裡還使用到了 [`async`](https://github.com/caolan/async) 這套 Library，輔助我們在非同步的環境下按照順序走過全部的測資。

## Assertion Part

API 本身的錯誤已經被包裝在 Promise 的 Catch 裡了，所以我們故意不處理 Catch，萬一真的發生錯誤，Mocha 會因為 Callback Function 沒有被呼叫而噴出 Timeout 錯誤，使該測試失敗。

至於如何驗證 Response 的資料一切正常，我們用到的是 `Chai` 這套 Assertion Library：

``` js
import chai from 'chai';
import { apiEngine } from '../../utils';
import todoAPI from '../../../build/common/api/todo';
import async from 'async';
import Todo from '../../../build/server/models/Todo';
let expect = chai.expect;

describe('#todoAPI', () => {
  let fakeTodos = [{
    text: 'this is a fake todo text',
  }, {
    text: 'foo',
  }, {
    text: '~bar~',
  }];

  before((done) => {
    Todo.remove({}, done);
  });

  describe('#create()', () => {
    it('should create todo', (done) => {
      async.eachSeries(fakeTodos, (fakeTodo, cb) => {
        todoAPI(apiEngine)
          .create(fakeTodo)
          .then((json) => {
            expect(json.todo).to.be.an('object');
            expect(json.todo.text).to.equal(fakeTodo.text);
            cb();
          });
      }, done);
    });
  });

  describe('#list()', () => {
    it('should list todos', (done) => {
      todoAPI(apiEngine)
        .list({ page: 1 })
        .then((json) => {
          expect(json.todos).to.be.an('array');
          expect(json.todos).to.have.lengthOf(fakeTodos.length);
          done();
        });
    });
  });

  after((done) => {
    Todo.remove({}, done);
  });
});
```

> 完整程式碼：[specs/endToEnd/apis/todo.js](https://github.com/gocreating/express-react-hmr-boilerplate/blob/dev/specs/endToEnd/apis/todo.js)

Chai 有很多語意化的 Chained Method 可以使用，讓我們可以很容易看懂測試的項目，例如上方程式中的 `expect(json.todo.text).to.equal(fakeTodo.text);`，可以很直覺地知道這項測試的目的是：預期 todoAPI.create() 的回傳值中的 todo.text 要等於我們 Post 過去的 fakeTodo.text，其他的測試亦同理，Chai 還有很多奇奇怪怪的語法可以使用，建議讀者們遇到相對應的 Testing Scenario 再去查詢即可。


Day 22 - Testing - 撰寫 End-To-End API 測試


## 使用 Travis

Travis 的使用方式非常容易，以 Github 專案為例，只要在專案根目錄建立 `.travis.yml` 檔案就完成一半了，另一半則是要自己到 Travis 網站連結 Github 帳號，選擇要啟用自動測試的 Repo。

以下是我們的 Boileprlate 的 .travis.yml 設定：

```
language: node_js

node_js:
  - "4"
  - "5"
  - "6"

cache:
  directories:
    - node_modules

before_script:
  - npm install -g mocha
  - npm install -g gulp

before_install:
  - "npm install -g npm@latest"

install:
  - npm install

script:
  - npm test

env:
  - CXX=g++-4.8

addons:
  apt:
    sources:
      - ubuntu-toolchain-r-test
    packages:
      - g++-4.8
```

> 完整設定檔：[.travis.yml](https://github.com/gocreating/express-react-hmr-boilerplate/blob/dev/.travis.yml)

由於 Travis 支援許多語言和環境，所以一開始先指定要使用 `nodejs`，以及要測試的版本為 4.x、5.x、6.x。`before_script`、`before_install`、`install` 和 `script` 四個部分的設定則是告訴 Travis Clone 完 Repo 後要怎麼建置專案、怎麼開始執行測試。

另外，我們額外設置了 `cache` 設定，這個設定是選擇性加入的，因為 `npm install` 通常佔用了整個測試的大部分時間，如果 Cache 住 node_modules 資料夾可以幫助我們加速整個測試流程。

## Sensitive Configs

開發開源專案時要切記敏感資料的處理，當 Repo 是開源時，一不小心就可能把暴露資料庫的登入資訊、Social App 的 Secret 等敏感資訊，通常建立專案時就會把敏感資訊寫入 .gitignore 過濾掉，避免受到版本控制。

敏感資訊理論上應該從版控系統中移除，但是這會造成 Travis 建置 Repo 之後無法正常啟動 App，因為原本該存在的設定檔都被移除了。我們的 Boileprlate 是個開源專案，因此也曾經面臨過同樣的問題，我自己的解法是將整個 App 會用到的設定值（無論敏感或不敏感）序列化為一個字串，App 啟動時再將該字串當作環境變數傳入。

實作這樣的方法必須在 Config 模組動點手腳：

``` js
if (process.env.TRAVIS) {
  module.exports = JSON.parse(process.env.PROJECT_SERVER_CONFIGS);
} else {
  module.exports = {
    // ...real configs
  };
}
```

> 完整程式碼：[configs/project/server.js](https://github.com/gocreating/express-react-hmr-boilerplate/blob/dev/configs/project/server.js)

加入條件判斷式來辨認目前 App 是否運行在 Travis 的 Server 上，如果是，就從環境變數 `PROJECT_SERVER_CONFIGS` 載入整個 App 的設定值。

此外，我們不可能將設定值手動處理序列化，這太愚蠢了，所以我們建立了一個 Gulp Task `dumpConfigs`：

![23-1.png](/posts/2016-12-01-ithome-iron-man/23-1.png)

接著把黃色部分的序列化的字串按照指示填入 Travis 的設定中即可：

![23-2.png](/posts/2016-12-01-ithome-iron-man/23-2.png)

之後 Travis 就可以正常跑起 App 了。

> 不過這個做法需要注意，每當設定值有變動時，就要記得重新 Dump 一次套用到 Travis 上。


Day 23 - Testing - Travis


一個 Web App 經過了開發和測試週期之後，最終要面對的就是部署上線，目前 Modern Web 的趨勢幾乎不考慮自架 Server 了，主要都是仰賴 AWS（Amazon Web Services）、Microsoft Azure 等 IaaS 服務，或是 Heroku、Linode 等 PaaS 服務。

## Heroku

我們的 Boilerplate 目前的 [Demo Site](https://express-react-hmr-boilerplate.herokuapp.com/) 就是使用 [Heroku](https://www.heroku.com/)，Heroku 屬於 PaaS 服務，可以免費使用，主打的特色就是平台上提供了非常多樣的 `Dynos`，大家可以把它想像成 Plugin 的概念，當 App 需要 MongoDB 的服務時，就購買 Mongo Dyno，需要排程服務時，也可以購買 Scheduling 相關的 Dyno。

不過，使用免費版本最大缺點就是，當 App 閒置一段時間沒有收到 Request 的話會被迫休眠，直到收到新的 Request 才會被喚醒，而喚醒的時間通常要數十秒，我個人覺得非常久，不過畢竟是免費的就將就一下吧！

## OpenShift

除了 Heroku 之外，還有另一個免費的 VPS 服務 － [OpenShift](https://www.openshift.com/)，不過它是比較偏向 IaaS，而且速度相對 Heroku 好像慢了點，有興趣的讀者可以玩玩看。

## PM2

找 VPS 的同時，我們也要注意 App 程式在 Production 的環境下該如何優化，[PM2](https://github.com/Unitech/pm2) 是一個 Production Process Manager，我們的 Boilerplate 在 Production 環境也是透過 PM2 來啟動 Server 的，筆者自己使用它的原因主要是因為 Node 本身是 Single Thread，只能跑在單一 Core 上，藉由 PM2 的輔助，我們可以將 App Fork 到所有的 CPU Cores 上形成 Cluster，理論上可以達到平行化加速的效果。

Boilerplate 中的 Porduction App 程式進入點 [src/server/pm2Entry.js](https://github.com/gocreating/express-react-hmr-boilerplate/blob/dev/src/server/pm2Entry.js) 是修改自 PM2 官網提供的[教學文件](http://pm2.keymetrics.io/docs/usage/use-pm2-with-cloud-providers/)，內容是在講解使用 Programmable 的方式控制 PM2 運行在 Heroku 上，有興趣的讀者歡迎自行閱讀。


Day 24 - Deploy - Technique Stack


## Deployable App

要讓 Node 的 Web App 部署在 Heroku 上需要注意兩件事：

1. Procfile

  為了讓 Heroku 知道如何啟動 App，需要在 Repo 根目錄建立一個檔案命名為 `Procfile`，例如 Boilerplate 的 Procfile 長這樣：

  ```
  web: npm run pm2
  ```

  意思是告訴 Heroku，我們的 Web App 要執行 `npm run pm2` 這個指令才能啟動。

2. Port

  千萬要注意 App 綁定的 Port 不可以寫死，Heroku 是透過環境變數 `PORT` 告訴我們的 App 要 Listen 哪一個 Port，所以 Production 環境下使用 Port 的優先順序應該是 `process.env.PORT` 高於預設 Port。

  我們的 Boilerplate 有三個綁定 Port 的可能性，按照優先順序是：

  - `PORT=9487 npm run pm2` 使用環境變數
  - `npm run pm2 -p 9487` 使用 Switch
  - `npm run pm2` 不綁定 Port，使用預設值 3000

  > 參考程式碼：[src/server/utils/getPort.js](https://github.com/gocreating/express-react-hmr-boilerplate/blob/dev/src/server/utils/getPort.js)

## 一鍵部署

Heroku 是借助 Git 的操作來部署 App，但是開發用的 Repo 需要 ignore 建置出來的檔案，部署用的 Repo 需要 ignore 原始碼，留下建置檔案，兩個 Repos 是完全衝突的，所以我在 Boilerplate 的作法是建立 `.deploy` 資料夾當作部署用 Repo 的根目錄，再搭配 Gulp Task 將必要檔案塞進去，接著執行 Git 和 Heroku 的 CLI 指令進行部署。

完整部署細節可以參考 [gulpfile.js](https://github.com/gocreating/express-react-hmr-boilerplate/blob/dev/gulpfile.js) 的 `deploy` Task。

在部署之前會先執行過測試指令 `npm test`，此時 `build` 資料夾下就會是 Production 版本的 App 了，此時只要執行：

```
gulp deploy
```

就能將 `build` 資料夾下的 App 部署至 Heroku 上了。

> 如果是第一次使用 Heroku CLI，要記得先以 CLI 指令登入 Heroku 才能夠正常使用 gulp deploy。


Day 25 - Deploy - Heroku


## Mirror Branch

我們先前費了很大的力氣，打造出一個這麼完整的 Boilerplate，但是究竟要怎麼拿它來加速開發客製化的程式呢？直覺上當然就是直接 Clone 下來開始客製化，但是一旦這麼做，Boilerplate 的 Codebase 和客製化 App 的 Codebase 從此就攪和在一起了，可想而知專案會變得難以維護。

所以筆者在此提出 `mirror` Branch 的概念，這是在 Git Flow 的 Branching Model 下新增的獨立 Branch，基本上就是把 Boilerplate Repo 的 `master branch` 拉到 App Repo 當作 `mirror branch`：

```
cd <your_project>
git flow init -d
git remote add -t master mirror https://github.com/gocreating/express-react-hmr-boilerplate.git
git fetch mirror master:mirror
```

再利用 Git Flow 的操作，將專案的初始化當作一個 Feature 合併到 develop branch：

```
git flow feature start mirror
git merge --no-ff --no-edit mirror
git flow feature finish mirror
```

接著你可能會需要修改 Boilerplate 的設定，像是 MongoDB 的帳密、.gitignore 設定等等，筆者自己是當作一個 Feature 來處理：

```
git flow feature start tune-mirror
# git commit ...
git flow feature finish tune-mirror
```

如果是剛建立的專案，可以用以下指令 Push 至 Git Server：

```
git remote add origin <your_project.git>
git push -u origin master
```

## Upgradation

各位可能會覺得上面的做法很瑣碎，有種多此一舉的感覺，但其實目的是為了 Boilerplate 可能隨時會更新而設計。我們的 Boilerplate 不是萬能的，總有一天會發現 Bug，總有一些時候，會想要做一些架構性的改善，或是新增好用的功能，簡單來說就是我們隨時會升級 Boilerplate。

倘若 Boilerplate 更新了，我們要如何把新的 Code 合併到已經使用 Boilerplate 開發到一半的 App 呢？這時候 mirror branch 就發揮了很大的好處，因為 mirror branch 和 Boilerplate Repo 是完全同步的，所以可以直接 Pull 最新版本的 Boilerplate：

```
git checkout mirror
git pull mirror mirror
```

接著才是考驗開發者功力的時候，一樣使用 Git Flow 開出 Feature 來處理新版本 mirror 和目前 App 的 Conflict：

```
git checkout develop
git flow feature start upgrade-mirror
git merge --no-ff --no-edit mirror
# solve conflicts
git flow feature finish upgrade-mirror
```

如果不是做架構性的變動，只是單純安全性更新、加新 Feature 的話，這樣的維護模式其實不太需要處理 Conflict，無論手上有多少客製化的 App 專案，都可以借助這個 mirror branch 機制優雅地管理每一個 App Repo！


Day 26 - Example - Start a new project


整個 Boilerplate 包覆了前端 Flux 及後端 MVC，還要注意 API、Pagination 等大大小小的細節，如果直接抓了 Boilerplate 就拿來用，門檻似乎有點太高了，所以今天我想帶各位讀者在 Boilerplate 的規範之下，實作一個`商業版`的 Todo List App。

## 建立新 Feature

```
git flow feature start todo-app
```

## 建立 Model

新建 Mongoose Model `src/server/models/Todo.js`：

``` js
import mongoose from 'mongoose';
import paginatePlugin from './plugins/paginate';

let Todo = new mongoose.Schema({
  text: String,
}, {
  versionKey: false,
  timestamps: {
    createdAt: 'createdAt',
    updatedAt: 'updatedAt',
  },
});

Todo.plugin(paginatePlugin);

export default mongoose.model('Todo', Todo);
```

> 完整程式碼：[src/server/models/Todo.js](https://github.com/gocreating/express-react-hmr-boilerplate/blob/dev/src/server/models/Todo.js)

考量 Todo Item 可能會有分頁的需求，因此掛上 Paginate Plugin。建立好 Model 之後，我習慣會在這個 Moment 做一次 Git Commit。

## 撰寫 API

先看 API Server 的部分，編輯 `src/server/routes/api.js`，補上 Todo Item 的 REST API 路由（由於我們不需要讀取單一 Todo Item 的內容，所以只有 List、Create、Update、Remove，而沒有 Read）：

``` js
import bodyParser from '../middlewares/bodyParser';
import todoController from '../controllers/todo';

export default ({ app }) => {
  // ...其他路由
  app.get('/api/todos', todoController.list);
  app.post('/api/todos', bodyParser.json, todoController.create);
  app.put('/api/todos/:id', bodyParser.json, todoController.update);
  app.delete('/api/todos/:id', todoController.remove);
};
```

> 完整程式碼：[src/server/routes/api.js](https://github.com/gocreating/express-react-hmr-boilerplate/blob/dev/src/server/routes/api.js)

再建立 Controller `src/server/controllers/todo.js`，實作 Todo Model 的 CRUD 操作：

``` js
import assign from 'object-assign';
import { handleDbError } from '../decorators/handleError';
import filterAttribute from '../utils/filterAttribute';
import Todo from '../models/Todo';

export default {
  list(req, res) {
    Todo.paginate({
      page: req.query.page,
      perPage: 5,
    }, handleDbError(res)((page) => {
      Todo
        .find({}, null, {
          limit: page.limit,
          skip: page.skip < 0 ? 0 : page.skip,
          sort: { createdAt: 'desc' },
        })
        .then((todos) => {
          res.json({
            todos: todos,
            page: page,
          });
        });
    }));
  },

  create(req, res) {
    const todo = Todo({
      text: req.body.text,
    });

    todo.save(handleDbError(res)((todo) => {
      res.json({
        todo: todo,
      });
    }));
  },

  update(req, res) {
    let modifiedTodo = filterAttribute(req.body, [
      'text',
    ]);

    Todo.findById(req.params.id, handleDbError(res)((todo) => {
      todo = assign(todo, modifiedTodo);
      todo.save(handleDbError(res)(() => {
        res.json({
          originAttributes: req.body,
          updatedAttributes: todo,
        });
      }));
    }));
  },

  remove(req, res) {
    Todo.remove({_id: req.params.id}, handleDbError(res)(() => {
      res.json({});
    }));
  },
};
```

> 完整程式碼：[src/server/controllers/todo.js](https://github.com/gocreating/express-react-hmr-boilerplate/blob/dev/src/server/controllers/todo.js)

接著是 Common Side 的部分，要來做 API 的 Mapping。建立 `src/common/api/todo.js`：

``` js
export default (apiEngine) => ({
  list: ({ page }) => apiEngine.get('/api/todos', { params: { page } }),
  create: (todo) => apiEngine.post('/api/todos', { data: todo }),
  update: (id, todo) => apiEngine.put(`/api/todos/${id}`, { data: todo }),
  remove: (id) => apiEngine.del(`/api/todos/${id}`),
});
```

> 完整程式碼：[src/common/api/todo.js](https://github.com/gocreating/express-react-hmr-boilerplate/blob/dev/src/common/api/todo.js)

目前為止，我們已經完成 Isomorphic API 了，一樣 Git Commit 一下。

## Reducer

編輯 `src/common/reducers/paginationReducer.js`，由於我們需要列出不同頁的 Todo List，同時還要兼顧 Caching，所以在這個 Reducer 內加上 `todos` 這個需要被分頁的資源：

``` js
import Resources from '../constants/Resources';

// ...其他處理細節的 Reducer

let paginate = /* ... */

let paginationReducer = combineReducers({
  // ...其他需要分頁的 State
  todos: paginate(Resources.TODO),
});

export default paginationReducer;
```

> 完整程式碼：[src/common/reducers/paginationReducer.js](https://github.com/gocreating/express-react-hmr-boilerplate/blob/dev/src/common/reducers/paginationReducer.js)

## Action Creator

Store 中儲存 Data 的資料結構確定以後，就可以撰寫 Action Creator 來操作 Store 了。請建立 `src/common/actions/todoActions.js`：

``` js
import { normalize, arrayOf } from 'normalizr';
import { todoSchema } from '../schemas';
import Resources from '../constants/Resources';
import { setEntities, removeEntities } from './entityActions';
import { setPages, prependEntitiesIntoPage } from './pageActions';

export const setTodos = (res) => (dispatch, getState) => {
  let normalized = normalize(res.todos, arrayOf(todoSchema));

  dispatch(setEntities(normalized));
  dispatch(setPages(Resources.TODO, res.page, normalized.result));
};

export const addTodo = (todo) => (dispatch, getState) => {
  let normalized = normalize([todo], arrayOf(todoSchema));

  dispatch(prependEntitiesIntoPage(
    Resources.TODO,
    normalized,
    1
  ));
};

export const removeTodo = (id) => removeEntities(Resources.TODO, [id]);
```

> 完整程式碼：[src/common/actions/todoActions.js](https://github.com/gocreating/express-react-hmr-boilerplate/blob/dev/src/common/actions/todoActions.js)

這裡的 Action Creator 主要是將 API 收到的 Response Data 透過 normalizr 正規化成 Store 儲存的資料結構。

到這裡建立完 Reducer 與 Action Creator 等 Redux 相關的程式時，我也會進行一次 Commit。

## View

建立 `src/common/components/pages/todo/ListPage.js`：

``` js
import React, { Component } from 'react';
import { connect } from 'react-redux';
import { push } from 'react-router-redux';
import Resources from '../../../constants/Resources';
import todoAPI from '../../../api/todo';
import { pushErrors } from '../../../actions/errorActions';
import { setCrrentPage } from '../../../actions/pageActions';
import {
  setTodos,
  addTodo,
  removeTodo,
} from '../../../actions/todoActions';
import PageLayout from '../../layouts/PageLayout';
import Pager from '../../utils/BsPager';

class TodoItem extends Component {
  // ...
}

class ListPage extends Component {
  constructor() {
    super();
    this.handlePageChange = this._handlePageChange.bind(this);
    this.fetchTodos = this._fetchTodos.bind(this);
    this.handleAddClick = this._handleAddClick.bind(this);
  }

  componentDidMount() {
    let { location } = this.props;

    this.fetchTodos(location.query.page || 1);
  }

  componentDidUpdate(prevProps) {
    let { page, todos } = this.props;

    if (todos.length === 0 && prevProps.page.current !== page.current) {
      this.fetchTodos(page.current);
    }
  }

  _handlePageChange(pageId) {
    let { dispatch } = this.props;

    dispatch(setCrrentPage(Resources.TODO, pageId));
  }

  _fetchTodos(page) {
    let { dispatch, apiEngine, location } = this.props;

    todoAPI(apiEngine)
      .list({ page })
      .catch((err) => {
        dispatch(pushErrors(err));
        throw err;
      })
      .then((json) => {
        dispatch(setTodos(json));
        dispatch(push({
          pathname: location.pathname,
          query: { page: json.page.current },
        }));
      });
  }

  _handleAddClick() {
    let { dispatch, apiEngine } = this.props;
    let text = this.refs.todotext.value;

    todoAPI(apiEngine)
      .create({ text })
      .catch((err) => {
        dispatch(pushErrors(err));
        throw err;
      })
      .then((json) => {
        dispatch(addTodo(json.todo));
        this.refs.todotext.value = '';
      });
  }

  handleSaveClick(id, newText) {
    let { dispatch, apiEngine } = this.props;

    return todoAPI(apiEngine)
      .update(id, { text: newText })
      .catch((err) => {
        dispatch(pushErrors(err));
        throw err;
      })
      .then((json) => {
        this.fetchTodos();
      });
  }

  handleRemoveClick(id) {
    let { dispatch, apiEngine } = this.props;

    todoAPI(apiEngine)
      .remove(id)
      .catch((err) => {
        dispatch(pushErrors(err));
        throw err;
      })
      .then((json) => {
        dispatch(removeTodo(id));
      });
  }

  render() {
    let { page } = this.props;

    return (
      <PageLayout>
        <input
          disabled={page.current !== 1}
          type="text"
          ref="todotext"
        />
        <button
          disabled={page.current !== 1}
          onClick={this.handleAddClick}
        >
          Add Todo
        </button>

        <ul>
          {this.props.todos.map((todo) =>
            <TodoItem
              key={todo._id}
              onRemoveClick={this.handleRemoveClick.bind(this, todo._id)}
              onSaveClick={this.handleSaveClick.bind(this, todo._id)}
              text={todo.text}
            />
          )}
        </ul>
        <Pager
          page={page}
          onPageChange={this.handlePageChange}
        />
      </PageLayout>
    );
  }
};

export default connect(({ apiEngine, pagination, entity }) => {
  let { page } = pagination.todos;
  let todoPages = pagination.todos.pages[page.current] || { ids: [] };
  let todos = todoPages.ids.map(id => entity.todos[id]);

  return {
    apiEngine,
    todos,
    page,
  };
})(ListPage);
```

> 完整程式碼：[src/common/components/pages/todo/ListPage.js](https://github.com/gocreating/express-react-hmr-boilerplate/blob/dev/src/common/components/pages/todo/ListPage.js)

這個 Component 最終串起 API 與 Redux，TodoItem 的 Code 有點瑣碎，所以就省略了。到這裡建立完 Components 也要記得 Commit 一下。

## Routes

建立 Todo List 頁面的路由 `src/common/routes/todo.js`，由於每一頁都是 Lazy Load，所以要使用 `getComponent` 和 `require.ensure` 動態載入頁面：

``` js
export default (store) => ({
  path: 'todo',
  getComponent(nextState, cb) {
    require.ensure([], (require) => {
      cb(null, require('../components/pages/todo/ListPage').default);
    });
  },
});
```

> 完整程式碼：[src/common/routes/todo.js](https://github.com/gocreating/express-react-hmr-boilerplate/blob/dev/src/common/routes/todo.js)

接著編輯 `src/common/routes/index.js`，加入上面建立好的 todo 路由：

``` js
export default (store) => ({
  path: '/',
  getChildRoutes(location, cb) {
    require.ensure([], (require) => {
      cb(null, [
        // ...其他頁面路由
        require('./todo').default(store),
        require('./notFound').default(store),
      ]);
    });
  },
  // ...
});
```

> 完整程式碼：[src/common/routes/index.js](https://github.com/gocreating/express-react-hmr-boilerplate/blob/dev/src/common/routes/index.js)

至此，我們完整實作了一個 Todo List App，打開瀏覽器就可以操作它了。確保正常運作後就可以 Commit 了！

## 撰寫測試

這個步驟我認為對一個新功能而言是非必要的，畢竟新功能很可能朝令夕改，所以寫不寫測試就看個人需求吧！

而 Todo List 的測試其實在 Day 22 已經有完整程式碼及說明，請參考 [Day 22 - Testing - 撰寫 End-To-End API 測試](./22)。

## 整理 Commit

實際上我很少依序寫完一個部份就 Commit 一次，比較常發生的情況是，整個 Feature 完成大約 90% 時才開始 Commit，開發順序也不會是這麼明確地 Step By Step，反而是 MVC + Redux 整陀一起寫，哪邊缺功能就寫哪邊，遇到 Bug 就修 Bug。當整個 Feature 寫得差不多了，再逐漸挑檔案進行 Commit。

通常在我 Commit 下去的那一瞬間，總是會發現程式碼裡面有 Typo，或者是突然找到 Bug，有時甚至是漏了一些功能。如此一來，後面為了修正程式所作的 Commit 會把 Commit History 弄得非常凌亂，這種時候我通常是透過 `git rebase -i` 指令來整理 Commit History。不過 Git 不屬於我們的討論範圍，而且也是我要求各位讀者閱讀本系列文章的先備技能，所以如果不懂的話還是請 Google 吧！

## 跑測試 & 完成 Feature

確定完成整個 Feature 之前，記得要跑一下測試：

```
npm test
```

如果有問題，就持續修正，然後回到上一步整理 Commit，直到測試通過為止，就能執行以下指令把新功能併入 develop branch 了：

```
git flow feature finish todo-app
```


Day 27 - Example - Todo List App


我們費了這麼大工夫搞出這麼一個 Boilerplate，要怎麼知道它不是紙上談兵，而是真的可以上線當做商業服務呢？最好的辦法當然就是拿它來實作商業應用！

現階段我正使用這個 Boilerplate 開發自己參與的新創團隊的網站服務 － [Caserhub](http://www.caserhub.com/)；一位好友目前的新創團隊也採用我們的 Boilerplate 來開發自己的商業應用；另外，我自己最先套用 Boilerplate 的應用是我的[個人網站](https://gocreating.herokuapp.com/)；日後我也打算拿這套 Boilerplate 開發實驗室的[形象網站](http://mccc.herokuapp.com/)。

## Case #1 - Caserhub

![28-1.png](/posts/2016-12-01-ithome-iron-man/28-1.png)

在這個應用中，非常著重表單的填寫，還有表單欄位的多元性，因此 Boilerplate 在表單處理上提供的大量彈性根本發揮地淋漓盡致啊！在此案例中，我需要客製化一個深度未知的巢狀 Select 欄位，也需要可以輸入標籤的 Input 欄位，多虧了 Boilerplate 先前規劃好的欄位寫法與架構，讓我可以在短時間內建出這兩種客製化的新欄位，而且很方便地直接使用在表單上。

## Case #2 - 個人網站

![28-2.png](/posts/2016-12-01-ithome-iron-man/28-2.png)

我的個人網站其實目前是未完工的狀態，目前正在使用 Draft.js 開發 WYSIWYG 編輯器，打算做為個人部落格的發文工具。在這個案例中，我可以全心開發編輯器，而不必煩惱多國語系、後台管理系統等如何撰寫，因為 Boilerplate 都已經幫我完成了。

## Boilerplate 的回饋補償機制

各位是否注意到，其實這些客製化專案中新增的 Feature 不只是能夠用在自己的專案裡，其實可以淬煉成獨立的模組再塞回 Boilerplate 中，而且這些新 Feature 是經過 Real World 的考驗，提供 Feature 的模組本身已經擁有適度的開發彈性（該有的 props 都有了，該有的 options 也都有了）。

因此從這幾個案例中，我歸納出了 Boilerplate 的生態中其實隱藏著`回饋補償機制`。

上游的 Boilerplate 提供基礎設施給下游不同的專案來進行客製化，客製化的過程中會開發出新的好用模組，這些模組為了適應客製化專案的需求而逐漸完善，最終這些好用的模組可以被加回 Boilerplate 中，未來就能提供更好用的 Boilerplate；而當上游的 Boilerplate 發現問題時，也可以透過 Git 的操作把 Patch 下載至下游的專案中。

下游專案把好用模組`回饋`給上游 Boilerplate，上游 Boilerplate 也把 Bug 的修正`補償`至下游的專案裡，這樣的機制我把它稱做`回饋補償機制`，由於它是一個正向的循環，所以我認為 Boilerplate 將會不斷進化，這也是為什麼我一直看好我們的 Boilerplate 的原因。


Day 28 - Case Study - Customization for your own app


前面我們從開發上的細節，一路談到測試、部署，算是圓滿走完一個迴圈了，但是，這樣的 Boilerplate 其實還有很多不足之處，對我來說，它永遠都是有改進空間的，所以今天要來講的不是技術細節，而是這個專案的遠景以及未來。

## React Native

首先我想做的是徹底落實 Universal 的精神，讓這一套 Codebase 不只是用在 Modern Web 的開發，而是把觸手伸往手機的 Native App，或是 Web-Based 的 PC App。React Native（簡稱 RN）是一個很有潛力的 Native App 開發工具，一樣使用 JSX 的語法，一樣使用 Redux 來管理狀態，一樣遵守 Flux 流程，一樣呼叫 Isomorphic API，基本上很多 Codebase 都是可以重複使用的。

目前我已經有試著在 Boilerplate 整合 RN，但是可能會有一些架構上的變動，所以實在不得不謹慎規劃，總之就敬請各位期待吧！

## Payment Service

這個 Boilerplate 一直都是以商業考量為重心，理當要有金流服務，但是筆者實在分身乏術，還沒有時間整合金流相關的功能，目前只有參考過幾個不同的 Library 或 SDK，乍看下 [Stripe](https://stripe.com/) 將會是我的首選，瞄過文件就略懂 7 成了，其它 Library 幾乎都是有看沒有懂，或者是對台灣的支援度不夠。日後如果整合好金流功能，可能會實作個 Donate Button 跟各位討錢吧 XD

## API Versioning

第三項是關於 API 的 Issue，目前 Boilerplate 的 API Server 沒有考量過版本的劃分，筆者雖然曾經查詢過相關議題，但網路上的風向好像亂亂的，有的人習慣把版本號塞進 URL：

```
http://company.com/api/v3.0/customers/123
```

有的人覺得要塞進 HTTP Header，讓 URL 保持乾淨的 RESTful 形式：

```
Content-Type: application/vnd.company.myapp-v3+json
```

我自己是偏好塞在 Header，不過要實作 API Versioning 也要很久之後了吧...

## CLI Code Generator

Boilerplate 本來就是拿來加速開發用的，所以我其實很想提供像 Rails 那樣的 CLI 工具，敲幾個指令就幾乎快把網站完成了。不過這個功能不能夠急著做，我想繼續實驗整個 Boilerplate 的架構是否有足夠的可靠度，等到整個架構不會朝令夕改的時候，才能夠發展 CLI 來自動化產生 Code。

以上四點是我目前對 Boilerplate 未來的主要想法，其餘的支線任務都列在 README 的 Roadmap 中，當然，這一切都只是我自己在腦補和幻想，隨時都可能說改就改，最終還是會看心情挑功能來實作！


Day 29 - Feature Works & Issues


這是一個有始有終的系列文章，即使今天是最後一章，我還是會把自己身上的技術涵養往讀者們的身上灌。

其實 Boilerplate 的應用情境非常多元，而我希望提供的是撐起大型應用的梁柱，是舒緩網站開發痛點的止痛劑，讓開發者只專注在開發自己產品的核心功能而無後顧之憂。

## 寫網站一點都不簡單

要完成一個 Boilerplate 絕不是一件容易的事，更何況是一個真正上線擺在你眼前的網站，所以即使是再小的網站，我都是對作者抱持著一顆尊敬的心，因為他投入的時間絕對比你想像中還要多，你永遠不知道他究竟花了多少心思在做以下的事情：

- 決定專案名稱
- 註冊各種服務
  - Go Daddy
  - Gmail
  - MongoLab
  - Google Analytics
  - Recaptcha
  - ...
- 註冊網域
- 找主機、找營運的方式（IaaS、PaaS、...）
- 找 Storage Server
- 找佈景主題，或是與設計師來回溝通
- 找字型
- 找無版權的素材
- 蒐集文案（服務條款、隱私權政策、...）
- 翻譯網站內容
- 建立 Repo
- 查詢需要用到的 Library、閱讀文件，內化之後實作出來
- 決定資料庫的 Schema
- 設計 API
- 了解常見安全議題，且知道如何應對
- 開始一個專案的生命週期
  - Develop
  - Debug
  - Staging
  - Commit
  - Refactor
  - Push
  - Deploy
- 撰寫測試
- 撰寫文件

更別忘了，能夠做到以上事情之前，要先投入多少心力學習以下這堆技術：

- html
- css
- javascript
- nodejs
- mvc
- reactjs
- flux
- git
- git flow
- http protocol
- rest api

一個使用者用 iPhone 6 的 Safari 看見網站上的一個按鈕，當下只會覺得就是一個按鈕；但是對工程師而言，先撇開按鈕觸發的互動不談，這個按鈕必須要兼顧手機、平板、電腦 3 種使用情境，Chrome、Firefox、Safari、IE 等至少 4 種瀏覽器，要考慮這個按鈕的一般狀態、hover 狀態、active 狀態、disable 狀態等至少 4 種狀態，總共 3 * 4 * 4 至少 48 種狀態下的每個狀態的 width、height、padding、margin、border、color、background、font、...

工程師看見的是 N 個維度的空間（Space），使用者看見的卻只是投影出來的一維的點（Point）。所以外行人看網站覺得簡單，是因為他們只看見看的見的東西；內行人看網站之所以覺得複雜，是因為看見太多別人看不見的。

## 致謝

- 感謝 Jeremy 的 Boilerplate 啟發了我這個專案的靈感
- 感謝朋友[沒一村](https://www.facebook.com/noootownnotes/?fref=ts)提供了這個比賽活動資訊

```











＊＊＊＊＊＊ 人格分裂分隔線 ＊＊＊＊＊＊











```

呵呵總算撐到第30天惹

你們以為我會正經到最後一刻嗎？

你他媽陀螺還在轉ㄅ

當然是要先來發一篇廢文慶祝R

完成鐵人的第一件事情就是

就是～

就是～就是！！！

就是！

鄧愣！

![30-1.gif](./30-1.gif)

要在人生的夢想清單勾起「完成IT鐵人賽」啊啊啊啊！！！！！

嗚嗚

真4太感動惹

眼睛都哭到快要掉下來惹

![30-2.jpg](./30-2.jpg)

女朋友也是替我哭得不要不要的

濕了一整片

.

.

.

![30-3.jpg](30-3.jpg)

內心小劇場演完 ler

大 guy 就是這樣

下台一鞠躬

謝謝大家看完這篇廢文

還有前面 29 篇 U 質好文

喜歡或認同請按讚加分享

我會祝你一生平安


Day 30 - 結語


原文為筆者參與`2017 iT 邦幫忙鐵人賽`所發表的系列文章，現重新收錄於個人部落格留存。

30 天打造 MERN Stack Boilerplate

文章列表