需实现 IUtf8SpanFormattable 以避免 ToString() 和 Encoding.UTF8.GetBytes() 导致的两次堆分配，通过 TryFormat 直接写入 Span，手写 UTF-8 编码逻辑，严格校验目标容量并禁止任何内存分配操作。
为什么需要实现 IUtf8SpanFormattable
当你在高性能场景（如 HTTP 响应序列化、日志批量写入）中频繁调用 ToString() 并转成 UTF-8 字节数组时，会触发字符串分配 + Encoding.UTF8.GetBytes() 两次堆分配。而 IUtf8SpanFormattable 允许你绕过字符串，直接把值格式化进 Span<byte></byte>，避免 GC 压力。它不是“锦上添花”，而是高吞吐服务里降低延迟的关键路径优化。
TryFormat 方法签名和核心约束
必须实现 bool TryFormat(Span<byte> destination, out int bytesWritten, ReadOnlySpan<char> format, IFormatProvider? provider)</char></byte>。注意三点：
-
destination容量可能不足，必须先计算所需字节数（不能硬编码长度），再比较destination.Length；不足就返回false，不写任何字节 - 不能调用任何会分配内存的方法（如
string.Create、Encoding.UTF8.GetBytes(string)、ReadOnlySpan<char>.ToArray()</char>） - UTF-8 编码逻辑必须手写：ASCII 字符直接写入，Unicode 字符需按 UTF-8 规则展开为 2~4 字节（例如
'€'是0xE2 0x82 0xAC）
示例：一个只含 ASCII 的简单类型可这样写：
public bool TryFormat(Span<byte> destination, out int bytesWritten, ReadOnlySpan<char> format, IFormatProvider? provider)
{
if (destination.Length < 3) // 假设最多输出 "123"
{
bytesWritten = 0;
return false;
}
var value = this.Value; // 假设是 int
bytesWritten = 0;
// 手写整数转 ASCII 字节（简化版，实际要用 RyuJIT 内置的 Number.Formatting）
if (value == 0)
{
destination[0] = (byte)'0';
bytesWritten = 1;
return true;
}
// … 省略完整整数格式化逻辑（推荐复用 <code>System.Numerics.BigInteger.TryWriteBytes</code> 或 <code>Utf8Formatter</code> 静态方法）
return true;
}
如何安全复用 .NET 内置 UTF-8 格式化逻辑
自己手写所有类型的 UTF-8 编码极易出错（尤其浮点、日期、带 culture 的数字）。.NET 6+ 提供了可靠的底层支持：
- 对基本类型（
int、long、double、Guid），优先调用Utf8Formatter.TryFormat(value, destination, out bytesWritten, format, provider) - 对
ReadOnlySpan<char></char>，先确认是否全 ASCII（span.All(c => c ），是则逐字节复制；否则必须用 <code>Encoding.UTF8.GetEncoder()+Convert，但要注意该 API 不接受Span，需改用Span<byte></byte>临时缓冲区并控制长度 - 组合类型（如结构体）应逐字段调用各自
TryFormat，累加bytesWritten，并在每步检查剩余空间
错误示范：Encoding.UTF8.GetBytes(myString).AsSpan().CopyTo(destination) —— 这会隐式分配 string 和 byte[]，完全违背设计初衷。
调试与验证关键点
实现后容易忽略的三个破坏性问题：
- 未处理
format参数：比如用户传"X4"要求十六进制，你的实现却忽略它，始终按默认格式输出 - 未校验
provider：当provider?.GetFormat(typeof(ICustomFormatter))返回非 null 时，应委托给它，而不是直接 fallback 到默认逻辑 - 边界字节截断：例如
destination.Length == 1时，对多字节 UTF-8 字符（如中文）只写前 1 字节，导致解码失败——必须保证每个字符完整写入，否则返回false
最有效的验证方式是用 Memory<byte></byte> 创建固定大小缓冲区，传入刚好够/不够的长度，断言返回值和 bytesWritten 是否符合预期；再用 Encoding.UTF8.GetString() 解码结果，确认语义正确。
