組件介面(API)設計指南[2]－類介面(class interface)，apiinterface

組件介面(API)設計指南[2]－類介面(class interface)，apiinterface

*返回目錄閱讀其他章節: http://blog.csdn.net/cuibo1123/article/details/39894477

類介面(class interface)

    你可以參考MGTileMenu的介面檔案。

    我們之前談論了一些介面的細節，這裡，例舉幾個通用規則：

規則1：使用當前平台的描述用語或構架

    一個最常見的API錯誤設計是使用外來的規則，API屬於一個特定的平台和相關開發人員生態系統。你不能使用任何其他不同平台的描述用語或構架，這會汙染你當前的程式碼程式庫，並破壞你同伴的工作效率。

    在編碼前要充分瞭解你的目標平台和代碼規範。例如，在IOS和OSX中，不使用異常機制處理錯誤。統一命名規則(規則要足夠詳細，但是也要足夠簡潔)。

    瞭解什麼是協議(protocol)，委託(delegate)，擴充(category)。始終在你的代碼中使用術語。遵守建構函式和解構函式的有關命名方案。遵守本地記憶體管理規則。

    就像在自然語言中詞彙和文法是不可分割的一樣，你的風格必須要符合指定平台。

 

規則2: 設計解耦

    設計時應該使組件和建立該組件的項目沒有關聯，如果是一個GUI組件或者視圖，那麼它應該顯示一些預設內容。利用現有的架構作為指導，儘可能讓委託協議(delegateprotocols)等互動保持鬆散耦合，適當的使用通知，並注意良好的設計和命名規則。

    要做到這一點，為每個組件建立一個單獨的測試專案是一個非常有效方法。強迫組件只使用自己的API。不要提取不相關的類之間的共同點。

    下面讓我們來看看類的介面。初始化方法是類介面中最重要的部分之一，它決定使用者如何使用你的組件。你的類需要對某些必要配置進行初始化。所以，一個明顯的規則如下：

規則3: 所需的初始化條件應該由參數提供 

    如果有什麼必須的初始化設定，不要等待需要它的時候再去提供，而要在需要之前由初始化參數提供。如果初始化沒有得到所需的條件則立刻返回空(nil)。

// 需要參數，不能是nil
- (id)initWithDelegate:(id<MGTileMenuDelegate>)theDelegate;

規則4: 允許訪問初始化參數

    這是上一個規則的延續：切記不要把初始化時使用者提供的參數隱藏在模組內部。要讓使用者可以訪問他們，並注意是否可以以某種方式修改(清除、或以其他方式修改)。

//必須通過初始化方法指定
@property (nonatomic, weak, readonly) id<MGTileMenuDelegate>delegate; 

這是以上兩條規則共有的樣本。

規則5: 注釋你的標頭檔 

    實際上，你不會總是提供獨立的文檔來說明代碼功能。如果你不提供獨立的文檔，那麼你的.h檔案(以及示範程式)就是你的文檔。他們應該被“適當”的注釋，這裡所說的適當是指：

    1:足夠詳細，但是篇幅不要太長。要足夠簡潔。 

    2:針對專業人員(語言和詞彙)。所有假設必須足夠安全謹慎。不要胡扯，不要含糊不清。

    特別是，你應簡要說明參數、屬性的功能和預設值。讓使用者在標頭檔中很容易檢索代碼功能，而不需要去看可執行代碼部分。

//瓦片背景漸層(default:藍)
@property (nonatomic) CGGradientReftileGradient;
// default: 5 pixels
@property (nonatomic) NSIntegerselectionBorderWidth;
// default:黑(底)白(頂)漸層
@property (nonatomic) CGGradientRefselectionGradient;

規則6: 整合到運行不多於3行代碼

    你的類應該設計成只需要很少的代碼就可以整合到項目(不包括委託/資料來源協議等)。不包含代理(delegate)方法，你的使用者應該只使用三行代碼即可進行最簡單的測試，這些行分別是：

    1:執行個體化

    2:基本配置。

    3:顯示或啟用它。

以下是來自MGTileMenu的相關代碼示範：

// 執行個體化.
tileController = [[MGTileMenuControlleralloc] initWithDelegate:self];
// 配置.
tileController.dismissAfterTileActivated = NO; // 使它更容易播放
// 顯示.
[tileControllerdisplayMenuCenteredOnPoint:locinView:self.view];

規則7: 一個繁雜的示範程式通常意味著組件功能零碎

    另一個推論: 你的示範程式大小決定了組件的品質，示範程式越小越好。示範所需代碼應該儘可能的少而簡單（但是也要在demo中適當的示範組件的定製化服務或功能）。

    使用一個空的Xcode模版，應該只需要添加很少的代碼，就能夠建立具有你的組件核心功能的應用。僅僅提供一個示範程式是不夠的，還必須確保複製－粘貼你提供的樣本程式後同樣能夠工作。

規則8: 設定預定方案 

    我開發應用程式的標準規則是不給使用者提供配置選項，而是選擇合理的預設值來適用大部分使用者。好的軟體，總是會固執己見。

    關於這一點，組件和應用程式有所不同，因為組件的使用情境是不明確的。當然，你可以讓組件只適用於特定的某一種情況，但通常我們更希望組件具有一定的靈活性。你永遠不知道其他開發人員會如何使用你的組件，因此，你必須讓它具有一定的通用性。

    仔細考慮組件所支援的功能是很重要的。尤其要考慮依賴關係－不是在編譯/連結時的依賴，而是邏輯功能與介面之間的依賴。我的做法是不在執行個體變數(成員)的層次去想這個問題，而是從“定製方案”的層次去想這個問題。弄清楚你想讓你的組件具備哪些定製方案？然後根據這些定製方案，來選擇公開哪些屬性給使用者。

    一個很容易犯的錯誤是公開的配置項(介面)不足而削弱了某種功能，比如下面的一些例子：

    1:公開了寬度和高度設定，但是沒有考慮圓角。

    2:公開了背景顏色的設定，但是沒有考慮高亮時的背景色設定。

    3:公開了尺寸設定，但是沒有考慮間距。

    這種錯誤通常取決於具體的組件，試著從顯示效果和功能的角度考慮屬性之間的關係。從使用者的角度來考慮問題。要靈活易用，但不要放棄組件的特性。

// 解除菜單後瓦片被啟用(YES; 預設)
@property (nonatomic) BOOLdismissAfterTileActivated;
// 右手模式(YES; 預設) 或左手模式(NO)
@property (nonatomic) BOOLrightHanded;
// 每個瓦片的寬高，單位:像素(預設72 像素)
@property (nonatomic) NSIntegertileSide;
// 瓦片間距, 單位:像素(預設: 20 像素)
@property (nonatomic) NSIntegertileGap;
// 瓷磚圓角的半徑, 單位:像素(預設: 12.0 像素)
@property (nonatomic) CGFloatcornerRadius;

    讓常識指引你。找到哪些在70％的情況下都會使用的選項，並提供這些選項給使用者。

 

規則9: 更多的特性，更少的操作 

    在我喜歡的組件中(其中一些是標準架構，一些是來自第三方的開源組件，也有我自己寫的)，有一個經常出現的特性。組件所實現的功能(所有功能，從初始化到狀態更新等)和公開的介面(存取器或自訂方法等)存在一定的比例關係。

    這些組件幾乎總是用更少的操作(這不是指介面上的操作，而是介面)來實現更多的特性。MGTileMenu有一個初始化和四個功能方法(其中一個是另一個介面的簡化)，以它的特性和操作來說，是四倍的比例關係。我認為這是一個不錯的比例，在具有簡潔實用的功能的同時，也能靈活的定製。

 // 參數不能為nil
- (id)initWithDelegate:(id<MGTileMenuDelegate>)theDelegate;
// 從0開始
- (CGPoint)displayMenuPage:(NSInteger)pageNumcenteredOnPoint:(CGPoint)centerPtinView:(UIView *)parentView;
- (void)dismissMenu;
// 從0開始
- (void)switchToPage:(NSInteger)pageNum;

 

規則10: 在你的控制項中使用控制項

    一個簡化API的很好的方法是：在你的組件中使用現有的組件。組件風格統一併不意味著你不能利用現有組件來構造新的組件(實際上這是一個良好的軟體工程基本原則)。

    例如UITableViewCell和UIButton的API如此簡單，就是因為它們使用了子控制項UILabels和UIImageViews。如果合適，你也可以這樣做－並且暴露子控制項，以便讓你當前的類介面更加簡潔一致。

    例如MGTileMenu中，瓦片是由UIButtons擴充的。與在自訂視圖中繪製並跟蹤輸入、提供提供者相比，這簡化了很多工作。

規則11: 你的便利方法也可能適合使用者

    你一定會在創作組件期間添加一些便利的方法，而又本能的將它們設為私人(private)。其實，你可以考慮使用者在整合你的組件時是否會用到這些方法，以此來決定是否公開(public)它們。

    例如，我在MGTileMenu中建立了這些便利的功能：

CGRectMGMinimallyOverlapRects(CGRectinner, CGRectouter, CGFloatpadding);
//RGB色彩漸層
CGGradientRefMGCreateGradientWithColors(UIColor *topColorRGB, UIColor *bottomColorRGB);

    第一個是儲存位置的結構，用於移動菜單，以便它在其父視圖中可以完全可見(方便其他開發人員建立與他們自己的UI配套的菜單)。第二個是儲存漸層色的結構，用於為菜單背景設定的圖形漸層(當背景改變後，會通過委託通知調用者)。

 

規則12: 神奇的效果是好的，神奇的數字不是

    你遲早會在組件中放入一些奇特的東西。並希望賦予更多像史蒂夫·喬布斯式的令人愉快的神奇特性。但我要說的是在你的代碼中具有特殊含義的數字。一個最常見的例子就是-1，它通常用來表示一組特別的東西，或特殊情況。

    用一個特定值表示一類情況，這樣做很正確。那麼什麼情況是不正確的那？顯然，不能在你的代碼中直接使用這種神秘的原始數值，尤其是不能把它暴露在API中。如果你必須暴露它，請把它封裝一下，比如使用#defines定義一個可以讓人理解的名字。

閱讀下一章節: http://blog.csdn.net/cuibo1123/article/details/39894477

－－－－－－－－－－－－－－－－－－－－－－－－－

英文原名《API Design》
       作者：Matt Gemmell
       原名連結：http://mattgemmell.com/api-design/

中文版由xoneday翻譯
       歡迎訪問譯者部落格：http://blog.xoneday.com
       新浪微博：@xoneday某天

如果這片譯文給您帶來了協助，希望您能通過下載我的APP來支援我：
豆瓣讀書：https://itunes.apple.com/cn/app/id695492935
便簽夾：https://itunes.apple.com/cn/app/id580552733

           

             便簽夾                                        豆瓣讀書

＊轉載聲明：請勿刪減作者／譯者資訊與支援部分的內容，如不接受此條款請勿轉載。

api介面是什

API：應用程式介面（API：Application Program Interface）
應用程式介面（API：application programming interface）是一組定義、程式及協議的集合，通過 API 介面實現電腦軟體之間的相互連信。API 的一個主要功能是提供通用功能集。程式員通過使用 API 函數開發應用程式，從而可以避免編寫無用程式，以減輕編程任務。
API 同時也是一種中介軟體，為各種不同平台提供資料共用。根據單個或分布式平台上不同軟體應用程式間的資料共用效能，可以將 API 分為四種類型：

遠端程序呼叫（RPC）：通過作用在共用資料緩衝器上的過程（或任務）實現程式間的通訊。
標準查詢語言（SQL）：是標準的訪問資料的查詢語言，通過通用資料庫實現應用程式間的資料共用。
檔案傳輸：檔案傳輸通過發送格式檔案實現應用程式間資料共用。
資訊交付：指松耦合或緊耦合應用程式間的小型格式化資訊，通過程式間的直接通訊實現資料共用。
當前應用於 API 的標準包括 ANSI 標準 SQL API。另外還有一些應用於其它類型的標準尚在制定之中。API 可以應用於所有電腦平台和作業系統。這些 API 以不同的格式串連資料（如共用資料緩衝器、資料庫結構、檔案架構）。每種資料格式要求以不同的資料命令和參數實現正確的資料通訊，但同時也會產生不同類型的錯誤。因此，除了具備執行資料共用任務所需的知識以外，這些類型的 API 還必須解決很多網路參數問題和可能的差錯條件，即每個應用程式都必須清楚自身是否有強大的效能支援程式間通訊。相反由於這種 API 只處理一種資訊格式，所以該情形下的資訊交付 API 只提供較小的命令、網路參數以及差錯條件子集。正因為如此，交付 API 方式大大降低了系統複雜性，所以當應用程式需要通過多個平台實現資料共用時，採用資訊交付 API 類型是比較理想的選擇。

API 與圖形使用者介面（GUI）或命令介面有著鮮明的差別：API 介面屬於一種作業系統或程式介面，而後兩者都屬於直接使用者介面。

有時公司會將 API 作為其公用開放系統。也就是說，公司制定自己的系統介面標準，當需要執行系統整合、自訂和程式應用等操作時，公司所有成員都可以通過該介面標準調用原始碼，該介面標準被稱之為開放式 API。
 
怎給自己的程式提供介面（API）給別的程式操作

這COM技術的一種,可以做成GUI EXE, 象Word, Excel;也可以做成Service.
從CoRegisterClassObject(...)看起吧, COM是Windows的一大支柱,但弄明白了它, 你也就可以當老大了.