Swift Snippets 完全指南:用 SE-0356 为 Swift 包编写可编译、可运行、可嵌入文档的示例代码
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):几行代码印在文档正文的代码框里。虽然阅读体验好,但有三个突出问题:
- 容易过时(go stale):代码被当作普通文本对待,不会定期构建,语言或 API 演进后常常无法编译;
- 缺少编辑器支持:作者在面向写作的编辑器里输入代码,没有语法高亮与内联报错,出错概率更高;
- 趋向伪代码:作者明知代码不会被真正运行,于是把大量解释塞进正文,产出对读者复制到自己项目毫无帮助的代码。
snippets 正是为了填补这两者之间的空档而生。按照提案的粒度划分,示例导向的文档谱系大致是:
- API 参考与内联代码碎片:通常不可编译,出现在列表、索引或符号页链接中,不具备组合性;
- Snippets(本文主题):一个文件演示一个任务,组合一个或多个 API,跨不超过少数几个模块。理想情况下,读者可以复制粘贴,或把它当作起点。典型例子包括:一个排序算法的实现、一个有趣的 SwiftUI 视图层级、在视图中显示 3D 模型的快速配方、演示 Swift Argument Parser 选项的 struct、使用自定义 coding keys 的 Codable 示例、Swift Algorithms "Guides" 里的许多示例,甚至不少 StackOverflow 回答;
- 完整示例工程与教程:组合一个或多个 API,乃至多种技术或模块,演示多个相互独立场景。
snippets 不打算取代前两种载体,而是提供介于两者之间的第三种教学方式。
核心设计:单文件、完整程序、处处可用
snippets 是包内独立的 .swift 文件,可以被 SwiftPM 当作可执行目标构建并运行。它具备三方面特性:
- 单文件:作者和读者都容易理解,天然适合内联进文档;
- 完整可运行程序:能够被测试、维护,作为"可直接复制使用"的代码交付;
- 可访问包内全部代码: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.swiftmanifest;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 需要做三件事:
- 查找并注册符号图 JSON 中出现的新的 snippet mix-in。由于把 snippets 当作符号处理,借助 SymbolKit 数据模型这一步基本是免费的;
- 支持新的
@Snippet指令,用与符号链接相同的逻辑校验path与slice参数。这以新的Semantic实例形式实现:
public final class Snippet: Semantic, DirectiveConvertible {
public static let directiveName = "Snippet"
// etc.
}
- 在
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 示例代码的推荐方式。