什麼是好的瀏覽器 API？

上個月，我參加了 Mozilla 的另一場討論，這次討論是關於網絡數據庫的未來。雖然討論的內容很有趣，但我發現一個相當籠統的辯論更是如此。最終出現了兩種與 JavaScript 的原生瀏覽器 API 相關的思想流派。一個陣營堅信原生 JavaScript API 應該盡可能低級，期望庫開發者在其之上構建更好的接口。另一個陣營，我是其中的一員，認為中級 API 是要走的路。沒有人認為瀏覽器應該為開發人員提供高級 API。但這一切意味著什麼？

低級

低級 API 只是為了提供功能而設計的。幾乎不需要使 API 漂亮或易於理解，因為它只需要完成這項工作。低級 API 對於新手，有時甚至是中級開發人員來說可能難以理解。這大大減少了可以使用 API 來發現問題的人數。庫開發人員有責任在低級 API 之上實現漂亮、可用的 API，以使一般開發人員可以訪問它們。低級瀏覽器 API 的最佳示例是 document.cookie .

document.cookie property 是 JavaScript 開發人員操作 cookie 的唯一接口，它是有史以來最醜陋的 API 之一。我已經寫了大量關於 cookie 以及如何在 JavaScript 中使用它們的文章，但這裡有一個簡單的概述。為了設置cookie，您需要將正確cookie格式的字符串分配給document.cookie ，如：

document.cookie = "name=Nicholas; domain=nczonline.net; path=/; expires=Sat, 02 May 2009 23:38:25 GMT

要檢索 cookie，您需要閱讀 document.cookie ，它返回以下格式的名稱-值對字符串：

name1=value1; name2=value2; name3=value3; name4=value4

為了檢索您想要的值，您必須首先在字符串中搜索名稱，然後解析出該值。

這個 API 被認為是低級的原因是實現需要知道 cookie 如何工作才能使用它。 document.cookie 屬性有效地模仿了 Set-Cookie 和 Cookie 通常對開發人員隱藏的 HTTP 標頭。為了編寫 cookie，您需要知道要使用的確切字符串格式，這意味著名稱和值需要進行 URI 編碼，cookie 的其他部分需要用分號和空格分隔，並且您需要知道正確的日期格式來設置到期日期。同樣，要讀取 cookie，您需要了解返回的字符串的格式，然後解析出您感興趣的數據。最簡單的用例並不比複雜的用例容易得多。從根本上說，除了已經了解 cookie 的人之外，其他任何人都無法使用此 API。

當大多數開發人員不直接使用 API 時，您可以說它是低級的。他們不能，執行任務所需的認知開銷太高。大多數使用 JavaScript 讀寫 cookie 的開發人員最終都使用 JavaScript 庫抽象，例如 YUI Cookie Utility（適用於 YUI 2 和 YUI 3），它抽像出所有令人討厭的實現細節。

這正是低級 API 的支持者認為應該發生的事情：瀏覽器應該簡單地提供功能，然後依靠開發社區圍繞它們創建可用的 API。低級 API 的主要論點是，您可以圍繞功能進行任意數量的有趣抽象，從而為開發人員提供更多選擇，以了解他們希望如何與功能進行交互。

低級 API 的問題在於啟動時間。因為您通過創建低級 API 限制了潛在用戶的數量，所以您基本上需要等到他們中的一個或多個發現足夠有趣的功能來創建可供開發社區的其他成員訪問的抽象。如果您希望新 API 快速開始使用，以便了解如何改進它，那麼低級 API 就行不通了。

注意： 大多數服務器端語言都有用於讀取/寫入 cookie 的原生抽象（ASP.NET、JSP、PHP），但 JavaScript 仍然沒有。

高級

論點的另一面是高級 API。高級 API 是為開發人員直接使用而設計的，通常非常直觀。這些 API 不僅僅關心提供功能，它們還希望為這些功能提供良好且有用的接口。高級 API 的設計首先考慮到了開發人員，因此，通常需要對開發人員將如何使用 API 進行理論分析。當然，這就是問題所在：您很少知道某人將如何使用 API，因此在瀏覽器中本地創建高級 API 是一項艱鉅的任務，如果不是不可能的話。

各種 JavaScript 庫都是高級 API 的好例子。它們都構建在同一個瀏覽器之上，但為相同的功能提供了截然不同的界面。使用 jQuery 的方式與使用 YUI 的方式非常不同，這是一件好事，因為開發人員可以選擇。但是想像一下，您是否告訴 YUI 開發人員他們必須使用 jQuery 語法編寫代碼，因為這就是所有可用的，反之亦然？你會有一大群不開心的開發人員。強迫人們以某種方式發展是災難的根源。正是這些抽像以及根據需要添加和刪除它們的能力，讓開髮變得愉快，並讓開發人員能夠繼續創新。

高級 API 的認知開銷非常低，因此開發人員可以輕鬆地直接使用它們。沒有人認為高級 API 適合瀏覽器，這是一件好事。選擇是好的，不同的抽像是好的。

中級

快樂的媒介是一個中級 API。在我看來，中級 API 是瀏覽器應該創建和實現的目標。顧名思義，中級 API 存在於低級和高級之間，兩全其美。中級 API 的定義（在我看來）是通過為最常見的用例提供簡單的接口，同時具有允許更強大的操作和不太常見的用例的擴展。第一部分，通用用例接口，非常簡單，無需抽象即可直接使用。不太常見的用例接口允許更複雜，甚至有點遲鈍，因為它會使用得更少。

XMLHttpRequest 就是一個很好的中級 API 的例子 .常見用例可以定義為發送 GET 請求以檢索 XML 數據。實現這一點不需要很多代碼：

var xhr = new XMLHttpRequest();
xhr.open("get", "/somexml", true);
xhr.onreadystatechange = function(){
    if (xhr.readyState == 4){
        if (xhr.status == 200){
            process(xhr.responseXML.getElementsByTagName("item"));
        }
    }
};
xhr.send(null);

雖然有些人會爭論 onreadystatechange 事件處理程序有點醜陋，從根本上說，您最終會檢查少量信息以確定您是否收到了正確的數據。您感興趣的數據位於邏輯位置，並且可以以您需要的格式輕鬆訪問：HTTP 狀態在那裡，並且 XML 被自動解析為 DOM。 API 做了大量工作來直接將這些數據提供給您。

不太常見的用例包括將表單數據發佈到 URL。代碼變得有點難看，但還是可以的：

var xhr = new XMLHttpRequest();
xhr.open("post", "/add", true);
xhr.setRequestHeader("Content-type", "application/x-www-form-urlencoded");
xhr.onreadystatechange = function(){
    if (xhr.readyState == 4){
        if (xhr.status == 200){
            signalComplete();
        }
    }
};
xhr.send(encodeURIComponent(name) + "=" + encodeURIComponent(value));

當然，您可以使用 XMLHttpRequest 對像還可以用於更複雜的過程，例如 Comet。關鍵是常見用例很簡單，並且界面可以輕鬆擴展到更複雜和不太常見的用例。這使得 JavaScript 庫還可以構建更好的接口來處理幕後更複雜用例的醜陋。每個 JavaScript 庫對如何啟動 Ajax 通信以及 XMLHttpRequest 的設計都有不同的看法 界面非常適合這種用法。

注意： 有人認為 XMLHttpRequest 對像也太低級了。我承認它不是最乾淨的 API，但它確實使常見用例易於執行。請記住，最初設計此對象時，常見的用例是從服務器檢索 XML 數據。從那時起，常見用例發生了變化，但仍使用相同的 API。對我來說，這表明這個 API 作為一個中級示例有多好。

結論

我的主張是原生瀏覽器 API 應該是中級的，這樣常見的用例很容易執行，但有足夠的擴展來支持不太常見的用例。當 API 太低級時，它們需要很長時間才能傳播並變得對開發社區有用；當 API 太高級時，人們要么接受它們，要么忽略它們，因為它們被迫朝著特定的方向發展。似乎較新的 API 更傾向於低級設計，這將需要其他人創建有用的抽象，然後開發人員才能真正使用它們。我想制止這種情況。使常見用例變得簡單，以便人們可以立即開始使用 API 並允許擴展。中級 API 代表了兩全其美。