接口文檔規范

目錄

• 接口文檔書寫規范
  • 接口：
    • restful接口規范：
    • url格式：
    • 請求方式：
    • 響應結果：
  • 生命周期：

接口文檔書寫規范

接口：

接口：聯系兩個物質的媒介，完成信息交互
web程序中：聯系前台頁面與后台數據庫的媒介
web接口組成：
	url：長得像放回數據的url鏈接
	請求參數：前台按照指定的key提供數據給后台
	請求方式： get| post | put | patch | delete
	響應數據：后台與數據庫交互后將數據反饋給前台

restful接口規范：

    接口規范：就是為了采用不同的后台語言，也能使用同樣的接口獲取到同樣的數據

    如何寫接口：接口規范是 規范化書寫接口的，寫接口要寫 url、響應數據,請求方式，請求參數---->（接口文檔）
	
	接口文檔： word , md ,Yapi(網頁版) --》 文檔

url格式：

url鏈接：
	1）接口都是操作前后台數據的，所以需要保證數據的安全性
		采用https協議
	2）接口用來操作數據，與網址(操作頁面)有區別，所以用特定的關鍵字表示接口
		api關鍵字
			- https://api.baidu.com
			- https://www.baidu.com/api
	3）接口操作的數據稱之為 資源，在url中只體現 資源 名稱(名詞)，不體現操作資源的方式動詞
		常規資源接口
			- https://api.baidu.com/books/
			- https://api.baidu.com/books/(pk)/
			
		非常規接口 - 和某資源不是特別密切或是不止一種資源
			- https://api.baidu.com/login/
			- https://api.baidu.com/place/search/
			
	4）如果一個資源存在多版本結果，在url鏈接中要用特定符號來兼容多版本共存
		v1|v2
			- https://api.baidu.com/v1/books/
			- https://api.baidu.com/v2/books/
			
	5）群資源操作，一般還有額外的限制條件，如排序、限制調試、分頁等等
		?限制條件
			- https://api.baidu.com/v1/books/?ordering=-price&limit=3

請求方式：

get：獲取單個或多個資源
    - https://api.baidu.com/books/
        群查，返回多個結果對象
    - https://api.baidu.com/books/(pk)/
        單查，返回單個結果對象

post：新增單個或多個資源
	- https://api.baidu.com/books/
    單增，提交單個數據字典，完成單增，返回單個結果對象
    群增，提供多個數據字典的數組，完成群增，返回多個結果對象
				
put：整體修改單個或多個資源
	- https://api.baidu.com/books/
	整體修改多個，提供多個數據字典的數組(數據字典中要包含主鍵)，完成群改，返回多個結果對象
	- https://api.baidu.com/books/(pk)/
	整體修改單個，提供單個數據字典(主鍵在url中體現)，完成單改，返回單個結果對象
		
patch：局部修改單個或多個資源
   方式與put完全相同，不同的是：操作的資源如果有5個key-value鍵值對，put請求提供的字典必須全包含，但是patch提供的字典包含的鍵值對0~5個都可以
        		
delete：刪除單個或多個資源
    - https://api.baidu.com/books/
        多刪，提供多個資源主鍵數據，完成群刪，不做任何資源返回(一般我們會返回結果信息：成功|失敗)
   - https://api.baidu.com/books/(pk)/
        單刪，不需要提供額外數據，完成單刪，不做任何資源返回(一般我們會返回結果信息：成功|失敗)
	

響應結果：

	響應對象中要包含網絡狀態碼(網絡狀態信息和網絡狀態碼捆綁出現，不要額外設置)：
		1xx：基本信息
		2xx：成功 - 200基本 201新增成功
		3xx：重定向
		4xx：客戶端錯誤 - 400錯誤請求；403請求無權限；404請求資源不存在
		5xx：服務端錯誤 - 500服務器錯誤
		
	數據狀態碼(一般都是前后台約定規則)：
		0：成功
		1：失敗 - 1xx：具體失敗信息(要在接口文檔中明確寫出)
		2：無數據 - 2xx：具體無數據信息(要在接口文檔中明確寫出)

	數據狀態信息(一般不僅僅是對數據狀態碼的解釋，更多是對結果的描述，給前台開發者閱讀的)

	數據結果(常量、數組、字典)，如果有子資源(圖片、音頻、視頻)，返回資源的url鏈接

eg:
   {
       "status": 0,
       "msg": 'ok',
       "results": [{
           "name": "遮天",
           "img": "https://api.baidu.com/media/book/xyjpng"
       }]
   } 	

生命周期：

vue項目生命周期：
	npm run serve => 運行的是 node_modules 依賴(webpack) => 加載主腳本文件(main.js) => 添加各種環境，渲染根組件(Vue、router、store、自定義、new Vue()) => 項目啟動了，之后的任務交給router進行管理
	
	
router生命周期
	瀏覽器/user(直接輸入，也可以router-link跳轉，也可以this.$router.push跳轉) => router的index.js映射出User組件，加載到內存(頁面User組件可以使用n個子組件) => 替換根組件的router-view
	
	
組件的生命周期(生命周期鈎子)：
	created、mounted