本文详解在 Go 中绕过 FCM/GCM data 字段仅支持 map[string]string 的限制，安全、兼容地发送 JSON 序列化的复杂数据结构（如嵌套 struct、slice），并提供两种实践方案：客户端序列化封装与自定义 Client 扩展。
本文详解在 go 中绕过 fcm/gcm `data` 字段仅支持 `map[string]string` 的限制，安全、兼容地发送 json 序列化的复杂数据结构（如嵌套 struct、slice），并提供两种实践方案：客户端序列化封装与自定义 client 扩展。
FCM（Firebase Cloud Messaging）官方明确要求 data 负载必须是扁平的 map[string]string，这是为保障跨平台兼容性与服务端解析稳定性而设定的设计约束。但实际业务中，常需传递结构化信息——例如用户通知详情（含 ID、标题、标签列表、时间戳）、订单状态变更（含商品数组、金额明细）等。直接违反该约定可能导致消息被截断、丢弃，或客户端解析失败。幸运的是，我们可在不破坏协议合规性的前提下，巧妙实现复杂数据传输。
✅ 方案一：JSON 序列化 + 单字段封装（推荐，零依赖、高兼容）
这是最稳妥、无需修改 SDK 的方式：将任意 Go 结构体（支持嵌套、切片、指针等）预先序列化为 JSON 字符串，再作为单一 string 值存入 data 映射的某个 key 下。
type NotificationPayload struct {
ID int `json:"id"`
Title string `json:"title"`
Tags []string `json:"tags"`
Metadata struct {
CreatedAt string `json:"created_at"`
Priority int `json:"priority"`
} `json:"metadata"`
}
func buildFCMPayload() (map[string]string, error) {
payload := NotificationPayload{
ID: 123,
Title: "新订单已确认",
Tags: []string{"order", "confirmed"},
Metadata: struct {
CreatedAt string `json:"created_at"`
Priority int `json:"priority"`
}{
CreatedAt: time.Now().Format(time.RFC3339),
Priority: 1,
},
}
b, err := json.Marshal(payload)
if err != nil {
return nil, fmt.Errorf("failed to marshal payload: %w", err)
}
// 注意：key 名可自定义（如 "payload"、"data_json"），但值必须是 string
return map[string]string{
"payload": string(b), // ← 关键：整个 JSON 作为 string 存入
}, nil
}
客户端接收时需反序列化：
Android/iOS/JS 端需从 data.payload 取出字符串，并手动 JSON.parse()（Web）或 new JSONObject()（Android）还原为对象。务必做异常处理，因网络传输或编码问题可能导致 JSON 损坏。
⚠️ 注意事项：
- 避免使用 json.RawMessage 直接赋值——它不是 string，会触发 FCM SDK 类型检查失败；
- 总 payload 大小仍受 FCM 限制（4KB for data-only messages），序列化后字符串长度需计入；
- Key 名建议语义化（如 "payload"），避免与业务字段冲突（如不要用 "id" 或 "title" 作外层 key）。
✅ 方案二：扩展 FCM Client（进阶，需维护 fork）
若项目长期重度依赖复杂数据，且团队有能力维护 SDK 分支，可升级 Data 字段类型为 interface{}，使其接受任意 JSON-serializable 值：
// 修改原 google/go-gcm 或 firebase-admin-go 中的 Message 定义
type Message struct {
// ...
Data interface{} `json:"data,omitempty"` // ← 替换原 map[string]string
// ...
}
// 使用时直接传 struct：
msg := &Message{
Token: "abc123...",
Data: NotificationPayload{...}, // 自动由 json.Marshal 处理
}
此方式更符合 Go 的类型表达力，但存在风险：
- 违反 FCM 官方文档契约，未来 API 升级可能引入静默兼容问题；
- 服务端若严格校验 data 类型（如 Firebase 后台），可能拒绝非 object 请求；
- 需自行确保 Data 值可被 json.Marshal 安全序列化（避免 nil slice、不可导出字段等）。
? 最佳实践总结
| 场景 | 推荐方案 | 理由 |
|---|---|---|
| 快速上线、多端兼容、低维护成本 | 方案一（JSON 封装） | 符合协议、无 SDK 依赖、调试直观 |
| 内部系统、强类型需求、长期演进 | 方案二（Client 扩展） | 减少重复序列化、提升开发体验，但需承担兼容性风险 |
| 强烈不建议 | 尝试手动拼接嵌套 map[string]string（如 "user.name"） | 易出错、无法表达数组、客户端解析逻辑碎片化 |
最终，遵循 FCM 设计初衷——保持 data 为扁平字符串映射，将结构化逻辑下沉至单字段内，是平衡健壮性与灵活性的黄金法则。复杂数据不是被禁止，而是需要你主动“打包”与“解包”。
