虚拟线程执行下面这段代码时，表面上和普通线程没有区别：

int count = socket.getInputStream().read(buffer);
process(buffer, count);

当 Socket 暂时没有数据，当前虚拟线程会暂停。承载它的 Carrier Thread 随后可以运行其他虚拟线程。网络数据到达后，原虚拟线程重新得到调度，read() 返回，代码继续执行 process()。

这里容易产生几个疑问：

• Carrier Thread 只能线性执行代码，当前方法还没有执行完，它怎么去运行另一个任务？
• 虚拟线程暂停后保存在哪里？
• 网络事件到达时，Poller 如何找到对应的虚拟线程？
• 调度队列中保存的是虚拟线程、回调函数，还是完整调用栈？
• 网络数据怎样回到原来的 buffer？
• Continuation.yield()、Thread.yield() 和 LockSupport.park() 分别负责什么？

本文以 JDK 21 的实现为基线，沿着一次 Socket 读取的调用过程分析这些问题。JDK 21 的虚拟线程采用 M:N 调度，大量虚拟线程由 JDK 调度到少量平台线程上运行；默认调度器是一个独立的 ForkJoinPool。（OpenJDK）

Carrier Thread 没有任务切换指令

先去掉虚拟线程，只看一个普通的工作线程：

final class Worker extends Thread {
    private final BlockingQueue<Runnable> queue;
    Worker(BlockingQueue<Runnable> queue) {
        this.queue = queue;
    }
    @Override
    public void run() {
        while (!isInterrupted()) {
            try {
                Runnable task = queue.take();
                task.run();
            } catch (InterruptedException e) {
                interrupt();
            }
        }
    }
}

这条线程始终线性执行。它从队列取出一个 Runnable，调用 run()，等待该方法返回，然后进入下一轮循环。

Runnable taskA = queue.take();
taskA.run();
Runnable taskB = queue.take();
taskB.run();

Carrier Thread 的工作方式也是如此。它不会在 taskA.run() 尚未返回时，突然跳到 taskB.run()。

虚拟线程能够切换，是因为 taskA.run() 可以在业务调用尚未完成时暂时返回。返回之前，JVM 会保存虚拟线程的调用栈。以后再次执行这个任务时，JVM 恢复原调用栈，代码继续运行。

因此，一条 Carrier Thread 上实际发生的是：

virtualThreadAResumeTask.run(); // 保存调用栈后暂时返回
virtualThreadBResumeTask.run(); // Carrier 回到调度循环后执行

Carrier Thread 仍然遵守普通方法调用规则。特殊能力位于 Continuation，它允许一段尚未完成的调用栈暂停和恢复。

调度队列中保存了什么

JDK 21 的 VirtualThread 内部有几个关键字段。省略诊断、线程容器和中断处理后，可以整理成下面的结构：

final class VirtualThread extends Thread {
    private final Executor scheduler;
    private final Continuation cont;
    private final Runnable runContinuation;
    private volatile int state;
    private volatile boolean parkPermit;
    private volatile Thread carrierThread;
}

其中：

• scheduler 指向虚拟线程调度器。
• cont 保存可暂停和恢复的执行状态。
• runContinuation 是提交给调度器的任务。
• state 记录虚拟线程当前处于运行、挂起或可调度状态。
• parkPermit 保存一次 unpark 许可。
• carrierThread 指向当前承载该虚拟线程的平台线程。

构造虚拟线程时，会创建 Continuation，并生成一个绑定到当前虚拟线程的方法引用：

this.cont = new VThreadContinuation(this, task);
this.runContinuation = this::runContinuation;

方法引用可以展开成一个普通的 Runnable：

final class ResumeTask implements Runnable {
    private final VirtualThread virtualThread;
    ResumeTask(VirtualThread virtualThread) {
        this.virtualThread = virtualThread;
    }
    @Override
    public void run() {
        virtualThread.runContinuation();
    }
}

调度队列中保存的核心内容是这样一个恢复任务。它持有 VirtualThread 引用，而 VirtualThread 再持有 Continuation。

ForkJoinPool.WorkQueue
    └── ForkJoinTask
          └── runContinuation
                └── VirtualThread
                      └── Continuation

VirtualThread 不直接操作 ForkJoinPool 中的某个工作队列。它只调用：

scheduler.execute(runContinuation);

默认调度器收到普通 Runnable 后，会将其包装为 ForkJoinTask，再放入内部队列。OpenJDK 的注释说明，在调度器 Worker 上提交时，任务进入本地队列；其他线程提交时，任务进入外部提交队列。（GitHub）

虚拟线程第一次运行

启动虚拟线程时，内部会把状态由 NEW 修改为 STARTED，随后提交 runContinuation：

void start() {
    if (!compareAndSetState(NEW, STARTED)) {
        throw new IllegalThreadStateException();
    }
    submitRunContinuation();
}
private void submitRunContinuation() {
    scheduler.execute(runContinuation);
}

某条 Carrier Thread 从 ForkJoinPool 队列中取出任务，最终调用：

virtualThread.runContinuation();

runContinuation() 的主要结构如下：

private void runContinuation() {
    int initialState = state();
    if (initialState != STARTED
            && initialState != UNPARKED
            && initialState != YIELDED) {
        return;
    }
    if (!compareAndSetState(initialState, RUNNING)) {
        return;
    }
    mount();
    try {
        cont.run();
    } finally {
        unmount();
        if (cont.isDone()) {
            afterDone();
        } else {
            afterYield();
        }
    }
}

mount() 将当前平台线程记录为 Carrier，并修改 JVM 中的当前线程身份：

private void mount() {
    Thread carrier = Thread.currentCarrierThread();
    setCarrierThread(carrier);
    carrier.setCurrentThread(this);
}

因此，虚拟线程中的业务代码调用：

Thread.currentThread()

得到的是 VirtualThread 对象，而不是底层 Carrier Thread。

随后执行：

cont.run();

第一次调用时，Continuation 从用户任务入口开始执行。OpenJDK 的 runContinuation() 确实是在 mount() 后调用 cont.run()，并在 finally 中完成 unmount() 和后续状态处理。（GitHub）

Continuation.yield() 如何释放 Carrier

假设业务代码的调用关系如下：

void handleRequest(Socket socket) throws IOException {
    User user = loadUser();
    byte[] buffer = new byte[1024];
    int count = socket.getInputStream().read(buffer);
    process(user, buffer, count);
}

虚拟线程执行到网络等待位置时，Carrier Thread 上的逻辑调用栈可能是：

ForkJoinPool.runWorker()
VirtualThread.runContinuation()
Continuation.run()
handleRequest()
InputStream.read()
NioSocketImpl.implRead()
Poller.poll()
LockSupport.park()
VirtualThread.park()
Continuation.yield()

执行 Continuation.yield() 后，JVM 会冻结属于当前 Continuation 的栈帧。局部变量、对象引用、调用关系和程序执行位置都会被保留。

例如，handleRequest() 对应的栈帧中可能存在：

socket  -> Socket@100
user    -> User@200
buffer  -> byte[]@300
count   -> 尚未赋值

这些数据属于虚拟线程的执行状态，不再依赖当前 Carrier Thread 的平台栈。

冻结成功后，控制流会离开 Continuation，回到调用 cont.run() 的位置。此时属于虚拟线程的深层调用栈已经从 Carrier Thread 上移走，Carrier Thread 上只剩调度器相关栈帧：

ForkJoinPool.runWorker()
VirtualThread.runContinuation()

cont.run() 随后返回，runContinuation() 进入 finally，执行 unmount()：

private void unmount() {
    Thread carrier = this.carrierThread;
    carrier.setCurrentThread(carrier);
    setCarrierThread(null);
}

runContinuation() 返回后，Carrier Thread 回到 ForkJoinPool 的工作循环，从队列中获取其他任务。

后续某条 Carrier Thread 再次调用 cont.run() 时，JVM 恢复此前冻结的栈帧，原来的 Continuation.yield() 开始返回，调用链依次继续：

Continuation.yield() 返回
VirtualThread.park() 返回
LockSupport.park() 返回
Poller.poll() 返回
NioSocketImpl.implRead() 继续

这里没有重新调用 handleRequest()，也没有从方法开头重新执行。恢复点位于此前暂停的位置。

park() 为什么不会立即重新入队

Continuation.yield() 只负责暂停执行，它并不决定虚拟线程什么时候继续。调度策略取决于是谁调用了它。

虚拟线程调用 Thread.yield() 时，当前线程依然具备运行条件，只是暂时让出 Carrier。执行栈冻结后，afterYield() 会立即重新提交 runContinuation：

RUNNING
  -> YIELDING
  -> YIELDED
  -> 重新提交
  -> RUNNING

LockSupport.park() 表达的是等待条件尚未满足。例如等待网络数据、等待锁释放或者等待队列元素。执行栈冻结后，虚拟线程不能立即重新进入运行队列，否则会不断恢复、检查条件、再次挂起，造成 CPU 空转。

它的状态变化为：

RUNNING
  -> PARKING
  -> PARKED

只有其他线程调用 unpark() 后，它才重新具备运行条件：

PARKED
  -> UNPARKED
  -> 重新提交
  -> RUNNING

OpenJDK 的 afterYield() 会检查当前状态。PARKING 会转为 PARKED，默认不重新提交；YIELDING 会转为 YIELDED 并立即提交。（GitHub）

对应代码可以简化为：

private void afterYield() {
    int s = state();
    if (s == PARKING) {
        setState(PARKED);
        if (parkPermit
                && compareAndSetState(PARKED, UNPARKED)) {
            submitRunContinuation();
        }
        return;
    }
    if (s == YIELDING) {
        setState(YIELDED);
        submitRunContinuation();
    }
}

Socket 读取如何进入 Poller

下面进入网络 I/O 路径。

int count = socket.getInputStream().read(buffer);

以 JDK 21 在 Linux 上的实现为例，JDK 会先尝试读取 Socket。内核接收缓冲区已有数据时，读取直接完成，不需要挂起虚拟线程。

如果当前没有数据，非阻塞读取会得到 EAGAIN 或等价状态。JDK 随后将文件描述符注册给 Poller，并挂起当前虚拟线程。JEP 444 描述了这一处理：JDK 中的阻塞网络操作无法立即完成时，虚拟线程会卸载；I/O 可以完成后，再把该虚拟线程提交回调度器。（OpenJDK）

简化后的读取逻辑如下：

int read(int fd, byte[] buffer) throws IOException {
    while (true) {
        int result = nonBlockingRead(fd, buffer);
        if (result >= 0) {
            return result;
        }
        Poller.poll(fd);
    }
}

Poller.poll(fd) 内部可以抽象为：

void poll(int fd) {
    Thread thread = Thread.currentThread();
    waiters.put(fd, thread);
    registerWithEpoll(fd);
    LockSupport.park();
}

由于当前执行的是虚拟线程，Thread.currentThread() 返回对应的 VirtualThread。

此时存在两份关联。

Linux 内核中的 epoll 记录：

监听 fd 37 的可读事件

JDK 的 Poller 记录：

fd 37 -> VirtualThread@500

操作系统只认识文件描述符，不认识 Java 虚拟线程。Poller 中的映射负责将内核事件重新关联到 Java 线程对象。JDK 21 的 Poller 就是网络事件通知和虚拟线程唤醒之间的中间层。（GitHub）

注册完成后，当前虚拟线程执行：

LockSupport.park();

park() 进入 VirtualThread.park()，设置 PARKING 状态并调用 Continuation.yield()。执行栈冻结后，虚拟线程变成 PARKED，Carrier Thread 被释放。

等待期间的对象关系如下：

Linux epoll
    └── fd 37
Poller
    └── fd 37 -> VirtualThread@500
VirtualThread@500
    ├── state = PARKED
    ├── carrierThread = null
    └── Continuation
          └── 保存 read() 及其上层调用栈
ForkJoinPool
    └── 当前没有该虚拟线程的恢复任务

虚拟线程此时没有占用 Carrier Thread，也不在运行队列中。Poller 保存它的等待关系，Continuation 保存它的执行状态。

网络就绪后如何重新调度

网络数据到达后，Linux 协议栈将字节放入 Socket 的内核接收缓冲区，并将 fd 标记为可读。

Linux 上的 Poller 线程通常阻塞在 epoll_wait()。事件返回后，它获得就绪的文件描述符：

int[] readyFds = epollWait();
for (int fd : readyFds) {
    Thread thread = waiters.remove(fd);
    if (thread != null) {
        LockSupport.unpark(thread);
    }
}

Poller 不执行用户的 handleRequest()，也不会在 Poller Thread 中调用原来的 InputStream.read()。它只找到等待该 fd 的虚拟线程，然后调用 unpark()。

VirtualThread.unpark() 的关键逻辑如下：

void unpark() {
    Thread currentThread = Thread.currentThread();
    if (!getAndSetParkPermit(true)
            && currentThread != this) {
        int s = state();
        if (s == PARKED
                && compareAndSetState(PARKED, UNPARKED)) {
            submitRunContinuation();
        }
    }
}

submitRunContinuation() 最终执行：

scheduler.execute(runContinuation);

这一步把虚拟线程重新交给调度器。OpenJDK 的 unpark() 会先设置 parkPermit，再通过状态 CAS 将已挂起的虚拟线程转为 UNPARKED，随后提交其恢复任务。（GitHub）

由于调用 unpark() 的通常是 Poller Thread，它不属于默认调度器的 Worker，因此这次任务一般走 ForkJoinPool 的外部提交路径。

某条 Carrier Thread 之后取出该任务，再次调用：

virtualThread.runContinuation();

状态由 UNPARKED 修改为 RUNNING，虚拟线程挂载到新的 Carrier Thread，然后执行：

cont.run();

此前冻结的调用栈被恢复，LockSupport.park() 返回，Socket 读取逻辑继续。

网络数据没有进入调度队列

调度队列中没有网络数据，也没有下面这种对象：

new ResumeTask(virtualThread, networkData);

Poller 的职责是通知“fd 现在可能可读”，调度器负责安排虚拟线程继续执行。网络字节仍然保存在 Socket 的内核接收缓冲区中。

虚拟线程恢复后，读取循环再次调用操作系统：

int read(int fd, byte[] buffer) throws IOException {
    while (true) {
        int result = nonBlockingRead(fd, buffer);
        if (result >= 0) {
            return result;
        }
        Poller.poll(fd);
        // park 返回后，再次进入循环
    }
}

第一次 nonBlockingRead() 返回 EAGAIN，虚拟线程进入等待。

网络就绪后，Poller 调用 unpark()，虚拟线程恢复，随后再次执行：

nonBlockingRead(fd, buffer);

这一次内核接收缓冲区已有数据，系统调用将字节复制到原来的 buffer 中，并返回字节数。

之所以仍然能够访问原来的 buffer，是因为 Continuation 保存的调用栈中仍持有：

buffer -> byte[]@300

数据传递路径为：

网卡
  -> Linux 网络协议栈
  -> Socket 内核接收缓冲区
  -> 虚拟线程被唤醒
  -> 恢复 read() 调用栈
  -> 再次执行 read()
  -> 数据复制到原 buffer

调度队列只传递执行资格。Poller 只传递就绪通知。网络数据由内核 Socket 缓冲区保存。

parkPermit 解决丢失唤醒

虚拟线程准备挂起时，网络事件可能提前到达。

考虑下面的时序：

虚拟线程发现当前没有数据
Poller 注册 fd
网络数据立即到达
Poller 调用 unpark()
虚拟线程随后才执行 park()

如果 unpark() 只能唤醒已经处于 PARKED 状态的线程，这次通知就会丢失。虚拟线程之后进入 park()，可能一直无法恢复。

parkPermit 相当于一个容量为 1 的许可：

private volatile boolean parkPermit;

unpark() 首先设置：

parkPermit = true;

park() 开始时先尝试消费许可：

if (getAndSetParkPermit(false)) {
    return;
}

如果网络事件已经到达，park() 直接返回，不再冻结调用栈。

连续调用多次 unpark() 也只会保存一个许可：

unpark(thread);
unpark(thread);
unpark(thread);

最终仍然只是：

parkPermit = true

下一次 park() 消费该许可后恢复为 false。

这也是 JUC 同步器通常使用循环检查条件的原因：

while (!conditionSatisfied()) {
    LockSupport.park();
}

park() 返回只说明线程重新获得执行机会，业务条件仍需重新判断。

PARKING 解决重复调度

RUNNING 和 PARKED 两个状态还不够，因为调用栈冻结需要一段执行过程。

虚拟线程会先执行：

state = PARKING;
Continuation.yield();

在设置 PARKING 后、Continuation 完成冻结前，Poller 可能已经调用 unpark()。

此时原 Carrier Thread 仍可能执行当前虚拟线程，不能立刻把恢复任务提交给调度器。否则另一条 Carrier Thread 可能同时取出该虚拟线程。

因此，在 PARKING 状态下，unpark() 只设置 parkPermit，暂不提交任务。

等 Continuation 冻结完成，原 Carrier 执行 afterYield()：

state = PARKED;
if (parkPermit
        && compareAndSetState(PARKED, UNPARKED)) {
    submitRunContinuation();
}

这样既保留了提前到达的唤醒通知，也避免两条 Carrier Thread 同时运行同一个虚拟线程。

另外，runContinuation() 在恢复前还会对状态执行 CAS。即使调度队列中意外出现两个指向同一虚拟线程的恢复任务，也只有一条 Carrier Thread 能成功将状态改为 RUNNING。

三条线程如何协作

完整实现虽然涉及 ForkJoinPool、Continuation、Poller 和操作系统，但运行过程仍然可以拆成三条普通线程循环。

Carrier Thread 的循环：

while (true) {
    Runnable task = scheduler.takeTask();
    task.run();
}

Poller Thread 的循环：

while (true) {
    int[] readyFds = epollWait();
    for (int fd : readyFds) {
        VirtualThread thread = waiters.remove(fd);
        LockSupport.unpark(thread);
    }
}

虚拟线程中的 Socket 读取循环：

while (true) {
    int count = tryRead(fd, buffer);
    if (count >= 0) {
        return count;
    }
    registerPoller(fd, Thread.currentThread());
    LockSupport.park();
}

三条执行流都保持线性。它们通过以下对象建立联系：

ForkJoinPool WorkQueue
    保存可运行的 runContinuation
VirtualThread
    持有 scheduler、Continuation 和线程状态
Poller
    保存 fd 到 VirtualThread 的等待关系
Socket 内核接收缓冲区
    保存网络数据

Carrier Thread 调用恢复任务，Poller 根据 fd 找到等待线程，虚拟线程通过 scheduler 重新提交自己，Continuation 保存暂停位置和局部对象引用。

完整调用路径

将整个过程连接起来，可以得到下面的关键路径：

Thread.startVirtualThread
  -> VirtualThread.start
  -> submitRunContinuation
  -> ForkJoinPool 工作队列
  -> Carrier 取出任务
  -> VirtualThread.runContinuation
  -> mount
  -> Continuation.run
  -> 用户代码
  -> Socket.read
  -> 非阻塞 read 返回 EAGAIN
  -> Poller 注册 fd
  -> LockSupport.park
  -> VirtualThread.park
  -> Continuation.yield
  -> 调用栈被冻结
  -> cont.run 暂时返回
  -> unmount
  -> VirtualThread 进入 PARKED
  -> Carrier 返回调度循环
网络数据到达
  -> Socket 内核接收缓冲区
  -> epoll_wait 返回 fd
  -> Poller 找到 VirtualThread
  -> LockSupport.unpark
  -> VirtualThread.unpark
  -> submitRunContinuation
  -> ForkJoinPool 工作队列
  -> Carrier 取出恢复任务
  -> VirtualThread.runContinuation
  -> mount
  -> Continuation.run
  -> 恢复被冻结的调用栈
  -> LockSupport.park 返回
  -> 再次执行 read
  -> 数据复制到原 buffer
  -> 用户代码继续

理解这条路径后，虚拟线程的调度就不再神秘。Carrier Thread 始终执行普通任务循环；Continuation 允许当前任务在保留调用栈的情况下暂时返回；Poller 将网络 fd 与等待中的虚拟线程关联起来；unpark() 在事件到达后重新提交恢复任务。

JDK 21 与 JDK 24 的 Pinning 差异

JDK 21 中，如果虚拟线程在持有 synchronized Monitor 时进入某些阻塞操作，Continuation 可能无法卸载，虚拟线程和 Carrier Thread 会一起阻塞，这种情况称为 Pinning。

因此，JDK 21 阶段经常建议避免在长时间 synchronized 临界区中执行网络 I/O，必要时使用 ReentrantLock。

JDK 24 交付了 JEP 491，修改了 JVM Monitor 与虚拟线程的协作方式。虚拟线程在 synchronized 方法或代码块中阻塞时，绝大部分情况下也能卸载并释放 Carrier Thread。JDK 24 之后，选择 synchronized 还是 java.util.concurrent.locks，应更多依据可中断获取、公平性、超时和条件变量等语义，而不是单纯为了规避 Monitor Pinning。（OpenJDK）

持锁期间执行长时间网络 I/O 仍然需要谨慎。即便 Carrier 能够释放，锁本身仍然处于持有状态，其他需要进入同一临界区的线程仍会等待。

参考源码

• JEP 444：Virtual Threads。（OpenJDK）
• JDK 21 java.lang.VirtualThread。（GitHub）
• JDK 21 jdk.internal.vm.Continuation。（GitHub）
• JDK 21 sun.nio.ch.Poller。（GitHub）
• JEP 491：Synchronize Virtual Threads without Pinning。（OpenJDK）

Finished reading? Leave a comment

最近在整理一套可以长期复用的 TypeScript 项目模板。

我的项目大多是 AI 工具、管理后台、工作流、编辑器和桌面端配套应用。技术栈以 React、TypeScript 和 Vite 为主，后端会使用 Node.js、PostgreSQL 和 Drizzle。

一开始考虑的是直接选择一个 React 全栈框架，把路由、SSR、数据请求、API 和部署统一起来。重点看了 Next.js、React Router Framework Mode 和 TanStack Start，也顺带关注了 Remix 3。

研究了一段时间后，我发现框架能力并不是越完整越合适。对于偏重交互的应用，SSR 和同构运行模型会引入不少额外概念，而这些概念未必能直接转化为产品收益。

最后确定的方向是：

公开站点使用 SSR 或 SSG
登录后的产品使用 SPA
业务能力通过统一 HTTP API 提供

这篇文章记录一下具体的判断过程。

TanStack Start 的吸引力

TanStack Start 很符合我对现代 TypeScript 框架的期待。

它建立在 TanStack Router 和 Vite 之上，提供类型安全路由、Search Params、Loader、Server Function、Middleware 和 SSR。再配合 TanStack Query、Form 和 Table，可以形成一套完整的前端应用开发体系。

一个简单的服务端查询可以写成：

export const listProjectsFn = createServerFn()
  .handler(async () => {
    return db.select().from(projects)
  })

路由中直接调用：

export const Route = createFileRoute('/projects')({
  loader: () => listProjectsFn(),
  component: ProjectsPage,
})

组件通过路由读取结果：

function ProjectsPage() {
  const projects = Route.useLoaderData()

  return <ProjectList projects={projects} />
}

这种写法不需要手动维护 HTTP Client 和返回类型。Server Function 在客户端表现得像一个普通的异步函数，输入和输出类型可以直接推导。

对于简单页面，这套模式很顺畅。

问题主要出现在页面交互开始变复杂之后。

例如，列表需要手动刷新，可以调用：

router.invalidate()

如果列表使用 TanStack Query，则会写成：

query.refetch()

新增一条记录后，可以重新执行路由 Loader：

await router.invalidate()

也可以让 Query Cache 失效：

await queryClient.invalidateQueries({
  queryKey: ['projects'],
})

这时项目里可能同时存在两套数据生命周期：

Route Loader 管理路由数据
TanStack Query 管理客户端缓存

如果继续加入 Query Options、Mutation、TanStack Form、TanStack Table 和 Zod，一个普通 Feature 很容易拆出很多文件：

project.server.ts
project.functions.ts
project.queries.ts
project.mutations.ts
project.schema.ts
project.form.ts
project.columns.tsx

这些模块单独看都有合理用途，但组合起来后，简单业务的框架代码占比会比较高。

TanStack 生态本身没有要求项目必须这样写。问题在于它提供的能力很多，开发者很容易在项目初期就把完整方案铺开。

对于复杂 Dashboard、实时数据、无限列表和乐观更新，这些抽象能够发挥作用。对于普通 CRUD，它们可能显得偏重。

Next.js 的复杂度在运行边界

Next.js 的代码通常更短。

Server Component 可以直接查询数据库：

export default async function ProjectPage() {
  const projectList = await db
    .select()
    .from(projects)

  return <ProjectList projects={projectList} />
}

修改操作可以写成 Server Action：

'use server'

export async function createProject(
  formData: FormData,
) {
  await db.insert(projects).values({
    name: String(formData.get('name')),
  })

  revalidatePath('/projects')
}

页面直接提交：

<form action={createProject}>
  <input name="name" />
  <button type="submit">创建</button>
</form>

这种模式对内容站、电商和以服务端渲染为主的页面很合适。页面、数据读取和修改逻辑可以放在相近的位置，项目初期的代码量也不大。

随着客户端交互增加，代码会逐渐涉及：

Server Component
Client Component
Server Action
Route Handler
Suspense
缓存失效
序列化边界

Next.js 的额外成本通常不表现为大量包装函数，而是运行模型和框架规则。

对于编辑器、工作流和管理后台，页面里往往有较多本地状态、轮询、实时数据、弹窗和多区域交互。此时 Server Component 与 Client Component 的边界需要持续维护。

Next.js 依然是成熟的生产方案，只是它更偏向以服务端组件和页面渲染为中心组织应用，不完全符合我目前的产品形态。

React Router 的数据模型比较统一

React Router Framework Mode 使用 Loader 和 Action 组织路由数据。

export async function loader() {
  return {
    projects: await listProjects(),
  }
}

export async function action({
  request,
}: Route.ActionArgs) {
  const formData = await request.formData()

  return createProject({
    name: String(formData.get('name')),
  })
}

export default function ProjectsPage({
  loaderData,
}: Route.ComponentProps) {
  return (
    <>
      <ProjectList projects={loaderData.projects} />

      <Form method="post">
        <input name="name" />
        <button type="submit">创建</button>
      </Form>
    </>
  )
}

它的模型比较接近传统 Web 开发：

读取数据使用 loader
修改数据使用 action
页面提交使用 Form 或 fetcher

Action 完成后，React Router 会重新验证相关 Loader，因此普通表单场景不需要额外维护 Query Cache。

这种方式适合表单和路由驱动的应用。Request、Response、Cookie、Session 和上传都使用标准 Web API，调试路径也比较清楚。

页面内操作较多时，Action 可能需要根据 intent 分发不同业务：

switch (formData.get('intent')) {
  case 'create':
    return createProject(formData)

  case 'archive':
    return archiveProject(formData)

  case 'delete':
    return deleteProject(formData)
}

也可以拆成独立 Resource Route。

React Router 的代码量通常介于 Next.js 和完整 TanStack 方案之间。它适合传统 Web 数据流，但对于复杂客户端缓存和多个组件共享远程状态，项目最终仍可能引入 TanStack Query。

SPA 的数据流更适合产品后台

把几个全栈框架放在一起比较之后，我重新审视了普通 SPA。

一个 SPA 项目的远程数据流很直接：

React Component
    ↓
TanStack Query
    ↓
HTTP API
    ↓
业务逻辑
    ↓
数据库

查询：

const projectsQuery = useQuery({
  queryKey: ['projects'],
  queryFn: projectApi.list,
})

手动刷新：

<button onClick={() => projectsQuery.refetch()}>
  刷新
</button>

新增后刷新列表：

const createProjectMutation = useMutation({
  mutationFn: projectApi.create,

  onSuccess: () => {
    queryClient.invalidateQueries({
      queryKey: ['projects'],
    })
  },
})

这套模型只有一份远程数据状态。

查询使用 useQuery
修改使用 useMutation
缓存刷新使用 invalidateQueries
页面参数使用 Router Search Params
本地状态使用 useState 或 Jotai

对于登录后的管理系统，这样的模型已经足够。

管理后台、AI 工具和工作流应用通常不会依赖搜索引擎索引内部页面。用户登录后会停留较长时间，主要操作发生在浏览器端。

SSR 在这些页面中的收益有限，但会增加 Hydration、服务端与客户端模块边界、Loader 生命周期和缓存同步等问题。

因此，我决定不让整个产品都进入 SSR 模型。

SSR 与 SPA 按路由区域拆分

最终的产品路由可以分成三个区域：

/                     官网首页
/pricing              定价页面
/blog/*                博客
/docs/*                文档
/tools/*               公开工具页面

/app/*                 登录后的产品
/app/projects/*        项目管理
/app/workflows/*       工作流
/app/analytics/*       数据分析

/api/*                 业务 API

公开区域使用 SSR 或 SSG，负责：

• SEO；
• 首屏内容；
• Open Graph；
• 博客和文档；
• 产品介绍；
• 公开工具页面。

/app 区域使用 SPA，负责：

• Dashboard；
• 工作流；
• 编辑器；
• AI 生成；
• 实时数据；
• 复杂表格；
• 多面板交互。

API 负责：

• 认证；
• 权限；
• 业务逻辑；
• 数据库访问；
• 文件上传；
• Webhook；
• Desktop 和其他客户端。

这样每个区域只维护一种主要数据模型。

最终的 Monorepo 结构

目前比较适合我的结构是：

repo/
├── apps/
│   ├── site/
│   ├── web/
│   ├── api/
│   ├── desktop/
│   └── worker/
│
├── packages/
│   ├── ui/
│   ├── contracts/
│   ├── db/
│   ├── shared/
│   └── config/
│
├── pnpm-workspace.yaml
├── package.json
└── tsconfig.json

各应用的职责如下：

apps/site
    官网、博客、文档和公开页面

apps/web
    登录后的 SPA 产品

apps/api
    统一业务 API

apps/desktop
    Tauri 客户端，需要时增加

apps/worker
    异步任务和 AI Job，需要时增加

共享包保持克制。

packages/ui 存放基础组件、样式 Token 和动画预设。

packages/contracts 存放真正需要跨客户端共享的 Zod Schema、错误结构和 API 类型。

packages/db 存放 Drizzle Schema、Migration 和数据库 Client。

业务代码默认留在具体 App 中，不会在项目开始阶段就提取到 packages/core。

API 使用 Hono

API 层选择 Hono。

它的路由写法比较轻：

const app = new Hono()

const projectRoutes = app
  .get('/projects', async (c) => {
    return c.json(await listProjects())
  })
  .post(
    '/projects',
    zValidator('json', createProjectSchema),
    async (c) => {
      const input = c.req.valid('json')
      const project = await createProject(input)

      return c.json(project, 201)
    },
  )

客户端可以使用 Hono RPC：

const client = hc<AppType>('/api')

在 TanStack Query 中调用：

export function useProjects() {
  return useQuery({
    queryKey: ['projects'],

    queryFn: async () => {
      const response =
        await client.projects.$get()

      if (!response.ok) {
        throw new Error(
          'Failed to load projects',
        )
      }

      return response.json()
    },
  })
}

完整调用链如下：

Component
    ↓
TanStack Query
    ↓
Hono RPC Client
    ↓
Hono Route
    ↓
Feature Function
    ↓
Drizzle

这套 API 可以同时提供给 Web、Desktop、浏览器扩展、Agent 和 Webhook。

相比框架内部专用的 Server Function，HTTP API 的复用范围更大。

后端按 Feature 组织

前后端拆分不意味着后端需要复制 Java 的分层方式。

不会采用这种全局目录：

controllers/
services/
repositories/
mappers/
dto/

API 仍然按 Feature 组织：

apps/api/src/features/project/
├── project.routes.ts
├── project.schema.ts
├── project.query.ts
├── project.command.ts
└── project.policy.ts

简单 Feature 只保留必要文件：

project.routes.ts
project.schema.ts

数据库实例可以直接导入：

import { db } from '@repo/db'

只有存在多个实现、复杂测试或运行时替换需求时，才使用参数注入或构造器注入。

不会为了保持架构形式，为每张表创建 Repository、Service 和 Mapper。

工具链保持激进，运行层保持稳定

项目工具链会使用相对新的方案：

Vite
Rolldown
Oxc
Oxlint
Oxfmt
Vite+
Vitest
Playwright

这些工具不会直接处理线上业务数据。即使某个版本出现兼容问题，也可以回退到对应的底层命令。

应用层使用：

React
TanStack Router
TanStack Query
TanStack Form
TanStack Table
Jotai
Tailwind CSS
shadcn/ui
Base UI
Motion
Lucide

其中 TanStack Form、Table 和 Jotai 都按需使用，不作为每个页面的固定依赖。

数据与安全层相对保守：

Node.js LTS
PostgreSQL
Drizzle ORM
Better Auth 稳定版本
Zod
正式数据库 Migration
Cookie Session

工具升级失败会影响开发效率，认证和数据库升级失败则可能影响用户和数据。两部分不应该使用相同的升级策略。

部署方式

源码上拆成多个 App，不代表生产环境必须维护大量服务。

可以使用同一个域名：

example.com/
    → Site

example.com/app/*
    → SPA

example.com/api/*
    → API

网关按路径分流：

/          → Site
/app/*     → Web
/api/*     → API

认证保持同源 Cookie。SPA 调用 /api 时不需要处理跨域 Token，Desktop 等外部客户端再使用单独的认证方式。

个人项目早期也可以让 Hono 同时提供 API 和 SPA 静态文件，保持一个 Docker 镜像和一个 Node 进程。

结论

这次技术选型没有确定一个统一管理所有能力的全栈框架，而是把不同类型的页面放回它们更适合的运行模型中。

公开内容使用 SSR 或 SSG
登录后的产品使用 SPA
通用业务能力使用 HTTP API

最终技术栈大致是：

Site
    Astro 或其他 SSR / SSG 方案

Web
    Vite
    React
    TanStack Router
    TanStack Query

API
    Hono
    Drizzle
    PostgreSQL
    Better Auth
    Zod

UI
    Tailwind CSS
    shadcn/ui
    Base UI
    Motion
    Lucide

Tooling
    Vite
    Rolldown
    Oxc
    Oxlint
    Oxfmt
    Vitest
    Playwright

这套结构保留了现代 TypeScript 工具链，也让业务后台继续使用熟悉的 SPA 数据流。

框架能力可以按项目需求增加。对于大多数偏工具型的产品，保持清楚的客户端、API 和数据边界，比在每个页面中同时组合 SSR、Loader、Server Function 和 Query 更容易维护。

Finished reading? Leave a comment

Resolver 是什么?

对于：

import Button from "@/components/Button";

JavaScript 引擎实际上只看到了 这些：

specifier = "@/components/Button"

接下来需要解决的问题是：

specifier
    ↓
真实模块

这个过程称为 Resolution。

Node.js ESM 规范中的入口算法：

ESM_RESOLVE(specifier, parentURL)

本质就是完成这个映射过程。

Node 默认支持哪些 specifier

Node 原生 Resolver 只支持四类：

import "./foo.js"
import "../foo.js"
import "/app/foo.js"

路径模块。

import react from "react"

包模块。

import db from "#db"

Package Imports。

import x from "file:///app/a.js"

URL 模块。

除此之外：

import x from "@/utils"

Node 无法解析。

直接进入：

Module Not Found

异常路径。

为什么 Alias 可以工作

假设存在：

import Button from "@/components/Button"

Webpack 配置：

resolve: {
  alias: {
    "@": "/project/src"
  }
}

Webpack 在执行真正解析前：

@/components/Button

先经过 Alias Resolver：

/project/src/components/Button

随后再进入正常模块解析。

因此 Alias 并不是一种新的模块类型。

而是：

旧 specifier
    ↓
新 specifier

的一次转换。

Vite Alias

Vite：

resolve: {
  alias: {
    "@": path.resolve(__dirname, "src")
  }
}

执行流程与 Webpack 完全一致。

对于：

import x from "@/utils/request"

Vite 首先执行：

@ -> /project/src

得到：

/project/src/utils/request

然后继续执行后续解析。

因此：

Webpack Alias
Vite Alias
Rspack Alias

本质是同一个东西。

区别只是 Resolver 实现不同。

TypeScript Paths 为什么经常失效

配置：

{
  "compilerOptions": {
    "paths": {
      "@/*": ["src/*"]
    }
  }
}

很多人会发现：

VSCode 正常
TypeScript 正常
Node 运行失败

原因是：

paths

不是运行时 Resolver。

TypeScript 只会在：

类型检查
IDE 跳转
编译阶段

使用 paths。

Node 运行时根本不会读取：

tsconfig.json

因此：

{
  "paths": {}
}

无法让 Node 识别：

import "@/utils"

必须额外配置：

Webpack Alias
Vite Alias
Rspack Alias
Node Loader

其中之一。

Node Loader 如何实现 Alias

Node 提供：

export async function resolve(
  specifier,
  context,
  nextResolve
)

允许接管解析过程。

例如：

export async function resolve(
  specifier,
  context,
  nextResolve
) {
  if (specifier.startsWith("@/")) {
    return {
      url: pathToFileURL(
        path.resolve(
          process.cwd(),
          "src",
          specifier.slice(2)
        )
      ).href,
      shortCircuit: true
    }
  }

  return nextResolve(specifier, context)
}

此时：

import x from "@/utils"

会变成：

file:///project/src/utils.js

然后进入正常加载流程。

Browser Import Map

浏览器没有：

node_modules

因此：

import React from "react"

无法工作。

Import Map 的作用：

<script type="importmap">
{
  "imports": {
    "react": "/vendor/react.js"
  }
}
</script>

执行：

import React from "react"

时。

浏览器先映射：

react
    ↓
/vendor/react.js

再继续加载。

Resolver 的本质

观察：

Webpack Alias
Vite Alias
Rspack Alias
TS Paths
Node Loader
Import Map

会发现它们都在做同一件事：

specifier
    ↓
mapping
    ↓
new specifier
    ↓
real URL

区别仅在于：

映射规则存放的位置不同

模块图的起点

对于：

import App from "./App"

编译器首先执行：

specifier
    ↓
resolver
    ↓
real module

得到：

App.tsx

然后继续递归：

App.tsx
    ↓
Button.tsx
    ↓
request.ts
    ↓
...

最终构建：

Module Graph

Tree Shaking、Code Splitting、HMR、Chunk 拆分全部建立在这个图之上。

因此 Resolver 是整个现代前端工具链真正的入口。

Finished reading? Leave a comment

Node.js ESM 解析算法（Resolution Algorithm）的职责只有两个：

1. 将 import 中的 specifier 解析为最终 URL
2. 判断该 URL 对应的模块格式

例如：

import react from "react";
import util from "./utils.js";
import config from "#config";

Node.js 最终需要得到：

react      -> file:///project/node_modules/react/index.js
./utils.js -> file:///project/src/utils.js
#config    -> file:///project/src/config/index.js

以及：

module
commonjs
json
wasm

等模块格式。

整个 ESM 规范本质上是在描述：

specifier
    ↓
resolved URL
    ↓
module format
    ↓
load
    ↓
execute

一、ESM_RESOLVE 总体流程

Node.js ESM 的入口算法：

ESM_RESOLVE(specifier, parentURL)

可以简化为：

判断 specifier 类型

URL
路径
#imports
裸包名

        ↓

解析得到 URL

        ↓

检查文件是否合法

        ↓

判断模块格式

        ↓

返回给 Loader

整个算法的核心目标：

specifier
      ↓
唯一 URL

而不是像 CommonJS 那样不断猜测。

二、specifier 分类

Node.js 将 specifier 分为四类。

1. URL Specifier

例如：

import x from "file:///app/src/a.js";

或者：

import x from "data:text/javascript,export default 1";

如果本身是合法 URL：

new URL(specifier)

成功。

那么直接返回。

2. Relative Specifier

例如：

import x from "./foo.js";
import y from "../bar.js";

Node.js 根据当前模块位置解析。

假设：

file:///app/src/main.js

执行：

import "./utils.js";

得到：

file:///app/src/utils.js

本质上就是：

new URL("./utils.js", parentURL)

3. Package Imports

例如：

import db from "#db";

或者：

import logger from "#utils/logger";

以：

#

开头。

会进入：

PACKAGE_IMPORTS_RESOLVE()

读取当前包：

{
  "imports": {
    "#db": "./src/db/index.js",
    "#utils/*": "./src/utils/*.js"
  }
}

例如：

import db from "#db";

最终得到：

./src/db/index.js

4. Bare Specifier

例如：

import react from "react";

import lodash from "lodash";

import axios from "axios";

既不是：

URL
路径
#import

就属于裸包名。

进入：

PACKAGE_RESOLVE()

开始查找 node_modules。

三、PACKAGE_RESOLVE

这是 Node.js 查找 npm 包的核心逻辑。

例如：

import react from "react";

当前文件：

/app/src/pages/home/index.js

Node.js 会不断向上查找：

/app/src/pages/home/node_modules/react
/app/src/pages/node_modules/react
/app/src/node_modules/react
/app/node_modules/react
/node_modules/react

直到找到。

等价于：

while(currentDirectory){
    查找 node_modules/packageName
    找不到继续向上
}

四、读取 package.json

找到包以后：

node_modules/react/package.json

Node.js 开始读取配置。

优先级如下：

exports
    ↓
main
    ↓
直接路径

五、exports 机制

现代 Node.js 包解析几乎完全依赖 exports。

例如：

{
  "exports": {
    ".": "./dist/index.js",
    "./jsx-runtime": "./dist/jsx-runtime.js"
  }
}

允许：

import React from "react";

对应：

.

得到：

./dist/index.js

允许：

import jsx from "react/jsx-runtime";

对应：

./jsx-runtime

得到：

./dist/jsx-runtime.js

但是：

import internal from "react/internal";

如果 exports 中不存在：

"./internal"

则报错：

Package Path Not Exported

六、exports 的本质

exports 可以理解为：

包对外暴露的公开 API

例如：

{
  "exports": {
    ".": "./dist/index.js",
    "./api": "./dist/api.js"
  }
}

允许：

import x from "my-lib";
import y from "my-lib/api";

禁止：

import z from "my-lib/dist/internal.js";

即使文件真实存在。

七、Conditional Exports

exports 不一定是字符串。

可以是对象。

例如：

{
  "exports": {
    ".": {
      "import": "./dist/index.mjs",
      "require": "./dist/index.cjs",
      "default": "./dist/index.js"
    }
  }
}

Node.js 会根据条件选择。

ESM：

import x from "lib";

匹配：

"import"

得到：

./dist/index.mjs

CommonJS：

require("lib");

匹配：

"require"

得到：

./dist/index.cjs

八、PACKAGE_SELF_RESOLVE

假设：

{
  "name": "my-lib",
  "exports": {
    ".": "./src/index.js",
    "./core": "./src/core.js"
  }
}

当前代码就在：

my-lib

内部。

那么：

import core from "my-lib/core";

不会去外部 node_modules 查找。

Node.js 会发现：

当前包名就是 my-lib

直接使用当前 package.json 的 exports。

这就是：

PACKAGE_SELF_RESOLVE

九、imports 机制

imports 和 exports 很像。

区别：

exports 给别人用
imports 给自己用

例如：

{
  "imports": {
    "#db": "./src/db/index.js",
    "#utils/*": "./src/utils/*.js"
  }
}

之后：

import db from "#db";

实际解析：

./src/db/index.js

再例如：

import stringUtil from "#utils/string.js";

得到：

./src/utils/string.js

十、Pattern Match

imports 和 exports 支持通配符。

例如：

{
  "exports": {
    "./features/*": "./src/features/*.js"
  }
}

执行：

import user from "pkg/features/user";

匹配：

*

得到：

user

最终：

./src/features/user.js

十一、PACKAGE_TARGET_RESOLVE

这是 exports/imports 真正执行映射的地方。

支持四种类型。

String

{
  "exports": {
    ".": "./dist/index.js"
  }
}

直接解析。

Object

{
  "exports": {
    ".": {
      "node": "./node.js",
      "browser": "./browser.js",
      "default": "./index.js"
    }
  }
}

根据 conditions 选择。

Array

{
  "exports": {
    ".": [
      "./native.js",
      "./fallback.js"
    ]
  }
}

前一个失败。

继续尝试下一个。

null

{
  "exports": {
    "./internal/*": null
  }
}

明确禁止导出。

十二、ESM_FILE_FORMAT

URL 定位完成后。

Node.js 需要判断：

这个文件应该按什么格式加载？

.mjs

module

.cjs

commonjs

.json

json

.wasm

wasm

.node

addon

原生扩展模块。

十三、type 字段的作用

对于：

.js

文件。

Node.js 会查找最近的 package.json。

例如：

{
  "type": "module"
}

那么：

app.js

被解释为：

ESM

如果：

{
  "type": "commonjs"
}

则：

app.js

被解释为：

CommonJS

因此：

.mjs

永远 ESM。

.cjs

永远 CommonJS。

.js

取决于 type。

十四、为什么 ESM 不支持目录导入

CommonJS：

require("./foo");

Node.js 会尝试：

foo.js
foo.json
foo.node
foo/index.js
foo/index.json

ESM：

import "./foo";

不会猜。

如果：

foo

是目录。

直接报错：

Unsupported Directory Import

正确写法：

import "./foo/index.js";

或者：

import "./foo.js";

十五、LOOKUP_PACKAGE_SCOPE

Node.js 如何找到最近的 package.json？

算法：

当前目录
      ↓
父目录
      ↓
继续向上
      ↓
直到根目录

例如：

/app/src/pages/home/index.js

查找：

/app/src/pages/home/package.json
/app/src/pages/package.json
/app/src/package.json
/app/package.json

找到第一个就停止。

十六、自定义 ESM Resolver

Node.js 默认解析：

import x from "./a.js";
import y from "react";

如果想支持：

import x from "@/utils";

怎么办？

答案：

Loader Hook

例如：

import { pathToFileURL } from "node:url";
import path from "node:path";

export async function resolve(
  specifier,
  context,
  nextResolve
) {
  if (specifier.startsWith("@/")) {
    return {
      url: pathToFileURL(
        path.resolve(
          process.cwd(),
          "src",
          specifier.slice(2)
        )
      ).href,
      shortCircuit: true
    };
  }

  return nextResolve(specifier, context);
}

运行：

node --loader ./loader.mjs app.js

之后：

import util from "@/utils.js";

就会自动映射：

src/utils.js

十七、完整解析链路

Node.js ESM 解析可以总结为：

import specifier
        ↓
ESM_RESOLVE
        ↓
判断类型

URL
路径
#imports
裸包名

        ↓

PACKAGE_RESOLVE

        ↓

exports
imports
main

        ↓

得到最终 URL

        ↓

ESM_FILE_FORMAT

        ↓

module
commonjs
json
wasm

        ↓

Loader

        ↓

Execute

总结

Node.js ESM 的核心思想不是“寻找文件”。

而是：

specifier
      ↓
确定 URL
      ↓
确定模块格式
      ↓
加载执行

整个 exports、imports、type、conditional exports、loader 机制，本质上都是围绕这一目标构建的。

ESM 解析模型相比 CommonJS 更严格、更静态、更接近浏览器，也更适合现代工具链（Vite、Webpack、Rspack、Rollup、Turbopack）进行分析和优化。

Finished reading? Leave a comment

最近在看 C++、Rust、Go 的编译过程。

刚开始最容易被一堆名词卡住：

• GCC
• Clang
• LLVM
• AST
• IR
• SSA
• MIR
• GIMPLE
• RTL
• Linker
• Loader

单独看每个词，好像都能理解一点。但把它们放到一张图里，就很容易乱。

后来我发现，问题不在于名词太多，而在于没有从一段真实程序出发。

编译器不是简单地“把源码翻译成汇编”。更准确地说，它是在不断降低程序的抽象层级：

人类写的源码
    ↓
结构化表示
    ↓
语义明确的表示
    ↓
适合优化的表示
    ↓
接近机器的表示
    ↓
机器可以执行的二进制

每一层中间表示，都是为了让某一类问题变得更容易处理。

下面用一段很小的 C++ 程序，把主流编译链路串起来。

extern "C" int printf(const char*, ...);

#define INC(x) ((x) + 1)

int add(int a, int b) {
    return a + b;
}

int main() {
    int x = INC(add(1, 2));
    printf("%d\n", x);
    return 0;
}

这段代码故意保留了几个点：

宏：INC
函数调用：add
外部符号：printf
C++ 符号：add 会发生 name mangling
链接阶段：printf 需要从 C 标准库解析
优化空间：add(1, 2) 和 INC 可以被优化成常量

一个小程序，基本够覆盖主流编译流程。

1. 源码不是编译器真正想要的东西

程序员看到的是：

int x = INC(add(1, 2));

人很容易理解它大概等价于：

int x = ((add(1, 2)) + 1);

但编译器不能一开始就这么理解。

源码只是字符流：

i n t 空格 x 空格 = 空格 I N C ...

编译器必须先把字符处理成更稳定的结构。

这也是为什么现代编译流程不会从源码直接跳到汇编。源码适合人读，不适合机器分析。

2. 预处理：C/C++ 最早的一层文本系统

C/C++ 的第一步通常是预处理。

clang++ -E main.cpp -o main.ii

预处理器主要处理：

#include
#define
#ifdef
#pragma

在这段程序里，最明显的是：

#define INC(x) ((x) + 1)

预处理后，核心代码会变成类似这样：

int main() {
    int x = ((add(1, 2)) + 1);
    printf("%d\n", x);
    return 0;
}

这一步有个很重要的认知：

预处理不是语义分析。

它不理解类型。

它不知道 add 是不是函数。

它也不知道 INC(add(1, 2)) 是否合理。

它只是按照规则展开文本。

这也是 C/C++ 宏容易制造问题的原因。宏不是函数，它不会遵守函数那套类型检查和作用域规则。

例如：

#define SQUARE(x) x * x

如果写：

SQUARE(1 + 2)

会被展开成：

1 + 2 * 1 + 2

而不是：

(1 + 2) * (1 + 2)

很多 C/C++ 的奇怪问题，其实还没进入真正编译阶段，只是在预处理阶段就已经埋雷了。

3. 词法分析：把字符切成 Token

预处理后，编译器开始做词法分析。

源码片段：

int x = ((add(1, 2)) + 1);

会被切成类似：

keyword      int
identifier   x
operator     =
punctuator   (
punctuator   (
identifier   add
punctuator   (
literal      1
punctuator   ,
literal      2
punctuator   )
punctuator   )
operator     +
literal      1
punctuator   )
punctuator   ;

这一步只负责“切词”。

它知道 int 是关键字。

知道 x 是标识符。

知道 1 是数字字面量。

但它还不知道：

x 是局部变量
add 是函数
printf 是外部函数
1 能不能传给 add

这些都不是词法分析负责的。

可以用 Clang 看 Token：

clang++ -Xclang -dump-tokens -fsyntax-only main.cpp

如果编译错误里出现非法字符、字符串没有闭合、数字字面量格式错误，通常就停在这一层附近。

4. 语法分析：从 Token 变成 AST

Token 还是线性的。

编译器需要知道程序结构。

例如：

int x = ((add(1, 2)) + 1);

语法分析后会变成一棵树，简化后大概是：

VarDecl x : int
    └── BinaryOperator +
        ├── CallExpr add
        │   ├── IntegerLiteral 1
        │   └── IntegerLiteral 2
        └── IntegerLiteral 1

这就是 AST，抽象语法树。

AST 的作用不是为了显得高级，而是为了把源码结构稳定下来。

源码是文本。

AST 是结构。

这一步之后，编译器终于知道：

这是一个变量声明
变量名是 x
初始化表达式是一个加法
加法左边是函数调用
加法右边是整数 1

但 AST 仍然不能证明程序正确。

例如：

int x = foo(1, 2);

即使 foo 根本不存在，也可以先构建 AST。

语法上没问题。

语义上才有问题。

可以用 Clang 看 AST：

clang++ -Xclang -ast-dump -fsyntax-only main.cpp

真实 C++ AST 会非常长。模板、重载、隐式转换、构造函数、析构函数都会出现在里面。

这也是 C++ 前端复杂度很高的原因。不是因为 Token 难切，也不是因为语法树难画，而是因为语义太复杂。

5. 语义分析：编译器真正开始理解程序

语义分析会处理这些问题：

add 是否存在
add 参数数量是否正确
add 参数类型是否匹配
printf 是否声明过
int x 的初始化是否合法
函数返回值是否符合声明

对这段代码来说：

int x = INC(add(1, 2));

预处理后是：

int x = ((add(1, 2)) + 1);

语义分析会确认：

add 的类型是 int(int, int)
add(1, 2) 返回 int
返回值可以和 1 做加法
结果可以赋给 int x

如果写成：

int x = add("hello", 2);

语法仍然成立。

AST 也能构建。

但语义分析会报错，因为参数类型不匹配。

很多开发者平时说“编译错误”，其实可以再细分：

语法错误：代码结构不合法
语义错误：结构合法，但意思不合法
链接错误：单个文件能编译，但最终符号找不到

这三个错误发生在完全不同的阶段。

Rust 的 Borrow Checker 也属于这个大范围。

例如：

let r;

{
    let x = 1;
    r = &x;
}

println!("{}", r);

这不是语法错误。

它的结构完全合法。

真正的问题是语义层面的：x 已经离开作用域，r 不能再引用它。

所以 Rust 的所有权、借用、生命周期，不应该理解成语法特性，而应该理解成更强的语义分析。

这也是 Rust 编译器比 Go 编译器复杂很多的原因之一。

6. AST 不适合优化，所以需要 IR

很多人第一次学编译流程，会以为：

源码
  ↓
AST
  ↓
汇编

这个模型太粗糙。

现代编译器不会长期停留在 AST 上做优化。

原因很简单：

AST 太接近源码。

例如：

int x = INC(add(1, 2));

AST 会保留很多源码结构。

但优化器真正关心的是：

这个值从哪里来
这个值被谁使用
这个计算有没有副作用
这个分支是否可达
这个变量能不能放进寄存器
这个函数能不能内联

AST 对这些问题并不友好。

所以编译器会把 AST 降低到 IR。

IR 是 Intermediate Representation，中间表示。

比如这段：

int x = INC(add(1, 2));

可以理解为降低成类似三地址码：

t1 = call add, 1, 2
t2 = t1 + 1
x = t2
call printf, "%d\n", x
return 0

这就比 AST 更适合优化。

表达式树被拆成了简单指令。

数据依赖也更清楚。

LLVM IR 会更像这样，简化后：

define i32 @_Z3addii(i32 %a, i32 %b) {
entry:
  %sum = add nsw i32 %a, %b
  ret i32 %sum
}

define i32 @main() {
entry:
  %call = call i32 @_Z3addii(i32 1, i32 2)
  %add = add nsw i32 %call, 1
  call i32 (ptr, ...) @printf(ptr @.str, i32 %add)
  ret i32 0
}

这里有几个点值得注意。

add 在 C++ 里可能会被编译成：

_Z3addii

这是 C++ name mangling。

因为 C++ 支持函数重载，链接器不能只看到一个名字 add。

例如：

int add(int, int);
double add(double, double);

这两个函数源码里都叫 add，但链接时必须区分。

而 printf 因为声明成：

extern "C" int printf(const char*, ...);

所以不会被 C++ 改名，仍然叫：

printf

这就是 extern "C" 的实际意义之一：控制符号名，方便和 C ABI 对接。

7. 优化：编译器开始改写程序

如果不开优化，编译器会比较忠实地保留程序结构。

如果打开优化：

clang++ -O2 -S -emit-llvm main.cpp -o main.ll

这段代码很可能被优化成类似：

define i32 @main() {
entry:
  call i32 (ptr, ...) @printf(ptr @.str, i32 4)
  ret i32 0
}

add(1, 2) 没了。

INC 展开后的 + 1 也没了。

x 也没了。

最后只剩：

printf("%d\n", 4)

这不是编译器乱改代码。

这是它证明了这些改写不会改变可观察行为。

这里发生了几类典型优化：

函数内联：add(1, 2) 被展开
常量折叠：1 + 2 + 1 变成 4
死代码删除：中间变量 x 不再需要

如果看过 Java JIT、Go SSA、Rust LLVM 优化，会发现这些优化名字经常重复出现。

原因很简单：程序优化的基本问题是相通的。

8. SSA：现代优化器为什么喜欢“变量只赋值一次”

SSA 是理解现代编译器优化的关键。

SSA，全称 Static Single Assignment。

意思是每个变量在静态程序里只赋值一次。

看这个例子：

int f(bool cond) {
    int x = 1;

    if (cond) {
        x = 2;
    }

    return x;
}

普通代码里，x 被赋值两次。

控制流一复杂，优化器就很难判断某个位置的 x 到底来自哪里。

SSA 会把它变成类似：

x1 = 1

if cond goto then else merge

then:
  x2 = 2
  goto merge

merge:
  x3 = phi(x1, x2)
  return x3

这里的：

phi(x1, x2)

表示：

如果从未进入 if 的路径来，x3 = x1
如果从 then 分支来，x3 = x2

SSA 的价值在于，它把“变量会变化”这件事变成了显式的数据流关系。

这对优化非常重要。

例如：

常量传播
死代码删除
公共子表达式消除
循环不变代码外提
值编号
逃逸分析

都会受益于 SSA。

LLVM IR 是 SSA 形式。

Go 编译器内部使用 SSA。

HotSpot C2 也使用接近 SSA 的 Sea of Nodes IR。

很多数据库优化器虽然不叫 SSA，但也会维护类似的数据依赖关系。

这不是某个编译器的小技巧，而是现代优化系统的基础方法。

9. 后端：从平台无关 IR 到机器相关 IR

LLVM IR 仍然是平台无关的。

比如：

%sum = add i32 %a, %b

这句话没有指定：

x86 用哪条指令
ARM 用哪条指令
结果放哪个寄存器
参数从哪里来
调用约定是什么

这些都是后端的问题。

后端要处理：

指令选择
寄存器分配
指令调度
调用约定
栈帧布局
目标平台 ABI

同一个加法，在 x86-64 下可能是：

mov eax, edi
add eax, esi
ret

在 ARM64 下可能是：

add w0, w0, w1
ret

IR 相同，目标机器不同，最终指令就不同。

这也是 LLVM 的价值所在。

语言实现者只要生成 LLVM IR，就可以复用 LLVM 的后端能力。

否则每写一门语言，都要自己支持：

x86-64
ARM64
RISC-V
Windows ABI
Linux ABI
macOS ABI
寄存器分配
指令选择
调试信息
异常处理

这几乎不现实

10. 目标文件：机器码还不是最终程序

后端生成汇编后，汇编器会生成目标文件：

clang++ -c main.cpp -o main.o

main.o 里面有机器码，但它还不是完整程序。

可以用：

nm main.o

看到符号。

可能会看到类似：

0000000000000000 T _Z3addii
0000000000000010 T main
                 U printf

含义大概是：

_Z3addii 已定义
main 已定义
printf 未定义

U printf 不是错误。

它只是说：当前目标文件里没有 printf 的实现，链接阶段需要去别的地方找。

这就是很多人第一次遇到 undefined reference 时容易误解的地方。

它不是语法错误。

也不是类型错误。

它是链接阶段的符号解析失败。

11. 链接：把分散的二进制拼成一个程序

链接器做的事情可以粗略理解为：

main.o
  +
libc
  +
启动代码
  +
运行时库
  ↓
可执行文件

它要解决：

符号解析
地址分配
重定位
静态库选择
动态库记录
入口点设置

如果写 C++，还会涉及：

name mangling
ODR
模板实例化
静态初始化
异常表
RTTI
虚表

比如：

undefined reference to `foo'

说明链接器找不到 foo 的实现。

multiple definition of `foo'

说明多个目标文件都提供了同一个强符号。

undefined reference to `_Z3addii'

说明 C++ 符号名对不上，可能是声明和定义不一致，也可能是 C/C++ ABI 混用出了问题。

链接器是独立于编译器前端的另一个大系统。

很多大型 C++ 工程的构建问题，其实不是编译器问题，而是链接器问题。

12. 加载：程序运行前，操作系统还要接手

执行：

./a.out

也不是 CPU 直接从 main 开始跑。

Linux 下大致会经历：

内核读取 ELF
映射程序段到虚拟内存
加载动态链接器
加载共享库
处理重定位
初始化运行时
调用 main

程序的内存布局大致包括：

.text     代码段
.rodata   只读数据
.data     已初始化全局变量
.bss      未初始化全局变量
heap      堆
stack     栈

所以严格说，完整链路不是：

源码 → 可执行文件

而是：

源码 → 目标文件 → 可执行文件 → 进程

编译器解决“怎么生成程序”。

链接器解决“怎么合成程序”。

加载器解决“怎么把程序变成进程”。

13. Clang、LLVM、GCC 应该怎么放在一张图里

现在再看这些名字，就清楚很多。

Clang + LLVM 是这样：

C++ Source
    ↓
Clang Frontend
    ↓
Clang AST
    ↓
LLVM IR
    ↓
LLVM Optimizer
    ↓
LLVM Backend
    ↓
Object File
    ↓
Linker
    ↓
Executable

GCC 是另一条链路：

C++ Source
    ↓
GCC C++ Frontend
    ↓
GENERIC
    ↓
GIMPLE
    ↓
GIMPLE SSA
    ↓
RTL
    ↓
GCC Backend
    ↓
Object File
    ↓
Linker
    ↓
Executable

这两条链路解决的是同一类问题，但内部表示不同。

Clang 不是 LLVM 的别名。

LLVM 也不是 Clang 的别名。

更准确地说：

Clang 是 C/C++/Objective-C 前端。
LLVM 是中端和后端基础设施。
GCC 是另一套完整编译器系统。

对应关系可以这样记：

Clang 负责读懂 C++。
LLVM 负责优化和生成机器码。
GCC 自己既有前端，也有中端和后端。

14. Rust 为什么有 HIR、MIR，又为什么用 LLVM

Rust 的流程大致是：

Rust Source
    ↓
AST
    ↓
HIR
    ↓
THIR
    ↓
MIR
    ↓
Borrow Check
    ↓
LLVM IR
    ↓
LLVM Backend
    ↓
Machine Code

Rust 这几层不是为了显得复杂。

每层都有明确责任。

AST 接近源码。

HIR 会把一些语法糖和表层结构降下来，让程序形态更稳定。

THIR 更适合类型检查后的表达式分析。

MIR 是 Rust 很关键的一层，适合表达控制流、move、borrow、drop、生命周期等语义。

LLVM IR 则负责进入通用优化和机器码生成阶段。

这里要注意一个区分：

MIR 是 Rust 语义层的 IR。
LLVM IR 是机器代码生成层的 IR。

Borrow Checker 不能直接依赖 LLVM IR。

因为 LLVM IR 已经太低级，Rust 的 ownership、borrow、drop 语义在那一层已经不适合作为主要分析对象。

也不能直接依赖 AST。

因为 AST 太接近语法表面，语法糖太多，不适合做严格的数据流和控制流分析。

所以 Rust 需要 MIR。

这就是中间表示真正的价值：不是多一层抽象，而是为特定分析提供合适的程序形态。

15. Go 为什么看起来简单很多

Go 的编译流程大致是：

Go Source
    ↓
Parser
    ↓
AST
    ↓
Type Check
    ↓
SSA
    ↓
Go Backend
    ↓
Machine Code

Go 默认不走 LLVM。

它有自己的 SSA 和后端。

这和 Go 的设计目标有关。

Go 语言本身刻意保持简单：

没有模板元编程
没有复杂宏系统
没有 Rust 那种 ownership 检查
没有 C++ 那种重载和隐式规则

所以 Go 编译器可以更直接。

这也是 Go 编译速度快的一个重要原因。

当然，“简单”不是说 Go 编译器没有技术含量。

Go 的逃逸分析、内联、SSA 优化、栈增长、GC 相关元数据生成，都有不少工程细节。

但和 C++、Rust 相比，Go 前端语义复杂度确实低很多。

16. 为什么现代编译器总在发明新的 IR

到这里，基本可以回答最初的问题。

为什么 GCC 有 GIMPLE 和 RTL？

为什么 LLVM 有 LLVM IR、SelectionDAG、Machine IR？

为什么 Rust 有 HIR、THIR、MIR？

为什么 Go 有 SSA？

因为没有一种表示适合所有阶段。

AST 适合表示源码结构。

HIR 适合消除表层语法。

MIR 适合表达语言语义和控制流。

LLVM IR 适合做平台无关优化。

Machine IR 适合做寄存器分配和指令调度。

RTL 适合 GCC 后端描述接近机器的操作。

同一段程序，在不同阶段要被看成不同的东西。

对人来说，它是业务逻辑。

对前端来说，它是语法树。

对类型系统来说，它是约束集合。

对优化器来说，它是数据流图。

对后端来说，它是指令选择和寄存器分配问题。

对链接器来说，它是符号和重定位记录。

对加载器来说，它是 ELF 段和动态库依赖。

编译器的复杂性，正是来自这些视角之间的切换。

17. 真正需要记住的主流流程

如果只保留主流路径，不陷入全部细节，可以记成这条线：

源码
  ↓
预处理
  ↓
Token
  ↓
AST
  ↓
语义分析
  ↓
IR
  ↓
SSA
  ↓
优化
  ↓
目标相关 IR
  ↓
汇编 / 目标文件
  ↓
链接
  ↓
可执行文件
  ↓
加载执行

对应到几个主流编译器：

Clang/LLVM:
C++ → Clang AST → LLVM IR → LLVM Backend → Object

GCC:
C++ → GENERIC → GIMPLE SSA → RTL → Object

Rust:
Rust → AST/HIR/THIR → MIR → LLVM IR → Object

Go:
Go → AST → Type Check → SSA → Go Backend → Object

这张图比单独背 AST、IR、SSA 更有用。

因为它告诉你每个系统在同一条工业流水线里的位置。

18. 学这套东西对工程有什么用

这不是纯理论。

遇到宏问题，你知道去看预处理结果：

clang++ -E main.cpp

遇到语法和语义问题，你知道它发生在前端：

clang++ -Xclang -ast-dump -fsyntax-only main.cpp

想看优化前后的差异，你知道去看 LLVM IR：

clang++ -O0 -S -emit-llvm main.cpp -o main_O0.ll
clang++ -O2 -S -emit-llvm main.cpp -o main_O2.ll

遇到符号找不到，你知道看目标文件：

nm main.o

想看 ELF 结构：

readelf -a a.out

想看汇编：

objdump -d a.out

这些工具不是为了炫技。

它们对应的是编译流程中的不同阶段。

能定位阶段，问题就已经解决了一半。

19. 编译器真正有价值的地方

编译器最有价值的地方，不是几个术语，而是一种看复杂系统的方法。

一个复杂输入，不会被直接执行。

它会先变成某种中间表示。

然后被分析、约束、优化、降低，最后才进入执行层。

这个模式不只存在于编译器里。

数据库会把 SQL 变成逻辑计划和物理计划。

JVM 会把字节码变成内部 IR，再交给 JIT 优化。

React 会把 UI 更新组织成 Fiber 结构。

Kubernetes Scheduler 会把调度请求变成资源约束和评分模型。

这些系统看起来不一样，但底层思路很接近：

输入不是直接执行的。
先建立表示。
再基于表示做分析和优化。
最后执行。

编译器只是这个思想最经典、最完整的版本。

如果能把 C++、Rust、Go、GCC、LLVM 这条线看懂，再回头看 JVM、数据库、前端框架、调度系统，很多设计就不再是孤立的名词了。

Finished reading? Leave a comment

Spring 6 循环依赖与早期代理：三级缓存的真实边界

基线：Spring Framework 6、Spring Boot 3。本文解释一个具体代理不一致案例，不把结论推广为所有 Bean 的普遍行为。

1. 问题模型

典型循环依赖：

A -> B -> Repository -> A

如果依赖注入发生在 Bean 完整初始化之前，Spring 可能通过三级缓存提前暴露引用。后续 Bean 初始化还可能经过 BeanPostProcessor 创建代理，于是出现：

Early Reference != Final Bean

2. 三级缓存能做什么

三级缓存中的 ObjectFactory 可以提供早期引用。实现 SmartInstantiationAwareBeanPostProcessor 的后处理器有机会通过 getEarlyBeanReference 参与早期代理。

AbstractAutoProxyCreator 会记录 early proxy reference，避免同一个自动代理在初始化后重复创建。但不是每一个 BeanPostProcessor 都参与 early reference。

普通后处理器若只在 postProcessAfterInitialization 阶段包装 Bean，就可能造成早期引用与最终对象身份不一致。具体是否发生，取决于 Spring 版本、后处理器顺序和代理类型。

3. Spring Boot 3 的处理建议

Spring Boot 2.6 起循环引用默认更严格。Boot 3 项目应优先拆除循环依赖，不要用 spring.main.allow-circular-references=true 作为默认修复。

推荐顺序：

1. 拆分服务和 Repository 的职责；
2. 使用事件或接口反转依赖方向；
3. 对确实需要延迟创建的依赖使用 @Lazy，并评估生命周期；
4. 检查事务、缓存、异步、异常翻译和自定义后处理器是否创建代理。

4. 排障方法

记录实际 Spring Framework 版本；查看 Bean 的代理类型和 Advisor；分别跟踪 getEarlyBeanReference 与 postProcessAfterInitialization；确认是否存在多个后处理器重复包装；检查 allowCircularReferences 和 BeanDefinition 顺序。

三级缓存不是“所有循环依赖都能解决”的保证。它只是容器在特定生命周期阶段提供早期引用的机制，最终仍需要一个清晰且可维护的依赖图。

Finished reading? Leave a comment

很多人学习 Kubernetes 网络时，一上来就接触：

• Pod
• Service
• Ingress
• CNI
• Flannel
• Calico

结果越学越乱。

真正的问题在于：

Kubernetes 网络并不是一个独立体系，而是建立在 Linux 网络之上的一层抽象。

如果不了解 Linux 网络，那么 Pod、Service、VXLAN 这些概念都会变成黑盒。

一、网络世界只有三个核心概念

整个网络可以抽象成三件事：

设备
地址
转发

对应：

设备：
网卡
交换机
路由器

地址：
MAC
IP

转发：
交换
路由
NAT

二、MAC 与 IP

MAC 地址

MAC 是二层地址。

00:11:22:33:44:55

作用是在同一个局域网内定位设备。

IP 地址

IP 是三层地址。

192.168.1.10
10.244.1.2
8.8.8.8

作用是跨网络定位设备。

三、交换机、ARP、路由器

交换机工作在二层，只看 MAC 地址，不看 IP、TCP、HTTP。

ARP 负责：

IP -> MAC

路由器工作在三层：

查看目标 IP
↓
查路由表
↓
决定下一跳

路由表示例：

ip route

192.168.1.0/24 dev eth0
default via 192.168.1.1

含义：

同网段直接发送
其他流量交给默认网关

四、NAT

私网地址不能直接在公网路由：

192.168.x.x
172.16.x.x
10.x.x.x

所以路由器会做 SNAT：

SRC 192.168.1.10
↓
SRC 公网 IP

并通过 conntrack 记录连接映射，用于回包恢复。

五、Linux Network Namespace

Namespace 是 Linux 的隔离机制。

Network Namespace 隔离的是一整套网络栈：

网卡
IP
路由表
ARP 表
iptables
端口空间

所以容器不是虚拟机，而是：

普通 Linux 进程
+
Namespace 隔离
+
Cgroups 限制
+
RootFS 文件系统

六、veth Pair

Namespace 之间需要连接，Linux 提供了 veth pair。

vethA <====> vethB

它像一根虚拟网线：

从 vethA 发出的包，会从 vethB 出来
从 vethB 发出的包，会从 vethA 出来

七、Linux Bridge

Bridge 是软件交换机。

ContainerA
   |
 Bridge
   |
ContainerB

它和物理交换机一样：

学习 MAC
查 MAC 表
转发数据帧

八、Docker 网络

Docker 默认网络结构：

Container
  eth0
    │
veth
    │
docker0
    │
Host

其中 docker0 是 Linux Bridge，同时被 Docker 配置了 IP：

docker0 = 172.17.0.1

所以 docker0 既是交换机，也是容器默认网关。

Docker 自己维护 IPAM：

172.17.0.0/16

容器 IP 通常由 Docker 分配：

172.17.0.2
172.17.0.3
172.17.0.4

九、Pod 是什么

Pod 不是容器。

一个 Pod 里可以有多个容器：

Pod
├── app
└── sidecar

真正持有网络命名空间的是 pause container。

pause container
└── Network Namespace

app
└── 加入 pause 的 Network Namespace

sidecar
└── 加入 pause 的 Network Namespace

所以同一个 Pod 内多个容器共享：

IP
localhost
端口空间

十、Kubernetes 单节点网络

很多 CNI 会在 Node 上创建类似 docker0 的网桥，比如：

cni0

结构：

PodA
  |
veth
  |
cni0
  |
veth
  |
PodB

同节点 Pod 通信时：

PodA ARP 查询 PodB MAC
↓
cni0 广播
↓
PodB 回复
↓
cni0 根据 MAC 表转发

这个过程本质是二层交换。

十一、CNI 是什么

Kubernetes 本身不直接实现网络。

它通过 CNI 插件处理 Pod 网络。

常见 CNI：

Flannel
Calico
Cilium

CNI 负责：

创建 veth
配置 IP
配置路由
接入 Bridge 或其他数据平面
维护跨节点通信

Pod IP 通常由 CNI 的 IPAM 模块分配，不是 Kubernetes 或 Linux 自动分配。

十二、跨节点 Pod 通信

假设：

Node1
PodA = 10.244.1.2

Node2
PodB = 10.244.2.2

PodA 访问 PodB：

10.244.1.2 -> 10.244.2.2

问题是：

Node1 怎么知道 10.244.2.0/24 在 Node2？

这就是 CNI 要解决的问题。

十三、VXLAN

VXLAN 是：

L2 Overlay over L3

意思是：

把二层网络封装到三层 IP 网络里面

原始 Pod 包：

SRC 10.244.1.2
DST 10.244.2.2

经过 VXLAN 封装：

Outer IP:
SRC Node1IP
DST Node2IP

UDP

VXLAN Header

Inner IP:
SRC 10.244.1.2
DST 10.244.2.2

包结构：

Outer Ethernet
Outer IP
UDP
VXLAN
Inner Ethernet
Inner IP
TCP
HTTP

中间物理网络只看到：

Node1IP -> Node2IP

Node2 收到后解 VXLAN，再把原始 Pod 包送给 PodB。

十四、flannel.1 是什么

flannel.1 不是进程。

它是 Linux VXLAN 网络设备。

类似：

eth0
docker0
cni0
vethxxx

路由表里：

10.244.2.0/24 dev flannel.1

意思是：

去 10.244.2.0/24 的流量
交给 flannel.1 这个 VXLAN 设备处理

然后 Linux 内核负责 VXLAN 封装。

flanneld 才是进程，它负责：

创建 flannel.1
写路由表
维护 Node 和 PodCIDR 的映射

十五、Service 的本质

Service 提供稳定访问入口。

例如：

Service IP = 10.96.0.10

但这个 IP 通常不是某张真实网卡上的 IP。

Service 本质是：

虚拟 IP
+
iptables / IPVS 转发规则

十六、kube-proxy

kube-proxy 监听：

Service
Endpoint / EndpointSlice

然后生成转发规则。

例如：

10.96.0.10:8080
↓ DNAT
10.244.1.2:8080

所以访问 Service 时，真实过程是：

访问 Service IP
↓
iptables / IPVS 命中规则
↓
DNAT 到某个后端 Pod IP
↓
通过 CNI 网络转发到目标 Pod

十七、CoreDNS

Pod 内访问服务名：

curl user-service

解析过程：

user-service
↓
CoreDNS
↓
Service ClusterIP
↓
kube-proxy
↓
Pod IP

十八、Ingress

Ingress 是规则，不是真正的网关进程。

真正处理流量的是 Ingress Controller，比如：

Nginx Ingress Controller
Traefik
APISIX
Kong

外部请求链路：

Browser
↓
LoadBalancer / NodePort
↓
Ingress Controller
↓
Service
↓
Pod

Ingress Controller 通常是七层反向代理，会解析：

Host
Path
TLS
HTTP Header

十九、完整链路总结

Linux 网络基础：

MAC
↓
ARP
↓
交换机
↓
路由器
↓
路由表
↓
NAT

容器网络基础：

Namespace
↓
veth
↓
Bridge
↓
IPAM
↓
Docker 网络

Kubernetes 网络：

Pod
↓
CNI
↓
PodCIDR
↓
cni0 / route / eBPF
↓
VXLAN / BGP
↓
Service
↓
CoreDNS
↓
Ingress

二十、最终结论

Kubernetes 网络不是凭空出现的新体系。

它本质是：

Linux 网络能力
+
CNI 自动化
+
Kubernetes 声明式编排

更具体地说：

Kubernetes 网络
=
Namespace
+
veth
+
Bridge
+
Route
+
NAT
+
iptables / IPVS
+
VXLAN / BGP / eBPF
+
CNI

理解 Kubernetes 网络，正确路径不是先背 Pod、Service、Ingress，而是先理解：

Linux 如何转发一个包
容器如何拥有自己的网络栈
Pod 如何通过 CNI 接入网络
跨节点 Pod 如何通过 VXLAN 或路由互通
Service 如何通过 DNAT 找到后端 Pod
Ingress 如何作为七层入口转发流量

Finished reading? Leave a comment

一、完整脚本，复制到bash终端运行

#!/usr/bin/env bash
set -e

echo "==> Setup zsh + Oh My Zsh + powerlevel10k"

# 1. zsh
if ! command -v zsh >/dev/null 2>&1; then
  echo "Install zsh..."
  brew install zsh
fi

# 2. oh-my-zsh
if [ ! -d "$HOME/.oh-my-zsh" ]; then
  echo "Install oh-my-zsh..."
  sh -c "$(curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)" "" --unattended
fi

ZSH_CUSTOM=${ZSH_CUSTOM:-$HOME/.oh-my-zsh/custom}

# 3. plugins
install_plugin () {
  if [ ! -d "$ZSH_CUSTOM/plugins/$1" ]; then
    git clone --depth=1 "$2" "$ZSH_CUSTOM/plugins/$1"
  fi
}

install_plugin zsh-autosuggestions https://github.com/zsh-users/zsh-autosuggestions
install_plugin zsh-syntax-highlighting https://github.com/zsh-users/zsh-syntax-highlighting

# 4. theme
if [ ! -d "$ZSH_CUSTOM/themes/powerlevel10k" ]; then
  git clone --depth=1 https://github.com/romkatv/powerlevel10k \
    "$ZSH_CUSTOM/themes/powerlevel10k"
fi

# 5. tools
if command -v brew >/dev/null 2>&1; then
  brew install fzf zoxide >/dev/null 2>&1 || true
  $(brew --prefix)/opt/fzf/install --all >/dev/null 2>&1 || true
fi

# 6. config
cat > ~/.zshrc <<'EOF'
export ZSH="$HOME/.oh-my-zsh"

ZSH_THEME="powerlevel10k/powerlevel10k"

plugins=(
  git
  zsh-autosuggestions
  zsh-syntax-highlighting
)

source $ZSH/oh-my-zsh.sh

command -v zoxide >/dev/null 2>&1 && eval "$(zoxide init zsh)"
[ -f ~/.fzf.zsh ] && source ~/.fzf.zsh
EOF

# 7. default shell
if [ "$SHELL" != "$(which zsh)" ]; then
  chsh -s "$(which zsh)"
fi

echo "Done. Restart terminal or run: source ~/.zshrc"
echo "Run: p10k configure"

包含

• zsh
• Oh My Zsh
• powerlevel10k
• autosuggestions / syntax-highlighting
• fzf / zoxide

使用

# 自动补全
git → 按 →

# 历史搜索
Ctrl + R

# 跳目录
z project

# git
gst / gco / gp

初始化主题

p10k configure

Finished reading? Leave a comment

做过「Markdown → 图片」的，应该都踩过这个坑：

Markdown → HTML → 浏览器 → 截图

然后你就会遇到：

• chromium 很重（部署麻烦）
• 分页不稳定（每次结果都可能不一样）
• 批量渲染性能很差
• serverless 环境基本不好搞 我最近有点受不了这套链路，就自己写了一个： marknative

核心思路（和常规方案完全不一样）

不走 HTML，不走 DOM，不走浏览器。

而是：

Markdown → AST → 自定义文档模型 → layout → 分页 → canvas 绘制

简单理解：

把“浏览器排版”这件事，自己实现了一套极简版本（只针对 Markdown）。

能干什么？

1. 直接输出 PNG / SVG

import { renderMarkdown } from 'marknative'

const pages = await renderMarkdown('# Hello')

await Bun.write('page-1.png', pages[0].data)

不需要：

• puppeteer
• headless chrome
• 截图

2. 天然支持分页（而且是稳定的）

默认就是：

• 1080 × 1440
• 类似卡片比例 而且分页是 deterministic 的：
• 同一份 Markdown
• 任意环境
• 渲染结果一致

3. 适合批量生成内容

比如：

• 小红书卡片
• 技术文章配图
• AI 自动生成内容图 相比 puppeteer：
• 启动更快
• 内存更低
• 更容易横向扩展

这个方向值得做

本质上，这类需求其实是：

“结构化文本 → 可控排版 → 图像输出” 但浏览器：

• 太通用（为网页设计）
• 不可控（CSS + layout 太复杂）
• 成本太高 而 Markdown 场景：
• 结构固定
• 可约束
• 非常适合做“专用排版引擎”

技术点（简单说几个有意思的）

• 用 micromark + mdast 做解析
• 自己实现 block / inline layout
• 用 skia-canvas 直接绘制
• layout 和 render 完全解耦 所以理论上可以
• 换 renderer（SVG / PDF / WebGL）
• 做自定义主题系统
• 做可视化编辑器（未来）

项目地址

👉 https://github.com/liyown/marknative

Finished reading? Leave a comment

claude 最近更新了交互是 UI，可以在聊天框流式输出可交互的页面 claude：

同时看到一个叫 Generative-UI-MCP 的项目，作者的想法很直接：用 MCP 协议把 Claude 能生成可交互 UI 这套东西复刻出来。

这个项目本身不复杂，但它把一件平时很难说清楚的事拆开了：Claude 这种交互式 UI，真正新在哪里；它为什么不像“AI 帮你写了一段前端代码”那么简单；以及它背后最先要解决的，到底是渲染问题，还是协议问题。

我后来又对着一段真实的 SSE 流式输出日志，把整个过程重新拆了一遍。两边对起来之后，会更清楚：Claude 风格的流式 UI，本质上不是“模型输出 HTML”，而是“模型持续输出一个宿主能够可靠消费的 UI 协议”。

这篇文章想讲的，就是这件事。

它是一个可持续交互UI 页面

Claude 这波交互式 UI / Artifacts，真正新的地方不是“AI 生成了一个页面”，那个早就有人做过了。新的地方在于：生成出来的东西还能继续用，还能继续跟模型交互，还能挂工具、更新状态。

这跟“AI 写了段前端代码，你复制出去跑”是完全不同的东西。

以前那种方式，模型是起点，生成完就结束了。现在这种方式，模型是这个 UI 会话里的持续参与者。用户在界面上的操作可以再回到模型，模型返回的新内容可以局部更新界面，来回转。

这个闭环大概长这样：

sequenceDiagram

actor U as 用户

participant UI as Widget UI

participant Host as 宿主 / Host

participant Tool as 工具 / API

participant LLM as 模型 / LLM



U->>UI: 点击、输入、操作

UI->>Host: emit(action, payload)



alt 前端可直接处理

Host->>UI: 更新本地状态

else 需要调工具

Host->>Tool: 调用业务接口

Tool-->>Host: 返回结果

Host->>UI: 局部更新

else 需要再问模型

Host->>LLM: 当前状态 + action

LLM-->>Host: 新内容 / 新 widget

Host->>UI: 增量插入或局部替换

end

这个循环跑得起来，才是真正的“交互式”。带几个按钮的 HTML 不叫交互式，事件能回流才叫。

一段真实的流式输出，能把这件事看得很清楚

如果看一段真实的 SSE 流式输出，会发现模型并不是一次性吐出一个完整页面，而是在流里持续输出不同类型的内容块，前端边收边拼，拼完再交给对应工具渲染。

拆开之后，大概是五步。

第一步：先加载 UI 生成规范

模型一开始并没有直接生成 widget，而是先调用了一个类似 visualize:read_me 的工具，输入参数非常短：

{

"modules": ["diagram", "interactive"]

}

这一步很关键。它说明模型在真正开始“画界面”之前，先去拿一份运行时 UI 规范。也就是说，生成不是裸奔的，模型先要知道这次该遵守什么规则。

第二步：工具返回一整套设计系统和流式输出约束

这份返回内容里，有几段特别关键。

先是模块说明：

Call read_me again with the modules parameter to load detailed guidance:

- `diagram` — SVG flowcharts, structural diagrams, illustrative diagrams

- `mockup` — UI mockups, forms, cards, dashboards

- `interactive` — interactive explainers with controls

- `chart` — charts, data analysis, geographic maps (Chart.js, D3 choropleth)

- `art` — illustration and generative art

然后是角色定义：

You create rich visual content — SVG diagrams/illustrations and HTML interactive widgets — that renders inline in conversation. The best output feels like a natural extension of the chat.

接着是它最关键的几条约束：

### Philosophy

- Seamless: Users shouldn't notice where claude.ai ends and your widget begins.

- Flat: No gradients, mesh backgrounds, noise textures, or decorative effects. Clean flat surfaces.

- Compact: Show the essential inline. Explain the rest in text.

- Text goes in your response, visuals go in the tool.

还有专门面向流式渲染的顺序规则：

### Streaming

Output streams token-by-token. Structure code so useful content appears early.

- HTML: <style> (short) → content HTML → <script> last.

- SVG: <defs> (markers) → visual elements immediately.

- Prefer inline style="..." over <style> blocks.

- Gradients, shadows, and blur flash during streaming DOM diffs. Use solid flat fills instead.

如果只看表面，这像一份设计规范；但从运行角度看，它其实更像一份“让模型输出稳定 UI 消息”的生成协议。

它在做几件事：

• 规定什么该出现在工具里，什么该出现在自然语言里

• 规定代码要按什么顺序流式吐出来

• 规定哪些视觉效果会破坏流式体验，所以禁止使用

• 规定组件必须适配宿主环境，比如 CSS 变量、深色模式、受控脚本能力

也就是说，这不是“给模型一些审美建议”，而是在给模型划一条窄轨道。

真正的关键，不是 HTML，而是模型输出的结构

随后模型开始调用另一个工具，比如 visualize:show_widget。这一段流最容易让人误解，因为它看起来像一堆零碎碎片：

event: content_block_delta

data: {"type":"content_block_delta","index":2,"delta":{"type":"input_json_delta","partial_json":"-2-2L"}}

单看这种片段，几乎没有可读性。但它们其实不是乱码，而是工具调用参数的一部分。宿主会把同一个 block 下不断到来的 partial_json 拼起来，最后还原成一个完整 JSON。

像这次，重组之后大概是这样：

{

"title": "ui_icons_outline",

"loading_messages": [

"Sketching icon paths...",

"Adding hover magic...",

"Lining up the grid..."

],

"i_have_seen_read_me": true,

"widget_code": "..."

}

这里面每个字段都很有意思。

title 是这次 widget 的标识。loading_messages 不是装饰，而是在把“等待”转成可感知的生成过程。i_have_seen_read_me 则像一个状态确认，表明模型是在已经读过规范的前提下生成的。

而真正的界面，都放进了 widget_code。

这一步揭示了流式 UI 的核心事实：模型不是直接输出最终页面，而是在输出一个宿主可以消费的 UI 消息。

为什么 Generative-UI-MCP 这个项目看起来很小，却很有价值

我原本以为要复刻 Claude 交互式 UI，需要很多东西：自定义渲染器、状态管理、完整前端运行时、组件库、DSL。

结果 Generative-UI-MCP 的核心极简得有点反直觉：

• 一个 load_ui_guidelines 工具，按需给模型加载 UI 生成规范

• 一个 system prompt 资源，把最基础的输出约束提前注入

没有大而全的组件系统，也没有复杂 DSL。

这个取舍反而很能说明问题：复刻 Claude 交互式 UI，最先要解决的不是“怎么渲染”，而是“怎么让模型输出一个宿主能稳定消费的结构”。渲染反而是后面的事。

所以这件事首先是协议问题，不是渲染问题

Claude 的交互式 UI 有一个很强的体验特征：widget 的出现是稳定、可预期的。不会这次变成代码块，下次又变成自然语言夹 HTML。

要做到这件事，不能靠模型“自觉”，只能靠协议。

Generative-UI-MCP 暴露出来的，正是这层东西：

• widget 要用专用 fence 包裹

• fence 里必须是结构化 JSON

• widget_code 字段里装 HTML 或 SVG

• 解释文本必须写在 widget block 外面

• 多个 widget 要拆成多个 block

• 输出顺序得适合流式渲染

这些约束堆起来，本质上已经非常接近一个轻量的 UI 消息协议。

宿主做的事情，本质上就是在这些消息之间路由。

为什么规范一定要按需加载，而不是一次性全塞进 prompt

复刻项目把 UI 规范拆成了几个模块：interactive、chart、mockup、diagram、art，需要什么再加载什么。

这不只是为了省 token，更关键的是：不同 UI 类型的约束本来就不一样。

• 图表有图表的规则

• 表单有表单的规则

• mockup 有 mockup 的规则

• diagram 有 diagram 的规则

• art 又是另一套生成方式

如果全塞进一个大 prompt，模型会被很多无关约束污染。按需加载的价值在于：只有在真正要生成某类 UI 时，模型才拿到那一类规则，输出才更稳定。

这和前面真实流里先传：

{

"modules": ["diagram", "interactive"]

}

其实是同一个思路。

流式的难点，从来不是“更快”，而是“边流边分帧”

很多人对流式的理解停留在“更快显示”。但从真实输出和复刻项目都能看出来，宿主真正要解决的是 parser。

宿主不能只是把 token 一个个打印出来。它必须知道：

• 当前是普通文本，还是 widget block

• 当前是在输出 block 起始，还是中间片段

• JSON 有没有完整闭合

• 什么时候可以直接显示文本

• 什么时候该进入收集模式

• 什么时候该把完整 widget_code 交给渲染器

整个过程大概是这样：

sequenceDiagram

participant LLM as 模型输出 (stream)

participant Parser as Stream Parser

participant Renderer as Widget 渲染器

participant UI as UI 界面



LLM->>Parser: token chunk 1..n

Parser->>UI: 普通文本直接显示



Note right of Parser: 识别到 widget fence
切换到收集模式

Parser->>Parser: 持续收集 JSON block

Parser->>Renderer: 完整 JSON
(title + widget_code)

Renderer->>UI: 挂载 HTML / SVG widget

Note right of UI: 一边生成，一边可见

Claude 那种“widget 自然浮现”的感觉，技术上并不是魔法，而是 parser 在做边流边分帧。

为什么连 <defs>、style 顺序、阴影这些细节都要管

第一次看到这类规范，很容易觉得它管得太细：

• SVG 里 <defs> 要先于图形

• HTML 里 style 在前、script 在后

• 尽量避免渐变、阴影、模糊

但这些规则不是在管审美，而是在管用户看到的每一帧是否合法。

原因很简单：

• <defs> 还没到，图形先出来，marker 和 clipPath 会先错后正

• style 太晚到，用户会先看到裸 UI，再看到样式突然补齐

• 渐变、模糊、阴影在流式 patch 过程中更容易出现跨帧不一致

Claude 输出 widget 很少出现明显抖动，不只是因为模型更强，也因为这套约束把中间态的不稳定性压下去了。

从一个真实 widget 看，这套方法到底偏向什么样的前端

在那段真实输出里，模型最终生成的是一个“25 个常用 UI 线条图标”的交互面板。它按类别展示图标，点击可以高亮，并在底部给出反馈。

从生成出来的 widget_code 可以看出几个很鲜明的取舍。

第一，布局非常简单，核心是稳定的 grid，而不是复杂的响应式技巧。

第二，样式极轻，全部基于宿主给的 CSS 变量，不写死颜色，天然适配深色模式。

第三，图标直接内联 SVG，不依赖图片资源，这样既容易流式输出，也容易在 hover 和 active 态切换颜色。

第四，JS 很短，只做本地交互，不做复杂状态管理，不请求网络，不引入框架。

这说明这类流式 UI 更像“会话中的即时交互壳”，不是完整前端应用。复杂逻辑交给模型，局部互动留在前端。

它很适合：

• 图标面板

• 对比卡片

• 轻量筛选器

• 小型图表

• 交互式解释器

• 内嵌 mockup

但不太适合：

• 超复杂业务表单

• 大型多页应用

• 重状态后台系统

• 强实时协作编辑器

因为它的优势是即时生成、即时嵌入、即时互动，不是长期运行的大型应用壳。

真实流里最后还有一个很重要的信号：文本和 UI 必须分工

在工具把 widget 渲染完之后，系统又返回了一句提示：

Content rendered and shown to the user. Please do not duplicate the shown content in text because it's already visually represented.

这句提示的价值很大。它明确告诉模型：已经渲染出来的东西，不要再重复讲一遍。

随后模型补上的自然语言也很克制，只做三件事：

• 概括这个 widget 是什么

• 告诉用户如何操作

• 提示用户下一步还能让模型做什么

这和前面 readme 里的那句：

Text goes in your response, visuals go in the tool.

正好闭环。

也就是说，Claude 风格的流式 UI，不只是“会渲染 widget”，它还在管理文本和视觉之间的职责边界。

Generative-UI-MCP 看不到的部分，反而是产品化最难的部分

老实说，看完这个复刻项目，会更清楚原版系统有哪些东西不是只靠协议就能补齐的。

1. 沙箱

模型生成的 HTML/JS 不能直接裸跑。必须有 iframe 隔离、白名单 CDN、脚本能力限制、资源权限边界。

否则模型只要生成一段恶意脚本，宿主就会出问题。

2. action 协议

用户点击之后发生什么，不能靠模型随便写 onclick 并自由决定逻辑。成熟设计更像是宿主先定义一套统一 action schema，比如：

• filter_changed

• submit_form

• request_refresh

• select_item

widget 只发动作，宿主决定本地处理、调工具，还是再问模型。

3. 增量 patch

Claude 在多轮对话里更新 widget，很多时候不是整块重生成，而是局部更新。这件事要求宿主维护状态，也要求模型知道什么时候该返回 patch，什么时候该返回完整替换。

demo 和产品级体验之间差得最多的地方，大概就在这里。

真正值得记住的一句话

看 Generative-UI-MCP 最大的收获，不是学到某个新技巧，而是更清楚地意识到：

做交互式 UI，这件事从来不是先解决渲染，而是先解决协议。

协议稳定了，才有后面的这些东西：

• 流式 parser

• widget 渲染

• 沙箱执行

• 事件回流

• 工具挂载

• 增量更新

Claude 把这条链路基本跑通了，所以它用起来不像 demo。Generative-UI-MCP 把这条链路最前面的那段逻辑开源出来了，所以这件事第一次变得足够可理解、可讨论、可拆解。

回头再看那些看似零碎的流式片段，尤其是不断出现的 input_json_delta、widget_code、tool_use，就不会再觉得它们只是噪音。它们其实正是这整套生成式 UI 协议在运行时留下的痕迹。

附录：这次流里真实出现的原始提示词

下面这部分不是整理后的模板，而是从真实流式输出里还原出的原始提示词和规范文本。

1. 模块选择

{

"modules": [

"diagram",

"interactive"

]

}

2. visualize:read_me 返回的规范文本

# Imagine — Visual Creation Suite



## Modules

Call read_me again with the modules parameter to load detailed guidance:

- `diagram` — SVG flowcharts, structural diagrams, illustrative diagrams

- `mockup` — UI mockups, forms, cards, dashboards

- `interactive` — interactive explainers with controls

- `chart` — charts, data analysis, geographic maps (Chart.js, D3 choropleth)

- `art` — illustration and generative art

Pick the closest fit. The module includes all relevant design guidance.



**Complexity budget — hard limits:**

- Box subtitles: ≤5 words. Detail goes in click-through (`sendPrompt`) or the prose below — not the box.

- Colors: ≤2 ramps per diagram. If colors encode meaning (states, tiers), add a 1-line legend. Otherwise use one neutral ramp.

- Horizontal tier: ≤4 boxes at full width (~140px each). 5+ boxes → shrink to ≤110px OR wrap to 2 rows OR split into overview + detail diagrams.



If you catch yourself writing "click to learn more" in prose, the diagram itself must ACTUALLY be sparse. Don't promise brevity then front-load everything.



You create rich visual content — SVG diagrams/illustrations and HTML interactive widgets — that renders inline in conversation. The best output feels like a natural extension of the chat.



## Core Design System



These rules apply to ALL use cases.



### Philosophy

- **Seamless**: Users shouldn't notice where claude.ai ends and your widget begins.

- **Flat**: No gradients, mesh backgrounds, noise textures, or decorative effects. Clean flat surfaces.

- **Compact**: Show the essential inline. Explain the rest in text.

- **Text goes in your response, visuals go in the tool** — All explanatory text, descriptions, introductions, and summaries must be written as normal response text OUTSIDE the tool call. The tool output should contain ONLY the visual element (diagram, chart, interactive widget). Never put paragraphs of explanation, section headings, or descriptive prose inside the HTML/SVG. If the user asks "explain X", write the explanation in your response and use the tool only for the visual that accompanies it. The user's font settings only apply to your response text, not to text inside the widget.



### Streaming

Output streams token-by-token. Structure code so useful content appears early.

- **HTML**: `<style>` (short) → content HTML → `<script>` last.

- **SVG**: `<defs>` (markers) → visual elements immediately.

- Prefer inline `style="..."` over `<style>` blocks — inputs/controls must look correct mid-stream.

- Keep `<style>` under ~15 lines. Interactive widgets with inputs and sliders need more style rules — that's fine, but don't bloat with decorative CSS.

- Gradients, shadows, and blur flash during streaming DOM diffs. Use solid flat fills instead.



### Rules

- No `` or `/* comments */` (waste tokens, break streaming)

- No font-size below 11px

- No emoji — use CSS shapes or SVG paths

- No gradients, drop shadows, blur, glow, or neon effects

- No dark/colored backgrounds on outer containers (transparent only — host provides the bg)

- **Typography**: The default font is Anthropic Sans. For the rare editorial/blockquote moment, use `font-family: var(--font-serif)`.

- **Headings**: h1 = 22px, h2 = 18px, h3 = 16px — all `font-weight: 500`. Heading color is pre-set to `var(--color-text-primary)` — don't override it. Body text = 16px, weight 400, `line-height: 1.7`. **Two weights only: 400 regular, 500 bold.** Never use 600 or 700 — they look heavy against the host UI.

- **Sentence case** always. Never Title Case, never ALL CAPS. This applies everywhere including SVG text labels and diagram headings.

- **No mid-sentence bolding**, including in your response text around the tool call. Entity names, class names, function names go in `code style` not **bold**. Bold is for headings and labels only.

- The widget container is `display: block; width: 100%`. Your HTML fills it naturally — no wrapper div needed. Just start with your content directly. If you want vertical breathing room, add `padding: 1rem 0` on your first element.

- Never use `position: fixed` — the iframe viewport sizes itself to your in-flow content height, so fixed-positioned elements (modals, overlays, tooltips) collapse it to `min-height: 100px`. For modal/overlay mockups: wrap everything in a normal-flow `
` and put the modal inside — it's a faux viewport that actually contributes layout height.

- No DOCTYPE, `<html>`, `<head>`, or `<body>` — just content fragments.

- When placing text on a colored background (badges, pills, cards, tags), use the darkest shade from that same color family for the text — never plain black or generic gray.

- **Corners**: use `border-radius: var(--border-radius-md)` (or `-lg` for cards) in HTML. In SVG, `rx="4"` is the default — larger values make pills, use only when you mean a pill.

- **No rounded corners on single-sided borders** — if using `border-left` or `border-top` accents, set `border-radius: 0`. Rounded corners only work with full borders on all sides.

- **No titles or prose inside the tool output** — see Philosophy above.

- **Icon sizing**: When using emoji or inline SVG icons, explicitly set `font-size: 16px` for emoji or `width: 16px; height: 16px` for SVG icons. Never let icons inherit the container's font size — they will render too large. For larger decorative icons, use 24px max.

- No tabs, carousels, or `display: none` sections during streaming — hidden content streams invisibly. Show all content stacked vertically. (Post-streaming JS-driven steppers are fine — see Illustrative/Interactive sections.)

- No nested scrolling — auto-fit height.

- Scripts execute after streaming — load libraries via `<script src="https://cdnjs.cloudflare.com/ajax/libs/...">` (UMD globals), then use the global in a plain `<script>` that follows.

- **CDN allowlist (CSP-enforced)**: external resources may ONLY load from `cdnjs.cloudflare.com`, `esm.sh`, `cdn.jsdelivr.net`, `unpkg.com`. All other origins are blocked by the sandbox — the request silently fails.



### CSS Variables

**Backgrounds**: `--color-background-primary` (white), `-secondary` (surfaces), `-tertiary` (page bg), `-info`, `-danger`, `-success`, `-warning`

**Text**: `--color-text-primary` (black), `-secondary` (muted), `-tertiary` (hints), `-info`, `-danger`, `-success`, `-warning`

**Borders**: `--color-border-tertiary` (0.15α, default), `-secondary` (0.3α, hover), `-primary` (0.4α), semantic `-info/-danger/-success/-warning`

**Typography**: `--font-sans`, `--font-serif`, `--font-mono`

**Layout**: `--border-radius-md` (8px), `--border-radius-lg` (12px — preferred for most components), `--border-radius-xl` (16px)

All auto-adapt to light/dark mode. For custom colors in HTML, use CSS variables.



**Dark mode is mandatory** — every color must work in both modes:

- In SVG: use the pre-built color classes (`c-blue`, `c-teal`, `c-amber`, etc.) for colored nodes — they handle light/dark mode automatically. Never write `<style>` blocks for colors.

- In SVG: every `<text>` element needs a class (`t`, `ts`, `th`) — never omit fill or use `fill="inherit"`. Inside a `c-{color}` parent, text classes auto-adjust to the ramp.

- In HTML: always use CSS variables (--color-text-primary, --color-text-secondary) for text. Never hardcode colors like color: #333 — invisible in dark mode.

- Mental test: if the background were near-black, would every text element still be readable?



### sendPrompt(text)

A global function that sends a message to chat as if the user typed it. Use it when the user's next step benefits from Claude thinking. Handle filtering, sorting, toggling, and calculations in JS instead.



### Links

`` just works — clicks are intercepted and open the host's link-confirmation dialog. Or call `openLink(url)` directly.



## When nothing fits

Pick the closest use case below and adapt. When nothing fits cleanly:

- Default to editorial layout if the content is explanatory

- Default to card layout if the content is a bounded object

- All core design system rules still apply

- Use `sendPrompt()` for any action that benefits from Claude thinking

3. visualize:show_widget 的真实参数

{

"title": "ui_icons_outline",

"loading_messages": [

"Sketching icon paths...",

"Adding hover magic...",

"Lining up the grid..."

],

"i_have_seen_read_me": true,

"widget_code": "<style>...</style>
...
<script>...</script>"

}

Content rendered and shown to the user. Please do not duplicate the shown content in text because it's already visually represented.



[This tool call rendered an interactive widget in the chat. The user can already see the result — do not repeat it in text or with another visualization tool.]

Finished reading? Leave a comment