Dioとは：Flutter用HTTPクライアントの特徴

Dioとは？

DioはDart言語のための強力なHTTPクライアントライブラリであり、Flutterアプリケーションで最も広く使用されています。Dioは、インターセプター、グローバル設定、トランスフォーマー、FormData、ファイルアップロード、柔軟なタイムアウト管理をサポートする豊富なAPIを提供し、Flutterコミュニティでのネットワーキングの主要な選択肢となっています。

このライブラリは、2018年にWenda Wangによって、多くの最新機能（全リクエストの統一設定、インターセプター、自動シリアライゼーション）が欠けていた組み込みのdart:io HttpClientの代替として作成されました。2025年までに、Dioは人気でDartチームのhttpパッケージを追い越し、pub.devによるとFlutterエコシステムのHTTPクライアントの中で第1位になりました。

Dioは3つのアダプターをサポートしています：DartNativeAdapter（Android、iOS、Desktopでデフォルト）、BrowserAdapter（Web）、IOAdapter。アダプターはプラットフォームに応じて自動的に選択されます。DioはすべてのFlutterプラットフォーム（Android、iOS、Web、macOS、Windows、Linux）に統一されたインターフェースを提供します。

Dioの仕組み

Dioのアーキテクチャはハンドラーチェーンに基づいています。各リクエストは一連のインターセプターを通過し、リクエスト（InterceptorsWrapper.onRequest）、レスポンス（onResponse）を変更したり、エラー（onError）を処理したりできます。インターセプターの後、リクエストはトランスフォーマー（Transformer）に渡され、送信前にデータを変換します。

Dioインスタンスは、ベースURL、デフォルトヘッダー、タイムアウト、レスポンスタイプ（JSON、stream、plain）、クエリパラメーター、データ形式を含むBaseOptionsオブジェクトを通じて設定されます。これらの設定はすべてのリクエストに適用されますが、特定のリクエストで上書きできます。BaseOptionsはアプリケーション全体の単一設定ポイントを提供し、エンドポイントの変更やグローバルヘッダーの追加を簡素化します。

Dioの各リクエストはResponse<T>を返します。Tはトランスフォーマー処理後のデータ型です。デフォルトでは、DioはJSONレスポンスを自動的にMap<String, dynamic>に変換します。型付けされたレスポンスには、Dioをシリアライゼーションパッケージ（json_serializable、freezed、built_value）と一緒に使用します。Responseにはdata、headers、statusCode、requestOptions、追加データが含まれます。

Dioのグローバル設定

基本設定はDio(BaseOptions)を通じて作成されます。すべてのリクエストのbaseUrl、connectTimeoutとreceiveTimeout、content-typeとacceptヘッダー、queryParametersを設定できます。これらのパラメーターはすべてのリクエストに適用され、コードの重複を排除し、ネットワーク設定管理を集中化します。

Dioは2つのシリアライゼーションモードをサポートしています：デフォルトのJSON（responseType: ResponseType.json）とストリーミング（ResponseType.stream）。ストリームモードでは、Response.dataはチャンクで読み取り可能なResponseBodyを返します。これは、すべてをメモリに読み込むことが望ましくない大きなペイロードファイルに便利です。プレーンモードは、自動JSON解析なしで生の文字列を返します。

Dioインターセプター

インターセプターは、リクエスト、レスポンス、エラーをインターセプトおよび変更するためのDioの主要な仕組みです。これらはOkHttpのInterceptorやKtorのプラグインを完全に置き換えますが、Dart固有のAPIとFutureによる非同期サポートを備えています。インターセプターはDioのグローバル設定と個別のリクエストの両方に追加できます。

LogInterceptor

組み込みのLogInterceptorは各リクエストをログに記録します：メソッド、URL、ヘッダー、ボディ、実行時間。コンパクトモード（リクエストごとに1行）とフルモード（ボディ付きの完全情報）の2つのモードがあります。LogInterceptorは開発中に特に便利ですが、条件付きインポートまたはグローバルフラグを使用してリリースビルドでは無効にすることをお勧めします。

カスタムインターセプターはInterceptorsWrapperクラスを通じて作成されます。1つ、2つ、または3つすべてのメソッド（onRequest、onResponse、onError）をオーバーライドできます。Dioはインターセプターをインターセプターリストに追加された順序で厳密に実行します。インターセプターがhandler.next()を呼び出さない場合、チェーンは中断され、レスポンスまたはエラーはアプリケーションに届きません。

Dioでの認証には、AuthorizationヘッダーにBearerトークンを追加するインターセプターを使用します。サーバーが401を返した場合、onErrorのインターセプターはリフレッシュリクエストを通じてトークンの更新を試み、新しいトークンで元のリクエストを再試行します。このパターンはトークンリフレッシュインターセプターと呼ばれ、response?.statusCode == 401をチェックしてDioExceptionを通じて実装されます。

Dioはリトライロジックの組み込みサポートをdio_smart_retryパッケージまたはカスタムRetryInterceptorを通じて提供します。リトライはモバイルアプリケーションにとって重要です：接続が2〜3秒間失われた場合、DioはconnectionTimeoutまたはconnectionErrorタイプのDioExceptionをスローします。RetryInterceptorはこの例外をキャッチし、指数バックオフ（1秒、2秒、4秒）で最大3回リクエストを再試行し、不安定なネットワーク環境でのアプリケーションの信頼性を向上させます。

DartでのDioコード例

Dioを使用した基本的なGETリクエストを見てみましょう。BaseOptionsを使用してインスタンスを作成し、ベースURLとタイムアウトを設定します。リクエストはget()メソッドを通じて実行され、Map形式のデータを含むResponseを返します。

final dio = Dio(BaseOptions(
    baseUrl: 'https://api.github.com',
    connectTimeout: Duration(seconds: 15),
    receiveTimeout: Duration(seconds: 15),
    headers: {
        'Accept': 'application/vnd.github.v3+json',
    },
))

final response = await dio.get('/users/octocat')
print(response.data['ログイン'])

JSONボディ付きのPOSTリクエストでは、MapオブジェクトまたはカスタムDTOを渡します。DioはjsonEncodeを通じてMapを自動的にJSONにシリアライズします。型付けされたDTOには、queryParametersオプション、dataフィールド、またはカスタムTransformerを使用します。

final data = {
    'name': 'my-project',
    'description': 'Created via Dio',
    'private': false,
}

final response = await dio.post(
    '/user/repos',
    data: data,
    options: Options(
        contentType: ContentType.json.value,
    ),
)

print(response.data['ID'])

認証インターセプターの追加

カスタムインターセプターは各リクエストにBearerトークンを追加します。onRequestメソッドは送信前に起動し、ヘッダーを変更します。401レスポンスの場合、インターセプターはトークンをリフレッシュし、dio.fetch(requestOptions)メソッドを使用してリクエストを再試行できます。

class AuthInterceptor extends InterceptorsWrapper {
    final String token

    AuthInterceptor(this.token)

    @override
    void onRequest(
        RequestOptions options,
        RequestInterceptorHandler handler,
    ) {
        options.headers['Authorization'] = 'Bearer $token'
        handler.next(options)
    }
}

dio.interceptors.add(AuthInterceptor('ghp_abc123'))

Dioを使用したファイルのアップロードとダウンロード

DioはFormDataを通じてファイルのアップロードを簡素化します。ファイルを送信するには、File、Bytes、またはAssetBundleからMultipartFileを作成します。FormDataは自動的に正しいバウンダリーとエンコーディングでmultipart/form-dataヘッダーを設定します。DioはonSendProgressを通じてアップロード進捗をサポートします。

ファイルのダウンロードにはdownload()メソッドを使用し、データストリームを直接ファイルに保存します。DioはRangeヘッダーを通じて中断されたダウンロードの再開をサポートしており、これは大きなファイルに特に便利です。ダウンロード進捗はonReceiveProgressを通じて追跡され、UIに進捗バーを表示できます。

final formData = FormData.fromMap({
    'file': await MultipartFile.fromFile(
        '/path/to/photo.jpg',
        filename: 'photo.jpg',
    ),
    'description': 'Profile photo',
})

await dio.post(
    '/upload',
    data: formData,
    onSendProgress: (sent, total) {
        final progress = sent / total * 100
        print('アップロード: $progress%')
    },
)

// ファイルのダウンロード
await dio.download(
    'https://example.com/file.zip',
    '/storage/emulated/0/Download/file.zip',
    onReceiveProgress: (received, total) {
        print('ダウンロード: ${received / total * 100}%')
    },
)

Dio使用時のよくある間違い

誤ったエラー処理が最も一般的な問題です。Dioはネットワーク不可、タイムアウト、HTTPエラー4xx/5xxなどの問題に対してDioException（旧DioError）をスローします。多くの開発者は汎用のExceptionのみをキャッチし、エラータイプやそれを特異的に処理する能力に関する情報を失っています。障害の原因を特定するにはDioException.typeを使用してください。

CancelTokenの無視はリクエストリークにつながります。ユーザーがリクエスト実行中に画面を離れると、Dioはリソースを浪費し、破棄されたStateの更新を試みる可能性があります。各リクエストに対して常にCancelTokenを作成し、dispose()でキャンセルしてください。CancelTokenはcancelタイプのDioExceptionを生成し、適切に処理する必要があります。

一時的な障害に対するリトライロジックの欠如。モバイルデバイスでは、ネットワークが短時間利用できなくなることがよくあります。タイムアウトまたは503/502レスポンス時に自動リクエストリトライを行うインターセプターを実装してください。dio_smart_retryパッケージのRetryInterceptorを使用するか、試行間に指数バックオフを備えたカスタムインターセプターを作成してください。