一日一技:如何閱讀技術文件(直播文案)

語言: CN / TW / HK

攝影:產品經理 

一盤這個醬蟹200多

今天這篇文章,是我今天(1月16日)知識星球直播的概要。詳細內容,大家可以觀看直播回放影片。已經在知識星球的同學,直接點選連線就能查看回放。尚未加入星球的同學,請在一週後,到我的B站上觀看影片。

我平常在公眾號粉絲群裡面常說,要多看官方文件,少看部落格。有些同學就說,官方文件看不懂啊。例如你想學習Python的logging模組,然後你會看到 logging — Python 的日誌記錄工具 — Python 3.10.2 文件 [1] 是下面這樣的:

又比如你想學習Golang裡面 net/http 的使用,你會看到它的文件 http package - net/http - pkg.go.dev [2] 是這樣的:

這樣的文件,你看完以後,可能也寫不出一個完整的可以執行的程式。但還有另一種文件,你就算第一次接觸這個軟體或者框架,你也能跟著它的指導寫程式碼,例如Scrapy的官方教程 Scrapy Tutorial — Scrapy 2.5.1 documentation [3] 。你甚至不會英語也沒關係,你就跟著黃綠背景的框框寫命令,複製程式碼,你也可以把爬蟲搞出來。

為什麼會有這樣的差異呢?因為我們平常籠統地叫做 文件 的東西,其實有兩種。前兩個反例是 API Reference ,API介面文件。Scrapy的叫做 Tutorial 教程 。API介面文件和教程文件是面向兩種不同用途的。

Python的Logging模組也有教程文件版: Logging HOWTO [4]

教程文件其實沒有什麼好說的,就是一步一步跟著走就能完成。教程文件會告訴你, 你不知道你不知道 的東西。

而API介面文件看起來就會比較費勁,因為它是用來告訴你 你知道你不知道 的東西。例如你知道有某個功能某個函式,但是你不知道它的具體語法怎麼寫,這個時候就用API介面文件。

在直播裡面,我以Scrapy下載器中介軟體和Pyppeteer為例來進行說明。我知道下載器中介軟體怎麼啟用,我也知道我要修改代理IP,應該編寫下載器中介軟體的 process_request 方法,但是這個方法接受哪些引數?它能返回什麼東西?這個時候我就可以到API介面文件裡面進行查詢。

同理,在Pyppeteer的Github倉庫裡面,Readme寫了兩個簡單的例子告訴我怎麼使用它開啟一個網頁。但是我應該怎麼使用XPath從頁面上選中一個元素,然後點選它?這個時候就可以到API介面文件裡面,搜尋 xpath ,找到對應的方法,看它接受什麼引數,返回什麼內容,會報什麼錯。

直播的最後,我和大家一起試圖從 net/http 的API文件裡面尋找怎麼更換代理IP。由於我用Go發起網路請求,主要是使用 imroc/req ,很少使用 net/http ,我處於 我不知道我不知道 的狀態,於是我跟大家一起崩潰在了這個API介面文件裡面。

參考文獻

[1] logging — Python 的日誌記錄工具 — Python 3.10.2 文件:  https://docs.python.org/zh-cn/3/library/logging.html

[2] http package - net/http - pkg.go.dev:  https://pkg.go.dev/net/http

[3] Scrapy Tutorial — Scrapy 2.5.1 documentation:  https://docs.scrapy.org/en/latest/intro/tutorial.html

[4] Logging HOWTO:  https://docs.python.org/3/howto/logging.html#logging-howto

未聞 Code·知識星球開放啦!

一對一答疑爬蟲相關問題

職業生涯諮詢

面試經驗分享

每週直播分享

......

未聞 Code·知識星球期待與你相見~

一二線大廠在職員工

十多年碼齡的程式設計老鳥

國內外高校在讀學生

中小學剛剛入門的新人

“未聞 Code技術交流群” 等你來!

入群方式:新增微信“mekingname”,備註“粉絲群”(謝絕廣告黨,非誠勿擾!)