@rosetears/aili-pi 0.1.0

package/skills/flutter-dev/references/networking.md

@@ -0,0 +1,566 @@
+# Networking
+
+Dio configuration, interceptors, error handling, and caching strategies for Flutter network requests.
+
+## Dio Setup
+
+```dart
+import 'package:dio/dio.dart';
+
+class ApiClient {
+  static final ApiClient _instance = ApiClient._internal();
+  factory ApiClient() => _instance;
+
+  late final Dio dio;
+
+  ApiClient._internal() {
+    dio = Dio(BaseOptions(
+      baseUrl: 'https://api.example.com/v1',
+      connectTimeout: const Duration(seconds: 10),
+      receiveTimeout: const Duration(seconds: 30),
+      sendTimeout: const Duration(seconds: 30),
+      headers: {
+        'Content-Type': 'application/json',
+        'Accept': 'application/json',
+      },
+    ));
+
+    dio.interceptors.addAll([
+      AuthInterceptor(),
+      LoggingInterceptor(),
+      RetryInterceptor(dio: dio),
+    ]);
+  }
+}
+```
+
+## Interceptors
+
+### Auth Interceptor
+
+```dart
+class AuthInterceptor extends Interceptor {
+  final TokenStorage _tokenStorage;
+
+  AuthInterceptor({TokenStorage? tokenStorage})
+      : _tokenStorage = tokenStorage ?? TokenStorage();
+
+  @override
+  void onRequest(RequestOptions options, RequestInterceptorHandler handler) async {
+    final token = await _tokenStorage.getAccessToken();
+    if (token != null) {
+      options.headers['Authorization'] = 'Bearer $token';
+    }
+    handler.next(options);
+  }
+
+  @override
+  void onError(DioException err, ErrorInterceptorHandler handler) async {
+    if (err.response?.statusCode == 401) {
+      try {
+        final newToken = await _refreshToken();
+        if (newToken != null) {
+          err.requestOptions.headers['Authorization'] = 'Bearer $newToken';
+          final response = await Dio().fetch(err.requestOptions);
+          return handler.resolve(response);
+        }
+      } catch (e) {
+        await _tokenStorage.clearTokens();
+      }
+    }
+    handler.next(err);
+  }
+
+  Future<String?> _refreshToken() async {
+    final refreshToken = await _tokenStorage.getRefreshToken();
+    if (refreshToken == null) return null;
+
+    final response = await Dio().post(
+      'https://api.example.com/v1/auth/refresh',
+      data: {'refresh_token': refreshToken},
+    );
+
+    if (response.statusCode == 200) {
+      final newToken = response.data['access_token'];
+      await _tokenStorage.saveAccessToken(newToken);
+      return newToken;
+    }
+    return null;
+  }
+}
+```
+
+### Logging Interceptor
+
+```dart
+class LoggingInterceptor extends Interceptor {
+  @override
+  void onRequest(RequestOptions options, RequestInterceptorHandler handler) {
+    debugPrint('→ ${options.method} ${options.uri}');
+    if (options.data != null) {
+      debugPrint('   Body: ${options.data}');
+    }
+    handler.next(options);
+  }
+
+  @override
+  void onResponse(Response response, ResponseInterceptorHandler handler) {
+    debugPrint('← ${response.statusCode} ${response.requestOptions.uri}');
+    handler.next(response);
+  }
+
+  @override
+  void onError(DioException err, ErrorInterceptorHandler handler) {
+    debugPrint('✗ ${err.response?.statusCode} ${err.requestOptions.uri}');
+    debugPrint('   Error: ${err.message}');
+    handler.next(err);
+  }
+}
+```
+
+### Retry Interceptor
+
+```dart
+class RetryInterceptor extends Interceptor {
+  final Dio dio;
+  final int maxRetries;
+  final Duration retryDelay;
+
+  RetryInterceptor({
+    required this.dio,
+    this.maxRetries = 3,
+    this.retryDelay = const Duration(seconds: 1),
+  });
+
+  @override
+  void onError(DioException err, ErrorInterceptorHandler handler) async {
+    final retryCount = err.requestOptions.extra['retryCount'] ?? 0;
+
+    if (_shouldRetry(err) && retryCount < maxRetries) {
+      await Future.delayed(retryDelay * (retryCount + 1));
+
+      err.requestOptions.extra['retryCount'] = retryCount + 1;
+
+      try {
+        final response = await dio.fetch(err.requestOptions);
+        return handler.resolve(response);
+      } catch (e) {
+        return handler.next(err);
+      }
+    }
+
+    handler.next(err);
+  }
+
+  bool _shouldRetry(DioException err) {
+    return err.type == DioExceptionType.connectionTimeout ||
+        err.type == DioExceptionType.sendTimeout ||
+        err.type == DioExceptionType.receiveTimeout ||
+        (err.response?.statusCode ?? 0) >= 500;
+  }
+}
+```
+
+## Error Handling
+
+### Custom Exception
+
+```dart
+sealed class ApiException implements Exception {
+  final String message;
+  final int? statusCode;
+  final dynamic data;
+
+  const ApiException({
+    required this.message,
+    this.statusCode,
+    this.data,
+  });
+}
+
+class NetworkException extends ApiException {
+  const NetworkException({super.message = 'Network connection failed'});
+}
+
+class ServerException extends ApiException {
+  const ServerException({
+    required super.message,
+    super.statusCode,
+    super.data,
+  });
+}
+
+class UnauthorizedException extends ApiException {
+  const UnauthorizedException({super.message = 'Authentication required'});
+}
+
+class ValidationException extends ApiException {
+  final Map<String, List<String>> errors;
+
+  const ValidationException({
+    required this.errors,
+    super.message = 'Validation failed',
+  });
+}
+```
+
+### Error Handler
+
+```dart
+class ApiErrorHandler {
+  static ApiException handle(DioException error) {
+    switch (error.type) {
+      case DioExceptionType.connectionTimeout:
+      case DioExceptionType.sendTimeout:
+      case DioExceptionType.receiveTimeout:
+        return const NetworkException(message: 'Connection timeout');
+
+      case DioExceptionType.connectionError:
+        return const NetworkException(message: 'No internet connection');
+
+      case DioExceptionType.badResponse:
+        return _handleResponse(error.response);
+
+      case DioExceptionType.cancel:
+        return const ApiException(message: 'Request cancelled');
+
+      default:
+        return ApiException(message: error.message ?? 'Unknown error');
+    }
+  }
+
+  static ApiException _handleResponse(Response? response) {
+    final statusCode = response?.statusCode ?? 0;
+    final data = response?.data;
+
+    switch (statusCode) {
+      case 400:
+        if (data is Map && data.containsKey('errors')) {
+          return ValidationException(
+            errors: Map<String, List<String>>.from(
+              (data['errors'] as Map).map(
+                (k, v) => MapEntry(k.toString(), List<String>.from(v)),
+              ),
+            ),
+          );
+        }
+        return ServerException(
+          message: data?['message'] ?? 'Bad request',
+          statusCode: statusCode,
+        );
+
+      case 401:
+        return const UnauthorizedException();
+
+      case 403:
+        return const ServerException(
+          message: 'Access denied',
+          statusCode: 403,
+        );
+
+      case 404:
+        return const ServerException(
+          message: 'Resource not found',
+          statusCode: 404,
+        );
+
+      case 422:
+        return ValidationException(
+          errors: _parseValidationErrors(data),
+        );
+
+      case >= 500:
+        return ServerException(
+          message: 'Server error',
+          statusCode: statusCode,
+        );
+
+      default:
+        return ServerException(
+          message: data?['message'] ?? 'Unknown error',
+          statusCode: statusCode,
+        );
+    }
+  }
+
+  static Map<String, List<String>> _parseValidationErrors(dynamic data) {
+    if (data is! Map) return {};
+    final errors = data['errors'];
+    if (errors is! Map) return {};
+    return errors.map((k, v) => MapEntry(
+      k.toString(),
+      v is List ? v.map((e) => e.toString()).toList() : [v.toString()],
+    ));
+  }
+}
+```
+
+## Repository Pattern
+
+```dart
+abstract class BaseRepository {
+  final Dio dio;
+
+  BaseRepository(this.dio);
+
+  Future<T> safeCall<T>(Future<T> Function() call) async {
+    try {
+      return await call();
+    } on DioException catch (e) {
+      throw ApiErrorHandler.handle(e);
+    }
+  }
+}
+
+class UserRepository extends BaseRepository {
+  UserRepository(super.dio);
+
+  Future<User> getUser(String id) => safeCall(() async {
+    final response = await dio.get('/users/$id');
+    return User.fromJson(response.data);
+  });
+
+  Future<List<User>> getUsers({int page = 1, int limit = 20}) => safeCall(() async {
+    final response = await dio.get('/users', queryParameters: {
+      'page': page,
+      'limit': limit,
+    });
+    return (response.data['data'] as List)
+        .map((e) => User.fromJson(e))
+        .toList();
+  });
+
+  Future<User> updateUser(String id, Map<String, dynamic> data) => safeCall(() async {
+    final response = await dio.patch('/users/$id', data: data);
+    return User.fromJson(response.data);
+  });
+}
+```
+
+## Caching
+
+### Memory Cache
+
+```dart
+class CacheInterceptor extends Interceptor {
+  final Map<String, CacheEntry> _cache = {};
+  final Duration maxAge;
+
+  CacheInterceptor({this.maxAge = const Duration(minutes: 5)});
+
+  @override
+  void onRequest(RequestOptions options, RequestInterceptorHandler handler) {
+    if (options.method != 'GET') {
+      handler.next(options);
+      return;
+    }
+
+    final key = _cacheKey(options);
+    final cached = _cache[key];
+
+    if (cached != null && !cached.isExpired) {
+      return handler.resolve(Response(
+        requestOptions: options,
+        data: cached.data,
+        statusCode: 200,
+      ));
+    }
+
+    handler.next(options);
+  }
+
+  @override
+  void onResponse(Response response, ResponseInterceptorHandler handler) {
+    if (response.requestOptions.method == 'GET') {
+      final key = _cacheKey(response.requestOptions);
+      _cache[key] = CacheEntry(
+        data: response.data,
+        expiry: DateTime.now().add(maxAge),
+      );
+    }
+    handler.next(response);
+  }
+
+  String _cacheKey(RequestOptions options) {
+    return '${options.uri}';
+  }
+
+  void invalidate(String pattern) {
+    _cache.removeWhere((key, _) => key.contains(pattern));
+  }
+
+  void clear() => _cache.clear();
+}
+
+class CacheEntry {
+  final dynamic data;
+  final DateTime expiry;
+
+  CacheEntry({required this.data, required this.expiry});
+
+  bool get isExpired => DateTime.now().isAfter(expiry);
+}
+```
+
+### Disk Cache with Hive
+
+```dart
+import 'package:hive_flutter/hive_flutter.dart';
+
+class DiskCacheInterceptor extends Interceptor {
+  static const String _boxName = 'api_cache';
+  final Duration maxAge;
+
+  DiskCacheInterceptor({this.maxAge = const Duration(hours: 1)});
+
+  @override
+  void onRequest(RequestOptions options, RequestInterceptorHandler handler) async {
+    if (options.method != 'GET') {
+      handler.next(options);
+      return;
+    }
+
+    final box = await Hive.openBox(_boxName);
+    final key = _cacheKey(options);
+    final cached = box.get(key);
+
+    if (cached != null) {
+      final entry = CachedResponse.fromJson(cached);
+      if (!entry.isExpired) {
+        return handler.resolve(Response(
+          requestOptions: options,
+          data: entry.data,
+          statusCode: 200,
+        ));
+      }
+    }
+
+    handler.next(options);
+  }
+
+  @override
+  void onResponse(Response response, ResponseInterceptorHandler handler) async {
+    if (response.requestOptions.method == 'GET') {
+      final box = await Hive.openBox(_boxName);
+      final key = _cacheKey(response.requestOptions);
+      await box.put(key, CachedResponse(
+        data: response.data,
+        expiry: DateTime.now().add(maxAge),
+      ).toJson());
+    }
+    handler.next(response);
+  }
+
+  String _cacheKey(RequestOptions options) => options.uri.toString();
+}
+
+class CachedResponse {
+  final dynamic data;
+  final DateTime expiry;
+
+  CachedResponse({required this.data, required this.expiry});
+
+  bool get isExpired => DateTime.now().isAfter(expiry);
+
+  factory CachedResponse.fromJson(Map<String, dynamic> json) {
+    return CachedResponse(
+      data: json['data'],
+      expiry: DateTime.parse(json['expiry']),
+    );
+  }
+
+  Map<String, dynamic> toJson() => {
+    'data': data,
+    'expiry': expiry.toIso8601String(),
+  };
+}
+```
+
+## Riverpod Integration
+
+```dart
+@riverpod
+Dio dio(Ref ref) {
+  return ApiClient().dio;
+}
+
+@riverpod
+UserRepository userRepository(Ref ref) {
+  return UserRepository(ref.watch(dioProvider));
+}
+
+@riverpod
+Future<User> user(Ref ref, String id) async {
+  final repository = ref.watch(userRepositoryProvider);
+  return repository.getUser(id);
+}
+
+@riverpod
+class Users extends _$Users {
+  @override
+  Future<List<User>> build() => _fetch();
+
+  Future<List<User>> _fetch() async {
+    final repository = ref.watch(userRepositoryProvider);
+    return repository.getUsers();
+  }
+
+  Future<void> refresh() async {
+    state = const AsyncLoading();
+    state = await AsyncValue.guard(_fetch);
+  }
+}
+```
+
+## Request Cancellation
+
+```dart
+class SearchRepository extends BaseRepository {
+  CancelToken? _searchToken;
+
+  SearchRepository(super.dio);
+
+  Future<List<SearchResult>> search(String query) async {
+    _searchToken?.cancel();
+    _searchToken = CancelToken();
+
+    return safeCall(() async {
+      final response = await dio.get(
+        '/search',
+        queryParameters: {'q': query},
+        cancelToken: _searchToken,
+      );
+      return (response.data as List)
+          .map((e) => SearchResult.fromJson(e))
+          .toList();
+    });
+  }
+}
+```
+
+## Common Patterns
+
+| Pattern | Usage |
+|---------|-------|
+| Singleton client | Single Dio instance across app |
+| Interceptor chain | Auth → Retry → Cache → Logging |
+| Repository layer | Abstract API from business logic |
+| Error mapping | Convert DioException to app exceptions |
+| Cancel tokens | Debounce/cancel previous requests |
+| Cache invalidation | Clear cache on mutations |
+
+## Networking Checklist
+
+| Item | Implementation |
+|------|----------------|
+| Base configuration | Timeouts, headers, base URL |
+| Auth handling | Token injection, refresh on 401 |
+| Error handling | Typed exceptions, user messages |
+| Retry logic | Exponential backoff for transient errors |
+| Request logging | Debug interceptor |
+| Caching | Memory/disk cache for GET requests |
+| Cancellation | Cancel tokens for search/debounce |
+
+---
+
+*Dio is an open-source package by the Flutter China community.*