Liuqi.dev
发布于

博客构建通过,示例却不能运行:给技术文章补上代码验收

作者
  • avatar
    姓名
    刘琦

技术博客里的代码块有一个容易被忽略的特点:即使里面写了不存在的 API,页面也可能照常生成。

近期修订本站 Java 21 文章时,就碰到了这种问题。原文出现了不存在的 Executors.newVirtualThreadPool(),另一段配置则把平台线程池参数当成了虚拟线程配置。它们在页面上都有语法高亮,看起来很像可直接使用的示例,但需要编译和运行测试才能验证。

相关旧文已经修订。这篇不再介绍虚拟线程本身,而是讨论一个更通用的问题:怎样给技术文章中的代码建立一套成本可控的验收流程?

一、先分清两种构建

博客构建主要检查页面能否生成,例如 MDX 能否解析、组件能否编译、路由能否导出。围栏中的 Java、SQL、YAML 通常只是需要展示的文本。

示例验证检查的是另一件事:读者照着写,目标工具能否接受,结果是否符合正文的解释。

因此,一篇文章至少有两条独立的检查线:

  • 内容构建:文章能不能被正常展示。
  • 示例验证:文章教的方法是否在指定条件下成立。

站点构建通过,不能替代 Java 编译器、数据库执行计划或框架配置测试。反过来,示例正确也不意味着线上页面一定更新。

二、给示例写一个最小契约

验证之前,先明确这段代码究竟承诺了什么。

以虚拟线程为例,最小契约可以写成:

项目约定
版本Java 21
依赖只使用 JDK 标准库
输入提交一个任务
预期任务运行在虚拟线程中
不包含高并发性能、数据库吞吐量和内存上限

最后一行尤其重要。一个任务成功运行,只能证明 API 可用及基本行为正确,不能推出“吞吐提升十倍”或“能承载百万请求”。

类似地,SQL 优化示例的契约不能只有“跑得更快”,还要包含“结果集合保持不变”。配置示例也不能只证明应用能启动,还要确认目标配置确实生效。

三、把关键代码补成完整程序

文章可以为了阅读省略样板代码,但测试版本必须完整。

下面保存为 VirtualThreadCheck.java,使用 Java 21 运行:

import java.util.concurrent.Executors;
import java.util.concurrent.TimeUnit;

public class VirtualThreadCheck {
    public static void main(String[] args) throws Exception {
        try (var executor = Executors.newVirtualThreadPerTaskExecutor()) {
            boolean virtual = executor.submit(
                () -> Thread.currentThread().isVirtual()
            ).get(5, TimeUnit.SECONDS);
            if (!virtual) {
                throw new AssertionError("Expected a virtual thread");
            }
        }
        System.out.println("PASS: task runs on a virtual thread");
    }
}

在带编译能力的 Java 21 环境中,可以直接使用源码文件启动方式:

java --version
java VirtualThreadCheck.java

预期输出:

PASS: task runs on a virtual thread

也可以使用完整 JDK 中的 javac:

javac --release 21 VirtualThreadCheck.java
java VirtualThreadCheck

这里故意没有使用 Java 的 assert 关键字,避免漏传 -ea 后,断言根本没有执行却仍显示成功。

准备本文时,上面的源码启动命令已在 OpenJDK 21.0.13 上执行通过。它验证的是单个任务的线程类型,没有进行性能压测。API 定义见 Java 21 Executors 文档。

四、配置必须验证效果,不能只验证格式

YAML 缩进正确,不代表配置项真实存在;应用正常启动,也不代表某个开关已经生效。

检查 Spring Boot 配置,可以使用 ApplicationContextRunner 启动范围较小的测试上下文,只加载目标自动配置,然后检查生成的 Bean 和实际行为。它的用法见 Spring Boot 自动配置测试文档。

针对旧文中的问题,测试分成两组:

  1. 只设置 spring.task.execution.pool.*,检查自动配置的执行器类型,并提交一个任务读取 Thread.currentThread().isVirtual()。
  2. 设置 spring.threads.virtual.enabled=true,重复同样的检查。

在 Java 21、Spring Boot 3.2.3、没有自定义 Executor 的测试条件下,第一组运行平台线程,第二组运行虚拟线程。修订旧文时,这两项测试都已通过。

这个基线只用于复核旧示例,不代表生产项目现在应该选择 Spring Boot 3.2.3。

也不需要为了证明线程池参数危险,就真的创建百万个线程。读取 Bean 的池配置,再执行一个任务验证线程类型,已经能确认“这是不是虚拟线程配置”。资源耗尽测试是另一项工作,不应随手混入文档验证。

五、增加反例,检查测试是否真的管用

只看到绿色结果,还不能判断测试是否覆盖了正文的关键承诺。

可以为几个高风险点准备独立反例:

  • 把正确的方法名换成不存在的方法,编译应失败。
  • 让 record 没有实现 switch 参数所需的接口,编译应失败。
  • 编译 Java 21 预览语法时去掉预览参数,应失败。
  • 在授权示例中,用另一个用户访问不属于自己的对象,应被拒绝。

这些反例要与正常示例分开放置。测试脚本预期它们失败,不能让普通构建因为反例而永远失败,也不能用 || true 把所有失败都吞掉。

还要检查失败原因。编译器不存在、依赖下载失败、源代码不合法,是三类完全不同的问题。一个不存在的 API 因为网络故障而“测试失败”,并没有证明测试找到了代码错误。

六、版本要进入测试条件

技术示例经常不是永远错误,而是只适用于某个版本。

Java 的预览特性尤其明显:它可能修改、继续预览,也可能被撤回。验证预览代码时,需要使用对应版本的 JDK,并在编译和运行阶段显式启用预览。不能仅在文章标题里写“Java 21”,测试时却随手使用另一版本。

例如,对于完整的 Java 21 预览示例:

javac --enable-preview --release 21 PreviewDemo.java
java --enable-preview PreviewDemo

这里的 PreviewDemo.java 代表另行准备的完整预览程序,不是前面的虚拟线程示例。虚拟线程在 Java 21 已经正式发布,不需要预览开关。规则见 Oracle 预览特性文档。

框架示例同样需要记录准确版本。不要用“3.x 都差不多”代替验证,也不要因为旧版本测试通过,就把它描述成当前最佳选型。

七、验收记录应当比“已测试”更具体

一次有用的记录可以很短:

运行环境:OpenJDK 21.0.13
检查对象:VirtualThreadCheck.java
执行命令:java VirtualThreadCheck.java
预期行为:任务内 isVirtual() 返回 true
结果:通过
未覆盖:并发压测、数据库访问、生产部署

记录需要与文章中的示例对应。正文改过代码,测试文件却没同步,就会出现“测试通过的是另一个版本”的问题。

小型博客可以先人工比对;示例多了,再考虑让正文引用同一份测试源码中的指定片段。不要一开始就搭复杂平台,更不要自动执行文章里任意来源的代码块。进入自动测试的示例应经过审阅,并在没有生产凭据和真实业务数据的隔离环境中运行。

最后

技术文章不必把每个片段都做成完整工程,但关键承诺应该能被检查。

API 是否存在,让编译器回答;配置是否生效,让运行结果回答;SQL 改写是否等价,让边界数据回答;性能是否提高,让对应负载的测量回答。

把这些问题分别验证,比在文章末尾笼统写一句“代码已测试”更有用,也更方便下一次版本升级时重新检查。