SpringBoot3+Vue3前后端分离棉花种植管理系统部署与验证

棉花种植基地管理系统这类项目，最近问的人不少。它不是一个模型，也不是一个工具，而是一套完整的农业种植管理后台系统，技术栈是 JAVA + SpringBoot3 + Vue.js3 + MySQL，前后端分离架构，跑起来之后是一个能在浏览器里操作的 Web 管理平台。核心价值在于把棉花种植过程中散落在 Excel、微信、纸质记录本上的信息，收拢到一套有权限、有流程、能统计的系统里。

它最值得关注的几个点：一是技术栈新，SpringBoot3 要求 JDK 17 起步，Vue3 用的是组合式 API 加 Vite 构建，不是那种还在用 JDK 8 + Vue2 + Element UI 的老骨架；二是模块覆盖面比较全，地块、品种、种植批次、农事记录、采收、库存、设备、用户角色权限、数据看板基本都有；三是前后端彻底分离，后端只吐 JSON，前端单独打包，接口能直接给小程序、App 或者第三方系统复用；四是部署门槛不高，一台 2 核 4G 的云服务器或者本地一台普通笔记本就能跑起来，不需要显卡。

这篇文章会带你走完整条链路：环境准备、数据库初始化、后端启动、前端联调、核心业务功能验证、接口调用与批量数据处理、资源占用观察、常见报错排查，最后给一套可以长期维护的落地建议。适合正在做课程设计/毕业设计的学生、需要给农业类企业做内部管理系统的开发者，以及想拿一套现成前后端分离脚手架做二次开发的人。

1. 核心能力速览

先把关键信息摊开说，看完这张表基本就能判断要不要动手了。需要说明的是，下面这些是基于标题技术栈和这类农业管理系统的通用设计整理出来的，具体到某一份代码，模块名、接口路径、字段命名一定会有差异，实际以你拿到的工程为准。

这张表里最容易被忽略的是"是否需要独立显卡"这一项。很多同学一看到管理系统就下意识问显存，实际上这类项目从头到尾跑的都是 CRUD 和 SQL 查询，最吃资源的是 JVM 堆内存和 MySQL 连接池，跟 GPU 一点关系都没有。你把预算花在内存和磁盘 IO 上，比花在显卡上划算得多。

另一个要提前说清楚的是"批量任务"。这类系统里的批量，基本不是指队列化的异步任务，而是指 Excel 批量导入、批量导出、批量修改状态这几种。如果你需要的是带进度条、失败重试、断点续传的批处理引擎，那这套骨架需要自己补一层任务调度，通常用 Spring 的 @Async 或者引入 Quartz/XXL-JOB 来做。

2. 适用场景与使用边界

先说适合谁。第一类是做毕设或者课程设计的同学，这套技术栈组合非常标准，答辩时讲前后端分离、讲 RBAC 权限模型、讲 RESTful 接口设计，都有东西可讲，而且代码量适中，不会像微服务那一套一样铺得太开收不回来。第二类是农业合作社、种植基地、农资公司的信息化负责人，需要一套内部台账系统，把地块、批次、投入品、采收数据管起来，这套东西改一改就能用。第三类是想练手的后端开发者，拿一套完整业务系统去熟悉 SpringBoot3 的新特性，比如 Jakarta EE 命名空间迁移、原生镜像支持、ProblemDetail 错误响应等，比看文档有效。

再说能解决什么问题。最直接的是记录分散。以前基地里地块信息在一个 Excel，施肥打药记录在另一个本子，采收过磅数据在第三个地方，月底对账要人工合并。系统化之后，一条种植批次从播种到采收的完整链路能串起来，投入品消耗和产出能对上。其次是权限混乱，谁能改数据、谁只能看，靠共享文件夹是管不住的，RBAC 模型能解决这个。第三是统计滞后，看板上的面积、产量、库存数据实时算出来，不用等月底手工汇总。

不适合的场景也要讲明白。第一，这不是一个物联网平台。如果你的需求是接入土壤墒情传感器、气象站、水肥一体化控制器做实时采集和自动控制，那这套系统的定位是"业务台账"，你需要在它旁边再挂一个数据采集中间件，通过 MQTT 或者 HTTP 把设备数据写进来。第二，它不适合做高并发。农业管理系统的真实用户数通常是个位数到几十个，用不上分库分表、缓存集群那一套，硬上反而增加维护成本。第三，涉及农户个人信息、土地承包信息、购销合同金额这类数据时，它不是一个合规级的安全系统，出厂状态下的权限粒度、审计日志、数据脱敏都需要你自己加固。

边界方面有三条必须说清楚。数据授权：系统里录入的农户姓名、身份证号、联系方式、地块坐标属于个人信息，采集前要取得本人同意，展示时要按需脱敏，导出 Excel 的功能要限制到具体角色，不能谁都点。账号安全：默认管理员账号上线前必须改密码，测试环境的弱口令不能带到生产环境，JWT 密钥、数据库密码不能硬编码提交到代码仓库。素材与内容：系统里上传的图片、合同扫描件、检测报告，要确认你有权存储和展示，涉及第三方检测机构出具的报告，转发和公开需要对方许可。

3. 环境准备与数据库初始化

3.1 软件清单与版本建议

这一步最容易翻车，先把清单列清楚再动手。

关于 JDK 版本，有个坑要提前提醒：SpringBoot3 全面迁移到 jakarta.* 命名空间，如果你从网上抄了一段 javax.servlet.http.HttpServletRequest 的代码，编译会直接报"程序包 javax.servlet 不存在"。这不是依赖没下全，是命名空间变了，改成 jakarta.servlet.http.HttpServletRequest 就好。

3.2 数据库建库与字符集

先建库。字符集一定要用 utf8mb4，不要用 utf8。原因很实际：棉花品种名、地块备注、农户姓名里可能出现生僻字和 emoji，MySQL 的 utf8 实际是 utf8mb3，只支持三字节，遇到四字节字符会直接插入失败或者变成问号。这个坑在测试阶段不明显，等真实数据进来才发现，改起来要动表和索引，非常麻烦。

sql复制-- 建库示例，库名与字符集需按实际项目调整
CREATE DATABASE IF NOT EXISTS cotton_base
  DEFAULT CHARACTER SET utf8mb4
  DEFAULT COLLATE utf8mb4_general_ci;

USE cotton_base;

-- 用户表：RBAC 模型的起点
CREATE TABLE IF NOT EXISTS sys_user (
  id            BIGINT       NOT NULL AUTO_INCREMENT COMMENT '主键',
  username      VARCHAR(50)  NOT NULL COMMENT '登录账号',
  password      VARCHAR(100) NOT NULL COMMENT '密码哈希，禁止明文存储',
  real_name     VARCHAR(50)  DEFAULT NULL COMMENT '姓名',
  phone         VARCHAR(20)  DEFAULT NULL COMMENT '手机号',
  status        TINYINT      NOT NULL DEFAULT 1 COMMENT '1启用 0禁用',
  create_time   DATETIME     NOT NULL DEFAULT CURRENT_TIMESTAMP,
  update_time   DATETIME     NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  deleted       TINYINT      NOT NULL DEFAULT 0 COMMENT '逻辑删除标记',
  PRIMARY KEY (id),
  UNIQUE KEY uk_username (username)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='系统用户表';

-- 地块表：种植业务的基础档案
CREATE TABLE IF NOT EXISTS base_plot (
  id            BIGINT       NOT NULL AUTO_INCREMENT,
  plot_code     VARCHAR(30)  NOT NULL COMMENT '地块编号',
  plot_name     VARCHAR(100) NOT NULL COMMENT '地块名称',
  area_mu       DECIMAL(10,2) DEFAULT NULL COMMENT '面积（亩）',
  soil_type     VARCHAR(50)  DEFAULT NULL COMMENT '土壤类型',
  location      VARCHAR(200) DEFAULT NULL COMMENT '位置描述',
  status        TINYINT      NOT NULL DEFAULT 1 COMMENT '1在用 0停用',
  create_time   DATETIME     NOT NULL DEFAULT CURRENT_TIMESTAMP,
  deleted       TINYINT      NOT NULL DEFAULT 0,
  PRIMARY KEY (id),
  UNIQUE KEY uk_plot_code (plot_code)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='地块档案表';

上面只是两张示意表，真实的工程里还会有角色表、菜单表、用户角色关联表、种植批次表、农事记录表、采收记录表、库存表等。导入建表脚本时有两个细节要注意：一是脚本开头如果有 DROP TABLE IF EXISTS，在生产环境执行前必须确认，否则一次误操作数据就没了；二是有外键约束的脚本要按依赖顺序执行，先建主表再建从表，不然会报 Cannot add or update a child row。

3.3 端口与目录规划

端口冲突是本地部署最常见的拦路虎。建议提前规划好，别等启动报错了再一个个试。

目录上也建议做隔离，别把数据库文件、上传文件、日志全堆在项目根目录：

bash复制# 建议的目录结构（路径按实际调整）
/data/cotton/
├── app/              # 后端 jar 包与启动脚本
├── web/              # 前端打包后的静态文件
├── upload/           # 用户上传的图片、附件
├── logs/             # 应用日志与 Nginx 日志
├── backup/           # 数据库定时备份
└── config/           # 外部化配置文件，不随代码走

把 upload 和 logs 放在项目目录外面，好处是重新部署时可以直接替换 app 和 web，用户上传的附件不会丢。这个习惯在本地开发时看不出价值，等第一次线上更新代码时就体现出来了。

4. 后端 SpringBoot3 服务启动与配置

4.1 配置文件怎么改

拿到工程后第一件事不是急着 Run，而是把配置文件里的数据库连接串、账号密码、文件上传路径改成本机的。SpringBoot3 的配置文件通常是 application.yml 或 application-dev.yml，用多环境 profile 区分开发和生产是标准做法。

yaml复制# application-dev.yml 示例，所有值需按本机环境替换
server:
  port: 8080
  servlet:
    context-path: /api

spring:
  datasource:
    driver-class-name: com.mysql.cj.jdbc.Driver
    url: jdbc:mysql://127.0.0.1:3306/cotton_base?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai&useSSL=false&allowPublicKeyRetrieval=true
    username: root
    password: 请替换为你的密码
    hikari:
      minimum-idle: 5
      maximum-pool-size: 20
      connection-timeout: 30000

  servlet:
    multipart:
      max-file-size: 20MB     # 单文件上传上限
      max-request-size: 50MB  # 单次请求总上限

  jackson:
    date-format: yyyy-MM-dd HH:mm:ss
    time-zone: GMT+8
    default-property-inclusion: non_null

# 自定义配置项，键名以实际工程为准
file:
  upload-path: /data/cotton/upload/
  access-prefix: /files/

logging:
  level:
    root: info
    com.example.cotton: debug
  file:
    name: /data/cotton/logs/app.log

几个参数值得单独说。allowPublicKeyRetrieval=true 是 MySQL 8 默认使用 caching_sha2_password 认证插件时容易踩的坑，不加这个参数可能报 Public Key Retrieval is not allowed。serverTimezone=Asia/Shanghai 不配好，时间字段会出现 8 小时偏差，采收日期这种东西一错就很难查。maximum-pool-size 不要无脑调大，20 个连接对几十人的管理系统完全够用，调成 200 反而会因为 MySQL 端 max_connections 不够而启动失败。

4.2 启动命令与首次编译

用 Maven 的话，先跳过测试打包，再启动。第一次打包会下载一堆依赖，网速慢的话等几分钟很正常，别以为是卡死了。

bash复制# 进入后端工程目录
cd cotton-backend

# 跳过测试打包，首次构建会下载依赖
mvn clean package -DskipTests

# 方式一：直接用 Maven 插件启动（开发调试常用）
mvn spring-boot:run -Dspring-boot.run.profiles=dev

# 方式二：用打包好的 jar 启动（更接近生产）
java -jar target/cotton-backend.jar --spring.profiles.active=dev

# 生产环境示例：指定堆内存与外部配置
java -Xms512m -Xmx1024m \
     -Dfile.encoding=UTF-8 \
     -jar /data/cotton/app/cotton-backend.jar \
     --spring.profiles.active=prod \
     --spring.config.location=/data/cotton/config/

-Xms512m -Xmx1024m 这组参数是通用示例，不是这个项目的推荐值，实际要按机器内存和并发量调。小机器上把最大堆设成物理内存的一半左右比较稳妥，留出空间给 MySQL 和操作系统。设得太小会频繁 Full GC 导致接口卡顿，设得太大反而可能被 OOM Killer 干掉，这个平衡点只能压测出来。

启动成功的标志是控制台出现 Started XxxApplication in x.xx seconds 这样的日志，并且能看到 Tomcat 在 8080 端口启动的记录。如果只打印了 Spring 的 banner 就停了，往下翻日志找 Caused by，真正的错误通常在异常链最末端。

4.3 登录与鉴权接口验证

后端起来之后，先别急着开前端。用 curl 直接打接口，能快速判断是后端问题还是前端问题。这类系统最核心的接口是登录，登录通了，token 拿到了，其他接口才有得测。

bash复制# 1. 登录接口，路径需按实际工程调整
curl -X POST "http://127.0.0.1:8080/api/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"123456"}'

# 预期返回类似：
# {"code":200,"msg":"登录成功","data":{"token":"eyJhbGciOi...","userId":1}}

# 2. 带上 token 请求需要鉴权的接口
curl -X GET "http://127.0.0.1:8080/api/plot/page?pageNum=1&pageSize=10" \
  -H "Authorization: Bearer 上一步拿到的token"

# 3. 验证无 token 时是否被正确拦截（预期返回 401 或业务码 401）
curl -i "http://127.0.0.1:8080/api/plot/page?pageNum=1&pageSize=10"

第 3 步很关键，很多人只测"能登录"，不测"不登录会被挡住"，结果上线后发现所有接口裸奔。判断标准很明确：不带 token 或者带错 token 时，接口必须返回未授权，而不是返回数据。如果返回了数据，说明拦截器或者 Spring Security 的过滤链配置有问题，这个必须先修掉再谈其他功能。

5. 前端 Vue3 工程启动与联调

5.1 依赖安装与开发服务启动

前端这边坑更多，主要是 Node 版本和包管理器不匹配。先看工程根目录有没有 .npmrc 或者 package.json 里的 packageManager 字段，有的话严格按照它指定的来。

bash复制# 进入前端工程目录
cd cotton-web

# 查看需要的 Node 版本（如果有 .nvmrc 文件）
cat .nvmrc 2>/dev/null || echo "未指定，建议使用 Node 18 LTS 或 20 LTS"

# 安装依赖，锁文件是哪个就用哪个命令
npm install          # 有 package-lock.json 时
# pnpm install       # 有 pnpm-lock.yaml 时
# yarn install       # 有 yarn.lock 时

# 启动开发服务器
npm run dev

# 生产构建
npm run build

npm install 报错的话，先看错误类型。ERESOLVE unable to resolve dependency tree 是依赖版本冲突，说明工程里某个包对 peer dependency 的约束和实际装的不一致，可以试着删掉 node_modules 和 lock 文件重装，但更稳妥的做法是问一下工程提供方用的是什么 Node 版本。gyp ERR! 这类报错通常是某个依赖需要本地编译，Windows 上要装 Visual Studio Build Tools，Linux 上要装 build-essential 和 python3。国内网络环境下下载依赖慢，可以配一个镜像源，这个是常规操作。

5.2 代理配置与跨域处理

前后端分离的开发模式下，前端跑在 5173，后端跑在 8080，浏览器直接请求就是跨域。标准解法是在开发服务器上配代理，把 /api 开头的请求转发到后端，这样浏览器眼里始终是同源请求。

javascript复制// vite.config.js 示例，路径与端口按实际工程调整
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import path from 'path'

export default defineConfig({
  plugins: [vue()],
  resolve: {
    alias: {
      '@': path.resolve(__dirname, 'src')
    }
  },
  server: {
    host: '0.0.0.0',
    port: 5173,
    proxy: {
      // 前端请求 /api/xxx，实际转发到 http://127.0.0.1:8080/api/xxx
      '/api': {
        target: 'http://127.0.0.1:8080',
        changeOrigin: true
      },
      // 如果有文件访问路径，也要一起代理
      '/files': {
        target: 'http://127.0.0.1:8080',
        changeOrigin: true
      }
    }
  }
})

这里有个高频理解偏差：context-path 设成了 /api，代理又配了 /api，需不需要 rewrite？答案取决于后端接口的完整路径。如果后端 context-path 是 /api，控制器上写的是 /plot/page，那真实地址就是 /api/plot/page，代理直接转发、不加 rewrite 才对。如果加了 pathRewrite: { '^/api': '' }，请求就变成 /plot/page，会 404。这类 404 排查起来最快的方法是在浏览器 F12 的 Network 面板里看请求的实际 URL，和后端日志里收到的 URL 对比，一眼就能看出少没少前缀。

生产环境就没有代理这回事了，通常用 Nginx 把前端静态资源和后端接口放在同一个域名下：

nginx复制# nginx.conf 片段，域名、路径按实际情况替换
server {
    listen 80;
    server_name your-domain.com;

    # 前端静态资源
    root /data/cotton/web;
    index index.html;

    # history 路由模式下必须加，否则刷新页面 404
    location / {
        try_files $uri $uri/ /index.html;
    }

    # 接口转发
    location /api/ {
        proxy_pass http://127.0.0.1:8080/api/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_read_timeout 60s;
        client_max_body_size 50m;
    }

    # 上传文件访问
    location /files/ {
        alias /data/cotton/upload/;
    }
}

try_files $uri $uri/ /index.html 这一行千万别漏。Vue Router 用 history 模式时，刷新 /plot/list 这种路径，Nginx 会去找这个文件，找不到就 404。加上这行之后，所有匹配不到的请求都回退到 index.html，由前端路由接管。这个坑几乎每个前端分离项目都会踩一次。

6. 核心业务功能测试与效果验证

部署通了不等于功能可用。下面按模块给一套验证顺序，每个模块都说清楚测什么、怎么判断成功、失败了往哪看。测的时候建议准备一份最小测试数据，比如 2 个地块、1 个品种、1 个种植批次、2 条农事记录，数据量小才好对照结果。

6.1 登录鉴权与角色权限

测试目的：确认 RBAC 模型真的生效，而不是只在页面上藏了按钮。

操作步骤：先用管理员账号登录，进入用户管理新建一个"只读"角色，只勾选查看权限；再新建一个测试账号绑定这个角色；然后退出，用测试账号登录，尝试访问地块列表、尝试点新增按钮、尝试直接调用新增接口。

预期结果：列表能看，新增按钮不显示或者置灰，直接 curl 调用新增接口返回无权限。

判断成功的标准：前端隐藏 + 后端拦截两层都生效。只做了前端隐藏的，用浏览器开发者工具改一下按钮的 disabled 属性或者直接构造请求就能绕过，这种属于没做权限。

常见失败原因：后端接口上忘加 @PreAuthorize 之类的方法级注解；角色和菜单的关联表数据没初始化全；token 里没带权限集合，导致后端判定时拿到空集合。排查时建议在后端拦截器里打一行日志，把当前用户和请求路径打出来，比猜快得多。

6.2 地块与种植批次管理

测试目的：验证基础档案的增删改查和关联关系。

操作步骤：新增一个地块，面积填 120.50 亩，土壤类型选沙壤土；保存后回到列表，用编号搜索；点编辑把面积改成 130.00，保存；再新增一个种植批次，选择刚建的地块和某个棉花品种，填写播种日期、计划采收日期。

预期结果：地块列表能搜到，编辑后面积正确更新，批次列表里能看到关联的地块名称而不是一串 ID。

判断成功的标准：面积这种 DECIMAL 字段保存后没有精度丢失，说明精度和小数位没丢；批次列表能正确带出地块和品种的名称，说明关联查询写对了；删除地块时如果已有批次引用，应该被拦住或者给出提示，而不是直接删掉留下孤儿数据。

常见失败原因：面积字段用 double 存导致 120.50 变成 120.499999，这是浮点精度问题，金额和面积一律用 BigDecimal 加 DECIMAL 列；关联查询返回空，多半是 XML 里的 resultMap 没配全或者用了 association 但列名对不上；删除时报外键约束错误但前端提示不友好，需要在全局异常处理器里把这类异常翻译成人话。

6.3 农事记录与投入品追溯

测试目的：验证一条记录能不能挂到具体批次上，并且能反查。

操作步骤：进入农事记录，选择种植批次，记录一次"施肥"，填写投入品名称、用量、操作日期、操作人；再记录一次"打药"，填写药剂名称和稀释倍数；然后回到批次详情页，看能不能看到这个批次的全部农事记录，按时间倒序排列。

预期结果：记录保存成功，批次详情能看到时间线，投入品数量能汇总。

判断成功的标准：时间线顺序正确、字段完整、汇总数对得上。如果批次详情看不到记录，先去数据库里查一下记录的 batch_id 是不是存进去了，存进去了就是查询条件写错了，没存进去就是前端传参或者后端接参的问题，这一步能砍掉一半排查时间。

常见失败原因：日期格式前后端不一致，前端传 2024-06-01，后端用 LocalDateTime 接会报解析失败，需要在字段上加 @JsonFormat 或者统一改成 LocalDate；操作人字段希望自动取当前登录用户，但代码里没从上下文取，前端让用户手填了，这种设计上就不对，应该在后端自动填充。

6.4 采收、库存与数据看板

测试目的：验证跨模块的数据联动和统计准确性。

操作步骤：给某个批次新增一条采收记录，填写采收日期、采收量（公斤）、等级；然后进库存模块，看是否有一条对应的入库流水；最后打开数据看板，核对总面积、总产量、库存总量这几个数字。

预期结果：采收保存后库存自动增加，看板数字随之变化，且和明细能对上。

判断成功的标准：这是最考验设计的一环。库存到底是在采收时自动生成流水，还是需要人工确认入库，取决于业务设计，但无论哪种，看板总数必须等于明细之和。差一点都要查清楚，统计口径错了比功能报错更危险，因为不报错，错得很安静。

常见失败原因：统计 SQL 用了 COUNT(*) 而不是 SUM(数量)，把记录条数当成了总量；多表关联统计时没加批次过滤条件，导致跨批次重复累加；库存扣减没做并发控制，两个人同时出库导致数量算错，这种要在 SQL 层用 UPDATE ... SET num = num - ? WHERE num >= ? 这种条件更新来保证。

6.5 列表查询、分页与导出

测试目的：验证大数据量下的查询体验和数据导出完整性。

操作步骤：造 5000 条以上的农事记录（用脚本批量插入最省事），然后在前端翻页、改每页条数、加筛选条件查，最后点导出 Excel。

预期结果：分页响应在 1 秒以内，筛选条件生效，导出的 Excel 行数和筛选结果一致。

判断成功的标准：翻到最后一页数据不重复不遗漏，导出文件用 Excel 打开不乱码、日期不是一串数字。

常见失败原因：分页插件没配好，total 返回的是当前页条数；排序字段没做白名单校验，存在注入风险；导出时一次性 select * 全表加载，几万条直接把内存打满，正确做法是流式查询或者分批取数写入。

7. 接口 API 调用与批量数据处理

7.1 接口规范与统一响应

这类系统的接口通常是统一的包装格式，比如 code、msg、data 三段式。这种设计的好处是前端拦截器可以统一处理：code 是 200 就取 data，是 401 就跳登录，是 500 就弹错误提示，业务代码不用每个接口都写一遍判断。

json复制{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "total": 128,
    "records": [
      {
        "id": 1,
        "plotCode": "P2024001",
        "plotName": "东区一号地",
        "areaMu": 120.50,
        "status": 1
      }
    ]
  }
}

如果你要对接小程序或者第三方系统，建议先跟后端确认三件事：鉴权方式是放在 Header 的 Authorization 还是请求参数里的 token；分页参数是 pageNum/pageSize 还是 current/size；时间字段是时间戳还是 yyyy-MM-dd HH:mm:ss 字符串。这三个对不上，联调能磨掉一整天。

7.2 Python 调用示例

用脚本调接口比手点页面更适合做回归测试和批量造数。下面这个示例是通用模板，路径和字段需要按实际工程替换。

python复制import requests

BASE_URL = "http://127.0.0.1:8080/api"

# 1. 登录拿 token
login_resp = requests.post(
    f"{BASE_URL}/auth/login",
    json={"username": "admin", "password": "请替换"},
    timeout=10
)
login_data = login_resp.json()
assert login_data.get("code") == 200, f"登录失败: {login_data}"
token = login_data["data"]["token"]

headers = {
    "Authorization": f"Bearer {token}",
    "Content-Type": "application/json"
}

# 2. 分页查询地块，验证列表接口
page_resp = requests.get(
    f"{BASE_URL}/plot/page",
    params={"pageNum": 1, "pageSize": 10},
    headers=headers,
    timeout=10
)
page_data = page_resp.json()
print("总数:", page_data["data"]["total"])

# 3. 新增一条农事记录，验证写接口
record_payload = {
    "batchId": 1,
    "recordType": "施肥",
    "content": "追施复合肥",
    "amount": 15.5,
    "recordDate": "2024-06-01",
    "operator": "测试员"
}
create_resp = requests.post(
    f"{BASE_URL}/farmRecord/save",
    json=record_payload,
    headers=headers,
    timeout=10
)
print("新增结果:", create_resp.json())

这段脚本有几个实用的小技巧：每步都设 timeout，不然接口挂住脚本会一直等；登录后立刻断言，避免拿不到 token 还往下跑一堆无意义的报错；打印完整响应而不是只打印状态码，因为业务错误通常藏在 code 和 msg 里，HTTP 状态码可能还是 200。

7.3 批量导入的设计要点

批量导入是这类系统的刚需，因为历史数据都在 Excel 里。实现上通常用 EasyExcel 或者 POI，前者在大数据量下内存表现更好。不管用哪个，有四个点必须做到，少一个都会在上线后出事。

第一，模板校验。导入前先校验表头，列名对不上直接拒绝，不要"能读多少读多少"，那样用户以为成功了，实际只进去一半。第二，行级校验。每行都要校验必填项、数据格式、编号是否重复，把错误行号和原因收集起来，最后一次性返回给用户，而不是遇到第一行错误就中断。第三，事务边界。全部成功才提交，有一条失败就整批回滚，或者明确设计成"部分成功"，但一定要在界面上说清楚是哪种。第四，数量上限。单次导入限制在几千行以内，超过的让用户拆文件，避免一次请求把堆内存打穿。

java复制// 批量导入的骨架示意，类名与注解以实际工程为准
@PostMapping("/import")
public Result<?> importExcel(@RequestParam("file") MultipartFile file) {
    List<PlotImportDTO> rows;
    try {
        rows = EasyExcel.read(file.getInputStream())
                .head(PlotImportDTO.class)
                .sheet()
                .doReadSync();
    } catch (Exception e) {
        return Result.fail("文件解析失败，请检查模板格式");
    }

    if (rows.isEmpty()) {
        return Result.fail("文件中没有可导入的数据");
    }
    if (rows.size() > 5000) {
        return Result.fail("单次最多导入 5000 条，请拆分后重试");
    }

    // 逐行校验，收集错误信息而不是直接抛出
    List<String> errors = new ArrayList<>();
    for (int i = 0; i < rows.size(); i++) {
        PlotImportDTO row = rows.get(i);
        if (row.getPlotCode() == null || row.getPlotCode().isBlank()) {
            errors.add("第 " + (i + 2) + " 行：地块编号不能为空");
        }
        // 其余校验省略，按业务补充
    }

    if (!errors.isEmpty()) {
        return Result.fail("校验未通过：" + String.join("；", errors));
    }

    // 校验通过后再走入库，入库方法上加事务
    plotService.saveBatch(rows);
    return Result.ok("导入成功 " + rows.size() + " 条");
}

导出同理，要注意两个细节：一是用流式写出，别把几万行先攒到内存里再写；二是文件名做 URL 编码，中文文件名在某些浏览器下会变成乱码，这个用 URLEncoder.encode(fileName, "UTF-8") 处理一下就好。

8. 资源占用、性能观察与常见问题排查

8.1 资源占用怎么观察

这个项目不吃 GPU，重点看三块：JVM 堆内存、MySQL 连接数和慢查询、磁盘 IO。

JVM 这边，启动后可以用 jps -l 找到进程号，再 jstat -gcutil <pid> 1000 每秒打一次 GC 情况。重点看老年代使用率（O 列）是不是持续上涨不回落，如果每次 Full GC 之后老年代还是很高，说明有内存泄漏或者堆设小了。更直观的方式是加 -XX:+HeapDumpOnOutOfMemoryError 参数，真出问题时能留下现场。

MySQL 这边，先看连接数：show status like 'Threads_connected';，再看慢查询有没有开：show variables like 'slow_query_log';。管理系统最容易出问题的是列表查询没走索引，几万条数据全表扫，一次查询几百毫秒，页面就明显卡。用 EXPLAIN 看一下执行计划，type 出现 ALL 就要考虑加索引了。

前端构建也是内存大户。npm run build 在 Node 18 上处理大工程时偶尔会报 JavaScript heap out of memory，这时候可以临时调大内存限制：

bash复制# 临时提高 Node 构建时的内存上限，数值按机器情况调整
export NODE_OPTIONS="--max-old-space-size=4096"
npm run build

影响性能的几个主要变量，按影响从大到小说：列表查询有没有走索引，这是第一位的；单页返回条数，pageSize 设成 100 和设成 10 的响应时间差好几倍；关联查询的层数，一条 SQL join 五六张表，数据量一大就撑不住，该拆成两次查询就拆；导出数据量，这是最容易把内存打爆的操作。至于前端页面渲染，只要不是一次渲染几千行表格，基本感知不到性能问题；真要展示大量数据，做虚拟滚动比优化接口更有效。

8.2 常见问题排查表

下面这张表覆盖了这套技术栈组合下最常遇到的几类问题，遇到报错先在这里对一遍，大部分能直接定位。

排查有个通用原则：先看日志，再看网络，最后看代码。SpringBoot 的异常堆栈很长，但真正的根因永远在最下面的 Caused by 里。前端的问题先按 F12 看 Network 和 Console，请求发没发出去、响应回来了什么，比读代码快十倍。

9. 最佳实践与后续扩展方向

部署跑通只是起点，真正决定这套系统能不能长期用下去的，是一些看起来不起眼的工程习惯。

第一，配置外置，密钥不进仓库。 数据库密码、JWT 密钥、第三方接口的 AppKey，这些一律放在外部配置文件或者环境变量里，.gitignore 要把 application-prod.yml 挡掉。见过太多仓库里明文躺着生产库密码的情况，这不是会不会出事的问题，是早晚的事。生产启动用 --spring.config.location 指定外部目录，代码仓库里只留模板。

第二，数据库必须有备份。 管理系统最怕的不是宕机，是数据丢了找不回来。哪怕是最简单的 mysqldump 加 crontab 每天凌晨跑一次，也比没有强。备份文件要放到另一台机器或者对象存储上，别和数据库放同一块盘，盘挂了两个一起没。

bash复制# 每日备份示例，路径与账号需替换
#!/bin/bash
BACKUP_DIR=/data/cotton/backup
DATE=$(date +%Y%m%d_%H%M%S)
mysqldump -uroot -p"请替换密码" \
  --single-transaction --routines --triggers \
  cotton_base | gzip > ${BACKUP_DIR}/cotton_base_${DATE}.sql.gz

# 只保留最近 14 天的备份
find ${BACKUP_DIR} -name "*.sql.gz" -mtime +14 -delete

第三，输入校验放在后端。 前端表单校验是为了体验，后端校验才是为了数据正确。所有接收参数的 DTO 都要加 @NotNull、@Size、@Pattern 这类注解，配合 @Valid 生效。别指望前端一定传对，用 Postman 绕过去太容易了。

第四，日志分级，别什么都打 info。 开发阶段 debug 方便，上了生产还全量 debug，一天几个 G 的日志，磁盘很快就满。建议生产环境 root 用 info，业务包用 info，只有排查特定问题时临时调成 debug，查完改回来。日志按天滚动，保留 15 到 30 天。

第五，接口限流和鉴权要落到网关层或拦截器层。 这个系统用户不多，但接口暴露在公网上就存在被扫的风险。至少要做的：登录接口加失败次数限制，防止撞库；敏感操作（删除、导出全量数据）记录操作日志，谁在什么时候干了什么要能查；文件上传校验类型和大小，别让人传个 .jsp 或者 .sh 上来。

第六，数据合规要当成功能来设计，而不是事后补救。 涉及农户个人信息、土地承包面积、购销价格的字段，做什么人可见要提前定好；导出功能要按角色控制，导出动作要留痕；测试环境不要用真实农户数据，造一批假数据更省心。这些在毕设阶段看起来多余，但真正给企业用的时候，这几条决定了系统能不能过内部审计。

后续可以扩展的方向有两个。一个是移动端，把地块巡查、农事上报做成小程序，田间地头直接用手机录，比回办公室补录准确得多，后端接口不用大改，加一层移动端专用的聚合接口就行。另一个是数据分析和报表，现在看板上的统计基本是实时聚合，数据量上来之后可以加一张按天预聚合的汇总表，把重计算从请求链路上挪走，页面打开速度会有明显改善。

回到最开始那个问题：这套系统值不值得试。如果你要的是一套技术栈现代、结构清晰、能跑起来看到完整业务流程的前后端分离项目，它完全够用，一台普通电脑装个 JDK 17、MySQL 8、Node 18 就能在本机跑通全流程，部署环节最花时间的其实是数据库导入和端口代理配置这两步。真正的坑不在启动，而在于权限是否真的落到后端、统计口径是否和明细对得上、批量导入有没有做行级校验，这三件事做到位，这套东西就能从"能演示"变成"能用"。

建议第一次部署时按本文顺序走一遍：先单独起后端，用 curl 验证登录和鉴权；再起前端，确认代理通；然后按模块逐个验证权限和业务联动；最后压一批数据看分页和导出的表现。这套流程跑下来，你对整套系统的理解会比读十遍代码都深。