FlutterやDartによるアプリケーション開発において、Web API（REST API）とのデータ送受信や設定ファイルの読み書きなど、ほぼすべての現場で扱われるデータ形式が「JSON」です。
Dartでは、標準ライブラリである dart:convert をインポートするだけで、手軽にJSONデータのエンコード（Dartオブジェクト ➔ JSON文字列）やデコード（JSON文字列 ➔ Dartオブジェクト）を行うことができます。
しかし、実際にコードを書く際には jsonEncode や jsonDecode という関数だけでなく、JsonCodec、JsonDecoder、JsonEncoder という3つのクラスが存在しており、それぞれの役割や使い分けに迷うケースも見受けられます。
本記事は、当ブログで解説しているDartのJSON関連クラスの個別記事を体系的にまとめた解説マップ（ピラーページ）です。各クラスの役割の違いや、実践で役立つ使い分けのポイントを分かりやすく整理しました。
JSON相互変換の基本構造と3クラスの役割関係
DartにおけるJSON操作は、大きく分けると「エンコード」と「デコード」の2方向の処理に分類されます。
- エンコード（シリアライズ）：Dartの
MapやListなどのオブジェクトを、送信や保存に適した「JSON文字列」へ変換する処理。 - デコード（デシリアライズ／パース）：ネットワークやファイルから受け取った「JSON文字列」を、プログラムで操作しやすいDartの
Map<String, dynamic>やList<dynamic>へ復元する処理。
dart:convert で提供されている主要な3クラスは、この処理方向に応じて以下のように役割分担されています。
| クラス名 | 担当処理 | 主な用途・特徴 |
|---|---|---|
| JsonCodec | 双方向（エンコード ＆ デコード） | 総合的な変換を担う統合クラス。標準の json 定数の実体。 |
| JsonDecoder | デコード（JSON文字列 ➔ オブジェクト） | 文字列のパースに特化。不正なJSONに対する例外処理（FormatException）など。 |
| JsonEncoder | エンコード（オブジェクト ➔ JSON文字列） | 文字列化に特化。見やすく整形するインデント機能（withIndent）など。 |
相互変換を担う統合クラス「JsonCodec」
JsonCodec は、エンコードとデコードの両方の機能を1つのクラスにまとめた総合コンバーターです。
普段よく使われる json.encode() や json.decode() という記述は、実は dart:convert で定義されているグローバルな JsonCodec インスタンス（const json = JsonCodec();）を呼び出しています。
クラス内部には独立したエンコーダーやデコーダーを取り出すプロパティも備わっており、全体の中心的な存在となっています。
- 個別詳細解説はこちら
➔ Dart JsonCodecクラスのdecoder()メソッドとencoder()メソッド
JSON文字列をDartオブジェクトに復元する「JsonDecoder」
APIから取得したレスポンス文字列などを、プログラム内で扱えるデータ構造へパースする役割を持つのが JsonDecoder です。
中心となる convert() メソッドにJSON文字列を渡すと、ルートの形状に応じて Map<String, dynamic> または List<dynamic> が返されます。
構文エラー（閉じ括弧の不足やカンマの余剰など）がある文字列を渡した場合は FormatException が発生するため、実際の開発現場では try-catch 構文と組み合わせて安全に処理するのが一般的です。
- 個別詳細解説はこちら
➔ Dart JsonDecoderクラスのコンストラクタとconvert()メソッド
DartオブジェクトをJSON文字列に変換する「JsonEncoder」
作成したデータモデルや連想配列を、サーバーへの送信やファイル保存のために文字列化するのが JsonEncoder です。
通常の convert() メソッドによる変換に加えて、開発時やデバッグで重宝するのが JsonEncoder.withIndent(' ') コンストラクタです。これを使用すると、改行やインデント（字下げ）を付与した読みやすいJSON（Pretty Print）を簡単に出力できるため、開発中のログ確認やデバッグ作業で役立ちます。
- 個別詳細解説はこちら
➔ Dart JsonEncoderクラスのコンストラクタとconvert()メソッド
現場でよく使われる使い分けのポイント
実際の開発現場では、シチュエーションに応じて以下のように使い分けるのが一般的です。
- 日常的なAPI通信やデータ処理
手軽に使えるトップレベル関数jsonDecode(str)やjsonEncode(obj)（内部でJsonCodecを利用）を使用するのが最もシンプルで推奨されます。 - ログ出力やデバッグ時の整形（Pretty Print）
JsonEncoder.withIndent(' ').convert(obj)を利用することで、階層構造が分かりやすいフォーマットで文字列化できます。 - ストリーム処理（大容量通信・ファイル読み込み）
ネットワークからの断片的なバイトデータを逐次パースしたい場合は、StreamパイプラインにJsonDecoderを挟み込んで段階的に変換する高度なアプローチも可能です。
まとめ
DartのJSON処理は、用途に応じて役割が明確に設計されています。
基本は jsonDecode / jsonEncode で事足りますが、それぞれの背後にある JsonCodec、JsonDecoder、JsonEncoder の役割を把握しておくことで、インデント整形や例外処理、ストリーム変換といった応用的な実装にも自信を持って対応できるようになります。
各クラスの詳しいコード例やメソッドの挙動については、上記の各詳細記事をご覧ください。
コメント