解決方案:如果我是前端團隊的負責人，我如何制定前端協作規范？

什么是規范？

規范，名詞意義上：即明確規定或既定的標準，如：道德規范、技術規范等。 動詞含義：指按照既定的標準和規范要求進行操作，使某種行為或活動達到或超過規定的標準，如：規范管理、規范運作。

為什么需要規范？

規范包含什么內容？

正如文章標題所說，前端協??作規范不僅僅指“編碼規范”，這個規范涉及到前端開發活動的方方面面，比如代碼庫管理、前后端協作等、代碼規范和兼容性規范；

需要協作的不僅僅是前端團隊。 在一個完整的軟件生命周期中，我們需要與產品/設計、后端（或本地客戶端團隊）和測試進行協作。 我們需要涵蓋這些內容。

下面就開始介紹吧。 如果我在前端團隊，我會如何制定前端規范，這個規范應該包含哪些內容？

1 工作流程規范 1.1 開發 1.1.1 版本規范

項目的版本號應該按照一定的規則進行迭代。 建議使用語義版本規范。 通過這個規范，用戶可以了解版本變更的影響范圍。 規則如下：

1.1.2 版本控制系統規范

大多數團隊都使用git作為版本庫，管理好代碼也是一門學問。 尤其是當多人參與并發協作、需要管理多個軟件版本時，定義良好的存儲庫管理規范可以使大型項目更有條理，提高成員協作的效率。

目前比較流行的git分支模型/工作流程是git-flow，但是大多數團隊都會根據自己的情況制定自己的git工作流程規范，比如我們團隊的分支規范

Git 有很多工作流方法論，這些工作流的選擇可能取決于項目的規模、項目的類型和團隊成員的結構。

比如一個簡單的個人項目可能不需要復雜的分支劃分，我們的修改直接提交到分支；

另一個例子是開源項目。 除了核心團隊成員之外，其他貢獻者沒有提交權限，我們也需要一定的手段來驗證和討論所貢獻的代碼是否合理。 所以對于開源項目fork工作流程是比較適合的。

了解常見的工作流程有助于組織或創建適合自己團隊的工作流程，并提交團隊協作的效率：

1.1.3 提交信息規范

有組織的提交信息可以提高項目的整體質量。 它至少具有以下優點：

社區中比較流行的信息規范是信息規范，這些也都非常不錯：

此外，這些工具可以幫助您驗證提交消息，以及生成：

1.2 構建規范

對于團隊或者需要維護的多個項目場景來說，統一的構建工具鏈非常重要。 這套工具應該強調“協議大于配置”，讓開發者更專注于業務開發。 在文章中，作者提出vue-cli3更新有很多亮點，非常適合作為團隊構建工具鏈的基礎：

我們可以選擇第三方CLI，當然也可以定制我們自己的構建鏈。 根據上面提到的構建鏈，它應該具有以下特征：

以下是社區中比較流行的構建工具。 當然，你也可以根據自己團隊的情況開發自己的CLI，但是以下工具還是很有參考價值的：

1.3 發布工作流程規范

發布工作流程是指發布“成品軟件”（例如測試或生產）的一組流程，標準化后可以實現自動化。

舉例來說，典型的發布工作流程如下：

如果您遵循上述準則，則可以使用社區中的現有工具來自動化此過程。 這些工具是：

1.4 持續集成

整個開發工作流程確定后，就可以使用持續集成服務來自動化整個流程。 例如，一個典型的 CI 流程：

什么是持續集成？它的含義是什么？

我們需要把持續集成拆成兩個詞來理解，什么是連續？ 什么是整合？

()，可以理解為‘頻繁’或者‘連續’。 無論是持續集成、敏捷開發思維，還是看板，他們都相信“持續”是他們的基礎。

舉個通俗的例子，比如代碼檢查，“持續”的代碼檢查就是只要代碼有變化（比如保存，或者IDE實時檢查，或者提交到版本庫）就檢查代碼，而“非連續”的代碼檢查連續”代碼檢查是在所有編碼完成后，然后進行檢查。 兩者對比可以發現，持續的代碼檢查可以盡早發現錯誤，錯誤也更容易理解和處理。 相反，非連續的代碼檢查可能會發現一堆錯誤。 互相糾纏，最終會變得不可收拾。

“連續性”的概念可以應用于軟件開發的各個方面。 從本質上講，它打破了傳統的瀑布式軟件開發流程，形成更小的開發閉環，不斷輸出產品，同時產品也不斷向上游反饋和修正。

那么什么是“整合”？ 從狹義上講，集成可以簡單地認為是“集成測試”。 集成測試可以用于代碼的靜態測試、單元測試、單元測試通過后的集成測試、應用整體形成后在模擬環境中運行E2E測試等。 也就是說，這里進行一系列的自動化測試來驗證軟件系統。

廣義的持續集成服務不僅僅是測試，它還衍生出很多概念，比如持續交付，持續部署bat 腳本命令內部注釋，如下圖

好吧，讓我們總結一下為什么持續集成是有益的：

對于持續集成規范，一般定義了這些內容：

定義持續集成腳本模板

常用的CI服務：

:-CI

普遍的

擴張

1.5 任務管理

作為前端，任務管理是必不可少的。 看板是目前最流行的任務管理工具。 它可以幫助我們了解項目的進度、資源的分配、恢復開發現場。

筆者畢業第一年在一家很小的外包公司工作。 初生牛犢不怕虎。 我實際上把看板和敏捷項目管理賣給了老板。 我想改善項目管理的低效率。 老板表示支持，但其他成員卻沒有多大積極性，結果當然是失敗了。

當時我還起草了一份《看板實施細則》，所以我在任務管理方面有了一些經驗。

讓我們談談一些有用的工具：

2 技術棧規范

筆者現在所在的公司前端技術棧之前非?；靵y。 Vue、React三大框架都有，風格也有很大不同。 飛機：

精通這三個框架的人很少，更不用說一個團隊了。

三大框架都有自己的設計理念，比如編程語言，與庫不同。 圖書館的更換成本非常低； 框架背后是架構和生態。 每個框架背后都涉及開發思維、生態系統、支持工具、最佳實踐和性能調優。 精通、精通一個框架的成本是非常高的。

因此，團隊的開發效率是建立在穩定、熟練的技術棧之上的。 穩定的技術棧規范有利于團隊協作和溝通； 另外，如果團隊精通這個技術棧，那么當出現問題或者需要深度調優的時候，也會相對容易一些。

前端技術棧規范主要包括以下幾種：

風格。 包含命名約定、預處理器、方法等。

動畫引擎

質量保證。 包含測試、lint、格式化工具、監控

項目構建工具流程。 例如，vue-cli

包管理器。 npm，紗線

項目管理工具

時間處理。 例如.js

模板引擎

開發工具

后端開發框架

工具庫

開發/調試工具

ETC。

您可以參考我們團隊的技術棧規范

2.1 技術選擇

如何從頭開始標準化團隊的技術棧，或者說如何選擇模型？ 例如，首先確定替代方案，您要選擇Vue還是React（一個可能引起爭議的話題）？

前幾天回答一個問題：，我舉了一個例子，說明幾年前我們是如何決定使用 React 或 Vue 的（注意結果不重要?。?/p>

這篇文章寫得很好，給了我一些啟發。 結合上面回答的例子，我來說一下相關技術選擇的一些方法（評分項）：

綜上所述，在這種情況下，React 獲勝。

擴大：

2.2 擁抱新技術

當然，也應該鼓勵團隊學習新技術，淘汰舊的技術棧。 因為總的來說，新技術或解決方案的誕生是為了提高生產力。 當團隊適應新技術選擇時，需要考慮以下幾點：

就我們團隊而言，每個成員都有自己的方向和感興趣的領域，所以我們可以分工合作去探索各自的領域，然后共享成果。 如果可靠的話，我們可以先在實驗項目中嘗試一下。 最后，它被擴展到其他項目。

3 瀏覽器兼容性規范

前端團隊應根據應用所面臨的用戶情況、應用類型、開發成本、瀏覽器市場統計等因素制定自己的瀏覽器兼容性規范，并寫入應用手冊中。

有了瀏覽器兼容性規范，前端開發和兼容性測試就有了依據，避免了爭議； 同時，這也是前端團隊對外的說法。 除非有特殊要求，前端開發者可以選擇忽略。

3.1 確定兼容策略

漸進增強或優雅降級。 這是兩種不同方向的策略。 漸進增強保證了低版本瀏覽器的體驗，對于支持新特性的新瀏覽器提供略微更好的體驗； 優雅降級則相反，為現代瀏覽器提供最佳體驗，而舊版瀏覽器回退以保證近似功能。

選擇不同的策略對前端開發影響比較大，但開發者別無選擇。 根據用戶比例來決定采用何種兼容策略。 如果大多數用戶使用現代瀏覽器，則應使用優雅降級，否則應選擇漸進增強。

3.2 確定瀏覽器評級

YUI曾經提出了瀏覽器分類的原則，這個原則至今仍然適用。 簡單來說，瀏覽器分為多個級別，不同級別表示支持程度不同。 例如，我們團隊將瀏覽器分為以下三個級別：

一般來說，等級是根據瀏覽器市場分布、用戶比例、開發成本等因素來劃分的。

作為示例，以下是我們管理系統的兼容性規范：

3.3 獲取統計數據

百度統計是中國網站使用最廣泛且免費的流量分析平臺。 如上圖所示，通過這些統計平臺，您可以獲取終端真實的瀏覽器使用情況，點擊查看示例。

如果公司還沒有開發自己的監控服務，推薦使用這些大廠支持的免費監控工具：

一般瀏覽器統計信息可以從這些地方獲得：

判斷瀏覽器是否支持某項功能：

4 項目組織規范

項目組織規范定義了如何組織一個前端項目，如項目命名、項目文件結構、版本號規范等，尤其是對于開源項目，規范的項目組織就顯得尤為重要。

4.1 項目組織總體規范

一個典型的項目組織規范如下：

.md：放置各個版本的變更內容，通常描述各個版本的變更內容。 方便用戶確定應該使用哪個版本。 有關規格，請參閱保留

.json：前端項目必需的。 描述當前版本、可用命令、包名、依賴項、環境約束、項目配置等信息。

.：忽略不必要的文件，避免將自動生成的文件提交到存儲庫

.：git配置，這里可能需要配置一些跨平臺的差異，比如換行規則

docs/：項目的詳細文檔，可選。

/：項目的示例代碼，可選。

build：項目工具類腳本放在這里，不是必需的。如果使用unity構建工具，則沒有這個目錄

dist/：項目構建結果輸出目錄

src/：源代碼目錄

test/：單元測試目錄。 根據 Jest 規范，該目錄通常與被測試的模塊位于同一父目錄中，例如：

/src
  __tests__/
    index.ts
    a.ts
  index.ts
  a.ts
復制代碼

測試：全局測試目錄，通常用于應用程序集成測試或E2E測試等用例

.env*：在項目中，我們通常會使用環境變量來影響應用程序在不同運行環境下的行為。 您可以從文件中讀取環境變量。 通常有三個文件：

基本上這些文件很少改動，團隊成員不要隨意改動，以免影響其他成員。 因此通常使用 .env.*.local 文件來覆蓋上述配置，并將存儲庫設置為忽略 *.local 文件。

對于開源項目通常還包括這些目錄：

任何優秀的開源項目都是你的老師，比如React、Vue……

4.2 目錄組織風格

以上只是一個通用的項目組織規范。 如何組織源代碼取決于您使用的技術堆棧和團隊偏好。 網上有很多教程，可以搜索一下如何組織XX項目。 概括起來，項目組織主要有以下三種風格：

大多數情況下，我們使用混合兩種方法的目錄結構，例如：

src/
  components/      #  項目通用的‘展示組件’
    Button/
      index.tsx    # 組件的入口, 導出組件
      Groups.tsx   # 子組件
      loading.svg  # 靜態資源
      style.css    # 組件樣式
    ...
    index.ts       # 到處所有組件
  containers/      #  包含'容器組件'和'頁面組件'
    LoginPage/     # 頁面組件, 例如登錄
      components/  # 頁面級別展示組件，這些組件不能復用與其他頁面組件。
        Button.tsx # 組件未必是一個目錄形式，對于一個簡單組件可以是一個單文件形式. 但還是推薦使用目錄，方便擴展
        Panel.tsx
      reducer.ts   # redux reduces
      useLogin.ts  # (可選)放置'邏輯', 按照分離邏輯和視圖的原則，將邏輯、狀態處理抽取到hook文件
      types.ts     # typescript 類型聲明
      style.css
      logo.png
      message.ts
      constants.ts
      index.tsx
    HomePage/
    ...
    index.tsx      # 應用根組件
  hooks/           # 可復用的hook
    useList.ts
    usePromise.ts
  ...
  index.tsx        # 應用入口, 在這里使用ReactDOM對跟組件進行渲染
  stores.ts        # redux stores
  contants.ts      # 全局常量
復制代碼

框架官員很少干預項目的組織。 讀者可以參考以下資源來建立自己的項目組織規范：

4.3 腳手架和項目模板

項目結構規范確定后，您可以創建自己的腳手架工具或項目模板，快速初始化一個項目或代碼模板。

相關資源：

5 編碼規范

網上的“前端規范”大多指的是編碼規范，是一種“狹義”的前端規范。

統一的編碼標準有利于團隊項目的長期維護。 一致的代碼標準可以提升團隊開發協作效率，提升代碼質量，減輕遺留系統維護負擔。

最直接的好處就是避免寫出糟糕的代碼。 糟糕的代碼與新手和老手沒有什么關系。 我還見過工作多年的“高級”工程師寫出惡心的代碼。 這樣的代碼隨著項目的迭代可能會變得難以管理。

現代的 Lint 工具非常先進，幾乎可以約束各種編碼行為。 比如約束文件長度、函數復雜度、命名規范、注解規范、接口黑名單、檢查簡單的邏輯錯誤……

每個程序員對于“好代碼”都有自己的看法。 統一編碼標準可以避免像秦始皇統一戰國一樣不必要的爭論和爭議。

事實上，與其自己建立前端編碼標準，作者更推薦選擇社區已經確定的標準。 這方面的資源有很多，因此本文不會武斷地提出自己的標準建議。 推薦以下資源：

5.1

規格

類型檢查。 暫時將它們分組在這里，因為它們都是“靜態測試”

5.2 HTML

規格

5.3 CSS

規格

方法

關于CSS，可以學習這些傳統的UI框架，他們的代碼組織很好，值得學習

5.4 代碼格式化

基本上所有與代碼格式相關的工作都可以交給去做，然后在此基礎上使用覆蓋語義相關的檢查

5.5 綜合

5.6 框架特定的風格指南

5.7 代碼

上述Lint工具和類型檢查器可以約束代碼風格并避免低級語法錯誤。 但即使使用上面的 Lint 和類型檢查，代碼也不一定是“好代碼”。

具體的自動化工具或文檔無法涵蓋代碼設計的許多“最佳實踐”。 這時候，“經驗”或者“群體智慧”就派上用場了。 例如，代碼階段將檢查以下內容：

如果您是第一次實施代碼，您可以創建一個檢查列表并對照它進行檢查。 熟練之后，心里就沒有代碼了。

代碼有很多好處，例如：

Code有兩種方式：一種是提交時，另一種是計時：

代碼實現起來比較困難，但是也要看你團隊的情況。 付給我們的錢更少、生活更多的團隊很少有時間立即處理其他成員的代碼。 這時候，計時會更有用，因為它看起來更“節省時間”。

而且提交時，你可以針對新人，比如你不信任他們的代碼或者想要幫助他們提高編碼技能。

相關資源：

6 文檔規范

文檔對于項目開發和維護、學習、重構和知識管理非常重要。

就像編寫測試一樣，大多數開發人員會發現編寫文檔很痛苦，但只有時間才能證明它的價值。 比如對于一個人員流動比較大的公司，如果有一個標準化的文件系統，那么工作的轉移就會很容易發生變化。

廣義上的文檔不僅僅指“描述文檔”本身。 它們有多種形式、來源和載體，可以描述一種知識，以及知識形成和迭代的過程。例如，存儲庫代碼提交記錄、代碼評論、決策和討論記錄、示例代碼、規范、傳統文檔、 ETC。

6.1 建立文檔中心

我們公司是做IM的，所以之前我們都喜歡用自己的通訊工具來共享文檔，這種方式有一個很大的問題：

如果沒有存檔的習慣（比如后端API文檔，因為是后端維護的，一般不會主動存檔），文檔可能會丟失，并且通訊工具不會永久保存您的文檔。當文件丟失時，需要向文檔維護者重新請求

不好的是，文檔維護人員還手動將其歸檔到本地，這導致了以下問題： 如果工作被移交，其他開發人員需要花一點時間才能找到它； 如果失去了，就真的消失了

每次更新文檔都需要一份新的副本，非常麻煩，而且可能會遺漏，導致不一致。

學習知識、有意義的討論記錄無法存檔。

以上是一種非常原始的文檔共享方式，很多小團隊都是這么做的。

建議將項目本身的文檔放在關聯的項目倉庫中，與項目代碼一起迭代。 當我們檢索或跟蹤文檔的歷史記錄時，這是最方便的方法。

然而，很多應用程序跨越多個團隊，每個團隊都會有自己的文檔輸出（如需求文檔、系統設計文檔、API文檔、配置文檔等），并且通常不在版本庫中。 這時候的文件就比較分散了。 所以一個統一的文檔中心是必要的。

我們公司現在選擇的解決方案是Git+bat 腳本命令內部注釋，也就是說所有的文檔都放在一個git倉庫下。 我之前也考慮過商業解決方案，比如石墨文檔、騰訊文檔，但管理層并不信任這些服務。

git項目的大概組織結構如下：

規范/
A應用/
  產品/
  設計/
  API文檔/
  測試/
  其他/
B應用/
復制代碼

Git倉庫（以Git倉庫為例）有很多優點，比如歷史跟蹤、版本控制、問題討論（可以關聯issue，或者提交）、多人協作、搜索、權限管理（為不同的人對不同的倉庫或分組設置權限） ） ）ETC。

Git+可以滿足開發者的大部分需求。 但Git最擅長的是處理純文本文件，對于二進制文件就無能為力了，而且對于這類文檔也無法在線預覽和編輯。

因此，Git+無法滿足多樣化的文檔處理需求，比如思維導圖、圖表、表格、PPT、白板等，畢竟它不是專業的文檔處理工具。 因此，對于產品、設計師等文檔需求豐富的場景，通常采用傳統方式或更專業的工具來管理文檔。

6.2 文件格式

毫無疑問，它是最適合開發者、最常用的文檔格式。 支持存儲庫的在線預覽和更改歷史跟蹤。

以下工具可以提高開發效率：

: 代碼檢查器

擴展名（代碼）：

圖表繪制工具：

6.3 定義文檔模板

關于如何寫出一篇好的文檔，很難通過標準或者規范來約束，因為它比較主觀。 一篇好的文檔取決于編輯者的邏輯總結能力、表達能力以及是否站在讀者的角度思考問題。

所以大多數情況下，我們可以為不同類型的文檔提供一個模板，并使用模板來解釋文檔需要包含哪些內容，并指導文檔的編寫者。

例如，API 文檔可能需要如下內容：

具體規范內容因團隊而異，就到此為止。

擴大：

6.4 討論記錄

總的來說，對于一個開源項目來說，除了官方文檔之外，也是非常重要的信息來源。 在Issue中，我們可以獲取其他開發者遇到的問題和解決方案、給予官方反饋/投票、關注官方最新動態、與其他開發者進行頭腦風暴等等。

因此，相比于使用IM，筆者更推薦Issue的溝通方式，因為它便于歸檔組織、索引和檢索。 而IM上的討論如流水一般，一去不復返了。

當然，兩種工具的應用場景是不同的。 如果你用IM一樣的方式使用Issue，那么Issue就會變得很水。 Issue 適合有意義且有目的的討論。 所以我要譴責那些在Issue上潑水的開發商。