建立前端開發準則,讓團隊能夠有效率的開發好維護的程式碼 —— 均一前端工程師宜陞技術分享

【前言】均一的程式碼基礎 junyiacademy 從 2013 年 fork Khan Academy 原始碼,一直發展到現在,程式碼的複雜度不可同日而語,開發和維護的難度越來越高,很根本而且不好償還的技術債逐漸浮上檯面,有些甚至成為新功能開發的巨大阻力。

於是,我們在 2020 六月決定制定出前端的開發準則,具體行動有停止混用多個框架,使用一致的目錄結構,並為選用的框架及相對應的目錄、檔案制定 style guide。最終希望前端能在有規範情況下,有效率的開發出可維護的程式碼。

行動 1:訂出 Client 端與 Server 端的狀態管理規範

狀態管理一直是複雜的前端專案需要面臨的問題,除了選一個好用的狀態管理工具,也需要為 UI 相關的 Client 端狀態與 API 資料相關的 Server 端狀態設計不同的管理方式。均一在此行動中分為兩階段進行,在階段一我們先選了 Redux(註 1)來統一我們的管理工具,並在階段二中持續優化 Client 端與 Server 端的狀態管理方式:

階段一:使用 Redux 統一狀態管理工具

其實均一的 codebase 中原本就有用到 Redux,但前端的狀態管理方式一直沒有統一的規範,常見的問題像是直接在 React 的 UI 元件中呼叫 API,導致 server 端的狀態邏輯混雜在應該只用來處理 UI 邏輯的元件之中。此外,在 React 推出了 Context API(註 2)之後,到底要用 Redux 還是 Context API 在前端團隊中一直是個懸而未決的大哉問。

因此在訂定狀態管理規範初期,最先開始處理的就是「Redux 有的人喜歡,有的人不喜歡」的問題。在經歷一段時間的研究與一場技術分享之後,考量到許多狀態管理機制在 Redux 中早已實作並有一套明確的 design pattern 可以遵循,對前端團隊來說,與其選擇 Context API 並自行訂定、維護一套狀態管理機制,不如先以設計優良的 Redux 出發,讓均一的團隊成員熟悉這個做法,之後要換其他套件都是可以討論的。

但 Redux 常為人詬病的一個問題就是,只為了處理一些狀態管理需求就需要寫一堆樣板程式,為了優化這個問題,我們採用了 Redux 官方推薦的 Redux Toolkit。使用 Redux Toolkit 中的 Slice 可以大幅簡化需要撰寫的樣板程式。此外,善用 Toolkit 中的 Selector 也讓均一的程式碼更解耦,在疊加新功能時可感受到新架構有更高的開發彈性。

在前面文章提到「直接在 UI 元件中呼叫 API」的非同步問題,則是藉由把呼叫 API 以及相關的 side effect 都搬移到 Redux 的 middleware,讓 UI 元件的邏輯更乾淨。而 Redux 的 middleware 種類繁多,常見的如:Redux-Saga、Redux-Thunk、基於 RxJS 的 Redux-Observable,考量到 RxJS(註 3)的泛用性較高,且在各個語言幾乎都有對應的套件,即使未來不再使用 Redux-Observable 還是可以持續使用 Rx 的概念進行開發,儘管 Redux-Observable 的學習成本較高,最後均一仍選擇了 Redux-Observable。

階段二:使用 React Query 管理 server 端狀態;Redux 只用來管理「複雜」的 client 端狀態

由於觀察到越來越多人推薦以 React Query、SWR(註 4)等套件來處理 data fetching,在訂定 Redux 規範時就持續在關注這些套件的發展,經過前端團隊進行相關的研究與試用後,決定以 React Query 取代 Redux-Observable。此決定的原因一部分是使用 React Query 確實可以少寫非常多樣板程式,讓程式碼變得更簡潔,另一部分則是考量到未來均一打算 migrate 到 GraphQL,而目前 React Query 對 GraphQL 的支援度較佳。

使用 React Query 的另一個好處是可以將 server 端的狀態以及 cache 機制統一交給 React Query 管理,如此一來就能明確的分離 server 端與 client 端的狀態。在大部分的專案中,當把 server 端狀態都交給 React Query 處理後,通常只會剩下少量的 client 端狀態,而 client 端的狀態變少,其實就不太需要使用 Redux 這個專門用來處理龐雜 client 端狀態的管理工具。在理想的情況下,均一的前端只需要 React + React Query 即可進行完善的狀態管理,只有在 client 端狀態較複雜的情況,才會請出 Redux 來幫忙管理。

行動 2:在新專案導入 TypeScript

均一前端團隊長期使用弱型別的 JavaScript 進行開發,TypeError 一直是工程師心中的痛,且在型別未明的情況下,常需要耗費大量的腦中記憶體來記住程式碼中的型別。考量到 TypeScript 的安全性明顯比 JavaScript 來得高,且各大套件也開始 migration 到 TypeScript 或甚至以 TypeScript 為主,均一團隊也開始在 codebase 中導入 TypeScript。

不過均一並沒有在原本的 codebase 導入 TypeScript,而是在新的前端 repo 導入,因此沒有經歷到太多 migration 的痛苦,否則就需要一步一步地將 strict mode 打開,慢慢解 error。而原本使用 JavaScript 的前端 repo,則使用 JSDoc 來進行基本的型別撰寫。

行動 3:制定 style guide

為了讓團隊中的前端工程師有統一的標準能夠遵循,我們開始為選用的框架、技術以及相對應的目錄結構制定 style guide,同時也期待實習生與其他的開發者能夠參考這些規範來上手均一的前端開發,減少因為不同人撰寫的程式碼差異過大導致維護困難的情況發生。

前端的 style guide 以 Google JS style guide 為基礎,在此基礎上針對以下幾個大項目撰寫實作規範:

  1. Naming,如:React handler functions 要怎麼命名
  2. Import/Export module statements,如:import module 的排列順序
  3. File’s implementation,例如:component 要怎麼寫
  4. Framework/Package usage,例如:Material-UI 的 styles API 要怎麼用

此外,我們也訂定了目錄結構的規範,希望能做到當想要改一個功能時,工程師不需要打開編輯器就已經大概知道要去哪個資料夾中的哪個檔案修改。

行動 4:將準則導入開發環境

要讓工程師快速的將 style guide 導入日常開發,我們想到最快的方法就是將這些原則直接透過自動化工具引入團隊成員的 IDE、Git flow 之中。

使用 Prettier 自動排版程式碼

均一長期以來都是透過 ESLint 在進行語法檢查,雖然 ESLint 確實提升了程式碼的一致性,但許多語法錯誤仍須透過肉眼辨識來進行手動修改,為了加速日常的排版工作,我們開始使用 Prettier(註 5)在 IDE 進行自動排版。

過去均一的 codebase 還沒有使用過類似的自動排版工具,因此在全面套用 Prettier 前我們先取一個 package 用 Prettier 進行排版,確定沒問題後,再一次性的將全部的 JS files 都進行排版。此後,前端寫 code 的體驗大升級,無時無刻都受益於 Prettier 搭配 VSCode 的 Format On Save 功能,在過去需要人工判斷的排版問題,現在只要按下 save 即瞬間完成。

使用 code snippet 省去複製貼上程式碼的時間

通常在寫 code 前會去複製貼上其他已符合 coding style 的程式碼,而 code snippet 其實就只是將程式碼的模板做成 snippet。snippet 比較有趣的地方在於,它能夠根據檔名自動將某些程式碼的 naming 設定為對應的文字,例如:component 要叫什麼名字,這也讓 snippet 除了節省複製、貼上、找模板的時間外,也省去了更新 naming 的時間。

在 commit 前檢查排版、語法的正確性

除了前面提到的在 IDE 中使用自動排版工具,在 Git 流程中,我們也設定了 commit 前的自動檢查機制(pre-commit)。最後均一是透過 husky(註 6)這個套件在 pre-commit 階段檢查 code change 是否有通過 Prettier 和 ESLint 檢查。多了這個工具在 commit 前督促工程師做好排版工作,省去不少在 code review 時溝通排版問題的時間。

附帶一提,由於團隊成員的 commit message 也長期沒有統一的規範,我們也為此導入了 Commitizen 來讓大家照著一定的格式撰寫 commit message。

總結與未來方向

建立準則後的差別

訂定了以上準則後,在均一開發前端明顯比過去容易得多。在一致的準則下開發,有更高的確定感,不會再苦於找不到檔案、不知道檔案要放哪、不知道該用哪個套件。此外,遵循設計優良的架構進行開發,明顯感受到模組間的耦合度降低,side effect 減少,在開發時有更高的彈性,對新進成員來說整體的開發環境也比過去友善多了。

未來的規劃

下一階段,均一的前端會使用 Nx(註 7)幫助我們管理 monorepo 中的多個 apps,並將均一常用的元件提取為共用元件,整理到 monorepo 中的 Storybook(註 8)。

另外,我們相信 GraphQL 是未來的趨勢,前端預計會在下一代的架構中使用 GraphQL,選擇技術時也會以該技術是否支援 GraphQL 為考量點。


註解

  1. Redux 是一個善於集中管理前端狀態的套件。
  2. Context API 是 React 負責傳遞資料到各個前端元件的 API,透過 Context API 可實作出類似 Redux 的狀態集中管理功能。
  3. RxJS 是透過 JavaScript 實作的 ReactiveX API。ReactiveX API 集成了 design pattern 中的 Observer pattern, Iterator pattern 以及 functional programming 的概念。
  4. React Query、SWR 都是用來管理前端非同步資料的套件,這些套件善於處理資料的取得、更新與快取。
  5. Prettier 是一套 code formatter,可透過 Prettier 改善程式碼的可讀性與排版的一致性
  6. husky 是一個可在 git commit, git push 階段執行 linter, tests 的開發工具
  7. Nx 是一套用來管理 full-stack monorepo 的開發工具
  8. Storybook 是一套用來管理 UI 元件與頁面的工具

均一招募中!

如果你對前端軟體開發充滿熱忱,而且跟宜陞一樣期待用科技來影響教育,我們正在尋找軟體工程師,馬上到招募頁面查看職位詳情!


作者|江宜陞(均一平台教育基金會前端工程師)
編輯|江芳瑜(均一平台教育基金會實習生)

分享這篇文章:

相關文章

生命的改變從教室開始

在孩子長大成人之前,有將近一半的時間在學校度過,許多孩子的成長與改變也在這裡發生。有些孩子從討厭數學到數學成績名列前茅、有些孩子從討厭學習到願意學習,卻也有些孩子無法前進,不論是學習動機低落、教育資源受限,都是可能的原因之一。

也因為看見了這些孩子的困境,我們希望透過科技的力量,提供孩子們優質且免費的學習資源,落實教育平權,打造一座沒有牆的教室。

我發現,原來教學就該是看見孩子真正需要被幫忙的地方,而不是看教學指引而已。

大同國小.林政琦老師

教室裡的改變

均一在一次次與學校、課輔班的合作中,看到許多成長與改變的故事。

我們看到有孩子從一開始放棄數學、不敢發問,到後來能主動舉手發問,甚至能教其他同學;也看到有老師體悟到成績不是一切,重要的是孩子們的學習態度以及如何面對挑戰與困難。

可能有一些東西並不是,成績單上面看得到的,有的時候我們好像,太在乎這個學生的表現是集中在成績這一塊。

文英國中.李延慶老師

孩子有無限多的可能正在教室中發生,邀請你與我們一起,創造更多免費優質的教育資源,讓更多孩子的未來有好的改變。

你也能一起參與改變

均一是一個非營利組織,為了專注於我們的願景使命,我們不承接政府預算、不發展有對價關係的盈利,仰賴與我們有相同願景使命的大眾捐款支持,期待集合眾人之力,實現真實的共創與共好。

邀請你一起參與 >> 公益支持

不分城鄉,教室裡的學習弱勢

不論在都市或是偏鄉,教室裡都存在著學習弱勢。每個孩子的學習步調、吸收知識速度都不同,如果孩子們沒辦法在教室裡學到適合自己步調與發展需求的內容,都有可能處於學習弱勢。我們希望透過平台上免費有趣的學習影片與習題、科技化的平台輔助功能,讓這些孩子能夠按照自己的步調學習,培養自信找回成就感,發揮原生天賦。

我們藉由課輔班合作計畫與學習扶助計畫,讓更多學習速度不同的孩子,得到差異化的教學,弭平學習落差,並在過程中持續鼓勵、陪伴孩子與教師

課輔班合作計畫

透過與課輔班合作,均一提供平板筆電載具、專業師資培訓與觀課陪伴,協助課輔班老師能以遊戲化的數學學習模式,讓弱勢孩子重拾學習興趣、鞏固基本學力。合作期間,也看到許多老師陪伴孩子的動人故事,我們記錄這些過程與故事,也邀請有興趣的你,點擊下列文章更了解計畫成果,也認識課輔班老師的故事!

有位平常學習上較落後的孩子,跟我分享,是磨數營讓她愛上數學。甚至跟我說 : 努力沒有做不到的事!

屏東躍愛課輔班 林綺漩 老師

學習扶助計畫

在 106 學年度,均一與苗栗縣和屏東縣分別合作進行「結合均一的課中補救」試辦計畫。藉由一般課堂的時間,抽離需要額外學習扶助的孩子到「學習扶助班級」,搭配均一平台的使用,有效診斷學生的學習斷點,提供個人化學習。

經過三年的顯著成效與現場教師的正面迴響,109 學年度起,均一在苗栗、屏東推動學習扶助「深化」模式,除了繼續數學課中學習扶助外,期盼藉由更深度投入的專案教師、更具規模的教師社群、更系統性的增能與支持,為學習扶助的師生帶來更有效的教與學。

學習扶助計畫進行的這幾年,我們不只看見許多孩子學習的進步,更看見許多老師教書育人的理念,邀請你點進下方文章,認識其中一位專案教師的故事。

苗栗文英國中李老師照片

帶孩子走出教室裡的無力感 —— 苗栗延慶老師分享

在眾多均一平台上的老師當中,今天想特別與大家分享延慶老師的故事。延慶老師是「均一課中學習扶助深化專案」的老師,他觀察到,傳統一體適用的教學當中,班級內存在的學習落差影響了孩子的學習信心;透過「課中學習扶助」,老師們能用不同的教學方式,幫助孩子建立學習成就感,以及對未來的信心。

了解更多 »

你也能一起參與改變

均一是一個非營利組織,為了專注於我們的願景使命,我們不承接政府預算、不發展有對價關係的盈利,仰賴與我們有相同願景使命的大眾捐款支持,期待集合眾人之力,實現真實的共創與共好。

邀請你一起參與 >> 公益支持

是老師,也是教育創新家

在均一有一群老師,不只出現在第一線教學現場,分享如何利用平台提供孩子們差異化教學,給學校或課輔班的老師,更設計出多元跨領域的課程,激發孩子們的學習動機。

我們在台灣擴大推廣 Code.org 的 Hour of Code 一小時玩程式,團隊夥伴製作中文化插電與不插電的程式課程、結合創意的教學設計,讓 Code.org 這套全球廣受好評的程式課程,在台灣的使用濃度達到世界排名第九、亞洲排名第二,讓臺灣的程式教育能夠與國際接軌。課程資源與師資培育,都逐步與國際接軌。

「模組化的課程設計,不論對教師教學、學生學習都有很大的幫助;因為課程規劃得很完整,老師能很清楚第一步要如何開始、接下來又該怎麼做,以及背後的教學目標,搭配程式闖關遊戲,小朋友會更有動機去嘗試、思考,甚至他們做完後、還會想再做一次,主動地去複習所學!」

太平國小 陳宜均老師

為了讓孩子透過程式學習運算思維,均一也設計了一系列 Scratch 課程,採取專案導向學習 (Project-Based Learning),以深入淺出的講義或影片引導,經由不同領域主題,’當孩子面對給予的任務,將學習如何解構問題、摘要重點、發現規律,循序漸進地練習程式的思考。

數電快閃教室

數電快閃教室計畫,是團隊夥伴到教學現場透過「數學 X 電腦科學」的跨領域課程,將好玩、互動性高的電腦科學融入數學的課程內容,讓孩子覺得原來數學可以這麼有趣,學到的知識也可以加以應用。均一也透過此課程和現場老師分享跨領域教學,探索更多的學習可能

後續雖遇上五月份的疫情,團隊發揮創意推出「線上快閃教室」,以線上的形式,快閃 18 所國小的線上教室,帶來「自學力就是你的超能力」主題分享,總計有 329 位學生參與,我們希望藉由這個活動,讓孩子在疫情期間能夠找到自己學習的目標和節奏。

當我們 Code 在一起說故事

「當我們 Code 在一起說故事」專案計畫,也就是平台上「電腦科學起步走|一起說故事」課程,是源自 Google 開發的 CS First,均一除了將其中文化翻譯,並且配合 108 課綱將課程內容和教學模組在地化。課程內容以程式作為跨域學習的槓桿,融合電腦科學、語文、音樂、藝術,鼓勵孩子用想像力編寫動人的故事,並且練習程式的思考。

此課程也獲選「 第三屆未來教育.臺灣100 – 全臺年度百大創新教學專案」的獎項殊榮。

每個孩子都希望能創造屬於自己的故事,細緻的課程架構,並附有專人引導的自學影片,孩子可以根據自己的學習和創作速度前進,人人都有成就感!

KIST: 拯民國小.宋亭緻老師

你也能一起參與改變

均一是一個非營利組織,為了專注於我們的願景使命,我們不承接政府預算、不發展有對價關係的盈利,仰賴與我們有相同願景使命的大眾捐款支持,期待集合眾人之力,實現真實的共創與共好。

 邀請你一起參與 >> 公益支持

教室裡的風景

每個人的生命當中,都有那麼幾位令人印象深刻的老師。有的老師幽默風趣、有的嚴厲而堅毅,有的老師像是再生父母,讓我們從學習與探索中,發揮生命更大的價值。

在 2021 年 的停課期間,有一種老師大量增加了,他們是守護孩子學習不中斷的「抗疫老師」,在短短幾天內,設法與孩子取得聯繫、使用各種數位工具,並給予遠距支持。

事實上,在在台灣的每一個角落,一直都能看見這些義無反顧為孩子付出的身影。以下是均一在推動教育改變的路上,遇到的幾位老師,希望透過簡短的文字、影片,與你一起分享,均一在教育現場的看見。

均一教師的身影

安溪國中——靜怡老師

靜怡老師任教於新北市安溪國中數學科,七年前開始使用均一教育平台,並將均一應用在「適性分組班」與自己的班級教學當中。

「讓孩子不會只是之前的挫折一直累積到最後,讓他可以在這裡找到讓他產生信心的地方。」/ 靜怡老師

點我看靜怡老師的完整分享 >>

 

安溪國中靜怡老師

 

高雄岡山教會課輔班——子婕老師  

子婕老師雖罹患罕病,仍完成中央大學數學、資工雙主修,更因為從小便與媽媽在教會服務弱勢孩童。研究所時對數位教學產生興趣、畢業後即投入弱勢教育。2020 年導入均一教學後,子婕老師與課輔團隊投入其中,幾乎天天討論到深夜。雖然孩子的學習成就並沒有一飛沖天,但她認為,孩子的正面心態、學習品格才是第一順位。

「我希望這些孩子記得,小時候有這麼一群人拼 死拼活努力去愛他們,他們是值得被愛的。」/ 子婕老師

點我認識「弱勢課輔班計畫」>>

均一如何支持教師

均一經由支持教師,更規模化地影響孩子。

在子婕老師參與的弱勢課輔班計畫中,均一在兩年內培訓了 110 位教師,其中有 87% 的老師過去未曾使用數位平台輔助教學,在經過師資培訓後,提升了 20% 老師的教學信心,大多數老師更能夠獨立於課堂中教學,陪伴孩子探索數位學習平台,找到適合的學習內容。

除了弱勢課輔班計畫之外,均一長期與苗栗、屏東學習扶助班級合作,培養學習扶助科技教師。疫情期間,更曾累積上千名老師同時在線參與研習培訓,支持全台教師、家長陪伴孩子停課不停學。疫情之後,超過半數的現場教師仍持續採取科技搭配教學,數位學習將是教師、學生、家長不可或缺的關鍵能力。我們期待持續投入培訓資源與教學法開發,支持現場教師,進而支持更多孩子。

你也能一起參與改變

均一是一個非營利組織,為了專注於我們的願景使命,我們不承接政府預算、不發展有對價關係的盈利,仰賴與我們有相同願景使命的大眾捐款支持,期待集合眾人之力,實現真實的共創與共好。

邀請你一起參與 >> 公益支持