网络通信基础

// OkHttp 证书锁定示例
val client = OkHttpClient.Builder()
    .certificatePinner(
        CertificatePinner.Builder()
            // 添加域名和证书 SHA-256 公钥哈希
            // 格式: "sha256/AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA="
            .add("api.example.com", "sha256/BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB=")
            // 添加备用证书哈希，防止证书轮换时应用失效
            .add("api.example.com", "sha256/CCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCC=")
            .build()
    )
    .build()

// 完整的 HttpURLConnection GET 请求示例
public String performGetRequest(String urlString) throws IOException {
    // 创建 URL 对象，urlString 是目标服务器地址
    URL url = new URL(urlString);
    
    // 打开连接，此时并未真正建立网络连接
    // 对于 HTTPS URL，返回的实际是 HttpsURLConnection 实例
    HttpURLConnection connection = (HttpURLConnection) url.openConnection();
    
    // 设置请求方法为 GET（默认就是 GET，这里显式声明）
    connection.setRequestMethod("GET");
    
    // 设置连接超时时间（单位：毫秒）
    // 超时后会抛出 java.net.SocketTimeoutException
    connection.setConnectTimeout(15000);
    
    // 设置读取超时时间（单位：毫秒）
    // 指从建立连接到读取到数据的最大等待时间
    connection.setReadTimeout(10000);
    
    // 设置请求头，告知服务器期望的响应格式
    connection.setRequestProperty("Accept", "application/json");
    
    // 使用 try-with-resources 确保资源自动关闭
    // 调用 getInputStream() 时才会真正发起网络请求
    try (InputStream inputStream = connection.getInputStream();
         // 使用 BufferedReader 提高读取效率
         BufferedReader reader = new BufferedReader(
             new InputStreamReader(inputStream, StandardCharsets.UTF_8))) {
        
        // StringBuilder 用于拼接响应内容
        StringBuilder response = new StringBuilder();
        String line;
        
        // 逐行读取响应体内容
        while ((line = reader.readLine()) != null) {
            response.append(line);
        }
        
        // 返回完整的响应字符串
        return response.toString();
        
    } finally {
        // 断开连接，释放资源
        // 注意：这不会关闭底层 socket，socket 可能被连接池复用
        connection.disconnect();
    }
}

// 完整的 HttpURLConnection POST 请求示例
public String performPostRequest(String urlString, String jsonBody) throws IOException {
    URL url = new URL(urlString);
    HttpURLConnection connection = (HttpURLConnection) url.openConnection();
    
    // POST 请求必须设置请求方法
    connection.setRequestMethod("POST");
    
    // 核心设置：启用输出模式，表示要向服务器发送请求体
    // 不设置此项将无法获取 OutputStream
    connection.setDoOutput(true);
    
    // 设置 Content-Type 告知服务器请求体格式
    connection.setRequestProperty("Content-Type", "application/json; charset=UTF-8");
    
    // 设置 Content-Length 便于服务器处理
    byte[] bodyBytes = jsonBody.getBytes(StandardCharsets.UTF_8);
    connection.setRequestProperty("Content-Length", String.valueOf(bodyBytes.length));
    
    // 超时设置
    connection.setConnectTimeout(15000);
    connection.setReadTimeout(10000);
    
    // 获取输出流并写入请求体
    // getOutputStream() 调用会隐式建立连接并发送请求头
    try (OutputStream outputStream = connection.getOutputStream()) {
        // 写入 JSON 请求体
        outputStream.write(bodyBytes);
        // flush 确保数据被发送出去
        outputStream.flush();
    }
    
    // 获取响应状态码
    int responseCode = connection.getResponseCode();
    
    // 根据状态码选择正确的输入流
    InputStream inputStream;
    if (responseCode >= 200 && responseCode < 300) {
        // 成功响应使用 getInputStream()
        inputStream = connection.getInputStream();
    } else {
        // 错误响应使用 getErrorStream()
        // 某些服务器在错误时也会返回有用的错误信息
        inputStream = connection.getErrorStream();
    }
    
    // 读取响应
    if (inputStream != null) {
        try (BufferedReader reader = new BufferedReader(
                new InputStreamReader(inputStream, StandardCharsets.UTF_8))) {
            StringBuilder response = new StringBuilder();
            String line;
            while ((line = reader.readLine()) != null) {
                response.append(line);
            }
            return response.toString();
        }
    }
    
    return null;
}

// Kotlin 中的 HttpURLConnection 高级配置示例
fun configuredRequest(urlString: String): HttpURLConnection {
    // 创建 URL 并打开连接
    val url = URL(urlString)
    val connection = url.openConnection() as HttpURLConnection
    
    // ===== 超时配置 =====
    // 连接超时：15秒，适用于移动网络环境
    connection.connectTimeout = 15_000
    // 读取超时：30秒，为服务器处理预留足够时间
    connection.readTimeout = 30_000
    
    // ===== 请求配置 =====
    // 设置为 POST 请求
    connection.requestMethod = "POST"
    // 启用输出流以发送请求体
    connection.doOutput = true
    // doInput 默认 true，显式设置增强可读性
    connection.doInput = true
    
    // ===== 请求头配置 =====
    // JSON 格式请求体
    connection.setRequestProperty("Content-Type", "application/json; charset=UTF-8")
    // 期望 JSON 格式响应
    connection.setRequestProperty("Accept", "application/json")
    // 自定义 User-Agent
    connection.setRequestProperty("User-Agent", "MyApp/1.0 Android")
    // Bearer Token 认证
    connection.setRequestProperty("Authorization", "Bearer your_token_here")
    // 禁用缓存，确保获取最新数据
    connection.setRequestProperty("Cache-Control", "no-cache")
    
    // ===== 重定向配置 =====
    // 禁用自动重定向，手动处理以支持 HTTP->HTTPS 重定向
    connection.instanceFollowRedirects = false
    
    // ===== 连接模式配置 =====
    // 使用缓存模式（默认），会在内存中缓存请求体
    // 如果请求体大小已知且较大，建议使用 setFixedLengthStreamingMode
    // connection.setFixedLengthStreamingMode(contentLength)
    // 如果请求体大小未知，使用分块传输
    // connection.setChunkedStreamingMode(0) // 0 表示使用默认块大小
    
    return connection
}
 
// 手动处理重定向的示例
fun requestWithRedirectHandling(urlString: String): String {
    var currentUrl = urlString
    var redirectCount = 0
    val maxRedirects = 5 // 防止无限重定向
    
    while (redirectCount < maxRedirects) {
        val url = URL(currentUrl)
        val connection = url.openConnection() as HttpURLConnection
        
        // 禁用自动重定向
        connection.instanceFollowRedirects = false
        connection.connectTimeout = 15_000
        connection.readTimeout = 10_000
        
        val responseCode = connection.responseCode
        
        // 检查是否为重定向响应 (3xx)
        if (responseCode in 300..399) {
            // 获取重定向目标 URL
            val location = connection.getHeaderField("Location")
            if (location.isNullOrEmpty()) {
                throw IOException("Redirect without Location header")
            }
            
            // 处理相对 URL
            currentUrl = URL(URL(currentUrl), location).toString()
            redirectCount++
            
            // 关闭当前连接
            connection.disconnect()
            
            continue // 继续请求新 URL
        }
        
        // 非重定向响应，读取并返回
        return connection.inputStream.bufferedReader().use { it.readText() }
    }
    
    throw IOException("Too many redirects")
}

<users>
    <user id="1">
        <name>Alice</name>
        <age>28</age>
    </user>
    <user id="2">
        <name>Bob</name>
        <age>32</age>
    </user>
</users>

// DOM 树的内存结构示意
// Document (根)
//    └── Element: users
//            ├── Element: user (attr: id="1")
//            │       ├── Element: name
//            │       │       └── Text: "Alice"
//            │       └── Element: age
//            │               └── Text: "28"
//            └── Element: user (attr: id="2")
//                    ├── Element: name
//                    │       └── Text: "Bob"
//                    └── Element: age
//                            └── Text: "32"

import org.w3c.dom.Document
import org.w3c.dom.Element
import org.w3c.dom.NodeList
import javax.xml.parsers.DocumentBuilderFactory
 
// 定义数据类，用于存储解析结果
data class User(val id: String, val name: String, val age: Int)
 
fun parseDom(xmlInputStream: InputStream): List<User> {
    // 创建结果列表
    val users = mutableListOf<User>()
    
    // 1. 获取 DocumentBuilderFactory 单例
    //    这是 JAXP (Java API for XML Processing) 的标准入口
    val factory = DocumentBuilderFactory.newInstance()
    
    // 2. 通过工厂创建 DocumentBuilder 实例
    //    DocumentBuilder 是线程不安全的，每次解析应创建新实例
    val builder = factory.newDocumentBuilder()
    
    // 3. 解析输入流，构建完整的 DOM 树
    //    注意：此步骤会将整个 XML 加载到内存
    val document: Document = builder.parse(xmlInputStream)
    
    // 4. 获取所有 <user> 元素节点
    //    返回的 NodeList 是"活的"——如果 DOM 树被修改，NodeList 会同步变化
    val userNodes: NodeList = document.getElementsByTagName("user")
    
    // 5. 遍历 NodeList，逐个处理 user 节点
    for (i in 0 until userNodes.length) {
        // 将 Node 强转为 Element 以便访问属性和子元素
        val userElement = userNodes.item(i) as Element
        
        // 6. 读取 id 属性
        //    getAttribute() 返回属性值字符串，若属性不存在则返回空串
        val id = userElement.getAttribute("id")
        
        // 7. 获取 <name> 子元素的文本内容
        //    getElementsByTagName 在当前元素范围内搜索
        //    textContent 会递归获取所有后代文本节点的拼接结果
        val name = userElement
            .getElementsByTagName("name")
            .item(0)                          // 获取第一个匹配的 <name> 元素
            .textContent                       // 提取文本内容
        
        // 8. 获取 <age> 子元素并转换为整数
        val age = userElement
            .getElementsByTagName("age")
            .item(0)
            .textContent
            .toInt()                           // String -> Int
        
        // 9. 构造 User 对象并添加到列表
        users.add(User(id, name, age))
    }
    
    return users
}

import org.xml.sax.Attributes
import org.xml.sax.helpers.DefaultHandler
import javax.xml.parsers.SAXParserFactory
 
data class User(val id: String, val name: String, val age: Int)
 
// 自定义 Handler，继承 DefaultHandler 以获得空实现的便利
class UserHandler : DefaultHandler() {
    
    // 解析结果列表
    val users = mutableListOf<User>()
    
    // 临时变量：存储当前正在解析的 user 数据
    private var currentId: String = ""
    private var currentName: String = ""
    private var currentAge: Int = 0
    
    // 标记当前正在解析哪个元素（用于 characters 回调判断）
    private var currentElement: String = ""
    
    // StringBuilder 用于累积 characters 回调中分段传入的文本
    // 注意：SAX 规范允许一段文本被拆分成多次 characters 调用
    private val textBuilder = StringBuilder()
    
    // 遇到开始标签时触发
    override fun startElement(
        uri: String,           // 命名空间 URI（无命名空间时为空）
        localName: String,     // 本地名称（无命名空间时可能为空）
        qName: String,         // 限定名（带前缀的完整标签名）
        attributes: Attributes // 属性集合
    ) {
        // 记录当前元素名，供 characters 回调使用
        currentElement = qName
        
        // 清空文本累积器，准备接收新元素的文本内容
        textBuilder.clear()
        
        // 如果是 <user> 标签，提取 id 属性
        if (qName == "user") {
            // getValue 按属性名获取值，若不存在返回 null
            currentId = attributes.getValue("id") ?: ""
        }
    }
    
    // 遇到文本内容时触发（可能被多次调用）
    override fun characters(
        ch: CharArray,         // 字符数组缓冲区
        start: Int,            // 本次文本在缓冲区中的起始位置
        length: Int            // 本次文本的长度
    ) {
        // 将本次收到的字符追加到 StringBuilder
        // 不能直接使用，因为可能只是完整文本的一部分
        textBuilder.append(ch, start, length)
    }
    
    // 遇到结束标签时触发
    override fun endElement(
        uri: String,
        localName: String,
        qName: String
    ) {
        // 获取累积的完整文本，并去除首尾空白
        val text = textBuilder.toString().trim()
        
        // 根据结束标签类型，将文本存入对应字段
        when (qName) {
            "name" -> currentName = text
            "age" -> currentAge = text.toIntOrNull() ?: 0
            "user" -> {
                // user 元素结束，构造完整的 User 对象
                users.add(User(currentId, currentName, currentAge))
                // 重置临时变量，为下一个 user 做准备
                currentId = ""
                currentName = ""
                currentAge = 0
            }
        }
        
        // 清空当前元素标记
        currentElement = ""
    }
}
 
// 使用 SAX 解析器
fun parseSax(xmlInputStream: InputStream): List<User> {
    // 1. 创建 SAXParserFactory 实例
    val factory = SAXParserFactory.newInstance()
    
    // 2. 通过工厂获取 SAXParser
    val parser = factory.newSAXParser()
    
    // 3. 创建自定义 Handler
    val handler = UserHandler()
    
    // 4. 开始解析，解析过程中会自动回调 Handler 的各方法
    parser.parse(xmlInputStream, handler)
    
    // 5. 解析完成后，从 Handler 中获取结果
    return handler.users
}

// 内存占用对比示意 (解析 10MB XML)
//
// DOM 方式：
// ┌─────────────────────────────────────┐
// │  Heap Memory                        │
// │  ┌───────────────────────────────┐  │
// │  │   Document Tree (~30-50MB)    │  │  <- 树结构通常是原文件 3-5 倍
// │  │   + 原始 byte[] (10MB)        │  │
// │  └───────────────────────────────┘  │
// └─────────────────────────────────────┘
//
// SAX 方式：
// ┌─────────────────────────────────────┐
// │  Heap Memory                        │
// │  ┌─────────┐                        │
// │  │ ~64KB   │  <- 仅解析器内部缓冲区  │
// │  │ buffer  │     + 应用状态变量      │
// │  └─────────┘                        │
// └─────────────────────────────────────┘

import android.util.Xml
import org.xmlpull.v1.XmlPullParser
import org.xmlpull.v1.XmlPullParserException
 
data class User(val id: String, val name: String, val age: Int)
 
fun parsePull(xmlInputStream: InputStream): List<User> {
    // 结果列表
    val users = mutableListOf<User>()
    
    // 1. 获取 XmlPullParser 实例
    //    Android 提供 Xml.newPullParser() 便捷方法
    //    底层使用 KXmlParser 实现（轻量高效）
    val parser: XmlPullParser = Xml.newPullParser()
    
    // 2. 配置解析器特性（可选）
    //    FEATURE_PROCESS_NAMESPACES: 是否处理 XML 命名空间
    //    简单场景下通常设为 false 以提升性能
    parser.setFeature(XmlPullParser.FEATURE_PROCESS_NAMESPACES, false)
    
    // 3. 设置输入源
    //    第二个参数为字符编码，null 表示自动检测
    parser.setInput(xmlInputStream, null)
    
    // 临时变量
    var currentId = ""
    var currentName = ""
    var currentAge = 0
    
    // 4. 获取初始事件类型
    var eventType = parser.eventType
    
    // 5. 主循环：持续拉取事件直到文档结束
    while (eventType != XmlPullParser.END_DOCUMENT) {
        
        // 6. 根据事件类型分支处理
        when (eventType) {
            
            XmlPullParser.START_TAG -> {
                // 7. 获取当前标签名
                val tagName = parser.name
                
                when (tagName) {
                    "user" -> {
                        // 8. 读取 user 标签的 id 属性
                        //    getAttributeValue(namespace, name)
                        //    namespace 为 null 表示无命名空间
                        currentId = parser.getAttributeValue(null, "id") ?: ""
                    }
                    "name" -> {
                        // 9. nextText() 是 Pull 解析器的便捷方法
                        //    自动读取当前标签的文本内容并移动到 END_TAG
                        //    等价于：next() -> 获取 TEXT -> next() 到 END_TAG
                        currentName = parser.nextText()
                    }
                    "age" -> {
                        // 10. 同理，读取 age 的文本并转为 Int
                        currentAge = parser.nextText().toIntOrNull() ?: 0
                    }
                }
            }
            
            XmlPullParser.END_TAG -> {
                // 11. 当遇到 </user> 结束标签时
                if (parser.name == "user") {
                    // 12. 构造 User 对象并加入列表
                    users.add(User(currentId, currentName, currentAge))
                    // 13. 重置临时变量
                    currentId = ""
                    currentName = ""
                    currentAge = 0
                }
            }
            // TEXT 事件在使用 nextText() 时已被处理，无需单独 case
        }
        
        // 14. 拉取下一个事件（核心！）
        //     如果忘记调用 next()，将陷入死循环
        eventType = parser.next()
    }
    
    return users
}

// nextText() 的等价伪代码
fun nextText(): String {
    // 前置条件：当前事件必须是 START_TAG
    require(eventType == START_TAG)
    
    // 调用 next() 移动到下一个事件
    next()
    
    // 如果下一个事件是 TEXT，提取文本
    val text = if (eventType == TEXT) {
        val result = text       // 获取文本内容
        next()                  // 再次移动
        result
    } else {
        ""                      // 空元素 <tag/> 的情况
    }
    
    // 此时应该位于 END_TAG
    require(eventType == END_TAG)
    
    return text
}

// 原生 JSONObject 解析示例
public User parseUser(String json) throws JSONException {
    // 1. 将 JSON 字符串解析为 JSONObject，内部触发词法分析
    JSONObject obj = new JSONObject(json);
    
    // 2. 通过 key 获取对应的值，类型由调用方法决定
    //    getString() 若 key 不存在或类型不匹配会抛出 JSONException
    String name = obj.getString("name");
    
    // 3. getInt() 会尝试将值转换为 int，字符串 "123" 也能转换成功
    int age = obj.getInt("age");
    
    // 4. optString() 是"宽容"版本，key 不存在时返回默认值而非抛异常
    //    适合处理可选字段，避免 try-catch 嵌套
    String email = obj.optString("email", "unknown@example.com");
    
    // 5. 解析嵌套对象：先获取 JSONObject，再递归提取字段
    JSONObject addressObj = obj.getJSONObject("address");
    String city = addressObj.getString("city");
    String street = addressObj.optString("street", "");
    
    // 6. 解析数组：获取 JSONArray 后遍历
    JSONArray tagsArray = obj.optJSONArray("tags");
    List<String> tags = new ArrayList<>();
    if (tagsArray != null) {
        // JSONArray 的 length() 返回元素数量
        for (int i = 0; i < tagsArray.length(); i++) {
            // 按索引获取元素，类型由方法决定
            tags.add(tagsArray.getString(i));
        }
    }
    
    // 7. 构建业务对象返回
    return new User(name, age, email, new Address(city, street), tags);
}

// GSON 基本用法示例
// 1. 定义数据类，字段名默认与 JSON key 一一对应
data class User(
    val name: String,           // 对应 JSON 中的 "name"
    val age: Int,               // 对应 JSON 中的 "age"
    @SerializedName("email_address")  // 2. 使用注解指定 JSON key 与字段名不同的映射
    val email: String,
    val address: Address?,      // 3. 嵌套对象自动递归解析
    val tags: List<String>      // 4. 集合类型自动处理
)
 
data class Address(
    val city: String,
    val street: String?
)
 
// 5. 创建 Gson 实例（通常全局复用，避免重复初始化开销）
val gson = Gson()
 
// 6. 反序列化：JSON 字符串 → Kotlin 对象
val user: User = gson.fromJson(jsonString, User::class.java)
 
// 7. 序列化：Kotlin 对象 → JSON 字符串
val outputJson: String = gson.toJson(user)

# 保留所有使用 @SerializedName 注解的字段不被混淆
-keepclassmembers class * {
    @com.google.gson.annotations.SerializedName <fields>;
}
 
# 或者直接保留整个数据类包
-keep class com.example.model.** { *; }

// Moshi 与 Kotlin 集成示例
// 1. 使用 @JsonClass 注解标记数据类，generateAdapter = true 表示生成代码而非反射
@JsonClass(generateAdapter = true)
data class User(
    val name: String,                    // non-null，JSON 缺失或为 null 时抛异常
    val age: Int,
    @Json(name = "email_address")        // 2. 指定 JSON key 名称
    val email: String,
    val address: Address?,               // 3. nullable，允许 JSON 中为 null 或缺失
    val tags: List<String> = emptyList() // 4. 默认参数，JSON 缺失时使用此值
)
 
@JsonClass(generateAdapter = true)
data class Address(
    val city: String,
    val street: String = ""              // 默认值
)
 
// 5. 构建 Moshi 实例，添加 KotlinJsonAdapterFactory（反射模式）
//    或使用 codegen 模式时无需添加
val moshi = Moshi.Builder()
    .addLast(KotlinJsonAdapterFactory())  // 反射模式需要此行
    .build()
 
// 6. 获取特定类型的 JsonAdapter
val adapter: JsonAdapter<User> = moshi.adapter(User::class.java)
 
// 7. 反序列化
val user: User? = adapter.fromJson(jsonString)
 
// 8. 序列化
val outputJson: String = adapter.toJson(user)

// 编译器自动生成的 UserJsonAdapter 伪代码（简化版）
class UserJsonAdapter(moshi: Moshi) : JsonAdapter<User>() {
    // 1. 在构造时获取嵌套类型的 Adapter，避免运行时查找
    private val addressAdapter: JsonAdapter<Address?> = moshi.adapter(Address::class.java)
    private val stringListAdapter: JsonAdapter<List<String>> = moshi.adapter(
        Types.newParameterizedType(List::class.java, String::class.java)
    )
    
    override fun fromJson(reader: JsonReader): User {
        // 2. 预定义局部变量，跟踪哪些字段已解析
        var name: String? = null
        var age: Int? = null
        var email: String? = null
        var address: Address? = null
        var tags: List<String>? = null
        
        // 3. 使用 selectName() 进行高效的 key 匹配（基于预计算的 Options）
        reader.beginObject()
        while (reader.hasNext()) {
            when (reader.selectName(OPTIONS)) {
                0 -> name = reader.nextString()
                1 -> age = reader.nextInt()
                2 -> email = reader.nextString()
                3 -> address = addressAdapter.fromJson(reader)
                4 -> tags = stringListAdapter.fromJson(reader)
                else -> reader.skipValue()  // 忽略未知字段
            }
        }
        reader.endObject()
        
        // 4. 构造对象，处理 null 和默认值
        return User(
            name = name ?: throw JsonDataException("Required field 'name' missing"),
            age = age ?: throw JsonDataException("Required field 'age' missing"),
            email = email ?: throw JsonDataException("Required field 'email_address' missing"),
            address = address,  // nullable，允许 null
            tags = tags ?: emptyList()  // 使用默认值
        )
    }
    
    override fun toJson(writer: JsonWriter, value: User?) { /* 序列化逻辑 */ }
}

// Kotlin Serialization 示例
// 1. 使用 @Serializable 注解标记数据类
@Serializable
data class User(
    val name: String,
    val age: Int,
    @SerialName("email_address")        // 2. 指定 JSON key
    val email: String,
    val address: Address? = null,       // 3. nullable + 默认值
    val tags: List<String> = emptyList()// 4. 默认值
)
 
@Serializable
data class Address(
    val city: String,
    val street: String = ""
)
 
// 5. 创建 Json 实例，可配置各种选项
val json = Json {
    ignoreUnknownKeys = true            // 忽略 JSON 中未知的字段
    encodeDefaults = false              // 序列化时不输出等于默认值的字段
    isLenient = true                    // 宽松模式，允许不规范的 JSON（如无引号的 key）
    coerceInputValues = true            // 将 null 强制转换为默认值（若字段有默认值）
    prettyPrint = true                  // 格式化输出
}
 
// 6. 反序列化
val user: User = json.decodeFromString<User>(jsonString)
// 或显式指定 serializer
val user2: User = json.decodeFromString(User.serializer(), jsonString)
 
// 7. 序列化
val outputJson: String = json.encodeToString(user)

// 泛型集合的类型安全解析
@Serializable
data class ApiResponse<T>(
    val code: Int,
    val message: String,
    val data: T
)
 
// 编译器自动推断 T = List<User>，生成正确的序列化器
val response: ApiResponse<List<User>> = json.decodeFromString(jsonString)
 
// 访问 data 时，类型已确定为 List<User>，无需强制类型转换
val users: List<User> = response.data

// 同一数据类，不同格式
val jsonOutput = Json.encodeToString(user)
val protobufOutput = ProtoBuf.encodeToByteArray(user)  // 需要 kotlinx-serialization-protobuf 依赖
val cborOutput = Cbor.encodeToByteArray(user)          // 需要 kotlinx-serialization-cbor 依赖

@Serializable
data class Person(
    val name: String,
    val age: Int = 18
)
 
val person = Json.decodeFromString<Person>("""{"name": "Alice", "age": null}""")

// 获取 ConnectivityManager 系统服务实例
// getSystemService() 返回的是一个 Binder 代理对象
val connectivityManager = context.getSystemService(Context.CONNECTIVITY_SERVICE) as ConnectivityManager

// ⚠️ 已废弃的 API（API 29 起标记 @Deprecated）
// 仅用于兼容旧版本 Android，不推荐在新项目中使用
@Suppress("DEPRECATION")
fun isNetworkAvailableLegacy(context: Context): Boolean {
    val cm = context.getSystemService(Context.CONNECTIVITY_SERVICE) as ConnectivityManager
    // getActiveNetworkInfo() 返回当前活跃网络的信息
    // 可能为 null（表示没有活跃网络）
    val networkInfo = cm.activeNetworkInfo
    // isConnected 表示网络是否已建立连接
    return networkInfo?.isConnected == true
}

// 现代 API：获取当前活跃网络及其能力
// 这是 Android 6.0+ 推荐的做法
fun checkNetworkModern(context: Context) {
    val cm = context.getSystemService(Context.CONNECTIVITY_SERVICE) as ConnectivityManager
    
    // getActiveNetwork() 返回当前系统默认使用的网络
    // 返回值是一个 Network 对象，可能为 null
    val activeNetwork: Network? = cm.activeNetwork
    
    // 如果没有活跃网络，直接返回
    if (activeNetwork == null) {
        Log.d("Network", "No active network")
        return
    }
    
    // getNetworkCapabilities() 获取指定网络的能力描述
    // 通过 NetworkCapabilities 可以判断网络的各种特性
    val capabilities: NetworkCapabilities? = cm.getNetworkCapabilities(activeNetwork)
    
    // capabilities 也可能为 null（网络刚断开时）
    capabilities?.let { caps ->
        // 检查网络是否具备访问互联网的能力
        val hasInternet = caps.hasCapability(NetworkCapabilities.NET_CAPABILITY_INTERNET)
        // 检查网络连接是否已验证（能真正访问外网）
        val isValidated = caps.hasCapability(NetworkCapabilities.NET_CAPABILITY_VALIDATED)
        
        Log.d("Network", "Has Internet: $hasInternet, Validated: $isValidated")
    }
}

// 全面检查网络能力的工具方法
// 返回一个包含各种网络属性的数据类
data class NetworkStatus(
    val isConnected: Boolean,           // 是否已连接
    val isWifi: Boolean,                // 是否为 Wi-Fi
    val isCellular: Boolean,            // 是否为蜂窝网络
    val isValidated: Boolean,           // 是否已验证（能真正上网）
    val isNotMetered: Boolean,          // 是否为非计费网络
    val downstreamBandwidthKbps: Int,   // 下行带宽估算 (Kbps)
    val upstreamBandwidthKbps: Int      // 上行带宽估算 (Kbps)
)
 
fun getNetworkStatus(context: Context): NetworkStatus {
    val cm = context.getSystemService(Context.CONNECTIVITY_SERVICE) as ConnectivityManager
    
    // 获取当前活跃网络
    val network = cm.activeNetwork
    // 获取网络能力描述
    val caps = network?.let { cm.getNetworkCapabilities(it) }
    
    // 如果没有网络或能力信息，返回断开状态
    if (caps == null) {
        return NetworkStatus(
            isConnected = false,
            isWifi = false,
            isCellular = false,
            isValidated = false,
            isNotMetered = false,
            downstreamBandwidthKbps = 0,
            upstreamBandwidthKbps = 0
        )
    }
    
    return NetworkStatus(
        // 有网络对象即表示已连接
        isConnected = true,
        // 检查传输类型是否为 Wi-Fi
        isWifi = caps.hasTransport(NetworkCapabilities.TRANSPORT_WIFI),
        // 检查传输类型是否为蜂窝网络
        isCellular = caps.hasTransport(NetworkCapabilities.TRANSPORT_CELLULAR),
        // VALIDATED 表示已通过互联网连通性测试
        isValidated = caps.hasCapability(NetworkCapabilities.NET_CAPABILITY_VALIDATED),
        // NOT_METERED 表示不按流量计费（Wi-Fi 通常具备此能力）
        isNotMetered = caps.hasCapability(NetworkCapabilities.NET_CAPABILITY_NOT_METERED),
        // 系统估算的下行带宽，单位 Kbps
        downstreamBandwidthKbps = caps.linkDownstreamBandwidthKbps,
        // 系统估算的上行带宽，单位 Kbps
        upstreamBandwidthKbps = caps.linkUpstreamBandwidthKbps
    )
}

// 实现一个功能完整的网络状态监听器
class NetworkMonitor(private val context: Context) {
    
    // ConnectivityManager 实例，用于注册/注销回调
    private val connectivityManager = 
        context.getSystemService(Context.CONNECTIVITY_SERVICE) as ConnectivityManager
    
    // 使用 StateFlow 暴露网络状态，便于 UI 层观察
    // MutableStateFlow 允许内部修改，对外暴露为只读 StateFlow
    private val _networkState = MutableStateFlow<NetworkState>(NetworkState.Unknown)
    val networkState: StateFlow<NetworkState> = _networkState.asStateFlow()
    
    // 定义网络状态的密封类，覆盖所有可能的状态
    sealed class NetworkState {
        object Unknown : NetworkState()                    // 初始状态，尚未检测
        object Unavailable : NetworkState()               // 无可用网络
        data class Available(                             // 网络可用
            val isWifi: Boolean,                          // 是否为 Wi-Fi
            val isValidated: Boolean,                     // 是否已验证
            val isMetered: Boolean                        // 是否计费
        ) : NetworkState()
    }
    
    // NetworkCallback 实现
    // 系统会在网络状态变化时回调这些方法
    private val networkCallback = object : ConnectivityManager.NetworkCallback() {
        
        // 当有网络变为可用时调用
        // network 参数是该网络的唯一标识符
        override fun onAvailable(network: Network) {
            super.onAvailable(network)
            Log.d("NetworkMonitor", "Network available: $network")
            // onAvailable 只表示网络可用，但能力信息需要在 onCapabilitiesChanged 中获取
            // 这里暂时设置为基础可用状态
        }
        
        // 当网络能力发生变化时调用
        // 这是获取网络详细信息的主要回调
        override fun onCapabilitiesChanged(
            network: Network,
            networkCapabilities: NetworkCapabilities
        ) {
            super.onCapabilitiesChanged(network, networkCapabilities)
            
            // 提取关键能力信息
            val isWifi = networkCapabilities.hasTransport(NetworkCapabilities.TRANSPORT_WIFI)
            val isValidated = networkCapabilities.hasCapability(
                NetworkCapabilities.NET_CAPABILITY_VALIDATED
            )
            // NOT_METERED 的反义就是计费网络
            val isMetered = !networkCapabilities.hasCapability(
                NetworkCapabilities.NET_CAPABILITY_NOT_METERED
            )
            
            // 更新状态流，触发 UI 层更新
            _networkState.value = NetworkState.Available(
                isWifi = isWifi,
                isValidated = isValidated,
                isMetered = isMetered
            )
            
            Log.d("NetworkMonitor", 
                "Capabilities changed: wifi=$isWifi, validated=$isValidated, metered=$isMetered")
        }
        
        // 当网络即将丢失时调用
        // maxMsToLive 表示网络预计还能维持的最大毫秒数
        override fun onLosing(network: Network, maxMsToLive: Int) {
            super.onLosing(network, maxMsToLive)
            Log.d("NetworkMonitor", "Network losing: $network, max ${maxMsToLive}ms remaining")
            // 可以在这里提前准备切换逻辑，如缓存关键数据
        }
        
        // 当网络完全丢失时调用
        override fun onLost(network: Network) {
            super.onLost(network)
            Log.d("NetworkMonitor", "Network lost: $network")
            // 更新状态为不可用
            _networkState.value = NetworkState.Unavailable
        }
        
        // 当请求的网络在超时时间内无法获得时调用
        // 仅在使用 requestNetwork() 并设置超时时触发
        override fun onUnavailable() {
            super.onUnavailable()
            Log.d("NetworkMonitor", "Network unavailable (request timeout)")
            _networkState.value = NetworkState.Unavailable
        }
    }
    
    // 开始监听网络状态
    // 应在 Activity.onStart() 或 Application.onCreate() 中调用
    fun startMonitoring() {
        // 构建网络请求，描述我们关心的网络类型
        val networkRequest = NetworkRequest.Builder()
            // 要求网络具备互联网能力
            .addCapability(NetworkCapabilities.NET_CAPABILITY_INTERNET)
            // 不限制传输类型（Wi-Fi/蜂窝都可以）
            .build()
        
        // 注册回调
        // registerNetworkCallback 会立即触发一次 onAvailable（如果有可用网络）
        connectivityManager.registerNetworkCallback(networkRequest, networkCallback)
        
        Log.d("NetworkMonitor", "Started monitoring network")
    }
    
    // 停止监听网络状态
    // 应在 Activity.onStop() 或适当的生命周期点调用
    fun stopMonitoring() {
        try {
            // 注销回调，避免内存泄漏
            connectivityManager.unregisterNetworkCallback(networkCallback)
            Log.d("NetworkMonitor", "Stopped monitoring network")
        } catch (e: IllegalArgumentException) {
            // 回调未注册时会抛出异常，这里静默处理
            Log.w("NetworkMonitor", "Callback was not registered")
        }
    }
}

// 主动请求特定类型的网络（需要权限）
// 这会导致系统尝试激活符合条件的网络
fun requestWifiNetwork(timeoutMs: Int = 30_000) {
    val request = NetworkRequest.Builder()
        // 要求 Wi-Fi 传输类型
        .addTransportType(NetworkCapabilities.TRANSPORT_WIFI)
        // 要求非计费（排除 Wi-Fi 热点等计费 Wi-Fi）
        .addCapability(NetworkCapabilities.NET_CAPABILITY_NOT_METERED)
        .build()
    
    // requestNetwork 会主动尝试连接符合条件的网络
    // 需要 CHANGE_NETWORK_STATE 权限
    connectivityManager.requestNetwork(
        request,
        networkCallback,
        timeoutMs  // 超时后触发 onUnavailable
    )
}

// 使用 Lifecycle 自动管理回调注册
class LifecycleAwareNetworkMonitor(
    private val context: Context,
    lifecycle: Lifecycle
) : DefaultLifecycleObserver {
    
    private val cm = context.getSystemService(Context.CONNECTIVITY_SERVICE) as ConnectivityManager
    private var callback: ConnectivityManager.NetworkCallback? = null
    
    init {
        // 将自身添加为生命周期观察者
        lifecycle.addObserver(this)
    }
    
    // Activity/Fragment 进入前台时自动注册
    override fun onStart(owner: LifecycleOwner) {
        callback = object : ConnectivityManager.NetworkCallback() {
            override fun onAvailable(network: Network) {
                // 处理网络可用
            }
            override fun onLost(network: Network) {
                // 处理网络丢失
            }
        }
        
        val request = NetworkRequest.Builder()
            .addCapability(NetworkCapabilities.NET_CAPABILITY_INTERNET)
            .build()
            
        cm.registerNetworkCallback(request, callback!!)
    }
    
    // Activity/Fragment 进入后台时自动注销
    override fun onStop(owner: LifecycleOwner) {
        callback?.let { 
            cm.unregisterNetworkCallback(it)
            callback = null
        }
    }
}
 
// 在 Activity 中使用
class MainActivity : AppCompatActivity() {
    private lateinit var networkMonitor: LifecycleAwareNetworkMonitor
    
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        // 传入 lifecycle，监控器会自动管理注册和注销
        networkMonitor = LifecycleAwareNetworkMonitor(this, lifecycle)
    }
}

<!-- AndroidManifest.xml -->
<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    
    <!-- 读取网络状态的权限（普通权限，自动授予） -->
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
    
    <!-- 如果需要使用 requestNetwork() 修改网络连接 -->
    <uses-permission android:name="android.permission.CHANGE_NETWORK_STATE" />
    
</manifest>

// 获取整机移动网络流量（自开机以来）
// getMobileTxBytes(): 移动网络发送的总字节数
// getMobileRxBytes(): 移动网络接收的总字节数
val mobileTx = TrafficStats.getMobileTxBytes()    // 移动网络上行流量
val mobileRx = TrafficStats.getMobileRxBytes()    // 移动网络下行流量
 
// 获取整机所有网络接口的流量（包括 Wi-Fi、移动网络、以太网等）
// getTotalTxBytes(): 所有网络接口发送的总字节数
// getTotalRxBytes(): 所有网络接口接收的总字节数
val totalTx = TrafficStats.getTotalTxBytes()      // 所有网络上行流量
val totalRx = TrafficStats.getTotalRxBytes()      // 所有网络下行流量
 
// 获取当前应用 UID 的流量
// getUidTxBytes(uid): 指定 UID 发送的总字节数
// getUidRxBytes(uid): 指定 UID 接收的总字节数
val myUid = android.os.Process.myUid()            // 获取当前应用的 UID
val appTx = TrafficStats.getUidTxBytes(myUid)     // 当前应用上行流量
val appRx = TrafficStats.getUidRxBytes(myUid)     // 当前应用下行流量
 
// 检查返回值有效性
// 返回 UNSUPPORTED (-1) 表示设备或内核不支持该统计项
if (appTx == TrafficStats.UNSUPPORTED.toLong()) {
    // 当前设备不支持此统计，可能是内核未开启 xt_qtaguid
    Log.w("TrafficStats", "UID traffic stats not supported on this device")
}

class TrafficMonitor {
    // 记录监控开始时的基线值
    private var baselineTx: Long = 0L
    private var baselineRx: Long = 0L
    private val uid = android.os.Process.myUid()
    
    /**
     * 开始监控：记录当前累计流量作为基线
     * 调用此方法后，可通过 getConsumedBytes() 获取增量流量
     */
    fun startMonitoring() {
        // 保存当前时刻的累计值作为计算起点
        baselineTx = TrafficStats.getUidTxBytes(uid)
        baselineRx = TrafficStats.getUidRxBytes(uid)
    }
    
    /**
     * 获取自监控开始以来消耗的流量
     * @return Pair<上行增量, 下行增量>，单位为字节
     */
    fun getConsumedBytes(): Pair<Long, Long> {
        // 当前累计值减去基线值，得到增量
        val currentTx = TrafficStats.getUidTxBytes(uid)
        val currentRx = TrafficStats.getUidRxBytes(uid)
        // 返回 (发送增量, 接收增量)
        return Pair(currentTx - baselineTx, currentRx - baselineRx)
    }
    
    /**
     * 格式化字节数为人类可读的字符串
     * @param bytes 原始字节数
     * @return 格式化后的字符串，如 "1.5 MB"
     */
    fun formatBytes(bytes: Long): String {
        // 根据数量级选择合适的单位
        return when {
            bytes < 1024 -> "$bytes B"                              // 字节
            bytes < 1024 * 1024 -> "%.2f KB".format(bytes / 1024.0) // 千字节
            else -> "%.2f MB".format(bytes / (1024.0 * 1024.0))     // 兆字节
        }
    }
}

/**
 * 获取系统中所有已安装应用的流量统计
 * 需要 android.permission.PACKAGE_USAGE_STATS 权限（Android 5.1+）
 * 或者 system app 权限
 */
fun getAllAppsTrafficStats(context: Context): List<AppTrafficInfo> {
    // 获取 PackageManager 实例，用于查询已安装应用
    val pm = context.packageManager
    // 获取所有已安装的应用（包括系统应用）
    // GET_META_DATA 标志确保获取完整的包信息
    val packages = pm.getInstalledApplications(PackageManager.GET_META_DATA)
    
    // 遍历所有应用，收集流量信息
    return packages.mapNotNull { appInfo ->
        // 获取该应用的 UID
        val uid = appInfo.uid
        // 查询该 UID 的收发流量
        val txBytes = TrafficStats.getUidTxBytes(uid)
        val rxBytes = TrafficStats.getUidRxBytes(uid)
        
        // 过滤掉无流量或不支持统计的应用
        if (txBytes == TrafficStats.UNSUPPORTED.toLong() || 
            (txBytes == 0L && rxBytes == 0L)) {
            null  // 返回 null，会被 mapNotNull 过滤掉
        } else {
            // 构建流量信息对象
            AppTrafficInfo(
                packageName = appInfo.packageName,     // 包名
                appName = pm.getApplicationLabel(appInfo).toString(),  // 应用名称
                uid = uid,                             // UID
                txBytes = txBytes,                     // 上行字节数
                rxBytes = rxBytes                      // 下行字节数
            )
        }
    }.sortedByDescending { it.txBytes + it.rxBytes }   // 按总流量降序排列
}
 
/**
 * 应用流量信息数据类
 */
data class AppTrafficInfo(
    val packageName: String,  // 应用包名，如 com.example.app
    val appName: String,      // 应用显示名称
    val uid: Int,             // Linux UID
    val txBytes: Long,        // 发送字节数（上行）
    val rxBytes: Long         // 接收字节数（下行）
) {
    // 计算总流量
    val totalBytes: Long get() = txBytes + rxBytes
}

object NetworkTags {
    // 定义语义化的 Tag 常量
    // Tag 是一个 32 位整数，低 16 位由应用自定义，高 16 位保留给系统
    const val TAG_VIDEO_STREAM = 0x1001    // 视频流数据
    const val TAG_IMAGE_LOAD = 0x1002      // 图片加载
    const val TAG_API_REQUEST = 0x1003     // API 接口请求
    const val TAG_ANALYTICS = 0x1004       // 数据埋点上报
}
 
/**
 * 在指定 Tag 下执行网络操作
 * 使用 inline + reified 确保异常类型信息在运行时可用
 * @param tag 流量标签
 * @param block 包含网络操作的 lambda
 * @return block 的执行结果
 */
inline fun <T> withTrafficTag(tag: Int, block: () -> T): T {
    // 保存之前的 Tag，以便恢复（支持嵌套调用）
    val previousTag = TrafficStats.getThreadStatsTag()
    try {
        // 设置新的 Tag，此后当前线程创建的 Socket 都会带上此标签
        TrafficStats.setThreadStatsTag(tag)
        // 执行实际的网络操作
        return block()
    } finally {
        // 无论成功失败，都恢复之前的 Tag
        // 这对于复用线程池中的线程尤为重要
        TrafficStats.setThreadStatsTag(previousTag)
    }
}
 
// 使用示例：为不同类型的网络请求打标签
fun loadVideoStream(url: String) {
    withTrafficTag(NetworkTags.TAG_VIDEO_STREAM) {
        // 此处所有网络操作的流量都会被标记为 VIDEO_STREAM
        // 包括 OkHttp、Retrofit、HttpURLConnection 等任何 HTTP 客户端
        val connection = URL(url).openConnection() as HttpURLConnection
        connection.inputStream.use { input ->
            // 读取视频流数据...
        }
    }
}

/**
 * OkHttp 拦截器：自动为请求打上流量标签
 * 根据请求路径或 Header 自动识别并应用合适的 Tag
 */
class TrafficTagInterceptor : Interceptor {
    override fun intercept(chain: Interceptor.Chain): Response {
        val request = chain.request()
        
        // 根据请求特征决定 Tag
        // 优先检查是否有自定义 Header 指定 Tag
        val tag = request.header("X-Traffic-Tag")?.toIntOrNull()
            ?: inferTagFromPath(request.url.encodedPath)  // 否则根据路径推断
        
        // 保存并设置 Tag
        val previousTag = TrafficStats.getThreadStatsTag()
        TrafficStats.setThreadStatsTag(tag)
        
        return try {
            // 继续请求链，此时 Socket 已被打标
            chain.proceed(request)
        } finally {
            // 恢复原 Tag（线程池中的线程会被复用）
            TrafficStats.setThreadStatsTag(previousTag)
        }
    }
    
    /**
     * 根据 URL 路径推断流量类型
     * @param path URL 路径部分
     * @return 对应的流量 Tag
     */
    private fun inferTagFromPath(path: String): Int {
        return when {
            path.contains("/video/") -> NetworkTags.TAG_VIDEO_STREAM
            path.contains("/image/") || path.endsWith(".jpg") || 
                path.endsWith(".png") -> NetworkTags.TAG_IMAGE_LOAD
            path.contains("/analytics") -> NetworkTags.TAG_ANALYTICS
            else -> NetworkTags.TAG_API_REQUEST  // 默认为 API 请求
        }
    }
}
 
// 配置 OkHttpClient 使用该拦截器
val client = OkHttpClient.Builder()
    .addInterceptor(TrafficTagInterceptor())  // 添加流量标记拦截器
    .build()

/**
 * 使用 NetworkStatsManager 获取更精细的流量统计
 * 需要权限：android.permission.PACKAGE_USAGE_STATS
 * 需要用户在"设置-应用-特殊权限-使用情况访问"中授权
 */
@RequiresApi(Build.VERSION_CODES.M)
fun getDetailedNetworkStats(context: Context, uid: Int, startTime: Long, endTime: Long) {
    // 获取 NetworkStatsManager 系统服务
    val nsm = context.getSystemService(Context.NETWORK_STATS_SERVICE) as NetworkStatsManager
    
    // 查询移动网络流量（指定时间范围）
    // TYPE_MOBILE = 0 表示移动蜂窝网络
    val mobileBucket = nsm.querySummaryForDevice(
        ConnectivityManager.TYPE_MOBILE,  // 网络类型：移动网络
        null,                              // subscriberId，null 表示所有运营商
        startTime,                         // 开始时间戳（毫秒）
        endTime                            // 结束时间戳（毫秒）
    )
    
    // 查询 Wi-Fi 流量
    // TYPE_WIFI = 1 表示 Wi-Fi 网络
    val wifiBucket = nsm.querySummaryForDevice(
        ConnectivityManager.TYPE_WIFI,    // 网络类型：Wi-Fi
        null,
        startTime,
        endTime
    )
    
    // NetworkStats.Bucket 包含 rxBytes 和 txBytes 字段
    Log.d("NetworkStats", "Mobile: rx=${mobileBucket.rxBytes}, tx=${mobileBucket.txBytes}")
    Log.d("NetworkStats", "WiFi: rx=${wifiBucket.rxBytes}, tx=${wifiBucket.txBytes}")
}

// 自定义 WebViewClient 实现导航拦截
class CustomWebViewClient : WebViewClient() {
 
    // 新版 API（API 24+），接收 WebResourceRequest 对象，信息更丰富
    override fun shouldOverrideUrlLoading(
        view: WebView,           // 当前 WebView 实例
        request: WebResourceRequest // 封装了请求的 URL、Headers、Method 等信息
    ): Boolean {
        val url = request.url.toString()  // 获取目标 URL 字符串
 
        // 场景1：拦截自定义协议，触发原生行为
        if (url.startsWith("myapp://")) {
            handleCustomScheme(url)      // 解析协议并执行原生逻辑
            return true                   // 返回 true 表示"我已处理，WebView 不要继续加载"
        }
 
        // 场景2：外部链接跳转系统浏览器
        if (!url.contains("mycompany.com")) {
            val intent = Intent(Intent.ACTION_VIEW, Uri.parse(url))
            view.context.startActivity(intent)  // 使用系统浏览器打开
            return true                          // 阻止 WebView 加载
        }
 
        // 场景3：HTTPS 降级检测（安全策略）
        if (url.startsWith("http://") && !url.startsWith("https://")) {
            Log.w("WebView", "Blocked insecure navigation: $url")
            return true  // 阻止不安全的 HTTP 跳转
        }
 
        // 默认行为：允许 WebView 正常加载
        return false  // 返回 false 表示"交给 WebView 处理"
    }
 
    // 旧版 API（已废弃但仍需兼容低版本设备）
    @Deprecated("Use shouldOverrideUrlLoading(WebView, WebResourceRequest)")
    override fun shouldOverrideUrlLoading(view: WebView, url: String): Boolean {
        // 与新版逻辑相同，但只能获取 URL 字符串
        return super.shouldOverrideUrlLoading(view, url)
    }
}

class InterceptingWebViewClient : WebViewClient() {
 
    // 资源拦截回调（运行在非 UI 线程，可执行耗时操作）
    override fun shouldInterceptRequest(
        view: WebView,
        request: WebResourceRequest
    ): WebResourceResponse? {  // 返回 null 表示不拦截，使用默认网络加载
        val url = request.url.toString()
 
        // 场景：将远程 JS 文件替换为本地预置版本（加速首屏）
        if (url.endsWith("vendor.bundle.js")) {
            return loadLocalResource(
                view.context,
                "assets/js/vendor.bundle.js", // 本地文件路径
                "application/javascript"       // MIME 类型
            )
        }
 
        // 场景：为所有图片请求添加自定义 Header（如鉴权 Token）
        if (isImageUrl(url)) {
            return fetchWithCustomHeaders(url, mapOf(
                "X-App-Token" to "your_auth_token",
                "X-Client-Version" to "1.0.0"
            ))
        }
 
        // 不拦截，走默认网络请求
        return null
    }
 
    // 从 assets 加载本地资源并构造 WebResourceResponse
    private fun loadLocalResource(
        context: Context,
        assetPath: String,
        mimeType: String
    ): WebResourceResponse? {
        return try {
            val inputStream = context.assets.open(assetPath) // 打开 asset 文件流
            WebResourceResponse(
                mimeType,     // MIME 类型，如 "text/html"、"image/png"
                "UTF-8",      // 字符编码
                inputStream   // 响应体数据流
            )
        } catch (e: IOException) {
            Log.e("WebView", "Failed to load local resource: $assetPath", e)
            null  // 加载失败则回退到网络请求
        }
    }
}

class ErrorHandlingWebViewClient : WebViewClient() {
 
    // HTTP 错误（4xx、5xx 状态码）
    override fun onReceivedHttpError(
        view: WebView,
        request: WebResourceRequest,
        errorResponse: WebResourceResponse  // 包含状态码和响应头
    ) {
        val statusCode = errorResponse.statusCode
        val url = request.url.toString()
 
        if (request.isForMainFrame) {  // 仅处理主文档错误
            when (statusCode) {
                404 -> showErrorPage(view, "页面不存在")
                500 -> showErrorPage(view, "服务器异常")
                503 -> showRetryPage(view, "服务暂时不可用")
            }
        }
        Log.w("WebView", "HTTP Error $statusCode for $url")
    }
 
    // 通用加载错误（网络不可达、DNS 失败、超时等）
    override fun onReceivedError(
        view: WebView,
        request: WebResourceRequest,
        error: WebResourceError  // 包含错误码和描述
    ) {
        if (request.isForMainFrame) {  // 只处理主框架错误，忽略子资源
            val errorCode = error.errorCode
            val description = error.description
 
            // 根据错误类型展示不同的本地错误页
            when (errorCode) {
                ERROR_HOST_LOOKUP -> showOfflinePage(view)  // DNS 解析失败
                ERROR_CONNECT -> showNetworkErrorPage(view) // 连接失败
                ERROR_TIMEOUT -> showTimeoutPage(view)      // 超时
                else -> showGenericErrorPage(view, description.toString())
            }
        }
    }
 
    // SSL/TLS 证书错误（极其敏感，需谨慎处理）
    override fun onReceivedSslError(
        view: WebView,
        handler: SslErrorHandler,  // 控制是否继续加载
        error: SslError            // 证书错误详情
    ) {
        // ⚠️ 安全警告：生产环境绝不能直接调用 handler.proceed()！
        // 这会忽略证书验证，使应用暴露于中间人攻击风险
        
        val errorType = when (error.primaryError) {
            SslError.SSL_EXPIRED -> "证书已过期"
            SslError.SSL_IDMISMATCH -> "证书域名不匹配"
            SslError.SSL_UNTRUSTED -> "证书不受信任"
            SslError.SSL_NOTYETVALID -> "证书尚未生效"
            else -> "未知 SSL 错误"
        }
 
        // 正确做法：提示用户风险，让用户决定
        AlertDialog.Builder(view.context)
            .setTitle("安全警告")
            .setMessage("$errorType\n\n继续访问可能存在风险，是否继续？")
            .setPositiveButton("继续") { _, _ -> handler.proceed() }  // 用户主动确认
            .setNegativeButton("取消") { _, _ -> handler.cancel() }   // 取消加载
            .setCancelable(false)
            .show()
    }
}

// 获取 CookieManager 单例
val cookieManager = CookieManager.getInstance()
 
// 在 Application 或首次使用 WebView 前启用 Cookie
cookieManager.setAcceptCookie(true)  // 允许 WebView 接收 Cookie（默认为 true）
 
// API 21+ 支持第三方 Cookie 控制（跨域 Cookie）
if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.LOLLIPOP) {
    cookieManager.setAcceptThirdPartyCookies(webView, true)  // 针对特定 WebView 实例
}

object CookieSyncHelper {
 
    /**
     * 将原生 HTTP 客户端的 Cookie 同步到 WebView
     * @param url 目标网页的 URL（Cookie 将关联到此 URL 的域名）
     * @param cookies 从 OkHttp CookieJar 或 Response Header 获取的 Cookie 列表
     */
    fun syncCookiesToWebView(url: String, cookies: List<Cookie>) {
        val cookieManager = CookieManager.getInstance()
 
        // 遍历所有 Cookie，逐个写入 CookieManager
        cookies.forEach { cookie ->
            // 构造符合 Set-Cookie 格式的字符串
            // 格式：name=value; Domain=xxx; Path=/; Expires=xxx; Secure; HttpOnly
            val cookieString = buildCookieString(cookie)
 
            // setCookie() 是同步方法，会立即写入内存
            // 注意：URL 参数决定了 Cookie 的作用域（域名匹配）
            cookieManager.setCookie(url, cookieString)
        }
 
        // 强制将内存中的 Cookie 持久化到磁盘
        // 这一步非常重要！否则 App 被杀死后 Cookie 会丢失
        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.LOLLIPOP) {
            cookieManager.flush()  // 异步写入磁盘
        } else {
            CookieSyncManager.getInstance().sync()  // 旧 API，已废弃
        }
    }
 
    /**
     * 构造 Set-Cookie 格式的字符串
     */
    private fun buildCookieString(cookie: Cookie): String {
        return buildString {
            append("${cookie.name}=${cookie.value}")  // 必需：名称=值
 
            cookie.domain?.let { append("; Domain=$it") }  // 域名限制
            cookie.path?.let { append("; Path=$it") }      // 路径限制
 
            if (cookie.expiresAt > 0) {
                // 将时间戳转为 HTTP 日期格式
                val dateFormat = SimpleDateFormat("EEE, dd MMM yyyy HH:mm:ss zzz", Locale.US)
                dateFormat.timeZone = TimeZone.getTimeZone("GMT")
                append("; Expires=${dateFormat.format(Date(cookie.expiresAt))}")
            }
 
            if (cookie.secure) append("; Secure")    // 仅 HTTPS 传输
            if (cookie.httpOnly) append("; HttpOnly") // 禁止 JS 访问
        }
    }
}

class WebActivity : AppCompatActivity() {
 
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
 
        // 步骤1：检查用户登录状态，获取已存储的 Cookie
        val sessionCookies = UserSession.getCookies()
 
        // 步骤2：在加载 WebView 之前同步 Cookie
        if (sessionCookies.isNotEmpty()) {
            CookieSyncHelper.syncCookiesToWebView(
                url = "https://www.mycompany.com",
                cookies = sessionCookies
            )
        }
 
        // 步骤3：此时加载页面，请求会自动携带 Cookie
        webView.loadUrl("https://www.mycompany.com/user/profile")
    }
}