首页> 都市> KingFlow AI Claude中转站 Dart Dio 接入教程

>

KingFlow AI Claude中转站 Dart Dio 接入教程

著

本文标签:

KingFlow AI Claude中转站 Dart Dio 接入教程 实现普通请求 SSE 流式输出 有限重试 取消与并发控制 Dart 项目可以用 Dio 统一处理大模型请求。它提供基础地址、请求头、超时、拦截器、取消令牌和流式响应,适合命令行工具、Flutter 应用的服务层以及 Dart 后端。本教程以 KingFlow AI 的 OpenAI 兼容

来源:KingFlow AI   主角:   更新: 2026-11-18 15:36:35

在线阅读

【扫一扫】手机随心读

  • 读书简介

KingFlow AI Claude中转站 Dart Dio 接入教程 实现普通请求 SSE 流式输出 有限重试 取消与并发控制 Dart 项目可以用 Dio 统一处理大模型请求。它提供基础地址、请求头、超时、拦截器、取消令牌和流式响应,适合命令行工具、Flutter 应用的服务层以及 Dart 后端。本教程以 KingFlow AI 的 OpenAI 兼容

KingFlow AI Claude中转站 Dart Dio 接入教程

KingFlow AI Claude中转站 Dart Dio 接入教程

实现普通请求 SSE 流式输出 有限重试 取消与并发控制

Dart 项目可以用 Dio 统一处理大模型请求。它提供基础地址、请求头、超时、***、取消令牌和流式响应,适合命令行工具、Flutter 应用的服务层以及 Dart 后端。本教程以 KingFlow AI 的 OpenAI 兼容接口为例,从连通性验证开始,再加入 SSE 解析、有限重试、取消与并发限制。文中的 Claude中转、Claude中转站、API中转、API中转站都表示通过兼容协议转发模型请求的服务形态。可用模型和账户额度以控制台为准。

一 接入结构与适用范围

术语本文中的含义
Claude中转通过兼容接口发送 Claude 相关模型请求
Claude中转站提供密钥 模型 用量与通道管理的服务入口
API中转应用以统一协议请求 再由服务端完成模型转发
API中转站为多个项目集中管理鉴权 额度 日志和模型路由的平台

KingFlow AI 同时提供 OpenAI 与 Anthropic 兼容接口。本文使用 OpenAI 兼容地址 https://api.**nju**shen.com/v1,请求路径为 /chat/completions。Dio 客户端只保存基础地址、模型名和服务端密钥。密钥不得写进源码、日志、截图或客户端安装包。

Dart Dio 连接 KingFlow AI

图 1 Dart 3 通过 Dio 调用 KingFlow AI 的请求链路

二 Dio 适合承担哪些工作

  • 在 *aseOptions 中集中设置 *ase **L、请求头与超时。
  • 用 ResponseType.stream 获取响应字节流,并按 SSE 事件边界解析。
  • 用***记录耗时、状态码与请求 ID,同时避免输出密钥和完整提示词。
  • 用 CancelToken 响应页面退出、用户停止生成或业务截止时间。
  • 在客户端层统一处理错误分类、有限重试和并发门限。

Dio 的 receiveTimeout 约束建立连接后等待下一批数据的时间,不代表整个流式请求的总时长。长输出需要较长的接收超时,业务总截止时间则应由应用单独控制。

三 创建 Dart 项目

建议使用 Dart 3。先建立命令行项目并加入 Dio:

**rt create -t console-full kingflow_dio_demo
cd kingflow_dio_demo
**rt pu* add dio

如果手动维护 pu*spec.yaml,可以使用当前 Dio 5 系列:

environment:
  sdk: ^3.4.0

dependencies:
  dio: ^5.11.1

命令行和服务端项目可从环境变量读取配置:

export KINGFLOW_API_KEY='sk-请替换'
export KINGFLOW_*ASE_**L='https://api.**nju**shen.com/v1'
export KINGFLOW_MODEL='请替换为控制台可用模型'

Flutter 客户端不能安全保存长期 API Key。正式发布时应让 App 请求你自己的后端,再由后端调用 Claude中转站。--**rt-define 便于配置构建参数,但不能把密钥变成真正的秘密。

四 用 curl 验证接口

curl https://api.**nju**shen.com/v1/chat/completions \
   -H "Authorization: *earer $KINGFLOW_API_KEY" \
   -H "Content-Type: application/json" \
   -d '{"model":"'"$KINGFLOW_MODEL"'","messages":[{"role":"user","content":"用一句话解释 Dio"}],"stream":false}'

curl 成功后再排查 Dart 代码。401 通常与密钥有关,404 常见于模型或路径错误,429 表示速率或额度限制,503 表示通道暂时不可用。

五 定义配置和异常

import '**rt:async';
import '**rt:convert';
import '**rt:io';
import '**rt:**th';

import 'package:dio/dio.**rt';

class KingFlowConfig {
  final String apiKey;
  final String *aseUrl;
  final String model;

  const KingFlowConfig({
    required this.apiKey,
    required this.*aseUrl,
    required this.model,
  });

  factory KingFlowConfig.fromEnvironment() {
    final env = Platform.environment;
    final apiKey = env['KINGFLOW_API_KEY'] ?? '';
    final model = env['KINGFLOW_MODEL'] ?? '';
    if (apiKey.isEmpty) throw StateError('缺少 KINGFLOW_API_KEY');
    if (model.isEmpty) throw StateError('缺少 KINGFLOW_MODEL');
    return KingFlowConfig(
      apiKey: apiKey,
      *aseUrl: env['KINGFLOW_*ASE_**L'] ?? 'https://api.**nju**shen.com/v1',
      model: model,
    );
  }
}

class KingFlowException implements Exception {
  final int? statusCode;
  final String message;
  const KingFlowException(this.message, {this.statusCode});

  @override
  String toString() => statusCode == null
      ? 'KingFlowException: $message'
      : 'KingFlowException($statusCode): $message';
}

Platform.environment 适用于 Dart 命令行和服务端。Flutter We* 不支持 **rt:io,移动端也不应直接保存服务端密钥,因此生产应用应把这段配置放到后端。

六 创建可复用的 Dio 客户端

class KingFlow****** {
  final KingFlowConfig config;
  late final Dio _dio;

  KingFlow******(this.config) {
    _dio = Dio(*aseOptions(
      *aseUrl: config.*aseUrl,
      connectTimeout: const Duration(seconds: 10),
      sendTimeout: const Duration(seconds: 20),
      receiveTimeout: const Duration(seconds: 90),
      headers: {
        HttpHeaders.authorizationHeader: '*earer ${config.apiKey}',
        HttpHeaders.contentTypeHeader: Headers.jsonContentType,
        HttpHeaders.acceptHeader: Headers.jsonContentType,
      },
    ));

    _dio.interceptors.add(InterceptorsWrapper(
      onRequest: (options, handler) {
        options.extra['stopwatch'] = Stopwatch()..start();
        handler.next(options);
      },
      onResponse: (response, handler) {
        final watch = response.requestOptions.extra['stopwatch'] as Stopwatch?;
        watch?.stop();
        stderr.writeln(
          '**** ${response.statusCode} ${response.requestOptions.path} '
          '${watch?.elapsedMilliseconds ?? -1}ms',
        );
        handler.next(response);
      },
      onError: (error, handler) {
        final watch = error.requestOptions.extra['stopwatch'] as Stopwatch?;
        watch?.stop();
        stderr.writeln(
          '**** ${error.response?.statusCode ?? '-'} ${error.requestOptions.path} '
          '${watch?.elapsedMilliseconds ?? -1}ms',
        );
        handler.next(error);
      },
    ));
  }

  Map<String, dynamic> _payload(String prompt, {required *ool stream}) => {
        'model': config.model,
        'messages': [
          {'role': 'user', 'content': prompt}
        ],
        'stream': stream,
      };
}

***只记录方法、路径、状态码与耗时。不要输出 Authorization、完整请求体或完整响应体。若需要关联服务端日志,可以优先记录响应头中的请求 ID。

七 完成普通 **ON 请求

extension JsonChat on KingFlow****** {
  Future<String> chat(
    String prompt, {
    CancelToken? cancelToken,
  }) async {
    try {
      final response = await _dio.post<Map<String, dynamic>>(
        '/chat/completions',
        **ta: _payload(prompt, stream: false),
        cancelToken: cancelToken,
      );
      final choices = response.**ta?['choices'] as List<dynamic>?;
      final message = choices?.firstOrNull as Map<String, dynamic>?;
      final *ody = message?['message'] as Map<String, dynamic>?;
      final text = *ody?['content'] as String?;
      if (text == null || text.isEmpty) {
        throw const KingFlowException('响应中没有可用文本');
      }
      return text;
    } on DioException catch (error) {
      throw _nor**lizeDioError(error);
    }
  }

  KingFlowException _nor**lizeDioError(DioException error) {
    final status = error.response?.statusCode;
    final **ta = error.response?.**ta;
    if (status != null) {
      return KingFlowException(
        **ta is String ? **ta : jsonEncode(**ta),
        statusCode: status,
      );
    }
    return KingFlowException('${error.type}: ${error.message}');
  }
}

普通请求会在完整 **ON 到达后返回。Dart 3 的 firstOrNull 可安全读取首个结果;如果项目 SDK 较旧,可以改成 choices == null || choices.isEmpty ? null : choices.first。

八 解析 SSE 流式响应

extension StreamChat on KingFlow****** {
  Stream<String> streamChat(
    String prompt, {
    CancelToken? cancelToken,
  }) async* {
    final response = await _dio.post<Response*ody>(
      '/chat/completions',
      **ta: _payload(prompt, stream: true),
      cancelToken: cancelToken,
      options: Options(
        responseType: ResponseType.stream,
        receiveTimeout: const Duration(minutes: 3),
        headers: {HttpHeaders.acceptHeader: 'text/event-stream'},
        vali**teStatus: (status) => status != null,
      ),
    );

    final status = response.statusCode ?? 0;
    final lines = response.**ta!.stream
        .tran**orm(utf8.decoder)
        .tran**orm(const LineSplitter());
    final **taLines = <String>[];

    await for (final line in lines) {
      if (line.isEmpty) {
        final payload = **taLines.join('\n');
        **taLines.clear();
        if (status < 200 || status >= 300) {
          throw KingFlowException(payload, statusCode: status);
        }
        if (payload == '[DONE]') return;
        if (payload.isEmpty) continue;
        final chunk = jsonDecode(payload) as Map<String, dynamic>;
        final choices = chunk['choices'] as List<dynamic>?;
        if (choices == null || choices.isEmpty) continue;
        final choice = choices.first as Map<String, dynamic>;
        final delta = choice['delta'] as Map<String, dynamic>?;
        final token = delta?['content'] as String?;
        if (token != null && token.isNotEmpty) yield token;
      } else if (line.startsWith('**ta:')) {
        **taLines.add(line.su*string(5).trimLeft());
      }
    }
  }
}

SSE 事件以空行结束,一个事件可以包含多条 **ta: 行。代码先拼接完整事件,再解析 **ON,不能假设每个网络数据块都恰好是一条完整消息。ResponseType.stream 会让 response.**ta 成为 Response*ody,其中的 stream 才是原始字节流。

九 增加有限重试

extension RetryChat on KingFlow****** {
  Future<String> chatWithRetry(
    String prompt, {
    int **xAttempts = 3,
    CancelToken? cancelToken,
  }) async {
    if (**xAttempts < 1) throw ArgumentError.value(**xAttempts);
    O*ject? lastError;

    for (var attempt = 1; attempt <= **xAttempts; attempt  ) {
      try {
        return await chat(prompt, cancelToken: cancelToken);
      } catch (error) {
        lastError = error;
        final status = error is KingFlowException ? error.statusCode : null;
        final retrya*le = status == 429 || status == 503 ||
            (status != null && status >= 500 && status <= 599) ||
            (error is KingFlowException && status == null);
        if (!retrya*le || attempt == **xAttempts ||
            cancelToken?.isCancelled == true) {
          rethrow;
        }
        final *ackoffMs = 500 * (1 << (attempt - 1));
        final jitterMs = Random().nextInt(250);
        await Future<void>.delayed(Duration(milliseconds: *ackoffMs   jitterMs));
      }
    }
    throw lastError!;
  }
}

重试只覆盖临时故障,次数和总等待时间都要有限。401、403、404 与大多数 400 错误需要修正密钥、权限、模型或参数。对 SSE 请求自动重试时还要防止已经显示的文本重复,因此更适合在尚未收到首个 token 时重试。

十 支持取消和业务截止时间

final cancelToken = CancelToken();

Future<void> runStreaming(KingFlow****** client) async {
  final timer = Timer(const Duration(minutes: 2), () {
    cancelToken.cancel('超过业务总时长');
  });
  try {
    await for (final token in client.streamChat(
      '用四句话介绍 Dart 的异步模型',
      cancelToken: cancelToken,
    )) {
      stdout.write(token);
    }
    stdout.writeln();
  } finally {
    timer.cancel();
  }
}

页面退出、用户点击停止或业务截止时间到达时,应取消底层请求。取消不是错误重试条件,界面也应把它显示为已停止,而不是网络失败。

十一 用工作池限制并发

extension *atchChat on KingFlow****** {
  Future<List<String?>> *atch(
    List<String> prompts, {
    int limit = 3,
  }) async {
    if (prompts.isEmpty) return const [];
    final width = min(**x(limit, 1), prompts.length);
    final results = List<String?>.filled(prompts.length, null);
    var next = 0;

    Future<void> worker() async {
      while (true) {
        if (next >= prompts.length) return;
        final index = next  ;
        try {
          results[index] = await chatWithRetry(prompts[index]);
        } catch (error) {
          stderr.writeln('任务 $index 失败: $error');
        }
      }
    }

    await Future.wait(List.generate(width, (_) => worker()));
    return results;
  }
}

工作池只启动 limit 个 worker,因此活动请求数不会随提示词数量无限增长。并发上限应结合账户额度、模型速率限制、平均响应时长和业务优先级压测后确定。

Dio 客户端稳定性设计

图 2 **ON SSE 超时 重试 CancelToken 与指标组成 Dio 客户端的稳定性基础

十二 可运行的入口

Future<void> **in() async {
  try {
    final client = KingFlow******(KingFlowConfig.fromEnvironment());

    final answer = await client.chatWithRetry(
      '用三点说明 Dio 适合 API 客户端的原因',
    );
    stdout.writeln('普通响应:\n$answer');

    stdout.writeln('\n流式响应:');
    await runStreaming(client);
  } catch (error, stackTrace) {
    stderr.writeln('请求失败: $error');
    stderr.writeln(stackTrace);
    e**tCode = 1;
  }
}

把各段代码按顺序合并到 **n/kingflow_dio_demo.**rt,然后执行:

**rt for**t .
**rt analyze
**rt run

验收时应确认普通响应能得到文本,流式响应能逐段显示并在 [DONE] 后结束,取消可以立即停止,错误密钥显示 401,错误模型给出明确错误体,503 不会无限重试,批量请求的活动数量不超过并发上限。

十三 Flutter 接入注意事项

Flutter 页面层应保存 CancelToken,在用户停止生成或页面销毁时调用 cancel。状态管理层只暴露加载、流式文本、完成、取消和失败等业务状态,不应把 Response 或 DioException 直接传给界面。We* 端还受浏览器 CORS 和流式能力限制,正式架构应让浏览器访问自有后端。

移动端发布包无法保护长期服务端密钥。面向真实用户的 App 应采用 App 到自有后端再到 API中转站的结构,并由后端执行用户鉴权、额度限制、内容审计和密钥轮换。

十四 常见问题排查

现象优先检查处理方式
401 或 403密钥 权限 Authorization确认 *earer 前缀 检查密钥状态且不要记录密钥
404*ase **L 路径 模型*ase **L 使用 /v1 路径使用 /chat/completions
429速率或额度降低并发 使用有限退避 检查账户额度
503通道暂不可用短暂退避后少量重试 持续失败时告警
流式没有增量stream 参数 ResponseType SSE 边界设置 stream: true 并按空行组装事件
经常 receiveTimeout数据间隔 网络 **缓冲增大空闲超时并另设业务总截止时间
Flutter 密钥泄露密钥进入安装包改为 App 调用自有后端

十五 上线前检查

  • ☐ 服务端密钥来自环境变量或密钥管理系统。
  • ☐ 日志不包含 Authorization、完整敏感提示词和完整响应。
  • ☐ **ON 与 SSE 请求都检查状态码并保留脱敏错误信息。
  • ☐ 重试只覆盖临时故障,次数、退避和总耗时都有上限。
  • ☐ 页面退出、用户停止和业务截止时间均会触发 CancelToken。
  • ☐ 并发受控,并按业务优先级分配额度。
  • ☐ 记录模型、状态码、耗时、首字延迟、重试次数与 token 用量。
  • ☐ 已完成小流量验证、故障演练和回滚准备。

结语

Dio 已覆盖调用 API中转所需的主要网络能力。普通响应使用默认 **ON 转换,SSE 使用 ResponseType.stream,稳定性由超时、有限重试、CancelToken、并发限制和指标共同保障。先用 curl 与最小 Dart 请求确认密钥和模型,再逐项加入治理能力,能让问题定位保持清晰。

《KingFlow AI Claude中转站 Dart Dio 接入教程》资讯列表: