在分布式链路追踪体系中，Baggage机制允许在服务间传递自定义的键值对上下文，例如用户ID、租户标识或实验标志。这些值需要写入HTTP请求头，而HTTP头字段值只能包含有限的可见字符，因此必须对Baggage属性值进行百分号编码，将其转换为安全的字符串形式。本文聚焦Ruby语言环境，分析Baggage属性值编码的具体实现路径，从规范约束到内置方法对比，再到手动编码和中间件集成，给出可直接用于生产环境的代码方案。
Baggage属性值编码的必要性与规范约束
W3C Baggage规范定义了一个名为baggage的HTTP头字段，用于传播用户自定义的键值对。头部内容由多个键值对组成，使用逗号分隔，键和值之间用等号连接。例如userId=alice,tenantId=acme。当值中包含空格、逗号、等号、分号或非ASCII字符时，解析器无法区分这些字符是数据的一部分还是结构分隔符，因此必须进行编码。
规范要求Baggage属性值使用百分号编码（percent-encoding），即RFC 3986定义的方式：保留字符和所有非ASCII字节转换为%HH格式，其中HH为该字节的十六进制大写表示。空格必须编码为%20，而不是某些表单编码中的加号+。例如值a b,c=d;中文编码后应为a%20b%2Cc%3Dd%3B%E4%B8%AD%E6%96%87。如果编码不严格，下游服务解析Baggage时会出现键值错位或丢失，甚至引发请求头注入风险。
此外，键名的规则不同。Baggage键只允许token字符，例如字母、数字以及!#$%&'*+-.^_`|~中的部分字符，通常不需要编码，但实现时应当校验并拒绝非法键名。值的编码是整个链路追踪正确性的基础，下面分析Ruby中可用的实现手段。
Ruby内置方法实现字符串编码
Ruby标准库中与URL编码相关的方法主要有URI.encode_www_form_component和CGI.escape。它们都能把字符串转换为适合HTTP传输的形式，但编码规则并不完全符合Baggage的要求。URI.encode_www_form_component遵循application/x-www-form-urlencoded格式，将空格编码为加号+；CGI.escape同样把空格转换为+。Baggage规范明确要求空格必须使用%20，因此直接使用这两个方法会导致属性值在跨语言或严格实现中解析错误。
更接近的是ERB::Util.url_encode，但其内部同样沿用表单编码规则，也会把空格变成+。Ruby的URI::DEFAULT_PARSER.escape方法虽然使用RFC 3986的百分号编码，但在较新版本的Ruby中已标记为废弃，且行为可能因版本而异，不建议作为长期方案。因此，实现一个简单可控的编码函数是更稳妥的选择。
下面的代码展示了自定义的percent_encode方法，它遍历字符串的每个字节，保留RFC 3986定义的unreserved字符集（字母、数字、-._~），其余字节一律转换为大写十六进制表示。
def percent_encode(str)
unreserved = [45, 46, 95, 126] # - . _ ~
str.bytes.map do |byte|
if (48..57).include?(byte) || (65..90).include?(byte) || (97..122).include?(byte) || unreserved.include?(byte)
byte.chr
else
format('%%%02X', byte)
end
end.join
end
这个方法逐字节处理，天然支持UTF-8编码的字符串。中文字符会按照UTF-8的多字节序列分割成多个%XX片段，下游解码后仍能还原为原始字符串。例如percent_encode('a b,c=d;中文')返回a%20b%2Cc%3Dd%3B%E4%B8%AD%E6%96%87，与Baggage规范完全一致。
手动编码实现与边界情况处理
手动编码的核心在于明确哪些字节可以原样保留、哪些必须转义。根据RFC 3986，unreserved字符包括A-Z a-z 0-9 - . _ ~，共66个字符。除此之外的所有字节，包括空格、逗号、等号、分号、斜杠、问号以及大于127的字节，都需要转换为%HH。实现时不能使用正则全局替换，因为正则处理UTF-8多字节字符容易出错，逐字节遍历是最可靠的方式。
边界情况包括：空字符串返回空字符串；只包含ASCII可打印字符的值保持可读性；包含百分号本身的值（例如100%）需要编码为100%25，避免解码时歧义；控制字符如换行符n（字节0x0A）编码为%0A，防止头部注入攻击。编码后的值应当不包含任何空格、双引号、反斜杠等可能干扰HTTP头解析的字符。
键名虽然不需要百分号编码，但需要校验。Baggage规范规定键必须匹配token语法，可以使用正则A[a-zA-Z0-9!#$%&'*+-.^_`|~]+z进行验证。如果键名包含非法字符，应当拒绝该键值对或抛出异常，避免产生无效的Baggage头部。
def valid_baggage_key?(key)
key.match?(/A[a-zA-Z0-9!#$%&'*+-.^_`|~]+z/)
end
def encode_pair(key, value)
raise ArgumentError, "invalid baggage key" unless valid_baggage_key?(key)
"#{key}=#{percent_encode(value)}"
end
这里使用了match?方法避免创建匹配数据对象，适合高频调用场景。实际的Baggage头部可能是多个键值对，序列化时用逗号拼接，但不能简单拼接，因为逗号出现在值中已被编码为%2C，因此安全。
在Ruby网络服务中集成Baggage编码模块
为了便于在Rack或Rails应用中使用，可以将编码逻辑封装成一个模块。该模块提供serialize方法，接受一个哈希，返回完整的Baggage头字段值；同时提供parse方法，从请求头字符串中还原键值对。下面是一个完整的实现示例。
module BaggageCodec
module_function
def percent_encode(str)
unreserved = [45, 46, 95, 126]
str.bytes.map do |byte|
if (48..57).include