從設計到管理，如何快速打造技術產品

時間  2021-08-12
標籤 css html 前端 vue react webpack ios git 程序員 github 欄目 CSS 简体版
原文   原文鏈接

回顧本身近幾年的工做經歷，從最先 17 年在團隊內部建立 Iceland [注1] ，到 19 年在開源社區參與 ICE 的由 1 到 10，再到 20 年由 0 到 1 建立了 AppWorks。其間也曾在阿里前端委員會參與了低代碼引擎 [注2] 早期的共建。這些經歷都屬於技術產品建設的範疇。

我見過一些有趣的想法和優秀的技術實現，但因爲產品的定位問題，最終沒有得到世俗意義上的成功；也經歷過有很是系統性規劃的項目，但因爲分工和執行問題，最終錯過了發展的時間窗口。服務好開發者確非易事，他們極其挑剔。把優秀的工程師們彙集在一塊兒工做也並不容易，他們特立獨行。

在如何服務好開發者羣體、如何管理大型的多人協做項目問題上，本身不敢說有多少成功的經驗，但也算是踩過很多的坑。當我再次面對技術產品化需求時，指望能系統性地梳理技術產品的建設方法，總結本身的經驗爲往後所用，也許對於其餘同窗來講也有些參考價值，所以寫下了這篇文章。

在這篇文章當中，筆者將介紹「如何作」的方法論，不會討論「爲何要作」的動機。因爲筆者的工做經歷主要以打造開源技術產品爲主，所以在文章中又會主要以「開源技術產品」爲例，但相信這些經驗對於內部技術產品也是適用的。

一個技術產品的打造，涉及到設計產品、設計架構、管理項目、編寫文檔、開發官網、運營產品、管理需求和缺陷等多個環節。要把這幾個環節都作好，纔有可能成功。技術產品項目在不一樣的階段又有不一樣的關注點，比方說前期更側重設計，發佈後更側重運營，穩按期則更側重需求管理和答疑，開源後則更側重項目管理。

下面筆者將按照這幾個環節來展開介紹相關的方法論和工具，而且會提供一些示例。css

image.png

設計產品

打造技術產品的第一步是明確使用怎樣的手段來解決目標用戶的問題，即要 「作什麼」，其本質是完成用戶產品的設計。

在此階段能夠進行一些輸入，例如能夠經過用戶調研和市場調研的方式來得出：用戶關注的問題當中，哪些是重要且緊急的？市面上有沒有相關的產品來解決這些問題，當前解決得怎麼樣？由此能夠明確，咱們要打造的技術產品，定位是什麼，提供哪些特性。

關於產品的特性，不妨思考：哪些功能是別人有咱們也有的(We too)？哪些功能是別人有但咱們能夠作得更好的(We better)？哪些功能又是咱們獨有的(We only)？

若是是圖形界面類產品（例如開發者工具），則能夠產出產品的交互稿：包含哪些功能模塊，用戶的使用流程是怎樣的？若是是代碼類產品（例如框架），則能夠產出官網交互稿和文檔大綱：設計產品官網的過程就是明確產品組織結構、核心能力及產品價值的過程，編寫文檔大綱的過程就是以客戶視角審視產品用戶體驗的過程。對於基礎庫，還能夠先明確對外 API 的設計：提供哪些屬性、方法和事件？html

image.png

總結一下，在產品設計環節主要交付的產物是：前端

image.png

設計架構

產品設計回答了「作什麼」的問題，接下來要去考慮 「怎麼作」，其本質是完成軟件架構的設計。

軟件架構的重要性不言而喻，它是系統實現的藍圖、溝通協做的基礎，決定了產品的質量。

關於如何設計一個好的架構以及怎麼描述你的架構設計，有很是多成熟的方法論，這裏就再也不贅述了，筆者也在學習實踐當中。在架構設計環節筆者的一個思路是：先作競品調研，再作架構製圖。vue

image.png

作競品調研，產出的是調研報告。經過調研去了解相關競品的架構模式，甚至是程序實現。當前技術資訊發達、開源社區活躍，太陽底下沒有新事物。咱們要作的事情，可能已經被人用好幾種方式實現了好幾個版本。在有限的時間內，找到問題域中最好的幾個實現進行調研，站在巨人的肩膀上思考，事半功倍。示例：《螞蟻 Could IDE 調研報告》 [注4]

作架構製圖，產出的是架構圖。架構製圖方法與工具備不少，UML 應該是大部分人最熟悉的製圖方法，UML 由如下兩大類圖組成：react

  • 結構圖（Structural Diagrams）：經過對象、屬性、操做和關係等方式，強調系統的靜態結構，其中最多見的類型包括類圖（Class Diagram）、組件圖（Component Diagram）和部署圖（Deployment Diagram）。
  • 行爲圖（Behavioral Diagrams）：經過展現對象之間的協做關係以及對象內部的狀態改變，強調系統的動態行爲，其中最多見的類型包括用例圖（Use Case Diagram）、活動圖（Activity Diagram）、時序圖（Sequence Diagram）和狀態機圖（State Machine Diagram）。


例如，能夠把這兩類圖應用到咱們的程序設計當中：webpack

  • 結構圖：程序中包含哪些類、對象和函數，它們之間的關係如何？=>類圖（Class Diagram）
  • 行爲圖：程序的運行流程是怎樣的？ => 時序圖（Sequence Diagram）


示例：VS Code 插件 Time Master 的程序設計（來源：#PR 620）ios

image.png

最後關於架構製圖，推薦一些方法論和小工具：git

  1. 方法論：@楚衡(pengqun.pq) 老師的 《架構製圖：工具與方法論》 一文，系統性地梳理了架構製圖的方法和工具，值得一再閱讀。
  2. 語雀富文本的文本繪圖功能，支持 PlantUML。PlantUML 是一種繪圖語言，可讓做者以類編寫 Markdown 的方式天然地畫圖，可進行多人協做和版本跟蹤，受到各知識系統的普遍支持：

image.png

管理項目

完成了產品和架構的設計後，開始進入項目開發的環節。這個環節主要關注的是：如何組織開發和怎樣進行協做。前者不管是我的仍是團隊項目都是通用的，後者取決於項目的規模。程序員

組織項目開發

image.png

倉庫劃分

倉庫的劃分是軟件架構設計在代碼組織層面的落地，須要有預見性，避免將來進行大規模的倉庫遷移。

倉庫的組織形式有兩種：多倉庫和單倉庫。單倉庫又多包(monorepo)和單包的區別。比方說 React ，就是多倉庫的組織形式：有主倉庫 facebook/react 是多包存儲庫，還有存放周邊倉庫的組織 reactjs/*。

這裏面沒有一成之規和好壞之分，主要取決於項目的規模和協做上的便利，或者說有時候純粹是我的喜愛問題。比方說有些技術產品將本身的插件、示例、官網都放到單獨的倉庫進行管理，有些則傾向於放到一塊兒。

示例：AppWorks 的倉庫劃分github

image.png

分支管理

爲了更好地利用 Git 這樣的源碼版本管理系統來進行多人協做，咱們須要制定分支管理策略。分支管理策略的目的是規範化工做流程，讓你們高效地進行合做，使得項目層次分明地發展下去。

分支管理策略包含了如下內容：

  • 有哪些分支類型？
  • 分支類型間的合併關係如何？
  • 基於分支的迭代路徑是怎樣的？


常見的 Git 工做流有 Centralized Workflow 、 Feature Branch Workflow、Gitflow Workflow、Forking Workflow 等等。Atlassian 的 Comparing Workflows 這篇文章對以上幾種工做流進行了比較。

目前社區上普遍採用的是最先由 Vincent Driessen 提出的 Gitflow Workflow：

image.png

Git 規約

項目基於 Git 進行源碼版本管理，還須要關注分支和標籤的命名、提交日誌格式等問題。它們的規範性可使得項目運做層次分明，項目成員對 Git 信息的理解保持一致。社區有不少 Git 規約，它們之間沒有好壞之分，主要關注規約的覆蓋度便可。

Git 提交日誌格式規約包含的內容有：日誌的格式、字數的限制、語言的選擇等。

在社區中應用得比較普遍的日誌格式是：

<type>[optional scope]: <subject>

[optional body]

[optional footer(s)]
複製代碼

其中 type 是用來描述本次提交的改動類型，通常可選值及對應含義以下：

  • feat: 新增功能
  • fix: 修復 bug
  • docs: 文檔相關的改動
  • style: 對代碼的格式化改動，代碼邏輯並未產生任何變化(例如代碼縮進，分號的移除和添加)
  • test: 新增或修改測試用例
  • refactor: 重構代碼或其餘優化舉措
  • chore: 項目工程方面的改動，代碼邏輯並未產生任何變化
  • revert: 恢復以前的提交


Git 提交日誌格式規約的完整版本，可參考 AngularJS Git Commit Message Conventions。

在項目工程上可使用命令行工具 commitlint ，結合 Git 提交日誌格式規約包 commitlint-config-ali，以及 Git Hooks 來進行提交卡口：

安裝命令行工具：

$ npm i --save-dev @iceworks/spec @commitlint/cli husky
複製代碼

建立提交日誌格式規約文件 .commitlintrc.js:

const { getCommitlintConfig } = require('@iceworks/spec');

// getCommitlintConfig(rule: 'common'|'rax'|'react'|'vue', customConfig?);
module.exports = getCommitlintConfig('react');
複製代碼

添加 Git Hooks 配置到 package.json:

{
  "husky": {
	"hooks": {
	  "commit-msg": "commitlint -E HUSKY_GIT_PARAMS"
	}
  }
}
複製代碼

1.@iceworks/spec 是淘系前端規約包，內部引用了 commitlint-config-ali
2. Husky 是一個簡易配置 Git Hooks的工具

工程方案

項目工程方案主要包括了代碼規約、本地工程和 CI&CD 的內容。

代碼規約

在多人協做項目中保持代碼風格的一致性是必要的。前端領域關於代碼規約的討論和沉澱都已經比較成熟，阿里前端委員會標準化小組制定了《前端編碼規約》 [注5] ，包括了語言（HTML/CSS|Sass|Less/JavaScript）和框架（React/Rax）的部分。淘系前端基於此規約進行拓展，產出了 @iceworks/spec 這個 npm 包，結合 ESLint、StyleLint、Prettier 等命令行工具來提供本地工程方面的配套保障。當咱們進行項目開發時，只須要引用該包和相應的命令行工具，作一些簡單的配置便可：

安裝命令行工具：

$ npm i --save-dev @iceworks/spec eslint stylelint prettier husky
複製代碼

配置 package.json：

{
  "scripts": {
    "lint": "npm run eslint && npm run stylelint",
    "eslint": "eslint --cache --ext .js,.jsx,.ts,.tsx ./",
    "stylelint": "stylelint ./**/*.scss",
    "prettier": "prettier **/* --write"
  },
  "husky": {
    "hooks": {
      "pre-push": "npm run lint"
    }
  }
}
複製代碼

本地工程

本地開發工程任務的設定是爲了提高開發效率並將團隊規約落實到開發中，一般包括如下部分：

  • setup: 初始化工程環境
  • dev: 啓動調試並預覽示例
  • lint: 執行靜態代碼分析
  • test: 執行單元測試
  • build: 執行源碼構建
  • publish: 發佈代碼


前端開發在本地工程配套設施上已經很是成熟，面向不一樣的項目類型都有相應的工程方案。常見的項目類型和相應的工程示例：\

CI&CD

持續集成 (CI) 和持續部署 (CD) 是自動化工做流程的重要組成部分。

在 Github 中，持續集成主要是經過 Actions 來實現的。固然還有另一些選擇或結合，例如 Travis、Appveyor、Circleci 等等。Github Actions 很是強大，能夠在任意的 Github Event 下運行。例如能夠在提交代碼到倉庫時、分支合併時、PR 建立時等等。基於 Github Actions 的任務一般包括：

  • 功能測試及代碼覆蓋率
  • 代碼構建
  • 代碼檢查（語法檢查、安全性檢查）
  • 資源部署（CDN 發佈、npm 發佈）

例如 VS Code 套件 AppWorks Pack 的 Actions：

  • PR 建立時：執行代碼檢查和功能測試任務
  • 提交代碼到 beta 分支時：執行代碼構建（構建插件安裝包）和資源部署（將安裝包上傳到 CDN）任務
  • 提交代碼到 main 分支時：執行代碼構建（構建插件安裝包）和資源部署（將安裝包發佈到 VS Code 插件市場）任務

在阿里內部，CI&CD 主要由 DEF [注6] 統一管理，根據不一樣的項目類型（Assets/WebApp/Serverless）有統一的自動化工做流程。

創建協做機制

image.png

上圖是筆者 2019 年在 Github 上的 Activity Overview，能夠看到有比較多的精力是分配在了與溝通協做的部分（Issues/PR/CR）。對於多人協做開發的項目，前期創建協做機制是提高團隊總體工做效率的必然要求。項目開源後，建立貢獻指南則可讓外部開發者參與到項目的開發當中。這二者是先後關聯的，在有些開源項目中是統一的。

一些社區的貢獻指南參考：

在協做機制裏面，筆者認爲幾個重點的內容有：RFC 機制、PR 規約和 CR 指南。

RFC 機制

部分技術產品採起 RFC(Request For Comments) 的形式進行項目的技術方案設計、討論與迭代，例如 React RFCs、Yarn RFCs、Rust RFCs 等等。RFC 是一種文檔優先的工做方式，而且讓方案在項目早期獲得充分的討論和論證。

RFC 機制主要包括了幾個方面的內容：

  1. 明確範疇：何時須要 RFC
  1. 設定流程：有哪些環節（提交、審查、實施或延期）及要求，在各環節中各個角色的職責是什麼
  1. 提供模板：RFC 的大綱

PR 規約

PR 規約的設定目的是爲了提高 PR 的質量和提升 CR 的效率。規範化的 PR 還能夠基於內容產出產品的更新日誌。PR 規約一般包含如下內容：

  • 內容格式的規約：標題和描述應該遵循怎樣的格式
  • 提交代碼的規約，例如新添加功能需提供測試用例、更新代碼需更新包版本號、每次 PR 的文件數和代碼行數限制等
  • 合併的規約，例如須要哪些人 approved 才能合併

一些開源項目將 PR 的規約經過 Github App 來進行保障，例如觀察測試代碼覆蓋率的變化。\

CR 指南

高度規範化的 CR 會扼殺生產力，但毫無要求的 CR 又每每是無效的。建立 CR 指南的目的是爲了提升 CR 的效率和有效性，在二者之間尋找某種平衡。CR 指南能夠包含如下內容：

  1. 代碼審查標準是什麼？
  2. 如何肯定審稿人？
  3. 在代碼審查中應該看什麼內容？
  4. 在代碼審查中有哪些文件導航的方法？
  5. 代碼審查的響應速度應該怎麼樣限定？
  6. 如何編寫代碼審查評論？
  7. 如何處理代碼審查中的回執？

示例：《Google 的 CR 指南》。


CR 的有效性則能夠經過完整閱讀率、評論率、平均行評審時長等指標來衡量，爲項目創建必定的數據指標來約束 CR 行爲。
\

CR 的效率與具體的代碼託管平臺有關，能夠在指南中提供平臺功能文檔和相應的小技巧。例如 Github 有完善的 CR 功能介紹文檔。

異步與實時

大多數開源項目採用異步的方式來進行協做，而不是集中辦公。這固然有所利弊，且取決於項目的性質和階段。若是採用了異步協做的方式，因爲開發者我的素質和工做習慣的不一樣，須要有必定的機制來保障項目開發的質量和效率。

不妨參照成熟開源項目的運做模式，比方說 VS Code 制定了年度的 Roadmap，而且將工做計劃細化到了月或周的維度；有明確的分工，不管是功能模塊仍是流程處理(Iusse/PR)；對需求和問題的反饋都有必定的管理手段。

還能夠經過一些的方式來實時同步項目的狀態，例如將項目的進度等信息經過機器人同步到在線聊天室（如釘釘羣）：

image.png

編寫文檔

技術產品面向用戶最重要的東西就是文檔。打造技術產品在文檔上須要考慮的問題是：如何給用戶提供好的閱讀體驗以及如何提升開發者文檔編寫和審閱的效率。

目前國內主流的技術文檔閱讀（消費）途徑是：語雀、自建網站和 Git 倉庫；編寫（生產）途徑是：在語雀上編寫或在 Git 倉庫上編寫。從生產到消費的鏈路有：\

  1. 在語雀上編寫
  • 在語雀上閱讀
  • 自建站點，請求語雀的接口獲取文檔內容後渲染成網頁
  1. 在倉庫上編寫
  • 在倉庫內閱讀
  • 自建站點，將 Markdown 渲染成網頁

對比這幾個鏈路的優缺點是：

image.png

大型項目或有開源的計劃，一般會選擇第四種方案。

開發官網

技術產品大多都須要一個官網來承載產品信息，又或者在「編寫文檔」上選擇了第四種方案，則須要考慮如何基於 Markdwon 來生成網站用於展現。目前社區上有不少文檔網站的方案，例如 Docusaurus、VuePress、Docsify 等等。在進行選型的時候能夠考量的點是：

  • 是否支持多主題？
  • 是否支持自定義頁面？
  • 是否支持生成靜態站點？
  • 是否支持寫多語言和多版本的文檔？
  • 是否支持在文檔中渲染示例？
  • 上手門檻如何？
  • 定製能力如何，使用何種技術棧進行定製？
  • 部署成本如何？

參考：《Docusaurus 與其餘工具的對比》


開源項目廣泛的選擇是部署到 GitHub Pages 上，資源託管和訪問域名的問題都搞定了。可是國內訪問 Github 實在太慢了，有一種解決方式是利用國內的代碼託管平臺（例如 gitee 或 coding）的 Pages 服務 來進行部署。能夠將 Github 的倉庫代碼同步到這些平臺上去。

在阿里內網，主要是經過 DEF 進行部署，針對文檔站點，有如下幾個方案：

image.png

對於內部技術產品來講，沒有必要將 CDN 資源發佈到外網，所以當下在 DEF 鏈路下選擇第三種方案是比較合適的。

運營產品

應持何種心態

完成了技術產品後，須要咱們主動去運營它。可能不少程序員不擅長這個環節，以爲有些譁衆取寵，黃婆賣瓜自賣自詡。筆者的觀點是：

  1. 技術運營是一種技術自信和擔當。
  2. 酒香也怕巷子深，尤爲是在信息爆炸的今天。

固然技術運營應該是真實的、適度的：

  1. 真實是指不誇大本身產品的功能，找到目標用戶並解決他們的問題；
  2. 適度是指運營的目的是爲了爭取曝光得到潛在的用戶，而不是騷擾他人或詆譭對手。

一些值得商榷的行爲：

  1. 作的產品跟 A 開發者羣體八根子都打不着，但挨個私聊發廣告；
  2. 在運營文章中自我摽榜，把競對貶的一文不值；
  3. 到各類競對的運營文章下瘋狂貼牛皮癬。

輸出什麼樣的內容

技術運營的內容上，軟文和乾貨天然可以得到技術媒體更多的轉發，這類文章一般都是從開發者切身關注的問題和技術熱點入手，經過方案的輸出吸引讀者，例如筆者寫過的《影響編碼心流的問題及其對策》、《10 個你可能還不知道 VS Code 使用技巧》、《從生產到消費，基於物料的前端開發鏈路》等等。硬廣也必不可少，這類文章主要講述產品的功能，經過講事實擺道理的方式直抒胸臆，例如《淘系前端研發工具 AppWorks 正式發佈》、《Iceworks: 從 GUI 開發工具到集成研發工做臺》等等。

毫無疑問，一個好的標題能爲文章得到更多的閱讀量。比方說筆者的兩篇文章：《淘系自研前端研發工具 AppWorks 正式發佈》就比《Iceworks: 多端研發套件》閱讀量和互動率高出一個檔次。一樣的，「如何快速打造爆款技術產品」的文章標題可能又比「如何打造技術產品」更具吸引力。甚至有些時候，我會在不一樣的投放渠道使用不一樣的文章標題或內容組織形式：嚴肅官媒、大衆傳媒和灌水社區的受衆對標題的敏感度和內容的喜愛傾向是不一樣的。

有哪些途徑

做爲技術產品的做者，應該主動尋找更多更廣更合適的渠道來進行技術宣發。遵循由小範圍到大範圍，逐漸鋪開的宣發思路。@法海(fahai) 老師著有一篇 《技術寫做如何宣發》 [注7]，從內網、公網、私域等方面梳理宣發渠道，該思路值得參考。

最後，一個技術產品的運營既須要有爆點，也須要有持續性。例如進入產品成熟期的 ICE 和 Rax 就經過月報、工做羣發佈產品更新日誌等形式持續同步產品的動態。

管理需求和缺陷

技術產品上線後，用戶可能會提交新的需求或反饋遇到的問題。怎樣以更高效的方式使得用戶得到更好的服務體驗是一個必須面對的問題。這方面筆者也沒有一個好的答案，這裏主要講講筆者看到的一些實踐。

開源項目一般經過 Issue 來收集用戶的需求和問題。Github 有 Issue Template 的功能可讓開發者經過模板定義不一樣類型 Issue 的內容格式，由此來引導用戶建立更高質量的 Issue：

image.png

此外，經過標籤的方式來對 Issue 進行歸類整理也是比較廣泛的管理形式。

image.png

Issue 的定位有點相似於商業產品的「工單模式」。開源項目的維護者沒有辦法迴應全部用戶的需求和問題，更指望社區用戶可以相互幫助解決問題，所以會建立線上溝通途徑讓使用者們彼此交流。例如國外開源項目常使用 Stack Overflow 或 Github Discussions 建立線上討論區，使用 Discord 建立實時在線聊天室。國內社區的「互助模式」主要是使用各種辦公溝通軟件（如釘釘）建立用戶羣。

阿里內部技術產品廣泛作法是經過 Aone [注8] 來跟蹤需求和缺陷，接入研發小蜜 [注9] 來提供答疑服務。得益於這些工具，在阿里內部，技術產品的需求和缺陷的管理已經能夠在線化了，將來徹底能夠數字化地評估技術團隊在這方面的投入和產出，例如中臺團隊能夠將答疑解決率、Aone 需求/缺陷處理率等指標歸入到績效考覈中。公司內部的技術產品也理應以商業產品的標準來要求本身。

寫在最後

題圖是筆者在參加某次手工活動時製做的木製品。我清楚地記得，車子的成型很是容易，只須要使用大型切割工具進行做業，幾步便可完成。但要讓它真正地成爲一個工藝品，則須要耐心和大量的時間去磨平它的菱角。我想作技術產品也是如此吧。正文所言的條條框框僅僅是讓技術產品有一個大致的輪廓，要讓它真正能爲開發者所用所喜好，還需點點滴滴、持續迭代的精雕細琢。

註釋

  1. 注1：Iceland 是淘系內部的界面設計平臺
  2. 注2：阿里低代碼引擎是面向低代碼領域的 SDK
  3. 注3：《淘系技術部前端外包現狀調研報告》是一分內部文檔，報告了淘系外包的研發現狀
  4. 注4：《螞蟻 Could IDE 調研報告》是一分內部文檔，Could IDE 是螞蟻一個以代碼爲中心、專業高效的雲端研發平臺
  5. 注5：《前端編碼規約》是一分內部文檔，是阿里前端標準化文檔的一部分
  6. 注6：DEF 是阿里內部的前端工程研發平臺
  7. 注7：《技術寫做如何宣發》是一篇內部文章，介紹瞭如何運用阿里內部的媒體渠道進行技術宣發
  8. 注8：Aone 是阿里內部的一站式研發協同平臺
  9. 注9：研發小蜜是阿里內部一款面向內部服務與支持場景的 SaaS 解決方案平臺

————————————————————————————————————————————

做者|梧忌

編輯|橙子君

出品|阿里巴巴新零售淘系技術

相關文章
相關標籤/搜索
每日一句
    每一个你不满意的现在，都有一个你没有努力的曾经。
本站公眾號
   歡迎關注本站公眾號,獲取更多信息
聯繫我們 最近搜索 最新文章 沪ICP备13005482号-10 MyBatis教程 SQL 教程 MySQL教程 Java 教程 Thymeleaf 教程 Hibernate教程 Spring教程 Redis教程