Protocol Buffers 默认将扩展字段序列化为形如 [package.message.field] 的 JSON 键名，但可通过 json_name 选项直接指定更简洁、符合 API 一致性的字段名，无需修改底层 marshalling 逻辑。

protocol buffers 默认将扩展字段序列化为形如 `[package.message.field]` 的 json 键名，但可通过 `json_name` 选项直接指定更简洁、符合 api 一致性的字段名，无需修改底层 marshalling 逻辑。

在使用 Protocol Buffers（尤其是 proto3）进行 JSON 序列化时，扩展字段（extensions）默认会以带方括号的规范格式（如 "[my.package.MyMessage.my_extension]"）作为 JSON 键名输出。这种命名虽符合 protobuf 规范，但在实际 REST API 设计中往往显得冗长且与已有字段风格不一致，影响可读性与兼容性。

幸运的是，protobuf 提供了标准且轻量的解决方案：json_name 字段选项。该选项允许你显式声明任意字段（包括扩展字段）在 JSON 中使用的键名，完全覆盖默认行为。

✅ 正确用法示例（在 .proto 文件中定义）：

Comprehensive Three.js 3D graphics reference

详细的 Three.js 3D 图形参考，涵盖场景设置、相机、几何体、材质、光照、动画、控制器、加载器、数学工具和调试。

下载

syntax = "proto3";

package example;

import "google/protobuf/descriptor.proto";

// 定义扩展目标消息
message TargetMessage {
  // 常规字段（可选）
  string id = 1;
}

// 定义扩展消息
message ExtensionData {
  string metadata = 1;
  int32 priority = 2;
}

// 声明扩展，并通过 json_name 指定友好键名
extend TargetMessage {
  ExtensionData my_extension = 100 [json_name = "extension_data"];
}

⚠️ 注意事项：

• json_name 必须是合法的 JSON 键名字符串（建议使用小写字母+下划线或小驼峰，避免空格或特殊符号）；
• 该选项仅影响 JSON 编码/解码行为，不影响二进制 wire 格式或 gRPC 通信；
• 使用 json_name 后，反序列化（unmarshalling）时也需按此名称传入 JSON 字段，否则字段将被忽略；
• 若多个扩展共用同一 json_name，会导致 JSON 解析冲突，应确保唯一性；
• Go 中需使用 google.golang.org/protobuf/encoding/jsonpb（v2）或 google.golang.org/protobuf/encoding/protojson（推荐），旧版 github.com/golang/protobuf/jsonpb（v1）不支持扩展字段的 json_name —— 这是关键兼容性前提。

? 小贴士：对于已广泛使用的扩展，可通过添加别名字段 + json_name 并保留旧字段（标记为 deprecated = true）实现平滑迁移，兼顾向后兼容与接口整洁性。

综上，无需 hack 底层 marshalling 逻辑或自定义 encoder，只需在 .proto 中为扩展字段添加 json_name 选项，即可优雅实现语义清晰、风格统一的 JSON 接口设计。