# spring-mvc

**Repository Path**: java-lesson/spring-mvc

## Basic Information

- **Project Name**: spring-mvc
- **Description**: No description available
- **Primary Language**: Java
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-16
- **Last Updated**: 2026-04-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Spring MVC + MyBatis + H2 示例项目

这是一个基于 Spring Framework、Spring MVC、MyBatis 和 H2 数据库的完整 Web 应用程序示例，**不使用 Spring Boot**。

## 📚 文档导航

- **[ARCHITECTURE.md](ARCHITECTURE.md)** - 架构设计、启动流程、数据流、技术细节
- **[DEPLOYMENT.md](DEPLOYMENT.md)** - 部署指南、故障排查、H2 控制台

## 技术栈

- **Spring Framework 7.0.6** - 核心框架
- **Spring MVC** - Web 层框架
- **MyBatis 3.5.19** - ORM 框架
- **MyBatis-Spring 4.0.0** - MyBatis Spring 集成
- **H2 Database 2.3.232** - 内存数据库
- **Jackson 2.19.0** - JSON 处理
- **JSP + JSTL** - 视图层
- **Maven** - 构建工具

## 项目结构

```
spring-mvc/
├── src/
│   ├── main/
│   │   ├── java/
│   │   │   └── com/example/
│   │   │       ├── config/          # Java Config 配置
│   │   │       │   ├── AppConfig.java           # 根配置（数据源、MyBatis）
│   │   │       │   ├── WebConfig.java           # Web MVC 配置
│   │   │       │   └── WebAppInitializer.java   # 应用初始化器（替代 web.xml）
│   │   │       ├── controller/      # 控制器层
│   │   │       │   ├── api/         # API 控制器
│   │   │       │   │   └── UserApiController.java
│   │   │       │   └── page/        # 页面控制器
│   │   │       │       └── UserPageController.java
│   │   │       ├── mapper/          # MyBatis Mapper 接口
│   │   │       │   └── UserMapper.java
│   │   │       ├── model/           # 实体类
│   │   │       │   └── User.java
│   │   │       └── service/         # 服务层
│   │   │           ├── UserService.java
│   │   │           └── impl/
│   │   │               └── UserServiceImpl.java
│   │   ├── resources/
│   │   │   ├── db/
│   │   │   │   ├── schema.sql       # 数据库表结构
│   │   │   │   └── data.sql         # 初始化数据
│   │   │   ├── mapper/              # MyBatis XML 映射文件
│   │   │   │   └── UserMapper.xml
│   │   │   └── database.properties  # 数据库配置
│   │   └── webapp/
│   │       ├── WEB-INF/
│   │       │   ├── views/
│   │       │   │   └── user-list.jsp             # 用户列表页面（含 Modal）
│   │       │   └── web.xml                       # Web 部署描述符（极简）
│   │       └── index.jsp                         # 首页
│   └── test/                     # 测试目录
└── pom.xml                       # Maven 配置文件
```

## 功能特性

### 用户管理功能
- ✅ 查看所有用户列表
- ✅ 创建新用户（支持密码）
- ✅ 编辑用户信息（支持修改密码）
- ✅ 删除用户
- ✅ REST API 支持
- ✅ 密码安全存储（BCrypt加密）
- ✅ 密码字段不暴露在API响应中

### 技术特性
- ✅ 分层架构设计
  - Controller 层：处理 HTTP 请求
  - Service 层：业务逻辑处理
  - Mapper 层：数据访问
- ✅ Java Config 配置（无 XML）
- ✅ 字符编码过滤器
- ✅ 异常处理

## 快速开始

### 前置要求
- JDK 26 或更高版本
- Maven 3.6+ 
- Servlet 容器（如 Tomcat 10+，支持 Jakarta EE 10）

### 构建项目

```bash
mvn clean package
```

这将在 `target/` 目录下生成 `spring-mvc-demo.war` 文件。

**详细部署指南**: 查看 [DEPLOYMENT.md](DEPLOYMENT.md)

## API 端点

### Web 页面
| 方法 | 路径 | 描述 |
|------|------|------|
| GET | `/` | 欢迎页面 |
| GET | `/users` | 用户列表（含 CRUD 操作 Modal） |

### REST API
| 方法 | 路径 | 描述 |
|------|------|------|
| GET | `/api/users` | 获取所有用户（JSON） |
| GET | `/api/users/{id}` | 获取单个用户（JSON） |
| POST | `/api/users` | 创建用户 |
| PUT | `/api/users/{id}` | 更新用户 |
| DELETE | `/api/users/{id}` | 删除用户 |

## 数据库配置

项目使用 H2 内存数据库，配置在 `src/main/resources/database.properties`：

```properties
h2.driver=org.h2.Driver
h2.url=jdbc:h2:mem:testdb;DB_CLOSE_DELAY=-1;DB_CLOSE_ON_EXIT=FALSE
h2.username=sa
h2.password=
```

数据库会在应用启动时自动初始化，包含示例数据。

### 数据库表结构
```sql
CREATE TABLE users (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,
    username VARCHAR(50) NOT NULL UNIQUE,
    email VARCHAR(100) NOT NULL UNIQUE,
    password VARCHAR(255),
    age INT,
    created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
);
```

**注意**: 
- `password` 字段使用 BCrypt 加密存储
- API 接口不会返回 password 字段（安全性考虑）
- 更新用户时，如果不提供 password 字段，将保留原密码

## 最佳实践说明

**完整架构文档**: 查看 [ARCHITECTURE.md](ARCHITECTURE.md)

### 1. 分层架构
- **Controller**: 仅负责处理 HTTP 请求和响应
  - `UserPageController`: 处理页面请求，返回视图
  - `UserApiController`: 处理 API 请求，返回 JSON
- **Service**: 包含业务逻辑和事务管理
- **Mapper**: 负责数据访问操作

### 3. 配置方式
- **Java Config** - 完全基于注解配置，无 XML
  - `AppConfig` - 根配置（数据源、MyBatis）
  - `WebConfig` - Web MVC 配置
  - `WebAppInitializer` - 应用初始化器（替代 web.xml）

### 4. 依赖注入
- 使用 Spring 的 `@Autowired` 进行依赖注入
- 面向接口编程

### 5. 异常处理
- Service 层抛出业务异常
- Controller 层捕获并友好展示

### 6. 代码规范
- 完整的 JavaDoc 注释
- 清晰的命名规范
- 合理的包结构

## 扩展建议

**技术债务和改进方向**: 查看 [ARCHITECTURE.md - 技术债务](ARCHITECTURE.md#技术债务和改进方向)

### 开发工作流

#### 添加新功能步骤
1. **设计数据库表** → 编写 schema.sql
2. **创建实体类** → model 包
3. **创建 Mapper** → mapper 接口 + XML
4. **创建 Service** → 接口 + 实现
5. **创建 Controller** → 处理 HTTP 请求
6. **创建视图** → JSP 页面
7. **测试功能** → 浏览器测试
8. **提交代码** → Git commit

#### 调试技巧
1. **断点调试** → IDE Debug 模式
2. **SQL 调试** → 开启 MyBatis DEBUG 日志
3. **网络请求** → 浏览器开发者工具 Network 面板

1. **添加验证**
   - 使用 Hibernate Validator 进行表单验证
   
2. **全局异常处理**
   - 使用 `@ControllerAdvice` 统一处理异常

3. **拦截器**
   - 添加登录验证拦截器

4. **分页功能**
   - 实现用户列表分页

5. **搜索功能**
   - 添加用户名/邮箱搜索

6. **单元测试**
   - 为 Service 层编写单元测试

7. **安全性**
   - ✅ 集成 Spring Security Crypto（BCrypt密码加密）
   - ✅ 密码字段序列化控制（WRITE_ONLY）
   - ⚠️ 待实现：Spring Security 身份验证和授权

## 注意事项

- 本项目使用 H2 内存数据库，重启后数据会重置
- 如需持久化数据，可修改 `database.properties` 中的 URL 为文件模式：
  ```properties
  h2.url=jdbc:h2:file:./data/testdb
  ```

### 常见问题

**Q1: 如何修改端口号？**  
A: 在 Maven 插件配置中修改 `<port>` 参数，或在 Tomcat 的 `server.xml` 中修改。

**Q2: 如何处理中文乱码？**  
A: 
- web.xml 已配置 CharacterEncodingFilter
- JSP 页面已设置 `charset=UTF-8`
- 确保数据库连接使用 UTF-8

**Q3: 如何切换到 MySQL？**  
A: 
1. 在 pom.xml 中添加 MySQL 驱动依赖
2. 修改 `database.properties`:
```properties
h2.driver=com.mysql.cj.jdbc.Driver
h2.url=jdbc:mysql://localhost:3306/mydb?useSSL=false&serverTimezone=UTC
h2.username=root
h2.password=your_password
```
3. 移除 H2 依赖（可选）

## 许可证

本项目仅供学习参考使用。