mpaas-springboot-base操做手册

时间 2019-12-07

标签 mpaas springboot base 手册栏目 Spring 繁體版

原文原文链接

介绍

mpaas-springboot-base是得帆公司开发,帮助开发者开发更规范更健壮的spring boot程序java

安装

目前没有提交至maven中央仓库,后续会提交到maven仓库.目前只能采用本地安装方式,安装前确认是否本地已安装maven.执行如下命令行,如能正常执行便可.spring

$ 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"

下载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

修改项目pom.xml文件,增长依赖

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

使用

配置启动类

修改启动类xxxApplication.java增长如下注解json

@ComponentScan(basePackages = {"com.definesys.mpaas.common","启动类所在的包路径"})

spring boot默认扫描启动类所在的package下的类,要手动增长注解才能让spring boot扫描到mpaas-springboot-base.好比启动类全路径为com.definesys.demo.DemoApplication那么注解应该写成如下格式api

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

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

接口返回

全部的controller返回值统一为com.definesys.mpaas.common.http.Response该类定义了一套标准返回格式和相关apibash

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没有数据app

Response ok=Response.ok();

输出curl

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

ps:每次请求服务器返回Response都会带一个惟一的requestid,该requestid可做为日志追踪业务查询等<br/>
2. 返回非列表数据maven

//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"
}

异常处理

这里将异常分为两类

运行时异常：指由于程序bug或者系统问题致使接口调用失败,属于不可预料异常
业务异常: 指业务数据不符合要求接口自己抛出异常

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"
}

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"
}