android-frame/frame/network/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

frame/network 模块架构

这是一个功能完备的Android网络框架模块，基于Retrofit + OkHttp实现，提供HTTP请求、WebSocket长连接、智能DNS解析、网络防封禁等功能。

核心架构设计

主要组件：

• NetworkService: 核心网络服务实现类，统一管理所有网络功能
• INetworkService: 对外统一接口，集成HTTP、WebSocket、主机管理等能力
• INetworkConfig: 网络配置接口，提供各种配置参数和回调

关键子系统：

1. 多场景HTTP客户端: 针对不同使用场景提供专门优化的OkHttp客户端

   • protocolHttpClient: 业务协议请求，包含缓存、拦截器链
   • imageHttpClient: 图片下载，优化连接超时
   • webHttpClient: Web资源下载，支持Cookie管理和缓存
   • fileHttpClient: 文件下载，长超时时间(5分钟)
   • statHttpClient: 统计上报，简化拦截器
   • dnsClient: DNS解析专用，短超时配置

2. WebSocket长连接管理 (NetworkService:116-1191):

   • 连接状态管理：DISCONNECT/CONNECTING/CONNECTED/DISCONNECTING
   • 自动重连机制：最多重连3次
   • 消息序列号管理和超时处理
   • 心跳保活：20秒ping间隔
   • 通知订阅和拦截器支持

3. 智能DNS解析系统 (dns/HttpsDns.kt):

   • DNS-over-HTTPS (DoH) 竞速解析
   • 本地TTL缓存管理
   • 系统DNS兜底
   • IP验证和引导DNS

4. 网络防封禁系统 (ban/NetAntiBanManager.kt):

   • 动态配置获取：HTTP + GitHub双通道
   • 配置优先级：用户 > 国家 > 全局
   • 主机域名替换和IP映射
   • 定时配置更新（5分钟间隔）

5. 主机管理和容错 (host/HostManager.kt):

   • 主备域名管理
   • 主机健康检查：6次错误后丢弃
   • 故障自动切换
   • 随机负载均衡

架构实现要点

WebSocket消息协议

• 消息格式：{ "msg": { "uri": "接口路径", "data": {...} }, "info": {...} }
• 序列号机制：每个请求分配唯一seqId用于响应匹配
• 协议编码：支持GZIP压缩传输
• 超时处理：20秒请求超时，自动清理

DNS解析优化

• 竞速机制: 多个DoH服务器并行解析，返回最快结果
• 缓存策略: 本地TTL缓存，避免重复解析
• 兜底机制: DoH失败时使用系统DNS + 配置IP映射

网络拦截器链路

协议HTTP客户端拦截器链（按顺序）：

1. HttpHostSelectInterceptor: 智能主机选择
2. HttpCommonHeaderInterceptor: 通用请求头注入
3. HttpProtocolStatInterceptor: 协议统计上报
4. HttpLoggingInterceptor: 调试日志（仅Debug模式）
5. 用户自定义拦截器

关键配置说明

• CONNECT_TIMEOUT = 30s: 连接超时，考虑DNS解析IP重试
• IO_TIMEOUT = 20s: IO读写超时
• PING_INTERVAL = 20s: WebSocket心跳间隔
• RECONNECT_MAX_COUNT = 3: 最大重连次数

测试策略

单元测试重点

• 防封禁配置合并逻辑（NetAntiBanManagerTest.kt）
• 用户匹配和国家匹配算法
• JSON序列化和反序列化

集成测试建议

• WebSocket连接和重连机制
• DNS解析竞速和缓存
• 主机故障切换
• 网络监控统计上报

依赖关系

外部依赖：

• okhttp: 核心HTTP客户端
• retrofit: HTTP接口定义（compileOnly）
• conscrypt: SSL/TLS优化

内部依赖：

• frame:base: 基础框架（日志、回调等）
• frame:data: 数据结构和JSON处理
• frame:coroutine: 协程调度器
• frame:util: 通用工具类
• frame:statistics: 统计事件上报

重要实现细节

主机故障处理流程

1. 网络请求失败时调用 markHostError()
2. 错误计数达到6次后从可用列表移除
3. 当前主机不可用时自动切换到备用主机
4. 所有主机不可用时触发防封禁配置更新

WebSocket消息处理流程

1. 消息发送前注入seqId和编码类型
2. 服务端响应时根据seqId匹配原始请求
3. 超时未响应的请求自动清理并回调错误
4. 支持服务端主动推送（notify）和合并消息（CTL_MERGE）

DNS缓存管理

• 使用ConcurrentHashMap保证线程安全
• 每个DNS记录包含TTL信息
• 缓存命中时检查TTL有效性
• 过期记录惰性清理，由新请求覆盖

开发注意事项

1. 线程安全: 所有公开接口都是线程安全的，内部使用ConcurrentHashMap等并发容器
2. 内存泄漏: WebSocket监听器需要手动注销，避免Activity泄漏
3. 网络切换: 框架会自动检测网络状态，无网络时不进行主机错误标记
4. 调试日志: 生产环境会关闭详细日志，开发时通过AppBase.debugLog控制
5. 配置热更新: 防封禁配置支持动态更新，无需重启应用

性能优化要点

• DNS预加载: preloadDomain()可在应用启动时预解析关键域名
• 连接复用: OkHttp连接池自动管理，避免频繁握手
• 数据压缩: WebSocket支持GZIP压缩，减少流量消耗
  
• 缓存策略: HTTP缓存和DNS缓存减少重复请求
• 竞速解析: 多DoH服务器并行提高解析速度