怎么寫設計文檔？

來源：DeepNoMind

• 1 問題描述
• 2 需求
• 3 概要設計
• 4 詳細設計
• 5 操作流程

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

這篇有趣的英文小短文通過一個簡單的小例子介紹了Google工程師是怎么寫設計文檔的。本文為中文翻譯。原文鏈接如下：https://reurl.cc/ZrVD2A

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

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

1 問題描述

在新冠疫情期間，要求健身房控制現場會員總數，要求會員在去健身房之前先在網站上預訂。預約需要提前兩天，從午夜開始。例如，2021年04月01日的預訂將在當地時間2021年03月30日00:00 AM開放。

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

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

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

2 需求

• 自動提前兩天在半夜預訂健身房
• 程序啟動后不需要人工交互，應該具有容錯性，能夠進行合理的重試
• 可以在Mac電腦上運行
• 用戶可以指定用戶名、密碼、預約的項目、日期和時間等

不在考慮范圍內：

• 只提前1或2天預訂，或當天預訂
• 容忍操作系統(tǒng)或網絡問題
• 在預約服務器停止運行后還要能夠工作
• 在網站結構（HTML）改變后，還要能夠工作

3 概要設計

瀏覽器自動化 vs 模擬請求

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

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

• [優(yōu)點] 瀏覽器自動化啟動了一個真實的瀏覽器實例，所以我們知道程序運行時發(fā)生了什么，它使調試和開發(fā)更加容易。
• [優(yōu)點] 網站需要JavaScript加載控件，而這較難通過編程實現，可能需要控制一些渲染引擎。
• [缺點] 瀏覽器自動化依賴于HTML結構，而模擬請求依賴于HTTP API，API相對穩(wěn)定，不太可能改變。

顯然利大于弊。

系統(tǒng)概述

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

Caffeinate[4]是一個阻止操作系統(tǒng)進入睡眠狀態(tài)的程序。如果系統(tǒng)休眠，程序將無法在半夜運行。

4 詳細設計

用戶輸入

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

重試

程序將捕獲所有異常（頁面未加載等）并重試100次直到預訂成功，成功的預訂通過確認DOM元素進行識別。

瀏覽器選擇

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

日志

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

1. 查找某個元素
2. 對元素進行操作（輸入文本、選擇選項或單擊）
3. 等待預期結果，然后返回1

因此，每個日志記錄將有兩項內容：

• 執(zhí)行了什么
• 在等待什么

這樣的日志記錄將使調試變得容易。

保持電腦持續(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的內部文本來定位它們。相對于DOM結構和屬性（類名等），內部文本的優(yōu)勢并不是說它不太可能更改，而是如果它們發(fā)生更改，更容易調試。當然，我們必須對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秒內加載失敗，將引發(fā)異常。

更多的實現細節(jié)

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

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

5 操作流程

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

python?book.py?--username?xxxxxx?--password?xxxxxx?--day?14?--time?‘5:00?PM’?--sport?small_pool

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

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

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

一個有趣的事實

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

1.?面試官：有了 for 循環(huán) 為什么還要 forEach ？
2.?PacVim：一個學習vim命令的游戲，再也不怕記不住了！
3.?100 行代碼透徹解析 RPC 原理
4.?阿里專家：如何畫出優(yōu)秀的架構圖？
最近面試BAT，整理一份面試資料《Java面試BATJ通關手冊》，覆蓋了Java核心技術、JVM、Java并發(fā)、SSM、微服務、數據庫、數據結構等等。
獲取方式：點“在看”，關注公眾號并回復?Java?領取，更多內容陸續(xù)奉上。
PS：因公眾號平臺更改了推送規(guī)則，如果不想錯過內容，記得讀完點一下“在看”，加個“星標”，這樣每次新文章推送才會第一時間出現在你的訂閱列表里。
點“在看”支持小哈呀，謝謝啦??！