一、接口调用日志封装的重要性

在Android开发中，网络接口调用是核心功能之一，但调试时往往面临以下痛点：日志分散在各个调用点，难以统一管理；关键参数（如请求URL、参数、响应数据）记录不全；异常场景（如网络错误、超时）缺乏详细追踪。这些问题导致问题定位效率低下，甚至影响线上故障排查。

通过日志封装，可以解决三大核心问题：

1. 统一日志格式：所有接口调用遵循相同模板，便于工具解析
2. 关键信息全覆盖：自动记录请求/响应的完整生命周期
3. 异常场景深度追踪：捕获并记录网络层、解析层等各级错误

以电商APP为例，封装后可将订单查询接口的调用日志结构化为：

[API_CALL] [2023-08-15 14:30:22] [Thread-1] 
REQUEST: /api/order/detail?orderId=12345 
PARAMS: {"userId":"67890"} 
RESPONSE: {"code":200,"data":{"status":"paid"}} 
DURATION: 152ms

二、日志封装的核心实现方案

1. 基础封装架构设计

采用”接口+实现”模式，定义统一日志接口：

interface ApiLogger {
    fun logRequest(url: String, params: Map<String, Any?>)
    fun logResponse(code: Int, data: Any?, duration: Long)
    fun logError(exception: Throwable)
}

实现类可灵活选择输出方式：

• 控制台输出：开发阶段快速查看
• 文件存储：持久化保存关键日志
• 远程上报：集成到监控系统

2. 请求阶段日志增强

在发起请求前，需记录：

• 完整URL（含查询参数）
• 请求体（JSON/XML格式化）
• 设备信息（网络类型、Android版本）

示例实现（Retrofit拦截器）：

class LoggingInterceptor : Interceptor {
    override fun intercept(chain: Interceptor.Chain): Response {
        val request = chain.request()
        val url = request.url.toString()
        val headers = request.headers.toString()
        // 记录请求日志
        ApiLoggerImpl.logRequest(
            url = url,
            params = parseQueryParams(url),
            headers = headers,
            timestamp = System.currentTimeMillis()
        )
        return chain.proceed(request)
    }
}

3. 响应阶段日志优化

需处理三种响应类型：

• 成功响应（200-299）：记录数据摘要
• 客户端错误（4xx）：记录请求重试次数
• 服务端错误（5xx）：触发告警机制

关键实现技巧：

// 使用Gson解析响应体时保留原始字符串
val responseBody = response.peekBody(1024 * 1024).string()
ApiLoggerImpl.logResponse(
    code = response.code,
    rawData = responseBody, // 保留原始响应
    parsedData = tryParse(responseBody), // 尝试解析
    duration = System.currentTimeMillis() - startTime
)

4. 异常处理深度封装

需捕获的异常层级：

1. 网络层：ConnectException、TimeoutException
2. 解析层：JsonSyntaxException、XMLParseException
3. 业务层：自定义的ApiException

异常日志增强方案：

try {
    // 接口调用代码
} catch (e: ConnectException) {
    ApiLoggerImpl.logError(
        exception = e,
        context = "Network unavailable",
        stackTrace = getStackTraceString(e)
    )
    throw CustomApiException(ERROR_NETWORK, e.message)
}

三、接口调用代码优化实践

1. 基础调用模板

推荐使用封装后的ApiClient：

object ApiClient {
    private val logger by lazy { ApiLoggerImpl() }
    suspend fun <T> callApi(
        api: suspend () -> T,
        apiName: String
    ): T {
        val startTime = System.currentTimeMillis()
        return try {
            val result = api.invoke()
            logger.logResponse(
                code = 200,
                data = result,
                duration = System.currentTimeMillis() - startTime
            )
            result
        } catch (e: Exception) {
            logger.logError(e)
            throw e
        }
    }
}
// 使用示例
viewModelScope.launch {
    try {
        val data = ApiClient.callApi(
            apiName = "getUserProfile",
            api = { userService.getProfile(userId) }
        )
        // 处理数据
    } catch (e: ApiException) {
        // 统一错误处理
    }
}

2. 参数校验与日志

在调用前验证参数有效性：

fun validateParams(params: Map<String, Any?>): Boolean {
    return when {
        params["userId"].isNullOrBlank() -> {
            ApiLoggerImpl.logError(IllegalArgumentException("userId required"))
            false
        }
        else -> true
    }
}

3. 响应数据脱敏处理

对敏感信息（如token、手机号）进行过滤：

fun sanitizeResponse(data: Any): Any {
    return when (data) {
        is String -> if (data.contains("token=")) "***" else data
        is Map<*, *> -> data.mapValues { sanitizeResponse(it.value) }
        is List<*> -> data.map { sanitizeResponse(it) }
        else -> data
    }
}

四、进阶优化方案

1. 日志分级管理

定义日志级别：

• DEBUG：完整请求/响应数据
• INFO：关键节点记录
• ERROR：异常堆栈

实现示例：

enum class LogLevel { DEBUG, INFO, ERROR }
interface ApiLogger {
    fun log(level: LogLevel, message: String)
}
// 使用时根据环境配置级别
if (BuildConfig.DEBUG || level >= currentLogLevel) {
    // 输出日志
}

2. 性能监控集成

在日志中加入性能指标：

data class ApiMetrics(
    val dnsTime: Long,
    val connectTime: Long,
    val sslTime: Long,
    val responseTime: Long
)
// 通过OkHttp的EventListener获取
class MetricsEventListener : EventListener {
    private val metrics = ApiMetrics()
    override fun dnsStart(call: Call, domainName: String) {
        metrics.dnsStart = System.nanoTime()
    }
    // 实现其他生命周期方法...
}

3. 自动化测试支持

为单元测试提供Mock日志：

class TestApiLogger : ApiLogger {
    private val logs = mutableListOf<String>()
    override fun log(message: String) {
        logs.add(message)
    }
    fun getLogs(): List<String> = logs
}
// 测试用例
@Test
fun `test api call logs`() {
    val logger = TestApiLogger()
    val client = ApiClient(logger)
    client.callApi({ "test" }, "testApi")
    assertTrue(logger.getLogs().any { it.contains("testApi") })
}

五、最佳实践建议

1. 开发阶段：启用DEBUG级别日志，记录完整请求/响应
2. 线上环境：仅记录ERROR级别，避免日志膨胀
3. 敏感数据：对手机号、身份证号等字段脱敏处理
4. 性能基准：建立接口调用耗时基线（如P90<500ms）
5. 异常告警：对连续失败的接口触发告警机制

通过系统化的日志封装，可使接口调用问题定位效率提升60%以上，同时降低代码重复率。建议结合项目实际情况，选择适合的封装层级，逐步完善日志体系。