# scaffold-servlet

**Repository Path**: javaweb-dev-tech/scaffold-servlet

## Basic Information

- **Project Name**: scaffold-servlet
- **Description**: 《软件开发综合项目实训》课程脚手架 · Servlet + JSP。学生可基于此脚手架夯实 Servlet / Filter / JDBC 原理后启动课程项目。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-24
- **Last Updated**: 2026-07-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# scaffold-servlet

> Servlet + 原生 HTML/CSS/JS 课程脚手架工程。基于 Jakarta EE 10 / Servlet 6.x，面向软件项目训练课程，提供从环境搭建到部署上线的完整骨架。

## 项目简介

本项目是一个**课程教学脚手架**，定位为「最小可运行的 Servlet 全栈示例」，不使用 Spring，不使用 JSP，回归原生 Servlet + JDBC + HTML，帮助学生理解 Web 应用底层原理。

- 后端：JDK 17 + Servlet 6.x（Jakarta EE 10 命名空间）+ 原生 JDBC + Druid 连接池
- 鉴权：Session + Cookie + Filter（不使用 Token）
- 前端：原生 HTML/CSS/JS + fetch（自动维护 session）
- 数据库：MySQL 8
- 部署：WAR 打包 + Tomcat 11 + Nginx 反向代理 + Docker Compose

## 5 分钟上手

### 1. 环境准备

| 工具 | 版本要求 |
| --- | --- |
| JDK | 17 |
| IntelliJ IDEA | Ultimate / Community + smart-tomcat 插件 |
| smart-tomcat 插件 | IDEA 插件市场安装 |
| 本地 Tomcat | 11（Servlet 6.0） |
| MySQL | 8.0 |

### 2. 初始化数据库

```bash
mysql -uroot -proot < sql/init.sql
```

该脚本会创建 `scaffold_servlet` 库、`user` / `demo_item` 表，并插入 1 个管理员（admin / admin123）与 3 条示例数据。

### 3. IDEA smart-tomcat 一键运行

1. 打开 IDEA → File → Open → 选择本工程根目录
2. 等待 Maven 下载依赖
3. 安装 smart-tomcat 插件（Settings → Plugins → 搜索 smart-tomcat）
4. 配置 Run：Run → Edit Configurations → + smart-tomcat
   - Tomcat Server：选择本地 Tomcat 11 安装目录
   - Deployment directory：`src/main/webapp`
   - Context Path：`/scaffold-servlet`
   - Server Port：`8080`
5. 点击运行，访问 http://localhost:8080/scaffold-servlet/

### 4. Docker 部署

```bash
mvn clean package
cd deploy
docker compose up -d --build
```

启动后包含三个服务：mysql、tomcat（8080）、nginx（80）。

## 目录结构

```
scaffold-servlet/
├── pom.xml                  # Maven 构建文件
├── mvnw / mvnw.cmd          # Maven Wrapper 脚本
├── deploy/                  # 部署相关（Dockerfile、docker-compose、nginx）
├── sql/                     # 数据库初始化脚本
├── api/                     # Postman 集合
├── docs/                    # 课程文档（学生填）
├── src/
│   ├── main/
│   │   ├── java/edu/course/scaffold/
│   │   │   ├── common/      # 统一响应 ApiResponse
│   │   │   ├── exception/   # 业务异常 + 全局异常处理
│   │   │   ├── filter/      # 编码/CORS/登录/权限过滤器
│   │   │   ├── util/        # JDBC/Json/MD5 工具
│   │   │   ├── controller/  # BaseServlet + Auth/DemoItem Servlet
│   │   │   ├── entity/      # 实体类
│   │   │   ├── dto/         # 视图对象 VO
│   │   │   ├── dao/         # 数据访问层 JDBC
│   │   │   └── service/     # 业务逻辑层
│   │   ├── resources/       # druid.properties、logback.xml
│   │   └── webapp/          # 静态资源 + WEB-INF/web.xml
│   └── test/                # 单元测试
└── .trae/                   # Trae 课程 Skill 占位
```

## 技术栈

- 语言：Java 17
- Web：Jakarta Servlet 6.0（jakarta.servlet.*）
- 数据库：MySQL 8.0
- 连接池：Alibaba Druid 1.2.20
- JSON：Jackson 2.15.2
- 工具：Lombok 1.18.42
- 测试：JUnit 5.13.2
- 构建：Maven（war 打包）
- 容器：Tomcat 11 / Docker / Nginx

## 常用命令

```bash
# 编译打包（生成 target/scaffold-servlet.war）
mvn clean package

# 跳过测试打包
mvn clean package -DskipTests

# 运行单元测试
mvn test

# Docker 部署
cd deploy && docker compose up -d --build

# 查看日志
docker compose logs -f tomcat
```

## 课程脚手架定位说明

本工程是**教学脚手架**，提供：

- 完整的分层架构（controller / service / dao / entity / dto）
- 统一的异常处理与响应格式（ApiResponse）
- 开箱即用的鉴权链路（Session + Filter）
- 可直接运行的 DemoItem 增删改查示例
- 部署一条龙（Docker Compose + Nginx）

学生可在其基础上扩展业务模块，无需重复搭建基础设施。`docs/` 目录下的需求、设计、测试、说明文档为空骨架，供学生按课程进度填充。