為API執行的處理做好萬全準備

一組好的API，必須要能夠讓客戶端程式碼在呼叫API中的函式時，明確知道API函式執行的結果。設計得宜的API函式，不僅可以讓客戶端程式碼區分執行結果究竟是成功或是失敗，同時也會讓客戶端程式碼在函式執行失敗時，有辦法知道發生錯誤的原因或者情況。

對於執行結果的相關訊息，需要更全盤掌握
這樣的資訊，對客戶端程式碼來說十分的重要。因為，並不是所有的API函式都能保證執行成功、不會發生任何錯誤。倘若無法讓客戶端程式碼得知執行的結果，那麼，客戶端程式碼就無法在執行發生異常時，進行相關的因應動作。

有些API設計者，僅利用API函式回傳一個代表成功或失敗的值（例如使用Boolean回傳型別），那麼，客戶端程式碼便僅能知道成功或失敗，卻無法更進一步準確找出失敗時的錯誤原因。一來，可能無法更適當地進行異常的處理動作，二來，客戶端程式設計者要進行除錯動作時，也會增加許多的難度。因此，提供更友善的API執行結果資訊，是一組好的API的必備條件。

有些API在錯誤資訊的提供上，是透過獨立的專門函式來完成。它們的API函式，執行時僅會回傳成功或失敗，但是讓客戶端程式碼在失敗時，另行呼叫特定函式來取得狀態的原因。例如，Windows的許多API函式在執行成功時，會回傳BOOL值，當回傳值為TRUE時，代表執行成功；為FALSE時，則代表執行失敗。而客戶端程式碼在得到API函式回傳FALSE時，可進一步呼叫GetLastError()這個函式，來取得失敗的錯誤代碼。

錯誤處理的典型做法
Windows的API總共定義了從0到15999的錯誤代碼，每個數字都有專門的意義。所以，在Windows的設計中，取得錯誤代碼的方式都一致，而所有錯誤代碼在每個可能回傳錯誤的API函式中，意義也都是一致的。當然，Windows也提供了將錯誤代碼對應至訊息字串的API函式FormatMessage，這有助於客戶端程式碼針對錯誤的情況，得以在日誌檔寫入時，或提示使用者訊息時，提供更有意義的訊息。Unix也有類似的設計，就像透過全域變數errno可以取得錯誤代碼、呼叫函式strerror()可以取得錯誤代碼對應的訊息。

至於對於採物件導向設計的API來說，採取異常（Exception）的機制來讓客戶端程式碼處理錯誤是十分直覺又理想的方式。不論採取那一種方式，API函式都應該為客戶端程式碼精確指出錯誤。

寫出API展示程式的重要性
當你完成一組API的設計及實作後，你最好撰寫一些相關的展示（demo）程式，用來展示你API所能發揮的功效。你可以假想若干個客戶端程式設計者最常會遭遇的情境，然後透過你的展示程式、運用你所設計的API來處理這些情境。

展示程式對想要嘗試使用API的程式設計者來說，用處很大。這些程式可以幫助他們更快理解：（1）運用你的API可以解決的重要問題，（2）究竟該如何運用你的API來解決問題，（3）運用你的API可以如何巧妙解決這些問題、省去他們多少力氣、讓他們的程式碼變得多優雅……等等。因此，好的展示程式碼比大量、冗長的文件更有幫助。

API的展示程式，除了可以向客戶端程式設計者傳達許多觀念之外，在API未對外釋出時，它也能讓API設計者，透過撰寫實際的程式，達到操演自身API的目的。

經過這樣的操演，能夠讓API的設計者，實際讓自己設身處地，發掘出設計API時會有的想法落差，同時了解究竟自己的API設計，是否需要其他的調校。

對API設計而言，一旦面對客戶端程式設計者的介面確立了，那麼，之後想要再做變動，所必須付出的代價就會相當大。因為，當你對客戶端程式設計者釋出後，他們便會基於你的設計開始撰寫客戶端程式碼，而日後API的修改，只要牽扯到介面的更動，所會波及到的程式碼其層面便很廣，所有的客戶端程式碼都有可能被影響到。

變更介面的時機與作為
當然，在設計階段便應該反覆推敲以驗證此事，但是，實際設想該寫些什麼樣的展示應用程式並且加以撰寫，便能夠透過實務來做最後的確認，以減少日後再度變更介面的可能。

既然談到了要降低變更介面的可能，就不能不談，倘若真的在釋出API提供給客戶端程式設計者開發他們的應用程式之後，發現你所設計的介面有所不足，甚至需要調整時，該怎麼辦？

修改原有的介面當然是下下策，既然API都釋出了，那麼便意謂著，基於你API所寫成的應用程式也有可能釋出，不然，也有可能正在撰寫中。修改原有的介面，等於是讓現有的程式碼作廢──除非客戶端程式碼並不打算升級到新版的API。

API難免遇到需要演化的情況，有時候是為了修正過去的錯誤、有時是為了調整，有時候是為擴充，以便加入更強大的功能。但，這些修正、調整及擴充，最好都能維持往下相容的特性，這樣才不會傷害到既有的客戶端程式碼。

我相信所有的客戶端程式設計者，都不會喜歡不維持往下相容的API，因為，客戶端程式設計者遇到這種情況，通常只有兩種選擇，其一是放棄升級到新版的API，而另一便是痛下決心，整個翻修。

放棄升級意謂著，只能一直維持現行版本，但若新版修正了重要錯誤，那麼不升級便無法獲得這些修正。翻修程式碼也是浩大的工程，需要投入的心力和時間也不小。因此，非到萬不得已、山窮水盡的局面，最好不要決定讓你的API往下不相容。

所有的改變，最好都透過擴充的方式去進行。但這考驗設計者的能耐。有一些微軟的API名稱後頭有著「Ex」兩個字母，而它們都有相對應沒有「Ex」兩個字的版本，例如CreateWindowEx()對應著CreateWindow()、RegisterClassEx()對應RegisterClass()。為什麼會有這一類的函式呢？因為都是設計者發現原來的版本不足以滿足需求、又不想改動原先版本的介面，所以只好擴充原有函式的介面，但以新函式的方式加入API之中。

雖然像這樣子的擴充方式看起來不是挺優雅的，起碼能夠達到目的，又能維持往下相容，也算是可接受的作法了。

此外，當你在釋出API之際，最好附上相關的單元測試碼。對於那些採取測試先行的設計者而言，這並不構成問題，因為他們在撰寫程式碼前，早就把單元測試用的程式碼給完成了。但，不管你是不是採測試先行的開發方式，能附上單元測試碼，對客戶端程式設計者來說，都能提供助益。他們可以確定你API的品質程度，也可以明白究竟他們所運用的API經過了那些測試。另一方面，測試程式往往也同時展示了運用API的方式，以及情境。

最後，所有的API釋出時，都應該附上足夠的文件說明。在這份文件中，最起碼要說明所有的API函式、每一個函式的作用、使用每個函式時的先決條件，當然，還有呼叫每個函式需要傳入那些參數、每個參數的意義、能接受的合法值範圍、回傳值的意義、以及可能會有那些執行結果的錯誤，如何得知究竟發生了什麼錯誤等等。

好的API設計影響深遠，好的API設計也能讓客戶端程式設計者時常感念在心。在本系列的文章中，試著介紹如何設計好的API，但這只是個起點，只要你能重視這件事，就會開始留意，不斷精進。