摘要：目前已做好了一些基礎(chǔ)的東西如配置，響應(yīng)規(guī)范等和公共的模塊，主要應(yīng)用于接口快速開(kāi)發(fā)。模塊顧名思義表示令牌，用于標(biāo)識(shí)當(dāng)前用戶，同時(shí)增加接口的安全性。在使用時(shí)，客戶端必須在配置了攔截器的接口請(qǐng)求中攜帶名為的請(qǐng)求參數(shù)。

實(shí)際上這個(gè)項(xiàng)目更像一個(gè)腳手架，是我多次開(kāi)發(fā)HTTP API應(yīng)用的經(jīng)驗(yàn)總結(jié)。其中包含了常用的模塊（如賬戶相關(guān)，版本更新等），以及本人認(rèn)為比較好的開(kāi)發(fā)方式和規(guī)范。目前已做好了一些基礎(chǔ)的東西(如配置，響應(yīng)規(guī)范等)和公共的模塊，主要應(yīng)用于APP(Android,IOS,WebApp)接口快速開(kāi)發(fā)。項(xiàng)目首頁(yè)

version.xml: 存放版本更新信息。entry節(jié)點(diǎn)代表一個(gè)版本，可設(shè)置一到多個(gè)，可自由切換。android和iphone節(jié)點(diǎn)的default屬性表示當(dāng)前的版本號(hào), 對(duì)應(yīng)entry的version節(jié)點(diǎn)值；

jdbc.properties: 這個(gè)都懂的，存放數(shù)據(jù)庫(kù)連接信息；

configure.xml: root下的子節(jié)點(diǎn)可以隨便寫(xiě)，但不能包含屬性。在服務(wù)器運(yùn)行過(guò)程中，一旦此文件內(nèi)容發(fā)生了變化，會(huì)實(shí)時(shí)生效，無(wú)需重啟。

舉例，從下面的文件中獲取prefix節(jié)點(diǎn)的值可使用AppProperty.me().getProperty("resource.prefix");讀取.

    
        
        http://mlongbo.com/upload
    

AppConstant類(lèi)存放諸如resource.prefix的配置常量, AppProperty類(lèi)用于讀取配置，因此建議使用如:

//AppContant類(lèi)的偽代碼
public static final String RES_PREFIX = "resource.prefix";

//AppProperty類(lèi)的偽代碼
public String resourcePrefix() {
    return getProperty(AppConstant.RES_PREFIX);
}

//業(yè)務(wù)模塊中調(diào)用。獲取配置
String str = AppProperty.me().resourcePrefix();

檢查賬號(hào)是否被注冊(cè): GET /api/account/checkUser

發(fā)送注冊(cè)驗(yàn)證碼: POST /api/account/sendCode

注冊(cè): POST /api/account/register

登錄： POST /api/account/login

查詢用戶資料: GET /api/account/profile

修改用戶資料: PUT /api/account/profile

修改密碼: PUT /api/account/password

修改頭像: PUT /api/account/avatar

意見(jiàn)反饋: POST /api/feedback

版本更新檢查: GET /api/version/check

文件上傳: POST /api/fs/upload

避免手拼json導(dǎo)致的錯(cuò)誤，而使用將Java Bean序列化為JSON的方式。

json數(shù)據(jù)的根節(jié)點(diǎn)使用code字段標(biāo)識(shí)本次響應(yīng)的狀態(tài)，如成功、失敗、參數(shù)缺少或參數(shù)值有誤，以及服務(wù)器錯(cuò)誤等；message節(jié)點(diǎn)包含服務(wù)器響應(yīng)回來(lái)的一些提示信息，主要是方便客戶端開(kāi)發(fā)人員在對(duì)接接口時(shí)定位錯(cuò)誤出現(xiàn)的原因。

一般的，響應(yīng)數(shù)據(jù)會(huì)分為兩種，第一種為列表數(shù)據(jù)，如一組用戶信息，另外一種是實(shí)體信息，如一條用戶信息。data字段值為數(shù)組，攜帶列表數(shù)據(jù)，datum字段值為json對(duì)象，攜帶實(shí)體數(shù)據(jù)。

如:

//實(shí)體數(shù)據(jù), 此結(jié)構(gòu)對(duì)應(yīng)DatumResponse類(lèi)
{
  "code": 1,
  "message": "成功查詢到該用戶信息",
  "datum": {
    "name": "jack",
    "lover": "rose",
    "sex": 1,
    "email": "[email protected]"
  }
}
//列表數(shù)據(jù), 此結(jié)構(gòu)對(duì)應(yīng)DataResponse類(lèi)
{
  "code": 1,
  "message": "成功查詢到兩條用戶信息",
  "data": [{
    "name": "jack",
    "lover": "rose",
    "sex": 1,
    "email": "[email protected]"
  },{
    "name": "rose",
    "lover": "jack",
    "sex": 0,
    "email": "[email protected]"
  }]
}
//登錄成功, 此結(jié)構(gòu)對(duì)應(yīng)LoginResponse類(lèi)
{
  "code": 1,
  "message": "登錄成功",
  "constant": {
    "resourceServer": "http://fs.mlongbo.com" //文件地址前綴
  }
  "info": {
    "name": "jack",
    "lover": "rose",
    "sex": 1,
    "email": "[email protected]"
  }
}
//多文件上傳, 部分成功，部分失敗. 此結(jié)構(gòu)對(duì)應(yīng)FileResponse類(lèi)
{
  "code": 0, //只要有一個(gè)文件上傳失敗，code就會(huì)是0
  "failed": ["file3"]
  "datum": {
    "file1": "/upload/images/file1.jpg",
    "file2": "/upload/images/file2.jpg"
  }
}
//缺少參數(shù)
{
  "code": 2,
  "message": "缺少name參數(shù)"
}
//參數(shù)值有誤
{
  "code": 2,
  "message": "sex參數(shù)值只能為0或1"
}

//token無(wú)效
{
  "code": 422,
  "message": "token值是無(wú)效的，請(qǐng)重新登錄獲取"
}

附上本人常用的幾種code值:

1 ok - 成功狀態(tài)。查詢成功，操作成功等；

0 faild - 失敗狀態(tài)

2 argument error - 表示請(qǐng)求參數(shù)值有誤, 或未攜帶必需的參數(shù)值

3 帳號(hào)已存在

4 注冊(cè)驗(yàn)證碼錯(cuò)誤

500 error - 服務(wù)器錯(cuò)誤

404 not found - 請(qǐng)求的資源或接口不存在

422 token error - 未傳遞token參數(shù),或token值非法

最多的還是非空檢查, 這里重點(diǎn)說(shuō)一下。因此，我寫(xiě)了一個(gè)工具。使用方法如下：

String name = getPara("name");
String lover = getPara("lover");
//使用此方式的前提是當(dāng)前controller類(lèi)要繼承自BaseAPIController類(lèi)
if (!notNull(Require.me().put(name, "name參數(shù)不能為空").put(lover,"lover參數(shù)不能為空"))) {
  return;
}

//效果等同于如下代碼:
if (StringUtils.isEmpty(name)) {
  renderJson(new BaseResponse(2, "name參數(shù)不能為空"));
  return;
}
if (StringUtils.isEmpty(lover)) {
  renderJson(new BaseResponse(2, "lover參數(shù)不能為空"));
  return;
}

//如果沒(méi)有傳遞name參數(shù)，將會(huì)得到如下響應(yīng):
{
  "code": 2,
  "message": "name參數(shù)不能為空"
}

公共模塊實(shí)現(xiàn)了基本功能，你可以根據(jù)自己的業(yè)務(wù)需求自由調(diào)整數(shù)據(jù)字段。

token, 顧名思義, 表示令牌，用于標(biāo)識(shí)當(dāng)前用戶，同時(shí)增加接口的安全性。目前不支持過(guò)期策略，也僅支持一個(gè)用戶一個(gè)終端的方式，即用戶在一處登錄后，再在另一處登錄會(huì)使之前登錄的token失效。

要啟用token功能只需要配置TokenInterceptor攔截器類(lèi)即可。

在使用時(shí)，客戶端必須在配置了攔截器的接口請(qǐng)求中攜帶名為"token"的請(qǐng)求參數(shù)。

服務(wù)端在繼承了BaseAPIController類(lèi)后可以直接調(diào)用getUser();函數(shù)獲取當(dāng)前用戶對(duì)象. 注意: 為了正常地使用getUser函數(shù)，必須在登錄接口中查出用戶對(duì)象后，使用類(lèi)似如下代碼建立token與用戶對(duì)象的映射：

User nowUser = User.user.findFirst(sql, loginName, StringUtils.encodePassword(password, "md5"));

//之后要將token值響應(yīng)給客戶端
String token = TokenManager.getMe().generateToken(nowUser));

在以往的接口開(kāi)發(fā)過(guò)程中，我們都是使用一個(gè)統(tǒng)一的文件上傳接口上傳文件后，服務(wù)器響應(yīng)上傳成功后的文件地址，客戶端再使用業(yè)務(wù)接口將文件地址作為參數(shù)值發(fā)送到服務(wù)器。這樣做的好處之一是便于服務(wù)端將文件統(tǒng)一管理，比如做緩存或CDN；另一方面是為了減小耦合度，比如此時(shí)要換成七牛CDN存放靜態(tài)文件，客戶端只需要改寫(xiě)文件上傳部分的代碼即可。

目前的文件上傳接口已實(shí)現(xiàn)一或多個(gè)文件同時(shí)上傳，客戶端在上傳時(shí)，必須要為每個(gè)文件指定一個(gè)請(qǐng)求參數(shù)名, 參數(shù)名用于在上傳結(jié)束后，根據(jù)服務(wù)器的響應(yīng)數(shù)據(jù)判斷哪些文件是上傳失敗的，哪些是上傳成功的，以及成功后的文件地址是什么。

服務(wù)器響應(yīng)實(shí)例如下：

//全部上傳成功
{
  "code": 1,
  "message": "success",
  "datum": {
    "file1": "/upload/images/file1.jpg",
    "file2": "/upload/images/file2.jpg"
  }
}
//全部上傳失敗
{
  "code": 0,
  "message": "failed",
  "failed": ["file1", "file2"]
}
//部分成功，部分失敗
{
  "code": 0, //只要有一個(gè)文件上傳失敗，code就會(huì)是0
  "failed": ["file3"]
  "datum": {
    "file1": "/upload/images/file1.jpg",
    "file2": "/upload/images/file2.jpg"
  }
}

關(guān)于版本更新的說(shuō)明，請(qǐng)查看第一章節(jié)中的項(xiàng)目配置，以及API文檔；

意見(jiàn)反饋模塊比較簡(jiǎn)單，你可以根據(jù)你的業(yè)務(wù)需求改動(dòng)數(shù)據(jù)庫(kù)字段，以及接口參數(shù)。

這個(gè)模塊目前實(shí)現(xiàn)的接口有：

檢查賬號(hào)是否已注冊(cè)

發(fā)送手機(jī)驗(yàn)證碼

注冊(cè)

登錄

查詢用戶資料

修改用戶資料

修改密碼

如果使用手機(jī)驗(yàn)證碼功能，你需要改寫(xiě)SMSUtils類(lèi)的sendCode函數(shù)以實(shí)現(xiàn)短信發(fā)送功能；如果不使用手機(jī)驗(yàn)證碼功能，可以在注冊(cè)的接口代碼中將驗(yàn)證碼檢查的功能去掉。在開(kāi)發(fā)調(diào)試的過(guò)程中，可以訪問(wèn)code.html查詢手機(jī)驗(yàn)證碼。

如果用戶表中的字段不能滿足你的業(yè)務(wù)需求，你可以自由增刪修改，但同時(shí)也需要修改注冊(cè)和修改用戶資料接口。

Jetty插件: 無(wú)需使用tomcat，直接使用maven的jetty插件啟動(dòng)項(xiàng)目；

ant工具： 一般情況下，我們的項(xiàng)目是在服務(wù)端使用maven自動(dòng)構(gòu)建的，但在開(kāi)發(fā)過(guò)程中，代碼經(jīng)常改變需要重新部署，如果重新打包更新又比較麻煩，因此在服務(wù)端使用maven命令重新構(gòu)建后，可直接執(zhí)行ant命令將已改動(dòng)的文件copy到tomcat應(yīng)用目錄。所以，若想正常使用該工具，你需要修改build.xml，將tomapp值修改為你的tomcat應(yīng)用路徑。

現(xiàn)有的API接口文檔

關(guān)于作者

馬隆博，Java，Javascript

Blog: http://mlongbo.com

E-Mail: [email protected]

相關(guān)項(xiàng)目: https://github.com/lenbo-ma/jfinal-api-s...

文章編寫(xiě)于: 2015/2/21

轉(zhuǎn)載請(qǐng)注明出處:

原文地址: http://mlongbo.com/2015/使用Jfinal編...

掃描二維碼，關(guān)注我。
內(nèi)容大多會(huì)是后端技術(shù)、前端工程、DevOps，偶爾會(huì)有一些大數(shù)據(jù)相關(guān)，會(huì)推薦一些好玩的東西。希望你會(huì)喜歡~