mailgun api v4 的 go 客户端必须使用 mailgun-go v4.0.0+，初始化需传 domain 和 private-key，发信仅支持已验证邮箱，html 邮件须用 embed.fs 预编译模板并避免内联样式，定时任务应使用 robfig/cron/v3，健康检查依赖本地 sync.map 缓存心跳，且域名 dns 验证须提前 48 小时完成。
Mailgun API v4 的 Go 客户端必须用 mailgun-go 且版本不能低于 v4.0.0
Mailgun 在 2023 年底已全面停用 v3 API，所有新注册账户仅支持 v4，老账户也强制迁移。用错版本会导致 HTTP 404 或 HTTP 401（提示 “API endpoint not found” 或 “Invalid credentials”），不是密钥问题，而是请求路径和鉴权方式变了。
实操建议：
- 用
go get github.com/mailgun/mailgun-go/v4@v4.0.0显式拉取 v4，别依赖go mod tidy自动选版——它可能默认拉 v3 - v4 的 client 初始化必须传
mailgun.NewClient(<domain>, <private-key>)</private-key></domain>，domain是你在 Mailgun 控制台看到的完整域名（如"sandbox123456789.mailgun.org"），不是子域名或别名 - 发信时必须用
mg.Send(ctx, msg)，其中msg是mailgun.Message类型，且To字段必须是已验证邮箱（测试期只能发给验证过的地址）
健康周报邮件内容需用 text/html 模板 + template.ParseFS 动态渲染
纯文本邮件无法展示服务状态表格、颜色标记、超链接跳转，但 Mailgun 不支持直接传 HTML 字符串——它会过滤掉 <style></style> 和内联样式，导致排版崩坏。正确做法是把 HTML 模板文件预编译进二进制，运行时注入数据。
实操建议：
- 模板文件（如
report.html）放在templates/目录下，用embed.FS加载：var templates embed.FS func init() { templates = template.Must(template.ParseFS(templates, "templates/*.html")) } - 模板里避免写
style="color:red"，改用内联 class（如<span class="status-down"></span>），再在<style></style>块里定义基础 CSS（Mailgun 允许内联<style></style>） - 调用渲染时传入结构体，字段名首字母大写（Go 模板反射要求），例如：
type ReportData struct { Services []ServiceStatus }
定时任务用 github.com/robfig/cron/v3 而非 time.Ticker
time.Ticker 在进程重启后无法恢复上次执行时间，且不支持表达式（比如“每周一上午 9 点”），硬编码 sleep 逻辑极易漂移。而 cron 库能精准按 cron 表达式调度，且支持 WithChain 插入日志、panic 捕获等中间件。
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
实操建议：
- 用
cron.New(cron.WithLogger(cron.DefaultLogger))初始化，避免 panic 导致整个调度器挂掉 - 添加 job 时用
Every(7*24*time.Hour)不可靠（启动时间影响首次触发），应写成"0 0 9 * * 1"（UTC 时间周一早 9 点） - 务必在
main()退出前调用c.Stop()，否则程序 kill 后 goroutine 可能残留
健康检查结果聚合必须走本地缓存，不能每次发信都实时调用各微服务
周报不是实时告警，若每封邮件生成都去轮询所有服务的 /health 接口，既增加被限流风险，又可能因某服务临时抖动导致误报。应该让各服务主动上报状态，后端只读缓存。
实操建议：
- 用
sync.Map存储各服务最新心跳时间戳（key 是 service name，value 是time.Time），比 Redis 更轻量、无网络延迟 - 各微服务每 30 秒 POST 到本服务的
/api/heartbeat，带{"service": "auth", "status": "ok"}，本服务更新sync.Map并刷新过期时间 - 发周报时只查缓存：若某服务最近 2 分钟无心跳，就标为
DOWN；否则标为UP，不重试、不 fallback
Mailgun 的 rate limit 是每分钟 300 封邮件，但更重要的是它的 DNS 验证和发信域名配置容易卡在“pending verification”状态——这不会报错，但邮件永远发不出。上线前务必在控制台确认 domain status 是 active，且 MX 记录已生效满 48 小时。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
