全栈地形图A Field Guide to the Full Stack — for backend engineers

00教材提纲

每一章只回答你已经问出来的问题，并且用你本机真实存在的那个项目当教具。顺序可以改；标「待写」的章节随时挑一章让我展开。

01一个全栈应用由什么组成

你现在的困惑不是「不会写」，而是「不知道这些东西各自是什么级别的存在」。所以第一章先不碰语法，先把这片地形的坐标系立起来：有几个程序在跑、各自跑在什么运行时上、边界在哪里。后面十三章都挂在这张图上。

1.1先数清楚：有几个东西在跑

在你熟悉的世界里，一个服务基本等于一个进程 + 一个二进制。编译出 ./server，扔到机器上，它自己跑。前端之所以让你觉得飘，是因为那边的产物不是可执行文件，而是一堆要被别的程序加载的资源。

把你本机四个项目摊开，一共只有四类「可执行物」：

这件事在你自己的 filetrans 里是字面意义上的真实：那堆前端文件最后变成了 Go 二进制里的一段字节数组。

//go:embed web/*
var webFiles embed.FS

两行代码，边界就清楚了：构建期前端被压成文件，编译期这些文件被塞进二进制，运行期 Go 的 HTTP handler 把它们吐给浏览器，浏览器把它们跑起来。「全栈」在这里不是一个模糊的形容词，而是三个明确的时刻。

1.2浏览器是你的运行时，不是你的 UI 库

把浏览器放在和「操作系统 + 消息循环 + 渲染器」同一级去理解，前端的所有古怪规则都会立刻变得有道理。下面这张对照表是整本书里对你性价比最高的东西，值得单独记下来：

最后一行那个「保留模式」是理解 React 的前提。DOM 是一棵常驻的对象树，像 Qt 的控件树：你不是每帧重画，而是改这棵树的属性，浏览器自己决定什么时候重排重绘。这意味着界面的当前样子，是你历史上所有改动的累积结果，而不是某个状态的函数。所有的 UI bug，一大半来自这里。

1.3React 和 Vue 到底是什么关系

答案先给：它们是同一层的两个竞品，解决的是同一个问题，心智模型重合度大概九成，不是上下游、不是互补、不需要都学。它们共同对抗的敌人，是上一节最后那句话——界面状态要靠你手动同步。

下面这个计数器在这页上真的在跑，三个标签页是三种写法的同一个功能：数字、加减、以及一个「偶数时高亮」的小标记。注意第一种写法里，你必须记得每次改了数字，都要去改两个地方的 DOM。

let n = 0;
const out = document.getElementById("d-out");
const badge = document.getElementById("d-parity");

function sync() {
  out.textContent = n;                        // 第 1 处同步
  badge.textContent = n % 2 ? "奇数" : "偶数"; // 第 2 处同步
  badge.dataset.even = n % 2 ? "no" : "yes";    // 第 3 处同步
}
document.getElementById("d-inc").onclick = () => { n++; sync(); };
document.getElementById("d-dec").onclick = () => { n--; sync(); };

function Counter() {
  const [n, setN] = React.useState(0);
  return (
    <div>
      <button onClick={() => setN(n - 1)}>−</button>
      <output>{n}</output>
      <button onClick={() => setN(n + 1)}>+</button>
      <span data-even={n % 2 ? "no" : "yes"}>{n % 2 ? "奇数" : "偶数"}</span>
    </div>
  );
}

const h = React.createElement;
function Counter() {
  const [n, setN] = React.useState(0);
  return h("div", null,
    h("button", { onClick: () => setN(n - 1) }, "−"),
    h("output", null, n),
    h("button", { onClick: () => setN(n + 1) }, "+"),
    h("span", { "data-even": n % 2 ? "no" : "yes" }, n % 2 ? "奇数" : "偶数")
  );
}
ReactDOM.createRoot(mount).render(h(Counter));

<script setup>
import { ref, computed } from "vue";
const n = ref(0);
const even = computed(() => n.value % 2 === 0);
</script>

<template>
  <div>
    <button @click="n--">−</button>
    <output>{{ n }}</output>
    <button @click="n++">+</button>
    <span :data-even="even ? 'yes' : 'no'">{{ even ? '偶数' : '奇数' }}</span>
  </div>
</template>

所以该怎么选

对你的建议很简单：继续用 React，不用纠结。不是因为它更好，而是因为你的仓库已经全在 React 上，而且让 AI 产出 React 代码时它的「见识」最广。学会之后看 Vue 代码不需要专门学习，一个下午就能读懂。

1.4名词层级表：哪些是同一层的，哪些根本不是

你列的那串名字（React、Vue、Next.js、图标库、动效库、Tauri、Wails）之所以搅在一起，是因为它们根本不在同一层。按层排一遍，整个混乱就散了：

1.5Next.js 到底解决什么

一句话：Next.js 把「HTML 在哪台机器上生成」变成了一个可选项，顺带把路由、打包、部署约定一起包了。

你的 gen_note 是最朴素的那种前端，叫 CSR（客户端渲染）。看它构建出来的首页，<body> 里真的只有一个空壳：

<head>
  <title>gen_note</title>
  <script type="module" crossorigin src="/assets/index-CHPP6raO.js"></script>
  <link rel="stylesheet" crossorigin href="/assets/index-C2uaYuKR.css">
</head>
<body>
  <div id="root"></div>  <!-- 整个界面都是这个空 div 里由 JS 渲染出来的 -->
</body>

两条请求路径对比，差别就在「谁生成 HTML」：

所以 Next.js 的代价很具体：线上多了一个必须常驻的 Node 进程（或者托管在 Vercel / Cloudflare 这类平台上）。而 CSR 的产物是纯静态文件，所以你的 Go 二进制 go:embed 一下就全搞定了，不需要 Node 出现在生产环境。

1.6一个库到底以什么形式存在，最后怎么用

这是你问得最准的一个问题。完整链条有五段，而且全都能在你本机的文件里看到：

第 1 段：npm 包就是「带头文件的静态库」

一个 npm 包解包后是一个普通目录，里面是 JS 文件、一个描述自己的 package.json、以及给 TypeScript 看的 .d.ts 类型声明。对照你的世界：

• node_modules/ ≈ vendor 目录，不进 git，可以随时删掉重装
• package.json ≈ CMakeLists + 依赖清单（dependencies 进产物，devDependencies 只在构建期用）
• package-lock.json ≈ 锁定整张依赖图的精确版本，保证两台机器装出一样的东西
• .d.ts ≈ 头文件，只在编译期存在

第 2 段：一个图标库的真身

你的 llm-wiki 依赖 lucide-react。那个包里，每个图标就是这么一小段数据——下面是从 npm 上直接拉下来的真实文件：

const House = [
  "svg",
  defaultAttributes,              // viewBox、stroke: "currentColor"、宽高 24…
  [
    ["path", { d: "M15 21v-8a1 1 0 0 0-1-1h-4a1 1 0 0 0-1 1v8" }],
    ["path", { d: "M3 10a2 2 0 0 1 .709-1.528l7-5.999a2 2 0 0 1 2.582 0l7 ..." }]
  ]
];
export { House as default };

就这样。图标库 = 一堆描述 SVG 的数组 + 一个把数组变成 DOM 的渲染函数。不是图片，不是字体，没有网络请求。下面这个示例把真的 lucide 包从 CDN 载进本页，然后用我手写的十行渲染函数把那段数据画出来：

function renderIcon([tag, attrs, kids = []], size) {
  const el = document.createElementNS("http://www.w3.org/2000/svg", tag);
  for (const [k, v] of Object.entries(attrs || {})) el.setAttribute(k, v);
  if (size) { el.setAttribute("width", size); el.setAttribute("height", size); }
  kids.forEach(k => el.appendChild(renderIcon(k)));
  return el;
}

第 3 段：打包器就是链接器

整包 lucide 有一千多个图标、三百多 KB。但你 import { House } from "lucide-react" 时，最终产物里只会留下 House 那一个数组。这个过程叫 tree-shaking，和你用 --gc-sections 做死代码消除是同一件事。

你的 gen_note 里有这件事最干净的证据。开发期的入口文件指向源码，构建后指向一个带内容 hash 的打包产物：

<div id="root"></div>
<script type="module" src="/src/main.tsx"></script>

<div id="root"></div>
<script type="module" crossorigin src="/assets/index-CHPP6raO.js"></script>

文件名里的 CHPP6raO 是内容哈希。内容变了名字就变，于是可以让浏览器永久缓存这个文件而不怕更新不生效。这是前端对「缓存失效」问题的标准答案，你在 CDN 层干过同样的事。

第 4 段：开发期的那个 Node 进程

开发时你是两个服务一起跑的：Vite 开发服务器（Node）伺候页面，Go 服务伺候接口。跨端口会撞上浏览器的同源策略，所以 Vite 在中间当反向代理——你项目里就是这么配的：

export default defineConfig({
  plugins: [react()],
  server: { proxy: { "/api": { target: "http://127.0.0.1:8787", changeOrigin: false } } },
});

于是页面请求 /api/notes 时，Vite 把它转给 8787 的 Go 服务。上线后这个 Node 进程完全消失，由 Go 同时负责静态文件和接口，路径天然同源，代理也就不需要了。开发期和生产期的拓扑不一样，这件事值得记住，因为「本地好的、上线 404」十次有八次出在这里。

第 5 段：动效库的三层

动效没有「一个库」，是三层不同的东西。下面两条跑道并排对比，左边零依赖，右边是真的 GSAP：

/* 1 CSS：声明「变化要花多久」，由浏览器插值。零依赖，优先选它 */
.mover { transition: transform .5s cubic-bezier(.2,.9,.25,1.1); }
.mover.is-out { transform: translateX(120px) rotate(45deg); }

// 2 GSAP：命令式时间轴，能编排序列、暂停、倒放、物理缓动
gsap.timeline()
  .to(el, { x: 120, rotate: 45, duration: .5, ease: "back.out(1.7)" })
  .to(el, { x: 0, rotate: 0, duration: .4 }, "+=0.15");

// 3 framer-motion：把动效包成 React 组件，适合「元素进出场」
<motion.div animate={{ x: 120 }} transition={{ type: "spring" }} />

1.7桌面端：套壳派与自绘派

先说共同点，这点最重要：Electron、Tauri、Wails、MyGo 用的前端产物和网页版一模一样，还是那堆 dist/ 文件。变的只是宿主——从「用户的浏览器」变成「你自己的程序里嵌的 WebView」。你会写网页，就已经会写它们的界面部分了。

对你来说 Wails 的吸引力很直白：主进程是 Go，你那些现成的 Go 代码能直接变成桌面应用的后端，前端产物还是 React 那一套。agent-archive 用的就是这条路（它的 frontend/ 是 React + Vite，依赖里有 @wailsio/runtime）。

第二种模式对你另有一层意义。看它官方的计数器例子，和本章 1.3 那个是同一个东西：

type counter struct{ n int }

func (s *counter) view(c *ui.Context) {
	ui.Column(c).Fill().Center().Gap(12).Children(func() {
		ui.Text(c, fmt.Sprint(s.n)).FontSize(40).Bold()
		if ui.PrimaryButton(c, "Increment").Clicked() {
			s.n++
		}
	})
}

没有 HTML，没有 JavaScript，没有 DOM，但思想和 React 一模一样：view 是应用状态的函数，框架调用它来构建每一帧，再画到 GPU 上。1.3 里那句「UI = f(state)」可以原样平移过来，换掉的只是渲染后端。这种做法在图形界面里叫即时模式（immediate mode），最有名的代表是 C++ 那边的 Dear ImGui——如果你见过它，MyGo 的原生 UI 会让你觉得很亲切。顺带说，这也正是理解 React 最快的一句话：React 相当于在保留模式的 DOM 上，盖了一层即时模式的壳。

它和 Fyne、Gio 属于同一派（自绘，不碰前端技术栈），区别是 MyGo 把两种模式放进了同一个框架，还把发布链路一起包了。

1.8五分钟读懂任何陌生前端仓库

这是本章能立刻用上的工具。拿到一个你没见过的仓库，按顺序做六件事，五分钟内就能说清它是什么、怎么跑、产物去哪：

• 看 package.json 的 scripts：dev 怎么起、build 产出到哪。这是入口。 cat package.json | head -40
• 看 dependencies 的前五个：有 next 就是 Next.js 应用，有 react 没 next 就是纯 SPA，有 vue 同理，有 electron / @tauri-apps/api / @wailsio/runtime 就是桌面应用。
• 找配置文件认构建工具：vite.config.*、next.config.*、webpack.config.*、src-tauri/tauri.conf.json、wails.json。有哪个就是哪条路。 ls -a | grep -E 'config|^src-tauri|wails'
• 看 dev 期的接口代理：vite.config 里的 server.proxy，或 next.config 里的 rewrites。它直接告诉你后端在哪个端口。
• 看产物怎么被交付：后端有没有 go:embed、Dockerfile 里有没有把 dist/ 拷进 nginx、还是直接托管在平台上。 grep -rn "go:embed\|dist" --include=*.go --include=Dockerfile .
• 打开 src/main.tsx（或 app/layout.tsx）：三十行内你就能看到挂载点、路由表和全局状态是怎么装起来的。

这六步对你本机任意一个仓库都成立。不信随便挑一个试：先猜，再按这六步验证。

1.9自测

能把下面四题用自己的话讲清楚，第 1 章就算过了。