Swift Snippets 完全指南:用 SE-0356 为 Swift 包编写可编译、可运行、可嵌入文档的示例代码

原创2026-09-21 19:19:441,748 阅读
文章标签:文档编程语言

Swift Snippets 完全指南:用 SE-0356 为 Swift 包编写可编译、可运行、可嵌入文档的示例代码

本指南以 Swift Evolution 提案 SE-0356《Swift Snippets》(Swift 5.7 已实现)为核心,系统讲解 Swift 包中一种全新的示例代码形态——snippets:它是短小、单文件、可被 Swift Package Manager(SwiftPM)自动识别并像可执行目标一样构建与运行的程序,同时又能以代码块形式嵌入 Swift-DocC 文档。读完本文,你将掌握 snippets 的目录约定、// snippet.hide / // snippet.show 与切片(slice)标记语法、@Snippet 文档指令、CLI 构建运行方式、snippetsDirectory 配置,以及 SwiftPM、SymbolKit、Swift-DocC、snippet-build 工具链背后的设计原理。

为什么需要 snippets:示例代码的两难

人们在用代码演示一个想法或 API 时,通常只有两种载体:

  • 完整的示例工程(sample projects):包含构建配置、资源、多个源文件,最终产出完整的 "app"。它适合展示某个具体、完整的场景,但创建和维护成本很高,容易退化成"什么都往里塞"的 kitchen sink 示例,读者也难以快速找到真正有价值的部分。
  • 文档内嵌代码片段(code listings):几行代码印在文档正文的代码框里。虽然阅读体验好,但有三个突出问题:
    1. 容易过时(go stale):代码被当作普通文本对待,不会定期构建,语言或 API 演进后常常无法编译;
    2. 缺少编辑器支持:作者在面向写作的编辑器里输入代码,没有语法高亮与内联报错,出错概率更高;
    3. 趋向伪代码:作者明知代码不会被真正运行,于是把大量解释塞进正文,产出对读者复制到自己项目毫无帮助的代码。

snippets 正是为了填补这两者之间的空档而生。按照提案的粒度划分,示例导向的文档谱系大致是:

  • API 参考与内联代码碎片:通常不可编译,出现在列表、索引或符号页链接中,不具备组合性;
  • Snippets(本文主题):一个文件演示一个任务,组合一个或多个 API,跨不超过少数几个模块。理想情况下,读者可以复制粘贴,或把它当作起点。典型例子包括:一个排序算法的实现、一个有趣的 SwiftUI 视图层级、在视图中显示 3D 模型的快速配方、演示 Swift Argument Parser 选项的 struct、使用自定义 coding keys 的 Codable 示例、Swift Algorithms "Guides" 里的许多示例,甚至不少 StackOverflow 回答;
  • 完整示例工程与教程:组合一个或多个 API,乃至多种技术或模块,演示多个相互独立场景。

snippets 不打算取代前两种载体,而是提供介于两者之间的第三种教学方式。

核心设计:单文件、完整程序、处处可用

snippets 是包内独立的 .swift 文件,可以被 SwiftPM 当作可执行目标构建并运行。它具备三方面特性:

  1. 单文件:作者和读者都容易理解,天然适合内联进文档;
  2. 完整可运行程序:能够被测试、维护,作为"可直接复制使用"的代码交付;
  3. 可访问包内全部代码:snippet 自动依赖宿主包(host package)中声明的所有库目标,因此可以自由 import 这些模块,在保持 snippet 代码简洁的同时实现强大行为。

提案还展望了 snippet-only packages(几乎完全由 snippets 组成的包)的可能性:比如"以新方式组合 UI 元素的配方集""逐 snippet 教授 Swift 语言""教材练习集"等。由于 snippets 能访问包内共享库,即使强大的概念也能用易读的 snippet 演示。

编写一个 snippet:描述、隐藏标记与 presentation code

基本结构

一个 snippet 文件可能是这样:

// The first contiguous line comments
// serve as the snippet's short description.

func someCodeToShow() {
    print("Hello, world!")
}

// snippet.hide

func someCodeToHide() {
    print("Some demo message")
}

// Still hidden
someCodeToHide()

// snippet.show

someCodeToShow()

文件顶部的连续行注释是 snippet 的简介(description),以 Markdown 书写,通常是简短的一段话,会随 snippet 一起展示。// snippet.hide 与 // snippet.show 用于在文档或未来支持 snippets 的工具中切换"隐藏/显示",让作者可以在运行时加入额外的演示逻辑,同时保持最终文档展示的代码干净整洁。

上述文件在文档中最终呈现的效果大致如下:

The first contiguous line comments serve as the snippet's short description.

func someCodeToShow() {
    print("Hello, world!")
}
someCodeToShow()

经过隐藏标记解析后提取出的代码,称为该 snippet 的 presentation code(展示代码)。

切片(Slices):一段代码多个代码块

文档中的代码块往往构成连续的叙事:先展示一段代码,配以散文说明,再展示下一段,且后一段会引用前一段定义的变量。例如:

First, call setup() to initialize the context:

let context = setup()

Then, call request(_:) with the desired mode:

context.request(.immediate)

第二个代码块引用了第一个代码块中的 context,因此就编译而言,snippet 由两个代码块组成。为了支持这种用法,作者可以在单个文件中用标识符"切片",并在文档中按需引用:

// snippet.setup
let context = setup()

// snippet.request
context.request(.immediate)

标记的完整形式为 // snippet.IDENTIFIER,其中 IDENTIFIER 必须是URL 兼容的路径组件(URL-compatible path component),以兼容 DocC 的链接解析逻辑。开启一个新切片会自动终止上一个切片;对于不相邻的切片,可以用 // snippet.end 显式结束当前切片:

// snippet.setup
let context = setup()
// snippet.end

// More code here...

// snippet.request
context.request(.immediate)

还可以把 show/hide 标记与切片混合使用:

// snippet.setup
let context = setup()

// snippet.hide
// More code here...
// snippet.show

// snippet.request
context.request(.immediate)

目录约定与快速上手

默认目录:Snippets

要开始为包添加 snippets,首先在包的 Sources、Tests 目录旁创建一个 Snippets 目录,然后直接放入 .swift 文件即可。文件的基名(base filename)必须彼此唯一。SwiftPM 会假定每个文件构成一个独立可执行目标,像构建其他可执行文件一样为宿主平台构建并运行它们。

开始之后,一个包可能长这样:

📁 MyPackage
  📁 Package.swift
  📁 Sources
  📁 Tests
  📂 Snippets
     📄 Snippet1.swift
     📄 Snippet2.swift
     📄 Snippet3.swift

分组:一层子目录

当 snippets 数量增多时,可以在 Snippets 下再建一层子目录来组织(仅允许一层),这不会影响下文介绍的 snippet 链接:

📁 MyPackage
  📁 Package.swift
  📁 Sources
  📁 Tests
  📂 Snippets
     📁 Group1
        📄 Snippet1.swift
        📄 Snippet2.swift
        📄 Snippet3.swift
    📁 Group2
        📄 Snippet4.swift
        📄 Snippet5.swift

覆盖目录位置:snippetsDirectory

与 ./Sources、./Tests 类似,用户可以通过给 Package 初始化器新增的可选参数 snippetsDirectory 覆盖 ./Snippets 的位置。由于 snippet 目标不会在 manifest 中逐个声明,该设置存在于包级别:

let package = Package(
    name: "MyPackage",
    snippetsDirectory: "Examples",
    products: [
      // ...
    ],
    dependencies: [
        // ...
    ],
    targets: [
        // ...
    ]
)

提示:提案后续示例默认使用 Snippets 目录。即使覆盖了 snippetsDirectory,下面 @Snippet 路径中的命名空间组件仍固定写作 Snippets。

在 Swift-DocC 文档中使用 @Snippet

Swift-DocC(或其他文档工具)可以在散文式 Markdown 文件中导入 snippets。DocC 中,在任何位置使用新的块指令 @Snippet 即可展示 snippet 的描述与代码,它只有一个必填参数 path:

@Snippet(path: "my-package/Snippets/Snippet1")

path 参数由三个部分组成:

  • my-package:包名,取自 Package.swift manifest;
  • Snippets:一个非正式命名空间,用于将 snippets 与符号(symbols)、文章(articles)区分开;无论上文 snippetsDirectory 是否被覆盖,这一部分都保持为 Snippets;
  • Snippet1:snippet 名称,取自文件去掉扩展名后的基名。

要插入某个切片,加上可选的 slice 参数,值对应源码中的标识符:

@Snippet(path: "my-package/Snippets/Snippet1", slice: "setup")

构建与运行:SwiftPM 的 CLI 支持

创建 snippets 后,SwiftPM 可以像处理可执行目标一样构建、运行它们。snippet 目标默认不会随普通构建执行,只有显式传入 swift build --build-snippets 时才会构建,这与"构建测试需要显式选择(swift test 或 swift build --build-tests)"的语义一致。提案建议在所有 CI 构建流程中构建 snippets,至少也要在构建文档时构建。

常用命令:

swift build                   # Builds source targets as usual,
                              # but excluding tests and snippets.

swift build --build-snippets  # Builds source targets, including snippets.

swift build Snippet1          # Build the snippet, Snippet1.swift, as an executable.

swift run Snippet1            # Run the snippet, Snippet1.swift.

测试 snippets:断言与前置条件

snippet 演示的代码本身理应由测试覆盖,但作者也可能希望在运行 snippet 时断言特定行为。提案没有采用 XCTest——因为 XCTest 断言无法在没有平台相关测试 harness 的情况下被收集和记录。snippets 本质上是可执行文件,因此用 asserts(断言)与 preconditions(前置条件) 即可满足绝大多数场景,同时让交互式与非交互式 snippets 并存、目前统一对待。关键是 snippets 必须能在 CI 与外部测试方案中可测试,从而一步完成自动化。

示例:

let numbers = [20, 19, 7, 12]
let numbersMap = numbers.map({ (number: Int) -> Int in
  return 3 * number
})

// snippet.hide
print(numbersMap)
precondition(numbersMap == [60, 57, 21, 36])

这里把 print 与 precondition 放进 // snippet.hide 与文件末尾之间,运行时会校验结果,但文档展示的代码保持简洁。

详细设计:工具链如何支撑 snippets

Swift Package Manager:自动发现目标

SwiftPM 在构造包的可用目标集合时,会按以下模式自动发现 snippet 文件:

  • ./Snippets/**.swift*
  • ./Snippets/*/*.swift

每个文件都会成为一类新的 .snippet 目标,行为大体等同于现有可执行目标。允许一层子目录,是为了在文件系统组织与"snippet 相关资源通过相对路径非正式查找"之间取得平衡。

snippet 目标自动依赖宿主包中声明的所有库目标,因此 snippets 可以自由 import 这些模块。将来为支持 snippet-only 包、组合两个独立包的示例,或需要辅助库的包,snippets 还能导入 manifest 中声明的依赖包里的库(见"未来方向")。

SymbolKit:snippet 成为符号

snippets 通过 Symbol Graph JSON 传递给 DocC,每个 snippet 成为一种符号。snippet 符号包含两条主要信息:以符号"文档注释"形式携带的描述,以及通过新 mix-in Snippet 携带的展示代码:

public struct Snippet: Mixin, Codable {
    public struct Slice: Codable {
        public var name: String?
        public var language: String?
        public var code: String
    }
    public var slices: [Slice]
}

当 snippet 没有任何切片注释时,上述模型由一个包含全部可见代码的 slice 组成。

Swift-DocC:解析与渲染

Swift-DocC 为支持 snippets 需要做三件事:

  1. 查找并注册符号图 JSON 中出现的新的 snippet mix-in。由于把 snippets 当作符号处理,借助 SymbolKit 数据模型这一步基本是免费的;
  2. 支持新的 @Snippet 指令,用与符号链接相同的逻辑校验 path 与 slice 参数。这以新的 Semantic 实例形式实现:
public final class Snippet: Semantic, DirectiveConvertible {
    public static let directiveName = "Snippet"
    // etc.
}
  1. 在 RenderContentCompiler 中把 @Snippet 出现处转换为段落与代码块,每种出现处产生如下内容:
    • 若 @Snippet 是切片:只输出该切片的代码作为 CodeBlock;
    • 若 @Snippet 不是切片:输出经正常符号处理流程的 Markdown 文档注释(一组块元素),然后为每个 snippet 切片输出其代码作为 CodeBlock。

Swift DocC Plugin 与 snippet-build 工具

Swift DocC Plugin 是一个 SwiftPM 命令插件(command plugin),用于为 SwiftPM 库与可执行文件构建文档,其插件机制基础来自提案 SE-0303《Package Manager Extensible Build Tools》。为了把包的 snippet 信息转发给 DocC,新增了一个工具 snippet-build,负责把 .swift 文件转换为 Symbol Graph JSON,插件会在 docc 之前运行它。

snippet-build 以与 SwiftPM 相同的方式遍历 Snippets 目录结构查找 .swift 文件,为每个文件在 Symbol Graph 中创建一个 snippet 符号条目,并输出到指定目录。用法如下:

USAGE: snippet-build <snippet directory> <output directory> <module name>

ARGUMENTS:
    <snippet directory> - The directory containing Swift snippets
    <output directory> - The directory in which to place Symbol Graph JSON file(s) representing the snippets
    <module name> - The module name to use for the Symbol Graph (typically should be the package name)

通常不期望用户手动运行这个命令。使用 Swift DocC Plugin 时需要开启 --enable-experimental-snippet-support 特性开关。

关于 Swift 插件依赖的说明

由于 SwiftPM 插件会把依赖折叠进插件客户端的依赖图中,为避免潜在的依赖循环或冲突,snippet-build 放弃了一些有用但次要的依赖:

  • Swift Argument Parser:很多包都会依赖它,因此 snippet-build 使用位置参数手工实现参数解析,且预期用法长期不变;
  • Swift Syntax:本可用于代码块分词,但 DocC 已在 Swift-DocC-Render 项目中实现了语法高亮。

这一依赖限制正是推动"把 Symbol Graph 生成从 .swift 文件下沉到编译器"调研的动因之一——那将与现有"为库和可执行文件生成符号图"的功能几乎相同的用法对齐。

兼容性影响

  • Source compatibility:启用 snippets 的改动不破坏源码兼容;
  • ABI stability:不影响 ABI 稳定性;
  • API resilience:不影响 API 弹性。

备选方案回顾

提案还评估并拒绝了四种替代路径,这些对比有助于理解 snippets 的定位:

  • 文字编程式:把 snippets 写进 Markdown:把源码嵌入 Markdown 文档、再提取组装成合法 Swift 文件或包去构建运行测试,需要自定义文件格式、隐藏 setup/测试代码、控制 import 等,工程量大且难以与现有工具链集成。snippets 则以"直接用现有工具链就能跑的 .swift 文件"为核心,天然便于分享甚至粘贴进 StackOverflow 回答;
  • 把 snippets 放进文档注释:会过度聚焦"模块内 API 的文档化",放弃跨模块组合、纯教育目的 snippet 包等更有价值的场景;
  • 把 snippets 做成 playground:playground 已演变为更强大、更依赖自定义工具、也更复杂的形态,通常独立成篇并自带支持文件;而开源 Swift 的包已有承载多文件多资源目标的能力,snippets 刻意保持"简单 .swift 文件"并与 SwiftPM、Swift-DocC 紧密集成;
  • 让测试充当 snippets:snippets 不打算成为测试或直接来自测试(虽然可自带断言校验行为);测试与示例代码的写作语境通常不同。未来或许可以从测试等来源提取 snippets。

未来方向

  • 每文件多个 snippets:未来可以用源码中的 start/end 标记表达多个 snippet;
  • 多文件 snippets:需要多个文件构建的情况已由示例目标/工程承载,大概率不是目标;但对嵌入现有多文件项目的 snippets,或许可以在构建时提取(这很可能要求提取逻辑下沉到编译器);
  • 构建时提取 snippets:snippet-build 可能下沉到将模块转换为 Symbol Graph JSON 的 SymbolGraphGen 库,从而复用共享实现与语义信息,支持从库、单元测试、大型示例工程等不同来源提取 snippets;
  • 构建文档时构建 snippets:当前 Swift-DocC 渲染文档只需读取 snippet 源文件,无需构建;未来可由插件在生成文档前请求构建 snippets,或在编译器构建 snippets 生成符号图时隐式完成;
  • snippet 依赖:当前 snippets 自动依赖宿主包内库;未来可增加声明外部依赖的能力,支持"专为演示其他包中一个或多个库"而存在的包。

总结

SE-0356 将"示例代码"从不可编译的文档文本与笨重的完整工程之间解放出来:一个 .swift 文件,既是完整可运行的程序,又能用 // snippet.hide / // snippet.show 和切片标记控制其在文档中的呈现,还能通过 @Snippet(path:slice:) 被 DocC 按需引用。配合 SwiftPM 的自动目标发现、swift build --build-snippets / swift run 的 CLI 支持、snippet-build 的符号图转换,snippets 真正实现了"写一次、处处读(跑)"。这套约定自 Swift 5.7 起可用,是编写高质量、可验证、可嵌入文档的 Swift 示例代码的推荐方式。

登录后查看全文
swift-evolution