用途:在 Phoenix 应用中实现邮件发送功能前使用,指导 Swoosh 的安装、配置、模板编写、投递与测试。
主要能力与规则:邮件定义放在独立模块(如 MyApp.Emails.UserEmail),不内联在 context 中;邮件模板复用 Phoenix 组件;按环境配置投递适配器(dev/test 用 Local,生产用真实适配器);用 Swoosh.TestAssertions 测试;不在 Web 请求中同步发信,改用 Oban 异步投递,简单场景可用 Task.start。
安装:在 mix.exs 添加 {:swoosh, "~> 1.14"}、{:finch, "~> 0.18"}、{:gen_smtp, "~> 1.0"},并在 application.ex 的监督树中加入 {Finch, name: MyApp.Finch}。配置后可在 iex -S mix 中用 MyApp.Mailer.deliver(Swoosh.Email.new(...)) 验证,返回 {:ok, %{}} 表示配置正确。
使用方式:定义 Mailer 模块 use Swoosh.Mailer, otp_app: :my_app;用 import Swoosh.Email 与 Phoenix.Component 构建 html_body 和 text_body;dev 配置 Swoosh.Adapters.Local 并设 config :swoosh, serve: true,可在 http://localhost:4000/dev/mailbox 预览;test 用 Swoosh.Adapters.Test;生产在 runtime.exs 用 System.get_env("SENDGRID_API_KEY") 读取密钥。投递推荐用 Oban worker(queue: :mailers, max_attempts: 3),在 context 中 Oban.insert 入队。
测试:import Swoosh.TestAssertions,使用 assert_email_sent/1 与 assert_no_email_sent/0 断言。
限制与注意:避免仅发送 HTML 邮件,应同时设置 text_body;不要在配置中硬编码 API 密钥;不要通过日志判断投递;忘记在监督树启动 Finch 会导致基于 API 的适配器失败。该技能与 oban-essentials、testing-essentials 等配套使用。