1. 项目背景与需求拆解1.1 乡村养鸭的数字化痛点先聊个题外话。我前阵子跟一个做畜禽养殖系统的朋友聊天他说现在乡村养鸭户的痛点根本不是“疫苗怎么打”“饲料怎么配”这些技术问题早就有兽医站和饲料商在管。真正的痛点是什么信息断档。养殖户手里有一本厚厚的记账本今天进了多少饲料、这批鸭子是哪天进的苗、上次防疫是什么时候做的、卖出去多少斤、均价多少全靠脑子记和本子记。然后到了一定规模——比如存栏5000只以上——本子就记不住了账也容易对不上加上中间商收购、政府补贴申报、保险理赔都要数据拿不出一份像样的台账就处处吃亏。我当时接到的这个模拟项目就是围绕这个痛点做的一套基于Spring Boot的乡村养鸭户综合服务管理平台。它的定位不是“高大上的物联网大屏”而是踏踏实实帮养鸭户把养殖全过程管起来的业务管理系统。核心使用者有三种角色养殖户本人、畜牧技术员、平台管理员覆盖的场景包括鸭舍管理、批次档案、饲料出入库、防疫记录、成鸭销售和利润统计。1.2 平台要解决的三个核心问题我在需求调研阶段把养鸭户的需求归拢成三个关键词记录、提醒、算账。记录。鸭子的批次、进苗日期、品种、数量、死亡淘汰数、饲料耗用这些必须有人管。一个批次养40到45天中间过程数据丢了后面全部白搭。提醒。防疫不是一次就完事鸭瘟、禽流感、鸭病毒性肝炎都有对应的免疫日龄窗口错过了再补就麻烦。平台必须能按日龄自动推算下一次免疫时间提前推送消息。算账。养鸭是典型的重投入、慢周转生意上游饲料成本、下游成鸭售价都在波动。养殖户最关心的就是“这一批赚了多少”。系统要能按批次归集收入和支出算清楚单只成本、单只利润。把这三个问题落实成系统功能就是这个平台的骨架往下拆每个模块都跑不开这几条主线。1.3 用户角色与业务闭环这个平台我设计成三类角色对应三类使用场景养殖户日常操作最主要的使用者管批次、记账、查提醒、看报表用手机端就能完成。技术员负责辖区养殖户的防疫任务下发、用药指导和异常上报处理。管理员维护基础数据比如药品字典、饲料品类、鸭苗供应商、收购商信息同时管理平台内所有用户的账号和权限。角色设计完成了整个业务就闭环了养殖户建批次 → 技术员下发防疫计划 → 养殖户确认执行并回填记录 → 饲料出库自动扣减库存 → 成鸭销售登记 → 系统按批次结算利润 → 技术员和管理员看到汇总分析。这个闭环逻辑贯穿整个系统后面每个模块的代码实现都是围绕它来做的。2. 技术选型与架构设计2.1 为什么选Spring Boot而不是微服务可能有人会问一个乡村养殖平台用得着Spring Boot吗直接用个轻量框架不行吗我的答案是Spring Boot 单人开发友好、生态成熟、招人好招是这种中小型业务系统最稳妥的选择。这个项目的技术栈是这样的后端Spring Boot 2.7.x、MyBatis Plus、Redis、MySQL 8.0前端Vue 3 Element Plus 做管理后台H5移动端适配养殖户使用部署Docker Compose 编排Nginx 做反向代理没有上微服务没有上Spring Cloud也没有搞分布式事务。原因很简单这个项目的用户量和数据量单体架构完全扛得住。养鸭户的并发不会高到哪去真正的复杂度在业务规则和易用性上不在架构规模上。微服务那套注册中心、网关、链路追踪在这样一个项目里只会增加部署难度和运维成本乡村站点的技术员不一定伺候得动。有的开发者一上来就想用微服务觉得显得有技术含量。我的经验是技术选型的第一原则是匹配业务规模不是匹配简历深度。单体优先等真正遇到性能瓶颈了再拆也不迟。2.2 前后端分离与移动端选型前端为什么拆成两套运营后台的表格、表单、统计图表很重适合PC端大屏操作养殖户的核心动作是“掏出手机记一笔”必须在手机上完成而且要简化到极致。我调研的几个养殖户都五十岁上下智能手机用得不算溜复杂界面根本没法用。所以移动端我特意做了极简化设计首页就四个大按钮分别是“记饲料”“记防疫”“记销售”“看批次”。点进去就是对应的表单字段数量压到最少提交就完事。这个设计思路最后在试用反馈里被反复提到说明抓对了需求。移动端这套H5页面直接嵌在微信公众号里养殖户不用下载App微信里就能打开。微信的生态在乡村渗透率极高这个入口成本为零。2.3 数据库设计与表结构规划数据库是这个项目的核心资产表结构我前后调了三版。给大家看看最终的库表设计思路用户相关用户表、角色表、用户角色关联表、养殖户档案表。养殖核心鸭舍表、批次表关联鸭舍、批次日龄记录表。物资相关饲料品类表、饲料入库单、饲料出库单、库存表。防疫相关防疫项目字典、免疫计划表、免疫执行记录表、异常上报表。销售相关销售订单表、收购商表、批次销售汇总表。统计相关按日期的饲料耗用汇总视图、批次利润明细视图。核心的业务逻辑都体现在批次表里我先放一个简化版的建表语句方便后面讲解CREATE TABLE batch_info ( id bigint(20) NOT NULL AUTO_INCREMENT, batch_no varchar(32) DEFAULT NULL COMMENT 批次编号, user_id bigint(20) DEFAULT NULL COMMENT 养殖户ID, duck_house_id bigint(20) DEFAULT NULL COMMENT 鸭舍ID, breed_type varchar(50) DEFAULT NULL COMMENT 品种, hatch_date date DEFAULT NULL COMMENT 进苗日期, hatch_count int(11) DEFAULT NULL COMMENT 进苗数量, current_count int(11) DEFAULT NULL COMMENT 当前存栏, dead_count int(11) DEFAULT NULL COMMENT 累计死亡/淘汰数, status tinyint(4) DEFAULT NULL COMMENT 状态1养殖中 2已出栏, expected_market_date date DEFAULT NULL COMMENT 预计出栏日期, create_time datetime DEFAULT NULL, update_time datetime DEFAULT NULL, PRIMARY KEY (id), KEY idx_user_id (user_id), KEY idx_hatch_date (hatch_date) ) ENGINEInnoDB DEFAULT CHARSETutf8mb4 COMMENT鸭子批次信息表;这个表的设计有几个考虑current_count是冗余字段每发生一次死亡或销售就做自减这样列表页展示存栏量不用实时聚合算查询效率高很多expected_market_date用来支撑出栏提醒是整个系统“提醒”功能的支点。3. 核心模块设计与实现3.1 认证与权限模块先说权限。系统三类角色权限要求完全不同。养殖户只能看自己和本鸭舍的数据技术员能看自己辖区的所有数据管理员全库可见。我用的方案是Spring Security JWT。登录成功后签发JWT里面带上用户ID和角色标识之后的每个请求后端从Token里解析身份再通过自定义注解做接口级鉴权。这里有个细节值得讲JWT本身是无状态的但系统里存在账号冻结、密码修改需要立即失效的场景纯JWT处理不了。我的做法是在Redis里存了一份Token黑名单登出或者改密之后把对应的jtiJWT ID写进黑名单过期时间是剩余有效期。这样既保住了无状态的好处又补上了主动失效的能力。核心的拦截器判断逻辑大概是这样的Component public class JwtAuthenticationInterceptor implements HandlerInterceptor { Autowired private StringRedisTemplate stringRedisTemplate; Override public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception { String token request.getHeader(Authorization); if (StringUtils.hasText(token) token.startsWith(Bearer )) { token token.substring(7); } // 校验签名和有效期 Claims claims JwtUtil.parseToken(token); if (claims null) { response.setStatus(401); return false; } // 校验是否在黑名单中 String blacklistKey jwt:blacklist: claims.getId(); if (Boolean.TRUE.equals(stringRedisTemplate.hasKey(blacklistKey))) { response.setStatus(401); return false; } // 把用户ID塞进Request上下文 request.setAttribute(userId, claims.get(userId)); request.setAttribute(roleCode, claims.get(roleCode)); return true; } }黑名单这套逻辑在实际开发中容易漏很多人写着写着就把登出功能做成前端删掉Token后端完全没有可控性。我这边测试的时候就遇到过用户改了密码旧Token还能用几天就是因为黑名单没做。加了之后安全问题才算真正堵上。3.2 批次档案与鸭舍容量管理批次是整个养殖数据的“主档”一切业务都挂在批次下面。我设计的批次生命周期是创建批次进苗→ 日常记录死亡/防疫/用料→ 出栏结算销售完成关闭批次。创建批次的时候有几个校验规则不能马虎鸭舍容量校验。一个鸭舍存栏上限是3000只如果当前存栏加上新批次进苗数超过容量必须提示“超容量”。这个校验我一开始写在Service层但后来发现并发情况下两个请求同时建批次可能绕过校验就加上了数据库层的唯一约束和Redis分布式锁的双保险。日龄计算逻辑。相同品种的疫苗程序是按日龄走的。系统里我写了一个工具类根据hatch_date和当前日期算出日龄再在日龄达到某个阈值时触发提醒。public class AgeUtil { public static int calculateAgeDays(LocalDate hatchDate, LocalDate targetDate) { if (hatchDate null || targetDate null) { return 0; } return (int) ChronoUnit.DAYS.between(hatchDate, targetDate); } }看起来简单但它直接决定了免疫提醒准不准。后来在联调测试里发现一个边界情况如果养殖户把进苗日期填错了回填之后再改过来提醒计划就要整体重新计算。所以我在更新hatch_date的接口里强制要求重新生成该批次所有未执行的免疫计划不能只改一个日期字段了事。3.3 饲料出入库与库存联动饲料管理这一块我采用的方案是两张表分离单据表和库存表。入库单、出库单各自记录流水库存表只存当前余量。每次出库的时候事务里同时执行“插入出库单”和“扣减库存”两个操作数据库行锁保证不会超扣。这里踩过一个坑分享给大家一开始出库扣库存我写的是“先查库存判断够不够再update”结果测试时用并发工具一压就出现了超扣问题。其实就是经典的并发更新丢失。后来改成了带条件的原子更新SQLUPDATE feed_stock SET stock_quantity stock_quantity - #{quantity} WHERE feed_type_id #{feedTypeId} AND stock_quantity #{quantity}注意那个AND stock_quantity #{quantity}这个条件配合行锁才是真正的原子校验。用程序先查再减中间永远有缝隙。这个坑在电商库存系统里是老生常谈但实际写业务代码的时候太容易犯了我专门写在这里提醒各位。饲料成本直接影响单只成本核算所以饲料单据里必须有单价字段。出库时单价怎么取我用的加权移动平均法(原库存金额 入库金额) / (原库存数量 入库数量)每次入库后重算库存成本价。这样月底算利润的时候饲料成本接近真实水平不会忽高忽低。3.4 防疫提醒与执行回填防疫模块是技术员使用频率最高的功能。我设计了两个维度模板化免疫程序和批次实际执行记录。模板免疫程序是按品种维护的比如“樱桃谷鸭”的免疫程序可能是7日龄打鸭瘟疫苗、14日龄打鸭病毒性肝炎疫苗、21日龄再强化一次。创建一个新批次后系统根据品种自动带出默认免疫计划。public void generateImmunePlan(Long batchId) { BatchInfo batch batchMapper.selectById(batchId); ListImmuneTemplate templates immuneTemplateMapper.selectByBreedType(batch.getBreedType()); for (ImmuneTemplate template : templates) { ImmunePlan plan new ImmunePlan(); plan.setBatchId(batchId); plan.setImmuneName(template.getImmuneName()); plan.setPlanDate(batch.getHatchDate().plusDays(template.getAgeDay())); plan.setStatus(0); // 0待执行 1已执行 2已逾期 immunePlanMapper.insert(plan); } }计划生成之后后端有个定时任务每半小时扫一次把所有“计划日期前一天和当天”且“状态待执行”的计划揪出来然后往养殖户微信端发提醒。这里我用的是定时任务框架按批次查还是按计划查一开始没想清楚后面发现按计划查更直接——因为计划表里已经冗余了plan_date不用再join批次表。执行回填的界面做得特别简单养殖户点“确认执行”然后填实际日期、药品用量、操作人附上一张现场照片完了。照片上传走的是本地存储路径Nginx直接映射静态目录访问没有引对象存储因为独立部署的服务器上没有那条件能省则省。3.5 销售结算与批次盈亏分析销售模块是养殖户最看重的。我的思路是每一笔销售填写销售日期、数量、单价、收购商系统自动关联到当前“养殖中”的批次。批次全部卖完后养殖户点“结算出栏”系统按批次汇总所有销售收入和所有成本自动算出利润数据。成本包括苗费批次创建时填的进苗成本、饲料成本按出库单汇总、防疫药品成本、人工和其他杂费。批次收入则来自销售订单汇总。利润计算的SQL我放在一个存储逻辑里避免每个报表页都写一遍聚合逻辑public BatchProfitVO calculateBatchProfit(Long batchId) { // 1. 收入汇总 BigDecimal income saleOrderMapper.sumAmountByBatchId(batchId); // 2. 成本分类汇总 BigDecimal feedCost feedOutStockMapper.sumCostByBatchId(batchId); BigDecimal medicineCost immuneRecordMapper.sumCostByBatchId(batchId); BigDecimal otherCost batchOtherCostMapper.sumCostByBatchId(batchId); BigDecimal totalCost feedCost.add(medicineCost).add(otherCost); // 3. 利润 BigDecimal profit income.subtract(totalCost); // ... }数据统计这块我强烈推荐用冗余字段方案在批次表上维护累计收入、累计成本两个字段每录入一笔销售或出库就实时累加。这样后续做“养殖户首页的利润卡片”或者“技术员区域汇总榜”时直接读取不用临时去跑大聚合SQL。乡村网络的服务器性能一般最怕报表页卡顿冗余换性能值。4. 实操过程与关键环节实现4.1 开发环境的搭建与初始化我本地的开发环境是JDK 1.8、Maven 3.8、MySQL 8.0、Redis 6.x。有人问为什么不用JDK 17或者21因为Spring Boot 2.7.x对JDK 8的兼容最稳而且乡村项目部署的服务器多数还是老系统装JDK 8的接受度最高。记住一个原则生产环境是什么开发环境就用什么别在版本上搞惊喜。数据库初始化我用的是spring.sql.init自动执行schema.sql和data.sql里面把角色、管理员账号、基础字典数据都初始化好。这样新环境部署的时候一条命令就能把库建好不用手动导入SQL脚本。前后端联调阶段我在application.yml里做了多环境配置spring: profiles: active: dev --- spring: config: activate: on-profile: dev datasource: url: jdbc:mysql://localhost:3306/duck_farm?useUnicodetruecharacterEncodingutf8useSSLfalseserverTimezoneAsia/Shanghai username: root password: root123 redis: host: localhost port: 6379 --- spring: config: activate: on-profile: prod datasource: url: jdbc:mysql://mysql-server:3306/duck_farm?useUnicodetruecharacterEncodingutf8useSSLfalseserverTimezoneAsia/Shanghai username: duck_app password: ${DB_PASSWORD}生产环境的数据库密码用环境变量注入不写在配置文件里这是安全底线。4.2 用MyBatis Plus加速CRUD开发业务系统大量CRUD手写BaseMapper太痛苦我直接用的MyBatis Plus。实体类加TableName注解Mapper接口继承BaseMapperT基础的增删改查不用写一行SQL。写一个典型的Controller接口比如保存防疫记录RestController RequestMapping(/api/immune) public class ImmuneRecordController { Autowired private ImmuneRecordService immuneRecordService; PostMapping(/record) public Result saveRecord(RequestBody Valid ImmuneRecordDTO dto) { // 手动设置操作人ID防止越权 dto.setOperatorId(CurrentUserHolder.getUserId()); boolean success immuneRecordService.saveWithPlanStatus(dto); return success ? Result.ok() : Result.fail(保存失败); } }这个saveWithPlanStatus方法里面有两件事插入免疫执行记录把对应免疫计划状态改成“已执行”。如果只做第一件列表页就会一直提醒“待执行”养殖户会觉得系统有问题。这种“操作业务数据 联动状态数据”的场景在整个系统里到处都是记住事务一定要加在Service层。4.3 定时提醒与微信消息推送提醒功能我用Spring自带的Scheduled来做单机场景完全够用。定时任务写了三个每30分钟扫描一次待执行的免疫计划给对应养殖户推消息。每天早上8点扫描饲料库存低于阈值的记录生成“请备货”提醒。每天晚上9点扫描预计出栏日期在3日内的批次提醒养殖户准备联系收购商。消息推送这块我最终用的是微信公众号模板消息接口。因为养殖户都关注了村畜牧站的公众号后台可以通过openid定向推送。推送逻辑里有个比较实用的细节定时任务里查出来的是“计划待执行的批次”但是我用Redis存了一个“今日已推送”的标记key是immu:notice:{planId}:{yyyyMMdd}过期时间24小时。这样同一个计划一天只推送一次不然定时任务半小时跑一次养殖户一上午收八九条消息肯定得骂人。4.4 部署方案与日常运维部署库用的是Docker Compose一条指令起所有服务。我写了三个容器MySQL、Redis、应用本身。应用镜像使用多阶段构建先Maven打包再JRE运行。简单展示一下我用的docker-composeversion: 3.8 services: mysql: image: mysql:8.0 container_name: duck-mysql environment: MYSQL_DATABASE: duck_farm MYSQL_ROOT_PASSWORD: root123456 volumes: - ./mysql-data:/var/lib/mysql restart: always redis: image: redis:6.2 container_name: duck-redis restart: always app: build: . container_name: duck-app depends_on: - mysql - redis environment: SPRING_PROFILES_ACTIVE: prod DB_PASSWORD: root123456 ports: - 8080:8080 restart: always有几个运维细节我吃了亏才记住的MySQL容器一定要挂外部数据卷否则容器一删数据全没了restart: always必须写不然服务器重启后服务起不来乡下没人全天看着多环境配置里的SPRING_PROFILES_ACTIVE和DB_PASSWORD一定得在容器启动时注入别写死在镜像里。5. 常见问题与避坑指南5.1 数据库连接池与超时问题项目上线后测试反馈服务器开两天就出现“偶尔接口第一次请求特别慢”的情况。排查了一圈定位到是数据库连接空闲超时后被MySQL服务端关闭而连接池没有及时发现拿到失效连接后第一次请求必然要报错重连耗时自然高。解决办法是配置连接池的test-while-idle和空闲回收时间同时保证连接池的最大连接数不要超过MySQL的max_connections。我在Druid连接池里做了如下配置spring: datasource: druid: initial-size: 5 min-idle: 5 max-active: 20 test-while-idle: true time-between-eviction-runs-millis: 60000 min-evictable-idle-time-millis: 300000这类问题在开发环境根本发现不了因为开发环境人少、数据库连接一直有活跃请求连接池里的空闲连接不会被回收。只有部署到服务器上、夜间没人用的时候空闲连接才会暴露出问题。5.2 大文件图片上传与Nginx配置防疫记录里的照片上传和养殖栏舍照片单张都是3到5MB的手机原图。一开始后端接口直接接收文件然后写磁盘发现高峰期时会占大量带宽而且Nginx默认配置的client_max_body_size只有1M直接报413。我的处理是前端在上传前用canvas压缩把图片宽度压到1200px以内质量压到0.7单张控制在300KB以内后端再限制单次上传大小2MB超了就提示“图片过大”。Nginx里加一行client_max_body_size 5m;顺带说明一下存储路径的设计。我用的是按照日期分目录存储/data/duck_upload/2025/01/15/uuid.jpg数据库里存相对路径页面通过Nginx的静态映射来访问。这里有个坑不要把绝对路径或者IP直连路径写进数据库否则以后迁服务器或者换域名就傻眼了数据库里的存量数据全都得改一遍。5.3 时区错乱引发的日期统计偏差日期统计错乱这个坑出现在做销售月度报表的时候。后端查出来的利润数据和前端展示的数据差一天查来查去发现是数据库时区与会话时区不一致导致的。MySQL 8.0默认时区是系统时区而连接串里我写的是serverTimezoneAsia/Shanghai两边应该一致。但实际上Docker容器内的MySQL系统时区是UTC跟宿主机的东八区差了8小时。这就导致所有DATETIME字段往里存的时候被数据库偏移了8小时存储查询出来再偏移回来日期就对不上了。解决方法是给MySQL容器显式设置时区environment: - TZAsia/Shanghai同时在启动命令里加--default-time-zone08:00。这类时区问题在开发环境很难复现因为开发环境的MySQL就是本地的时区没漂移只有部署到容器环境才会炸出来。5.4 养殖户误操作与数据纠正机制乡村用户操作系统的容错性要求比城市用户高得多。养殖户很容易把数字填错比如进苗数量1000填成了10000或者日期选错。系统里必须有一套“反审批”机制。我的设计是所有关键单据批次创建、出库单、销售单都支持在当天内无理由撤回撤回后自动回补库存和金额。超过当天需要技术员账号审核后才能纠正而且纠正会留下操作日志。这样做的考虑是养殖户才是数据的责任主体系统要给他们试错的余地。如果设计成“录入就锁定修改要审批”养殖户一点小事就得打电话找技术员技术员也不堪其扰。把纠错权限下放一部分剩下的一部分走审核留痕既能满足灵活性又能保证数据可信。5.5 性能优化的三个核心点对于这种体量的业务系统性能优化不需要上什么高级手段抓住三个点就够了。第一数据库索引。批次表上按user_id和hatch_date建索引销售订单按batch_id建索引免疫计划按status和plan_date建索引。最有效的办法是打开慢查询日志把执行超过200ms的SQL捞出来挨个EXPLAIN看有没有走全表扫描。第二缓存热数据。鸭舍列表、品种字典、饲料品类这类变更频率极低的数据启动时加载进Redis或者本地缓存接口响应从几十毫秒降到几毫秒。第三批量操作。技术员给一个片区的几十个养殖户群发防疫通知如果用循环插入数据库连接和事务开销很大。改成MyBatis Plus的批量插入一次性拼接SQL性能提升非常明显。至于前端首屏慢的问题Vue项目用路由懒加载只看首屏需要的组件其余模块点击再加载效果很好但很多人一开始会忽略。6. 经验总结与后续扩展我在做这个项目的过程中最深的体会是乡村信息化系统的成败不在功能有多少而在养殖户愿不愿意用、用起来顺不顺手。你的技术栈再先进架构再复杂如果用户打开页面找不到“记一笔”的按钮那一切都是白搭。比较庆幸的是我在设计阶段专门留了两周时间做了现场调研跟养殖户坐在一起看他们怎么记账、怎么卖鸭、怎么请兽医最后把界面和流程都简化到了“三步以内完成一次记录”的程度。事实证明这部分投入回报最高。这个项目后续还能扩展不少方向。第一个是接入电子秤和智能水表让称重数据、饮水量自动采集减少人工录入第二个是增加简单的病害知识库和行情分析把被动记录变成主动指导第三个是跟冷链物流和深加工企业做数据对接打通从养殖场到餐桌的溯源链条。但无论往哪个方向扩展数据质量和数据闭环始终是根基。只要每一批鸭子从进苗到出栏的数据都沉淀在系统里这个平台就永远有价值和竞争力。最后分享一个小技巧做这类业务系统不管你会不会遇到先花时间把“数据字典”做好。品种表、药品表、饲料种类表、收购商表全用单独的字典表管理页面用下拉框选择不要让人手动填写。这样后期统计报表才能按字典分组不然五花八门的手填文字会把你逼疯。
