前阵子正好把一个在线英语阅读分级平台从零到一完整落地，技术栈就是标题里那套：SpringBoot + Vue，配合 Java + MySQL + MyBatis。整个过程踩了不少坑，也总结了一些可以直接复用的经验。这篇文章我会把项目从需求分析、数据库设计、后端接口、前端页面到联调排错完整拆开讲，有需要做类似系统或正在搞SpringBoot+Vue前后端分离项目的朋友，可以直接照着抄作业。

这个平台的核心价值其实很清晰：解决英语阅读材料“千人一面”的问题。不同水平的学习者读同一篇文章，要么太简单没进步，要么太难直接劝退。系统把文章按可读性难度分级，再结合用户当前的阅读水平做推荐和记录跟踪，做成了一个带管理后台的完整闭环系统。

1. 先拆需求：为什么需要一个在线英语阅读分级平台

1.1 分级阅读到底在分什么

先说一个容易被忽略的背景。英语阅读分级不是拍脑袋按文章长度分，而是有专业评估标准的。国际上比较常用的是蓝思值（Lexile）和Flesch-Kincaid可读性公式。蓝思值的核心逻辑大致看两个维度：句子平均长度和词频。高频词越多、句子越短，难度就越低；反之，低频词密集、长句多、从句嵌套深，难度就高。

实际开发里不可能像专业机构那样做复杂的语料分析，所以平台采用了简化方案：管理员在创建文章时，通过系统内置的评估表单给文章打分，系统根据“平均句长 + 低频词占比”的近似公式自动生成一个难度系数区间，再由管理员确认或修正所属等级。评测中心则通过简单的完形填空和阅读理解题，反推用户的当前等级。

正是这个“分级”逻辑，让平台跟普通的文章管理网站区别开来。普通网站只做展示和搜索，平台则多了一层“智能匹配”的规则，后续的所有推荐和记录都围绕这个规则展开。

1.2 选型逻辑：SpringBoot+Vue凭什么

选SpringBoot+Vue其实是这个体量项目的最优解，没有悬念。

先看后端。如果退回几年用传统的SSM（Spring+SpringMVC+MyBatis）写法，光是spring和mybatis的XML配置文件就能堆出一大堆，而且内嵌容器都没有，部署还要单独装Tomcat。SpringBoot把这些全部抹平了，内嵌Tomcat，mvn spring-boot:run或者直接跑main方法就能启动，配置也收敛到application.yml一个文件里。对中小型系统来说，开发效率提升非常明显。

再看前端。Vue这种数据驱动的SPA单页应用，配合Element UI这类组件库，后台管理页面的开发速度确实是传统JSP没法比的。JSP时代前后端耦合在一起，改个按钮颜色都要重新打包发布，联调时两拨人经常互相等。前后端分离之后，前端只调接口，后端只出接口，两边可以并行开工，部署也可以分开。对于这个阅读平台来说，前台阅读页追求流畅交互，后台管理页追求高效操作，本质上就是两种不同的页面形态，用Vue组件化来做非常合适。

1.3 功能模块的全貌

整个系统从使用角色出发，天然分成三条线。

• 学生/普通用户端：注册登录、分级测评、推荐书架、文章阅读器、阅读进度记录、生词本。
• 管理后台：文章资源管理（增删改查、上下架）、难度等级配置、用户管理（禁用/启用、重置密码）、数据统计（用户数、文章数、阅读量）。
• 公共支撑：JWT登录鉴权、统一异常处理、跨域配置、文件上传（文章封面、音频资源）。

这三条线在代码里分别对应前端的三个路由模块和后台的三组Controller。模块的边界在设计阶段就得画清楚，不然后面写代码会出现“管理端的功能散落在用户端Controller里”这种混乱局面。

2. 数据库设计：这几张表是怎么把分级、用户和阅读记录串起来的

2.1 核心表结构概览

数据库是整系统的地基，表结构设计好了，后面写业务就像搭积木。我用了9张核心表，列出来给大家参考：

这里有一个很容易踩的坑：sys_user里的level_id到底是直接存整数等级，还是关联read_level表？我建议一定关联等级表。因为等级不只是“1、2、3”三个数字，它还有难度区间、描述文案、甚至前端展示用的颜色标识。独立成表之后，以后想调整分级标准，只需要改read_level表里的min_score和max_score，不需要动任何业务代码。

2.2 文章和难度的关联方式

read_article表里设计了level_id外键，还有一个score字段用来存文章计算出的具体难度分。为什么不只存一个外键？因为分级的颗粒度不够。两个都存的好处是：列表页可以按具体分数排序，展示时再映射到对应的等级标签。比如分数在400L到600L之间是A级，600L到800L是B级，这种映射关系都在read_level表里统一管理。

文章内容直接存在MySQL的TEXT字段里，不用文件存储。核心原因是内容量级不大，千篇级文章存库完全没问题，而且后期要做关键词检索、内容联动处理，还是数据库更顺手。刚开始做的时候别过早引入Elasticsearch或者OSS对象存储，先把基础流程跑通更重要。

2.3 阅读记录和生词本的设计细节

read_record表是整个系统里数据增长最快的表，设计上有一点必须提前考虑：数据重复。同一个用户反复打开同一篇文章，如果每次都插入一条新记录，表会很快膨胀，统计也会乱。所以我在user_id和article_id上加了联合唯一索引，这样从数据库层面就保证了一条用户-文章组合最多只对应一条记录，后续用INSERT ... ON DUPLICATE KEY UPDATE的写法做更新。

progress字段用来记录阅读进度。这里我一开始存的是百分比整数，后来发现用户可能从第3页跳到第9页，百分比不好还原现场。建议存“当前读到第几页”或者“当前滚动位置”，配合文章总页数或者总字数，前端重新打开时能精确还原位置。

word_book生词本表加了一个source_article_id字段，这个字段特别有用：用户点某个生词时，可以回跳到它最早出现的那篇文章，形成学习闭环。不要小看这个设计，很多学习类产品“收藏了就不再管”的问题，就是因为缺少了来源追溯。

3. 后端落地：SpringBoot+MyBatis里的核心接口与SQL细节

3.1 项目代码结构：controller/service/mapper是怎么分工的

SpringBoot项目结构清晰，代码就好维护。我用的标准分层：

• controller：只做参数接收、参数校验、结果返回，不写业务逻辑。
• service：业务逻辑都在这层，事务注解也加在service方法上。
• mapper：只放MyBatis的Mapper接口，SQL写在XML或者注解里。
• entity：数据库表对应的实体类。
• common：统一返回结果Result、全局异常处理器、JWT工具类、常量类。
• config：跨域配置、MyBatis配置、Web拦截器配置。

统一返回对象长这样：

public class Result<T> { private Integer code; private String message; private T data; public static <T> Result<T> success(T data) { Result<T> result = new Result<>(); result.code = 200; result.message = "success"; result.data = data; return result; } public static <T> Result<T> error(Integer code, String message) { Result<T> result = new Result<>(); result.code = code; result.message = message; return result; } }

前端拿到code为200就处理data，其他code抛出message。配合全局异常处理器，业务代码里可以简洁地抛自定义异常，不用每个方法都写一堆try-catch。

3.2 MyBatis的配置和XML映射实践

MyBatis用了这么多年仍然活跃，核心优势就是SQL可控。Spring Boot整合MyBatis非常简单，引入mybatis-spring-boot-starter即可。有几个配置强烈建议打开：

mybatis: mapper-locations: classpath:mapper/*.xml type-aliases-package: com.example.readplatform.entity configuration: map-underscore-to-camel-case: true

map-underscore-to-camel-case太重要了。没有它，数据库的create_time字段映射到Java的createTime属性会全是null，很多人排查半天发现自己写的实体类属性名跟数据库字段对不上，就是这个配置没开。

再看动态SQL。列表页的搜索条件非常典型：按标题模糊搜索、按等级筛选、按状态筛选，条件是组合的、可选的。用XML动态SQL处理非常舒服：

<select id="pageArticles" resultType="com.example.entity.ReadArticle"> SELECT * FROM read_article <where> <if test="title != null and title != ''"> AND title LIKE CONCAT('%', #{title}, '%') </if> <if test="levelId != null"> AND level_id = #{levelId} </if> <if test="status != null"> AND status = #{status} </if> </where> ORDER BY create_time DESC </select>

<where>标签会自动处理掉第一个条件前面的AND，非常省心。需要注意，LIKE拼接不要用'%'+#{title}+'%'这种写法，建议用CONCAT函数，因为#{}预编译占位符在字符串拼接时不会被插值到SQL里，直接用'%#{title}%'是匹配不到数据的。

关于#{}和${}的区别，再强调一次：#{}是预处理占位符，底层用PreparedStatement，能防SQL注入；${}是字符串替换，直接拼进SQL，有注入风险。能用#{}就用#{}，只有ORDER BY后面的动态排序字段这种实在没办法的场景才用${}，而且必须做白名单校验。

分页直接用PageHelper插件，一行代码就能完成物理分页：

PageHelper.startPage(pageNum, pageSize); List<ReadArticle> list = articleMapper.pageArticles(condition); PageInfo<ReadArticle> pageInfo = new PageInfo<>(list);

注意PageHelper是ThreadLocal实现的，所以startPage必须紧跟第一条查询语句，中间不能插别的查询操作，否则会把分页条件带到不相关的查询上，这是个经典坑位。

3.3 核心接口的实现思路

登录接口。密码用BCrypt加密存储，不要用MD5。MD5是哈希算法，可以被彩虹表反查；BCrypt自带盐值，每次加密结果都不同，即使两条相同密码的密文也不一样。Spring Security里的PasswordEncoder直接可用，不想整套引入Security，单独引入spring-security-crypto依赖也行。

登录成功后签发JWT令牌：

String token = JwtUtil.createToken(user.getId(), user.getUsername(), user.getRoleId());

前端拿到token存进localStorage，后续请求在请求头里加Authorization。后端拦截器负责校验，校验不过直接返回401。JWT的好处是服务端不存session状态，水平扩展时不需要做session同步，适合前后端分离部署的场景。

推荐文章接口。这里只有一个业务规则：根据用户当前等级，从文章表里捞出该等级区间的文章，再排除掉读过的，按阅读量排序。SQL大概长这样：

<select id="recommendArticles" resultType="ReadArticle"> SELECT a.* FROM read_article a WHERE a.status = 1 AND a.level_id = #{levelId} AND a.id NOT IN ( SELECT article_id FROM read_record WHERE user_id = #{userId} ) ORDER BY a.view_count DESC LIMIT 10 </select>

阅读进度接口。这个接口是读写一体的：用户打开文章时调用来获取上次进度，退出时再来提交进度。提交就用前面说的INSERT ... ON DUPLICATE KEY UPDATE语法：

INSERT INTO read_record (user_id, article_id, progress, duration, update_time) VALUES (#{userId}, #{articleId}, #{progress}, #{duration}, NOW()) ON DUPLICATE KEY UPDATE progress = VALUES(progress), duration = duration + VALUES(duration), update_time = NOW()

3.4 事务与数据一致性：别让测评成绩和等级更新“打架”

平台里有一个典型的多步骤写操作：用户提交测评试卷，系统算出分数，然后根据分数更新用户的等级。这一整套动作，必须放在同一个事务里。试想一下，分数算出来了，但更新等级时数据库突然报错，用户看到的结果就是“我做了题但等级没变”，数据就不一致了。

实现上只需要在service方法上加@Transactional：

@Transactional(rollbackFor = Exception.class) public void submitExam(Long userId, Long paperId, Integer score) { // 1. 保存测评记录 examRecordMapper.insert(...); // 2. 根据分数确定新等级 Integer newLevelId = levelMapper.matchLevelByScore(score); // 3. 更新用户等级 userMapper.updateLevel(userId, newLevelId); }

这里有个经验：rollbackFor = Exception.class必须写。因为Spring默认只回滚RuntimeException，如果业务代码里抛出的是受检异常（比如IOException），不加rollbackFor就不会回滚，很容易出问题。

另外，@Transactional还有一个经典失效场景：同一个类里的A方法调B方法，B方法上有@Transactional，这个事务是不生效的。原因是Spring事务基于AOP代理，内部调用不会经过代理对象。解决办法是拆分到不同的Bean里，或者自己注入自己，或者用事务模板TransactionTemplate。我个人的习惯是复杂事务直接用TransactionTemplate，因为它的边界非常明确：

transactionTemplate.execute(status -> { examRecordMapper.insert(...); userMapper.updateLevel(...); return Boolean.TRUE; });

4. 前端实现：Vue组件化开发与HTML+CSS的页面细节

4.1 环境准备：从零到跑起来的前端工程

前端开发环境所需的东西不多：Node.js和npm，不会可以去官网下个长期支持版，一路下一步装完。然后用Vue官方脚手架创建项目：

npm install -g @vue/cli vue create read-frontend

创建过程中会交互式问一些问题：选择Vue 3还是Vue 2，是否安装Vue Router和Vuex/Pinia。对于新项目，优先Vue 3 + Pinia + Vue Router 4。不过如果团队对Vue 2更熟，用Vue 2也完全没有问题，平台这类系统的复杂度还远没到需要吃Vue 3性能红利的地步。

项目创建完之后，要装几个必要的依赖：

npm install axios npm install element-ui # Vue 2 或 element-plus（Vue 3）

装依赖这一步很多人会栽在网速上，特别是依赖包特别多的时候。实测下来用npm官方源可能很慢，换成国内镜像能快很多：

npm config set registry https://registry.npmmirror.com

4.2 页面结构和组件拆分

路由规划直接决定前端的目录结构。我用的路由大致如下：

• /login：登录/注册页
• /home：首页，推荐书架
• /read/:id：阅读器页面
• /words：生词本
• /profile：个人中心
• /admin：管理后台（嵌套路由，含文章管理、用户管理、数据统计）

组件拆分遵循“复用优先”原则。文章卡片组件ArticleCard在首页和管理后台都会用，提取成公共组件；分页组件、等级标签组件、状态开关组件也全部组件化。组件化带来的收益是实打实的：首页调整卡片样式，管理后台的列表样式会同步更新，改一个文件搞定两处。

路由守卫是必须做的：

router.beforeEach((to, from, next) => { const token = localStorage.getItem('token'); if (to.meta.requiresAuth && !token) { next('/login'); } else if (to.path.startsWith('/admin') && localStorage.getItem('roleId') !== '1') { next('/home'); } else { next(); } });

如果没有这层守卫，用户直接在地址栏输入/admin路径就能进入管理后台，权限形同虚设。注意这只做了前端拦截，真正严格的控制还是要靠后端接口的权限校验配合。

4.3 阅读器页面的HTML+CSS细节

阅读器是用户停留时间最长的页面，它的排版质量直接决定了平台的口碑。Vue单文件组件里， 部分就是HTML结构，