mpaas-springboot-base操作手冊

wls1036發表於2019-01-19
Spring Boot

介紹

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"
com.smec.remes.auto.controller.FastRepairController.testException(FastRepairController.java:50)

    ....
}

如果是執行時錯誤系統預設返回的錯誤資訊為系統出錯請聯絡管理員如果想更改該資訊，可以在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=u7cfbu7edfu51fau9519u8bf7u7a0du540eu518du8bd5
$curl http://localhost:8080/testException?data=a
{
    "code": "error",
    "message": "系統出錯請聯絡管理員",
    "requestid": "27c5ead8fa4a49e1b5cd44cc55ce130e"
}

相關文章