PureRhyme Mailer 📧

璞瑞雅诗邮件服务模块 - 基于 MidwayJS 和 Nodemailer 的企业级邮件发送服务

📖 项目简介

PureRhyme Mailer 是一个基于 MidwayJS 框架的邮件服务模块，提供稳定、可配置的邮件发送功能。支持模板化邮件内容，便于集成和维护。

✨ 核心特性

• 🚀 高性能: 基于 MidwayJS 框架，支持依赖注入和模块化架构
• 📧 邮件发送: 使用 Nodemailer 实现可靠的邮件发送服务
• 🎨 模板支持: 内置 HTML 邮件模板，支持验证码邮件等场景
• ⚙️ 配置化: 通过配置文件管理 SMTP 等参数`
• 🔒 类型安全: 完全使用 TypeScript 编写，提供完整的类型定义
• 🧪 测试覆盖: 提供 Jest 单元测试支持

📦 安装

# 使用 npm
npm install yash-mailer

# 使用 yarn
yarn add yash-mailer

# 使用 pnpm
pnpm add yash-mailer

🚀 快速开始

1. 配置邮件服务

在你的 MidwayJS 项目中添加邮件配置：

// src/config/config.default.ts
export default {
  mailer: {
    host: 'smtp.example.com',
    port: 587,
    secure: false, // true for 465, false for other ports
    auth: {
      user: '[email protected]',
      pass: 'your-password'
    }
  }
};

2. 注册服务

// src/configuration.ts
import { Configuration } from '@midwayjs/core';
import * as mailer from 'yash-mailer';

@Configuration({
  imports: [
    mailer
  ]
})
export class MainConfiguration {}

3. 使用邮件服务

import { Inject, Controller, Post, Body } from '@midwayjs/core';
import { MailService } from 'yash-mailer';

@Controller('/api/mail')
export class MailController {
  @Inject()
  mailService: MailService;

  @Post('/send-verification')
  async sendVerification(@Body() body: { email: string; code: string }) {
    await this.mailService.send({
      to: body.email,
      subject: '验证码邮件',
      html: JSON.stringify({
        code: body.code,
        event: 0 // EmailEvent.Verification
      })
    });
    
    return { success: true };
  }
}

📚 API 文档

MailService

邮件服务的主要类，提供邮件发送功能。

方法

send(options: SendMailOptions): Promise<void>

发送邮件的主要方法。

参数:

• options: Nodemailer 的 SendMailOptions 对象
  • to: 收件人邮箱地址
  • subject: 邮件主题
  • html: 邮件内容（JSON 字符串格式）

示例:

await mailService.send({
  to: '[email protected]',
  subject: '验证码邮件',
  html: JSON.stringify({
    code: '123456',
    event: EmailEvent.Verification
  })
});

sendVerificationMail(code: string, options: SendMailOptions): Promise<string>

发送验证码邮件的便捷方法。

参数:

• code: 验证码
• options: 邮件选项

返回:

• Promise<string>: 邮件消息 ID

接口定义

MailerConfigurationType

interface MailerConfigurationType {
  host: string;      // SMTP 服务器地址
  port: number;      // SMTP 端口
  secure: boolean;   // 是否使用 SSL/TLS
  auth: {
    user: string;    // 邮箱用户名
    pass: string;    // 邮箱密码
  };
}

EmailEvent

enum EmailEvent {
  Verification = 0  // 验证码邮件
}

🎨 邮件模板

验证码邮件模板

内置的验证码邮件模板具有以下特性：

• 🎨 现代化的设计风格
• 📱 响应式布局，支持移动设备
• 🔒 安全提示信息
• 🏢 品牌定制化内容

模板预览：

• 包含 PureRhyme 品牌 Logo
• 突出显示验证码（36px 大字体）
• 10分钟有效期提示
• 安全警告信息
• 隐私政策链接

🔧 开发指南

环境要求

• Node.js >= 16.x
• TypeScript ~4.8.0
• MidwayJS ^3.20.4

开发环境搭建

# 克隆项目
git clone <repository-url>
cd mailer

# 安装依赖
pnpm install

# 构建项目
pnpm build

# 运行测试
pnpm test

# 测试覆盖率
pnpm cov

# 代码检查
pnpm lint

# 修复代码格式
pnpm lint:fix

项目结构

src/
├── config/
│   └── config.default.ts     # 默认配置
├── html/
│   └── verification.ts        # 验证码邮件模板
├── service/
│   └── mailer.service.ts      # 邮件服务实现
├── configuration.ts           # MidwayJS 配置
├── index.ts                   # 模块入口
└── interface.ts              # 类型定义

test/
└── index.test.ts             # 单元测试

添加新的邮件模板

1. 在 src/html/ 目录下创建新的模板文件
2. 在 interface.ts 中添加新的邮件事件类型
3. 在 MailService 中添加对应的发送方法
4. 更新单元测试

🧪 测试

项目使用 Jest 进行单元测试：

# 运行所有测试
pnpm test

# 查看测试覆盖率
pnpm cov

# 监视模式运行测试
npm run test:watch

📋 版本发布

# 构建并发布
pnpm release

🤝 贡献指南

1. Fork 项目
2. 创建特性分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 打开 Pull Request

代码规范

项目使用 mwts 进行代码检查和格式化：

# 检查代码规范
pnpm lint

# 自动修复代码格式
pnpm lint:fix

📄 许可证

本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情。

🔗 相关链接

• MidwayJS 官方文档
• Nodemailer 文档
• PureRhyme 官网
• 隐私政策

📞 技术支持

如果您在使用过程中遇到问题，请通过以下方式联系我们：

• 提交 Issue
• 发送邮件至技术支持团队