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

- 姓名
- 刘琦
技术博客里的代码块有一个容易被忽略的特点:即使里面写了不存在的 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 自动配置测试文档。
针对旧文中的问题,测试分成两组:
- 只设置
spring.task.execution.pool.*,检查自动配置的执行器类型,并提交一个任务读取Thread.currentThread().isVirtual()。 - 设置
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 改写是否等价,让边界数据回答;性能是否提高,让对应负载的测量回答。
把这些问题分别验证,比在文章末尾笼统写一句“代码已测试”更有用,也更方便下一次版本升级时重新检查。