nRouter Kotlin SDK:以協程為先的設計筆記
Coroutines first: notes on nRouter's Kotlin SDK
nRouter Kotlin SDK 以協程為先,透過 suspend 函數處理呼叫、以冷 Flow 傳送串流,並提供可分支處理的具型別錯誤。版本 3.1.2 可作為 Gradle 依賴;SDK 從環境變數讀取 NROUTER_API_KEY,並在 Dispatchers.IO 上執行呼叫。串流請求在收集 Flow 時才會啟動,收集器離開後便會停止。
A Kotlin client for an API gateway can be a thin wrapper around blocking HTTP calls, with a coroutine adapter bolted on. The nRouter Kotlin guide goes the other way: the SDK is coroutines-first from the start — suspend functions for calls, a cold Flow for streaming, and typed error subclasses you can branch on.
Full guide: https://nrouter.ai/docs/sdks/kotlin
Setup
The guide publishes the artifact to your local Maven cache (./gradlew clean check publishToMavenLocal), then it's a normal Gradle dependency:
dependencies {
implementation("ai.nrouter:nrouter-sdk-kotlin:3.1.2")
}
NRouter() reads NROUTER_API_KEY from the environment, targets https://api.nrouter.ai/v1, and dispatches on Dispatchers.IO, so calls don't block your caller's context. (For Android apps, the guide points to the separate nrouter-sdk-android artifact.)
A call, and what comes back
suspend fun main() {
val client = NRouter()
val result = client.chatCompletions(
JSONObject()
.put("model", "nrouter/auto")
.put("messages", listOf(mapOf("role" to "user", "content" to "Hello!")))
.put("nrouter_optimize", "balanced")
)
val content = result.body.getJSONArray("choices")
.getJSONObject(0).getJSONObject("message").getString("content")
println(content)
println("Request ID: ${result.meta.requestId}")
}
Two things worth noticing. The routing preference rides in the payload: "nrouter/auto" plus "nrouter_optimize" (quality, balanced or cost), with "nrouter_cost_band" (low, mid, high) available under cost. And the response carries .meta extracted from the gateway's x-nr-* headers, so request ID and cost metadata arrive as typed fields instead of header strings you parse yourself.
Streaming is a cold Flow — nothing moves until you collect:
client.messagesStream(
JSONObject()
.put("model", "nrouter/auto")
.put("messages", listOf(mapOf("role" to "user", "content" to "Hello!")))
).collect { chunk ->
print(chunk.delta)
}
Cold matters here: the request starts on collection and stops when the collector goes away, which is exactly the lifecycle behaviour you want in a view model or a Ktor handler.
Errors you can branch on
Gateway refusals map to subclasses of NRouterError: Request (400, including cost_band_unsatisfiable), GuardrailBlocked (400), Authentication (401), Credit (402), RateLimit (429) and Service (503). The detail that makes this practical is isRetryable — true for RateLimit, Service and Transport — so a retry policy is one when branch instead of a table of status codes maintained by hand.
That's the whole shape: a JVM client that treats coroutines as the default rather than an add-on, and lets the gateway carry routing, budgets and guardrails behind one key. The guide has the full walkthrough: https://nrouter.ai/docs/sdks/kotlin
來源:DEV Community · dev.to