埋設 DFP - DoubleClick for Publishers 廣告

初始設定

比較跳脫一般經驗法則的是，在載入 script 之後，服務仍然不是可用狀態，因此，此時不可呼叫相關服務 API。

譬如，以下是錯誤做法：

1
2
3
4

$.getScript('//www.googletagservices.com/tag/js/gpt.js').then(function () {
    window.googletag.pubads().enableSingleRequest();
    window.googletag.enableServices();
});

不論是透過直接在 html 中埋入 script tag 的方式載入，或是以上面的方式動態載入 DFP script，都不可以直接呼叫 DFP 的 API。

正確的做法，須將命令以函數的形式，推到 window.googletag.cmd 陣列中。注意，此時 googletag 和 googletag.cmd 可以只是普通物件和陣列。待 DFP 服務啟動後，會在 googletag 中添加功能，然後逐一呼叫被推入 googletag.cmd 陣列的函數。也就是說，在該函數中才能保證 DFP 的服務已備妥，並且才能呼叫 API：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

var adUnitPath = 'pub-id/slot-id';
var adSize = [300, 25];
var adElementId = 'id-to-html-element';

$.getScript('//www.googletagservices.com/tag/js/gpt.js').then(function () {
    var googletag = window.googletag || (window.googletag = []);
    googletag.cmd = (googletag.cmd || []);
    googletag.cmd.push(function () {
        initDfp();
        googletag.defineSlot(adUnitPath, adSize, adElementId)
            .addService(googletag.pubads());
        googletag.display(adElementId);
    });
});

function initDfp() {
    googletag.pubads().enableSingleRequest();
    googletag.enableServices();
}

上面的 adElementId，雖然在 DFP 上使用 generate tag 時，會產生一個 div-gpt-ad-1234567890123-0 格式的字串，要我們填在 html 元素作為 id 使用，但其實只要保握 html 的基本原則：id 不要重複，在這裡使用任意 id 皆可，並不影響廣告呈現。不過 DFP 仍然建議，id 最好能反映廣告版位，以方便投廣告的客戶確認。

多個廣告版位

上面的做法，如果直接套用在多個廣告上，雖然不會有什麼問題，但是重複執行 DFP 的設定，還是讓人渾身不舒服。

可以將 $.getScript() 和 initDfp() 的處理包裝起來，讓它們永遠只會執行一次：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

function once(fn) {
    var promise;
    return function () {
        var args;
        if (!promise) {
            args = Array.prototype.slice.call(arguments);
            promise = Promise.resolve(fn.apply(null, args));
        }
        return promise;
    };
}

var loadDfp = once(function () {
    return $.getScript('//www.googletagservices.com/tag/js/gpt.js').then(function () {
        window.googletag = window.googletag || {};
        window.googletag.cmd = window.googletag.cmd || [];
        return window.googletag;
    });
});

var initDfp = once(function (googletag) {
    googletag.pubads().enableSingleRequest();
    googletag.enableServices();
});

然後，每個要新增版位的地方，都這樣呼叫：

1
2
3
4
5
6
7
8

loadDfp().then(function (googletag) {
    googletag.cmd.push(function () {
        initDfp(googletag);
        googletag.defineSlot(adUnitPath, adSize, adElementId)
          .addService(googletag.pubads());
        googletag.display(adElementId);
    });
});

注意到，initDfp() 的呼叫，不能併到 loadDfp() 中執行，只能在 googletag.cmd.push() 的函數中執行，否則就又犯了一開始的錯誤。

上面的寫法，還是有點囉唆，於是，我們還可以進一步包裝成這樣：

1
2
3
4
5
6
7
8

function dfp(fn) {
    loadDfp().then(function (googletag) {
        initDfp(googletag);
        googletag.cmd.push(function () {
            fn(googletag);
        });
    });
}

1
2
3
4
5

dfp(function(googletag) {
    googletag.defineSlot(adUnitPath, adSize, adElementId)
        .addService(googletag.pubads());
    googletag.display(adElementId);
});

動態新增廣告

上面的做法，適用於內容不會變動的頁面。如果是無限捲動列表形式的頁面，可能需要每隔幾個項目就顯示一則廣告。官方建議的做法，是透過呼叫 disableInitialLoad() 函數禁止初始廣告載入，然後於版面備妥時，再呼叫 refresh() 更新廣告內容。

1
2
3
4
5

function initDfp(googletag) {
    googletag.pubads().enableSingleRequest();
    googletag.pubads().disableInitialLoad();
    googletag.enableServices();
}

注意上面 googletag.pubads().disableInitialLoad() 的呼叫。此呼叫將改變 display() 函數的行為，使 display() 函數只註冊廣告版位，而不進行顯示。

在動態插入廣告之後，再呼叫 refresh() 函數，更新廣告：

1
2
3
4
5
6

dfp(function(googletag) {
    var slot = googletag.defineSlot(adUnitPath, adSize, adElementId)
        .addService(googletag.pubads());
    googletag.display(adElementId);
    googletag.pubads().refresh([slot]);
});

注意上面如何儲存 slot，然後用以呼叫 refresh() 函數。

自動縮合沒有廣告的版面

也許我們的版位不是非常熱門，經常開天窗(希望不是)。一旦廣告版位沒有人投遞廣告，該廣告版位就會顯示成空白。如果這是所有的版面的常態的話，可以考慮直接在初始化的時候，設定所有的版面在沒有廣告的時候，自動縮合。

1
2
3
4
5
6

function initDfp(googletag) {
    googletag.pubads().enableSingleRequest();
    googletag.pubads().disableInitialLoad();
    googletag.pubads().collapseEmptyDivs();
    googletag.enableServices();
}

或者，也可以根據需要，依據版面別進行個別設定：

1
2
3
4
5
6
7
8
9
10

var adCollapse = false;

dfp(function(googletag) {
    const slot = googletag.defineSlot(adUnitPath, adSize, adElementId)
        .addService(googletag.pubads())
        .setCollapseEmptyDiv(adCollapse);
    googletag.display(adElementId);
    googletag.pubads().refresh([slot]);

});

React Component 範例

最後，測試的過程中寫了一簡單的 React 範例程式，提供給大家參考。

參考資料

• Google 發佈商廣告代碼範例
• 收合空白的 div 元素
• API

前言

這篇文章記錄個人嘗試 CSS-modules 過程中所遇到的問題，並且順便將目前業界各種對 modular css 的嘗試/進展，做一個相關資訊的摘錄。

還沒有找到適合自己偏好作法的讀者，可以將此文視為簡單的技術選型指南，從中挑選適合自己的作法。

模組化的 CSS

學過網頁設計的人都知道，CSS 作用的對象，是整個 html 文件。這在過去網頁都是靜態文件為主的年代，完全是合情合理的設計，不過到現代大量 Web App 為主的 SPA 時代，這樣的特性，反而造成 Web App 開發的困擾。而 CSS 規格的發展，又遠遠落後於 JavaScript / HTML5 的發展，因此，出現了各種不同的模組化嘗試。

CSS-in-JS (Inline Styles)

在這一兩年引起廣泛注目的 ReactJS，其引入的 JSX 語法，倡導在 JavaScript 中撰寫 html markup。更早，甚至於在發表 ReactJS 之前，其團隊就有人介紹 CSS-in-JS 的構想 (YouTube 影片找到後補上)：以 JavaScript 撰寫 CSS，從而避開 global scope 的問題。

原理就是使用 JSON 語法取代 css rule，然後使用程式轉換為 css inline style，再設定給元件。譬如：

1

head.style.cssText = 'width:200px;height:70px;display:bolck';

現在最受歡迎的 radium，引用其 readme 介紹，用法像這樣：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49

var Radium = require('radium');
var React = require('react');
var color = require('color');

@Radium
class Button extends React.Component {
  static propTypes = {
    kind: React.PropTypes.oneOf(['primary', 'warning']).isRequired
  };

  render() {
    // Radium extends the style attribute to accept an array. It will merge
    // the styles in order. We use this feature here to apply the primary
    // or warning styles depending on the value of the kind prop. Since its
    // all just JavaScript, you can use whatever logic you want to decide which
    // styles are applied (props, state, context, etc).
    return (
      <button
        style={[
          styles.base,
          styles[this.props.kind]
        ]}>
        {this.props.children}
      </button>
    );
  }
}

// You can create your style objects dynamically or share them for
// every instance of the component.
var styles = {
  base: {
    color: '#fff',

    // Adding interactive state couldn’t be easier! Add a special key to your
    // style object (:hover, :focus, :active, or @media) with the additional rules.
    ':hover': {
      background: color('#0074d9').lighten(0.2).hexString()
    }
  },

  primary: {
    background: '#0074D9'
  },

  warning: {
    background: '#FF4136'
  }
};

雖然解決了 global scope 問題，但似乎引入了更多問題：

1. 難以搭配使用前處理器，

   這應該是致命問題，至少，autoprefixer 應該已經是標準配備了吧。

2. 難以調整、除錯。

   由於 inline style 只對單一元件有效，在 Chrome DevTools 中，一次也只能改一個元件，不像平常只要修改 rule，馬上就可以套用到所有的對應元件上。

Naming Conventions

使用人為的命名規範方式，來區別模組名稱。

這方面的嘗試堪稱代表的有：OOCSS, SMACSS, BEM, SUIT，其中又以 BEM 及 SUIT 最受到歡迎。許多人認為 SUIT 是 BEM 的改良，而其語法除了 camelCase 較不討喜之外，相對於 BEM 使用 __ 及 -- 來區別層級，SUIT 的語法更容易理解。

採用命名規範來處理 css 的模組化問題，最重要的守則，就是：

採用這些方案的好處是，由於是 100% 原生的 CSS 語法，因此有以下優點:

1. 不須要任何前處理器工具，導入、除錯最容易，
2. 可以輕易與既有的前處理器工具搭配，
3. 可以避免使用巢狀的選擇器，提昇效能，並且避免結構依賴問題。

上面第二項，譬如可以使用 PostCSS 外掛 postcss-bem，就可以使用巢狀的宣告方式，省卻繁複的名稱重複撰寫問題，輕鬆撰寫符合 SUIT 規範的 CSS：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

@namespace app {
  @component SearchForm {
    padding: 0;
    margin: 0;

    // Typically, place modifiers above descendents
    @modifier advanced {
      padding: 1rem;
    }

    @descendent textField {
      border: 1px solid #ccc;

      // This creates a state for the textField descendant
      @when invalid {
        border: 1px solid red;
      }
    }
  }
}

輸出：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

.app-SearchForm {
  padding: 0;
  margin: 0;
}

.app-SearchForm–advanced {
  padding: 1rem;
}

.app-SearchForm-textField {
  border: 1px solid #ccc;
}

.app-SearchForm-textField.is-invalid {
  border: 1px solid red;
}

每個輸出的 class，都將直接對應到目標元件上，從而避免使用巢狀的選擇器：

1
2
3

<form name=“search” class=“app-SearchForm”>
  <input name=“name” class=“app-SearchForm-textField” required></input>
</form>

缺點：

1. 仍然是 global scope

   雖然稍後會介紹的 CSS-modules 基本上也是 global scope，不過相較於 CSS-modules，BEM/SUIT 不小心出現重複命名的機會還是比較高，不過，當然這可以透過下面提到的 linter 來避免。

2. 手動處理容易出錯

   我一直覺得很奇怪，可能是我自己閱讀的還不夠多，好像很少看到有人提到/抱怨，目前還缺乏 markup 處理工具，幫忙將同樣的結果套用到 html 上。雖然有 postcss-bem 幫忙處理 css 部份，但目前只能手動將最終的名稱套用到 html 上，仍然相當不方便，而且容易出錯。雖然有 postcss-bem-linter 來幫忙檢查 css 是否符合 BEM/SUIT 規範，卻沒有工具可以用來檢查 html。

3. 名稱太長

   如果認為 class 名稱太長，可以使用 gulp-selectors 這類工具，進一步做處理。不過也有不少反對意見，主要是認為開啟 GZip 壓縮即可，甚至也有人認為這樣會影響 SEO，但是應該是除非動到 microformat，否則沒有影響。

CSS-modules

CSS-modules 基本上只是一個規格，描述使用 :local 與 :global 關鍵字來區別 scope；使用 composes 關鍵字來引用其它規則。

CSS-modules 的作者 Mark Dalgleish，在他的 The End of Global CSS 一文中提到，利用 Webpack 在 2015/04/22 發佈的 local scope 功能，我們可以透過 :local(.className) 的語法，得到轉化之後的 class 名稱：

MyComponent.css

1
2
3
4
5
6

:local(.foo) {
  color: red;
}
:local(.bar) {
  color: blue;
}

MyComponent.jsx

1
2
3
4
5
6
7
8
9
10
11
12

import styles from './MyComponent.css';
import React, { Component } from 'react';
export default class MyComponent extends Component {
  render() {
    return (
      <div>
        <div className={styles.foo}>Foo</div>
        <div className={styles.bar}>Bar</div>
      </div>
    );
  }
}

上面 import 得到的 styles，實際上是一個 JSON 物件，內容是透過 :local() 定義的 class 名稱做為鍵值，對應到計算處理過、保證不重複的亂數名稱數值，像這樣：

1
2
3
4

{
  "foo": "_1rJwx92-gmbvaLiDdzgXiJ",
  "bar": "_13LGdX8RMStbBE9w-t0gZ1"
}

然後再利用插入字串的方式，將產出的 class 名稱，注入到 template 中，而達成某種程度隱藏 class 名稱，避免名稱污染問題。不過雖然 class 名稱已經處理過，基本上卻仍然是全域可見。

Mark Dalgleish 認為，一直不斷地重複寫 :local 太麻煩了，大多時候他都是使用 local scope，僅有極少數時候，才需要用到 global scope，所以後來 css-loader 就同意預設為 local scope 了：

1
2
3
4
5

.root {
}

.primary {
}

上面透過 styles.foo 的方式，手動以插值的方式注入 class 名稱的作法，還是比較繁瑣。我個人比較傾向於 react-css-modules 的作法，既然要用到工具來處理，既然已經使用 JSX 語法，就應該一次到位，避免再寫多餘的程式碼來引用 style：

dialog.css

1
2
3
4
5

.root {
}

.primary {
}

dialog.jsx

1
2
3
4
5
6
7
8
9
10
11
12

import React from 'react';
import CSSModules from 'react-css-modules';
import styles from './dialog.css';

@CSSModules(styles)
export default class Dialog extends React.Component {
  render() {
    return <div styleName='root'>
      <a styleName='primary'>Confirm</a>
    </div>
  }
}

注意這裡使用 styleName 來引用 class，同時也不再需要寫 styles. 部份。另外，react-css-modules 還做了檢查，若引用的 class 不存在，會提出警告。

一切都非常美好。

而我個人碰到的問題則是：

1. 與 PostCSS 搭配的取捨

   原有的專案採用 PostCSS 及 cssnext 外掛，尤其是用到了 nesting 功能，在與 css-loader 搭配上，遇到了『雞生蛋、蛋生雞』問題，無法正確設定套用的順序。目前只能先停用遇到問題的語法。

2. 預設 local scope

   我認為 css-loader 衝過頭了，預設不應該是 local scope，Local scope 只有在撰寫元件的時候需要用到。整個網頁還是有許多共用元素需要使用 global scope css。Webpack css-loader 預設開啟 local scope，會造成引用其他 framework 的 style 的極大困難。

   譬如，無法使用這樣的語法來引用 global style：

   1 2 3

   :global { @import 'normalize.css'; }

   其實我個人傾向於希望能夠在要使用 local scope 時，才以 :local block 的方式啟用：

   1 2 3 4 5 6 7

   :local { .root { } .primary { } }

   這樣就不會影響到既有的程式。

   可惜 css-loader 只能透過 modules 參數啟動，否則就完全不支援 local scope。因此，目前這個問題只能透過針對不同路徑套用不同的 css-loader 的方式解決：

   webpack.config.js

   1 2 3 4 5 6 7 8 9 10 11 12 13 14

   module: { loaders: [{ test: /.jsx?$/, loader: 'babel' }, { test: /.css$/, exclude: path.resolve(dirname, 'client'), loader: 'style!css?modules&localIdentName=[name][local]' }, { test: /.css$/, include: path.resolve(__dirname, 'node_modules'), loader: 'style!css' }] }

3. Webpack + ReactJS 以外的選擇？

由於目前 CSS-modules 的實作，主要還是基於 Webpack 的 css-loader。而 Webpack 的思維，是以 JavaScript 為核心，透過 require() 函數來描述相關資源的關係，剛好與 ReactJS 的 JSX 的作法相同，兩者可說是天作之合。然而，明明要套用 class 的對象是 html/template，卻必須勞動 JavaScript 在執行期間來處理，似乎不是那麼經濟。

雖然 Browserify 有 css-modulesify，但 Browserify 其實是更加以 JavaScript 為中心，因此採用的是與 css-loader 完全相同的作法。

我個人傾向於，工具應該要能夠在前處理期間就做好這些轉換工作，最終的 css 和 html template 都能直接處理好 local class 名稱對應，在 JavaScript 中，只要直接引用 template 即可。

輸入：

dialog.css

1
2
3
4
5

.root {
}

.primary {
}

dialog.html

1
2
3
4
5

<link href="./dialog.css" rel="stylesheet" type="text/localcss" />

<div class="root">
  <a class="primary">Confirm</a>
</div>

輸出：

dialog.html

1
2
3
4
5
6
7
8
9
10
11

<style type=“text/css”>
.root1rJwx92-gmbvaLiDdzgXiJ {
}

.primary13LGdX8RMStbBE9w-t0gZ1 {
}
</style>

<div class="root1rJwx92-gmbvaLiDdzgXiJ">
  <a class="primary13LGdX8RMStbBE9w-t0gZ1">Confirm</a>
</div>

當然，這只是目前實作的問題，除了實作預設為 local scope 值得商榷之外，CSS-modules 規範本身並沒有太大的問題。

CSS Modules 详解及 React 中实践 這篇文章有相當深入精闢的技術解說，想進一步了解 CSS-modules 的朋友千萬不要錯過。

Web Components / Shadow DOM

Shadow DOM 是 Web Components 的附屬規格，目前仍在草案階段，瀏覽器的支援也許還不足，但是實際上已經有相當多成熟的實作。最好的例子就是 Polymer，已經正式發表 1.0 版，而 AngularJS 2.0 也即將正式發佈。即使不使用 framework，也可以直接透過 polyfill 使用。

重點是，在 Shadow DOM 中，不論 markup 或 style，都是私有的，外界只能看到最外層的元件。換句話說，對 Shadow DOM 而言，CSS 就是 local scope 的！

使用 Polymer 定義元件的範例：

contact-card.html_

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

<dom-module id="contact-card">
  <link rel="import" type="css" href="contact-card.css">
  <template>
    <content></content>
    <iron-icon icon="star" hidden$="{{!starred}}"></iron-icon>
  </template>
  <script>
    Polymer({
      is: 'contact-card',
      properties: {
        starred: Boolean
      }
    });
  </script>
</dom-module>

使用方式：

index.html

1
2
3
4

<contact-card starred>
  <img src="profile.jpg" alt="Eric's photo">
  <span>Eric Bidelman</span>
</contact-card>

使用 AngularJS 2.0 定義元件的的範例：

1
2
3
4
5
6
7
8
9

import { Component } from 'angular2/core';

@Component({
  selector: 'contact-card',
  templateUrl: 'components/contact.component.html',
  styleUrls:  ['components/contact.component.css']
})
export default class ConcatCard {
}

就是這麼簡單。即使是使用 polyfill，它也會幫忙處理好 CSS scope 問題 (雖然無法真正隱藏)。只是，又回到在執行期間處理轉換的問題。

2016/04/28 補充：剛發表 2.0 版的 Vue.js，早在 1.0 時即有 "Single File Components" 的作法，透過 vue-loader 或 vueify 處理之後，也同樣具有 local scope CSS (注意 scoped 屬性):

my-component.vue

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

<style scoped>
.my-component h2 {
    color: red;
}
</style>

<template>
    <div class="my-component">
        <h2>{{msg}}</h2>
    </div>
</template>

<script>
module.exports = {
    data: function () {
        return {
            msg: 'hello!'
        }
    }
}
</script>

Houdini

Houdini: Maybe The Most Exciting Development In CSS You've Never Heard Of， 脫逃大師胡迪尼，將為我們在瀏覽器上面留下隱密的後門、看不見的掛勾，讓我們可以在最千鈞一髮的時刻全身而退。

這方面的資訊雖然還不多，不過，如同上文作者所言，這將發生在不久的將來。屆時一旦 CSS PARSER API 完成，要添加客製化的 local scope 語法，應該不是難事。

結論

若專案選擇使用 ReactJS/JSX，得力於 react-css-modules 及 Webpack 的功勞，可以使用直覺的語法，不用放棄慣用的前處理器，就可以享用 CSS-modules 的好處。

若是喜歡追求業界標準，可以考慮直接採用 Web Components/Shadow DOM，或是架構在此基礎之上的 framework 來實作。

如果不想把專案的建構搞得太複雜，則可以考慮最通用的 BEM/SUIT 命名規範方案。

參考資料

• CSS Modules
• BEM and SMACSS: Advice From Developers Who’ve Been There
• Using PostCSS with BEM and SUIT Methodologies
• CSSConf 2015 筆記(二) – CSS Modules
• 谈谈 CSS Modules
• CSS Modules 详解及 React 中实践

前言

本文整理截至目前 AngularJS 1.5 為止， 個人以為的最佳實務做法。

為什麼現在？基於以下三點理由：

• 雖然 AngularJS 2.0 發佈在即，但是既有的 AngularJS 1.x 程式碼仍需要維護。
• 由於 AngularJS 1.x 受到廣泛的歡迎，前後做了不少的改進，因此網路上到處可見其實已經過時的作法。
• 基於向後相容的原則，有些功能雖然被保留下來，但未必是最佳作法。

『你可以這麼做，不代表你必須這麼做』，基於『JavaScript: The Good Parts』的哲理，本文適合具有 AngularJS 1.x 實務開發經驗，然而卻隨著 AngularJS 的發展，逐漸對於網路上充斥各種主觀、矛盾的說法、用法感到困惑的開發者。

雖然遵循本文提出的原則，可以以趨近於元件化的風格開發 AngularJS 1.5 應用程式，但本文不涉及 AngularJS 1.x 移轉到 AngularJS 2.0 議題。

在閱讀本文之前，建議讀者可以先閱讀 Angular 1 Style Guide 這篇文章，本文的程式碼基本上遵循該文倡導的風格，除了少數與下一篇參考文章的建議牴觸之外。

本文主要內容則是基於 Sane, scalable Angular apps are tricky, but not impossible. Lessons learned from PayPal Checkout. 這篇文章，並補充個人觀點。

最佳實務

不要使用 ng-controller

出處：Don’t use ng-controller

典型的 ng-controller 用法如下：

1
2
3

<div ng-controller="myController">
  <strong>{{foo}}</strong>
</div>

這有什麼問題呢？

• ng-controller 違反元件封裝的原則：template 未能與 controller 程式碼封裝在一起，而獨自暴露在 html 中。
• 無法重複使用：基於第一個理由，你的 controller 無法直接重複使用：必須複製 template。

不要在路由中指定 controller

出處：Don’t specify controllers in your routes

不論是 AngularJS 內建的 router 或是一般常用的 ui-router，典型的寫法，都是同時指定 template / templateUrl 及 controller：

1
2
3
4
5

$routeProvider.
  when('/phones', {
    templateUrl: 'partials/phone-list.html',
    controller: 'PhoneListController'
  });

這有什麼問題呢？

其實跟『不要使用 ng-controller』的狀況類似，都是與封裝有關：

• 若使用 template 來指定，那麼當要重複使用 controller 時，就必須複製該 template，
• 若使用 templateUrl 來指定，那麼就有可能不小心指定了錯誤的 template 檔案，造成與 controller 不一致的狀況。

盡可能元件化 (使用 component 取代 ng-controller)

出處：

• Make everything a directive
• Exploring the Angular 1.5 .component() method

基於上面兩點，應該將原本可能使用到 ng-controller 的部份，一律改用 component 來寫。

雖然還是可以使用 $compileProvider.directive() 來定義 directive，在 AngularJS 1.5 下，則提供了新的 component() 函數。這是為了讓 AngularJS 1.X 程式移植到 AngularJS 2.0 比較容易，而特地提供，讓開發者以比較接近 AngularJS 2.0 component 寫法的方式來定義元件：

myComponent.html

1

<strong>{{vm.foo}}</strong>

myComponent.js

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

var myTemplate = require('./myComponent.html');

var myComponent = {
    bindings: {
        foo: '=',
        value: '@',
        oneWay: '<',
        twoWay: '=',
        callback: '&'
    },
    template: myTemplate,
    controller: MyComponentController,
    controllerAs: 'vm'
};

myapp.component('myComponent', myComponent);

MyComponentController.$inject = ['$http'];
function MyComponentController($http) {
    this.foo = 'bar';
}

注意，使用 component() 函數來建立元件時：

• 必然以 restrict: 'E' 的形式建立，也就是只能建立 element 形式的元件，
• 必然以 scope: {} 的形式建立，也就是建立 "isolated scope"，不會繼承 parent scope。因此，若需要外部 scope 的資料，必須明確在 bindings 中定義屬性，並在使用 element tag 時傳入。
• 承上，在 component() 函數中，已使用 bindings 取代 scope 及在 1.3 ~ 1.4 之間引入的 bindToController 屬性。所以在 component() 函數中，scope 及 bindToController 屬性無效，也不應再使用。
• 如果你沒有自行指定 controllerAs，則會自動幫你指定為 $ctrl，也就是說，強迫必須使用 controllerAs 語法 (參考後面『永遠使用 "controllerAs" 語法』)。

另外，

• 由於 component() 函數只能用來建立 element 元件，如果元件必須同時或者只支援其他類型，譬如 attribute 形式，則必須使用 directive() 函數定義。
• 上面使用 require() 引入 template 檔案的作法，是採用 Webpack 的作法。實務上可以直接使用 templateUrl 指定外部檔案, 或直接以內聯的形式定義 template 內容。
• 推薦像上面這樣，將 myComponent 的設定獨立定義，甚至獨立為一個檔案，這樣將來要移轉為 AngularJS 2.0 元件會比較方便。
• 將 controller 放在後面獨立定義，並以 constructor 的形式，開頭名稱大寫，是 John Papa 推薦的作法。

最後，再提醒一下，定義元件時，使用 myComponent 名稱，這名稱就稱為該元件的 "directive name"。首字小寫，這是 AngularJS 定義元件的推薦慣例。(當作是定義 instance 變數，所以小寫開頭。)
而在 html 中使用時，則必須使用 my-component，這稱為該元件的 "tag name"。全部小寫，以 - 分隔單字，雖然 HTML 不區分大小寫，但是使用全小寫是推薦的慣例。
而 controller 的名稱為 MyComponent，因為它是一個 constructor。首字大寫，表示這是一個 class，這是 JavaScript 的慣例。

一旦定義好 component，就可以如下使用：

在 markup 中使用

1
2
3

<body ng-app="myApp">
    <my-component foo="bar"></my-component>
</body>

在路由中使用

1
2
3
4

$routeProvider.
  when('/phones', {
    template: '<my-component foo="bar"></my-component>'
  });

好處如下：

• 完全封裝，不須再擔心 controller 與 template 不一致，
• 需要的屬性可以由外部以偏好的方式，以 expression 的形式指定，傳入的是計算後的值，元件內部不再依賴於外部的特定屬性名稱，
• 如果需要處理事件，也可以在 bindings 中以 eventName: '&' 的方式定義，同樣由外部以偏好的方式指定，元件不需要依賴於外部 scope 的特定方法名稱，
• 因為是 "isolated scope"，所以不必擔心 scope 之間的資料存取、覆蓋、同步問題。

Refactoring Angular Apps to Component Style 這篇文章詳細介紹各種將 controller 改用 component 的形式撰寫的步驟，相當值得一讀，強烈推薦。

使用 component() 定義 element 元件；使用 directive() 定義 attribute directive

建議只要是 element 形式的 directive，都使用 component() 函數來建立。其它情況則使用 directive() 函數。這裡一併列出建議的 element 元件 及 attribute directive 的參考寫法，做為對照。

1. 定義 component / element directive：

   1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18

   var myTemplate = '<div></div>'; var myComponent = { bindings: { value: '@', oneWay: '<', twoWay: '=', callback: '&' }, template: myTemplate, controller: MyComponentController, controllerAs: 'vm' }; app.component('myComponent', myComponent); MyComponentController.$inject = ['$http']; function MyComponentController($http) { }

2. 定義 attribute directive：

   1 2 3 4 5 6 7 8 9 10 11 12 13 14 15

   var myDirective = { restrict: 'A', scope: { value: '@', oneWay: '<', twoWay: '=', callback: '&' }, link: myDirectiveLinker }; app.directive('myDirective', myDirective); function myDirectiveLinker(scope, element, attrs) { }

永遠使用 isolated scope

出處：Always use an isolated scope

首先，你只有在定義 directive 時，才能指定 scope 種類 (註)。而 scope 有三種：

1. isolated scope: scope: {}

   建立一個獨立的 scope。要交換的資料必須明確定義。

2. new scope: scope: true

   建立新的 child scope，並且繼承 parent scope。

3. no scope: scope: false

   不建立 scope，直接使用 parent scope。

這有什麼問題呢？

• 既然 directive 就是 element 和 attribute (還有 class 和 comment 但是官方不建議使用)，讓它們可以直接存取父元件的資料不是很奇怪嗎？標準 html 的標籤不都是要自行指定屬性？

• 繼承了 parent scope，也就意謂著依賴於 parent scope，因此元件的可重用性就大幅降低。

• 因為 scope 是以類似 prototpye 的方式繼承，親子 scope 之間會發生屬性遮蔽問題 (請參考下一段說明)。

因此，強烈建議一律使用 "isolated scope"，不要使用另外兩種。當需要 parent scope 資料時，請明確定義屬性，並由 parent scope 指定傳入。

註：即使在 ng-controller 中使用 "controllerAs" 語法，也只是幫你以指定的名稱建立一個包裹物件而已，scope 類型仍然是 "new scope"，並無法指定 scope 類型。這也是一個不應該使用 ng-controller 的好理由。

永遠將屬性資料以物件加以包裹，或使用 "controllerAs" 語法

出處：

• Only ever bind to sub-properties of an object
• Exploring Angular 1.3: Binding to Directive Controllers

只要遵循上面『盡可能元件化 (使用 component 取代 ng-controller)』的原則，即自動 (強制) 獲得使用 "controllerAs" 及 "isolated scope" 的好處。

如果你不需要知道 AngularJS 過去最被詬病的 scope 黑暗歷史，或者，你已經了解什麼是 "controllerAs"，可以放心跳過這一段。

像這樣的寫法：

1

<input type="text" ng-model="username" />

其中 username 將直接繫結到上層 scope 的 username 屬性。這裡的關鍵字是『上層 scope』。

這有什麼問題呢？

• 由於某些 AngularJS 的 directive，譬如 ngIf，會建立新的 scope，也就是前面的提到的 "new scope"，注意 "new scope" 會繼承到 parent scope。意思是說，你的 binding 將會根據你的 element 所在的位置，因而繼承了你沒有預料到的『上層 scope』，因此而可能有不同的行為。

• 其次，由於屬性是以 prototype 的方式繼承，一旦 child scope 建立了同名的屬性，就同時遮蔽了 parent scope 的同名屬性。使得原本希望直接更新 parent scope 屬性的意圖落空。

注意，以下範例為了清楚起見，直接使用 ng-controller 建立新的 scope，實務上仍然建議『盡可能元件化 (使用 component 取代 ng-controller)』。

See the Pen AngularJS Scope Problem by amobiz (@amobiz) on CodePen.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

<div ng-app="app">
    <h4>Form 1</h4>
    <form ng-controller="ParentController">
        <label>Username: </label>{{username}}<br>
        <input type="text" ng-model="username" />
    </form>

    <h4>Form 2</h4>
    <form ng-controller="ParentController">
        <label>Username: </label>{{username}}<br>
        <div ng-if="!registered">
            <input type="text" ng-model="username" />
        </div>
    </form>
</div>

1
2
3
4
5
6

angular.module('app', [])
.controller('ParentController', ParentController)

function ParentController($scope) {
    $scope.username = 'My Name';
}

注意上面 Form 2，當你輸入資料時，ParentController 的 username 並不會同步更新。

為了避開巢狀 scope 的 prototype properties 繼承問題，可以在 parent scope 中以物件的形式將值包裝起來。
這樣，在 child scope 中，只要永遠不直接對 scope 設定屬性，就不用擔心 scope 屬性遮蔽問題。而透過該物件存取其屬性，就能自由與 parent scope 交換存取資料。

See the Pen AngularJS Scope via Object by amobiz (@amobiz) on CodePen.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

<div ng-app="app">
    <h4>Form 1</h4>
    <form ng-controller="ParentController">
        <label>Username: </label>{{vm.username}}<br>
        <input type="text" ng-model="vm.username" />
    </form>

    <h4>Form 2</h4>
    <form ng-controller="ParentController">
        <label>Username: </label>{{vm.username}}<br>
        <div ng-if="!vm.registered">
            <input type="text" ng-model="vm.username" />
        </div>
    </form>
</div>

1
2
3
4
5
6
7
8
9

angular.module('app', [])
.controller('ParentController', ParentController)

function ParentController($scope) {
    var vm = {};
    vm.username = 'My Name';

    $scope.vm = vm;
}

注意 vm 在這裡是可以任意自訂的名稱，取名 vm 是 "View Model" 的意思。

指定 "controllerAs" 之後，controller 中的 this 與 $scope 有何不同？

由於上面的作法，可以優雅地解決 scope 遮蔽問題，AngularJS 1.2 針對這個作法，新增了 "controllerAs" 語法。

首先，不推薦，但你可以使用 ng-controller="MyController as $ctrl" 的方式啟用這個功能；
再者，你可以在 directive() 及 component() 函數，使用 controller: 'MyController as $ctrl' 的方式啟用，或者以 controllerAs: '$ctrl' 的方式另外指定。

"ControllerAs" 語法，只是上面介紹的作法的語法蜜糖，當你寫 controller as $ctrl 時，AngularJS 在背後所做的事，基本上就跟上面一樣。

細節是這樣的，首先，記住 controller 函數其實是一個 constructor，AngularJS 會以 new 操作子呼叫你的 controller 函數，以建立一個新的物件，然後，AngularJS 會自動幫你在 $scope 中，以 $ctrl 為屬性名稱，將該物件指定給 $scope。直接以程式展示的話，大概是像這樣：

1
2
3
4
5
6
7

function MyController() {
    this.username = 'My Name';
}

function $$MyControllerWrapper$$($scope) {
    $scope.$ctrl = new MyController();
}

所以，從另一個角度看，在上面的 controller 中的 this，只是一個普通的 JavaScript 物件，當然也就沒有 $scope 的功能。這就解釋了為什麼使用了 "controllerAs" 語法後，就無法在 controller 中使用 $scope 的功能。因此，如果在 controller 中需要 $scope 功能的話，就必須再另外透過 DI 注入 $scope 物件，就像這樣：

1
2
3
4
5
6
7
8

MyController.$inject = ['$scope'];
function MyController($scope) {
    this.username = 'My Name';

    $scope.$watch('registered', function (newValue, oldValue) {
        // ...
    });
}

參考資料 / 延伸閱讀

這一篇解釋得很詳細：

AngularJS: "Controller as" or "$scope"?

這一篇說明為何 1.3 需要引進 bindToController，以及後來在 1.4 的演進：

Exploring Angular 1.3: Binding to Directive Controllers。

John Papa 是一直大力推廣 "controllerAs" 語法的人：

Do You Like Your Angular Controllers with or without Sugar?
AngularJS's Controller As and the vm Variable

然後，AngularJS 1.5 引進了上面介紹的 component() 函數，同時，似乎是為了有所區別，AngularJS team 決定 (沒有找到相關資料，請看下面的推論) 引入新的 bindings 屬性，用來完全取代 scope 及 bindToController。我想這應該是為了避免使用者誤用，而造成模稜兩可的狀況：

1. 退回到 1.4，強制定義 scope: {}，而使用 bindToController 定義屬性

   因為在 1.4 時，bindToController 屬性就可以直接定義屬性，其意義與 bindings 完全相同，只不過並未強制 scope: {} 的定義。若這麼做的話，等於是期望使用者這樣定義：

   1 2 3 4 5 6

   { scope: {}, bindToController: { attribute: '=' } }

   但是若使用者卻使用 1.3 的語法：

   1 2 3 4 5 6

   { scope: { attribute: '=' }, bindToController: true }

   那麼，哪個屬性有效呢？記住，我們已經強制定義 scope: {}，所以這裡的 scope 定義無效；而我們期望定義為 hash object 的 bindToController，在這裡當然也找不到正確的屬性定義。

2. 退回到 1.3，仍然使用 scope 定義屬性，強制 bindToController: true 屬性。

   也就是說，期望使用者這樣定義：

   1 2 3 4 5 6

   { scope: { attribute: '=' }, bindToController: true }

   但是若使用者卻使用 1.4 的功能：

   1 2 3 4 5 6

   { scope: {}, bindToController: { attribute: '=' } }

   那麼，又是哪個屬性有效呢？同樣地，我們已經強制定義 bindToController: true，所以這裡的 bindToController 定義無效；而我們期望定義為 hash object 的 scope，在這裡當然也找不到正確的屬性定義。

所以，由此推論，AngularJS team 為了避免上述兩種模稜兩可的狀況，而決定乾脆同時忽略 scope 和 bindToController 的使用者定義，分別強制其值為 {} 及 true，而另外使用 bindings 來定義屬性。

雖然不確定理由是否如上述推論，但同時有三個屬性 (scope, bindToController, bindings)，提供一樣的功能，顯然又是一個為了向後相容，而疊床架屋的例子，雖然解決了問題，但同時也造成了更多混淆。

少用 $rootScope

出處：Limit your use of $rootScope

應該不須贅言，$rootScope 基本上就等於 global。

盡量讓狀態靠近使用的元件

出處：Keep your state as close as possible to the components which need it.

大部分情況下，你的元件應該能自給自足，或者，頂多需要由父元件提供資料。有些時候，你可能需要在多個元件之間共用資料。除非你是在開發通用的元件，譬如 Tab / TabPanel，這時你可能要考慮使用 require 屬性。否則，開發一般應用程式時，應該盡量在最靠近它們的共同父元件上提供共用的資料。

index.html

1
2
3

<body ng-app="app">
    <parent></parent>
</body>

parent.js

1
2
3
4
5
6
7
8
9
10
11
12
13

var template = [
    '<child-one foo="vm.bar"></child-one>',
    '<child-two baz="vm.bar"></child-two>'
].join('');
app.component('parent', {
    template: template,
    controller: ParentController,
    controllerAs: 'vm'
});

function ParentController() {
    this.bar = 'woo';
}

child-one.js

1
2
3
4
5
6
7
8
9
10
11

app.component('childOne', {
    bindings: {
        foo: '='
    },
    controller: ChildOneController,
    controllerAs: 'vm'
});

function ChildOneController() {
    console.log(this.foo);
}

child-two.js

1
2
3
4
5
6
7
8
9
10
11

app.component('childTwo', {
    bindings: {
        baz: '='
    },
    controller: ChildTwoController,
    controllerAs: 'vm'
});

function ChildTwoController() {
    console.log(this.baz);
}

就使用 factory() 函數 (忘記 service() 和 provider() 吧)

出處：Forget about services and providers

直接先講結論：

在 AngularJS 中，能夠透過 DI 注入使用的，都是服務。

一般常在爭論的，所謂 factory, service 及 provider，其實根本都不是真正的主體，它們都只是用來建立服務的方法。

正確的說，我們透過 factory(), service(), provider()，甚至 constant(), value() 這些方法，建立服務。而不論是用哪一個方法建立的服務，它們本質上完全相同，唯一的不同就只有建立的形式不同。

爭論什麼是 factory, service 及 provider，只是讓問題失焦。甚至於，我主張，不應該說『一個 factory』，而應該這麼說：『一個使用 factory() 函數建立的服務』。

如果你了解它們背後的實作方式，全部都是基於同一個其界面具有 $get() 函數的物件，你就可以根據需要，自在地採用適合你的情境的『形式』來建立服務；如果還是不了解，就根據本項建議，全部採用 factory() 來建立服務。

詳細說明

許多人都建議只使用 factory，主要理由如下：

1. 不管是 factory, service 或 provider，其本質上都相同，背後的實作都是 provider，
2. 它們全都是 singleton，
3. provider 的存在，只是為了提供更改預設值的初始化功能，但其實有許多方式可以做到，並不是非 provider 不可，
4. factory 比 service 有彈性。

我認為以上的說法還不夠精準，最好改為：

以下透過模擬它們的實作方式，稍微說明一下它們的差異。簡單地說，它們的差別可以用下面這段虛擬碼表達，為了簡單起見，dependency injection 處理的部份完全不列入。

首先，我們建立的 module，具有 (自動注入) 下列 $provide 提供的 factory(), service() 及 provider() 等函數 (其它略)：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

var $provide = {
    provider: provider,
    factory: factory,
    service: service
};

var $$providerRegistry = {};
var $$serviceRegistry = {};

function provider(serviceName, ProviderConstructor) {
    var serviceProvider = new ProviderConstructor();
    var serviceProviderName = serviceName + 'Provider';
    $$providerRegistry[ serviceProviderName ] = serviceProvider;

    var service = serviceProvider.$get();
    $$serviceRegistry[ serviceName ] = service;
}

function factory(serviceName, factoryFunction) {
    return provider(serviceName, function ProviderConstructor() {
        this.$get = factoryFunction;
    });
}

function service(serviceName, ServiceConstructor) {
    return factory(serviceName, function factoryFunction() {
        return new ServiceConstructor();
    });
}

其中 provider() 函數，做了這些事：

1. 以 new 運算子呼叫我們提供的 ProviderConstructor() 建構子，建立一個物件，這個物件也就是所謂的 Provider 服務，
2. 將此 Provider 服務物件以 serviceName + 'Provider' 的名稱，註冊為一個服務，這個服務將只能透過 config() 函數注入使用，
3. 呼叫此物件的 $get() 方法，此方法回傳的物件才是真正的服務物件，
4. 將服務物件以我們提供的 serviceName 為名稱，註冊為一個服務，這個服務將能夠在 run(), factory(), service(), provider(), controller(), directive() ... 等函數，以及任意建構子中注入使用。
5. 對每個服務而言，上面的過程，在整個應用程式生命週期中，只會執行一次。

而 factory() 函數，則是:

1. 建立一個 ProviderConstructor() 建構子，以該建構子做為參數呼叫上面的 provider() 函數，
2. provider() 函數以 new 運算子呼叫該 ProviderConstructor() 建構子時，將建立一個具有 $get() 方法的物件，該 $get() 方法直接被設定為我們傳入的 factoryFunction() 函數，因此呼叫 $get() 方法，即等於呼叫 factoryFunction() 函數，
3. 根據上面 provider() 函數的說明， ProviderConstructor() 建構子建立的物件，將被以 serviceName + 'Provider' 的名稱，註冊為一個所謂的 Provider 服務，
4. 根據上面 provider() 函數的說明，$get() 方法被呼叫，於是 factoryFunction() 函數回傳的任意值，將以我們提供的 serviceName 為名稱，註冊為一個服務，
5. 對每個服務而言，上面的過程，在整個應用程式生命週期中，只會執行一次。

而 service() 函數，則是:

1. 建立一個 factoryFunction() 函數，以該函數做為參數呼叫上面的 factory() 函數，
2. 在剛剛的 factoryFunction() 函數中，以 new 運算子呼叫傳入的 ServiceConstructor 建構子，建立服務物件，並將其返回，
3. 根據上面 factory() 函數的說明，factory() 函數又會轉呼叫 provider() 函數，
4. factoryFunction() 函數返回的物件，也就是 ServiceConstructor 建構子建立的物件，最終被以 serviceName 為名稱，註冊為服務，
5. 同時，會有一個僅包含 $get() 方法的物件，被以 serviceName + 'Provider' 的名稱，註冊為所謂的 Provider 服務。
6. 對每個服務而言，上面的過程，在整個應用程式生命週期中，只會執行一次。

解釋起來似乎很麻煩，但是直接看程式碼，其實真的沒有什麼驚奇的地方。

重點有兩個：

1. 每個服務，實際上都會伴隨著一個 Provider 服務，但只有透過 provider() 函數來建立，該 Provider 服務才有機會附加其他額外方法，而 factory() 和 service() 函數建立的 Provider 服務，都只會有 $get() 方法，
2. 它們全部都只有在註冊的時候，被執行唯一的一次，其結果就被儲存下來成為 singleton，再也沒有機會改變。
3. 不管在哪個模組註冊，註冊的服務都是全域共用的。

我過去一直以為 factory() 函數與 service() 函數的差異是，它每次被要求注入的時候都會執行一次，畢竟它的名稱叫做 "factory"，而且又只是個普通函數，所以我一直以為它就是 "factory method"，應該每次都回傳新的物件。但事實上它卻不是這樣被設計的，它跟 使用 service() 函數來建立服務完全一樣，我們傳入的 factory function 總是只被呼叫一次。

我從來沒有在任何一篇文章中看過有人強調這一點，最多只說它們全部都是 singleton。甚至大部分的文章在描述的時候，反而讓人誤以為每次都會呼叫 $get() 函數，譬如，在 Service vs Factory - Once and for all 這篇文章中這樣描述：

大概的意思就是說，每次我們向 injector 要求時，就會呼叫 provider 的 $get() 函數。

錯錯錯！ $get() 函數永遠只會被呼叫一次！

正是因為只會被呼叫一次，並且其結果被儲存下來，所以不論是透過 factory(), service() 或 provider() 函數，實際上建立的服務都是 singleton，建立之後的行為完全一樣，它們之間真正的差別就是建立的形式不同。

AngularJS team 真的是把一件簡單的事情極度複雜化了，而且明明同樣都是服務，卻用了三種不同的方式來建立，又偏偏取了很不好的一組名稱，才會導致連他們自己人，都會在所謂的解惑文中，用不正確的方式描述其行為。

由下面的範例就可以看出來 (請打開 console 看 log)：

1. 雖然建立的是 personFactory，但是卻同時存在有 personFactoryProvider，
2. console.log 中，"personFactory begin" 與 "personFactory end" 各只出現一次，表示 factory 函數只被呼叫一次，
3. personFactory.rtti 的值，在兩個 controller 中相同，表示 personFactory 的確是同一個物件，
4. 由 PersonController1 透過 personFactory.defaults() 函數設定的值，在 PersonController2 可以看得到。

See the Pen Angular: factory function only got called once by amobiz (@amobiz) on CodePen.

了解背後的運作原理之後，再來看看實際上要建立服務時，我們如何透過 factory(), service() 或 provider() 函數來建立。

基本定義方式如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

angular.module('app', [])
.provider('myProvider', function ProviderConstructor() {
    this.$get = function getter() {
        return 'whatever';
    };
    this.config = function config(options) {
    };
}
.service('myService', function ServiceConstructor() {
    this.method = function () {
    };
}
.factory('myFactory', function factoryFunction() {
    return 'whatever';
};

雖然透過 provider() 函數建立服務的彈性最大，也能提供設定功能，但是如同前面的範例的 defaults() 函數，設定功能有很多方式可以達成，因此並沒有非使用 provider() 函數不可的理由。而 service() 函數由於強制必須提供 constructor，所以服務本身只能是物件類型，彈性上多少受到一些限制。基於這些理由，多數的人才會建議：一律使用 factory() 函數來建立服務。

使用 factory() 函數來建立服務的常見用法

回傳常數

1
2
3
4
5
6
7
8

.factory('pi', function () {
    return 3.14159;
};

use.$inject = ['pi'];
function use(pi) {
    var area = pi * this.radius * this.radius;
}

這個作法足以取代 constant(), .value()。

回傳服務物件

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39

app.factory('personFactory', personFactory);

function Person(name, attributes) {
    this.name = name;
    this.attributes = attributes;
}

Person.prototype.eat = function (what) {
};

function personFactory() {
    var defaults = {
        gender: 'unspecified'
    };

    return {
        setDefaults: function (options) {
            Object.assign(defaults, options);
        },
        create: function (name) {
            return new Person(name, Object.assign({}, defaults));
        }
    };
}

app.run(run)
.controller('PersonController', PersonController);

run.$inject = ['personFactory'];
function run(personFactory) {
    personFactory.setDefault({
        country: 'Taiwan'
    });
}

PersonController.$inject = ['personFactory'];
function PersonController(personFactory) {
    var person = personFactory.create('John');
}

可以看到：

• 可以提供 factory method，如上面的 create() 函數。最重要的是，它能夠接受參數。
• 可以提供 config 功能，如上面的 setDefaults() 函數，足以取代 provider。

回傳建構子

老實說，我比較不建議這個作法。使用 DI，就是不希望依賴於實作，不希望由 client 自行建構依賴物件。使用 DI 應該直接取得立即可用的物件或服務，應該依賴於其界面，而不是其實作。

1
2
3
4
5
6
7
8
9
10
11
12
13
14

.factory('Person', function () {
    function Person() {
    }

    Person.prototype.eat = function (what) {
    };

    return Person;
}

use.$inject = ['Person'];
function use(Person) {
    var person = new Person();
}

不要使用 module.config

出處：Forget about module.config

大多數時候，module.run() 函數即可勝任模組的初始化工作，沒有必要非在 module.config() 中進行初始化。許多時候，基於封裝原則，甚至於應該在元件中進行初始化。

唯一的例外，就是必須使用到 AngularJS 或第三方程式庫提供的 Provider 的時候，譬如 $routeProvider。這是因為 AngularJS 做了一個很不好的決定：強制 Provider 只能在 module.config() 中使用。你在開發自己的應用程式時，實在沒有必要跟著這麼做。

謹慎使用 scope 事件

出處：Be careful with event publishing and listening

透過 $rootScope 或 $scope 發佈事件，應該是針對不特定受眾所為，通常是設計 API 時才需要考慮。多數時候，你只是在開發應用程式，所有的元件都在你的掌握之中，你可以透過元件之間的屬性，或 callback 函數來傳遞資料。如果是服務，則應該考慮使用 Promise。如果隨意濫用 $rootScope 或 $scope 發佈事件，小心導致程式難以除錯的風險。

善加使用 $exceptionHandler

出處：Take advantage of $exceptionHandler

你的程式中未捕獲的 exception 都會丟給 $exceptionHandler 這個服務處理，這個服務預設的行為是輸出 log。你可以定義自己的 $exceptionHandler 服務，這將覆蓋原本的服務，讓你有機會自行處理錯誤：也許是上傳錯誤到後端伺服器進行記錄等等。

1
2
3
4
5
6

angular.module('exceptionOverride', []).factory('$exceptionHandler', function () {
    return function(exception, cause) {
        exception.message += ' (caused by "' + cause + '")';
        throw exception;
    };
});

找到合適的方法上傳 log 到後端伺服器

出處：Find a good way to publish logs to the server side

SPA 應用程式是在使用者的瀏覽器中執行，如果沒有適當地記錄 log 訊息，根本無從得知在使用者的瀏覽器中到底發生了什麼事。

最底限至少應該在應用程式發生錯誤時，輸出錯誤訊息，請求使用者幫忙回報。若經過使用者同意，也可以考慮記錄整個執行過程，排除敏感資料，上傳到後端伺服器加以記錄分析。

上傳的時候應該盡力減少發送次數及流量，並且務必做好加密的動作。

另外，可以考慮使用商業化的產品，譬如 Loggy、Paper Trail 等。

使用 angular-ui-router

出處：Use angular-ui-router

如果你的服務 API 遵循 RESTful 原則，你可能會有許多 resources 具有 sub-resources，而 RESTful 要求每個 resource 應該要有唯一的 URL。然而 AngularJS 內建的 ngRoute 不支援巢狀路由，因此並不算 RESTful 友好。

稍具規模，支援 RESTful 的 AngularJS 1.X 應用程式，都應該考慮使用 ui-router，甚至可以考慮搭配 ui-router-extras，以提供更多進階功能。

為什麼不使用新的 AngularJS 2.0 的 ngComponentRouter？

目前不推薦 ngComponentRouter 的主要原因，是因為：

1. 尚未正式發佈

   ngComponentRouter 原本計畫要隨同在 AngularJS 1.4 發佈，但是現在已 1.5 卻還是沒有正式發佈，想必 AngularJS team 也還有其他考量。或許只是因為 AngularJS 2.0 尚未正式發佈，而針對 AngularJS 1.x 的規格也仍然還在變動。

2. 目前的參考文件比較缺乏。

   最新的文件可以參考 Component Router。其它目前在網路上可以找到的針對 AngularJS 1.x 的文章幾乎全部都已經過時，都是還是使用 controller 的方式。建議可以參考 StackOverflow 上 Angular 1.5 and new Component Router 的回答。或直接參考 ngComponentRouter 的 examples。另外，我也寫了一個 sample 可以參考：

See the Pen Angular 1.5 component router playground by amobiz (@amobiz) on CodePen.

小心使用 Promise 並且注意 AngularJS 對 Promise 錯誤的特殊處理

出處：Be careful with promises and error handling

首先，不論是透過 AngularJS 自己的 $q 提供的 Promise，或是標準的 Promise/A+，如果你沒有使用 catch() 捕捉錯誤，任何錯誤，包括 throw 的錯誤以及沒有 fulfilled 的錯誤，都將無聲無息地被吃掉。

再來，除非你是透過 return $q.reject(err) 回傳錯誤，否則任何其它被 throw 出來的錯誤，即使你已經使用 catch() 捕捉了，它們都還是會被丟到前面提到的 $exceptionHandler 服務。這就面臨了兩難的困境。意謂著，如果你使用 catch() 捕捉錯誤，同時也使用 $exceptionHandler 服務處理未捕捉的錯誤，結果是同一個錯誤你將處理兩次。

為了避免這個問題，可以借用 Java 的 checked exception 的概念：屬於你的設計中，明確會丟出來的錯誤，把它們當作是 checked exception，一律使用 $q.reject(err) 來處理，這樣它們就不會進入到 $exceptionHandler 服務；至於哪些你沒有預料到，或者是程式設計錯誤造成的錯誤，則把它們當作是 unchecked exception，讓它們由 $exceptionHandler 服務來把捕捉。

避免使用延遲載入

出處：Try to avoid lazy loading

AngularJS 1.x 的模組，只能在啟動階段定義，使用任何的 hack，即使是透過路由來做延遲載入，都無可避免的有其缺陷，更不用說這會無謂地增加程式的複雜度。

了解 $digest 循環的判斷方式

出處：Be careful with the digest cycle

在 AngularJS 1.x 中，所謂的雙向資料繫結 (two way data binding)，是靠著不斷地檢查 scope 中的變數是否有變動，而在變動時做出反應：更新畫面或根據使用者輸入更新 scope 資料。由於資料之間可能有關聯性，所以某些資料更新後，可能會導致其它資料也需要更新，也就是發生所謂的漣漪效應。因此，AngularJS 會持續地進行檢查、更新，直到資料不再發生變動為止。如果資料持續不斷發生變動，則 10 次 $digest loop 之後，AngularJS 就會丟出 exception。

AngularJS 如何檢查資料是否發生異動？它並不是靠傳說中的 Object.observe()(註)，而是藉由儲存舊值，透過比對舊值與現值，來判斷是否發生異動。然而，這裡存在著一個陷阱：由於資料可以經由函數回傳，如果函數將資料包裹在物件或陣列中回傳，雖然就『值』本身來看，並沒有發生異動，實際的包裹物件已經不是同一個了。

1
2
3

$scope.foo = function () {
    return { bar: 'baz' };
};

JavaScript 並不像 Java 一樣，有所謂 equals() 和 hashCode() 方法，用來快速檢查兩個物件的『值』是否相等，也就是所謂的『等價』。因此，為了效率考量，AngularJS 並不會進行所謂 deepEqual() 檢查，而只是檢查物件是不是同一個 (位址相同)。由於每次要比對現值時，就會呼叫一次函數，而函數每次都會回傳一個新的包裹物件，因此每次都判定為資料發生異動，於是超過 10 次之後，就丟出錯誤了。

因此，上面的例子比較好的作法，應該像這樣：

1
2
3
4
5

var foo = { bar: 'baz' };

$scope.foo = function () {
    return foo;
};

這樣每次被呼叫時，回傳的都是同一個物件，AngularJS 就不會誤判了。

註：Object.observe() 提案已經於 2015 年 11 月撤銷，因此未來也不可能使用 Object.observe() 來檢查資料異動。

結論

AngularJS 可以算是最早引入自訂 html 元件概念的 framework，只是早期的推廣，強調 ng-controller 的使用方便性，導致許許多多程式將業務邏輯與畫面呈現全部混在 controller 中。雖然 AngularJS 2.0 發佈在即，也更趨近於 Web Component 標準，舊有使用 AngularJS 1.x 的應用程式，只要嚴守元件化的原則，仍然可以寫出相當容易維護的程式，甚至於更有利於將來移植到 AngularJS 2.0。

以上整理，已盡力將參考資料完整列出，惟個人學識有限，如有謬誤或不足之處，歡迎補正，謝謝。

前一陣子，left-pad 的作者，因為不滿 npmjs.com 屈從財團的壓力，未經作者同意就擅自移轉所有權，因此憤而將全部模組從 npm 下架，而導致眾多知名模組受到波及。此事件引起了廣泛的反思。

然而，漸漸出現一種聲音，開始呼籲大家不要使用 open source、要盡量自己寫程式碼，不要依賴別人的模組，就像這篇文章：『NPM & left-pad: Have We Forgotten How To Program?』(中譯)。更有甚者，連『懂得怎麼寫程式之前，別去玩 node.js 好嗎？』這樣的話都出來了。

走火入魔？

首先，該文作者提到，整個事件的源頭，left-pad 只有 11 個星星 (話說現在已經有 710 顆星星)，只有 11 行程式碼。整個產業卻因 11 行程式碼而崩潰實在不可思議。

我還是要說，造成崩潰的並不是這 11 行程式碼，這 11 行程式碼並沒有造成任何程式執行錯誤，這 11 行程式碼沒有品質問題；造成崩潰的是這 11 行程式碼，掌握在不遵守 open source 遊戲規則的 npmjs.com 手中；造成崩潰的是，整個產業的運作，竟是依賴在這樣一家公司上。(說的有點重，但是實在是無法接受傾斜於財團而欺壓獨立開發者的行為。)

舉 Internet 域名為例，對於那些域名已經被搶註冊的大企業，取回域名的最快手段，就是透過收購的方式，打官司也可行，但曠日費時，而且不保證一定勝訴。同樣的邏輯，open source 軟體名稱，憑什麼企業就有權強制他人不許用？

Npm 事件的問題，是整個 ecosystem 『把持』在少數特定企業而衍生的危機，解法應該是盡可能的分散化，不要依賴於『中央集權』。就像 Java 現在把持在 Oracle 手中，遲遲不肯實現 open source 的承諾而遭人唾棄一樣。

這跟 open source 如何演化，跟程式設計師會不會寫程式，根本毫無關係。

作者提到：

There’s a package called isArray that has 880,000 downloads a day, and 18 million downloads in February of 2016. It has 72 dependent NPM packages. Here’s its entire 1 line of code:
1
return toString.call(arr) == '[object Array]';

作者在文中就提到，依賴於 isArray() 的模組，有 72 個。只有 72 個相依性，竟然有人可以稱之為『瘋狂的引用他人的模組』、『走火入魔』。

模組下載數量怎麼算？

那『18 million downloads in February of 2016』又怎麼說呢，大家不是在『瘋狂下載』？

大家真的知道 npm 的 download 數怎麼計算的嗎？

以我的 globjoin 為例，只不過僥倖被 stylelint 一個模組引用，現在每個月都有超過三萬次下載，請問，有人瘋狂地引用我的模組嗎？沒有，只有一個 stylelint 引用！三萬次下載你以為就有三萬個不重複使用者嗎？也不是，每次模組更新，就會重新下載，合併計算。

作者舉的 isArray 例子，大家可以去看看它的相依模組，其中不乏像 browserify、buffer 這樣的重量級模組。我可以說，isArray() 的超高下載量，跟我的 globjoin 的現象相同 (當然等級不同)，只是被某些知名的模組引用了。並沒有人『瘋狂的引用他人的模組』，好嗎？！

至於另一個例子 is-positive-integer，『檢查一個整數是否是正數』這個模組的存在本身，的確符合作者的理論。但是由這個模組的實際下載量根本不高來看，更只能證明，顯然絕大多數的開發者並不會貿然使用毫無意義的模組。沒有人使用的模組，就算它依賴於兩萬個模組，影響也極有限。特地拿一個沒有人使用的模組來指責全體開發者，有何意義？

一部分要歸咎於歷史因素

至於像 isArray 這樣的函數的存在，正是因為過去並沒有原生的函數可以使用，而導致每個人都要自己寫一個系統本應該要有的功能。這一點在英文原文下面的討論，是一個攻防重點，大家不妨去看看。

回頭看看 isArray() 的實現：

1

return toString.call(arr) == '[object Array]'

沒錯，只有短短的一行。但是捫心自問，不參考任何文件、資料，你隨時都寫的出來嗎？
如果你每次又要再寫一遍的時候，都還需要翻找文件，這樣真的會比較快嗎？

再來談談封裝

如果程式中到處充滿 return toString.call(arr) == '[object Array]'，你就必須直接看到程式碼的細節，而無法像 Bob 大叔在『Clean Code』中所說的，程式碼應該要『讓名稱代表意圖』。於是，你還是會把它封裝成 isArray()。封裝之後，請問你會把它放在哪裡？

某個模組裡！

這麼一來，跟直接引用別人的模組，又有何不同，只不過是自己寫的就會比較好看？就不存在模組相依性問題？

不要忘了，別人還寫好了測試程式。

沒有測試程式的程式碼，就是『遺留程式碼』。

你為了不要『相依』別人的模組，自幹了自己的模組，然後不寫測試？好吧，你會寫測試，那麼，這就不是『一行程式碼』的問題了。從頭到尾，你只是在重複別人已經處理好的問題。

『Have We Forgotten How To Program?』

作者提到，一個簡單的『blank project template』就要引用 28,000 個檔案，這是不是太過複雜了？甚至於直接結論：

I get the impression that the NPM ecosystem participants have created a fetish for micro-packages.

『開發者有一種不良的、對微型模塊的熱衷。』

It feels to me as if the entire job of an NPM-participating developer is writing the smallest amount of code possible to string existing library calls together in order to create something new that functions uniquely for their personal or business need.

只想『拼拼湊湊、串起來交差』。

先不論這 28,000 個檔案，究竟實際被專案引用的有多少，而用來輔助專案開發的比例又有多少。如果一個專案實際上就是有這些需求，那麼這些檔案，不論改用何種方式撰寫，它們的複雜性並不會因此降低，並不是把 100 個函數，全部寫在一起，變成為一個函數，它就變得不複雜了；事實上剛好相反。

過去開發者不斷地重新發明輪子，而軟體專家則不斷地疾呼要 reuse。終於現在 JavaScript 社群蓬勃發展，大家支持 open source，信任 open source 反而變成『不良』的習慣？

『Functions Are Not Packages』

模組並不是這樣定義的。根據維基百科對『Modularity』的定義：

In software design, modularity refers to a logical partitioning of the "software design" that allows complex software to be manageable for the purpose of implementation and maintenance. The logic of partitioning may be based on related functions, implementation considerations, data links, or other criteria.

『在軟體設計中，模組化是指軟體設計的邏輯分割，以允許複雜的軟體，能夠以可管理的方式實作及維護。邏輯分割可能基於相關性、實作考量、資料連結、以及其它要素。』

要我說，任何具有獨立性、內聚性，可以管理的東西，都可以將它做成模組，哪怕只是提供一些常數。

『Do one thing and do it well』，『程式應該只關注一個目標，並儘可能把它做好。讓程式能夠互相協同工作。』稟持著 Unix 的設計哲學，node.js 社群也信奉這個原則，讓每個元件，做到最好，讓每個元件，能夠隨意組合使用。

『Third Party Problems』

There’s absolutely no guarantee that what someone else has written is correct, or even works well. Even if correct, is it the most optimal solution possible? At least when you write the code yourself, you can easily modify it to fix bugs and improve its efficiency. Not that there should be many bugs in 1 line functions.

沒有人強迫你用他們的模組，你要使用前，本應做好評估。甚至，如果你是 TDD 派，只要你的程式碼通過測試，就是該模組的功能符合你的需求的證明。更何況如果你對該模組有疑慮，大可以針對該模組撰寫測試來進行評估。『為什麼要幫別人寫測試？』你問。這一段程式你原本不是要自幹？難道自幹就不用寫測試？

至於，如何保證引用的模組，是『最有效率的解決方案』？好問題，你如何證明你自幹的程式碼，是『最有效率的解決方案』？

『至少我自己寫的程式碼，要怎麼改就可以怎麼改。』---- 你知道 open source 是什麼意思嗎？

Second, even if the package’s logic is correct, I can’t help but be amazed by the fact that developers are taking on dependencies for single line functions that they should be able to write with their eyes closed. In my opinion, if you cannot write a left-pad, is-positive-integer, or isArray function in 5 minutes flat (including the time you spend Googling), then you don’t actually know how to code.

我前面已經回答過了，忘記的話請自行回捲。

『Strive For Few Dependencies』

The more dependencies you take on, the more points of failure you have.

你自己寫的程式碼也是一樣，如果你不寫測試的話。

have you vetted any of the programmers who have written these functions that you depend on daily?

你每天吃進肚子裡的東西，穿在身上的衣服，出門開的車，住的房子，你有去審核評估過製作者嗎？

還是那句話，別人都已經攤開 source 給你看了，為什麼還偏偏要自己寫？你要不要相信這些程式碼，由測試決定！要是怕 npm 又出問題，不會把用到的模組都複製一份到 local repo，或是自己架個 server 嗎？

結論

作者其實只有一個重點：只有自己會寫程式，別人都是笨蛋都不會寫程式，所以不要相信別人寫的程式。即使別人寫的程式有嚴謹的測試，自己的卻沒有。一個開源社群的茁壯非常不容易，落井下石卻很簡單。將整個生態圈的蓬勃發展，形容為失控，而呼籲大家不要使用，根本就是因噎廢食。

社群已經出現反思的聲音，表示有人看到問題了，接下來自然就會有人提出解決辦法，這就是社群的運作法則。

在社群上有網友問到如何判斷 npmjs.com (或任意 open source 平台)上的套件，是否支援 node 或 browser，以下我將自己的經驗整理回答如下：

1. 首先當然就是先看 readme。通常 for browser 專用的套件，都會直接說明支援哪些瀏覽器，或在哪些瀏覽器測試過。另一個觀察的方式就是看它是否還可以使用 bower 安裝。

2. 再來，可以了解一下套件提供的功能，自行判斷一下這些功能的實作需要哪些平台功能的支援。由此大概判斷是 for node 或 for browser。

3. 另外，可以看套件本身支援哪種模組格式：

   • 採用 AMD 的話，通常作者只預期可以在 browser 上使用 (但實際上也許可以供 node 使用)，

   • 採用 UMD 的話，通常作者預期可以同時在 browser 和 node 上使用，

   • 採用 CommonJS 的話，通常作者只預期可以在 node 上使用 (但實際上也許可以供 browser 使用)，

   • 採用 ES2015 module 的話，就很難僅憑格式判斷。

     這一點因為現在 browserify 和 webpack 的流行，越來越多人只使用 CommonJS 或 ES2015 格式，所以只能做為參考。

4. 看一下相依的模組，看看有沒有熟悉的模組，這些模組是否只支援特定平台。

5. 掃一下 source code，看看有沒有平台相關的關鍵字，譬如 window, location (browser) 或 process, readFile (node) 之類。

6. 如果上面的方式都無法判斷的話，最快的方式就是直接寫測試程式，在目標平台上執行看看。

   因為至少有下面兩項因素會導致套件無法在 browser 上使用：

   • 套件本身或依賴的套件用到了 node 的專屬 API

     不過，類似 browserify 這樣的工具可以提供簡單的 node API 供 browser 下使用。

   • 用到了一般瀏覽器尚未支援的語言特性

     不過，一樣可以用 babel 等工具來克服。

     相反地，如果是要在 node 上使用，怕套件本身或依賴的套件用到了 browser host object 的話，真的只有直接測試比較快。

7. 最後的絕招，如果在所有的文件上都找不到的話，就直接向作者詢問吧。

   真的要先確認文件上找不到再發問，建議直接發 issue (標示為 Question)，因為其他使用者也可能會想知道答案。大部分的作者都會很熱心回答，不過有時候還是需要耐心等候。

最後，也歡迎大家到我的 npm 和 GitHub 針對專案提問或建議，能發 PR 當然是最好了。 <3

Google AMP 是用來加速顯示靜態網頁內容的技術。

主要由三個部份組成：AMP HTML (content), AMP JS (runtime), Google AMP Cache。

其中 AMP HTML 及 AMP JS 牽涉到內容的技術部份，可以一併來檢視。可以這麼說，為了達成瞬間顯示的效能，這兩項技術禁用一些容易阻塞瀏覽器的元素：

1. Style 必須內聯定義，以加速版面的計算。
2. 除了 AMP 元件必要的 JavaScript 之外，禁用其他 JavaScript。以避免諸如 document.write(), 或動態改變 class, style 等造成 reflow 的狀況。
3. 所有的外部資源均需要使用訂製的 AMP 元件來引用，以便由 AMP 管理資源的載入順序。主要是為了要讓網頁最前面可視區域能最優先顯示。
4. 所有的外部資源均需要設定尺寸大小，以便在資源實際載入前，先行計算 layout。讓畫面不會在資源載入後又重新計算。

第四點乍看之下似乎限制了 RWD 的可能性，但實際上所有的元素仍然可以使用 media query，根據不同媒體設定可視尺寸。
不過這同時也導致一個疑惑，既然元素實際顯示的大小，可以使用 media query 改變，若設定的大小與 media query 指定的不同，不是又會造成 reflow 嗎？

關於這部份的技術細節部份，留待下一篇文章，介紹如何開發符合 AMP 規格的頁面時，再詳細介紹。

至於 Google AMP Cache，則是利用 Google 無所不在的 CDN，讓內容可以就近取得，加速網頁的下載。

與 Apple News 及 Facebook Instant Articles 的比較

已經有許多文章對此進行了詳細的比較，總結來說，有以下的差異：

體驗不同

Apple News 及 Facebook Instant Articles 雖然也強調速度，但同時更強調他們的技術可以提昇互動與沈浸體驗 (interactive and immersive)；而 Google AMP 則並未著重在內容體驗上，而是主打呈現速度。

載具不同

Apple News 及 Facebook Instant Articles 都必須使用特定的 App 來存取；而 Google AMP 則是獨立的頁面，可以使用任何瀏覽程式閱讀。

驅動方式不同

Apple News 及 Facebook Instant Articles 基本上都是透過類似 RSS 的技術來遞送內容，而 Google AMP 則不預設任何方式來發現內容 (基本上 Google 當然是希望讀者透過自家的搜尋引擎)，並透過標準 HTTP/HTTP2 來傳送。

限制不同

Apple News 及 Facebook Instant Articles 基本上都是透過平台本身的技術來加速與強化內容，因此在格式上未做太多限制；而 Google AMP 由於不允許使用自訂 JavaScript，因此即便是廣告都必須符合 AMP 的規範，透過特定的 AMP 元件來引用。

簡單地說，Apple News 及 Facebook Instant Articles 算是 CMS 平台，而 Google AMP 則是格式。

有網友說，不像 Facebook 採用的是標準的 HTML 5，『AMP 並不是標準的 HTML, 應該算是 HTML 的延伸並有自己定義的 AMP 屬性』。事實上，AMP 採用的是 Web Components 技術，而 Web Components 又依賴於 Shadow DOM，雖然這些標準仍然處於草案階段，但是實際上已是相當成熟的技術，並且已有 polyfill 可以支援現有的主流瀏覽器。相反地，Facebook Instant Articles 必需以 Facebook App 閱覽，而不是瀏覽器，是否採用 HTML 5 的標準，根本已無關緊要。

另外，所謂 『Facebook Instant Articles 會自動幫內容出版商做格式轉換，這點 Google AMP 相較於 Facebook Instant Articles 略遜一籌。』

我想這一點恐怕是見仁見智。

首先，就誘因而言，若出版商不需做任何處理，就可以讓內容呈現在 Facebook Instant Articles 上，出版商的接受度當然是會提高。但關鍵是，Facebook Instant Articles 並未公佈技術細節，出版商並沒有最終內容呈現的控制權，你無法控制內容最終呈現在讀者面前的樣貌，甚至於部份內容 (因為即時顯示的需要) 被移除了，你完全無權置喙。

相對地，Google AMP 是 Open Source，所有的技術公開，除了 WordPress 已經支援 AMP，毫無疑問，很快地就會有大量的工具出爐，協助出版商轉換內容。無論是否透過工具自動轉換，出版商對於最終內容的呈現，擁有完整的控制權。

結論

自從首度發布，可以看到 AMP components 的數量不斷成長，也就是說，AMP 頁面可以承載的內容，也越來越豐富了。可以這麼說，AMP 是一個不斷發展，充滿生命力的技術。當然，這還是要歸功於 Open Source 的力量。

參考資料

• Accelerated Mobile Pages Project
• Turn Your AMP Up To 11: Everything You Need To Know About Google’s Accelerated Mobile Pages
• Instant Articles
• Instant Articles Frequently Asked Questions
• WordPress Sites Now Support Google’s AMP To Make Mobile Pages Load Much Faster
• 最近幾則跟數位出版格式有關的新聞

使用 Atom 編輯器，安裝上 linter-eslint 外掛，再加上一個現成的 ESLint 範本，就可以無痛投入到 ESLint 的懷抱了。

轉移到 ESLint

老實說，很慶幸我恰巧選擇了使用 Atom 編輯器，及 linter-eslint package 外掛來進行轉換工作，整個過程輕鬆愉快，一個晚上，就把所有的專案都移轉到 ESLint 下了。(其實不一定要 Atom，任何可以支援 linter-eslint 的編輯器都可以。)

我的作法如下：

1. 安裝 Atom
   安裝後，執行起來。

2. 安裝 linter-eslint

   1. 點選 Edit / Preferences 選單，
   2. 點選 Install 標籤，
   3. 在 Search packages 輸入框中輸入 linter-eslint，
   4. 按下右邊的 Package 按鈕，
   5. 找到之後，按下 Install 按鈕。它會自動安裝相依的 linter 模組，
   6. 重新啟動 Atom。

3. 找一個現成的規則檔做為起點
   最好是包含完整規則的範本，譬如這個，直接放到專案根目錄下，就可以開始移轉了。

4. 修正錯誤
   打開專案目錄，開啟程式碼，根據發生的錯誤，依自己的喜好，或所屬公司、組織的標準， 決定處理方式：

   • 關閉規則
   • 調整規則
   • 修正程式碼

5. 修正所有的專案

   1. 針對每個專案，複製上個步驟所修正的最新規則檔，重複步驟 4。
   2. 將最後完成的專案的規則檔，複製到所有修正過的專案下，重複步驟 4，確認這個規則檔適用於所有的專案。若不適用於所有的專案，則可以考慮在個別專案 source 目錄下，另增一個只適用於個別專案的規則檔，或是只針對特定檔案以 directives 的形式設定。

6. 把最終的規則檔，放到範本專案中，讓未來的新專案可以一體適用。

借助 linter-eslint 查詢錯誤規則

linter-eslint 其實是 linter 的 plugin，而 linter 的界面做的相當好：

1. 在編輯器中直接強調錯誤的程式碼，以及違反的規則名稱
   到底是那一段程式碼發生錯誤，以及違反了那一條規則，一目了然。

2. 在下方的錯誤列表中，可以使用滑鼠圈選文字的方式，複製錯誤規則名稱
   如果懶的自己打規則名稱，或者怕打錯，還可以直接複製，然後到網站上查詢。

這一點是我覺得 ESLint 這麼好用的最重要原因。所有的規則，一一對應，沒有模糊不清的地方。你只要根據規則名稱，到 Rules 搜尋一下，就可以找到對應的說明，然後就可以判斷自己要不要遵守這條規則，或是根據自己的喜好或習慣，開關或調整規則的選項。

ESLint 超簡單入門

ESLint 完全可以自行決定是否套用特定規則，以及套用到何種程度。

1. 配置規則可以使用下列各種方式：

1. 直接以 directives 的形式寫在檔案中。只對該檔案生效，並且覆蓋其他方式的配置。同時

2. 以 .eslintrc.* 檔案的方式獨立配置。對該目錄及所有子目錄的檔案生效；每個子目錄都可以有自己的 .eslintrc.* 檔案配置，並且覆蓋其父目錄的配置。注意，繼承規則時，會一路往磁碟的根目錄查詢規則，任何目錄若不想繼承其父目錄的規則，可以使用 "root": true 加以阻絕。最後

3. 如果是以 npm 管理模組，可以直接在 pacakge.json 中的 "eslintConfig" 區段直接配置。(以重複使用的角度，我個人不建議使用這種方式。)

2. 支援 ES2015 及 JSX 語法規則

可以在規則檔中以 "ecmaFeatures" 區塊，指定要套用那些語法規則。(文件中沒有提到如何以 directives 的方式在檔案中指定。不過我想最好還是整個專案採用一致的標準會比較好。)

3. 指定可執行環境

以 /* eslint-env node, mocha */ 或在配置檔中以 "env" 區塊指定模組或應用程式的可執行環境，譬如 browser, es6, node, amd, mocha 及 jasmine 等。ESLint 將假設這些環境的 global 變數的存在，而不會報告錯誤：『使用未定義的變數』。譬如：

1
2
3
4
5
6

{
    "env": {
        "browser": true,
        "node": true
    }
}

4. 自行指定既存的 global 變數

如果某些程式庫仍使用 global 變數的方式匯出功能，則必須以 /* global angular, bootstrap */ (注意沒有 s，這是為了與 JSLint/JSHit 相容。其實我是覺得可以 globals 和 global 兩種都支援)。或在配置檔中以 "globals" 區塊加以指定，以免報告錯誤。譬如：

1
2
3
4
5
6

{
    "globals": {
        "angular": false,
        "bootstrap": true
    }
}

其中 true 代表該 global 變數可以被覆寫。

5. 支援外掛

外掛必須先以 npm 安裝，然後以 "plugins" 區塊指定要使用的外掛名稱，外掛名稱如果以 eslint-plugin- 開頭，最好省略不寫 eslint-plugin- 前置名稱 (配置外掛選項時會用到)。譬如：

1
2
3
4
5
6

{
    "plugins": [
        "plugin1",
        "eslint-plugin-plugin2"
    ]
}

6. 可以關閉或調整規則

規則的 directives 格式完整形式如下：

1

/ eslint rule-name: [severity, options ...], "plugin-name/rule-name": [severity, options ...] /

若以規則檔指定，則以 "rules" 區指定規則。規則的 JSON 格式完整形式如下：

1
2

"rule-name": [severity, options ...],
"plugin-name/rule-name": [severity, options ...]

其中 severity 的值可以是下列三個：

而 options 的部份，則每一條規則不同，需要查文件。若不需要指定 options 部份，則可以省略 [] 括號。

如果使用的外掛需要調整設定，則必須以 "plugin-name/rule-name" 的形式指定。注意，這時候不能指定 eslint-plugin- 前置名稱。

譬如：

directives

1

/ eslint "plugin1/rule1": 2, "plugin2/rule1": [1, "always"] /

.eslintrc.json

1
2
3
4
5
6
7

{
    "rules": {
        "eqeqeq": 0,
        "quotes": [2, "double"],
        "yoda": [1, "never", { "exceptRange": true }]
    }
}

7. 可以使用擴展的方式重複使用設定檔

為了確保設定檔只有一份，而不是散落在各個專案中，可以利用 "extends" 區塊，指定規則檔，然後再加以補正。譬如說，可以有一個模組，實際上不含任何功能，唯一的目的就是提供 .eslintrc.* 檔案供其他專案引用：

1
2
3
4
5
6
7
8
9
10

{
    "extends": [
        "./node_modules/coding-standard/.eslintrc.json",
        "./node_modules/coding-standard/.eslintrc-jsx.json"
    ],
    "rules": {
        // Override any settings from the "parent" configuration
        "eqeqeq": 1
    }
}

由上面例子也可以看到，ESLint 允許在 JSON 檔案中撰寫註解 (雖然標準的 JSON 不允許，譬如 package.json)。

結論

利用上述的方式套用範本，只需要針對衝突的規則加以處理，調整到最適合自己的方式，一點都不難。還不快投入 ESLint 的懷抱！

想參考我的 Open Source 專案 (符合 ECMAScript 5，未使用 ES2015 的語法) 的 .eslintrc.json 做為起點的朋友，請自行取用。

歡迎大家的回饋與心得分享。

參考文章：

• ESLint Configuring
• ESLint Rules
• Linting Tools Comparison

相關文章：

最早的 JavaScript linter 是 JSLint，但是由於作者 Douglas Crockford 設定了太多個人主觀認定必須要遵守的強制規則，而且很少有妥協的餘地，所以後來強調可以配置規則的 JSHint 漸漸崛起，我自己從一開始就是使用 JSHint，並且也用了蠻長一段時間。然而...

JSHint 的問題

過去使用 JSHint 時，有非常多的困擾：

1. 難以確認發生錯誤的規則

預設情況下，根本無法從它的錯誤訊息中，得知是違反那一條規則。每次遇到錯誤，只能利用它的錯誤訊息來搜尋文件，每次幾乎都是看完所有的文件，還是找不到正確的規則。然後你才會不小心發現 (想起來)，它可以在執行的時候指定 --verbose 參數，然後就會顯示對應的規則代碼 (warning code)，譬如 (W034)。這難道不應該是預設行為才對嗎？

最糟糕的是，JSHint 的 API 並不支援 verbose 選項，這是寫在 cli 模組裡的，也就是說，如果你是使用自動化建制工具，如 Gulp 或 Grunt，那麼你永遠看不到規則代碼！

2. 沒有完整的規則代碼列表

好不容易總算找到規則代碼了，到它的文件頁面，在右上角輸入規則代碼，按下 "Jump to docs" 搜尋，結果只會跳到 JSHint Options 頁面，好吧，那麼應該在頁面上搜尋得到吧，按下 Ctrl+F 搜尋，還是找不到 W034。

翻遍文件，你絕對找不到任何說明，除了文件首頁的介紹文章中，以 W034 介紹如何開關警告錯誤訊息時提到。

那麼，W034 到底是什麼呢？還好，有 JSLint Error Explanations 這樣的網站，可以在這裡查詢錯誤代碼，譬如：搜尋 W034，可以找到這個錯誤是 Unnecessary 'use strict'，在這裡可以看到極為詳細的說明。

3. 規則代碼無法望文生義

當你調整好規則，繼續快樂地 coding。幾天之後，你再次看到 W034，卻根本記不得這條規則是什麼。像這種寫在 source code 檔案中的 directives： /* jshint -W034 */，除非你在旁邊寫註解來說明這條規則，否則你光是看到 W034，根本稿不清楚這是什麼規則。但是這樣一來，每個檔案都必須重複同樣的內容，根本違反 DRY 原則。

那麼，寫在 .jshintrc 檔案如何？很不幸的是，.jshintrc 檔案是 JSON 格式，而標準 JSON 是不能有註解的。更不用提 JSHint 文件上根本就沒有提到像 W034 這樣的規則，要如何寫在 .jshintrc 檔案中了。

在 Google 直接搜尋 W034，可以找到在這個 Grunt 的 Issue 中，有人回答了 Grunt 的作法：

1
2
3
4
5

jshint: {
  options: {
    '-W034': true
  }
}

同樣的方法也可以套用在 .jshintrc 檔案中。

4. 配置選項與規則代碼兩套規則

前面提到的文件頁面，裡面提到的 directives 使用的 options 都是像 unused 及 eqnull 這樣的選項。這些選項，比較像是大分類，而執行 JSHint 時所報告的錯誤，實際可能是由這些選項、或是預設的選項所控制，但是卻無從得知這些規則代碼與配置選項之間的對應關係。所以，即使你很仔細地設定了每一條配置選項， JSHint 還是有可能會報告錯誤。除非你已經是 JavaScript 的專家，在面對 JSHint 報告的發生錯誤的規則代碼時，你很難知道究竟是那一條規則所造成的，於是，你只能以規則代碼去查詢 JSLint Error Explanations 網站。最後，恐怕還是只能在 source code 上寫下 /* jshint -W034 */ 。

結論

其實 JSHint 自己也承認這些問題的存在：

Trying to figure out how JSHint options work can be confusing and frustrating (and we're working on fixing that!)

在 JSHint 變得更酷之前，就先允許我們小小地[叛逃][applying-eslint-using-atom-linter-eslint]吧。

參考文章：

• JSHint Documentation
• JSHint Options
• JSHint在线文档翻译（一）：基本介绍
• JSHint在线文档翻译（二）: 选项

相關文章：

前言

長期關注本部落格的朋友，可能有發現到，除了原本在 Blogger 的 格物致知 之外，還有一個同步更新的網站 Fragments of Time 位於 Logdown。

這是因為我在之前的文章『Medium 與 Facebook Notes 簡短試用』中提到的，厭倦了使用 HTML 撰寫部落格，所以在 Logdown 發佈之後，曾經有一段時間，我是在 Logdown 先用 Markdown 語法撰寫文章，然後再將 HTML 複製到 Blogger 中。

現在決定改用 GitHub Pages / hexo，上面的步驟就省了，現在我可以直接用 Markdown 寫文章，然後下個指令，就自動轉成 HTML 並且發佈。當初除了必須手動複製這個原因之外，其實在使用 Logdown 時，還遇到一些不方便的地方，並且做了一些筆記。我不確定現在這些問題是否依舊沒有改善，整理出來，給不幸遇到的朋友參考看看。

Q: 無法在同一頁中，建立交互連結

A: 有兩個問題:

1. Logdown 不會自動為 header 元素設定 id，所以必須自行加上 anchor 元素。如:

   1	### <a id="mylink" href="#">My Link</a>

2. Logdown 不支援 [link text][link reference] 的連結語法，所以只能使用 [My Link](#mylink) 的語法建立連結。如：

   1	Here is My Link.

參考:

Markdown Cheatsheet

Q: 在 Logdown 的 inline code 中，「$」顯示不出來。(2014/08/04)

A: 由於 Logdown 支援 LaTeX，其中還支援 inline math 語法，就是「$ expression $」，但是這樣卻反而造成顯示普通程式時的困擾，如 jQuery 的代表符號「$」，如果產出的 HTML 要用「<code>」標籤強調，用 markdown 語法必須寫成「$」，但是在 Logdown 中，這樣寫的時候「$」這個符號是顯示不出來的。目前解決方法是直接使用 HTML 標籤：「<code>$</code>」。

參考:

在 logdown 裡面打複雜方程式

參考文章：

• Markdown Cheatsheet
• 在 logdown 裡面打複雜方程式
• 台灣製造，新一代部落格平台 Logdown 團隊專訪

相關文章：

• Medium 與 Facebook Notes 簡短試用

前言

Glob 類似於 regular expression，但是僅用來匹配檔案路徑名稱。名稱由來是 UNIX 一個負責解析匹配檔案、叫做 global command 的模組。

本文針對 gulp 使用的 node-glob 所支援的語法及選項進行說明，詳細的使用方法可參考 node-glob 的說明。

gulp.src() 基本使用方式

1
2
3
4
5
6

var gulp = require('gulp');
var uglify = require('gulp-uglify');

gulp.src('*/.js')
    .pipe(uglify())
    .pipe(gulp.dest('dist'));

gulp.src() 還支援陣列形式的多組 glob 參數：

1
2
3

gulp.src(['/*.js', '/*.ts'])
    .pipe(uglify())
    .pipe(gulp.dest('dist'));

不過這個例子，可以使用後面介紹的『多選結構』加以簡化，而不必使用陣列：

1
2
3

gulp.src('*/.{js,ts}')
    .pipe(uglify())
    .pipe(gulp.dest('dist'));

或者，直接使用 node-glob 來匹配檔案

安裝

1

npm install --save glob

注意，雖然 GitHub 上的名稱為 node-glob，但是 npm 上卻是註冊為 glob，因此安裝時名稱必須為 glob。

呼叫 glob() 函數

1
2

var glob = require('glob');
var files = glob('*/', { dot: true });

檔案路徑匹配結果以陣列回傳，如果沒有匹配任何路徑或檔案，將回傳空陣列。

Glob 元字元

前面兩個例子中，呼叫 gulp.src() 及 glob() 函數的第一個字串參數，就是所謂的 glob，其中 * 及 / 字元，就是所謂的 Glob 元字元。就是這些元字元，讓我們可以以簡單的模式，即可對應各種不同的檔案名稱。

多選結構，『{』及『}』元字元：

首先，在開始解析 glob 之前，其中的『{}』部份，會先被擴展開來，每個以『,』隔開的部份，都會造成整個 glob 被複製一次，成為個別的 glob。系統再分別針對這些個別的 glob，一一去比對檔案系統，然後將吻合的檔案，綜合起來，去除重複的檔案後傳回。

1. 若 glob 中包含兩個以上的『{}』部份，可想而知，被擴展的 glob 將以等比級數比例增加。譬如，a{b,c}{d,e}?，將擴展為：abd?, abe?, acd?, ace?。
2. 『{}』中的部份，可以包含路徑分隔符號『/』，譬如，a{/b/c,bc} 將被擴展為 a/b/c 及 abc。

匹配路徑分隔符號，『/』元字元：

『/』元字元用來標示路徑分隔符號。除了『/』元字元及後面介紹的『**』元字元之外，其他元字元所能夠匹配的檔案路徑字元，皆不包含路徑分隔符號。

任意字元，『*』元字元：

在 glob 中若出現『*』元字元，則在該元字元的位置，可以匹配任意數量的任意檔案路徑字元，包含 0 個字元，也就是可以不匹配任何字元

譬如，a*.js 可以匹配 a.js, a4.js, about.js，但是不包含 app/about.js，因為不匹配『/』路徑分隔符號 (如前所述，匹配的字元不包含『/』路徑分隔符號，後不再贅述)。

任意單一字元，『?』元字元：

在 glob 中若出現『?』元字元，則在該元字元的位置，必須且只能匹配一個任意路徑字元。

譬如，a?.js 可以匹配 a4.js 及 ax.js，但是不能匹配 a.js, about.js。

字元組，『[』及『]』元字元：

與 regular expression 類似，字元組的意義為，匹配若干字元之一，且僅匹配一個路徑字元。同樣與 regular expression 類似地，若字元組的第一個字元為『!』或『^』，則為『排除型字元組』，代表該位置不得匹配字元組中列出的字元。

譬如，a[bc].js 可以匹配 ab.js 及 ac.js，但是不能匹配任何其他檔案路徑。
而，a[!bc].js 或 a[^bc].js，兩種寫法意義相同，可以匹配 a4.js 及 ax.js 及任何其他 a 開頭 .js 結尾的兩個字元檔名的檔案，但是就是不能匹配 ab.js 及 ac.js。

模式匹配，『@(pattern|pattern|pattern)』：

匹配的路徑，必須吻合任一 pattern，實際的意義由開頭的字元決定：

• 『!』：不得與列出的任一 pattern 吻合 (0)
• 『?』：可選的吻合，即可以不吻合，或者有一次吻合 (0~1)
• 『*』：可選的吻合，即可以不吻合，或者有一次以上吻合 (0~n)
• 『+』：必須吻合，至少一次，或一次以上 (1~n)
• 『@』：必須吻合，一次，且僅能一次吻合 (1)

注意，『(』與『)』皆是合法的檔案名稱，所以若少了前面的『!』,『?』,『*』,『+』及『@』等元字元，則『(』與『)』不會被當作是模式匹配元字元。

任意路徑，『**』元字元：

又稱為 globstar 元字元，只有當單獨出現在路徑中時才有效，也就是必須以 **/ 或 /**/ 的形式出現才有效。一旦發揮作用，可以匹配包含任意子目錄的任意路徑。也就是說，全部任意深度的子目錄都將被匹配。但是不包含 symlinked 目錄，即不包含目錄捷徑。

選項

gulp.src() 及 glob() 函數的第二個參數是 options，可以用來改變 glob 匹配的行為。

dot 選項與 . 字元

. 字元並非元字元。在 Linux 下，目錄或檔案名稱若以 . 字元開頭，則為隱藏檔案。因此，glob 預設不會匹配以 . 字元開頭的檔案，除非明確在 glob 中明確寫出 . 字元。即使在 Windows 底下，也保留相同的行為。

譬如：a* 不會匹配 .access 檔案或目錄，**/b* 不會匹配 abc/.batch 檔案或目錄，除非分別明確寫為 .a* 及 **/.b*。

如果程式經常需要匹配隱藏檔案，可以在呼叫 glob() 函數時，在第二個參數提供 { dot: true } 選項，讓 glob() 函數像一般字元一樣，對待 . 字元。

base 選項

在 gulp 中，要特別注意的是 base 的決定與作用。

base 的作用，是匹配檔案的路徑參考原點。簡單地說，就是『匹配檔案的路徑，要從哪裡算起』。

所有匹配的檔案，其路徑必須以相對於 base 所指定的路徑為起點，以相對路徑表示。也可以這樣解讀：base 的作用是，最終匹配的檔案路徑及名稱，將排除 base 路徑部分。所以，base 的值，將會影響檔案輸出時是否包含目錄、若包含目錄，又是哪些目錄路徑。

那麼，base 是如何決定的呢? Gulp 關於 base 屬性的預設值的說明提到：

Default: everything before a glob starts

這恐怕有點誤導，事實上整個 pattern 都是 glob，而 gulp 的說明恐怕把 glob 狹義解釋為是指普通文字以外的部分，譬如 *, ? 等通配字元。

正確地說，base 的預設值，是指未動用到通配字元而能夠匹配的路徑的部分。只有兩種可能情況符合：

1.glob 中不含路徑分隔符號，也就是不匹配任何目錄。所以 base 就是 .。
2.glob 中含有路徑分隔符號，但是路徑是直接寫出，不含任何通配字元。一旦路徑中含有通配字元，就會被排除在 base 路徑之外。

譬如：

上面是以 base 的觀點來說明。反過來說，對於匹配的檔案來說，一旦匹配成功，若匹配的檔案含有路徑，而該路徑是透過通配字元匹配的，則匹配的路徑將包含在匹配檔案的匹配路徑中。

所以：

1. 在指定 glob 時若不含目錄通配字元，則找到的檔案，將忽視其路徑部分，因此，由 gulp.src('src/*.js') 對應到 gulp.dest() 時，檔案將不含目錄，直接寫到 gulp.dest() 指定的目錄。

2. 若指定了 ?, * 或 ** 目錄通用字元，由於目錄通用字元將被視為檔案的一部分，所以輸出到 gulp.dest() 時，檔案將被寫入到目錄通用字元所匹配的路徑下。

譬如：

假設存在 app/views/options/options.html，且一律指定 dest('dist')：

3.透過指定 "base" property 來改變參照路徑；或者，在 gulp.dest() 指定輸出路徑。

下面的範例中，對 gulp.src() 指定了兩個不同的 glob：

1
2
3
4
5
6

gulp.src([ 'bower.json', 'app/manifest.json' ])
      .pipe(plugins.configSync({
           fields: [ 'version' ]
      }))
      // 注意這裡若指定為 gulp.dest('/') 則真的會輸出到磁碟的根目錄。
      .pipe(gulp.dest('.'));

但是由於兩個檔案的根目錄不同，同時目錄也都未使用通配字元，所以最後匹配的檔案都不含路徑，因此，使用 gulp.dest('.') 輸出時，將輸出到專案目錄 (假設專案叫做 project) 下：

1
2
3

project
    +-- bower.json
    +-- manifest.json

這裡當然也可以藉由指定通配字元 "*/manifest.json" 從而避免 base 的指定。但是，這樣的寫法，很可能會殃及無辜檔案。同時，最重要的是，反而不容易看出我們真正的意圖：就是只要 app/manifest.json 這個檔案。

因此，這裡可以藉由指定 base property 來改變參照路徑，強迫匹配的檔案以目前目錄為相對路徑表示，從而，得以保留檔案的目錄資訊。

1
2
3
4
5

gulp.src([ 'bower.json', 'app/manifest.json' ], { base: '.' })
      .pipe(plugins.configSync({
           fields: [ 'version' ]
      }))
      .pipe(gulp.dest('.'));

輸出如下：

1
2
3
4

project
    +-- app
            +-- manifest.json
    +-- bower.json

當匹配的檔案都在共同的子目錄之下時，若輸出目錄仍然希望含有特定目錄，則可以在 gulp.dest() 指定輸出路徑：

1
2
3

gulp.src('app/scripts/*/.js')
    .pipe(uglify())
    .pipe(gulp.dest('dist/scripts'));

4.透過 gulp-flatten 可消除匹配的路徑。

1
2
3
4

var flatten = require('gulp-flatten');
gulp.src('bower_components/*/.min.js')
    .pipe(flatten())
    .pipe(gulp.dest('build/js'));

參考資料

• Glob
• Maintain Directory Structure while Globbing
• gulp.src(): options.base
• node-glob
• gulp-flatten

相關文章

前言

最近正在開發一個幫助重複使用 gulp task 的工具：gulp-chef，所以分別研究了 Gulp 3.9 和 Gulp 4.0 的原始碼，以下是 Gulp 3.9 的快速筆記。

解析 Gulp 原始碼

進入點：

gulp/index.js

Gulp 繼承 Orchestrator:

1
2
3
4
5
6
7
8
9
10

var util = require('util');
var Orchestrator = require('orchestrator');
var gutil = require('gulp-util');
var deprecated = require('deprecated');
var vfs = require('vinyl-fs');

function Gulp() {
    Orchestrator.call(this);
}
util.inherits(Gulp, Orchestrator);

Orchestrator 的定義：

orchestrator/orchestrator

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

Orchestrator.prototype.add = function (name, dep, fn) {
    ...

    this.tasks[name] = {
        fn: fn,
        dep: dep,
        name: name
    };
    return this;
};

Orchestrator.prototype.task = function (name, dep, fn) {
    if (dep || fn) {
        // alias for add, return nothing rather than this
        this.add(name, dep, fn);
    } else {
        return this.tasks[name];
    }
};

可以看到：

1. gulp.task() 透過 gulp.add() 函數，將定義的 task 包裝為物件，儲存在 gulp.tasks[] 陣列中。
2. 透過 gulp.task() 函數，其實可以取得特定名稱的 task 物件的完整定義。

下面這一行乍看之下似乎是多餘的，因為 Gulp 繼承 Orchestrator 時，就已經同時取得 .add() 及 .task() 函數，但是 Orchestrator.prototype.task() 實際上將工作委託給 Orchestrator.prototype.add() 函數，然而task() 並未改變任何行為，因此，其實只要讓 task() 也指向 add() 即可：

gulp.task() 改直接引用自 Orchestrator.prototype.add 成為別名:

1

Gulp.prototype.task = Gulp.prototype.add;

gulp.src(), gulp.dest() 直接引用自 vinyl-fs:

1
2

Gulp.prototype.src = vfs.src;
Gulp.prototype.dest = vfs.dest;

gulp.watch() 將監看對象陣列攤平，丟給 vinyl-fs 的 .watch() 函數：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

Gulp.prototype.watch = function(glob, opt, fn) {
    if (typeof opt === 'function' || Array.isArray(opt)) {
        fn = opt;
        opt = null;
    }

    // Array of tasks given
    if (Array.isArray(fn)) {
        return vfs.watch(glob, opt, function() {
            this.start.apply(this, fn);
        }.bind(this));
    }

    return vfs.watch(glob, opt, fn);
};

gulp.src() 透過 glob-stream 將 glob 轉換為 vinyl (File)(vinyl 是黑膠唱片的意思，表示承載內容的物品)：

vinyl-fs/lib/src/index.js

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60

var assign = require('object-assign');
var through = require('through2');
var gs = require('glob-stream');
var File = require('vinyl');
var duplexify = require('duplexify');
var merge = require('merge-stream');
var sourcemaps = require('gulp-sourcemaps');
var filterSince = require('../filterSince');
var isValidGlob = require('is-valid-glob');

var getContents = require('./getContents');
var resolveSymlinks = require('./resolveSymlinks');

function createFile(globFile, enc, cb) {
    cb(null, new File(globFile));
}

function src(glob, opt) {
    var options = assign({
        read: true,
        buffer: true,
        sourcemaps: false,
        passthrough: false
    }, opt);

    var inputPass;

    if (!isValidGlob(glob)) {
        throw new Error('Invalid glob argument: ' + glob);
    }

    var globStream = gs.create(glob, options);

    var outputStream = globStream
        .pipe(resolveSymlinks())
        .pipe(through.obj(createFile));

    if (options.since != null) {
        outputStream = outputStream
        .pipe(filterSince(options.since));
    }

    if (options.read !== false) {
        outputStream = outputStream
            .pipe(getContents(options));
    }

    if (options.passthrough === true) {
        inputPass = through.obj();
        outputStream = duplexify.obj(inputPass, merge(outputStream, inputPass));
    }
    if (options.sourcemaps === true) {
        outputStream = outputStream
            .pipe(sourcemaps.init({loadMaps: true}));
    }
    globStream.on('error', outputStream.emit.bind(outputStream, 'error'));
    return outputStream;
}

module.exports = src;

glob-stream/index.js

1
2
3
4
5
6
7
8
9
10
11
12
13
14

// create globbing stuff
var globber = new glob.Glob(ourGlob, ourOpt);

...

globber.on('match', function(filename) {
    found = true;

    stream.write({
        cwd: opt.cwd,
        base: basePath,
        path: path.resolve(opt.cwd, filename)
    });
});

vinyl 雖然有專屬的 module （class），也有許多 method 可用:

wearefractal/vinyl

但是對於 Gulp 來說，它只需要四個欄位：

1
2
3
4
5
6

{
    base: string,
    cwd: string,
    path: string, // filename
    contents: any // file content
}

在 Gulp 中，由 gulp.src() 開始，一直到 gulp.dest() 為止，傳遞的都是只有上面四個欄位的 vinyl。

所以，像 Browserify 這樣的工具若要能夠供 Gulp 使用，必須透過 vinyl-source-stream 這樣的工具，將輸出的文字內容，轉換為 vinyl 的格式，同時賦予檔案名稱：

同場加映，解析 vinyl-source-stream 原始碼

hughsk/vinyl-source-stream / index.js

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

var through2 = require('through2')
var File = require('vinyl')
var path = require('path')

module.exports = function (filename, baseDir) {
    var ins = through2();    // .......................................................(3)
    var out = false

    var opts = {
        contents: ins        // ...............................................(3)
    }

    // NOTE: 注意其 opts.path 的決定方式
    if (filename) opts.path = path.resolve(baseDir || process.cwd(), filename)
    if (baseDir) opts.base = baseDir

    var file = new File(opts);    //  ...............................................(2)

    // 回傳的是 through2 物件，注意 objectMode: true。........................................(1)
    return through2({
        objectMode: true
    }, function(chunk, enc, next) {
        if (!out) {
            this.push(file) // NOTE: 這裡推入 vinyl 物件。.......................(2)
            out = true
        }

        ins.push(chunk)     // ................................................(4)
        next()
    }, function() {
        ins.push(null)        // ................................................(5)
        this.push(null)
    })
}

可以看到：

1. 回傳的是 through2 物件 (through2 是 node 常用的 stream 包裝函數，可以避免使用繼承的方式撰寫 stream 物件)。
2. through2 接受的第一個函數，稱為 transformFunction，是當 stream 在傳輸資料時，負責進行內容轉換工作。
   使用 through2 時，透過 push() 函數將實際上要輸出的內容，加到輸出 stream 中。可以看到這裡要傳輸的是 vinyl 物件，所以回傳的 through2 物件，在定義的時候，必須指定 objectMode: true。
3. 前面提到 vinyl 物件最重要的四大屬性，其中 contents 是用來傳輸 / 存放檔案內容的。在這裡，contents 實際上又是一個 through2 物件，注意這裡沒有定義 objectMode，所以這是一個 byte stream。
4. 在每當 up stream 有資料傳送進來時，便呼叫 push() 函數，將資料推送到 buffer 中。
5. through2 接受的第二個函數，稱為 flushFunction，是當 stream 資料傳輸完畢時，負責進行最後的收尾清理工作。在這裡都 push(null) 表示資料結尾。

相關文章

前言

由於實在是受不了使用 HTML 寫部落格的瑣碎，前一陣子決定將部落格由 Blogger 移轉出來之後，除了 GitHub Pages / hexo 這個可以使用 Markdown 的組合之外，其實還評估了幾個平台，尤其其中 Facebook Notes 剛剛全新改版，吸引了不少的目光，所以就順勢評估了一下 Medium 和 Facebook Notes。

Medium

優點

提供簡單的格式化工具，可以輕鬆寫出排版漂亮的文章。

問題

1. Code block 根本是災難。

操作方式：選擇程式碼，然後按 Ctrl+Alt+6 (PC), Cmd-6 (Mac)

• 常常將鄰近的區塊含入。
• 無法支援 inline code span，選取段落裡的關鍵字要標示為程式碼時，會變成整個段落被標示為程式碼。

1. 無法插入網路圖片(必須上傳到 Medium)
2. 不支援 markdown

Facebook Notes

優點

根本是抄襲 medium。

問題

1. 一樣不支援 code block
2. 一樣無法插入網路圖片(必須上傳到 Facebook)
3. 一樣不支援 markdown
4. 文章不能太長，最多只能有 300 個 item (應該是指段落):

Your note is too long. Please limit the number of paragraphs, list items, headers, and embedded media to 300 items.

結論

Medium 和 Facebook Notes 都是適合一般軟性文章的平台；但是由於無法做到必要的格式化，顯然不適合以技術性內容為主的作者 (不是只有我持這樣的看法)。

鑽牛角尖時間：Promise: resolver vs handler

不曉得讀者有沒有同樣的困擾：Promise 的 resolver 與 handler 有著不同的 signature (形式) 及啟動方式，看起來非常地不協調：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

// resolver 由 Promise() constructor 啟動
return new Promise(resolver)
    // handler 由 then() 函數啟動
    .then(handler, onerror);

// resolver 具有 function (resolve, reject) 的形式
function resolver(resolve, reject) {
    fs.readFile('readme.md', function (err, data) {
        if (err) {
            reject(err);
        } else {
            resolve(data);
        }
    });
}

// fulfillment handler 具有 function (result) 的形式
function handler(markdown) {
    return marked(markdown);
}

// rejection handler 具有 function (reason) 的形式
function onerror(error) {
    log(error);
}

這樣的設計，著眼點是：對於已經使用 promise 模式的函數，早就已經回傳 Promise 物件了，使用上不涉及到 Promise 物件的建立，只要直接取用其回傳的 Promise 物件，呼叫其 #then() 函數即可，像這樣：

1
2
3
4

$.get(url)
    .then(function (text) {
        // ...
    });

至於那些需要自行處理 Promise 物件的函數，是尚未使用 promise 模式的函數。這些函數，若要使用 promise 模式^[註1]，必須先設法建立一個 Promise 物件，然後 Promise 物件在稍後呼叫指定的 resolver 函數，而 resolver 函數異步處理完畢後，再透過 resolve() 與 reject() 函數來完成整個處理過程。既然建立 Promise 物件和呼叫 resolver 函數這兩個動作似乎具有時間上的耦合，因此，這個責任就被設計，並落在 Promise 物件的 constructor 上：

1
2
3
4
5
6
7
8
9
10
11

return new Promise(resolver);

function resolver(resolve, reject) {
    fs.readFile('readme.md', function (err, data) {
        if (err) {
            reject(err);
        } else {
            resolve(data);
        }
    });
}

但是，真的不能處理得更好，更一致嗎？

嘗試 1：讓 resolver 的 signature 與 handler 一致

首先，必須先建立一個 Promise 物件。由於 Promise 提供有 Promise.resolve() 函數，可以建立一個已經 fulfilled 的 Promise 物件，顯然可以利用它來幫忙建立初始的 Promise 物件。有了初始的 Promise 物件，就可以對它呼叫 #then() 函數，然後以一致的 signature 撰寫 resolver 與 handler 了。

然而，因為要讓 resolver 與 handler 使用一致的 signature，這麼一來，resolver 就無法取得 resolve() 與 reject() 函數，所以 resolver 反而必須自行建立 Promise 物件：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

Promise.resolve(true)
  .then(resolver)
  .then(handler)
  .catch(onerror);

function resolver(initValue) {
    return new Promise(function (resolve, reject) {
        fs.readFile('readme.md', function (err, data) {
            if (err) {
                reject(err);
            } else {
                resolve(data);
            }
        });
    });
}

function handler(markdown) {
    return marked(markdown);
}

function onerror(error) {
    log(error);
}

嗯...不好。看起來只是把該做的事情，搬到不同的地方做而已，並沒有讓事情更簡化。

嘗試 2：讓 handler 與 resolver 採用一般化的，一致的 signature

如果採用兩者的聯集形式： function (value, resolve, reject) 呢？

為此，我為 Promise 添加了兩個函數，分別是 Promise.first() 與 Promise#next()，負責幫忙建立 Promise 物件，並且轉送 #then() 函數傳遞的值：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47

Promise.first = function (handler) {
    return new Promise(function (resolve, reject) {
        return handler(undefined, resolve, reject);
    });
};

Promise.prototype.next = function (handler) {
    return this.then(function (value) {
        return new Promise(function (resolve, reject) {
            return handler(value, resolve, reject);
        });
    });
};

return Promise
  .first(resolver)
  .then(handler)
  .next(writer)
  .catch(onerror);

function resolver(initValue, resolve, reject) {
    fs.readFile('readme.md', function (err, data) {
        if (err) {
            reject(err);
        } else {
            resolve(data);
        }
    });
}

function handler(markdown) {
    return marked(markdown);
}

function writer(data, resolve, reject) {
    fs.writeFile('readme.md.bak', data, function (err) {
        if (err) {
            reject(err);
        } else {
            resolve(data);
        }
    });
}

function onerror(error) {
    log(error);
}