模塊開發(fā)設計規(guī)范-原生

第一章簡介

為滿足廣大開發(fā)者自定義擴展模塊的需求，APICloud推出模塊擴展SDK（以下簡稱SDK），提供給有一定iOS和android開發(fā)基礎的開發(fā)者，通過簡單的接口實現(xiàn)，輕松接入APICloud平臺，快速開發(fā)擴展模塊，自行實現(xiàn)對APICloud功能的擴展，滿足開放者實際項目的需求，提升App的質(zhì)量及用戶體驗。

由于APICloud是一個極為優(yōu)化的平臺，完全從開發(fā)者角度去設計和定義各個模塊接口。所以，要求模塊開發(fā)者必須嚴格遵守一定的開放規(guī)范和接口定義，以期保證模塊功能的完整性，減少模塊使用者的學習成本，提高模塊的復用性，減少前端開發(fā)者的代碼量，使其能夠快速被開放者掌握，方便在實際項目中使用，縮短項目開發(fā)周期。

第二章閱讀對象

認真閱讀模塊開發(fā)指導文檔ModuleProgrammingGuide(iOS).docx和ModuleProgrammingGuide(Android).docx的ios或android模塊開發(fā)者。并且能夠獨立完成簡單的模塊開發(fā)。

第三章接口文檔編寫規(guī)范

模塊開發(fā)首先應確定初版模塊接口文檔。模塊接口文檔確定規(guī)范了模塊所要實現(xiàn)的功能及其接口，給模塊開發(fā)者在模塊代碼開發(fā)過程中提供了指導和規(guī)范。同時模塊接口文檔是前端開發(fā)者使用模塊的唯一文檔。前端開發(fā)者就是根據(jù)此接口文檔了解模塊實現(xiàn)了哪些功能，每個接口每個參數(shù)如何使用。如果沒有一個完整清晰的模塊接口文檔，無論開發(fā)出功能多么強大、接口如何完整的模塊也都是毫無意義的，因為前端開發(fā)者根本不知道如何使用開發(fā)出來的模塊。

模塊接口文檔初版確定后即可著手開始模塊開發(fā)，在模塊開發(fā)過程中可能會遇到ios和android邏輯流程不統(tǒng)一、UI效果差別過大、接口定義不全面或過于冗余、參數(shù)不規(guī)范等若干的問題，針對這些問題應立刻完善接口文檔。確保最終完成的模塊的完整性（功能完整）和統(tǒng)一性（iOS和android兩個版本的統(tǒng)一）。

文檔撰寫，必須按照規(guī)定的格式規(guī)范。文檔應編寫為md格式文件，md文件制作請參考網(wǎng)絡相關教程。以下是從文檔內(nèi)容方面介紹接口文檔書寫格式，一個標準的模塊接口文檔可分為四部分，分別為：

• 目錄
• 模塊概述
• 方法接口詳述
• 常量詳解

i. 目錄

目錄是模塊所有接口總覽，其規(guī)范如下圖：

ii. 模塊概述

模塊概述是用來說明本模塊是什么，有什么用，實現(xiàn)了那些功能，前端開發(fā)者在使用本模塊前應注意那些問題，等相關說明。如果模塊是帶UI效果的模塊，則必須有該UI效果的截圖，如下圖所示：

iii. 方法接口描述

方法接口描述講解了模塊接口的功能實現(xiàn)，分為如下六個部分：

1. 接口名及其描述，如：

2. 參數(shù)描述，包括參數(shù)類型、默認值、參數(shù)描述及其內(nèi)部字段（沒有可不寫），如：

3. 回調(diào)函數(shù)及其內(nèi)部字段說明（沒回調(diào)可不寫），格式如下圖：

4. 示例代碼，示例代碼里的參數(shù)要給固定值，前端開發(fā)者直接復制此段代碼幾個運行出默認效果，示例代碼要格式化。如圖：

5. 補充說明，用來說明調(diào)用此接口需要注意的事項，沒有可寫無

6. 可用性，說明此接口支持的系統(tǒng)及其版本，格式如下圖：

第四章模塊接口設計規(guī)范

模塊設計規(guī)范是從產(chǎn)品角度，對模塊功能及其結構設計的規(guī)范。主要包括對ui類模塊的規(guī)范、第三方sdk模塊規(guī)范、功能類模塊規(guī)范以及其他通用模塊設計規(guī)范

i. 帶界面的UI類模塊

帶界面的UI類模塊是指為解決一些html+js實現(xiàn)不了的ui類效果，或者網(wǎng)頁實現(xiàn)起來消耗過多系統(tǒng)資源，實現(xiàn)效果不理想而提供的模塊。這類模塊都有一個共同點----都有ui界面。

開發(fā)設計此類模塊需要遵循以下設計原則：

• 必須包含open、close、show、hide接口
• 任意元素的前景和背景必須同時支持圖片和顏色
• 所有可自定義的元素，包括文本或者圖片，或者某個效果等，必須要有默認值

ii. 集成第三方SDK的模塊

集成第三方SDK的模塊是指把第三方服務供應商的開放SDK封裝為APICloud的模塊，使之遵守APICloud的開發(fā)規(guī)范，前端開發(fā)者通過簡單的調(diào)用模塊接口就可以使用第三方提供的服務功能。

此類模塊的設計原則如下：

• 模塊命名要包含第三方服務名，如百度地圖—baiduMap
• 接口設計要盡量少，可以用type區(qū)分其功能，如微信分享sendRequest
• 初始化sdk需要前端開發(fā)者傳入從第三方平臺申請的key時，一般設計成讓前端開發(fā)者在config文件里配置，然后模塊開發(fā)者調(diào)用APICloud接口（iOS上，此接口為[the features]）獲取key值，同時也需兼容從js前端通過接口傳給原生。

iii. 交互類UI模塊

交互類UI模塊是指需要跟用戶交互，捕獲用戶操作指令事件，并將此事件傳遞給前端開發(fā)者的一類UI模塊。

開發(fā)設計這類模塊需要注意如下三點

• 同一界面有多個事件需要callBack給前端開發(fā)者時，相同類型的事件callBack到一個接口，含有回調(diào)的接口越少越好，盡量把所有的callBack集成到一個接口中，一般可用index區(qū)分之
• 功能接口設計必須全面完整，不能在設計上存在邏輯問題
• 同一界面可以打開多個實例對象時，要通過callback返回資源id，用以區(qū)分。若同一頁面不允許同時打開多個，則有實例對象存在時，第二次open直接return現(xiàn)存對象。

iv. 功能類模塊

功能類模塊是針對特定功能開發(fā)的模塊，此類模塊沒有UI界面。設計此類模塊除要遵守開發(fā)常規(guī)模塊需要遵守的規(guī)則外還需要注意一點：

• 保持功能的完整性，全面性

v. 通用設計規(guī)范

通用設計規(guī)范是指每個模塊的開發(fā)設計所遵守的標準規(guī)范，如下四條：

• 文件操作，如圖片，文本等，必須同時支持fs、widget、file等相對或者絕對路徑，必要時支持http訪問
• 盡量不要引用太大的外部工具庫，如果必須使用，能刪減則刪減。冗余的外部庫將導致服務器編譯效率降低
• 輸出的API Case中，有多個使用場景時必須分別輸出多個case，如微信分享需要單獨輸出分享圖片，分享視頻，分享音樂等case
• 務必養(yǎng)成及時提交代碼至SVN的習慣，同時任何只要涉及到代碼或者資源文件更改的操作，都必須完整的走一遍代碼及模塊包提交的流程

vi. 拆分模塊的設計原則

為保證模塊的簡潔，減少功能冗余，降低開發(fā)者使用難度，模塊設計無論從接口還是參數(shù)上都要盡量簡短。不允許出現(xiàn)邏輯極其復雜，參數(shù)非常多的模塊。對于復雜的模塊，可以按功能和界面布局拆分成多個簡單的小模塊

下面是對于復雜模塊的拆分原則：

• 功能不同，設計為新模塊
• 布局不同，定義為新模塊

模塊的自定義是以參數(shù)傳遞來實現(xiàn)的，而參數(shù)智能定義界面元素的大體位置，如:left、right、center等。如果需求必須從坐標層級上自定義ui元素的位置，則可拆分出一個新的模塊，如listView的cell元素布局問題。

第五章命名規(guī)范

命名規(guī)范是從命名角度對模塊開發(fā)的規(guī)范。命名規(guī)范必須遵守以下命名原則：

• 小駝峰命名法則
• 簡介通俗易懂，見名知意
• 突出其主要功能特點

命名規(guī)范包括模塊名命名規(guī)范、接口命名規(guī)范、參數(shù)命名規(guī)范、callBack返回值命名規(guī)范以及常量命名規(guī)范。

i、模塊名命名規(guī)范

模塊名首字母需小寫。模塊名一般由兩個單詞組成，前者為動、名詞，說明其功能特點，后者為名詞說明其類型。如：cityList，pullMenu，barChart。亦可用單個單詞表示，如：calendar，panorama

常見的模塊名有：

1， 菜單類-------**Menu

2， 選擇器類-------------**Selector

3， 圖表類-----------------**Chart

4， 按鈕類-----------------**Button

5， 視圖類-----------------**View

6， 列表類-----------------**List

7， 閱讀類------------------**Reader

8， 瀏覽類------------------**Browser

ii、接口命名規(guī)范

接口命名規(guī)范是對接口名命名的規(guī)范。

接口名的命名遵循以下規(guī)則：

• 需要打開才能使用的模塊，其打開接口一般用open，與之對應close關閉接口供開發(fā)者調(diào)用
• 含有ui界面類的模塊一般會有顯示和隱藏接口，用show，和hide
• 刷新數(shù)據(jù)和UI界面類型接口一般用reloadData和update
• 其它功能類型的接口名一般使用單個動詞單詞，如fs的讀寫read，write

常用的接口名總結：

1， open -------------------打開模塊的接口

2， close ------------------關閉模塊的接口

3， show -------------------顯示模塊視圖接口

4， hide -------------------隱藏模塊視圖接口

5， reloadData--------------刷新數(shù)據(jù)

6， update------------------刷新界面

7， appendData--------------往現(xiàn)有數(shù)據(jù)源拼接新的數(shù)據(jù)

8， setRefreshHeader-----------設置下拉刷新

9， setRefreshFooter ----------設置上拉加載更多

10， pay---------------------支付

11， setValue----------------設置指定元素的值

12， config------------------模塊偏好設置

iii、參數(shù)命名規(guī)范

參數(shù)命名規(guī)范是對接口內(nèi)使用到的參數(shù)命名的規(guī)范.

參數(shù)命名規(guī)范遵守如下條款：

1）需要ui展示的模塊坐標參數(shù)一般為x,y,w,h（有些ui為圓形的，則傳圓心坐標和半徑命名為centerX，centerY，radius）

2）定義頁面元素顏色的參數(shù)一般由兩部分組成，前者一般為名詞，用來指定是誰的顏色，后者為固定單詞Color

3）定義字體大小的參數(shù)一般用size即可

4）傳圖片路徑的參數(shù)由兩部分組成，前者指定是誰的圖片，一般用名詞，后者用image單詞的縮寫Img

5）把視圖固定在哪個窗口上的參數(shù)統(tǒng)一用fixedOn

6）按鈕的背景圖片參數(shù)一般用這兩個normal和highlight來表示普通狀態(tài)下的圖片路徑和點擊效果圖片路徑

7）打開ui視圖時是否使用動畫的參數(shù)名為 anim

8）需要傳數(shù)組類的參數(shù)命名分為兩部分前者表示是什么數(shù)組，后者加s或者單詞Array

9）文件資源地址類型參數(shù)由兩部分組成，前者表示意義，后者加Path（本地路徑）或Url（網(wǎng)絡路徑）

10）常量枚舉類型通常用type表示，需要特殊說明的Type前加說明單詞

11）禁止使用數(shù)字代表type，盡量使用字符串，如：left，right。。。。

常用的參數(shù)及其說明：

1，x ：模塊視圖左上角在俯視圖的坐標點

2，y ：模塊視圖左上角在俯視圖的坐標點

3，w ：模塊視圖的寬

4，h ：模塊視圖的高

5，centerX ：UI為圓形的模塊中心點的坐標

6，centerY ：UI為圓形的模塊中心點的坐標

7，radius ：圓形視圖的半徑

8，bg ：視圖的背景，必須支持圖片，十六進制色值(以下簡稱#)，rgb值，rgba值

9，**Color(color) ：指定元素的顏色值 必須支持# ，rgb，rgba值

10，fontSize : 字體大小

11，title ：標題

12，subTitle ：子標題

13，**Img(img) ：元素圖片，必須支持圖片，十六進制色值，rgb值，rgba值

14，**Url(url) ：指定元素的網(wǎng)絡路徑，一般支持http，https協(xié)議

15，**Path(path) : 指定元素的本地路徑，必須支持widget，fs，res本地協(xié)議

16，fixedOn ：模塊視圖將被添加在某個窗口上的名字

17，normal ：按鈕的常態(tài)背景圖片，支持rgb，#，rgba，本地路徑(path)

18，highlight : 按鈕被按下時背景圖片，支持rgb，#，rgba，本地路徑(path)

19，selected ：按鈕選中后的背景圖片，支持rgb，#，rgba，本地路徑(path)

20，anim ：布爾值，表示是否添加動畫

21，**Array(array) ：指定元素的數(shù)組

22，items ：指定元素的數(shù)組

23，**Type(type) : 用以區(qū)分類型

24，**Index(index) ：用于指定某個元素

25，**Id(id) ：用以區(qū)分模塊的某個實例對象

26，value ：指定元素的值

27，lat : 經(jīng)度

28，lon ：緯度

29，**Max(max) ：最大值

30，**Min(min) ：最小值

31，pageControl ：此參數(shù)可指定頁面控制器的相關信息

32，**Btn(button) : 指定按鈕的相關參數(shù)

33，**Key(key) ：用于指定某個key

34，placeholder**：占位圖

35，activeColor

36，inactiveColor

iv、返回值（callback）命名規(guī)范

對返回值的參數(shù)命名規(guī)范，有如下規(guī)則：

• 狀態(tài)值和錯誤信息統(tǒng)一用status和msg
• 返回點擊按鈕的下標的參數(shù)一般用index
• 點擊事件和拖動事件用eventType區(qū)分

常用的callBack值命名：

1， **Id（id） ：模塊實例對象的id

2， index ：一般用來區(qū)分多個按鈕的點擊

3， status ：布爾值，用來表示是否初始化打開成功

4， msg ：錯誤信息

5， data ：返回獲取的數(shù)據(jù)

6， value ：回調(diào)值

7， state : 表示打開狀態(tài)

8， code ：錯誤碼

v、常量命名規(guī)范

常量命名規(guī)范和參數(shù)命名規(guī)范大體一致，與參數(shù)命名規(guī)范唯一不同的一點是：需要用多個單詞來表示常量的時候，多個單詞間用下劃線隔開。如：web_page,up_down

第六章參數(shù)類型規(guī)范

參數(shù)類型規(guī)范包括對數(shù)字/字符串類型的參數(shù)規(guī)范、布爾值類型的參數(shù)規(guī)范、json對象類型的參數(shù)規(guī)范。

• 數(shù)字類型的參數(shù)，必須兼容字符串類型。同樣，字符串類型的參數(shù)，也必須兼容數(shù)字類型。比如：文檔上寫x參數(shù)的數(shù)字類型是數(shù)字類型，那么前端開發(fā)者傳進來"10"、'10'、10都是必須兼容的
• 布爾值類型參數(shù)必須兼容數(shù)字類型和字符串類型，與js布爾類型規(guī)范一致，0為假，非零為真，字符串true為真，非ture為假。
• json對象類型的參數(shù)必須符合json規(guī)范，與json數(shù)據(jù)格式規(guī)范一致，否則報json對象解析失敗的錯誤。

第七章總結

本文檔主要從模塊開發(fā)的設計規(guī)范和命名規(guī)范兩個角度出發(fā)，對模塊開發(fā)過程中遇到的問題做了初步規(guī)范。嚴格按照此文檔規(guī)范進行模塊開發(fā)，是每個模塊開發(fā)者必須遵守的準繩。

第三章和第四章和第五章為本文檔的重點，分別講述了模塊開發(fā)的文檔編寫、設計規(guī)范和命名規(guī)范。本開發(fā)規(guī)范文檔不是為了限制開發(fā)者，而是為了讓開發(fā)者更自由，簡單，輕松的學習、組織自己的前端代碼，從而迅速開發(fā)出符合用戶需求的APP。

第八章注意事項

1. 若已有SDK官方封裝的模塊，則不允許開發(fā)者再重復封裝此SDK。
2. 不鼓勵開發(fā)功能相同的模塊。