元数据卡

• 前置知识：Vol 9 第1章（泛型/类型系统）、Vol 6 软件工程基础（注解、包管理）
• 预计时间：45 分钟
• 核心难度：进阶
• 阅读模式：高度专注
• 可选跳过：Rust 宏的卫生性部分可略读
• 完成标志：能解释什么是"代码生成代码"；理解 Java 注解处理、Python 元类、Rust 宏三者的核心区别

你的进度

这是遗迹的最后一扇门。你推开它，发现里面空荡荡的，只有一面镜子——镜子里映出的不是你的脸，而是你写的代码本身。墙上刻着一句话："最强大的工具是能改造工具本身的工具。"

老陈在角落的笔记本里留了一段话："我在 Python 里写了一个生成 API 接口的工厂函数，在 Rust 里写了一个生成 parser 的宏，在 Java 里写了一个处理数据库映射的注解处理器。它们做的是一样的东西——写代码的代码。"

你的任务

元编程（metaprogramming）是"写代码的代码"。你的普通代码操作数据，元代码操作代码本身。从 C 的宏（文本替换）到 Rust 的宏（AST 操作），从 Python 的元类到 Java 的注解处理器——每一种元编程方案都在回答同一个问题：能不能让编译器或运行时帮我把重复的工作干了？

本章分层

• 必读：元编程的核心分类、Java 注解处理、Rust 声明式宏
• 选读：Python 元类
• 进阶：Rust 过程式宏、内部 DSL 模式

破局 · 溯源

你发现自己在重复写同一类代码——每个实体类都需要 CRUD 方法、每个控制器都要做参数校验、每个 API 端点都要记录日志。

public class UserController {
    public Response createUser(CreateUserRequest req) {
        // 参数校验
        if (req.getName() == null || req.getName().isEmpty()) {
            throw new ValidationException("name is required");
        }
        // 转换 + 调用 Service
        User user = new User();
        user.setName(req.getName());
        userService.create(user);
        // 记录日志
        logger.info("User created: {}", user.getId());
        return Response.ok(user);
    }
}

public class OrderController {
    public Response createOrder(CreateOrderRequest req) {
        // 跟上面几乎一样，对象名不同
        if (req.getProductId() == null) {
            throw new ValidationException("productId is required");
        }
        Order order = new Order();
        order.setProductId(req.getProductId());
        orderService.create(order);
        logger.info("Order created: {}", order.getId());
        return Response.ok(order);
    }
}

你可以手工复制粘贴，然后祈祷改一处不要漏了另一处。或者，你可以让代码帮你去生成这段代码。

---

元编程的三种层次

层次	时机	代表
编译期代码生成	编译时	Java 注解处理器、Rust 宏
运行时代码修改	运行时	Python 元类、Ruby method_missing
DSL（领域特定语言）	抽象层	内部 DSL (Java Builder)、外部 DSL (DSL parser)

---

Rust 宏：在编译期操作 AST

Rust 有两种宏。先看最简单的——声明式宏（macro_rules!）：

// 定义一个宏：实现向量的快速创建
macro_rules! vec {
    ( $( $x:expr ),* ) => {
        {
            let mut temp_vec = Vec::new();
            $(
                temp_vec.push($x);
            )*
            temp_vec
        }
    };
}

// 使用
let v = vec![1, 2, 3];  // 展开成 vec.push(1); vec.push(2); vec.push(3);

这个宏匹配模式 $( $x:expr ),*——意思是"逗号分隔的任意多个表达式"。匹配后，对每个匹配到的表达式执行 temp_vec.push($x)。

C 的宏 vs Rust 的宏：

#define SQUARE(x) x * x
// SQUARE(1+2) 展开成 1+2*1+2 = 5 —— 不是你想要的！

C 的宏是在文本层面替换。Rust 的宏是在抽象语法树（AST）层面操作——解析完语法树后，对 AST 节点进行匹配和替换。1+2 在整个宏展开中是一个完整的表达式节点，不会被拆分。

这就是"卫生性"（hygiene）的含义：Rust 宏不会无意中捕获外层作用域的变量，不会产生语法解析二义性。

过程式宏（procedural macro） 更进一步——你写的宏本身是一段 Rust 程序，接收 TokenStream，输出 TokenStream：

// 最常用的过程式宏之一：派生宏 (derive macro)
#[derive(Debug, Clone)]
struct User {
    name: String,
    age: u32,
}

#[derive(Debug)] 告诉编译器：自动生成 Debug trait 的实现。你可以自定义派生宏：

// 这是一个简化示意，实际需要用 proc_macro crate
#[proc_macro_derive(MyBuilder)]
pub fn my_builder_derive(input: TokenStream) -> TokenStream {
    // 解析输入结构体 -> 生成 Builder 模式代码 -> 转成 TokenStream 输出
}

Rust 的过程式宏让你能在编译期完全控制代码生成——不依赖运行时反射，没有性能开销。

为什么 Rust 选宏而不是注解处理器？ 语言内置宏体系让代码生成跟语法树深度绑定，不需要外挂的注解处理器进程。代价是宏的编写和学习曲线陡峭。

---

Java 注解处理器：编译期代码生成

Java 的元编程方案是注解处理器——它不在语言内部，而是在 javac 编译过程中的一个插件点。

// 定义一个注解
@Retention(RetentionPolicy.SOURCE)  // 只保留到源码阶段
@Target(ElementType.TYPE)
public @interface Builder {
    // 标记需要生成 Builder 模式的类
}

// 定义一个注解处理器
@SupportedAnnotationTypes("com.example.Builder")
@SupportedSourceVersion(SourceVersion.RELEASE_21)
public class BuilderProcessor extends AbstractProcessor {
    @Override
    public boolean process(Set<? extends TypeElement> annotations,
                          RoundEnvironment roundEnv) {
        for (Element element : roundEnv.getElementsAnnotatedWith(Builder.class)) {
            // 读取类信息，生成 Builder 源码
            generateBuilder((TypeElement) element);
        }
        return true;
    }

    private void generateBuilder(TypeElement element) {
        // 使用 Filer 创建新的 .java 文件
        // 写入生成的 Builder 代码
    }
}

它是怎么工作的？

1. javac 扫描带 @Builder 的类
2. 调用 BuilderProcessor.process()
3. 处理器读取被注解的类的元信息（字段、类型）
4. 通过 Filer API 写一个新的 .java 文件
5. javac 自动编译新生成的文件

这跟 Rust 宏的区别在哪？

	Rust 宏	Java 注解处理器
输入	TokenStream/AST	编译好的 TypeElement
输出	TokenStream	完整的 .java 文件
时机	编译展开	编译过程中
反射	不需要	需要镜子 API 读取结构
代码风格	宏内写出生成逻辑	生成器类 + 输出 .java

Java 的方案更"重型"——需要外挂处理器、需要注册到 javac。但它也更容易调试：生成的是你能读懂的 Java 源码。

经典案例：Project Lombok —— @Data、@Getter、@Setter 都是注解处理器生成的。你可以自己写一个简化版的 @Builder 来理解这个过程。

Java 21 中，注解处理器的地位有所变化：语言层面引入了 @PreviewFeature 等新注解，但注解处理器的基本机制没有变化。理解它很重要，因为 Spring Boot、MapStruct、Lombok 都依赖它。

---

Python 元类：运行时的类工厂

Python 的元编程跟 Java/Rust 完全不同——它发生在运行时，而不是编译期。

在 Python 中，类本身是对象。当你写 class User: 时，Python 调用 type() 来创建这个类对象。元类（metaclass）就是"创建类的类"——你可以定制类的创建过程。

# 一个简单的元类：自动为类添加 created_at 字段
class TimestampMeta(type):
    def __new__(cls, name, bases, attrs):
        # 在创建类时自动添加一个字段
        attrs['created_at'] = None
        return super().__new__(cls, name, bases, attrs)

# 使用元类
class User(metaclass=TimestampMeta):
    def __init__(self, name):
        self.name = name

u = User("Alice")
print(u.created_at)  # None —— 元类自动添加的

这是怎么做到的？ type.__new__ 是一个类工厂——接收类名、基类、属性字典，返回一个新的类对象。自定义元类就是重写这个工厂过程，在类创建前修改属性字典。

跟 Java 注解处理的对比：

# Python 元类：运行时，拦截类创建
# 你不需要外置处理器，不需要重新编译
# 但：性能有运行时开销，IDE 难以推断元类生成的成员

class ApiEndpointMeta(type):
    def __new__(cls, name, bases, attrs):
        # 扫描所有方法，自动为以 'api_' 开头的方法注册路由
        for method_name, method in attrs.items():
            if method_name.startswith('api_'):
                route = method_name[4:]  # api_users -> /users
                # 这里可以注册路由
                print(f"Registering route: {route}")
        return super().__new__(cls, name, bases, attrs)

class MyAPI(metaclass=ApiEndpointMeta):
    def api_users(self): pass
    def api_orders(self): pass
    def helper(self): pass  # 不注册

元类的陷阱：类被创建时执行，不是类实例化时执行。如果你在元类中做 IO 操作，导入类的时候就会触发。另外，元类的继承是多层的——一个类的元类和父类的元类可能冲突。Python 3 有类创建顺序算法来解决，但理解起来需要一些时间。

---

内部 DSL：用宿主语言写领域语言

DSL（领域特定语言）是你为特定问题域设计的"小语言"。SQL 是 DSL（查询）、Regex 是 DSL（匹配）、Makefile 是 DSL（构建）。

内部 DSL 是指利用宿主语言的语法构造出自然流畅的领域表达。Java 的 Builder 模式其实是一种内部 DSL：

// 内部 DSL 风格
Pizza pizza = Pizza.builder()
    .size(Size.LARGE)
    .crust(Crust.THIN)
    .addTopping(Topping.CHEESE)
    .addTopping(Topping.PEPPERONI)
    .build();

这些 size()、crust()、addTopping() 只是返回自身的普通 Java 方法——但链式调用给人一种"用 Java 在描述一个比萨"的感觉。

更专业的内部 DSL（例如 jOOQ——Java 写 SQL）：

create.selectFrom(BOOK)
      .where(BOOK.PUBLISHED_IN.eq(2009))
      .and(BOOK.TITLE.like("%Java%"))
      .fetch();

这个不是字符串 SQL，是类型安全的 DSL——BOOK.PUBLISHED_IN 是代码生成的类。你在 IDE 中有自动补全，字段名拼错了编译不通过。

内部 DSL vs 外部 DSL：

	内部 DSL	外部 DSL
实现方式	利用宿主语言语法	自定义解析器
工具支持	宿主 IDE 支持	需要独立工具链
灵活性	受限于宿主语法	完全自定义
学习成本	会宿主语言即可	需要学另一门语言
案例	jOOQ, AssertJ, Spock	SQL, YAML, GraphQL

内部 DSL 的哲学：不创造一个全新的语言，而是把你的宿主语言用到极致，让它像在表达你的领域概念。

---

三方案对比

	Rust 宏	Java 注解处理器	Python 元类
时机	编译期	编译期	运行时（类导入时）
语言内置	是（内置宏系统）	否（标准库+编译器钩子）	是（type 体系）
操作对象	AST 节点	编译好的 TypeElement	类对象运行时结构
性能开销	0（编译后展开）	0（编译后源码已硬编码）	有（每次导入执行）
学习曲线	陡	中	中

---

常见陷阱

1. "元编程=神奇=不加区分使用" —— 元编程增加理解成本。每一层抽象都让调试更加复杂。能用普通代码解决的问题，就不要用宏/元类
2. "注解处理器只能生成胶水代码" —— 正确，但也只能做到这一步。Lombok 生成 getter/setter，MapStruct 生成映射器——这是注解处理器的甜蜜区
3. "元类可以替代继承" —— 可以，但不要。元类修改类的创建过程，而继承修改类的行为。两者目标不同

通关挑战

• 热身：在 Java 中写一个 @LogExecutionTime 注解（只声明），思考如果要实现它，注解处理器需要处理什么信息
• 动手：用 Rust 的 macro_rules! 写一个 hashmap! 宏，让你能写 hashmap!("key" => "value") 来代替显式的 HashMap 插入
• 观察：在 Python 中定义一个元类，在 __new__ 中打印 name 和 attrs，然后定义一个使用该元类的类——观察元类的执行时机

旅人笔记

元编程是你在语言之内操纵语言——不是使用编译器，而是成为编译器的一部分。但它是一把双刃剑：每一次代码生成都是对可读性的承诺，承诺"这个黑盒做对了它该做的事"。

→ 下一站预告

你走完了语言遗迹的六个构室。类型、内 存、并发、函数、字节码、元编程——每一扇门背后都是一个语言可能的选择方向。这些知识不会绑定到任何一门语言上，它们让你学新的语言时，一眼就能看出"哦，你们在这条岔路口选了跟 Java 不同的方向"。

前方是数学塔。馆长在那里等你，手里拿着一本发光的书。