Python 函數庫 APIs 編寫指南

來源:Python工程師

ID:pythonbuluo

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

簡潔性

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

• 減少冗餘的代碼：數一數從第一行開始到你真正調用 API 函數的行數。例如： 與 Request 庫相比，進行 HTTP 請求時 urllib2 庫就很多的冗餘代碼。

• 使用案例例如： 這個網頁展示的內容：https://python-social-auth-docs.readthedocs.io/en/latest/use_cases.html

• 在實踐中逐步完善：實用且明智的缺省值設置

– 具有缺省設置，並根據最常用的使用情況來設置缺省值。

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

• 不要將源代碼片段復制黏貼進你的 API 中。

• 避免麻煩的輸入：- 檢查是否存在參數名歧義的情況。例如在 Scrapy 1.2 中，send 方法有一個to參數，接收的是字符串列表。如果用戶傳入一個字符串，這個方法就會遍歷這個字符串，並將每個字符當做一個郵箱地址並發送郵件。在 Scrapy 1.3 中則修改了這個 Bug，修改後即可以接收字符串，也可以接收字符串列表。- 檢測是否只是為了調用 API 就實例化某些東西的情況。如果存在，可以考慮接收封裝值。例如：對於一個僅接受類文件對象的函數，如果用戶想要調用它，就不得不使用 StringIO模塊。- 檢查是否可以使用內置類型來替換自定義類型。或者兩者都支持使用。

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

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

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

一致性

• 命名問題：你 API 中的命名是否和 Python 的習俗保持了一致性？ 我們命名應該與 PEP8 中所給出一致。PEP8 是 Python 官方的代碼風格指南。為了保持命名與代碼風格的一致性，建議使用 flake8 來規範你的 API 代碼。

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

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

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

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

靈活性

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

  – 檢查函數的名稱中是否包含了`and`或者是否包含多個操作。 如果確實如此，應該將這個函數拆成多個不同的函數。但是，如果這個函數經常被調用，那麼可以保留一個結合了眾多函數的函數。例如：print_formatted函數可以被拆解為兩個函數：print和formated

  – 檢查是否存在用戶復制黏貼代碼以改變函數功能的行為。 應該提供代碼重構，回調功能。

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

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

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

  – 用戶調用 API 時，要處理用戶可能需要所有情況

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

• 建立抽象- 按照底層做到的結構，去封裝我們的函數成員與對象。例如 Beautiful Soup 就為多個分析器設計了同樣的 API 結構。

  – 提供多級的抽象結構，從最簡單到最個性化。例如， Celery 既提供了@app.task這個裝飾器，又提供了個性化的 task 類，而這個類繼承於celery.Task

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

  – 將底層做到中常見的錯誤進行封裝，避免給用戶直接報錯。例如當 API 支持多個數據引擎的時候，出現數據庫連接錯誤時，其顯示信息應該一樣。這個幫助用戶找出問題所在，並且在修改數據庫引擎時不會需要修改很多代碼。

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

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

安全性

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

• 檢查常見的錯誤，使用 Python 內置的 warning 模塊來記錄警告

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

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

• 不要依賴方法的調用順序，盡量使用 with 語句。

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

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

總結我的 API 旨在將簡單的事情變的簡潔，將複雜的事情變為現實，將錯誤的事情永遠杜絕。

英文原文：http://python.apichecklist.com/ 譯者：無

Linux雲計算及運維架構師高薪實戰班》2018年12月10日即將開課中，120天衝擊Linux運維年薪30萬，改變速約~~~~

*聲明：推送內容及圖片來源於網路，部分內容會有所改動，版權歸原作者所有，如來源信息有誤或侵犯權益，請聯繫我們刪除或授權事宜。

– END –