Android应用WiFi连接实战：从传统API到Android 10+新方案的平滑迁移

1. Android WiFi连接API的版本变迁如果你正在开发一个需要连接WiFi的Android应用可能会发现不同系统版本之间的API差异让人头疼。特别是从Android 10开始Google对WiFi连接API做了大刀阔斧的改革这让很多老项目不得不面临迁移的问题。我刚开始接触这个迁移过程时踩了不少坑。最让人困惑的是为什么Google要突然改变这套已经稳定运行多年的API后来才明白这是为了更好的隐私保护和权限控制。在Android 10之前任何应用只要获取了位置权限就能随意扫描和连接WiFi网络这显然存在安全隐患。传统使用的WifiConfiguration类在Android 10及以上版本已经被标记为deprecated废弃。取而代之的是两套新方案WifiNetworkSpecifier和WifiNetworkSuggestion。这两者虽然都能实现WiFi连接但设计理念和使用场景却大不相同。2. 传统API的经典实现方式在Android 10之前我们通常这样连接WiFiWifiConfiguration wifiConfig new WifiConfiguration(); wifiConfig.SSID \ ssid \; wifiConfig.preSharedKey \ password \; wifiConfig.hiddenSSID true; wifiConfig.status WifiConfiguration.Status.ENABLED; WifiManager wifiManager (WifiManager) context.getSystemService(Context.WIFI_SERVICE); int netId wifiManager.addNetwork(wifiConfig); boolean success wifiManager.enableNetwork(netId, true);这套API看似简单直接但实际使用中有几个常见陷阱需要注意SSID和密码的引号问题必须用双引号包裹SSID和密码否则连接会失败。这个细节很容易被忽略。加密类型判断需要根据扫描结果中的capabilities字段判断加密方式WEP、WPA等不同的加密类型需要不同的配置。已保存网络处理如果网络已经保存在设备配置中应该先启用已有配置而不是创建新配置。我在一个项目中就遇到过这样的问题用户反馈在某些设备上WiFi连接不稳定。后来发现是因为没有正确处理已保存的网络配置导致系统中有多个相同SSID的配置造成了冲突。3. Android 10的新API详解Android 10引入了全新的WiFi连接API主要分为两种方式3.1 WifiNetworkSpecifier方式这是更接近传统方式的一种实现适合需要立即连接特定WiFi的场景WifiNetworkSpecifier specifier new WifiNetworkSpecifier.Builder() .setSsid(ssid) .setWpa2Passphrase(password) .build(); NetworkRequest request new NetworkRequest.Builder() .addTransportType(NetworkCapabilities.TRANSPORT_WIFI) .setNetworkSpecifier(specifier) .build(); ConnectivityManager connectivityManager (ConnectivityManager) context.getSystemService(Context.CONNECTIVITY_SERVICE); ConnectivityManager.NetworkCallback callback new ConnectivityManager.NetworkCallback() { Override public void onAvailable(Network network) { // 连接成功 } Override public void onUnavailable() { // 连接失败 } }; connectivityManager.requestNetwork(request, callback);这种方式的特点是需要用户授权会弹出系统对话框连接是即时发起的适合需要确保连接成功的场景3.2 WifiNetworkSuggestion方式这是一种更温和的连接方式系统会考虑你的建议但不保证立即连接WifiNetworkSuggestion suggestion new WifiNetworkSuggestion.Builder() .setSsid(ssid) .setWpa2Passphrase(password) .setIsAppInteractionRequired(true) .build(); WifiManager wifiManager (WifiManager) context.getSystemService(Context.WIFI_SERVICE); ListWifiNetworkSuggestion suggestions new ArrayList(); suggestions.add(suggestion); int status wifiManager.addNetworkSuggestions(suggestions); if (status WifiManager.STATUS_NETWORK_SUGGESTIONS_SUCCESS) { // 建议添加成功 }这种方式的特点是不需要立即用户授权系统会在合适的时候自动连接适合后台静默连接的场景4. 兼容新旧版本的实战方案在实际项目中我们通常需要兼容多个Android版本。下面分享一个经过实战检验的工具类设计方案public class WifiConnector { private final Context context; private final WifiManager wifiManager; private final ConnectivityManager connectivityManager; public WifiConnector(Context context) { this.context context; this.wifiManager (WifiManager) context.getSystemService(Context.WIFI_SERVICE); this.connectivityManager (ConnectivityManager) context.getSystemService(Context.CONNECTIVITY_SERVICE); } public void connectToWifi(String ssid, String password, WifiConnectCallback callback) { if (Build.VERSION.SDK_INT Build.VERSION_CODES.Q) { connectWithNewApi(ssid, password, callback); } else { connectWithLegacyApi(ssid, password, callback); } } SuppressLint(MissingPermission) private void connectWithLegacyApi(String ssid, String password, WifiConnectCallback callback) { // 传统API实现 } RequiresApi(api Build.VERSION_CODES.Q) private void connectWithNewApi(String ssid, String password, WifiConnectCallback callback) { // 新API实现 } public interface WifiConnectCallback { void onSuccess(); void onFailure(); } }这个工具类的关键点在于版本自动检测根据设备版本自动选择适当的API统一回调接口无论使用哪种API都通过相同的回调通知结果权限处理确保在调用前已经获取了必要的权限在实际使用中还需要注意以下几点在AndroidManifest.xml中声明必要的权限运行时权限检查特别是位置权限处理WiFi开关状态如果WiFi关闭需要提示用户打开5. 常见问题与调试技巧在实现WiFi连接功能时有几个常见问题值得特别注意5.1 权限问题从Android 10开始WiFi相关API对权限要求更加严格。除了传统的CHANGE_WIFI_STATE和ACCESS_WIFI_STATE权限外还需要ACCESS_FINE_LOCATION或ACCESS_COARSE_LOCATION权限对于Android 12还需要NEARBY_DEVICES权限这些权限不仅要在manifest中声明还需要在运行时请求。我遇到过这样的情况代码看起来没问题但就是连接失败最后发现是忘记请求运行时权限。5.2 后台限制Android对后台应用的网络操作有严格限制。如果你的应用在后台运行某些WiFi操作可能会被系统阻止。特别是使用WifiNetworkSuggestion方式时建议添加以下标志.setIsAppInteractionRequired(true)这样可以确保当用户与应用交互时系统会优先考虑你的网络建议。5.3 调试技巧调试WiFi连接问题时以下几个技巧很有帮助查看系统日志过滤Wifi标签可以看到详细的连接过程检查返回状态码特别是addNetwork()和enableNetwork()的返回值使用adb命令adb shell dumpsys wifi可以查看详细的WiFi状态信息测试不同设备不同厂商的ROM可能有不同的实现细节6. 性能优化建议在实现WiFi连接功能时性能优化也是需要考虑的重要因素减少重复扫描缓存扫描结果避免频繁调用扫描接口合理处理回调确保及时注销不再需要的NetworkCallback优化重试机制对于连接失败的情况实现合理的退避策略电池优化长时间后台扫描会显著增加耗电量需要平衡功能与功耗我曾经优化过一个智能家居应用的WiFi模块通过合理设置扫描间隔和缓存策略将电量消耗降低了约30%。7. 未来兼容性考虑随着Android系统的持续演进WiFi相关的API可能还会继续变化。为了确保应用的长期兼容性建议隔离WiFi操作代码将WiFi相关代码集中管理便于后续修改使用最新API即使需要兼容旧版本也应以新API为主要实现定期检查API变更关注Android开发者博客和API差异报告考虑使用Jetpack组件如WorkManager处理后台网络操作在最近的一个项目中我们采用了分层设计底层是版本特定的实现上层是统一的业务接口。这样当下一个Android大版本带来API变化时我们只需要修改底层实现即可。