Yan 项目简介（Instruction）

English 中文文档

注：全新微服务项目lion已经逐步开发，基于SpringCloud的一整套方案，详情查看https://github.com/micyo202/lion

本项目是一整套整合 Dubbo+Zookeeper+SpringMVC+Spring+MyBatis 支持分布式的高效率便捷开发RPC框架，使开发人员更专注于业务，达到面向业务开发。
项目使用 Maven 构建，便于项目管理，可支持 Oracle、MySql 等主流数据库。
项目模块化分层明确，代码规范，便于后期维护等工作。
前端展示界面采用基于 Boostrap 实现的响应式布局，并集成了一系列的动画效果插件，整体界面简洁、美观大方并可优雅的与后台完成交互操作。
项目目标是为中小型企业打造全方位的J2EE企业级开发解决方案，提高工作效率。
该项目是yan-demo单节点项目的升级版，支持分布式

近期更新内容

• beta 1.0.1：添加spring-session+redis技术，用于解决负载均衡下session共享问题
• beta 1.0.0：项目整体改造，升级为RPC架构。（注：若想查看非RPC版请移步至https://gitee.com/micyo202/yan）
• beta 0.1.0：模块优化，删除不必要的模块，优化代码（模块详情参考：三、项目结构）
• beta 0.0.5：前端添加ECharts，便于图形化展示
• beta 0.0.4：添加JMS（ActiveMQ）消息服务（目前仅测试方法，暂无业务流转，后期逐渐完善细化）
• beta 0.0.3：添加Solr搜索引擎服务（基本的全文检索功能，可根据实际需求情况进行二次开发，后期本人再逐渐完善）
• beta 0.0.2：优化整体代码、添加更多注释，结构更清晰、代码更易懂
• beta 0.0.1：将原有yan-demo项目重构，保留原有功能，模块拆分、优化项目结构

项目所需工具及版本 *

• zookeeper-3.4.11 http://mirror.bit.edu.cn/apache/zookeeper/zookeeper-3.4.11
• apache-activemq-5.15.2 http://activemq.apache.org/activemq-5152-release.html
• solr-7.1.0 https://mirrors.tuna.tsinghua.edu.cn/apache/lucene/solr/7.1.0

一、项目开发环境&工具（Environment&Tools）

• MacOS Sierra / Windows 7
• MySql 5.7
• Redis 4.0.8
• JDK 1.8
• CentOS 7
• IntelliJ IDEA 2017.2.5 / Eclipse 4.6.1
• Navicat Premium 11.1.12
• Maven 3.3.9
• Jetty 9.4.6.v20170531 / Tomcat 9.0.1

二、技术选型（Technology）

1.服务端技术（Server）

2.前端技术（Web）

三、项目结构（Construction）

yan -- 根目录
├── yan-api -- 接口模块（提供核心接口方法）
|    ├── main -- 主模块路径
|    |    ├── java -- java类路径
|    |    |    ├── com.yan.api -- 核心接口包
|    |    |    |    ├── jms -- 消息服务接口
|    |    |    |    ├── persistence -- 持久化接口
├── yan-common -- 公共模块
|    ├── main -- 主模块路径
|    |    ├── java -- java类路径
|    |    |    ├── com.yan.common -- 公共类包
|    |    |    |    ├── annotation -- 注解类
|    |    |    |    ├── aspect -- 切面类
|    |    |    |    ├── constant -- 常量定义类
|    |    |    |    ├── model -- 通用模型
|    |    |    |    ├── service -- 泛型对象服务
|    |    |    |    ├── spring -- spring扩展类
|    |    |    |    ├── support -- 基础支持类
├── yan-core -- 核心模块（提供核心方法）
|    ├── main -- 主模块路径
|    |    ├── java -- java类路径
|    |    |    ├── com.yan.core -- 核心类包
|    |    |    |    ├── annotation -- 注解类
|    |    |    |    ├── aspect -- 切面类
|    |    |    |    ├── controller -- 控制器
|    |    |    |    ├── injector -- 注入类
|    |    |    |    ├── listener -- 消息消费者监听器
|    |    |    |    ├── shiro -- 安全认证类
├── yan-dao -- 数据库访问模块（该模块主要通过 mbg 插件生成相应的模型及接口映射）
|    ├── main -- 主模块路径
|    |    ├── java -- java类路径
|    |    |    ├── com.yan.dao -- dao层包
|    |    |    |    ├── mapper -- 接口映射类
|    |    |    |    ├── model -- 数据库模型类
|    |    ├── resources -- 资源配置路径
|    |    |    ├── database -- 数据库sql文件
|    |    |    ├── mybatis -- sqlMap映射文件
|    |    |    ├── properties -- 配置文件
├── yan-plugins -- 插件模块（自定义插件）
|    ├── main -- 主模块路径
|    |    ├── java -- java类路径
|    |    |    ├── com.yan.plugins -- 插件包
|    |    |    |    ├── mybatis.generator -- mbg插件类（包含注释插件、序列化插件）
├── yan-service -- 服务模块（核心接口方法实现）
|    ├── main -- 主模块路径
|    |    ├── java -- java类路径
|    |    |    ├── com.yan.service -- 服务包
|    |    |    |    ├── jms -- 消息服务接口实现类
|    |    |    |    ├── persistence -- 持久化接口实现类
├── yan-web -- web模块
|    ├── main -- 主模块路径
|    |    ├── java -- java类路径
|    |    |    ├── com.yan.web.controller -- 业务处理控制器包
|    |    ├── resources -- 资源配置路径
|    |    |    ├── properties -- 项目配置文件
|    |    |    ├── spring -- spring的配置文件
|    |    ├── webapp -- web应用根路径
|    |    |    ├── common -- 公共路径
|    |    |    ├── resources -- 静态资源路径
|    |    |    ├── views -- 视图路径

四、项目入门（Introduction）

1. 下载项目，并且导入到IDE开发工具中（建议使用：IntelliJ IDEA）
2. 使用 Maven 构建项目
3. 创建数据库并执行 yan-dao 模块中 resources/database 路径下的 yan.sql 文件，创建整个项目必要的表（如：用户表、资源表、日志记录表等...）
4. 分别修改 yan-dao、yan-service、yan-web 模块中 resources/properties 路径下的 *.properties 配置文件（具体修改方法及对应属性解释，详见 - 五、配置说明）
5. 完成以上步骤就可以正常部署启动服务了：
   a). 启动 zookeeper 服务，命令：bin/zkServer.sh start，端口：2181（*必要服务，不启动该服务导致项目无法正常运行）
   b). 启动 activemq 服务，命令：bin/activemq start，端口：8161 / 61616（非必要服务，若不启动该服务，则项目运行中会有jms监听器异常，但不影响整体能）
   c). 启动 solr 服务，命令：bin/solr start，端口：8983（非必要服务，若不启动该服务，则搜索引擎无法使用，但不影响整体功能）
   [以上服务具体配置及启动命令，这里我不多做阐述了，不知道的可自行百度搜索]
6. 启动完以上基础的服务后，就可以运行项目了
   a). 首先启动 yan-service，直接运行该模块中的 com.yan.service.ServiceApp.main() 方法来启动
   b). 其次启动 yan-web ，可（使用 jetty / tomcat 均可）[详细部署过程在这里就不多做阐述了]，启动成功后即可访问web应用界面。接下来进入开发阶段
7. 根据实际业务需求，在对应的数据库中创建业务表，表命名规范：“模块名_表名” 如：SYS_RESOURCE（系统模块资源表）
8. 修改 yan-dao 模块中 resources 路径下的 generatorConfig.xml 中的 targetPackage 包名及 tableName 表名，使用 MyBatis generator 插件生成对应的持久层模块代码（Maven 执行命令：mvn mybatis-generator:generate），具体配置请参考MyBatis GeneratorXML Configuration
9. 在 yan-api 模块中 src/main/java 路径下创建对应的接口
10. 在 yan-service 模块中 src/main/java 路径下创建对应的接口服务实现类，并在 src/main/resources/META-INF/spring 路径下的 spring-dubbo-provider.xml 配置中添加声明暴露对应服务接口
11. 在 yan-web 模块中 src/main/java 路径下创建对应的 controller 控制器，该控制器类命名规范以 Controller 结尾，继承 BaseController 类，编写 controller 控制器业务处理代码（具体使用参考 - 七、示例代码），并在 src/main/resources/spring/config 路径下的 spring-dubbo-customer.xml 配置中添加声明暴露对应服务接口
12. 在 yan-web 模块中 src/main/webapp/views 路径下创建对应的jsp页面，并编写前端页面展示代码

五、配置说明（Properties）

yan-dao 模块 resources/properties 中配置文件说明

yan-service 模块 resources/properties 中配置文件说明

yan-web 模块 resources/properties 中配置文件说明

六、常用方法（Methods）

方法均在继承于BaseController的controller类中使用this.metodName或直接使用methodName来进行调用（注：methodName代表需要调用的方法名称，方法名称见下表）

七、示例代码（Codes）

创建一个继承与BaseController的控制器

@Controller
public class XxxController extends BaseController {
	...
}

获取日志日志记录Logger对象

// 方法一：使用注解获取
@LogInject
private static Logger log;

// 方法二：使用工厂方法获取
private static Logger log = LoggerFactory.getLogger(XxxController.class);

获取service对象

// 获取delegateService对象
@Autowired
private DelegateService delegateService;

// 获取泛型Service对象
@Autowired
private XxxService xxxService;

分页查询后台代码

// 使用对象 service 分页查询数据
@RequestMapping("/list")
@ResponseBody
public PageModel<Xxx> list(int offset, int limit) {
	XxxExample example = new XxxExample();
   PageModel<Xxx> pageModel = xxxService.selectByExampleForOffsetPage(example, offset, limit);
   return pageModel;
}

// 使用 delegateService 自定义 sqlMap 分页查询数据
@RequestMapping("/list")
@ResponseBody
public PageModel<Xxx> list(int offset, int limit) {
	String statement = "com.yan.dao.mapper.xxx.XxxCustomMapper.getXxx";
	PageModel<Xxx> pageModel = delegateService.selectPagination(statement, offset, limit);
   return pageModel;
}

分页查询前台代码

<table id="table"><table>

$('#table').bsTable({
		url: '${pageContext.request.contextPath}/xxx/list',
		idField: 'id',
		columns: [
			{field: 'state', checkbox: true},
			{field: 'id', title: 'id', align: 'center'},
			...
			]
	});

文件上传

@RequestMapping("/upload")
public String upload(HttpServletRequest request) {
	// 调用父类的上传方法，在jsp中必须指定form为enctype="multipart/form-data"
	List<String> fileNames = this.fileUpLoad(request);
	return "success";
}

文件下载（在jsp页面使用通用的下载方法，使用restful风格）

<a href="${pageContext.request.contextPath}/文件名称/download">文件下载</a>

自定义文件下载后台方法

@RequestMapping("/download")
public ResponseEntity<byte[]> download(String fileName) {
	// 调用父类文件下载方法
	return this.fileDownLoad(fileName);
}

常用 delegateService 方法

// 使用自定义sql模板查询单个对象
Xxx xxx = delegateService.selectOne(statement);
Xxx xxx = delegateService.selectOne(statement, parameter);
		
// 使用自定义sql模板查询对象集合
List<Xxx> list = delegateService.selectList(statement);
List<Xxx> list = delegateService.selectList(statement, parameter);

// 使用自定义sql模板有范围的查询，（每次返回指定的对象条数集合）
List<Xxx> list = delegateService.selectList(statement, parameter, rowBounds);

// 使用自定义sql模板进行分页查询
PageModel<Xxx> pageModel = delegateService.selectPagination(statement, offset, limit);
PageModel<Xxx> pageModel = delegateService.selectPagination(statement, parameter, offset, limit);

// 使用自定义sql模板保存
int res = delegateService.insert(statement);
int res = delegateService.insert(statement, parameter);

// 使用自定义sql模板修改
int res = delegateService.update(statement);
int res = delegateService.update(statement, parameter);

// 使用自定义sql模板删除
int res = delegateService.delete(statement);
int res = delegateService.delete(statement, parameter);

常用对象 service 方法

// 使用对象方法根据主键查询
Xxx xxx = xxxService.selectByPrimaryKey(id);

// 使用对象方法根据 criteria 查询
List<Xxx> list = xxxService.selectByExample(example);

// 方法一：使用对象方法根据 criteria 分页查询（推荐）
PageModel<Xxx> pageModel = xxxService.selectByExampleForOffsetPage(example, offset, limit);
// 方法二：使用对象方法根据criteria分页查询
PageModel<Xxx> pageModel = xxxService.selectByExampleForStartPage(example, pageNum, pageSize);

// 使用对象方法添加
int res = xxxService.insert(record);
int res = xxxService.insertSelective(record);

// 使用对象方法根据主键修改
int res = xxxService.updateByPrimaryKey(record);
int res = xxxService.updateByPrimaryKeySelective(record);

// 使用对象方法根据 criteria 修改
int res = xxxService.updateByExample(record, example);
int res = xxxService.updateByExampleSelective(record, example);

// 使用对象方法根据主键删除
int res = xxxService.deleteByPrimaryKey(productCode);

// 使用对象方法删除根据 criteria 删除
int res = xxxService.deleteByExample(example);

更多方法使用请参考项目中的示例代码

八、效果预览（Preview）

九、许可证（License）

MIT License