1. 项目概述与需求拆解1.1 智慧乡村治理到底在解决什么问题这两年做基层政务类项目的机会比前几年多了不少其中“智慧乡村治理平台”是很有代表性的一个方向。我做这个项目时最早接触到的需求其实特别朴素村里要填报各种台账、上传巡查记录、统计人口信息、处理村民上报的问题全靠微信群和Excel来回传。乡一级汇总数据的时候各村发的表格格式不一汇总工作量大数据也经常对不上。所以这个项目的核心并不是“造一个多先进的东西”而是把乡村治理中最琐碎、最耗人力、最容易出错的环节搬到线上让数据走系统、流程可追踪、结果能统计。整个平台围绕四个维度展开人村民、网格员、村两委成员、事事件上报、任务分派、流转处理、物房屋、设施、公共资源、组织村、乡两级管理架构。从技术角度看这其实是一个典型的企业级Web应用核心在于权限控制严密、数据隔离清晰、业务流程完整。我选择Spring Boot作为基础框架主要是看中它生态成熟、起步快团队招人也好招。项目采用前后端分离架构后端以Spring Boot为核心前端使用Vue生态的现成框架整个团队在两个月内完成了核心版本。1.2 模块划分与业务边界接手需求后我没有急着写代码而是先花了一周时间和业务方一起梳理模块边界。最终我们把平台划分为六个核心模块村民管理包括户籍人口、常住人口、流动人口的基础信息维护支持Excel导入导出、标签化管理。事件上报与处置村民或网格员发现问题后发起事件系统按规则分派给对应负责人处理完成需提交佐证材料和办结说明。网格化治理把村域按网格划分每个网格绑定网格员支持网格巡查、签到打卡、问题发现记录。村务管理公告发布、议事投票、三务公开内容归类不做过度扩展系统只做数据支撑和展示、村务档案存储。任务督办乡级管理员可下发任务到村村再细分到人全流程限时督办、到期提醒。数据统计看板面向乡级管理者的统计报表包括事件处置率、巡查覆盖率、人口数据汇总等。模块划分清楚了后端微服务的边界也就清楚了。考虑到项目规模不大我没有拆微服务而是采用单应用多模块的方式组织代码。这一点后面细讲。2. 技术选型与系统架构设计2.1 为什么选择 Spring Boot 这套生态现在做这类管理平台可选的技术栈很多。Go的Gin、Python的Django/Flask、Node的NestJS都可以做但我在这个项目里还是选了Spring Boot理由有三点第一生态完整权限、事务、缓存、消息都有成熟方案。Spring Security加上JWT做认证授权MyBatis-Plus做数据访问Redis做缓存和分布式锁这些组件组合起来非常顺手不需要自己造轮子。第二对业务方后续的二次开发和维护更友好。乡村治理平台的实际使用者往往会在运行过程中不断提新需求Java生态的稳定性和可维护性更好团队接手成本低。第三部署和运维方式简单。打成一个jar包放到服务器上就能跑配合Nginx做反向代理没有复杂的环境依赖。我选用的核心组件版本组合如下组件选型用途说明基础框架Spring Boot 2.7.x项目基石自动配置减少重复工作数据访问MyBatis-Plus 3.5.x单表CRUD不用手写SQL复杂查询用XML数据库MySQL 8.0稳定可靠免费也好用缓存Redis 6.x会话缓存、热点数据、定时任务锁认证授权Spring Security JWT无状态认证适配前后端分离接口文档Knife4j自动生成Swagger文档方便前后端联调工具库Hutool日期、文件、加密等常用工具集合2.2 整体架构与包结构规划系统采用前后端分离架构。后端只提供RESTful API前端是一个独立的Vue项目。这样做的好处是前后端可以并行开发我这边专注接口逻辑前端同事专注页面交互。后端代码按功能模块分层而不是按技术层分。这一点是我比较坚持的。很多项目喜欢建一堆controller、service、mapper包然后把所有模块的类都混在一起前期看着整齐后期改起来非常痛苦。我采用的包结构如下com.rural.platform ├── common # 通用工具类、统一返回结果、异常处理 ├── config # 配置类拦截器、CORS、MyBatis-Plus配置等 ├── security # 认证授权相关JWT过滤器、登录逻辑、权限注解 ├── module │ ├── person # 村民管理模块 │ ├── event # 事件处理模块 │ ├── grid # 网格化管理模块 │ ├── village # 村务管理模块 │ ├── task # 任务督办模块 │ └── statistics # 数据统计模块 │ ├── controller │ ├── service │ ├── mapper │ ├── entity │ └── dto └── RuralApplication.java每个模块内部按controller、service、mapper、entity、dto分层。模块之间的依赖通过service接口调用避免直接跨模块访问Mapper。比如事件模块需要读取网格信息时通过GridModuleService提供的方法获取而不是直接操作grid表。这样虽然多写了几行代码但模块边界清晰后期维护省心得多。2.3 数据库建模思路数据库设计是整个项目的地基。我建模的时候遵循几个原则业务状态用数值字典表示、关键操作记录留痕、多对多关系必须有中间表、大字段单独拆表存储。核心表设计包括villager_info村民基本信息表包含姓名、身份证号、联系方式、户籍类型、政治面貌、家庭地址等字段。身份证号做唯一索引但存储时加密处理。grid_info网格信息表包含网格名称、所属村、网格员ID、管理范围描述。event_info事件信息表包含事件标题、描述、类型、紧急程度、状态、上报人ID、网格ID、处理人ID、处理结果、佐证材料URL列表。event_flow事件流转记录表记录每一次状态变更的操作人、操作时间、操作内容方便追溯。task_info任务表包含任务标题、内容、下发人、接收单位、截止时间、办理状态。village_notice村务公告表包含标题、内容、发布人、发布时间、附件列表。sys_user系统用户表登录账号、密码盐值、关联人员ID、账号状态。sys_role、sys_user_role角色和用户角色关联表。设计时有个细节值得说事件流转记录表是后来补上的。最初设计只有event_info表里的status字段但业务方提出要能看到每个事件的完整办理过程谁在什么时候做了什么操作。加了event_flow表之后不但满足了追溯需求数据统计分析也更好做了。3. 核心功能模块实现3.1 用户认证与权限控制的实现细节这个平台涉及乡、村两级用户权限区分得很细。我用Spring Security加JWT做认证用自定义注解做权限校验。登录流程是标准的用户名密码校验前端请求验证码接口获取图片验证码登录时携带账号、密码和验证码标识。后端校验验证码通过后查库确认账号密码正确生成JWT返回给前端。JWT里只放了用户ID和角色标识其余用户信息每次从Redis缓存中取避免JWT过大。权限控制做了两级第一级是接口级别的访问控制。使用PreAuthorize注解配合自定义权限表达式比如PreAuthorize(authService.checkPermission(village:notice:publish)) PostMapping(/notice) public ResultVoid publishNotice(RequestBody NoticeDTO dto) { // 发布公告逻辑 }这里的authService会在运行时从Redis中加载当前用户的权限标识集合判断是否包含village:notice:publish这个权限点。不通过就直接抛异常由全局异常处理器返回403。第二级是数据级别的权限隔离。乡级用户可以看全乡数据村级用户只能看本村数据。这个没法用注解解决我封装了一个数据权限工具类。在查询时通过ThreadLocal拿到当前登录用户的归属村ID动态拼接到SQL条件里。比如事件列表查询时QueryWrapperEventInfo wrapper new QueryWrapper(); wrapper.eq(hasRole(admin) ? county_id : village_id, currentVillageId());这个方案简单有效但有一个前提查询必须走统一的Service入口不能在Mapper里另起炉灶写自定义SQL绕过权限拼接。我在代码评审时专门强调过这一点也通过代码扫描工具检查自定义SQL里是否都带了village_id条件。3.2 事件上报与处置流程的实现事件处理是平台使用频率最高的功能也是业务流程最复杂的部分。我得花点篇幅讲讲设计过程和踩过的坑。事件状态我定义了五档待分派PENDING、处理中PROCESSING、待验收VERIFYING、已完成FINISHED、已驳回REJECTED。村民上报或者网格员巡查发现的事件初始状态为待分派。分派逻辑有两种模式自动分派和手动分派。自动分派针对有明确类型的紧急事件通过事件类型和网格的映射关系直接找到对应网格员。手动分派适用于复杂事件由村级管理员指定处理人。关键代码片段如下Transactional(rollbackFor Exception.class) public void dispatchEvent(Long eventId, Long handlerId, String comment) { EventInfo event eventMapper.selectById(eventId); if (event null || !Status.PENDING.equals(event.getStatus())) { throw new BizException(事件不存在或状态不允许分派); } // 更新事件主表 event.setHandlerId(handlerId); event.setStatus(Status.PROCESSING.getValue()); event.setDispatchTime(LocalDateTime.now()); eventMapper.updateById(event); // 写入流转记录 EventFlow flow new EventFlow(); flow.setEventId(eventId); flow.setFromStatus(Status.PENDING.getValue()); flow.setToStatus(Status.PROCESSING.getValue()); flow.setOperatorId(getCurrentUserId()); flow.setComment(comment); flow.setCreateTime(LocalDateTime.now()); eventFlowMapper.insert(flow); }这里加了Transactional注解保证主表更新和流转记录写入在同一个事务里不会出现状态改了但记录没写的情况。处理完成时处理人需要填写办理说明并上传佐证材料照片或PDF。上传文件用的是本地磁盘存储路径规则是/data/rural-platform/files/yyyy/MM/dd/xxx.jpg访问通过Nginx映射静态路径。文件URL存在event_info的attachment字段里用逗号分隔。3.3 网格化治理模块的实现网格化治理听起来像是一个简单的人员管理功能实际做起来牵扯的东西不少。网格不仅仅是划片还牵涉到网格员、房屋、人口之间的关联关系。每个村划分若干网格如下图逻辑村包含网格网格绑定网格员网格员负责网格内所有事务。一个网格员可以绑定多个网格但一个网格只能有一个主责网格员。这个模块的核心功能是巡查任务管理。乡村治理有明确的巡查要求比如每天巡查多少户、发现隐患要上报等。系统的做法是乡级管理员配置巡查计划系统每天按计划自动生成巡查任务分派给对应的网格员。自动生成任务用Spring的Scheduled定时任务实现Component public class PatrolTaskGenerator { Scheduled(cron 0 30 7 * * ?) public void generateDailyTasks() { ListGridInfo grids gridService.listAllWithManager(); for (GridInfo grid : grids) { if (!patrolTaskService.hasTaskToday(grid.getId())) { createTaskForGrid(grid); } } } }这里有个细节如果直接遍历网格生成任务网格数量多的时候没问题但万一某个网格员的网格重复绑定就可能生成重复任务。所以我在生成前先查一下当天是否已经有任务避免重复。同时生成逻辑不是单线程直接跑完而是分批创建防止数据量大时造成数据库压力。巡查时网格员在移动端操作上报问题或者记录巡查结果。后端就是常规的增删改查接口比较有技术含量的是经纬度位置记录网格员在巡查打卡时上传当前位置后端校验位置是否在网格范围内。我用的是射线法判断点是否在多边形内把网格边界坐标存到数据库的JSON字段里。public static boolean isPointInPolygon(Point p, ListPoint polygon) { boolean inside false; int n polygon.size(); for (int i 0, j n - 1; i n; j i) { Point pi polygon.get(i); Point pj polygon.get(j); if (((pi.getLat() p.getLat()) ! (pj.getLat() p.getLat())) (p.getLng() (pj.getLng() - pi.getLng()) * (p.getLat() - pi.getLat()) / (pj.getLat() - pi.getLat()) pi.getLng())) { inside !inside; } } return inside; }这个方法网上资料很多但真正落地时需要处理边界点和坐标转换的问题。我们实际用的是高德地图的坐标体系数据库里存的也是同一体系的坐标所以不需要做坐标转换。但如果不同来源的坐标混用一定要统一坐标体系否则判断结果会差出几十米甚至更多。3.4 数据统计与可视化平台面向乡级管理者的统计看板主要展示几类数据事件处置情况、巡查任务完成情况、人口数据汇总、任务督办进度。这些统计报表如果每次都实时查数据库查询会很慢。我的做法是建了一张统计中间表每天凌晨通过定时任务跑批把前一天的各类汇总数据计算好存入中间表。页面展示时直接查中间表时间复杂度从O(n)降到O(1)。定时任务的实现Scheduled(cron 0 15 1 * * ?) public void refreshStatistics() { // 事件统计 ListEventStatRow eventStats eventService.countEventByVillageAndType(); // 巡查统计 ListPatrolStatRow patrolStats patrolService.countPatrolByGrid(); // 写入统计表前先清空旧数据 statisticsMapper.deleteAll(); statisticsMapper.batchInsert(eventStats); statisticsMapper.batchInsert(patrolStats); }跑批任务有两个注意点一是要避免清空数据后、写新数据前这段时间页面查到空数据所以我用了先写入临时表再替换的方式二是定时任务要加分布式锁虽然单机部署时不担心但后面如果扩成多实例就必须用Redis的SETNX做分布式锁防止多个实例同时跑批。图表数据接口返回给前端的是聚合后的JSON类似{ date: 2024-05-01, count: 26 }这种结构。前端直接用ECharts渲染柱状图和折线图不需要做额外加工。4. 关键技术难点与应对方案4.1 村民Excel导入导出功能的实现乡村治理系统最不缺的就是数据导入导出功能尤其村民信息表动不动就是几千上万条数据。这个功能我最初用EasyExcel做开发很快但遇到两个问题。第一个问题是数据校验。Excel里的身份证号经常出现格式问题比如长度不对、校验位错误、甚至包含特殊字符。我在导入时做了逐行校验错误信息要精确到行号和列名方便业务人员修正后重新导入。校验逻辑放在导入服务里public ImportResult importVillagers(MultipartFile file) { ListVillagerImportRow rows EasyExcel.read(file.getInputStream()) .head(VillagerImportRow.class) .sheet() .doReadSync(); ListString errors new ArrayList(); for (int i 0; i rows.size(); i) { VillagerImportRow row rows.get(i); String error validateRow(row); if (error ! null) { errors.add(第 (i 2) 行: error); } } if (!errors.isEmpty()) { return ImportResult.fail(errors); } // 批量插入分批执行 for (int i 0; i rows.size(); i 500) { int end Math.min(i 500, rows.size()); villagerMapper.batchInsert(rows.subList(i, end)); } return ImportResult.success(rows.size()); }第二个问题是导入的性能。一次性插入上万条数据到MySQL如果用单条insert语句跑起来很慢。我改成MyBatis的批量插入每次500条实测一万条数据导入加校验大约在三秒内完成可以接受。导出功能我是分页查询再写入Excel避免一次性加载全部数据把内存撑爆。EasyExcel支持流式写也就是边查边写数据量大时内存占用稳定。4.2 附件上传与文件管理事件处理中涉及的现场照片、村务公开的文件材料都需要上传和下载。这个功能初期我用了最简单的实现方案后来踩了坑才逐步完善。初期方案是把文件直接存到项目目录下upload/文件夹数据库存相对路径。上线后发现两个问题第一项目通过jar包部署后upload目录在jar包外的同级目录路径写死了迁移服务器时很容易漏拷文件第二Nginx配置不当导致用户无法直接通过URL访问图片。改进后的方案是文件存储目录统一为/data/rural-platform/files在application.yml里配置成参数部署时通过环境变量注入。Nginx配置静态资源映射location /files/ { alias /data/rural-platform/files/; expires 7d; }上传接口设计为单文件接口返回文件的相对访问路径。前端拿到路径后拼上服务的baseUrl就能直接展示图片。文件类型上我在后端校验了扩展名和MIME类型配合Apache Tika做内容级别的类型识别防止恶意上传伪装成图片的可执行文件。数据库里存的是相对路径而不是完整URL这样做的好处是如果域名或IP变了无需改数据库。这个细节在处理政务类项目时尤其重要因为部署环境经常变化。4.3 事务一致性与并发控制乡村治理平台上有个典型的高并发场景同一时间大量数据上报时多个事务并发操作同一表记录。最典型的例子是事件分派和村民信息更新。分派事件的场景中同一个事件被两个管理员同时分派理论上只允许一个人成功。我需要保证操作是原子的。用事务加状态判断可以解决大部分问题但极端并发下可能会出现“先查出状态为待分派、两个事务同时更新成功”的情况这就要用到乐观锁。我用的方案是在event_info表加了一个version字段更新时带上版本号Update(UPDATE event_info SET status #{status}, version version 1 WHERE id #{id} AND version #{version}) int updateStatusWithVersion(EventInfo event);更新返回0说明版本冲突说明别人已经改了这条记录当前操作需要重新加载数据再决定是否继续。这个方案相比悲观锁SELECT FOR UPDATE更适合读多写少的场景不会长时间锁住记录。另外任务督办中的限时功能用了Redis的过期键。任务分派时在Redis设置一个带TTL的key到达截止时间后自动触发回调更新任务状态为超时。这个方案避免了定时扫描数据库带来的延迟和压力。如果怕Redis数据丢失可以在应用启动时做一次补偿扫描把截止时间已过但状态未更新的任务批量修正。5. 常见问题排查与避坑实录5.1 数据库连接池配置不当导致服务假死系统上线运行一周后突然出现接口响应极慢的情况部分请求直接超时。查了日志发现大量等待获取数据库连接的警告Druid连接池的active count长期等于max active。排查过程先看慢SQL日志发现没有明显慢查询再看数据库CPU使用率也不算高最后定位到是连接池泄漏。原因是代码中有一个查询操作使用了线程池并发查询但部分子线程抛出异常后连接没有归还到连接池。我加了Spring的异常处理和连接泄漏检测机制Druid开启了removeAbandoned配置spring: datasource: druid: max-active: 50 min-idle: 10 remove-abandoned: true remove-abandoned-timeout: 180这个配置让超过3分钟没有归还的物理连接被强制回收。同时我排查了代码里的异常分支把所有查询操作都收拢到统一的查询代理里用try-finally确保连接归还。这个坑给我的教训是不要嫌Druid配置项多生产环境一定要把所有超时和回收机制都打开连接池泄漏是Java后端最常见的隐形杀手之一。5.2 定时任务重复执行系统部署到测试环境时部署了两个实例做负载均衡。结果发现每天凌晨的统计任务被重复执行了两次。原因很简单没有分布式锁多个实例同时触发定时任务。我用Redis的SETNX加锁锁的KEY是任务名称VALUE是实例ID加上时间戳过期时间设为任务执行的最大耗时加缓冲String lockKey task:refresh-statistics; String requestId UUID.randomUUID().toString(); Boolean locked redisTemplate.opsForValue() .setIfAbsent(lockKey, requestId, 10, TimeUnit.MINUTES); if (Boolean.TRUE.equals(locked)) { try { refreshStatistics(); } finally { String lockValue (String) redisTemplate.opsForValue().get(lockKey); if (requestId.equals(lockValue)) { redisTemplate.delete(lockKey); } } }删除锁时先判断值是不是自己的避免误删别人的锁。这个判断和删除两个操作我用Lua脚本保证原子性。如果不用Lua理论上会出现删掉别人新持有的锁的极端情况。5.3 前后端联调时的跨域与Token问题项目前后端分离开发环境下前端跑在8080端口后端跑在9090端口跨域是必然的。我配置了CORS过滤器允许所有来源访问但上线前发现Mock接口在联调时经常出现无法获取Token的情况。排查发现两个问题一个是对携带Token的预检请求OPTIONS没有放行Spring Security拦掉了另一个是前端发请求时Token没被正确放到Authorization头里因为前端配置拦截器时漏了某些请求类型。解决方案是手动处理预检请求并在调用JWT过滤器的逻辑中判断是否为OPTIONS请求是的话直接放行。JWT过滤器我设置了自定义的异常路径在Token过期、签名错误时返回不同的错误码前端可以根据错误码决定是刷新Token还是跳转到登录页。Override protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain chain) throws IOException, ServletException { if (request.getMethod().equalsIgnoreCase(OPTIONS)) { chain.doFilter(request, response); return; } String token resolveToken(request); if (StringUtils.hasText(token) jwtTokenProvider.validateToken(token)) { Authentication auth jwtTokenProvider.getAuthentication(token); SecurityContextHolder.getContext().setAuthentication(auth); } chain.doFilter(request, response); }这里还有个容易忽略的点JWT的有效期不宜太长政务类系统建议两小时左右。为了用户体验我实现了刷新Token机制前端发现Token还剩10分钟到期时调用refresh接口换取新Token服务端用Redis存储refreshToken过期时间设为7天。6. 权限模型设计与数据隔离6.1 基于RBAC的权限模型这个系统的用户角色比较复杂有乡级管理员、乡级业务人员、村级管理员、网格员、普通村民每种角色的权限范围差异很大。我采用RBAC基于角色的访问控制模型没搞更复杂的ABAC模型因为RBAC已经能覆盖需求而且容易理解、容易维护。数据库设计了四张表用户表、角色表、权限表、用户角色关联表。权限点按模块和操作维度划分统一编码格式为模块:操作比如person:add (新增村民)event:dispatch (分派事件)event:finish (办结事件)grid:patrol (执行巡查)statistics:view (查看统计)功能权限通过Spring Security注解实现接口级控制角色和权限点的映射关系存在数据库里。超级管理员乡级管理员默认拥有所有权限直接在代码里判断角色类型即可。6.2 数据隔离的实用方案功能权限管的是“能不能做”数据权限管的是“能看哪些数据”。数据隔离分为两种情况第一种是村级隔离。村级管理员和网格员只能操作本村数据。这个在大多数查询接口中通过动态拼接village_id条件实现。第二种是网格级隔离。网格员只能看到自己网格内的数据比村级更细。我在查询事件列表时如果当前登录用户是网格员角色就额外拼上grid_id条件。网格员默认是绑定一个网格还是一组网格用的是IN条件。if (isGridUser()) { ListLong gridIds getCurrentUserGridIds(); wrapper.in(grid_id, gridIds); } else if (isVillageAdmin()) { wrapper.eq(village_id, getCurrentVillageId()); }这套数据隔离方案在初版上线时没有任何问题但随着数据量增长页面出现了一个新问题组合查询时如果用户手动选择了其他条件比如查全部已办结事件拼SQL的顺序会导致条件渲染错误页面显示的数据超出了应有的范围。我最后换了思路把数据权限从Service层下沉到统一的查询拦截器里用MyBatis-Plus的拦截器机制自动追加条件不再依赖业务代码的自觉性。这个改动也对后续开发提了个要求新写的SQL必须走统一查询封装不能随意拼原生SQL。7. 部署上线与运行维护经验7.1 构建打包与环境配置项目使用Maven构建打包命令很简单mvn clean package -DskipTests。产物是一个可执行的jar包大约120MB左右包含了所有依赖。配置管理是这类项目的关键。我用了Spring Boot的多环境配置application-dev.yml、application-test.yml、application-prod.yml公共配置放在application.yml。部署时通过启动参数指定环境java -jar rural-platform.jar --spring.profiles.activeprod数据库密码、Redis密码这些敏感配置不在配置文件里写死而是通过环境变量注入。启动脚本里从环境变量取值传给Spring Bootexport DB_PASSWORD${DB_PASSWORD} java -jar rural-platform.jar --spring.profiles.activeprod \ --spring.datasource.password${DB_PASSWORD}政务类项目对数据安全要求较高我还在备份策略上做了补充。每天凌晨通过系统cron执行MySQL逻辑备份备份文件保留30天每月一次全量备份到另一台机器。7.2 线上性能调优项目上线后我做了几轮性能优化。第一轮是SQL优化。通过慢查询日志发现事件列表查询在数据量过万后明显变慢。原查询带了好几个OR条件MySQL优化器选择了全表扫描。解决方法是重写查询逻辑把OR条件拆成UNION ALL并加上联合索引。事件表加了两组索引一个是对village_idstatus的组合索引另一个是对handler_idstatus的组合索引。第二轮是缓存优化。村务公告、办事指南这类低频变更的数据用了Redis做缓存缓存失效时间设为5分钟。热点数据查询比如统计看板直接读中间表不再实时计算。第三轮是数据库连接池优化。将Druid的max-active从默认的20调到了50同时设置了连接空闲超时时间。调完后测试环境的并发能力明显提升qps从200左右涨到了350以上。还有一点提醒别忽略JVM参数。默认的JVM堆大小是物理内存的四分之一如果服务器内存是8G堆就只有2G跑不了多少数据。我把生产环境的JVM参数设为-Xms2g -Xmx4g -Xmn1g根据实际流量调整效果不错。8. 一些用过的工具和团队协作心得这个项目的完整生命周期里除了编码还牵扯文档、接口管理、测试和代码审查。我在下面整理几张协作工具清单给准备做同类项目的人一个参考。环节使用方案作用接口文档Knife4j 后端Swagger注解自动生成接口文档前端可以直接在线调试需求管理在线思维导图加表格拆解页面字段、接口字段和业务规则代码协作Git分支管理每个迭代一个feature分支合并前代码审查部署管理shell脚本一键构建、上传、重启减少人工误差问题追踪自建在线问卷表格记录Bug、复现步骤、修复版本Knife4j是我特别想推荐的。前后端联调时前端人员可以直接在文档页调试接口不需要后端手动导出接口说明。把Swagger的注解写好文档质量直接决定了联调效率。我在Controller上把所有参数都加了example示例值前端复制JSON时不用猜格式。代码评审这块我坚持每个合并请求至少由另一名开发者审查。审查重点看三件事SQL是否会走索引、事务是否有回滚边界、数据权限条件是否完整。这三类问题靠测试很难发现但代码评审很容易抓到。9. 写在最后的实际体会这个项目从需求调研到正式上线前后花了大概三个月。回头总结最深的体会是技术选型永远不是这类项目最难的地方真正难的是把业务逻辑理清楚、把数据边界划明白、把权限体系设计得不留死角。早期我急于搭建代码骨架先把CRUD接口都写好了才补权限和数据隔离逻辑结果返工了不少。如果再来一次我一定先做权限模型和数据字典的设计再动手写业务代码。纸上谈兵听起来浪费时间实际上能省掉后面大量的改bug时间。还有一点想和做类似项目的同行说政务类系统的需求变更非常频繁。上线后不到两个月业务方就提出了十几个优化项比如事件类型自定义、网格拆分功能、多级审核流程。所以代码里尽量保留扩展点表和字段设计时不要过度压缩留出冗余。轻松一点写代码以后维护时真的会感谢自己当初多留的那几个字段。如果要我给新接手类似项目的人一条最具体的建议那就是别把Excel导入导出当小功能处理。乡村治理类系统中大量的历史数据都要通过Excel迁移进系统导入的校验逻辑、错误提示、性能表现直接决定了业务方对系统的第一印象。我亲眼见过一个系统因为导入5000条数据超时被业务方拒绝使用的例子。数据迁移的体验做不好后面功能再完善也很难扭转印象。这个平台后续我打算接入更细化的移动端巡查能力把网格员的日常工作进一步数字化。项目能做扎实靠的还是把每个基础功能的细节吃透这比追求新技术栈有用得多。 
长河君 · 2026/10/13 20:04:02 · 阅读 1.2k 基于Spring Boot的智慧乡村治理平台设计与实践
1. 项目概述与需求拆解1.1 智慧乡村治理到底在解决什么问题这两年做基层政务类项目的机会比前几年多了不少其中“智慧乡村治理平台”是很有代表性的一个方向。我做这个项目时最早接触到的需求其实特别朴素村里要填报各种台账、上传巡查记录、统计人口信息、处理村民上报的问题全靠微信群和Excel来回传。乡一级汇总数据的时候各村发的表格格式不一汇总工作量大数据也经常对不上。所以这个项目的核心并不是“造一个多先进的东西”而是把乡村治理中最琐碎、最耗人力、最容易出错的环节搬到线上让数据走系统、流程可追踪、结果能统计。整个平台围绕四个维度展开人村民、网格员、村两委成员、事事件上报、任务分派、流转处理、物房屋、设施、公共资源、组织村、乡两级管理架构。从技术角度看这其实是一个典型的企业级Web应用核心在于权限控制严密、数据隔离清晰、业务流程完整。我选择Spring Boot作为基础框架主要是看中它生态成熟、起步快团队招人也好招。项目采用前后端分离架构后端以Spring Boot为核心前端使用Vue生态的现成框架整个团队在两个月内完成了核心版本。1.2 模块划分与业务边界接手需求后我没有急着写代码而是先花了一周时间和业务方一起梳理模块边界。最终我们把平台划分为六个核心模块村民管理包括户籍人口、常住人口、流动人口的基础信息维护支持Excel导入导出、标签化管理。事件上报与处置村民或网格员发现问题后发起事件系统按规则分派给对应负责人处理完成需提交佐证材料和办结说明。网格化治理把村域按网格划分每个网格绑定网格员支持网格巡查、签到打卡、问题发现记录。村务管理公告发布、议事投票、三务公开内容归类不做过度扩展系统只做数据支撑和展示、村务档案存储。任务督办乡级管理员可下发任务到村村再细分到人全流程限时督办、到期提醒。数据统计看板面向乡级管理者的统计报表包括事件处置率、巡查覆盖率、人口数据汇总等。模块划分清楚了后端微服务的边界也就清楚了。考虑到项目规模不大我没有拆微服务而是采用单应用多模块的方式组织代码。这一点后面细讲。2. 技术选型与系统架构设计2.1 为什么选择 Spring Boot 这套生态现在做这类管理平台可选的技术栈很多。Go的Gin、Python的Django/Flask、Node的NestJS都可以做但我在这个项目里还是选了Spring Boot理由有三点第一生态完整权限、事务、缓存、消息都有成熟方案。Spring Security加上JWT做认证授权MyBatis-Plus做数据访问Redis做缓存和分布式锁这些组件组合起来非常顺手不需要自己造轮子。第二对业务方后续的二次开发和维护更友好。乡村治理平台的实际使用者往往会在运行过程中不断提新需求Java生态的稳定性和可维护性更好团队接手成本低。第三部署和运维方式简单。打成一个jar包放到服务器上就能跑配合Nginx做反向代理没有复杂的环境依赖。我选用的核心组件版本组合如下组件选型用途说明基础框架Spring Boot 2.7.x项目基石自动配置减少重复工作数据访问MyBatis-Plus 3.5.x单表CRUD不用手写SQL复杂查询用XML数据库MySQL 8.0稳定可靠免费也好用缓存Redis 6.x会话缓存、热点数据、定时任务锁认证授权Spring Security JWT无状态认证适配前后端分离接口文档Knife4j自动生成Swagger文档方便前后端联调工具库Hutool日期、文件、加密等常用工具集合2.2 整体架构与包结构规划系统采用前后端分离架构。后端只提供RESTful API前端是一个独立的Vue项目。这样做的好处是前后端可以并行开发我这边专注接口逻辑前端同事专注页面交互。后端代码按功能模块分层而不是按技术层分。这一点是我比较坚持的。很多项目喜欢建一堆controller、service、mapper包然后把所有模块的类都混在一起前期看着整齐后期改起来非常痛苦。我采用的包结构如下com.rural.platform ├── common # 通用工具类、统一返回结果、异常处理 ├── config # 配置类拦截器、CORS、MyBatis-Plus配置等 ├── security # 认证授权相关JWT过滤器、登录逻辑、权限注解 ├── module │ ├── person # 村民管理模块 │ ├── event # 事件处理模块 │ ├── grid # 网格化管理模块 │ ├── village # 村务管理模块 │ ├── task # 任务督办模块 │ └── statistics # 数据统计模块 │ ├── controller │ ├── service │ ├── mapper │ ├── entity │ └── dto └── RuralApplication.java每个模块内部按controller、service、mapper、entity、dto分层。模块之间的依赖通过service接口调用避免直接跨模块访问Mapper。比如事件模块需要读取网格信息时通过GridModuleService提供的方法获取而不是直接操作grid表。这样虽然多写了几行代码但模块边界清晰后期维护省心得多。2.3 数据库建模思路数据库设计是整个项目的地基。我建模的时候遵循几个原则业务状态用数值字典表示、关键操作记录留痕、多对多关系必须有中间表、大字段单独拆表存储。核心表设计包括villager_info村民基本信息表包含姓名、身份证号、联系方式、户籍类型、政治面貌、家庭地址等字段。身份证号做唯一索引但存储时加密处理。grid_info网格信息表包含网格名称、所属村、网格员ID、管理范围描述。event_info事件信息表包含事件标题、描述、类型、紧急程度、状态、上报人ID、网格ID、处理人ID、处理结果、佐证材料URL列表。event_flow事件流转记录表记录每一次状态变更的操作人、操作时间、操作内容方便追溯。task_info任务表包含任务标题、内容、下发人、接收单位、截止时间、办理状态。village_notice村务公告表包含标题、内容、发布人、发布时间、附件列表。sys_user系统用户表登录账号、密码盐值、关联人员ID、账号状态。sys_role、sys_user_role角色和用户角色关联表。设计时有个细节值得说事件流转记录表是后来补上的。最初设计只有event_info表里的status字段但业务方提出要能看到每个事件的完整办理过程谁在什么时候做了什么操作。加了event_flow表之后不但满足了追溯需求数据统计分析也更好做了。3. 核心功能模块实现3.1 用户认证与权限控制的实现细节这个平台涉及乡、村两级用户权限区分得很细。我用Spring Security加JWT做认证用自定义注解做权限校验。登录流程是标准的用户名密码校验前端请求验证码接口获取图片验证码登录时携带账号、密码和验证码标识。后端校验验证码通过后查库确认账号密码正确生成JWT返回给前端。JWT里只放了用户ID和角色标识其余用户信息每次从Redis缓存中取避免JWT过大。权限控制做了两级第一级是接口级别的访问控制。使用PreAuthorize注解配合自定义权限表达式比如PreAuthorize(authService.checkPermission(village:notice:publish)) PostMapping(/notice) public ResultVoid publishNotice(RequestBody NoticeDTO dto) { // 发布公告逻辑 }这里的authService会在运行时从Redis中加载当前用户的权限标识集合判断是否包含village:notice:publish这个权限点。不通过就直接抛异常由全局异常处理器返回403。第二级是数据级别的权限隔离。乡级用户可以看全乡数据村级用户只能看本村数据。这个没法用注解解决我封装了一个数据权限工具类。在查询时通过ThreadLocal拿到当前登录用户的归属村ID动态拼接到SQL条件里。比如事件列表查询时QueryWrapperEventInfo wrapper new QueryWrapper(); wrapper.eq(hasRole(admin) ? county_id : village_id, currentVillageId());这个方案简单有效但有一个前提查询必须走统一的Service入口不能在Mapper里另起炉灶写自定义SQL绕过权限拼接。我在代码评审时专门强调过这一点也通过代码扫描工具检查自定义SQL里是否都带了village_id条件。3.2 事件上报与处置流程的实现事件处理是平台使用频率最高的功能也是业务流程最复杂的部分。我得花点篇幅讲讲设计过程和踩过的坑。事件状态我定义了五档待分派PENDING、处理中PROCESSING、待验收VERIFYING、已完成FINISHED、已驳回REJECTED。村民上报或者网格员巡查发现的事件初始状态为待分派。分派逻辑有两种模式自动分派和手动分派。自动分派针对有明确类型的紧急事件通过事件类型和网格的映射关系直接找到对应网格员。手动分派适用于复杂事件由村级管理员指定处理人。关键代码片段如下Transactional(rollbackFor Exception.class) public void dispatchEvent(Long eventId, Long handlerId, String comment) { EventInfo event eventMapper.selectById(eventId); if (event null || !Status.PENDING.equals(event.getStatus())) { throw new BizException(事件不存在或状态不允许分派); } // 更新事件主表 event.setHandlerId(handlerId); event.setStatus(Status.PROCESSING.getValue()); event.setDispatchTime(LocalDateTime.now()); eventMapper.updateById(event); // 写入流转记录 EventFlow flow new EventFlow(); flow.setEventId(eventId); flow.setFromStatus(Status.PENDING.getValue()); flow.setToStatus(Status.PROCESSING.getValue()); flow.setOperatorId(getCurrentUserId()); flow.setComment(comment); flow.setCreateTime(LocalDateTime.now()); eventFlowMapper.insert(flow); }这里加了Transactional注解保证主表更新和流转记录写入在同一个事务里不会出现状态改了但记录没写的情况。处理完成时处理人需要填写办理说明并上传佐证材料照片或PDF。上传文件用的是本地磁盘存储路径规则是/data/rural-platform/files/yyyy/MM/dd/xxx.jpg访问通过Nginx映射静态路径。文件URL存在event_info的attachment字段里用逗号分隔。3.3 网格化治理模块的实现网格化治理听起来像是一个简单的人员管理功能实际做起来牵扯的东西不少。网格不仅仅是划片还牵涉到网格员、房屋、人口之间的关联关系。每个村划分若干网格如下图逻辑村包含网格网格绑定网格员网格员负责网格内所有事务。一个网格员可以绑定多个网格但一个网格只能有一个主责网格员。这个模块的核心功能是巡查任务管理。乡村治理有明确的巡查要求比如每天巡查多少户、发现隐患要上报等。系统的做法是乡级管理员配置巡查计划系统每天按计划自动生成巡查任务分派给对应的网格员。自动生成任务用Spring的Scheduled定时任务实现Component public class PatrolTaskGenerator { Scheduled(cron 0 30 7 * * ?) public void generateDailyTasks() { ListGridInfo grids gridService.listAllWithManager(); for (GridInfo grid : grids) { if (!patrolTaskService.hasTaskToday(grid.getId())) { createTaskForGrid(grid); } } } }这里有个细节如果直接遍历网格生成任务网格数量多的时候没问题但万一某个网格员的网格重复绑定就可能生成重复任务。所以我在生成前先查一下当天是否已经有任务避免重复。同时生成逻辑不是单线程直接跑完而是分批创建防止数据量大时造成数据库压力。巡查时网格员在移动端操作上报问题或者记录巡查结果。后端就是常规的增删改查接口比较有技术含量的是经纬度位置记录网格员在巡查打卡时上传当前位置后端校验位置是否在网格范围内。我用的是射线法判断点是否在多边形内把网格边界坐标存到数据库的JSON字段里。public static boolean isPointInPolygon(Point p, ListPoint polygon) { boolean inside false; int n polygon.size(); for (int i 0, j n - 1; i n; j i) { Point pi polygon.get(i); Point pj polygon.get(j); if (((pi.getLat() p.getLat()) ! (pj.getLat() p.getLat())) (p.getLng() (pj.getLng() - pi.getLng()) * (p.getLat() - pi.getLat()) / (pj.getLat() - pi.getLat()) pi.getLng())) { inside !inside; } } return inside; }这个方法网上资料很多但真正落地时需要处理边界点和坐标转换的问题。我们实际用的是高德地图的坐标体系数据库里存的也是同一体系的坐标所以不需要做坐标转换。但如果不同来源的坐标混用一定要统一坐标体系否则判断结果会差出几十米甚至更多。3.4 数据统计与可视化平台面向乡级管理者的统计看板主要展示几类数据事件处置情况、巡查任务完成情况、人口数据汇总、任务督办进度。这些统计报表如果每次都实时查数据库查询会很慢。我的做法是建了一张统计中间表每天凌晨通过定时任务跑批把前一天的各类汇总数据计算好存入中间表。页面展示时直接查中间表时间复杂度从O(n)降到O(1)。定时任务的实现Scheduled(cron 0 15 1 * * ?) public void refreshStatistics() { // 事件统计 ListEventStatRow eventStats eventService.countEventByVillageAndType(); // 巡查统计 ListPatrolStatRow patrolStats patrolService.countPatrolByGrid(); // 写入统计表前先清空旧数据 statisticsMapper.deleteAll(); statisticsMapper.batchInsert(eventStats); statisticsMapper.batchInsert(patrolStats); }跑批任务有两个注意点一是要避免清空数据后、写新数据前这段时间页面查到空数据所以我用了先写入临时表再替换的方式二是定时任务要加分布式锁虽然单机部署时不担心但后面如果扩成多实例就必须用Redis的SETNX做分布式锁防止多个实例同时跑批。图表数据接口返回给前端的是聚合后的JSON类似{ date: 2024-05-01, count: 26 }这种结构。前端直接用ECharts渲染柱状图和折线图不需要做额外加工。4. 关键技术难点与应对方案4.1 村民Excel导入导出功能的实现乡村治理系统最不缺的就是数据导入导出功能尤其村民信息表动不动就是几千上万条数据。这个功能我最初用EasyExcel做开发很快但遇到两个问题。第一个问题是数据校验。Excel里的身份证号经常出现格式问题比如长度不对、校验位错误、甚至包含特殊字符。我在导入时做了逐行校验错误信息要精确到行号和列名方便业务人员修正后重新导入。校验逻辑放在导入服务里public ImportResult importVillagers(MultipartFile file) { ListVillagerImportRow rows EasyExcel.read(file.getInputStream()) .head(VillagerImportRow.class) .sheet() .doReadSync(); ListString errors new ArrayList(); for (int i 0; i rows.size(); i) { VillagerImportRow row rows.get(i); String error validateRow(row); if (error ! null) { errors.add(第 (i 2) 行: error); } } if (!errors.isEmpty()) { return ImportResult.fail(errors); } // 批量插入分批执行 for (int i 0; i rows.size(); i 500) { int end Math.min(i 500, rows.size()); villagerMapper.batchInsert(rows.subList(i, end)); } return ImportResult.success(rows.size()); }第二个问题是导入的性能。一次性插入上万条数据到MySQL如果用单条insert语句跑起来很慢。我改成MyBatis的批量插入每次500条实测一万条数据导入加校验大约在三秒内完成可以接受。导出功能我是分页查询再写入Excel避免一次性加载全部数据把内存撑爆。EasyExcel支持流式写也就是边查边写数据量大时内存占用稳定。4.2 附件上传与文件管理事件处理中涉及的现场照片、村务公开的文件材料都需要上传和下载。这个功能初期我用了最简单的实现方案后来踩了坑才逐步完善。初期方案是把文件直接存到项目目录下upload/文件夹数据库存相对路径。上线后发现两个问题第一项目通过jar包部署后upload目录在jar包外的同级目录路径写死了迁移服务器时很容易漏拷文件第二Nginx配置不当导致用户无法直接通过URL访问图片。改进后的方案是文件存储目录统一为/data/rural-platform/files在application.yml里配置成参数部署时通过环境变量注入。Nginx配置静态资源映射location /files/ { alias /data/rural-platform/files/; expires 7d; }上传接口设计为单文件接口返回文件的相对访问路径。前端拿到路径后拼上服务的baseUrl就能直接展示图片。文件类型上我在后端校验了扩展名和MIME类型配合Apache Tika做内容级别的类型识别防止恶意上传伪装成图片的可执行文件。数据库里存的是相对路径而不是完整URL这样做的好处是如果域名或IP变了无需改数据库。这个细节在处理政务类项目时尤其重要因为部署环境经常变化。4.3 事务一致性与并发控制乡村治理平台上有个典型的高并发场景同一时间大量数据上报时多个事务并发操作同一表记录。最典型的例子是事件分派和村民信息更新。分派事件的场景中同一个事件被两个管理员同时分派理论上只允许一个人成功。我需要保证操作是原子的。用事务加状态判断可以解决大部分问题但极端并发下可能会出现“先查出状态为待分派、两个事务同时更新成功”的情况这就要用到乐观锁。我用的方案是在event_info表加了一个version字段更新时带上版本号Update(UPDATE event_info SET status #{status}, version version 1 WHERE id #{id} AND version #{version}) int updateStatusWithVersion(EventInfo event);更新返回0说明版本冲突说明别人已经改了这条记录当前操作需要重新加载数据再决定是否继续。这个方案相比悲观锁SELECT FOR UPDATE更适合读多写少的场景不会长时间锁住记录。另外任务督办中的限时功能用了Redis的过期键。任务分派时在Redis设置一个带TTL的key到达截止时间后自动触发回调更新任务状态为超时。这个方案避免了定时扫描数据库带来的延迟和压力。如果怕Redis数据丢失可以在应用启动时做一次补偿扫描把截止时间已过但状态未更新的任务批量修正。5. 常见问题排查与避坑实录5.1 数据库连接池配置不当导致服务假死系统上线运行一周后突然出现接口响应极慢的情况部分请求直接超时。查了日志发现大量等待获取数据库连接的警告Druid连接池的active count长期等于max active。排查过程先看慢SQL日志发现没有明显慢查询再看数据库CPU使用率也不算高最后定位到是连接池泄漏。原因是代码中有一个查询操作使用了线程池并发查询但部分子线程抛出异常后连接没有归还到连接池。我加了Spring的异常处理和连接泄漏检测机制Druid开启了removeAbandoned配置spring: datasource: druid: max-active: 50 min-idle: 10 remove-abandoned: true remove-abandoned-timeout: 180这个配置让超过3分钟没有归还的物理连接被强制回收。同时我排查了代码里的异常分支把所有查询操作都收拢到统一的查询代理里用try-finally确保连接归还。这个坑给我的教训是不要嫌Druid配置项多生产环境一定要把所有超时和回收机制都打开连接池泄漏是Java后端最常见的隐形杀手之一。5.2 定时任务重复执行系统部署到测试环境时部署了两个实例做负载均衡。结果发现每天凌晨的统计任务被重复执行了两次。原因很简单没有分布式锁多个实例同时触发定时任务。我用Redis的SETNX加锁锁的KEY是任务名称VALUE是实例ID加上时间戳过期时间设为任务执行的最大耗时加缓冲String lockKey task:refresh-statistics; String requestId UUID.randomUUID().toString(); Boolean locked redisTemplate.opsForValue() .setIfAbsent(lockKey, requestId, 10, TimeUnit.MINUTES); if (Boolean.TRUE.equals(locked)) { try { refreshStatistics(); } finally { String lockValue (String) redisTemplate.opsForValue().get(lockKey); if (requestId.equals(lockValue)) { redisTemplate.delete(lockKey); } } }删除锁时先判断值是不是自己的避免误删别人的锁。这个判断和删除两个操作我用Lua脚本保证原子性。如果不用Lua理论上会出现删掉别人新持有的锁的极端情况。5.3 前后端联调时的跨域与Token问题项目前后端分离开发环境下前端跑在8080端口后端跑在9090端口跨域是必然的。我配置了CORS过滤器允许所有来源访问但上线前发现Mock接口在联调时经常出现无法获取Token的情况。排查发现两个问题一个是对携带Token的预检请求OPTIONS没有放行Spring Security拦掉了另一个是前端发请求时Token没被正确放到Authorization头里因为前端配置拦截器时漏了某些请求类型。解决方案是手动处理预检请求并在调用JWT过滤器的逻辑中判断是否为OPTIONS请求是的话直接放行。JWT过滤器我设置了自定义的异常路径在Token过期、签名错误时返回不同的错误码前端可以根据错误码决定是刷新Token还是跳转到登录页。Override protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain chain) throws IOException, ServletException { if (request.getMethod().equalsIgnoreCase(OPTIONS)) { chain.doFilter(request, response); return; } String token resolveToken(request); if (StringUtils.hasText(token) jwtTokenProvider.validateToken(token)) { Authentication auth jwtTokenProvider.getAuthentication(token); SecurityContextHolder.getContext().setAuthentication(auth); } chain.doFilter(request, response); }这里还有个容易忽略的点JWT的有效期不宜太长政务类系统建议两小时左右。为了用户体验我实现了刷新Token机制前端发现Token还剩10分钟到期时调用refresh接口换取新Token服务端用Redis存储refreshToken过期时间设为7天。6. 权限模型设计与数据隔离6.1 基于RBAC的权限模型这个系统的用户角色比较复杂有乡级管理员、乡级业务人员、村级管理员、网格员、普通村民每种角色的权限范围差异很大。我采用RBAC基于角色的访问控制模型没搞更复杂的ABAC模型因为RBAC已经能覆盖需求而且容易理解、容易维护。数据库设计了四张表用户表、角色表、权限表、用户角色关联表。权限点按模块和操作维度划分统一编码格式为模块:操作比如person:add (新增村民)event:dispatch (分派事件)event:finish (办结事件)grid:patrol (执行巡查)statistics:view (查看统计)功能权限通过Spring Security注解实现接口级控制角色和权限点的映射关系存在数据库里。超级管理员乡级管理员默认拥有所有权限直接在代码里判断角色类型即可。6.2 数据隔离的实用方案功能权限管的是“能不能做”数据权限管的是“能看哪些数据”。数据隔离分为两种情况第一种是村级隔离。村级管理员和网格员只能操作本村数据。这个在大多数查询接口中通过动态拼接village_id条件实现。第二种是网格级隔离。网格员只能看到自己网格内的数据比村级更细。我在查询事件列表时如果当前登录用户是网格员角色就额外拼上grid_id条件。网格员默认是绑定一个网格还是一组网格用的是IN条件。if (isGridUser()) { ListLong gridIds getCurrentUserGridIds(); wrapper.in(grid_id, gridIds); } else if (isVillageAdmin()) { wrapper.eq(village_id, getCurrentVillageId()); }这套数据隔离方案在初版上线时没有任何问题但随着数据量增长页面出现了一个新问题组合查询时如果用户手动选择了其他条件比如查全部已办结事件拼SQL的顺序会导致条件渲染错误页面显示的数据超出了应有的范围。我最后换了思路把数据权限从Service层下沉到统一的查询拦截器里用MyBatis-Plus的拦截器机制自动追加条件不再依赖业务代码的自觉性。这个改动也对后续开发提了个要求新写的SQL必须走统一查询封装不能随意拼原生SQL。7. 部署上线与运行维护经验7.1 构建打包与环境配置项目使用Maven构建打包命令很简单mvn clean package -DskipTests。产物是一个可执行的jar包大约120MB左右包含了所有依赖。配置管理是这类项目的关键。我用了Spring Boot的多环境配置application-dev.yml、application-test.yml、application-prod.yml公共配置放在application.yml。部署时通过启动参数指定环境java -jar rural-platform.jar --spring.profiles.activeprod数据库密码、Redis密码这些敏感配置不在配置文件里写死而是通过环境变量注入。启动脚本里从环境变量取值传给Spring Bootexport DB_PASSWORD${DB_PASSWORD} java -jar rural-platform.jar --spring.profiles.activeprod \ --spring.datasource.password${DB_PASSWORD}政务类项目对数据安全要求较高我还在备份策略上做了补充。每天凌晨通过系统cron执行MySQL逻辑备份备份文件保留30天每月一次全量备份到另一台机器。7.2 线上性能调优项目上线后我做了几轮性能优化。第一轮是SQL优化。通过慢查询日志发现事件列表查询在数据量过万后明显变慢。原查询带了好几个OR条件MySQL优化器选择了全表扫描。解决方法是重写查询逻辑把OR条件拆成UNION ALL并加上联合索引。事件表加了两组索引一个是对village_idstatus的组合索引另一个是对handler_idstatus的组合索引。第二轮是缓存优化。村务公告、办事指南这类低频变更的数据用了Redis做缓存缓存失效时间设为5分钟。热点数据查询比如统计看板直接读中间表不再实时计算。第三轮是数据库连接池优化。将Druid的max-active从默认的20调到了50同时设置了连接空闲超时时间。调完后测试环境的并发能力明显提升qps从200左右涨到了350以上。还有一点提醒别忽略JVM参数。默认的JVM堆大小是物理内存的四分之一如果服务器内存是8G堆就只有2G跑不了多少数据。我把生产环境的JVM参数设为-Xms2g -Xmx4g -Xmn1g根据实际流量调整效果不错。8. 一些用过的工具和团队协作心得这个项目的完整生命周期里除了编码还牵扯文档、接口管理、测试和代码审查。我在下面整理几张协作工具清单给准备做同类项目的人一个参考。环节使用方案作用接口文档Knife4j 后端Swagger注解自动生成接口文档前端可以直接在线调试需求管理在线思维导图加表格拆解页面字段、接口字段和业务规则代码协作Git分支管理每个迭代一个feature分支合并前代码审查部署管理shell脚本一键构建、上传、重启减少人工误差问题追踪自建在线问卷表格记录Bug、复现步骤、修复版本Knife4j是我特别想推荐的。前后端联调时前端人员可以直接在文档页调试接口不需要后端手动导出接口说明。把Swagger的注解写好文档质量直接决定了联调效率。我在Controller上把所有参数都加了example示例值前端复制JSON时不用猜格式。代码评审这块我坚持每个合并请求至少由另一名开发者审查。审查重点看三件事SQL是否会走索引、事务是否有回滚边界、数据权限条件是否完整。这三类问题靠测试很难发现但代码评审很容易抓到。9. 写在最后的实际体会这个项目从需求调研到正式上线前后花了大概三个月。回头总结最深的体会是技术选型永远不是这类项目最难的地方真正难的是把业务逻辑理清楚、把数据边界划明白、把权限体系设计得不留死角。早期我急于搭建代码骨架先把CRUD接口都写好了才补权限和数据隔离逻辑结果返工了不少。如果再来一次我一定先做权限模型和数据字典的设计再动手写业务代码。纸上谈兵听起来浪费时间实际上能省掉后面大量的改bug时间。还有一点想和做类似项目的同行说政务类系统的需求变更非常频繁。上线后不到两个月业务方就提出了十几个优化项比如事件类型自定义、网格拆分功能、多级审核流程。所以代码里尽量保留扩展点表和字段设计时不要过度压缩留出冗余。轻松一点写代码以后维护时真的会感谢自己当初多留的那几个字段。如果要我给新接手类似项目的人一条最具体的建议那就是别把Excel导入导出当小功能处理。乡村治理类系统中大量的历史数据都要通过Excel迁移进系统导入的校验逻辑、错误提示、性能表现直接决定了业务方对系统的第一印象。我亲眼见过一个系统因为导入5000条数据超时被业务方拒绝使用的例子。数据迁移的体验做不好后面功能再完善也很难扭转印象。这个平台后续我打算接入更细化的移动端巡查能力把网格员的日常工作进一步数字化。项目能做扎实靠的还是把每个基础功能的细节吃透这比追求新技术栈有用得多。