# rpc 错误：code = Internal，desc = 头部键 "X-User-ID" 包含不可打印 ASCII 字符的值

- **ID:** `go/grpc-metadata-key-invalid`
- **领域:** go
- **类别:** data_error
- **验证级别:** ai_generated
- **修复率:** 80%

## 根因

gRPC 元数据键必须为小写 ASCII；值必须为可打印 ASCII。含大写字母的键或含控制字符的值违反规范。

## 版本兼容性

| 版本 | 状态 | 引入 | 弃用 |
|------|------|------|------|
| google.golang.org/grpc 1.0+ | active | — | — |

## 解决方案

1. **** (95% 成功率)
   ```
   Normalize keys to lowercase and use -bin suffix for binary values:
md := metadata.Pairs(
    "x-user-id", userID,
    "x-trace-bin", string(traceBytes),
)
ctx = metadata.NewOutgoingContext(ctx, md)
   ```
2. **** (85% 成功率)
   ```
   Sanitize values before attaching:
func sanitize(s string) string {
    return strings.Map(func(r rune) rune {
        if r >= 0x20 && r < 0x7f { return r }
        return -1
    }, s)
}
   ```

## 无效尝试

- **** — Base64 helps only for binary values when the key ends in -bin; a non-printable value on a non-bin key still fails. (70% 失败率)
- **** — The metadata is malformed deterministically; retries fail identically. (95% 失败率)