简介面向政企单位办公场景的 Java 公文流转系统源码适合刚接触 OA 或公文审批流程的 Java Web 开发者参考学习也可作为高校 Java Web 课程设计与毕业设计的素材。项目围绕公文生命周期组织代码包含发文登记、收文管理、审批流转、会签、退回以及权限控制等模块能够帮助读者理解一类 OA 系统的状态流转与角色协作逻辑。压缩包共 157 个文件约 3.88MB类型统计以 60 个 class、40 个 JSP、30 个 Java、8 个 jar、7 个 XML 为主。JSP 页面负责界面展示Java 与 class 承载业务逻辑jar 提供框架依赖XML 管理数据源或参数配置整体目录结构较清晰适合导入 Eclipse 或 IDEA 后结合数据库运行调试。已有 280 人学习下载从中可以提炼 DAO、Service、Servlet 的分层写法与审批状态更新思路也可以借助项目中的 JSP 标签和权限判断方式为二次开发电子政务、OA 办公应用提供可落地的源码参考。1. 拿到 Java 公文流转系统源码.zip第一件事不是看代码接手一个 Java 公文流转系统源码.zip大部分人的第一反应是解压后直接翻代码结果看了一下午 controller 和 mapper越看越晕最后还是跑不起来。这类源码包在毕业设计、课程设计和中小型单位 OA 采购里出现频率极高本质是一个以审批流为核心的 Web 应用覆盖发文、收文、签报、会议纪要等场景。它的价值不在于代码写得有多花哨而在于工作流引擎和权限模型能不能在这个基础上改造成你自己的业务。适合谁看刚入职没接触过工作流的 Java 开发、要用现成源码做毕设的学生、以及想评估这套东西能不能直接给单位用的人。下文只讲一件事——怎么把这份 zip 变成一套能跑、能改、能上线试用的系统。2. 解压后先看工程骨架源码模块划分与依赖关系文档说这是“源码.zip”但 zip 里的工程结构直接决定你要不要继续投入时间。先按一个标准 Spring Boot 项目的思路去摸骨架比东翻一页西看一个类要高效得多。2.1 先用目录树定位三个关键位置拿到任意 Java 源码包我一般会先解压然后看顶层目录。不要急着在 IDE 里打开先在本机用命令行把结构列出来。常见做法是直接用tree命令Windows 下没有就dir /sMac 和 Linux 直接tree -L 3。看三个位置src/main/java下是否按controller / service / mapper / entity分包这决定代码好不好找逻辑入口。src/main/resources下有没有application.yml或application.properties以及processes/bpmn这类目录——存在它说明流程引擎用的不是纯自研状态机。pom.xml里的依赖坐标看清楚 Spring Boot 版本、工作流引擎选型、持久层框架用的是 MyBatis 还是 JPA。拿一份真实的源码包来做例子它的顶层结构一般是这样的java-gongwen-system ├── pom.xml ├── README.md ├── sql │ └── gongwen_init.sql └── src ├── main │ ├── java │ │ └── com │ │ └── office │ │ ├── controller │ │ ├── service │ │ ├── mapper │ │ └── model │ └── resources │ ├── application.yml │ ├── mapper │ └── processes └── test这个结构里sql目录的价值比src目录还高——先看初始化 SQL 能知道数据库里到底有哪些表、有哪些是 Activiti 或 Flowable 的引擎表有哪些是业务表哪些是权限表。我拿到包会直接把 SQL 文件打开搜索CREATE TABLE的个数通常一个能跑起来的 WA 系统表数量在 30 到 60 张之间。如果只有 10 来张表那这个公文的“流转”大概率只是把状态字段改了改并不是真正的工作流引擎。2.2 技术栈选型为什么大多是 Spring Boot MyBatis Activiti国内能下载到的 Java 公文流转源码技术栈高度趋同Spring Boot 作为容器MyBatis 或 MyBatis-Plus 做持久层MySQL 存业务数据前面的网页渲染层可能是 Thymeleaf、JSP 或前后端分离的 Vue 工程。工作流引擎这块要么集成 Activiti 7 或 Flowable要么自己写一张approval_record表加一个status字段硬编码判断节点状态。真实项目里这两种方案怎么选带 Activiti/Flowable 的源码包上手成本和坑都多一倍但后期扩展审批链路的能力强很多。自研状态机的源码包结构简单、好读懂但一旦出现“多级审批驳回后重新提交要回到上一节点”这种需求状态字段会膨胀到完全失控。就公文流转这个业务来说我建议优先选带流程引擎的版本因为发文审批天然有“科室拟稿→部门负责人审核→办公室复核→分管领导签发”这种多级节点靠状态字段硬写的系统三个月后没人能维护。看pom.xml时把握几个关键依赖坐标parent groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-parent/artifactId version2.5.12/version /parent dependency groupIdorg.activiti/groupId artifactIdactiviti-spring-boot-starter/artifactId version7.1.0.M6/version /dependency dependency groupIdmysql/groupId artifactIdmysql-connector-java/artifactId scoperuntime/scope /dependency讲一下这里的参数逻辑Spring Boot 版本锁定在 2.5.x 是最常见的——太新容易和 Activiti 自动配置冲突太老又带不动 JDK 8 以上的新语法。Activiti 选 7.1.0.M6 这个里程碑版本是因为它默认支持 Spring Boot 2.x 的自动装配避免了老版本那种自己手工注册ProcessEngine的一大堆 XML 配置。实际项目里看到这个组合基本可以判断写这套源码的人至少自己跑通过一次。2.3 数据库表模型怎么一眼认出引擎表还是业务表数据库里同时存在两类表这是公文流转系统区分其他管理系统的显著特征。一类是 Activiti 引擎表表名有规律act_ge_*是通用数据act_ru_*是运行实例act_hi_*是历史数据比如act_ru_task存当前待办任务、act_hi_procinst存历史流程实例。另一类是业务表以sys_、biz_开头比如sys_user、sys_role、biz_oa_document公文主表、biz_oa_attachment附件表。看一套系统能不能改明白先分清楚这两类表非常重要。我见过不少人在act_ru_task里去查业务字段查半天发现里面根本没有公文标题因为它只存流程实例 ID 和任务节点信息公文的基本信息全部在biz_oa_document表里。业务表和流程表的关联靠的是process_instance_id或business_key这种关联字段源码的 service 层要做一次“流程实例→业务主表”的映射。改公文的状态显示、列表查询动的一定是业务表改审批链路、多级审核节点动的一定是 BPMN 文件和流程引擎相关代码。这个边界想不清楚后面二次开发一定会陷入“黑匣子”状态。3. 从 zip 到跑通环境准备与最小启动步骤这部分是新手卡住的重灾区。缺一个 JDK 环境变量配置、数据库版本不对、端口被占用任何一个环节都能让系统停在启动日志里不走。按下面的顺序一步步来。3.1 环境准备与版本匹配表动手之前先把版本对齐。常见的失败案例是用 MySQL 8.0 跑 MySQL 5.7 的初始化脚本、用 JDK 17 去跑 Spring Boot 2.5编译没问题但驱动和依赖直接报缺包。下面这组版本是我在多个源码包里验证过的稳妥搭配组件推荐版本说明JDK1.88u201Spring Boot 2.5 和 Activiti 7 官方兼容度最高MySQL5.7.x初始化脚本多半按这个版本写导出Maven3.6.33.8 有时会卡中央仓库私服配置Redis不需要大多数源码没接 Redis若配置了才需要Node.js不需要前后端分离版本才需要本轮按后端单体讲JDK 安装完成后按 Windows 或 Linux 把JAVA_HOME指到 JDK 根目录并加到PATH然后在命令行验证java -version mvn -version mysql --version如果mvn -version报错而java -version正常说明 Maven 找不到 JDK 路径去检查系统环境变量里的JAVA_HOME是否配置这一步万不能省。3.2 初始化数据库与修改配置文件解压源码后在sql目录找到初始化脚本。连接 MySQL 后用 source 命令一次性导入不要在 Navicat 里直接拖 SQL 文件有些脚本里带了USE语句连库不对会出现部分表丢失的情况mysql -uroot -p source /root/java-gongwen-system/sql/gongwen_init.sql;导入完成后回来改application.yml。最核心的改动就是数据源配置其他配置项可以先用源码里的默认值跑通后再调server: port: 8080 spring: datasource: url: jdbc:mysql://localhost:3306/gongwen_db?useUnicodetruecharacterEncodingutf8useSSLfalseserverTimezoneAsia/ShanghainullCatalogMeansCurrenttrue username: root password: 123456 driver-class-name: com.mysql.cj.jdbc.Driver activiti: database-schema-update: true db-history-used: true history-level: full这里重点说明两个参数。数据源 URL 必须带characterEncodingutf8和nullCatalogMeansCurrenttrue——前者解决公文正文和附件名中文乱码后者是 Activiti 表结构初始化时“找不到 act_ge_property 表”的经典报错来源。database-schema-update: true表示首次启动时让 Activiti 自动建 25 张引擎表生产环境要改成false并手动固化表结构但本地第一次跑必须为 true否则启动报Table act_ge_property doesnt exist。3.3 在项目根目录启动源码包后端传统单体项目最省事的方式是直接在项目根目录执行 Maven 启动命令不需要先把工程导入 IDEA 再跑先验证环境是通的再进 IDEcd /root/java-gongwen-system mvn spring-boot:run第一次执行会花几分钟下载依赖注意看日志末尾。启动成功的标志不是出现 “Started Application in xx seconds”而是数据库里多出了act_ge_property等以act_开头的一批表。启动过程如果报依赖下载失败的包优先看 Maven 镜像源是否配置在settings.xml里加阿里云镜像再重新执行。然后验证接口是否正常响应curl -X POST http://localhost:8080/login \ -H Content-Type: application/json \ -d {username:admin,password:admin123}返回一段带 token 的 JSON 就说明后端活了。浏览器访问http://localhost:8080能看到登录页面说明整个链路打通。看到 404 不要慌检查前端静态资源是否在src/main/resources/static下这个包如果是前后端分离项目还需要另外启动 Vue 静态服务但那属于另一个流程了。4. 公文流转核心实现工作流引擎与节点跳转逻辑跑通之后源码最值得读的部分就是审批流的实现。公文流转和普通 CRUD 的区别全在这一层看懂了它你就掌握了改造整条审批链路的能力。4.1 流程定义BPMN 文件里藏着真正的审批链路打开src/main/resources/processes目录里面会有document_approval.bpmn或类似名称的文件。这个 XML 文件定义的节点直接对应公文里“拟稿→审核→会签→签发”的链路。看一个简化版本的定义process iddocumentProcess name公文发文审批流程 isExecutabletrue startEvent idstart name开始/ userTask idtask_draft name拟稿 activiti:assignee${draftUser}/ userTask idtask_dept_approve name部门审核 activiti:assignee${deptManager}/ userTask idtask_office_review name办公室复核 activiti:assignee${officeUser}/ userTask idtask_leader_sign name分管领导签发 activiti:assignee${leaderUser}/ sequenceFlow idflow1 sourceRefstart targetReftask_draft/ sequenceFlow idflow2 sourceReftask_draft targetReftask_dept_approve/ sequenceFlow idflow3 sourceReftask_dept_approve targetReftask_office_review/ sequenceFlow idflow4 sourceReftask_office_review targetReftask_leader_sign/ endEvent idend name结束/ sequenceFlow idflow5 sourceReftask_leader_sign targetRefend/ /processactiviti:assignee用的是表达式写法${deptManager}来自提交审批时放入流程变量的用户 ID。顺流程的设计不算难难点全在驳回和撤回上。看源码时要多留意两件事是否有boundaryEvent边界事件来拦截超时未处理的任务。驳回到底是直接taskService.complete()结束当前任务后回到上一个节点还是用runtimeService.createChangeActivityStateBuilder()做跳转。大多数源码只做了最简单的驳回也就是设置ACTIVITI_SKIP_EXPRESSION_ENABLED或直接跳转到指定节点一旦你遇到“二级部门审核后要打回一级重新拟稿再走流程”这种需求就要自己改跳转逻辑了。4.2 审批操作任务处理与流程变量传递流程节点的流转是通过TaskService完成的。下面是源码中最常见的审批通过实现注意看变量的设置和任务的完成顺序Service public class WorkflowTaskService { private final TaskService taskService; private final RuntimeService runtimeService; public void approve(String taskId, String userId, String comment, MapString, Object vars) { // 记录审批意见到流程变量供后续节点和历史查询使用 vars.put(approver_ taskId, userId); vars.put(comment_ taskId, comment); // 设置当前节点的处理结果为“同意” taskService.setVariableLocal(taskId, approved, Boolean.TRUE); taskService.addComment(taskId, null, comment); // 完成任务引擎根据 BPMN 的 sequenceFlow 自动推送到下一节点 taskService.complete(taskId, vars); } public void reject(String taskId, String userId, String comment) { taskService.setVariableLocal(taskId, approved, Boolean.FALSE); taskService.addComment(taskId, null, comment); // 驳回的核心从历史节点中找到上一个 userTask Task task taskService.createTaskQuery().taskId(taskId).singleResult(); String processInstanceId task.getProcessInstanceId(); ListHistoricActivityInstance activities historyService .createHistoricActivityInstanceQuery() .processInstanceId(processInstanceId) .finished() .activityType(userTask) .orderByHistoricActivityInstanceEndTime().desc() .list(); // 找到最近一个非当前任务的 userTask跳回该节点 for (HistoricActivityInstance activity : activities) { if (!activity.getActivityId().equals(task.getTaskDefinitionKey())) { runtimeService.createChangeActivityStateBuilder() .processInstanceId(processInstanceId) .moveActivityIdTo(task.getTaskDefinitionKey(), activity.getActivityId()) .changeState(); break; } } taskService.complete(taskId); } }代码背后的逻辑要理解到位taskService.complete()并不是结束流程它只是告诉流程引擎“当前节点的活儿干完了”引擎根据 BPMN 文件里配好的sequenceFlow决定下一步走到哪个节点。所以同一套源码修改 BPMN 的流转路线就可以改变整个审批路径不需要改 Java 代码。驳回跳转有个隐蔽的问题跳回上一节点时流程变量approved已经变成false但原来的审批意见还在历史表里。正确的做法是在跳转前把当前节点的意见保存到act_hi_comment表上面代码中的addComment干的就是这件事否则查历史详情时只能看到同意记录看不到驳回理由。这也是源码里审批历史“缺一条驳回意见”的最常见原因。4.3 会签与分发公文系统不一样的坑公文流转里还有两类特殊任务会签和多级分发。会签是指办公室复核通过后需要同时发给多个部门负责人并联签署意见不是单纯串行走到下一节点。如果源码是简单用userTask串行表示的那就不是真会签只是一个顺序审批。打开 BPMN 看有没有activiti:assignee配多个候选人或multiInstanceLoopCharacteristics后者才是并行会签的正确实现userTask idtask_countersign name会签 activiti:assignee${assigneeList} multiInstanceLoopCharacteristics isSequentialfalse activiti:collection${countersignUserList} activiti:elementVariableassignee completionCondition${nrOfCompletedInstances nrOfInstances}/completionCondition /multiInstanceLoopCharacteristics /userTask这里的collection来自提交时传入的会签人 ID 列表completionCondition声明了会签结束条件。默认条件表示所有人签完才流转如果单位实际要求“过半同意就通过”可以把条件改成${nrOfCompletedInstances nrOfInstances / 2}。类似这种改造是公文系统二次开发里最常见的需求改动点都在 BPMN 和流程变量上不涉及 Java 代码。公文还有“分发”环节——签发后把文件自动推送给各科室阅读这通常不用 Activiti 实现而是业务代码在流程结束后往biz_document_read表里批量插入记录。源码里找到签发节点完成后的监听器ExecutionListener或SpringEventListener里面会有insertReadRecord的批量插入逻辑这个位置又是一个高频改造点需要按部门分组分发时改这个监听器里的查询条件。5. 部署到跑通5 个高频踩坑点与排查方法这不是“可能遇到”的问题而是我照着这类源码实际部署后真实踩过、也看别人反复踩的坑。按出现频率排序每一条都是现象原因解法。5.1 端口被占用导致启动直接失败现象执行mvn spring-boot:run后日志停在Web server failed to start. Port 8080 was already in use.整个应用起不来。原因服务器或本机已有其他程序占用 8080。最常见的是之前一个没杀掉的 Java 进程占了端口或者本机开了 Tomcat、Nginx 等 Web 服务。解决要么改端口要么杀进程。改端口最快编辑application.yml把server.port改成8081然后用新端口访问。杀进程的话 Linux 下执行lsof -i:8080 | grep java拿到 PID 后kill -9 PID。这里更推荐改端口因为很多路径和重定向的前缀是针对原端口的杀了旧进程不代表路径里面没写死 8080。5.2 数据库字符集不对公文标题在页面上全是问号现象登录进去后公文列表的中文标题显示成????数据库里查出来的也是乱码但系统启动不报错。原因建库时没有指定utf8mb4字符集或者 JDBC URL 里没带characterEncodingutf8。Activiti 引擎自动建的 25 张表默认沿用库的字符集库是 latin1表就是 latin1。解决不要在已有系统上改表字符集那是另一层麻烦。重建库最干净先备份数据还没数据的话不用备份然后CREATE DATABASE gongwen_db DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;重新导入 SQL再重启系统。5.3 Activiti 引擎表没有自动生成现象系统启动日志提示Could not update Activiti database schema或直接报Table act_ge_property doesnt exist。原因application.yml里spring.activiti.database-schema-update被设成了false或者没写导致引擎不自动建表。源码作者在开发环境跑通后经常忘了把配置写回代码里。解决检查配置文件确认database-schema-update: true。如果数据库里本来连act_ge_property都没有直接启动就会成功创建如果数据库里已经有不完整的act_表建议先 DROP 掉这批表再启动让引擎重新建旧的不完整表结构会让引擎误以为初始化已完成反而跳过了建表流程。5.4 改了 BPMN 文件流程还是走老逻辑现象在src/main/resources/processes里改完 BPMN 节点重启系统后申请公文走的新链路没生效自动跑的还是旧节点顺序。原因Activiti 启动时会自动部署processes目录下的 BPMN 文件但如果 BPMN 的id和版本没变引擎不会重新部署它会沿用历史表中已存在的同名流程定义。这是工作流引擎的版本机制不是你的代码没编译。解决改 BPMN 后同时把流程定义的id改一个名字比如documentProcess_v2或者使用repositoryService.createDeployment()在代码里手动部署并给个新版本号。更省事的办法把数据库里act_re_procdef表和act_re_deployment表中对应旧流程的行删掉重启后重新部署。要养成习惯——改 BPMN 前先看act_re_deployment表有没有已部署记录有就删掉再改。5.5 打包发布后 CPU 负载异常偏高或内存溢出现象本地 IDE 跑得好好的打成 jar 包放到服务器上运行后刚开始正常半小时后 CPU 飙到 100%或者OutOfMemoryError崩溃。原因这类源码大多没有做连接池调优。Activiti 的历史数据清理没有配置定时任务日志越攒越多同时 DBCP 或 HikariCP 在流量上来时会一直扩容连接数。解决如果不是正式上线本地部署阶段不用管。正式投入前务必在配置里加上几个参数HikariCP 的maximum-pool-size: 20、minimum-idle: 5启动参数加上-Xms512m -Xmx1024m数据库的act_hi_*历史表要定期清理源码里如果能找到一个HistoryCleanJob或定时任务就说用配置开启它找不到就在application.yml里加一个 Spring Scheduled 任务定期DELETE FROM act_hi_procinst WHERE END_TIME_ DATE_SUB(NOW(), INTERVAL 30 DAY)。6. 二次开发方向把通用审批流改造成本单位流程源码跑通只是开始真正值钱的是你能不能把它改成本单位的形态。基于常见的公文流转源码有三个方向性价比最高按实施难度从低到高排列。第一给表单里加联动字段。很多源码的公文表单是纯文本字段比如“紧急程度”下拉框选了“特急”后“要求完成时间”应该自动高亮或者必填。这个不用动流程引擎只用在前端 JS 里加联动判断后端加一个字段校验注解NotNull即可。定位到src/main/resources/static下的表单页面找到urgency相关的select元素给它的change事件挂一个回调函数。第二改审批意见的展示方式。源码默认在流程历史页用时间线方式列act_hi_comment的内容但公文场景要求按节点顺序展示“拟稿人意见、部门负责人意见、领导批示”。推荐做法是直接查act_hi_comment表并按TIME_排序或使用historyService.createHistoricActivityInstanceQuery()按节点聚合把每个节点的最后一条意见作为该节点的最终意见。这里有个习惯不要把审批意见塞到业务表biz_oa_document里否则每次回退、撤回都要同步更新业务表数据一致性很难维护。第三把串行审批改成可选节点的动态流程。公文单位一个高频需求是“不重要文件只需科室审核重要文件才需要领导签发”。改法是在 BPMN 里给“办公室复核”到“领导签发”之间加一条条件线在sequenceFlow上配conditionExpressionsequenceFlow idflow_special sourceReftask_office_review targetReftask_leader_sign conditionExpression xsi:typetFormalExpression ![CDATA[${needLeaderApprove true}]] /conditionExpression /sequenceFlow然后在提交公文的 Java 代码里根据文件密级或紧急程度往流程变量里放needLeaderApprove。这样系统就能自己判断走哪条分支不再每份公文都走满 4 个节点。这个改法对硬编码状态机的源码无效但对带 Activiti 的源码就是改 BPMN 一个变量的事情。我做这类源码改造有一年多的经验最大的一个体会是别急着动流程引擎的 Java 代码先跑通、再读 BPMN、最后改变量。流程定义文件是源码包里的“后悔药”改 Java 代码容易改出副作用改 BPMN 最多就是流程走错一个节点回滚成本低得多。希望这篇笔记帮你在拿到 Java 公文流转系统源码.zip 后少走几条弯路。本文还有配套的精品资源点击获取