[任務(wù)]
用筋斗云框架創(chuàng)建一個(gè)Web接口項(xiàng)目叫mysvc，創(chuàng)建數(shù)據(jù)庫，提供對(duì)ApiLog對(duì)象的操作接口。
先從github上下載開源的筋斗云后端框架及示例應(yīng)用：https://github.com/skyshore2001/jdcloud-php
建議安裝git工具直接下載，便于以后更新，例如直接創(chuàng)建Web接口項(xiàng)目叫mysvc：
git clone https://github.com/skyshore2001/jdcloud-php.git mysvc如果github訪問困難，也可以用這個(gè)git倉庫： http://dacatec.com/git/jdcloud-php.git
配置好Web服務(wù)器，php環(huán)境和MySQL數(shù)據(jù)庫。 注意PHP最低版本需要5.4版本，需要打開mysql, pdo, gd等支持。
在Web服務(wù)器上將項(xiàng)目下的接口主目錄（即server目錄）暴露出來，假設(shè)URL是：
http://localhost/mysvc/先別急著訪問這個(gè)地址，而是先配置數(shù)據(jù)庫連接等，在瀏覽器中打開這個(gè)頁面：
http://localhost/mysvc/tool/init.php這個(gè)工具會(huì)先檢查運(yùn)行環(huán)境是否正確，如有異常（比如php版本不對(duì)，缺少組件等）請(qǐng)先解決。 然后創(chuàng)建接口應(yīng)用使用的數(shù)據(jù)庫和配置文件。
初始化工具運(yùn)行完后，生成的配置文件為php/conf.user.php，之后也可以手工編輯該文件。
數(shù)據(jù)模型定義在主設(shè)計(jì)文檔DESIGN.wiki中，作為示例，里面定義了一些數(shù)據(jù)模型，像用戶(User)，訂單(Ordr)以及前面提過的操作日志(ApiLog)等，還定義了一些常用接口，如登錄操作(login)等。 我們通過通過命令行工具tool/upgrade.php可以創(chuàng)建或更新數(shù)據(jù)庫：
cd toolphp upgrade.php(這時(shí)進(jìn)入upgrade交互操作，輸入initdb命令創(chuàng)建或更新數(shù)據(jù)庫)> initdb(輸入命令q退出)> q我們進(jìn)入server目錄看看：
api.php就是接口應(yīng)用程序，提供Web接口。tool目錄中是一些線上工具，比如查看日志、計(jì)劃任務(wù)等。對(duì)象型接口一般寫在文件php/api_objects.php中，函數(shù)型接口一般寫在php/api_functions.php中。 里面已經(jīng)包含了一些示例接口，一般在示例基礎(chǔ)上修改即可。共用邏輯寫在app.php中，各種工具和接口應(yīng)用程序均可用；注意如果只是多個(gè)接口共用的邏輯，直接寫在api.php文件中就可以。為了學(xué)習(xí)對(duì)象型接口，我們將php/api_objects.php清空，從頭開始來寫，以暴露ApiLog對(duì)象為例，在php/api_objects.php中加上一句：
class AC_ApiLog extends accessControl{}這一句代碼就提供了對(duì)ApiLog對(duì)象的標(biāo)準(zhǔn)增刪改查(CRUD)接口如下：
查詢對(duì)象列表，支持分頁、查詢條件、統(tǒng)計(jì)等：ApiLog.query() -> table(id, tm, addr)添加對(duì)象，通過POST參數(shù)傳遞字段值，返回新對(duì)象的idApiLog.add()(tm, addr) -> id獲取對(duì)象ApiLog.get(id) -> {id, tm, addr}更新對(duì)象，通過POST參數(shù)傳遞字段值。ApiLog.set(id)(tm?, addr?)刪除對(duì)象ApiLog.del(id)[接口原型的描述方式]
在上面的接口原型描述中，用了兩個(gè)括號(hào)的比如add/set操作，表示第一個(gè)括號(hào)中的參數(shù)通過GET參數(shù)（也叫URL參數(shù)）傳遞，第二個(gè)括號(hào)中的參數(shù)用POST參數(shù)（也叫FORM參數(shù)）傳遞。 多數(shù)接口參數(shù)支持用GET方式或POST方式傳遞，除非在接口說明中特別指定。 帶”?”表示參數(shù)或返回的屬性是可選項(xiàng)，可以不存在。
接口原型中只描述調(diào)用成功時(shí)返回?cái)?shù)據(jù)的數(shù)據(jù)結(jié)構(gòu)，完整的返回格式是[0, 返回?cái)?shù)據(jù)]；而在調(diào)用失敗時(shí)，統(tǒng)一返回[非0錯(cuò)誤碼, 錯(cuò)誤信息]。
我們可以直接用curl工具來模擬前端調(diào)用，用add接口添加一行數(shù)據(jù)，使用HTTP POST請(qǐng)求：
curl http://localhost/mysvc/api.php/ApiLog.add -d "tm=2016-9-9 10:10" -d "addr=shanghai"curl用”-d”參數(shù)指定參數(shù)通過HTTP body來傳遞，由于默認(rèn)使用HTTP POST謂詞和form格式(Content-Type=application/x-www-form-urlencoded)， 這種參數(shù)一般稱為POST參數(shù)或FORM參數(shù)，與通過URL傳遞的GET參數(shù)相區(qū)別。 結(jié)果輸出一個(gè)JSON數(shù)組：
[0,11338]0表示調(diào)用成功，后面是成功時(shí)返回的數(shù)據(jù)，add操作返回對(duì)象id，可供get/set/del操作使用。
用get接口取出這個(gè)對(duì)象出來看看：
curl http://localhost/mysvc/api.php/ApiLog.get?id=11338輸出：
[0,{"id":11338,"tm":"2016-09-09 00:00:00","addr":"shanghai"}]這里參數(shù)id是通過URL傳遞的。 前面說過，未顯式說明時(shí)，接口的參數(shù)可以通過URL或POST參數(shù)方式來傳遞，所以本例中URL參數(shù)id也可以通過POST參數(shù)來傳遞：
curl http://localhost/mysvc/api.php/ApiLog.get -d "id=11338"如果取一個(gè)不存在的對(duì)象，會(huì)得到錯(cuò)誤碼和錯(cuò)誤信息，比如：
curl http://localhost/mysvc/api.php/ApiLog.get?id=999999輸出：
[1,"參數(shù)不正確"]再用set接口做一個(gè)更新，按接口要求，要將id參數(shù)放在URL中，要更新的字段及值用POST參數(shù)：
curl http://localhost/mysvc/api.php/ApiLog.set?id=11338 -d "addr=beijing"輸出：
[0, "OK"]再看很靈活的query接口，取下列表，默認(rèn)支持分頁，會(huì)輸出一個(gè)nextkey字段：
curl http://localhost/mysvc/api.php/ApiLog.query返回示例：
[0,{ "h":["id","tm","addr"], "d":[[11353,"2016-01-04 18:31:06","::1"],[11352,"2016-02-04 18:30:43","::1"],...], "nextkey":11349}]返回的格式稱為壓縮表，”h”為表頭字段，”d”為表的數(shù)據(jù)，在接口描述中用table(id, 其它字段...)表示。
默認(rèn)返回的JSON數(shù)據(jù)未經(jīng)美化，效率較高，如果想看的清楚些，可以在配置文件conf.user.php中設(shè)置測(cè)試模式：
putenv("P_TEST_MODE=1");測(cè)試模式不僅美化輸出數(shù)據(jù)，還可返回更多調(diào)試信息，前端可用URL參數(shù)_debug設(shè)置調(diào)試等級(jí)0-9，如果設(shè)置為9，甚至可以查看SQL調(diào)用日志：
這在調(diào)試SQL語句時(shí)很有用。此外，測(cè)試模式還會(huì)開放某些內(nèi)部接口，以及缺省允許跨域訪問，便于通過web頁面測(cè)試接口。注意線上生產(chǎn)環(huán)境絕不可設(shè)置為測(cè)試模式。
query接口也支持常用的數(shù)組返回，需要加上_fmt=list參數(shù)：
返回示例：
[0,{ "list": [ { "id": 11353, "tm": "2016-01-04 18:31:06", "addr": "::1" }, { "id": 11352, "tm": "2016-02-04 18:30:43", "addr": "::1" }, ... ], "nextkey":11349}]還可以將_fmt參數(shù)指定為”csv”, “Excel”, “txt”等，在瀏覽器訪問時(shí)可直接下載相應(yīng)格式的文件，讀者可自己嘗試。
取下一頁可以用_pagekey字段，還可指定一次取的數(shù)據(jù)條數(shù)，用_pagesz字段：
curl "http://localhost/mysvc/api.php/ApiLog.query?_pagekey=11349&_pagesz=5"不僅支持分頁，query接口非常靈活，可以指定返回字段、查詢條件、排序方式， 比如查詢2016年1月份的數(shù)據(jù)(cond參數(shù))，結(jié)果只需返回id, addr字段(res參數(shù)，也可用于get接口)，按id倒序排列(orderby參數(shù))：
curl http://localhost/mysvc/api.php/ApiLog.query -d "res=id,addr" -d "cond=tm>='2016-1-1' and tm<'2016-2-1'" -d "orderby=id desc"甚至可以做統(tǒng)計(jì)，比如查看2016年1月里，列出訪問次數(shù)排名前10的地址，以及每個(gè)地址訪問了多少次服務(wù)器，也可以通過query接口直接查出。 做一個(gè)按addr字段的分組統(tǒng)計(jì)(gres參數(shù))：
curl http://localhost/mysvc/api.php/ApiLog.query -d "gres=addr" -d "res=count(*) cnt" -d "cond=tm>='2016-1-1' and tm<'2016-2-1'" -d "orderby=cnt desc" -d "_pagesz=10"輸出示例：
[0,{ "h":["addr","cnt"], "d":[["140.206.255.50",1],["101.44.63.119",73],["121.42.0.85",70],...], "nextkey": 3}][接口調(diào)用的描述方式]
在之后的示例中，我們將使用接口原型來描述一個(gè)調(diào)用，不再使用curl，比如上面的調(diào)用將表示成：
ApiLog.query(gres=addr res="count(*) cnt" cond="tm>'2016-1-1' and tm<'2016-2-1'" orderby="cnt desc" _pagesz=10)->{ "h":["addr","cnt"], "d":[["140.206.255.50",1],["101.44.63.119",73],["121.42.0.85",70],...], "nextkey": 3}返回?cái)?shù)據(jù)如非特別聲明，我們將只討論調(diào)用成功時(shí)返回的部分，比如說返回”O(jiān)K”實(shí)際上表示返回[0, "OK"]。
新聞熱點(diǎn)
疑難解答
圖片精選
網(wǎng)友關(guān)注
