企业官网建设流程全解析

• 后端
• 即时通讯

本指南以官方仓库中的 faq.md 文档为主体，围绕 socket.io-client-java 使用过程中最常被问到的六大问题展开：服务端 Cookie 的持久化与携带、AWS 负载均衡下的粘性会话、强制 TLS v1.2+、创建大量客户端时的 OkHttp 并发限制、客户端进程无法退出的问题，以及把事件参数（JSONObject）映射成 POJO 的两套方案。读完本文，你将掌握通过自定义IO.Options与 OkHttpClient 解决上述问题的完整可运行代码，并理解这些配置在 IO.java 与 Manager.java 底层是如何被消费的。

背景：为什么这些问题的答案都绕不开 OkHttp

socket.io-client-java 是一个与 Socket.IO v1.0 及以后版本兼容的 Java 客户端库，其网络层（HTTP 请求与 WebSocket 连接）完全由 OkHttp 驱动，同时依赖 engine.io-client 实现底层传输。这一点从 pom.xml 的依赖声明中可以确认：engine.io-client:2.1.0被声明为核心依赖，而 engine.io-client 内部再依赖okhttp:3.12.12。

因此，本 FAQ 中几乎所有问题的解决方案都有一个共同形态：自行构建一个 OkHttpClient，通过IO.Options的两个字段注入给客户端：

IO.Options options = new IO.Options(); options.callFactory = okHttpClient; // 负责 HTTP 请求（如 long-polling） options.webSocketFactory = okHttpClient; // 负责 WebSocket 连接 Socket socket = IO.socket(URI.create("https://example.com"), options);

在源码层面，Manager.java 定义了静态的defaultWebSocketFactory与defaultCallFactory；当用户传入的Options中对应字段为 null 时，Manager 构造函数 会回退到这两个默认工厂。此外，IO.java 还提供了IO.setDefaultOkHttpWebSocketFactory(...)与IO.setDefaultOkHttpCallFactory(...)两个静态方法，用于为所有socket 实例设置默认的 OkHttp 客户端（即 usage 文档中「default settings for all sockets」的写法，见 usage.md）。

如何处理 Cookie：把服务端下发的 Cookie 存下来并在后续请求中自动携带

在需要会话保持（session persistence）的场景下，服务端通过Set-Cookie下发 Cookie，客户端必须在后续每次请求中携带它们。socket.io-client-java 本身不做 Cookie 持久化，因此需要你提供一个带自定义CookieJar的 OkHttpClient。

方案一：手写一个内存版 CookieJar

文档给出了一份完整的自实现，核心是CookieJar的两个接口方法：saveFromResponse在收到响应时保存 Cookie，loadForRequest在发起请求前回填 Cookie：

public class MyApp { public static void main(String[] argz) throws Exception { IO.Options options = new IO.Options(); OkHttpClient okHttpClient = new OkHttpClient.Builder() .cookieJar(new MyCookieJar()) .build(); options.callFactory = okHttpClient; options.webSocketFactory = okHttpClient; Socket socket = IO.socket(URI.create("https://example.com"), options); socket.connect(); } private static class MyCookieJar implements CookieJar { private Set<WrappedCookie> cache = new HashSet<>(); @Override public void saveFromResponse(HttpUrl url, List<Cookie> cookies) { for (Cookie cookie : cookies) { this.cache.add(new WrappedCookie(cookie)); } } @Override public List<Cookie> loadForRequest(HttpUrl url) { List<Cookie> cookies = new ArrayList<>(); Iterator<WrappedCookie> iterator = this.cache.iterator(); while (iterator.hasNext()) { Cookie cookie = iterator.next().cookie; if (isCookieExpired(cookie)) { iterator.remove(); // 过期即清理 } else if (cookie.matches(url)) { // 只返回匹配当前 URL 的 Cookie cookies.add(cookie); } } return cookies; } private static boolean isCookieExpired(Cookie cookie) { return cookie.expiresAt() < System.currentTimeMillis(); } } private static class WrappedCookie { private final Cookie cookie; public WrappedCookie(Cookie cookie) { this.cookie = cookie; } @Override public boolean equals(Object o) { if (!(o instanceof WrappedCookie)) return false; WrappedCookie that = (WrappedCookie) o; return that.cookie.name().equals(this.cookie.name()) && that.cookie.domain().equals(this.cookie.domain()) && that.cookie.path().equals(this.cookie.path()) && that.cookie.secure() == this.cookie.secure() && that.cookie.hostOnly() == this.cookie.hostOnly(); } @Override public int hashCode() { int hash = 17; hash = 31 * hash + cookie.name().hashCode(); hash = 31 * hash + cookie.domain().hashCode(); hash = 31 * hash + cookie.path().hashCode(); hash = 31 * hash + (cookie.secure() ? 0 : 1); hash = 31 * hash + (cookie.hostOnly() ? 0 : 1); return hash; } } }

值得注意的实现细节：

• WrappedCookie重写了equals/hashCode，比较的字段是 name、domain、path、secure、hostOnly——这样同一 Cookie 名的重复下发会被HashSet去重覆盖，避免缓存膨胀。
• loadForRequest中先做expiresAt()过期判断再调用cookie.matches(url)，保证既不过期、又属于当前请求域名的 Cookie 才会被带上。
• 该实现仅保存在内存中，进程重启后 Cookie 丢失；需要跨进程/跨重启持久化请使用方案二。

方案二：直接使用 PersistentCookieJar 库

如果你不想手写，可以使用 PersistentCookieJar 这类现成实现（配合SetCookieCache与SharedPrefsCookiePersistor，后者非常适合 Android 的 SharedPreferences 场景）：

public class MyApp { public static void main(String[] argz) throws Exception { IO.Options options = new IO.Options(); ClearableCookieJar cookieJar = new PersistentCookieJar(new SetCookieCache(), new SharedPrefsCookiePersistor(context)); OkHttpClient okHttpClient = new OkHttpClient.Builder() .cookieJar(cookieJar) .build(); options.callFactory = okHttpClient; options.webSocketFactory = okHttpClient; Socket socket = IO.socket(URI.create("https://example.com"), options); socket.connect(); } }

测试佐证：仓库测试代码 executions/Connection.java 与 SSLConnectionTest.java 均采用「构造 OkHttpClient → 同时赋给options.callFactory与options.webSocketFactory」的写法，说明这是官方验证过的注入方式。

如何配合 AWS 负载均衡：粘性会话与 AWSALB Cookie

当把 Socket.IO 服务横向扩展到多个节点时，同一个会话的所有 HTTP 请求必须落在同一台服务器上（因为每个节点只持有自己连接的内存状态）。AWS 应用型负载均衡（ALB）通过向客户端下发一个名为AWSALB的 Cookie 来实现粘性会话（sticky sessions）。

对客户端而言，处理方式就一句话：把AWSALBCookie 正确地存下来并随后续请求回传。这正是上一节「如何处理 Cookie」要解决的问题——AWSALB与普通会话 Cookie 没有本质区别，只需把上面的自定义 CookieJar 或 PersistentCookieJar 方案接入即可。也就是说，先按上节做法配置 CookieJar，再配合 ALB 开启粘性会话，即可保证同一 Socket.IO 会话的所有请求都命中同一节点。

更进一步的说明可参考官方针对该问题的解释：当服务端向客户端发送AWSALBCookie 时，它会被saveFromResponse捕获；此后该域的后续请求（包括 Engine.IO 的握手与 long-polling 轮询）都会在loadForRequest中带上它，从而让 ALB 把请求路由回同一个后端实例。

如何强制 TLS v1.2 及以上：用 ConnectionSpec.RESTRICTED_TLS 覆盖默认 TLS 配置

如文首所述，库的 HTTP 与 WebSocket 层由 OkHttp 承担。当前版本依赖 OkHttp3.12.12——它是最后一个同时支持 Java 7+ 与 Android 2.3+（API level 9+）的版本。该版本默认启用MODERN_TLS配置，会允许TLSv1与TLSv1.1，这在安全合规要求严格的场景（如金融、政务内网）往往不被接受。

解决方式是提供自定义 OkHttpClient，通过connectionSpecs明确限定只使用ConnectionSpec.RESTRICTED_TLS（该规范只启用 TLS v1.2 及以上）：

OkHttpClient okHttpClient = new OkHttpClient.Builder() .connectionSpecs(Arrays.asList( ConnectionSpec.RESTRICTED_TLS )) .readTimeout(1, TimeUnit.MINUTES) // important for HTTP long-polling .build(); IO.Options options = new IO.Options(); options.callFactory = okHttpClient; options.webSocketFactory = okHttpClient; Socket socket = IO.socket(URI.create("https://example.com"), options);

两个使用要点：

1. readTimeout(1, TimeUnit.MINUTES)几乎是此类场景的标配：HTTP long-polling 模式下，客户端会有一个长期挂起的 GET 请求用来接收服务端推送，默认较短的读超时会导致轮询请求被误判为超时中断。文档在「创建大量客户端」与「正确关闭客户端」两节中也反复强调这一点。
2. 文档明确备注：下一个大版本（major version）将升级到 OkHttp 4。如果你已经在项目中直接依赖 OkHttp 4，请注意与当前库依赖的 3.x API 兼容性问题。

关于自定义 SSL/TLS 的完整形态，可参考仓库测试 SSLConnectionTest.java：它构造了带自定义KeyStore、SSLContext、HostnameVerifier的 OkHttpClient，既可通过options.callFactory/options.webSocketFactory按实例注入（connect测试），也可通过IO.setDefaultOkHttpCallFactory(...)/IO.setDefaultOkHttpWebSocketFactory(...)设为全局默认（defaultSSLContext测试），并在tearDown()中置空恢复。

如何创建大量客户端：突破 OkHttp Dispatcher 的每主机 5 连接上限

默认情况下你无法创建超过 5 个Socket.IO 客户端——第 6 个及以后的客户端会被断开，报错原因通常是 "transport error" 或 "ping timeout"。根因是默认 OkHttpDispatcher的maxRequestsPerHost为 5：同一个 host 上同时执行的请求数超过 5 后，多余的请求会排队等待，从而拖垮握手与心跳。

通过自定义Dispatcher提升上限即可：

int MAX_CLIENTS = 100; Dispatcher dispatcher = new Dispatcher(); dispatcher.setMaxRequests(MAX_CLIENTS * 2); dispatcher.setMaxRequestsPerHost(MAX_CLIENTS * 2); OkHttpClient okHttpClient = new OkHttpClient.Builder() .dispatcher(dispatcher) .readTimeout(1, TimeUnit.MINUTES) // important for HTTP long-polling .build(); IO.Options options = new IO.Options(); options.callFactory = okHttpClient; options.webSocketFactory = okHttpClient; for (int i = 0; i < MAX_CLIENTS; i++) { Socket socket = IO.socket(URI.create("https://example.com"), options); }

为什么是MAX_CLIENTS * 2？文档给出了精确解释：HTTP long-polling 模式下，每个客户端同时存在两条请求——一条长期挂起的 GET 请求（接收服务端数据）与一条按需发起的 POST 请求（发送数据）。所以若目标并发客户端数为MAX_CLIENTS，请求上限至少要设为2 * MAX_CLIENTS，setMaxRequests与setMaxRequestsPerHost都应如此设置。若客户端处于 WebSocket 模式则长连接只有一条，可按需下调，但乘以 2 是安全的上限策略。

如何正确关闭客户端：不止 disconnect()，还要关闭 OkHttp 的线程池

只调用socket.disconnect()可能不够。原因在于 OkHttp 的Dispatcher在内部创建一个ThreadPoolExecutor（默认存活 60 秒），该线程池会阻止 Java 程序正常退出——表现为程序在结束后还挂起约 60 秒。

正确姿势：持有Dispatcher引用，在disconnect()之后手动shutdown()其executorService()：

Dispatcher dispatcher = new Dispatcher(); OkHttpClient okHttpClient = new OkHttpClient.Builder() .dispatcher(dispatcher) .readTimeout(1, TimeUnit.MINUTES) // important for HTTP long-polling .build(); IO.Options options = new IO.Options(); options.callFactory = okHttpClient; options.webSocketFactory = okHttpClient; Socket socket = IO.socket(URI.create("https://example.com"), options); socket.connect(); // then later socket.disconnect(); dispatcher.executorService().shutdown();

仓库中的可执行示例 executions/Connection.java 印证了这一模式：它在 engine 层close事件触发后调用client.dispatcher().executorService().shutdown()，保证示例进程能干净退出。注意dispatcher.executorService()与client.dispatcher()是同一个实例——你也可以像示例那样只保留 OkHttpClient 引用，用client.dispatcher().executorService().shutdown()完成关闭。

如何把事件参数映射成 POJO：基于 org.json 的两种转换方案

为什么收到的是 JSONObject：从解析器源码看数据类型

本库使用org.json包中的JSONTokener解析服务端下发的数据包，因此事件监听器里收到的是JSONObject/JSONArray。这一点有源码佐证：IOParser.java 的decodeString方法在剥离包类型、命名空间、ack id 后，用new JSONTokener(str.substring(i)).nextValue()解析剩余负载，并在 isPayloadValid 中校验 EVENT 包的 payload 必须是JSONArray（首个元素为事件名）。随后 Socket.java 的onevent将JSONArray展开为参数数组并派发给监听器。

因此「把事件参数转成业务 POJO」就成为高频需求，官方文档给出了 Jackson 与 Gson 两套方案。

方案一：Jackson（配合 jackson-datatype-json-org）

pom.xml引入三个依赖（注意jackson-datatype-json-org专门提供JsonOrgModule，能让 Jackson 直接读写 org.json 的对象）：

<?xml version="1.0" encoding="UTF-8"?> <project> <dependencies> <dependency> <groupId>com.fasterxml.jackson.core</groupId> <artifactId>jackson-core</artifactId> <version>2.13.3</version> </dependency> <dependency> <groupId>com.fasterxml.jackson.core</groupId> <artifactId>jackson-databind</artifactId> <version>2.13.3</version> </dependency> <dependency> <groupId>com.fasterxml.jackson.datatype</groupId> <artifactId>jackson-datatype-json-org</artifactId> <version>2.13.3</version> </dependency> ... </dependencies> ... </project>

业务代码里注册JsonOrgModule后，直接用convertValue把args[0]（JSONObject）转成 POJO：

public class MyApp { private static final ObjectMapper MAPPER = new ObjectMapper().registerModule(new JsonOrgModule()); public static void main(String[] argz) throws Exception { Socket socket = IO.socket(URI.create("https://example.com")); socket.on("my-event", (args) -> { MyObject object = MAPPER.convertValue(args[0], MyObject.class); // ... }); socket.connect(); } public static class MyObject { public int id; public String label; } }

方案二：Gson（两种写法）

pom.xml引入 Gson：

<?xml version="1.0" encoding="UTF-8"?> <project> <dependencies> <dependency> <groupId>com.google.code.gson</groupId> <artifactId>gson</artifactId> <version>2.8.9</version> </dependency> ... </dependencies> ... </project>

写法 A：先toString()再fromJson。利用JSONObject.toString()输出 JSON 字符串，交给 Gson 解析。代码最简洁，但多一次字符串序列化开销：

public class MyApp { private static final Gson GSON = new Gson(); public static void main(String[] argz) throws Exception { Socket socket = IO.socket(URI.create("https://example.com")); socket.on("my-event", (args) -> { MyObject object = GSON.fromJson(args[0].toString(), MyObject.class); // ... }); socket.connect(); } public static class MyObject { public int id; public String label; } }

写法 B：手写递归转换，把 JSONObject 映射为 Gson 的 JsonObject（性能更优）。文档注释指出这是为了性能——省去toString()产生的中间字符串。核心是两组重载的map方法，递归处理嵌套的JSONObject、JSONArray与基础类型：

public class MyApp { private static final Gson GSON = new Gson(); public static void main(String[] argz) throws Exception { Socket socket = IO.socket(URI.create("https://example.com")); socket.on("my-event", (args) -> { MyObject object = GSON.fromJson(map(args[0]), MyObject.class); // ... }); socket.connect(); } public static class MyObject { public int id; public String label; } public static JsonObject map(JSONObject source) throws JSONException { JsonObject output = new JsonObject(); Iterator<String> iterator = source.keys(); while (iterator.hasNext()) { String key = iterator.next(); Object value = source.get(key); if (value instanceof JSONObject) { output.add(key, map((JSONObject) value)); } else if (value instanceof JSONArray) { output.add(key, map((JSONArray) value)); } else if (value instanceof Number) { output.addProperty(key, (Number) value); } else if (value instanceof String) { output.addProperty(key, (String) value); } else if (value instanceof Boolean) { output.addProperty(key, (Boolean) value); } else if (value instanceof Character) { output.addProperty(key, (Character) value); } } return output; } public static JsonArray map(JSONArray source) throws JSONException { JsonArray output = new JsonArray(); for (int i = 0; i < source.length(); i++) { Object value = source.get(i); if (value instanceof JSONObject) { output.add(map((JSONObject) value)); } else if (value instanceof JSONArray) { output.add(map((JSONArray) value)); } else if (value instanceof Number) { output.add((Number) value); } else if (value instanceof String) { output.add((String) value); } else if (value instanceof Boolean) { output.add((Boolean) value); } else if (value instanceof Character) { output.add((Character) value); } } return output; } }

选型建议：数据量大、吞吐敏感时选 Jackson 方案或 Gson 写法 B；追求最少依赖、代码最直白时选 Gson 写法 A。三种写法都保留了 POJO 的普通字段映射（如id、label），无需额外注解。

补充阅读与常见陷阱

• 版本兼容性：本库与 Socket.IO 服务端的兼容关系参见 installation.md：客户端 1.x 对应服务端 2.x（或以allowEIO3: true连接 3.1.x/4.x），客户端 2.x 对应服务端 3.x/4.x。FAQ 中所有示例均以客户端 2.x 时代的 API 为准。
• IO.socket的连接复用语义：IO.java 中managers缓存机制决定：相同 URI 默认复用同一个Manager（支持多命名空间 multiplexing）；若需强制新建连接，请设置options.forceNew = true——在批量创建客户端时这通常是必须的，因为默认缓存会导致多个Socket共享底层连接。
• 依赖版本说明：仓库当前pom.xml声明的版本为2.1.3-SNAPSHOT（pom.xml），文档正文引用的稳定发布版以 Maven Central 实际可用版本为准；OkHttp 仍为 3.12.12，升级到 OkHttp 4 的计划在下一个大版本。

• 后端
• 即时通讯