357 lines
6.8 KiB
Markdown
357 lines
6.8 KiB
Markdown
# API 接口说明
|
||
|
||
## 用户相关接
|
||
|
||
### 1. 发送验证码
|
||
|
||
**接口地址:** `POST /user/sendCode`
|
||
|
||
**请求参数:**
|
||
```json
|
||
{
|
||
"account": "13800138000", // 手机号或邮箱
|
||
"type": "register" // 验证码类型: register-注册, login-登录, reset-重置密码
|
||
}
|
||
```
|
||
|
||
**响应示例:**
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "验证码发送成功",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
**说明:**
|
||
- 手机号格式: 1开头的11位数字
|
||
- 邮箱格式: 标准邮箱格式
|
||
- 验证码有效期: 5分钟
|
||
- 验证码长度: 6位数字
|
||
|
||
---
|
||
|
||
### 2. 用户注册
|
||
|
||
**接口地址:** `POST /user/register`
|
||
|
||
**请求参数:**
|
||
```json
|
||
{
|
||
"username": "testuser", // 用户名（必填）
|
||
"password": "123456", // 密码（必填）
|
||
"email": "test@example.com", // 邮箱（邮箱和手机号至少填一个）
|
||
"telephone": "13800138000", // 手机号（邮箱和手机号至少填一个）
|
||
"code": "123456", // 验证码（必填）
|
||
"avatar": "http://..." // 头像URL（可选）
|
||
}
|
||
```
|
||
|
||
**响应示例:**
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "注册成功",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
**说明:**
|
||
- 用户名不能重复
|
||
- 邮箱和手机号至少填写一个
|
||
- 邮箱和手机号不能重复
|
||
- 需要先调用发送验证码接口
|
||
- 密码会自动进行 MD5 加密
|
||
|
||
---
|
||
|
||
### 3. 用户登录
|
||
|
||
**接口地址:** `POST /user/login`
|
||
|
||
**请求参数:**
|
||
```json
|
||
{
|
||
"account": "testuser", // 账号（用户名/邮箱/手机号）
|
||
"password": "123456" // 密码
|
||
}
|
||
```
|
||
|
||
**响应示例:**
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "登录成功",
|
||
"data": {
|
||
"token": "uuid-token-string",
|
||
"userId": 1,
|
||
"username": "testuser"
|
||
}
|
||
}
|
||
```
|
||
|
||
**说明:**
|
||
- account 支持用户名、邮箱、手机号三种方式登录
|
||
- 登录成功后返回 token，后续请求需要在 Header 中携带: `Authorization: token值`
|
||
|
||
---
|
||
|
||
### 4. 用户登出
|
||
|
||
**接口地址:** `POST /user/logout`
|
||
|
||
**请求头:**
|
||
```
|
||
Authorization: your-token
|
||
```
|
||
|
||
**响应示例:**
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "登出成功",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 5. 获取当前用户信息
|
||
|
||
**接口地址:** `GET /user/info`
|
||
|
||
**请求头:**
|
||
```
|
||
Authorization: your-token
|
||
```
|
||
|
||
**响应示例:**
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": {
|
||
"id": 1,
|
||
"username": "testuser",
|
||
"password": null,
|
||
"email": "test@example.com",
|
||
"telephone": "13800138000",
|
||
"avatar": null,
|
||
"loginIp": "127.0.0.1",
|
||
"status": 1,
|
||
"createTime": "2025-01-01T12:00:00",
|
||
"updateTime": "2025-01-01T12:00:00"
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 6. 根据ID查询用户
|
||
|
||
**接口地址:** `GET /user/{id}`
|
||
|
||
**请求头:**
|
||
```
|
||
Authorization: your-token
|
||
```
|
||
|
||
**响应示例:**
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": {
|
||
"id": 1,
|
||
"username": "testuser",
|
||
"password": null,
|
||
"email": "test@example.com",
|
||
"telephone": "13800138000",
|
||
"avatar": null,
|
||
"loginIp": "127.0.0.1",
|
||
"status": 1,
|
||
"createTime": "2025-01-01T12:00:00",
|
||
"updateTime": "2025-01-01T12:00:00"
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 7. 更新用户信息
|
||
|
||
**接口地址:** `PUT /user`
|
||
|
||
**请求头:**
|
||
```
|
||
Authorization: your-token
|
||
```
|
||
|
||
**请求参数:**
|
||
```json
|
||
{
|
||
"id": 1,
|
||
"username": "newusername",
|
||
"email": "newemail@example.com",
|
||
"telephone": "13900139000",
|
||
"avatar": "http://..."
|
||
}
|
||
```
|
||
|
||
**响应示例:**
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "更新成功",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
**说明:**
|
||
- 不能通过此接口修改密码
|
||
- 需要修改密码请使用专门的修改密码接口
|
||
|
||
---
|
||
|
||
### 8. 修改密码
|
||
|
||
**接口地址:** `PUT /user/password`
|
||
|
||
**请求头:**
|
||
```
|
||
Authorization: your-token
|
||
```
|
||
|
||
**请求参数:**
|
||
```json
|
||
{
|
||
"oldPassword": "123456",
|
||
"newPassword": "654321"
|
||
}
|
||
```
|
||
|
||
**响应示例:**
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "密码修改成功",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 配置说明
|
||
|
||
### 短信宝配置
|
||
|
||
在 `application.properties` 中配置短信宝账号信息:
|
||
|
||
```properties
|
||
# 短信宝配置
|
||
# 请前往 https://www.smsbao.com/ 注册账号并获取用户名和密码
|
||
smsbao.username=your_username
|
||
smsbao.password=your_password
|
||
```
|
||
|
||
**注册短信宝账号:**
|
||
1. 访问 https://www.smsbao.com/
|
||
2. 注册账号并充值
|
||
3. 获取用户名和密码（注意：密码是 MD5 加密后的值）
|
||
4. 配置到 application.properties 中
|
||
|
||
---
|
||
|
||
### 邮件配置
|
||
|
||
在 `application.properties` 中配置邮箱信息:
|
||
|
||
```properties
|
||
# 邮件配置（以 QQ 邮箱为例）
|
||
spring.mail.host=smtp.qq.com
|
||
spring.mail.port=587
|
||
spring.mail.username=your_email@qq.com
|
||
spring.mail.password=your_authorization_code
|
||
spring.mail.default-encoding=UTF-8
|
||
spring.mail.properties.mail.smtp.auth=true
|
||
spring.mail.properties.mail.smtp.starttls.enable=true
|
||
spring.mail.properties.mail.smtp.starttls.required=true
|
||
```
|
||
|
||
**配置 QQ 邮箱:**
|
||
1. 登录 QQ 邮箱网页版
|
||
2. 进入【设置】->【账户】
|
||
3. 找到【POP3/IMAP/SMTP/Exchange/CardDAV/CalDAV服务】
|
||
4. 开启 SMTP 服务
|
||
5. 生成授权码（注意：不是 QQ 密码！）
|
||
6. 将邮箱地址和授权码配置到 application.properties 中
|
||
|
||
**其他邮箱配置:**
|
||
- **163 邮箱**: `smtp.163.com`，端口 `465` 或 `25`
|
||
- **Gmail**: `smtp.gmail.com`，端口 `587`
|
||
- **企业邮箱**: 联系管理员获取 SMTP 服务器地址
|
||
|
||
---
|
||
|
||
## 数据库说明
|
||
|
||
### 用户表结构
|
||
|
||
```sql
|
||
CREATE TABLE `app_user` (
|
||
`id` BIGINT(20) NOT NULL AUTO_INCREMENT COMMENT '用户ID',
|
||
`username` VARCHAR(50) NOT NULL COMMENT '用户名',
|
||
`password` VARCHAR(100) NOT NULL COMMENT '密码',
|
||
`email` VARCHAR(100) DEFAULT NULL COMMENT '邮箱',
|
||
`telephone` VARCHAR(20) DEFAULT NULL COMMENT '手机号',
|
||
`avatar` VARCHAR(255) DEFAULT NULL COMMENT '头像URL',
|
||
`login_ip` VARCHAR(50) DEFAULT NULL COMMENT '最后登录IP',
|
||
`status` TINYINT(1) DEFAULT 1 COMMENT '状态：0-禁用 1-启用',
|
||
`create_time` DATETIME DEFAULT NULL COMMENT '创建时间',
|
||
`update_time` DATETIME DEFAULT NULL COMMENT '更新时间',
|
||
PRIMARY KEY (`id`),
|
||
UNIQUE KEY `uk_username` (`username`),
|
||
UNIQUE KEY `uk_email` (`email`),
|
||
UNIQUE KEY `uk_telephone` (`telephone`),
|
||
KEY `idx_create_time` (`create_time`)
|
||
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='应用用户表';
|
||
```
|
||
|
||
---
|
||
|
||
## 错误码说明
|
||
|
||
| 错误码 | 说明 |
|
||
|--------|------|
|
||
| 200 | 成功 |
|
||
| 500 | 失败 |
|
||
|
||
---
|
||
|
||
## 开发说明
|
||
|
||
### 验证码存储
|
||
|
||
- 验证码存储在 Redis 中
|
||
- Key 格式: `verify_code:{type}:{account}`
|
||
- 有效期: 5分钟
|
||
- 验证成功后自动删除
|
||
|
||
### 密码加密
|
||
|
||
- 使用 MD5 加密
|
||
- 前端传输明文密码，后端自动加密存储
|
||
|
||
### 登录认证
|
||
|
||
- 使用 Sa-Token 进行身份认证
|
||
- Token 有效期: 30天
|
||
- 除登录、注册、发送验证码接口外，其他接口都需要认证
|
||
|
||
### 验证码发送
|
||
|
||
- **手机验证码**: 通过短信宝自动发送短信
|
||
- **邮件验证码**: 通过 Spring Mail 自动发送 HTML 格式的精美邮件
|
||
- 验证码为 6 位随机数字
|
||
- 邮件模板包含品牌样式，提升用户体验
|