怎么寫出一份令人驚嘆的設(shè)計文檔？

一份好的設(shè)計文檔需要提供清晰的問題描述、整體的概要設(shè)計、涵蓋各個細(xì)節(jié)的詳細(xì)設(shè)計等。

這篇有趣的英文小短文通過一個簡單的小例子介紹了Google工程師是怎么寫設(shè)計文檔的。本文為中文翻譯。原文鏈接如下：https://luanjunyi.medium.com/how-do-i-write-engineering-design-docs-in-google-an-example-f19febe0297c

寫文檔是我在谷歌學(xué)到的最重要的技能之一。在谷歌，文檔被用來討論問題、作為真實的信息源、組織知識。在我工作過的其他公司中，沒有一家對如何使用文檔進(jìn)行協(xié)作有這樣深刻的理解。

這篇文章就是關(guān)于我在谷歌如何寫設(shè)計文檔的一個例子，這是一個真實的項目，用于在新冠疫情期間控制健身房現(xiàn)場人數(shù)。即使在新冠疫情結(jié)束后不需要預(yù)約健身房了，也可以訪問GitHub上的源代碼[1]。為了讓這篇文章更有趣，現(xiàn)在每個人都可以在谷歌文檔[2]上進(jìn)行評論，而且谷歌文檔的格式也比Medium支持的要好。

在新冠疫情期間，要求健身房控制現(xiàn)場會員總數(shù)，要求會員在去健身房之前先在網(wǎng)站上預(yù)訂。預(yù)約需要提前兩天，從午夜開始。例如，2021年04月01日的預(yù)訂將在當(dāng)?shù)貢r間2021年03月30日00:00 AM開放。

這個健身房里的游泳池提供的位置非常有限。我嘗試了好幾次，都沒能預(yù)定到早上6點的時間，后來工作人員告訴我，由于需求量很大，必須在午夜預(yù)訂。但是熬夜到半夜會打亂我的生物鐘，所以我沒法接受。

而且我覺得雇人做這件事也很不好，因為在內(nèi)心深處，我認(rèn)為早睡是健康高效生活方式的核心習(xí)慣，用金錢剝奪別人的好習(xí)慣是不道德的。在被告知沒有別的辦法之后，我決定寫一個程序來為我做預(yù)訂。

我個人認(rèn)為用機(jī)器人來做工作是對別人的不公平，所以我對這個決定一點兒也沒感到自豪。相反，我認(rèn)為健身房應(yīng)該提高一些場地的價格。但這顯然超出了設(shè)計文檔的范圍，而且是非常主觀的想法。

瀏覽器自動化 vs 模擬請求

瀏覽器自動化是指通過程序來控制真實的瀏覽器，并在GUI上自動化操作。模擬請求是指讓程序通過HTTP與服務(wù)器交互，這個程序就像是一個Web瀏覽器（而不是控制一個瀏覽器）。

考慮到下面幾點，我認(rèn)為瀏覽器自動化比模擬請求更好：

• [優(yōu)點] 瀏覽器自動化啟動了一個真實的瀏覽器實例，所以我們知道程序運(yùn)行時發(fā)生了什么，它使調(diào)試和開發(fā)更加容易。

• [優(yōu)點] 網(wǎng)站需要JavaScript加載控件，而這較難通過編程實現(xiàn)，可能需要控制一些渲染引擎。

• [缺點] 瀏覽器自動化依賴于HTML結(jié)構(gòu)，而模擬請求依賴于HTTP API，API相對穩(wěn)定，不太可能改變。

顯然利大于弊。

系統(tǒng)概述

Selenium[3]是一個提供瀏覽器自動化解決方案的軟件庫。我們的程序?qū)⒂肞ython編寫，并通過Python API控制Selenium，Selenium則通過它的Gecko驅(qū)動程序控制Firefox。

Caffeinate[4]是一個阻止操作系統(tǒng)進(jìn)入睡眠狀態(tài)的程序。如果系統(tǒng)休眠，程序?qū)o法在半夜運(yùn)行。

用戶輸入

用戶名、密碼、日期等都是從命令行參數(shù)中輸入的。

重試

程序?qū)⒉东@所有異常（頁面未加載等）并重試100次直到預(yù)訂成功，成功的預(yù)訂通過確認(rèn)DOM元素進(jìn)行識別。

瀏覽器選擇

我們需要使用主流瀏覽器之一。我考慮并測試了Chrome、Firefox和Safari，Safari和Chrome都需要額外的步驟來使用相應(yīng)的Selenium驅(qū)動程序，所以我選擇了Firefox。它也需要一些來自操作系統(tǒng)設(shè)置的認(rèn)證，但只需要在最初幾次確認(rèn)就可以了。

日志

程序自動執(zhí)行瀏覽器操作，就像是由用戶發(fā)起的一樣。本質(zhì)上，它將在循環(huán)中執(zhí)行以下操作：

1. 查找某個元素

2. 對元素進(jìn)行操作（輸入文本、選擇選項或單擊）

3. 等待預(yù)期結(jié)果，然后返回1

因此，每個日志記錄將有兩項內(nèi)容：

• 執(zhí)行了什么

• 在等待什么

這樣的日志記錄將使調(diào)試變得容易。

保持電腦持續(xù)運(yùn)行

如果操作系統(tǒng)在程序啟動到午夜之間進(jìn)入休眠狀態(tài)，則程序在午夜就無法運(yùn)行了，Caffeinate可以防止這種情況發(fā)生。它是一個命令行工具，我們在Python中把它作為子進(jìn)程啟動：

定位控制

Selenium提供了一組方法[5]來訪問特定的DOM元素，其中xpath的表達(dá)能力最強(qiáng)。因此，我們將使用find_element_by_xpath來定位DOM元素，如按鈕、輸入框等。

只要有可能，我們寧愿依賴DOM的內(nèi)部文本來定位它們。相對于DOM結(jié)構(gòu)和屬性（類名等），內(nèi)部文本的優(yōu)勢并不是說它不太可能更改，而是如果它們發(fā)生更改，更容易調(diào)試。當(dāng)然，我們必須對DOM結(jié)構(gòu)做一些假設(shè)，比如我們需要點擊class='control'分區(qū)（div）下的class='logon'的第二個按鈕。

等待頁面加載

在發(fā)送每個HTTP請求后，程序需要等待加載頁面（通常是2~5秒，是的，這個站點很慢）。這是由WebDriverWait API[6]完成的。例如，以下代碼將等待120秒，直到被加載并成為可被點擊的按鈕。

如果按鈕在120秒內(nèi)加載失敗，將引發(fā)異常。

更多的實現(xiàn)細(xì)節(jié)

選擇正確的日期。假設(shè)我們想預(yù)定4月14日，我們無法在預(yù)訂日歷上選擇文本為‘14’的單元格，因為3/14的單元格有類似的屬性。當(dāng)前月份的單元格必須包含有class cal-in-month。

調(diào)整月份。預(yù)訂日歷顯示的是當(dāng)月的當(dāng)天，而不是我們打算預(yù)訂的月份。如果兩天后就是下個月，這就會有問題。因此，我們必須添加另一個步驟實現(xiàn)在這個邊界情況下選擇正確的月份。

假設(shè)我想預(yù)訂4月14日的游泳池，需要在4月11日的任意時間運(yùn)行以下命令：

程序?qū)⒚啃菝?秒鐘被喚醒檢查一次時間，這個檢查不會有任何明顯的CPU消耗。Caffeinate將阻止操作系統(tǒng)進(jìn)入睡眠狀態(tài)，直到午夜時分。

在4月12日午夜，它將啟動Firefox瀏覽器，并自動完成預(yù)訂。之后，Caffeinate進(jìn)程和主進(jìn)程都將退出，操作系統(tǒng)將正常進(jìn)入休眠狀態(tài)。

4月12日的早上，我會看一下日志，看看預(yù)訂是否成功。

一個有趣的事實

競爭確實非常激烈，通常在第1分鐘預(yù)約就結(jié)束了。每個時段總共只有6個名額，毫無疑問，在早上6點預(yù)訂是不可能的。

相關(guān)鏈接：

1. https://github.com/luanjunyi/smac_booking_robot

2. https://docs.google.com/document/d/1NRj-NdDW_wD1-GwZAJc-Nfrbq8xMiX1Hggrzguh-fjY/edit?usp=sharing

3. https://www.selenium.dev/

4. https://ss64.com/osx/caffeinate.html

5. https://selenium-python.readthedocs.io/locating-elements.html

6. https://selenium-python.readthedocs.io/waits.html?highlight=WebDriverWait#explicit-waits

作者：俞凡 譯

來源：DeepNoMind