# web-sdk

**Repository Path**: qsyout/web-sdk

## Basic Information

- **Project Name**: web-sdk
- **Description**: 基于springboot 2.0.0.RELEASE封装集成的json api快速开发组件
- **Primary Language**: Java
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2020-08-18
- **Last Updated**: 2021-03-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# web-sdk

#### 介绍
基于springboot 2.0.0.RELEASE封装集成的json api快速开发组件，  
即可按照快速json方式开发，亦可按照传统mvc形式进行开发，  
持久化层进行统一封装，方便调用  
封装一系列工具类，完全满足日常web开发使用；

#### 软件架构
基于springboot 2.0.0.RELEASE封装，使用其他主要组件如下：  
    springboot 2.0.0.RELEASE  
    beetl 2.9.3  
    fastjson 1.2.31  
    kaptcha 2.3.2  
    validate-starter 1.0.0.RELEASE  

#### 使用说明

    maven中引用：
```
    <parent>
		<groupId>org.springframework.boot</groupId>
		<artifactId>spring-boot-starter-parent</artifactId>
		<version>2.0.0.RELEASE</version>
	</parent>

    ……

    <dependency>
        <groupId>com.qsyout</groupId>
        <artifactId>web-sdk</artifactId>
        <version>1.0.0.RELEASE</version>
    </dependency>
```

    主要配置项如下：  
        com.qsyout.sdk.log.path=logback日志文件存放路径  
        com.qsyout.sdk.mail.host=邮件服务器地址，推荐使用[smtp.163.com]  
        com.qsyout.sdk.mail.userName=账户名  
        com.qsyout.sdk.mail.password=账户密码  
        com.qsyout.sdk.mail.encoding=UTF-8  
        com.qsyout.sdk.mail.alias=qsyout软件平台    邮件别称  
        com.qsyout.sdk.mail.admin=管理员邮箱地址  发生系统错误时，会将异常错误信息的堆栈发送到管理员邮箱  
        com.qsyout.sdk.sync.dao.threads=10，使用多线程的形式查询数据库，查询连接池的数量，默认10  
  
    注解使用：  
        @Api    标注在请求的方法上[或者标注在BaseService子类的execute方法上]   
            desc    接口描述  
            open    是否是开放api(不需要登录)，默认false  
            permission    接口的权限标识   
            record  是否记录日志(一般指数据库简要日志)，默认true   
        @JsonResult    标注在请求的方法上[或者标注在BaseService子类的execute方法上]   
            info    是否提示消息，默认false   
            message    消息提示内容，默认：操作成功

        说明：所有标注JsonResult注解的请求方法，返回统一json结构，示例如下：   
```
        {
            "status":1200,info:true,message:"操作成功",data:obj      ---obj  表示具体返回值
        }
```  
        status为返回状态：1200成功，2500系统错误，1500业务错误，1403权限不足，1413参数校验错误  
  
  
    快速json api开发方式：  
        1、添加spring bean并继承com.qsyout.sdk.declare.BaseService，bean命名必须以Service结尾；  
        2、接口注册：在resources/receives下根据url路径添加xml文件，例如：   
            url:/sys/menu/loadMenuData.do  --->  LoadMenuDataService
![接口定义位置](https://gitee.com/qsyout/web-sdk/raw/master/dist/loadMenuData.png "接口定义位置")     
   
        3、xml中定义了xml头和请求参数的结构，详情参考：
[validate-starter 1.0.0.RELEASE](https://gitee.com/qsyout/validate-starter)   
   
   
    持久化层开发方式：          
        1、mybatis的xml文件直接定义在resources/sqlmap下，例如：  
![sqlmap定义位置](https://gitee.com/qsyout/web-sdk/raw/master/dist/sqlmap.png "sqlmap定义位置")     
        
        2、xml定义示例：  
```
        <?xml version="1.0" encoding="UTF-8"?>
        <!DOCTYPE mapper PUBLIC "-//mybatis.org//DTD Mapper 3.0//EN" "http://cache.qsyout.com/dtd/mybatis-3-mapper.dtd">
        <mapper namespace="TABLE_NAME">
                <insert id="insert" parameterType="Map">
                insert into table(
                    `column1`,`column2`,`column3`
                )values(
                    #{column1},#{column2},#{column3}
                )
            </insert>
        </mapper>
```
        3、统一调用IbatisDao的相关方法即可完成数据库操作：  
            ibatisDao.update(String statementName, Object params)    数据操纵语言DML(新增/编辑/删除)   
            ibatisDao.load(String statementName, Object params)    数据查询语言DQL(查询结果仅仅一条，大于一条报错)   
            ibatisDao.queryForList(String statementName, Object params)    数据查询语言DQL(查询结果大于等于一条)   
            statementName:TABLE_NAME.insert    params:mybatis参数（parameterType）
              
        4、调用方式：  
            在BaseService子类中，直接调用ibatisDao；   
            在其它bean中使用，仅需要依赖注入即可；  

        5、事务管理：在需要事务的方法上添加@Transactional即可；  
  
  
    异常处理：  
        框架封装了3种运行时异常，用于不同的应用场景：
            1、业务异常：com.qsyout.sdk.ex.BusinessException，在也业务方法中抛出，用于当***不满足业务条件时提醒用户消息；   
            2、参数校验异常：com.qsyout.sdk.ex.ParamsValidateException，很少调用，框架一般会进入业务方法前校验参数，当参数不符合条件时，抛出该异常，当一些特殊场景需要按照条件校验参数时用到；  
            3、com.qsyout.sdk.ex.ForbiddenException，很少调用，框架一般在验证权限时调用；

    工具类：
        框架封装一些常见的工具类：
            DateUtil        时间相关的工具类
            EncryptUtil     加密工具类（md5）
            JSEscapeUtils   java模拟js的escape和unescape函数
            MailUtil        发送邮件工具类
            SpringUtil      spring获取bean工具类
            StringUtil      字符串工具类
            SubjectUtil     当前请求工具类封装
            WebUtil         web相关的工具类


#### 技术支持
    技术交流群QQ：1009166083，有任何问题或者技术咨询可发送邮件到2375276632@qq.com并备注web-sdk技术咨询