SSM实战：图书管理系统全链路解析与避坑指南

简介这份资源面向正在学习 Java Web 与 SSM 框架整合的初学者及课程设计开发者提供一套可直接运行的图书信息管理系统完整工程帮助读者理解 Spring MVC、Spring 与 MyBatis 三层架构的协作方式并可作为毕业设计或实训项目的参考底稿。压缩包共 188 个文件约 55.89MB以 103 个 jar 依赖包和 28 个 xml 配置为主辅以 12 个 java 源码、12 个 class 编译文件、7 个 jsp 页面、6 个 properties 配置及 2 个 sql 脚本覆盖依赖库、映射配置、控制器与实体类、前端页面和建库脚本等完整环节工程结构清晰便于按模块对照学习。目前已有 1120 人学习下载。读者可从中获得一套可部署于 MyEclipse/Eclipse Tomcat MySQL 环境的 SSM 整合范例借助实体、Mapper、Service 与 Controller 的分层代码理解请求流转与数据库映射并参考 sql 脚本快速还原数据表适合作为框架入门与项目复现的实践素材。1. 图书信息管理系统一个能跑通 SSM 全链路的练手项目接手一个老系统的维护任务时最怕的不是代码烂而是根本不知道一个请求从浏览器发出后到底经过了哪些层才落到数据库。这份基于 Spring MVC Spring MyBatis 的图书信息管理系统恰好把这条链路完整摊开在你面前浏览器点一下“查询图书”请求穿过 DispatcherServlet、Controller、Service、Mapper最后变成一条 SQL 打到 MySQL再原路返回渲染成页面。它不追求花哨功能图书的增删改查、分页、条件检索就是全部业务但 SSM 三层怎么粘、XML 映射怎么写、事务边界划在哪全都摆在明面上。适合刚学完三大框架、想找个完整项目把知识串起来的新手也适合需要一份干净 SSM 骨架做二次开发起点的熟手。下面按“能干什么、怎么跑、怎么改”的顺序拆。2. 技术栈与目录结构SSM 三层怎么落到文件夹上2.1 选型逻辑为什么是 Spring MVC Spring MyBatis 而不是别的这套组合在图书管理这类中小型业务里几乎是标配原因不复杂。Spring MVC 负责 Web 层把 URL 和 Controller 方法做映射参数绑定、返回值序列化这些脏活它全包了Spring 作为容器管理 Bean 的生命周期和依赖注入同时用声明式事务把 Service 层的方法圈起来MyBatis 负责持久层SQL 写在 XML 里字段和对象属性的映射关系一目了然改 SQL 不用动 Java 代码。三者各管一段边界清晰。对比一下常见替代方案就明白取舍了。用 JPA/Hibernate 的话复杂查询和分页往往要跟 Criteria API 较劲图书检索这种带多条件拼接的场景反而更绕用纯 JDBC 则要手写连接管理和结果集映射重复代码多。MyBatis 的 XML 映射在“SQL 要能随时调”的项目里优势明显DBA 看一眼 XML 就知道这条语句干了什么。这套选型的代价是配置文件偏多Spring 的 XML、MyBatis 的 XML、Web 的 XML 三份要维护但对学习来说配置多恰恰意味着每一层的装配过程都看得见不是被 Spring Boot 的自动配置一把藏起来。2.2 目录结构一个请求会经过哪些文件标准 Maven Web 工程的结构大致如下每个目录对应一层职责book-manager/ ├── pom.xml └── src/main/ ├── java/com/example/book/ │ ├── controller/ # Spring MVC 控制器 │ ├── service/ # 业务接口 │ │ └── impl/ # 业务实现事务在这里 │ ├── mapper/ # MyBatis Mapper 接口 │ ├── entity/ # 图书等实体类 │ └── util/ # 分页、日期等工具 ├── resources/ │ ├── spring-context.xml # Spring 容器 事务 │ ├── spring-mvc.xml # MVC 视图、扫描 │ ├── mybatis-config.xml # MyBatis 全局配置 │ ├── mapper/ # 各实体对应的 SQL XML │ └── jdbc.properties # 数据库连接参数 └── webapp/ ├── WEB-INF/ │ ├── web.xml # DispatcherServlet 与监听器 │ └── views/ # JSP 页面 └── static/ # css、js一个“查询图书列表”的请求路径是这样的web.xml里配置的DispatcherServlet拦截/下的请求按spring-mvc.xml的组件扫描找到BookControllerController 调BookServiceService 通过注入的BookMapper接口发起查询MyBatis 根据mapper/BookMapper.xml里的 namespace 和 id 找到对应 SQL执行后把结果集映射成Book对象列表一路返回给 Controller最后放进 Model 交给 JSP 渲染。这条链路里任何一环配错页面就是 404 或者 500所以排查问题时按这个顺序倒推最有效。2.3 依赖清单pom.xml 里必须有哪几块依赖版本不必追新SSM 这套组合对版本敏感Spring 5.x 配 MyBatis 3.5.x、MySQL 驱动 8.x 是稳妥搭配。核心依赖分四组!-- Spring 核心与 Web MVC -- dependency groupIdorg.springframework/groupId artifactIdspring-webmvc/artifactId version5.3.30/version /dependency !-- Spring 事务与 JDBC 支持 -- dependency groupIdorg.springframework/groupId artifactIdspring-jdbc/artifactId version5.3.30/version /dependency !-- MyBatis 与 Spring 整合包 -- dependency groupIdorg.mybatis/groupId artifactIdmybatis-spring/artifactId version2.1.2/version /dependency dependency groupIdorg.mybatis/groupId artifactIdmybatis/artifactId version3.5.13/version /dependency !-- MySQL 驱动与连接池 -- dependency groupIdmysql/groupId artifactIdmysql-connector-java/artifactId version8.0.33/version /dependency dependency groupIdcom.alibaba/groupId artifactIddruid/artifactId version1.2.20/version /dependencymybatis-spring这个包容易被漏掉它提供SqlSessionFactoryBean和MapperScannerConfigurer是把 MyBatis 塞进 Spring 容器的桥梁没有它 Mapper 接口注入不进来。连接池用 Druid 是常见做法监控页面在调试连接泄漏时很省事换成 HikariCP 也行改dataSource的 bean 类即可。JSP 还需要javax.servlet-apiscope 设 provided和jstl这两个在 Tomcat 运行时由容器提供打包时不带进去。3. 核心配置拆解三份 XML 如何把三层粘起来3.1 web.xmlDispatcherServlet 与字符编码过滤器web.xml是整个应用的入口声明两件事必须配对前端控制器和编码过滤器。顺序有讲究编码过滤器要排在 DispatcherServlet 前面否则 POST 提交的中文在进入 Controller 之前就已经乱码了。!-- 字符编码过滤器必须放在最前 -- filter filter-nameencodingFilter/filter-name filter-classorg.springframework.web.filter.CharacterEncodingFilter/filter-class init-param param-nameencoding/param-name param-valueUTF-8/param-value /init-param init-param param-nameforceEncoding/param-name param-valuetrue/param-value /init-param /filter filter-mapping filter-nameencodingFilter/filter-name url-pattern/*/url-pattern /filter-mapping !-- Spring MVC 前端控制器 -- servlet servlet-namedispatcher/servlet-name servlet-classorg.springframework.web.servlet.DispatcherServlet/servlet-class init-param param-namecontextConfigLocation/param-name param-valueclasspath:spring-mvc.xml/param-value /init-param load-on-startup1/load-on-startup /servlet servlet-mapping servlet-namedispatcher/servlet-name url-pattern//url-pattern /servlet-mappingforceEncoding设为 true 表示响应也强制用 UTF-8不设的话 GET 请求返回的中文在某些容器下仍会乱。load-on-startup为 1 让 Servlet 在容器启动时就初始化配置错误能早暴露而不是等第一个请求进来才报错。另外还需要一个ContextLoaderListener加载spring-context.xml把 Service 和 DataSource 这些非 Web 层的 Bean 装进根容器和 MVC 子容器形成父子关系——子容器能拿到父容器的 Bean反过来不行这个层级关系决定了 Controller 能注入 Service而 Service 不该依赖 Controller。3.2 spring-context.xml数据源、SqlSessionFactory 与事务这份配置是后端的骨架三块内容数据源、MyBatis 工厂、事务管理器。!-- 读取 jdbc.properties -- context:property-placeholder locationclasspath:jdbc.properties/ !-- Druid 数据源 -- bean iddataSource classcom.alibaba.druid.pool.DruidDataSource init-methodinit destroy-methodclose property nameurl value${jdbc.url}/ property nameusername value${jdbc.username}/ property namepassword value${jdbc.password}/ property nameinitialSize value5/ property namemaxActive value20/ /bean !-- SqlSessionFactory 交给 Spring 管理 -- bean idsqlSessionFactory classorg.mybatis.spring.SqlSessionFactoryBean property namedataSource refdataSource/ property nameconfigLocation valueclasspath:mybatis-config.xml/ property namemapperLocations valueclasspath:mapper/*.xml/ /bean !-- 扫描 Mapper 接口生成代理 Bean -- bean classorg.mybatis.spring.mapper.MapperScannerConfigurer property namebasePackage valuecom.example.book.mapper/ /bean !-- 事务管理器 注解驱动 -- bean idtransactionManager classorg.springframework.jdbc.datasource.DataSourceTransactionManager property namedataSource refdataSource/ /bean tx:annotation-driven transaction-managertransactionManager/mapperLocations用通配符一次加载所有 SQL XML新增实体时只要把 XML 丢进mapper/目录就自动生效不用改配置。MapperScannerConfigurer扫描接口包为每个 Mapper 接口生成动态代理这样 Service 里Autowired注入接口就能直接用背后是 MyBatis 的SqlSessionTemplate在干活。事务管理器选DataSourceTransactionManager配合Transactional注解Service 方法上标一个就自动开启、提交、回滚不用手写commit/rollback。3.3 spring-mvc.xml视图解析器与静态资源放行MVC 子容器的配置重点是视图解析和静态资源。JSP 放在WEB-INF/views下前缀后缀配好Controller 返回book/list就能定位到/WEB-INF/views/book/list.jsp。!-- 只扫描 Controller避免和根容器重复 -- context:component-scan base-packagecom.example.book.controller/ !-- 开启注解驱动处理 RequestMapping 等 -- mvc:annotation-driven/ !-- 视图解析器 -- bean classorg.springframework.web.servlet.view.InternalResourceViewResolver property nameprefix value/WEB-INF/views// property namesuffix value.jsp/ /bean !-- 静态资源交给默认 Servlet 处理 -- mvc:default-servlet-handler/component-scan只扫 controller 包是关键细节。如果这里写成扫整个com.example.bookService 会被 MVC 子容器也扫一遍和根容器里的实例重复事务注解可能失效——这是 SSM 项目里最隐蔽的坑之一。mvc:default-servlet-handler让 css、js、图片这些静态文件绕过 DispatcherServlet否则/static/xxx.css会被当成一个找不到映射的请求返回 404。4. 核心代码链路从 Controller 到 Mapper 的完整实现4.1 实体与 Mapper 接口字段映射的起点实体类就是数据库表的镜像字段名和列名的对应关系靠 MyBatis 的映射规则或者resultMap处理。图书表假设有id、book_name、author、price、stock、category几个字段实体类用驼峰命名book_name对应bookName。开启mapUnderscoreToCamelCase后下划线自动转驼峰省掉大量resultMap手写。public class Book { private Integer id; private String bookName; // 对应 book_name private String author; private BigDecimal price; private Integer stock; private String category; // getter / setter 省略 }Mapper 接口只声明方法不写实现实现由 MyBatis 动态生成public interface BookMapper { // 条件查询 分页 ListBook selectByCondition(Param(keyword) String keyword, Param(category) String category, Param(offset) int offset, Param(limit) int limit); // 统计总数分页要用 int countByCondition(Param(keyword) String keyword, Param(category) String category); int insert(Book book); int update(Book book); int deleteById(Integer id); Book selectById(Integer id); }Param注解给参数起名XML 里就能用#{keyword}引用。多个参数不加Param的话MyBatis 会按arg0、param1这种默认名处理SQL 里写起来容易对不上所以多参数方法一律加注解是稳妥习惯。4.2 Mapper XML动态 SQL 与分页查询条件检索的难点在于“关键字可能为空、分类可能不选”动态 SQL 用if和where解决拼接问题避免手写字符串拼接带来的语法错误和注入风险。mapper namespacecom.example.book.mapper.BookMapper select idselectByCondition resultTypecom.example.book.entity.Book SELECT id, book_name, author, price, stock, category FROM book where if testkeyword ! null and keyword ! AND (book_name LIKE CONCAT(%, #{keyword}, %) OR author LIKE CONCAT(%, #{keyword}, %)) /if if testcategory ! null and category ! AND category #{category} /if /where ORDER BY id DESC LIMIT #{offset}, #{limit} /select select idcountByCondition resultTypeint SELECT COUNT(*) FROM book where if testkeyword ! null and keyword ! AND (book_name LIKE CONCAT(%, #{keyword}, %) OR author LIKE CONCAT(%, #{keyword}, %)) /if if testcategory ! null and category ! AND category #{category} /if /where /select /mapperwhere标签会自动处理开头的AND第一个条件成立时不会拼出WHERE AND这种非法语句。#{}是预编译占位符值走PreparedStatement参数绑定能防注入${}是字符串直接拼接除非拼表名或排序字段否则不要用。分页用LIMIT offset, limitoffset由页码和每页条数算出来countByCondition单独查总数两个查询条件必须完全一致否则会出现“总数 20 条但翻到第 3 页是空的”这种对不上的情况。4.3 Service 层事务边界与分页计算Service 是业务逻辑和事务的落点。图书新增要校验库存非负、书名不重复这些判断放这里Transactional标在方法上抛异常自动回滚。Service public class BookServiceImpl implements BookService { Autowired private BookMapper bookMapper; Override public PageResultBook queryByPage(String keyword, String category, int pageNum, int pageSize) { // 页码兜底防止前端传 0 或负数 if (pageNum 1) pageNum 1; int offset (pageNum - 1) * pageSize; ListBook list bookMapper.selectByCondition(keyword, category, offset, pageSize); int total bookMapper.countByCondition(keyword, category); return new PageResult(list, total, pageNum, pageSize); } Override Transactional(rollbackFor Exception.class) public void addBook(Book book) { if (book.getStock() null || book.getStock() 0) { throw new IllegalArgumentException(库存不能为负); } bookMapper.insert(book); } }rollbackFor Exception.class是血泪经验Spring 默认只对RuntimeException回滚受检异常不触发回滚业务里抛个自定义的受检异常数据就悄悄写进去了。显式声明后所有异常都回滚。分页的offset计算放在 Service 而不是 Controller是为了让分页逻辑只有一处改每页条数时不用满项目找。4.4 Controller参数绑定与视图返回Controller 负责接收请求、调 Service、把结果塞进 Model。查询列表和新增表单提交两个方法最能体现参数绑定的用法。Controller RequestMapping(/book) public class BookController { Autowired private BookService bookService; GetMapping(/list) public String list(RequestParam(defaultValue 1) int pageNum, RequestParam(defaultValue 10) int pageSize, RequestParam(required false) String keyword, RequestParam(required false) String category, Model model) { PageResultBook page bookService.queryByPage(keyword, category, pageNum, pageSize); model.addAttribute(page, page); model.addAttribute(keyword, keyword); model.addAttribute(category, category); return book/list; // 解析为 /WEB-INF/views/book/list.jsp } PostMapping(/add) public String add(Book book, RedirectAttributes ra) { bookService.addBook(book); ra.addFlashAttribute(msg, 新增成功); return redirect:/book/list; } }RequestParam的defaultValue让分页参数缺省时也有值required false让关键字可以为空。Book book这种对象参数Spring 会按字段名自动从请求参数绑定表单里namebookName直接映射到实体属性不用逐个RequestParam。新增成功后用redirect:重定向而不是直接返回视图是为了避免刷新页面重复提交RedirectAttributes的 flash 属性能跨重定向传一次消息重定向后消失适合提示语。5. 避坑与排查SSM 项目最容易翻车的五个地方5.1 启动报 404Controller 根本没被扫到现象是 Tomcat 起来了访问/book/list返回 404日志里没有任何映射信息。原因通常是spring-mvc.xml的component-scan包名写错或者web.xml里contextConfigLocation指向的配置文件路径不对。解决方式是先看启动日志有没有Mapped {[/book/list]}这类行没有就检查扫描包路径和 Controller 上的Controller、RequestMapping是否齐全再确认DispatcherServlet的url-pattern是/而不是/*后者会把 JSP 请求也拦下来导致视图解析失败。5.2 中文乱码POST 和 GET 表现还不一样现象是表单提交的中文书名存进库变成问号或者页面显示乱码。原因分两层POST 乱码是CharacterEncodingFilter没配或顺序不对GET 乱码是 Tomcat 的URIEncoding默认不是 UTF-8。解决上过滤器放最前并设forceEncodingtrueGET 请求则在 Tomcat 的server.xml里给 Connector 加URIEncodingUTF-8或者干脆把查询改成 POST。数据库连接串也要带characterEncodingutf8三层编码统一才彻底。5.3 事务不生效异常了数据还是写进去了现象是 Service 方法里先插入再抛异常结果插入的记录还在。原因常见三种Transactional标在了 Controller 而不是 Service方法不是public异常类型是受检异常而没配rollbackFor。另外如果spring-mvc.xml把 Service 也扫了一遍MVC 子容器里的实例没有事务代理注入到 Controller 的就是这个裸实例。解决是确认注解在 Service 实现类的 public 方法上、rollbackFor显式声明、MVC 扫描范围只留 controller 包。5.4 Mapper 注入失败报 NoSuchBeanDefinitionException现象是启动时提示找不到BookMapper类型的 Bean。原因是MapperScannerConfigurer的basePackage和接口实际包名不一致或者 Mapper XML 的namespace和接口全限定名对不上。还有一种情况是 XML 放在resources/mapper下但mapperLocations写成了classpath*:mapper/*.xml之外的形式通配没匹配到。解决是核对包名、namespace、mapperLocations三处字符串完全一致启动日志里搜mapper关键字看加载了几个 XML。5.5 分页总数和列表对不上翻页出现空页现象是列表显示 10 条、总数显示 25 条翻到第 3 页却是空的。原因是countByCondition和selectByCondition的条件不一致比如列表查了关键字但统计漏了分类条件或者offset算错。解决是把两个查询的条件拼装抽成共用的sql片段用include引用保证条件同源offset用(pageNum - 1) * pageSize统一在 Service 算别在 Controller 和 XML 里各算一遍。6. 二次开发改造从单表 CRUD 扩到多表关联的实操思路拿到这套骨架做二次开发最常见的需求是“图书要带分类表和作者表的信息”单表查询就不够了。改造的核心是把Book实体扩展出关联字段Mapper XML 用resultMap做嵌套映射而不是在 Java 里循环查。下面这个resultMap把图书和分类的一对一关系映射出来resultMap idBookWithCategory typecom.example.book.entity.Book id propertyid columnid/ result propertybookName columnbook_name/ result propertyauthor columnauthor/ !-- 关联分类对象 -- association propertycategoryInfo javaTypecom.example.book.entity.Category id propertyid columnc_id/ result propertyname columnc_name/ /association /resultMap select idselectWithCategory resultMapBookWithCategory SELECT b.id, b.book_name, b.author, c.id AS c_id, c.name AS c_name FROM book b LEFT JOIN category c ON b.category_id c.id where if testkeyword ! null and keyword ! AND b.book_name LIKE CONCAT(%, #{keyword}, %) /if /where /selectassociation处理一对一一对多用collection。列名加c_前缀是为了避免和主表字段重名resultMap里靠column区分。改造时实体类加categoryInfo字段Service 和 Controller 基本不用动因为返回的还是Book列表只是对象里多了关联数据。验证方法是造两条分类数据、三条图书数据其中一条图书的分类为空看LEFT JOIN下这条记录的categoryInfo是否为 null 而不是整个图书丢失——这是关联查询最容易翻车的地方INNER JOIN会把没分类的图书直接过滤掉。另一个高频改造是加操作日志。我的习惯是在 Service 方法上加自定义注解用 Spring AOP 切面拦截把方法名、参数、操作人写进日志表而不是在每个方法里手写日志代码。切面里注意别把Transactional的顺序搞乱日志切面优先级设低一点保证业务事务先提交再记日志否则业务回滚了日志却留下了对账时对不上。改造完一定要跑一遍完整链路验证新增一条带分类的图书查列表看关联字段有没有值改库存看事务有没有生效删一条看关联查询会不会报空指针。我一般会在BookMapper的测试类里把这四个场景写成断言改完 XML 先跑测试再启动 Tomcat比在页面上点半天快得多。从那以后我每次动 Mapper XML 都强制先跑一遍这组断言省下不少“页面看着正常、数据其实错了”的返工。希望帮到你。本文还有配套的精品资源点击获取