點擊上方“朱小廝的博客”，選擇“設為星標”

后臺回復"書"，獲取

后臺回復“k8s”，可領取k8s資料

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

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

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

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

—?1?—

問題描述

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

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

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

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

—?2?—

需求

• 自動提前兩天在半夜預訂健身房

• 程序啟動后不需要人工交互，應該具有容錯性，能夠進行合理的重試

• 可以在Mac電腦上運行

• 用戶可以指定用戶名、密碼、預約的項目、日期和時間等

不在考慮范圍內：

• 只提前1或2天預訂，或當天預訂

• 容忍操作系統或網絡問題

• 在預約服務器停止運行后還要能夠工作

• 在網站結構（HTML）改變后，還要能夠工作

—?3?—

概要設計

瀏覽器自動化 vs 模擬請求

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

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

• [優點] 瀏覽器自動化啟動了一個真實的瀏覽器實例，所以我們知道程序運行時發生了什么，它使調試和開發更加容易。

• [優點] 網站需要JavaScript加載控件，而這較難通過編程實現，可能需要控制一些渲染引擎。

• [缺點] 瀏覽器自動化依賴于HTML結構，而模擬請求依賴于HTTP API，API相對穩定，不太可能改變。

顯然利大于弊。

系統概述

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

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

—?4?—

詳細設計

用戶輸入

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

重試

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

瀏覽器選擇

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

日志

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

查找某個元素

對元素進行操作（輸入文本、選擇選項或單擊）

等待預期結果，然后返回1

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

• 執行了什么

• 在等待什么

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

保持電腦持續運行

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

subprocess.Popen([‘caffeinate’,?‘-d’,?‘-w’,?‘%d’?%?os.getpid()])

定位控制

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

只要有可能，我們寧愿依賴DOM的內部文本來定位它們。相對于DOM結構和屬性（類名等），內部文本的優勢并不是說它不太可能更改，而是如果它們發生更改，更容易調試。當然，我們必須對DOM結構做一些假設，比如我們需要點擊class='control'分區（div）下的class='logon'的第二個按鈕。

等待頁面加載

在發送每個HTTP請求后，程序需要等待加載頁面（通常是2~5秒，是的，這個站點很慢）。這是由WebDriverWait API[6]完成的。例如，以下代碼將等待120秒，直到<button ng-reflect-router-link= ' /Appointments ' >被加載并成為可被點擊的按鈕。

book_btn?=?WebDriverWait(driver,?120).until(EC.element_to_be_clickable((By.XPATH,?“//button[@ng-reflect-router-link=’/Appointments’]”)))

如果按鈕在120秒內加載失敗，將引發異常。

更多的實現細節

選擇正確的日期。假設我們想預定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將阻止操作系統進入睡眠狀態，直到午夜時分。

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

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

想知道更多？掃描下面的二維碼關注我后臺回復"技術"，加入技術群 后臺回復“k8s”，可領取k8s資料【精彩推薦】

• ClickHouse到底是什么？為什么如此牛逼！

• 原來ElasticSearch還可以這么理解

• 面試官：InnoDB中一棵B+樹可以存放多少行數據？

• 架構之道：分離業務邏輯和技術細節

• 星巴克不使用兩階段提交

• 面試官：Redis新版本開始引入多線程，談談你的看法？

• 喜馬拉雅自研網關架構演進過程

• 收藏：存儲知識全面總結

• 微博千萬級規模高性能高并發的網絡架構設計

總結

以上是生活随笔為你收集整理的怎么写出一份令人惊叹的设计文档？的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。