为何Protobuf的map字段在Python生成代码中为RepeatedCompositeFieldContainer？

问题背景 #

我有一个定义了map<string, string>字段的.proto文件：

syntax = "proto3";

message Message {
  map<string, string> map = 1;
}

使用buf生成Python代码后，该map字段的类型注解标注为ScalarMap[str, str]，但实际运行时打印字段类型，结果却是RepeatedCompositeFieldContainer。

生成的Python代码片段：

class ExchangeAuthzCodeRequest(google.protobuf.message.Message):
    ...

    @property
    def access_token_vars(self) -> google.protobuf.internal.containers.ScalarMap[str, str]:
        ...

运行时打印类型的输出：

print(type(proto_msg.access_token_vars))
# 输出: <class 'google.protobuf.internal.containers.RepeatedCompositeFieldContainer'>

疑问 #

1. 为何map<string, string>字段在Python运行时是RepeatedCompositeFieldContainer，而非注解里的ScalarMap？
2. 这是预期行为吗？还是我的Protobuf定义或使用存在问题？

附加信息 #

• Protobuf版本：4.25.3
• mypy-protobuf版本：3.5.0
• buf配置：

version: v1
plugins:
- name: python
  out: .
- name: mypy
  out: .
- name: grpclib_python
  out: .

解答 #

1. 类型差异的原因 #

Protobuf的map字段底层是通过重复的键值对消息实现的，RepeatedCompositeFieldContainer就是这个底层实现对应的容器类型。而ScalarMap是Protobuf提供的抽象映射接口，它封装了底层的重复容器，对外暴露字典式的操作接口（比如[]取值赋值、keys()/values()方法等）。

生成代码中用ScalarMap做类型注解，是为了给mypy这类静态类型检查工具提供准确的类型提示，让开发者明确这个字段可以像字典一样操作；但运行时的实际实例是底层的重复容器——这是因为Protobuf需要保持和二进制序列化格式的兼容性，map在序列化时本质就是序列化为重复的键值对消息。

2. 是否为预期行为？ #

这是完全符合预期的正常行为，你的Protobuf定义和使用没有问题。

具体原因：

• Protobuf官方Python实现的设计就是如此：map字段的静态类型注解用ScalarMap（或对应泛型Map类型），但运行时实例是内部的重复容器，同时该容器实现了MutableMapping接口，所以你可以完全像操作普通字典一样使用这个字段，功能不受影响。
• mypy-protobuf生成的类型注解是正确的，它的作用是让静态类型检查能验证你对map字段的操作是否符合字典的使用规范，而运行时的实际类型属于Protobuf的内部实现细节，无需过度关注。

你可以正常使用该字段的所有字典式操作，比如proto_msg.access_token_vars["key"] = "value"、遍历items()等，这些操作都会正常生效。

内容的提问来源于stack exchange，提问作者yoav.weber