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

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

version.xml: 存放版本更新信息。entry節(jié)點代表一個版本，可設置一到多個，可自由切換。android和iphone節(jié)點的default屬性表示當前的版本號, 對應entry的version節(jié)點值；

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

configure.xml: root下的子節(jié)點可以隨便寫，但不能包含屬性。在服務器運行過程中，一旦此文件內容發(fā)生了變化，會實時生效，無需重啟。

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

    
        
        http://mlongbo.com/upload
    

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

//AppContant類的偽代碼
public static final String RES_PREFIX = "resource.prefix";

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

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

檢查賬號是否被注冊: GET /api/account/checkUser

發(fā)送注冊驗證碼: POST /api/account/sendCode

注冊: POST /api/account/register

登錄： POST /api/account/login

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

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

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

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

意見反饋: POST /api/feedback

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

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

避免手拼json導致的錯誤，而使用將Java Bean序列化為JSON的方式。

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

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

如:

//實體數(shù)據(jù), 此結構對應DatumResponse類
{
  "code": 1,
  "message": "成功查詢到該用戶信息",
  "datum": {
    "name": "jack",
    "lover": "rose",
    "sex": 1,
    "email": "jack@gmail.com"
  }
}
//列表數(shù)據(jù), 此結構對應DataResponse類
{
  "code": 1,
  "message": "成功查詢到兩條用戶信息",
  "data": [{
    "name": "jack",
    "lover": "rose",
    "sex": 1,
    "email": "jack@gmail.com"
  },{
    "name": "rose",
    "lover": "jack",
    "sex": 0,
    "email": "rose@gmail.com"
  }]
}
//登錄成功, 此結構對應LoginResponse類
{
  "code": 1,
  "message": "登錄成功",
  "constant": {
    "resourceServer": "http://fs.mlongbo.com" //文件地址前綴
  }
  "info": {
    "name": "jack",
    "lover": "rose",
    "sex": 1,
    "email": "jack@gmail.com"
  }
}
//多文件上傳, 部分成功，部分失敗. 此結構對應FileResponse類
{
  "code": 0, //只要有一個文件上傳失敗，code就會是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無效
{
  "code": 422,
  "message": "token值是無效的，請重新登錄獲取"
}

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

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

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

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

3 帳號已存在

4 注冊驗證碼錯誤

500 error - 服務器錯誤

404 not found - 請求的資源或接口不存在

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

最多的還是非空檢查, 這里重點說一下。因此，我寫了一個工具。使用方法如下：

String name = getPara("name");
String lover = getPara("lover");
//使用此方式的前提是當前controller類要繼承自BaseAPIController類
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;
}

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

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

token, 顧名思義, 表示令牌，用于標識當前用戶，同時增加接口的安全性。目前不支持過期策略，也僅支持一個用戶一個終端的方式，即用戶在一處登錄后，再在另一處登錄會使之前登錄的token失效。

要啟用token功能只需要配置TokenInterceptor攔截器類即可。

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

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

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

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

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

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

服務器響應實例如下：

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

關于版本更新的說明，請查看第一章節(jié)中的項目配置，以及API文檔；

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

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

檢查賬號是否已注冊

發(fā)送手機驗證碼

注冊

登錄

查詢用戶資料

修改用戶資料

修改密碼

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

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

Jetty插件: 無需使用tomcat，直接使用maven的jetty插件啟動項目；

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

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

關于作者

馬隆博，Java，Javascript

Blog: http://mlongbo.com

E-Mail: mlongbo@gmail.com

相關項目: https://github.com/lenbo-ma/jfinal-api-s...

文章編寫于: 2015/2/21

轉載請注明出處:

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

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