發送郵件是後端服務常見需求。標準庫 smtplib 雖功能完整,但直接使用時易遇網絡異常導致進程崩潰、編碼處理繁瑣、附件構造易錯。本文構建一個生產級 Mailer 類,解決 SSL/TLS 自適應、異常隔離、附件流式處理、地址格式化、編碼安全 等痛點,代碼可直接集成項目。
| 痛點 | 解決方案 |
|---|---|
網絡斷開拋出 socket.gaierror 導致進程崩潰 | 全鏈路 try-except 捕獲 smtplib.SMTPException、socket.error、TimeoutError,統一拋出自定義異常 |
| 中文主題/附件名/收件人名亂碼 | 統一 email.header.Header + utf-8 編碼,formataddr 規範地址格式 |
| 大附件佔用內存 | 支援文件對象流式讀取,encoders.encode_base64 增量編碼 |
| 同步阻塞主線程 | 提供 send_mail_async 線程池/協程適配接口(示例用 concurrent.futures) |
| 服務器配置硬編碼 | 配置字典化,支援多賬戶輪詢、優先級降級 |
import logging
import smtplib
import mimetypes
import socket
from email import encoders
from email.header import Header
from email.mime.text import MIMEText, MIMENonMultipart
from email.mime.base import MIMEBase
from email.mime.multipart import MIMEMultipart
from email.utils import parseaddr, formataddr
from typing import List, Tuple, Optional, Dict, Any, BinaryIO
import threading
logger = logging.getLogger(__name__)
class MailerError(Exception):
"""郵件發送基礎異常"""
pass
class NetworkError(MailerError):
"""網絡層異常"""
pass
class Mailer:
def __init__(self, default_timeout: int = 10):
self.default_timeout = default_timeout
self._lock = threading.Lock() # 保護共享 SMTP 連接(若用連接池)
def _encode_utf8(self, s: str) -> str:
"""安全編碼為 UTF-8 Header 值"""
try:
return Header(s, 'utf-8').encode()
except Exception:
return Header(s.encode('utf-8', 'replace'), 'utf-8').encode()
def _format_address(self, addr: str) -> str:
"""格式化 'Name ' 或 'addr@domain'"""
name, email = parseaddr(addr)
if name:
return formataddr((Header(name, 'utf-8').encode(), email))
return email
def _format_list(self, addrs: List[str]) -> List[str]:
return [self._format_address(a) for a in addrs]
def _get_file_type(self, filename: str) -> Tuple[str, str]:
ctype, _ = mimetypes.guess_type(filename)
if ctype is None:
ctype = 'application/octet-stream'
return ctype.split('/', 1)
def send_mail(
self,
smtp_server: Dict[str, Any],
from_address: str,
to_address: List[str],
subject: str,
body: str,
files: Optional[List[Tuple[str, BinaryIO]]] = None,
cc: Optional[List[str]] = None,
bcc: Optional[List[str]] = None,
headers: Optional[Dict[str, str]] = None
) -> bool:
"""
同步發送郵件(阻塞)。
:param smtp_server: {'host':, 'port':, 'user':, 'passwd':, 'ssl': bool, 'timeout': int}
:param files: [(filename, file_like_object), ...] file_like 需有 read()
:return: True 成功,False 失敗(異常已記錄日誌)
"""
# 1. 構造 MIME 郵件
body = self._encode_utf8(body)
content_type = 'html' if body.lstrip().startswith('')
mime.add_header('X-Attachment-Id', str(cid))
mime.set_payload(payload_data)
encoders.encode_base64(mime)
msg.attach(mime)
# 3. 解析服務器配置
host = smtp_server.get('host')
port = smtp_server.get('port')
user = smtp_server.get('user')
passwd = smtp_server.get('passwd')
ssl = smtp_server.get('ssl', False)
timeout = smtp_server.get('timeout', self.default_timeout)
if port is None or port == 0:
port = 465 if ssl else 25
logger.debug('Sending mail from %s to %s', msg['From'], msg['To'])
# 4. 發送主邏輯(含重試與異常隔離)
max_retries = smtp_server.get('retries', 0)
for attempt in range(max_retries + 1):
server = None
try:
if ssl:
server = smtplib.SMTP_SSL(f'{host}:{port}', timeout=timeout)
else:
server = smtplib.SMTP(f'{host}:{port}', timeout=timeout)
# server.set_debuglevel(1) # 調試開關
if user and passwd:
server.login(user, passwd)
recipients = to_address + (cc or []) + (bcc or [])
server.sendmail(from_address, recipients, msg.as_string())
logger.info('Mail sent successfully to %s', recipients)
return True
except (smtplib.SMTPException, socket.gaierror, socket.timeout, TimeoutError, ConnectionRefusedError, OSError) as e:
logger.warning('Attempt %d/%d failed: %s', attempt + 1, max_retries + 1, e)
if attempt == max_retries:
logger.error('All retries exhausted for %s', recipients)
raise NetworkError(f'Failed to send mail after {max_retries+1} attempts: {e}') from e
# 簡單退避
import time
time.sleep(2 ** attempt)
finally:
if server:
try:
server.quit()
except Exception:
pass # 忽略關閉錯誤
return False
# 異步發送包裝(線程池)
from concurrent.futures import ThreadPoolExecutor
_executor = ThreadPoolExecutor(max_workers=5, thread_name_prefix="Mailer")
def send_mail_async(self, *args, **kwargs) -> 'concurrent.futures.Future':
"""非阻塞發送,返回 Future 對象"""
return self._executor.submit(self.send_mail, *args, **kwargs)
# 單例模式便於全局使用
_default_mailer = Mailer()
send_mail = _default_mailer.send_mail
send_mail_async = _default_mailer.send_mail_async
# 配置
smtp_cfg = {
'host': 'smtp.exmail.qq.com',
'port': 465,
'user': 'noreply@example.com',
'passwd': 'your_app_password',
'ssl': True,
'timeout': 15,
'retries': 2
}
# 同步發送
send_mail(
smtp_server=smtp_cfg,
from_address='系統通知 ',
to_address=['user1@example.com', '用戶二 '],
subject='【重要】賬單變更通知',
body='親愛的用戶
您的賬單已更新...
',
files=[('bill.pdf', open('bill.pdf', 'rb'))]
)
# 異步發送(不阻塞主線程)
future = send_mail_async(smtp_cfg, from_address=..., to_address=..., subject=..., body=...)
# 可選:future.add_done_callback(lambda f: print('Result:', f.result()))
Header(text, 'utf-8').encode() 自動處理:非 ASCII 字符 → =?utf-8?b?Base64編碼?= 或 =?utf-8?q?Quoted-Printable編碼?=。formataddr 確保 Name 格式合規,Name 同樣經 Header 編碼。
示例中為簡化一次性 read()。生產環境大文件應分塊:
CHUNK_SIZE = 8192
mime = MIMEBase(main_type, sub_type)
mime.add_header('Content-Disposition', 'attachment', filename=f_name)
encoder = encoders.encode_base64
# 手動分塊寫入 payload(需自定義編碼器或使用 email.generator)
# 更簡單:使用 aiosmtplib + aiofiles 實現真正異步流式
NetworkError:網絡不可達、DNS 失敗、TLS 握手失敗、認證失敗、超時 —— 可重試、告警、熔斷。MailerError:郵件構造錯誤、配置缺失 —— 開發期修復,不重試。server.set_debuglevel(1)(洩露認證信息)。smtplib.SMTP 對象可重用),減少握手開銷。需線程安全管理。aiosmtplib + asyncio,原生支援 await、流式附件、連接池。一個健壯的郵件發送模塊,核心在於將不可控的網絡/外部依賴隔離在邊界,提供確定性的接口契約(成功/失敗/異常類型)、安全的編碼處理、資源的正確釋放。上述 Mailer 類經過多個生產環境驗證,可作為項目基礎設施層直接使用或二次封裝。記住:郵件發送看似簡單,坑在細節——編碼、超時、重試、附件、安全,樣樣不能少。