Android AIDL 是如何转换成 Java 文件的:从 .aidl 到 .java 的完整链路

5 阅读5分钟

1. 引言

在 Android 开发中,AIDL(Android Interface Definition Language)是跨进程通信(IPC)最常用的方式之一。我们只需要写一个 .aidl 文件,声明接口方法,编译之后就能在代码里直接调用 Stub、asInterface() 等方法。

很多人会好奇:.aidl 文件到底是怎么变成 .java 文件的? 是谁在什么时候做的转换?生成的 Java 代码长什么样?

本文从构建流程、转换工具、生成代码结构三个层面,把这条链路讲清楚。

2. 一句话结论

.aidl 到 .java 的转换由 AIDL 编译器(aidl 可执行程序) 完成,它由 Android Gradle Plugin 在编译期自动调用:

  • 输入:src/main/aidl/xxx/IFoo.aidl
  • 输出:build/generated/aidl_source_output_dir/.../xxx/IFoo.java
  • 时机:Gradle 任务 compileDebugAidl(或 compileReleaseAidl)执行阶段,早于 Java 编译

也就是说,它不是运行时行为,而是构建期代码生成(code generation)。

3. 整体构建流程

flowchart TD
  A["编写 IFoo.aidl"] --> B["Gradle 配置 sourceSets.aidl"]
  B --> C["任务 compileDebugAidl"]
  C --> D["调用 aidl 可执行程序"]
  D --> E["生成 IFoo.java 到 build/generated"]
  E --> F["加入 Java 编译源集"]
  F --> G["javac / kotlinc 编译"]
  G --> H["打包进 APK"]

关键点:

  1. AGP 会扫描 src/main/aidl 目录下的所有 .aidl 文件;
  2. 对每个文件调用一次 aidl 命令;
  3. 生成的 .java 被注册为 Java 源集的一部分,参与后续编译;
  4. 因此你在代码里 import xxx.IFoo 时,IDE 能跳转到生成文件。

4. AIDL 编译器做了什么

aidl 本质上是一个语法解析 + 代码模板生成的工具,流程可以拆成四步:

4.1 词法与语法分析

AIDL 有自己的语法规则(类似 Java 接口的子集),编译器先用 lex/yacc 风格的解析器把 .aidl 文本解析成 AST(抽象语法树),得到:

  • package 名
  • import 列表
  • interface 名
  • 方法签名(返回类型、参数、方向标记 in / out / inout)
  • 常量定义

4.2 类型检查与符号解析

编译器需要知道每个类型是:

  • 基本类型(int、long、boolean 等)
  • String / CharSequence
  • List / Map
  • 可序列化的 Parcelable
  • 其他 AIDL 接口

对于自定义类型,它会去 -I 指定的 import 路径里查找对应的 .aidl 文件,确认类型合法。

4.3 生成 Java 代码

这是核心步骤。编译器内置了一套 Java 代码模板,把 AST 填充进去,输出一个完整的 .java 文件。生成的内容包括:

  • 接口本身(继承 android.os.IInterface)
  • 内部抽象类 Stub(继承 Binder 并实现接口)
  • Stub.Proxy 代理类(客户端调用时使用)
  • asInterface()、asBinder() 等辅助方法
  • 每个方法的 TRANSACTION_xxx 常量
  • DESCRIPTOR 描述符字符串

4.4 写出文件

最后按 package 路径创建目录,把 Java 源码写到输出目录,文件名与接口名一致。

5. 生成的 Java 代码结构

假设我们有这样一个 AIDL:

// IRemoteService.aidl
package com.example.ipc;

interface IRemoteService {
    int getPid();
    String getName(String prefix);
}

编译后生成的 IRemoteService.java 大致结构如下(省略部分细节):

package com.example.ipc;

public interface IRemoteService extends android.os.IInterface {

    /** Default implementation for IRemoteService. */
    public static class Default implements com.example.ipc.IRemoteService {
        @Override
        public int getPid() throws android.os.RemoteException {
            return 0;
        }

        @Override
        public java.lang.String getName(java.lang.String prefix)
                throws android.os.RemoteException {
            return null;
        }

        @Override
        public android.os.IBinder asBinder() {
            return null;
        }
    }

    /** Local-side IPC implementation stub class. */
    public static abstract class Stub extends android.os.Binder
            implements com.example.ipc.IRemoteService {

        private static final java.lang.String DESCRIPTOR = "com.example.ipc.IRemoteService";

        public Stub() {
            this.attachInterface(this, DESCRIPTOR);
        }

        public static com.example.ipc.IRemoteService asInterface(android.os.IBinder obj) {
            if (obj == null) {
                return null;
            }
            android.os.IInterface iin = obj.queryLocalInterface(DESCRIPTOR);
            if (iin != null && iin instanceof com.example.ipc.IRemoteService) {
                return (com.example.ipc.IRemoteService) iin;
            }
            return new com.example.ipc.IRemoteService.Stub.Proxy(obj);
        }

        @Override
        public android.os.IBinder asBinder() {
            return this;
        }

        @Override
        public boolean onTransact(int code, android.os.Parcel data,
                                  android.os.Parcel reply, int flags)
                throws android.os.RemoteException {
            switch (code) {
                case INTERFACE_TRANSACTION:
                    reply.writeString(DESCRIPTOR);
                    return true;
                case TRANSACTION_getPid:
                    data.enforceInterface(DESCRIPTOR);
                    int _result = this.getPid();
                    reply.writeNoException();
                    reply.writeInt(_result);
                    return true;
                case TRANSACTION_getName:
                    data.enforceInterface(DESCRIPTOR);
                    java.lang.String _arg0 = data.readString();
                    java.lang.String _result = this.getName(_arg0);
                    reply.writeNoException();
                    reply.writeString(_result);
                    return true;
            }
            return super.onTransact(code, data, reply, flags);
        }

        private static class Proxy implements com.example.ipc.IRemoteService {
            private android.os.IBinder mRemote;

            Proxy(android.os.IBinder remote) {
                mRemote = remote;
            }

            @Override
            public android.os.IBinder asBinder() {
                return mRemote;
            }

            @Override
            public int getPid() throws android.os.RemoteException {
                android.os.Parcel _data = android.os.Parcel.obtain();
                android.os.Parcel _reply = android.os.Parcel.obtain();
                int _result;
                try {
                    _data.writeInterfaceToken(DESCRIPTOR);
                    boolean _status = mRemote.transact(Stub.TRANSACTION_getPid, _data, _reply, 0);
                    _reply.readException();
                    _result = _reply.readInt();
                } finally {
                    _reply.recycle();
                    _data.recycle();
                }
                return _result;
            }

            @Override
            public java.lang.String getName(java.lang.String prefix)
                    throws android.os.RemoteException {
                android.os.Parcel _data = android.os.Parcel.obtain();
                android.os.Parcel _reply = android.os.Parcel.obtain();
                java.lang.String _result;
                try {
                    _data.writeInterfaceToken(DESCRIPTOR);
                    _data.writeString(prefix);
                    boolean _status = mRemote.transact(Stub.TRANSACTION_getName, _data, _reply, 0);
                    _reply.readException();
                    _result = _reply.readString();
                } finally {
                    _reply.recycle();
                    _data.recycle();
                }
                return _result;
            }
        }

        static final int TRANSACTION_getPid = android.os.IBinder.FIRST_CALL_TRANSACTION + 0;
        static final int TRANSACTION_getName = android.os.IBinder.FIRST_CALL_TRANSACTION + 1;
    }

    public int getPid() throws android.os.RemoteException;
    public java.lang.String getName(java.lang.String prefix) throws android.os.RemoteException;
}

可以看到,AIDL 只是语法糖,真正干活的是这段自动生成的 Java 代码:Proxy 负责把方法调用序列化进 Parcel 并 transact,Stub.onTransact 负责反序列化并分发到真实实现。

6. 手动执行 aidl 命令

如果想亲眼看到转换过程,可以手动调用 aidl 可执行文件。它位于 Android SDK 的 build-tools/<version>/ 目录下:

# 查看 aidl 版本
$ANDROID_HOME/build-tools/34.0.0/aidl --version

# 手动编译一个 aidl 文件
$ANDROID_HOME/build-tools/34.0.0/aidl \
  -p $ANDROID_HOME/platforms/android-34/framework.aidl \
  -I src/main/aidl \
  -o out \
  src/main/aidl/com/example/ipc/IRemoteService.aidl

参数说明:

  • -p:指定 framework.aidl,提供 android.os.* 等系统类型的定义
  • -I:import 搜索路径,自定义 Parcelable 或 AIDL 接口需要
  • -o:输出目录
  • 最后一个参数是待编译的 .aidl 文件

执行后会在 out/ 下生成对应的 .java 文件,内容与 Gradle 构建产物一致。

7. 在 Gradle 中查看生成结果

AGP 默认把生成文件放在:

app/build/generated/aidl_source_output_dir/debug/out/

可以在 app/build.gradle 中自定义输出目录:

android {
    sourceSets {
        main {
            aidl.srcDirs = ['src/main/aidl']
        }
    }
}

也可以直接执行任务观察:

./gradlew :app:compileDebugAidl --info

日志里会打印每一次 aidl 调用的完整命令行,非常适合排查「为什么我的 AIDL 没生成」这类问题。

8. 常见问题

8.1 为什么找不到生成的 Java 文件?

  • 先确认 .aidl 放在 src/main/aidl 下,且包路径与 package 声明一致;
  • 执行一次 ./gradlew clean assembleDebug,让 compileDebugAidl 重新跑;
  • 检查是否开启了 buildFeatures { aidl true }(AGP 8.0+ 默认关闭)。

8.2 自定义 Parcelable 报错找不到符号

需要在 aidl 目录下同时提供同名的 .aidl 声明文件,例如:

// com/example/ipc/User.aidl
package com.example.ipc;
parcelable User;

并在使用它的 AIDL 中 import com.example.ipc.User;。

8.3 生成代码能修改吗?

不能。生成目录属于构建产物,每次编译都会被覆盖。需要扩展行为时,应继承 Stub 编写服务端实现,而不是改生成文件。

9. 总结

环节说明
转换工具Android SDK 中的 aidl 可执行程序
触发时机Gradle 任务 compileDebugAidl,编译期
输入src/main/aidl/**/*.aidl
输出build/generated/aidl_source_output_dir/**/*.java
生成内容接口、Stub、Proxy、asInterface、TRANSACTION_* 常量
本质语法解析 + 模板化代码生成

理解了这条链路,再去看 Binder 机制、Parcel 序列化、onTransact 分发,就会顺畅很多——AIDL 只是帮你把繁琐的模板代码写好了而已。