Home
LegoAdmin系统开发手册
LegoAdmin是一款前后端分离的低代码开发平台，系统基于vue element-ui + SpringBoot框架分模块设计，经过多个大版本的迭代升级，已经逐步趋向于成熟稳定。系统集成了现阶段最流行的微服务架构，在兼容单体快捷部署的同时也具备务分布式高可用的集群部署，不管是个人还是企业使用都能大大降低对系统的运维要求。
使用LegoAdmin您可以几乎无需做任何的代码编写即可生产出一套具备流程审批、功能流转的系统。不管您是技术人员还是业务人员，只需要通过阅读系统操作手册，即可通过系统界面快速实现自己想要的功能。
如果LegoAdmin对您带来了帮助，希望您能给作者Star支持并多多推广。在系统使用过程中如果遇到问题也可以到QQ群或者仓库中提交Issues，如果您需要了解更多系统的使用和更灵活的系统定制功能，也欢迎与作者联系
gitee项目地址：https://gitee.com/zqliang_01/lego-admin.git
github项目地址：https://github.com/zqliang-01/lego-admin.git
LegoAdmin低代码开发平台是一套同时具备单体开发部署和分布式微服务开发部署的前后端分离的管理系统。基于本手册能够对理解系统项目源码、设计思路和二次开发提供帮助，同时也对LegoAdmin系统自身的建设和技术共享提供途径。
阅读本手册，您需要具备JAVA技术开发知识储备：对SpringBoot微服务、阿里系微服务组件有一定的了解、对VUE2前端开发框架有一定的了解、对Uniapp跨端开发框架有一定的了解。如果自身未接触过相关知识点，建议先自行学习相关语法基础后再阅读本手册。
本手册会基于LegoAdmin系统所使用到的技术框架进行分模块讲解，通过项目前后端分离源码、项目目录结构、设计思想等多方面进行分解说明。理论上通过对本手册的阅读能够基本熟悉LegoAdmin系统的源码结构和设计思想，对于二次开发和系统插件模块开发均有很大的帮助。LegoAdmin项目在设计初期就定义了严格的规则，各个模块基本都遵循统一的分包机制，同时对业务逻辑也是最简化的设计，如果阅读人员具备一定知识储备，通过直接阅读源码也能基本了解系统的结构思想。
由于LegoAdmin系统还在不断开升级代中，本手册只代表当前版本（V1.7）系统进行说明，对于后续系统迭代更新后产生的变化不在本手册体现。同时为了简化读者对系统源码的理解能力，很多系统设计都是直接对接数据库操作，对性能设计不做过高的要求。如果您在阅读或使用过程中遇到问题，欢迎到Github/Gitee上提交issue，作者很乐意与各位读者交流分享技术心得！
LegoAdmin系统采用Maven多模块项目模式搭建，基于各个微服务功能进行模块划分，目前系统模块划分为如下几个
整体系统模块主要分为应用模块和插件模块两类，除了lego-plugin地下的模块外，其他均为应用模块。应用模块可以作为独立的微服务直接启动，且功能和数据均互相独立。插件模块则是提供代码通用能力，如基础工具类、权限控制、mybatis-plus、hibernate、分片表等。各模块的具体说明如下：
Lego-parent模块是所有模块的父模块，本模块不涉及源码文件，只做配置管理，主要集成了项目的基础Maven仓库配置、项目前后端打包插件配置、SQL执行器插件配置、以及功能模块引用配置等信息。
Lego-admin模块是单体架构启动的入口，通过本模块的pom.xml可以看出，该模块只做其他模块引用操作，只有一个LegoAdminApplication启动类，项目开发阶段或单体启动阶段只需要启动该类的main方法即可启动整个项目后端。
LegoAdminApplication启动类说明：
该类为单体SpringBoot启动入口，该类的注解说明
@EntityScan：该注解为springjpa框架使用，用于配置扫描entity表关联领域对象的包路径，按系统默认即可
@MapperScan：该注解为mybatis-plus框架使用，用于配置mapper扫描的包路径，如果使用mapper包引入mybatis-plus时配置
@EnableFeignClients：该注解为open-feign框架使用，用于配置FeignClient接口的包路径，按系统默认即可
@SpringBootApplication：该注解为springboot框架使用，标识当前类为springboot启动入口类
@EnableJpaRepositories：该注解为springjpa框架使用，用于自定义Dao接口的扫描装配操作
创建的Bean说明
StpLogic：集成sa-token的jwt操作，通过jwt形式管理登陆token，只有单体启动时需要故通过启动来装配
resources目录配置了单体启动时的配置信息，包含：
application-template.properties：基础配置，需要拷贝重命名为application.properties，具体配置项说明见application.properties
banner.txt：项目启动banner配置，可配置后台启动时的banner信息和打印端口，springboot版本信息等
log4j2.xml：log4j2配置文件，控制日志输出的粒度和格式信息。
客户关系管理模块为系统演示模块，模块内的代码除了基础配置类代码外均为通过代码生成功能生成的代码。该模块主要是为了方便演示代码生成功能的使用，以及系统项目模块的包划分情况。
包前缀：com.lego.crm，其中com.lego为固定前缀，与启动类中配置的扫描包名相关联，不能修改，修改后会影响扫描自动装配操作。
各子包功能说明见系统包目录说明
该模块为系统必须模块，用于管理系统组织架构，基础配置相关功能。包含用户管理、组织管理、角色权限管理、应用管理、表单元数据管理、系统配置管理等接口服务。
各包的具体含义与系统包目录说明一致
Lego-system模块为系统必须模块，其中controller/romote提供基本所有模块使用的通用接口，通过ICommonService暴露，通过查看ICommonService的实现，可以发现该实现包含两个，分别是SysCommonService（单体启动时使用）和CommonService（微服务启动时使用）
ICommonService主要方法说明如下：
addLog：统一操作日志新增
findEmployeeBy：通过用户账号查询用户简要信息
findDeptBy：通过部门编码查询部门简要信息
findDictBy：通过字典编码查询字典简要信息
addSysMessage：新增系统消息
findRelateCodeBy：查询菜单关联编码（系统里目前用于查询菜单关联的报表编码）
findPermissionCodesBy：查询用户所拥有的权限编码
findRoleCodesBy：查询用户所拥有的角色编码
findDataPermissionEmployeeCode：查询当前用户的数据权限
findPermissionCodeByTable：查询自定义表单的权限（流程表单填写时校验权限用）
findFormBy：查询自定义表单的简要信息
findEmployeeCodesByRole：查询拥有指定角色的用户编码（流程节点多实例使用）
findEmployeeCodesByDept：查询用于指定部门的用户编码（流程节点多实例使用）
该服务主要为了解决跨服务调用而单独抽离，出于性能考虑，涉及到字典、用户组织相关操作可以考虑缓存后读取。涉及日志、消息发布相关的操作可以考虑引入消息队列通过异步处理减低系统操作耗时。
该模块为功能扩展模块，主要是提供了系统知识库管理能力。模块包结构严格按照基础基础模块定义，具体包说明见系统包目录说明
流程管理模块为功能扩展模块，通过接入该模块后可以是哟流程管理相关功能，具体包说明见系统包目录说明。
当前流程框架使用Flowable6.8.0版本，支持完整的流程管理，任务分配，权限控制等能力，且流程功能彻底隔离。对flowable进行了二次定制开发，主要服务类说明如下：
FlowableDefinitionService：流程定义服务，该服务集成和优化了流程定义的操作，把流程定义封装成了对应的增删改查，整合进LegoAdmin框架的Action操作中，对流程定义相关的调整产生对应的日志记录
FlowableInstanceService：流程实例服务，实例就相对于已经发起的流程。本模块对实例进行了二次开发，引入了实例状态FlowableTaskLogType，提供了查询实例状态节点（前端流程图状态展示）等方法
FlowableModelService：流程模型服务，模型即流程设计图，该服务提供了对设计图的增、删、改、查、发布等操作
FlowableTaskService：流程节点任务服务，该服务为流程主要服务，也是系统投入改造力度最大的服务。该服务涵盖了节点任务的处理、委派、转派、拒绝、保存等操作，同时也包含了对节点表单的展示，授权，管理等操作。
除了服务类外，该模块还引入了一个新包：handler，handler包主要是处理节点任务完工/流程完工的操作，通用也提供FlowableFeignCompleteHandler和FlowableLocalCompleteHandler两个实现，分别对应微服务和单体启动情况下的任务处理回调操作。通过FlowableFeignCompleteHandler我们可以发现，微服务模式下也是通过OpenFeign进行的远程调用实现任务处理。
服务网关模块为微服务模式启动时的必须模块，用于作为微服务统一的接口入口。网关模块不做功能使用，所以包布局与普通应用模块不同，更偏向于配合管理类。个包功能说明如下：
config：配置类，包含自定义负载均衡包（用于开发阶段自定义负载策略，实现减少启动模块开发），静态资源配置，用于定义本地静态资源。如果为Nginx部署可以不配置本地静态资源。
controller：首页入口，WebFlux非阻塞式的接口
filter：各类过滤器，用于控制权限是否登陆、缓存请求、跨域处理、Xss攻击处理等，gateway使用的spring-gateway，都是过滤器链的形式进行层层控制。
handler：统一异常拦截处理器
loadbalancer：负载均衡器，自定义负载均衡器，与配置类适配使用
properties：自定义配置
定时任务管理模块相当于xxl中的admin模块，主要用于配置管理定时任务、查看定时任务运行情况等操作。
本模块与xxl-job-admin对应，内部结构也是对xxl-job-admin进行的二次调整，其中对接口和服务层进行了重写，适配LegoAdmin框架的统一模式，同时集成了现有的权限管理机制。core包则是直接延用xxl-job-admin核心包，但是新增了站内信的实现MessageJobAlarm，新增了自定义配置JobAdminStartConditional用于控制系统是否启用相关的心跳服务。
该模块使用上完全兼容xxl-job-admin所有操作，同时集成了LegoAdmin的权限管理和界面风格，具体细节可以参考https://www.xuxueli.com/xxl-job/
移动端管理模块为提供移动端接入能力，如果需要使用移动端是才需要启动。该模块同样严格遵循LegoAdmin模块包结构，具体包说明见系统包目录说明。
本模块目前已经对接微信开放平台，实现微信小程序的用户自动登录流程。如果需要集成其他平台如：微信公众号、支付宝小程序等，可以按需调整对接。由于移动端使用的Uniapp技术，可以直接编译出多端源码使用。
统计分析模块主要用于管理维护自定义报表、首页大屏统计图等操作。按需启动，如果不启动则会影响首页大屏和报表的使用。
本模块通用严格遵循LegoAdmin模块包结构，具体包说明见系统包目录说明。
统计分析能完全兼容Mybatis语法的新式进行报表查询定义，主要是通过MybatisDynamicExecutor实现，同时基于ShardingJDBC实现了多数据源路由的操作，在启动sharding配置的情况下可以通过ShardingHintConfig指定SQL数据源，也可以直接在脚本中使用分片表配置实现跨库/分表查询操作。
核心模块为插件模块，主要用于提供系统的基础能力，包含：Mybatis-plus、SpringJpa、job执行器、FeignClient、Redis、Sa-token鉴权、通用查询等。LegoAdmin系统中基本所有模块均引用了核心模块，如果不希望引用过多的依赖，也可以选择不引用，而是自己按需配置自己的模块引用内容，LegoAdmin原则是模块独立且高度支持自定义，但单体启动时由于各模块会合并启动，需处理好新引入的依赖冲突问题，改模块项目的包含了基础配置，具体配置项可见本模块的application-common.yaml
Mybatis-plus：关键源码对应com.lego.core.data.mybaties，通过引用lego-core模块后通过配置文件导入mybatis即可使用，在LegoAdmin系统中Mybatis更多是用于查询类操作，自定义配置见本模块的application-mybatis.yaml
SpringJpa：关键源码对应com.lego.core.data.hibernate，通过引用lego-core模块后通过配置文件导入hibernate即可使用,在LegoAdmin系统中SpringJpa更多是用于增、删、改等业务逻辑处理操作，自定义配置见本模块的application-hibernate.yaml
job：关键源码对应com.lego.core.module.job,对应xxl-job-core内容，系统通过实现类AdminFeignClient和修改XxlJobExecutor.initAdminBizList方法类适配微服务模式下job执行器调度的场景。
FeignClient：关键源码对应com.lego.core.feign,目前feign接口层集成到了core包中，主要是为了减少分包情况，但如果存在大量频繁的feign调用，可以考虑对feign独立模块。LegoAdmin对Feign调用进行了定义，所有调用均需先定义API接口如ISystemAPI，然后再定义ISystemClient客户端，接口提供方也需要实现对应的API如SysCommonController，该操作的主要目的是使得接口的调用和提供一致化，防止接口发生变化时，FeignClient不变引起调用异常，保持接口与client同步。
Redis：关键源码对应com.lego.core.data.redis,系统重新定义了RedissonTemplate，对Redis的操作均通过该类进行。通过自定义的配置类RedisConfiguration接收系统配置并初始化集群/单机RedissonAutoConfigurationCustomizer配置器，通过自定义RedissonAutoConfiguration实现RedissonClient和RedisTemplate的bean装配。在微服务模式启动时Redis配置为必须，且sa-token通过SaTokenDaoRedisImpl来管理会话存储信息。Redis自定义配置见本模块的application-redis.yaml
Sa-token：关键源码对应com.lego.core.web.sa，LegoAdmin基本常规使用Sa-token框架，其中SaTokenInterceptor通过继承SaInterceptor扩展了权限注解的作用范围，使得直接父类注解可以作用所有子类。SaTokenDaoRedisImpl集成了redis存储会话信息的能力。SaTokenCaptchaValidator则集成了不同模式下的验证码管理流程。
SpringMVC：关键源码对应com.lego.core.web，该包地下各类的具体说明：LegoWebConfig基础配置入口，该类集成了自定义拦截器（模块可以通过实现ILegoInterceptor接口注入Bean使用）、跨域处理、基于FastJson的序列化转换器等。LegoExceptionHandler集成了统一异常拦截处理器（模块可以通过实现ILegoExceptionHandler接口注入Bean实现链式处理异常响应），LegoWebInit可进行项目启动时的数据初始化操作。
文件管理：关键源码对应com.lego.core.web.upload，所有文件处理器均需实现FileHandler接口，目前系统实现了阿里云OSS对象存储和本地文件存储两个管理器，可以通过配置lego.file.config指定。
本模块集成了ShardingJDBC相关能力，支持通过接口管理相关分片策略配置信息。通过引入本模块，即可通过元数据库的配置实现分片表数据源。本模块通用严格遵循LegoAdmin模块包结构，具体包说明见系统包目录说明。
模块关键类说明：
ShardingDataSourceConfig分片数据源配置类，当开启sharding.open=true后会通过该配置替换原数据源为ShardingJDBC数据源。
ShardingHintConfig：强制路由设置，如果开启分片数据源后可以通过该类强制指定走哪个分片路由信息。
ShardingInterceptor：清除会话强制路由信息拦截器
LegoAdmin系统后端模块采用统一的包布局，分别为：action、assembler、controller、dao、dto、entity、listener、service、vo，各包含义说明如下，实际开发过程中也可以按需调整或新增对应的包，如util等
| action |
模版方法类，增、删、改操作分别对应Add、Delete、Modify相关Action类，该类基于基础模版方法分别抽象了对应操作的方法，开发者只需要实现对应的操作类即可对相关表对象进行数据操作。 preprocess：前置校验，一般用于校验入参合法性，控制数据变更前的动作 createTargetEntity：新增数据专属，只要new出对应数据对象即可插入数据 doModify：修改数据专属，对数据对象进行set属性修改即可修改数据 postprocess：数据操作后置处理方法，一般用于处理关联数据或构造新Action操作 PS：使用Action类的数据对象需重写doBuildReadableSnapshot方法，用于匹配对象是否有做过属性修改以及生成相关变更日志操作 |
| assembler |
装配器类，用于将系统数据对象转换为前端接口返回数据对象，通过assembler可以方便的进行数据对象到结果对象的按需装配。 如果前端只需要部分数据，可以在这里进行单独过滤后再转换。如果使用系统jpa框架的数据处理，对象的get操作可能会产生动态代理的查数据操作，此时如果的跨表对象则可能会触发查询动作，并且每次都是按数据对象全字段查询，而assembler中对于该类动作需要甄别并优化处理。 如果涉及到多表跨表查询的数据结果，建议使用mybatis-plus的Mapper直接查询结果对象 |
| controller |
接口入口，对应springMVC框架的C层。系统集成了sa-token，在该层内可以通过sa-token相关的注解实现权限控制和会话管理。为了简化配置，目前事务的入口也控制在BaseController中，如果有需要可以按需修改。 该层包含remote包，用于暴露接口给其他微服务调用，在微服务模式启动时使用，该类接口需要实现对应的API接口类，用于规范定义FeignClient的方法。如CrmFlowableController控制器用于接收流程回调，就需要实现ICrmAPI接口。 |
| dao |
数据持久化层，对应JPA中的Repositories，需要包含接口和实现类两块，且实现类需在接口的impl包内，接口与实现类只有前缀I区别。接口需继承IGenericDao/IBusGenericDao，实现类需基础BusGenericDao/GenericDao和实现对应接口。 Dao层有两块常用操作，支持通过GenericConditionVO实现通用查询，还支持通过QueryHandler进行动态条件查询，具体使用见对应章节说明。通过Dao层，可以基于HQL/SQL很方便的实现多条件动态/连表查询操作 |
| dto | 前端数据交互类，在LegoAdmin系统中，接口调用返回的数据会通过XxxInfo的类返回，该类一般实现DTO父类，通过Assembler层进行数据装配后返回 |
| entity |
数据领域对象层，该层未Jpa中数据库表对应的类，一般与数据库表名驼峰命名，需继承BusEntity/BaseEntity。 该类完全兼容hibernate/jpa相关规范通过注解的形式实现数据库表操作，可由代码生成功能基于数据库表生成。 需重写doBuildReadableSnapshot方法用于action操作 |
| listener | Flowable流程监听器，用于监听流程节点操作和流程完工后的操作，会通过bean注册到IFlowableCompletedService服务中用于被Flowable流程模块调用。该包非必须，如果使用Flowable流程定义功能才需使用，如果为微服务模式启动还需定义对应的FeignClient，可参考ICrmAPI相关实现 |
| service |
服务层，由于LegoAdmin没有引入跨服务调用的机制，服务层更多是充当逻辑处理中转，还有查询处理中转的操作 包含接口 + 实现类，实现类需在接口impl包内 服务一般需继承BusService/BaseService，通过Dao和Assmebler可以很方便的实现增、删、改、查等操作 |
| vo | LegoAdmin系统中VO充当数据提交参数接收的角色，接口中接收前端提交的参数或者方法中的入参一般使用vo相关的类，命名为XxxxVO，支持继承PageVO实现分解参数接收，ModifyVO实现修改参数，CreateVO实现新增操作等 |
| mapper | Mybatis-plus定义的Mapper接口，可以支持无sql操作已经对应的Mapper.xml实现自定义sql。该包为扩展包，可按需接入 |
PS：除了上述定义的包，开发过程中可以按需新增或修改指定包，但特殊包不能修改包名和子包信息，否则可能会导致系统自动扫描装配失败！
该配置文件为springboot默认配置文件，如果是单体启动，则对应lego-admin模块的配置，微服务模式启动则每个模块均需配置。配置项说明如下
| spring.profiles.include | SpringBoot配置，用于导入需要用到的基础配置文件，common必须，mybatis框架，hibernate框架按需导入，使用系统模块时必须。实际对应Lego-core模块的配置文件 |
| spring.application.name | 模块应用名称，微服务时表示注册中心注册名称，相同名称标识同一个服务，同时也是定时任务的执行器AppName，如果设置则需与定时调度的执行器对应，单体启动时可不设置， |
| spring.cloud.sentinel.enabled | 是否启用sentinel流量监控限流，单机启动时设置为false |
| spring.cloud.service-registry.auto-registration.enabled | 是否启用nacos服务发现注册能力，单机启动时设置为false |
| server.port | 后端服务启动端口，按需设置，默认为8443 |
| sharding.open | 是否开启分片表配置，按需设置，默认为false |
| open-detail-tips | 是否启用异常提示详细信息，开启后出现异常时会在前端提示具体异常堆栈信息，默认为false |
| auto-run-sql | 是否启用自动执行更新初始化SQL脚本，启用后系统后端启动时会检测sql是否存在新版本，如果存在则自动执行更新sql |
| jdbc.classname | 基础数据库驱动类名，默认mysql驱动类 |
| jdbc.url | 基础数据库链接地址 |
| jdbc.username | 基础数据库登陆用户名 |
| jdbc.password | 基础数据库登陆密码 |
| sa-token.jwt-secret-key | Sa-token配置的jwt密钥，单机启动时才需配置，用于生成jwt-token |
| xxl.job.admin.addresses | Xxl-job调度中心地址，配置后则启动xxl机制，多个调度中心是用逗号分隔，微服务启动调度中心时可填写负载地址 lb://job，其中job为调度中心微服务名称 |
| lego.root.path | 项目源码路径，用于导入模块使用，配置为项目的根路径地址，配置后才可以使用模块导入能力 |
| lego.start-type | 服务启动模式：generic单体启动、microservice微服务启动，可不配置,默认单体模式 |
| lego.redis-host | Redis服务地址，需要include导入redis配置才会生效，更多配置信息如果需要自定义可以参考Lego-core模块的application-redis.yaml |
| lego.redis-password | Redis服务密码 |
| lego.sentinel.dashboard | Sentinel限流控制面板地址配置，配置限流监控配置面板地址 |
该配置为系统基础配置文件，包含springBoot配置、自定义配置、flowable配置、xxl-job配置、sa-token配置、feign配置等信息，具体配置项说明如下：
| server.tomcat.Xxxx | SpringBoot内置tomcat相关参数配置，具体配置可参考SpringBoot官方说明 |
|
spring.servlet.Xxxx spring.resources.Xxxx |
SpringVMC相关配置，具体配置可参考SpringMVC官方说明 |
| flowable.Xxx | Flowable工作流相关配置，具体配置项可参考Flowable官方对应版本说明 |
| lego.file.config | 附件管理器配置，可选值：local（本地存储）、aliOss（阿里云对象存储） |
| lego.file.local | 本次存磁盘储路径 |
| lego.file.oss | 阿里云对象存储参数， |
| sa-token.Xxxx | Sa-token框架配置参数，具体参数说明可参考Sa-Token官方说明 |
| xxl.job.Xxxx | Xxl-job定时任务配置参数，其中特殊参数accessToken默认为jwt密钥，否则使用lego-admin。执行器appname默认使用系统配置的application.name，否则使用xxl-job-executor-sample。其他具体参数说明可参考Xxl-job官方2.4版本说明。 |
| feign.Xxxx | Open-Feign框架配置参数，具体参数说明可参考Open-Feign官方说明 |