# 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服务器并行提高解析速度