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

簡潔性

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

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

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

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

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

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

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

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

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

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

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

一致性

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

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

空值問題：在空值意義的定義是否一致？目前的是最好的選擇嗎？- 決定下面哪個代表了空值：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)

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

靈活性

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

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

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

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

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

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

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

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

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

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

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

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

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

國際化終端用戶看到的字符串。

安全性

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

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

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

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

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

快速報錯： 程序出錯就直接退出并不是 Python 式的思維

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

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