Roadmaps for Front-End Developers

邁入 2020 是公司前端團隊第六週年，剛好來整理 2019 年度 Front-End 的實踐與技術盤點，對於前端團隊而言，什麼才是該關注的面向，此篇快速梳理了現況開發模式、過去回顧及未來的關注，期望也能給予往後成員一些 Guideline 方向可以遵循。

可以瀏覽由 Kamran Ahmed 所整理的 Developer Roadmap，能快速檢視自我能力所缺乏之處，也明確知道前端的職責範圍，下圖為其中幾個重點項目，接下來會針對這些面向進行探討：

Client-Side Frameworks

公司內使用了 Angular 一年與 React 五年，經常被問到有沒有考慮用 Vue 或其他關鍵字技術，既然 React Ecosystem 已經能夠在數個專案的磨合下，大幅度的滿足團隊需求，又有什麼特別的原因需要打破舒適圈呢？或是我們在這問題之上應該要釐清的是， Why React.js Community。伴隨新版 Facebook UI 重構的需求，React 時常改版與提出新的設計理念，有大公司的背書外，最主要影響一個技術迭代是生態圈及社群的活絡，除了看彼此語法之間的差異，應全局地探索技術的效率效能、穩定性、擴展性與前瞻性。

在採用一個技術時，不只是比較 API 的封裝，我們挑選能改變開發思維，並在想法上有所突破者，恰巧 React 就是這方面的領頭羊。除了 Declarative and Reactive Programing、Data Flow、Immutability 的設計理念，到近年 Functional Programing，也讓 UI Component 模組化成為顯學。種種目的除了降低專案維護上的困難、增加開發可預期性，並使測試更為方便，以提升專案健康度。

選擇一門技術，是否對於思維上有所改變

Zero Configuration Setup

前端領域最為困難的是開發工具，理解現代工具 Webpack 的發展是有必要的，但每當開始新專案又得再次堆起積木，前置作業花費瑣碎的時間，因此有了生成專案的工具，不大需要額外的設定，並保有客製化的擴充彈性。這些工具不只是快速讓架構生成，大幅減小專案啟動的最大靜摩擦力，也一定比率的讓維運成本轉嫁，以專注於產能提升。

面對不同性質的網站需求，且當專案規模不明確時，在以下三個成熟 Zero Configuration Frameworks 工具的比較下，Next.js 相較能夠滿足各類專案，是最為彈性的解決方案：

維運成本轉嫁，專注於產能提升

UI Modularize

採用 React 使得 UI 元件模組化成為顯學，就一個專案的開發週期來說，先定義元件、各個頁面挑選元件進行組裝，複雜的元件可以將數枚元件 Compose 搭配在一起使用，甚至是跨專案能夠複用。

過去 MCS-UI 是以一個團隊標準化作為目標，搭建符合 Branding 的 Guideline，小團隊在維護上還是相當有難度，時常因人力與專案時程壓力而妥協，以至於採用 Open source UI Framework 的團隊仍佔多數。面對需求的變動，Material-UI 是 Google 提出規劃完整的設計框架，其元件種類豐富、文檔齊全、API Spec 的擴充性、用以提升開發體驗的 Styled System 設計，都是採用前考量的重點，甚至在使用後也能從中學習到一些技巧。

談論模組化，前端除了 CSS 外，邏輯上的封裝也是一種設計美學，React 經歷了三次的變革，從 Higher-Order Components (HOC) 到 Render props，以及近期的 Hooks，不是追求語法上的標新立異，確實解決了模組化的痛點，讓測試更專注，模組化複用思維的改變引領各大社群的相繼參照與討論，這也是 React 的魅力所在。

UI 模組化成為了顯學

延伸閱讀：

[Apr, 2017] Build A Web App in MediaTek

[Apr, 2017] Refactoring React Component in Reactive Way

API Communication and Data Layer

提到前後端分離，各團隊能在分工下達到最大效益，除專注於各自領域的開發外，最重要的是雙邊的溝通，GraphQL 成為最佳的橋樑。GraphQL 除了已知整體網站效能的提升外，文件化是大多數團隊忽視的重點，肯定沒有工程師會想花費過多的心思在撰寫與維護 API Documentation 上，而 GraphQL Introspection 有著開發完即完成文檔的特性。因此當開發一套系統時，前後端可以先協商 GraphQL Schema Definition Language (SDL)，一旦定下了 Spec 將大幅減去溝通成本。

Side Effects 與狀態的管理是前端的課題之一，幾年前的 RESTful 與 Redux 是大神們提出的主流解決方案，而後各種完善的工具如雨後春筍般出現。後起之秀 Apollo Client 搭著 GraphQL 順風車出現，從 Cache 設計上讓很多瑣碎的事情自動化、聲明式的數據取用，大幅降低前端專案 Codebase 的複雜度，使狀態的管理更為直覺。

同樣的，此難題由 Facebook 提出從根本設計上去改善，因而 React Concurrent Mode 的出現，將提升 Side Effect 的微控能力，勢必會再次帶動使用者體驗上的優化，是未來可以密切關注的項目。

GraphQL 的採用成為專案的首選

延伸閱讀：

[Dec, 2017] GraphQL — JavaScript Fullstack Solution

[Aug, 2017] GraphQL Microservice with Apollo

[Jul, 2017] Centralized Error Handle in React with RxJS

Code Quality and Performance

工具標準化是一個 Codebase 健康度的表現，如今已有 Prettier 讓 Coding Style 排版不再煩惱，搭配 ESLint 規範的 Rules 使開發語法基礎、語意細節不遺漏，除此之外 Static Type Check 也是多人合作不可或缺的一部分，採用 TypeScript 補足了 JavaScript 型別語法上的不足。另外，也可以採用諸如 GraphQL Code Generator 的工具，自動化產生 Type 語法，盡量減少撰寫瑣碎的程式碼。

前面段落提到模組化，其目的之一讓測試更為專注。在過往以 Jest 撰寫測試的經驗中，應從 User Story 在意的操作行為進行測試，也因此 React Testing Library 的理念取代了 Enzyme，不要過度理解實作細節。一般來說並不需要達到 100% Test Coverage rate，尤其時在 Scrum 快速迭代下，過多的測試反成累贅，目前經驗大概介於 70% 左右。

最後評估網站，因應瀏覽器的更新，效能指標需與時俱進，最好的做法是查看社群統整的大抄：HEAD、Front-End Checklist、Front-End Performance Checklist 都是很棒的整理，為產品交付前可以參考的清單。

從 User Story 行為進行測試，不過度理解實作細節

延伸閱讀：

[Jul, 2017] React Stack 開發體驗與優化策略

[Apr, 2017] Introducing Prettier with Eslint

[May, 2017] Component-based Code Splitting

[May, 2017] 這個雷踩了四次，為什麼你可能需要 Eslint

[May, 2017] Reproducing Medium Style Progressive Image Loading for React

CICD Workflow and Production

工作流程可以從工程面與管理面不同角度切入，實質上是相互關聯，如下圖，針對每一個流程，Scrum 的管理工具 Jira 在看板的設計也可以有對應關係。從工程面來看，採用最簡單直覺的 GitHub Flow 開始，完成開發後發起 Pull Rrequest 讓團隊進入 Code Review 的階段，CI 自動化跑測試，同意合併進入 Master 分支，觸發打包部署到測試環境。經測試反饋後，最後下 Git Tag，觸發部署到正式環境。

常見有 Travis、Circle CI、Jenkins，而我們使用 Drone 作為 CI Server，以 Docker-based 為基礎，乾淨的執行環境不必再煩惱干擾的問題。有別於以往在 Bamboo 使用 UI 來設定流程，採取 Workflow as Code 的方式來管理專案，也就是流程跟著程式碼走，以便於版本控制，權限下放工程師能完整設定可預期的工作流程。

現在有諸如 Pkg 的工具，可以打包為執行檔成 Binary，提供跨平台支援，而容器化已是產品交付的標準，搭配 Docker Compose 或 Kubernetes，讓管理複雜的容器成為了如今不可或區的利器，因此有了 DevOps Roadmap 更寬廣的路要走，這不是簡單的事情，也是目前所欠缺的。在建置機器環境時，以往都是直接進入環境開始安裝相依環境，之後應採用類似 Infrastructure as Code (IaC) 的概念，讓機器管理與維運更具可預期性。

延伸閱讀：

[May, 2018] Deploy a commercial Next.js application with pkg and docker

[May, 2018] Make Your React Service Portable

[Sep, 2017] 五分鐘 Kubernetes 有感

[Aug, 2017] Microservice 產品交付

[Jul, 2017] 使用 CircleCI 2.0 Workflows 挑戰三倍速

[Apr, 2017] I18n Workflow for React Project

Beyond Front-End

專案可能碰到要洽接數個現有系統的案例，GraphQL 很適合扮演所謂 Backend-For-Frontend (BFF) 的角色，其實就是一個 Proxy Sever 的實作，匯流統整數據，最終只揭露單一 Endpoint 給前端頁面使用，對於全站整體效能有所提升。另外，前後端使用 JavaScript 開發，使得部分邏輯 Client Side 與 Server Side 可以共用，因此前端也具備開發後端的能力。

在 TensorFlow.js 的發展下，能使用瀏覽器資源進行深度學習，非常適合在終端裝置做識別的應用，能夠在不透過網路傳輸下，進行即時的推論與預測，是一個非常有趣的領域。因此前端也適合從此踏入 AI，當一個跨領域的斜槓前端。

斜槓前端，具備統整能力

延伸閱讀：

[Sep, 2019] Inference on the Browser with Tensorflow JS

[Dec, 2017] GraphQL 漸進式導入的架構

Conclusion

雖然在前端的世界目前都是寫 JavaScript 為主，那團隊開發模式為什麼會發生迭代，進而產生 Legacy Code 與技術債呢？其一，因硬體與瀏覽器的進步與安全性的加強，驅動了技術的變化，原本十行程式完成的事情變成一行就搞定，而現在已有 Webpack、Babel 等完善的開發工具，已經盡量彌平過渡期所造成的差異，並使程式語言更具擴充性，提升開發體驗舒適度。

最主要應該還是人的因素，團隊成員的流動與組成，常常是決定一個團隊技術棧的關鍵。在人力充沛時，可以考慮團隊自主開發細節的 UI Library，但人力緊縮時，就只能做出一些取捨採用現成的工具。技術的選擇，也因專案規模與需求而異，並不會有一招半式能打天下的作法，但不變的只有過程中所累積的經驗與開發思維。適應追逐新技術的環境，是前端領域不可或缺的能力。

References

• Roadmap to becoming a web developer in 2019

全民人工智慧時代來臨，近期正進行公司的深度學習課程中，所以挑了一組常見的 Kaggle Dogs vs. Cats Dataset 來練習。網路上的學習資源已經相當豐富，這篇文章主要會紀錄從訓練端到終端上的過程，以 Python Karas 做訓練，輸出轉換成 Tensorflow.js 的格式，在瀏覽器端進行推論，完整地走過一遍。

Links: GitHub | Jupyter Notebook | Demo

Convolutional Neural Network

針對影像問題上主要會拿 Convolutional Neural Network 來分析，CNN 使用 Convolutional 概念擷取特徵、Pooling 降維加速計算，並在訓練中自動學習最佳參數。而其中如何去設計中間層是非常需要經驗的，雖然可以從頭搭建出自己的模型，但也有更有效率的做法，也就是 Transfer Learning：直接採用 Pre-trained 的模型與參數。本篇文章挑選了由 Keras 實作 ImageNet 資料集所訓練出來的 VGG16 模型，直接複用中間層來萃取圖像特徵，最後再客製化輸出層來作為最後分類器使用。

Training

Running Jupyter Notebook on Google Colab

Jupyter Notebook 是很常見來撰寫程式的工具，所見即所得的特性，相當適合拿來對資料結構做前處理。Notebook 也便於結果的分享，因此 Kaggle 會有許多熱心的人上傳各自的實驗過程，不管是要 Reproduce 或在學習上都很有幫助，筆者也是直接參考推薦數最多的 Uysim’s Notebook 來整理資料。以下是最後整份 Notebook 的紀錄，可以直接跑在 Google Colab 並且選擇 GPU 來加速運算，接下來的段落會把每個步驟稍微解釋：

Jupyter Notebook: https://github.com/evenchange4/nextjs-tfjs-cnn/blob/master/python/vgg16.ipynb

Pre-requirements

在 Notebook 中可以直接下 kaggle CLI 指令，將資料集下載到 Google Colab 的空間，但每次重新連接可能會被分配新的環境，過程中資料不會被保留，所以也可以透過 Mount Google drive 把最後要輸出的結果放到個人的空間上：

!kaggle competitions download -c dogs-vs-cats
drive.mount('/content/drive')

Build Model

Transfer Learning Model 實作上直接拿 Keras 提供的 VGG16，因為設定 include_top=False 忽略 Output Layers，只拿中間層來當作 Feature Extractor，並且設定 trainable = False Freeze Layers，直接使用訓練好的 weights=’imagenet’ 參數。後面加上 Classifier Layers，這幾層的參數則是需要在過程中被從頭訓練的，其中使用 BatchNormalization 讓數值不會過大過小，加速收斂。接著數層全連接層 Dense，以及避免 Overfitting 使用 Dropout：一定機率讓神經元被忽略。最後我們要分類貓或狗，設定輸出兩個維度，並挑選 Softmax 激活函數使得機率總和為 1：

pre_trained_model = VGG16(include_top=False, weights='imagenet')
for layer in pre_trained_model.layers:
    layer.trainable = False

x = BatchNormalization()(pre_trained_model.output)
x = Flatten()(x)
x = Dense(units=2048, activation="relu")(x)
x = Dense(units=256, activation="relu")(x)
x = Dropout(0.5)(x)
x = Dense(units=2, activation="softmax")(x)

model = Model(inputs=pre_trained_model.input, outputs=x)
model.compile(loss='categorical_crossentropy',
              optimizer='adam',
              metrics=['accuracy'])

Prepare data

在真正開始跑訓練前，需要把資料做好準備，首先將下載的資料集切分為訓練用的 Training data，與小部分判斷訓練結果的 Validation data。若資料量不足，為了避免 Overfitting 的狀況，可以使用由 Keras 提供的 Data augmentation ImageDataGenerator 功能，在每一輪 Epoch 自動生成相仿的圖片供訓練。見下圖範例，將原始圖像旋轉、縮放、裁減、翻轉，轉化後的假資料，以提升模型的泛化能力：

Fit Model

跑訓練與調校模型參數是過程中最耗時的，可以採用 GPU 來加速運算，其中設定 batch_size 讓 Mini-batch Gradient Descent 小批小批更新學習參數；透過 epochs 設定資料集要拿來訓練幾輪。除此之外，可以預先設定訓練結束的 callbacks 邏輯，例如若連續幾輪都沒獲得優化，EarlyStopping 就直接中斷訓練；又或是下左圖觀測 Validation Accuracy 連續兩輪都沒有提升，讓 ReduceLROnPlateau 調降 Learning Rate，來減小訓練步伐。下右圖為視覺化最後訓練出來 Accuracy 的變化：

EarlyStopping(patience=5)
ReduceLROnPlateau(monitor='val_acc', 
                  patience=2, 
                  verbose=1, 
                  factor=0.5, 
                  min_lr=0.00001)

Predict Result

最後我們來看沒有提供答案的 Testing data，將預測得到的結果整理好 CSV 格式，上傳到 Kaggle Late Submission 進行 Log Loss 評分，如果滿意可以 model.save 將模型及訓練參數輸出，最後會得到一份 HDF5 格式的檔案 model.h5。

Client side

緊接著進入前端 JavaScript 的世界，使用 Next.js 快速搭建環境，並使用 React Material UI 做了基本 Layout。載入模型前，首先將上個段落的 model.h5 透過 tensorflowjs_converter 轉成 Tensorflow.js 的格式，其輸出包含 model.json 與 Binary weight files，這邊拿準備好的 Docker image 環境來執行 CLI，最後下圖利用 Netron 來視覺化模型，驗證轉換後的結果是否正確：

$ docker run -it --rm \
  -v "$PWD/python:/python" \
  evenchange4/docker-tfjs-converter \
  tensorflowjs_converter --input_format=keras model.h5 model-tfjs

在跑預測前，需要把輸入圖檔調整為模型的 Input Tensor，並注意也需要用當初在 Keras VGG16 的 Image Preprocess 步驟，將圖片 Tensor 做一些前處理運算，因為 Tensorflow.js 的支援，讓這些步驟簡單很多：

// preprocessImage.ts

const imageTensor = tf.browser
  .fromPixels(image)
  .resizeNearestNeighbor([224, 224])
  .toFloat()
  .sub(meanImageNetRGB)
  .reverse(2)
  .expandDims();

Web Worker

最後實驗嘗試將 Predict 函式丟到 Web Worker，使用 WebGL 運算，目前 Chrome 支援度會比較好，但在 CNN 的支援上不是很到位，UI Main thread 還是會有卡頓感，這也是之後前端可以優化的目標。下圖是操作流程，先透過 Web Worker 將模型與參數下載，接著就可以上傳圖片進行瀏覽器端的預測了：

// inference.worker

const model = await tf.loadLayersModel('/static/model.json');
model.predict(imageTensor);

Conclusion

在這篇文章我們走過了 Transfer Learning，一開始複用 VGG16 來搭建一個分類器，使用 Kaggle Dataset 在 Google colab 上用 GPU 來快速訓練，最後把輸出的模行轉換成 Tensorflow.js 的格式，在瀏覽器做本地端預測。雖然目前結果不甚好，之後需要花費大量時間調校，但在深度學習的研究成果下，類神經網路已經非常便於使用了。另外可以研究的方向是，預測準確度與模型大小的取捨，目前 VGG16 輸出檔案太大，造成瀏覽器端需要花費很多時間下載。期待接下來也許可以透過這樣的架構，從生活中或公司的資料實際找尋更有趣的應用案例，如果你喜歡這類的文章，可以 👏 讓我知道，也歡迎訂閱 Medium 喔！

References

• Keras CNN Dog or Cat Classification
• VGG16-with-TensorflowJs
• TensorFlow.JS — Using JavaScript Web Worker to Run ML Predict Function
• AI 如何找出你的喵
• TensorFlow.js Example: MNIST CNN Transfer Learning Demo
• TensorFlow.js — Explore tensor operations through VGG16 preprocessing
• Classifying images using Keras MobileNet and TensorFlow.js in Google Chrome
• Building a blood cell classification model using Keras and tfjs
• Keras 框架中的 epoch、bacth、batch size、iteration
• https://github.com/Elwing-Chou/TibameDL
• https://github.com/leemengtaiwan/cat-recognition-train
• Data Augmentation 資料增強
• [機器學習 ML NOTE] CNN 演化史(AlexNet、VGG、Inception、ResNet)+Keras Coding

Special thanks to mnicnc404.

As I mentioned in the “Make Your React Service Portal”, there is a scenario that we deliver commercial applications with docker. Letting customers operate their own applications without source code is the key point in this deploy flow.

Nowadays, Golang may be the best solution of back-end application and end up with the smallest binary file. Node.js is a common choice in front-end/React ecosystems. However, there is no built-in function to package Node.js project. Fortunately, the pkg CLI made by zeit does a great job for Node.js platform.

In this artical, we will introduce pkg to package the Next.js application into an single executable file and use Docker to wrap it with Alpine Linux environment.

PKG

The pkg CLI enables you to package your Node.js project into an executable that can be run even on devices without Node.js installed. — zeit/pkg

First, we need to describe pkg configuration of a Node.js project in package.json:

1. bin: The entrypoint of Node.js project. You will need a custom server for the Next.js project.
2. pkg.assets: Raw contents of the project. You might want to specify several public static files built by Next.js here.
3. pkg.scripts: The JavaScript files need to be compiled into binary without sources.

Next.js file path problem

Second, the pkg puts packaged files in their own snapshot filesystem prefixed with /snapshot/ during the process. You may encounter some path related problems at runtime, we need to customize the next server of Next.js:

// server.js

const next = require('next');
const nextConfig = require('./next.config');

const app = next({ dev, dir: __dirname, conf: nextConfig });

Then, run the command to package the entire application into an executable. You can also specify the target machine environments with --targets option and output path via --out-path as well.

$ pkg . --targets node9-alpine-x64 --out-path pkg

# output to pkg/binary

Trick of reducing binary size for Next.js project

The original binary file is 85.4MB. The main bottleneck is that pkg package unnecessary files.

One is document-like files. We can introduce .yarnclean to remove them from node_modules (-0.2MB). The other is that Next.js treat devDependencies as dependencies. However, we don’t really need them for production usage (e.g. webpack):

$ yarn autoclean --force
$ rm -rf node_modules/webpack node_modules/webpack-dev-middleware node_modules/webpack-hot-middleware

The final size of binary file is about 66MB.

Docker multi-stage builds

Docker could be a popular solution to deliver the application with machine environments. Customers can directly use docker-compose or Kubernetes to manage container services.

To make the docker image even smaller, we use Docker multi-stage builds (requiring Docker 17.05 or higher) to reduce layers and remove useless files. Here, we copy the single binary artifact made by pkg from first stage to the second stage.

In the first stage named as “builder” stage, it cotains a regular npm flow. We use mhart/alpine-node as base image and copy all source codes into the container. Do the processes of installing node_modules, building Next.js and packaging into binary:

// Dockerfile - stage 1

FROM mhart/alpine-node AS builder
WORKDIR /app
COPY . .
RUN yarn install
RUN yarn run build 
RUN yarn run pkg

In the second stage, we copy one single executable file from the first builder stage. We adopt the Alpine image alpine which is the smallest Linux image. Just to remind, you might need to install some missing apk libraries (e.g. libstdc++):

// Dockerfile - stage 2

FROM alpine
RUN apk update && \
  apk add --no-cache libstdc++ libgcc ca-certificates && \
  rm -rf /var/cache/apk/*

WORKDIR /app
COPY --from=builder /app/pkg .
CMD ./next-app

Finally, build the docker image and run with predefined environment variables:

$ docker build -t app .
$ docker run --rm -it -p 3003:3003 -e "PORT=3003" app

Deploy to Now.sh

We now deliver the docker image to customers without source code. It is also possible to verify it by deploying the docker service to any PaaS. Now.sh supports Docker multi-stage builds in OSS plan. All we need is one command:

$ now --docker

That’s it. Awesome zeit! https://nextjs-pkg-docker-alpine.now.sh

Conclusion

In this article we take a look at an example of delivering a commercial Next.js application with pkg and docker. It is quite convenient to deploy it to Now.sh cloud service. Technically, this approach should work with every Node.js project.

The full source code is available on GitHub evenchange4/nextjs-pkg-docker-alpine repository.

evenchange4/nextjs-pkg-docker-alpine

Further Readings

1. Make Your React Service Portable
2. Microservice 產品交付
3. 2018 GraphQL 漸進式導入的架構
4. 五分鐘 Kubernetes 有感

References

1. https://github.com/zeit/next.js/blob/canary/examples/with-pkg/README.md
2. https://github.com/zeit/next.js/blob/canary/examples/with-docker/README.md

Thanks to Lynn Lin.

TL;DR 直接看 Next.js with-docker 範例，簡單地搭配 Docker 來設定環境參數。

在服務開發與營運的過程中，時常碰到要將程式部署到不同的機器環境上。簡化的流程會是從本機端開發後，部署到 Staging 環境經由 End-to-End 測試，確認沒問題才正式上到 Production 機器，而其中環境參數的配置與管理是整個流程中不可忽略的要點。

若純為伺服器端的服務，不外乎讀取環境變數或 .env 來決定這個服務所需的參數。然而，在網頁端的做法稍有不同，尤其是 React App 多了一道手續，經由 Building Tools 打包，才輸出優化後 JavaScript/Static Bundle 檔案。這篇主要探討『前端專案設定環境變數』之做法，大致上有三種：

a. Client side runtime

可以在程式中針對各個環境寫一串邏輯，來決定當下應採用的配置。因此當瀏覽器載入頁面時，JavaScript Runtime 會拿 Domain Name 作為判斷依據：

// config.js
if (/staging\.com/.test(window.location.host)) {
  OAUTH_DOMAIN = 'oauth.staging.com';
  S3_URL = 'staging.s3.amazonaws.com';
  PUBLIC_TOKEN = 'PUBLIC_TOKEN';
} else if (/production\.com/.test(window.location.host)) {
  OAUTH_DOMAIN = 'oauth.production.com';
  S3_URL = 'production.s3.amazonaws.com';
  PUBLIC_TOKEN = 'PUBLIC_TOKEN';
}

這樣的做法很簡單，但缺點可想而知，所有機器的參數值都會被揭露給使用者，而且在 Runtime 使用 IF/ELSE 會影響效能，所以是三種做法中最不推薦的。

b. Build time — Webpack

在前端程式打包 Bundle 的流程中，會使用諸如 Babel Plugin 或 Webpack DefinePlugin 來處理環境變數設定的問題，最後還會跑過 Dead-code Elimination 的機制，所以不會揭露多餘的參數。Building Tools 的設定與程式邏輯大概為：

// webpack.js
new webpack.DefinePlugin({
  'process.env.APP_ENV': process.env.APP_ENV,
}),

// config.js
// Dead code will be removed
if (process.env.APP_ENV === 'staging') {
  OAUTH_DOMAIN = 'oauth.staging.com';
  S3_URL = 'staging.s3.amazonaws.com';
  PUBLIC_TOKEN = 'PUBLIC_TOKEN';
}
if (process.env.APP_ENV === 'production') {
  OAUTH_DOMAIN = 'oauth.production.com';
  S3_URL = 'production.s3.amazonaws.com';
  PUBLIC_TOKEN = 'PUBLIC_TOKEN';
}

接者在 Build 時，透過 APP_ENV 指定你要的環境：

$ APP_ENV=staging npm run build
$ APP_ENV=production npm run build

這樣的做法還蠻常見的，只要在 CI 上給與 APP_ENV 值，即可套用正確的配置，也不會有方法 a 提到的效能問題。

缺點是如果你有五台不同的環境，就要 Build 出五包 Bundles，若 CI 沒有平行執行 Jobs 的能力，Build Time 會是倍數成長，也就是利用時間換取效能的做法。

c. Docker container — runtime inject

有一種商業模式是將軟體授權客戶，讓他們自行去營運，我們不是把整包 Source Code 給客戶，而是只交付打包後的前端 Bundles。而客戶在 Runtime 時才會決定他們的環境參數，因此我們的目標是讓同一份 React App 在任何環境都能執行，上述 a、b 兩種方法就不夠彈性。

這個解法需要有一台 Web Server，在 HTML File Response 時注入到 Global Variable，通常就是放在 window 底下，使得瀏覽器端也可以取用參數：

// template.html
<script>
  window.OAUTH_DOMAIN = 'oauth.staging.com';
  window.S3_URL = 'staging.s3.amazonaws.com';
  window.PUBLIC_TOKEN = 'PUBLIC_TOKEN';
</script>

方法 c 的缺點是一般的 Static HTML 網頁架構就不適用了。

Next.js 的解法

筆者最近的專案使用 Next.js 做為 SSR 架構，這邊舉例他們提出的解法，其實也是把參數存在 Global，然後在 Next.js 啟動時注入，而官方開出的 API 使用起來大概會是這樣：

另外，現今的較為流行的封裝方式是 Docker，連同執行環境一並打包：

我們交付前預先跑 docker build，在客戶取得建置後的 Docker Image 後，即可 Runtime 設定 Docker Container 的參數：

有興趣的話可以參考我最近貢獻的 with-docker 範例。

比較參數儲存位置

方法 a 將配置的參數存放在程式邏輯中；方法 b 雖然可以在 Building Tools 中設定，但 a、b 兩種其實都是存在專案的 Repository；而方法 c 不再將環境變數放在專案內，反而應該使用 Docker-compose 或是 K8S 去統一管理。

Conclusion

這篇文章整理三種常見的前端專案參數設定方式，在經由比較後，方法 a 會暴露不該揭露的資訊也會影響效能；方法 b 是很常見的做法，但是建置時間過長且不 Portable；在考慮商業模式後，方法 c 可能是最為優雅並符合 Microservice 的概念了。

這些提到的做法都有在筆者的專案中使用，其實也不是什麼特別嚴重的問題。如果你喜歡這類的文章，可以點個拍手 👏 讓我知道，也歡迎訂閱 Medium 喔！

Further Readings

1. Microservice 產品交付
2. 2018 GraphQL 漸進式導入的架構
3. GraphQL Microservice with Apollo
4. 五分鐘 Kubernetes 有感

References

1. https://github.com/zeit/next.js/blob/canary/examples/with-universal-configuration-runtime/README.md
2. https://github.com/zeit/next.js/blob/canary/examples/with-docker/README.md

Thanks to Te-Chi Liu and Daniel Tseng.

GraphQL 出來幾年熱度依然不減，從今年數場演講與文章中，看得出越來越成熟的趨勢，筆者有在 Side Project 先試用看看覺得挺不錯的，直到近期公司新專案總算開始準備導入 GraphQL，這篇文章主要整理了置底 Reference 段落列出的內容，來看看 GraphQL 可能有哪些架構方法，建議有時間可以自行詳讀一遍。

雖然說是新專案，仍然是建立在 Legacy System 之上，會使用到舊有的 REST API，因此需要分別從 Client Side 與 Server Side 的角度來探討，怎麼樣的架構適合漸進式的導入 GraphQL。

Client Side

不免俗套先從 REST 的缺點來探討，現階段我們維運三年前開發的 MCS (MediaTek Cloud Sandbox) 中是全面採用 REST 的架構，要瀏覽 Detail 頁面至少打 7 支 Resource API，可以想像頁面的負擔相當大，在上圖 GraphQL 的設計理念中，透過將 Data Requirements 往前端搬移，讓頁面所需的資訊盡量能在一個 Request 內完成，來優化網路的傳輸問題。

前端今年最熱門的狀態管理肯定非 Redux 莫屬，一旦要轉換為 GraphQL 的架構，可以挑選由 GraphQL 為出發點設計的 Relay 或 Apollo 框架，筆者比較偏好社群活躍度高的 Apollo Client 2.0，社群導向也相較有趣很多，另外 Apollo 背後用 Observable 實作相當不錯。

a. REST + GraphQL Hybrid

如果我們直接建立一個新的 GraphQL Server，會造成前端維護的困難，因為要同時處理 REST 與 GraphQL 的結構。為了提供彈性的調整空間，Apollo Client 2.0 抽象出的 Apollo Link 可以解決此類問題，其中 Apollo Link REST (apollo-link-rest or @n1ru4l/apollo-link-rest) 的擴充，讓你在定義 Schema 時可以使用 @rest Directive 整合額外用到的 REST API，而其背後會自動幫你轉換為 REST API 送出，Query 寫起來像是：

// example: GitHub
query userProfile {
  person @rest(type: "Person", path: "people/1/") {
    name
  }
}

透過 Hybrid 的方式間接導入 GraphQL，頁面上新的功能用 GraphQL，部分也可以使用既有的 REST API，但是問題只解決了一半，還是會有上圖發出多個 Requests 的問題，官方套件也特別說明現階段還在開發中，尚未實作完 Mutation 的操作，所以暫時還不是一個很成熟的解法。

b. GraphQL Layer

我們也可以把 GraphQL Server 抽出來放到中間當作 GraphQL Layer，除了可以用來封裝背後任何既有 API Service 外，新的功能也能直接與 Database 溝通，並且將邏輯實作在這台 GraphQL Server 上，最後只提供一個 GraphQL Endpoint 給前端使用。

c. GraphQL API Gateway

New features will be built in a GraphQL Native way, and combined into the existing GraphQL API using schema stitching. — GraphQL API Gateway & GraphQL Native

筆者認為這是目前看到算是 Best Practice 的架構，中間多了一層 API Gateway 的設計，這台 GraphQL Gateway 不直接與 Database 溝通，而是把前端的 Requests 需求往後面的 API Service 送。而後面直接與 Database 串接的 GraphQL Server 稱為 GraphQL Native。

Schema Stitching & Delegate

後面的 API Service 不論你要用 REST 實作，又或是直接使用 GraphQL 更好，能透過 Introspection Query 把 GraphQL Native 定義的 Schema 存放到 Gateway 機器上，一旦 API Gateway 收到 Request 就 Delegate 到 GraphQL Native Service 去，甚至是可以透過 Schema Stitching 的設定，將多個 GraphQL Microservice 合併成一個。

Caching & Error Tracing

API Gateway 除了可以保有現有的架構外，可以在這個層級處理棘手的 Caching 以及 Tracing 問題，因此 Apollo 也提供 Engine 服務來幫你做掉這塊，詳情可以參考：

Introducing Apollo Engine: insights, error reporting and caching for GraphQL

Conclusion

這篇文章簡單整理了幾種可能的架構方法，新專案還沒有正式的啟動，算是 2018 的新年許願，希望能夠正式導入 GraphQL，也透過這次的 Survey 看到不同的設計理念。最後一個 Gateway 架構雖然是相較最彈性的，但也伴隨系統的複雜化，最後會評估團隊人力狀況做出不同的決定，如果對後續筆者專案採用的架構有興趣，歡迎關注並訂閱 Medium 喔！

Further Readings

1. GraphQL Microservice with Apollo — 使用 GraphQL 獲取 Medium 最新文章列表

References

1. How do GraphQL remote schemas work? — Understanding GraphQL schema stitching (Part I)
2. GraphQL Schema Stitching explained: Schema Delegation — Understanding GraphQL schema stitching (Part II)
3. Apollographql Docs
4. GraphQL schema stitching / GitHub
5. The GraphQL stack: How everything fits together
6. GraphQL vs. REST
7. How to GraphQL? — Big Picture (Architecture)

若要模擬網頁操作，以往多半會採用 Selenium 等工具進行開發，無論安裝速度或啟動時間實在是有點緩慢，現在有了 Chrome Headless 讓整體流程順暢許多。本篇就由 Node.js 封裝的套件 Puppeteer，以及近期接觸的三個案例，快速簡介有什麼樣的應用。

Headless Chrome is shipping in Chrome 59. It’s a way to run the Chrome browser in a headless environment. Essentially, running Chrome without chrome! It brings all modern web platform features provided by Chromium and the Blink rendering engine to the command line. — Getting Started with Headless Chrome.

#1. End-to-end testing with Jest in Travis CI

前陣子做了個 GitHub Polls App，可以讓你在 Issue 中使用 /polls 指令來額外加載一個現成的投票系統 Gh-Polls (by TJ)。做的事情其實很簡單，當 Issue 新增或修改時，透過 Webhook 將所下達的指令轉換成 Markdown 取代原有的 Content：

Probot on Twitter

Create polls in your discussions on GitHub with `/polls` thanks to @evenchange4 https://t.co/WvrkdxJT2v https://t.co/paAD1AOLbT

雖然只是個 Side Project，但我還是想做點簡單的測試，確保系統是穩定的運作，因此我嘗試了使用 Puppeteer 與 Jest 做整合，寫一點簡易的 Script 走過 登入、新增 Issue、Content Assertion、關閉 Issue，並且搭配 Async/Await 的語法讓整個流程更為直覺，測試大致會像是這樣：

// jest.test.js

it('should create a Polls label', async () => {
  // Login
  await page.goto('https://github.com/login')
  await page.type('input#login_field', ACCOUNT)
  
  // ...

  const labelTitle = await page.$eval('#selector', el => el.title)
  expect(labelTitle).toBe('Polls')
})

上左動畫圖演示的是平常打開 Slow motion 的開發模式，啟動時會跳出藍色 Icon 的 Chrome 視窗，並且放慢操作速度。另外，也可以設定 Headless 參數讓測試跑在 CI 中，因為不需要啟動 Chrome GUI，整合 Traivs Cron Jobs 每天跑一次，每次只需花費一分鐘。

puppeteer.launch({
  headless: true, // default
  slowMo: 0,      // default 
});

至於 Jest 與 Puppeteer 的整合安裝與配置建議可以參考文章：

End-to-end Tests that Don't Suck with Puppeteer - Ropig

#2. Website crawler as an API service

如果有爬蟲的需求也可以透過 Puppeteer 來處理，雖然 Node.js API 已經可以很簡單的一步驟一步驟撰寫 Scripts，但是每次寫起來也是蠻煩瑣的，因此我做了一個 Microservice 讓你可以透過 URL 定義 Action query（Click-and-wait）來操作網頁，最後只返回你感興趣的資訊，蠻適合拿來處理 SPA 類型網站，因為其實就是一個簡單的 Pre-render Service。

這個專案封裝了 Docker Image 並且 Deploy 到 Now.sh，因此直接在 Container 裡面執行 Chrome Headeless 也是沒有問題的！只是要注意可能會碰到 Linux Sandbox 的問題，記得要多一些設定：

puppeteer.launch({
  args: ['--no-sandbox'], // for docker
});

#3. SPA pre-render tools

我之前在『React Stack 開發體驗與優化策略』中簡介 CRA（Create-react-app）搭配基於 jsdom 的 React-snapshot 來進行 Pre-render 來優化 SEO。但其實 Pre-render 還有很多實作可以參考，例如也有人用 Puppeteer 做了相似的套件 React-snap。有興趣可以直接去看看最近轉換過去的 PR，這邊就不再做詳細說明了。

Conclusion

Puppeteer 對於 Javascript 開發者非常的方便，但畢竟是 Chrome 所封裝的工具，如果你要做跨瀏覽器的測試就沒辦法了，不過因為速度上很有感還蠻值得一試的！現階段也將公司的專案導入 Puppeteer 作為 E2E 的測試工具，如果之後有更近一步的研究心得，也會整理並分享出來，有興趣歡迎訂閱我的 Medium 文章喔！

References

1. End-to-end Tests that Don’t Suck with Puppeteer
2. React Stack 開發體驗與優化策略

＊如果你喜歡這篇文章，別忘了可以點個 👏 👏 👏 讓我知道喔！

下半年最有趣莫過於 K8S 的認識，台灣社群也蹦出好多相關的活動，除了 K8S day 之外也有 Kubernetes 101 — 半小時理解 Pokemon 背後的開源容器技術 一連好幾天有大神分享的活動，激起我想要了解架構層的興趣，本篇主要是學習過程紀錄。

Kubernetes

左架構圖雖然乍看複雜，但其實中只要認識其中幾個基本的元件：

1. Cluster：由紫色 Master 來管理底下橘色的 Node。
2. Pod：對 Container 再一次封裝，之後如果要 Scale，就會自動新增刪減 Pod，是 Immutable deploy 的最小單位。
3. Service：Pod 運行後需要透過定義 Service 才能讓外部的使用者訪問。

Install

學習上最快速方便的方法是，直接在本機端安裝單機版 Minikube Cluster ，因其安裝在 VituralBox 內任你盡情把玩。安裝 kubectl 工具稍後能進行簡易的 K8S API 操作。接著，透過 start 將 Cluster 於背景運行就能看到 Dashboard 介面：

# Install virtualbox https://www.virtualbox.org/wiki/Downloads
$ brew cask install minikube
$ brew install kubectl

$ minikube start
$ minikube dashboard

部署 Docker Image

可以選擇從 Dockerhub 下載 Image 到你的 Cluster 中，這邊使用筆者一個 Side Project Docker Image 來示範，最後會看到 Deployment / Pod 列表多了個運行中的項目：

$ kubectl run medium-api \
  --image=evenchange4/micro-medium-api:latest \
  --port=3000
$ kubectl get deployments
$ kubectl get pods -o wide

揭露 Service

Pod 中的 Container 雖然已經運行了，但外部的使用者並不能訪問到，因此接下來要 Expose Service。透過 Minikube 的指令能方便查詢 VitrualBox 的 IP 以及 Service ，最後會自動打開瀏覽器頁面，下右側圖即為 Side Project 的頁面，能夠透過 GraphQL 查詢 Medium 的文章列表，有興趣可以參考 GraphQL Microservice with Apollo：

$ kubectl expose deployment medium-api --type=LoadBalancer
$ kubectl get service
$ minikube service medium-api

Scale

雖然單機版環境只有一個 Node，依然可以模擬如果要 Scale 成兩個單位的 Pod，可以透過 replicas 參數來配置。一旦設定完畢，K8S 就會幫你自動新增一個 Pod，又或是自動把多餘的 Pod 關閉，因此不必自己擔心 Pod 的 Lifecycle：

$ kubectl scale deployment/medium-api --replicas=2
$ kubectl get pods -o wide

Rolling 版本更新

Container 是基於 Docker Image 的 Tag 做控制，所以可以透過指定 Tag 來達到 Rollout 機制，例如這邊把原先吃 Latest Tag 降版為 2.1.0，也可以透過 undo 來達到 Rollback 效果：

$ kubectl set image deployments/medium-api \
  medium-api=evenchange4/micro-medium-api:2.1.0
$ kubectl rollout status deployments/medium-api
$ kubectl rollout undo deployments/medium-api

其他指令

當然還有其他很豐富的用法，例如追蹤 Log、到 Pod 內進行 Debug 等等，特別推薦 Oh-my-zsh 使用者安裝方便的 Autocompletion Plugin：

# Logs
$ kubectl logs --follow <POD-NAME>

# Execute Commands
$ kubectl exec <POD-NAME> -it -- ls

# Kill
$ kubectl delete service medium-api
$ kubectl delete deployment medium-api
$ minikube stop

# zsh pulgin
# plugins=(kubectl)

Cofiguration file

到這邊你可能會覺得想要部署服務，還要透過上述的指令一一操作未免太麻煩，所以 kubectl 其實能使用定義好的 YAML 格式檔來執行指令。例如這邊先匯出之前操作的 Expose Service 動作，並嘗試重新使用 service.yaml 來建立 Service：

$ kubectl get services medium-api -o yaml > ./service.yaml
$ kubectl create -f ./service.yaml

雖然可以透過單一 YAML 檔案來取代繁複的 Commands，但是 YAML 檔案要怎麼生出來呢？大部分情況是需要手動去進行撰寫配置的。緊接著又冒出另一個問題，如果我要更新一個新的版號，是不是就得產生一份新的 YAML 檔？

所以，我們需要透過 Helm 來幫忙把整個服務的配置 Pre-Cofiguration，並且把盡量把 YAML 檔案定義出 Template，如此一來就能重複地使用同一份設定配置了。

Helm & Chart

Helm 等同於前端開發常用的 Npm，只不過安裝的東西不是套件而是一個運行服務，而 K8S 這邊把整包服務稱作 Chart，事實上類似 package.json 定義出 Chart.yaml 來描述系統的架構。

Install and setup

Helm 主要分為 CLI Client 與 Tiller Server ，可以透過 init 指令會幫你在 Cluster 中快速地建立環境與配置：

$ brew install kubernetes-helm
$ helm init

Use a Chart

當然，我可以一鍵安裝別人提供的 Chart，例如我要在 Cluster 建置一個 Wordpress Chart 是什麼感覺呢？官方的 Chart Repository KubeApps 有一個 Wordpress 的穩定版可以下載使用：

$ helm install stable/wordpress

打完下班。可以看到下左圖 Wordpress Chart 運行了兩個 Service，分別為 Mariadb 以及 Wordpress Server，右圖為跑起來的頁面。

但是多半時候可能想要設定一些參數做客製化，Wordpress Chart 就有提供後台相關的變數供設定，透過 set 參數來進行覆寫，又或是直接透過 values.yaml 來一次給定所有的參數，詳情可以參考 Wordpress Configuration。

$ helm install \
  --name my-release \
  --set wordpressUsername=admin \
  stable/wordpress

# or
$ helm install \
  --name my-release \
  -f values.yaml \
  stable/wordpress

Define your Chart

Helm 提供快速 create Chart 的指令， 並且可以透過 --dry-run --debug 來預先瀏覽產出的設定是不是你想要的，確認後才真正的執行安裝：

$ helm create mcs-lite-chart
$ helm install . --dry-run --debug
$ helm install . --name mcs-lite-chart

可以看到上右圖 Create Chart 指令所建立出來的資料夾，真的就是幾個 YAML File 所組成的，因此提供一個很好的格式化管理方式，也可以用 Helm Linter 檢測，複雜的系統肯定要花更多功夫設計這份 Template！

如果你想要了解 Chart Template 的每個元件，建議可以跑過 The missing CI/CD Kubernetes component: Helm package manager，慢慢地一步驟一步驟跟著學習。

Deployment Version Control

使用 Helm 管理 Chart 除了可以參數化 K8S 設定檔外，另外一個重點是版本控管。上版的時候可以用 upgrade 重新部署 Chart，有點類似 kubectl rollout 的機制，但是這邊是整個系統 Deployment 層級的版本控管，因此也可以隨時 rollback 回到上一次的版本：

$ helm ls
$ helm upgrade mcs-lite-app .
$ helm rollback mcs-lite-app 1

最後你可以自架 Helm Repository 提供你的 Chart.yaml，也可以透過 package 指令打包目前的 Chart 資料夾，進而交付給使用者去下載安裝：

$ helm package . --debug -d ./charts
$ helm install ./charts/mcs-lite-chart-0.1.0.tgz

後記

前陣子在玩 Zeit 的 Now.sh，發現跟 K8S 的指令非常相像，感覺背後應該也是 K8S 的技術。架構這種東西很燒腦也很好玩，如果流程建置的很完善，身為前端工程師平常應該是不會碰觸，但為了避免錯誤的想像，自己玩過會比較有感一點。我覺得十分鐘系列的懶人版對於想了解但不需要自己操作的人很有幫助，因此稍微紀錄一下順便與前端團隊分享。

Further Readings

1. Microservice 產品交付 — Dockerize 與 Zeit JavaScript 跨平台解決方案
2. GraphQL Microservice with Apollo — 使用 GraphQL 獲取 Medium 最新文章列表

References

• The missing CI/CD Kubernetes component: Helm package manager
• Using Helm to deploy to Kubernetes
• Helm Quickstart Guide
• 十分钟带你理解Kubernetes核心概
• Kubernetes basics / Hello minikube
• https://github.com/kubernetes/charts/tree/master/stable/wordpress

Thanks to Lynn Lin, 施舜元, 李孟修 and Daniel Tseng.

星期三參加了由優拓主辦的 GraphQL Taiwan 社群小聚 #1，沒想到蠻多公司都有在使用，各種資源都蠻到位的，觀望很久也躍躍欲試，大大們都鋪了幾年的路了，還不上車嗎？現場跟其他工程師交流，也有跟 MediaTek 情況蠻類似的公司，專案由前後端分離的團隊個別負責，要導入 GraphQL 早已經不是技術上的問題，人力工作分配影響更廣。

這篇文章主要從前端角度驗證，能不能在既有系統下，Client Side、API Server 中間再多增加一層 GraphQL Server，而我 DEMO 上拿 Medium API 來使用，架構大致如下圖所示：

Medium API

用 Medium 撰寫文章很方便，但就是不知道為什麼官方都沒提供獲取文章列表的正常 API，目前有兩個方向：

1. RSS XML：但 Parse XML 有一點麻煩，而且我只要要列表 Title 以及 URL 就好。範例： https://medium.com/feed/@evenchange4。
2. JSON String：其實是有返回 JSON 的隱藏 API，但應該是為了JSON Hijacking 安全性問題，開頭多塞了 ])}while(1);</x> 字串，並且限制不支持 CORS 資源共享。但事實上文章列表本來就只要拿 Public 的，所以我在 Server Side 把格式做了簡單的轉換。範例：https://medium.com/@evenchange4/latest?format=json&limit=10。

GraphQL Schema

因為是第一次開發 GraphQL Server，問了其他開發者建議直接用 Facebook 的 Graphql-JS 來使用，寫起來像是一個個 Object 的定義，為了感受一下結構，挑了有名氣的真的假的 Rumors-api Open Source 來看，剛開始看眼花繚亂的，但因為我要做的 Side Project 其實非常的簡單，所以最後拿 Apollo 的 GraphQL-Tools 來定義 Schema，用起來簡潔多了。

GraphQL-Tools 只要定義好兩件事情：Type 與 Resolver。

1. Type

其實就是一個 String，用來表示 GraphQL 型別的語言。Medium 文章的定義如下 typeDefs 所示，其中還可以自己宣告 type 或是用 scalar 來擴充基本型態：

const typeDefs = `
  scalar Timestamp

  type Content {
    subtitle: String
  }

  type Post {
    id: ID!
    subtitle: String!
    content: Content!
    firstPublishedAt: Timestamp!
  }
`;

2. Resolver

定義取值的函示，可以返回 Promise 或是 Value。實際 Query posts 的時候會向 Medium 打 API，接到返回的 Response 來做後續處理。又或是想把巢狀的資料扁平化，新增一個 subtitle 欄位，就是返回一個 Value：

const resolvers = {
  Query: {
    posts: (obj, { username }, context) =>
      API.getPost(username).then(...),
  },
  Post: {
    subtitle: R.path(['content', 'subtitle']),
  },
};

最後，透過 GraphQL-Tools makeExecutableSchema 來生成 schema。也因為GraphQL 是強型別，所以測試的時候可以把 Type 定義的資料都 Mock 掉，例如預設 String，測試時就會產生 "Hello World"

const { makeExecutableSchema } = require('graphql-tools');
const schema = makeExecutableSchema({ typeDefs, resolvers });

// Mock for test
const { addMockFunctionsToSchema } = require('graphql-tools');
addMockFunctionsToSchema({ schema });

Apollo Server

小聚議題上有提到，Apollo 維護了數種 Server Framework 的 Plugin，同樣的接口真的很方便。我挑選非常輕量的 Zeit Micro 來實作，因為範例實在太精簡了，文檔一字不刪直接貼過來：

import { microGraphiql, microGraphql } from "graphql-server-micro";
import micro, { send } from "micro";
import { get, post, router } from "microrouter";
import schema from "./schema";

const graphqlHandler = microGraphql({ schema });
const graphiqlHandler = microGraphiql({ endpointURL: "/graphql" });

const server = micro(
  router(
    get("/graphql", graphqlHandler),
    post("/graphql", graphqlHandler),
    get("/graphiql", graphiqlHandler),
    (req, res) => send(res, 404, "not found"),
  ),
);

server.listen(3000);

其中 schema 即為上個段落最終生成的結果，這邊還做了另一件事是快速 Setup GraphiQL 作為開發使用。

Per-request Memory Cache

小聚最後一個議程 Daniel Tseng 介紹的 Dataloader，可以幫助 GraphQL 提升效能。設定上可以在 microGraphql 中進行傳遞，如此一來每個 Resolver 都能透過 context 來共享同一份 Dataloader Instance 來達到 Memory Cache 目的，記得把原本 Object 參數改為 Function 使用：

const graphqlHandler = microGraphql(() => ({
  schema,

  //  Per-request basis
  context: {
    loader: new DataLoader(...),
  },
}));

Query: {
  posts: (obj, { username }, context) =>
    context.loader.load(username).then(...),
},

Fetch to Apollo-Fetch

議程上也有提到 Apollo Client 的輕量套件，封裝的跟原本 Fetch 很像，使用起來很簡單，但比較複雜的前端架構下次可能就會試試看用 React-Apollo 來管理了：

const uri = 'https://micro-medium-api.now.sh/graphql';
const apolloFetch = createApolloFetch({ uri });

apolloFetch({
  query: `query PostQuery($username: String!, $limit: Int!){
    posts(username: $username, limit: $limit) {
      title
      firstPublishedAt
      url
      content {
        subtitle
      }
    }
  }`,
  variables: `{
    "username": "evenchange4",
    "limit": 100
  }`,
})
.then({ data } => { this.setState(...) })
.catch(error => { ... });

後記

直接打別人的 API 來封裝實在也不太好，所以後來還補上了 Rate-limit 的 Middleware 來限制每個 IP 一秒只能打一次 Request，有興趣可以去看看 GitHub Source Code。

很久沒寫後端 Server 了，因為 GraphQL 實在太紅，後端相關的 Framework/Library 都想試著玩玩看，一開始還搞不太清楚套件彼此間的關係。透過這樣一個 Side Project 來簡易的驗證 GraphQL Server 的可行性，希望有朝一日也能運用在公司專案上！

Further Readings

1. Microservice 產品交付 — Dockerize 與 Zeit JavaScript 跨平台解決方案
2. 使用 CircleCI 2.0 Workflows 挑戰三倍速

References

1. GraphQL Taiwan Meetup 001 — GraphQL
2. GraphQL Taiwan Meetup 001 — Dataloader

＊完整的專案放在 Evenchange4/micro-medium-api，如果你喜歡這系列文章，關於 Michael 在 OSS 專案開發心得，別忘了可以點個 👏 讓我知道喔！

Thanks to Lynn Lin and Daniel Tseng.

繼上一篇，使用 CircleCI 2.0 Workflows 挑戰三倍速 中將 Docker 導入 CI 設定測試環境外，這次著重在 CD 與產品交付，也試著使用 Docker 來建置 Production 機器，並且提交到其他服務平台上。

選擇交付方式

首先，從使用者最終會拿到什麼討論。產品交付有很多手段，常見可以透過部署公有雲、上架 APP 或是發布套件等等，另外也有像 MediaTek IoT Cloud 離線版，整體架構採用 NW.js 來開發桌面程序，只要幾個點擊就讓前端網頁以及伺服器端運行起來，並且輸出跨平台的執行檔。

當不需要 GUI，或單純想把 HTTP Service 專案跑起來，常碰的問題在於執行時所造成不可預期的錯誤，因此可以考慮連同執行環境一同交付。採用 Docker 來封裝是一個不錯的選擇，只要提供 Image，就能夠透過統一的接口來執行 Container。另外一種方法是本篇將提到 Zeit 的 Pkg，透過 Node.js 輸出 Binary 執行檔的做法。

JavaScript 的解決方案

開始關注 Zeit 是因為其前端的 Next.js 框架，Zeit 專案幾乎都是 JavaScript 實作的，所以對於前端工程師要追 OSS 原始碼非常地方便。他們在這一兩年也持續不斷地推出其他非常實用的產品，每當發布 Twitter 就是一陣好評，是一個值得學習的組織。

Zeit 旗下產品有一個很大的特性，只專注於處理單一事情上，接口也設計跟他的 Logo 一樣的簡潔，這一點非常符合 Microservice 的特性。本篇文章也是基於其底下產品的使用心得分享。

另外還有很多由社群開發的延伸套件與工具，可以查看 Awesome-zeit 列表，而這次我也做了兩個 Side Project Microservice 來驗證這整個流程，可以參考並玩玩看，接下來段落會討論四種部署方法以及工具：

1. Micro-medium-api：封裝 Medium API，撈取文章列表 [DEMO]。
2. Micro-github-release：下載最新的 GitHub release asset [DEMO]。

Micro

Asynchronous HTTP microservices.

Micro 8

透過 Micro 要建立一個 HTTP Service 再簡單不過了，只要揭露一個 Handler Function，就能快速地跑起來。可以參考上面 Micro 8 的文章，Zeit 是怎麼針對 HTTP Server 進行優化的，主要把 HTTP Server 分為 Production 使用的 micro 以及 Development 使用的 micro-dev。開發上如果是 Node 8.0 以上版本，就可以直接寫 async/await 語法：

// index.js
const handler = async (req, res) => {
  const response = await fetch('http://...')
  return response.json()
};

module.exports = handler;

單一職責的 Microservice 設定單一 Entrypoint 來處理 Request 應該就足夠，如果有 Routing 的需求，可以使用社群開發的 micro-router，至於 Middleware 部分其實就是層層的 Function Composition，可以使用 Ramda 來達成：

// index.js
const R = require('ramda');
const { router, get } = require('microrouter');

const enhance = R.compose(
  cors({
    allowMethods: ['GET'],
    origin: '*',
  }),
  compress,
)

module.exports = router(
  get('/:id', enhance(handler)),
)

執行上用 npm script 來區分，本機端使用 npm run dev，當你部署到正式環境，就可以直接執行 npm start：

// package.json
"scripts": {
  "start": "micro",
  "dev": "micro-dev"
}

雖然 Micro 實做上很簡單，處理稍微複雜的系統，也可以有很不同的玩法，建議可以瀏覽 Awesome-micro 來看看其他人是怎麼設計 Microservices 的。

a. 𝚫 Now.sh Service

Realtime global deployments.

部署前端專案雖然我還是最推薦 Netlify 的服務，不過其只能 Serve Static Files，因此通常有 Server 需求的專案，就必須找一些 PaaS 來使用。因此推薦 Now.sh，他們的服務非常的精簡，包含部署上也不太需要什麼設定，比起以前用過類似的 Heroku 服務簡單很多。

簡易的 JSON 設定格式

專案若是 Node.js Server，就直接透過預設的 npm 方式進行部署，特別要注意加上 NODE_ENV=production，才不會下載太多非必要的開發套件，也可以透過下方範例中的 env 來設定。當然，較複雜的環境或甚至是非 Node.js，Now.sh 也支援透過 Docker 來設定專案的環境，只要將 Dockerfile 推上 Now Service，就會建置 Docker Image。最後透過 now-cli 快速部署：

// package.json
"now": {
  "type": "npm", // or 'docker'
  "env": {
    "NODE_ENV": "production"
  }
},

# now-cli deploy
$ now

Subdomain Alias

因為 Now.sh 預設新增專案都會自動產生含一串 Hash 的網址，如果想要讓網址看起來簡單一點，可以註冊一個 Subdomain，只要透過下方的 alias 設定即可，然後同樣透過 CLI 執行：

// package.json
"now": {
  "alias": "mcs-lite-app"
}

$ now alias

Instance automatically scaled

Now.sh 服務有一個 Sleep 機制，每當一段時間沒有流量或是超過你的 Instances 額度，就會暫時被 Frozen 直到下次啟動，如果你需要也可以將專案設定一個最大最小的範圍，讓 Now.sh 幫你依需求自動設定，又或是只設定最小 Instance 1 就不會暫停了：

$ now scale mcs-lite-app.now.sh 1

Continuous Delivery

官方提供完整的 Now CLI 套件，也可以拿來串接 CI，每當測試成功就執行部署到 Now.sh 上。下方流程中透過 Wait for ready 的指令，等待新的網站佈署成功，中間可以加上一點 End-to-End 測試，完成後將 Alias 指向新的 Instance，最後才把舊的 Instance 砍掉，來達到 Zero Downtime 的目的：

// .travis.yml
after_success:
  # 1. Wair for deployment ready
  - URL=$(now --public)
  - await-url $URL

  # 2. Alias and purge old services
  - now alias set "$URL" "$ALIAS"
  - now rm $PROJECT --safe --yes

Now.sh 對於 OSS 專案雖然是免費的，仍然有使用量限制，另外也沒支援 Docker Compose 或是多個 Port，不過還蠻適合拿來放一些 Side Project 或是 Demo page 的。特別要注意如果有用 DB 在每次重新部署都會洗掉，可能要搭配其他 Database 服務一併使用。

Deploy Button

由社群開發的，類似 Heroku Deploy Button，可以放在 README 文件上讓使用者一鍵快速部署自己專屬的 Microservice，可以參考左圖 MCS Lite Demo 在文件上的部署流程。

b. Pkg

Package your Node.js project into an executable.

將 Node.js 執行環境也一並打包，只輸出單一執行檔，如此一來使用者就不需要額外下載 Node.js 環境。可以透過 package.json 來設定 Binary 的執行入口，接著透過 pkg 指令就能輸出預設的三種平台的檔案：

// package.json
"bin": "bin/server.js"

$ pkg . --out-path pkg

> pkg@4.2.2
> Targets not specified. Assuming:
  node8-linux-x64, node8-macos-x64, node8-win-x64

交付上，透過 TravisCI 設定自動部署，一旦有 Git Tag 推上 GitHub，就將 Pkg 輸出的執行檔上傳到 GitHub Release：

// .travis.yml
deploy:
  provider: releases
  api_key:
    secure: ...
  file_glob: true
  skip_cleanup: true
  file: "./pkg/*"
  on:
    repo: evenchange4/micro-medium-api
    tags: true

c. NPM Release

Node.js 使用者肯定偏好使用 NPM 來安裝，既然在上個段落 Pkg 已經設定好 package.json 的 bin 檔，那不如就順便把它給 Release 到 NPM 上吧，同樣透過 Travis 來做交付：

// .travis.yml
provider: npm
  email: evenchange4@gmail.com
  api_key:
    secure: ...
  on:
    repo: evenchange4/micro-medium-api
    tags: true

CLI Argument

關於接口設計上，之前有用過其它套件做過，但都沒有 yargs 套件開發時來的簡潔，建議可以試試看。當然，最後也可以直接輸出當作文件用：

$ micro-medium-api --help
Usage: micro-medium-api <command> [options]
 
Options:
  -p, --port     HTTP server PORT       [default: 3000]
  -h, --help     Show help              [boolean]
  -v, --version  Show version number    [boolean]

一旦有套件更新，使用者要怎麼知道呢？推薦使用 update-notifier 來幫你達成，其實最新的 npm 5 也是用這套來做的。在你的執行檔入口中，預先跑過版本檢查，當使用者下指令時就會跳出如下圖資訊：

// bin/cli.js
const updateNotifier = require('update-notifier')
const pkg = require('../package.json')

updateNotifier({ pkg }).notify()

d. Dockerize

Server 環境問題是專案初期設定上的盲點，要一勞永逸地解法就是封裝 Docker Image。目前許多平台都早已支援使用 Dockerfile 進行設定了，包含各大 CI/CD 服務工具等等。以下 MCS Lite 為例，其中封裝了運行環境、執行程序，最後只揭露 Port 即可。當使用者建置完 Docker Image 後，就可以簡單地使用 Docker Run 指令執行 Container：

# Dockerfile

FROM node:6.10.3
RUN ...
EXPOSE 3000
ENTRYPOINT ["npm", "start"]

$ docker run --rm -it -p 3000:3000 -p 8000:8000 mcslite/mcs-lite-app

DockerHub Automatic Build

除了在本機端下載 Dockerfile 建置 Docker Image 外，也可以透過 DockerHub 自動地將 Image 預先建立好，其他人就能直接下載使用。左圖使用 DockerHub Automatic Build 功能，也就是能夠連動放在 GitHub 上的 Dockerfile，一旦 GitHub 有更新就會 Trigger DockerHub 建立出新的 Image，當然也可以設定 Git Tag 來做版本控制。

Multi-Stage Builds in Docker Cloud

Multi-stage Build 是 Docker 17.05 的新功能，可以設定建置、測試以及最後 Runtime Stage 來自不同的 Image，來達到最終揭露的 Image 最小化的目的。下方的 Dockerfile 可以看到有兩個 FROM ，輸出後從原本 266 MB 縮減為 16MB：

# Dockerfile

# Build 266 MB
FROM node:8.2.1 AS builder
RUN npm install

# Runtime 16 MB
FROM mhart/alpine-node:base-8.2.1
COPY --from=builder /app .
CMD npm start

又舉例來說，你可能需要 Node.js 環境來建置前端靜態檔案，但是最終在 Server 上只需要 Python 跑 Web Server，就可以用這個方法讓 Production Image 有 Python 但不包含 Node.js 環境。可惜目前在 DockerHub 上仍然是 Docker 穩定版號 17.03，所以並不能使用。根據 Issues#1039 討論，看來要能等到 Multi-stage 支援遙遙無期，官方也沒辦法給個確切的日期，反倒是看到很多文章都在推 Docker Cloud：

Multi-Stage Builds - Docker Blog

Docker Cloud 是 Based on DockerHub 所開發，因此介面與功能上幾乎都有涵蓋到，並且多了許多設定可以做選擇，例如下圖可以選擇 Docker 版本。但缺點是需要登入才能看到 Dashboard，對於 OSS 專案資訊不夠透明：

另外在 Automatic Build 的設定上也多了一點彈性，例如想要將 npm 習慣上的 Git Tag v1.0.1 轉換成 1.0.1，也就是去掉 v 開頭。如此指定 Docker Image 版號時也比較符合一般大眾的格式 Image:1.0.1。

後記

透過 Side Project 驗證的四種部署方式，才會真正的思考如何交付才能最順暢。將專案設定 Docker 也可幫助整合測試，例如以往要將前後端分離的數個專案跑起來才能進行 End-to-End 實測，封裝後就能簡單地跑起來。

下一步，也許會參考幾個 OSS 專案對於 Now.sh 與 GitHub 的整合，來模擬看看 Staging Continuous Deployment 的功能，如果你對後續嘗試感興趣，可以關注我的 Medium 喔。

最後，工商時間。快試試建置您專屬的物聯網雲平台吧！

MCS-Lite/mcs-lite-app-demo

Further Readings

1. 使用 CircleCI 2.0 Workflows 挑戰三倍速
2. React Stack 開發體驗與優化策略
3. Build A Web App in MediaTek

References

1. Deployment lifecycle and Scalability in now
2. sholladay/await-url

＊完整的專案放在 MCS-Lite/mcs-lite-app-demo 以及 evenchange4/Micro-github-release，如果你喜歡這系列文章，關於 Michael 在 OSS 專案開發心得，別忘了可以點個 ❤️ 讓我知道喔！

CircleCI 2.0 雖然出來一年多了，不久前七月初才正式 Launch，聽說加速不少，並且基於 Docker 以及 Workflow 設定模式，與公司內部的 DroneCI 設定起來蠻相似的，所以來試試看。

專案背景簡介

這是 MediaTek IoT Cloud 開源專案之一，文章討論的設定專注於前端的部分，基本上皆為 JavaScript 實作。此專案屬於 Monorepo 性質，也就是一個 Repository 包含數個 Project (Website) 或是 Library (NPM)。

在年初的時候因為還是 Private 狀態，當時考慮了 Circle 1.0 一個 Private 免費額度來作為主要 CI，開源後換到主流的 Travis，畢竟整合的服務較為完善，策略上兩個 CI 同時分別跑一部分的 Job，然後再設定 GitHub Protect 功能，必須都要綠勾勾才能 Merge PR。

以下作為數據參考：

• Project 頁面類型數量：4
• Library 類型數量：12
• Test File 數量：262、Coverage: 87%

// jest
Test Suites: 225 total
Tests:       628 total
Snapshots:   479 total

CircleCI 2.0 VS Travis Beta

本篇文章一部分在於 Travis 與 Circle 2.0 的比較。雖然 Travis 也可以用 Docker，但是其整合的還不完整，基本上都要用 docker run 來執行 Script；Travis 也同樣提供 Stage Jobs 的概念，但仍然在 Beta 階段，我實際玩起來並沒有加速到反而變慢，所以最後選擇用 CircleCI 2.0。

CI 做了哪些事

a. Dependency Install

安裝 NPM 相依套件，全篇都以 Yarn 來作為 NPM Client 進行討論。

b. Bootstrap

使用 Lerna 進行 Monorepo 管理，其中最關鍵的步驟在於 Hoist Bootstrap，把所有子目錄的 node_modules 都提升到根目錄去，若彼此之間若有相依性會透過 Symbolic Link 關聯起來。最後把所有子目錄使用 Babel 轉為 CommonJS Module。

c. Lint

包含了 JavaScript Coding Style 的 Eslint、CSS Coding Style 的 Stylelint 以及少部分 Static Type Checker 的 Flow。

d. Unit Test

絕大部分都使用 Jest 做 Snapshot Testing。

e. Building Test

除了功能性 Unit Test 外，另一個重點是要測試頁面建置過程（Webpack）有沒有問題。

如上圖，將 Job 切分為上個段落的 a~e 個步驟，以往依序執行將會是這些片段時間的總和，大致會是 7 分鐘。

事實上，除了 a 與 b 是需要預先跑完才能往下執行外，其他步驟皆可獨立執行，因此可以採取 CircleCI 2.0 的 Workflows，預設免費可以同時跑 4 個 Job，所以切成四個恰恰好。如此一來，整體所需時間就會是 a + b + d 的總和，差不多三分半。

理論上，單純透過 Parallel Job Execution 就能加速兩倍左右。

CI 還做了哪些事

環境設定

最重要的就是開發時的版號能夠固定，這樣一旦發生錯誤時才能將範圍縮小。如果是 Travis 或 CircleCI 1.0 的設定方式是透過 YAML 設定 Node.JS 版號，但是像是 Yarn 的版號就比較麻煩，寫起來大概像是：

以往會需要自己寫些 Script 來判斷 Yarn 的環境，進行鎖版的動作。那如果是 CircleCI 2.0 則是使用 Docker Image，設定起來簡單很多：

# .circleci/config.yml
docker:
  - image: node:8.2.1

可以直接使用官方維護的 Node Docker Image 即可，已經預設有把 Yarn 包在裡面。

Caching

Cache 絕對是 CI 的一大重點，在 Travis 時，可以透過簡單的目錄指定來設定哪些檔案要 Cache 起來：

# .travis.yml
cache:
  yarn: true  # Global .cache/yarn
  directories:
    - ~/.yarn # 上個段落安裝 yarn 鎖版用
    - node_modules

雖然 CircleCI 2.0 變得稍微複雜一點，但是功能就更為強大了，例如這邊可以計算 Lockfile 的 Checksum 來指令要哪一包 Cache：

dependency-cache-{{ checksum "yarn.lock" }}

因為是 Docker Based，記得要把 Yarn Cache 目錄設在專案內：

yarn config set cache-folder .yarn-cache

這樣稍後才能把專案內的資料夾做 Cache：

# .circleci/config.yml
- save_cache:
    key: yarn-cache-{{ checksum "yarn.lock" }}
    paths:
      - .yarn-cache

Workflows

在 CircleCI 2.0 的設計中會先把 Job 獨立設定好，而後才會在底下設定 Job 的執行順序與相依性，例如這個專案中會先執行完 a + b (Bootstrap)，才會執行後續的 c、d、e：

# .circleci/config.yml
jobs:
  - bootstrap
  - lint:
      requires:
        - bootstrap
  - test:
      requires:
        - bootstrap
  - test-page:
      requires:
        - bootstrap

不嚴謹的實驗結果

Without cache:

Travis: 12 min
Circle2: 4 min

With cache:

Travis: 9.5 min
Circle2: 3.5 min 🚀

後記

雖然 Travis 與 CircleCI 各有優缺點，像要設定多個 Node.JS 環境來跑還是 Travis 的 Matrix 方便。他們都對於 OSS 非常的有善，基本上免費就很夠用，不如多設定幾個 CI 多一份保障。

下一步，可能會從根本的問題來處理，例如 Monorepo 在最外層設定一個 Test Runner 來跑 Unit Test 就好，減少啟動時間；另外 Lerna + Yarn 的方案之後可以考慮換成 Yarn 新版內建的 Workspace 功能，相信會有更好的整合。未來如果想看這部分的嘗試，可以關注我的 Medium。

本篇文章都沒有提及 CD 的部分，事實上我更推薦使用 Netlify 來做為前端專案的部署，在我之前的經驗中跑得比 Travis 或 CircleCI 還來的快。

Further Readings

1. React Stack 開發體驗與優化策略
2. Build A Web App in MediaTek

References

1. CircleCI 2.0 Documents、Circleci/Frontend Config
2. 減少 node_modules 大小來加速部署 Node.js 專案

＊完整的 Migrate PR 放在 MCS-Lite/mcs-lite，如果你喜歡這系列文章，關於 Michael 在 OSS 專案開發心得，別忘了可以點個 ❤️ 讓我知道喔！