一、OAuth票据刷新机制概述

OAuth2.0协议中，Access Token（访问令牌）的有效期通常较短（如1-2小时），而Refresh Token（刷新令牌）的长期有效性（如30天）允许客户端在Access Token过期后重新获取新令牌，避免用户频繁登录。这一机制在移动端应用中尤为重要，直接影响用户体验和安全性。

1.1 票据刷新场景分析

• 场景1：用户打开应用时，检查本地存储的Access Token是否过期，若过期则自动触发刷新流程。
• 场景2：API请求因Access Token过期返回401未授权错误时，拦截请求并触发刷新。
• 场景3：后台定时刷新令牌，确保令牌始终有效（需权衡安全性与性能）。

1.2 核心挑战

• 异步处理：刷新过程需阻塞原请求，避免并发问题。
• 错误处理：需处理Refresh Token过期、网络异常等边界情况。
• 状态管理：刷新成功后需更新全局状态，避免重复刷新。

二、Dio库的核心能力与适配

Dio是Flutter中最流行的HTTP客户端库，其拦截器机制和并发控制能力为OAuth票据刷新提供了完美支持。

2.1 Dio的拦截器体系

Dio通过Interceptor类实现请求/响应的统一处理，支持三种拦截方式：

dio.interceptors.add(InterceptorsWrapper(
  onRequest: (RequestOptions options, RequestInterceptorHandler handler) {
    // 请求前处理（如添加Token）
    handler.next(options);
  },
  onResponse: (Response response, ResponseInterceptorHandler handler) {
    // 响应后处理（如解析数据）
    handler.next(response);
  },
  onError: (DioError error, ErrorInterceptorHandler handler) {
    // 错误处理（如401触发刷新）
    handler.next(error);
  },
));

2.2 并发控制与锁机制

为避免重复刷新，需实现请求队列和锁机制：

class TokenLock {
  bool _isRefreshing = false;
  final List<Completer<void>> _waiters = [];
  Future<void> acquire() async {
    if (_isRefreshing) {
      final completer = Completer<void>();
      _waiters.add(completer);
      return completer.future;
    }
    _isRefreshing = true;
  }
  void release() {
    _isRefreshing = false;
    if (_waiters.isNotEmpty) {
      final next = _waiters.removeAt(0);
      next.complete();
    }
  }
}

三、完整实现方案

3.1 令牌存储与状态管理

使用flutter_secure_storage安全存储令牌：

import 'package:flutter_secure_storage/flutter_secure_storage.dart';
class TokenManager {
  static const _storage = FlutterSecureStorage();
  static const _keyAccessToken = 'access_token';
  static const _keyRefreshToken = 'refresh_token';
  static const _keyExpiry = 'token_expiry';
  static Future<void> saveTokens({
    required String accessToken,
    required String refreshToken,
    required int expiresIn,
  }) async {
    final expiry = DateTime.now().add(Duration(seconds: expiresIn)).millisecondsSinceEpoch;
    await _storage.write(key: _keyAccessToken, value: accessToken);
    await _storage.write(key: _keyRefreshToken, value: refreshToken);
    await _storage.write(key: _keyExpiry, value: expiry.toString());
  }
  static Future<Map<String, String>?> getTokens() async {
    final accessToken = await _storage.read(key: _keyAccessToken);
    final refreshToken = await _storage.read(key: _keyRefreshToken);
    final expiryStr = await _storage.read(key: _keyExpiry);
    if (accessToken == null || refreshToken == null || expiryStr == null) return null;
    final expiry = int.parse(expiryStr);
    if (DateTime.now().millisecondsSinceEpoch > expiry) {
      await clearTokens();
      return null;
    }
    return {
      'access_token': accessToken,
      'refresh_token': refreshToken,
    };
  }
  static Future<void> clearTokens() async {
    await _storage.deleteAll();
  }
}

3.2 刷新逻辑实现

class AuthInterceptor extends Interceptor {
  final TokenLock _tokenLock = TokenLock();
  final Dio _authDio = Dio(); // 专用Dio实例用于刷新请求
  @override
  void onError(DioError err, ErrorInterceptorHandler handler) async {
    if (err.response?.statusCode == 401) {
      try {
        await _tokenLock.acquire();
        final tokens = await TokenManager.getTokens();
        if (tokens == null) {
          _tokenLock.release();
          handler.reject(err);
          return;
        }
        final response = await _authDio.post(
          'https://auth-server.com/refresh',
          data: {'refresh_token': tokens['refresh_token']},
        );
        final newTokens = response.data as Map<String, dynamic>;
        await TokenManager.saveTokens(
          accessToken: newTokens['access_token'],
          refreshToken: newTokens['refresh_token'],
          expiresIn: newTokens['expires_in'],
        );
        // 重试原请求
        final options = err.requestOptions;
        options.headers['Authorization'] = 'Bearer ${newTokens['access_token']}';
        final retryResponse = await _retryRequest(options);
        handler.resolve(retryResponse);
      } catch (e) {
        await TokenManager.clearTokens();
        handler.reject(DioError(
          requestOptions: err.requestOptions,
          error: e,
          type: DioErrorType.other,
        ));
      } finally {
        _tokenLock.release();
      }
    } else {
      handler.next(err);
    }
  }
  Future<Response> _retryRequest(RequestOptions options) async {
    final dio = options.extra['dio'] as Dio? ?? throw Exception('Dio instance not found');
    return dio.request(
      options.path,
      data: options.data,
      queryParameters: options.queryParameters,
      options: Options(
        method: options.method,
        headers: options.headers,
      ),
    );
  }
}

3.3 全局Dio配置

final dio = Dio(BaseOptions(
  baseUrl: 'https://api.example.com',
  connectTimeout: 5000,
  receiveTimeout: 3000,
));
dio.interceptors.add(AuthInterceptor());
// 在请求中附加Dio实例（用于重试）
Future<void> makeRequest() async {
  try {
    final response = await dio.get(
      '/data',
      options: Options(extra: {'dio': dio}),
    );
    print(response.data);
  } catch (e) {
    print('Request failed: $e');
  }
}

四、安全优化与最佳实践

4.1 安全增强措施

• 令牌轮换：每次刷新时生成新的Refresh Token，立即使旧Token失效。
• HTTPS强制：确保所有令牌传输通过HTTPS加密。
• CSRF防护：在刷新端点添加state参数验证请求来源。

4.2 性能优化建议

• 预取令牌：在应用启动时检查令牌有效期，提前刷新避免请求阻塞。
• 指数退避：刷新失败时采用指数退避算法重试（如1s、2s、4s）。
• 本地缓存：将令牌信息缓存到内存，减少存储I/O。

4.3 错误处理策略

enum AuthErrorType {
  invalidGrant,       // 无效的Refresh Token
  networkError,       // 网络问题
  serverError,        // 认证服务器错误
  unknown             // 其他错误
}
class AuthException implements Exception {
  final AuthErrorType type;
  final String message;
  AuthException(this.type, this.message);
  @override
  String toString() => 'AuthException($type): $message';
}

五、总结与展望

本文实现的Dio拦截器方案具有以下优势：

1. 非侵入式：通过拦截器自动处理令牌刷新，业务代码无需修改。
2. 线程安全：通过锁机制避免并发刷新问题。
3. 可扩展性：支持自定义错误处理和重试策略。

未来可探索的方向包括：

• 集成Flutter的riverpod或bloc进行状态管理
• 实现多账号支持
• 添加生物识别验证（如Face ID/Touch ID）保护Refresh Token

通过合理设计，OAuth票据刷新机制可以成为移动应用安全架构的核心组件，为业务提供稳定可靠的身份认证服务。