# DailyEncouragement

**Repository Path**: GeorgeZeng123/daily-encouragement

## Basic Information

- **Project Name**: DailyEncouragement
- **Description**: 每日定时发送鼓励邮件
- **Primary Language**: Java
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2025-12-17
- **Last Updated**: 2026-01-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: Java

## README

# DailyEncourageMail - 每日励志图文邮件推送系统
一个基于Spring Boot开发的**每日定时发送励志图文邮件**的Java项目，支持从远程API获取励志短句（本地兜底）、随机加载图片并内嵌到HTML邮件中，每天自动推送给指定收件人。

## 🌟 功能特性
1. **定时发送**：基于Spring Scheduler实现每天固定时间（如早8点）触发邮件发送。
2. **内容动态获取**：优先从远程`uapi`接口获取励志短句，接口失败时自动使用本地TXT文件兜底。
3. **图文邮件**：随机加载本地图片并内嵌到HTML邮件中，使用Thymeleaf渲染美观的邮件模板。
4. **多收件人支持**：配置文件中可设置多个收件人，用逗号分隔。
5. **健壮的异常处理**：邮件发送、内容加载失败时记录日志并执行兜底逻辑，保证服务稳定性。
6. **易于测试**：提供HTTP接口手动触发邮件发送，支持单元测试/集成测试。

## 🛠 技术栈
| 技术/框架                | 版本/作用                                                                 |
|-------------------------|--------------------------------------------------------------------------|
| Spring Boot             | 3.2.5（项目核心框架，快速开发）|
| Spring Mail             | 封装JavaMail，实现邮件发送（支持HTML、内嵌图片）|
| Spring Scheduler        | 轻量级定时任务框架，实现每天定时触发                                     |
| Thymeleaf               | 模板引擎，渲染HTML邮件内容（样式美观、可维护）|
| FastJSON2               | JSON解析，处理远程API返回的励志短句数据                                 |
| Lombok                  | 简化Java代码（省略getter/setter、日志声明等）|
| uapi Client             | 远程API客户端，获取励志短句                                             |
| Maven                   | 项目构建和依赖管理                                                       |

## 🚀 快速开始
### 1. 环境准备
- **JDK**：17及以上（Spring Boot 3.x要求）
- **Maven**：3.6.x及以上
- **邮箱**：支持SMTP服务的邮箱（如QQ邮箱、163邮箱、企业邮箱）
- **资源**：励志图片（jpg/png/jpeg）、本地励志短句TXT文件（兜底用）

### 2. 项目部署
#### 2.1 拉取/下载项目
将项目克隆到本地（或直接下载源码）：
```bash
git clone https://github.com/your-username/DailyEncourageMail.git
cd DailyEncourageMail
```

#### 2.2 配置修改
修改`src/main/resources/application.yml`配置文件，替换为自己的信息：
```yaml
# 邮件配置（以QQ邮箱为例）
spring:
  mail:
    host: smtp.qq.com       # SMTP服务器地址（163邮箱：smtp.163.com）
    port: 465               # SSL端口（非SSL：587）
    username: your-qq@qq.com # 发送方邮箱账号
    password: your-auth-code # 邮箱SMTP授权码（不是登录密码，需在邮箱设置中开启）
    protocol: smtps
    properties:
      mail:
        smtp:
          ssl:
            enable: true
          auth: true
        debug: false # 生产环境关闭调试

# 自定义邮件配置
mail:
  to: receiver1@xxx.com,receiver2@xxx.com # 多个收件人用逗号分隔
  subject: "每日励志短句 | 新的一天，新的开始！" # 邮件主题
  inspirational:
    text-path: classpath:inspirational/texts.txt # 本地兜底短句路径
    img-path: classpath:inspirational/images/    # 励志图片目录路径

# 远程API配置（uapi）
uapi:
  base-url: https://uapis.cn # 远程API地址
  api-key: ""                # API密钥（若无则留空）
  timeout: 5000              # 接口超时时间（毫秒）
```

#### 2.3 资源准备
在`src/main/resources`目录下创建以下文件/目录：
1. **励志短句文件**：`inspirational/texts.txt`（每行一个短句，兜底用）
   ```txt
   人生没有白走的路，每一步都算数。
   努力的意义，在于让自己有更多选择。
   今天的不开心，到此为止；明天的你，要光芒万丈。
   ```
2. **励志图片目录**：`inspirational/images/`（放入jpg/png/jpeg格式的励志图片，并添加`default.jpg`作为兜底图片）
3. **邮件模板**：`templates/inspirational-mail.html`（项目已提供，可根据需求自定义样式）

#### 2.4 打包/运行项目
##### 方式1：本地直接运行
在IDE中启动主类`com.DailyEncourageApplication`，或使用Maven命令：
```bash
mvn spring-boot:run
```

##### 方式2：打包为Jar包运行
```bash
# 打包
mvn clean package -DskipTests
# 运行Jar包
java -jar target/dailyEncourage-1.0-SNAPSHOT.jar
```

### 3. 测试项目
#### 3.1 手动触发邮件发送
启动项目后，访问以下接口手动触发邮件发送：
```
http://localhost:8080/send-mail
```
访问后，控制台会输出日志，收件人邮箱会收到励志图文邮件。

#### 3.2 定时任务测试
默认定时任务为**每天早上8点**执行，可临时修改`com.task.InspirationalMailTask`中的Cron表达式为每分钟执行一次，测试定时功能：
```java
// 注释原有定时任务，添加测试用的Cron
// @Scheduled(cron = "0 0 8 * * ?")
@Scheduled(cron = "0 */1 * * * ?") // 每分钟执行一次
```

## 📁 项目结构
```
src/main/java/com/
├── DailyEncourageApplication.java  // 项目入口类（开启定时任务）
├── controller/
│   └── TestMailController.java     // 测试接口：手动触发邮件发送
├── model/
│   └── InspirationalSaying.java    // 远程API返回的励志短句实体
├── service/
│   └── MailSendService.java        // 邮件发送核心服务
├── task/
│   └── InspirationalMailTask.java  // 定时任务类：每天触发邮件发送
└── util/
    └── InspirationalContentLoader.java // 励志内容加载工具（远程API+本地兜底+图片加载）

src/main/resources/
├── application.yml                 // 核心配置文件
├── inspirational/
│   ├── texts.txt                   // 本地兜底励志短句
│   └── images/                     // 励志图片目录（含default.jpg）
└── templates/
    └── inspirational-mail.html     // Thymeleaf邮件模板
```

## ❓ 常见问题
### 1. 邮箱发送失败：授权码错误
- **原因**：`spring.mail.password`配置的是邮箱登录密码，而非SMTP授权码。
- **解决方案**：在邮箱设置中开启POP3/SMTP（或IMAP/SMTP）服务，生成授权码并替换配置。

### 2. 远程API调用失败，使用本地兜底
- **原因**：网络问题、API地址错误、API密钥无效。
- **解决方案**：检查网络连接，确认`uapi.base-url`和`api-key`配置正确，本地`texts.txt`文件是否有有效短句。

### 3. 图片加载失败，显示默认图片
- **原因**：`inspirational/images/`目录下无有效图片，或图片格式不支持（仅支持jpg/png/jpeg）。
- **解决方案**：添加有效图片，确保`default.jpg`存在。

### 4. 定时任务不执行
- **原因**：主类未添加`@EnableScheduling`注解，或Cron表达式错误、服务器时区不一致。
- **解决方案**：检查主类注解，验证Cron表达式（可使用[在线Cron生成器](https://cron.qqe2.com/)），调整服务器时区为东八区（GMT+8）。

### 5. 邮件内容乱码
- **原因**：邮件编码未设置为UTF-8。
- **解决方案**：项目中已在`MimeMessageHelper`中指定UTF-8编码，无需额外修改。

## 📌 扩展功能（可选）
1. **失败重试**：集成`Spring Retry`，实现邮件发送失败后自动重试（如重试3次，间隔5秒）。
2. **分布式定时任务**：替换Spring Scheduler为Quartz或XXL-Job，支持分布式部署和动态调整定时任务。
3. **后台管理**：添加Spring Boot Admin或自定义页面，管理励志短句、图片、收件人列表。
4. **多渠道推送**：除邮件外，添加钉钉、企业微信、微信公众号推送功能。
5. **配置中心**：集成Nacos/Apollo，实现配置动态刷新（无需重启项目）。
6. **监控告警**：集成Prometheus+Grafana监控项目运行状态，邮件发送失败时触发告警。

## 📄 许可证
本项目采用MIT许可证开源，可自由修改、分发和使用，详情见LICENSE文件。

## 🙏 致谢
- Spring Boot官方文档：https://docs.spring.io/spring-boot/docs/current/reference/html/
- Thymeleaf官方文档：https://www.thymeleaf.org/documentation.html
- uapi接口：提供励志短句的远程API支持