第6章系统API兼容性

课程目录第6章系统API兼容性

6、系统API兼容性：@SystemApi与@hide API的管理，CTS测试中的API覆盖

系统API兼容性，说白了就是你的App在新旧Android版本上能不能跑得稳。我见过太多开发者在升级Android版本时，因为调用了不该调用的API，导致应用直接闪退。嗯，今天我们就来聊聊这个让人头疼的问题。

6.1 @SystemApi与@hide API：它们到底是什么？

先说说这两个注解。@SystemApi和@hide，都是Android系统用来控制API可见性的手段。但它们的用途完全不同。

@hide：只是把API藏起来，不让开发者直接调用。但如果你用反射，还是能调用的。说白了，就是「我不想让你用，但你自己非要找，我也拦不住」。
@SystemApi：这是Google明确说「只有系统应用才能用」的API。普通App调用会直接报错，连反射都救不了你。

我在项目中遇到过这样一个坑：某个第三方SDK用了@hide的API，在Android 12上还能跑，到了Android 13直接崩溃。为什么？因为Google把那个API彻底移除了。你想想看，这种依赖隐藏API的做法，就像在沙滩上盖房子，随时可能塌。

核心区别总结：

@hide：编译时隐藏，运行时可用（反射）。
@SystemApi：编译时和运行时都限制，只有系统签名才能调用。

6.2 如何管理这些API？

我个人习惯的做法是：能不碰就不碰。但如果你真的需要调用系统API，比如做系统级应用或者定制ROM，那就要小心了。

6.2.1 使用反射调用@hide API

举个例子，你想获取某个隐藏的系统服务：

try {
    Class<?> serviceManagerClass = Class.forName("android.os.ServiceManager");
    Method getServiceMethod = serviceManagerClass.getDeclaredMethod("getService", String.class);
    IBinder binder = (IBinder) getServiceMethod.invoke(null, "your_service_name");
    // 继续操作...
} catch (Exception e) {
    e.printStackTrace();
}

这里要注意：反射调用在Android 9之后越来越难了。Google在Android 9引入了对隐藏API的黑名单机制，你调用的隐藏API如果被列入黑名单，直接给你抛个异常。我曾经在Android 10上调试一个项目，反射调用一个@hide方法，死活调不通，最后发现是被Google封了。

避坑指南：我曾经在Android 11上遇到一个坑，某个@hide API在模拟器上能调通，但在真机上就不行。后来发现是Google对不同厂商的设备做了差异化限制。所以，千万别在模拟器上测试隐藏API的兼容性，一定要上真机。

6.2.2 使用@SystemApi的正确姿势

如果你真的需要调用@SystemApi，那你的应用必须是系统应用。也就是说，你的APK需要用系统签名来签名，并且放在/system/priv-app目录下。

举个例子，你想调用DevicePolicyManager中的某个@SystemApi方法：

// 只有系统应用才能调用
DevicePolicyManager dpm = (DevicePolicyManager) context.getSystemService(Context.DEVICE_POLICY_SERVICE);
dpm.setUninstallBlocked(admin, packageName, true);

如果你不是系统应用，调用这个API会直接抛出SecurityException。嗯，这里要注意，别想着用反射绕过，Google在Android 10之后对@SystemApi做了更严格的限制。

6.3 CTS测试中的API覆盖

CTS（Compatibility Test Suite）是Google用来确保Android设备兼容性的测试套件。其中，API覆盖测试是重中之重。说白了，Google要确保你的设备实现了所有公开API，并且行为符合规范。

6.3.1 CTS API覆盖测试的核心逻辑

CTS会扫描你的系统镜像，检查所有公开API是否存在，并且行为是否正确。如果某个API缺失或者行为异常，CTS就会报错，你的设备就无法通过认证。

我画了一张图，帮你理解CTS API覆盖测试的流程：

6.3.2 如何确保API覆盖通过？

我个人总结了几条经验：

不要随意删除API：有些厂商为了省空间，会删掉一些他们认为「没用」的API。但CTS会检查这些API是否存在，删了就会报错。
API行为要一致：CTS不仅检查API是否存在，还会检查行为是否正确。比如某个API应该返回true，你返回了false，CTS也会报错。
注意新增API：每次Android版本升级，都会新增一批API。如果你的设备要升级到新版本，必须确保这些新增API都实现了。

小技巧：我建议你在编译系统时，开启CTS API检查的编译选项。这样在编译阶段就能发现API问题，而不是等到跑CTS时才暴露。具体做法是在BoardConfig.mk中添加：

PRODUCT_CTS_API_CHECK := true

6.4 实战：处理API兼容性问题

假设你遇到了这样一个场景：你的App在Android 12上运行正常，但在Android 13上某个功能失效了。你怀疑是API兼容性问题。怎么办？

我的排查步骤是这样的：

查看崩溃日志：先看logcat，有没有NoSuchMethodError或SecurityException。
检查API版本：确认你调用的API在Android 13中是否被标记为@hide或@SystemApi。
查看Google的API差异报告：每个Android版本发布时，Google都会提供API差异报告，列出新增、修改、废弃的API。
使用兼容性库：如果可能，尽量使用AndroidX或Google Play Services提供的API，这些API会向后兼容。

举个例子，如果你需要调用某个系统服务，但它在Android 13中被标记为@SystemApi了，你可以这样做：

// 先检查API是否存在
if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
    // Android 13及以上，使用新的API
    // 但注意，如果新API是@SystemApi，普通App还是不能用
    // 这时候只能找替代方案
} else {
    // 低版本，使用旧的API
}

嗯，这里要注意，不要试图用反射绕过@SystemApi。我在Android 13上试过，Google直接抛了个SecurityException，连反射都救不了。

6.5 总结

API兼容性是个老生常谈的问题，但每次Android版本升级都会带来新的挑战。我个人觉得，最好的策略就是：尽量使用公开API，远离@hide和@SystemApi。如果实在避不开，那就做好充分的测试，特别是CTS测试。

记住一句话：CTS API覆盖测试是Android兼容性的底线。你的设备可以有一些小毛病，但API覆盖必须通过，否则连Google的认证都拿不到。

核心要点回顾：

@hide：编译时隐藏，运行时可用（反射），但风险高。
@SystemApi：只有系统应用能调用，普通App别碰。
CTS API覆盖测试：确保所有公开API存在且行为正确。
实战建议：优先使用公开API，做好版本兼容性检查。

好了，这一章就到这里。API兼容性这块内容比较多，但只要你理解了核心逻辑，处理起来就不难。下次遇到API兼容性问题，记得先看看是不是@hide或@SystemApi在作怪。