Swift 标准库新增 `FilePath`:SE-0529 提案深度解析与跨平台路径编程实战

原创2026-09-22 22:37:421,950 阅读
文章标签:文档编程语言

Swift 标准库新增 FilePath:SE-0529 提案深度解析与跨平台路径编程实战

FilePath 是 Swift 标准库新引入的路径货币类型(currency type),它把 Linux、Darwin、Windows 三种平台的路径语法(分隔符、锚点、特殊组件、Darwin resource fork 等)封装为结构化的强类型 API,并配套提供组件视图、文件系统解析与 C 互操作能力。本文以 SE-0529 提案原文 为主体,结合仓库内相关提案(SE-0513、SE-0340、SE-0485、SE-0446)展开,读者读完后将掌握 FilePath 的核心类型体系、路径分解模型、各平台锚点语义、解析与比较语义,以及向标准库迁移的兼容性方案。

动机:为什么 String 不适合表示文件路径

Swift 长期以来没有标准的文件系统路径表示。swift-system 包在 0.0.1 版本引入了 FilePath,并积累了完整的平台正确路径操作 API;但因为它位于外部包中,标准库和 Swift 运行时无法依赖它,toolchain 内的 Foundation 等库的 API 也无法使用它。

与此同时,每个需要"命名一个文件路径"的新 API 都面临与 SE-0513 相同的困境——只能用 String。而 String 作为路径载体有三个根本缺陷:

  1. 不捕获路径结构:路径中的锚点、组件、后缀这些结构信息完全丢失;
  2. 表示形式随平台而异:各平台的路径字符串语法不同;
  3. 路径组件不一定是合法 Unicode:字节序列可能无法用 String 无损承载。

FilePath 以平台原生编码存储路径(Linux/Darwin 上为 CChar,Windows 上为 UInt16),把路径语法的平台细节(分隔符、锚点形式、特殊组件、乃至 Darwin resource fork)封装在类型内部,让开发者无需精通每个平台的约定就能正确操作路径。其中 FilePath.Anchor 表示路径开头标识卷或参考点(盘符、UNC 共享、Darwin resolve flag 等)的部分,这一部分跨平台差异极大,用字符串手工处理极易出错。

佐证:仓库中的 SE-0513 提案正是这一困境的直接体现——它提议为 CommandLine 增加 public static var executablePath: FilePath?,并在"备选方案"中明确说明:不用 String 是因为 FilePath 将被从 swift-system 包引入标准库,它能更好地处理路径字符串,并通过 FilePath.withCodeUnits(_:) 与 C API 互操作。

提案概览:四个核心类型与一段上手示例

SE-0529 提议向 Swift 模块新增 FilePath、FilePath.Anchor、FilePath.Component、FilePath.ComponentView 四个类型,以及构造、分解、解析、C 互操作等必备功能。提案原文给出了一段完整的上手示例:

var path: FilePath = "/var/www/static/index.html"

path.isAbsolute                      // true
path.hasTrailingSeparator            // false

print(path.anchor)                   // Optional(/)
for component in path.components {
    print(component, component.kind) // "var": .regular, "www": .regular, ...
}

// Resolve against the filesystem
let resolved = try path.resolve()

// Construct a path through mutation
var config: FilePath = "/etc/nginx"
config.components.append("nginx.conf")
// config is "/etc/nginx/nginx.conf"

// On Windows, transplant a conventional path to verbatim-component form
var winPath: FilePath = #"C:\Users\dev\project"#
winPath.anchor?.driveLetter            // Optional("C")
winPath.anchor?.isVerbatimComponent    // Optional(false)
winPath.anchor = #"\\?\C:\"#
print(winPath)                         // \\?\C:\Users\dev\project

// On Darwin, strip kernel resolve flags by replacing the anchor with `/`
var darwinPath: FilePath = "/.nofollow/etc/passwd"
darwinPath.anchor = "/"
print(darwinPath)                       // /etc/passwd

从这段代码可以直观看到四类核心能力:查询(isAbsolute、hasTrailingSeparator、anchor、components)、解析(resolve())、变更构造(components.append)、平台语义移植(Windows 锚点改写、Darwin resolve flag 剥离)。

详细设计:路径分解模型

提案的详细设计围绕一个统一的分解模型展开:任何路径都可以理解为三部分——锚点(anchor)、相对路径组件序列(relative path components)、后缀(suffix)。

  • 锚点标识参考点并位于所有组件之前,还可能编码平台专属指令,例如 Windows 上解释其余路径的语法 \\?\,或 Darwin 上指示内核遇到符号链接即报错的 /.nofollow/;
  • 相对路径组件是非空的"不透明字节包",不包含 NUL 或组件分隔符等属于路径语法(由内核解析)的字节;. 与 .. 在路径语法中有特殊含义(在 Windows verbatim-component 路径之外),内核会特殊解释它们,其余组件是文件系统上实体的不透明名称,对其进行任何解释都超出本提案范围;
  • 后缀指示内核在解析完最后一个组件之后做什么:Linux、Darwin、Windows 上可能是可选的尾部分隔符(告诉内核把它当作目录,或穿越符号链接);Darwin 上还可能是(与尾部分隔符互斥的)固定后缀 /..namedfork/rsrc,用于寻址文件的 resource fork。

例如 Linux 路径 /foo/bar:锚点为 /,相对路径组件为 [foo, bar],无尾部分隔符。

路径语法 vs. 文件系统解释

内核先定义并解析路径语法,这与"哪些文件系统以何种配置挂载在何处"无关。Linux 使用标准 POSIX 语法,Darwin 额外识别一组锚点前缀与 resource fork 后缀,Windows 有自身的形式。FilePath 的分解严格跟随内核解析。

内核识别锚点、特殊组件 ./..(因此有了 Component.Kind)与后缀;其余一切作为不透明字节包交给文件系统驱动,这些字节的含义由驱动和挂载配置决定,且可能随运行时变化。提案给出了两个对比鲜明的例子:

  • .zfs/snapshots/<id> 被解析为相对组件 [.zfs, snapshots, <id>]。若这些组件到达启用了快照的 ZFS 卷,驱动会把它们当作快照引用;在其它文件系统上则只是一条普通路径。内核不区分 .zfs 与 .foo,FilePath 也不区分。
  • Darwin 的 /.nofollow/ 恰恰相反:XNU 在解析阶段就提取其含义,甚至在驱动运行之前(.nofollow 根本不会传给驱动)。它是路径语法的一部分,FilePath 将其建模为锚点。

FilePath 将锚点与后缀同相对组件集合分开分解,且三者都参与 == 比较。如果你不断从 /foo/bar 弹出组件,最终停在 /,该操作变为幂等;在 Darwin 上,从 /.nofollow/foo/bar 不断弹出,不动点是 /.nofollow/ 而非 /;/.vol/1234/5678/foo 则停在 /.vol/1234/5678(注意:没有尾部分隔符)。这些行为缺乏 XNU 内核专门知识很难直观理解——如果类型隐藏了这些结构,开发者就得靠逐字节解析与重建来恢复它,而这正是 FilePath 替开发者做的事。

Linux 的语法平凡且保持不变,Windows 的语法形式自 1993 年 Windows NT 3.1 以来保持稳定,而 Darwin 的语法随时间增长。FilePath 直接跟踪 XNU 的解析,而不是让开发者各自维护自己的解析器。

锚点(Anchor)

  • Linux 上,锚点对绝对路径而言就是根 /;
  • Darwin 上还可能包含 resolve flag(如 /.nofollow/、/.resolve/3/ 等)与/或卷标识符(如 /.vol/1234/5678);
  • Windows 上,锚点涵盖盘符(C:\、C:)、UNC 服务器/共享(\\server\share)、verbatim 或设备命名空间形式(\\?\C:\、\\.\pipe),以及语法上必需的根分隔符。
extension FilePath {
  public struct Anchor: Sendable {
    /// 锚点是否为"有根"的:固定到卷根而非工作目录。
    /// Linux/Darwin 上所有锚点都是有根的;
    /// Windows 上 `\`、`C:\`、`\\server\share`、`\\?\C:\`、`\\.\pipe` 有根,
    /// 而 `C:` 不是——它命名了一个盘符,却相对该盘的当前工作目录解析。
    public var isRooted: Bool { get }

#if os(Windows)
    /// 盘符:`C:\` => "C"、`c:` => "c"、`\\?\C:\` => "C"、`\\.\C:\` => "C";
    /// UNC 锚点、非盘符设备锚点、当前盘根 `\` 返回 nil。
    /// 值按原样呈现、不做大小写归一化;Windows 盘符不限于 A-Z,
    /// 冒号前的任意非分隔符码元都构成盘符;若为未配对代理项则返回 U+FFFD。
    public var driveLetter: Unicode.Scalar? { get }

    /// 该锚点是否使用 Windows verbatim-component 形式(`\\?\`)。
    /// 在该形式下 `/` 是合法的组件名内字符,`.` 与 `..` 没有目录特殊含义。
    public var isVerbatimComponent: Bool { get }
#endif
  }

  /// 路径的锚点;纯相对路径返回 nil。
  public var anchor: Anchor? { get set }
}

anchor 是可变属性,这是上一节示例中"移植锚点"(Windows 换 verbatim 前缀、Darwin 剥离 resolve flag)的实现基础。Anchor.driveLetter 之所以选 Unicode.Scalar 而非 Character/String,是因为盘符是冒号前单个 WTF-16 码元,Unicode.Scalar 是三者中最窄且仍可用字面量比较(anchor.driveLetter == "C")的类型;同时它不强制大写归一化,把大小写不敏感匹配留给路径解析(运行时、版本相关的 Unicode upcase 表)。

Windows 的三种路径风格

Windows 路径按前导字节可分为三种风格,提案为此引入了一套术语(Microsoft 文档并未给出权威命名):

  1. Conventional(常规):盘符形式(C:\...、C:...)、UNC 形式(\\server\share\...)、当前盘根(\...)与无根路径(foo\bar)。大多数代码写的就是这种风格,其中 / 与 \ 可互换作为分隔符,. 与 .. 具有通常的目录含义。
  2. Device-namespace(设备命名空间):以 \\.\ 开头、后跟 Win32 设备名(如 \\.\pipe、\\.\NUL、\\.\COM1、\\.\PhysicalDrive0)。锚点由 \\.\ 加设备名构成,锚点之后的组件应用于该设备的命名空间。特殊形式 \\.\C:\... 被视为磁盘引用,通过 Anchor.driveLetter 暴露盘符。
  3. Verbatim-component(逐字组件):以 \\?\ 开头,以最小归一化传给内核。/ 是合法组件名字符而非分隔符,. 与 .. 是字面名称而非目录引用。识别三种子形式:逐字磁盘(\\?\C:\...)、逐字 UNC(\\?\UNC\server\share\...)、逐字普通(\\?\name\...)。

提案特别注明:Win32 层会把 NUL、COM1 等遗留设备名改写为 \\.\NUL、\\.\COM1 再交给 NT 内核,常规与设备命名空间风格的边界在 Win32 层是模糊的。FilePath 不模拟这种改写,把它们当作普通命名组件。

Darwin 锚点规范化

部分 Darwin 锚点形式存在等价拼写,FilePath 在构造时做规范化,使语义相同的路径按字节相等:

  • /.resolve/1/ 规范化为 /.nofollow/(两者都指 XNU 的 do-not-follow-symlinks 标志);
  • /.vol/NNNN/2/ 规范化为 /.vol/NNNN/@/(卷引用内 @ 是根目录 inode 2 的别名)。

其它 resolve-flag 编号(/.resolve/3/、/.resolve/5/ 等)与 /.vol/NNNN/MMMM/ 中的其它 inode 编号按原样保留。

未来的潜在平台

分解模型天然可扩展到更多平台:POSIX 允许以"恰好两个斜杠"开头的路径具有实现定义的含义。Linux 把双斜杠视为单斜杠,而 Cygwin 用 //server/share 映射 UNC、//cygdrive/c 映射 C: 盘。在假设的 Cygwin 支持下,//cygdrive/c/foo/bar 的锚点将是 //cygdrive/c/(盘符为 "c"),组件为 [foo, bar]。

绝对、相对与有根

所有路径都相对于某个参考点。"绝对(absolute)"指仅相对已命名卷的根的路径:不依赖当前工作目录/当前工作盘(Windows)、环境变量(如 $HOME)、/etc/passwd 内容等。绝对性属于锚点的属性。

  • Linux/Darwin 上绝对路径以 / 开头;
  • Windows 上绝对路径以盘符加根分隔符(C:\)开头,或以 UNC/设备锚点(\\server\share\、\\?\、\\.\)开头;
  • Windows 的 \foo 与 C:foo 都是相对路径:前者相对当前盘,后者相对 C 盘上的当前目录。

Windows 还有与"绝对"不同的"有根(rooted)"概念(见 Anchor.isRooted):所有绝对路径都有根,但有些有根路径是相对的。\foo 有根(相对某卷的根),但该卷(即当前盘)未被命名,所以不绝对。Linux/Darwin 上有根等价于绝对。

extension FilePath {
  /// 若该路径无需额外起始位置即可唯一标识文件位置,返回 true。
  /// 不做 shell 展开或环境变量替换;`~` 开头的路径视为相对。
  public var isAbsolute: Bool { get }
}

注意:Windows 保留 CON、NUL、COM1 等遗留设备名并内部改写为设备路径,因此含这些名称的路径经 Win32 规范化后可能被 NT 内核视为绝对路径,且"包含"的含义随 Windows 版本变化(Windows 10 认为 COM1.txt 是设备名,Windows 11 不认为)。FilePath 不模拟该改写。

为什么叫 Anchor 而不叫 Root:最初提案包含 FilePath.Root 类型,但 Root 无法干净地容纳所有平台锚点形式——C:foo 命名了盘符却并非锚定在盘根,算不上"root"。Anchor 更贴切:它命名参考点而不断言该参考点是根。Python pathlib 自 3.4 起就为这一概念使用 .anchor;Rust 使用 "prefix" 但过于笼统(既可指相对组件前的整个区域,也可特指卷标识符之前固定长度的元数据,如 Windows 的 \\?\ 或 Darwin 的 /.nofollow),且 Sequence.prefix 已有不同含义。

组件(FilePath.Component)

FilePath.Component 表示路径的单个组件,永远非空且不含目录分隔符。

extension FilePath {
  public struct Component: Sendable {
    /// 组件是普通文件/目录名,还是特殊目录 `.` / `..`。
    /// 分类反映组件在源路径上下文中的有效含义:在 Windows
    /// verbatim-component 路径中,`.` 与 `..` 没有特殊目录含义,分类为 `.regular`。
    /// 当组件被插入不同上下文的路径时(如 `init(verbatim:)` 构造的组件
    /// 插入非 verbatim 路径),会按目标路径的锚点重新分类。见 `var kind`。
    public enum Kind: Sendable {
      case currentDirectory   // 特殊目录 `.`,表示当前目录
      case parentDirectory    // 特殊目录 `..`,表示父目录
      case regular            // 文件或目录名
    }

    public var kind: Kind { get }
  }
}

#if os(Windows)
extension FilePath.Component {
  /// 把输入视为 verbatim 组件内容创建组件。
  /// 与 `init?(_:)` 不同,它接受含 `/` 的字符串——在 Windows
  /// verbatim-component(`\\?\`)路径中 `/` 是合法组件名字符。
  /// 结果组件无论是否为 `.`/`..`,kind 均为 `.regular`。
  /// 字符串为空或含 `\`、`NUL` 或其它在 verbatim 路径中也非法的字符时返回 nil。
  public init?(verbatim string: String)
  public init?(verbatim codeUnits: Span<FilePath.CodeUnit>)
}
#endif

组件视图(FilePath.ComponentView)

FilePath.ComponentView 是路径相对组件的 BidirectionalCollection 与 RangeReplaceableCollection,覆盖路径中锚点之后、后缀之前的全部内容,并呈现归一化视图:

  • 重复分隔符被忽略(无空组件):a///b 得 [a, b];
  • 非 verbatim-component 的 Windows 路径中 / 视为 \:a/b 与 a\b 都得 [a, b];
  • . 组件被忽略,除非它是无根路径的第一个组件:a/./b、/./a/b、a/b/. 都得 [a, b];./foo 得 [., foo](首组件 kind == .currentDirectory);
  • .. 组件始终呈现:a/../b 得 [a, .., b]。

在 Windows verbatim-component 路径(\\?\)中,. 与 .. 不是特殊目录引用,不会从组件视图丢弃,而是以 kind == .regular 呈现。因此组件分类取决于它源自的路径的锚点,而非仅凭字节本身。

extension FilePath {
  public struct ComponentView:
    BidirectionalCollection, RangeReplaceableCollection, Sendable,
    Hashable, Comparable
  { }

  /// 查看构成该路径的相对路径组件。
  public var components: ComponentView { get set }
}

示例:var path: FilePath = "/home/username/scripts/tree" 后执行 path.components.insert("bin", at: path.components.lastIndex(of: "scripts")!),路径变为 /home/username/bin/scripts/tree。

后缀(Suffix)

后缀是出现在路径最后一个相对组件之后的平台指令,告诉内核在解析完其余路径后做什么。后缀不是组件,不会由 ComponentView 返回,但语义上有意义并影响相等性。存在两种后缀形式,二者互斥(一个路径至多有一个后缀):

  1. 尾部分隔符(Linux、Darwin、Windows):断言路径的最终组件命名的是目录,并要求在该最终组件处解析符号链接;
  2. Resource fork 后缀(/..namedfork/rsrc,仅 Darwin):选择命名文件的 resource fork。

尾部分隔符

尾部分隔符是路径末尾不属于锚点语法一部分的目录分隔符。它在 syscall 层携带含义:POSIX 上尾部 / 等价于追加 .,强制在最终组件处解析符号链接并断言结果是目录。例如若 /tmp/link 是指向目录的符号链接,lstat("/tmp/link") 检查符号链接本身,而 lstat("/tmp/link/") 会跟随它;open("/tmp/foo/", O_RDONLY) 在 foo 是普通文件时以 ENOTDIR 失败,而 open("/tmp/foo", O_RDONLY) 成功。Windows 上有类似语义。

FilePath 保留尾部分隔符——这是相对 System.FilePath 的行为变更(后者在构造时剥离)。Python pathlib 也选择剥离,这被广泛认为是一个错误。

由于尾部分隔符语义上有意义,它对相等性显著:FilePath("/tmp/foo") != FilePath("/tmp/foo/")。希望两者等价处理的代码应显式移除尾部分隔符再比较。

extension FilePath {
  /// 路径是否以目录分隔符结尾,且该分隔符并非锚点语法所必需。
  /// `/tmp/foo/` 返回 true;`/tmp/foo` 返回 false;
  /// `/` 与 `C:\` 返回 false(分隔符属于锚点语法);
  /// `\\server\share\` 与 `/.vol/1234/5678/` 返回 true(命名卷不依赖
  /// 尾部分隔符即完整)。
  /// 设为 true 会在没有尾部分隔符时追加一个;设为 false 会移除之。
  /// Darwin 上对含 resource fork 后缀的路径设为 true 会用尾部分隔符替换后缀。
  public var hasTrailingSeparator: Bool { get set }

  /// 返回添加尾部分隔符的副本;已有或路径为空则原样返回;
  /// Darwin 上若有 resource fork 后缀则以尾部分隔符替换之。
  public func withTrailingSeparator() -> FilePath

  /// 返回移除尾部分隔符的副本;没有则原样返回。
  public func withoutTrailingSeparator() -> FilePath
}

(仅 Darwin)Resource fork

Darwin 上文件可同时有 data fork(普通内容)与 resource fork(辅助数据流)。XNU 内核在路径查找时向路径追加固定后缀 /..namedfork/rsrc 来寻址 resource fork:给定文件 /foo/bar,路径 /foo/bar/..namedfork/rsrc 标识该文件的 resource fork。内核仅在后缀逐字出现在路径末尾(直至空终止符)时识别它。

该后缀与尾部分隔符直接类似:不是相对组件,而是对内核"解析完最终组件后做什么"的指令。它有语义含义(选择不同的字节流)、影响 ==,并与尾部分隔符互斥。FilePath 在解析时识别该后缀,不把 ..namedfork 与 rsrc 呈现为相对组件。

#if canImport(Darwin)
extension FilePath {
  /// 路径是否以 resource fork 引用(`/..namedfork/rsrc`)结尾。
  /// 为 true 时路径标识最终组件命名实体的 resource fork;
  /// 该后缀被 XNU 内核在路径查找时消费,不会作为组件出现在 ComponentView。
  /// 与 hasTrailingSeparator 互斥。
  ///
  ///     FilePath("/foo/..namedfork/rsrc").isResourceFork  // true
  ///     FilePath("/foo").isResourceFork                    // false
  ///     FilePath("/foo/..namedfork/rsrc/").isResourceFork // false
  public var isResourceFork: Bool { get set }

  /// 返回追加 `/..namedfork/rsrc` 的副本;
  /// 已有 resource fork 则返回自身;有尾部分隔符则替换之。
  public func withResourceFork() -> FilePath

  /// 返回移除 resource fork 后缀的副本;没有则返回自身。
  public func withoutResourceFork() -> FilePath
}
#endif

说明:resource fork 是相对冷门的 Darwin 特性,本提案只提供观察与操作该后缀的最小 API,不提出跨平台表面;核心要求是 FilePath 能正确解析这些后缀(它们不是相对组件),并让开发者能观察和移除它们,与尾部分隔符 API 对齐。

路径重建

分解的逆操作:由锚点、组件序列与后缀(尾部分隔符或 Darwin 上的 resource fork)构造路径。适合移植锚点到既有组件、组装独立计算出的部件、或开发者希望对分解的每个轴显式控制时使用。重建结果与等效字符串字面量的解析和归一化完全一致:组件间不会出现重复分隔符(组件本身不含分隔符);非 verbatim 路径中内部的 . 组件(若有)被归一化丢弃;.. 组件保留。

extension FilePath {
  /// 从分解形式创建路径。anchor 为 nil 时结果相对;
  /// hasTrailingSeparator 为 true 且结果非空、且尚未以锚点结构所需
  /// 的分隔符结尾时,追加尾部分隔符。
  public init(
    anchor: Anchor?,
    _ components: some Sequence<Component>,
    hasTrailingSeparator: Bool = false
  )
}

#if canImport(Darwin)
extension FilePath {
  /// 带 resource fork 后缀的分解构造。
  /// resourceFork 为 true 时结果以 `/..namedfork/rsrc` 结尾;
  /// 与尾部分隔符互斥,构造带尾部分隔符的路径请用跨平台初始化器。
  public init(
    anchor: Anchor?,
    _ components: some Sequence<Component>,
    resourceFork: Bool
  )
}
#endif

分解示例总表

提案给出了三张分解示例表,是理解各平台语义的最直观参考。

Linux 与 Darwin:

输入 锚点 组件 尾部分隔符?
/usr/local/bin / [usr, local, bin] 否
/tmp/foo/ / [tmp, foo] 是
foo/bar -- [foo, bar] 否
. -- [.] 否
./foo/bar -- [., foo, bar] 否
/ / [] 否
(空) -- [] 否
/./foo / [foo] 否
foo/./bar -- [foo, bar] 否
foo/. -- [foo] 是
a///b -- [a, b] 否
.. -- [..] 否
a/b/../c -- [a, b, .., c] 否

Darwin 专属:

输入 锚点 组件 尾部分隔符或 resource fork?
/.nofollow/foo/bar /.nofollow/ [foo, bar] 否
/.resolve/1/foo/bar /.nofollow/(已规范化) [foo, bar] 否
/.resolve/3/foo/bar /.resolve/3/ [foo, bar] 否
/.vol/1234/5678/foo/bar /.vol/1234/5678 [foo, bar] 否
/.vol/1234/2/foo /.vol/1234/@(已规范化) [foo] 否
/.vol/1234/5678/ /.vol/1234/5678 [] 是(尾部分隔符)
foo/bar/file/..namedfork/rsrc -- [foo, bar, file] 是(resource fork)

Windows:

输入 锚点 组件 尾部分隔符?
C:\foo\bar C:\ [foo, bar] 否
C:foo\bar C: [foo, bar] 否
\foo \ [foo] 否
\\server\share\foo \\server\share [foo] 否
\\server\share\ \\server\share [] 是
\\.\pipe\name \\.\pipe [name] 否
\\.\NUL \\.\NUL [] 否
\\.\PhysicalDrive0\foo \\.\PhysicalDrive0 [foo] 否
\\.\C:\foo\.\bar \\.\C:\ [foo, bar] 否
\\?\pictures\kittens \\?\pictures [kittens] 否
\\?\UNC\server\share\foo \\?\UNC\server\share [foo] 否
\\?\C:\foo\.\bar \\?\C:\ [foo, ., bar] 否
\\.\UNC\server\share\foo \\.\UNC [server, share, foo] 否

注意最后一行中 . 以 kind == .regular 的组件出现,因为它位于 verbatim-component 路径内,. 无特殊含义。此外,UNC 形式 \\server\share\ 末尾的 \ 是 Windows 上的尾部分隔符(命名卷 \\server\share 本身被视为完整根,参见 Windows 的 PathCchIsRoot);Darwin 上 /.vol/1234/5678/ 末尾的 / 同理是尾部分隔符(/.vol/1234/5678 是完整根)。

解析(resolve())

解析是咨询文件系统以产生路径绝对形式的过程:解析后的路径是绝对的、不含符号链接、不含 ./.. 组件。因为需要文件系统访问,它是可抛出的操作,且所有中间组件必须存在。解析结果是快照:其后文件系统变化(如创建或删除符号链接)可能使解析状态失效。

extension FilePath {
  /// 针对文件系统解析该路径,产生绝对路径并解析所有符号链接与 `.`/`..` 组件。
  /// 所有中间组件必须存在;无法解析时抛出错误。
  /// 该操作是同步的且可能阻塞。
  @available(*, noasync)
  public func resolve() throws -> FilePath
}

resolve() 是同步阻塞的,因此标注 @available(*, noasync),在 async 上下文中不可用。noasync 是 SE-0340 引入的 availability 种类,它只诊断"从 async 上下文调用"这一种阻塞错误场景;提案展望语言层面针对阻塞 I/O 的 effects 系统,让编译器把阻塞作为函数属性更广泛地跟踪。非阻塞变体是未来工作。

注意:Darwin 上解析可能向锚点插入 resolve flag:/.nofollow/foo/bar 表示"对 /foo/bar 不跟随符号链接"。未来 API 将提供抑制或修改该行为的方式。

注意:Windows verbatim-component 路径(\\?\)把 . 与 .. 当字面组件名而非特殊目录引用,解析后的路径中可能保留此类组件;前述 Component/ComponentView 已正确将它们作为普通组件处理。

不咨询文件系统的词法解析(折叠 ..)与词法 resolve-beneath(确保子路径不逃逸基目录)属于安全敏感代码的重要工具,原 pitch 中提出但推迟到未来工作;本提案先提供真正的 resolve(),确保开发者从第一天起就有正确工具可用。同样推迟的还有真正的"快照时点路径等价"操作(考虑硬链接与卷挂载,例如 Darwin 的 /foo/bar 与 /.vol/1234/5678 可能指向同一实体)。

打印、比较与哈希

FilePath 遵循 CustomStringConvertible:其 description 打印锚点(若有)、由平台分隔符连接的组件、以及尾部分隔符或 resource fork 后缀(若有)。FilePath.Anchor 与 FilePath.Component 同样遵循;它们的无标签 String 初始化器是可失败的(开发者可能传入非法锚点或组件)。FilePath 的 String 初始化器同样可失败,对含 NUL 的输入返回 nil;字符串字面量初始化器在非法输入时 trap(目前是运行时,未来工作是把更多此类检查暴露为编译期错误)。

extension FilePath:
  Hashable, Comparable,
  CustomStringConvertible, CustomDebugStringConvertible,
  ExpressibleByStringLiteral
{
  /// 路径的文本表示。内容不是良构 Unicode 时以 U+FFFD 替换非法字节
  /// (见 String.init(decoding:))。
  public var description: String { get }
  public var debugDescription: String { get }

  /// 从字符串字面量创建路径;字面量含 NUL 或其它非法形式时 trap。
  public init(stringLiteral: String)

  /// 从字符串创建路径;含 NUL(任何受支持平台上都非合法路径字节)时返回 nil。
  public init?(_ string: String)
}

Anchor 与 Component 的协议遵循及初始化器形态与此一致(Anchor 字面量前置条件:非空、无 NUL、构成合法锚点;Component 字面量前置条件:非空、无 NUL 或目录分隔符)。

相等语义:两个 FilePath 相等当且仅当锚点相同、组件视图产生相同序列、且尾部分隔符或 resource fork 后缀的有无一致。

// 打印反映归一化后的组件视图
print(FilePath("a///b"))      // "a/b"
print(FilePath("a/./b"))      // "a/b"
print(FilePath("/./foo"))     // "/foo"
print(FilePath("/tmp/foo/"))  // "/tmp/foo/"
print(FilePath("."))          // "."

// 比较依次比较锚点、归一化组件、后缀信息(尾部分隔符或 resource fork)
FilePath("a///b") == FilePath("a/b")          // true:都打印为 "a/b"
FilePath("a/./b") == FilePath("a/b")          // true:都打印为 "a/b"
FilePath("/./foo") == FilePath("/foo")        // true:都打印为 "/foo"
FilePath("/tmp/foo/") == FilePath("/tmp/foo/") // true

FilePath("/tmp/foo") != FilePath("/tmp/foo/") // true:尾部分隔符不同
FilePath(".") != FilePath("")                 // true:"." 与 ""

FilePath("/.nofollow/foo/bar") != FilePath("/foo/bar")    // true:锚点不同(Darwin)
FilePath(#"\\.\C:\foo\bar"#) != FilePath(#"C:\foo\bar"#)  // true:锚点不同(Windows)

FilePath.== 回答的是"两条路径在消除无意义的编码差异(重复分隔符、内部 . 组件)之后是否拼写相同",它纯句法、不咨询文件系统,因此适合作为 Dictionary 或有序数组等数据结构中的键。其比较语义提供了直觉上的可替换性:两条路径恰好在打印相同时比较相等(模 U+FFFD 的 Unicode 纠错)。

提案用一个精妙的类比解释这一点:文件路径类似于指导内核结合文件系统驱动遍历虚拟文件系统的一组"方向"。两组不同方向的路径即使可能到达同一目的地(因硬链接、符号链接、父目录解析等),也比较为不相等。例如 XNU 路径 /.nofollow/foo/bar 不同于 /foo/bar,因为前者给内核的方向包含"沿途遇到符号链接就报错"的条款;尾部斜杠同理有语义,因为它指示内核跟随最终组件的符号链接并验证结果是目录。

Comparable 提供适合有序集合的确定性顺序:对路径归一化字节表示做字典序比较(平台相关,见上文"路径分解"):先锚点字节、再按序组件字节、以尾部分隔符或 resource fork 后缀作最终决胜。ComponentView 也遵循 Hashable 与 Comparable,但其比较与哈希只考虑路径的相对组件部分,不含锚点与后缀。

大小写不敏感、文件系统感知等价等其它比较模式是未来工作,更适合放在专门库或作为 comparator 参数;FilePath 是可弹性(resilient)类型且比较非内联,ABI 允许在必要时调整内部表示。

路径与字符串

FilePath、FilePath.Anchor、FilePath.Component 都可解码/校验为 Swift String:

extension String {
  /// 将路径内容解释为 UTF-8(Linux/Darwin)或 UTF-16(Windows)创建字符串。
  /// 非良构 Unicode 以 U+FFFD 替换(见 String.init(decoding:))。
  public init(decoding path: FilePath)
  public init(decoding anchor: FilePath.Anchor)
  public init(decoding component: FilePath.Component)

  /// 从路径创建字符串并校验内容为 UTF-8(Linux/Darwin)/UTF-16(Windows)。
  /// 非良构 Unicode 时返回 nil。
  public init?(validating path: FilePath)
  public init?(validating anchor: FilePath.Anchor)
  public init?(validating component: FilePath.Component)
}

说明:这套 API 是可分离的——备选方案是让开发者经 .description 提取字符串,或把字符串创建推迟到码元层面(但会因 CChar/UInt16 差异需要 #if)。

底层字节访问与 C 互操作

FilePath 通过基于闭包的 withCodeUnits(_:) 提供底层以 NUL 结尾的平台字节,供 C 互操作使用。它跟踪 String.withCString(_:) 的模式,但额外传递码元个数(不含空终止符),调用方无需重算长度。以 NUL 结尾的字节也可经 nullTerminatedCodeUnits 直接作为 span 获取。

extension FilePath {
#if !os(Windows)
  /// 平台原生路径编码中表示"字符"的类型
  public typealias CodeUnit = CChar
#else
  public typealias CodeUnit = UInt16
#endif

  /// 用指向路径 NUL 结尾内容的指针及空终止符前的码元个数调用闭包。
  /// 指针仅在闭包期间有效;计数不含空终止符。
  /// Windows 上指针为宽指针(UnsafePointer<UInt16>),
  /// 参见 String.withCString(encodedAs:_:)。
  public func withCodeUnits<Result, E: Error>(
    _ body: (UnsafePointer<FilePath.CodeUnit>, Int) throws(E) -> Result
  ) throws(E) -> Result
}

FilePath、FilePath.Anchor、FilePath.Component、FilePath.ComponentView 均提供基于 Span 的底层字节访问;组件不含目录分隔符与空终止符。Span/OutputSpan 分别来自非逃逸类型提案 SE-0446 与 SE-0485。

extension FilePath.Component {
  /// 该组件平台码元的 span。
  public var codeUnits: Span<FilePath.CodeUnit> { get }

  /// 从平台码元 span 创建组件;码元为空或非法(如包含多个组件)时返回 nil。
  public init?(codeUnits: Span<FilePath.CodeUnit>)
}

extension FilePath.ComponentView {
  /// 路径相对组件部分的平台码元 span。
  public var codeUnits: Span<FilePath.CodeUnit> { get }
}

extension FilePath.Anchor {
  /// 该锚点平台码元的 span。
  public var codeUnits: Span<FilePath.CodeUnit> { get }
}

extension FilePath {
  /// 该路径平台码元的 span,不含空终止符。
  public var codeUnits: Span<FilePath.CodeUnit> { get }

  /// 该路径平台码元的 span,含末尾空终止符。
  public var nullTerminatedCodeUnits: Span<FilePath.CodeUnit> { get }

  /// 从平台码元 span 创建路径;span 不应含空终止符;
  /// 含 NUL(任何平台都非法)时返回 nil。
  public init?(codeUnits: Span<FilePath.CodeUnit>)

  /// 以指定容量创建路径,然后用覆盖路径未初始化内存的输出 span 调用闭包。
  /// 容量不含空终止符。
  public init<E: Error>(
    capacity: Int,
    initializingCodeUnitsWith initializer: (inout OutputSpan<FilePath.CodeUnit>) throws(E) -> Void
  ) throws(E)
}

注:ComponentView 没有对应的码元初始化器——这与 FilePath 的相对路径码元初始化器冗余,且对带锚点的路径可能想返回 nil。正确做法是初始化一个 FilePath 再取它的组件视图。

兼容性与采用影响

源码兼容:所有变更都是增量添加。SystemPackage.FilePath 与/或 System.FilePath 可通过条件 typealias 迁移到标准库的 FilePath:

#if compiler(>=6.4) // 或该变更落地的版本
public typealias FilePath = Swift.FilePath
#else
public struct FilePath { ... }
#endif

来自 SystemPackage.FilePath 的既有功能(如句法便捷方法)可在包含此变更的 toolchain 版本上作为 Swift.FilePath 的扩展添加,从而获得平滑的源码兼容迁移路径。swift-system 的 FilePath.Root 应正式弃用,改用跨平台抽象 FilePath.Anchor。

ABI 兼容:本提案纯粹是标准库 ABI 的扩展,不改变任何既有特性。Darwin 上 System.FilePath 目前有 ABI 承诺;可通过 ABI 级重定向处理迁移,使既有链接 System.FilePath 的二进制继续工作。

采用影响:采用者需要包含此变更的 toolchain,该类型无法在不额外工作的情况下回部署到旧运行时。对 swift-system 既有用户:SystemPackage(SwiftPM 包)可按上文 #if 条件处理;System(Darwin framework)可执行 ABI 迁移,把既有 System.FilePath 符号重定向到标准库实现,为既有 Darwin 二进制保持二进制兼容。

未来方向

提案在核心之外规划了多项未来工作,全部以"先落地核心类型"为前提:

  • 句法操作:lastComponent、stem、extension、removingLastComponent() 等便捷访问器,以及 append、push、removePrefix 等变更方法,可基于 ComponentView 表达且可回部署。路径追加的 / 运算符也是未来工作,争议点是右操作数应为单个组件、组件序列、还是解析后作为相对路径拼接的路径/字符串,各有锚点处理与错误行为取舍。
  • 词法解析与 resolve-beneath:不咨询文件系统折叠 ..、确保子路径不逃逸基目录的操作,对沙箱与安全敏感代码重要,计划后续添加。
  • resolve() 的非阻塞变体:async 非阻塞形式依赖标准库 I/O 池设计;同步非阻塞形式在阻塞不可接受的环境也可行但属次要。@available(*, noasync) 只诊断 async 上下文这一种阻塞错误场景,语言级 effects 系统才能更广地跟踪阻塞。
  • 退化路径形式的更丰富校验:当前可失败初始化器只拒绝普遍非法的 NUL;遗留设备名、长度限制、受限字符集等校验是应用相关的,未来可把校验暴露为可配置检查而非把单一策略固化进类型。
  • 平台专属 Anchor API:Anchor 适合进一步平台专属分解与分析(提案给出了 strawperson 设计)。
  • 平台字符串 API 与 CInterop:swift-system 定义了 CInterop 命名空间(PlatformChar、PlatformUnicodeEncoding)与 init(platformString:);本提案提供 withCodeUnits(_:) 与各子类型的 Span 访问。若语言获得 NUL 结尾指针类型的标准故事(生命周期绑定的借用指针等),FilePath 可暴露 var cString 属性取代闭包式 withCodeUnits(_:)。
  • 路径解析 API 与 verbatim 存储模式:暴露内部解析器以支持借用存储(如 Span)上的就地解析;日志与诊断场景可能受益于保留原始字节的 verbatim 存储模式(FilePath 的弹性足以在未来添加)。
  • SystemString:swift-system 内部为 FilePath 提供底层存储的 SystemString 类型,未来可能作为公共类型独立发布。
  • 更多路径类型与文件系统专属功能:类型强化不变量的 AbsolutePath、ResolvedPath;平台专属外来路径类型 XNUPath、Win32Path、WinNTPath;跨平台可失败转换(如 POSIX 路径转 Windows 路径并诊断不可表示部分);存储泛型的路径类型;组件上的大小写转换、Unicode 归一化等文件系统(及配置)专属功能。FilePath 是"当前运行平台"路径的货币类型,多平台路径库服务不同角色(如在 macOS 上处理 Windows 路径的构建工具),两者约束不同、应分离以保持货币类型简单。
  • 遗留设备名处理:Windows 遗留设备名(CON、NUL、COM1 等)在 Win32 层受特殊处理且随版本而异,未来可添加检测或缓解,可能作为 resolve-beneath 或沙箱 API 的一部分。

备选方案回顾

  • 在 Swift 6.4 做更多:原 pitch 含 FilePath.Root、便捷方法(lastComponent、stem、extension、starts(with:)、append、push)与词法解析。决定先落地核心(类型、协议遵循、组件视图、真实解析),因为类型与协议遵循无法事后追溯添加(否则会有迁移成本,如有人自行让 FilePath 遵循 Hashable);延迟 API 可作为扩展添加且可回部署。
  • resolve() 的其它命名:resolveByBlocking()(把阻塞写进名字,但更倾向用 @available(*, noasync) 与文档传达)、resolveFromFileSystem()(冗余,解析本来就是 resolve() 的默认含义)、resolveSync()/resolveAsync() 成对命名(未来 async 版本仍用 resolve 同名重载)、命名空间自由函数(成员形式更利于可发现性与同类类型对齐)。最终采用 resolve(),阻塞性质由 @available(*, noasync) 与文档传达。
  • Anchor.driveLetter 的类型:依次考虑 Character、String,最终选 Unicode.Scalar——盘符是冒号前单个 WTF-16 码元,Character(字素簇)与 String 都夸大其结构;Unicode.Scalar 是三者中最窄且仍可作字面量比较、可干净转换为 FilePath.CodeUnit 与 String。同时决定不把盘符规范化为大写:常见 A-Z 折叠平凡,但盘符可以是任意码元,其余部分的大小写不敏感匹配依赖系统 Unicode upcase 表(解析期运行时资源),FilePath 保持原样并推迟大小写不敏感匹配。
  • 加入 Codable 遵循:刻意不做。序列化路径本质上是平台专属的(Linux/Darwin 序列化的路径在 Windows 上无意义),且同一平台不同 OS 版本间路径含义可能变化(Windows 10/11 设备名识别不同、Darwin 可能新增 resolve flag 值)。System.FilePath 现有的 Codable 遵循采用笨拙的二进制编码且一直是摩擦源。序列化留给应用层,String(decoding:) 与 init?(_ string:) 提供必要转换。
  • 把整个 swift-system 引入 toolchain:FilePath 与 FileDescriptor、Errno 等不同——它贯穿整个技术栈(内核级编程到高层脚本自动化),值得单独先行;syscall 如 FilePath.stat 仍留在 System/SystemPackage。
  • 放进单独的标准库模块:FilePath 可放入随 toolchain 发布但需显式 import 的新模块,但货币类型一旦需要 import 就价值大减——String、Array、Int、Result 都在 Swift 模块,FilePath 也应如此。
  • 使用 Foundation 的 URL:URL 面向 URI 语义(scheme 解析、百分号编码),与路径结构、不变式不同;URL(fileURLWithPath:) 与 URL.appendingPathComponent 会做阻塞文件系统调用,对看似纯数据的类型很意外;Linux/Darwin 上含非 UTF-8 字节的路径无法无损进入需要百分号编码的 file:// URL;且 Foundation 在依赖栈高处,Swift 运行时与 toolchain 组件无法依赖它。
  • 什么都不做:每个需要命名文件的新 API 继续使用 String,延续 FilePath 本要解决的"结构丢失、平台不正确、类型不安全"。

总结

SE-0529 为 Swift 标准库引入了以 FilePath 为货币类型的完整路径抽象:Anchor 承载跨平台差异最大的"参考点"语义,Component 与 ComponentView 提供归一化的组件级操作,尾部分隔符与 resource fork 后缀保证 syscall 级语义不被丢失,resolve() 提供内核背书的真解析,withCodeUnits(_:) 与 Span 家族打通 C 互操作。它同时为 swift-system 用户提供了清晰的迁移路径(条件 typealias + ABI 重定向),并为未来的句法操作、词法解析、非阻塞解析等预留了弹性空间。对任何在 Swift 中处理文件路径的开发者而言,FilePath 都是值得立即采用的类型——正如仓库中 SE-0513 所示,CommandLine.executablePath 这类新 API 已经选择以 FilePath 作为返回类型,而不是 String。

登录后查看全文
swift-evolution