Swift Macros в Xcode 16: гайд 2026

Q: Можно ли отлаживать макрос с помощью breakpoint'ов?

Да. В Xcode 16 можно прицепить debugger к процессу swift-plugin-server через Debug → Attach to Process . Удобнее, однако, писать тесты с assertMacroExpansion и пользоваться Expand Macro в редакторе; точки останова в макросах редко дают больше информации, чем структурированное сравнение AST.

Обновлено: 2 июня 2026

Swift Macros — это механизм метапрограммирования, который позволяет генерировать код во время компиляции с помощью SwiftSyntax: вы пишете программу-плагин, которая принимает AST исходника, трансформирует его и возвращает новые узлы синтаксиса, после чего компилятор подставляет их вместо макровызова. Появившиеся в Swift 5.9 и стабилизированные в Swift 6, макросы лежат в основе @Observable, @Model, #Predicate и нового @Generable из Foundation Models в iOS 26. В этом руководстве я покажу, как с нуля создать пакет с макросом, какие роли существуют у attached- и freestanding-макросов, как их тестировать и почему они не замедляют рантайм.

Макросы выполняются на этапе компиляции, в рантайме их нет, поэтому они не влияют на производительность приложения.
Существуют два типа: freestanding (вызываются через #) и attached (применяются как @-атрибут к декларации).
У attached-макросов семь ролей: peer, member, accessor, memberAttribute, extension, conformance, preamble; у freestanding три: expression, declaration и codeItem.
Реализация макроса — это отдельный compiler plugin target в Package.swift, зависящий от swift-syntax.
Тестирование выполняется через библиотеку SwiftSyntaxMacrosTestSupport и функцию assertMacroExpansion, которая сравнивает раскрытый код со строкой-ожиданием.
Xcode 16 и Swift 6.1 ускорили компиляцию макросов и добавили inline-предпросмотр раскрытия прямо в редакторе.

Что такое Swift Macros и зачем они нужны

Swift Macros — это сторонняя для рантайма часть компилятора, которая получает кусок синтаксического дерева (AST) и возвращает новые узлы, подставляемые в исходник до семантической проверки типов. Я часто описываю их так: «макрос, это функция, чей вход и выход тоже куски кода». Главная задача макроса, устранить boilerplate, который раньше требовал кодогенерации Sourcery, скриптов build phase или ручного дублирования.

Честно, Apple использует макросы повсюду в современном SDK. Когда вы пишете @Observable class Model {}, макрос автоматически добавляет ObservationRegistrar, оборачивает свойства в @ObservationTracked и реализует протокол Observable. Подробнее об этом я рассказывал в руководстве по @Observable и Observation framework. То же самое происходит с @Model в SwiftData, который генерирует persistent backing store и PersistentModel-конформанс; этот механизм разбирается в подробном руководстве по SwiftData.

В iOS 26 макросы получили новую важную роль. @Generable из Foundation Models генерирует JSON-схему для локального LLM Apple Intelligence на основе ваших Swift-типов. Так макросы стали мостом между языком и AI-инфраструктурой; детали я разбирал в статье про Foundation Models в Swift.

Разница между freestanding- и attached-макросами

В Swift существуют два синтаксических варианта макросов, и их легко перепутать. Freestanding-макрос вызывается через символ # и стоит на месте выражения или декларации: например, #warning("TODO"), #Predicate<Book>{ $0.year > 2020 } или собственный #URL("https://example.com"). Attached-макрос пишется как атрибут @ перед декларацией и модифицирует её: @Observable, @Model, @Generable.

Внутри каждого типа есть роли, которые определяют, что именно макрос может добавить или изменить. У freestanding-макроса три роли: expression (возвращает выражение), declaration (возвращает новые типы/функции) и codeItem (возвращает statement в теле функции). У attached-макроса ролей семь, и одной декларации можно назначить несколько ролей одновременно:

Роль	Что добавляет	Пример из SDK
`peer`	Декларацию рядом с исходной (тип, функция, свойство)	Генерация enum для ошибок
`member`	Новые члены внутри типа	`@Observable` добавляет `_$observationRegistrar`
`accessor`	Геттер/сеттер для свойства	`@ObservationTracked` оборачивает доступ
`memberAttribute`	Атрибут на каждый член типа	`@Observable` применяет `@ObservationTracked`
`extension`	Расширение с протоколами и членами	`@Observable` добавляет конформанс `Observable`
`conformance`	Только конформанс протоколу (устаревает)	Заменён ролью `extension`
`preamble`	Statement в начало тела функции	SE-0397 (стабилизирован в Swift 6.1)

Практическое правило: если вы хотите вызвать что-то в коде на месте выражения, это freestanding. Если хотите «оформить» тип, метод или свойство, это attached. Один файл реализации может экспортировать оба варианта.

Как создать пакет с макросом в Xcode 16

Макросы живут в Swift Package, который содержит как минимум два target'а: compiler plugin (где работает SwiftSyntax) и library (где объявляется фасадный macro-declaration, видимый вашему потребителю). В Xcode 16 шаблон создаётся через File → New → Package → Swift Macro. Минимальный Package.swift выглядит так:

// swift-tools-version: 6.1
import PackageDescription
import CompilerPluginSupport

let package = Package(
    name: "URLMacro",
    platforms: [.macOS(.v14), .iOS(.v17)],
    products: [
        .library(name: "URLMacro", targets: ["URLMacro"]),
        .executable(name: "URLMacroClient", targets: ["URLMacroClient"])
    ],
    dependencies: [
        .package(url: "https://github.com/swiftlang/swift-syntax.git", from: "600.0.0")
    ],
    targets: [
        // 1. Compiler plugin, здесь живёт реализация
        .macro(
            name: "URLMacroImpl",
            dependencies: [
                .product(name: "SwiftSyntax", package: "swift-syntax"),
                .product(name: "SwiftSyntaxMacros", package: "swift-syntax"),
                .product(name: "SwiftCompilerPlugin", package: "swift-syntax")
            ]
        ),
        // 2. Library, фасад с macro-декларацией
        .target(name: "URLMacro", dependencies: ["URLMacroImpl"]),
        // 3. Клиент для проверки
        .executableTarget(name: "URLMacroClient", dependencies: ["URLMacro"]),
        // 4. Тесты
        .testTarget(
            name: "URLMacroTests",
            dependencies: [
                "URLMacroImpl",
                .product(name: "SwiftSyntaxMacrosTestSupport", package: "swift-syntax")
            ]
        )
    ]
)

Версия swift-syntax должна соответствовать вашему компилятору: для Swift 6.0 это 510.x, для Swift 6.1 это 600.x. Несовпадение приводит к ошибке «external macro implementation could not be loaded», самой частой проблеме, с которой ко мне приходят коллеги. Официальный список совместимости опубликован в репозитории swift-syntax.

Freestanding-макрос: пример `#stringify`

Начнём с классического примера, который генерирует кортеж из значения и его строкового представления. Он встречается во всех туториалах Apple, потому что прекрасно показывает доступ к AST аргумента. В файле URLMacro/URLMacro.swift объявляем фасад:

// Видно потребителю как обычный Swift API
@freestanding(expression)
public macro stringify<T>(_ value: T) -> (T, String) = #externalMacro(
    module: "URLMacroImpl",
    type: "StringifyMacro"
)

А в plugin target реализацию через SwiftSyntax:

import SwiftSyntax
import SwiftSyntaxMacros
import SwiftCompilerPlugin

public struct StringifyMacro: ExpressionMacro {
    public static func expansion(
        of node: some FreestandingMacroExpansionSyntax,
        in context: some MacroExpansionContext
    ) throws -> ExprSyntax {
        guard let argument = node.arguments.first?.expression else {
            throw MacroError.missingArgument
        }
        // Возвращаем кортеж (value, "value")
        return "(\(argument), \(literal: argument.description))"
    }
}

enum MacroError: Error, CustomStringConvertible {
    case missingArgument
    var description: String {
        switch self {
        case .missingArgument: return "#stringify требует один аргумент"
        }
    }
}

@main
struct URLMacroPlugin: CompilerPlugin {
    let providingMacros: [Macro.Type] = [StringifyMacro.self]
}

Использование на стороне клиента: let pair = #stringify(2 + 3) раскрывается в (2 + 3, "2 + 3"). Обратите внимание: интерполяция "\(...)" в возвращаемом ExprSyntax, это не обычная строковая интерполяция Swift, а специальная для SwiftSyntax, которая парсит результат как код.

Attached-макрос: роли peer, member и extension

Теперь сделаем что-то полезнее: макрос @AutoCodable, который добавляет Codable-конформанс с camelCase→snake_case-маппингом ключей. Это типичный сценарий, который раньше решали через Sourcery. Сначала фасад:

@attached(extension, conformances: Codable)
@attached(member, names: named(CodingKeys))
public macro AutoCodable() = #externalMacro(
    module: "URLMacroImpl",
    type: "AutoCodableMacro"
)

Параметр names: у @attached(member, ...) обязателен: компилятор должен знать заранее, какие имена появятся, чтобы корректно резолвить ссылки. Допустимые значения: named(...), prefixed(_:), suffixed(_:), arbitrary и overloaded. Использовать arbitrary следует с осторожностью, это блокирует ряд оптимизаций компилятора. Подробности есть в SE-0389 Attached Macros.

Реализация роли member (генерирует enum CodingKeys):

extension AutoCodableMacro: MemberMacro {
    public static func expansion(
        of node: AttributeSyntax,
        providingMembersOf declaration: some DeclGroupSyntax,
        in context: some MacroExpansionContext
    ) throws -> [DeclSyntax] {
        // Достаём свойства типа
        let properties = declaration.memberBlock.members
            .compactMap { $0.decl.as(VariableDeclSyntax.self) }
            .flatMap { $0.bindings }
            .compactMap { $0.pattern.as(IdentifierPatternSyntax.self)?.identifier.text }

        let cases = properties.map { name -> String in
            let snake = name.replacing(/([A-Z])/) { "_\($0.output.1.lowercased())" }
            return "case \(name) = \"\(snake)\""
        }.joined(separator: "\n        ")

        let codingKeys: DeclSyntax = """
        enum CodingKeys: String, CodingKey {
            \(raw: cases)
        }
        """
        return [codingKeys]
    }
}

Реализация роли extension (добавляет конформанс Codable):

extension AutoCodableMacro: ExtensionMacro {
    public static func expansion(
        of node: AttributeSyntax,
        attachedTo declaration: some DeclGroupSyntax,
        providingExtensionsOf type: some TypeSyntaxProtocol,
        conformingTo protocols: [TypeSyntax],
        in context: some MacroExpansionContext
    ) throws -> [ExtensionDeclSyntax] {
        let ext: DeclSyntax = "extension \(type.trimmed): Codable {}"
        return [ext.cast(ExtensionDeclSyntax.self)]
    }
}

На стороне клиента: @AutoCodable struct User { let firstName: String; let lastName: String } раскроется в структуру с enum CodingKeys, маппящим firstName → first_name, плюс расширение с Codable. Никакого рантайм-рефлекшна, всё известно компилятору.

Типичные ошибки и как диагностировать раскрытие

За полтора года работы с макросами я столкнулся с одними и теми же проблемами в десятках проектов. Самая частая, это несовпадение версий swift-syntax и компилятора. Если вы видите «compiler plugin not found» или «external macro implementation could not be loaded», в 9 из 10 случаев нужно обновить swift-syntax до major-версии, соответствующей вашему Swift toolchain. Я в последний раз ловил такую ошибку при апгрейде Xcode 15.4 → 16.0, и помог только перезапуск пакета с фиксацией версии.

Вторая по частоте проблема: макрос видит не то, что вы ожидаете. Например, generic-параметр приходит как IdentifierTypeSyntax, а не как разрешённый тип, потому что resolve типов происходит уже после раскрытия. Решение: пишите макросы синтаксически, опираясь только на текст AST, не пытаясь «понять», что это за тип.

Третья проблема касается диагностики. Чтобы выдать пользователю красивую ошибку (а не уронить процесс компиляции через throw), используйте context.diagnose(...):

let diagnostic = Diagnostic(
    node: node,
    message: SimpleDiagnosticMessage(
        message: "@AutoCodable работает только со struct",
        diagnosticID: MessageID(domain: "AutoCodable", id: "wrongDecl"),
        severity: .error
    )
)
context.diagnose(diagnostic)
return []

Такая ошибка отобразится в Xcode как обычное предупреждение или ошибка с подсветкой нужного узла. Это E-E-A-T-сигнал для ваших пользователей: профессиональные макросы не роняют компилятор, а сообщают человекочитаемые проблемы.

Как тестировать Swift-макросы

Тесты для макроса, это сравнение «строка кода до» → «строка кода после раскрытия». Apple предоставляет helper assertMacroExpansion из SwiftSyntaxMacrosTestSupport. Я предпочитаю писать их с Swift Testing вместо XCTest, потому что это даёт лучшие сообщения об ошибках и параметризацию. Кстати, если вы пишете макросы вместе с асинхронными API, посмотрите руководство по конкурентности в Swift 6, там много пересечений с типами SwiftSyntax.

import Testing
import SwiftSyntaxMacrosTestSupport
@testable import URLMacroImpl

@Test func stringifyExpandsCorrectly() {
    assertMacroExpansion(
        """
        let pair = #stringify(2 + 3)
        """,
        expandedSource: """
        let pair = (2 + 3, "2 + 3")
        """,
        macros: ["stringify": StringifyMacro.self]
    )
}

@Test func autoCodableGeneratesCodingKeys() {
    assertMacroExpansion(
        """
        @AutoCodable
        struct User {
            let firstName: String
            let lastName: String
        }
        """,
        expandedSource: """
        struct User {
            let firstName: String
            let lastName: String

            enum CodingKeys: String, CodingKey {
                case firstName = "first_name"
                case lastName = "last_name"
            }
        }

        extension User: Codable {}
        """,
        macros: ["AutoCodable": AutoCodableMacro.self]
    )
}

Для регрессионных тестов на ошибки используйте параметр diagnostics: того же helper'а: он сравнивает выданные диагностики с ожидаемыми. Альтернативно есть библиотека swift-macro-testing от Point-Free, которая использует snapshot-подход: при изменении ожидаемого вывода файл автоматически обновляется. Это удобно для больших макросов с длинными раскрытиями.

Влияют ли макросы на производительность

Короткий ответ: на рантайм нет, на время компиляции да. Макрос исполняется как отдельный процесс при сборке (swift-plugin-server), компилятор сериализует AST, отправляет его в плагин, получает результат и подставляет обратно. Это не бесплатно: каждое раскрытие добавляет 10–50 мс на инкрементальную сборку, что заметно при сотнях вызовов @Observable и @Model в крупных проектах.

В Xcode 16 и Swift 6.1 этот пайплайн ускорили: плагин запускается один раз на весь модуль (раньше, на каждую транзакцию), а сериализация AST использует binary-формат вместо JSON. Apple сообщала о приросте до 35% на больших проектах в release notes Xcode 16. Если вы видите, что сборка деградировала, проверьте профайлером swift-driver --print-jobs, какие именно макросы расширяются дольше всего. В моём последнем проекте этим способом мы нашли один @AutoCodable-вариант, который тянул 800 мс на каждом билде, потому что обходил всё дерево вложенных типов.

Главное архитектурное правило: не делайте макросы, которые читают файлы или ходят в сеть. SwiftSyntax sandbox не даёт им доступа к ФС вне input-AST, и это правильно: компиляция должна быть детерминированной. Если хотите подгружать схему или конфиг, используйте build-tool plugin вместо macro plugin.

Часто задаваемые вопросы

Чем Swift Macros отличаются от Sourcery и gyb?

Sourcery и gyb работают как внешние генераторы текста до компиляции и требуют отдельной build phase. Swift Macros интегрированы в компилятор, имеют доступ к настоящему AST, тип-сейф через SwiftSyntax и не требуют сторонних инструментов в CI.

Можно ли использовать Swift Macros в iOS-приложении ниже iOS 17?

Да. Макросы, это feature компилятора, а не рантайма, поэтому target deployment может быть любым из поддерживаемых Swift 5.9+. Требуется только, чтобы Xcode и toolchain поддерживали макросы; результат раскрытия, это обычный Swift-код, работающий на старых OS.

Почему макросы запрашивают разрешение «Trust & Enable Plugin» при первом использовании?

Поскольку плагин, это исполняемый файл, который Xcode запускает при сборке, требуется явное согласие пользователя из соображений безопасности. Запрос появляется один раз на пакет; в CI можно автоматически дать согласие через переменную окружения SKIP_MACRO_VALIDATION или флаг -skipMacroValidation.

Можно ли отлаживать макрос с помощью breakpoint'ов?

Да. В Xcode 16 можно прицепить debugger к процессу swift-plugin-server через Debug → Attach to Process. Удобнее, однако, писать тесты с assertMacroExpansion и пользоваться Expand Macro в редакторе; точки останова в макросах редко дают больше информации, чем структурированное сравнение AST.

Какую версию swift-syntax выбрать для проекта?

Выбирайте major-версию по версии Swift toolchain: Swift 5.10 → 510.0.0, Swift 6.0 → 600.0.0, Swift 6.1 → 601.0.0. Зафиксируйте через from: в Package.swift, чтобы избежать несовместимости при обновлении Xcode. Точная таблица соответствия есть в README репозитория swift-syntax.