新源基础开发框架使用手册 V1.7

公共文档

变更历史

1 框架说明

1.1 组件介绍

框架基于Spring Boot进行开发，目前主要使用了如下的相关组件：

• MyBatis： ORM框架
• Apache Shiro: 权限安全框架
• Ehcache: 本地缓存，目前主要是Shiro依赖用到
• Redis: 网络实时缓存
• Freemarker: 模板引擎
• Log4j：日志
• Layui： 前端框架

1.2 框架图

需要注意几点：

• 在XxxService通过Mybatis注释，配置对应的Mapper接口类
• 整个框架没有DAO层的出现，基本上BaseService起到了通用DAO的作用。

1.3 包类名规范

在此与test_demo表为例，子系统名即为：test，相关类的目录规范如下

1.3.1 后端代码

• 实体类： com.bitnei.cloud.test.domain.Demo.java
• Mapper接口： com.bitnei.cloud.test.mapper.DemoMapper.java
• 业务接口： com.bitnei.cloud.test.service.IDemoService.java
• 业务实现： com.bitnei.cloud.test.service.impl.DemoService.java
• 控制类： com.bitnei.cloud.test.web.DemoController.java
• Mapper.xml： /resources/mapper/test/DemoMapper.xml

1.3.2 前端代码

• 列表页面： /resources/templates/module/test/demo/list.ftl
• 新增页面： /resources/templates/module/test/demo/add.ftl
• 编辑页面： /resources/templates/module/test/demo/update.ftl
• 导出模板： /resources/templates/module/test/demo/export.xls

1.3.3 自定义样式脚本图片

二次开发自定义编写的脚本，样式，还有引用的图片，必须按规定放在/resources/static/extend目录。引用的第三方前端组件，按规定放到/resources/static/frame目录

1.4 配置项说明

2 数据库规范

表名和字段名，统一采用小写+下划线，并且应该是有意义而且易于理解的，最好是能够表达字段含义的英文字母。
注意，所有的表和字段都必须填写相关注释。

2.1 表名

• 命名规则： 子系统_名称，比如 base_user,则表示基础子系统下的用户表。
• 注释规则： 模块名|表名描述|sql表alias，比如“用户管理|用户表|u”，其中的u将对应mapper.xml中的alias

2.2 字段

• 主键规则：统一用id varchar(36)
• 名称规则：若表有名称字段的，统一用name，长度视具体情况而定
• 注释规则：字段描述
  

  框架支持生成搜索条件的注释，比如注释字段为用户名|action:search#lis

3 代码细节

3.1 混合模型支持

• 实体类需要继承TailBean类来实现混合模型(实体+Map)的特性。关于混合模型使用的规则，数据表字段直接在实体中定义，联表查询的字段，用map获取。

• 混合模型需要Mapper.xml的支持，需要配置resultMap

• 获取map的值，比如User u;可以通过u.get("roleIds")获取roleIds的值

3.1 业务层

• 直接通过指定的sqlid来调用
• 业务实现类要指定命名空间，即mapper类

4 组件标签

4.1 select

如果ds=sql，那么sql应该固定返回val和name字段，比如select id as val,name as name from xxxx

示例

  <div class="layui-form-item">
        <label class="layui-form-label">状态</label>
        <div class="layui-input-block">
        <@core.select name="status"  ds="dict" key="USER_STATE" value="1" />
        </div>
    </div>

4.2 radio

如果ds=sql，那么sql应该固定返回val和name字段，比如select id as val,name as name from xxxx

4.3 checkbox

4.3.1 属性定义

如果ds=sql，那么sql应该固定返回val和name字段，比如select id as val,name as name from xxxx

4.4 dialog (列表弹窗选择器)

4.4.1 属性定义

sql应该固定返回id和name字段，比如select id as id,name as name from xxxx

4.4.2 示例

   <div class="layui-form-item">
        <label class="layui-form-label">角色</label>
        <div class="layui-input-block">
        <@core.dialog name="roleNames" key="base.RoleMapper.treeNodes" value="" multiple=true refer="roleIds" title="请选择角色" height="600px" />
        </div>
    </div>

4.5 tree (树形选择器)

4.5.1 属性定义

sql应该固定返回id和name字段，比如select id as id,name as name from xxxx

4.5.2 示例

   <div class="layui-form-item">
        <label class="layui-form-label">父节点</label>
        <div class="layui-input-block">
        <@core.tree name="parentName" key="base.AreaMapper.treeNodes" value="${(obj.parentId)!}" display="${(obj.tails.parentName)!}"  multiple=true refer="parentId" title="请选择上级区域"/>
        </div>
    </div>

4.6 lngLat (经纬度拾取器)

4.6.1 属性定义

4.6.2 示例

<div class="layui-form-item">
     <@core.lngLat lngName="lng" latName="lat" lng="${(obj.lng)!0}" lat="${(obj.lat)!0}"  addressFrom="address"/>
   <div>

5 格式化标签

5.1 字典格式化

示例

<@formatter.dict code='BASE_EMPLOYEE_IS_USE' key='isUse'/>
#表格
{field: 'isUse', title: '权限状态', width: 120, templet:"#isUse"},

5.2 名称格式化

此标签主要用于列表格式化显示，另外`DataLoader.loadNames(Object)`方法可用于在编辑、查看页面，将外键关联的名称显示出来，而不必通过关联表查询。同样在处理导出时，调用此方法，也可以将相关数据查询出来。

5.2.1 属性

5.2.2 使用说明

1、 在domain实体的相应get方法增加@LinkName注解

@LinkName(table = "base_role")
public String getRoleIds() {
    return roleIds;
}

2、 在service层显示调用DataLoader.loadNames(Object)方法（目前传参支持List、LayModel和TailBean的子类）

LayModel layModel = new LayModel();
ayModel.setCount(pm.getTotal());
layModel.setData(pm.getRows());
DataLoader.loadNames(layModel);
return layModel;

3、在前端页面使用标签

<@formatter.name key='roleIds' url='/role/update' width="600px" height='500px'/>
<script>
#表格列定义
 {field: 'roleNames', title: '角色',templet: '#roleIds'},
</script>

5.2.3 效果

6 开发规范

此章节主要约定了开发过程中的规范，避免开发人员在开发过程中，出现遗漏和不规范的情况。

6.1 权限控制

该框架采用 Apache Shiro实现用户访问权限的控制，支持前后端的权限控制。其中前端采用的是Freemarker标签方式，而后台是需要在控制器方法中，增加注解。而权限控制的核心元素，则是资源编码（对应模块管理中的编码）。另外，建议编码的命名为业务大模块_功能模块_动作,比如新增用户，命名为BASE_USER_ADD

通过代码生成器生成的代码，已经生成了对应的资源信息。如果是单独开发的，需要必须手工增加资源信息，并在前后端代码中，加以控制。我们约定，在下面章节点，我们将以新增用户的权限处理来举例说明，权限是如何控制的

6.1.1 前端控制

前端通过freemarker标签进行控制，常用的标签包括：

• hasPermission: 验证当前用户是否拥有该权限
• authenticated: 验证用户是否已经登录系统
• lacksPermission：验证当前用户不拥有某种权限，与hasPermission标签是相对的

1、 为了对新增用户进行权限控制，首先我们需要在前台页面/base/user/list.ftl页面中，html的新增按钮元素用freemarker标签已经包括起来

<@shiro.hasPermission name="BASE_USER_ADD">
    <a class="layui-btn btn-add btn-default" id="btn-add">新增</a>
</@shiro.hasPermission>

2、然后，出于安全和隐私控制，我们同时将新增相关的JS代码也进行控制

<@shiro.hasPermission name="BASE_USER_ADD">
//绑定新增按钮事件
bindAdd('/base/user/add','新增',"540px","530px",gridObj);
</@shiro.hasPermission>

6.1.2 后端控制

在控制器通过注解@RequiresPermissions控制权限（注意，功能关联的其他请求，也应该加上注解进行控制，常用的就是包括页面和Ajax调用）

/**
* 新增页面
* @param model
* @return
*/
@GetMapping(value = "/add")
@RequiresPermissions("BASE_USER_ADD")
@SLog(action = "新增页面")
public String add(Model model) {
    return BASE+"add";
}
/**
* 保存
* @param job
* @return
*/
@PostMapping(value = "/add")
@ResponseBody
@RequiresPermissions("BASE_USER_ADD")
@SLog(action = "新增用户")
public AppBean add(User user){
    userService.insert(user);
    return new AppBean("增加成功");
}

6.2 日志收集

系统日志目前是通过提供自定义的注解方式实现，提供的注解为下：
* Module: 模块名，比如用户管理
* SLog: 动作名，比如新增

下面我们以新增用户举例：

1、需要在控制类声明上加上@Module注解

/**
 * 用户管理
 * @author 陈鹏
 * @Time 2017-07-04 18:29:52
 */
@Module(name = "用户管理")
@Controller
@RequestMapping(value = "/user")

2、在新增方法加上注解SLog注解，由于新增涉及到两个请求，所以此处在这两个方法都加上SLog注解

/**
* 新增页面
* @param model
* @return
*/
@GetMapping(value = "/add")
@RequiresPermissions("BASE_USER_ADD")
@SLog(action = "新增页面")
public String add(Model model) {
    return BASE+"add";
}
/**
* 保存
* @param job
* @return
*/
@PostMapping(value = "/add")
@ResponseBody
@RequiresPermissions("BASE_USER_ADD")
@SLog(action = "新增用户")
public AppBean add(User user){
    userService.insert(user);
    return new AppBean("增加成功");
}

3、日志采集情况可以通过日志管理中查看。

6.3 缓存处理

6.3.1 Mybatis二级缓存

框架对于Mybatis二级缓存进行扩展，由Mybatis默认的内存改为了Redis。使用方式如下：

1、配置文件，在application.yml的redis配置中，增加mybatis缓存配置spring.redis.mybatis.index，即指定二级缓存放的redis的db

spring:
  redis:
    database: 12
    host: 192.168.6.141
    port: 6380
    password: 123456
    mybatis:
      index: 13

2、需要在mybatis的mapper的xml开启二级缓存支持，即cache的type为com.bitnei.cloud.common.cache.MybatisRedisCache

<mapper namespace="com.bitnei.cloud.base.mapper.JobMapper">
    <cache type="com.bitnei.cloud.common.cache.MybatisRedisCache" eviction="LRU" flushInterval="6000000" size="1024" readOnly="false"/>
    ...........
</mapper>

3、缓存管理，为了避免出现开发人员使用不当导致内存不同步的情况，框架提供了mybatis二级缓存的管理功能，支持查看和清理等操作。

6.4 导出文件

6.4.1 流程描述

在这里，以导出系统日志为示例：

1、编写mysql语句： 正常情况下，我们可以直接使用数据列表的sql语句，如下

 <!-- 分页查询 -->
    <select id="pagerModel" resultMap="tailResults" parameterType="java.util.HashMap">
        select
        <include refid="moreColumns"/>
        from
        base_log log
        where
        1=1
        <if test="username != null">
        and log.username like "%"#{username}"%"
        </if>
        <if test="moudle != null">
        and log.moudle like "%"#{moudle}"%"
        </if>
        <if test="action != null">
        and log.action like "%"#{action}"%"
        </if>
        ORDER BY log.TIME DESC
    </select>

2、业务层采集数据： 如果模块代码是通过代码生成工具生成的，正常业务层代码是不需要改动的

    @Override
    public void export() {
        List list = findBySqlId("pagerModel",ServletUtil.getQueryParams());
        String srcBase = RequestContext.class.getResource("/templates/").getFile();
        String srcFile = srcBase +"module/base/log/export.xls";
        ExcelData ed = new ExcelData();
        ed.setTitle("日志管理");
        ed.setExportTime(DateUtil.getNow());
        ed.setData(list);
        String outName = String.format("%s-导出-%s.xls", "日志管理", DateUtil.getShortDate());
        EasyExcel.renderResponse(srcFile,outName,ed);
    }

3、配置excel模板： 框架的excel模板为export.xls，excel文件中共有两个sheet,一个为列定义，一个参数配置。详细的excel配置，将在下面章节进行描述。

6.4.2 excel配置

6.4.2.1 列定义

列定义采用Freemarker实现，支持freemarker指令表达式。在这里，框架默认对象名为obj，比如Log实体定义为

public class Job extends TailBean {
    /**  **/
    private String id;
    /** 任务名称 **/
    private String name;
    /** 类名 **/
    private String className;
    /** 方法名 **/
    private String methodName;
    /** Cron表达式 **/
    private String cron;
    /** 上次执行时间 **/
    private String lastJobTime;
    /** 最后异常信息 **/
    private String lastException;
    /** 启用状态 **/
    private Integer status;
    /** 耗时 **/
    private Integer takeTime;
    /** 创建时间 **/
    private String createTime;
    /** 创建人 **/
    private String createBy;
    /** 更新时间 **/
    private String updateTime;
    /** 更新人 **/
    private String updateBy;
    /** 备注 **/
    private String note;
    ....getter/setter........
}

然后在excel中就可以根据实现情况，进行配置模板。另外，导出文件的样式，也可以直接调整。导出文件，样式和模板的保持一致。

6.4.2.2 参数配置

目前框架支持的参数项如下：

• extName ：导出文件扩展名，支持xls、zip，默认值为xls
  1、xls: 即导出单一excel文件
  2、zip: 生成至少1个excel文件，然后压缩为zip文件
• pageSize: 分页数，在导出文件为zip或多sheet时，sheet的记录数，默认为10000
• enableMultSheet: 是否启用多sheet，如果extName为xls，此参数为是，将配合分页数使用，即一个sheet的数量为分页数

6.4.3 导出文件名规范

• 导入文件名： 模块名-时间.后缀，比如日志管理-20180410154150.xls或日志管理-20180410154150.zip
• sheet命名： 数据列起始序号

7 系统自动化工具

7.1 代码生成

代码生成依赖于数据库表的注释，详细注释规则参见# 2 数据库规范。

• 1、数据表： 即要生成代码的数据库表
• 2、所属上级： 即模块的归属上级菜单
• 3、生成列表：
• • XML: 即xxxMapper.xml文件
• • Mapper： Mapper接口
• • Domain：模型实体
• • 服务层： IXxxService接口和XxxService实现类
• • 控制层： XxxController
• • 列表页面: list.ftl文件
• 工具栏按钮：
• • 增加：增加按钮，勾选时，会生成add.ftl
• • 导出：勾选时，会生成export.xls导出模板文件
• 行功能按钮
• • 编辑：勾选时，会生成update.ftl
• • 查看：勾选时，会生成view.ftl
• • 删除：勾选时会生成删除相关代码