用途
本技能用于在 Crystal 语言中实现编译期元编程，围绕宏（macro）展开，帮助构建强大的抽象、DSL 和代码生成系统。当需要减少样板代码、构建领域特定语言、生成重复的方法/类/模块、实现编译期校验与类型检查、生成序列化/反序列化代码、构建基于注解的编程模式、实现自动委托或代理、构建编译期配置系统、从 schema 生成数据库模型、实现编译期依赖注入、生成类型安全的构建器模式、从规范生成 API 客户端、实现面向切面编程模式时，可参考本技能。
主要能力
- 宏基础：宏在编译期运行，接收 AST 节点作为参数，可生成并返回插入程序的代码。包括简单宏定义、多参数宏、带块宏（使用 {{yield}}）、字符串插值（使用 {{}} 生成标识符、字面量和代码）。
- 编译期迭代：使用 {% for %} 遍历集合，包括遍历数组、哈希字面量、类型的方法。
- 条件编译：使用 {% if %} 基于标志、类型或表达式进行编译期条件判断，涵盖平台特定代码、功能标志、基于类型的条件。
- AST 节点类型：宏接收不同类型的 AST 节点，包括查看节点类型（class_name）、处理标识符（.id 转换）、操作字符串字面量。
- 进阶宏模式：构建路由 DSL（收集并编译路由）、自动 JSON 序列化、编译期配置系统。
- 宏方法：在类型上调用并可访问编译期类型信息，包括从类型信息生成方法（如 table_name、column_names）、属性内省（生成初始化器与 to_s）、方法委托。
- 调试宏：编译期打印（{{puts}} 输出值或类型信息）、宏展开检查（使用 --no-codegen 标志查看宏展开）。
使用方式
宏通过 macro 关键字定义，使用 {{}} 进行插值，使用 {% %} 执行编译期逻辑。示例涵盖定义 getter、多参数属性、带块宏、生成方法名、枚举辅助方法、常量定义、验证器、序列化器、路由处理、JSON 序列化、配置常量和委托等。调试时可在宏中使用 {{puts}} 打印，或用 crystal build --no-codegen app.cr 查看宏展开。
适用场景
适用于需要减少样板代码、构建 DSL、生成重复方法/类/模块、实现编译期校验与类型检查、自定义属性定义、生成序列化代码、构建注解式编程、自动委托或代理、编译期配置、从 schema 生成数据库模型、自定义断言的测试框架、编译期依赖注入、类型安全构建器、从规范生成 API 客户端以及面向切面编程等场景。
限制与注意事项
资料列出最佳实践与常见陷阱，但未提供版本兼容范围、性能基准、平台支持矩阵或官方收费信息，这些事实暂未提供。常见陷阱包括：忘记 .id 转换、字符串与符号混淆、宏无限递归、作用域冲突、类型解析时机、缺少 nil 检查、硬编码假设、错误信息不清晰、过度使用全局状态、未处理空集合、模板语法错误、类型不匹配、命名空间污染、平台依赖、循环依赖。