威胁模型

讨论检测方案之前，必须明确攻击者的能力边界。在当前主流 rootless 越狱环境下：

• GOT rebinding（fishhook）：通过修改 __DATA segment 中的 GOT/Lazy Symbol Pointer，可拦截任何通过 PLT 调用的 C 函数。不修改函数 prologue，不触发代码签名校验。
• MSHookFunction（CydiaSubstrate）：直接修改 C 函数 prologue 的前几条指令，插入跳转到替换函数的 trampoline。对 inline call 和 GOT call 均有效。
• ObjC Method Swizzling：通过 method_setImplementation 或 Logos %hook 替换任意 ObjC 方法的 IMP 指针。
• 注入时机：Tweak 在 __attribute__((constructor)) 阶段注入，早于 main() 和 UIApplicationMain。攻击者在 App 代码开始执行前就已经完成布局。

这意味着一个直接推论：任何仅依赖单一 API 返回值的检测都可以被精准拦截。有效的防御必须在多个层次形成冗余，并且——这是 App X 方案最具启发性的部分——必须在检测命中后制造攻击者难以逆转的既成事实。

第一层：检测层

文件系统探测——覆盖面决定一切

越狱环境在文件系统中留下大量 artifact。经典越狱（unc0ver、checkra1n）集中在 /Applications/Cydia.app、/usr/sbin/sshd 等路径；rootless 越狱则使用 /var/jb 作为根目录，派生出一套完全不同的路径树。

App X 维护了一份包含 40+ 路径的检测列表，覆盖经典与 rootless 两种环境：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

// 经典越狱路径
"/Applications/Cydia.app"
"/Library/MobileSubstrate/DynamicLibraries"
"/usr/sbin/sshd"
"/bin/bash"
"/etc/apt"

// rootless 越狱路径（Dopamine / palera1n）
"/var/jb"
"/.installed_dopamine"
"/procursus"
"/var/binpack"
"/var/checkra1n.dmg"

// 调试工具
"/usr/sbin/frida-server"
"/tmp/frida-"
"/usr/local/bin/cycript"

但路径列表只是检测内容的一半——同样重要的是检测入口的多样性。App X 同时通过以下 API 检查路径是否存在：

最后一项值得展开。syscall() 是一个通用的系统调用包装函数——它不经过 libc 中各个具名函数的实现，直接通过系统调用号发起内核请求：

1
2
3
4

int result = syscall(SYS_stat64, "/var/jb", &st);
if (result == 0) {
    // 越狱文件存在——即使 stat() 函数本身已被 Hook
}

攻击者如果只 Hook 了 stat()，这条检测仍然能命中。要绕过它，攻击者必须额外 Hook syscall() 并在内部解析第一个参数（系统调用号），针对 SYS_stat64、SYS_access、SYS_open 分别处理。这显著增加了攻击者的工作量和出错概率。

更激进的做法：使用 inline assembly 直接执行 svc #0x80 指令。这种方式连 syscall() 的 GOT 入口都绕过了，是当前已知最难被用户态 Hook 拦截的检测手段。App X 的 SecureUtilityPlus 框架中存在这类 inline SVC 检测——经逆向确认，攻击者无法通过 GOT rebinding 或 MSHookFunction 将其拦截。

环境变量与进程信息

注入框架在进程中留下的痕迹不只是文件：

1
2
3
4

// 环境变量检查
const char *env = getenv("DYLD_INSERT_LIBRARIES");
if (env != NULL) return YES;
// 同时检查 DYLD_LIBRARY_PATH, DYLD_FRAMEWORK_PATH, _MSSafeMode, _SafeMode

App X 同时通过 C 层 getenv() 和 ObjC 层 NSProcessInfo.environment 两个入口检查——两条路径的底层实现不同，攻击者必须同时覆盖。

动态库枚举

通过 dyld API 枚举当前进程加载的动态库镜像：

1
2
3
4
5
6
7
8

uint32_t count = _dyld_image_count();
for (uint32_t i = 0; i < count; i++) {
    const char *name = _dyld_get_image_name(i);
    if (strstr(name, "substrate") || strstr(name, "TweakInject") ||
        strstr(name, "ellekit") || strstr(name, "frida")) {
        return YES;
    }
}

这里存在一个攻击者容易犯的一致性错误：如果攻击者过滤了 _dyld_get_image_name 的返回值（隐藏注入 dylib 名称）但没有同步调整 _dyld_image_count 的返回值，或者没有同步处理 _dyld_get_image_header 和 _dyld_get_image_vmaddr_slide，那么这些 API 返回的数据之间就会产生不一致——image count 与实际可枚举数量不匹配本身就是一个检测信号。

防御建议：在不同时机多次调用 dyld 系列 API，对比 count 是否随时间突变、是否存在 index 空洞、count 与 header 数量是否一致。

URL Scheme 与文件系统可写性

1
2
3
4
5
6
7
8

// URL Scheme 探测
NSArray *schemes = @[@"cydia://", @"sileo://", @"zbra://",
                     @"filza://", @"undecimus://", @"activator://"];
for (NSString *s in schemes) {
    if ([[UIApplication sharedApplication] canOpenURL:[NSURL URLWithString:s]]) {
        return YES;
    }
}

1
2
3
4
5
6
7

// 文件系统可写性检查
struct statfs fs;
statfs("/", &fs);
if (!(fs.f_flags & MNT_RDONLY)) {
    // 根文件系统可写——正常 iOS 设备不应出现此情况
    return YES;
}

这两类检测验证的信息来源与文件路径完全不同——前者检查系统注册的 URL handler，后者检查文件系统挂载属性。攻击者需要额外 Hook canOpenURL: 和 statfs 并伪造返回值。

反调试

1
2
3
4
5
6
7

static BOOL isBeingDebugged(void) {
    int name[4] = {CTL_KERN, KERN_PROC, KERN_PROC_PID, getpid()};
    struct kinfo_proc info = {};
    size_t size = sizeof(info);
    sysctl(name, 4, &info, &size, NULL, 0);
    return (info.kp_proc.p_flag & P_TRACED) != 0;
}

App X 的 DebuggerChecker 检测 P_TRACED 标志位。攻击者需要 Hook sysctl 并在结果中清除该标志。此外，App X 还检查了 security.mac.amfi.developer_mode_status——这是 iOS 16+ 开发者模式的状态标志，越狱设备上通常为启用状态。

安全框架：SecureUtilityPlus

上述所有检测手段并非散落在业务代码中，而是被组织在一个名为 SecureUtilityPlus 的安全框架内——这是一个 Swift 编写的模块化检测引擎，包含以下 Checker 类：

其中 MSHookFunctionChecker 的存在对攻击者产生了重大的「工具选择约束」——它检查 C 函数 prologue 的前几字节是否被修改为 trampoline 跳转模式（LDR Xn, #offset; BR Xn）。一旦检测到，直接设置无效回调地址并通过 dispatch queue 执行跳转，触发 crash。

这迫使攻击者放弃 MSHookFunction——当前最通用的 C 函数 Hook 框架——转而使用 fishhook。而 fishhook 只能 Hook 通过 GOT 调用的函数，对模块内部的 inline call 无效。这种「限制攻击者工具选择」的策略比单纯「检测越狱特征」更具战略价值。

业务层状态分散

App X 不将越狱判定集中在一个布尔值中，而是将检测结果散布在超过 15 个属性和方法中：

1
2
3

isJailBreak, phoneIsJailBreak, isJailBrokenOne, isJailBrokenThree,
isJailBrokenFour, isJailBrokenFive, p_isJailBreak1, p_isJailBreak2,
MaxentJailBroken, jailbroken, jailbreaking, isJailbroken ...

并通过 authorityWithJailBreakFlag: 将标记传递给权限系统，在网络请求、页面跳转、登录等业务节点反复读取。攻击者需要通过全类遍历（objc_copyClassList）逐一找到并替换每个方法实现——遗漏任何一个都会导致业务异常或触发退出。

第二层：冻结层

如果说检测层回答的是「是否越狱」，那么冻结层回答的是「检测命中后如何让 App 变得不可用而不是简单退出」。这是 App X 方案中最具创新性的部分。

持续性冻结循环

当 inline SVC 检测到越狱文件后，App X 不是调用 exit() 退出——而是启动一个持续运行的冻结循环，以极高频率（30 秒内 14,000+ 次调用）执行以下操作：

1
2
3
4
5
6
7
8
9
10
11
12
13
14

// 阻塞主线程（~470 次/秒）
dispatch_semaphore_wait(semaphore, DISPATCH_TIME_FOREVER);

// 禁用动画（~166 次/秒）
[UIView setAnimationsEnabled:NO];

// 忽略触摸事件
[[UIApplication sharedApplication] beginIgnoringInteractionEvents];

// 禁用交互
view.userInteractionEnabled = NO;

// 移除所有动画
[layer removeAllAnimations];

这种设计的精妙之处在于：

1. 冗余覆盖：5 种不同的冻结手段并行执行。即使攻击者 Hook 了其中 3 种，剩余 2 种仍然足以让 App 不可交互。
2. 持续对抗：这不是一次性调用，而是一个永久运行的循环。攻击者不能「在启动时绕过一次就结束」——必须持续对抗每一次冻结尝试。
3. 高频淹没：每秒数百次的调用频率意味着攻击者的拦截逻辑同样需要执行数百次。任何性能问题都会被放大。

dispatch_semaphore_wait 作为主武器

冻结循环的核心武器是 dispatch_semaphore_wait(semaphore, DISPATCH_TIME_FOREVER)——在主线程上调用它会无限期阻塞主线程，使 RunLoop 停止调度事件。

为什么选择 semaphore 而非 sleep() 或 NSThread sleepForTimeInterval:？因为 semaphore 的阻塞发生在内核层面（mach_msg trap），从调用栈上看与正常的 GCD 同步操作难以区分。而 sleep() 的意图过于明显，更容易被针对性拦截。

时间门控

冻结循环中的 UI 冻结调用（setAnimationsEnabled:NO、removeAllAnimations 等）使用了一个巧妙的时间门控——前 3 秒允许正常执行：

1
2
3
4
5
6

// App 自身在启动阶段可能合法调用 setAnimationsEnabled:NO
// 3 秒后才是冻结循环的恶意调用
CFAbsoluteTime elapsed = CFAbsoluteTimeGetCurrent() - launchTime;
if (elapsed > 3.0) {
    // 此时的调用来自冻结循环——执行冻结
}

这增加了攻击者的区分难度：简单地「Hook 所有 setAnimationsEnabled:NO 调用使其无效」会破坏 App 自身的启动动画逻辑。攻击者必须实现与 App 相同的时间门控，或者找到其他区分合法调用与恶意调用的方式。

第三层：退出层

冻结层之外，App X 还部署了弹窗退出作为 fallback 机制。

弹窗 + exit 组合

1
2
3
4
5
6
7
8
9
10

UIAlertController *alert = [UIAlertController
    alertControllerWithTitle:@"安全提示"
    message:@"您的设备环境存在隐私信息泄露风险..."
    preferredStyle:UIAlertControllerStyleAlert];
[alert addAction:[UIAlertAction actionWithTitle:@"确定"
    style:UIAlertActionStyleCancel
    handler:^(UIAlertAction *action) {
        exit(0);
    }]];
[rootVC presentViewController:alert animated:YES completion:nil];

弹窗的 action handler 中调用 exit(0)——这构成了独立于冻结层的第二条退出路径。攻击者需要同时做到：

1. 拦截 presentViewController:animated:completion: 阻止弹窗展示
2. 确保即使弹窗展示了，handler 中的 exit() 也不会被执行
3. 识别哪些弹窗是安全相关的（不能拦截所有弹窗——否则正常业务弹窗也会消失）

App X 使用了两个安全弹窗——「安全提示」和「风险提示」——文案中包含「越狱」「风险」「设备」「异常」等关键字。攻击者可以基于关键字匹配来识别安全弹窗，但这种方法在 App 变更文案时会失效。

showJailBrokenAlertIfNeeded 的隐蔽触发

除了直接构造 UIAlertController，App X 还在多个业务类中实现了 showJailBrokenAlertIfNeeded 方法。这些方法散布在不同模块中，在不同时机被调用——攻击者需要通过全类遍历找到所有包含该 selector 的类并逐一替换。

三层联动的设计哲学

App X 的方案之所以有效，不在于任何单一层次的强度，而在于三层之间的联动关系：

不信任任何单一 API

检测层使用了 7 种不同的文件 API + syscall 包装 + inline SVC。即使攻击者 Hook 了 6 种，第 7 种仍然能触发冻结。

检测与响应分离

检测模块（SecureUtilityPlus 各 Checker）只负责设置状态标记。冻结循环和弹窗退出是独立的响应模块，各自读取状态并执行。这意味着攻击者不能通过 Hook 单个检测函数返回 NO 就同时绕过检测和响应——响应可能已经被触发了。

Hook 框架检测作为 force multiplier

MSHookFunctionChecker 不直接检测越狱，但它限制了攻击者的工具选择。被迫使用 fishhook 的攻击者无法拦截 inline call 和直接函数调用，这为 inline SVC 检测创造了不可绕过的锚点。

高频持续 vs. 一次性

冻结循环是永久运行的——这与「启动时检测一次」的方案形成本质区别。即使攻击者在 constructor 阶段成功绕过了所有检测，冻结循环仍然在持续执行。攻击者必须同时对抗检测绕过和冻结解除两个独立问题。

成本不对称

防御方的每一次小改动都迫使攻击者重新逆向和适配。这种不对称性是纵深防御的核心经济学。

小结

App X 的越狱检测方案展示了一个重要的设计理念：有效的越狱检测不是一个「判断题」（是否越狱），而是一个「持续对抗系统」。三层防御——检测命中后不是简单退出，而是通过高频冻结循环制造不可逆的 UI 死亡状态，再辅以弹窗退出作为 fallback——构成了一个攻击者必须同时解决多个独立问题才能突破的体系。

对于移动安全防御方而言，最核心的 takeaway 是：把对抗成本从「检测准确性」转移到「响应不可逆性」。检测总会被绕过——在 root 权限面前没有绝对不可绕过的用户态检测。但响应机制的设计可以让绕过变得极其昂贵：攻击者不仅要绕过检测，还要逆转已经触发的冻结循环、拦截持续涌来的 semaphore wait、处理散布在十几个类中的退出入口。当绕过成本持续上升并超过攻击者愿意投入的阈值时，纵深防御的目标就达成了。

XeTeX 的 interchar token 原语

xeCJK 的一切行为都建立在 XeTeX 提供的 interchar token 机制之上。理解这一原语是理解 xeCJK 的前提。

XeTeX 允许为每个 Unicode 码位分配一个整数「字符类」（character class），通过 \XeTeXcharclass 赋值：

1
2

\XeTeXcharclass`你 = 1    % 将「你」归入类 1
\XeTeXcharclass`A = 0     % 将「A」归入类 0（默认）

当 \XeTeXinterchartokenstate = 1 时，XeTeX 在排版过程中检测相邻字符的类别变化。如果前一个字符属于类 $i$、后一个属于类 $j$（$i \neq j$），XeTeX 会在两者之间自动插入 \XeTeXinterchartoks i j 中预存的 token 序列：

1

\XeTeXinterchartoks 1 0 = {\hskip 0.25em}  % 类 1 → 类 0 时插入间距

这个机制的关键特性是：它工作在 token 层，发生在字符被「吃进」主列表之前。这意味着插入的 token 序列可以包含任意 TeX 命令——切换字体、开关分组、插入 penalty、执行条件判断——而不仅仅是 kern 或 glue。xeCJK 正是利用这一点，在字符类边界处注入了完整的字体切换、间距计算和标点处理逻辑。

但 token 层工作也带来一个根本限制：interchar 机制无法区分一个字符是来自 Unicode 直接输入，还是来自 \char 原语的间接输出。这个限制后面会反复出现。

字符分类体系

xeCJK 在 XeTeX 原生的 Default（类 0）和 Boundary（类 4095）基础上，建立了一套面向中文排版的字符分类体系：

分类初始化发生在 xeCJK.dtx 的 \xeCJKResetCharClass 中。全角标点的归类数据来自 XeTeX 的 unicode-char-prep.pl 脚本和 Unicode Line Break 属性数据库（UAX#14），涵盖数百个码位。这不是拍脑袋定义的——它与 Unicode 标准的断行算法保持对齐。

值得注意的是 CM 类（Combining Marks / IVS）的设计：异体字选择符（U+E0100–U+E01EF）在 Unicode 中紧跟基字符出现，用于指定字形变体。如果把它们归入 CJK 类，就会在基字符与选择符之间触发不必要的 interchar 动作。CM 类的行为与 CJK 几乎相同，唯一区别是 CJK → CM 过渡不插入任何内容——选择符「透明地」附着在前一个字符上。

类别转换矩阵

有了字符分类，核心问题就是：当类 $A$ 后面紧跟类 $B$ 时，该做什么？xeCJK 在源码中以一个 9×9 矩阵的形式定义了所有类别对的行为。下表给出完整的 81 种转换（省略 HangulJamo，其行为与 CJK 相同但自身之间不插入内容）：

表中符号含义：

• —：不插入任何内容（纯西文之间、半角标点之间等）
• 入CJK：开启 CJK 分组 + 切换字体 + 输出字符
• 出+ecglue：关闭 CJK 分组（ecglue 由后续边界恢复处理）
• CJKglue：插入中文字间距
• 标点glue：触发标点压缩逻辑（kern 计算）
• 标点→CJK：从标点进入普通 CJK 字符的过渡
• 记xxx：写入标记 kern（为后续恢复留下线索）
• 恢复：读取标记 kern，决定插入 ecglue 或 CJKglue
• 恢复NS：NormalSpace 专用恢复路径
• =CJK：行为与对应的 CJK 行完全相同（CM/HangulJamo 透传）

矩阵的几个规律一目了然：CM 行和 CM 列几乎全部复制 CJK 的行为；Boundary 行是恢复逻辑的入口；对角线上只有 CJK→CJK 有实质操作（插入 CJKglue）。

核心转换规则可以进一步归纳为四条路径：

进入 CJK 区域

当字符从 Default、HalfLeft、HalfRight 或 NormalSpace 转入 CJK 时：

1
2
3
4
5
6
7

\xeCJK_inter_class_toks:nnn { Default } { CJK }
  {
    \xeCJK_class_group_begin:    % 开启 CJK 分组
    \xeCJK_select_font:          % 切换到 CJK 字体
    \xeCJK_fallback_symbol:NN    % 后备字体检测
    \CJKsymbol                   % 输出字符
  }

\xeCJK_class_group_begin: 做三件事：开启 TeX 分组（\bgroup）、设置一个标志表示当前处于 CJK 分组内、将 \XeTeXdashbreakstate 置零以避免破折号间折行。字体切换只在这个入口点发生——CJK 区域内部的字符间不再重复切换。

离开 CJK 区域

1
2

\xeCJK_inter_class_toks:nnn { CJK } { Default }
  { \xeCJK_class_group_end: }   % 关闭 CJK 分组

离开时只关闭分组。间距（\CJKecglue）并不在这里插入，而是延迟到后续的边界恢复阶段——这是 xeCJK 最微妙的设计之一。

CJK 内部

1
2

\xeCJK_inter_class_toks:nnn { CJK } { CJK }
  { ... \CJKglue ... \CJKsymbol }

CJK 字符之间插入 \CJKglue（默认 0pt plus 0.08\baselineskip）——这是中文排版中字间距的弹性胶，允许行末微调。

经过 Boundary

CJK 字符与西文之间如果有空格或命令间隔，流程变成：

1

CJK → Boundary → Default

这时简单的「相邻类检测」不再适用——CJK 和 Default 不直接相邻。xeCJK 需要在 CJK → Boundary 时记录状态，再在 Boundary → Default 时恢复间距。这就引出了 xeCJK 最复杂的子系统。

边界恢复状态机

这是 xeCJK 架构中最精密、也是历史上 Bug 最密集的部分。理解它需要一个三层模型。

第一层：标记 kern 判定

xeCJK 的核心思路是：在 CJK → Boundary 过渡时，向当前列表写入一个特殊的 kern 节点作为「标记」。后续 Boundary → Default 或 Boundary → CJK 过渡发生时，通过 \lastkern 读回这个标记，判断应该恢复什么间距。

不同的标记值代表不同的上下文。xeCJK 通过 \xeCJK_declare_node:n 为每种标记分配一个唯一的 kern 宽度（从 11sp 起递增），用 \lastkern 即可区分：

*注：default-space 使用 glue（而非 kern）作为标记，因为 kern 会干扰 XeTeX 的 character protrusion（字符突出）功能。判定方式相应改为 \lastskip 而非 \lastkern。

标记节点本身由两个背靠背的 kern 构成——先 \kern -Nsp 再 \kern Nsp，净宽度为零，不影响排版输出。\xeCJK_remove_node: 通过两次 \unkern 将其删除。

恢复逻辑集中在 \xeCJK_check_for_glue: 函数中：

1
2
3
4
5
6
7
8
9
10
11
12

\cs_new_protected:Npn \@@_check_for_glue_auxi:
  {
    \dim_case:nn { \tex_lastkern:D }
      {
        { \@@_node:n { CJK } }
        { \xeCJK_remove_node: \CJKglue }
        { \@@_node:n { CJK-space } }
        { \xeCJK_remove_node: \@@_ccglue_or_space: }
        { \@@_node:n { default } }
        { \xeCJK_remove_node: \skip_horizontal:N \l_@@_ecglue_skip }
      }
  }

\xeCJK_remove_node: 删除标记 kern 本身（它只是内部簿记，不应出现在最终排版输出中），然后插入正确的间距。

第二层：whatsit 定点恢复

问题在于，\lastkern 只能看到「当前列表最后一个节点」。如果标记 kern 写入之后、恢复判定之前，有其他节点被插入，\lastkern 就看不到标记了。

最常见的干扰源是 \special 产生的 whatsit 节点。例如 \textcolor{red}{...} 会在颜色切换时插入 PDF 颜色指令的 whatsit：

1
2

... [CJK 标记 kern] [color whatsit] ...
                                      ↑ \lastkern 看到的是这里

xeCJK 曾尝试通用 whatsit 恢复——「只要上一节点是 whatsit，就根据保存的状态恢复 glue」。但这在 hyperref 等包的场景下导致误判（#803）：biblatex 参考文献列表中 \raise\hbox{[} 后面的 hyperref 注释 whatsit 被错误恢复出 ecglue，产生 [ 1] 类的可见间距。

当前实现收窄为定点恢复——只对两个已知安全的 whatsit 来源做补丁：

1. \set@color（color/xcolor）：颜色 whatsit 插入后，如果之前有 xeCJK 标记，立即重放标记 kern
2. \Hy@BeginAnnot（hyperref）：进入链接注释前保存节点状态并清空，注释开始后选择性重放

其他来源的 whatsit（如 \raise\hbox 内部的）不参与恢复。这等价于把设计哲学从「猜测恢复」改为「精确重建」。

第三层：ecglue 缓存取值

\CJKecglue 默认是 ~，即当前字体的词间空格。这个值依赖字体——不同字体、不同字号的空格宽度不同。

问题在于：如果恢复点处的字体已经不是 CJK 字体（比如中间经过了 \texttt 分组），重新展开 \CJKecglue 会拿到错误的字体度量。

解决方案是缓存：在 CJK → Boundary 过渡时（此时仍处于正确的 CJK 字体上下文），立即测量 \CJKecglue 并存入 \l_@@_ecglue_skip。后续所有恢复路径统一使用这个缓存值。

为什么选择 CJK→Boundary 作为缓存时机？

• 初始化时缓存——会随后续字号切换而过期
• 每个字符都缓存——频率过高、状态复杂度大
• CJK→Boundary——恰好是离开正确 CJK 上下文前的最后稳定时机

三层合在一起，构成了 xeCJK 边界恢复的完整心智模型：用 \lastkern 判定边界类型，被 whatsit 打断时走定点补丁，恢复时使用缓存的 ecglue 值。

字体管理

xeCJK 的字体管理建立在 fontspec 之上，但加了一层面向 CJK 的封装。

切换时机

CJK 字体切换只发生在 interchar token 触发的分组入口处。当 XeTeX 检测到字符从非 CJK 类切换到 CJK 类时，interchartoks 中的 \xeCJK_select_font: 执行字体切换。CJK 区域内部的字符间不重复切换——整个 CJK 连续序列共享同一次字体选择结果。

这意味着 xeCJK 的字体开销是 $O(\text{边界数})$ 而非 $O(\text{字符数})$。对于一段纯中文文本，边界只出现在段落首尾和中间夹杂的西文处。

字体族注册

\setCJKmainfont、\newCJKfontfamily 等用户命令最终调用 \xeCJK_set_family:nnn，后者完成两件事：

1. 通过 fontspec 加载字体并注册 NFSS 字体族（全局）
2. 定义用户可见的切换命令（局部）

「字体族注册是全局的，切换命令是局部的」这一区分是有意为之的——它与 fontspec 的 \newfontfamily 语义保持一致：在分组内声明的字体切换命令不会泄漏到组外，但已注册的字体族信息可被后续代码复用。

后备字体

当主 CJK 字体不包含某字符时，xeCJK 通过 \setCJKfallbackfamilyfont 设置的后备链逐一尝试。检测机制是 \xeCJK_fallback_symbol:NN——在 interchar 入口处、输出字符前检查当前字体是否包含该码位，不包含则按优先级切换到后备字体。

标点压缩系统

中文排版中标点符号的宽度处理是一个高频痛点：全角标点在视觉上占据一个汉字宽度，但其字形实际上只填充了一半空间，另一半是空白 side bearing。相邻标点如果都保持全角，会出现明显的视觉「空洞」。标点压缩的目标就是消除或减少这些多余空白。

数据来源

xeCJK 通过 XeTeX 的 \XeTeXglyphbounds 原语获取每个标点字符的左右 side bearing：

1
2

\XeTeXglyphbounds 1 \the\XeTeXcharglyph`，  % 左侧 bearing
\XeTeXglyphbounds 3 \the\XeTeXcharglyph`，  % 右侧 bearing

这些数据是字体相关的——不同 CJK 字体的标点字形设计差异很大。xeCJK 在文档初始化时测量并缓存所有全角标点的 bearing 数据。

标点样式

xeCJK 提供 PunctStyle 选项，预定义了多种压缩策略：

• quanjiao（全角）：所有标点占一个汉字宽，不压缩
• banjiao（半角）：所有标点压缩到半个汉字宽
• kaiming（开明）：句末标点（。！？）保持全角，其他压缩
• hangmobanjiao（行末半角）：仅行末标点压缩
• CCT：模拟 CCT 系统的标点处理

每种样式实际上是一组规则，定义了「标点前方 kern」和「标点后方 kern」在不同上下文（行首、行末、相邻标点）中的取值。用户可通过 \xeCJKDeclarePunctStyle 声明自定义样式。

相邻标点的 kern 计算

当两个标点相邻时（如「」后跟「，」），它们之间的压缩量由两个标点的 bearing 之和决定。xeCJK 通过 \xeCJKsetkern 允许手动覆盖这些值，但通常由样式规则自动计算。内部存储在 g_@@_punct/kern/<char1>/<char2>/tl 属性表中。

间距系统总览

把前面各部分涉及的间距类型汇总：

\CJKglue 和 \CJKecglue 都可通过 \xeCJKsetup 全局修改。但注意：\CJKecglue 的默认值 ~ 是字体相关的——换字体或字号后它的实际宽度会变化。这正是边界恢复第三层「缓存取值」要解决的问题。

xCJKecglue 选项：统一源码空格行为

默认情况下，xeCJK 对「源码中 CJK 与西文直接相邻」和「源码中 CJK 与西文之间有空格」的处理是不同的：

• 中文text（无空格）→ 边界恢复插入 \CJKecglue
• 中文 text（有空格）→ 保留 TeX 原生词间空格 glue

这意味着用户的源码书写习惯会影响最终排版的间距宽度。对于追求一致性的文档，xeCJK 提供了 xCJKecglue 选项：

1

\xeCJKsetup{xCJKecglue=true}

启用后，源码空格被「吃掉」并统一替换为 \CJKecglue——无论写 中文text 还是 中文 text，得到的间距完全相同。

这个选项与边界恢复状态机的关系值得一提：前面标记 kern 表中的 default-space（16sp，使用 glue 而非 kern 作为标记）正是为 xCJKecglue=true 路径服务的。它标记「这里原来有源码空格，恢复时需要替换为 \CJKecglue」。当 xCJKecglue=false 时，这个标记根本不会被写入——源码空格直接保留为正常 glue，无需标记和恢复。

选择用 glue 而非 kern 作为标记也是有原因的：default-space 标记的位置恰好是原来空格 glue 所在的位置，用同类型节点替换可以避免干扰 XeTeX 的 character protrusion（字符突出）功能。判定方式相应从 \lastkern 变为 \lastskip。

兼容性补丁：模式与哲学

xeCJK 的 interchar 机制对 TeX 的执行流有侵入性——它在字符之间注入了 token。这与很多第三方包的假设冲突。xeCJK 通过 \@@_package_hook:nn 延迟加载兼容补丁。

典型补丁遵循一个固定模式：

1
2
3
4
5
6
7

\@@_package_hook:nn { ulem }
  {
    % 重定义 ulem 的关键命令
    % 在入口处 \makexeCJKinactive（关闭 interchar）
    % 执行原始操作
    % 分组结束时自动恢复 interchar 状态
  }

\makexeCJKinactive 将 \XeTeXinterchartokenstate 设为 0，相当于告诉 XeTeX「在这段代码中不要做 interchar 检测」。这是最直接的隔离手段。

不同包的补丁复杂度差异很大：

• ulem：简单隔离——下划线渲染过程中关闭 interchar 即可
• pifont：需要先 \mode_leave_vertical:（进入水平模式），否则垂直模式下的分组赋值会泄漏到输出例程
• listings：需要完全重写字符转换机制——用 \scantokens 替代 \lccode + \lowercase 路线，避免 CJK 字符被设为 active catcode
• color/xcolor 和 hyperref：需要在 whatsit 插入点做状态保存/重放，这已经上升到边界恢复状态机的层面

这些补丁的共同哲学是最小侵入：不重定义第三方包的全部接口，只在已知冲突点做定点修复。

\char 原语：一条架构级红线

XeTeX 的 interchar 机制工作在 token 层——它看到的是「将要输出到当前列表的字符 token」，无法区分这个字符来自 Unicode 直接输入还是 \char"4E00 这样的原语调用。

这意味着 \char 输出的字符同样会触发 interchar 检测。对于大多数场景这没有问题——但在某些数学包（如 mtpro2）中，\char 被用来取字形而非输出文本字符，此时 interchar 的字体切换和间距插入完全是多余甚至有害的。

xeCJK 对此确立了一条架构约束：

\char 必须始终保持 XeTeX primitive 身份，不得被重定义。

早期曾有方案尝试在 \AtBeginDocument 中重定义 \char，但这会破坏 xint 等包在加载期通过 \let 保存原语的假设。当前的稳定策略是三层的：

1. 提供 \xeCJKchar——语义是「绕过 interchar 输出字符」，实现上在输出前临时关闭 interchar
2. 对已知受影响的第三方包做自动补丁（如 mtpro2 的 \overcbrace）
3. 其他场景需用户手动用 \makexeCJKinactive 分组包装

这不是一个「没时间做完美方案」的妥协，而是一个刻意的设计选择：低侵入优先。改变原语身份的全局影响不可控，定点补丁的影响范围可预测。

Token 层 vs. 节点层：xeCJK 的根本约束

要真正理解 xeCJK 为什么是现在这个样子，需要先理解 TeX 引擎处理文档的两个阶段。

两个世界

Token 层（输入处理阶段）：TeX 把源文件逐字符读入，转化为 token 流——字符 token、命令 token。宏展开、条件判断、赋值都在这里发生。此时还没有「排版」：没有盒子、没有 glue 节点、没有断行。XeTeX 的 interchar 机制正是工作在这一层——它在字符 token 被送入排版引擎之前，往 token 流里插入额外的 token。

节点层（排版阶段）：token 被「消化」后变成排版节点——字符节点（glyph）、glue 节点、kern 节点、penalty 节点、whatsit 节点等。这些节点组成水平/垂直列表，最终经断行、分页算法处理后输出到 PDF。LuaTeX 的 callback 机制工作在这一层——它可以在断行前后直接遍历、修改完整的节点列表。

核心区别在于可见范围：

• Token 层只能看到「当前正在处理的 token」和有限的前瞻（\peek），对已经写入列表的内容只能通过 \lastkern、\lastpenalty、\lastnodetype 等原语回溯最后一个节点
• 节点层能看到整段或整行的完整节点列表，可以任意向前、向后遍历和修改

这就是为什么 xeCJK 需要那套复杂的边界恢复状态机：它在 token 层做决策，看不到全貌，只能靠「提前埋标记 kern、事后读 \lastkern」来推断上下文。而 LuaTeX-ja 在节点层工作，判断「这个字符前面是 CJK 还是西文」只需要往前遍历一个节点——不需要标记，不需要状态机，不需要担心 whatsit 打断。

时间复杂度的差异

两者渐近复杂度相同（都是线性），但工作模式不同：

xeCJK 的代价分摊在整个输入过程中：每个字符边界触发一次 interchar toks 执行 O(1) 的工作（查标记、插 glue、切字体），没有额外的遍历。总代价 O(n)，常数因子很小。

LuaTeX-ja 把间距处理集中在回调点：字符消化阶段不做间距处理，等一整段输入完毕后在 pre_linebreak_filter 回调中遍历整段节点列表。通常需要 2–3 趟遍历（kanjiskip、xkanjiskip、标点压缩各一趟），总代价 O(kn)，常数因子更高。

但这并不意味着 xeCJK 在性能上占优。LuaTeX 引擎本身比 XeTeX 更快（现代化的内存模型、Lua 的 JIT 友好性），回调的额外开销被引擎层面的提速抵消。实际文档编译中，瓶颈通常在字体加载和 PDF 输出，不在间距计算。

复杂度的性质

更值得关注的是两者代码复杂度的性质差异：

• xeCJK 的复杂度大部分是偶然的（accidental complexity）：标记 kern、whatsit 定点恢复、ecglue 缓存——这些机制的存在不是因为排版问题本身需要它们，而是因为 token 层看不到全貌，被迫发明的变通。如果能直接访问节点列表，这些东西根本不需要存在。
• LuaTeX-ja 的复杂度大部分是本质的（essential complexity）：它实现了更完整的日文排版模型（基于 JIS X 4051 / W3C JLREQ），处理的规则本身就更丰富——行头/行末禁则、连续标点压缩、ruby 对齐、竖排。代码量更大，但每一段代码都在处理「真正的排版问题」，而不是在绕平台限制。

节点层拥有完整信息，反而让很多判断变得直截了当。xeCJK 做的事相对少，但每件事都要和平台限制搏斗。

小结

xeCJK 的设计可以从两个维度理解：

横向看，它是一个建立在 XeTeX interchar token 原语之上的字符间距与字体控制层。字符分类定义了「什么和什么相邻」，转换矩阵定义了「相邻时做什么」，标点压缩和字体切换是具体的「做什么」。这一层是声明式的、静态的——给定分类和规则，行为完全确定。

纵向看，边界恢复状态机处理的是「相邻」这个概念被打破时怎么办。空格、命令、颜色 whatsit、hyperref 注释——所有这些都可能在 CJK 与西文之间插入不可见的节点，打断 interchar 的直接相邻检测。状态机的三层设计（标记 kern → whatsit 定点恢复 → ecglue 缓存）是 xeCJK 历史上最密集的 Bug 来源，也是其最精密的工程成果。

xeCJK 的设计哲学是在 token 层模拟节点层的行为。这个根本约束决定了它的所有设计选择：为什么需要标记 kern 而不是直接查看列表内容，为什么 whatsit 恢复必须是定点的而不能是通用的，为什么 \char 不能被安全地重定义。理解了这个约束，就理解了 xeCJK 为什么是现在这个样子——不是因为它不够好，而是因为 XeTeX 的 interchar 机制本身就是一个 token 层的工具，xeCJK 在这个约束内做到了能做的一切。

CJKglue 导言区设置被覆盖（#761）

现象

用户在导言区通过 \xeCJKsetup{CJKglue=...} 设置自定义字间距，\begin{document} 后设置被 ctex 的默认值覆盖，完全不生效。同样的设置放在正文中则正常。

1
2
3
4
5
6
7

\documentclass{article}
\usepackage{ctex}
\xeCJKsetup{CJKglue={\hskip 1em plus 0.05em minus 0.05em}}
\begin{document}
% 导言区的 CJKglue 设置没有任何效果
\zhlipsum[34][name=zhufu]
\end{document}

根因

ctex 的 linestretch 机制通过 \selectfont 钩子链——\ctex_update_size: → \ctex_update_stretch: → \@@_update_stretch_auxii:——在每次字体切换时重新计算并设置 \CJKglue。问题在于 \@@_update_stretch_auxii: 无条件地调用 \ctex_update_ccglue: 覆盖 \CJKglue，而不检查用户是否已经手动修改过它。

有趣的是，linestretch 禁用时走的另一条路径 \@@_update_stretch_auxi: 已经有 \ctex_if_ccglue_touched:TF 检查——只在用户未修改 \CJKglue 时才覆盖。\@@_update_stretch_auxii: 缺少同样的守卫，是一个遗漏。

修复：两次迭代

第一次修复尝试用 docstrip 守卫 %<*pdftex|xetex> 在 \@@_update_stretch_auxii: 中直接加入 \ctex_if_ccglue_touched:TF 检查。但这个方案有一个隐蔽的问题：ctex.sty 是以 {style,ctex} 标签从 dtx 中提取的，不包含 pdftex / xetex 引擎标签，导致守卫代码被 docstrip 直接剥离，修复实际无效。

第二次修复换了策略——不在主体代码中做条件编译，而是利用引擎 .def 文件的加载时机：

1
2
3

% 默认实现：所有引擎的原始行为
\cs_new_protected:Npn \@@_update_stretch_auxii:
  { \@@_update_stretch_auxiii: }

1
2
3
4
5
6
7
8
9
10

% 在 pdftex/xetex 引擎 .def 中，通过 \ctex_at_end:n 在包加载末尾重定义
\ctex_at_end:n
  {
    \cs_set_protected:Npn \@@_update_stretch_auxii:
      {
        \ctex_if_ccglue_touched:TF
          { \ctex_update_ccwd: }
          { \@@_update_stretch_auxiii: }
      }
  }

将 linestretch 的实际计算逻辑提取到 \@@_update_stretch_auxiii:，\@@_update_stretch_auxii: 默认直接调用它。在 ctex-engine-pdftex.def 和 ctex-engine-xetex.def 中，通过 \ctex_at_end:n 在包加载末尾重定义 \@@_update_stretch_auxii:，加入 \ctex_if_ccglue_touched:TF 守卫。这样一来：

• 用户已修改 \CJKglue → 只更新 \ccwd，不覆盖用户设置
• 用户未修改 \CJKglue → 走原始路径，自动计算
• LuaTeX / upTeX 不受影响，保持原始行为

这个修复过程本身就是一个教训：在 dtx 中使用 docstrip 守卫做条件编译时，必须确认目标输出文件的标签集合包含所需的守卫标签。否则，看起来正确的代码会被静默剥离。

macOS 15 字体检测失效（#722）

背景

ctex 的 fontset=mac 选项通过检测苹方（PingFang）字体是否存在来区分 macnew（El Capitan 及之后）和 macold（之前）两套字库配置。检测方式是检查苹方字体文件是否位于 /System/Library/Fonts/ 路径下。

从 macOS 15 (Sequoia) 开始，Apple 将苹方、楷体、仿宋等字体改为「downloadable」——它们不再预装在系统字体目录中，而是在首次使用时按需下载，存放在 /System/Library/AssetsV2/ 下的缓存目录中。这导致 ctex 的文件存在性检测失效，macnew 被错误判断为 macold。

修复策略

修复分三层：

版本号检测作为后备判据。通过读取 /System/Library/CoreServices/SystemVersion.plist 获取 macOS 主版本号。XeTeX 通过 TeX I/O 逐行读取 plist 文件，LuaTeX 通过 io.open 直接解析。版本号 ≥ 15 时判定为 macnew。

运行时字体可用性检测。在 macnew 的 XeTeX 分支中，不再假设字体一定存在，而是用 \fontspec_font_if_exist:nTF 逐一检测可选字体（楷体、仿宋、隶书、圆体、苹方）的可用性。核心字体（宋体、黑体）直接加载——它们在 macOS 15 上始终可用；可选字体不可用时静默跳过。

LuaTeX 的 AssetsV2 扫描。LuaTeX 分支用 lfs（LuaFileSystem）扫描 AssetsV2 目录，定位 downloadable 字体的实际路径，动态注册到 luaotfload 的搜索路径中。

苹方字体不可用时回退到黑体（Heiti SC）；版本检测失败时 warning 并回退到 macold。

LuaTeX 下 \verb 前间距丢失（#556）

现象

在 LuaTeX 下使用 ctex 排版时，\verb 命令前的 xkanjiskip（中西文间距）丢失：

1
2
3
4

\documentclass{ctexart}
\begin{document}
字\verb|foo|字    % LuaTeX 下 "字" 和 "foo" 之间缺少间距
\end{document}

根因

luatexja 的 lltjcore 模块对 \verb 做了一个关键补丁：将 \verb 内部使用的 \null（空 \hbox{}）替换为 \vadjust{}。原因是空 hbox 会阻断 luatexja 的 xkanjiskip 自动插入机制——luatexja 在相邻字符间插入 xkanjiskip 时，中间如果有 hbox 节点就会被截断。

但 ctex 在加载 luatexja 时禁用了 ltj-latex（为了使用自己的字体管理机制），连带着 lltjcore 的 \verb 补丁也没有被加载。

修复

在 ctex 的 LuaTeX 引擎适配代码中移植 lltjcore 的两个补丁：

1. \verb 重定义——将 \null 替换为 \vadjust{}
2. \do@noligs patchcmd——同样替换其中的 \null

同时声明 ver@lltjcore.sty 防止 lltjcore 被重复加载。新增 verb01 回归测试验证 \verb 和 \texttt 在 LuaTeX 下产生相同的 hbox 宽度。

hyperref driverfallback 警告（#715）

当 beamer 等文档类在 ctex 之前加载 hyperref 时，ctex 通过 \hypersetup 设置 driverfallback，但此选项作为加载选项在 hyperref 已加载后被禁用，触发警告。

修复方式是将 driverfallback 从 \ctex_hypersetup:n 中分离：hyperref 未加载时用 \PassOptionsToPackage，已加载时跳过此选项。

旧字体钩子兼容代码清理（#746）

ctex 和 xeCJK 中保留了针对 LaTeX < 2020/10/01 的旧 NFSS 字体钩子回退路径——直接操作 \@rmfamilyhook 或 patch \rmfamily / \fontfamily。2020/10/01 的 LaTeX 内核引入了新的 NFSS 钩子机制，此后的版本不再需要这些回退。

考虑到 TeX Live 2020 已发布六年，继续维护旧路径的代价（代码复杂度、测试负担）高于收益。此次清理移除了所有旧路径，仅保留使用新 NFSS 钩子的代码。这是一个 breaking change：不再支持 LaTeX < 2020/10/01。

测试基线维护

除了上述功能性改动，还有一类不起眼但必要的工作：维护测试基线文件（.tlg）。ctex 的 config-contrib 测试套件中包含 pkuthss 和 thuthesis 等真实模板的回归测试，它们对 xeCJK 行为变化非常敏感。

本轮维护中，xeCJK 的多次行为修正（ecglue 缓存修复、whatsit 节点处理变化、\textcolor 场景修复）都触发了 ctex 侧测试基线的更新。例如 xeCJK #803 移除通用 whatsit 恢复后，pkuthss 测试中 hyperref \special 注释后的重复 ecglue 被正确消除，基线中对应的三处 \glue 条目需要删除。

这类更新没有代码改动，但对 CI 的持续通过至关重要。

版本号提升与发布

所有改动完成后，ctex 的版本号从 v2.5.10 提升到 v2.6.0，并移动 ctex-v2.6.0 tag 到最新提交。ctex 已接入 tag 触发的自动 release 流水线——推送 ctex-v* 格式的 tag 即可自动执行 l3build ctan、打包 zip 并创建 GitHub Release。

小结

ctex 作为中文 LaTeX 排版的基石，其维护工作有一个显著特点：大量问题来自外部环境的变化——操作系统升级（macOS 15 字体路径变更）、上游宏包更新（hyperref 选项语义变化）、TeX 引擎差异（LuaTeX 的 xkanjiskip 机制）——而非 ctex 自身的逻辑错误。这意味着维护者需要持续追踪外部生态的变化，并在 ctex 层面做适配。

CJKglue 被覆盖的问题则是另一类：内部代码路径之间的不一致。\@@_update_stretch_auxi: 有守卫而 \@@_update_stretch_auxii: 没有，这种不一致在最初编写时可能是有意为之（两条路径的语义不同），但随着功能演进变成了 Bug。docstrip 守卫失效的问题更是提醒我们：在 dtx 中做条件编译时，必须清楚地知道每个输出文件的标签集合——这不是一个直觉上容易把握的信息。

从工程角度看，这轮维护中一个反复出现的模式是：修复 xeCJK 的行为 → 更新 ctex 的测试基线 → 验证 CI 通过。ctex 和 xeCJK 虽然是独立的包，但通过 config-contrib 测试紧密耦合。这种耦合是有意为之——真实模板的回归测试能捕获单元测试发现不了的集成问题——但也意味着一个包的改动可能需要另一个包同步更新基线。保持这种跨包测试的健康运转，是 ctex-kit 作为 monorepo 的核心价值之一。

背景：CJKpunct 的标点处理模型

在深入 Bug 之前，有必要简要回顾 CJKpunct 的核心模型。CJKpunct 将每个标点字符分为三类：

• class 0：非标点的 CJK 字符
• class 1：开标点（左括号、左引号等）
• class 2：闭标点（句号、逗号、右括号等）

当 \CJKpunct@CJKpunctsymbol 处理一个标点时，它按如下顺序插入节点：

1

[lglue] → [lrule(零宽)] → 标点字符 → [rrule(零宽)] → [rglue]

其中 lrule 和 rrule 是宽度为标点挤压量的零高零深 \vrule——这是实现标点「占半格」视觉效果的关键；lglue 和 rglue 则是标点与前后文字之间的弹性间距。这个模型在绝大多数场景下工作良好，但在两个边界条件上出了问题。

Bug #747：段首开标点的幽灵缩进

现象

在 minipage、tcolorbox 内嵌 \newtheorem 等 \parindent=0 的环境中，当段落以全角开标点（如「（」）开头时，第二段及之后的段落会出现约 5.4pt 的异常缩进，而首段正常。

1
2
3
4
5
6
7

\begin{minipage}{\linewidth}
  （第一段）正常

  （第二段）多了约 5.4pt 缩进

  （第三段）同样多了约 5.4pt 缩进
\end{minipage}

根因分析

问题出在 CJKpunct 对 class 1 开标点的 lglue 插入逻辑。修复前的代码无条件地在开标点前插入 lglue：

1
2
3

\ifnum\CJKpunct@currentcharclass=1\relax
  \hskip \csname CJKpunct...@lglue@...\endcsname
    plus 0.1em minus 0.1em

首段之所以不受影响，是因为 lglue 紧跟在段首的强制换行（\penalty -10000）之后，TeX 的断行算法将其作为可丢弃节点（discardable item）消除。但从第二段开始，情况不同：每段开头有一个宽度为 \parindent 的 indent box（即使 \parindent=0，这个零宽 box 依然存在）。indent box 是不可丢弃的，它阻止了 lglue 被消除——于是 lglue 的自然宽度（在 quanjiao 样式下约 5.4pt）变成了可见的「幽灵缩进」。

修复

修复策略是：仅在前方确有 CJK 字符时才插入 lglue。判据是 \CJKpunct@lastkern——CJKpunct 在每个 CJK 字符后都会留下一个特征 kern，其值大于零。

1
2
3
4
5

\ifnum\CJKpunct@currentcharclass=1\relax
  \ifnum\CJKpunct@lastkern>0\relax
    \hskip \csname CJKpunct...@lglue@...\endcsname
      plus 0.1em minus 0.1em
  \fi

这个条件精确地区分了「开标点跟在 CJK 字符后面」和「开标点出现在段首或非 CJK 内容后面」两种情况。段首时 \lastkern 为零（前面只有 indent box 或段首处理结构），lglue 被正确跳过。

Bug #671：段末闭标点后的多余空行

现象

在 pdfLaTeX 下，当段落末尾恰好是全角闭标点（如句号「。」），且该行被 TeX 断行算法挤压（glue set 为负）时，闭标点后会出现一个不期望的空行。用 XeLaTeX 或 LuaLaTeX 编译则无此问题。

1
2
3

这是一段文本这是一段文本这是一段文本这是一段文本这是一段 $abcde$。

% ↑ pdfLaTeX 下，上面这段后面会多出一个空行

根因分析

闭标点（class 2）处理完毕后，CJKpunct 会插入一个 rglue（\hskip）。修复前的代码直接插入：

1
2
3
4

\ifnum\CJKpunct@currentcharclass=2\relax
  \hskip \csname CJKpunct...@rglue@...\endcsname
    plus 0.1em minus 0.1em
\fi

当闭标点恰好位于段落最后一个字符时，这个 rglue 成为段末节点列表上的最后一个 glue。TeX 的断行算法允许在 glue 处断行——于是它在 rglue 处断出了一个空行（一个只包含 indent box 的 hbox），这就是用户看到的「多余空行」。

之所以只在 pdfLaTeX 下出现，是因为 XeTeX 和 LuaTeX 使用 xeCJK 或 LuaTeX-ja 处理标点，不走 CJKpunct 的代码路径。

修复

修复方法极其简洁——在 rglue 前加一个 \nobreak：

1
2
3
4
5

\ifnum\CJKpunct@currentcharclass=2\relax
  \nobreak
  \hskip \csname CJKpunct...@rglue@...\endcsname
    plus 0.1em minus 0.1em
\fi

\nobreak 等价于 \penalty 10000，告诉 TeX 的断行算法「此处禁止断行」。这样 rglue 就不会成为合法的断行点，段末不再产生空行。

需要注意的是，这并不会阻止闭标点出现在行尾。\nobreak 只禁止在 rglue 本身处断行；在正文中间，TeX 仍然可以在 rglue 之后、下一个字符之前的 glue（CJKglue 或 lglue）处断行，视觉效果与之前完全一致——闭标点留在行尾，下一个字符去到新行。\nobreak 精确地堵住的是段末场景：此时 rglue 后面没有下一个字符，它是节点列表上最后一个 glue，如果允许在此断行就会断出空行。

这个修复与 CJKpunct 已有的处理风格一致——在标点间距序列中，kern 和 rule 之间也使用了类似的 \nobreak 来防止不期望的断行。

从零搭建 l3build 回归测试

ctex-kit 的 ctex 和 xeCJK 模块早已有完善的 l3build 测试框架，但 CJKpunct 一直没有。在修复上述两个 Bug 的过程中，我为 CJKpunct 建立了完整的测试基础设施。

测试框架搭建

首先是 build.lua 配置：

1
2

module  = "cjkpunct"
checkengines = { "pdftex" }

CJKpunct 只在 pdfTeX 引擎下工作（XeTeX 用 xeCJK，LuaTeX 用 LuaTeX-ja），因此测试引擎限定为 pdftex。

三个测试用例

punct-basic.lvt：基础加载和标点样式测试，验证 CJKpunct 的核心功能——标点能被正确排版、标点样式（quanjiao、banjiao 等）切换生效。这是冒烟测试。

punct-indent.lvt：#747 的回归测试。核心策略是比较「新 hbox 中的孤立开标点」与「CJK 字符后的开标点」的宽度差异：

1
2
3
4
5

\TEST{Opening~punct~at~start~has~no~lglue}{
  \hbox_set:Nn \l_tmpa_box { （ }
  \dim_set:Nn \l_tmpa_dim { \box_wd:N \l_tmpa_box }
  \TYPE { opening-punct-alone-width:~ \dim_use:N \l_tmpa_dim }
}

在新 hbox 中，\lastkern 为零，修复后不应插入 lglue；而在 CJK 字符之后，\lastkern > 0，lglue 应正常插入。

punct-rglue.lvt：#671 的回归测试。策略更为精巧——将标点排入 hbox 后逆向拆解节点，验证 rglue 前存在 \penalty 10000：

1
2
3
4
5
6
7
8
9
10
11
12
13

\TEST{Right~punct~rglue~preceded~by~nobreak~(github~\#671)}{
  \hbox_set:Nn \l_tmpa_box { 测。 }
  \hbox_set:Nn \l_tmpb_box {
    \tex_unhbox:D \l_tmpa_box
    \tex_unkern:D   % 去掉尾部 kern
    \tex_unkern:D   % 去掉 rrule 的 kern
    \tex_unskip:D   % 去掉 rglue
    \xdef \g_tmpa_tl { \the \tex_lastpenalty:D }
  }
  \int_compare:nNnTF { \g_tmpa_tl } = { 10000 }
    { \TYPE { PASS:~nobreak~before~rglue } }
    { \TYPE { FAIL:~penalty~is~\g_tmpa_tl } }
}

这种「拆节点验证」的测试方式直接检查 TeX 内部数据结构，比「看排版结果」可靠得多——它不受字体度量变化的影响。

CI 集成

CJKpunct 依赖 arphic 字体（gbsn 等），这些字体在所有平台的 TeX Live 中都可用。测试已接入 GitHub Actions CI，在全平台运行。.tlg 基线文件最初从 CI 输出中获取，因为 CJK 字体的度量数据在不同平台上可能有微小差异。

文档 driver 迁移

CJKpunct 的文档 driver 一直使用 ltxdoc + CJKutf8 + hypdoc + dvipdfmx 的古老组合。这套组合有几个实际问题：

• CI 上需要安装 CJKutf8、CJKspace、hypdoc、atbegshi 等一系列额外依赖
• 需要 CJK 字体通过 zhwindowsfonts 配置，对非 Windows 环境不友好
• hypdoc 与 dtxchecksum 不兼容，导致 l3build ctan 打包时 checksum 验证失败

迁移方案很直接：将 driver 切换到 ctxdoc（ctex-kit 各包通用的文档类），编译引擎改为 XeLaTeX。这样一来，CJK 字体由 ctex 自动配置，所有额外依赖全部移除，整个 driver 从 20 余行缩减到寥寥数行。

对于 checksum 与 hypdoc 不兼容的问题，在 build.lua 中将 checksum 函数覆盖为空操作：

1

checksum = function() end

这是一个务实的折中：CJKpunct 的代码量不大（约 940 行），CheckSum 的防篡改意义有限，而绕过这个不兼容可以让 CI 打包流水线跑通。

版本号与发布

上述所有改动合入主线后，CJKpunct 的版本号从 v4.8.4 提升到 v4.8.5。这是 CJKpunct 自 2014 年以来的首次版本更新。同时，CJKpunct 也被纳入了新建的 tag 触发自动 release 流水线——推送 CJKpunct-v* 格式的 tag 即可自动打包 CTAN zip 并创建 GitHub Release。

小结

CJKpunct 的这两个 Bug 有一个共同特点：它们都源于宏包对「边界条件」的处理不够精确。lglue 在段首不应出现，rglue 在段末不应成为断行点——这些约束在正文中间永远不会被触发，只有在段落的首尾才暴露。

修复本身都很小——一个是加了一层 \ifnum 判断，另一个是加了一个 \nobreak——但定位过程需要对 TeX 断行算法中可丢弃节点的规则、indent box 的存在性、\lastkern 的语义有清晰的理解。这也是为什么我在修复的同时投入了相当精力建设测试框架：对于这类依赖 TeX 内部行为的微妙 Bug，光靠肉眼看排版结果是不够的，必须有能直接验证节点结构的自动化测试。

从工程角度看，为一个只有约 940 行代码的宏包搭建完整的 l3build 测试、CI 流水线和自动发布机制，投入产出比看起来不高。但 CJKpunct 的用户基数不小——任何使用 pdfLaTeX + ctex 的文档都间接依赖它——而且它的代码风格属于「不敢轻易碰」的那类：全局状态多、条件嵌套深、缺乏注释。测试框架的存在让未来的维护者（包括未来的我）能够更有信心地修改代码，而不必担心引入不可见的回归。

DAG 可视化：让黑箱变成白盒

Pineapple 的 DAG 是引擎自动从算子的输入输出字段推导出来的——用户不手动画图。这带来了便利，但也带来了黑箱：当 pipeline 复杂到二三十个算子时，用户无法直观确认「引擎理解的依赖关系是不是我想的那样」。

DOT 与 Mermaid 双格式

internal/dag/visualize.go 提供了两种渲染格式：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

func RenderDOT(g *Graph) string {
    var b strings.Builder
    b.WriteString("digraph pipeline {\n")
    b.WriteString("    rankdir=TB;\n")
    b.WriteString("    node [shape=box, style=filled, fontname=\"Helvetica\"];\n\n")

    for _, node := range g.Nodes {
        opType := types.OperatorType(node.Config.OperatorType)
        color := dotColors[opType]
        label := fmt.Sprintf("%s\\n[%s]", node.Name, opType)
        fmt.Fprintf(&b, "    %q [label=%q, fillcolor=%q];\n", node.Name, label, color)
    }
    // edges: 直接遍历 Node.Succs
    for _, node := range g.Nodes {
        for _, succ := range node.Succs {
            fmt.Fprintf(&b, "    %q -> %q;\n", node.Name, g.Nodes[succ].Name)
        }
    }
    b.WriteString("}\n")
    return b.String()
}

Graphviz DOT 适合本地渲染成 SVG，精确控制布局；Mermaid flowchart 适合直接嵌入 Markdown 文档和 PR description。节点按算子类型着色——Recall 绿、Transform 蓝、Filter 橙、Merge 紫、Reorder 黄、Observe 灰——一目了然。

通过 Engine.RenderDAG(format) 公共 API 暴露，HTTP 端点 GET /dag?format=dot|mermaid 直接服务。用户一条 curl 就能拿到 DAG 图：

1

curl -s localhost:8080/dag | dot -Tsvg -o dag.svg

传递性归约与纵向布局

初版可视化直接遍历所有推导出的边，包括被更长路径隐含的冗余边，导致图上出现大量交叉线。解决方案是传递性归约：遍历每条边 u→v，检查是否存在中间路径 u→...→v，有则跳过。同时将布局方向从左到右（LR）改为自上而下（TB），更符合 pipeline 的流水线直觉。

这个渲染层归约后来被更彻底的方案取代（见后文「执行图传递性归约」），渲染函数简化为直接遍历 Node.Succs 画边——因为 Succs 本身已经是归约后的最小边集。

资源配置热加载

Pineapple 在上一个版本已经支持引擎配置热加载——修改 JSON 配置文件后服务自动重建 Engine。但 ResourceManager（管理特征索引等需要定时刷新的外部数据）没有跟上，仍然需要重启服务才能更新资源配置。

解决方案是将 resources 从裸指针改为 atomic.Pointer[resource.Manager]，与 enginePtr 对齐。pkg/server/server.go 中的热加载流程变为：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

func reloadConfig(path string) error {
    data, err := os.ReadFile(path)
    if err != nil {
        return err
    }

    engine, err := pine.NewEngine(data)
    if err != nil {
        return err
    }

    newRM := resource.NewManager()
    if err := newRM.LoadFromRootConfig(data); err != nil {
        return err
    }
    if err := newRM.Start(context.Background()); err != nil {
        return err
    }

    if err := resource.ValidateResourceDeps(data, newRM); err != nil {
        newRM.Stop()
        return err
    }

    enginePtr.Store(engine)
    oldRM := resources.Swap(newRM)
    if oldRM != nil {
        oldRM.Stop()
    }
    return nil
}

关键设计：新 Manager 先 Start 成功再替换。如果新配置有问题（解析失败、资源拉取超时），旧配置保持不变，服务继续运行。这避免了「加载到一半，新的没起来、旧的已停掉」的窗口期。resources.Swap 原子替换后才 Stop 旧 Manager，读路径始终有效。

列存 DataFrame

行存的 GC 瓶颈

原有的 RowFrame 以 []map[string]any 存储每个 item——一行一个 map。推荐系统的 pipeline 经常处理上千个 item，每个 item 几十个字段，这意味着数万个小 map 分配，GC 压力显著。

列存设计

引入 Frame 接口，抽象出行存和列存两种实现：

1
2
3
4
5
6
7
8
9
10

type Frame interface {
    Common(field string) any
    SetCommon(field string, value any)
    ItemCount() int
    Item(index int, field string) any

    BuildInput(commonFields, itemFields []string, commonDefaults, itemDefaults map[string]any) *types.OperatorInput
    ApplyOutput(out *types.OperatorOutput, opName string, recall bool) error
    ToResult(commonOut, itemOut []string) *types.Result
}

ColumnFrame 以 map[string][]any 存储，每个字段一个 slice，item 按下标访问：

1
2
3
4
5
6

type ColumnFrame struct {
    mu       sync.RWMutex
    common   map[string]any
    columns  map[string][]any
    rowCount int
}

一个设计选择值得一提：列存使用 []any 而非泛型 slice。原因是 Pineapple 的字段值类型在运行时才确定（JSON 解析后是 float64、string、bool 等混合类型），泛型化无法避免 interface boxing，反而增加复杂度。

通过 JSON 配置的 "storage_mode": "row"|"column" 选择，Python DSL 侧同步支持 Flow(storage_mode="column")。列存在字段写入和构造上更高效（分配更少），但结构变更（删除行、重排序）因需遍历所有列而略慢——适用于「字段多、结构变更少」的 pipeline。

控制算子显式命名

Python DSL 中的 if_() / else_() / end_if_() 在编译时被降级为 transform_by_lua 算子。之前这些控制算子的名字是 transform_by_lua_XXXXXX（哈希后缀），在 DAG 可视化中完全看不出哪个节点是条件分支。

编译器改为生成 if_1、elseif_2、else_3 这样的显式名称。DAG 图中一眼就能识别控制流节点，不再淹没在一堆 transform_by_lua_* 里。这个改动看似微小，但对包含多层嵌套条件分支的复杂 pipeline 来说，可视化的可读性提升是质的飞跃。

运行时架构两项重构

v0.3.10 在同一个版本内完成了两项关联的架构改善。

Frame 并发自治

原来的调度器持有一把全局 sync.RWMutex，每次算子读写 DataFrame 都要经过调度器加锁。这个设计把「数据安全」的职责放在了错误的层级——调度器负责 DAG 编排，不应该关心数据访问的同步。

重构后锁下沉到 Frame 实现内部。RowFrame 和 ColumnFrame 各自持有一个 sync.RWMutex：

1
2
3
4
5
6
7
8
9
10
11
12

type RowFrame struct {
    mu     sync.RWMutex
    common map[string]any
    items  []map[string]any
}

func (f *RowFrame) Common(field string) any {
    f.mu.RLock()
    v := f.common[field]
    f.mu.RUnlock()
    return v
}

读操作（Common、Item、BuildInput）取 RLock，写操作（SetCommon、ApplyOutput）取 Lock。调度器代码中移除所有锁操作。

过程中曾尝试更激进的方案：给 ColumnFrame 用双锁（commonMu + structMu），让 common 字段和 item 字段的并发访问互不干扰。但 benchmark 显示结构体从 24 字节膨胀到 72 字节后，cache line 压力导致结构变更操作约 1.8 倍退化。最终回退到单锁方案——简单且够用。

执行图传递性归约

前文提到的 DAG 可视化传递性归约做在渲染层，每次渲染都要重新计算。更重要的是，调度器遍历 Node.Preds 等待前驱时，仍然要遍历包含冗余边的完整边集——虽然语义正确（等待一个已经被间接等过的前驱只是多一次 channel receive），但浪费了 CPU。

解决方案是将归约从渲染层下沉到 dag.Build() 阶段：

1
2
3
4
5
6
7
8
9
10
11
12
13
14

func Build(sequence []string, operators map[string]config.OperatorConfig) (*Graph, error) {
    // Phase 1: barrier edges
    // Phase 2: data hazard edges
    // Phase 3: merge source edges

    // Phase 4: Transitive reduction
    reduce(g)

    // Validate: no cycles
    if _, err := TopologicalSort(g); err != nil {
        return nil, err
    }
    return g, nil
}

reduce 的实现对每条边 u→v 做 BFS 检查是否存在绕过直连的替代路径：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

func reducedEdges(g *Graph) [][2]int {
    n := len(g.Nodes)
    adj := make([][]int, n)
    for i, node := range g.Nodes {
        adj[i] = node.Succs
    }

    var edges [][2]int
    for u := 0; u < n; u++ {
        for _, v := range adj[u] {
            if !reachableWithout(adj, n, u, v) {
                edges = append(edges, [2]int{u, v})
            }
        }
    }
    return edges
}

归约不改变执行语义：done[pred] channel 的 close 在 Go 内存模型下提供 happens-before 保证，可达性不变则执行顺序约束不变。渲染层代码因此大幅简化（删除 76 行归约逻辑），直接遍历 Node.Succs 画边即可。整个系统只做一次归约，调度器和可视化同时受益。

跨服务 Transform 算子

推荐系统中常见的模式是：主 pipeline 需要调用下游的特征服务获取额外字段。这本质上是一个「远程子 pipeline 调用」。之前用户只能写自定义 Go 算子来实现 HTTP 调用，缺乏统一抽象。

新增的 transform_by_remote_pineapple 算子调用下游 Pineapple 服务的 /execute 端点，核心挑战是字段映射：本地 frame 的字段名和下游服务的字段名可能不同。

按位置对应的映射模型

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

// 构造下游请求：local common_input[i] → remote common_request[i]
reqCommon := make(map[string]any, len(o.CommonInput))
for i, localField := range o.CommonInput {
    if i < len(commonReqFields) {
        reqCommon[commonReqFields[i]] = in.Common(localField)
    }
}

// 解析下游响应：remote common_response[i] → local common_output[i]
for i, localField := range o.CommonOutput {
    if i < len(commonRespFields) {
        if val, ok := result.Common[commonRespFields[i]]; ok {
            out.SetCommon(localField, val)
        }
    }
}

common_request[i] 与 common_input[i] 按位置一一对应，item_request[i] 与 item_input[i] 同理，响应侧亦然。这四组映射参数是可选的——当未提供时，直接使用 metadata 字段名（无映射），适用于上下游字段名一致的场景。

错误处理策略

1
2
3
4
5
6
7

func (o *RemotePineappleOp) handleError(out *pine.OperatorOutput, err error) error {
    if o.failOnError {
        return err
    }
    out.SetWarning(err)
    return nil
}

fail_on_error 参数控制下游错误的处理方式：true 时下游错误为 fatal，整个 DAG 中止；false 时降级为 warning，pipeline 继续执行。这让业务团队可以根据下游服务的重要程度灵活配置——核心特征服务用 fatal，辅助增强服务用 warning。

Python DSL 中一行声明即可接入下游服务：

1
2
3
4
5
6
7
8
9

flow.transform_by_remote_pineapple(
    common_input=["user_age"],
    item_input=["item_id"],
    item_output=["item_feature"],
    host="feature-service",
    port=8080,
    item_request=["id"],
    item_response=["feature"],
)

算子级数据并行框架

许多 Transform 算子的 per-item 计算是独立的（如特征归一化、远程调用、模型推理），天然可以并行加速。但之前没有统一机制——要么靠用户在算子内部自己开 goroutine，要么靠 DAG 层面的算子间并行。

三个关键设计决策

在动手实现之前，有三个问题需要先回答。

第一，哪些算子类型支持数据并行？ 初看之下 Recall 和 Observe 似乎也可以，但仔细分析后发现只有 Transform 兼容：

第二，数据并行时允许写 common 字段吗？ 多个 shard 并行写 common 字段没有安全的 merge 语义——不同 shard 可能算出不同值，引擎无法决定谁胜出。而真正需要数据并行的场景（per-item 密集计算）天然只写 item 字段。因此：启用 data_parallel 时强制要求 common_output 为空。如果未来出现真实的 common 聚合需求，再讨论 map-reduce 方案。

第三，在哪一层实现？ 不改 DAG 推导逻辑。数据并行是单个算子节点的运行时优化，对 DAG 拓扑完全透明。

编译期守门

这两条约束在 NewEngine 阶段强制校验：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

func validateDataParallel(opName string, opCfg *config.OperatorConfig, opType types.OperatorType) error {
    if opCfg.DataParallel > 1 {
        if opType != types.OpTypeTransform {
            return &ValidationError{
                Message: fmt.Sprintf("operator %q: data_parallel=%d is only supported for Transform operators, got %s",
                    opName, opCfg.DataParallel, opType),
            }
        }
        if len(opCfg.Meta.CommonOutput) > 0 {
            return &ValidationError{
                Message: fmt.Sprintf("operator %q: data_parallel=%d requires empty $metadata.common_output",
                    opName, opCfg.DataParallel),
            }
        }
    }
    return nil
}

编译期拒绝不合法配置，而非运行时静默失败。

分片、并行、合并

运行时实现在 internal/runtime/parallel.go，分三步。

分片——将 items 切成 N 份，尽量等分，余量分配给前几个 shard：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

func splitInput(input *types.OperatorInput, n int) ([]*types.OperatorInput, []int) {
    total := input.ItemCount()
    common := input.RawCommon()
    items := input.RawItems()

    if n > total {
        n = total
    }

    base := total / n
    rem := total % n

    parts := make([]*types.OperatorInput, n)
    offsets := make([]int, n)
    start := 0
    for i := 0; i < n; i++ {
        size := base
        if i < rem {
            size++
        }
        // ... copy shard items, share common
        parts[i] = types.NewOperatorInput(common, shardItems)
        offsets[i] = start
        start += size
    }
    return parts, offsets
}

所有 shard 共享同一个 common map（只读），items 按下标范围独立拷贝。offsets 记录每个 shard 在原始 items 中的起始位置，供合并时重映射索引。

并行执行——每个 shard 一个 goroutine，带独立的 panic recovery：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

func parallelExecute(ctx context.Context, cop *CompiledOperator, input *types.OperatorInput) (*types.OperatorOutput, error) {
    parts, offsets := splitInput(input, cop.Config.DataParallel)

    execCtx, cancel := context.WithCancel(ctx)
    defer cancel()

    outputs := make([]*types.OperatorOutput, len(parts))
    var (
        wg      sync.WaitGroup
        errOnce sync.Once
        first   error
    )

    for i := range parts {
        wg.Add(1)
        go func(idx int) {
            defer wg.Done()
            out := types.NewOperatorOutput()
            err := executeWithRecovery(execCtx, cop, parts[idx], out)
            if err != nil {
                errOnce.Do(func() {
                    first = err
                    cancel() // 任一 shard 失败，取消所有
                })
                return
            }
            outputs[idx] = out
        }(i)
    }

    wg.Wait()
    if first != nil {
        return nil, first
    }
    return mergeOutputs(outputs, offsets), nil
}

errOnce + cancel() 确保任一 shard 失败立即终止其他 shard。executeWithRecovery 将 panic 转化为 PanicError，与单线程路径行为一致。

合并——将各 shard 的 itemWrites 按偏移量重映射为绝对索引：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

func mergeOutputs(outputs []*types.OperatorOutput, offsets []int) *types.OperatorOutput {
    merged := types.NewOperatorOutput()
    for i, out := range outputs {
        if out == nil {
            continue
        }
        if w := out.GetWarning(); w != nil {
            merged.SetWarning(w)
        }
        offset := offsets[i]
        for localIdx, fields := range out.GetItemWrites() {
            absIdx := localIdx + offset
            for field, value := range fields {
                merged.SetItem(absIdx, field, value)
            }
        }
    }
    return merged
}

shard 0 写 [0, k) 的 item，shard 1 写 [k, m) 的 item……各 shard 的本地索引加上 offset 就是全局索引。合并后的 OperatorOutput 与单线程执行产生的完全一致。

调度器接入

调度器的改动极小——只需在执行前判断 DataParallel > 1：

1
2
3
4
5
6

if cop.Config.DataParallel > 1 {
    output, execErr = parallelExecute(ctx, cop, input)
} else {
    output = types.NewOperatorOutput()
    execErr = cop.Instance.Execute(ctx, input, output)
}

后续的 ValidateOutput、warning 收集、debug snapshot、ApplyOutput 全部保持原流程不变。

等价性验证

构造 100 个 items，同一个 doubleItemOp 分别以 data_parallel=1（基线）和 data_parallel=2,3,4,7 执行，逐 item 对比输出值，断言完全一致。测试覆盖了等分、非等分、shard 数大于 item 数等边界情况。

性能实测

使用 Horner 多项式（degree 5，per-item 做 5 次乘加）通过完整引擎路径测量：

轻量 per-item 计算下，数据并行有负收益——goroutine 创建、shard 分配、Output 合并的固定开销（约 30-50%）大于并行节省的时间。这个结果符合预期：数据并行的目标场景是 per-item 计算量足够重的算子。

以 10,000 items 为例，框架「税」约为 1.4 ms，折合每 item 约 0.14 us。这意味着只要单 item 计算时间超过这个水位线，并行就开始盈利。对于一次 HTTP 调用动辄几毫秒的场景（比如刚才介绍的 transform_by_remote_pineapple），这个开销可以忽略。算子完全不需要改代码，在 DSL 中加一行 data_parallel=4 就能让引擎自动分片并行。

小结

从 v0.3.4 到 v0.4.0 的十次迭代，表面上是功能列表的增长，背后是两条贯穿性的设计理念在反复兑现。

职责归位。资源热加载把 ResourceManager 的生命周期对齐到引擎级别；Frame 并发自治把锁从调度器下沉到数据层；传递性归约从渲染层下沉到构建阶段。每一次「下沉」都在回答同一个问题：这件事该由谁负责？当职责归位后，上层代码自然简化，下层代码自然内聚。

约束即能力。数据并行框架最有说服力的设计决策不是「支持什么」，而是「禁止什么」——只支持 Transform、禁止 common_output。正是这两条编译期硬约束，让分片-并行-合并的运行时实现变得直截了当：不需要处理 common 字段冲突，不需要担心屏障语义被破坏，不需要为每种算子类型写特化路径。约束越明确，实现越简单，出错的空间越小。

这个原则在 Pineapple 中反复出现：Recall 只能 AddItem 所以多路召回可以安全并行；六种类型的 Output 约束在运行时强制校验而非靠约定；data_parallel 的类型和字段约束在编译期拒绝而非运行时报错。每一条「做不到的事」，都是引擎可以自动做出正确决策的前提。

本文将从架构设计、DAG 构建算法、并行调度机制、Lua 嵌入层、控制流编译等维度，完整拆解 Pineapple 的核心原理，并附上真实的 benchmark 数据。

架构：Python 声明，Go 执行，JSON 解耦

Pineapple 由两个独立组件构成：

• Apple（Python）——声明式 DSL，面向业务团队。运行后产出 JSON 配置文件，不参与运行时计算。
• Pine（Go）——执行引擎，面向工程团队。解析 JSON 配置，构建 DAG，并行调度算子。

二者之间唯一的持久边界是 JSON 配置。这意味着业务团队修改 Python 流水线后，只需重新生成 JSON，Go 服务自动热加载，无需重编译、无需重启。

1
2
3
4
5
6
7

Python DSL  ──(compile)──>  JSON 配置
                                │
                                v
                 Go 引擎解析 JSON，推导算子依赖
                                │
                                v
                  构建 DAG，拓扑排序，并行执行

Pine 被定位为纯计算库——整个引擎只暴露两个 API：

1
2

engine, err := pine.NewEngine(jsonConfig)  // 编译：JSON → 不可变执行计划
result, err := engine.Execute(ctx, req)    // 执行：请求进，结果出

NewEngine 之后 Engine 不可变，可被任意数量的 goroutine 并发调用 Execute。配置重载？创建新 Engine，通过 atomic.Pointer 原子替换，旧实例由 GC 回收。没有 Reload 方法，没有读写锁，读路径零锁竞争。

这种极简 API 设计意味着 Pine 可以被嵌入到任何部署形态——HTTP 服务、gRPC 服务、离线批处理 Runner——而不需要任何修改。

六种算子类型

Pineapple 将所有算子严格分为六种类型，每种类型决定了允许的输出方法和 DAG 语义：

类型约束在运行时强制执行——算子返回后，调度器检查 OperatorOutput 中实际调用了哪些方法，不符合类型约束直接返回 error。这不是约定，是硬校验。

数据冒险驱动的 DAG 构建

这是 Pineapple 最核心也最独特的设计。

传统的 DAG 引擎需要用户手动声明算子之间的依赖关系，或者按照拓扑层级手动编排。Pineapple 的做法不同：算子只需声明自己读写哪些字段，引擎自动推导依赖。这个推导算法直接借鉴了计算机体系结构中 CPU 流水线的**数据冒险（data hazard）**模型。

三种数据冒险

1
2
3
4
5

// internal/dag/dag.go

// Phase 2: Apply data hazards for common and item fields separately
addEdges(g, sequence, operators, true)  // common fields
addEdges(g, sequence, operators, false) // item fields

引擎对 common 字段和 item 字段分别执行一遍数据冒险分析，追踪三种冒险类型：

对于学过计算机体系结构的读者，这三种冒险应该很熟悉——它们正是经典五级流水线需要处理的数据相关性。Pineapple 将这套模型从指令级搬到了算子级。

逐字段追踪器

每个字段独立维护一个追踪器：

1
2
3
4
5

type fieldTracker struct {
    lastMutWriter   int   // 最近一个覆写型写者
    additiveWriters []int // 追加型写者（recall）
    activeReaders   []int // 活跃读者
}

关键的精妙之处在于区分了两种写入语义：

• 覆写型写者（mutating writer）：Transform 的 SetItem，修改已有行，产生完整的 WAW 和 WAR 冲突。
• 追加型写者（additive writer）：Recall 的 AddItem，追加新行，不影响已有行。

追加型写者之间不存在 WAW/WAR 冲突——这正是多路召回可以完全并行的理论基础。引擎不需要用户声明「这几个 Recall 可以并行」，数据冒险分析自动得出这个结论。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

isAdditiveWrite := !isCommon && opType == types.OpTypeRecall

if isAdditiveWrite {
    // 追加型：只记录为 additive writer，不建 WAW/WAR 边
    ft.additiveWriters = append(ft.additiveWriters, i)
} else {
    // 覆写型：完整的 WAW + WAR 处理
    if ft.lastMutWriter >= 0 {
        addEdge(g, ft.lastMutWriter, i) // WAW
    }
    for _, reader := range ft.activeReaders {
        addEdge(g, reader, i) // WAR
    }
    ft.lastMutWriter = i
    ft.additiveWriters = nil
    ft.activeReaders = nil
}

屏障语义

Filter、Merge、Reorder 这三种算子会改变 item 集合的「结构」（组成或顺序），因此被标记为屏障（barrier）。屏障算子的语义很简单：所有前序算子必须执行完毕，屏障执行完毕后后续算子才能开始。

1
2
3
4
5
6
7
8
9
10
11
12
13

func addBarrierEdges(g *Graph, sequence []string, operators map[string]config.OperatorConfig) {
    for i, name := range sequence {
        if !opType.IsBarrier() {
            continue
        }
        for j := 0; j < i; j++ {
            addEdge(g, j, i) // 所有前序 → 屏障
        }
        for j := i + 1; j < n; j++ {
            addEdge(g, i, j) // 屏障 → 所有后序
        }
    }
}

这等价于经典并行计算中的 barrier synchronization 原语。

行集合级别的依赖

有些算子需要「所有 item 都就绪」才能执行——比如统计 item 总数的 transform_size。Pineapple 通过一个虚拟的哨兵字段 _row_set_ 来建模这种行集合级因果关系：

1
2
3
4
5
6
7
8

const rowSetSentinel = "_row_set_"

if isAdditiveWrite {
    writeFields = append(writeFields, rowSetSentinel) // Recall 是 _row_set_ 的追加型写者
}
if opCfg.RowDependency {
    readFields = append(readFields, rowSetSentinel)   // 声明了行依赖的算子是 _row_set_ 的读者
}

这个设计的巧妙之处在于：行集合依赖完全复用了已有的 RAW/WAW/WAR 机制，没有引入任何新的推导逻辑。Recall 对 _row_set_ 做追加型写入，需要完整行集合的算子声明读取 _row_set_，标准的 RAW 依赖自然保证了执行顺序。

Channel-per-Node 并行调度

DAG 构建完成后，调度器的实现出人意料地简洁。核心思想只有一句话：为每个算子节点创建一个 channel，节点完成时 close 该 channel，后继节点通过 select 等待所有前驱 channel。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

func Run(ctx context.Context, plan *Plan, frame *dataframe.Frame, stats *Stats) ([]Warning, []types.OpTrace, error) {
    n := len(plan.Graph.Nodes)
    done := make([]chan struct{}, n)
    for i := 0; i < n; i++ {
        done[i] = make(chan struct{})
    }

    for i := 0; i < n; i++ {
        go func(idx int) {
            defer close(done[idx])

            // 等待所有前驱完成
            for _, pred := range node.Preds {
                select {
                case <-done[pred]:
                case <-ctx.Done():
                    return
                }
            }

            // 构建输入快照 → 执行算子 → 应用输出
            // ...
        }(i)
    }
}

这是一种隐式拓扑排序调度——不需要维护就绪队列、不需要中央调度器轮询，DAG 的拓扑约束完全通过 channel 的阻塞-唤醒语义自然实现。无依赖的算子在 DAG 构建完成的瞬间就开始并行执行，调度延迟趋近于零。

close(channel) 而非 send 是关键选择：一次 close 可以唤醒任意数量的等待者，天然支持一对多依赖。而 ctx.Done() 分支确保错误发生时所有等待中的 goroutine 快速退出。

引擎托管读写

算子并不直接读写 DataFrame。调度器在执行前后分别持锁构建输入快照和应用输出：

1
2
3
4
5
6
7
8
9
10
11
12
13

// 构建只读输入快照
mu.Lock()
input := dataframe.BuildInput(frame, commonInput, cop.Config.Meta.ItemInput, ...)
mu.Unlock()

// 算子执行——不持锁，完全并行
output := types.NewOperatorOutput()
execErr = cop.Instance.Execute(ctx, input, output)

// 应用输出
mu.Lock()
applyErr := dataframe.ApplyOutput(frame, output, cop.Name, cop.Config.Recall)
mu.Unlock()

锁只保护 BuildInput（从 map 中按字段名取值）和 ApplyOutput（写回 map）这两个极快的操作。算子执行本身——也就是耗时的大头——完全并行，不持锁。在 DAG 依赖已经保证顺序正确的前提下，这把 mutex 只是为了防止 Go 的 map 并发读写 panic，而非用于同步业务逻辑。

Trace 预分配与零 GC 竞争

1
2
3

traces = make([]types.OpTrace, n) // 按节点数预分配
// 每个 goroutine 直接写自己的槽位
traces[idx] = types.OpTrace{Name: cop.Name, Duration: duration, ...}

trace 数组按节点索引预分配，每个 goroutine 写自己的槽位，无需加锁。DAG 中止时未执行的算子不会出现在最终 trace 中——trace 的长度本身就是故障定位的线索。

Panic 恢复

每个算子的执行都包裹在 defer recover() 中。panicking 的算子被转化为 PanicError（带完整堆栈），终止当前 DAG，但进程继续服务其他请求。这是一条铁律：绝不因为单个请求的算子 bug 而 crash 进程。

Lua 嵌入：零 CGo，池化 VM

Pineapple 内置了 transform_by_lua 算子，允许用户用 Lua 脚本定义特征计算和条件逻辑，无需新增 Go 代码即可快速迭代。

底层使用 gopher-lua——一个纯 Go 实现的 Lua 5.1 VM，零 CGo 依赖，交叉编译和部署与纯 Go 项目无异。

两种执行模式

• Item 模式（function_for_item）：Go 对每个 item 调用一次 Lua 函数。common 字段作为标量全局变量设置一次，item 字段在每次迭代前更新为当前行的值。
• Common 模式（function_for_common）：Go 调用一次 Lua 函数。item 字段被转化为 Lua table（1-indexed 数组），包含所有行的值，支持跨 item 聚合。

State Pool：池化 + 全局变量清理

Lua VM 的状态管理是这个模块最精巧的部分。每个 Lua 算子实例持有一个基于 sync.Pool 的状态池：

1. 初始化：创建第一个 LState，加载并编译脚本，调用 snapshotGlobals 捕获 _G 全局变量的基线集合。
2. 借出：从 pool 获取一个已编译脚本的 LState，高并发时自动创建新实例。
3. 归还：调用 clearNonBaseline 遍历 _G，将所有非基线全局变量设为 nil，然后放回 pool。

这保证了每次借出的 LState 都是干净的——上一次执行设置的 item 字段全局变量不会泄漏到下一次执行。脚本只编译一次，sync.Pool 在高峰期自动扩张，空闲时由 GC 回收，完美适应并发度波动。

性能实测

我们设计了五个复杂度档次的 benchmark，对比 Lua 与等价 Go 原生算子的性能差距：

端到端测试中，引擎框架（DataFrame 构建、DAG 调度）占总耗时的 50-70%，显著稀释了 Lua VM 的纯计算差距。这意味着在真实系统中，简单逻辑下 Lua 仅比 Go 慢约 1.3x——对于推荐系统场景，这个开销远小于 Redis 查询或特征服务调用的 I/O 延迟，可以忽略不计。

只有在密集数值计算（L5 级别）且 item 数量较大时，Go 原生算子才有显著优势。这给了业务团队一个清晰的决策框架：快速迭代用 Lua，热路径上的密集计算用 Go。

控制流编译：if/else 降级为数据依赖

Pineapple 的 Python DSL 支持条件分支：

1
2
3
4
5

flow.if_("user_age < 18") \
    .transform_dispatch(common_field="default_score", item_field="score") \
.else_() \
    .transform_by_lua(lua_script="...", function_for_item="score") \
.end_if_()

但 Go 引擎没有任何 if/else 原语。控制流在编译阶段就被完全消解了。

降级策略

编译器将每个分支转化为一个 transform_by_lua 控制算子，该算子计算一个布尔值写入编译器生成的隐藏 common 字段（如 _if_1、_else_2）：

1
2
3
4

-- if 分支的控制算子
function evaluate()
  if (user_age < 18) then return false else return true end
end

语义反转是关键：true 表示「跳过」，false 表示「执行」。分支内的业务算子通过 skip 字段引用对应的控制属性——当控制属性为 true 时，算子被跳过。

elseif/else 的控制算子会额外读取前面所有分支的控制属性，链式依赖保证了分支互斥。嵌套 if 天然支持，内层控制算子吸收外层条件。

对引擎零侵入

这个设计的优雅之处在于：控制流完全降级为数据依赖。控制属性作为普通 common 字段存在于 DataFrame 中，参与标准的 DAG 数据冒险分析，调度器通过已有的 skip 评估逻辑处理跳过。Go 引擎不需要任何分支处理代码，控制流的正确性完全由 DAG 依赖保证。

而且，控制属性是可观测的——开启 debug 模式就能看到每个分支的计算结果，排查分支逻辑错误变得非常直观。

单一事实来源：从 Go Schema 到 Python DSL

Pineapple 的代码生成流水线确保了 Go 算子注册信息是唯一的事实来源。

1
2
3
4
5
6
7
8
9
10
11
12
13

// 算子注册：Go 侧定义 Schema
func init() {
    pine.Register(pine.OperatorSchema{
        Name:        "transform_normalize",
        Type:        pine.OpTypeTransform,
        Description: "Normalizes a numeric field to [0, 1] range.",
        Params: map[string]pine.ParamSpec{
            "field": {Type: "string", Required: true, Description: "Target field."},
            "min":   {Type: "float64", Required: true, Description: "Range minimum."},
            "max":   {Type: "float64", Required: true, Description: "Range maximum."},
        },
    }, func() pine.Operator { return &NormalizeOp{} })
}

一次 go run ./cmd/pineapple-codegen 从注册表中读取所有 Schema，同时生成：

• Python 类型化 Helper（apple_generated/operators.py）——带完整类型注解和 IDE 补全
• Markdown 算子文档（doc/operators/）——参数表格、元数据契约、用法示例
• Python 资源类（apple_generated/resources.py）——资源声明的类型化绑定

1
2
3
4
5
6
7
8

Go Schema (注册表)
    │  codegen
    ├─────────> Python helpers (apple_generated/)
    ├─────────> Markdown docs (doc/operators/)
    │
    │  DSL 声明
    v
Python Flow → compile → JSON → Go 引擎加载

Register() 中强制校验 Description 和所有参数的 Description 非空——缺少就 panic，代码根本无法注册成功，更不可能上线。这比常见的「lint 检查文档注释」方案更为激进：编译时强制，而非运行时建议。

Python DSL 还有一个巧妙的设计：Flow.__getattr__ 拦截所有未知方法调用，将其记录为 OpCall。这意味着即使没有跑 codegen，flow.some_future_op(...) 也能工作——DSL 天然前向兼容任何未来算子。codegen 生成的类型化 Helper 是锦上添花（IDE 补全和类型检查），而非必需品。

编译期四重校验

Apple 编译器在生成 JSON 之前执行四重静态校验：

1. 字段覆盖——每个算子声明读取的字段必须有上游产出（「定义前使用」检查）
2. 死代码检测——产出字段未被下游消费的算子被标记为无效
3. 写后覆写检测——同一字段被多次写入时发出警告
4. 控制流完整性——if_ 必须有对应的 end_if_，空分支报错

这些校验全部是声明式的——只需要算子序列和 Flow 契约，不需要运行时信息。将错误拦截在开发阶段，而非部署后。

动态资源管理

算子在执行时经常需要读取定时刷新的外部数据——特征索引表、AB 实验配置、轻量模型参数。Pineapple 的 pkg/resource 包提供了一个与 Engine 生命周期完全独立的资源管理器。

1
2
3
4

rm := resource.NewManager()
rm.Register("user_features", fetchFeatureTable, 5*time.Minute)
rm.Start(ctx)  // 首次同步拉取，后续异步定时刷新
defer rm.Stop()

设计要点：

• 无锁读：atomic.Value 实现读写分离，读路径零锁竞争。刷新 goroutine 构建完整新版本后原子替换。
• 首次同步，后续异步：Start() 首次同步拉取（失败则 fail fast），后续刷新不阻塞请求。
• 刷新失败保留旧版本：不清空旧数据，保证降级可用。
• 编译期依赖校验：DSL 编译器校验所有 resource_name 引用是否有对应声明；引擎启动时 ValidateResourceDeps 交叉检查 pipeline 引用与 ResourceManager 中已注册的资源名。

算子侧只依赖一个极简的只读接口：

1
2

rp := resource.FromContext(ctx)
val, ok := rp.Get("user_features")

测试时注入 mock 同样简单：resource.NewStatic(map[string]any{"user_features": testData})。

第三方扩展：零侵入的插件化

Pineapple 的扩展机制完全基于 Go 原生的 init() + blank import 模式，没有引入任何插件框架。第三方项目在不修改 Pineapple 源码的前提下添加自定义算子和资源：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

// my-project/operators/my_scorer/scorer.go
func init() {
    pine.Register(schema, func() pine.Operator { return &MyScorer{} })
}

// my-project/cmd/my-server/main.go
import (
    _ "github.com/Liam0205/pineapple/operators" // 内置算子
    _ "my-project/operators/my_scorer"            // 自定义算子
    "github.com/Liam0205/pineapple/pkg/server"
)

func main() {
    server.Run(server.Config{ConfigPath: *configPath, Addr: *addr})
}

自定义算子与内置算子享有完全相同的能力——DAG 调度、trace、hot reload、codegen 生成 Python 绑定和文档。整个扩展体验的核心是：写算子代码和一个几行的 main.go wrapper，框架帮你搞定一切。

小结

回顾 Pineapple 的设计，几条贯穿性的理念值得提炼：

编译时强制优于运行时检查。从注册时强制填写描述（缺失直接 panic），到 DSL 编译器的四重静态校验，到启动阶段的资源依赖交叉检查——每一层都在把错误拦截在尽可能早的阶段。这不是防御性编程，而是将「正确性」从程序员的记忆力转移到系统的保证上。

借鉴成熟的抽象模型。数据冒险模型来自 CPU 流水线设计，barrier 语义来自并行计算，channel-per-node 调度利用了 Go 的并发原语。Pineapple 没有发明新的依赖推导理论，而是将经过数十年验证的模型搬到了新的应用场景。这种「站在巨人肩上」的策略，让系统设计者可以直接引用学术文献来论证正确性，而不是依赖测试覆盖率和直觉。

对称性降低认知负担。算子注册和资源注册完全对称（Schema + Factory）；MetadataHolder 和 DebugHolder 完全对称；控制流降级复用了 Lua 算子和 skip 机制。学会一种模式，就能理解整个系统中类似的构造。

极简 API 背后是深思熟虑的约束。Engine 不可变，没有 Reload；算子类型决定允许的输出方法，没有例外；追加型写者和覆写型写者的区分是硬编码的，不是配置项。这些「做不到的事」正是系统可以自动做出正确决策的前提——正因为 Recall 只能 AddItem，引擎才能安全地让多个 Recall 并行执行。

Pineapple 仍在 pre-1.0 阶段积极迭代。如果你正在构建一个需要多步骤数据处理流水线的系统，不妨尝试一下这种「声明即并行」的开发方式。

项目地址：github.com/Liam0205/pineapple

项目结构

先看整体目录：

1
2
3
4
5
6
7
8
9
10
11
12

14_todo_api/
├── main.go                ← 入口：组装依赖、启动服务
├── model/
│   └── todo.go            ← 数据模型
├── response/
│   └── response.go        ← 泛型 API 响应包装
├── store/
│   ├── store.go           ← Store 接口 + 内存实现
│   └── store_test.go      ← 表驱动测试 + 并发安全测试
├── handler/
│   ├── handler.go         ← HTTP 处理层
│   └── handler_test.go    ← httptest 集成测试

四个包按职责划分：model 定义数据结构，store 负责存取，handler 处理 HTTP，response 提供统一的响应格式。main 只做组装。这是第四篇讨论的「按领域拆包」原则的实际应用。

调用链路也很清晰：

1
2
3
4
5

客户端请求
  → net/http（路由匹配 + 连接管理）
    → handler（解析请求 → 调用 store → 构建响应）
      → store（业务逻辑 + 数据存取）
        → model（纯数据结构）

每一层只依赖它下面的层，不反向依赖。

API 设计

遵循 REST 风格——用 URL 标识资源，用 HTTP 方法表达操作：

1
2
3
4
5

GET    /todos           列出所有（可选 ?status=done 过滤）
POST   /todos           创建
GET    /todos/{id}      获取单个
PUT    /todos/{id}      更新（支持部分更新）
DELETE /todos/{id}      删除

所有响应使用统一的 JSON 格式：成功时 {"data": ...}，失败时 {"error": "..."}。

数据模型

从依赖树的叶子开始。model 包不依赖项目内的任何其他包，只定义数据结构：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

package model

import "time"

type Todo struct {
    ID        string    `json:"id"`
    Title     string    `json:"title"`
    Done      bool      `json:"done"`
    CreatedAt time.Time `json:"created_at"`
}

type CreateRequest struct {
    Title string `json:"title"`
}

type UpdateRequest struct {
    Title *string `json:"title,omitempty"`
    Done  *bool   `json:"done,omitempty"`
}

Todo 是核心实体，CreateRequest 和 UpdateRequest 是客户端发送的请求体。将请求体和实体分开定义是 API 设计的常见做法——客户端不应该控制 ID 和创建时间。

UpdateRequest 的字段是指针类型，这是为了实现「部分更新」：客户端发 {"done": true} 时，Title 为 nil（不更新），Done 非 nil（更新）。如果用 bool 而不是 *bool，就无法区分「客户端没传」和「客户端传了 false」——因为两者反序列化后都是零值 false。这个技巧只在需要区分「未传」和「传了零值」的场景下才需要；对于 CreateRequest 这种全量必填的结构，直接用值类型就好。

泛型响应包装

response 包用泛型定义统一的 API 响应格式——这是第五篇讨论的泛型在实际项目中的应用：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

package response

import (
    "encoding/json"
    "net/http"
)

type Response[T any] struct {
    Data  T      `json:"data,omitempty"`
    Error string `json:"error,omitempty"`
}

func JSON[T any](w http.ResponseWriter, status int, resp Response[T]) {
    w.Header().Set("Content-Type", "application/json")
    w.WriteHeader(status)
    json.NewEncoder(w).Encode(resp)
}

func OK[T any](w http.ResponseWriter, data T) {
    JSON(w, http.StatusOK, Response[T]{Data: data})
}

func Created[T any](w http.ResponseWriter, data T) {
    JSON(w, http.StatusCreated, Response[T]{Data: data})
}

func Err(w http.ResponseWriter, status int, msg string) {
    JSON(w, status, Response[any]{Error: msg})
}

没有泛型时，Data 只能是 interface{}，调用方拿到响应后还得做类型断言。有了 Response[T]，OK(w, todo) 返回的就是 Response[model.Todo]，OK(w, todos) 返回的就是 Response[[]*model.Todo]——类型在编译期确定。

存储层

store 包是业务逻辑的核心，综合运用了接口、错误处理和并发控制。

接口与哨兵错误

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

package store

import (
    "errors"
    "fmt"
    "sync"
    "time"

    "learn-go/14_todo_api/model"
)

var ErrNotFound = errors.New("todo not found")

type Store interface {
    List() []*model.Todo
    Get(id string) (*model.Todo, error)
    Create(title string) *model.Todo
    Update(id string, req model.UpdateRequest) (*model.Todo, error)
    Delete(id string) error
}

Store 是接口，定义了存储层的行为契约。handler 依赖这个接口，不依赖具体实现——未来换成数据库只需要写一个新的实现，handler 代码不用改。这是第二篇讨论的隐式接口的实际价值。

ErrNotFound 是哨兵错误，调用方通过 errors.Is(err, store.ErrNotFound) 来判断——不比较字符串，而是比较值。这是第三篇讨论过的错误处理惯例。

内存实现

1
2
3
4
5
6
7
8
9
10
11

type MemoryStore struct {
    mu     sync.RWMutex
    todos  map[string]*model.Todo
    nextID int
}

func NewMemoryStore() *MemoryStore {
    return &MemoryStore{
        todos: make(map[string]*model.Todo),
    }
}

sync.RWMutex 区分读锁和写锁：多个读操作可以同时进行（RLock），写操作独占（Lock）。对于「读多写少」的 API 服务，比普通的 sync.Mutex 并发性能更好。

读操作用 RLock：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

func (s *MemoryStore) List() []*model.Todo {
    s.mu.RLock()
    defer s.mu.RUnlock()

    result := make([]*model.Todo, 0, len(s.todos))
    for _, todo := range s.todos {
        result = append(result, todo)
    }
    return result
}

func (s *MemoryStore) Get(id string) (*model.Todo, error) {
    s.mu.RLock()
    defer s.mu.RUnlock()

    todo, ok := s.todos[id]
    if !ok {
        return nil, ErrNotFound
    }
    return todo, nil
}

写操作用 Lock：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45

func (s *MemoryStore) Create(title string) *model.Todo {
    s.mu.Lock()
    defer s.mu.Unlock()

    s.nextID++
    id := fmt.Sprintf("todo-%d", s.nextID)

    todo := &model.Todo{
        ID:        id,
        Title:     title,
        Done:      false,
        CreatedAt: time.Now(),
    }
    s.todos[id] = todo
    return todo
}

func (s *MemoryStore) Update(id string, req model.UpdateRequest) (*model.Todo, error) {
    s.mu.Lock()
    defer s.mu.Unlock()

    todo, ok := s.todos[id]
    if !ok {
        return nil, ErrNotFound
    }

    if req.Title != nil {
        todo.Title = *req.Title
    }
    if req.Done != nil {
        todo.Done = *req.Done
    }
    return todo, nil
}

func (s *MemoryStore) Delete(id string) error {
    s.mu.Lock()
    defer s.mu.Unlock()

    if _, ok := s.todos[id]; !ok {
        return ErrNotFound
    }
    delete(s.todos, id)
    return nil
}

Update 中体现了指针字段的作用：只有非 nil 的字段才会被更新，实现部分更新语义。

存储层测试

测试紧跟实现来读。用到了表驱动测试、子测试和并发安全测试：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80

package store

import (
    "sync"
    "testing"

    "learn-go/14_todo_api/model"
)

func TestCRUD(t *testing.T) {
    s := NewMemoryStore()
    var todoID string

    t.Run("Create", func(t *testing.T) {
        todo := s.Create("买牛奶")
        if todo.Title != "买牛奶" {
            t.Errorf("Title = %q, want %q", todo.Title, "买牛奶")
        }
        if todo.Done {
            t.Error("new todo should not be done")
        }
        if todo.ID == "" {
            t.Error("ID should not be empty")
        }
        todoID = todo.ID
    })

    t.Run("Get", func(t *testing.T) {
        todo, err := s.Get(todoID)
        if err != nil {
            t.Fatalf("Get(%q) error: %v", todoID, err)
        }
        if todo.Title != "买牛奶" {
            t.Errorf("Title = %q, want %q", todo.Title, "买牛奶")
        }
    })

    t.Run("Get_NotFound", func(t *testing.T) {
        _, err := s.Get("nonexistent")
        if err != ErrNotFound {
            t.Errorf("Get(nonexistent) error = %v, want ErrNotFound", err)
        }
    })

    t.Run("Update_Title", func(t *testing.T) {
        newTitle := "买酸奶"
        todo, err := s.Update(todoID, model.UpdateRequest{Title: &newTitle})
        if err != nil {
            t.Fatalf("Update error: %v", err)
        }
        if todo.Title != "买酸奶" {
            t.Errorf("Title = %q, want %q", todo.Title, "买酸奶")
        }
        if todo.Done {
            t.Error("Done should not change when only Title is updated")
        }
    })

    t.Run("Update_Done", func(t *testing.T) {
        done := true
        todo, err := s.Update(todoID, model.UpdateRequest{Done: &done})
        if err != nil {
            t.Fatalf("Update error: %v", err)
        }
        if !todo.Done {
            t.Error("Done should be true")
        }
    })

    t.Run("Delete", func(t *testing.T) {
        err := s.Delete(todoID)
        if err != nil {
            t.Fatalf("Delete error: %v", err)
        }
        _, err = s.Get(todoID)
        if err != ErrNotFound {
            t.Error("Get after Delete should return ErrNotFound")
        }
    })
}

这些子测试共享同一个 store 实例，前一个步骤的结果是后一个步骤的输入——Create 的 ID 传给 Get，Update 修改后 Delete 删除，Delete 后 Get 验证 404。

注意测试文件声明的是 package store（不是 package store_test），所以可以直接访问 ErrNotFound 等未导出的标识符——这是第四篇讨论的 _test.go 特权。

并发安全测试更有意思：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

func TestConcurrency(t *testing.T) {
    s := NewMemoryStore()
    s.Create("初始任务")

    var wg sync.WaitGroup
    const goroutines = 50

    for i := 0; i < goroutines; i++ {
        wg.Add(2)

        go func() {
            defer wg.Done()
            s.Create("并发创建")
        }()

        go func() {
            defer wg.Done()
            s.List()
        }()
    }

    wg.Wait()

    todos := s.List()
    expected := 1 + goroutines
    if len(todos) != expected {
        t.Errorf("List() len = %d, want %d", len(todos), expected)
    }
}

50 个 goroutine 同时写、50 个同时读。如果 RWMutex 保护有遗漏，go test -race 会捕获数据竞争。

HTTP 处理层

handler 包是 HTTP 和业务逻辑的衔接点：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

package handler

import (
    "encoding/json"
    "errors"
    "net/http"
    "strings"

    "learn-go/14_todo_api/model"
    "learn-go/14_todo_api/response"
    "learn-go/14_todo_api/store"
)

type Handler struct {
    store store.Store
}

func New(s store.Store) *Handler {
    return &Handler{store: s}
}

Handler 持有 store.Store 接口——依赖注入。main 函数负责创建具体的 MemoryStore 并传进来。

路由注册

Go 1.22 开始支持 "METHOD /path" 格式的路由，{id} 是路径参数：

1
2
3
4
5
6
7

func (h *Handler) RegisterRoutes(mux *http.ServeMux) {
    mux.HandleFunc("GET /todos", h.handleList)
    mux.HandleFunc("POST /todos", h.handleCreate)
    mux.HandleFunc("GET /todos/{id}", h.handleGet)
    mux.HandleFunc("PUT /todos/{id}", h.handleUpdate)
    mux.HandleFunc("DELETE /todos/{id}", h.handleDelete)
}

在 1.22 之前，标准库的 ServeMux 不支持方法匹配和路径参数，需要第三方路由库（如 gorilla/mux）或手动在 handler 里判断 r.Method。现在标准库就够用了。

各 Handler 实现

列出所有 todo，支持 ?status=done 过滤：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

func (h *Handler) handleList(w http.ResponseWriter, r *http.Request) {
    todos := h.store.List()

    statusFilter := r.URL.Query().Get("status")
    if statusFilter != "" {
        filtered := make([]*model.Todo, 0)
        for _, todo := range todos {
            switch strings.ToLower(statusFilter) {
            case "done":
                if todo.Done {
                    filtered = append(filtered, todo)
                }
            case "undone":
                if !todo.Done {
                    filtered = append(filtered, todo)
                }
            }
        }
        todos = filtered
    }

    response.OK(w, todos)
}

创建：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

func (h *Handler) handleCreate(w http.ResponseWriter, r *http.Request) {
    var req model.CreateRequest
    if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
        response.Err(w, http.StatusBadRequest, "invalid JSON: "+err.Error())
        return
    }

    if strings.TrimSpace(req.Title) == "" {
        response.Err(w, http.StatusBadRequest, "title is required")
        return
    }

    todo := h.store.Create(req.Title)
    response.Created(w, todo)
}

获取、更新、删除的结构都是同一个模式——解析请求、调用 store、处理错误、返回响应：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40

func (h *Handler) handleGet(w http.ResponseWriter, r *http.Request) {
    id := r.PathValue("id")

    todo, err := h.store.Get(id)
    if err != nil {
        h.handleError(w, err)
        return
    }

    response.OK(w, todo)
}

func (h *Handler) handleUpdate(w http.ResponseWriter, r *http.Request) {
    id := r.PathValue("id")

    var req model.UpdateRequest
    if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
        response.Err(w, http.StatusBadRequest, "invalid JSON: "+err.Error())
        return
    }

    todo, err := h.store.Update(id, req)
    if err != nil {
        h.handleError(w, err)
        return
    }

    response.OK(w, todo)
}

func (h *Handler) handleDelete(w http.ResponseWriter, r *http.Request) {
    id := r.PathValue("id")

    if err := h.store.Delete(id); err != nil {
        h.handleError(w, err)
        return
    }

    response.OK(w, map[string]string{"deleted": id})
}

错误映射用 errors.Is 将 store 层的哨兵错误转换为 HTTP 状态码：

1
2
3
4
5
6
7

func (h *Handler) handleError(w http.ResponseWriter, err error) {
    if errors.Is(err, store.ErrNotFound) {
        response.Err(w, http.StatusNotFound, err.Error())
        return
    }
    response.Err(w, http.StatusInternalServerError, "internal error")
}

Handler 测试

Go 标准库的 httptest 包可以在不启动真实 HTTP 服务的情况下测试 handler——构造请求、录制响应、直接调用 ServeHTTP：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

package handler

import (
    "bytes"
    "encoding/json"
    "net/http"
    "net/http/httptest"
    "testing"

    "learn-go/14_todo_api/model"
    "learn-go/14_todo_api/response"
    "learn-go/14_todo_api/store"
)

func setupTestServer() *http.ServeMux {
    s := store.NewMemoryStore()
    h := New(s)
    mux := http.NewServeMux()
    h.RegisterRoutes(mux)
    return mux
}

func decodeResponse[T any](t *testing.T, rec *httptest.ResponseRecorder) response.Response[T] {
    t.Helper()
    var resp response.Response[T]
    if err := json.NewDecoder(rec.Body).Decode(&resp); err != nil {
        t.Fatalf("decode response: %v", err)
    }
    return resp
}

decodeResponse 是一个泛型辅助函数——又一个泛型的实际用例：不同测试需要解码不同类型的响应体，一个函数搞定。

测试创建和获取的完整流程：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

func TestCreateAndGet(t *testing.T) {
    mux := setupTestServer()

    // 创建
    body := `{"title":"学习 Go"}`
    req := httptest.NewRequest("POST", "/todos", bytes.NewBufferString(body))
    rec := httptest.NewRecorder()
    mux.ServeHTTP(rec, req)

    if rec.Code != http.StatusCreated {
        t.Fatalf("POST /todos status = %d, want %d", rec.Code, http.StatusCreated)
    }

    resp := decodeResponse[model.Todo](t, rec)
    if resp.Data.Title != "学习 Go" {
        t.Errorf("Title = %q, want %q", resp.Data.Title, "学习 Go")
    }

    // 用返回的 ID 获取
    todoID := resp.Data.ID
    req = httptest.NewRequest("GET", "/todos/"+todoID, nil)
    rec = httptest.NewRecorder()
    mux.ServeHTTP(rec, req)

    if rec.Code != http.StatusOK {
        t.Fatalf("GET status = %d, want %d", rec.Code, http.StatusOK)
    }
}