gRPC 国际化完全指南：非英文环境下各 API 字段的字符集、编码规则与底层实现

gRPC 作为通用 RPC 框架，其调用方与服务方可能身处完全不同的语言环境，因此本文档 doc/internationalization.md 系统梳理了在非英文环境下使用 gRPC 各 API 元素时应遵循的字符集与编码约定——哪些字段允许承载各国语言文字、哪些字段被刻意限制为 ASCII、以及它们在网络传输层分别以何种形式编码。读完本文，你将清楚知道：方法名、主机名、状态消息、metadata 的 key 与 value 各自应使用何种语言类型表示、哪些会自动做 percent-encoding、哪些需要你自行做 punycode 转换，并能从本仓库源码层面理解这些规则背后的协议约束与性能考量。

国际化设计的总体原则：能承载非英文的字段与刻意 ASCII-only 的字段

文档开篇即点明 gRPC 国际化的两条并行原则：部分 API 元素必须能够表示非英文内容（如面向用户展示的状态描述文字），而另一部分元素则被有意保留为纯 ASCII，理由是"简洁与性能"（simplicity & performance）。

API 元素	是否允许非英文字符	传输层表示	语言层推荐类型
RPC 方法名（Method name）	否，ASCII-only	HTTP/2 文本头字段值（:path）	string
主机名（Host name）	允许（需 punycode）	punycode 编码后的字符串	string / unicode string
状态详情/消息（Status detail/message）	允许，含各国字母字符	unicode 字符串，线上自动 percent-encoded	unicode string
Metadata key	否（由 HTTP/2 头字段名规则限定）	HTTP/2 header/trailer 名称	string
Metadata 值（文本型）	否（由 HTTP/2 头字段文本值规则限定）	HTTP/2 header/trailer 文本值	string
Channel target（建连目标）	文档标注为 TBD（未决）	—	—

理解这张表是掌握 gRPC 国际化的起点：面向机器的标识符（方法名、metadata key/value）走 ASCII，面向人的文本（状态消息）走 unicode。下面逐一深入。

RPC 方法名（Method name）：刻意 ASCII 化的"热路径"字段

规则与动机

文档对方法名给出了明确的约束：

Method names are ASCII-only and may only contain characters allowed by HTTP/2 text header values.

即方法名仅允许 ASCII 字符，且字符集合还受 HTTP/2 文本头字段值合法字符集限制。其背后的动机有两个层面：

1. 协议层面的先天限制：gRPC 调用时方法名会被拼进 HTTP/2 请求行的 :path 伪头中。见本仓库协议文档 doc/PROTOCOL-HTTP2.md 中 Path → "/" Service-Name "/" {_method name_} 的定义，其实际形态如 :path = /google.pubsub.v2.PublisherService/CreateTopic（doc/PROTOCOL-HTTP2.md）。既然 :path 是 HTTP/2 的文本头字段值，方法名自然不能超出 HTTP/2 文本字段可承载的字符范畴。
2. 性能层面的刻意取舍：文档明确指出，方法名处理处于整个 RPC 调用链路中非常热（hot）的代码路径上，每多做一次编码/解码转换都会带来不必要的开销，因此设计上直接禁止非 ASCII 字符，从源头省掉任何额外的编解码步骤。

protobuf 的额外限制

文档还提醒：大多数 gRPC 服务基于 protobuf 定义，而 protobuf 对方法名/服务名只允许一个比上述子集更严格的 ASCII 子集（标识符规则，如字母、数字、下划线）。因此对于 protobuf 服务，"方法名无法承载非英文"实际上几乎不构成任何限制——服务端生成代码中的方法标识符天然就是 ASCII 的。

语言层推荐表示

文档推荐在语言 API 中以 string 类型表示方法名（例如 "/helloworld.Greeter/SayHello" 这样的完整方法路径或方法短名）。由于约束本身就是 ASCII，普通字节串即可，无需 unicode 语义。

主机名（Host name）：punycode 由用户负责，框架不代劳

规则：使用国际化域名需自行提供 punycode 形式

域名系统（DNS）本身只支持 ASCII 字符，国际化域名（IDN）在标准上是通过 punycode（RFC 3492）转换成以 xn-- 开头的 ASCII 兼容编码（ACE）形式后进入 DNS 与传输层的。gRPC 文档对主机名的规定是：

Host names are punycode encoded, but the user is responsible for providing the punycode-encoded string.

也就是说，gRPC 核心不会把中文域名（或其他非英文域名）自动转成 punycode——如果你希望使用国际化主机名，必须由你在调用侧先把域名转换为 punycode 编码后的字符串（如 xn--...），再交给 gRPC。这与"方法名不能传中文"不同：主机名在字符能力上是支持国际化的，只是转换责任在调用方。

语言层推荐表示与覆盖限制

• 语言 API 中推荐使用 string / unicode string 表示（因为在某些语言绑定层可能同时暴露原始 unicode 与已编码串）。
• 文档特别强调了一个重要限制：在发起 RPC 时覆盖（override）主机名/authority 的能力，仅由 C-core 实现的 gRPC（即所有绑定到底层 C-core 的语言实现）支持，纯上层实现无法做到。这提醒跨语言使用者，若需要通过 authority 覆盖来路由请求，需确认当前语言绑定基于 C-core。

状态消息（Status detail/message）：唯一"官方欢迎"各国文字、并自动 percent-encoding 的字段

规则

与面向机器的方法名、主机名不同，状态消息是**预期要包含各民族字母字符（national-alphabet characters）**的字段——因为它是直接展示给最终用户看的错误说明。规则如下：

Allowed values are unicode strings (content will be percent-encoded on the wire).

• 允许值：unicode 字符串；
• 线上行为：内容会被 percent-encoded（百分号编码）后再传输。

底层实现佐证：两处源码都能看到状态消息的 percent-encoding

文档所说的"线上 percent-encoded"并非抽象描述，本仓库源码中有两处直接印证：

1. HTTP/2 服务端过滤器：在 src/core/ext/filters/http/server/http_server_filter.cc 中，FilterOutgoingMetadata 会在把服务端返回的 grpc-message（即状态消息）写出去之前，执行：

void FilterOutgoingMetadata(ServerMetadata* md) {
  if (Slice* grpc_message = md->get_pointer(GrpcMessageMetadata())) {
    *grpc_message = PercentEncodeSlice(std::move(*grpc_message),
                                       PercentEncodingType::Compatible);
  }
}

2. 状态转 protobuf：在 src/core/util/status_helper.cc 的 StatusToProto 中，把 absl::Status 转成 google.rpc.Status 消息时同样先做一次 percent-encoding，源码注释解释了原因：protobuf string 字段要求 UTF-8 编码，但 C++ string 并不强制这一点，所以需要先转换成 percent-encoded 字符串以保持其是合法的 UTF-8：

// Protobuf string field requires to be utf-8 encoding but C++ string doesn't
// this requirement so it can be a non utf-8 string. So it should be converted
// to a percent-encoded string to keep it as a utf-8 string.
Slice message_percent_slice =
    PercentEncodeSlice(Slice::FromExternalString(status.message()),
                       PercentEncodingType::Compatible);

percent-encoding 的两个变体（理解"Compatible"是关键）

两个调用点都使用了 PercentEncodingType::Compatible 而非 URL 变体。二者的差异定义在 src/core/lib/slice/percent_encoding.h：

• PercentEncodingType::URL：仅将 [A-Za-z0-9-_.~] 视为无需编码的 unreserved 字节（严格的 URL 编码，对应 RFC 3986）；
• PercentEncodingType::Compatible：将 ascii7 非控制字符中除 % 以外的全部字节视为无需编码的字节。

据此可以推断：状态消息走的是 "HTTP/2 兼容" 变体，即常规可打印 ASCII 字符（如英文与常见标点）原样传输，只有非 ASCII 部分（例如中文等 UTF-8 编码下逐字节大于 0x7E 的字节）才被编码为 %XX，同时 % 本身会被编码为 %25——这样既保证了对人可读的文本尽可能保持可读，又保证整串内容落在 HTTP/2 文本字段的合法范围内。解码侧则由 PermissivePercentDecodeSlice 负责，如其头文件注释所述是"宽容（permissive）"解码：遇到无法解码的 % 三元组时原样透传、不会失败。

Metadata key：由 HTTP/2 头字段名规则限定的 ASCII 名称

规则

Allowed values are defined by HTTP/2 standard (metadata keys are represented as HTTP/2 header/trailer names).

metadata 的 key 在 wire 上直接映射为 HTTP/2 的 header/trailer 字段名（如 grpc-timeout、authorization），因此其合法字符集完全由 HTTP/2 对头字段名的规定决定，本质上只允许 ASCII 字符，且按规范应使用小写。

底层实现佐证：源码用位图精确限定合法 key 字节

本仓库 src/core/lib/surface/validate_metadata.cc 用编译期构造的 BitSet<256> 精确刻画了 gRPC 实际放行的 metadata key 字节集合：

constexpr LegalHeaderKeyBits() {
  for (int i = 'a'; i <= 'z'; i++) set(i);
  for (int i = '0'; i <= '9'; i++) set(i);
  set('-');
  set('_');
  set('.');
}

也就是说，gRPC 实现层的合法 key 为：小写字母 a-z、数字 0-9，以及 -、_、. 三种符号——比 HTTP/2 文本字段理论上允许的字符还要收紧，从实现上杜绝了非 ASCII key。校验入口 ValidateHeaderKeyIsLegal（见 src/core/lib/surface/validate_metadata.cc）以及 C 接口 grpc_validate_header_key_is_legal 被调用栈上的多个位置使用，例如 src/core/lib/surface/filter_stack_call.cc、src/core/lib/surface/call_utils.cc 以及 src/core/credentials/call/plugin/plugin_credentials.cc 等，凡是有 metadata 写入/注入的地方都会先做合法性校验。

因此在使用层面可以总结出两条硬性约束：metadata key 必须全部为 ASCII（推荐小写 a-z、数字与 -_.），不要用中文等非英文 key；语言 API 中推荐以 string 类型携带。

Metadata 值（文本型 Metadata value）：HTTP/2 文本值的 ASCII 边界与二进制 metadata 的区分

规则

Allowed values are defined by HTTP/2 standard (metadata values are represented as HTTP/2 header/trailer text values).

文本型 metadata 的值在 wire 上表现为 HTTP/2 的 header/trailer 文本值，其合法范围同样由 HTTP/2 文本字段规则限定。

底层实现佐证：非二进制值校验为可打印 ASCII 0x20–0x7E

src/core/lib/surface/validate_metadata.cc 中的 LegalHeaderNonBinValueBits 定义了"非二进制（non-binary）"文本值的合法集合：

constexpr LegalHeaderNonBinValueBits() {
  for (int i = 32; i <= 126; i++) {
    set(i);
  }
}

即 ASCII 可打印字符范围（空格到 ~），配合 ValidateNonBinaryHeaderValueIsLegal（validate_metadata.cc）逐字节校验。这也印证了社区普遍经验：gRPC 文本型 metadata 值必须是 ASCII；直接塞入中文 UTF-8 字节会导致非法值错误。

需要承载非英文/任意字节时：使用 -bin 二进制 metadata

理解了上面的边界后，一个自然的追问是：metadata 想携带 UTF-8 文本（或任意字节序列）该怎么办？答案是 gRPC 提供了一类特殊的 二进制（binary）metadata：以 -bin 后缀结尾的 key 被标记为二进制 header，其值允许任意字节并在 wire 上以 Base64 文本形式传输。源码中同样可以看到这一分类逻辑，例如 src/core/lib/surface/validate_metadata.cc 中的 grpc_is_binary_header / grpc_key_is_binary_header 即用于判断某 key 是否为 -bin 二进制 header。这是 metadata 中"非英文内容"的官方通道——需要 UTF-8/多语言内容的 metadata 值应选择 -bin 后缀的二进制 metadata，而普通文本型 metadata 值应保持在 ASCII 内。

Channel target（建连目标）：文档中标注 TBD 的开放问题

文档在 channel 创建场景的 target（channel target）一项下目前仅标注了 TBD（待定），即 gRPC 官方尚未在本文档中对 target 的国际化字符规则给出最终结论。在使用时建议仍以 ASCII 目标字符串（如 dns:///host:port、unix:///path 等 target 语法）为准；如需通过国际化主机名建连，走前文所述的 punycode 主机名路径，并留意该 target 中 host 部分的编码语义后续可能随文档更新而明确。

总结：一张图记住 gRPC 国际化规则

用一句话概括全文：gRPC 只在"给人看"的状态消息（status message）上无条件支持各国文字（自动 percent-encoding），其余面向协议的标识符——方法名、主机名、metadata key 与文本值——都停留在 ASCII 世界；国际化主机名需调用方自行 punycode 编码，metadata 若要携带多语言/二进制内容则应选用 -bin 二进制 metadata 通道。语言 API 层的推荐类型（string / unicode string）与上述 wire 表示一一对应，跨语言使用者（C++、Python、Ruby、Objective-C、PHP、C# 等基于 C-core 的实现）遵循同一套约束。相关深入材料可继续阅读：

• 国际化规则原文：doc/internationalization.md
• HTTP/2 上的方法名/路径编码细节：doc/PROTOCOL-HTTP2.md
• percent-encoding 双变体实现：src/core/lib/slice/percent_encoding.h、src/core/lib/slice/percent_encoding.cc
• 状态消息编码现场：src/core/ext/filters/http/server/http_server_filter.cc、src/core/util/status_helper.cc
• metadata key/value 合法性位图：src/core/lib/surface/validate_metadata.cc