前端通訊：ajax設計方案（九）--- 完善文檔

ajax-js 1.9.1 文檔

目錄

 *  common(options, isCreatePoll)
 *  config(options)
 *  get(url, data, successEvent, errorEvent, timeoutEvent)
 *  post(url, data, successEvent, errorEvent, timeoutEvent)
 *  postJSON(url, data, successEvent, errorEvent, timeoutEvent)
 *  postFormData(url, formData, successEvent, errorEvent, timeoutEvent)
 *  obtainBlob(type, url, data, successEvent, errorEvent, timeoutEvent)
 *  promiseAjax(url, data, type)
 *  longPolling(type, url, data, successEvent, timeFrequency, errorEvent, timeoutEvent)
 *  upload(url, file, size, fileType, successEvent, errorEvent, timeoutEvent)
 *  upload_big(url, file, cutSize, fileType, successEvent, progressEvent, errorEvent, timeoutEvent)
 

common(options, isCreatePoll)

參數:  
 * options  <object>  請求參數，指定請求的各類參數，具體參數設置請到最下面查看
 * isCreatePoll  <boolean>  是否建立請求鏈接池子（內部使用，不對外，下一期迭代修改）
 
描述：  
　　ajax-js庫核心api，其餘暴露方法都是對該方法的封裝  


config(options)

參數:  
 * options  <object>  全局參數，具體參數設置請到最下面查看

 
描述：  
　　設置請求的全局參數


get(url, data, successEvent, errorEvent, timeoutEvent)

參數:  
 * url  <string>  請求地址
 * data  <object>  請求參數
 * successEvent  <function>  成功回調
 * errorEvent  <function>  失敗回調 [可選]
 * timeoutEvent  <function>  超時回調  [可選]
 
描述：  
　　get請求


post(url, data, successEvent, errorEvent, timeoutEvent)

參數:  
 * url  <string>  請求地址
 * data  <object>  請求參數
 * successEvent  <function>  成功回調
 * errorEvent  <function>  失敗回調  [可選]
 * timeoutEvent  <function>  超時回調  [可選]
 
描述：  
　　post請求，默認contentType = ''的請求


postJSON(url, data, successEvent, errorEvent, timeoutEvent)

參數:  
 * url  <string>  請求地址
 * data  <object>  請求參數
 * successEvent  <function>  成功回調
 * errorEvent  <function>  失敗回調  [可選]
 * timeoutEvent  <function>  超時回調  [可選]
 
描述：  
　　post請求，默認contentType = 'json'的請求


postFormData(url, formData, successEvent, errorEvent, timeoutEvent)

參數:  
 * url  <string>  請求地址
 * formData  <formData>  請求參數，formData對象
 * successEvent  <function>  成功回調
 * errorEvent  <function>  失敗回調  [可選]
 * timeoutEvent  <function>  超時回調  [可選]
 
描述：  
　　post請求，發送formData對象


obtainBlob(type, url, data, successEvent, errorEvent, timeoutEvent)

參數:  
 * type  <string>  請求類型（默認post）
 * url  <string>  請求地址
 * data  <object>  請求參數
 * successEvent  <function>  成功回調
 * errorEvent  <function>  失敗回調  [可選]
 * timeoutEvent  <function>  超時回調  [可選]
 
描述：  
　　發送請求，獲取blob二進制的數據流


promiseAjax(url, data, type)

參數:  
 * url  <string>  請求地址
 * data  <object>  請求參數
 * type  <string>  請求類型
 
描述：  
　　封裝promise，處理請求    

注意：
    在後面迭代將完善promise模型實現，而後把該方法去除，讓全部對外暴露方法直接接入promise


longPolling(type, url, data, successEvent, timeFrequency, errorEvent, timeoutEvent)

參數:  
 * type  <string>  請求類型
 * url  <string>  請求地址
 * data  <object>  請求參數
 * successEvent  <function>  成功事件處理，若是讓輪詢中止，則在第二個回調參數設置stop屬性就好
 * timeFrequency  <function>  輪詢時間
 * errorEvent  <function>  失敗回調  [可選]
 * timeoutEvent  <function>  超時回調  [可選]
 
描述：  
　　長輪詢請求，支持無限輪詢和可控制式的輪詢    

注意：
    successEvent(data,that)回調中，能夠設置that.stop = true讓輪詢中止


upload(url, file, size, fileType, successEvent, errorEvent, timeoutEvent)

參數:  
 * url  <string>  文件上傳地址
 * file  <blob>  input=file 選擇的文件
 * size  <number>  文件限制大小
 * fileType  <string/array>  文件限制類型 mime類型。全部類型設置：'*'，不然其餘類型，每一個類型都用數組包括進去
 * successEvent  <function>  成功事件處理，若是讓輪詢中止，則在第二個回調參數設置stop屬性就好
 * errorEvent  <function>  失敗回調  [可選]
 * timeoutEvent  <function>  超時回調  [可選]
 
返回：
 * status
  * 0請選擇文件
  * 1超出文件限制大小
  * 2非容許文件格式
 
描述：  
　　上傳文件請求    

注意：
    瀏覽器和服務器對上傳文件都有大小限制的


upload(url, file, cutSize, fileType, successEvent, progressEvent, errorEvent, timeoutEvent)

參數:  
 * url  <string>  文件上傳地址
 * file  <blob>  input=file 選擇的文件
 * cutSize  <number>  切割文件大小
 * fileType  <string/array>  文件限制類型 mime類型。全部類型設置：'*'，不然其餘類型，每一個類型都用數組包括進去
 * successEvent  <function>  成功事件處理，若是讓輪詢中止，則在第二個回調參數設置stop屬性就好
 * errorEvent  <function>  失敗回調  [可選]
 * timeoutEvent  <function>  超時回調  [可選]
 
返回：
 * status
  * 0請選擇文件
  * 1非容許文件格式
 
描述：  
　　超大文件切割上傳    

注意：
    該方法規避了瀏覽器和服務器對上傳文件大小的限制，可是對於後端處理每一個分片文件最後組合有必定的要求


全局參數含義

options可設置參數：
 * url 
    * 描述： 接口請求地址    
    * 默認值：''
    
 * type 
    * 描述： 接口請求類型，現支持get、post，日後迭代完善符合RESTfull的規則    
    * 默認值：'post'
     
 * baseURL 
    * 描述：  統一追加前綴
    * 默認值：'post'
    * demo：全部接口請求都有/api或者https://xxx，就能夠進行設置，會在每一個請求時候統一追加到完整url中   
      
 * data 
    * 描述： 接口傳輸的數據，默認{}，get請求會追加到url中，post正常在請求體中
    * 默認值：{}
      
 * async 
    * 描述： 是否異步請求
    * 默認值：true
    * 注意： 在新規範中，瀏覽器已經將false進行警告，這是影響用戶體驗的操做，由於同步請求會阻塞頁面
      
 * requestHeader
    * 描述： 接口請求中設置的http的header數據    
    * 默認值：{}
      
 * publicData
    * 描述： 接口請求中的公共數據，功能相似baseURL同樣，最後會合並的
    * 默認值：{}
      
 * timeout
    * 描述： 接口請求超時時間
    * 默認值：5000
    * 注意： 這是瀏覽器側的超時時間，超過期間瀏覽器會主動斷開鏈接，作超時響應事件
      
 * responseType
    * 描述： 但願得到的接口響應數據類型
    * 默認值：'json'
    * 注意： 這是XMLHTTPRequest level 2的規範，支持''、'text'、'document'、'json'、'blob'、'arrayBuffer'
    
 * contentType
    * 描述： 接口請求中能夠發送的數據類型
    * 默認值：''
    * 注意： 內置可設置的值''、'json'、'form'，若有其它需求，可在requestHeader中設置content-Type的值
    
 * withCredentials
    * 描述： 在跨域接口請求中是否發送跨域憑證（cookie）
    * 跨域方案： CORS跨域
    * 默認值：false
    * 注意： 內置可設置的值''、'json'、'form'，若有其它需求，可在requestHeader中設置content-Type的值
    
 * errStatus
    * isOpenErr ：是否開啓功能
    * errURL： 蒐集錯誤上報接口
    * 
    * 描述：是否設置錯誤蒐集機制
    * 默認值：isOpenErr = false、errURL = ''
    
 * loadBalancing
    * isOpen： 是否開啓功能
    * cluster： 負載服務器地址，能夠配置多活地址
    * 
    * 描述：提供前端請求分發功能
    * 默認值：isOpenErr = false、cluster = []
    
 * serviceSwitching
    * isOpen： 是否開啓功能
    * strategies：服務切換策略
    * backupUrl：服務切換地址
    * 
    * 描述：宕機切換功能，在特定策略中，可以使前端有能力進行服務切換
    * 默認值：isOpen = false、strategies = function(){}、backupUrl = ''
    
 * pool
    * isOpen： 是否開啓功能
    * requestNumber： 請求池等待鏈接的請求數量
    * 
    * 描述：請求池優化請求速度
    * 默認值：isOpen = true、requestNumber = 6
    
 * transformRequest
    * 描述：請求前參數處理
    * 默認值：function(data){ return data }
    * 注意： data爲須要處理參數
    
 * transformResponse
    * 描述：請求後參數處理
    * 默認值：function(data){ return data }
    * 注意： data爲須要處理參數
    
 * successEvent
    * 描述： 請求成功的回調處理
    * 默認值：function(res){}
    * PS： res爲請求成功返回的數據
    
 * errorEvent
    * 描述： 請求錯誤的回調處理
    * 默認值：function(err){}
    * PS： err爲請求錯誤的消息
    
 * timeoutEvent
    * 描述： 請求超時的回調處理
    * 默認值：function(timeout){}    * PS： timeout爲請求超時的消息



以前欠下的文檔，如今終於補全了，也能夠去git上查看，順手點個star，感謝