Swift 공식 문서 정리 - 매크로 (Macros)

안녕하세요! 오늘은 Swift 5.9에서 도입된 '매크로(Macros)'에 대해 알아보겠습니다. 매크로를 사용하면 반복적인 코드 작성을 줄이고, 컴파일 시점에 코드를 자동 생성할 수 있어 개발 효율성과 코드 품질을 크게 향상시킬 수 있습니다.

📌 매크로란?

매크로는 컴파일 시간에 코드를 생성하는 도구로, 개발자가 직접 작성해야 할 반복적인 코드를 자동으로 만들어줍니다. Swift 컴파일러는 코드를 빌드하기 전에 모든 매크로를 확장합니다.

매크로의 주요 특징:

• 항상 코드를 추가만 하고, 기존 코드를 삭제하거나 수정하지 않음
• 문법적으로 유효한 Swift 코드를 생성
• 타입 안전성 보장
• 매크로 확장 중 오류 발생 시 컴파일 오류로 처리

📌 매크로의 종류

Swift는 두 가지 유형의 매크로를 제공합니다:

1. 독립 매크로 (Freestanding Macros)

독립 매크로는 이름 앞에 해시 기호(#)를 붙여 호출하며, 다른 선언에 첨부되지 않고 독립적으로 사용됩니다.

func myFunction() {
    print("현재 실행 중인 함수: \(#function)")
    #warning("문제가 있습니다")
}

이 예제에서:

• #function은 현재 함수의 이름으로 대체됩니다.
• #warning은 사용자 정의 컴파일 경고를 생성합니다.

2. 첨부 매크로 (Attached Macros)

첨부 매크로는 이름 앞에 앳 기호(@)를 붙여 호출하며, 특정 선언에 첨부되어 해당 선언을 수정합니다.

// 매크로 없이 작성한 코드
struct SundaeToppings: OptionSet {
    let rawValue: Int
    static let nuts = SundaeToppings(rawValue: 1 << 0)
    static let cherry = SundaeToppings(rawValue: 1 << 1)
    static let fudge = SundaeToppings(rawValue: 1 << 2)
}

// 매크로를 사용한 간결한 코드
@OptionSet<Int>
struct SundaeToppings {
    private enum Options: Int {
        case nuts
        case cherry
        case fudge
    }
}

@OptionSet 매크로는 private 열거형의 케이스를 읽고, 각 옵션에 대한 상수를 생성하며, OptionSet 프로토콜 준수성을 자동으로 추가합니다.

📌 매크로 확장의 작동 방식

Swift가 매크로를 확장하는 과정은 다음과 같습니다:

1. 코드 파싱: 컴파일러가 코드를 읽고 추상 구문 트리(AST)라는 메모리 표현을 생성합니다.
2. 매크로 실행: 컴파일러가 AST의 일부를 매크로 구현에 전송하여 확장을 요청합니다.
3. 코드 대체: 확장된 코드로 매크로 호출을 대체합니다.
4. 컴파일 진행: 확장된 소스 코드로 컴파일을 계속합니다.

예를 들어, #fourCharacterCode("ABCD") 매크로는 4글자 문자열을 해당하는 부호 없는 32비트 정수로 변환합니다:

let magicNumber = #fourCharacterCode("ABCD")
// 확장 후: let magicNumber = 1145258561 as UInt32

매크로 확장 시 중요한 보안 조치:

• 매크로 구현은 매크로 호출 부분의 AST만 접근 가능
• 파일 시스템이나 네트워크에 접근할 수 없는 샌드박스 환경에서 실행
• 매크로 확장은 입력 외의 외부 요소(예: 현재 시간)에 의존하지 않아야 함

📌 매크로 선언하기

매크로는 macro 키워드를 사용하여 선언합니다:

@attached(member)
@attached(extension, conformances: OptionSet)
public macro OptionSet<RawType>() = 
        #externalMacro(module: "SwiftMacros", type: "OptionSetMacro")

매크로 선언의 주요 요소:

• 매크로 역할(Role): @attached 또는 @freestanding 속성으로 지정
• 이름과 제네릭 매개변수: 위 예시에서는 OptionSet<RawType>
• 구현 위치: #externalMacro 매크로로 구현 모듈과 타입을 지정

매크로 역할 지정

첨부 매크로는 @attached 속성으로 역할을 지정합니다:

@attached(member, names: named(RawValue), named(rawValue), 
        named(`init`), arbitrary)
@attached(extension, conformances: OptionSet)
public macro OptionSet<RawType>() = 
        #externalMacro(module: "SwiftMacros", type: "OptionSetMacro")

독립 매크로는 @freestanding 속성으로 역할을 지정합니다:

@freestanding(expression)
public macro line<T: ExpressibleByIntegerLiteral>() -> T = 
        /* ... 매크로 구현 위치... */

📌 매크로 구현하기

매크로를 구현하기 위해서는 두 가지 구성 요소가 필요합니다:

1. 매크로 확장을 수행하는 타입
2. 매크로를 API로 노출하는 라이브러리

Swift Package Manager로 매크로 생성하기

새 매크로 패키지 생성:

swift package init --type macro

기존 프로젝트에 매크로 추가:

1. Package.swift 파일에서 Swift 도구 버전을 5.9 이상으로 설정
2. CompilerPluginSupport 모듈 가져오기
3. 최소 배포 대상에 macOS 10.15 포함
4. 매크로 구현 및 라이브러리 타겟 추가

 

// swift-tools-version: 5.9

import PackageDescription
import CompilerPluginSupport

let package = Package(
    name: "MyPackage",
    platforms: [.iOS(.v17), .macOS(.v13)],
    // ...
    dependencies: [
        .package(url: "https://github.com/swiftlang/swift-syntax", from: "509.0.0")
    ],
    targets: [
        // 매크로 구현 타겟
        .macro(
            name: "MyProjectMacros",
            dependencies: [
                .product(name: "SwiftSyntaxMacros", package: "swift-syntax"),
                .product(name: "SwiftCompilerPlugin", package: "swift-syntax")
            ]
        ),
        // 매크로를 API로 노출하는 라이브러리 타겟
        .target(name: "MyProject", dependencies: ["MyProjectMacros"]),
    ]
)

매크로 구현 예제

#fourCharacterCode 매크로 구현:

import SwiftSyntax
import SwiftSyntaxMacros

public struct FourCharacterCode: ExpressionMacro {
    public static func expansion(
        of node: some FreestandingMacroExpansionSyntax,
        in context: some MacroExpansionContext
    ) throws -> ExprSyntax {
        guard let argument = node.argumentList.first?.expression,
              let segments = argument.as(StringLiteralExprSyntax.self)?.segments,
              segments.count == 1,
              case .stringSegment(let literalSegment)? = segments.first
        else {
            throw CustomError.message("정적 문자열이 필요합니다")
        }

        let string = literalSegment.content.text
        guard let result = fourCharacterCode(for: string) else {
            throw CustomError.message("유효하지 않은 4글자 코드입니다")
        }

        return "\(raw: result) as UInt32"
    }
}

private func fourCharacterCode(for characters: String) -> UInt32? {
    guard characters.count == 4 else { return nil }

    var result: UInt32 = 0
    for character in characters {
        result = result << 8
        guard let asciiValue = character.asciiValue else { return nil }
        result += UInt32(asciiValue)
    }
    return result
}

enum CustomError: Error { case message(String) }

매크로 플러그인 진입점:

import SwiftCompilerPlugin

@main
struct MyProjectMacros: CompilerPlugin {
    var providingMacros: [Macro.Type] = [FourCharacterCode.self]
}

📌 매크로 개발과 디버깅

매크로는 테스트 기반 개발에 적합합니다:

• 외부 상태에 의존하지 않음
• 문자열에서 쉽게 구문 노드 생성 가능
• AST의 description 속성으로 결과 확인 가능

테스트 예제:

let source: SourceFileSyntax =
    """
    let abcd = #fourCharacterCode("ABCD")
    """

let file = BasicMacroExpansionContext.KnownSourceFile(
    moduleName: "MyModule",
    fullFilePath: "test.swift"
)

let context = BasicMacroExpansionContext(sourceFiles: [source: file])

let transformedSF = source.expand(
    macros:["fourCharacterCode": FourCharacterCode.self],
    in: context
)

let expectedDescription =
    """
    let abcd = 1145258561 as UInt32
    """

precondition(transformedSF.description == expectedDescription)

📌 실용적인 매크로 활용 사례

매크로는 다음과 같은 작업에 특히 유용합니다:

1. 상용구 코드 생성: JSON 직렬화, 코딩 키 생성 등
2. 디자인 패턴 구현: 싱글톤, 팩토리, 빌더 패턴 등
3. 프로토콜 준수 자동화: Equatable, Hashable, Codable 등
4. 로깅 및 디버깅 지원: 함수 추적, 성능 측정 등
5. DSL(Domain-Specific Language) 만들기: SwiftUI 스타일의 선언적 구문 등

📌 매크로 사용 시 주의사항

1. 매크로를 과도하게 사용하지 마세요: 필요한 경우에만 사용
2. 매크로 확장 코드를 이해하세요: 생성된 코드가 무엇인지 알아야 함
3. 매크로 문서화를 철저히 하세요: 동작 방식과 생성하는 코드를 명확히 설명
4. 테스트를 작성하세요: 다양한 입력에 대한 매크로 동작을 테스트
5. 매크로 구현에서 외부 상태에 의존하지 마세요: 결정적인 결과 생성

📌 정리

Swift 매크로는 컴파일 시간에 코드를 생성하여 반복적인 작업을 자동화하고 코드 품질을 향상시키는 강력한 도구입니다. 독립 매크로와 첨부 매크로라는 두 가지 유형을 통해 다양한 사용 사례를 지원하며, 엄격한 안전성 보장을 제공합니다.

매크로를 적절히 활용하면:

• 코드 중복을 줄일 수 있습니다
• 실수를 방지할 수 있습니다
• 코드 가독성을 향상시킬 수 있습니다
• 개발자 생산성을 높일 수 있습니다

Swift 매크로는 아직 발전 중인 기능이지만, 이미 많은 잠재력을 보여주고 있습니다. 복잡한 상용구 코드를 간결하게 만들고 더 표현력 있는 API를 설계하는 데 매크로를 활용해 보세요!