第一次在项目里引入 Telegram 的官方库时，开发者常会问：同一套代码真的能跑遍 Windows、macOS、Linux 甚至 Android 吗？答案背后是一套精心雕琢的跨平台架构，而这套架构的核心思路，恰恰是让 C++ 的高性能与各语言的易用性在同一个进程里共生。
抽象层与平台无关的核心
TDLib 将所有业务逻辑封装进 td::Client，这层代码只依赖标准 C++17 与 std::thread，不出现任何系统调用。平台差异通过一个名为 Platform 的纯虚基类抽象出来：文件 I/O、日志、网络栈等实现分别在 platform/linux、platform/windows、platform/android 目录下提供对应子类。编译时依据宏 TD_WINDOWS、TD_LINUX 等切换，实现了“一次编译，处处运行”。
统一的异步消息总线
所有 API 调用都走 td_api::Object 的序列化路径，库内部维护一个环形缓冲区，生产者线程把请求写入，消费者线程读取并交给网络层。返回的结果同样以对象形式压入同一队列，外部只需要轮询或注册回调即可。因为消息体本身是自描述的 JSON‑like 结构，跨语言边界时只需要一次二进制序列化，省去了手写 marshaling 的繁琐。
语言绑定的桥接层
桥接层本质上是一个自动生成的 C‑ABI 包装：每种语言都有对应的 tdjson 动态库，暴露 td_json_client_create、td_json_client_send、td_json_client_receive 等函数。以 Python 为例，ctypes 直接加载 libtdjson.so，把返回的 JSON 字符串交给 json.loads 解析；在 JavaScript（Node）里，ffi-napi 完成同样的工作。这种模式让每种语言只关心序列化与事件调度，底层细节全部由 C++ 保持一致。
- C++：直接使用
td::Client，最小化层级。 - Python：
tdjson包装，配合asyncio实现协程。 - Java/Kotlin：JNI 调用，同步转异步的桥接类。
- Swift：通过模块映射生成的
TDLib桥接。
平台适配器的细粒度实现
在移动端，网络层会优先走系统提供的 CFNetwork（iOS）或 OkHttp（Android），因为它们自带 TLS 加速和流量监控；而在桌面 Linux，TDLib 则直接使用 libcurl，配合 epoll 实现高并发 I/O。日志系统也不统一：Windows 使用 OutputDebugString，macOS 则走 os_log，这让调试信息在每个平台的原生日志工具里自然出现。
如此层层拆解后，你会发现跨平台并不是把同一套代码硬塞进去，而是让每个系统的“强项”在恰当的抽象点上接管，剩下的业务逻辑全程在 C++ 核心里跑。把握住这两层分离的原则，后续无论是添加新语言绑定，还是移植到未曾支持的嵌入式系统，都只需要实现对应的 Platform 子类和 ABI 包装，核心库本身几乎不动。
