编辑文章

知序

返回

Markdown

# 00 - 课程总览

> 这篇解决什么问题：在 Java 里跑 JavaScript，是什么体验？你的 Java 项目里出现了一句"怎么让业务规则能热更新"或"这段逻辑要是能写在脚本里、每次分析部不用发版就好了"。你可能随口想过"要不让 Java 跑一段 JavaScript"，但真上手又不知道从哪开始——Nashorn 没了、网上说法又五花八门。这篇先带你建立整体认知：GraalJS 是什么、这门课会带你走到哪、你需要准备什么。读完你会建立一条完整的学习主线，并知道接下来该点什么。
> 读完你会知道：GraalJS 能干什么、为什么它是当前 Java 内嵌 JS 的默认答案、这门课 12 篇正文的递进路线，以及你要不要学、怎么学效率最高。

---

## 1. 先说清楚：这课解决的真实痛点

先别急着记 API。先看一个每个 Java 后端都会遇到的真实场景：**业务规则想热更新**。

传统写法是"规则死在 Java 代码里"：

```text
if (amount >= 1000 && vipLevel >= 2) {
    // 返现逻辑
}
```

改一条规则 = 改代码、发版、重启、灰度。而业务方往往说："我就想改一下满减门槛，为什么还要排一次发版？"

**把规则变成一段可执行的 JavaScript 存起来**，就能解决：规则是数据，改规则只是改一条数据库记录，应用不用重启。这正是规则引擎的常见实现，也是本课第 11 篇会亲手做的场景。

而"在 Java 里跑 JS"这个需求，当下最稳的答案就是 **GraalJS**。

> 一句话：**很多"能不能不重启就改行为"的需求，本质都是"在 Java 里跑一段脚本"，而 GraalJS 是这个方向现在最靠谱的引擎。**

---

## 2. GraalJS 是什么：一个图看懂

GraalJS 是 GraalVM 官方提供的 JavaScript 引擎，**运行在普通 JDK 17+ 上**，通过 Truffle 框架 + Graal JIT 拿到接近 V8 的性能，完整支持 ECMAScript 2023。它取代了 JDK 15 被移除的 Nashorn，成为 Java 应用内嵌 JS 的官方推荐方案。

![GraalJS 引擎架构与 Java 调用链](/images/excalidraw/graaljs-01-architecture.svg)

*图：GraalJS 引擎架构与 Java 调用链*

```text
┌─────────────────────────────────────────────────┐
│                  Java 应用                       │
│   ┌───────────────────────────────────────────┐ │
│   │        Polyglot API（Context / Value）     │ │  ← 推荐入口
│   │        或 javax.script（ScriptEngine）     │ │  ← 兼容层
│   └───────────────────────────────────────────┘ │
│                        ▼                        │
│   ┌───────────────────────────────────────────┐ │
│   │              GraalJS 引擎                  │ │
│   │  Truffle AST 解释器  +  Graal JIT 编译器   │ │
│   └───────────────────────────────────────────┘ │
│                        ▼                        │
│                 JVM（宿主运行时）                │
└─────────────────────────────────────────────────┘
```

**它给你的能力，一句话概括**：Java 和 JS 之间既能互调（Java 传数据给 JS 算、JS 反过来调用 Java 方法），又能在沙箱里安全地执行不可信脚本。这套能力是 Node.js 那种"独立运行时"给不了的。

> 一句话：**GraalJS = 让 Java 进程内嵌一个高性能 JS 引擎，既能互操作、又能沙箱隔离。**

---

## 3. 这门课的 12 篇正文，是一条怎么走的路线

为什么不直接教你 API？因为内嵌脚本的能力是**逐层递进的**，跳过基础后面会卡壳。我把 12 篇正文排成四段，正好对应你从"明白"到"能用"的四个阶段：

| 段 | 篇 | 讲什么 | 你会拿到什么 |
|---|---|---|---|
| 第一段 · 入门 | 01 什么是 GraalJS | 引擎定位、Truffle/Graal JIT 原理、能力边界 | 理解它凭什么值得用 |
| 第二段 · 双入口 | 02 ScriptEngine · 03 Context API | 老接口迁移 / 新接口首选 | 分清两种写法该用哪个 |
| 第三段 · 进阶 | 04 类型 · 05/06 互调 · 07 共享 · 08 异常 · 09 沙箱 | 值怎么转、双向调用、共享、兜错、隔离 | 能安全地真实互操作 |
| 第四段 · 实战 | 10 规则引擎 · 11 模板渲染 · 12 踩坑 | 串起全部能力做两个场景 + 避坑 | 两条可直接借鉴的落地代码 |

![课程四段主线：入门→双入口→进阶→实战](/images/excalidraw/graaljs-00-course-map.svg)

*图：课程四段主线：入门→双入口→进阶→实战*

```text
什么是 GraalJS ──→ 双入口 ──→ 互调用得安全 ──→ 两个实战
  (01)           (02/03)     (04~09)        (10/11/12)
```

**关键提醒**：别想着"每条 API 都记熟再往下"。这条路的正确节奏是——第一遍跟着主线跑通 "能执行一段 JS 并取值"，你就已经打败了绝大多数卡在环境和概念上的人。

> 一句话：**课程主线 = 先跑通一段 JS，再学会安全互操作，最后串成两个真实场景。**

---

## 4. 你需要准备什么（很简单）

这门课**只需要你能写 Java**，基础到"会用 try-with-resources、会在工程里引入一个依赖"就够，不需要你懂任何 JS 或 GraalVM 深层原理（JS 语法我们会边用边说）。硬件与软件：

| 需要 | 说明 | 门槛 |
|---|---|---|
| JDK 17+ | 普通 JDK 即可，**不需要** GraalVM JDK | 你八成已经有了 |
| 一个 Java 工程 | 能引入第三方库即可，IDE 自带也行 | 已有 |
| 一个 IDE | IntelliJ / Eclipse / VS Code 任一 | 已有 |

> ⚠️ 有个大坑要提前说：**别用"未装 js 组件的 GraalVM JDK"**，会上报 `language js is not installed`。用普通 JDK 17+ 反而最省事。原因见第 12 篇踩坑 ①。

> 一句话：**零新增前端能力负担，你只需要会写 Java 就能跟完全程。**

---

## 5. 怎么学效率最高（可选的三个回合）

和直觉相反，这门课**不需要你先背 API**。建议这样读：

- **第一遍（只读）**：把 12 篇正文通读，只求"知道每篇解决什么问题、主线怎么串"。很多术语第一遍不用记。
- **第二遍（跟着做）**：从 01 一路到 12，每篇的示例代码亲手敲一遍、跑出和文中一致的结果。跑通比看懂重要。
- **第三遍（自己造）**：不看示例，自己写一遍——比如自己设计一条规则存库再求值（对应 10 篇）、自己写一个模板函数（对应 11 篇）。

**最容易劝退的地方**不是概念难，而是"想在 02 篇就弄懂 09 篇的沙箱"。别急着深挖，先让主线跑通。

> 一句话：**先跑通、再深挖。第一遍的目标是"能执行一段 JS 并拿到结果"，后面每一项再逐个攻破。**

---

## 6. 学完你能做什么（对照验证）

学完 12 篇正文，你应该能独立做对下面这几件事，这就是这门课合格线：

```text
1. 用 Context.eval 执行一段 JS 并 asInt() 取值                                 ← 03
2. 区分老接口 ScriptEngine 和新接口 Context 各在什么场景用                      ← 02/03
3. 把一个 Java 订单 Map 传进 JS 函数算折扣，再把结果读回 Java                   ← 05
4. 让 JS 反过来调用你暴露的 Java 对象方法 / Java.type 建类                      ← 06
5. 配置一个"只能纯计算、动不了文件系统和类"的沙箱，并正确捕获 JS 抛出的异常      ← 08/09
6. 自己接入两条真实链路：规则存库热更新求值、Java 给数据 JS 出 HTML             ← 10/11
7. 遇到环境类报错（语言未装、classpath 缺 jar、中文乱码）能 10 分钟内定位        ← 12
```

> 一句话：**合格的标志是"双入口、双向互调、沙箱、实战串场景"四件事你都能独立做出来。**

---

## 7. 踩过的坑（给新手打预防针）

```text
1. 想"先全懂再动手" → 永远开不了工 → 先跑通一段 JS 再说
2. 用官网/教程说的 GraalVM JDK 硬跑 → 报 language not installed → 直接换普通 JDK 17+
3. 只记概念不敲示例 → 真用起来全会忘 → 每篇示例亲手 run 一次
4. 想一次把 JS 语法学全 → 被劝退 → 跟着用例边学边用，够用就行
```

---

## 8. 本篇小结

```text
┌──────────────────────────────────────────────────────┐
│  GraalJS：在 Java 里跑 JS    要带走的话                 │
├──────────────────────────────────────────────────────┤
│  1. 痛点：不改代码不发版地改行为 ↔ 在 Java 里跑脚本     │
│  2. GraalJS = 官方 JS 引擎，普通 JDK17+ 即可，性能近 V8 │
│  3. 能力 = 双向互调 + 沙箱隔离，Node.js 给不了          │
│  4. 路线 = 入门 → 双入口 → 安全互操作 → 两个实战         │
│  5. 合格线 = 能执行 JS + 双向互调 + 沙箱 + 串场景        │
└──────────────────────────────────────────────────────┘
                    │
                    v
   知道了"这套能力是什么、怎么走"，下一步把它跑起来
                              ──→ 第 01 篇：什么是 GraalJS
```

[下一篇：01 - 什么是 GraalJS]

预览

图名保存后生成 /images/excalidraw/<图名>.svg（只能用字母、数字、短横线、下划线、点）