makeomatic/ms-mailer

邮件发送微服务镜像文档

1. 镜像概述

本镜像提供一个轻量级邮件发送微服务，专门用于通过AMQP（高级消息队列协议）接收邮件发送任务并执行。该服务设计为松耦合的微服务组件，可无缝集成到基于消息队列的分布式系统中，实现异步、可靠的邮件发送功能。

2. 核心功能与特性

• AMQP协议支持：通过监听指定AMQP路由（队列）接收邮件发送任务
• 消息任务处理：解析接收到的消息任务，提取邮件相关参数（收件人、主题、内容等）
• 邮件发送执行：连接配置的SMTP服务器并执行邮件发送操作
• 任务状态反馈：支持将邮件发送结果（成功/失败）反馈至指定AMQP响应队列
• 错误处理机制：内置重试逻辑处理临时发送失败，支持错误日志记录

3. 使用场景与适用范围

• 异步邮件发送：适用于需要非阻塞邮件发送的业务场景，如用户注册确认、订单通知等
• 分布式系统集成：作为独立微服务部署，与其他系统组件通过消息队列解耦通信
• 高并发邮件处理：支持水平扩展以应对高并发邮件发送需求
• 第三方系统通知：为各类业务系统提供统一的邮件发送接口，简化系统架构

4. 使用方法与配置说明

4.1 环境变量配置

以下环境变量为必须配置项：

可选配置项：

4.2 Docker部署示例

4.2.1 基本部署（docker run）

bash
docker run -d \
  --name mailer-microservice \
  -e AMQP_HOST=rabbitmq \
  -e AMQP_PORT=5672 \
  -e AMQP_QUEUE=email-tasks \
  -e AMQP_USER=admin \
  -e AMQP_PASSWORD=admin123 \
  -e SMTP_HOST=smtp.example.com \
  -e SMTP_PORT=587 \
  -e SMTP_USER=noreply@example.com \
  -e SMTP_PASSWORD=smtp-pass-123 \
  -e SMTP_FROM="Example Service <noreply@example.com>" \
  mailer-microservice:latest

4.2.2 Docker Compose配置

yaml
version: '3'
services:
  mailer:
    image: mailer-microservice:latest
    container_name: mailer-service
    environment:
      - AMQP_HOST=rabbitmq
      - AMQP_PORT=5672
      - AMQP_QUEUE=email-tasks
      - AMQP_USER=admin
      - AMQP_PASSWORD=admin123
      - SMTP_HOST=smtp.example.com
      - SMTP_PORT=587
      - SMTP_USER=noreply@example.com
      - SMTP_PASSWORD=smtp-pass-123
      - SMTP_USE_TLS=true
      - RETRY_MAX_ATTEMPTS=3
    depends_on:
      - rabbitmq
    restart: unless-stopped

  rabbitmq:
    image: rabbitmq:3-management
    container_name: rabbitmq
    ports:
      - "5672:5672"
      - "15672:15672"
    environment:
      - RABBITMQ_DEFAULT_USER=admin
      - RABBITMQ_DEFAULT_PASS=admin123

4.3 消息任务格式

AMQP队列中接收的消息任务需遵循以下JSON格式：

json
{
  "taskId": "unique-task-identifier",
  "recipient": "user@example.com",
  "subject": "邮件主题",
  "content": "邮件正文内容",
  "contentType": "text/plain",  // 可选，默认为text/plain，支持text/html
  "replyToQueue": "email-results"  // 可选，指定结果反馈队列
}

4.4 结果反馈格式

若指定了replyToQueue，服务会将发送结果反馈至该队列，格式如下：

json
{
  "taskId": "unique-task-identifier",
  "status": "success",  // success 或 failed
  "timestamp": "2023-10-01T12:34:56Z",
  "message": "邮件发送成功"  // 成功时为成功消息，失败时为错误信息
}