構(gòu)建Python庫(kù)API有用的建議清單

本篇文章基于 2017 PyCon 大會(huì)上的演講：How to make a good library API。列出對(duì)于構(gòu)建 Python 庫(kù) API 有用的建議清單。

簡(jiǎn)潔性

在 README 文件中寫入簡(jiǎn)單的客戶端代碼。例如：Pendulum 的 README文件就是以簡(jiǎn)單的用戶代碼開始的。

減少冗余的代碼：數(shù)一數(shù)從第一行開始到你真正調(diào)用 API 函數(shù)的行數(shù)。例如： 與 Request 庫(kù)相比，進(jìn)行 HTTP 請(qǐng)求時(shí) urllib2 庫(kù)就很多的冗余代碼。

使用案例例如： 這個(gè)網(wǎng)頁(yè)展示的內(nèi)容：https://python-social-auth-docs.readthedocs.io/en/latest/use_cases.html

在實(shí)踐中逐步完善：實(shí)用且明智的缺省值設(shè)置

- 具有缺省設(shè)置，并根據(jù)最常用的使用情況來設(shè)置缺省值。

-設(shè)置參數(shù)位置，將最常用的參數(shù)放在前面，將相似的放在一起。例如： JavaScript 的history.pushState函數(shù)的默認(rèn)參數(shù)順序是：state, title, URL。然而很多用戶僅僅想要將 URL 添加進(jìn)歷史值中，但是實(shí)際的情況卻迫使他們不得不設(shè)置 state 與 title 參數(shù)的值。

不要將源代碼片段復(fù)制粘貼進(jìn)你的 API 中。

避免麻煩的輸入：- 檢查是否存在參數(shù)名歧義的情況。例如在 Scrapy 1.2 中，send 方法有一個(gè)to參數(shù)，接收的是字符串列表。如果用戶傳入一個(gè)字符串，這個(gè)方法就會(huì)遍歷這個(gè)字符串，并將每個(gè)字符當(dāng)做一個(gè)郵箱地址并發(fā)送郵件。在 Scrapy 1.3 中則修改了這個(gè) Bug，修改后即可以接收字符串，也可以接收字符串列表。- 檢測(cè)是否只是為了調(diào)用 API 就實(shí)例化某些東西的情況。如果存在，可以考慮接收封裝值。例如：對(duì)于一個(gè)僅接受類文件對(duì)象的函數(shù)，如果用戶想要調(diào)用它，就不得不使用 StringIO模塊。- 檢查是否可以使用內(nèi)置類型來替換自定義類型?；蛘邇烧叨贾С质褂谩?/p>

堅(jiān)持最小驚訝原則（ Principle of least astonishment）：如果一個(gè)函數(shù)特征很讓人吃驚，或許就應(yīng)該考慮重新設(shè)計(jì)它了。- 程序默認(rèn)的行為是用戶所期望的嗎？- 程序默認(rèn)的行為是否符合用戶對(duì)于程序性能、副作用，安全性，可靠性，安全性以及限制條件的要求？

要做到抽象- 讓用戶不需要關(guān)心問題是怎么解決的，而是關(guān)心要解決什么問題。 例如： 為了完成一個(gè)簡(jiǎn)單的工作，項(xiàng)目開發(fā)人員不必過于在意任務(wù)序列、消息破壞，序列化等操作，他們只需要使用 @aap.task 這樣一個(gè)裝飾器即可。 API 關(guān)注的是任務(wù)的定義而不是完成任務(wù)的過程。- 檢查 API 中是否包含了不應(yīng)該有的東西，牢記，要小心所謂的“抽象漏洞定理”（ The Law of Leaky Abstractions）。例如： RPC（remote procedure call）就是一個(gè)很好的反面教材，因?yàn)樗鼘⑦h(yuǎn)程資源當(dāng)做了本地資源進(jìn)行抽象處理，但實(shí)際上遠(yuǎn)程資源的處理不同于本地資源。

像點(diǎn) Python 的樣子- 努力向常見的 Python 習(xí)俗靠近，使你的 API 調(diào)用看起來就跟 Python 內(nèi)置的 API 一樣。 例如在 Python2 中，ConfigParser.get 接受一個(gè) section 參數(shù)和一個(gè) option 參數(shù)。但是這個(gè)并不符合 Python 習(xí)俗，在 Python 的字典（dict）對(duì)象的 get 方法中，我們接受的是 key 參數(shù) 和一個(gè)缺省參數(shù)。 在 Python3 中，這個(gè)問題得以修復(fù)，此函數(shù)的參數(shù)輸入就類似字典那樣了。

一致性

命名問題：你 API 中的命名是否和 Python 的習(xí)俗保持了一致性？ 我們命名應(yīng)該與 PEP8 中所給出一致。PEP8 是 Python 官方的代碼風(fēng)格指南。為了保持命名與代碼風(fēng)格的一致性，建議使用 flake8 來規(guī)范你的 API 代碼。

命名問題：API 中的命名是否一致？- 術(shù)語(yǔ)的順序：string_encodeVSdecode_string- 縮寫問題：activate_prevVSfetch_previous以及bin2hex VS strtolower- 是否帶有下劃線：gettypeVSget_class- 單復(fù)數(shù)問題：values_list VSvalue_list- 正負(fù)問題：button.enabled == TrueVSbutton.disabled == True

空值問題：在空值意義的定義是否一致？目前的是最好的選擇嗎？- 決定下面哪個(gè)代表了空值：None、False、[]、''、0- 小心一些出人意料的值：bool(datetime.time(0)) == False在Python3.5以前是這樣

參數(shù)問題：在參數(shù)的順序上是否具有一致性？例如：datetime.datetime(year, month, day, minute, second, microsecond)vsdatetime.timedelta(days, seconds, microseconds, milliseconds, minutes, hours, weeks)

行為問題：在相似或者不同的行為上是否具有一致性？行為的不對(duì)稱應(yīng)該反應(yīng)在格式的不對(duì)稱上。例如，numbers.sort()VSsort(numbers)

靈活性

減小整體的不連續(xù)性- 檢查所有的類的功能是否單一職責(zé)？如果不是，就應(yīng)該把那些類拆解開來。例如，一個(gè)從緩存中獲取數(shù)據(jù)的類應(yīng)該將其連接緩存服務(wù)器的步驟交給另一個(gè)類做。

- 檢查函數(shù)的名稱中是否包含了`and`或者是否包含多個(gè)操作。 如果確實(shí)如此，應(yīng)該將這個(gè)函數(shù)拆成多個(gè)不同的函數(shù)。但是，如果這個(gè)函數(shù)經(jīng)常被調(diào)用，那么可以保留一個(gè)結(jié)合了眾多函數(shù)的函數(shù)。例如：print_formatted函數(shù)可以被拆解為兩個(gè)函數(shù)：print和formated

- 檢查是否存在用戶復(fù)制粘貼代碼以改變函數(shù)功能的行為。 應(yīng)該提供代碼重構(gòu)，回調(diào)功能。

- 檢查在函數(shù)內(nèi)部是否使用了屬性值，如果有可以使用 get_something 方法代替。例如在 Djando 的 REST 框架中， CursorPagination 這個(gè)類僅僅支持一個(gè)固定大小的屬性值：page_size，其原因就是這個(gè)類沒有g(shù)et_page_size這個(gè)方法。 這個(gè)問題再后來就通過上述方法解決了，即添加了 get_page_size方法。

- 盡量避免隱藏可能有用的參數(shù)。例如我們的 API 中調(diào)用了另一個(gè)低級(jí)的 API 但是卻沒有展示這個(gè)低級(jí) API 的參數(shù)情況

- 返回用戶可能需要的一切信息

- 用戶調(diào)用 API 時(shí)，要處理用戶可能需要所有情況

- 在進(jìn)行 API 測(cè)試的時(shí)候要測(cè)試每一個(gè)mock.pathch。 雖然在程序運(yùn)行的時(shí)候有一些東西不容易修改，但我們可以通過設(shè)置參數(shù)來修改某些東西。例如，Python 的內(nèi)置函數(shù)sched.scheduler接受兩個(gè)參數(shù)timefunc和delayfunc。而我們沒必要對(duì)time.monotonic和time.sleep兩個(gè)函數(shù)進(jìn)行 mock 測(cè)試，用戶會(huì)根據(jù)自己的需求進(jìn)行相應(yīng)的改變。

建立抽象- 按照底層實(shí)現(xiàn)的結(jié)構(gòu)，去封裝我們的函數(shù)成員與對(duì)象。例如 Beautiful Soup 就為多個(gè)分析器設(shè)計(jì)了同樣的 API 結(jié)構(gòu)。

- 提供多級(jí)的抽象結(jié)構(gòu)，從最簡(jiǎn)單到最個(gè)性化。例如， Celery 既提供了@app.task這個(gè)裝飾器，又提供了個(gè)性化的 task 類，而這個(gè)類繼承于celery.Task

- 提供擺脫封裝的方法，讓用戶可以直接使用被抽象的資源和能力。例如，Django 的查詢集合支持使用.extra方法將自定義的 SQL 與 ORM 進(jìn)行結(jié)合來產(chǎn)生查詢語(yǔ)句，同時(shí)也支持使用.raw來直接使用原生的 SQL 查詢語(yǔ)句。

- 將底層實(shí)現(xiàn)中常見的錯(cuò)誤進(jìn)行封裝，避免給用戶直接報(bào)錯(cuò)。例如當(dāng) API 支持多個(gè)數(shù)據(jù)引擎的時(shí)候，出現(xiàn)數(shù)據(jù)庫(kù)連接錯(cuò)誤時(shí)，其顯示信息應(yīng)該一樣。這個(gè)幫助用戶找出問題所在，并且在修改數(shù)據(jù)庫(kù)引擎時(shí)不會(huì)需要修改很多代碼。

要有 Python 范- 對(duì)于獲?。╣et）和 設(shè)置（set）操作使用 Python 的自帶屬性- 對(duì)于運(yùn)算符重載要使用魔法方法（magic method）- 對(duì)于簡(jiǎn)單的調(diào)試，使用__repr__魔法方法- 對(duì)于包含 打開-關(guān)閉 或者 開始-結(jié)束 這樣的包含生命周期的問題，使用 with 語(yǔ)句- 對(duì)于容易組合共同行為或者登記某些東西使用裝飾器- 對(duì)于迭代使用迭代器- 對(duì)于復(fù)雜的邏輯問題使用生成器- 對(duì)異步問題使用 asyncio- 盡量使用內(nèi)置的集合- 對(duì)于簡(jiǎn)單的控制反演使用簡(jiǎn)單的高級(jí)函數(shù)，例如在list.sort函數(shù)中接受key參數(shù)作為等級(jí)高低計(jì)算函數(shù)以便計(jì)算列表的順序。- 對(duì)于復(fù)雜的流程問題，可以按照 函數(shù)/類的管道、繼承、生成器的順序逐一考慮。例如 管道問題可參考：python-social-auth 管道；繼承問題可參考： Django 的類； 生成器問題可參考： Scrapy 的爬蟲程序。- 尊重鴨子式編程風(fēng)格，要求諒解比諒解本身更加容易

國(guó)際化終端用戶看到的字符串。

安全性

檢查文檔中的用于描述函數(shù)功能的警告性字眼，例如： warning，careful，remember to, dont't forget。如果存在這些字眼，就得考慮如何更改代碼使得函數(shù)更加安全穩(wěn)定。

檢查常見的錯(cuò)誤，使用 Python 內(nèi)置的 warning 模塊來記錄警告

明確不安全的行為。例如如果一些變量沒有設(shè)置值，不要特意為它設(shè)置。不要到處寫 fileds = None 這樣的語(yǔ)句。

不要通過對(duì)象名稱或者模塊名稱來隱式地鏈接代碼，使用一個(gè)注冊(cè)函數(shù)或者注冊(cè)裝飾器。例如 Django-admin 的注冊(cè)問題不僅支持通過函數(shù)也支持裝飾器。

不要依賴方法的調(diào)用順序，盡量使用 with 語(yǔ)句。

快速報(bào)錯(cuò)： 程序出錯(cuò)就直接退出并不是 Python 式的思維

- 當(dāng)一個(gè)庫(kù)函數(shù)接受到一個(gè)無效的具有錯(cuò)誤格式或者錯(cuò)誤表達(dá)的參數(shù)，例如參數(shù)溢出，就產(chǎn)生一個(gè) Value Error 錯(cuò)誤。- 當(dāng)一個(gè)庫(kù)函數(shù)接受到一個(gè)不兼容類型的數(shù)據(jù)便產(chǎn)生一個(gè) TypeError 錯(cuò)誤，例如 duck 類型并不兼容 quack 類型。 不要在 if isinstance(duck, LibDuck) 或者 if type(duck) == LibDuck) 這樣的語(yǔ)句中引發(fā)異常。首先嘗試使用 quack，如果錯(cuò)誤則引發(fā) TypeError 異常，并打印明確的錯(cuò)誤信息。

總結(jié)我的 API 旨在將簡(jiǎn)單的事情變的簡(jiǎn)潔，將復(fù)雜的事情變?yōu)楝F(xiàn)實(shí)，將錯(cuò)誤的事情永遠(yuǎn)杜絕。