初始版本,工具基础类
This commit is contained in:
332
docs/email.md
Normal file
332
docs/email.md
Normal file
@@ -0,0 +1,332 @@
|
||||
# 邮件工具文档
|
||||
|
||||
## 概述
|
||||
|
||||
邮件工具提供了SMTP邮件发送功能，使用Go标准库实现，无需第三方依赖。
|
||||
|
||||
## 功能特性
|
||||
|
||||
- 支持SMTP邮件发送
|
||||
- 支持TLS/SSL加密
|
||||
- 支持发送原始邮件内容（完全由外部控制）
|
||||
- 支持便捷方法发送简单邮件
|
||||
- 使用配置工具统一管理配置
|
||||
|
||||
## 使用方法
|
||||
|
||||
### 1. 创建邮件发送器
|
||||
|
||||
```go
|
||||
import (
|
||||
"github.com/go-common/config"
|
||||
"github.com/go-common/email"
|
||||
)
|
||||
|
||||
// 从配置加载
|
||||
cfg, err := config.LoadFromFile("./config.json")
|
||||
if err != nil {
|
||||
log.Fatal(err)
|
||||
}
|
||||
|
||||
emailConfig := cfg.GetEmail()
|
||||
if emailConfig == nil {
|
||||
log.Fatal("email config is nil")
|
||||
}
|
||||
|
||||
// 创建邮件发送器
|
||||
mailer, err := email.NewEmail(emailConfig)
|
||||
if err != nil {
|
||||
log.Fatal(err)
|
||||
}
|
||||
```
|
||||
|
||||
### 2. 发送原始邮件内容（推荐，最灵活）
|
||||
|
||||
```go
|
||||
// 外部构建完整的邮件内容（MIME格式）
|
||||
emailBody := []byte(`From: sender@example.com
|
||||
To: recipient@example.com
|
||||
Subject: 邮件主题
|
||||
Content-Type: text/html; charset=UTF-8
|
||||
|
||||
<html>
|
||||
<body>
|
||||
<h1>邮件内容</h1>
|
||||
<p>这是由外部构建的完整邮件内容</p>
|
||||
</body>
|
||||
</html>
|
||||
`)
|
||||
|
||||
// 发送邮件（工具只负责SMTP发送，不构建内容）
|
||||
err := mailer.SendRaw(
|
||||
[]string{"recipient@example.com"}, // 收件人列表
|
||||
emailBody, // 完整的邮件内容
|
||||
)
|
||||
if err != nil {
|
||||
log.Fatal(err)
|
||||
}
|
||||
```
|
||||
|
||||
### 3. 发送简单邮件（便捷方法）
|
||||
|
||||
```go
|
||||
// 发送纯文本邮件（内部会构建邮件内容）
|
||||
err := mailer.SendSimple(
|
||||
[]string{"recipient@example.com"},
|
||||
"邮件主题",
|
||||
"邮件正文内容",
|
||||
)
|
||||
if err != nil {
|
||||
log.Fatal(err)
|
||||
}
|
||||
```
|
||||
|
||||
### 4. 发送HTML邮件（便捷方法）
|
||||
|
||||
```go
|
||||
// 发送HTML邮件（内部会构建邮件内容）
|
||||
htmlBody := `
|
||||
<html>
|
||||
<body>
|
||||
<h1>欢迎</h1>
|
||||
<p>这是一封HTML邮件</p>
|
||||
</body>
|
||||
</html>
|
||||
`
|
||||
|
||||
err := mailer.SendHTML(
|
||||
[]string{"recipient@example.com"},
|
||||
"邮件主题",
|
||||
htmlBody,
|
||||
)
|
||||
if err != nil {
|
||||
log.Fatal(err)
|
||||
}
|
||||
```
|
||||
|
||||
### 5. 使用Message结构发送（便捷方法）
|
||||
|
||||
```go
|
||||
import "github.com/go-common/email"
|
||||
|
||||
msg := &email.Message{
|
||||
To: []string{"to@example.com"},
|
||||
Cc: []string{"cc@example.com"},
|
||||
Bcc: []string{"bcc@example.com"},
|
||||
Subject: "邮件主题",
|
||||
Body: "纯文本正文",
|
||||
HTMLBody: "<html><body><h1>HTML正文</h1></body></html>",
|
||||
}
|
||||
|
||||
err := mailer.Send(msg)
|
||||
if err != nil {
|
||||
log.Fatal(err)
|
||||
}
|
||||
```
|
||||
|
||||
## API 参考
|
||||
|
||||
### NewEmail(cfg *config.EmailConfig) (*Email, error)
|
||||
|
||||
创建邮件发送器。
|
||||
|
||||
**参数：**
|
||||
- `cfg`: 邮件配置对象
|
||||
|
||||
**返回：** 邮件发送器实例和错误信息
|
||||
|
||||
### (e *Email) SendRaw(recipients []string, body []byte) error
|
||||
|
||||
发送原始邮件内容（推荐使用，最灵活）。
|
||||
|
||||
**参数：**
|
||||
- `recipients`: 收件人列表（To、Cc、Bcc的合并列表）
|
||||
- `body`: 完整的邮件内容（MIME格式），由外部构建
|
||||
|
||||
**返回：** 错误信息
|
||||
|
||||
**说明：** 此方法允许外部完全控制邮件内容，工具只负责SMTP发送。
|
||||
|
||||
### (e *Email) Send(msg *Message) error
|
||||
|
||||
发送邮件（使用Message结构，内部会构建邮件内容）。
|
||||
|
||||
**参数：**
|
||||
- `msg`: 邮件消息对象
|
||||
|
||||
**返回：** 错误信息
|
||||
|
||||
**说明：** 如果需要完全控制邮件内容，请使用SendRaw方法。
|
||||
|
||||
### (e *Email) SendSimple(to []string, subject, body string) error
|
||||
|
||||
发送简单邮件（便捷方法）。
|
||||
|
||||
**参数：**
|
||||
- `to`: 收件人列表
|
||||
- `subject`: 主题
|
||||
- `body`: 正文
|
||||
|
||||
### (e *Email) SendHTML(to []string, subject, htmlBody string) error
|
||||
|
||||
发送HTML邮件（便捷方法）。
|
||||
|
||||
**参数：**
|
||||
- `to`: 收件人列表
|
||||
- `subject`: 主题
|
||||
- `htmlBody`: HTML正文
|
||||
|
||||
### Message 结构体
|
||||
|
||||
```go
|
||||
type Message struct {
|
||||
To []string // 收件人列表
|
||||
Cc []string // 抄送列表（可选）
|
||||
Bcc []string // 密送列表（可选）
|
||||
Subject string // 主题
|
||||
Body string // 正文（纯文本）
|
||||
HTMLBody string // HTML正文（可选）
|
||||
Attachments []Attachment // 附件列表（可选）
|
||||
}
|
||||
```
|
||||
|
||||
### Attachment 结构体
|
||||
|
||||
```go
|
||||
type Attachment struct {
|
||||
Filename string // 文件名
|
||||
Content []byte // 文件内容
|
||||
ContentType string // 文件类型
|
||||
}
|
||||
```
|
||||
|
||||
## 配置说明
|
||||
|
||||
邮件配置通过 `config.EmailConfig` 提供：
|
||||
|
||||
| 字段 | 类型 | 说明 | 默认值 |
|
||||
|------|------|------|--------|
|
||||
| Host | string | SMTP服务器地址 | - |
|
||||
| Port | int | SMTP服务器端口 | 587 |
|
||||
| Username | string | 发件人邮箱 | - |
|
||||
| Password | string | 邮箱密码或授权码 | - |
|
||||
| From | string | 发件人邮箱地址 | Username |
|
||||
| FromName | string | 发件人名称 | - |
|
||||
| UseTLS | bool | 是否使用TLS | false |
|
||||
| UseSSL | bool | 是否使用SSL | false |
|
||||
| Timeout | int | 连接超时时间（秒） | 30 |
|
||||
|
||||
## 常见SMTP服务器配置
|
||||
|
||||
### Gmail
|
||||
```json
|
||||
{
|
||||
"host": "smtp.gmail.com",
|
||||
"port": 587,
|
||||
"useTLS": true,
|
||||
"useSSL": false
|
||||
}
|
||||
```
|
||||
|
||||
### QQ邮箱
|
||||
```json
|
||||
{
|
||||
"host": "smtp.qq.com",
|
||||
"port": 587,
|
||||
"useTLS": true,
|
||||
"useSSL": false
|
||||
}
|
||||
```
|
||||
|
||||
### 163邮箱
|
||||
```json
|
||||
{
|
||||
"host": "smtp.163.com",
|
||||
"port": 25,
|
||||
"useTLS": false,
|
||||
"useSSL": false
|
||||
}
|
||||
```
|
||||
|
||||
### 企业邮箱（SSL）
|
||||
```json
|
||||
{
|
||||
"host": "smtp.exmail.qq.com",
|
||||
"port": 465,
|
||||
"useTLS": false,
|
||||
"useSSL": true
|
||||
}
|
||||
```
|
||||
|
||||
## 注意事项
|
||||
|
||||
1. **推荐使用SendRaw方法**：
|
||||
- `SendRaw`方法允许外部完全控制邮件内容
|
||||
- 可以构建任意格式的MIME邮件（包括复杂附件、多部分内容等）
|
||||
- 工具只负责SMTP发送，不构建内容
|
||||
|
||||
2. **邮件内容构建**：
|
||||
- 使用`SendRaw`时，需要外部构建完整的MIME格式邮件内容
|
||||
- 可以参考RFC 5322标准构建邮件内容
|
||||
- 便捷方法（`Send`、`SendSimple`、`SendHTML`）内部会构建简单格式的邮件内容
|
||||
|
||||
3. **密码/授权码**：
|
||||
- 很多邮箱服务商需要使用授权码而不是登录密码
|
||||
- Gmail、QQ邮箱等需要开启SMTP服务并获取授权码
|
||||
|
||||
4. **端口选择**：
|
||||
- 587端口：通常使用TLS（STARTTLS）
|
||||
- 465端口：通常使用SSL
|
||||
- 25端口：通常不使用加密（不推荐）
|
||||
|
||||
5. **TLS vs SSL**：
|
||||
- UseTLS=true：使用STARTTLS（推荐，端口587）
|
||||
- UseSSL=true：使用SSL（端口465）
|
||||
|
||||
6. **错误处理**：
|
||||
- 所有操作都应该进行错误处理
|
||||
- 建议记录详细的错误日志
|
||||
|
||||
## 完整示例
|
||||
|
||||
```go
|
||||
package main
|
||||
|
||||
import (
|
||||
"log"
|
||||
|
||||
"github.com/go-common/config"
|
||||
"github.com/go-common/email"
|
||||
)
|
||||
|
||||
func main() {
|
||||
// 加载配置
|
||||
cfg, err := config.LoadFromFile("./config.json")
|
||||
if err != nil {
|
||||
log.Fatal(err)
|
||||
}
|
||||
|
||||
// 创建邮件发送器
|
||||
mailer, err := email.NewEmail(cfg.GetEmail())
|
||||
if err != nil {
|
||||
log.Fatal(err)
|
||||
}
|
||||
|
||||
// 发送邮件
|
||||
err = mailer.SendSimple(
|
||||
[]string{"recipient@example.com"},
|
||||
"测试邮件",
|
||||
"这是一封测试邮件",
|
||||
)
|
||||
if err != nil {
|
||||
log.Fatal(err)
|
||||
}
|
||||
|
||||
log.Println("邮件发送成功")
|
||||
}
|
||||
```
|
||||
|
||||
## 示例
|
||||
|
||||
完整示例请参考 `examples/email_example.go`
|
||||
|
||||
Reference in New Issue
Block a user