JavaEE博客系统实战：Servlet+JSP+MyBatis从零搭建文章列表

学 JavaEE 的人大概都经历过这个阶段：Servlet 会写了，JSP 也认识了，JDBC 连 MySQL 也能跑通了，但真要独立做点什么，又觉得无从下手。这次开一个《JavaEE33-博客系统案例实战》系列，就是想彻底解决这个问题——从零开始撸一个博客系统，第一期先把项目搭起来，再把博客列表这个核心页面做出来，让数据库里的文章真正“晒”到浏览器上。这个项目适合刚学完 JavaEE 基础、准备做完整项目但还不想碰 Spring Boot 的同学，也适合想回顾 Servlet + JSP 经典开发链路的老手。整个系列会往后一直迭代：列表、详情、发布、编辑，最后加一个简单的后台，所以你看不到什么一步到位的炫技，更多的是工程上最稳、最能被复现的做法。

顺带说一句，很多人纠结“学完 Servlet 和 JSP 到底能干什么”，博客系统就是答案。它算不上大项目，但足够完整：列表、详情、分页、搜索、发布、编辑、删除，几乎把 CRUD 应用里会遇到的场景都覆盖了。这篇先把地基打好，后面几期都在这个基础上盖楼。

1. 为什么是博客系统，以及“列表先行”的选型逻辑

1.1 博客系统为什么适合当 JavaEE 练手项目

我在带人入门 JavaEE 的时候，很少推荐学生管理系统、图书馆管理系统这类项目，原因很简单：这些系统太重业务规则，技术点反而单薄。博客系统的业务模型非常直接——文章是核心实体，用户看文章、写文章、改文章，整个过程没有复杂的权限和状态流转，却覆盖了 Web 开发的完整链路。

你可以把它理解成一个“包罗 CRUD 的标准样本”：博客列表是查询，文章详情是单条查询，发布文章是新增，编辑删除是更新和删除。再加上分页、分类筛选、按时间排序、阅读量统计这些周边功能，一个博客系统能把 JavaEE 开发中的高频技能全部串起来。而且博客系统天然是 Web 形态，用户能看到自己的劳动成果——把文章发布出去，刷新页面就能看到效果，这种即时反馈对学习非常有用。

这期的目标是“博客列表”，也就是把数据库里的文章展示到首页。别小看这个功能，从用户视角看，进入博客第一眼看到的就是文章列表，没有列表，详情、发布、后台都无从谈起；从技术视角看，列表背后涉及查询、排序、分页、渲染这几件事，把列表做透了，后续功能就是在这个骨架上做加法。

1.2 先做列表、不做登录，背后的两层原因

我见过很多新手做项目，上来就先把登录注册做完，注册、登录、验证码、改密码折腾一个星期，结果主页还是空的，心态先崩了。博客系统为什么不先做登录？两个原因。

第一，从需求优先级看，博客的第一用户是“读者”，不是“作者”。一个博客系统上线第一天，最需要保证的是用户能打开首页、看到文章。登录注册只是作者写文章时需要的门禁，属于后台功能，优先级天然靠后。先做一个能让内容“被看见”的闭环，比先做一个空壳系统更能验证技术方案是否可行。

第二，从教学节奏看，列表功能涉及的是最核心的“请求→处理→渲染”链路：浏览器发起请求，Servlet 接收参数，调用 Service 查库，拿到数据放进 request 域，转发到 JSP 渲染。这条链路跑通，JavaEE 的骨架你就真正掌握了。登录功能无非是在这条链路前面加一层 Session 判断，本质并没有新增多少技术含量。

说白了一句话：先学会“把数据晒出来”，再考虑“让谁进来写”。

1.3 技术选型：Servlet + JSP + MyBatis + MySQL，为什么不用 Spring Boot

这个系列叫 JavaEE，那技术栈我就尽量贴近经典 JavaEE 路线：Servlet 4.0 + JSP + MyBatis + MySQL + Tomcat 9 + Maven。没有用 Spring Boot，是刻意为之。Spring Boot 的自动配置帮开发者省掉了太多麻烦，但也把底层逻辑藏得太深。你用它写一个 Controller 接收参数、返回数据，十分钟能跑通，可一旦出了问题，你不知道请求是怎么进到容器、Servlet 容器和 Spring 容器是什么关系、过滤器在哪里生效。

用经典 Servlet + JSP，你得自己配置 web.xml，自己处理请求参数，自己决定视图怎么转发。这个过程不是折磨，是在帮你建立 Web 应用的底层心智模型。以后你切到 Spring Boot，会发现框架帮你做的其实就是这些事，只是自动化了。

MyBatis 是我在“纯 JDBC”和“Spring Data JPA”之间做的折中。纯 JDBC 写数据访问太啰嗦，一个查询要写连接、写 PreparedStatement、写 ResultSet 映射，重复代码一大堆；MyBatis 保留了 SQL 的可控性，同时把样板代码收掉，是最适合这个阶段的持久层框架。下面用一张表说明选型思路：

如果你之后想上 Vue3 做前后端分离，这套后端项目也不必推翻：把 JSP 换成返回 JSON 的接口，Servlet 把数据写进 response 的 Writer 里，前端用 axios 去拿，核心的查询、分页逻辑仍然可以复用。到系列后期我会单独讲这个改造思路。

2. 工程骨架搭建：从空目录到能在 Tomcat 里跑起来

2.1 开发环境版本：JDK、Tomcat、MySQL 的匹配关系

很多新手在这个环节就卡住了，原因不是不会写代码，而是版本之间“拧着劲”。先说一个最常见的版本坑：Tomcat 10 和 Tomcat 9 的包名不一样。Tomcat 10 开始把 javax.servlet 换成了 jakarta.servlet，网上流传的老教程大多数写的是 javax.servlet.*，代码照着敲完部署到 Tomcat 10 上直接 ClassNotFoundError。我这个项目用的是 Tomcat 9.0.x + JDK 8 或 11 + MySQL 8.0，这是目前最稳妥也最普及的组合。

JDK 我建议直接用 11，太老的环境会遇到一些新库不支持的问题，太新的 JDK 搭配老 Tomcat 也可能有小毛病。MySQL 用 8.0 没问题，但要注意驱动类名是 com.mysql.cj.jdbc.Driver，不是老版本的 com.mysql.jdbc.Driver，连接 URL 还需要带上时区参数 serverTimezone=Asia/Shanghai，否则会报时区错误。

IDE 这块，有人用 IDEA，有人用 Eclipse，也有人用 VS Code。我这次开发用的是 VS Code，配 Java Extension Pack，插件装好后 Java 的编译、调试、Maven 支持都能用。VS Code 里配 JavaEE 环境，核心是装好 “Extension Pack for Java”，再配合“Tomcat for Java”插件把 war 包部署到 Tomcat。这个组合对内存占用比 IDEA 友好很多，我自己长期在用。

2.2 Maven 工程结构：目录与依赖配置

项目里建的 Maven 工程要打包成 war 包，因为最终要放进 Tomcat 运行。目录结构这样建：

code复制blog/
├── pom.xml
└── src
    └── main
        ├── java
        │   └── com/blog
        │       ├── dao/
        │       ├── entity/
        │       ├── servlet/
        │       └── util/
        ├── resources
        │   ├── mybatis-config.xml
        │   └── mapper/
        │       └── ArticleMapper.xml
        └── webapp
            ├── WEB-INF/
            │   └── web.xml
            ├── css/
            └── list.jsp

明确一下各层职责：entity 放数据库表对应的实体类，dao 放数据访问接口，util 放常量、日期工具之类的工具类，servlet 放控制层。新手最常犯的错误是啥都往 Servlet 里塞——查数据库的代码写在 Servlet 里，封装数据的代码也写在 Servlet 里，一个类几百行。分层不是形式主义，分开之后你会发现每个类的职责清晰了，排查问题也容易了。

pom.xml 里的依赖是另一个重灾区。贴一下核心依赖配置：

xml复制<dependencies>
    <!-- Servlet API，Tomcat 提供，打包时不需要包含 -->
    <dependency>
        <groupId>javax.servlet</groupId>
        <artifactId>javax.servlet-api</artifactId>
        <version>4.0.1</version>
        <scope>provided</scope>
    </dependency>

    <!-- JSP API -->
    <dependency>
        <groupId>javax.servlet.jsp</groupId>
        <artifactId>javax.servlet.jsp-api</artifactId>
        <version>2.3.3</version>
        <scope>provided</scope>
    </dependency>

    <!-- JSTL 标签库 -->
    <dependency>
        <groupId>javax.servlet</groupId>
        <artifactId>jstl</artifactId>
        <version>1.2</version>
    </dependency>

    <!-- MyBatis -->
    <dependency>
        <groupId>org.mybatis</groupId>
        <artifactId>mybatis</artifactId>
        <version>3.5.15</version>
    </dependency>

    <!-- MySQL 驱动 -->
    <dependency>
        <groupId>mysql</groupId>
        <artifactId>mysql-connector-java</artifactId>
        <version>8.0.33</version>
    </dependency>
</dependencies>

注意 Servlet API 和 JSP API 的 scope 是 provided，意思是编译时需要，但打包时不用带进去，因为 Tomcat 自己已经有这两套库了。很多新手没加 provided，结果 war 包把 servlet-api.jar 也打进去了，部署后和 Tomcat 自带的类冲突，报一堆奇怪异常。

2.3 web.xml 与项目启动检查

web.xml 是 JavaEE Web 应用的入口配置文件。Servlet 3.0 以后支持注解扫描，你可以在 Servlet 类上用 @WebServlet 直接声明路径，不一定非要写进 web.xml，但 web.xml 保留着两个作用：配置欢迎页，配置编码过滤器。对于中文系统来说，编码过滤器是生命周期级别的配置，强烈建议写上：

xml复制<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="http://xmlns.jcp.org/xml/ns/javaee"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/javaee
                             http://xmlns.jcp.org/xml/ns/javaee/web-app_4_0.xsd"
         version="4.0">

    <display-name>blog</display-name>

    <welcome-file-list>
        <welcome-file>list</welcome-file>
    </welcome-file-list>

    <filter>
        <filter-name>encodingFilter</filter-name>
        <filter-class>com.blog.servlet.EncodingFilter</filter-class>
        <init-param>
            <param-name>encoding</param-name>
            <param-value>UTF-8</param-value>
        </init-param>
    </filter>
    <filter-mapping>
        <filter-name>encodingFilter</filter-name>
        <url-pattern>/*</url-pattern>
    </filter-mapping>
</web-app>

编码过滤器是我处理中文乱码的第一道防线。请求进来先设 request.setCharacterEncoding("UTF-8")，响应出去之前设 response.setContentType("text/html;charset=UTF-8")，后面数据库连接再带 utf8 参数，三层都统一，乱码基本和你无缘。这一步很多人忽略，等页面出现“��”再去问为什么就晚了。

工程建好后，先别急着写业务代码。用 Maven 的 package 打成 war 包，丢进 Tomcat 的 webapps 目录，启动 Tomcat，访问 http://localhost:8080/blog/，如果能出现 Tomcat 默认的 404 页面或欢迎页处理结果，说明工程能跑起来，接下来再开始填业务逻辑。

3. 数据库设计：文章表决定了博客系统的天花板

3.1 article 表的字段设计与类型选择

博客系统的数据模型不需要多复杂，核心就一张 article 表。但这张表设计得好不好，直接决定后面做详情、做分类、做后台时要返工多少代码。我见过很多培训班项目用一张大宽表硬扛所有需求，字段类型也随意选用，后面索引建不了、排序不对劲，只能推倒重来。这里给出我建议的建表语句，然后逐个字段解释为什么这么建。

sql复制CREATE TABLE article (
    id INT UNSIGNED PRIMARY KEY AUTO_INCREMENT,
    title VARCHAR(200) NOT NULL COMMENT '文章标题',
    summary VARCHAR(500) DEFAULT NULL COMMENT '摘要',
    content TEXT COMMENT '正文内容',
    category VARCHAR(50) DEFAULT '未分类' COMMENT '分类',
    cover_url VARCHAR(255) DEFAULT NULL COMMENT '封面图',
    status TINYINT NOT NULL DEFAULT 1 COMMENT '状态：0草稿 1已发布',
    view_count INT UNSIGNED NOT NULL DEFAULT 0 COMMENT '阅读量',
    create_time DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
    update_time DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP 
        ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
    KEY idx_status_create (status, create_time)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='文章表';

每个字段的选择都有讲究。id 用 INT UNSIGNED 自增主键，无业务含义，稳定且利于索引；title 用 VARCHAR(200) 而不是 TEXT，因为标题长度有限，而且后续可能给标题建索引，TEXT 的查询效率远低于 VARCHAR；summary 设置 500 字符，为列表页的摘要展示预留足够空间；content 用 TEXT 类型，可以存约 6.4 万字的文章，个人博客完全够用，如果有长文需求可以换成 MEDIUMTEXT。

view_count 用 INT UNSIGNED 而不是 BIGINT，是因为单篇文章阅读量很难超过 42 亿，unsigned int 到顶足够用，还能省存储。create_time 用的是 DATETIME，不是 TIMESTAMP。很多教材还在用 TIMESTAMP，但它有 2038 年问题，还受时区影响，一个项目里只要有一次时区没设置对，存进去的时间就乱了。DATETIME 没有时区概念，存进去是什么显示就是什么，做个人博客这种场景最合适。

3.2 状态、时间、编码这三个容易出问题的细节

status 字段我用 TINYINT 而不是 BOOLEAN，这是一个很实际的取舍。布尔类型只有 0 和 1 两个值，看起来够用，但博客文章的状态往往会扩展到“草稿、已发布、已下线、回收站”，用 TINYINT 可以平滑扩展，0、1、2、-1 随便加，完全不用改表结构。查询的时候配一个状态常量类，代码可读性也不会差。这就是典型的“用空间换扩展性”的设计。

编码统一是这张表真正的大杀器。表和字段的字符集一定要明确设成 utf8mb4，不要用 MySQL 默认的 latin1，也别用 utf8——utf8 在 MySQL 里存不了 Emoji 和部分生僻字，utf8mb4 是完整的 Unicode 编码，一个字符最多 4 字节，包括四字节 Emoji 都能存下。现在很多人的文章里混着表情符号、数学符号，用 utf8 存到一半就会报 Incorrect string value，到时候再改表的字符集，比现在多花十倍时间。

在 status, create_time 上建联合索引，是为列表页的默认查询准备的。列表页最常见的查询条件是 WHERE status = 1 ORDER BY create_time DESC，联合索引能同时覆盖两个条件，避免 filesort。数据量小的时候看不出差别，等文章超过几千条，这个索引是救命级别的优化。MySQL 的复合索引遵循最左前缀原则，我把 status 放前面，因为状态是筛选条件，create_time 放后面承担排序。

3.3 初始化测试数据与验证查询

表建好之后，插入几条测试数据，让列表页不至于空荡荡：

sql复制INSERT INTO article (title, summary, content, category, status) VALUES
('我的第一篇博客', '记录从零搭建博客系统的全过程', '这里是正文内容…', 'JavaEE', 1),
('MySQL 表设计的一些心得', '字段类型选择的经验和坑', '这里是正文内容…', '数据库', 1),
('为什么建议先学 Servlet 再学 Spring Boot', '底层认知比框架熟练更重要', '这里是正文内容…', 'Java', 1),
('VS Code 配置 JavaEE 开发环境记录', '从插件安装到 Tomcat 部署', '这里是正文内容…', '工具', 1),
('博客系统系列规划', '未来几个月的更新计划', '这里是正文内容…', '随笔', 0);

注意最后一条我把 status 设成了 0（草稿），这样列表查询时能顺便验证“只展示已发布文章”的逻辑是否生效。数据插入后先到 MySQL 命令行跑一下分页查询，确认 SQL 没问题再进 Java 代码：

sql复制SELECT id, title, summary, category, view_count, create_time
FROM article
WHERE status = 1
ORDER BY create_time DESC, id DESC
LIMIT 0, 5;

LIMIT 的写法有两种，LIMIT offset, size 和 LIMIT size OFFSET offset，MySQL 都支持。分页查询的 offset 计算公式是 (pageNum - 1) * pageSize，这个公式一定要写对，很多新手第一期分页正常，翻到第二页就少一条数据或者重复一条数据，基本都是这里算错了。

4. 后台实现：从 MySQL 到内存的完整链路

4.1 实体类与数据库字段映射

数据库表设计好了，接下来是 Java 端的实体类。这块要说一个 MyBatis 的版本问题：如果你用的 MySQL 驱动是 8.x，MyBatis 是 3.5 以上，那实体类里的时间字段可以直接用 java.time.LocalDateTime，不用再去碰 java.util.Date 那个老古董。LocalDateTime 处理时间格式化更顺手，JSP 页面配合 datetime 解析也干净。实体类就这样写：

java复制public class Article {
    private Integer id;
    private String title;
    private String summary;
    private String category;
    private Integer viewCount;
    private LocalDateTime createTime;

    // 无参构造、有参构造、getter/setter 省略
}

实际上表里还有 content、cover_url、update_time 这些字段，实体类里为什么只写这几个？列表页用不到正文内容，查出来也是浪费内存和带宽。MyBatis 查询时只需 select 需要的列，实体类自然也不用定义全部字段。这个做法叫“按需查询”，等做详情页的时候再定义一个包含 content 的实体类，或者直接复用 Article 加上 content 字段都行。

MyBatis 默认的字段映射规则是“下划线转驼峰”，create_time 会自动映射到 createTime。这个功能默认没开，需要在 mybatis-config.xml 里显式开启：

xml复制<settings>
    <setting name="mapUnderscoreToCamelCase" value="true"/>
</settings>

我遇到过一个同事没开这个配置，结果查出来的 createTime 全是 null，排错排了一下午。你可以不依赖这个设置，用 resultMap 手工映射，但代码会啰嗦很多。个人建议直接开这个全局设置，省下来的时间和精力去干更重要的事。

4.2 Dao 层：MyBatis 的 Mapper 与 XML

Dao 层负责 SQL 的编写和执行。MyBatis 支持注解写 SQL，也支持 XML 写 SQL。列表查询这种简单 SQL，注解和 XML 差别不大，但后面做动态条件查询（比如按分类筛选）、多表关联时，XML 的可维护性强太多了。我习惯从一开始就统一用 XML，保持风格一致。

ArticleMapper 接口和 XML 文件放在同一层级的包路径下，XML 的 namespace 指向接口全类名：

java复制public interface ArticleMapper {

    List<Article> selectPublishedArticlePage(@Param("offset") int offset,
                                              @Param("pageSize") int pageSize);

    long countPublishedArticle();
}

对应的 ArticleMapper.xml：

xml复制<mapper namespace="com.blog.dao.ArticleMapper">

    <select id="selectPublishedArticlePage" resultType="com.blog.entity.Article">
        SELECT id, title, summary, category, view_count, create_time
        FROM article
        WHERE status = 1
        ORDER BY create_time DESC, id DESC
        LIMIT #{offset}, #{pageSize}
    </select>

    <select id="countPublishedArticle" resultType="long">
        SELECT COUNT(*)
        FROM article
        WHERE status = 1
    </select>
</mapper>

为什么列表要“查一次当前页数据 + 查一次总条数”？因为分页导航需要知道总页数，而总页数需要通过总条数和每页条数算出来。两个查询都要走，不能偷懒只查一个。运行 SQL 的时候你会发现，count 查询可以不用查具体数据，加个 COUNT(*) 就完了，性能上比 SELECT * 好很多。

MyBatis 的 @Param 注解要记得加，不然 XML 里引用 #{offset} 会报“参数找不到”的错。这是 MyBatis 老版本一个很坑的设定，新版本可以不加，但加了绝对没错，能明确参数语义还能避免多参数时的坑。

4.3 Service 层：分页参数校验与返回封装

Service 层是 Controller 和 Dao 之间的缓冲层。这个层干的事是业务规则的校验和处理，而不是简单的传话。列表功能里看似没有“业务”，但分页参数校验就是典型的业务逻辑。

用户访问 blog/list?page=999 的时候，如果数据库一共只有 2 页，直接查第 999 页会查出一个空集，页面看起来就像出 bug 了。合理的做法是：Service 层拿到页码后先判断，小于 1 就重置为 1，大于总页数就重置为最后一页，pageSize 不接收前端传参，固定为 5 或 10。这样无论用户怎么造 URL，页面都不会出现空白和异常。

分页数据我用一个 PageBean 统一封装：

java复制public class PageBean<T> {
    private int pageNum;      // 当前页
    private int pageSize;     // 每页条数
    private long total;       // 总条数
    private int pages;        // 总页数
    private List<T> list;     // 当前页数据

    public PageBean(int pageNum, int pageSize, long total, List<T> list) {
        this.pageNum = pageNum;
        this.pageSize = pageSize;
        this.total = total;
        this.list = list;
        this.pages = (int) Math.ceil((double) total / pageSize);
    }
}

总页数计算用了 Math.ceil((double) total / pageSize)，这是一个容易踩坑的地方：如果 total 和 pageSize 都是整数，total / pageSize 的结果会直接截断取整，导致多出一条数据没被算进页数里。比如 11 条数据、每页 5 条，11 / 5 在 Java 里结果是 2，但真实应该分 3 页。先转成 double，再向上取整，才能得到正确结果。

Service 层代码再封装一层：

java复制public class ArticleService {

    private ArticleMapper articleMapper = SqlSessionUtil.getMapper(ArticleMapper.class);

    public PageBean<Article> pagePublishedArticles(int pageNum, int pageSize) {
        long total = articleMapper.countPublishedArticle();
        int pages = (int) Math.ceil((double) total / pageSize);
        if (pageNum < 1) {
            pageNum = 1;
        }
        if (pageNum > pages && pages > 0) {
            pageNum = pages;
        }
        int offset = (pageNum - 1) * pageSize;
        List<Article> list = articleMapper.selectPublishedArticlePage(offset, pageSize);
        return new PageBean<>(pageNum, pageSize, total, list);
    }
}

SqlSessionUtil 是一个工具类，封装了 MyBatis 的 SqlSession 获取和 Mapper 代理生成。Servlet 和 Service 之间的引用我直接用静态工具类拿 Mapper，没有引入 Spring 的依赖注入。这是刻意简化：这个阶段把 Spring IoC 容器引进来，等于把 Servlet 生命周期和容器管理两个复杂概念叠加在一起，新手很容易搞混。手动管理 SqlSession 是理解 MyBatis 工作机制的最好方式。

4.4 Servlet 控制层：参数解析与视图转发

Servlet 这一层的职责是：接收 HTTP 请求，解析参数，调用 Service，把结果放进 request 域，转发到 JSP。代码很薄，但容易写错的地方不少。用 @WebServlet 注解声明访问路径，转发到列表页：

java复制@WebServlet("/list")
public class BlogListServlet extends HttpServlet {

    private final ArticleService articleService = new ArticleService();

    @Override
    protected void doGet(HttpServletRequest request, HttpServletResponse response)
            throws ServletException, IOException {
        String pageNumStr = request.getParameter("page");
        int pageNum = 1;
        if (pageNumStr != null && !pageNumStr.isBlank()) {
            try {
                pageNum = Integer.parseInt(pageNumStr);
            } catch (NumberFormatException e) {
                pageNum = 1;
            }
        }

        int pageSize = 5;
        PageBean<Article> pageBean = articleService.pagePublishedArticles(pageNum, pageSize);

        request.setAttribute("pageBean", pageBean);
        request.getRequestDispatcher("/list.jsp").forward(request, response);
    }
}

Servlet 里对 page 参数做了容错处理：字符串为空和数字格式非法的都会回退到第 1 页。这个细节很多人忽略，用户访问 blog/list?page=abc 时，Integer.parseInt 会直接抛 NumberFormatException，不 catch 的话整页报 500。写代码的时候思路要换成“用户永远不会按你的预期输参数”，所有外部输入都要校验。

最后用 forward 而不是 sendRedirect。这里必须说清楚：sendRedirect 是重定向，浏览器会重新发起第二次请求，request 对象是新的，你用 setAttribute 放进去的数据第二次请求根本拿不到；forward 是服务端内部跳转，同一个 request 从头传到尾，数据自然能到 JSP。经验不足的开发者在这一步最容易踩坑——列表页打开一片空白，一开始还以为是 JSP 的问题，其实是重定向把数据弄丢了。

5. 前端渲染：用 JSTL 把文章列表“晒”出来

5.1 为什么在 JSP 里坚持用 JSTL 而不是 Java 代码块

现在到了“让文章晒出来”的关键一步。JSP 页面有两种赋值写法，一种是在页面最上面写 <% ... %> Java 代码块，一种是基于 EL 表达式和 JSTL 标签库的方式。

jsp复制<%-- 不推荐的写法 --%>
<%
    PageBean<Article> pb = (PageBean<Article>) request.getAttribute("pageBean");
    for (Article a : pb.getList()) {
        out.println("<h2>" + a.getTitle() + "</h2>");
    }
%>

这种 Scriptlet 写法在十几年前的老项目里很常见，现在再看到基本可以判定是历史遗留代码。问题有三个：一是 JSP 页面里写 Java 代码，页面维护者必须同时懂 Java 和 HTML，分工完全打乱；二是 out.println 拼字符串拼 HTML，标签稍微复杂一点，字符串引号和尖括号满天飞，想调个样式都艰难；三是 Java 代码和 HTML 混在一起，容易产生 XSS 注入等安全问题——用户提交的内容如果不做 HTML 转义直接 out.println 输出，等于给攻击者留了后门。

JSTL 加 EL 表达式的写法是从业者的标准答案。EL 表达式负责取值，JSTL 的 <c:forEach> 负责循环，<c:if> 负责条件判断，页面结构清晰，可读性拉满。而且 JSTL 的 <c:out> 默认做 HTML 转义，能有效防止 XSS，属于“顺手就安全”的设计。

5.2 列表页核心片段与空状态处理

list.jsp 的核心结构如下。先引入 JSTL 核心标签库，再用 EL 从 request 域的 pageBean 里取数据：

jsp复制<%@ page contentType="text/html;charset=UTF-8" language="java" %>
<%@ taglib prefix="c" uri="http://java.sun.com/jsp/jstl/core" %>
<%@ taglib prefix="fmt" uri="http://java.sun.com/jsp/jstl/fmt" %>
<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <title>我的博客</title>
</head>
<body>

<h1>我的博客</h1>

<c:forEach items="${pageBean.list}" var="article">
    <div class="article-item">
        <h2>
            <a href="${pageContext.request.contextPath}/article/detail?id=${article.id}">
                <c:out value="${article.title}"/>
            </a>
        </h2>
        <p class="summary"><c:out value="${article.summary}"/></p>
        <div class="meta">
            <span class="category">${article.category}</span>
            <fmt:formatDate value="${article.createTime}" pattern="yyyy-MM-dd HH:mm"/>
            <span>阅读 ${article.viewCount}</span>
        </div>
    </div>
</c:forEach>

</body>
</html>

注意两个细节。第一，文章标题和摘要我用 <c:out> 输出，而不是直接用 ${article.title}。原因前面提过，${} 直接输出是原样输出，<c:out> 会把 <script> 这类的标签转义成普通文本。个人博客虽然访问量不大，但从第一天开始养好这个习惯，以后做任何展示类需求都不会阴沟里翻船。

第二，链接路径用了 ${pageContext.request.contextPath}，作用是把项目上下文路径拼到 URL 前。比如项目部署后访问路径是 http://localhost:8080/blog/，那 contextPath 就是 /blog。如果不拼它，直接用 /article/detail?id=${article.id}，浏览器会跳到 http://localhost:8080/article/detail，绕过了 /blog 这一层，直接 404。这个问题在我的学员项目中出现的概率非常高，必须提前打好预防针。

再补充一个很容易被忽略的空状态处理。如果数据库里一篇文章都没发布，pageBean.list 是空的，页面会显示一个光秃秃的页面，用户会认为网站坏了。加一段容错：

jsp复制<c:if test="${empty pageBean.list}">
    <p class="empty-tip">还没有发布文章，敬请期待。</p>
</c:if>

这段代码放在 forEach 外面或者里面都可以，我更倾向于放在外面。它解决的不仅是展示问题，还是在告诉用户“这里是空的，但这是正常状态”，把“看起来像 bug”变成“明确的前端提示”。

5.3 分页导航与路径问题

数据多了之后，列表页必须有分页导航。分页导航的本质是生成一组带 page 参数的链接，让用户能翻到不同页。页面底部加一段：

jsp复制<div class="pagination">
    <c:if test="${pageBean.pageNum > 1}">
        <a href="${pageContext.request.contextPath}/list?page=${pageBean.pageNum - 1}">上一页</a>
    </c:if>

    <span>第 ${pageBean.pageNum} / ${pageBean.pages} 页</span>

    <c:if test="${pageBean.pageNum < pageBean.pages}">
        <a href="${pageContext.request.contextPath}/list?page=${pageBean.pageNum + 1}">下一页</a>
    </c:if>
</div>

我这里只做了“上一页/下一页”，没有把每个页码循环输出，原因是新手容易在这一步陷入页码算法的泥潭。页码算法讲究可多啦：当前页前后各显示几个、第一页和最后一页要不要固定显示、中间断开用什么符号连接，这些细节做起来可以写一整篇文章。第一版先把上一页下一页跑通，等系列后期后台管理做分页时再处理完整页码导航。

有一点必须提醒：分页导航里的页码链接，是经过 Service 层校验之后的 pageBean.pageNum，不是直接从 URL 拿的原始参数。用户访问 list?page=999 时，Service 把它重置成了最后一页，那导航里显示的当前页就是最后一页，上一页的链接也会指向倒数第二页。如果你页面里写死的是 request 原始参数，就会出现在第 999 页点“上一页”跑到第 998 页的荒谬结果。

6. 实测中的坑：VS Code 环境配置与部署调试经验

6.1 VS Code 配置 JavaEE 开发环境的一点心得

不是说用 VS Code 开发 JavaEE 就要折腾半天——现在插件生态比前几年好太多了。核心装“Extension Pack for Java”一个包，里面包含 Java 语言服务、Maven 支持、调试器、Test Runner 等全套工具。装完打开 pom.xml，它会自动识别 Maven 工程，下载依赖，左侧出现 Maven 视图，编译、打包、安装这些命令点鼠标就能跑，不需要记一堆命令行。

Tomcat 部署方面，装“Tomcat for Java”插件，然后按 Ctrl+Shift+P 输入 Tomcat: Add Tomcat Server，指定本地 Tomcat 9 的安装目录，插件会识别出 server。之后右键 war 包直接 “Run on Tomcat”，它会自动完成部署和启动。这个插件对新手非常友好，缺点是版本更新比较慢，遇到高版本 Tomcat 偶尔不兼容，我实测下来配 Tomcat 9.0.73 没有遇到问题。

如果插件部署不顺，还有一个最朴素的方案：mvn clean package 打完 war 包，手动复制到 Tomcat webapps 目录，双击 startup.bat 启动。这个方法听起来“土”，但绝对稳定。我在线上帮别人排障的时候，有一半都是插件装了一堆但没装对，最后手动部署反而一次通过。别鄙视“土办法”，它是最不容易出现歧义的道路。

6.2 Tomcat 版本引发的 404 与包名错误

第一次启动访问 http://localhost:8080/blog/list 出现 404，排查思路要清晰。先看 Tomcat 控制台有没有启动异常，再确认 war 包是否成功解压，然后看访问路径。路径 404 最常见原因有三种：URL 少了 contextPath、注解 /list 写成了 /* 或 /list/、web.xml 里 filter 的 url-pattern 写错导致请求被拦截。

其中最容易让人懵的是 @WebServlet 注解没生效。Tomcat 7 以后默认开启注解扫描，但有一个前提：你的项目必须由 Servlet 容器管理。如果 web.xml 版本太老（比如声明成 2.3），容器会认为项目不支持注解，Servlet 注册不上，访问路径自然就 404。所以 web.xml 头部的 version 一定要声明成 4.0，和 Tomcat 9 匹配。

还有一个我在 Tomcat 10 上踩过的坑：网上很多新代码用 jakarta.servlet 包名，如果 Tomcat 是 9，运行时会报 ClassNotFoundException；反过来，你写的 javax.servlet 代码丢到 Tomcat 10，结果一样。我的建议很明确：统一用 Tomcat 9 + javax，别在这个点上纠结。

6.3 中文乱码的来龙去脉与一套标准解法

中文乱码有三种来源，分别出现在不同环节，排查时可以对号入座。

第一种是浏览器发请求时带的参数乱码。GET 请求的参数拼在 URL 里，Tomcat 9 默认 URL 编码是 UTF-8，一般问题不大；POST 请求的参数在请求体里，默认编码是 ISO-8859-1，所以必须设置编码过滤器或调用 request.setCharacterEncoding("UTF-8")。这也就是 web.xml 那个 filter 真正起作用的地方。

第二种是响应乱码，JSP 页面出现一堆乱码字符，通常是 JSP 的 pageEncoding 没写对。在 JSP 文件第一行写 <%@ page contentType="text/html;charset=UTF-8" %> 是标准解法，同时文件本身的编码也要是 UTF-8。VS Code 右下角就可以切换编码，保存时选“UTF-8 带 BOM”或“UTF-8”均可，但要和页面声明一致。

第三种是数据库乱码，页面显示正常，但数据库里存的是乱码。这个检查三处：MySQL 连接 URL 加 characterEncoding=utf8、建表语句指定 CHARSET=utf8mb4、MySQL 服务端系统变量 character_set_server。如果前面两个都做了仍然乱码，执行 SHOW VARIABLES LIKE 'character_set%'; 检查服务端。一个靠谱的排查口令是：三处一律 UTF-8，哪里有个别字就是哪里没统一。

最后给一个实用的小技巧：当列表页渲染结果和预期不符时，先把异常看待。查看 JSP 转译后的 Java 文件（Tomcat 的 work/Catalina/localhost/blog/org/apache/jsp/ 目录）可以定位是 EL 表达式问题还是标签库问题。很多时候页面报错信息不友好，但转译后的 Java 文件里会详细标出第几行出错。这个技巧帮我跳过了大量“看不清报错”的干瞪眼时间，你可以实测一下。

代码写到这里，整个博客系统的基础已经立住了：项目能启动，数据库有表，列表页能按分页展示已发布文章。下一期我打算接着做文章详情页，把 id 参数从列表链接传到 Servlet，再查出单篇文章完整内容展示出来——你会发现有了这一期的骨架，剩下的只是往已经跑通的链路上加新节点。先别急着学新框架，把这个链路吃透，比什么都重要。