ImprovWifi 跨平台传输层设计：把协议层做薄，把宿主层做稳

本文基于 Sang.ImprovWifi 的实践，分享我如何把 Improv 协议层抽离成可复用内核，再通过 Windows/Linux/AOT 三种宿主实现完成跨平台落地。

1. 引言

前面我已经写过几篇关于 Improv Wi-Fi 的文章，主要是介绍其如何使用。这里我想从设计的角度聊聊我在实现 Sang.ImprovWifi 时的一些思路和教训，尤其是如何把协议层做薄、宿主层做稳，从而实现真正可维护的跨平台代码。

这篇文章就来聊聊这个设计思路的细节，在开发跨平台的服务时，经常遇到一个看似普通、实则很痛的问题：同样的业务逻辑，一换平台就要重写一遍 BLE 代码。

这件事最直接的后果，不是开发慢，而是质量不一致。Windows 版稳定，Linux 版可能刚起步；Linux 版修了一个 bug，Windows 版又漏同步。久而久之，项目维护会越来越吃力。

在设计 Sang.ImprovWifi 时，我的核心尝试就是把这件事反过来：

协议层只做协议
宿主层只做平台
业务层只做业务

听起来像一句"架构口号"，但实践下来，它确实能显著降低复杂度。

2. 为什么要先做协议层

Improv 本身是开放协议，核心其实不复杂：

设备暴露固定 Service 和 Characteristic
客户端写入 RPC Command（如 Identify、Wi-Fi 配置）
设备更新状态并返回 RPC Result URL

真正复杂的是"状态一致性"和"事件语义"，比如：

授权前后状态怎么切
校验失败时返回哪个错误码
何时触发 ProvisioningRequested
RpcResult 的 payload 如何编码

这些都属于协议语义，天然应该独立于平台。

所以我在项目里先做了 ImprovWifi.Protocol，把这些东西收敛成可复用模型，而不是散落在每个平台实现里。

3. 三层结构

项目结构大致如下：

ImprovWifi.Protocol
- 协议常量
- ImprovPacketCodec
- ImprovService 状态机
- 事件模型与通用传输抽象
平台传输层
- ImprovWifi.Transport.Windows
- ImprovWifi.Transport.Linux
- ImprovWifi.Transport.Linux.Aot
Demo 层
- ImprovWifi.Demo.Windows
- ImprovWifi.Demo.Linux
- ImprovWifi.Demo.Linux.Aot

这个分层的核心好处，是把"变化频率不同"的代码分离。

协议变化频率低，但正确性要求高
平台实现变化频率高，且受系统能力影响大
Demo 变化更快，主要用于验证场景

把它们揉在一起，维护成本会指数上升。

4. 事件驱动模型

我在 ImprovTransportServer 里提供了一组业务友好的事件：

ProvisioningRequested
IdentifyRequested
CurrentStateChanged
ErrorStateChanged
RpcResultChanged

这组事件的价值在于：

平台差异被屏蔽
业务代码只关注输入和输出
上层可以非常自然地接入真实联网逻辑

例如，你可以在 ProvisioningRequested 里调用系统网络栈；成功后调 CompleteProvisioning(url)，失败就调 FailProvisioning(error)。这个编程模型在 Windows 和 Linux 上是一致的。

5. Linux AOT 版的意义：给受限设备一条工程化路径

ImprovWifi.Transport.Linux.Aot 不是"多写一个版本"，而是为了真实设备场景。

很多 ARM 小板上，AOT + native 是更现实的组合：

启动路径更可控
依赖更可控
跨架构分发更可控

在这个版本里，我做的不是"把 C# 全部改成 Rust"，而是只把最贴近 BlueZ 的部分放进 Rust，再通过 C ABI 暴露能力。这样我们保留了 .NET 协议层和上层业务的一致性。

5.1 为什么选择 Rust

早期 ImprovWifi.Transport.Linux 依赖的是 Linux.Bluetooth，这条路径在 AOT 下问题比较明显，核心不是业务逻辑，而是运行时兼容和底层行为稳定性。

后面我又尝试替换到 Tmds.DBus 路线，这一步确实解决了一部分问题，但在我这块测试板上，AOT 仍然不是"稳定可交付"的状态，尤其是在重复启动和异常恢复这类真实场景里。

这里做了一个对比测试，使用了"假 AOT"方式，也就是单文件发布 + 裁剪，不是严格意义上的 Native AOT，这样在板子上测试发现业务流程本身是没问题的。

也就是说，问题并不在 Improv 协议逻辑，而是在 AOT + Linux BLE 宿主这层的可控性。

到这里，方向就很清晰了：

协议层保留在 .NET
Linux BLE 宿主下沉到更可控的 native 层
用稳定 C ABI 连接两侧

于是我最终选择了 Rust 自研这条路，要把 AOT 场景做稳，必须把最底层那部分拿回可控范围。

5.2 Rust 项目和 C ABI 设计

这条路也并不是一帆风顺，中间折腾了不少，经历了：

打包 NuGet 里 native 文件路径不对
回调递归调用导致死循环，CPU 飙升、URL 重复打印
首次启动正常，二次启动就报错，最后定位到 BLE 资源释放不彻底

这里不再展开实现细节。具体的 Rust 项目可以在 GitHub 项目的 native/improvwifi_transport_linux_aot_native 目录下看到。下面这段代码主要用于说明 C ABI 接口边界，核心设计思路是：

Rust 负责实现 BlueZ 广播、GATT、D-Bus 对象导出
通过 C ABI 导出一组句柄式 API 给 .NET 调用
.NET 通过回调表接收 native 事件，再映射回 ImprovTransportServer 的语义事件

在 native 侧，我导出了一组句柄式 API，在 .NET 包装层中，通过回调表接收 native 事件：

cs 复制代码

using System.Runtime.InteropServices;

namespace ImprovWifi.Transport.Linux.Aot.Native;

internal static partial class LinuxAotNativeMethods
{
    private const string LibraryName = "improvwifi_transport_linux";

    [StructLayout(LayoutKind.Sequential)]
    internal struct CallbackTable
    {
        public IntPtr OnIdentifyRequested;
        public IntPtr OnProvisioningRequested;
        public IntPtr OnStateChanged;
        public IntPtr OnErrorChanged;
        public IntPtr OnRpcResultReady;
    }

    [LibraryImport(LibraryName, EntryPoint = "improv_server_create")]
    internal static partial IntPtr Create();

    [LibraryImport(LibraryName, EntryPoint = "improv_server_destroy")]
    internal static partial void Destroy(IntPtr handle);

    [LibraryImport(LibraryName, EntryPoint = "improv_server_start")]
    internal static partial int Start(IntPtr handle);

    [LibraryImport(LibraryName, EntryPoint = "improv_server_stop")]
    internal static partial int Stop(IntPtr handle);

    [LibraryImport(LibraryName, EntryPoint = "improv_server_set_callbacks")]
    internal static partial int SetCallbacks(IntPtr handle, in CallbackTable callbacks, IntPtr userData);

    [LibraryImport(LibraryName, EntryPoint = "improv_server_set_authorized")]
    internal static partial int SetAuthorized(IntPtr handle, [MarshalAs(UnmanagedType.I1)] bool authorized);

    [LibraryImport(LibraryName, EntryPoint = "improv_server_set_config")]
    internal static partial int SetConfig(
        IntPtr handle,
        byte[] adapterNameUtf8,
        nuint adapterNameLength,
        byte[] deviceNameUtf8,
        nuint deviceNameLength,
        [MarshalAs(UnmanagedType.I1)] bool discoverable,
        [MarshalAs(UnmanagedType.I1)] bool includeTxPower);

    [LibraryImport(LibraryName, EntryPoint = "improv_server_complete_provisioning")]
    internal static partial int CompleteProvisioning(IntPtr handle, byte[] urlUtf8, nuint urlLength);

    [LibraryImport(LibraryName, EntryPoint = "improv_server_fail_provisioning")]
    internal static partial int FailProvisioning(IntPtr handle, byte errorCode);
}

这个模式的优势是边界非常明确：

native 只关心"事件发生了"
协议层只关心"状态应该怎么变"
双方都不需要知道对方内部实现

6. 结语

跨平台开发最难的，从来不是"支持几个平台"，而是"在平台差异存在的前提下，仍然保持语义一致和迭代效率"。

通过开发 Sang.ImprovWifi 这套实践给我的最大反馈是：当你把协议层做薄、宿主层做稳，很多复杂问题会自然变简单。

除了让拆分和分层更易于理解与维护外，最大的好处是：在排查问题时，可以快速判断问题属于哪一层。是协议层的逻辑问题，还是宿主层的实现问题？当你在 AOT 版本上遇到问题时，就知道先从 native 层的日志和状态入手，而不是怀疑协议层的实现。