#跟着坚果学鸿蒙#

一、宏的基本概念与作用

1.1 宏是什么？

在仓颉语言中，宏（Macro） 是一种强大的元编程工具。它允许我们在编译期对代码进行分析和变换，从而生成新的代码片段。换句话说，宏的输入是代码本身（以词法单元 Tokens 的形式），输出也是代码。

这种机制使得我们可以在不改变运行时逻辑的前提下，灵活地扩展语言特性，实现诸如日志注入、条件编译、DSL 构建等功能。

1.2 宏与函数的区别

特性	函数	宏
执行阶段	运行期	编译期
输入类型	数据值	程序代码片段（Tokens）
输出形式	返回计算结果	生成新代码

举个例子：一个函数 print(x) 在程序运行时才会执行；而一个宏 @dprint(x) 则在编译时被展开为多个打印语句，这些语句将在运行时被执行。

1.3 宏的核心价值

• 元编程：用代码生成代码，提升开发效率。
• 领域特定语言（DSL）构建：通过宏定义语法糖，使代码更贴近业务表达。
• 条件代码生成：根据配置或环境变量决定是否生成某些代码。

---

二、宏的分类体系

2.1 按参数特征划分

无属性宏（Simple Macro）

只有一个输入参数（即 Tokens 序列），适用于简单的代码转换任务。

示例：

@dprint(x + y)

有属性宏（Attribute Macro）

接受两个 Tokens 参数：一个是属性（如配置信息），另一个是目标代码片段。适用于需要附加配置信息的复杂转换。

示例：

@log(level = "debug")
func myFunc() { ... }

---

三、宏的实现原理与语法结构

3.1 核心组件

• Tokens 类型：表示一段代码的词法单元序列。
• quote 表达式：用于构造新的 Tokens，相当于“代码模板”。
• 插值语法 $(...)：将已有 Tokens 动态插入到 quote 中。

3.2 宏的定义与调用

定义宏

宏必须定义在专用的宏包中，并使用 macro package 声明：

macro package demo
import std.ast.*

public macro Sample(input: Tokens): Tokens {
    let codeStr = input.toString()
    return quote {
        print("执行的代码是：${$(codeStr)}")
        $(input)
    }
}

调用宏

在主程序中调用宏时，使用 @ 符号加宏名的方式：

@Sample
x + y

3.3 编译流程

由于宏是在编译期展开的，因此需要分两步编译：

# 第一步：编译宏包
cjc macro_pkg/*.cj --compile-macro

# 第二步：编译主程序
cjc main.cj -o program

---

四、典型应用场景与示例

4.1 调试打印宏

用于自动插入调试信息，方便排查问题。

@dprint(x + y)

// 展开后：
print("x + y = ")
println(x + y)

4.2 条件代码注入宏

根据编译配置决定是否生成特定代码。

public macro DebugLog(input: Tokens) {
    if (globalConfig.mode == Mode.DEV) {
        return quote( println(${input}) )
    } else {
        return quote() // 生产环境不生成代码
    }
}

4.3 函数增强宏

对函数体进行改造，例如添加日志、计时等通用行为。

@ModifyFunc
func myFunc() { counter++ }

// 展开后：
func myFunc(id: Int64) {
    println("start ${id}")
    counter++
    println("end")
}

---

五、高级特性与限制说明

5.1 作用域与导入规则

• 宏必须定义在 macro package 中。
• 只有宏可以标记为 public，普通函数不能对外暴露。
• 导入宏包时需明确指定，且不允许宏包中的非宏符号被导出。

5.2 嵌套与递归调用

• 支持多层嵌套宏调用（如 @Outer @Inner）。
• 支持有限递归，但必须在 quote 表达式内进行。
• 提供上下文通信接口：
  • AssertParentContext()：验证当前宏是否被特定宏调用。
  • SetItem()/GetChildMessages()：跨宏通信。

5.3 使用限制

• 输入必须是合法的 Token 序列。
• 特殊字符（如 @、未闭合括号）需转义处理。
• 宏展开后的代码必须符合仓颉语言的语法规范。

---

六、最佳实践建议

1. 优先使用无属性宏：对于简单功能，尽量避免引入属性参数，保持简洁。
2. 拆分复杂逻辑：将大型宏拆分为多个协作的小宏，提高可维护性。
3. 善用 quote 和插值：保持生成代码的结构清晰，便于阅读和调试。
4. 启用编译期打印：利用调试宏查看宏展开过程，帮助定位问题。
5. 测试不同编译模式：确保宏在不同配置下都能正确展开，特别是生产/开发模式切换时的行为一致性。