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之前，我们通常这样连接WiFi：

WifiConfiguration 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看似简单直接，但实际使用中有几个常见陷阱需要注意：

1. SSID和密码的引号问题：必须用双引号包裹SSID和密码，否则连接会失败。这个细节很容易被忽略。

2. 加密类型判断：需要根据扫描结果中的capabilities字段判断加密方式（WEP、WPA等），不同的加密类型需要不同的配置。

3. 已保存网络处理：如果网络已经保存在设备配置中，应该先启用已有配置而不是创建新配置。

我在一个项目中就遇到过这样的问题：用户反馈在某些设备上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); List<WifiNetworkSuggestion> 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(); } }

这个工具类的关键点在于：

1. 版本自动检测：根据设备版本自动选择适当的API
2. 统一回调接口：无论使用哪种API，都通过相同的回调通知结果
3. 权限处理：确保在调用前已经获取了必要的权限

在实际使用中，还需要注意以下几点：

• 在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连接问题时，以下几个技巧很有帮助：

1. 查看系统日志：过滤"Wifi"标签，可以看到详细的连接过程
2. 检查返回状态码：特别是addNetwork()和enableNetwork()的返回值
3. 使用adb命令：adb shell dumpsys wifi可以查看详细的WiFi状态信息
4. 测试不同设备：不同厂商的ROM可能有不同的实现细节

6. 性能优化建议

在实现WiFi连接功能时，性能优化也是需要考虑的重要因素：

1. 减少重复扫描：缓存扫描结果，避免频繁调用扫描接口
2. 合理处理回调：确保及时注销不再需要的NetworkCallback
3. 优化重试机制：对于连接失败的情况，实现合理的退避策略
4. 电池优化：长时间后台扫描会显著增加耗电量，需要平衡功能与功耗

我曾经优化过一个智能家居应用的WiFi模块，通过合理设置扫描间隔和缓存策略，将电量消耗降低了约30%。

7. 未来兼容性考虑

随着Android系统的持续演进，WiFi相关的API可能还会继续变化。为了确保应用的长期兼容性，建议：

1. 隔离WiFi操作代码：将WiFi相关代码集中管理，便于后续修改
2. 使用最新API：即使需要兼容旧版本，也应以新API为主要实现
3. 定期检查API变更：关注Android开发者博客和API差异报告
4. 考虑使用Jetpack组件：如WorkManager处理后台网络操作

在最近的一个项目中，我们采用了分层设计：底层是版本特定的实现，上层是统一的业务接口。这样当下一个Android大版本带来API变化时，我们只需要修改底层实现即可。