mcp-cli-bridge: Skill for Claude Code

AOT 与 JSON 序列化经验总结

成功经验

1. JsonSerializerContext 源生成器

• .NET NativeAOT 编译必须使用 JsonSerializerContext 源生成器
• 不能使用运行时 JsonSerializer.Serialize<T> 或 JsonSerializer.Deserialize<T>
• 每个项目/模块应创建独立的 JsonSerializerContext，避免类型冲突

[JsonSerializable(typeof(MyType))]
[JsonSerializable(typeof(Dictionary<string, JsonElement>))]
[JsonSourceGenerationOptions(PropertyNamingPolicy = JsonKnownNamingPolicy.CamelCase)]
public partial class MyContext : JsonSerializerContext { }

2. 显式声明所有序列化类型

• JsonSerializerContext 必须显式声明所有序列化类型
• 包括嵌套类型如 Dictionary<string, JsonElement>
• 使用 JsonPropertyName 特性显式指定 JSON 属性名

3. Task 结果获取

• AOT 下 Task<T>.Result 属性可能被修剪
• 应使用模式匹配：task is Task<string> stringTask
• 避免使用反射获取 Result 属性

private static string GetTaskResult(Task task)
{
    if (task is Task<string> stringTask)
        return stringTask.Result;
    return string.Empty;
}

4. 单文件发布路径处理

• AppContext.BaseDirectory 在单文件发布时指向临时目录
• 应使用 Process.GetCurrentProcess().MainModule?.FileName 获取实际路径

var processDir = Path.GetDirectoryName(Process.GetCurrentProcess().MainModule?.FileName);

5. DynamicallyAccessedMembers 注解

• 必须应用于泛型参数、属性、字段等所有相关位置
• 接口和实现类的泛型注解必须一致

public void AddSingleton<
    [DynamicallyAccessedMembers(DynamicallyAccessedMemberTypes.PublicConstructors)] TService,
    [DynamicallyAccessedMembers(DynamicallyAccessedMemberTypes.PublicConstructors)] TImplementation>()

避坑指南

1. record struct 与 DynamicallyAccessedMembers

• record struct 的自动属性与 DynamicallyAccessedMembers 注解不兼容
• 应使用手动定义的结构体

// 错误
private readonly record struct ServiceRegistration(
    Type ServiceType,
    [property: DynamicallyAccessedMembers(...)] Type? ImplementationType,
    ...
);

// 正确
private readonly struct ServiceRegistration
{
    public Type ServiceType { get; }
    [DynamicallyAccessedMembers(DynamicallyAccessedMemberTypes.PublicConstructors)]
    public Type? ImplementationType { get; }
    ...
}