一个API网关的Kotlin客户端,最省事的做法是包一层阻塞式HTTP调用,再补个协程适配器。nRouter的Kotlin指南走的是另一条路:SDK从一开始就是协程优先——调用用挂起函数,流式用冷Flow,错误是带类型的子类,可以直接分支处理。
先看接入方式。指南把构建产物发布到本地Maven缓存,执行./gradlew clean check publishToMavenLocal,之后就是一条普通的Gradle依赖:ai.nrouter:nrouter-sdk-kotlin:3.1.2。
NRouter()会从环境变量读取NROUTER_API_KEY,指向https://api.nrouter.ai/v1,并在Dispatchers.IO上调度,调用不会阻塞调用方的上下文。Android应用另有nrouter-sdk-android构件。
一次调用长这样:构造NRouter(),调用挂起函数chatCompletions,传入模型nrouter/auto、消息列表,以及nrouter_optimize。返回结果里,正文从choices数组第一项的message.content取出,请求ID则来自result.meta.requestId。
这里有两处值得留意。路由偏好跟着请求体走:nrouter/auto配nrouter_optimize(可选quality、balanced、cost),在cost下还能用nrouter_cost_band(low、mid、high)。响应里的.meta是从网关的x-nr-*响应头提取出来的,请求ID和成本元数据以类型化字段到达,不用自己解析头字符串。
流式是冷Flow——不收集就不动:
- 调用messagesStream,同样传入模型和消息;
- 对它collect,每个分片打印chunk.delta
“冷”在这里很关键:请求在收集时才开始,收集器消失时就停止。这正好是视图模型或Ktor处理器想要的声明周期行为。
网关的拒绝会映射成NRouterError的子类:Request(400,包含cost_band_unsatisfiable)、GuardrailBlocked(400)、Authentication(401)、Credit(402)、RateLimit(429)和Service(503)。
让这套设计真正好用的是isRetryable:RateLimit、Service和Transport为真。于是重试策略就是一个when分支,而不是一张需要手工维护的状态码表。
整体形状就是这样:一个把协程当默认而非附加项的JVM客户端,让网关在一个密钥背后承担路由、预算和护栏。
热门跟贴