IntelliJ IDEA
IntelliJ IDEA – the IDE for Professional Development in Java and Kotlin
如何使用 Kotlin Notebook 实现高效开发
Kotlin Notebook 是一种专为 JVM 开发者打造的全新交互式环境。 本文将介绍 Notebook 的主要功能，并展示如何利用这些功能来提升工作效率。
如何使用 Kotlin Notebook
从 2025.1 版本开始，Kotlin Notebook 与 IntelliJ IDEA 捆绑，在各种上下文中使用 Notebook 变得前所未有的简单。 您可以通过以下三种主要方式创建 Notebook：
在项目中创建 Notebook
打开项目后，在 Project（项目）视图中，右键点击源根目录或某个文件夹，然后选择 New | Kotlin Notebook（新建 | Kotlin Notebook）。
这将在项目内创建一个 .ipynb 文件。 通常将 Notebook 置于 notebooks 或 samples 子目录中，但也可以将它们置于项目内的任意位置。
创建临时 Notebook
假设您要在不向项目添加新文件的情况下试验代码。 此时，临时 Notebook 会非常实用。 要创建不属于特定项目的 Notebook，请按以下步骤操作：
- 使用 New Scratch File（新建临时文件）操作（macOS 上按 Cmd+Shift+N，Windows/Linux 上按 Ctrl+Alt+Shift+Insert）。
- 从列表中选择 Kotlin Notebook。
这将在 Scratches and Consoles | Kotlin Notebooks 目录中创建一个文件，并且该 Notebook 可在所有项目中访问，方便您存储零散的代码段并在需要时随时引用它们。
从 Welcome（欢迎）屏幕创建 Notebook
您无需打开项目即可直接从 Welcome（欢迎）屏幕打开或创建 Kotlin Notebook。 导航到 Kotlin Notebook 标签页并点击 New Notebook（新建 Notebook）。 系统将提示您为 Notebook 命名，并选择将其另存为临时文件还是存储到指定文件夹。
基础知识：交互式单元执行与内核控制
Kotlin Notebook 在 IntelliJ IDEA 内提供了熟悉的 Notebook 界面，支持轻松运行代码和管理执行状态。 每个 Notebook 由可独立或按序执行的单元组成。 Notebook 顶部的工具栏包含用于运行单元和管理 Kotlin 内核的控件：
- 运行单个单元：点击代码单元左侧的 Run（运行）按钮，或按 Ctrl+Enter/ Cmd+Enter。 单元的代码随即运行，输出结果直接显示在单元下方。
- 运行多个单元：点击 Run All（全部运行）以从上至下执行 Notebook 中的所有单元。 如果要运行特定点之下的所有单元（例如，从 Notebook 的中间恢复）您可以右键点击该单元并选择 Run All Below（运行下方所有单元）。 这种灵活性让您能够重新运行整个 Notebook 或特定部分，无需手动运行每个单元。
- 中断执行：如果某个单元耗时过长或陷入死循环，请点击 Interrupt（中断）按钮 (⏹)。 此操作会停止当前运行的单元，而不会影响已执行单元的状态。 此功能适用于暂停长期运行的计算或取消误操作。
- 重启/停止会话：使用 Restart Kernel（重启内核）按钮 (🔄) 重置 Kotlin 内核。 重启操作会终止当前会话并清除运行时状态，因此所有变量和 import 都会变为未解析状态。 这有助于确保干净的初始状态（例如，从头开始运行 Notebook 或从错误状态恢复）。 您也可以通过关闭 Notebook 或使用 Kotlin Notebook 工具窗口中的标准 Stop （停止）操作（此操作会关闭内核进程）彻底停止会话。
- 配置 Kotlin Notebook：工具栏上的齿轮图标可以打开 Kotlin Notebook 设置，您可以在其中调整 Notebook 的配置。 借助此设置面板，您可以控制 Kotlin 内核环境，例如使用的 JDK 或内核版本。
使用这些控件，您能够以交互方式执行代码并管理 Notebook 的状态，执行的每个单元都会获得一个编号。
此编号非常重要，因为 Notebook 的状态取决于执行顺序，而不仅仅是单元的线性顺序。 例如，如果单元 A 定义了一个变量，而单元 B 使用了该变量，则必须按正确顺序执行这两个单元。 Kotlin Notebook 会通过以下方式提供帮助：使用星号 (*) 标记尚未运行的单元；每次运行单元时更新其执行计数。
通过 Gist 和 Datalore 分享 Notebook
使用标准 .ipynb Notebook 格式的优势之一是您可以轻松分享您的工作成果。 Kotlin Notebook 提供了便捷的方式来与他人分享 Notebook 或在线发布您的成果：
- GitHub Gist：您可以快速将当前的 Notebook 作为 GitHub Gist 分享。 只需点击工具栏上的 Create Gist（创建 Gist）按钮（带 GitHub 标徽的图标）。 IDE 会将 Notebook 导出到您 GitHub 帐户上的 Gist，并生成一个可分享的 URL。您可以将此 URL 发送给同事，供他们在 GitHub 上查看该 Notebook 或将其下载到本地。 此功能非常适合快速分享示例或在问题和论坛中添加 Notebook 内容。 Gist 将包含 JSON 格式的 Notebook，GitHub 可以呈现该格式以供预览。 您的 Kotlin Notebook 中的所有代码、输出和 Markdown 都会保留。
- JetBrains Datalore：由于 Kotlin Notebook 与 JetBrains 的在线数据科学 Notebook 平台 Datalore 使用相同的文件格式和 Kotlin Jupyter 内核，您的 Notebook 与该平台完全兼容。 只需将 .ipynb 文件上传到 Datalore 即可分享或在云端继续工作。 这意味着，您只需将 Notebook 移至 Datalore 即可轻松与他人协作 – 无需任何转换。
Kotlin Notebook 支持利用 Gist 快速分享代码段以及利用 Datalore 实现云端协作，让分享成果和原型设计变得轻而易举。 无论是公开发布代码段还是与团队成员合作分析数据，您都能在 IntelliJ IDEA 与 Web 端之间无缝切换。
测试 REST API
Kotlin Notebook 为后端和 API 开发者提供了一个强大的工具：能够直接从 Notebook 调用和测试 RESTful API，并完全支持 HTTP 方法、JSON 序列化和基于 IDE 的代码补全。 此功能通过集成由 Ktor 提供支持的 Kotlin HTTP 客户端实现。
要开始，只需在代码单元中添加 %use ktor-client。 此命令会拉取基于 Ktor 的 HTTP 客户端和 kotlinx.serialization 库，两者都随时可用。 之后，您可以通过 http 变量访问 Notebook 中的预配置 HTTP 客户端实例。
强类型 HTTP 调用：借助 HTTP 客户端集成，您可以使用 Kotlin 代码执行 HTTP 请求并获得类型化结果。 例如，要从 API 获取 JSON 数据，您可以编写以下代码：
val response = http.get("https://jsonplaceholder.typicode.com/todos/1")
response.bodyAsText()
此代码将执行 GET 请求，并以针对打印美化且高亮显示的 JSON 输出格式返回响应。
自动 JSON 序列化：Notebook 的 HTTP 客户端与 Kotlin 序列化集成，响应可自动被反序列化：
Ktor 客户端集成将自动处理类生成和 JSON 反序列化本身。 这意味着您可以获得一个包含适当字段的类型化 Kotlin 对象，而无需手动处理 JSON 解析。 如果拥有预定义的数据类，您也可以使用适当的类型实参调用响应的 body() 方法。
在后台，此功能依赖于开源的 kotlin-jupyter-http-util 库，该库将 Ktor 客户端和序列化功能整合到 Notebook 中。 实际上，这意味着您的 Kotlin Notebook 可以充当功能完整的 HTTP 客户端工具（类似 Postman 或 REST 客户端），而且还能在 Kotlin 中编写脚本并对响应进行断言。 此功能特别适合试用端点、测试微服务或抓取 Web API – 所有操作均在 IntelliJ IDEA 中完成。
处理数据：表和可视化
数据探索者会对 Kotlin Notebook 感到得心应手。 通过与用于表格数据的 Kotlin DataFrame 库和用于图表的 Kandy 库紧密集成，2025.1 版本显著增强了数据显示和绘图能力。 这些集成将您的 Notebook 转变为一种交互式数据探索工具。
DataFrame 集成 – 交互式表
添加 DataFrame 库时，通过在单元中放入 %use dataframe，您可以获得一种强大的 DSL 供操作数据。 它以与 HTTP 集成逻辑相同的方式从运行时构建类型信息，例如：
当您显示 DataFrame（例如，通过评估包含表的变量或调用 df.head()）时，Kotlin Notebook 将使用特殊的 UI 组件而不是纯文本进行呈现。 它提供：
- 可滚动分页：优雅地处理大型数据集。 表输出不会尝试转储成千上万行，而是按页显示有限行数并提供导航控件。
- 可排序列：只需点击列标题即可按该列对表进行排序。
- 分层数据钻取：如果您的 DataFrame 包含嵌套数据（例如，某一列包含另一个表或复杂对象），则可以内联展开该数据。 点击包含嵌套结构的单元即可深入查看子表。 这种浏览方式非常适合加载到 DataFrame 中的分层 JSON 数据集。
- 在单独的标签页中打开：有时您想并排比较两个表。 现在，您可以将 DataFrame 输出移动到 Notebook 界面内的独立标签页中。 您在每个新标签页中打开的表都保持可访问状态，因此您可以在多个数据视图之间切换。
- 导出到文件：输出面板现在提供了一个 Export（导出）按钮 (💾)。 只需点击几下，即可将显示的 DataFrame 导出为 CSV、JSON 或 XML 等常用格式的文件。 如果您转换了一些数据并且想保存结果，此功能非常有用。 默认情况下，DataFrame 将保存到您的项目目录，但您可以选择任意位置。 导出的数据遵循当前显示的状态（例如，如果您已按某列对视图进行了排序，导出将遵循该排序顺序，因此所见即所得）。
您也可以直接将 CSV 文件拖放到 Notebook 上：随后会自动生成并执行必要的代码。 您可以立即开始处理加载的 DataFrame。
借助 Kotlin DataFrame，您可以将 CSV 和 JSON 文件以及 SQL 查询结果加载到表中，随后使用 Kotlin 代码对它们进行筛选、聚合与转换。 Kotlin Notebook 会以人性化的方式展示每一步操作的结果， 如同在 IDE 中内置了一个微型数据网格，可以提供数据操作的实时反馈。
要详细了解 Kotlin DataFrame 的全部功能，请查阅官方文档。
使用 Kandy 直观呈现数据
没有可视化的数据科学 Notebook 是不完整的。 Kotlin Notebook 与 Kandy 集成，这是一个由 JetBrains 基于 LetsPlot 构建并由 Kotlin 团队创建的绘图库，目的是为使用 Kotlin DataFrame 和 Kotlin Notebook 的开发者提供最佳体验。 在一个单元中运行 %use kandy 即可在 Notebook 中加载 Kandy 库并启用呈现支持。 这样，您就可以使用 Kandy 简单且类型安全的 DSL 创建图表，并让它们直接显示在代码下方。
例如，您可以为包含 Year（年）和 Population（人口）列的 DataFrame df 快速生成一个折线图：
%use kandy
df.plot {
line {
x(Year)
y(Population)
width = 3.5
color = Color.LIGHT_BLUE
}
layout.title = "Population Growth"
}
当您执行此单元时，Notebook 的输出区域会显示一个图表。
您可以在 Kandy 文档和示例库中看到许多图表示例。
导出和复制图：您可以轻松保存或复制图表。 每个图输出都有一个输出菜单（可以通过将鼠标悬停在输出上时出现在输出右上角的小图标访问）。 在此菜单中，选择 Export Plot As…（将图导出为…）， 将图表保存为图像文件。
如果您需要立即在另一个应用程序中使用该图，则可以选择 Copy Plot（复制图），此功能会将图表图像复制到剪贴板，方便您将其快速粘贴到文档或聊天工具中。 这种工作流使分享数据中的可视化分析变得轻而易举：首先运行单元来创建图表，随后只需点击几下即可导出或复制该可视化结果。
Kandy 的绘图功能与 DataFrame 相结合，可以提供流畅的数据探索体验。 您可以在表中加载和准备数据，随后使用图表直观呈现模式 – 全程使用 Kotlin 完成。 您甚至可以进行迭代、调整数据转换并重新运行图单元来即时查看更新。 Kotlin Notebook 确保图表在 IDE 内高效呈现，无需切换到外部浏览器来查看交互式视觉效果。 有关更高级的用法（如交互式图或复杂布局），请参阅 Kandy 文档，但对于大多数需求，几行 Kotlin 代码即可生成所需图表。
使用 JVM 库和项目代码
Kotlin 拥有丰富的库生态系统，且与 Java 无缝集成。 Kotlin Notebook 可以利用这些优势，允许将外部库或您自己项目的代码轻松引入 Notebook 会话。
使用 %use 和 USE {} 添加外部库
在 Notebook 中使用第三方 JVM 库（例如，HTTP 客户端、CSV 解析器或机器学习工具包）时，您主要有两种选择：
- 通过 %use 导入集成库：Kotlin Notebook 附带了一组面向许多流行库（如 Kotlin DataFrame、Kandy、Ktor、KotlinDL 等）的预定义库描述符。 您可以使用神奇的
%use libraryName导入这些库，而无需考虑依赖项！ 如我们在示例中所见：%use dataframe引入 Kotlin DataFrame 库并设置其呈现器，%use ktor-client引入 Ktor 和相关实用工具。 我们在 GitHub 上维护了一个支持的库及其描述符的列表，并且许多社区库也已集成。 - 通过 Gradle 语法使用未集成库：如果
%use不支持某个特定的库，或者需要指定版本，您仍然可以使用 Gradle 风格的依赖项块手动添加。 Kotlin Notebook 支持特殊的USE { ... }代码块，您可以在其中声明仓库和依赖项，例如：
USE {
repositories {
maven("https://my.repo/url")
}
dependencies {
implementation("com.example:my-library:1.2.3")
implementation("org.apache.commons:commons-text:1.10.0")
}
}
此代码将获取指定的 Maven 工件并将它们添加到 Notebook 的类路径中。 要微调库的解析方式，可以使用 Kotlin Notebook 选项。
当您使用这两种方法之一加载库时，如果存在描述符或集成类，Kotlin Notebook 内核可能会执行额外的集成步骤。 详细了解如何定义您自己的库集成。
如果在一个单元中添加了库，后续单元中的代码可以使用该库，但同一单元中的代码可能需要在该单元执行后才能识别到它。 最佳做法是将 %use 命令或 USE {} 块放在 Notebook 的顶部，或者至少放在它们自己的单元中。 此外，如果重启内核，则需要重新运行相应的依赖项单元以重新建立类路径。
使用项目代码和模块依赖项进行原型设计
Kotlin Notebook 还能与项目中的代码交互，这使其在原型设计和调试中非常有用。 例如，如果您有一个大型代码库，您可以创建一个临时 Notebook 以交互方式试验自己的 API 或数据模型，而无需编写临时 main 函数或单元测试。
2025.1 版本简化了项目代码在 Notebook 中的使用体验，并且提供了更多配置选项：
- 模块类路径选择：默认情况下，当您在 IntelliJ IDEA 项目中打开 Notebook 文件时，Notebook 的类路径不会包含任何项目依赖项。 不过，您也可以将 Notebook 设置为依赖所有项目库，或者依赖特定的项目模块及其内部的所有依赖项。 使用 Notebook 工具栏中的组合框在这些选项之间切换。
- 最新代码：Notebook 使用您项目中的已编译类。 为确保最新的已编译 .class 文件可用，您应该在运行 Notebook 之前构建您的项目。 如果您在 Notebook 打开时编辑了项目中的源文件，系统会提示重新构建模块并重启 Notebook，以便在 Notebook 的输出中看到更改生效。
- 集成：如果您的项目在 Notebook 所依赖的模块中为 Kotlin Notebook 定义了任何集成类，这些集成也会被加载。
Kotlin Notebook 对库和依赖项的处理方式允许您将所需的任何内容（无论是知名的库还是您自己的代码）整合到一起，并以交互方式使用。 由于 Kotlin Notebook 可以访问您的项目代码，您可以执行许多操作，例如，对应用程序的类进行实例化、调用业务逻辑中的函数，或者对数据模型运行快速实验。 您甚至可以使用 Notebook 针对您的 API 编写探索性测试，因为 Notebook 支持以任意顺序运行代码并检查结果，这比固定的单元测试更灵活。
后续计划
下一篇文章将介绍 Kotlin Notebook 的高级功能。 敬请关注！
如果您有任何问题或建议，您可以：
- 在本文下方直接提问。
- YouTrack：创建一个 #ktnb 工单来报告 bug 或建议功能。
- Slack：加入 #notebooks 频道参与讨论并提问。
- 电子邮件：发送电子邮件至 teodor.irkhin@jetbrains.com，提出任何建议或将 Kotlin Notebook 集成到您的工作流中的功能请求。
本博文英文原作者：
Subscribe to IntelliJ IDEA Blog updates
