# jmb-banked

**Repository Path**: chlwmj/jmb-banked

## Basic Information

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

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-10-30
- **Last Updated**: 2025-10-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Spring Boot 3.0 用户登录API

基于 Spring Boot 3.0 + Java 17 开发的用户登录系统，支持国密加密算法和数据脱敏功能。

## 技术栈

- **Spring Boot 3.0.13** - 主框架
- **Java 17** - 编程语言
- **MyBatis Plus 3.5.5** - ORM框架
- **MySQL 8.x** - 数据库
- **Lombok** - 简化代码
- **SpringDoc OpenAPI 2.2.0** - API文档（Swagger）
- **Hutool 5.8.25** - 工具库（包含国密算法）
- **BouncyCastle** - 加密库
- **JWT** - Token认证
- **Jasypt 3.0.5** - 配置文件加密

## 核心特性

### 1. 国密加密
- **SM3算法** - 用于密码哈希加密（类似SHA-256）
- **SM4算法** - 用于敏感数据对称加密（类似AES）

### 2. 数据脱敏
支持多种脱敏策略，返回给前端时自动脱敏：
- **手机号脱敏** - 138****8000
- **身份证脱敏** - 110101********3456
- **邮箱脱敏** - a***@example.com
- **姓名脱敏** - 张*

### 3. 配置文件加密
- **Jasypt加密** - 数据库密码、JWT密钥等敏感配置加密存储
- **环境变量支持** - 生产环境密钥通过环境变量注入
- **多算法支持** - 支持多种加密算法

### 4. JWT认证
- 登录成功后返回JWT Token
- Token有效期24小时

## 项目结构

```
springboot-login-api/
├── src/main/java/com/example/login/
│   ├── annotation/          # 自定义注解（脱敏注解）
│   ├── common/              # 公共类（统一响应）
│   ├── config/              # 配置类（Swagger、MyBatis Plus）
│   ├── controller/          # 控制器
│   ├── dto/                 # 数据传输对象
│   ├── entity/              # 实体类
│   ├── enums/               # 枚举类（脱敏策略）
│   ├── exception/           # 异常处理
│   ├── mapper/              # MyBatis Mapper
│   ├── serializer/          # 序列化器（脱敏实现）
│   ├── service/             # 业务层
│   │   └── impl/            # 业务实现
│   └── util/                # 工具类（国密、JWT）
├── src/main/resources/
│   ├── sql/                 # SQL脚本
│   │   └── schema.sql       # 数据库建表脚本
│   └── application.yml      # 配置文件
└── pom.xml                  # Maven配置
```

## 快速开始

### 前置要求
- JDK 17+
- Maven 3.6+
- MySQL 8.0+ 或 Docker（二选一）

### 方式一：使用 Docker 启动数据库（推荐⭐）

**最快捷的方式，无需安装 MySQL！**

#### Windows 用户

双击运行 `start-docker-db.bat`，或在命令行执行：
```cmd
start-docker-db.bat
```

#### Linux/Mac 用户

```bash
./start-docker-db.sh
```

**就这么简单！** 数据库已启动在端口 **13306**

📖 详细说明：
- **快速指南：** `快速启动Docker数据库.md`
- **完整文档：** `Docker部署指南.md`

**连接信息：**
- 主机：`localhost`
- 端口：`13306`
- 用户：`root`
- 密码：查看 `.env` 文件中的 `MYSQL_ROOT_PASSWORD`
- 数据库：`login_db`

---

### 方式二：使用本地 MySQL

#### 1. 安装 MySQL 8.0+

#### 2. 执行SQL脚本

```bash
mysql -u root -p < src/main/resources/sql/schema.sql
```

#### 3. 修改配置

将 `application.yml` 中的端口改为 3306：
```yaml
spring:
  datasource:
    url: jdbc:mysql://localhost:3306/login_db
```

### 3. 加密配置文件（重要！）

#### 步骤1：生成加密密文

运行加密工具生成密文：
```bash
# 运行 JasyptEncryptUtil.java 的 main 方法
# 或使用 Maven 命令：
mvn compile exec:java -Dexec.mainClass="com.example.login.util.JasyptEncryptUtil"
```

#### 步骤2：更新配置文件

将生成的密文替换到 `src/main/resources/application.yml` 中：
```yaml
spring:
  datasource:
    url: jdbc:mysql://localhost:3306/login_db?useUnicode=true&characterEncoding=utf8&useSSL=false&serverTimezone=Asia/Shanghai
    username: ENC(你的加密后的用户名)
    password: ENC(你的加密后的密码)

jwt:
  secret: ENC(你的加密后的JWT密钥)

sm4:
  key: ENC(你的加密后的SM4密钥)
```

**详细说明请查看：** `使用Jasypt加密配置的步骤.md` 和 `配置文件加密说明.md`

### 4. 设置加密密钥（生产环境）

**开发环境** 可以跳过此步骤，使用配置文件中的默认密钥。

**生产环境** 必须通过环境变量设置加密密钥：

```bash
# Linux/Mac
export JASYPT_PASSWORD=你的强密码

# Windows PowerShell
$env:JASYPT_PASSWORD="你的强密码"

# Windows CMD
set JASYPT_PASSWORD=你的强密码
```

### 5. 运行项目

```bash
# 编译
mvn clean compile

# 运行（开发环境）
mvn spring-boot:run

# 运行（生产环境 - 带加密密钥）
mvn spring-boot:run -Djasypt.encryptor.password=你的强密码
```

### 6. 访问接口

- **API文档**: http://localhost:8080/api/swagger-ui.html
- **API接口**: http://localhost:8080/api/v3/api-docs

> **注意：** 如果启动失败，提示 "Unable to decrypt"，请检查加密密钥是否正确。

## API接口

### 用户注册
```
POST /api/user/register
Content-Type: application/json

{
  "username": "test01",
  "password": "123456",
  "realName": "张三",
  "phone": "13800138000",
  "email": "test@example.com",
  "idCard": "110101199001011234"
}
```

### 用户登录
```
POST /api/user/login
Content-Type: application/json

{
  "username": "test01",
  "password": "123456"
}
```

响应示例：
```json
{
  "code": 200,
  "message": "登录成功",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiJ9...",
    "user": {
      "id": 1,
      "username": "test01",
      "realName": "张*",
      "phone": "138****8000",
      "email": "t***@example.com",
      "idCard": "110101********1234",
      "status": 1
    }
  },
  "timestamp": 1698765432000
}
```

### 获取用户信息
```
GET /api/user/{id}
Authorization: Bearer {token}
```

### 获取用户列表
```
GET /api/user/list
Authorization: Bearer {token}
```

## 国密加密说明

### SM3加密（密码）
- 用户注册时，密码使用SM3算法加密后存储
- 用户登录时，输入的密码使用SM3加密后与数据库中的密码比对
- SM3是不可逆的哈希算法，即使数据库泄露也无法还原原始密码

### SM4加密（身份证）
- 用户注册时，身份证号使用SM4算法加密后存储
- 查询用户时，身份证号自动解密
- SM4是对称加密算法，可以加密和解密

### API 传输加密（前后端通信）

系统支持前后端数据传输加密，使用 SM4 算法。

#### 密钥格式说明

> ⚠️ **重要**：前端使用 **sm-crypto** 库时，密钥必须是**十六进制格式**（32个十六进制字符）！

**密钥等价关系：**
- **字符串格式**（CryptoJS 库）：`SM4Key2024ABCDEF` （16个字符）
- **十六进制格式**（sm-crypto 库）：`534d344b657932303234414243444546` （32个字符）

这两个密钥是**等价的**，只是格式不同！

#### 后端配置

在 `application.yml` 中配置：

```yaml
api:
  crypto:
    # 方式1：使用字符串密钥（适配 CryptoJS）
    key: SM4Key2024ABCDEF
    key-format: string
    
    # 方式2：使用十六进制密钥（适配 sm-crypto）推荐 ⭐
    # key: 534d344b657932303234414243444546
    # key-format: hex
    
    enabled: true
```

#### 前端对接

**完整文档请查看：**
- 📖 `密钥格式说明.md` - 密钥格式详细说明
- 📖 `前端sm-crypto库对接指南.md` - sm-crypto 库使用指南（推荐）
- 📖 `前端快速开始.md` - CryptoJS 库快速接入
- 📖 `前端文档索引.md` - 所有前端文档导航

**快速开始：**

使用 sm-crypto 库（推荐，真正的国密算法）：
```javascript
import { sm4 } from 'sm-crypto';

// ✅ 使用十六进制密钥
const KEY_HEX = "534d344b657932303234414243444546";

function encrypt(data) {
  return sm4.encrypt(JSON.stringify(data), KEY_HEX, {
    mode: 'ecb',
    padding: 'pkcs#7'
  });
}
```

使用 CryptoJS 库（简单易用）：
```javascript
import CryptoJS from 'crypto-js';

// ✅ 使用字符串密钥
const KEY = "SM4Key2024ABCDEF";

function encrypt(data) {
  const key = CryptoJS.enc.Utf8.parse(KEY);
  return CryptoJS.AES.encrypt(JSON.stringify(data), key, {
    mode: CryptoJS.mode.ECB,
    padding: CryptoJS.pad.Pkcs7
  }).toString();
}
```

## 数据脱敏说明

返回给前端的敏感数据会自动脱敏：
- **姓名**：张三 → 张*
- **手机号**：13800138000 → 138****8000
- **邮箱**：test@example.com → t***@example.com
- **身份证**：110101199001011234 → 110101********1234

## 测试账号

数据库初始化时会自动创建两个测试账号：

| 用户名 | 密码 | 真实姓名 | 手机号 |
|--------|------|----------|---------|
| admin  | 123456 | 张三 | 13800138000 |
| user01 | 123456 | 李四 | 13800138001 |

## 配置文件加密说明

### 为什么需要加密配置？

配置文件中包含敏感信息（数据库密码、JWT密钥等），如果明文存储会带来安全风险。本项目使用 **Jasypt** 对敏感配置进行加密。

### 如何使用？

详细步骤请查看：
- **快速入门**：`使用Jasypt加密配置的步骤.md`
- **完整文档**：`配置文件加密说明.md`

### 三步快速配置

1. **生成密文**：运行 `JasyptEncryptUtil.java`
2. **替换配置**：将密文用 `ENC()` 包裹后放入 `application.yml`
3. **设置密钥**：生产环境通过环境变量 `JASYPT_PASSWORD` 设置

### 示例

```yaml
# 明文（不推荐）
spring:
  datasource:
    password: root

# 密文（推荐）
spring:
  datasource:
    password: ENC(xMpCOKC5I4INuR0P6M3N4g==)
```

## 开发建议

### 1. 密钥管理最佳实践
在生产环境中，建议：
- ✅ 使用环境变量注入加密密钥
- ✅ 不同环境使用不同的加密密钥
- ✅ 定期更换加密密钥
- ✅ 使用密钥管理服务（KMS）
- ❌ 不要将密钥硬编码在配置文件中
- ❌ 不要将密钥提交到 Git 仓库

### 2. 配置文件分离
为不同环境创建不同的配置文件：
```
application.yml              # 公共配置
application-dev.yml          # 开发环境
application-test.yml         # 测试环境
application-prod.yml         # 生产环境（必须加密）
```

### 3. 日志配置
添加日志框架（如Logback）配置文件以便于调试和生产环境使用。

## License

Apache License 2.0