企业官网建设流程全解析

1. 项目概述：为什么 React Native 在 Android 上做长连接必须直面“前台服务”这道坎

React Native 开发者聊到 Android 长连接，十有八九会皱眉头——不是逻辑写不出来，而是“连得上、留不住、保不住”。你写好了 WebSocket 连接、加了心跳、做了重连，App 切到后台 30 秒，连接断了；用户锁屏 2 分钟，进程被系统回收，心跳停了；夜间待机 6 小时，系统直接杀掉整个 Service，重连策略根本没机会触发。这不是代码 bug，是 Android 系统级的生存规则。而标题里提到的“前台服务”，就是绕过这套规则、让长连接在后台持续存活的唯一合规路径。它不是可选项，是 Android 8.0（API 26）之后的强制要求——没有前台服务，任何后台网络保活都只是幻觉。

我做过 4 个需要实时消息推送的 RN 项目，从金融行情到工单调度，全部踩过这个坑。最典型的一次：测试同学反馈“下班后收不到紧急告警”，我们查日志发现连接在 19:47:12 断开，而手机是在 19:45 锁屏的。不是心跳没发，是系统把我们的 WebSocket 线程池直接干掉了。后来我们把前台服务加上，配合指数退避重连，连续 72 小时后台在线率从 41% 拉到 99.2%。关键不在于“技术多炫酷”，而在于尊重 Android 的生命周期设计——前台服务不是特权，是向系统明确声明：“我在做一件用户正在依赖的事，请别杀我”。

标题里的三个关键词，其实是环环相扣的生存链：前台服务是载体（让进程不被杀），心跳是存在感证明（告诉系统“我还活着，且在干活”），指数退避重连是容错底线（网络抖动、临时断网、服务端重启时，不狂轰滥炸，也不轻易放弃）。三者缺一不可。比如只做心跳，没前台服务？心跳包发不出去，系统早把你进程回收了；只做前台服务，没心跳？系统可能判定你“挂起无响应”，照样降优先级甚至杀死；只做指数退避，没前台服务和心跳？重连请求发不出去，退避再优雅也是纸上谈兵。

适合谁看？如果你正面临这些场景：IM 类 App 需要秒级消息到达、IoT 设备监控要求持续上报状态、车载或医疗类 App 不能容忍连接中断、或者你的 RN App 在 Android 上被投诉“收不到通知”——那这篇就是为你写的。不需要你是 Android 原生专家，但得愿意打开 AndroidManifest.xml 和 Java 文件；不需要你精通 JNI，但得理解 Service 生命周期和 ForegroundService 的权限边界。接下来，我会把整套方案拆成可落地的模块，告诉你每一步为什么这么写、不这么写会怎样、以及那些官方文档里绝不会写的“实操暗礁”。

2. 整体架构设计：为什么必须绕过 React Native 默认通信层，直连 Android 原生服务

2.1 核心矛盾：RN 的 JS 线程 vs Android 的后台限制

React Native 的默认通信模型是 JS 线程驱动一切：JS 层调用 NetInfo 监听网络、调用 WebSocket API 建连、定时器 setInterval 发心跳。问题在于，Android 系统对后台 JS 线程毫无敬畏。从 Android 8.0 开始，系统严格限制后台应用的 CPU、网络、传感器使用。一旦 App 进入后台（Activity onPause），JS 线程很快被挂起，setInterval 停摆，WebSocket.onmessage 回调不再触发，甚至 fetch 请求都可能超时失败。这不是 RN 的缺陷，是 Google 对电池续航和用户体验的硬性约束。

我试过所有“纯 JS 方案”：用 AppState.addEventListener('change') 监听前后台切换，切后台时启动 WebWorker（RN 不支持）、用 react-native-background-timer（实际在后台最多运行 5 分钟就被系统终止）、甚至尝试用 WebView 内嵌长连接（WebView 同样受后台限制）。结果都一样——稳定运行不超过 10 分钟。最终结论很残酷：在 Android 上，长连接的“心脏”必须放在原生层，JS 层只能是“大脑”和“嘴”。大脑负责业务逻辑（比如收到消息后更新 Redux 状态），嘴负责把指令传给心脏（比如“重连”、“发送心跳”），但心脏本身——那个持续呼吸、搏动、供血的实体——必须是 Android 的 ForegroundService。

2.2 架构选型：为什么选择“原生 Service + JS Bridge”而非第三方库

市面上有 react-native-background-fetch、react-native-foreground-service 等库，它们封装了 ForegroundService。但我的经验是：初期省事，后期踩坑无数。比如 background-fetch 的“后台任务”本质是系统调度的离散 Job，无法保证毫秒级心跳；foreground-service 库的 Notification 配置常与 targetSdkVersion 冲突，导致 Android 12+ 安装失败；更致命的是，这些库的 WebSocket 实现往往基于 OkHttp 或 Retrofit，与 RN 的 JS WebSocket 不互通，消息无法跨层传递。

所以我的方案是“最小化原生介入，最大化可控性”：

• 原生层只做三件事：管理 ForegroundService 生命周期、维护 WebSocket 连接、执行心跳与重连逻辑；
• JS 层只做两件事：通过 NativeModule 调用原生方法（如 startConnection()）、监听原生发来的事件（如 onMessageReceived）；
• 通信桥梁用 RN 自带的 NativeModules 和 DeviceEventEmitter，不引入额外依赖。

这样做的好处是：所有关键逻辑（尤其是重连策略、心跳超时判断）完全由你掌控；Notification 的图标、文字、点击行为可以按产品需求定制；当 Android 新版本发布（如 Android 14 的后台限制升级），你只需改几行 Java 代码，不用等第三方库更新。

2.3 关键决策：为什么用 OkHttp 而非 Java WebSocket

在原生层实现 WebSocket，有两个主流选择：Java 标准库的javax.websocket（需额外引入 Tyrus）或 OkHttp 的WebSocketListener。我选 OkHttp，理由很实在：

• OkHttp 是 Android 事实标准：RN 的网络层底层就是 OkHttp，复用它能避免证书信任、DNS 解析、代理配置等重复工作；
• 内存泄漏防护成熟：OkHttp 的WebSocketListener有完善的onFailure和onClosed回调，能精准捕获连接异常；
• 心跳控制更灵活：OkHttp 的pingIntervalMillis可直接设置，比手动Timer更可靠（系统休眠时 Timer 可能失效）；
• 兼容性好：从 Android 5.0 到 14，OkHttp 4.x 全覆盖，而javax.websocket在低版本 Android 上需要大量适配。

提示：不要用java.net.HttpURLConnection或AsyncTask实现长连接——前者不支持 WebSocket 协议，后者在 Android 11+ 已废弃，且无法在后台持续运行。

2.4 权限与配置：AndroidManifest.xml 的“生死线”

前台服务不是开了就行，它需要三道“通关文牒”：

1. 前台服务权限：<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
2. 通知渠道权限（Android 8.0+ 强制）：必须创建 NotificationChannel，否则startForeground()直接抛异常；
3. 后台启动 Activity 限制豁免（Android 10+）：如果服务需要在后台启动（如开机自启），需申请REQUEST_IGNORE_BATTERY_OPTIMIZATIONS，但这属于敏感权限，需引导用户手动开启。

最关键的配置在AndroidManifest.xml的<service>标签：

<service android:name=".LongConnectionService" android:enabled="true" android:exported="false" android:foregroundServiceType="specialUse" />

注意android:foregroundServiceType="specialUse"——这是 Android 12+ 新增的类型，用于声明“此服务涉及用户核心功能（如消息、位置）”，比"mediaProjection"或"location"更贴合长连接场景。如果设为"none"，Android 12+ 会拒绝启动。

注意：android:exported="false"是安全底线。导出的服务可能被恶意 App 调用，导致连接被劫持或滥用。

3. 核心细节解析：前台服务、心跳、指数退避的实现要点与避坑指南

3.1 前台服务：不只是startForeground()，而是完整的生命周期闭环

很多人以为startForeground()一行代码就完事了，其实这只是冰山一角。一个健壮的前台服务必须处理四种“死亡威胁”：

• 用户手动清除（划掉最近任务）：此时onDestroy()被调用，需清理资源；
• 系统内存不足：onTrimMemory()触发，需释放非关键缓存；
• 设备重启：需监听BOOT_COMPLETED广播，自动恢复服务；
• App 更新或崩溃：onCreate()必须幂等，避免重复初始化。

我的LongConnectionService.java核心结构如下：

public class LongConnectionService extends Service { private static final int NOTIFICATION_ID = 1001; private WebSocket mWebSocket; private OkHttpWebsocketListener mWebSocketListener; private NotificationManager mNotificationManager; @Override public void onCreate() { super.onCreate(); // 1. 初始化 NotificationChannel（Android 8.0+） createNotificationChannel(); // 2. 初始化 OkHttp Client（单例，避免重复创建） OkHttpClient client = new OkHttpClient.Builder() .pingInterval(30, TimeUnit.SECONDS) // OkHttp 内置心跳 .build(); // 3. 初始化 WebSocketListener（含重连逻辑） mWebSocketListener = new OkHttpWebsocketListener(this); } @Override public int onStartCommand(Intent intent, int flags, int startId) { // 4. 启动前台服务（必须在 onStartCommand 中调用） startForeground(NOTIFICATION_ID, buildNotification()); // 5. 尝试连接（此处启动重连流程） connectToServer(); return START_STICKY; // 系统杀死后，会尝试重启服务 } private void connectToServer() { Request request = new Request.Builder() .url("wss://your-api.com/ws") .build(); mWebSocket = mOkHttpClient.newWebSocket(request, mWebSocketListener); } private Notification buildNotification() { Intent notificationIntent = new Intent(this, MainActivity.class); PendingIntent pendingIntent = PendingIntent.getActivity( this, 0, notificationIntent, PendingIntent.FLAG_IMMUTABLE | PendingIntent.FLAG_ONE_SHOT); return new NotificationCompat.Builder(this, CHANNEL_ID) .setContentTitle("消息服务运行中") .setContentText("实时消息已连接") .setSmallIcon(R.drawable.ic_notification) .setContentIntent(pendingIntent) .setOngoing(true) // 关键！防止用户清除 .build(); } }

避坑重点：

• START_STICKY不是“万能复活符”。系统内存充足时会重启，但若用户主动 Force Stop，服务将永久停止，必须依赖用户再次打开 App 触发。
• setOngoing(true)是防止用户误关的关键。没有它，Notification 可被滑动清除，服务随之停止。
• PendingIntent.FLAG_IMMUTABLE是 Android 12+ 强制要求，漏写会导致startForeground()崩溃。

3.2 心跳机制：双保险设计——OkHttp 内置心跳 + 应用层业务心跳

OkHttp 的pingInterval是第一道防线，但它只保证 TCP 连接层面的活跃，无法验证业务层是否正常。比如服务端 WebSocket 连接池满了，TCP 连接还在，但业务消息发不出去。所以必须叠加应用层心跳。

我的方案是“双心跳协同”：

• OkHttp 层：pingInterval(30, TimeUnit.SECONDS)，由 OkHttp 自动发送 ping 帧，超时自动断开；
• 应用层：JS 层每 45 秒发送一次{"type":"heartbeat","ts":1712345678}消息，原生层收到后立即回复{"type":"pong"}。

为什么间隔不同？避免“同频共振”。如果两者都是 30 秒，网络抖动时可能同时失败，导致误判断连。错开时间，增加容错窗口。

应用层心跳的 JS 实现：

// utils/longConnection.js let heartbeatTimer = null; const HEARTBEAT_INTERVAL = 45000; // 45秒 export const startHeartbeat = () => { if (heartbeatTimer) return; heartbeatTimer = setInterval(() => { const payload = { type: 'heartbeat', ts: Date.now() }; // 通过 NativeModule 发送 LongConnectionModule.send(payload); }, HEARTBEAT_INTERVAL); }; export const stopHeartbeat = () => { if (heartbeatTimer) { clearInterval(heartbeatTimer); heartbeatTimer = null; } };

原生层接收并响应：

// LongConnectionModule.java @ReactMethod public void send(ReadableMap payload, Promise promise) { try { String json = Arguments.toString(payload); if (mWebSocket != null && mWebSocket.isOpen()) { mWebSocket.send(json); promise.resolve(true); } else { promise.reject("CONNECTION_CLOSED", "WebSocket not open"); } } catch (Exception e) { promise.reject("SEND_ERROR", e.getMessage()); } } // 在 OkHttpWebsocketListener.onMessage() 中处理 pong @Override public void onMessage(@NotNull WebSocket webSocket, @NotNull String text) { try { JSONObject obj = new JSONObject(text); String type = obj.optString("type", ""); if ("pong".equals(type)) { // 心跳响应成功，更新最后心跳时间 lastPongTime = System.currentTimeMillis(); } else if ("message".equals(type)) { // 业务消息，转发给 JS 层 sendEventToJS("onMessageReceived", obj); } } catch (JSONException e) { // 忽略非法 JSON } }

注意：lastPongTime是判断“业务层失联”的关键。如果System.currentTimeMillis() - lastPongTime > 90000（90秒），则认为业务心跳失败，触发重连。

3.3 指数退避重连：不只是2^n * base，而是带熔断与随机抖动的工业级策略

指数退避常被简化为“第一次等 1 秒，第二次等 2 秒，第三次等 4 秒……”。这在实验室可行，但在生产环境会引发灾难：当服务端集群宕机，所有客户端在同一时刻重连，形成“雪崩式重连风暴”，压垮刚恢复的服务器。

我的重连策略包含四个维度：

1. 基础退避：baseDelay = 1000ms，maxDelay = 30000ms（30秒）；
2. 随机抖动：每次延迟乘以0.5 ~ 1.5的随机因子，打散重连时间点；
3. 熔断机制：连续 5 次重连失败后，暂停 5 分钟，避免无效轮询；
4. 网络状态感知：结合ConnectivityManager，无网络时不重连，有网络才启动退避计时。

Java 层重连核心逻辑：

private int retryCount = 0; private long lastRetryTime = 0; private static final int MAX_RETRY_COUNT = 5; private static final long MELTDOWN_DURATION = 5 * 60 * 1000; // 5分钟熔断 private void scheduleReconnect() { // 1. 熔断检查 if (retryCount >= MAX_RETRY_COUNT) { long now = System.currentTimeMillis(); if (now - lastRetryTime < MELTDOWN_DURATION) { Log.w("LongConn", "Meltdown active, skip reconnect"); return; } // 熔断期结束，重置计数 retryCount = 0; } // 2. 计算退避延迟（带抖动） long baseDelay = (long) Math.pow(2, retryCount) * 1000; long jitter = (long) (baseDelay * (0.5 + Math.random() * 0.5)); long delay = Math.min(jitter, 30000); // 上限30秒 // 3. 检查网络状态 if (!isNetworkAvailable()) { Log.d("LongConn", "No network, delay reconnect to next network change"); // 注册网络状态广播，下次有网时再重连 return; } // 4. 执行重连 retryCount++; lastRetryTime = System.currentTimeMillis(); new Handler(Looper.getMainLooper()).postDelayed(this::connectToServer, delay); }

为什么需要熔断？我们曾遇到服务端 DNS 故障，客户端重连间隔从 1 秒涨到 16 秒，但第 5 次重连时 DNS 仍不可用，第 6 次又从 1 秒开始……形成无限循环。熔断后，5 分钟内只尝试一次，大幅降低无效请求。

随机抖动的价值：假设 10 万台设备同时断连，不加抖动，它们会在t=0s,t=1s,t=3s,t=7s这几个时间点集中重连。加抖动后，重连时间分散在[0,1.5]s,[1,4.5]s,[3,10.5]s区间，峰值请求量下降 60% 以上。

4. 实操过程：从零搭建可落地的长连接模块（含完整代码与配置）

4.1 第一步：创建 ForegroundService 并配置 Manifest

在android/app/src/main/java/com/yourapp/下新建LongConnectionService.java：

package com.yourapp; import android.app.Notification; import android.app.NotificationChannel; import android.app.NotificationManager; import android.app.PendingIntent; import android.app.Service; import android.content.Context; import android.content.Intent; import android.os.Build; import android.os.IBinder; import androidx.core.app.NotificationCompat; import androidx.core.app.NotificationManagerCompat; import okhttp3.OkHttpClient; import okhttp3.Request; import okhttp3.WebSocket; import okhttp3.WebSocketListener; import okio.ByteString; public class LongConnectionService extends Service { private static final String CHANNEL_ID = "long_connection_channel"; private static final int NOTIFICATION_ID = 1001; private OkHttpClient mOkHttpClient; private WebSocket mWebSocket; private OkHttpWebsocketListener mWebSocketListener; @Override public void onCreate() { super.onCreate(); createNotificationChannel(); initOkHttpClient(); mWebSocketListener = new OkHttpWebsocketListener(this); } private void createNotificationChannel() { if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) { CharSequence name = "长连接服务"; String description = "保持消息实时到达"; int importance = NotificationManager.IMPORTANCE_LOW; NotificationChannel channel = new NotificationChannel(CHANNEL_ID, name, importance); channel.setDescription(description); NotificationManager notificationManager = getSystemService(NotificationManager.class); notificationManager.createNotificationChannel(channel); } } private void initOkHttpClient() { mOkHttpClient = new OkHttpClient.Builder() .pingInterval(30, TimeUnit.SECONDS) .build(); } @Override public int onStartCommand(Intent intent, int flags, int startId) { startForeground(NOTIFICATION_ID, buildNotification()); connectToServer(); return START_STICKY; } private void connectToServer() { Request request = new Request.Builder() .url("wss://your-api.com/ws") // 替换为你的 WebSocket 地址 .build(); mWebSocket = mOkHttpClient.newWebSocket(request, mWebSocketListener); } private Notification buildNotification() { Intent notificationIntent = new Intent(this, MainActivity.class); PendingIntent pendingIntent = PendingIntent.getActivity( this, 0, notificationIntent, PendingIntent.FLAG_IMMUTABLE | PendingIntent.FLAG_ONE_SHOT); return new NotificationCompat.Builder(this, CHANNEL_ID) .setContentTitle("消息服务运行中") .setContentText("实时消息已连接") .setSmallIcon(R.drawable.ic_notification) // 需准备图标 .setContentIntent(pendingIntent) .setOngoing(true) .build(); } @Override public IBinder onBind(Intent intent) { return null; } @Override public void onDestroy() { super.onDestroy(); if (mWebSocket != null) { mWebSocket.cancel(); } mOkHttpClient.dispatcher().cancelAll(); } }

在android/app/src/main/AndroidManifest.xml的<application>标签下添加：

<service android:name=".LongConnectionService" android:enabled="true" android:exported="false" android:foregroundServiceType="specialUse" />

并在<application>外部（同级）添加权限：

<uses-permission android:name="android.permission.FOREGROUND_SERVICE" /> <uses-permission android:name="android.permission.POST_NOTIFICATIONS" /> <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

4.2 第二步：实现 OkHttp WebSocketListener 与重连逻辑

新建OkHttpWebsocketListener.java：

package com.yourapp; import android.util.Log; import androidx.annotation.NonNull; import okhttp3.Response; import okhttp3.WebSocket; import okhttp3.WebSocketListener; import okio.ByteString; import org.json.JSONObject; public class OkHttpWebsocketListener extends WebSocketListener { private final LongConnectionService service; private long lastPongTime = System.currentTimeMillis(); public OkHttpWebsocketListener(LongConnectionService service) { this.service = service; } @Override public void onOpen(@NonNull WebSocket webSocket, @NonNull Response response) { Log.i("LongConn", "WebSocket connected"); service.setWebSocket(webSocket); lastPongTime = System.currentTimeMillis(); // 启动心跳 service.startHeartbeat(); } @Override public void onMessage(@NonNull WebSocket webSocket, @NonNull String text) { try { JSONObject obj = new JSONObject(text); String type = obj.optString("type", ""); if ("pong".equals(type)) { lastPongTime = System.currentTimeMillis(); } else { // 转发业务消息到 JS 层 service.sendEventToJS("onMessageReceived", obj); } } catch (Exception e) { Log.e("LongConn", "Parse message error", e); } } @Override public void onFailure(@NonNull WebSocket webSocket, @NonNull Throwable t, Response response) { Log.e("LongConn", "WebSocket failure", t); service.handleConnectionFailure(); } @Override public void onClosed(@NonNull WebSocket webSocket, int code, @NonNull String reason) { Log.i("LongConn", "WebSocket closed: " + code + " " + reason); service.handleConnectionClosed(); } }

在LongConnectionService.java中添加辅助方法：

// 添加成员变量 private boolean isConnecting = false; // 在 connectToServer() 中添加 private void connectToServer() { if (isConnecting) return; // 防止重复连接 isConnecting = true; // ... 原有连接代码 ... } // 添加连接失败处理 public void handleConnectionFailure() { isConnecting = false; scheduleReconnect(); } public void handleConnectionClosed() { isConnecting = false; scheduleReconnect(); } // 添加 setWebSocket 方法 public void setWebSocket(WebSocket webSocket) { this.mWebSocket = webSocket; } // 添加 sendEventToJS 方法（用于向 JS 发送事件） public void sendEventToJS(String eventName, Object data) { WritableMap params = Arguments.createMap(); if (data instanceof JSONObject) { try { params.putString("data", ((JSONObject) data).toString()); } catch (Exception e) { Log.e("LongConn", "JSON stringify error", e); } } getReactApplicationContext() .getJSModule(DeviceEventManagerModule.RCTDeviceEventEmitter.class) .emit(eventName, params); }

4.3 第三步：创建 NativeModule 暴露 JS 接口

新建LongConnectionModule.java：

package com.yourapp; import androidx.annotation.NonNull; import com.facebook.react.bridge.Promise; import com.facebook.react.bridge.ReactApplicationContext; import com.facebook.react.bridge.ReactContextBaseJavaModule; import com.facebook.react.bridge.ReactMethod; import com.facebook.react.bridge.ReadableMap; import com.facebook.react.modules.core.DeviceEventManagerModule; public class LongConnectionModule extends ReactContextBaseJavaModule { private final LongConnectionService service; public LongConnectionModule(ReactApplicationContext context) { super(context); this.service = new LongConnectionService(); // 注意：这里需改为单例获取，实际应通过 Application 获取 } @NonNull @Override public String getName() { return "LongConnectionModule"; } @ReactMethod public void startConnection(Promise promise) { try { // 启动服务 Intent intent = new Intent(getReactApplicationContext(), LongConnectionService.class); getReactApplicationContext().startService(intent); promise.resolve(true); } catch (Exception e) { promise.reject("START_ERROR", e.getMessage()); } } @ReactMethod public void send(ReadableMap payload, Promise promise) { // 实现见前文 } }

在android/app/src/main/java/com/yourapp/MainApplication.java的getPackages()方法中注册：

@Override protected List<ReactPackage> getPackages() { @SuppressWarnings("UnnecessaryLocalVariable") List<ReactPackage> packages = new PackageList(this).getPackages(); packages.add(new LongConnectionPackage()); // 创建新 Package return packages; }

新建LongConnectionPackage.java：

package com.yourapp; import com.facebook.react.ReactPackage; import com.facebook.react.bridge.NativeModule; import com.facebook.react.bridge.ReactApplicationContext; import com.facebook.react.uimanager.ViewManager; import java.util.ArrayList; import java.util.Collections; import java.util.List; public class LongConnectionPackage implements ReactPackage { @Override public List<NativeModule> createNativeModules(ReactApplicationContext reactContext) { List<NativeModule> modules = new ArrayList<>(); modules.add(new LongConnectionModule(reactContext)); return modules; } @Override public List<ViewManager> createViewManagers(ReactApplicationContext reactContext) { return Collections.emptyList(); } }

4.4 第四步：JS 层集成与使用

安装必要依赖：

npm install react-native-device-event-emitter # 或 yarn add react-native-device-event-emitter

创建src/utils/longConnection.js：

import { NativeModules, DeviceEventEmitter } from 'react-native'; import { useEffect, useRef } from 'react'; const { LongConnectionModule } = NativeModules; const eventEmitter = DeviceEventEmitter; // 全局状态 const connectionState = { isConnected: false, lastMessage: null, }; export const useLongConnection = () => { const messageHandlerRef = useRef(null); useEffect(() => { // 监听原生事件 const subscription = eventEmitter.addListener('onMessageReceived', (event) => { try { const data = JSON.parse(event.data); connectionState.lastMessage = data; connectionState.isConnected = true; if (messageHandlerRef.current) { messageHandlerRef.current(data); } } catch (e) { console.warn('Parse native message error', e); } }); // 启动连接 LongConnectionModule.startConnection() .then(() => { console.log('Long connection started'); }) .catch((err) => { console.error('Start connection failed', err); }); return () => { subscription.remove(); // 可选：断开连接 // LongConnectionModule.stopConnection(); }; }, []); const sendMessage = (payload) => { if (typeof payload === 'object') { LongConnectionModule.send(payload, (success) => { if (!success) console.warn('Send failed'); }); } }; return { sendMessage, setOnMessage: (handler) => { messageHandlerRef.current = handler; }, getConnectionState: () => ({ isConnected: connectionState.isConnected, lastMessage: connectionState.lastMessage, }), }; }; // 独立函数式调用 export const startLongConnection = () => { return LongConnectionModule.startConnection(); }; export const sendLongConnectionMessage = (payload) => { return new Promise((resolve, reject) => { LongConnectionModule.send(payload, (result) => { if (result) resolve(result); else reject(new Error('Send failed')); }); }); };

在组件中使用：

import React, { useEffect } from 'react'; import { View, Text, Button } from 'react-native'; import { useLongConnection } from './utils/longConnection'; const ChatScreen = () => { const { sendMessage, setOnMessage, getConnectionState } = useLongConnection(); useEffect(() => { setOnMessage((message) => { console.log('Received:', message); // 更新 UI 或 Redux }); }, []); const handleSend = () => { sendMessage({ type: 'chat', content: 'Hello from RN!', timestamp: Date.now(), }); }; return ( <View> <Text>Status: {getConnectionState().isConnected ? 'Connected' : 'Disconnected'}</Text> <Button title="Send Message" onPress={handleSend} /> </View> ); }; export default ChatScreen;

5. 常见问题与排查技巧实录：那些文档里找不到的“血泪教训”

5.1 问题速查表：高频故障与定位路径

5.2 实操心得：三年踩坑总结的 5 条铁律

铁律一：永远在onCreate()初始化，不在onStartCommand()
我最初把 OkHttp Client 创建放在onStartCommand()，结果服务被系统重启时，onStartCommand()重复调用，Client 被创建多次，内存泄漏。正确做法：onCreate()是服务生命周期的起点，只执行一次，所有单例初始化放这里。

铁律二：startForeground()必须在onStartCommand()中，且必须在return前
曾经为了“先连再显通知”，我把startForeground()放在connectToServer()成功回调里。结果onStartCommand()返回START_STICKY后，服务因未前台化被系统杀死。记住：startForeground()是“保命符”，必须第一时间亮出来。

铁律三：JS 层的AppState监听只用于“辅助”，不能替代原生服务
有人想用AppState.addEventListener('background', () => { /* 启动服务 */ })，但AppState在后台可能不触发，或触发延迟。正确姿势：App 启动时就startService()，让服务常驻，JS 层只负责业务交互。

铁律四：Notification 图标必须用Adaptive Icon，且ic_notification.xml放在mipmap目录
普通 PNG 图标在 Android 8.0+ 会显示为白方块。必须创建res/mipmap/ic_notification.xml，使用<adaptive-icon>标签，并在AndroidManifest.xml中引用@mipmap/ic_notification。

铁律五：重连时务必cancel()旧 WebSocket
mWebSocket.cancel()不是可选操作。不取消旧连接，新连接建立时旧连接的onFailure()可能仍在回调，导致scheduleReconnect()被多次调用，形成重连风暴。

5.3 性能与稳定性压测数据（实测结果）

我们在一台 Pixel 4a（Android 12）上进行了 72 小时压测，模拟弱网（3G，丢包率 5%）、频繁切后台、锁屏唤醒等场景：