Objective-C API 設計指南：打造直觀、靈活、可重用的元件

核心哲學

API 是開發者的使用者介面 (DX)。優秀 API 應具備：直觀性、容錯性、易用性。設計原則同 UI/UX：預設值滿足 70% 場景、預設即可用、漸進式揭露複雜度。

四大介面元素

1. 類別介面：公開屬性與方法
2. 委派協議：行為客製化回呼
3. 資料來源協議：資料驅動內容
4. 通知：廣播式事件傳遞

25 條設計規則精華

類別介面 (Rule 1-12)

1. 使用平台慣用語：遵循 Cocoa 命名、記憶體管理、協議模式。勿移植 Java/C# 風格。
2. 設計解耦：元件預設可獨立運作，無專案相依。建立獨立 Demo 專案強迫自己用自家 API。
3. 必要參數放入初始化：`-initWithDelegate:` 回傳 `nil` 若缺參。@property (readonly) id delegate; 暴露只讀。
4. 允許存取初始化參數：屬性公開供檢查/修改。
5. 標頭檔即文件：簡潔註解每個屬性/方法，標註預設值。// default: 72 pixels
6. 三行代碼整合測試：實例化 → 基本配置 → 顯示/啟用。超過即代碼異味。
7. Demo 越小越好：Demo 膨脹 = 元件設計不佳。
8. 分析具體場景：暴露「層面」屬性而非單一變數。如圓角半徑、邊框寬度、顏色漸層為「外觀層面」。
9. 多屬性、少方法：屬性/方法比 ≥ 4:1。屬性表達配置，方法表達動作。
10. 在控制項中使用控制項：複用 `UIButton`、`UIImageView` 而非自繪，簡化實作與 API。
11. 對人方便 = 對己方便：內部實用工具函數公開化 (如 `MGMinimallyOverlapRects`、`MGCreateGradientWithColors`)。
12. 魅力可以，魔數不行：特殊值用常數定義。#define MG_PAGE_SWITCHING_TILE_INDEX -1

委派/資料來源協議 (Rule 13-22)

13. 限制 required 方法：僅保留不可或缺者 (MGTileMenu 僅 5 個 required)。
14. 設計易達性：強制提供無障礙標籤 (label/description)，支援 VoiceOver。
15. 使用語意物件作參數：傳 `NSDate` 而非數字，傳 `UIColor` 而非 RGB 三元組。
16. 語意優於慣例：若現有 API 不符元件語意，重新設計 (如菜單用 tile 索引而非 UIButton 陣列)。
17. 高亮狀態通知：`didSelectTile:` / `didDeselectTile:` 讓 App 即時回應觸控反饋。
18. Optional 方法非保證：實作 optional 時仍應呼叫預設行為，回傳 `nil`/`0` 觸發預設。
19. 總是傳送 sender：委派方法第一參數必為發送者。`-tileMenu:didActivateTile:`
20. 查詢方法先放關鍵參數：`-imageForTile:inMenu:` (關鍵在前)，非 `-tileMenu:imageForTile:`。
21. 通知方法 sender 在前：`-tileMenu:willSwitchToPage:` 符合人類溝通習慣。
22. 慣例可破，若有更好設計：如 `validateMenuItem:` 改為 `isTileEnabled:inMenu:` 更清晰。

通知 (Rule 23-24)

23. 委派與通知並行：同一事件同時提供委派回呼與通知，參數對應 `userInfo` 字典。
24. userInfo 豐富完整：包含委派方法所有參數，接收者可能無委派連結。

最終測試 (Rule 25)

25. 全組合測試：每個 optional 方法、每個通知、每個客製化點、所有組合。寧可砍功能、不可出貨帶 Bug。

MGTileMenu 實戰範例

// 初始化 (必要參數)
- (id)initWithDelegate:(id)delegate;

// 客製化屬性 (10+ 屬性 vs 4 方法)
@property (nonatomic) BOOL dismissAfterTileActivated; // default YES
@property (nonatomic) BOOL rightHanded;              // default YES
@property (nonatomic) NSInteger tileSide;            // default 72
@property (nonatomic) NSInteger tileGap;             // default 20
@property (nonatomic) CGFloat cornerRadius;          // default 8

// 委派協議 (合併資料來源)
@protocol MGTileMenuDelegate 
@required
- (NSInteger)numberOfTilesInMenu:(MGTileMenuController*)menu;
- (UIImage*)imageForTile:(NSInteger)tile inMenu:(MGTileMenuController*)menu;
- (NSString*)labelForTile:(NSInteger)tile inMenu:(MGTileMenuController*)menu;
- (NSString*)descriptionForTile:(NSInteger)tile inMenu:(MGTileMenuController*)menu;
- (void)tileMenu:(MGTileMenuController*)menu didActivateTile:(NSInteger)tile;
@optional
- (void)tileMenu:(MGTileMenuController*)menu didSelectTile:(NSInteger)tile;
- (void)tileMenu:(MGTileMenuController*)menu didDeselectTile:(NSInteger)tile;
- (BOOL)isTileEnabled:(NSInteger)tile inMenu:(MGTileMenuController*)menu;
@end

// 通知
extern NSString *MGTileMenuWillDisplayNotification;
extern NSString *MGTileMenuDidDisplayNotification;
// userInfo: @{ MGPageNumberKey : @(pageNumber) }

總結

遵循此 25 條規則，可產出設計良好、靈活、可重用、令人愉悅的 Objective-C 元件。核心在於：以使用者 (開發者) 為中心，預設即可用、漸進揭露、語意清晰、測試徹底。