InterpolatedStringHandler 是编译器在特定条件下自动生成的高性能插值构造器，仅当定义了带 [InterpolatedStringHandler] 特性的重载方法且调用满足优化条件时启用，用于高频日志、格式化等避免字符串分配的场景。
InterpolatedStringHandler 是什么，什么时候该用
它不是用来替代普通字符串插值的语法糖，而是编译器在特定条件下自动生成的高性能插值构造器，只在你定义了接受 InterpolatedStringHandler 参数的重载方法、且调用时满足编译器优化条件时才启用。普通写法如 $"Hello {name}" 不会触发它——除非你显式写了匹配的 handler 接收方法。
典型适用场景：高频日志拼接、格式化输出（比如 ILogger.LogDebug 的底层实现）、避免临时字符串分配的性能敏感路径。
- 必须是
ref struct类型，不能装箱或逃逸到堆上 - 必须有至少一个构造函数，签名含
int literalLength, int formattedCount - 必须提供
AppendLiteral(string)和AppendFormatted等方法(T) - 调用方方法需标记
[InterpolatedStringHandler]特性
怎么写一个可被编译器识别的 handler
最简可用结构要同时满足语法和语义约束，否则编译器直接忽略 handler 路径，回落到默认 string 插值。
public ref struct MyHandler
{
private Span<char> _buffer;
private int _pos;
<pre class="brush:php;toolbar:false;">public MyHandler(int literalLength, int formattedCount, Span<char> buffer)
{
_buffer = buffer;
_pos = 0;
}
public void AppendLiteral(ReadOnlySpan<char> value)
{
value.CopyTo(_buffer[_pos..]);
_pos += value.Length;
}
public void AppendFormatted<t>(T value) where T : ISpanFormattable
{
value.TryFormat(_buffer[_pos..], out int charsWritten, default, null);
_pos += charsWritten;
}</t></char></char>
}
注意几个硬性要求：
- 构造函数参数顺序不能错：
int literalLength, int formattedCount必须在前，后续参数（如Span）可选但必须有 - 必须有
AppendLiteral和至少一个泛型AppendFormatted方法，否则编译失败 - 如果 handler 构造时传入的是栈空间（如
stackalloc char[256]），必须确保调用链不跨 async 边界
为什么加了 [InterpolatedStringHandler] 还没走 handler 路径
常见原因不是代码写错，而是调用上下文不满足编译器的“确定性优化”判断——它宁可不用也不用错。
- 目标方法未声明为
ref参数（handler 类型本身是ref struct，但接收参数必须写成ref MyHandler） - 插值表达式里用了不支持的表达式，例如
$"{GetAsyncValue().Result}"或$"{obj?.Name ?? "N/A"}"—— 编译器会因副作用/空合并运算符放弃 handler 优化 - 目标方法重载存在歧义，比如同时有
void Log(MyHandler)和void Log(string)，且调用时没有强制类型提示，编译器可能选后者 - 项目 SDK 版本低于
net6.0，或未开启10.0
验证是否生效最直接的办法：反编译生成的 IL，看是否调用了 handler 的构造和 Append 方法；或者在 handler 构造函数里抛异常，看运行时是否触发。
性能提升真实吗？要注意哪些边界问题
在纯内存操作场景（如日志缓冲区写入），能消除 90%+ 的中间字符串分配，但收益高度依赖使用方式。
- handler 自身生命周期必须短于调用栈帧——不能 return、不能赋值给字段、不能进 lambda 捕获，否则编译报错
- 如果最终还是要转成
string（比如调用ToString()），而 handler 内部用的是Span，就得额外拷贝，此时不如直接用StringBuilder配合string.Create - 多线程安全需自行保证：handler 是 ref struct，天然不共享，但如果你把它作为参数传给多个并行任务，就已违反规则
- 调试体验差：handler 实例无法在 Watch 窗口展开查看内容，只能靠日志或断点检查
_pos和缓冲区状态
真正难的不是写对 handler，而是让整个调用链从 API 设计、参数传递到执行路径都保持“无逃逸”——这需要对 Span 生命周期和编译器优化逻辑都有体感。稍有松动，就退回 string 拼接。
