企业官网建设流程全解析

1. 项目整体定位与技术选型：为什么是Hadoop、Spark加Spring Boot

1.1 这个系统到底在解决什么问题

去年接了一个学生体质健康信息系统的课程设计项目，要求必须走大数据技术栈，不能像平时交作业那样用单机MySQL糊弄过去。当时第一反应是：体测数据能有多大？一个学校几千人，一年也就几千条记录，至于上Hadoop吗？真正动手之后我才理解，这个课题要的不是“数据量”，而是“数据处理的工程链路”——从原始体测文件采集、分布式存储、离线清洗统计，到Spring Boot对外提供查询接口，最后落到可视化大屏展示。把这套链路跑通，比单纯写一个CRUD管理系统有价值得多。

系统面向的使用场景很明确：学校体育教研室每学年组织学生体测，拿到身高、体重、肺活量、立定跳远、坐位体前屈、50米跑、耐力跑、引体向上或者仰卧起坐这些原始成绩，然后要回答几个问题：全校整体体质合格率是多少？各年级、各班级的BMI分布如何？某个学生连续几年的肺活量趋势是上升还是下降？哪些男生的耐力跑成绩明显低于标准？

如果只看单个问题，Excel就够了。但要把这些数据统一存起来、定期清洗、按多种维度聚合，再供大屏和管理端使用，就需要一个分层明确的数据处理流程。这个项目最终拆成三块独立模块：Hadoop负责原始文件的分布式存储；Spark负责把杂乱的体测文件清洗成结构化指标，并完成统计聚合；Spring Boot只负责读Spark算好的结果，通过REST接口输出给可视化大屏。三块各司其职，改动任何一块都不会把其他模块拖垮。

1.2 三件套分工和核心数据流

先说说三件套各自扮演的角色。Hadoop在这里不是用来堆数据的，而是提供HDFS分布式文件系统和YARN资源调度。体测原始文件按学年、批次上传后，统一落到HDFS目录，比如/physique/raw/2024/。这样做的直接好处是：文件不需要预先整理成严格统一的格式，后续清洗交给Spark任务去处理。

Spark负责的是脏活累活。原始体测数据可能是不同老师录入的Excel转CSV、有的带表头、有的身高单位不统一，甚至有空值行。Spark任务把这些数据读进来，做去重、类型转换、单位统一，然后算出BMI、肺活量体重指数、得分等级等指标，再按班级、年级、性别做聚合统计。最终统计结果写回MySQL，供业务层查询。

Spring Boot处在最上层，它不直接接触HDFS原始数据，而是读MySQL里已经算好的统计表。有人问为什么不直接从HDFS读，我试过，接口响应十几秒起步，而且Spark底层如果没跑起来，接口直接报错。改成“Spark离线算好、Spring Boot只查结果”之后，大屏接口响应基本稳定在100毫秒以内。

这个架构里最关键的认知是：Spring Boot不是数据处理引擎，它只是结果展示的入口。把计算逻辑放到Spark里，把结果缓存到数据库，业务层才能做到轻量、稳定。整个数据流向可以概括为：上传体测文件 → HDFS存储 → Spark清洗统计 → MySQL结果表 → Spring Boot接口 → 可视化大屏。

1.3 为什么不是单机数据库硬扛

这个问题当时纠结了很久。几千条体测数据用Spring Boot加MySQL完全能扛，为什么还要引入Hadoop和Spark？后来我给自己一个合理的解释：这个项目的主体不是“体测数据管理系统”，而是“基于大数据的学生体质健康信息系统”。技术考察点在于你是否能独立搭建集群环境、能否用分布式计算框架完成ETL和统计分析、能否把大数据技术栈和业务展示打通。换句话说，Hadoop和Spark是课程设计的核心考核对象，MySQL只是结果存储附件。

另外一个现实理由是扩展性。如果后续接入多个校区、多个学年的数据，加入了可穿戴设备采集的实时心率、步数等字段，单表单库的查询会迅速劣化。HDFS天然支持文件横向扩展，Spark的分布式算子也能在集群扩容后自动并行。所以即便现在数据量不大，采用这套方案也为后续扩展留了余地。

2. 底层环境：伪分布式搭建与集群演进的实践选择

2.1 起步阶段为什么选伪分布式

课程设计或者毕业设计的环境资源通常很紧张，学校实验室一般给你一台8G内存的虚拟机已经是仁至义尽。这种情况下硬上三节点集群不现实，所以多数人会选择Hadoop伪分布式模式：在单台机器上分别启动NameNode、DataNode、ResourceManager、NodeManager进程，模拟一个最小可用的Hadoop环境。

伪分布式不是阉割版，除了没有多节点的高可用和真正的分布式存储，HDFS的命名空间、数据块复制机制、YARN的任务调度流程都是完整的。在这个模式下，跑Spark任务能完整体验提交任务、查看Application日志、观察Executor日志的过程，这对理解大数据架构至关重要。

我搭建时用的是Hadoop 3.3.x版本，关键配置就三处：core-site.xml里把fs.defaultFS设为hdfs://localhost:9000，hdfs-site.xml里把dfs.replication设为1（单副本），yarn-site.xml里把yarn.nodemanager.aux-services设为mapreduce_shuffle。很多刚接触Hadoop的同学不知道，用Maven打包MapReduce任务时如果报找不到系统类，需要在mapred-site.xml里配置mapreduce.application.classpath，否则提交任务会一直卡在Running状态。

启动顺序也有讲究。先执行hdfs namenode -format格式化NameNode，再运行start-dfs.sh启动HDFS，最后start-yarn.sh启动资源调度。格式化这一步只允许做一次，第二次格式化会把原集群的clusterID搞乱，导致DataNode起不来。我后面会专门讲这个坑。

2.2 从伪分布式到HA集群：Hadoop和Zookeeper整合的触发点

很多人看到“hadoop和zookeeper整合实战”这个热搜词会疑惑，伪分布式不是已经能用了吗，为什么还要加Zookeeper？答案很简单：伪分布式只有一台机器，NameNode挂了整个集群就歇菜。进入HA（高可用）模式后，集群至少有两台NameNode，一台Active一台Standby，需要Zookeeper来协调谁当主、谁从Standby切到Active。

真正把Hadoop和Zookeeper整合起来，通常发生在两种场景：一是课程设计要演示高可用能力，二是生产环境不允许单点故障。Zookeeper在这里承担两个职责：维护NameNode的主备状态，以及存储HDFS的命名空间编辑日志（通过JournalNode）。配置主线是：先启动Zookeeper集群，再配置hdfs-site.xml里的nameservices、dfs.ha.namenodes.xxx、dfs.namenode.rpc-address等参数，然后配置dfs.ha.automatic-failover.enabled=true，最后执行hdfs zkfc -formatZK格式化Zookeeper状态存储。

如果你做的是单机伪分布式，Zookeeper不是必需项。但面试或者答辩时一定会被问到“如果NameNode挂了怎么办”，所以哪怕不在项目里实际部署，也要把整合思路讲清楚。我用三个节点实际验证过：手动把Active NameNode进程杀掉，大约10秒内Standby节点通过Zookeeper完成状态切换，客户端连接自动恢复到新主节点。

2.3 环境变量和本地调试的坑

Hadoop环境里最容易忽视的是环境变量和本地库。在Windows本机调试Spark任务去读HDFS时，经常报找不到Hadoop native库的错误。解决办法是下载对应Hadoop版本的winutils.exe和hadoop.dll，放到Hadoop解压目录的bin文件夹，并在HADOOP_HOME环境变量指向该目录。否则每次跑Spark作业都会出现平台相关的权限异常，看起来像代码问题，其实是本地库缺失。

还有一个容易踩的坑是用别人“已编译jar包”。网上有些教程会提供已经编译好的Hadoop二进制包，但你必须确认这个包对应的Hadoop版本和你系统JDK版本是否一致。比如用JDK 11编译的Hadoop 3.3包，放到JDK 8环境里启动ResourceManager，会直接抛UnsupportedClassVersionError。我在项目里坚持用Apache官方源码包，避免这种黑盒问题。

2.4 Docker镜像作为快速验证方案

如果你实在不想花一下午搭建伪分布式，还有一条捷径：直接用现成的Hadoop Docker镜像。国内外社区都有维护好的单节点Hadoop镜像，一个docker-compose.yml就能把NameNode和DataNode拉起来，端口映射出来直接访问NameNode UI。这种方式非常适合前期把Spark代码跑通、验证数据链路，毕竟环境问题不应该卡住你一周。

不过我不建议直接把Docker容器当作最终交付环境。答辩时老师大概率会问底层配置细节，如果你只说“我用镜像拉起来就跑”，会显得对底层原理不熟悉。更好的做法是：先用Docker快速验证Spark计算逻辑，再手动搭一遍伪分布式集群作为正式演示环境。两条腿走路，既节省时间又经得起追问。

3. 数据处理主链路：从体测原始数据到Spark统计指标

3.1 原始数据字段设计与样本格式

数据格式设计决定了Spark清洗的工作量。体测原始数据字段一般包括：学号、姓名、性别、年级、班级、身高、体重、肺活量、立定跳远、坐位体前屈、50米跑、800米或1000米跑、引体向上或仰卧起坐。注意耐力跑男生是1000米，女生是800米，引体向上主要针对男生，仰卧起坐针对女生。如果字段设计不合理，后面按性别统计会很痛苦。

我采用JSON Lines格式，每条记录占一行，方便Spark按行读取。样例数据是这样：

{"student_id":"20230101","name":"张三","gender":"男","grade":"2023","class_name":"计科2301","height_cm":175.2,"weight_kg":68.5,"vital_capacity_ml":4120,"long_jump_cm":238.0,"forward_bend_cm":12.5,"run_50m_s":7.3,"endurance_run_s":252.0,"pull_ups":8}

这样设计的好处是字段类型一目了然，数字型字段直接以数字类型存储，避免后续再转换。唯一的不足是中文姓名在JSON里需要处理编码，所以我在Spark读取时显式指定encoding("UTF-8")，否则某些环境配置下中文会乱码。

3.2 Spark读取JSON与Schema处理

Spark读取JSON最直接的方式是spark.read.json("hdfs://localhost:9000/physique/raw/2024/*.json")。如果不指定schema，Spark会默认推断所有字段类型，这在大文件场景下会额外扫描一遍数据，效率低还可能推断错误。比如student_id这种包含前导0的字段，容易被推断成整型丢掉0；学号本来就是字符串，如果用数值类型存储，后面接口返回就出问题。

更稳妥的做法是显式定义StructType，把每个字段的类型写清楚。我给这个项目定义的精简schema如下：

from pyspark.sql.types import StructType, StructField, StringType, FloatType, IntegerType from pyspark.sql import SparkSession schema = StructType([ StructField("student_id", StringType(), True), StructField("name", StringType(), True), StructField("gender", StringType(), True), StructField("grade", StringType(), True), StructField("class_name", StringType(), True), StructField("height_cm", FloatType(), True), StructField("weight_kg", FloatType(), True), StructField("vital_capacity_ml", FloatType(), True), StructField("long_jump_cm", FloatType(), True), StructField("forward_bend_cm", FloatType(), True), StructField("run_50m_s", FloatType(), True), StructField("endurance_run_s", FloatType(), True), StructField("pull_ups", IntegerType(), True) ]) df = spark.read.option("encoding", "UTF-8").option("mode", "PERMISSIVE").schema(schema).json("hdfs://localhost:9000/physique/raw/2024/*.json")

mode("PERMISSIVE")的意思是遇到格式错误或者类型转换失败的行，Spark不会直接崩溃，而是把整行置为null并记录坏数据，后续可以过滤掉。这比FAILFAST模式在生产环境里更实用，因为体测原始文件脏数据太常见，比如身高写成“168cm”、体重缺空、耐力跑时间写成“4分20秒”等。

3.3 体质指标计算逻辑与得分分档

清洗完之后，核心是计算体质健康指标。这里有两个必算项：BMI（体重指数）和肺活量体重指数。BMI公式是体重公斤数除以身高米数的平方，即weight_kg / (height_cm / 100) ** 2。在Spark里用withColumn实现：

from pyspark.sql import functions as F df = df.withColumn("bmi", F.round(F.col("weight_kg") / (F.col("height_cm") / 100) ** 2, 2)) df = df.withColumn("vital_index", F.round(F.col("vital_capacity_ml") / F.col("weight_kg"), 2))

计算出来只是数值，实际统计时要按国家标准分档。BMI的分档一般是：低于18.5为低体重，18.5到23.9为正常，24到27.9为超重，28以上为肥胖。用when和otherwise表达式就能完成：

df = df.withColumn( "bmi_level", F.when(F.col("bmi") < 18.5, "低体重") .when(F.col("bmi") < 24, "正常") .when(F.col("bmi") < 28, "超重") .otherwise("肥胖") )

同时还需要根据各项成绩打一个综合等级。我在项目里简化处理：先根据耐力和引体向上/仰卧起坐单项及格线判断是否合格，再把体检指标加权汇总，最后按分数分成优秀、良好、及格、不及格四档。具体算法不复杂，关键是这个步骤完全在Spark DataFrame里完成，几百行数据处理不到几秒钟就出了结果。

3.4 统计结果落库：写MySQL还是回写HDFS

计算完每个学生的指标之后，下一步是聚合统计并落库。我最终选择把统计结果写入MySQL，而不是留在HDFS上。原因是Spring Boot项目里MySQL操作最顺，MyBatis-Plus直接查表就能用，省去额外引入查询引擎。Spark写MySQL的标准方式是使用df.write.jdbc(url, table, properties)：

props = { "user": "root", "password": "your_password", "driver": "com.mysql.cj.jdbc.Driver" } df.groupBy("grade", "class_name", "gender") \ .agg( F.count("student_id").alias("student_count"), F.round(F.avg("bmi"), 2).alias("avg_bmi"), F.sum(F.when(F.col("bmi_level") == "肥胖", 1).otherwise(0)).alias("obesity_count") ) \ .write.mode("overwrite").jdbc("jdbc:mysql://localhost:3306/physique_db", "class_health_summary", props)

mode("overwrite")适合每次Spark任务重新计算后整体刷新统计表，保证大屏数据是最新的。要注意的是，Spark写JDBC的并发和分区策略不一定最优，如果统计表数据量大，可以在性能方面调整分区数。对于课程设计这个量级，直接写没任何压力。

如果把结果回写HDFS，也有一个好处：保留了中间层数据，方便随时用Spark重新跑历史统计。但Spring Boot读HDFS数据比较麻烦，通常还得引入Hive或者对象存储客户端，链路会变长。我对这个项目的建议是：中间结果只保留最细粒度的指标数据在HDFS，聚合统计结果写MySQL；两者职责不同，不要混用。

4. Spring Boot服务端：数据访问与接口聚合设计

4.1 模块化项目结构怎么拆

Spring Boot单模块跑通所有业务是最简单的，但代码写多了会非常混乱。这个项目我拆成了四个模块，用Maven管理：

• physique-parent：父工程，统一管理依赖版本。
• physique-common：公共实体类、统一返回体Result<T>、异常处理。
• physique-server：核心业务模块，包含Controller、Service、Mapper。
• physique-api：对外接口模块，打包成独立服务。

典型目录结构如下：

physique-server ├── controller │ ├── DashboardController.java │ ├── StudentController.java │ └── ReportController.java ├── service │ ├── HealthStatService.java │ └── impl │ └── HealthStatServiceImpl.java ├── mapper │ ├── ClassHealthSummaryMapper.java │ └── StudentPhysicalMapper.java └── config ├── CorsConfig.java └── MybatisPlusConfig.java

模块分离的好处是改接口层不碰公共服务，改实体类不碰Controller，对于多人协作的课设项目尤其重要。而且Spring Boot的自动配置在多模块下反而更清晰，@SpringBootApplication放在physique-server里，其他模块依赖它打包出的Jar即可。

4.2 Spring Boot版本选择与依赖管理

版本选择这个坑，真的值得单说。很多同学上来就用最新版Spring Boot 3.x，然后发现MyBatis-Plus插件不能用、javax.*包找不到、Druid连接池配置失效。Spring Boot 3.x要求JDK 17起步，如果你本地是JDK 8，直接启动报错。我推荐用Spring Boot 2.7.x作为课程设计和技术学习的稳定方案，因为它对JDK 8和Java EE生态的支持非常成熟。

项目里关键依赖是MyBatis-Plus和Druid。MyBatis-Plus 3.5.x对Spring Boot 2.7.x兼容性很好，基本是引入依赖、扫描Mapper就能用。Druid连接池配置也很顺手：

spring: datasource: url: jdbc:mysql://localhost:3306/physique_db?useUnicode=true&characterEncoding=UTF-8&serverTimezone=Asia/Shanghai username: root password: your_password driver-class-name: com.mysql.cj.jdbc.Driver type: com.alibaba.druid.pool.DruidDataSource

这里有个细节，MySQL驱动类名新版本是com.mysql.cj.jdbc.Driver，老版本是com.mysql.jdbc.Driver。如果你用的连接池版本比较老，新驱动类会识别不了。锁版本的时候把MySQL驱动、Druid、Spring Boot统一起来，能避免连锁问题。

4.3 数据访问层和查询优化

因为Spark已经把聚合结果算好了，服务端的Mapper层实际上非常简单。比如查询班级体质汇总，就是MyBatis-Plus的selectList加条件构造器。我贴一段典型的查询：

@Service public class HealthStatServiceImpl implements HealthStatService { @Resource private ClassHealthSummaryMapper classHealthSummaryMapper; @Override public List<ClassHealthSummary> listByGrade(String grade) { LambdaQueryWrapper<ClassHealthSummary> wrapper = new LambdaQueryWrapper<>(); wrapper.eq(ClassHealthSummary::getGrade, grade) .orderByDesc(ClassHealthSummary::getStudentCount); return classHealthSummaryMapper.selectList(wrapper); } }

关键优化点有两个。第一，给表加索引，尤其是grade、class_name、gender这些分组和筛选字段。否则随着数据量增长，MySQL回表查询会越来越慢。第二，避免循环查询，比如大屏需要全校总人数和各年级人数，不要写一个for循环逐年级查询，而是用一条带GROUP BY的SQL整合返回。MyBatis-Plus支持QueryWrapper里的select("grade, count(*) as total")，直接查一个Map列表。

4.4 大屏专用接口的聚合返回设计

可视化大屏通常会在同一屏展示多个图表，如果每个图表都单独请求一个后端接口，不仅请求数量多，而且前端逻辑分散。我给大屏设计了三个聚合接口，每个接口返回一个图表组所需的数据结构：

• /api/dashboard/overview：返回总量卡片数据（总人数、优秀率、良好率、平均BMI、男女比例）。
• /api/dashboard/trend：返回各学年BMI和合格率趋势。
• /api/dashboard/distribution：返回年级/班级维度的分布数据，供柱状图和饼图使用。

统一返回体是Result<T>，结构如下：

{ "code": 200, "message": "success", "data": { "totalStudents": 4820, "excellentRate": 18.6, "goodRate": 42.3, "passRate": 82.9, "avgBmi": 22.3, "genderRatio": { "male": 48.2, "female": 51.8 } } }

一个接口能支撑大屏上四个卡片，前端只调一次就拿到所有概览数据，非常清爽。设计接口时一定要考虑前端渲染成本，能聚合就不要拆散。后端每次多查几张表，对MySQL来说完全不是瓶颈，但前端每次多发起一次HTTP请求，在大屏这种场景上会造成明显的加载等待。

5. 可视化大屏：从数据到图表的落地过程

5.1 大屏布局和视觉设计

大屏不是普通的后台页面，它的环境通常是1920×1080的电视机或者投影幕布。我采用的布局是典型的“上中下结构”：顶部是标题栏，中间区域放核心指标卡片，下方左侧放班级分布柱状图，下方中间放BMI分布饼图，下方右侧放学年趋势折线图。整体配色以深色底加亮色数据为主，深蓝背景配合浅蓝和橙色，这样在LED大屏上不会刺眼，又足够醒目。

布局实现用CSS Grid就够，不需要引入重型框架。为了保证不同分辨率下不变形，我用了transform: scale方案：固定设计稿尺寸1920×1080，页面加载时根据屏幕实际宽高比计算缩放比例，整体缩放大屏容器。这个做法比rem方案稳定得多，也是市面上可视化大屏的常见处理方式。

做这个项目时我参考过百度可视化大屏的技术方案，也看过DataV和Suger这类低代码平台。它们的优点是拖拽即用，但缺点是灵活性有限，而且答辩时不好讲原理。所以我最后还是选择用原生Vue3加ECharts手写，虽然花的时间会多一些，但每个图表如何渲染、数据怎么绑定都一清二楚，答辩环节更占优势。

5.2 ECharts图表绑定与动态刷新

ECharts是大屏图表核心，核心用法是初始化实例、传入option对象。我建议把每个图表封装成一个组件，接收props传入统计数据，内部维护自己独立的echarts实例。

折线图的series数据是用后端接口的trend字段直接映射的：

const trend = [ { year: "2021", avgBmi: 22.5, passRate: 80.2 }, { year: "2022", avgBmi: 22.1, passRate: 82.5 }, { year: "2023", avgBmi: 22.4, passRate: 84.1 }, { year: "2024", avgBmi: 22.3, passRate: 82.9 } ]; option = { xAxis: { type: 'category', data: trend.map(item => item.year) }, yAxis: { type: 'value' }, series: [ { name: '平均BMI', type: 'line', data: trend.map(item => item.avgBmi) }, { name: '合格率', type: 'line', data: trend.map(item => item.passRate) } ] };

动态刷新我用的是setInterval定时轮询，每60秒重新请求一次/api/dashboard/overview。这个频率对学校体测数据的实时性足够，也不会给后端造成压力。要注意的是，组件销毁前必须clearInterval，否则页面切走之后，定时器还在后台请求数据，既浪费资源也会导致报错。

如果你考虑实时性更强的场景，比如体质监测设备实时上报，那建议用WebSocket而非轮询。但课程设计的体测数据一天最多更新一次，轮询方案简单可靠，完全够用。

5.3 大屏渲染性能优化技巧

大屏常见问题是图表太多导致页面卡顿。我的经验是控制图表实例数量，借助ECharts的setOption做增量更新，而不是每次数据变化都销毁重建实例。

chart.setOption(option, { notMerge: true, lazyUpdate: true });

这里notMerge: true表示整体替换数据项，lazyUpdate表示延迟到下一帧再更新，能有效减少频繁请求时的抖动。另一个优化是关闭ECharts中不必要动画，尤其是数据量大的柱状图，动画反而会造成视觉卡顿。用animation: false可以减少渲染开销。

如果前端渲染上千条数据，还要考虑对原始数据进行聚合再渲染。比如趋势图看的是年度变化，前端只需要拿到12个点；如果后端一次性返回几千条明细，前端反而要做大量DOM操作。这也是我在后端接口里做聚合而不是把明细抛给前端的原因。大屏的数据查询粒度，永远要比明细层高一个维度。

6. 部署调试全流程复盘：踩过的坑与排查思路

6.1 Hadoop节点起不来，症状像“数据目录损坏”

做伪分布式时最典型的故障是：第一次跑通之后，第二天重启机器发现jps看不到NameNode进程，日志里提示Incompatible clusterIDs或者Storage directory already exists。根因几乎都是重复格式化NameNode，导致同一个DataNode节点上记录的集群ID和NameNode的集群ID不一致。

排查思路要按链路走：先执行jps确认哪些进程存在，再去logs/hadoop-xxx-namenode-xxx.log里看具体异常，然后比对namespaceID和clusterID。如果确认是格式化导致的不一致，最简单的解决办法就是停掉所有Hadoop进程，删除/tmp/hadoop-*下的临时数据目录，然后重新格式化NameNode。前提是HDFS里没有必须保留的数据，否则别删。

这个坑对于课程设计项目来说是必考的踩坑点，因为初学者几乎都会格式化两次以上。我在实际调试中还遇到一个变体：Windows虚拟机突然断电，DataNode重新启动后一直尝试连接原NameNode失败，后来通过清理dfs/nn和dfs/dn目录下的VERSION文件并重建集群才恢复。

6.2 Spark读取JSON时的字段类型问题

跑Spark任务时常见的现象是：某个字段统计出来全是null，或者某一行记录直接消失。第一次遇到时以为是数据本身问题，后来排查发现是Schema定义和实际数据不一致。最典型的是字符串类型的字段被显式定义成数值类型，导致脏数据整行被丢弃。

我当时用df.printSchema()排查，发现vital_capacity_ml偶发出现null。进一步用df.filter(df.vital_capacity_ml.isNull()).show(20)查看问题数据，结果是某几行记录里肺活量字段写成了"4120ml"这种带单位的值，Spark在PERMISSIVE模式下无法转换，直接把字段置空。解决办法是清洗时用正则表达式提取纯数字：

from pyspark.sql import functions as F df = df.withColumn( "vital_capacity_ml", F.regexp_extract(F.col("vital_capacity_ml_raw"), r"(\d+)", 1).cast("float") )

这个经验说明一个问题：Spark读文件时，80%的报错不是集群问题，而是数据格式问题。拿到一批新数据后，先不要急着算指标，先跑一版show()和printSchema()，观察数据长什么样，再写清洗逻辑，效率会高很多。

6.3 Spring Boot版本太高引发的依赖冲突

Spring Boot版本选择不当会引发连锁反应。我的一个同学从网上找了一个项目模板，把Spring Boot升级到3.2.x，结果项目里所有原本在javax.servlet包下的代码全部编译报错。因为自Spring Boot 3.0起，官方把Java EE API从javax迁移到了jakarta，如果你的代码或者第三方依赖还在用老包名，必须全面替换。

排查依赖冲突的最快方法是执行mvn dependency:tree，查看引入的依赖路径。比如我在调试Druid连接池时，发现项目里有不同版本的javax.servlet-api和jakarta.servlet-api同时存在，导致运行时注入HttpServletResponse报错。锁版本之后问题消失。

对于课程设计，我给一个实际建议：不要追求最新版本，选Spring Boot 2.7.x加JDK 8/11即可。网上大多数教学资料、开源模板都基于这个组合，遇到问题时更容易查资料。等把大数据链路跑通，再回头尝试升级到Spring Boot 3.x也不迟。

6.4 大屏接口跨域与超时问题

大屏前端一般跑在独立的开发服务器上，比如Vite默认代理到http://localhost:8080的Spring Boot服务。前端配置代理后正常情况下不存在跨域问题，但如果你直接部署时前端静态资源由Nginx代理、后端独立端口，就会出现跨域。这时需要在Spring Boot配置CorsFilter。

Spring Boot 2.4之后，allowedOrigins对跨域来源有限制，推荐用allowedOriginPatterns。我项目里配置如下：

@Configuration public class CorsConfig implements WebMvcConfigurer { @Override public void addCorsMappings(CorsRegistry registry) { registry.addMapping("/api/**") .allowedOriginPatterns("*") .allowedMethods("GET", "POST", "PUT", "DELETE", "OPTIONS") .allowedHeaders("*") .allowCredentials(true) .maxAge(3600); } }

另一个常见问题是超时。大屏第一次打开时，如果Spark任务还在跑或者MySQL连接池还没有预热，接口可能要等好几秒。解决思路有两个：一是给启动流程加一个定时预热任务，项目启动后主动调用几次查询接口；二是把Spark批处理任务定时凌晨执行，保证大屏访问时只查MySQL结果表。后一种方案才是根本解法。

6.5 一条完整排查链路：大屏数据为什么不对劲

以“大屏显示的总人数和实际体测人数不一致”为例，完整排查链路是这样的：先在浏览器按F12查看Network面板，确认接口返回的数据是多少；如果总数少了200人，再查后端接口SQL，看是不是WHERE条件多加了grade参数；如果SQL正常，再回头查MySQL统计表里到底有多少行；如果MySQL数也对，问题就出在Spark任务本身，大概率是清洗时把某些脏数据的整行丢弃了。

那一次就是我把“性别”字段中少数“男 ”带空格的记录清洗成了null，然后Spark的count在过滤null时直接忽略掉了。最终解决办法是在groupBy之前统一trim所有字符串字段：

df = df.withColumn("gender", F.trim(F.col("gender")))

这条排查链路其实可以提炼成通用方法：从最终展示端往前一层一层回查。先看前端拿到的数据，再看接口返回，再看SQL结果，再看数据源。每一步用最容易观察的环节切分，不要一头扎进日志里盲目翻找。这套方法在Spark和Spring Boot联调时尤其好用。

如果现在重新做一遍，我会调整哪些地方

项目跑到后期我才意识到，真正影响开发效率的往往不是技术难度，而是没有在开始前梳理清楚“哪些功能用Spark离线算，哪些功能用Spring Boot实时查”。如果让我重做一遍，我会在一开始就画好数据分层的边界：原始文件只进HDFS，中间指标数据只保留在Spark计算层，聚合结果只落MySQL，前端只读聚合接口。每层职责单一，调试时定位问题会快很多。

另外我会把Spark任务的运行方式改成通过spark-submit脚本提交，而不是在IDE里直接跑。IDE运行Spark任务容易和本地Hadoop配置纠缠在一起，作者本人开发机可以跑，换一台机器就各种环境问题；改用spark-submit后，提交命令是标准的，环境差异只反映在配置文件里，可复现性更好。

最后一个经验是文档同步问题。这个项目有源码、有文档还要调试，如果文档和代码不同步，过了两周自己都看不懂。我在项目里维护了一个简单的MARKDOWN文档，记录每次修改的数据字段、Spark任务入口、接口返回结构。虽然麻烦，但在答辩前整理材料时会发现，那些随手记录的细节才是最终报告里最有价值的内容。做大数据项目，数据要分层，代码要分层，文档同样要分层。