Lancet 轻量级 Android AOP 框架官方文档

@Proxy

public @interface Proxy {
    String value();
}

@Proxy 注解将使用新的方法替换代码里存在的原有目标方法。例如，如果代码中有 10 个地方调用了 Dog.bark()，代理这个方法后，所有的 10 处调用都会变为 _Lancet.xxxx.bark()。而在这个新方法内部，会执行你在 Hook 方法中所编写的逻辑。

@Proxy 通常用于对系统 API 的劫持。虽然我们无法直接注入代码到系统提供的库之中，但我们可以劫持掉所有调用系统 API 的地方，从而在不修改源码的情况下改变其行为。

@NameRegex

@NameRegex 用来限制操作的作用域，仅用于 Proxy 模式中。例如，你只想代理某一个包名下的所有目标操作，或者在代理所有网络请求时，不想代理掉自己发起的请求。使用 NameRegex 可以对 TargetClass、ImplementedInterface 筛选出的 Class 再进行一次正则匹配过滤。

@Insert

public @interface Insert {
    String value();
    boolean mayCreateSuper() default false;
}

@Insert 将新代码插入到目标方法原有代码的前后。这种方式常用于操作 App 与 Library 的类，并且可以通过 This 对象操作目标类的私有属性与方法。

当目标方法不存在时，还可以使用 mayCreateSuper 参数来创建目标方法。例如，下面将代码注入每一个 Activity 的 onStop 生命周期：

@TargetClass(value = "android.support.v7.app.AppCompatActivity", scope = Scope.LEAF)
@Insert(value = "onStop", mayCreateSuper = true)
protected void onStop() {
    System.out.println("hello world");
    Origin.callVoid();
}

这里的 Scope 意为目标是 AppCompatActivity 的所有最终子类。如果一个类 MyActivity extends AppcompatActivity 没有重写 onStop，会自动创建 onStop 方法，而 Origin 在这里就代表了 super.onStop()。

效果如下：

protected void onStop() {
    System.out.println("hello world");
    super.onStop();
}

注意：Hook 方法的 public/protected/private 修饰符会完全照搬目标方法的修饰符。

匹配目标类

很多时候，我们不会仅匹配一个类，会有注入某各类所有子类，或者实现某个接口的所有类等需求。所以通过 TargetClass、ImplementedInterface 两个注解及 Scope 进行目标类匹配。

@TargetClass

通过类名称查找。

1. @TargetClass 的 value 是一个类的全限定名。
2. Scope.SELF：代表仅匹配 value 指定的目标类本身。
3. Scope.DIRECT：代表匹配 value 指定类的直接子类。
4. Scope.ALL：代表匹配 value 指定类的所有子类（包括间接子类）。
5. Scope.LEAF：代表匹配 value 指定类的最终子类。众所周知 Java 是单继承，所以继承关系是树形结构，这里代表了指定类为顶点的继承树的所有叶子节点。

@ImplementedInterface

通过接口查找。情况比通过类查找稍复杂一些。

1. @ImplementedInterface 的 value 可以填写多个接口的全名。
2. Scope.SELF：代表直接实现所有指定接口的类。
3. Scope.DIRECT：代表直接实现所有指定接口，以及指定接口的子接口的类。
4. Scope.ALL：代表 Scope.DIRECT 指定的所有类及其所有子类。
5. Scope.LEAF：代表 Scope.ALL 指定的森林结构中的所有叶节点。

当我们使用 @ImplementedInterface(value = "I", scope = ...) 时，目标类匹配结果如下：

• Scope.SELF -> A
• Scope.DIRECT -> A, C
• Scope.ALL -> A, B, C, D
• Scope.LEAF -> B, D

匹配目标方法

虽然在 Proxy、Insert 中我们指定了方法名，但识别方法必须要更细致的信息。我们会直接使用 Hook 方法的修饰符、参数类型来匹配方法。

所以一定要保持 Hook 方法的 public/protected/private、static 信息与目标方法一致，参数类型、返回类型与目标方法一致。返回类型可以用 Object 代替。方法名不限，异常声明也不限。

但有时候我们并没有权限声明目标类。这时候怎么办？可以使用 ClassOf 注解来替代对类的直接 import。

public class A {
    protected int execute(B b) {
        return b.call();
    }
    private class B {
        int call() {
            return 0;
        }
    }
}

@TargetClass("com.dieyidezui.demo.A")
@Insert("execute")
public int hookExecute(@ClassOf("com.dieyidezui.demo.A$B") Object o) {
    System.out.println(o);
    return (int) Origin.call();
}

ClassOf 的 value 一定要按照 (package_name.)(outer_class_name$)inner_class_name([]...) 的模板。例如：

• java.lang.Object
• java.lang.Integer[][]
• A[]
• A$B

API 交互

我们可以通过 Origin 与 This 与目标类进行一些交互。

Origin

Origin 用来调用原目标方法，可以被多次调用。

• Origin.call()：用来调用有返回值的方法。
• Origin.callVoid()：用来调用没有返回值的方法。

另外，如果你有捕捉异常的需求，可以使用 Origin.call/callThrowOne/callThrowTwo/callThrowThree() 或 Origin.callVoid/callVoidThrowOne/callVoidThrowTwo/callVoidThrowThree() 系列方法。

示例：

@TargetClass("java.io.InputStream")
@Proxy("read")
public int read(byte[] bytes) throws IOException {
    try {
        return (int) Origin.<IOException>callThrowOne();
    } catch (IOException e) {
        e.printStackTrace();
        throw e;
    }
}

This

仅用于 Insert 方式的非静态方法的 Hook 中。

• get()：返回目标方法被调用的实例化对象。
• putField & getField：你可以直接存取目标类的所有属性，无论是 protected 还是 private。另外，如果这个属性不存在，我们还会自动创建这个属性。自动装箱拆箱肯定也支持了。

一些已知的缺陷：

• Proxy 不能使用 This。
• 你不能存取你父类的属性。当你尝试存取父类属性时，我们还是会创建新的属性。

示例：

package me.ele;
public class Main {
    private int a = 1;
    public void nothing() {
    }
    public int getA() {
        return a;
    }
}

@TargetClass("me.ele.Main")
@Insert("nothing")
public void testThis() {
    Log.e("debug", This.get().getClass().getName());
    This.putField(3, "a");
    Origin.callVoid();
}

Tips 与注意事项

1. 内部类命名：内部类应该命名为 package.outer_class$inner_class 格式。
2. SDK 开发：SDK 开发者不需要 apply 插件，只需要 provided me.ele:lancet-base:x.y.z。
3. 编译性能：尽管我们支持增量编译，但当我们使用 Scope.LEAF、Scope.ALL 覆盖的类有变动，或者修改 Hook 类时，本次编译将会变成全量编译。开发者需注意这一点以优化构建速度。
4. 异常处理：在使用 Origin 调用方法时，建议根据目标方法签名选择合适的异常抛出方法，避免吞掉关键异常。
5. 兼容性：请确保 Gradle 版本与 Lancet 插件版本兼容，旧版本可能不支持新版 Gradle 特性。

License

Licensed under the Apache License, Version 2.0 (the 'License'); you may not use this file except in compliance with the License. You may obtain a copy of the License at

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an 'AS IS' BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.