mpaas-springboot-base操做手冊

介紹

mpaas-springboot-base是得帆公司開發,幫助開發者開發更規範更健壯的spring boot程序

安裝

目前沒有提交至maven中央倉庫,後續會提交到maven倉庫.目前只能採用本地安裝方式,安裝前確認是否本地已安裝maven.執行如下命令行,如能正常執行便可.

$ mvn -v
Apache Maven 3.5.0 (ff8f5e7444045639af65f6095c62210b5713f426; 2017-04-04T03:39:06+08:00)
Maven home: /Users/asan/u01/mvn
Java version: 1.8.0_161, vendor: Oracle Corporation
Java home: /Library/Java/JavaVirtualMachines/jdk1.8.0_161.jdk/Contents/Home/jre
Default locale: zh_CN, platform encoding: UTF-8
OS name: "mac os x", version: "10.12.4", arch: "x86_64", family: "mac"

1. 下載mpaas-springboot-base-v1.0.0.jar包,執行如下命令將jar包安裝至本地倉庫.

mvn install:install-file -Dfile="/Users/asan/workspace/mpaas/common/out/artifacts/mpaas-springboot-base_v1_0_0/mpaas-springboot-base-v1.0.0.jar" -DgroupId=com.definesys.mpaas -DartifactId=mpaas-springboot-base -Dversion=1.0.0 -Dpackaging=jar

1. 修改項目pom.xml文件,增長依賴

<dependency>
    <groupId>com.definesys.mpaas</groupId>
    <artifactId>mpaas-springboot-base</artifactId>
    <version>1.0.0</version>
</dependency>

使用

配置啓動類

修改啓動類xxxApplication.java增長如下註解

@ComponentScan(basePackages = {"com.definesys.mpaas.common","啓動類所在的包路徑"})

spring boot默認掃描啓動類所在的package下的類,要手動增長註解才能讓spring boot掃描到mpaas-springboot-base.好比啓動類全路徑爲com.definesys.demo.DemoApplication那麼註解應該寫成如下格式

@ComponentScan(basePackages = {"com.definesys.mpaas.common","com.definesys.demo"})

至此,你可使用mpaas-springboot-base全部的功能.

接口返回

全部的controller返回值統一爲com.definesys.mpaas.common.http.Response該類定義了一套標準返回格式和相關api

Response字段

private String code = CODE_OK;  //操做結果編碼 ok/error
    private String message;         //記錄錯誤信息或者須要提示給用戶的信息
    private Long total;             //記錄總數
    private Object data;            //非列表數據
    private List<Object> table;     //列表數據
    private String requestid;       //請求uuid
    
    public static final String CODE_OK = "ok";
    public static final String CODE_ERR = "error";

規定若是是系統錯誤,如程序異常,空指針等,以http status形式返回500錯誤.程序應該返回一個code=error的而且http code=500的Response,但若是放在業務代碼裏處理不只繁瑣也容易忽略掉異常,致使有漏網之魚.mpaas也提供了更爲簡便的方案,下面會提到.<br/>
從返回的數據類型來看,抽象出列表和非列表兩種數據,這邊放到兩個字段裏,列表數據放到table非列表數據防到data

Response-Api:返回成功

1. 只返回code沒有數據

Response ok=Response.ok();

輸出

{
    "code": "ok",
    "requestid": "0f253675a20147d1b4b106404e4ed21d"
}

ps:每次請求服務器返回Response都會帶一個惟一的requestid,該requestid可做爲日誌追蹤業務查詢等<br/>
2. 返回非列表數據

//Response ok=new Response()
Response ok=Response.ok();
Map<String,String> data=new HashMap<String,String>();
data.put("user","asan");
data.put("company","definesys");
ok.setData(data);

輸出

{
    "code": "ok",
    "data": {
        "company": "definesys",
        "user": "asan"
    },
    "requestid": "2fcae4e453b746e6bfbf95fc76e1618b"
}

若是返回的數據都是key-value形式,也能夠寫成以下形式

Response ok = Response.ok().set("user", "asan")
                .set("company", "definesys")
                .set("email","jianfenng.zheng@definesys.com");

3. 返回列表數據

List<String>list=new ArrayList<>();
list.add("jianfeng");
list.add("asan");
list.add("Mr.Zheng");
Response ok=Response.ok();
ok.setTable(list);

輸出

{
    "code": "ok",
    "total": 3,
    "table": [
        "jianfeng",
        "asan",
        "Mr.Zheng"
    ],
    "requestid": "534435d7812d4810916abd9577b350cf"
}

一樣也能夠寫成以下形式

Response ok = Response.ok().addListItem("jianfeng")
                .addListItem("asan")
                .addListItem("Mr.Zheng");

4. 返回錯誤

Response ok = Response.error("系統出錯");

輸出

{
    "code": "error",
    "message": "系統出錯",
    "requestid": "a491589ed2b04fe1b1a7e4c73c29178e"
}

異常處理

這裏將異常分爲兩類

1. 運行時異常：指由於程序bug或者系統問題致使接口調用失敗,屬於不可預料異常
2. 業務異常: 指業務數據不符合要求接口自己拋出異常

mpass也分別提供兩個類MpaasRuntimeException和MpaasBusinessException對應運行時異常和業務異常

下面以一個例子說明說明這兩個異常使用方法<br/>

測試接口

@RequestMapping(value = "/testException")
    public Response testException(@RequestParam(value = "data") String data) {
        Integer value = null;
        try {
            value = Integer.parseInt(data);
        } catch (Exception ex) {
            throw new MpaasRuntimeException(ex);
        }
        if (value < 10) {
            throw new MpaasBusinessException("數據不合法請輸入一個大於10的數字");
        }
        return Response.ok();
    }

RuntimeException(運行時異常)

$ curl http://localhost:8080/testException?data=a -v
*   Trying ::1...
* TCP_NODELAY set
* Connected to localhost (::1) port 8080 (#0)
> GET /testException?data=a HTTP/1.1
> Host: localhost:8080
> User-Agent: curl/7.51.0
> Accept: */*
>
< HTTP/1.1 500   ##返回500
< Content-Type: application/json;charset=UTF-8
< Transfer-Encoding: chunked
< Date: Mon, 27 Aug 2018 10:58:41 GMT
< Connection: close
<
* Curl_http_done: called premature == 0
* Closing connection 0
{
    "code": "error",
    "message": "系統出錯請聯繫管理員",
    "requestid": "f8beb8c1e817414ba0b2e856f22b0b4d"
}

BusinessException(業務異常)

$ curl http://localhost:8080/testException?data=9 -v
*   Trying ::1...
* TCP_NODELAY set
* Connected to localhost (::1) port 8080 (#0)
> GET /testException?data=9 HTTP/1.1
> Host: localhost:8080
> User-Agent: curl/7.51.0
> Accept: */*
>
< HTTP/1.1 200 ##返回200
< Content-Type: application/json;charset=UTF-8
< Transfer-Encoding: chunked
< Date: Mon, 27 Aug 2018 10:59:57 GMT
<
* Curl_http_done: called premature == 0
* Connection #0 to host localhost left intact
{
    "code": "error",
    "message": "數據不合法請輸入一個大於10的數字",
    "requestid": "0ff8e520aa8548cba06be3d181fc0f7d"
}

ok

curl http://localhost:8080/testException?data=11 -v
*   Trying ::1...
* TCP_NODELAY set
* Connected to localhost (::1) port 8080 (#0)
> GET /testException?data=11 HTTP/1.1
> Host: localhost:8080
> User-Agent: curl/7.51.0
> Accept: */*
>
< HTTP/1.1 200
< Content-Type: application/json;charset=UTF-8
< Transfer-Encoding: chunked
< Date: Mon, 27 Aug 2018 11:01:41 GMT
<
* Curl_http_done: called premature == 0
* Connection #0 to host localhost left intact
{
    "code": "ok",
    "requestid": "8e5db7548fc34f5c95420b5ea23e9893"
}

在開發時,但願後臺可以返回完整錯誤棧這樣方便後臺人員排查問題,能夠在application.properties加入如下配置

spring.mpaas.mode=DEV

$curl http://localhost:8080/testException?data=a
{
    "code": "error",
    "message": "com.definesys.mpaas.common.exception.MpaasRuntimeException: java.lang.NumberFormatException: For input string: \"a\"\ncom.smec.remes.auto.controller.FastRepairController.testException(FastRepairController.java:50)\n
    ....
}

若是是運行時錯誤系統默認返回的錯誤信息爲系統出錯請聯繫管理員若是想更改該信息，能夠在application.properties加入如下配置

spring.mpaas.mode=PROD
spring.mpaas.errormsg=提示信息的unnicode編碼

若是是中文須要轉成unicode編碼,能夠在http://tool.chinaz.com/tools/unicode.aspx這裏進行轉碼.如想更改成系統出錯請稍後再試轉碼以後配置

spring.mpaas.mode=PROD
spring.mpaas.errormsg=\u7cfb\u7edf\u51fa\u9519\u8bf7\u7a0d\u540e\u518d\u8bd5

$curl http://localhost:8080/testException?data=a
{
    "code": "error",
    "message": "系統出錯請聯繫管理員",
    "requestid": "27c5ead8fa4a49e1b5cd44cc55ce130e"
}