怎么寫出一份令人驚嘆的設計文檔?
一份好的設計文檔需要提供清晰的問題描述、整體的概要設計、涵蓋各個細節(jié)的詳細設計等。
這篇有趣的英文小短文通過一個簡單的小例子介紹了Google工程師是怎么寫設計文檔的。本文為中文翻譯。原文鏈接如下：https://luanjunyi.medium.com/how-do-i-write-engineering-design-docs-in-google-an-example-f19febe0297c
寫文檔是我在谷歌學到的最重要的技能之一。在谷歌，文檔被用來討論問題、作為真實的信息源、組織知識。在我工作過的其他公司中，沒有一家對如何使用文檔進行協(xié)作有這樣深刻的理解。
這篇文章就是關于我在谷歌如何寫設計文檔的一個例子，這是一個真實的項目，用于在新冠疫情期間控制健身房現(xiàn)場人數(shù)。即使在新冠疫情結束后不需要預約健身房了，也可以訪問GitHub上的源代碼[1]。為了讓這篇文章更有趣，現(xiàn)在每個人都可以在谷歌文檔[2]上進行評論，而且谷歌文檔的格式也比Medium支持的要好。
—?1?—
問題描述
在新冠疫情期間，要求健身房控制現(xiàn)場會員總數(shù)，要求會員在去健身房之前先在網(wǎng)站上預訂。預約需要提前兩天，從午夜開始。例如，2021年04月01日的預訂將在當?shù)貢r間2021年03月30日00:00 AM開放。
這個健身房里的游泳池提供的位置非常有限。我嘗試了好幾次，都沒能預定到早上6點的時間，后來工作人員告訴我，由于需求量很大，必須在午夜預訂。但是熬夜到半夜會打亂我的生物鐘，所以我沒法接受。
而且我覺得雇人做這件事也很不好，因為在內(nèi)心深處，我認為早睡是健康高效生活方式的核心習慣，用金錢剝奪別人的好習慣是不道德的。在被告知沒有別的辦法之后，我決定寫一個程序來為我做預訂。
我個人認為用機器人來做工作是對別人的不公平，所以我對這個決定一點兒也沒感到自豪。相反，我認為健身房應該提高一些場地的價格。但這顯然超出了設計文檔的范圍，而且是非常主觀的想法。
—?2?—
需求
自動提前兩天在半夜預訂健身房
程序啟動后不需要人工交互，應該具有容錯性，能夠進行合理的重試
可以在Mac電腦上運行
用戶可以指定用戶名、密碼、預約的項目、日期和時間等
只提前1或2天預訂，或當天預訂
容忍操作系統(tǒng)或網(wǎng)絡問題
在預約服務器停止運行后還要能夠工作
在網(wǎng)站結構（HTML）改變后，還要能夠工作
—?3?—
概要設計
瀏覽器自動化 vs 模擬請求
瀏覽器自動化是指通過程序來控制真實的瀏覽器，并在GUI上自動化操作。模擬請求是指讓程序通過HTTP與服務器交互，這個程序就像是一個Web瀏覽器（而不是控制一個瀏覽器）。
考慮到下面幾點，我認為瀏覽器自動化比模擬請求更好：
[優(yōu)點] 瀏覽器自動化啟動了一個真實的瀏覽器實例，所以我們知道程序運行時發(fā)生了什么，它使調(diào)試和開發(fā)更加容易。
[優(yōu)點] 網(wǎng)站需要JavaScript加載控件，而這較難通過編程實現(xiàn)，可能需要控制一些渲染引擎。
[缺點] 瀏覽器自動化依賴于HTML結構，而模擬請求依賴于HTTP API，API相對穩(wěn)定，不太可能改變。
顯然利大于弊。
系統(tǒng)概述
Selenium[3]是一個提供瀏覽器自動化解決方案的軟件庫。我們的程序?qū)⒂肞ython編寫，并通過Python API控制Selenium，Selenium則通過它的Gecko驅(qū)動程序控制Firefox。
Caffeinate[4]是一個阻止操作系統(tǒng)進入睡眠狀態(tài)的程序。如果系統(tǒng)休眠，程序?qū)o法在半夜運行。
—?4?—
詳細設計
用戶輸入
用戶名、密碼、日期等都是從命令行參數(shù)中輸入的。
重試
程序?qū)⒉东@所有異常（頁面未加載等）并重試100次直到預訂成功，成功的預訂通過確認DOM元素進行識別。
瀏覽器選擇
我們需要使用主流瀏覽器之一。我考慮并測試了Chrome、Firefox和Safari，Safari和Chrome都需要額外的步驟來使用相應的Selenium驅(qū)動程序，所以我選擇了Firefox。它也需要一些來自操作系統(tǒng)設置的認證，但只需要在最初幾次確認就可以了。
日志
程序自動執(zhí)行瀏覽器操作，就像是由用戶發(fā)起的一樣。本質(zhì)上，它將在循環(huán)中執(zhí)行以下操作：
查找某個元素
對元素進行操作（輸入文本、選擇選項或單擊）
等待預期結果，然后返回1
因此，每個日志記錄將有兩項內(nèi)容：
執(zhí)行了什么
在等待什么
這樣的日志記錄將使調(diào)試變得容易。
保持電腦持續(xù)運行
如果操作系統(tǒng)在程序啟動到午夜之間進入休眠狀態(tài)，則程序在午夜就無法運行了，Caffeinate可以防止這種情況發(fā)生。它是一個命令行工具，我們在Python中把它作為子進程啟動：
subprocess.Popen([‘caffeinate’,?‘-d’,?‘-w’,?‘%d’?%?os.getpid()])
定位控制
Selenium提供了一組方法[5]來訪問特定的DOM元素，其中xpath的表達能力最強。因此，我們將使用find_element_by_xpath來定位DOM元素，如按鈕、輸入框等。
只要有可能，我們寧愿依賴DOM的內(nèi)部文本來定位它們。相對于DOM結構和屬性（類名等），內(nèi)部文本的優(yōu)勢并不是說它不太可能更改，而是如果它們發(fā)生更改，更容易調(diào)試。當然，我們必須對DOM結構做一些假設，比如我們需要點擊class='control'分區(qū)（div）下的class='logon'的第二個按鈕。
等待頁面加載
在發(fā)送每個HTTP請求后，程序需要等待加載頁面（通常是2~5秒，是的，這個站點很慢）。這是由WebDriverWait API[6]完成的。例如，以下代碼將等待120秒，直到
book_btn?=?WebDriverWait(driver,?120).until(EC.element_to_be_clickable((By.XPATH,?“//button[@ng-reflect-router-link=’/Appointments’]”)))
如果按鈕在120秒內(nèi)加載失敗，將引發(fā)異常。
更多的實現(xiàn)細節(jié)
選擇正確的日期。假設我們想預定4月14日，我們無法在預訂日歷上選擇文本為‘14’的單元格，因為3/14的單元格有類似的屬性。當前月份的單元格必須包含有class cal-in-month。
調(diào)整月份。預訂日歷顯示的是當月的當天，而不是我們打算預訂的月份。如果兩天后就是下個月，這就會有問題。因此，我們必須添加另一個步驟實現(xiàn)在這個邊界情況下選擇正確的月份。
—?5?—
操作流程
假設我想預訂4月14日的游泳池，需要在4月11日的任意時間運行以下命令：
python?book.py?--username?xxxxxx?--password?xxxxxx?--day?14?--time?‘5:00?PM’?--sport?small_pool
程序?qū)⒚啃菝?秒鐘被喚醒檢查一次時間，這個檢查不會有任何明顯的CPU消耗。Caffeinate將阻止操作系統(tǒng)進入睡眠狀態(tài)，直到午夜時分。
在4月12日午夜，它將啟動Firefox瀏覽器，并自動完成預訂。之后，Caffeinate進程和主進程都將退出，操作系統(tǒng)將正常進入休眠狀態(tài)。
4月12日的早上，我會看一下日志，看看預訂是否成功。
一個有趣的事實
競爭確實非常激烈，通常在第1分鐘預約就結束了。每個時段總共只有6個名額，毫無疑問，在早上6點預訂是不可能的。
相關鏈接：
https://github.com/luanjunyi/smac_booking_robot
https://docs.google.com/document/d/1NRj-NdDW_wD1-GwZAJc-Nfrbq8xMiX1Hggrzguh-fjY/edit?usp=sharing
https://www.selenium.dev/
https://ss64.com/osx/caffeinate.html
https://selenium-python.readthedocs.io/locating-elements.html
- https://selenium-python.readthedocs.io/waits.html?highlight=WebDriverWait#explicit-waits
作者：俞凡 譯
來源：DeepNoMind
