第 1 章 卷一 起步与核心：导言

本章导读

卷一是一整本书的地基。无论你最终用 XRT 写网络服务、解析配置还是做安全连接，你写下的每一行代码都站在这一卷的内容之上：错误怎么报告（第 4 章）、内存怎么分配与归还（第 5 章）、出问题怎么注入故障定位（第 6 章）、临时对象怎么零开销管理（第 7 章）、按需裁剪到多小（第 8 章）。这些不是"高级特性"，而是全库统一的语言——后面的每一章都会直接使用这里建立的规则，不会再解释第二遍。

本卷的知识地图与阅读顺序：

给三类读者的建议路径：初学 C 的读者按章节顺序通读，每章的完整程序亲手编译运行一遍——本卷的程序都很短，但每一个都值得跑；有 C 工程经验的读者可以快速通过第 2、3 章，把时间投在第 4 章（错误模型是 XRT 最独特的设计之一）和第 6 章（故障注入是后续网络与 TLS 章节测试方法的基础）；从其他语言来的读者请特别注意第 3 章的"视图"概念与第 5 章的所有权约定——它们分别是字符串切片和智能指针思路在 C 里的对应物，但规则更严格。

命名与术语约定

读 XRT 代码前，先约定一套"看名识意"的规则，全书通用。函数与类型用模块前缀 + 大驼峰：xrt 开头的是内核函数（xrtJsonParse 即 json 模块的解析函数），小写 x 开头的短名是类型（xerror、xstrview），全大写 X 开头的是常量与宏（XERR_TIMEOUT、XRT_NPOS）。参数名带匈牙利式前缀：p 指针、i 整数、s 零结尾字符串、b 布尔、arr 数组、Text/View 视图——看到 pConfig 与 iCount 就知道类型，不必跳回声明。输出参数几乎总是指针形参（C 没有引用），且函数失败时不写入输出——"失败无副作用"让错误恢复代码不必清理半成品。

三个会反复出现的术语先立字据：拥有（own）指"你负责释放它，恰好一次"；借用（borrow）指"可以用但不许释放，寿命跟着源"；托管指对象自带生命周期机制（引用计数或归属池），你按规则增减持有而非直接分配释放。第 3 章的视图是借用的载体，第 5 章的全局堆是拥有的出口，引用计数是托管的实现——三者构成 XRT 内存叙述的骨架。

学习检验

每读完一章，用三个问题自检：这一章解决了什么问题（能用一句话对同事说清吗）？契约区列的硬规则有哪几条（合上书能复述吗）？避坑区的症状你能在自己过往的代码里找到影子吗？三个都能答，再进入下一章；有一个卡住，回该小节重读——本卷是地基，后面的楼层不会替你补。这份检验清单也是全书的学习方法：XRT 的每个模块都值得用"问题、契约、坑"三件套来消化，养成这个习惯后，读任何新模块的速度都会明显变快。

如何使用本书

每章的结构是固定的：导读说明这一章站在哪、要去哪；引入从一个真实问题出发，而不是从 API 清单出发；概念建立心智模型，配状态机或流程图示；示例是完整可编译的程序——每个都带编译命令和真实输出，多数直接取自仓库 examples/ 目录（代码块右上角有"源码"链接可跳转 Gitee 对照）；契约汇总错误、所有权、线程三条硬规则；避坑给出症状、原因与错误/正确代码对照；练习分基础、进阶、挑战三级。读正文的建议节奏：先通读概念与示例，再自己动手跑程序，最后做至少基础级练习——三步走完，一章的知识才算落地。

遇到不认识的函数，两个入口：每章末尾的"本章涉及的 API 参考手册"直达该模块的完整参考页（签名、参数约束、返回值、错误、范例）；或者打开官网的 API 搜索页输入函数名。参考页与本书共用同一批事实来源，不会有口径打架。

阅读准备

只需要两样东西：一个 C11 编译器（GCC/Clang/MSVC 均可，本书示例以 Windows + GCC 的输出为准，其他平台输出一致或注明差异），以及 XRT 源码一份——git clone https://gitee.com/xywhsoft/xrt.git 或直接下载压缩包。不需要预先安装任何第三方库：XRT 运行时零第三方依赖，示例只用 C 标准库。所有示例的编译命令都在各章的输出块里，复制即可运行；把仓库根目录作为工作目录，命令中的相对路径（如 -I single、examples/...）才能正确解析。

全书路线

卷一之后：卷二到卷五是"数据与系统"半场——数学随机、容器、文本与结构化数据、日志与文件进程；卷六到卷九是"并发与网络"半场——线程协程、网络、安全、Web 协议核心；卷十卷十一是五个扩展库；卷十二回到工程视角（构建、裁剪、测试、性能）；卷十三用五个完整项目把全书串起来。每卷开头的导言页会给出该卷的知识地图与先修要求——如果某一卷的先修你还没读，导言会明确指回对应的章节。

卷一结束时，你应该能不查文档回答这些问题：一个会失败的 XRT 函数返回什么、错误详情从哪里读；一块内存从哪里来、归谁释放；一个不受信任的输入用什么防线兜底；以及把 XRT 裁剪到只含所需模块要动哪一行宏。带着这些问题出发。