api接口約定及數據規范 · tp3擴展基礎類

> ### api接口設計的最佳規范是遵循restful 風格 > ### 規范是約定，目的是讓開發者在同一種規則下面編寫api接口，避免歧義 > ### 規范參照其他，但也不必完全遵循，設計出符合我們自己使用方便的規范即可 **url的設計：** * 按照rest的理念，將一切視為資源 * url中不應該包含動詞，以簡單明了的名詞作為url , 使得url 更加的語義化，減少url的長度 * 以HTTP動詞作為此次請求的動作類型 * tp中需要配合路由實現 **我們自己的項目：** * 由于tp自帶路由解析，我們可以自定義語義化的url , 甚至使用強制路由模式，即每個請求都必須有對應的路由匹配，才能請求成功，否則404. * 不使用傳統的pathinfo模式，因為會暴露項目的應用路徑 * 后臺使用param()方式獲取參數，避免出現參數獲取不到的問題 > #### url設計最佳實踐： > 1、定義自己的路由文件，如有必要強制使用路由 > 2、查詢：GET，創建：POST，更新：PUT，刪除：DELETE > 3、請求頭和響應頭一律使用json類型的數據格式： Content-Type:Application/json, > 4、對于同一個url名詞可以對應多種操作，如下： ``` http://127.0.0.1/articles GET http://127.0.0.1/articles/1 GET http://127.0.0.1/articles POST http://127.0.0.1/articles/1 PUT http://127.0.0.1/articles/1 DELETE ``` 那么后臺對應的路由就該這樣： ``` 'URL_ROUTER_ON' => true, 'URL_ROUTE_RULES'=>[ ['articles$' ,'Home/Index/index','',['method' => 'get']], ['articles$' , 'Home/Index/add','',['method' => 'post']], ['articles/:id$' , 'Home/Index/info','',['method' => 'get']], ['articles/:id$' , 'Home/Index/update','',['method' => 'put']], ['articles/:id$' , 'Home/Index/delete','',['method' => 'delete']], ], ``` **傳輸數據格式：** * 服務端與客戶端數據傳遞使用json格式 * 請求參數和返回參數中，盡量不要參雜無用字段，即需要什么就傳什么 * 對于每個字段的數據類型應該盡量嚴格區分，由于js是強語言類型，PHP是弱語言類型，字符串和數字對于PHP語法本身沒什么影響，但是對于js卻完全不同。 * 一個完整的api請求應該包含這幾個部分：HTTP請求 = 請求方式 + 請求頭 + 請求體； * HTTP響應 = 狀態碼 + 響應頭 + 響應體； * 盡量避免null類型的字段，可以給個默認值 "" > 數據傳輸最佳實踐： **HTTP請求：** ``` GET方式請求： HTTP/1.1 GET www.xxx.com Content-Type:application/json a=1&b=3&c=tt POST方式請求 HTTP/1.1 POST www.xxx.com Content-Type:application/json { "a": 1, "b":2, "c" :"ttt" } ``` | 參數 | 描述 | | --- | --- | | POST\|GET | 請求方式 | | Content-Type:application/json | 傳輸數據格式 json類型 | | a=1&b=3&c=tt <br> { "a":1, ... } | key-value 格式 <br> { } 格式 | **HTTP響應：** ``` HTTP/1.1 200 ok Content-Type:application/json { "data":[], "message":"xxxxxxxxxxxx", "errcode" : "xxxxxxxxxxxx" } HTTP/1.1 400 Bad Request Content-Type:application/json { "message":"xxxxxxxxxxxx", "errcode" : "xxxxxxxxxxxx" } ``` | 參數 | 描述 | | --- | --- | | 200 \| 400 | 表述成功的狀態碼 \| 表示失敗的錯誤碼 | | Content-Type:application/json | 傳輸數據格式 json類型 | | data | 返回的數據 [ 錯誤的請求沒有該字段 ] | | message | 返回的提示信息 | | errcode | 返回的信息代碼 | > 約定后臺數據返回的固定格式：異常或失敗返回: ``` { "message": "姓名必須", "errcode": 1005 } ``` 查詢列表（不分頁）返回： ``` { "data": [ { "id": 2, "name": "dino", "nickname": "sunny", "mobile": "15205451022" } ], "message": "查詢成功", "errcode": 1000 } ``` 查詢單條記錄： ``` { "data": { "id": 6, "name": "dd_dino12121" }, "message": "查詢成功", "errcode": 1000 } ``` 查詢分頁列表返回： ``` { "data": { "total": 10, "per_page": 1, "current_page": 1, "last_page": 10, "list": [ { "nickname": "sunny", "name": "dd_0007", "id": 14 } ] }, "message": "查詢成功", "errcode": 1000 } ``` 添加成功返回： ``` { "data": [], "message": "添加成功", "errcode": 1001 } ``` 編輯成功返回： ``` { "data": [], "message": "編輯成功", "errcode": 1002 } ``` 刪除成功返回： ``` { "data": [], "message": "刪除成功", "errcode": 1003 } ``` > 數據格式的問題解決： 1、由于MySQL數據庫本身的原因，默認會把數據庫中的字段類型全部轉為字符串，解決方法是修改公共配置文件： ``` // 數據庫連接參數 'DB_PARAMS' => array( PDO::ATTR_STRINGIFY_FETCHES => false, PDO::ATTR_EMULATE_PREPARES => false ), ``` 2、使用模型獲取器，自動將字段類型轉為需要的格式