# easyWeb

**Repository Path**: lxj-creator/easy-web

## Basic Information

- **Project Name**: easyWeb
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-11
- **Last Updated**: 2026-07-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# EasyWeb

基于 Spring Boot 的多模块单体 Web 应用框架。

## 项目结构

```
EasyWeb/
├── pom.xml                  # 父级 POM（统一管理依赖版本、插件）
├── easyweb-app/             # 应用主模块（Web 启动入口）
│   ├── pom.xml
│   └── src/
│       ├── main/
│       │   ├── java/lxj/easy/
│       │   └── resources/
│       └── test/
├── easyweb-security/        # 安全模块（Sa-Token + JWT 认证鉴权）
│   ├── pom.xml
│   └── src/
│       └── main/
│           ├── java/lxj/easy/security/
│           └── resources/
└── README.md
```

### 模块说明

| 模块             | 说明                                       |
| ---------------- | ------------------------------------------ |
| `EasyWeb`        | 父级模块，统一管理依赖版本和构建插件       |
| `easyweb-app`    | 应用主模块，Web 启动入口，包含业务代码     |
| `easyweb-security` | 安全模块，Sa-Token + JWT 认证鉴权        |

### 添加新子模块

在根目录创建新模块目录，添加 `pom.xml` 继承父级：

```xml
<parent>
    <groupId>lxj.easy</groupId>
    <artifactId>EasyWeb</artifactId>
    <version>1.0-SNAPSHOT</version>
</parent>

<artifactId>easyweb-xxx</artifactId>
```

然后在根 `pom.xml` 的 `<modules>` 中声明：

```xml
<modules>
    <module>easyweb-app</module>
    <module>easyweb-xxx</module>
</modules>
```

## 环境要求

| 环境     | 版本     | 说明                                      |
| -------- | -------- | ----------------------------------------- |
| JDK      | 1.8      | JAVA_HOME 需指向 JDK 1.8 路径             |
| Maven    | 3.6+     | 项目构建工具                              |
| MySQL    | 8.x      | 数据库                                    |

## 技术栈

| 技术                | 版本       | 说明                         |
| ------------------- | ---------- | ---------------------------- |
| Spring Boot         | 2.7.18     | 2.x 最终维护版，支持 JDK 8   |
| MyBatis-Plus        | 3.5.5      | 增强版 MyBatis               |
| Druid               | 1.2.21     | 阿里巴巴数据库连接池         |
| MySQL Connector/J   | 8.0.33     | MySQL 8 驱动（父工程管理）   |
| Lombok              | 1.18.30    | 简化实体类代码（全局共享）   |
| Hutool              | 5.8.25     | Java 工具包                  |
| Jackson             | 2.13.5     | JSON 序列化（父工程管理）    |
| Hibernate Validator | 6.2.x      | 参数校验（父工程管理）       |
| Tomcat（内嵌）      | 9.0.83     | Web 容器（父工程管理）       |
| Sa-Token            | 1.39.0     | 轻量级权限认证框架           |
| JJWT                | 0.11.5     | JWT 生成与解析库             |

## 依赖说明

### Spring Boot 核心

| 依赖                          | 版本   | 说明         |
| ----------------------------- | ------ | ------------ |
| `spring-boot-starter-web`     | 2.7.18 | Web 启动器   |
| `spring-boot-starter-validation` | 2.7.18 | 参数校验   |

### 数据库相关

| 依赖                          | 版本   | 说明               |
| ----------------------------- | ------ | ------------------ |
| `mysql-connector-j`           | 8.0.33 | MySQL 8 驱动       |
| `mybatis-plus-boot-starter`   | 3.5.5  | MyBatis-Plus       |
| `druid-spring-boot-starter`   | 1.2.21 | Druid 连接池       |

### 工具类

| 依赖                    | 版本   | 说明                       |
| ----------------------- | ------ | -------------------------- |
| `lombok`                | 1.18.30| 简化代码（编译时排除打包） |
| `hutool-all`            | 5.8.25 | Hutool 全量工具包          |
| `jackson-datatype-jsr310` | 2.13.5 | Java 8 日期时间支持      |

### 测试

| 依赖                      | 版本   | 说明                       |
| ------------------------- | ------ | -------------------------- |
| `spring-boot-starter-test`| 2.7.18 | JUnit 5、Mockito 等        |

## 构建插件

### spring-boot-maven-plugin

- 支持 `mvn spring-boot:run` 直接启动应用
- 支持 `mvn package` 打包为可执行 JAR
- **Lombok 排除配置**：通过 `<excludes>` 将 Lombok 从最终打包产物中排除，减小 JAR 体积

```xml
<plugin>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-maven-plugin</artifactId>
    <configuration>
        <excludes>
            <exclude>
                <groupId>org.projectlombok</groupId>
                <artifactId>lombok</artifactId>
            </exclude>
        </excludes>
    </configuration>
</plugin>
```

> Lombok 仅在编译期生效，运行时不需要，因此排除可减小最终产物体积。

## 快速开始

```bash
# 编译所有模块
mvn clean compile

# 运行应用主模块
mvn spring-boot:run -pl easyweb-app

# 打包所有模块
mvn clean package -DskipTests

# 仅打包应用模块
mvn clean package -pl easyweb-app -am -DskipTests
```

---

## 安全架构

### 方案选型

本项目采用 **Sa-Token + JWT** 组合方案：

| 组件 | 职责 |
|---|---|
| **Sa-Token** | 认证鉴权框架，负责登录认证、权限校验、会话管理 |
| **JWT** | Token 规范，将 Sa-Token 的 Token 替换为 JWT 格式，实现无状态认证 |

### 工作原理

#### 认证流程

```
客户端                          服务端
  │                              │
  │  1. POST /api/auth/login     │
  │  {username, password}        │
  │ ───────────────────────────> │
  │                              │
  │              2. 验证用户名密码（查数据库）
  │                              │
  │              3. StpUtil.login(userId)
  │                 Sa-Token 生成 JWT Token
  │                              │
  │  4. 返回 JWT Token           │
  │ <─────────────────────────── │
  │                              │
  │  5. 后续请求携带 Token       │
  │  Header: Authorization: Bearer xxx
  │ ───────────────────────────> │
  │                              │
  │              6. SaInterceptor 拦截
  │                 解析 JWT Token
  │                 验证签名 + 提取用户信息
  │                              │
  │  7. 返回数据                 │
  │ <─────────────────────────── │
```

#### Sa-Token 的三种 JWT 模式

| 模式 | 说明 | 适用场景 |
|---|---|---|
| **Simple**（当前采用） | Token 替换为 JWT，Session 仍存服务端 | 入门推荐，兼顾安全与性能 |
| **Mix** | Token 为 JWT，Session 数据嵌入 Token | 无状态场景 |
| **Stateless** | 完全无状态模式 | 微服务/分布式 |

#### 核心组件说明

| 组件 | 文件 | 职责 |
|---|---|---|
| SaTokenConfig | `config/SaTokenConfig.java` | 注册 Sa-Token 拦截器，配置 JWT 模式 |
| StpInterfaceImpl | `config/StpInterfaceImpl.java` | 加载用户权限/角色数据（需对接数据库） |
| SaTokenExceptionHandler | `config/SaTokenExceptionHandler.java` | 统一处理认证鉴权异常 |

### 依赖关系

```
easyweb-app（应用主模块）
  └── easyweb-security（安全模块）
        ├── sa-token-spring-boot-starter（Sa-Token 核心）
        ├── sa-token-jwt（Sa-Token JWT 整合）
        └── jjwt（JWT 生成与解析）
```

### 配置说明

```yaml
sa-token:
  token-name: Authorization       # Token 名称（HTTP Header 名）
  timeout: 2592000                # Token 有效期（30天）
  active-timeout: -1              # 临时有效期（-1 表示不启用）
  is-concurrent: true             # 允许并发登录（多端同时在线）
  is-share: true                  # 多端共用同一 Token
  jwt-secret-key: xxx             # JWT 签名密钥（生产环境请使用复杂密钥）
```

### 常用 API

```java
// 登录
StpUtil.login(userId);

// 获取当前登录用户ID
Long userId = StpUtil.getLoginIdAsLong();

// 检查登录状态
StpUtil.checkLogin();

// 权限校验
StpUtil.checkPermission("user:add");

// 角色校验
StpUtil.checkRole("admin");

// 注销登录
StpUtil.logout();

// 注解方式校验权限
@SaCheckPermission("user:add")
public void addUser() { ... }
```

### JWT 安全说明

- **防篡改**：JWT 通过 HMAC-SHA256 签名保证数据完整性，任何篡改都会导致签名验证失败
- **Secret 密钥**：仅存在于服务端，不随 Token 传输，用于签名生成和验证
- **不存敏感信息**：JWT Payload 仅为 Base64 编码（非加密），禁止存放密码等敏感数据
- **密钥管理**：生产环境务必替换 `jwt-secret-key`，建议 32 字符以上并定期轮换