swift-language

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Swift Language Patterns

Swift 语言模式

Core Swift language features and modern syntax patterns targeting Swift 5.9+ through Swift 6. Covers language constructs, type system features, Codable, string and collection APIs, and formatting. For concurrency (actors, async/await, Sendable), see the

swift-concurrency

skill. For SwiftUI views and state management, see

swiftui-patterns

针对Swift 5.9+到Swift 6版本的核心Swift语言特性与现代语法模式。涵盖语言构造、类型系统特性、Codable、字符串与集合API以及格式化相关内容。如需了解并发相关内容（actors、async/await、Sendable），请查看

swift-concurrency

技能。如需了解SwiftUI视图与状态管理，请查看

swiftui-patterns

。

If/Switch Expressions

If/Switch 表达式

Swift 5.9+ allows

if

and

switch

as expressions that return values. Use them to assign, return, or initialize directly.

swift

// Assign from if expression
let icon = if isComplete { "checkmark.circle.fill" } else { "circle" }

// Assign from switch expression
let label = switch status {
case .draft: "Draft"
case .published: "Published"
case .archived: "Archived"
}

// Works in return position
func color(for priority: Priority) -> Color {
    switch priority {
    case .high: .red
    case .medium: .orange
    case .low: .green
    }
}

Rules:

Every branch must produce a value of the same type.
Multi-statement branches are not allowed -- each branch is a single expression.
Wrap in parentheses when used as a function argument to avoid ambiguity.

Swift 5.9+允许将

if

和

switch

作为返回值的表达式。可直接用于赋值、返回值或者初始化操作。

swift

// Assign from if expression
let icon = if isComplete { "checkmark.circle.fill" } else { "circle" }

// Assign from switch expression
let label = switch status {
case .draft: "Draft"
case .published: "Published"
case .archived: "Archived"
}

// Works in return position
func color(for priority: Priority) -> Color {
    switch priority {
    case .high: .red
    case .medium: .orange
    case .low: .green
    }
}

规则：

每个分支必须返回相同类型的值。
不支持多语句分支——每个分支只能是单个表达式。
作为函数参数使用时需要用括号包裹，避免歧义。

Typed Throws

Swift 6+ allows specifying the error type a function throws.

swift

enum ValidationError: Error {
    case tooShort, invalidCharacters, alreadyTaken
}

func validate(username: String) throws(ValidationError) -> String {
    guard username.count >= 3 else { throw .tooShort }
    guard username.allSatisfy(\.isLetterOrDigit) else { throw .invalidCharacters }
    return username.lowercased()
}

// Caller gets typed error -- no cast needed
do {
    let name = try validate(username: input)
} catch {
    // error is ValidationError, not any Error
    switch error {
    case .tooShort: print("Too short")
    case .invalidCharacters: print("Invalid characters")
    case .alreadyTaken: print("Taken")
    }
}

Rules:

Use
```
throws(SomeError)
```
only when callers benefit from exhaustive error handling. For mixed error sources, use untyped
```
throws
```
.
```
throws(Never)
```
marks a function that syntactically throws but never actually does -- useful in generic contexts.
Typed throws propagate: a function calling
```
throws(A)
```
and
```
throws(B)
```
must itself throw a type that covers both (or use untyped
```
throws
```
).

Swift 6+支持指定函数抛出的错误类型。

swift

enum ValidationError: Error {
    case tooShort, invalidCharacters, alreadyTaken
}

func validate(username: String) throws(ValidationError) -> String {
    guard username.count >= 3 else { throw .tooShort }
    guard username.allSatisfy(\.isLetterOrDigit) else { throw .invalidCharacters }
    return username.lowercased()
}

// Caller gets typed error -- no cast needed
do {
    let name = try validate(username: input)
} catch {
    // error is ValidationError, not any Error
    switch error {
    case .tooShort: print("Too short")
    case .invalidCharacters: print("Invalid characters")
    case .alreadyTaken: print("Taken")
    }
}

规则：

仅当调用方能从穷尽错误处理中获益时，才使用
```
throws(SomeError)
```
。如果存在多个错误来源，使用无类型的
```
throws
```
。
```
throws(Never)
```
标记语法上支持抛出但实际永远不会抛出错误的函数——适用于泛型场景。
类型化错误会传递：调用了
```
throws(A)
```
和
```
throws(B)
```
的函数，自身抛出的错误类型必须覆盖两者（或者使用无类型
```
throws
```
）。

Result Builders

@resultBuilder

enables DSL-style syntax. SwiftUI's

@ViewBuilder

is the most common example, but you can create custom builders for any domain.

swift

@resultBuilder
struct ArrayBuilder<Element> {
    static func buildBlock(_ components: [Element]...) -> [Element] {
        components.flatMap { $0 }
    }
    static func buildExpression(_ expression: Element) -> [Element] { [expression] }
    static func buildOptional(_ component: [Element]?) -> [Element] { component ?? [] }
    static func buildEither(first component: [Element]) -> [Element] { component }
    static func buildEither(second component: [Element]) -> [Element] { component }
    static func buildArray(_ components: [[Element]]) -> [Element] { components.flatMap { $0 } }
}

func makeItems(@ArrayBuilder<String> content: () -> [String]) -> [String] { content() }

let items = makeItems {
    "Always included"
    if showExtra { "Conditional" }
    for name in names { name.uppercased() }
}

Builder methods:

buildBlock

(combine statements),

buildExpression

(single value),

buildOptional

(

if

without

else

buildEither

(

if/else

buildArray

(

for..in

buildFinalResult

(optional post-processing).

@resultBuilder

支持DSL风格的语法。SwiftUI的

@ViewBuilder

是最常见的例子，你也可以为任意领域自定义builder。

swift

@resultBuilder
struct ArrayBuilder<Element> {
    static func buildBlock(_ components: [Element]...) -> [Element] {
        components.flatMap { $0 }
    }
    static func buildExpression(_ expression: Element) -> [Element] { [expression] }
    static func buildOptional(_ component: [Element]?) -> [Element] { component ?? [] }
    static func buildEither(first component: [Element]) -> [Element] { component }
    static func buildEither(second component: [Element]) -> [Element] { component }
    static func buildArray(_ components: [[Element]]) -> [Element] { components.flatMap { $0 } }
}

func makeItems(@ArrayBuilder<String> content: () -> [String]) -> [String] { content() }

let items = makeItems {
    "Always included"
    if showExtra { "Conditional" }
    for name in names { name.uppercased() }
}

Builder方法：

buildBlock

（组合语句）、

buildExpression

（单个值）、

buildOptional

（不带else的if）、

buildEither

（if/else）、

buildArray

（for..in）、

buildFinalResult

（可选的后置处理）。

Property Wrappers

Custom

@propertyWrapper

types encapsulate storage and access patterns.

swift

@propertyWrapper
struct Clamped<Value: Comparable> {
    private var value: Value
    let range: ClosedRange<Value>

    var wrappedValue: Value {
        get { value }
        set { value = min(max(newValue, range.lowerBound), range.upperBound) }
    }

    var projectedValue: ClosedRange<Value> { range }

    init(wrappedValue: Value, _ range: ClosedRange<Value>) {
        self.range = range
        self.value = min(max(wrappedValue, range.lowerBound), range.upperBound)
    }
}

// Usage
struct Volume {
    @Clamped(0...100) var level: Int = 50
}

var v = Volume()
v.level = 150   // clamped to 100
print(v.$level) // projected value: 0...100

Design rules:

```
wrappedValue
```
is the primary getter/setter.
```
projectedValue
```
(accessed via
```
$property
```
) provides metadata or bindings.
Property wrappers can be composed:
```
@A @B var x
```
applies outer wrapper first.
Do not use property wrappers when a simple computed property suffices.

自定义

@propertyWrapper

类型可以封装存储和访问逻辑。

swift

@propertyWrapper
struct Clamped<Value: Comparable> {
    private var value: Value
    let range: ClosedRange<Value>

    var wrappedValue: Value {
        get { value }
        set { value = min(max(newValue, range.lowerBound), range.upperBound) }
    }

    var projectedValue: ClosedRange<Value> { range }

    init(wrappedValue: Value, _ range: ClosedRange<Value>) {
        self.range = range
        self.value = min(max(wrappedValue, range.lowerBound), range.upperBound)
    }
}

// Usage
struct Volume {
    @Clamped(0...100) var level: Int = 50
}

var v = Volume()
v.level = 150   // clamped to 100
print(v.$level) // projected value: 0...100

设计规则：

```
wrappedValue
```
是主要的取值/赋值方法。
```
projectedValue
```
（通过
```
$property
```
访问）提供元数据或绑定。
Property Wrapper可以组合使用：
```
@A @B var x
```
会先应用外层的wrapper。
简单计算属性就能满足需求时不要使用Property Wrapper。

Opaque and Existential Types

不透明类型与存在类型

some Protocol

(Opaque Type)

some Protocol

（不透明类型）

The caller does not know the concrete type, but the compiler does. The underlying type is fixed for a given scope.

swift

func makeCollection() -> some Collection<Int> {
    [1, 2, 3]  // Always returns Array<Int> -- compiler knows the concrete type
}

Use

some

for:

Return types when you want to hide implementation but preserve type identity.

Parameter types (Swift 5.9+):

func process(_ items: some Collection<Int>)

-- equivalent to a generic

<C: Collection<Int>>

调用方不知道具体类型，但编译器知道。在给定作用域内底层类型是固定的。

swift

func makeCollection() -> some Collection<Int> {
    [1, 2, 3]  // Always returns Array<Int> -- compiler knows the concrete type
}

some

适用于：

你希望隐藏实现但保留类型标识的返回值场景。

参数类型（Swift 5.9+）：

func process(_ items: some Collection<Int>)

——等价于泛型

<C: Collection<Int>>

。

any Protocol

(Existential Type)

any Protocol

（存在类型）

An existential box that can hold any conforming type at runtime. Has overhead from dynamic dispatch and heap allocation.

swift

func process(items: [any StringProtocol]) {
    for item in items {
        print(item.uppercased())
    }
}

存在类型容器可以在运行时存储任意符合协议的类型。存在动态派发和堆分配的开销。

swift

func process(items: [any StringProtocol]) {
    for item in items {
        print(item.uppercased())
    }
}

When to choose

选型建议

Use `some`	Use `any`
Return type hiding concrete type	Heterogeneous collections
Function parameters (replaces simple generics)	Dynamic type erasure needed
Better performance (static dispatch)	Protocol has `Self` or associated type requirements you need to erase

Rule of thumb: Default to

some

. Use

any

only when you need a heterogeneous collection or runtime type flexibility.

使用 `some`	使用 `any`
隐藏具体类型的返回值	异构集合
函数参数（替代简单泛型）	需要动态类型擦除
性能更好（静态派发）	协议带有 `Self` 或关联类型要求，需要进行擦除

经验法则： 默认优先使用

some

。仅当你需要异构集合或者运行时类型灵活性时才使用

any

。

Guard Patterns

Guard 模式

guard

enforces preconditions and enables early exit. It keeps the happy path left-aligned and reduces nesting.

swift

func processOrder(_ order: Order?) throws -> Receipt {
    // Unwrap optionals
    guard let order else { throw OrderError.missing }

    // Validate conditions
    guard order.items.isEmpty == false else { throw OrderError.empty }
    guard order.total > 0 else { throw OrderError.invalidTotal }

    // Boolean checks
    guard order.isPaid else { throw OrderError.unpaid }

    // Pattern matching
    guard case .confirmed(let date) = order.status else {
        throw OrderError.notConfirmed
    }

    return Receipt(order: order, confirmedAt: date)
}

Best practices:

Use
```
guard
```
for preconditions,
```
if
```
for branching logic.
Combine related guards:
```
guard let a, let b else { return }
```
.

The

else

block must exit scope:

return

throw

continue

break

, or

fatalError()

Use shorthand unwrap:
```
guard let value else { ... }
```
(Swift 5.7+).

guard

用于强制前置条件，支持提前退出。可以让正常逻辑保持左对齐，减少嵌套层级。

swift

func processOrder(_ order: Order?) throws -> Receipt {
    // Unwrap optionals
    guard let order else { throw OrderError.missing }

    // Validate conditions
    guard order.items.isEmpty == false else { throw OrderError.empty }
    guard order.total > 0 else { throw OrderError.invalidTotal }

    // Boolean checks
    guard order.isPaid else { throw OrderError.unpaid }

    // Pattern matching
    guard case .confirmed(let date) = order.status else {
        throw OrderError.notConfirmed
    }

    return Receipt(order: order, confirmedAt: date)
}

最佳实践：

前置条件校验用
```
guard
```
，分支逻辑用
```
if
```
。
合并相关的guard语句：
```
guard let a, let b else { return }
```
。
```
else
```
代码块必须退出当前作用域：
```
return
```
、
```
throw
```
、
```
continue
```
、
```
break
```
或者
```
fatalError()
```
。
使用简写解包：
```
guard let value else { ... }
```
（Swift 5.7+）。

Never Type

Never 类型

Never

indicates a function that never returns. It conforms to all protocols since Swift 5.5+ (bottom type).

swift

// Function that terminates the program
func crashWithDiagnostics(_ message: String) -> Never {
    let diagnostics = gatherDiagnostics()
    logger.critical("\(message): \(diagnostics)")
    fatalError(message)
}

// Useful in generic contexts
enum Result<Success, Failure: Error> {
    case success(Success)
    case failure(Failure)
}
// Result<String, Never> -- a result that can never fail
// Result<Never, Error>  -- a result that can never succeed

// Exhaustive switch: no default needed since Never has no cases
func handle(_ result: Result<String, Never>) {
    switch result {
    case .success(let value): print(value)
    // No .failure case needed -- compiler knows it's impossible
    }
}

Never

表示函数永远不会返回。从Swift 5.5+开始它符合所有协议（底类型）。

swift

// Function that terminates the program
func crashWithDiagnostics(_ message: String) -> Never {
    let diagnostics = gatherDiagnostics()
    logger.critical("\(message): \(diagnostics)")
    fatalError(message)
}

// Useful in generic contexts
enum Result<Success, Failure: Error> {
    case success(Success)
    case failure(Failure)
}
// Result<String, Never> -- a result that can never fail
// Result<Never, Error>  -- a result that can never succeed

// Exhaustive switch: no default needed since Never has no cases
func handle(_ result: Result<String, Never>) {
    switch result {
    case .success(let value): print(value)
    // No .failure case needed -- compiler knows it's impossible
    }
}

Regex Builders

Swift 5.7+ Regex builder DSL provides compile-time checked, readable patterns.

swift

import RegexBuilder

// Parse "2024-03-15" into components
let dateRegex = Regex {
    Capture { /\d{4}/ }; "-"; Capture { /\d{2}/ }; "-"; Capture { /\d{2}/ }
}

if let match = "2024-03-15".firstMatch(of: dateRegex) {
    let (_, year, month, day) = match.output
}

// TryCapture with transform
let priceRegex = Regex {
    "$"
    TryCapture { OneOrMore(.digit); "."; Repeat(.digit, count: 2) }
        transform: { Decimal(string: String($0)) }
}

When to use builder vs. literal:

Builder: complex patterns, reusable components, strong typing on captures.
Literal (
```
/pattern/
```
): simple patterns, familiarity with regex syntax.
Both can be mixed: embed
```
/.../
```
literals inside builder blocks.

Swift 5.7+的Regex builder DSL提供编译时校验、可读性更强的模式。

swift

import RegexBuilder

// Parse "2024-03-15" into components
let dateRegex = Regex {
    Capture { /\d{4}/ }; "-"; Capture { /\d{2}/ }; "-"; Capture { /\d{2}/ }
}

if let match = "2024-03-15".firstMatch(of: dateRegex) {
    let (_, year, month, day) = match.output
}

// TryCapture with transform
let priceRegex = Regex {
    "$"
    TryCapture { OneOrMore(.digit); "."; Repeat(.digit, count: 2) }
        transform: { Decimal(string: String($0)) }
}

什么时候用builder还是字面量：

Builder：复杂模式、可复用组件、捕获值强类型校验。
字面量（
```
/pattern/
```
）：简单模式、熟悉正则语法的场景。
两者可以混合使用：在builder块中嵌入
```
/.../
```
字面量。

Codable Best Practices

Codable 最佳实践

Custom CodingKeys

自定义CodingKeys

Rename keys without writing a custom decoder:

swift

struct User: Codable {
    let id: Int
    let displayName: String
    let avatarURL: URL

    enum CodingKeys: String, CodingKey {
        case id
        case displayName = "display_name"
        case avatarURL = "avatar_url"
    }
}

无需编写自定义解码器即可重命名键名：

swift

struct User: Codable {
    let id: Int
    let displayName: String
    let avatarURL: URL

    enum CodingKeys: String, CodingKey {
        case id
        case displayName = "display_name"
        case avatarURL = "avatar_url"
    }
}

Custom Decoding

自定义解码

Handle mismatched types, defaults, and transformations:

swift

struct Item: Decodable {
    let name: String
    let quantity: Int
    let isActive: Bool

    init(from decoder: Decoder) throws {
        let container = try decoder.container(keyedBy: CodingKeys.self)
        name = try container.decode(String.self, forKey: .name)
        quantity = try container.decodeIfPresent(Int.self, forKey: .quantity) ?? 0
        if let boolValue = try? container.decode(Bool.self, forKey: .isActive) {
            isActive = boolValue
        } else {
            isActive = (try container.decode(String.self, forKey: .isActive)).lowercased() == "true"
        }
    }
    enum CodingKeys: String, CodingKey { case name, quantity; case isActive = "is_active" }
}

处理类型不匹配、默认值和转换逻辑：

swift

struct Item: Decodable {
    let name: String
    let quantity: Int
    let isActive: Bool

    init(from decoder: Decoder) throws {
        let container = try decoder.container(keyedBy: CodingKeys.self)
        name = try container.decode(String.self, forKey: .name)
        quantity = try container.decodeIfPresent(Int.self, forKey: .quantity) ?? 0
        if let boolValue = try? container.decode(Bool.self, forKey: .isActive) {
            isActive = boolValue
        } else {
            isActive = (try container.decode(String.self, forKey: .isActive)).lowercased() == "true"
        }
    }
    enum CodingKeys: String, CodingKey { case name, quantity; case isActive = "is_active" }
}

Nested Containers

嵌套容器

Flatten nested JSON into a flat Swift struct:

swift

// JSON: { "id": 1, "metadata": { "created_at": "...", "tags": [...] } }
struct Record: Decodable {
    let id: Int
    let createdAt: String
    let tags: [String]

    enum CodingKeys: String, CodingKey {
        case id, metadata
    }

    enum MetadataKeys: String, CodingKey {
        case createdAt = "created_at"
        case tags
    }

    init(from decoder: Decoder) throws {
        let container = try decoder.container(keyedBy: CodingKeys.self)
        id = try container.decode(Int.self, forKey: .id)
        let metadata = try container.nestedContainer(
            keyedBy: MetadataKeys.self, forKey: .metadata)
        createdAt = try metadata.decode(String.self, forKey: .createdAt)
        tags = try metadata.decode([String].self, forKey: .tags)
    }
}

See

references/swift-patterns-extended.md

for additional Codable patterns (enums with associated values, date strategies, unkeyed containers).

将嵌套JSON扁平化解析为单层Swift结构体：

swift

// JSON: { "id": 1, "metadata": { "created_at": "...", "tags": [...] } }
struct Record: Decodable {
    let id: Int
    let createdAt: String
    let tags: [String]

    enum CodingKeys: String, CodingKey {
        case id, metadata
    }

    enum MetadataKeys: String, CodingKey {
        case createdAt = "created_at"
        case tags
    }

    init(from decoder: Decoder) throws {
        let container = try decoder.container(keyedBy: CodingKeys.self)
        id = try container.decode(Int.self, forKey: .id)
        let metadata = try container.nestedContainer(
            keyedBy: MetadataKeys.self, forKey: .metadata)
        createdAt = try metadata.decode(String.self, forKey: .createdAt)
        tags = try metadata.decode([String], forKey: .tags)
    }
}

更多Codable模式（带关联值的枚举、日期策略、无键容器）请查看

references/swift-patterns-extended.md

。

Modern Collection APIs

现代集合 API

Prefer these modern APIs over manual loops:

swift

let numbers = [1, 2, 3, 4, 5, 6, 7, 8]

// count(where:) -- Swift 5.0+, use instead of .filter { }.count
let evenCount = numbers.count(where: { $0.isMultiple(of: 2) })

// contains(where:) -- short-circuits on first match
let hasNegative = numbers.contains(where: { $0 < 0 })

// first(where:) / last(where:)
let firstEven = numbers.first(where: { $0.isMultiple(of: 2) })

// String replacing() -- Swift 5.7+, returns new string
let cleaned = rawText.replacing(/\s+/, with: " ")
let snakeCase = name.replacing("_", with: " ")

// compactMap -- unwrap optionals from a transform
let ids = strings.compactMap { Int($0) }

// flatMap -- flatten nested collections
let allTags = articles.flatMap(\.tags)

// Dictionary(grouping:by:)
let byCategory = Dictionary(grouping: items, by: \.category)

// reduce(into:) -- efficient accumulation
let freq = words.reduce(into: [:]) { counts, word in
    counts[word, default: 0] += 1
}

优先使用这些现代API替代手动循环：

swift

let numbers = [1, 2, 3, 4, 5, 6, 7, 8]

// count(where:) -- Swift 5.0+, use instead of .filter { }.count
let evenCount = numbers.count(where: { $0.isMultiple(of: 2) })

// contains(where:) -- short-circuits on first match
let hasNegative = numbers.contains(where: { $0 < 0 })

// first(where:) / last(where:)
let firstEven = numbers.first(where: { $0.isMultiple(of: 2) })

// String replacing() -- Swift 5.7+, returns new string
let cleaned = rawText.replacing(/\s+/, with: " ")
let snakeCase = name.replacing("_", with: " ")

// compactMap -- unwrap optionals from a transform
let ids = strings.compactMap { Int($0) }

// flatMap -- flatten nested collections
let allTags = articles.flatMap(\.tags)

// Dictionary(grouping:by:)
let byCategory = Dictionary(grouping: items, by: \.category)

// reduce(into:) -- efficient accumulation
let freq = words.reduce(into: [:]) { counts, word in
    counts[word, default: 0] += 1
}

FormatStyle

Use

.formatted()

instead of

DateFormatter

NumberFormatter

. It is type-safe, localized, and concise.

swift

// Dates
let now = Date.now
now.formatted()                                       // "3/15/2024, 2:30 PM"
now.formatted(date: .abbreviated, time: .shortened)   // "Mar 15, 2024, 2:30 PM"
now.formatted(.dateTime.year().month().day())          // "Mar 15, 2024"
now.formatted(.relative(presentation: .named))        // "yesterday"

// Numbers
let price = 42.5
price.formatted(.currency(code: "USD"))               // "$42.50"
price.formatted(.percent)                             // "4,250%"
(1_000_000).formatted(.number.notation(.compactName)) // "1M"

// Measurements
let distance = Measurement(value: 5, unit: UnitLength.kilometers)
distance.formatted(.measurement(width: .abbreviated)) // "5 km"

// Duration (Swift 5.7+)
let duration = Duration.seconds(3661)
duration.formatted(.time(pattern: .hourMinuteSecond)) // "1:01:01"

// Byte counts
Int64(1_500_000).formatted(.byteCount(style: .file)) // "1.5 MB"

// Lists
["Alice", "Bob", "Carol"].formatted(.list(type: .and)) // "Alice, Bob, and Carol"

Parsing:

FormatStyle

also supports parsing:

swift

let value = try Decimal("$42.50", format: .currency(code: "USD"))
let date = try Date("Mar 15, 2024", strategy: .dateTime.month().day().year())

使用

.formatted()

替代

DateFormatter

NumberFormatter

。它类型安全、支持本地化、语法简洁。

swift

// Dates
let now = Date.now
now.formatted()                                       // "3/15/2024, 2:30 PM"
now.formatted(date: .abbreviated, time: .shortened)   // "Mar 15, 2024, 2:30 PM"
now.formatted(.dateTime.year().month().day())          // "Mar 15, 2024"
now.formatted(.relative(presentation: .named))        // "yesterday"

// Numbers
let price = 42.5
price.formatted(.currency(code: "USD"))               // "$42.50"
price.formatted(.percent)                             // "4,250%"
(1_000_000).formatted(.number.notation(.compactName)) // "1M"

// Measurements
let distance = Measurement(value: 5, unit: UnitLength.kilometers)
distance.formatted(.measurement(width: .abbreviated)) // "5 km"

// Duration (Swift 5.7+)
let duration = Duration.seconds(3661)
duration.formatted(.time(pattern: .hourMinuteSecond)) // "1:01:01"

// Byte counts
Int64(1_500_000).formatted(.byteCount(style: .file)) // "1.5 MB"

// Lists
["Alice", "Bob", "Carol"].formatted(.list(type: .and)) // "Alice, Bob, and Carol"

解析：

FormatStyle

也支持解析：

swift

let value = try Decimal("$42.50", format: .currency(code: "USD"))
let date = try Date("Mar 15, 2024", strategy: .dateTime.month().day().year())

String Interpolation

字符串插值

Extend

DefaultStringInterpolation

for domain-specific formatting. Use

"""

for multi-line strings (indentation is relative to the closing

"""

). See

references/swift-patterns-extended.md

for custom interpolation examples.

扩展

DefaultStringInterpolation

实现领域特定的格式化。使用

"""

编写多行字符串（缩进相对于闭合的

"""

计算）。自定义插值示例请查看

references/swift-patterns-extended.md

。

Common Mistakes

常见错误

Using
any
when
some
works. Default to
```
some
```
for return types and parameters.
```
any
```
has runtime overhead and loses type information.
Manual loops instead of collection APIs. Use
```
count(where:)
```
,
```
contains(where:)
```
,
```
compactMap
```
,
```
flatMap
```
instead of manual iteration.
DateFormatter
instead of FormatStyle.
```
.formatted()
```
is simpler, type-safe, and handles localization automatically.
Force-unwrapping Codable decodes. Use
```
decodeIfPresent
```
with defaults for optional or missing keys.
Nested if-let chains. Use
```
guard let
```
for preconditions to keep the happy path at the top level.
String regex for simple operations. Use
```
.replacing()
```
and
```
.contains()
```
before reaching for Regex.
Ignoring typed throws. When a function has a single, clear error type, typed throws give callers exhaustive switch without casting.
Overusing property wrappers. A computed property is simpler when there is no reuse or projected value needed.
Building collections with
var
+
append
in a loop. Prefer
```
map
```
,
```
filter
```
,
```
compactMap
```
, or
```
reduce(into:)
```
.
Not using if/switch expressions. When assigning from a condition, use an expression instead of declaring
```
var
```
and mutating it.

能使用
some
的场景使用了
any
。返回值和参数默认优先使用
```
some
```
。
```
any
```
有运行时开销，还会丢失类型信息。
使用手动循环而不是集合API。使用
```
count(where:)
```
、
```
contains(where:)
```
、
```
compactMap
```
、
```
flatMap
```
替代手动遍历。
使用
DateFormatter
而不是FormatStyle。
```
.formatted()
```
更简单、类型安全，还能自动处理本地化。
强制解包Codable解码结果。可选或缺失的键使用
```
decodeIfPresent
```
加默认值。
嵌套if-let链。前置条件使用
```
guard let
```
让正常逻辑保持在顶层。
简单操作使用字符串正则。使用正则前优先考虑
```
.replacing()
```
和
```
.contains()
```
。
忽略typed throws。当函数只有单一明确的错误类型时，typed throws让调用方无需类型转换即可做穷尽switch判断。
过度使用property wrappers。没有复用需求或者不需要projected value时，计算属性更简单。
在循环中使用
var
+
append
构建集合。优先使用
```
map
```
、
```
filter
```
、
```
compactMap
```
或者
```
reduce(into:)
```
。
不使用if/switch表达式。根据条件赋值时，使用表达式代替声明
```
var
```
再修改的写法。

Review Checklist

评审检查清单

```
some
```
used over
```
any
```
where possible
```
guard
```
used for preconditions, not nested
```
if let
```
Collection APIs used instead of manual loops

.formatted()

used instead of

DateFormatter

NumberFormatter

Codable types use
```
CodingKeys
```
for API key mapping
```
decodeIfPresent
```
with defaults for optional JSON fields
if/switch expressions used for simple conditional assignment
Property wrappers have clear reuse justification
Regex builder used for complex patterns (literal OK for simple ones)
String interpolation is clean -- no unnecessary
```
String(describing:)
```
Typed throws used when callers benefit from exhaustive error handling
```
Never
```
used appropriately in generic contexts

尽可能使用
```
some
```
而非
```
any
```
前置条件使用
```
guard
```
，而非嵌套
```
if let
```
使用集合API替代手动循环

使用

.formatted()

替代

DateFormatter

NumberFormatter

Codable类型使用
```
CodingKeys
```
做API键映射
可选JSON字段使用
```
decodeIfPresent
```
加默认值
简单条件赋值使用if/switch表达式
Property Wrapper有明确的复用理由
复杂模式使用Regex builder（简单模式用字面量即可）
字符串插值简洁——没有不必要的
```
String(describing:)
```
调用方能从穷尽错误处理中获益时使用typed throws
泛型场景中合理使用
```
Never
```

References

参考资料

Extended patterns and Codable examples:
```
references/swift-patterns-extended.md
```

扩展模式与Codable示例：
```
references/swift-patterns-extended.md
```

swift-language

Original

Translation

Swift Language Patterns

Swift 语言模式

Contents

目录

If/Switch Expressions

If/Switch 表达式

Typed Throws

Typed Throws

Result Builders

Result Builders

Property Wrappers

Property Wrappers

Opaque and Existential Types

不透明类型与存在类型

some Protocol (Opaque Type)

some Protocol（不透明类型）

any Protocol (Existential Type)

any Protocol（存在类型）

When to choose

选型建议

Guard Patterns

Guard 模式

Never Type

Never 类型

Regex Builders

Regex Builders

Codable Best Practices

Codable 最佳实践

Custom CodingKeys

自定义CodingKeys

Custom Decoding

自定义解码

Nested Containers

嵌套容器

Modern Collection APIs

现代集合 API

FormatStyle

FormatStyle

String Interpolation

字符串插值

Common Mistakes

常见错误

Review Checklist

评审检查清单

References

参考资料

`some Protocol`
(Opaque Type)

`some Protocol`
（不透明类型）

`any Protocol`
(Existential Type)

`any Protocol`
（存在类型）