简介：面向Java Web初学者与课程设计开发者的一套家庭健康管理实战项目源码，围绕家庭成员档案、健康指标上报与健康报告生成等场景，帮助读者理解SSM框架下从需求分析到功能落地的完整实现路径。压缩包共107个文件、约806KB，以34个Java源文件承载后端业务逻辑，21个JSP页面与2个HTML文件构成前台界面，17个XML配置文件负责框架与映射配置，另有JS、CSS及Bootstrap相关样式脚本支撑交互与布局，并附SQL脚本便于快速建库。资源涵盖家庭管理、成员管理、指标管理、用户管理、指标上报和健康报告等模块，界面管理、核心功能与辅助功能分层设计，适合用作毕业设计参考或SSM入门练手。目前已有42人学习下载，可据此对照梳理项目结构、理解前后台协作方式并积累排错经验。
1. 家庭健康管理系统：一个把体检报告搬进浏览器的 SSM 实战项目
去年帮一个做社区健康服务的团队看代码，他们用 Excel 管老人血压血糖，三个月就攒了两百多个文件，谁改过哪一行全靠文件名后缀区分。后来换成一套基于 SSM 的家庭健康管理系统，录入、查询、趋势对比全在一个页面里完成，才算把这件事从“人肉对账”里捞出来。这个项目用 Java 做后端、HTML 做前端，核心就两块：家庭成员档案和健康指标记录。它适合两类人——想找一个结构完整、能直接跑起来的 SSM 练手项目的学生，以及需要给小型健康服务场景做二次开发的一线开发者。技术栈不花哨，但分层清楚，指标管理这条链路从表结构到页面渲染都是通的，拿来做健康管理类需求的起点很合适。
2. 技术栈与目录结构：SSM 三层怎么落到健康指标这条线上
2.1 为什么是 SSM 而不是 Spring Boot
这个项目选的是传统 SSM（Spring + SpringMVC + MyBatis）组合，没有上 Spring Boot。放在今天看有点“老派”，但对家庭健康管理这种业务量不大、部署环境简单的系统来说，反而省事：不用管自动配置的玄学，XML 里写了什么容器就加载什么，排查问题时链路是明面上的。常见做法是 Spring 管 Service 和事务、SpringMVC 管请求分发、MyBatis 管 SQL 映射，三层各司其职。
依赖上一般会看到这些坐标：spring-context、spring-webmvc、spring-jdbc、mybatis、mybatis-spring、mysql-connector-java、druid连接池，外加jstl和servlet-api。版本不用追新，JDK 8 配 Spring 5.x 是这套组合里最稳的搭配，Tomcat 8.5 或 9 都能跑。我一般会把版本号统一提到pom.xml的properties里，避免后面改一处漏一处。
<!-- pom.xml 关键依赖，版本统一在 properties 管理 --> <properties> <spring.version>5.3.30</spring.version> <mybatis.version>3.5.13</mybatis.version> </properties> <dependencies> <!-- Spring 核心与 Web MVC --> <dependency> <groupId>org.springframework</groupId> <artifactId>spring-webmvc</artifactId> <version>${spring.version}</version> </dependency> <!-- MyBatis 与 Spring 整合包，缺了它 SqlSession 注入不进来 --> <dependency> <groupId>org.mybatis</groupId> <artifactId>mybatis-spring</artifactId> <version>2.1.2</version> </dependency> <!-- MySQL 驱动，注意 8.x 驱动类名带 cj --> <dependency> <groupId>mysql</groupId> <artifactId>mysql-connector-java</artifactId> <version>8.0.33</version> </dependency> </dependencies>这段配置里有两个参数值得留意：mybatis-spring的版本要和 MyBatis 主版本对齐，2.x 配 3.5.x；MySQL 驱动 8.x 的连接串要带serverTimezone，否则启动时报时区错误是高频翻车点。依赖拉不下来时先看本地仓库有没有残缺的.lastUpdated文件，删掉重拉比反复改镜像快。
2.2 目录结构：按层分包，指标模块独立成块
项目是标准的 Maven Web 工程，src/main/java下按controller / service / service.impl / mapper / entity分包，src/main/resources放 Spring 和 MyBatis 的 XML，src/main/webapp放 JSP 或静态 HTML 加WEB-INF。健康指标相关的类集中在entity/HealthIndicator.java、mapper/HealthIndicatorMapper.java、service/HealthIndicatorService.java这条线上，找代码时顺着指标名一路搜下去就行。
family-health/ ├── src/main/java/com/health/ │ ├── controller/ # 请求入口，MemberController、IndicatorController │ ├── service/ # 业务接口 │ │ └── impl/ # 业务实现，事务注解加在这层 │ ├── mapper/ # MyBatis 接口，与 XML 一一对应 │ └── entity/ # Member、HealthIndicator 等实体 ├── src/main/resources/ │ ├── spring-context.xml # 数据源、事务、Service 扫描 │ ├── spring-mvc.xml # 视图解析器、静态资源放行 │ ├── mybatis-config.xml # 别名、驼峰映射 │ └── mapper/ # 各模块 SQL 映射文件 └── src/main/webapp/ ├── WEB-INF/views/ # JSP 页面 └── static/ # css、js这个结构的好处是边界清楚：Controller 只做参数接收和视图跳转，业务判断全在 Service，SQL 全在 mapper XML。二次开发时加一个新指标（比如血氧），改动点就是实体加字段、mapper 加一条 insert、Service 加一个方法、页面加一个输入框，四步走完，不会牵一发动全身。坏处是文件多，新手第一次打开容易迷路，建议先顺着web.xml找到 DispatcherServlet 的配置，再顺着spring-mvc.xml的组件扫描路径反推包结构，比盲翻快得多。
2.3 配置文件之间的咬合关系
SSM 项目跑不起来，八成是几个 XML 没咬合上。web.xml里要配ContextLoaderListener加载spring-context.xml，再配DispatcherServlet加载spring-mvc.xml，两个容器一个管 Service 一个管 Controller，扫描包不能重叠，否则事务不生效或者 Bean 重复创建。spring-context.xml里配数据源、SqlSessionFactoryBean、MapperScannerConfigurer和事务管理器；spring-mvc.xml里配注解驱动、视图解析器前缀后缀、静态资源放行。
<!-- spring-context.xml 片段：数据源与 MyBatis 整合 --> <bean id="dataSource" class="com.alibaba.druid.pool.DruidDataSource"> <property name="url" value="jdbc:mysql://localhost:3306/family_health?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai"/> <property name="username" value="root"/> <property name="password" value="123456"/> </bean> <bean id="sqlSessionFactory" class="org.mybatis.spring.SqlSessionFactoryBean"> <property name="dataSource" ref="dataSource"/> <!-- 驼峰映射开着，数据库 create_time 才能自动对上 createTime --> <property name="configuration"> <bean class="org.apache.ibatis.session.Configuration"> <property name="mapUnderscoreToCamelCase" value="true"/> </bean> </property> </bean> <!-- 扫描 mapper 接口，和 XML 同包同名即可自动绑定 --> <bean class="org.mybatis.spring.mapper.MapperScannerConfigurer"> <property name="basePackage" value="com.health.mapper"/> </bean>mapUnderscoreToCamelCase这个开关是血泪经验：不开的话，实体里createTime永远拿到 null，查半天以为是 SQL 写错了。连接串里的characterEncoding=utf8也别省，中文姓名和备注字段乱码基本都出在这。事务管理器用DataSourceTransactionManager，在 Service 实现类上打@Transactional，注意扫描包要包含 service 包，且不要和 mvc 容器的扫描范围交叉。
3. 核心模块拆解：健康指标从录入到趋势展示的完整链路
3.1 实体与表结构：指标怎么存才不别扭
健康指标的核心矛盾是“指标种类会变”。今天量血压，明天加血糖，后天可能加血氧，如果每种指标建一张表，加一种就要改表结构、改代码，维护成本高。这个项目采用的是“一条记录一个指标值”的宽表思路：health_indicator表里放member_id、indicator_type、indicator_value、measure_time、unit、remark，指标类型用字典值区分。好处是加新指标不用动表，坏处是查询时要按类型过滤，SQL 稍复杂。
CREATE TABLE health_indicator ( id BIGINT PRIMARY KEY AUTO_INCREMENT, member_id BIGINT NOT NULL COMMENT '关联家庭成员', indicator_type VARCHAR(32) NOT NULL COMMENT '血压/血糖/体重等', indicator_value DECIMAL(10,2) NOT NULL COMMENT '测量值', unit VARCHAR(16) DEFAULT NULL COMMENT '单位，如 mmHg', measure_time DATETIME NOT NULL COMMENT '测量时间', remark VARCHAR(255) DEFAULT NULL, create_time DATETIME DEFAULT CURRENT_TIMESTAMP, KEY idx_member_type_time (member_id, indicator_type, measure_time) );索引idx_member_type_time是这条链路的性能关键：趋势查询永远是“某成员 + 某指标 + 时间范围”，三列联合索引能直接命中。indicator_value用DECIMAL而不是FLOAT，血压 120.5 这种值用浮点存会出现 120.49999 的精度问题，展示时很难看。实体类HealthIndicator字段与表一一对应，measureTime用java.util.Date或LocalDateTime都行，后者配 MyBatis 3.5 以上不用额外类型处理器。
3.2 Mapper 层：按类型和时间范围取趋势数据
Mapper 接口只声明方法，SQL 写在 XML 里。趋势展示需要按成员和指标类型取一段时间内的记录，按测量时间升序返回，前端才能画折线。这里用@Param传参，XML 里用#{}占位，避免拼接注入。
// HealthIndicatorMapper.java public interface HealthIndicatorMapper { // 新增一条指标记录 int insert(HealthIndicator indicator); // 按成员 + 指标类型 + 时间范围查趋势 List<HealthIndicator> selectTrend(@Param("memberId") Long memberId, @Param("type") String type, @Param("start") Date start, @Param("end") Date end); }<!-- HealthIndicatorMapper.xml --> <select id="selectTrend" resultType="com.health.entity.HealthIndicator"> SELECT id, member_id, indicator_type, indicator_value, unit, measure_time, remark FROM health_indicator WHERE member_id = #{memberId} AND indicator_type = #{type} <if test="start != null"> AND measure_time >= #{start} </if> <if test="end != null"> AND measure_time <= #{end} </if> ORDER BY measure_time ASC </select><if>标签让时间范围可选，前端不传就查全部历史，传了就查区间，一个方法覆盖两种场景。resultType直接指向实体，靠驼峰映射把measure_time对到measureTime，不用写resultMap。注意 XML 里>=要写成>=，否则解析报错，这是新手最容易卡住的地方之一。
3.3 Service 层：录入校验与事务边界
Service 层承担两件事：录入时的业务校验，以及把“新增指标 + 更新成员最近测量时间”这类组合操作放进一个事务。校验包括成员是否存在、指标值是否在合理区间、测量时间不能晚于当前时间。合理区间用配置或常量维护，别硬编码在 if 里散落各处。
@Service public class HealthIndicatorServiceImpl implements HealthIndicatorService { @Autowired private HealthIndicatorMapper indicatorMapper; @Autowired private MemberMapper memberMapper; @Override @Transactional(rollbackFor = Exception.class) public void addIndicator(HealthIndicator indicator) { // 成员必须存在，否则指标成了孤儿数据 Member member = memberMapper.selectById(indicator.getMemberId()); if (member == null) { throw new IllegalArgumentException("成员不存在"); } // 测量时间不允许晚于当前时间，防止误填未来日期 if (indicator.getMeasureTime().after(new Date())) { throw new IllegalArgumentException("测量时间不能晚于当前时间"); } indicatorMapper.insert(indicator); // 同步更新成员最近测量时间，列表页排序用 memberMapper.updateLastMeasureTime(indicator.getMemberId(), indicator.getMeasureTime()); } }@Transactional的rollbackFor = Exception.class不能省，默认只回滚运行时异常，校验抛的是IllegalArgumentException属于运行时异常没问题，但后面如果改成受检异常就会静默不回滚。两个写操作放一个事务里，保证成员最近测量时间和指标记录一致，否则列表页排序会出现“有记录但时间没更新”的错位。
3.4 Controller 与页面：一次录入请求的完整走向
Controller 接收表单参数，调用 Service，成功后重定向到列表页，失败带回错误信息。用RedirectAttributes传提示，避免刷新重复提交。页面用 JSP 渲染，表单字段和实体属性同名，SpringMVC 自动绑定。
@Controller @RequestMapping("/indicator") public class IndicatorController { @Autowired private HealthIndicatorService indicatorService; @PostMapping("/add") public String add(HealthIndicator indicator, RedirectAttributes ra) { try { indicatorService.addIndicator(indicator); ra.addFlashAttribute("msg", "录入成功"); } catch (IllegalArgumentException e) { // 校验失败回显原因，不吞异常 ra.addFlashAttribute("error", e.getMessage()); } return "redirect:/indicator/list?memberId=" + indicator.getMemberId(); } }请求链路是：浏览器提交表单 → DispatcherServlet 按@RequestMapping找到方法 → 参数绑定到HealthIndicator→ Service 校验并落库 → 重定向到列表。redirect:前缀触发重定向，配合RedirectAttributes的 flash 属性，提示信息只在下一次请求可见，刷新不会重复弹。列表页再用 JSTL 的<c:forEach>遍历趋势数据，前端 JS 拿数据画简单折线即可，不引入重型图表库也够用。
4. 跑起来：环境准备、建库与启动排查
4.1 环境清单与建库脚本
跑这个项目需要 JDK 8、Maven 3.6+、MySQL 5.7 或 8.0、Tomcat 8.5/9。IDE 用 IntelliJ IDEA 或 Eclipse 都行，前者对 Maven Web 项目支持更顺。建库先执行项目自带的schema.sql，没有的话按第 3 章的建表语句手动建，再插几条测试数据。
# 建库并导入结构 mysql -uroot -p -e "CREATE DATABASE family_health DEFAULT CHARSET utf8mb4;" mysql -uroot -p family_health < sql/schema.sql # 编译打包，跳过测试加快首次启动 mvn clean package -DskipTests打包产物是target/*.war，丢进 Tomcat 的webapps目录，启动后访问http://localhost:8080/family-health/。用 IDEA 的话配一个 Tomcat Server 运行配置，Deployment 里加 exploded artifact，改代码热部署比反复打包快。
4.2 启动报错的排查顺序
启动失败先看日志第一段异常，别从最后一行往上翻。常见顺序是：数据源连不上 → Mapper 绑定失败 → 视图解析 404。数据源问题看连接串的库名、端口、账号密码，以及 MySQL 8 的时区参数；Mapper 绑定失败看接口和 XML 是否同包同名、MapperScannerConfigurer的包路径对不对；404 看spring-mvc.xml的视图前缀后缀和 Controller 返回值是否匹配。
提示：第一次跑建议把日志级别调到 DEBUG，
org.springframework和com.health两个包开 DEBUG，Bean 加载和 SQL 执行都能看到，比猜快得多。
4.3 用测试数据验证指标链路
系统起来后先建一个家庭成员，再录三条同类型指标（比如三天的血压），然后进趋势页看是否按时间升序展示。这一步能同时验证表单绑定、Service 校验、Mapper 查询和页面渲染四条链路。如果趋势页空白但数据库有数据，先查measure_time的时区是否一致，再查前端取字段名有没有拼错。
5. 避坑与常见问题：这套 SSM 组合最容易翻车的地方
5.1 中文乱码：从表单到数据库要过三道关
现象是页面输入的中文姓名存进库变成问号。原因通常有三处：JSP 页面没声明pageEncoding="UTF-8"、web.xml没配CharacterEncodingFilter、数据库连接串缺characterEncoding=utf8。解决是把三处都补齐，过滤器配forceEncoding=true，建库用utf8mb4兼容生僻字和表情。三道关缺一道都会乱，别只改一处就以为好了。
5.2 事务不生效：扫描包重叠是元凶
现象是 Service 里两个写操作，第二个抛异常但第一个没回滚。原因是spring-mvc.xml和spring-context.xml都扫了 service 包，Controller 容器里生成了一个没被事务代理的 Service 实例。解决是 mvc 容器只扫 controller 包，context 容器扫 service 和 mapper 包，两边不重叠。改完重启，日志里能看到事务代理类的名字才算对。
5.3 日期绑定失败：格式不匹配直接 400
现象是提交带日期的表单报 400，日志提示类型转换失败。原因是measure_time传的是2024-05-01 08:30这种字符串，实体是Date，没有注册转换器。解决是在实体字段上加@DateTimeFormat(pattern = "yyyy-MM-dd HH:mm")，或在 Controller 里加@InitBinder注册CustomDateEditor。前端input type="datetime-local"的默认格式带T，提交前用 JS 替换成空格最省事。
5.4 静态资源 404：DispatcherServlet 抢了请求
现象是页面样式全丢，css/js 请求返回 404。原因是web.xml里 DispatcherServlet 映射到/，把所有请求都接管了。解决是在spring-mvc.xml里加<mvc:resources mapping="/static/**" location="/static/"/>和<mvc:default-servlet-handler/>，让静态资源走默认 Servlet。配完记得清浏览器缓存，不然改了也看不到效果。
5.5 连接池耗尽：忘了关 SqlSession
现象是跑一段时间后报“等待连接超时”。原因是手写了SqlSession却没在 finally 里 close，或者 Mapper 方法里嵌套查询开了新会话。用mybatis-spring的MapperScannerConfigurer自动管理会话就不会有这个问题，前提是别在 Service 里手动openSession。连接池参数上，maxActive设 20 左右够用，maxWait设 3000 毫秒，超时能快速暴露问题而不是无限等。
6. 二次开发：加一个新指标类型要动哪几处
给这套系统加“血氧”指标，改动点其实很固定，我一般按下面这个顺序走，每步都能单独验证，不会一次改一堆然后不知道哪步错了。
第一步，字典表或常量类里加BLOOD_OXYGEN类型，如果项目用字典表就插一条记录，用常量就加一个枚举值。第二步，前端录入页加一个指标类型选项和对应的单位提示，血氧单位是%，输入范围 0 到 100。第三步，Service 的校验逻辑里补一条区间判断，超出范围直接抛IllegalArgumentException，复用现有的错误回显。第四步，趋势页的类型下拉框数据源跟着字典走，不用改代码。第五步，如果要做异常值提醒，在 Service 落库后加一个判断，超过阈值往提醒表插一条，别在 Controller 里写业务。
// 指标类型枚举，新增类型只改这里 public enum IndicatorType { BLOOD_PRESSURE("血压", "mmHg", 60, 200), BLOOD_SUGAR("血糖", "mmol/L", 2, 30), WEIGHT("体重", "kg", 20, 200), BLOOD_OXYGEN("血氧", "%", 70, 100); // 新增一行即可 private final String label; private final String unit; private final double min; private final double max; IndicatorType(String label, String unit, double min, double max) { this.label = label; this.unit = unit; this.min = min; this.max = max; } // 校验值是否在合理区间，Service 里统一调用 public boolean inRange(double value) { return value >= min && value <= max; } }把区间和单位收进枚举，Service 里就只剩一句if (!type.inRange(value)) throw ...，以后再加指标只动枚举，校验逻辑零改动。验证方法是录一条 99 的血氧看是否通过、录一条 120 的看是否被拦，再进趋势页确认新类型能选到、能出图。这套改法我在几个类似项目里都用过，比在每个 if 里散着写阈值靠谱得多。
从那以后我每次接这类健康管理项目，都先把指标类型做成枚举或字典，再动页面和 SQL，顺序反了就会陷入“改一处崩三处”的循环。希望这个拆解能帮你少走点弯路，把这份源码跑起来、改成自己场景能用的样子。
本文还有配套的精品资源，点击获取
