flu-cli-core 1.0.0

package/templates/core_files/network/app_http.dart.template

@@ -0,0 +1,306 @@
+import 'package:dio/dio.dart';
+import 'package:flutter/foundation.dart';
+
+import '../config/app_config.dart';
+import 'app_error_code.dart';
+import 'app_response.dart';
+import 'interceptors/index.dart';
+import 'response_adapter.dart';
+
+/// App 网络请求核心类
+///
+/// 1. 统一返回 [AppResponse]，不抛出异常
+/// 2. 支持泛型自动解析 [fromJson]
+/// 3. 支持配置适配器 [AppResponseAdapter]
+/// 4. 支持请求级错误控制 [showError]
+class AppHttp {
+  static final AppHttp _instance = AppHttp._internal();
+  factory AppHttp() => _instance;
+
+  late Dio _dio;
+  bool _initialized = false;
+  bool _autoShowError = true;
+
+  AppHttp._internal();
+
+  /// 获取 Dio 实例 (懒加载)
+  Dio get dio {
+    if (!_initialized) {
+      // 默认初始化，防止未调用 init 时报错
+      init();
+    }
+    return _dio;
+  }
+
+  /// 全局初始化
+  ///
+  /// [adapter] 响应适配器，默认使用 [DefaultResponseAdapter]
+  /// [interceptors] 额外的拦截器
+  /// [autoShowError] 是否全局开启错误弹窗，默认 true
+  static void init({
+    AppResponseAdapter? adapter,
+    List<Interceptor>? interceptors,
+    bool autoShowError = true,
+  }) {
+    final instance = AppHttp._instance;
+    instance._autoShowError = autoShowError;
+    final config = AppConfig.I;
+
+    instance._dio = Dio(
+      BaseOptions(
+        baseUrl: config.apiBaseUrl,
+        connectTimeout: config.connectTimeout,
+        receiveTimeout: config.receiveTimeout,
+        headers: {
+          'Content-Type': 'application/json',
+          'Accept': 'application/json',
+        },
+      ),
+    );
+
+    // 1. 添加日志拦截器（完整输出，不截断）
+    if (config.enableLog) {
+      instance._dio.interceptors.add(
+        FullLogInterceptor(
+          requestBody: true,
+          responseBody: true,
+        ),
+      );
+    }
+
+    // 2. 添加响应处理拦截器 (核心)
+    instance._dio.interceptors.add(
+      AppResponseInterceptor(
+        adapter: adapter ?? DefaultResponseAdapter(),
+        autoShowError: autoShowError,
+      ),
+    );
+
+    // 2.5 添加网络错误拦截器
+    instance._dio.interceptors.add(
+      NetworkErrorInterceptor(autoShowError: autoShowError),
+    );
+
+    // 3. 添加自定义拦截器
+    if (interceptors != null) {
+      instance._dio.interceptors.addAll(interceptors);
+    }
+
+    instance._initialized = true;
+  }
+
+  // ========================================================================
+  // 核心请求方法 - 统一返回 AppResponse，不抛异常
+  // ========================================================================
+
+  /// GET 请求
+  ///
+  /// [path] 请求路径
+  /// [fromJson] 解析函数，将 JSON 转换为对象 T
+  /// [showError] 本次请求是否显示错误弹窗，null 则使用全局配置
+  Future<AppResponse<T>> get<T>(
+    String path, {
+    Map<String, dynamic>? queryParameters,
+    T Function(dynamic)? fromJson,
+    bool? showError,
+    Options? options,
+    CancelToken? cancelToken,
+  }) async {
+    return _request<T>(
+      method: 'GET',
+      path: path,
+      queryParameters: queryParameters,
+      fromJson: fromJson,
+      showError: showError,
+      options: options,
+      cancelToken: cancelToken,
+    );
+  }
+
+  /// POST 请求
+  Future<AppResponse<T>> post<T>(
+    String path, {
+    dynamic data,
+    Map<String, dynamic>? queryParameters,
+    T Function(dynamic)? fromJson,
+    bool? showError,
+    Options? options,
+    CancelToken? cancelToken,
+  }) async {
+    return _request<T>(
+      method: 'POST',
+      path: path,
+      data: data,
+      queryParameters: queryParameters,
+      fromJson: fromJson,
+      showError: showError,
+      options: options,
+      cancelToken: cancelToken,
+    );
+  }
+
+  /// PUT 请求
+  Future<AppResponse<T>> put<T>(
+    String path, {
+    dynamic data,
+    Map<String, dynamic>? queryParameters,
+    T Function(dynamic)? fromJson,
+    bool? showError,
+    Options? options,
+    CancelToken? cancelToken,
+  }) async {
+    return _request<T>(
+      method: 'PUT',
+      path: path,
+      data: data,
+      queryParameters: queryParameters,
+      fromJson: fromJson,
+      showError: showError,
+      options: options,
+      cancelToken: cancelToken,
+    );
+  }
+
+  /// DELETE 请求
+  Future<AppResponse<T>> delete<T>(
+    String path, {
+    dynamic data,
+    Map<String, dynamic>? queryParameters,
+    T Function(dynamic)? fromJson,
+    bool? showError,
+    Options? options,
+    CancelToken? cancelToken,
+  }) async {
+    return _request<T>(
+      method: 'DELETE',
+      path: path,
+      data: data,
+      queryParameters: queryParameters,
+      fromJson: fromJson,
+      showError: showError,
+      options: options,
+      cancelToken: cancelToken,
+    );
+  }
+
+  // ========================================================================
+  // 私有统一请求处理逻辑
+  // ========================================================================
+
+  Future<AppResponse<T>> _request<T>({
+    required String method,
+    required String path,
+    dynamic data,
+    Map<String, dynamic>? queryParameters,
+    T Function(dynamic)? fromJson,
+    bool? showError,
+    Options? options,
+    CancelToken? cancelToken,
+  }) async {
+    try {
+      // 组装 Options
+      options ??= Options();
+      options.method = method;
+      // 将请求级错误控制参数传入 extra
+      options.extra ??= {};
+      if (showError != null) {
+        options.extra!['showError'] = showError;
+      }
+
+      final response = await dio.request(
+        path,
+        data: data,
+        queryParameters: queryParameters,
+        options: options,
+        cancelToken: cancelToken,
+      );
+
+      // 解析响应 (此时 response.data 已经被拦截器转换为标准 Map)
+      return _parseResponse<T>(response.data, fromJson);
+    } on DioException catch (e) {
+      return _handleDioError<T>(e, showError: showError ?? _autoShowError);
+    } catch (e) {
+      return AppResponse<T>(
+        code: -1,
+        msg: '未知错误: ${e.toString()}',
+        data: null,
+      );
+    }
+  }
+
+  /// 解析标准响应 Map 为 AppResponse
+  AppResponse<T> _parseResponse<T>(
+    dynamic data,
+    T Function(dynamic)? fromJson,
+  ) {
+    if (data is Map<String, dynamic>) {
+      final code = data['code'] as int;
+      final msg = data['msg'] as String;
+      final rawData = data['data'];
+
+      // 泛型数据解析
+      T? parsedData;
+      if (rawData != null && fromJson != null) {
+        try {
+          parsedData = fromJson(rawData);
+        } catch (e) {
+          debugPrint('❌ JSON解析失败: $e');
+          // 解析失败视为错误，或者你可以决定返回 data=null 但 code=200
+          // 这里建议视为错误，因为数据契约不符
+          return AppResponse<T>(
+            code: AppErrorCode.parseError,
+            msg: '数据解析失败: $e',
+            originalData: rawData,
+          );
+        }
+      } else if (rawData != null && rawData is T) {
+        // 如果未提供解析函数但类型匹配 (例如 T 是 String 或 Map)
+        parsedData = rawData;
+      }
+
+      return AppResponse<T>(
+        code: code,
+        msg: msg,
+        data: parsedData,
+        originalData: rawData,
+      );
+    }
+    return AppResponse<T>(
+      code: AppErrorCode.parseError,
+      msg: '响应格式错误',
+      data: null,
+    );
+  }
+
+  /// 处理 Dio 错误
+  AppResponse<T> _handleDioError<T>(DioException e, {bool showError = true}) {
+    String msg = '';
+    switch (e.type) {
+      case DioExceptionType.connectionTimeout:
+        msg = '连接超时';
+        break;
+      case DioExceptionType.sendTimeout:
+        msg = '请求超时';
+        break;
+      case DioExceptionType.receiveTimeout:
+        msg = '响应超时';
+        break;
+      case DioExceptionType.badResponse:
+        msg = '服务器错误 (${e.response?.statusCode})';
+        break;
+      case DioExceptionType.cancel:
+        msg = '请求取消';
+        break;
+      default:
+        msg = e.message ?? '网络连接异常';
+    }
+
+    // 注意：网络错误的弹窗已由 NetworkErrorInterceptor 统一处理
+    // 这里只需返回标准的错误响应即可
+    return AppResponse<T>(
+      code: AppErrorCode.networkError,
+      msg: msg,
+      data: null,
+    );
+  }
+}

package/templates/core_files/network/app_response.dart.template

@@ -0,0 +1,81 @@
+import 'app_error_code.dart';
+
+/// 统一响应模型
+///
+/// 无论后端返回什么格式,经过 [AppResponseAdapter] 处理后,
+/// 最终在 Service 层拿到的永远是这个对象。
+class AppResponse<T> {
+  /// 统一状态码
+  /// 0 或 200 表示成功,其他表示失败
+  final int code;
+
+  /// 统一消息
+  /// 成功消息或错误提示
+  final String msg;
+
+  /// 业务数据
+  final T? data;
+
+  /// 原始响应数据 (保留备查)
+  final dynamic originalData;
+
+  AppResponse({
+    required this.code,
+    required this.msg,
+    this.data,
+    this.originalData,
+  });
+
+  /// 创建成功响应
+  factory AppResponse.success({
+    T? data,
+    String msg = '成功',
+    int code = AppErrorCode.success,
+  }) {
+    return AppResponse(
+      code: code,
+      msg: msg,
+      data: data,
+    );
+  }
+
+  /// 创建失败响应
+  factory AppResponse.fail({
+    required String msg,
+    int code = AppErrorCode.networkError,
+    T? data,
+  }) {
+    return AppResponse(
+      code: code,
+      msg: msg,
+      data: data,
+    );
+  }
+
+  // ========================================================================
+  // 状态判断方法
+  // ========================================================================
+
+  /// 请求是否成功
+  bool get isSuccess => code == AppErrorCode.success || code == AppErrorCode.successAlt;
+
+  /// 请求是否失败
+  bool get isFailed => !isSuccess;
+
+  /// 是否未授权 (需要登录)
+  bool get isUnauthorized => code == AppErrorCode.unauthorized;
+
+  /// 是否禁止访问 (权限不足)
+  bool get isForbidden => code == AppErrorCode.forbidden;
+
+  /// 是否网络错误
+  bool get isNetworkError => code == AppErrorCode.networkError;
+
+  /// 是否解析错误
+  bool get isParseError => code == AppErrorCode.parseError;
+
+  @override
+  String toString() {
+    return 'AppResponse(code: $code, msg: $msg, data: $data)';
+  }
+}

package/templates/core_files/network/index.dart.template

@@ -0,0 +1,12 @@
+// 导出网络层类 (按字母顺序排列)
+
+// 错误码常量
+export 'app_error_code.dart';
+// 网络工具
+export 'app_http.dart';
+// 网络响应
+export 'app_response.dart';
+// 网络拦截器
+export 'interceptors/index.dart';
+// 网络响应适配器
+export 'response_adapter.dart';

package/templates/core_files/network/interceptors/app_response_interceptor.dart.template

@@ -0,0 +1,44 @@
+import 'package:dio/dio.dart';
+import 'package:flutter/material.dart';
+
+import '../../utils/toast_util.dart';
+import '../response_adapter.dart';
+
+/// 响应处理拦截器
+///
+/// 1. 使用适配器转换响应数据
+/// 2. 自动处理错误提示 (可配置)
+class AppResponseInterceptor extends Interceptor {
+  final AppResponseAdapter adapter;
+  final bool autoShowError;
+
+  AppResponseInterceptor({
+    required this.adapter,
+    this.autoShowError = true,
+  });
+
+  @override
+  void onResponse(Response response, ResponseInterceptorHandler handler) {
+    // 1. 转换数据格式
+    final adaptedMap = adapter.adapt(response.data);
+
+    // 2. 替换原始数据为标准格式
+    response.data = adaptedMap;
+
+    // 3. 自动错误提示处理
+    // 优先使用请求配置的 showError,如果未配置则使用全局配置
+    final showError =
+        response.requestOptions.extra['showError'] as bool? ?? autoShowError;
+
+    final code = adaptedMap['code'];
+    final msg = adaptedMap['msg'];
+
+    // 如果失败且需要显示错误
+    if (code != 200 && code != 0 && showError == true) {
+      ToastUtil.error(msg);
+      debugPrint('❌ API错误: $msg');
+    }
+
+    handler.next(response);
+  }
+}

package/templates/core_files/network/interceptors/auth_interceptor.dart.template

@@ -0,0 +1,30 @@
+import 'package:dio/dio.dart';
+
+/// Token 自动注入拦截器
+///
+/// 在每个请求的 Header 中自动添加 Authorization token
+///
+/// 使用示例:
+/// ```dart
+/// HttpUtil.init(
+///   interceptors: [
+///     AuthInterceptor(
+///       getToken: () => StorageUtil.getString('token') ?? '',
+///     ),
+///   ],
+/// );
+/// ```
+class AuthInterceptor extends Interceptor {
+  final String Function() getToken;
+
+  AuthInterceptor({required this.getToken});
+
+  @override
+  void onRequest(RequestOptions options, RequestInterceptorHandler handler) {
+    final token = getToken();
+    if (token.isNotEmpty) {
+      options.headers['Authorization'] = 'Bearer $token';
+    }
+    handler.next(options);
+  }
+}

package/templates/core_files/network/interceptors/error_interceptor.dart.template

@@ -0,0 +1,48 @@
+import 'package:dio/dio.dart';
+import 'package:flutter/foundation.dart';
+
+/// 统一错误处理拦截器
+///
+/// 处理 401/403 等常见错误状态码
+///
+/// 使用示例:
+/// ```dart
+/// HttpUtil.init(
+///   interceptors: [
+///     ErrorInterceptor(
+///       onUnauthorized: (_) {
+///         // 跳转登录页
+///         Get.offAllNamed('/login');
+///       },
+///       onForbidden: (_) {
+///         // 显示无权限提示
+///         showToast('无访问权限');
+///       },
+///     ),
+///   ],
+/// );
+/// ```
+class ErrorInterceptor extends Interceptor {
+  final void Function(int statusCode)? onUnauthorized;
+  final void Function(int statusCode)? onForbidden;
+
+  ErrorInterceptor({
+    this.onUnauthorized,
+    this.onForbidden,
+  });
+
+  @override
+  void onError(DioException err, ErrorInterceptorHandler handler) {
+    final statusCode = err.response?.statusCode;
+
+    if (statusCode == 401) {
+      debugPrint('❌ 未授权访问,请重新登录');
+      onUnauthorized?.call(401);
+    } else if (statusCode == 403) {
+      debugPrint('❌ 无访问权限');
+      onForbidden?.call(403);
+    }
+
+    handler.next(err);
+  }
+}

package/templates/core_files/network/interceptors/index.dart.template

@@ -0,0 +1,6 @@
+export 'app_response_interceptor.dart';
+export 'auth_interceptor.dart';
+export 'error_interceptor.dart';
+export 'log_interceptor.dart';
+export 'network_error_interceptor.dart';
+export 'retry_interceptor.dart';

package/templates/core_files/network/interceptors/log_interceptor.dart.template

@@ -0,0 +1,97 @@
+import 'dart:convert';
+import 'package:dio/dio.dart';
+import 'package:flutter/foundation.dart';
+
+/// 完整日志拦截器
+///
+/// 解决 debugPrint 长度限制导致响应内容被截断的问题
+class FullLogInterceptor extends Interceptor {
+  final bool request;
+  final bool requestHeader;
+  final bool requestBody;
+  final bool responseHeader;
+  final bool responseBody;
+  final bool error;
+
+  FullLogInterceptor({
+    this.request = true,
+    this.requestHeader = false,
+    this.requestBody = true,
+    this.responseHeader = false,
+    this.responseBody = true,
+    this.error = true,
+  });
+
+  @override
+  void onRequest(RequestOptions options, RequestInterceptorHandler handler) {
+    if (request) {
+      _log('┌─────────────────────────────────────────────────');
+      _log('│ Request: ${options.method} ${options.uri}');
+    }
+    if (requestHeader) {
+      _log('│ Headers: ${options.headers}');
+    }
+    if (requestBody && options.data != null) {
+      _log('│ Body: ${_formatJson(options.data)}');
+    }
+    if (request) {
+      _log('└─────────────────────────────────────────────────');
+    }
+    handler.next(options);
+  }
+
+  @override
+  void onResponse(Response response, ResponseInterceptorHandler handler) {
+    if (responseBody) {
+      _log('┌─────────────────────────────────────────────────');
+      _log('│ Response: ${response.statusCode} ${response.requestOptions.uri}');
+      if (responseHeader) {
+        _log('│ Headers: ${response.headers.map}');
+      }
+      _log('│ Body:');
+      _logLongText(_formatJson(response.data));
+      _log('└─────────────────────────────────────────────────');
+    }
+    handler.next(response);
+  }
+
+  @override
+  void onError(DioException err, ErrorInterceptorHandler handler) {
+    if (error) {
+      _log('┌─────────────────────────────────────────────────');
+      _log('│ ❌ Error: ${err.type}');
+      _log('│ Message: ${err.message}');
+      if (err.response != null) {
+        _log('│ Status: ${err.response?.statusCode}');
+        _logLongText(_formatJson(err.response?.data));
+      }
+      _log('└─────────────────────────────────────────────────');
+    }
+    handler.next(err);
+  }
+
+  /// 格式化 JSON
+  String _formatJson(dynamic data) {
+    try {
+      if (data is Map || data is List) {
+        return const JsonEncoder.withIndent('  ').convert(data);
+      }
+      return data.toString();
+    } catch (e) {
+      return data.toString();
+    }
+  }
+
+  /// 输出长文本（分段打印，避免截断）
+  void _logLongText(String text) {
+    const chunkSize = 800;
+    for (var i = 0; i < text.length; i += chunkSize) {
+      final end = (i + chunkSize < text.length) ? i + chunkSize : text.length;
+      _log('│ ${text.substring(i, end)}');
+    }
+  }
+
+  void _log(String msg) {
+    debugPrint(msg);
+  }
+}

package/templates/core_files/network/interceptors/network_error_interceptor.dart.template

@@ -0,0 +1,58 @@
+import 'package:dio/dio.dart';
+import 'package:flutter/foundation.dart';
+
+import '../../utils/toast_util.dart';
+
+/// 网络错误拦截器
+///
+/// 统一处理超时、连接失败等网络异常，并自动弹出错误提示
+///
+/// 使用示例:
+/// ```dart
+/// AppHttp.init(
+///   autoShowError: true, // 全局开启错误弹窗
+///   interceptors: [
+///     // 其他拦截器...
+///   ],
+/// );
+/// ```
+class NetworkErrorInterceptor extends Interceptor {
+  final bool autoShowError;
+
+  NetworkErrorInterceptor({this.autoShowError = true});
+
+  @override
+  void onError(DioException err, ErrorInterceptorHandler handler) {
+    // 优先使用请求级配置，如果未设置则使用全局配置
+    final showError =
+        err.requestOptions.extra['showError'] as bool? ?? autoShowError;
+
+    if (showError) {
+      final msg = _getErrorMessage(err);
+      ToastUtil.error(msg);
+      debugPrint('❌ 网络错误: $msg');
+    }
+
+    handler.next(err);
+  }
+
+  /// 根据异常类型返回友好的错误提示
+  String _getErrorMessage(DioException e) {
+    switch (e.type) {
+      case DioExceptionType.connectionTimeout:
+        return '连接超时';
+      case DioExceptionType.sendTimeout:
+        return '请求超时';
+      case DioExceptionType.receiveTimeout:
+        return '响应超时';
+      case DioExceptionType.badResponse:
+        return '服务器错误 (${e.response?.statusCode})';
+      case DioExceptionType.cancel:
+        return '请求取消';
+      case DioExceptionType.connectionError:
+        return '网络连接异常';
+      default:
+        return e.message ?? '未知网络错误';
+    }
+  }
+}