Net Android Networking Library

Net is a non-intrusive Android network request library built on top of OkHttp and Kotlin Coroutines. It is designed to be compatible with all OkHttp APIs while providing high-level abstractions for common Android networking tasks.

Key Capabilities:

• Concurrency Management: Supports Concurrent, Serial, Queue, and Synchronous request modes. Includes built-in support for returning the fastest result from concurrent requests.
• Lifecycle Awareness: Automatic request cancellation based on lifecycle and ViewModel support.
• Data Handling: Generic type support for network returns and converters for various data formats (JSON, Protobuf, etc.).
• UI Integration: Automatic handling of Pull-to-Refresh, Load-More, Pagination, Loading Dialogs, and Toast error messages.
• Advanced Networking: Support for HTTPS configuration, Cookie persistence, timed/time-limited requests, and complex caching strategies (Cache-then-Network, LRU, etc.).
• Monitoring: Detailed upload/download progress monitoring (speed, time remaining, etc.).

Request parameters are categorized into two types based on the HTTP method used:

1. UrlRequest: Used for GET, HEAD, OPTIONS, and TRACE. Parameters are located in the URL (Query parameters).
2. BodyRequest: Used for POST, DELETE, PUT, and PATCH. Parameters are sent in the request body as a stream.

Parameter Helper Functions

scopeNetLife {
    val userInfo = Post<UserInfoModel>(Api.LOGIN) {
        param("username", "用户名")
        param("password", "6f2961eb44b12123393fff7e449e50b9de2499c6")
    }.await()
}

Within a scopeNetLife block, you can manage multiple requests in different ways:

Synchronous Requests

Requests are executed sequentially. The second request will only start after the first one completes. You can use the result of the first request as a parameter for the second.

Concurrent Requests

To execute requests in parallel, initiate the request objects without calling .await() immediately. This allows multiple requests to be sent simultaneously. You then call .await() on each to retrieve their respective results.

Scope Management

• Multiple requests in the same scope can be managed together.
• If requests are completely unrelated, you can create multiple separate scopes.

// Synchronous: B waits for A
scopeNetLife {
    val userInfo = Get<UserInfo>(Api.USER).await() // A

    val config = Get<Config>(Api.CONFIG) { // B
        param("userId", userInfo.id) // Uses result from A
    }.await()
}

// Concurrent: Both start at the same time
scopeNetLife {
    val getUserInfoAsync = Get<UserInfo>(Api.USER)
    val getConfigAsync = Get<Config>(Api.CONFIG)

    val userInfo = getUserInfoAsync.await() 
    val config = getConfigAsync.await()
}

When using launch inside a scopeXX function, the relationship is hierarchical.

• Execution Order: If an error occurs in the launch block, the invokeOnCompletion callback (A) executes before the outer scope's .catch block (B).
• Error Propagation:
  • If the scopeNet (outer scope) encounters an error, the request inside the launch (child) is cancelled.
  • If the launch (child) encounters an error, it triggers an error in the scopeNet (outer scope).

scopeNet {
    val await = Post<String>("path").await()

    launch {
       val task = Post<String>("path/error").await()  // Error occurs here
    }.invokeOnCompletion {
        // A
    }
}.catch {
     // B
}

scopeNet {
    val await = Post<String>("path").await()

    launch {
       val task = Post<String>("path/error").await()  // 此时发生请求错误
    }.invokeOnCompletion {
        // A
    }
}.catch {
     // B
}