【Haskell学習｜実務向け】実務で役立つ！`aeson-better-errors`でJSONパースエラーを劇的に改善する

1. 導入: なぜ`aeson-better-errors`が実務で重要なのか

関数型プログラミングの世界でJSONデータを扱う際、HaskellではAesonがデファクトスタンダードとして広く使われています。しかし、実務で外部APIからのレスポンスや複雑な設定ファイルなど、大規模なJSONデータを扱うようになると、標準のAesonが吐き出すエラーメッセージに悩まされることが少なくありません。

例えば、「Error in $: Aeson.Types.Internal.ObjectExpected」のような簡潔すぎるメッセージでは、JSON構造のどこで、何が間違っているのかを特定するのに多大な労力と時間を要します。特にネストが深く、フィールド数が多いJSONの場合、この問題は深刻です。

ここで登場するのが、本日ご紹介する`aeson-better-errors`ライブラリです。このライブラリは、標準Aesonの`FromJSON`インスタンスを記述する際に、より詳細なパス情報付きのエラーメッセージを提供することで、JSONパースエラーのデバッグ体験を劇的に改善してくれます。実務における開発効率向上、そして何よりも開発者の精神衛生のために、このライブラリはまさに「神ライブラリ」と呼べるでしょう。

2. 基礎知識: 標準Aesonと`aeson-better-errors`の違い

まず、標準AesonでのJSONパースの基本的な流れを振り返りましょう。
Aesonでは、JSONデータに対応するHaskellのデータ型を作成し、その型に`FromJSON`型クラスのインスタンスを定義します。このインスタンスの`parseJSON`メソッド内で、JSONの`Value`型から目的のHaskellデータ型への変換ロジックを記述します。エラーが発生した場合、`Parser`モナドの`fail`関数を使ってエラーを報告しますが、このときのメッセージは非常に限定的です。

一方、`aeson-better-errors`は、独自の`Decoder`モナドを提供します。この`Decoder`モナドは`MonadError`のインスタンスであり、JSON構造を辿るための豊富なコンビネータ群（`field`, `key`, `index`など）を持っています。これらのコンビネータを使うことで、データ型がJSONのどのパスにどのように対応しているかを明示的に記述でき、もしパースに失敗した場合には、そのパス情報をエラーメッセージに含めて報告できるようになります。

簡単に言えば、標準Aesonが「ここでエラーが起きた」という結果だけを伝えるのに対し、`aeson-better-errors`は「JSONのこのパスで、このフィールドが、この型として期待されたのに、実際はこうだった」という詳細な状況を教えてくれるのです。

3. 実装/解決策: `aeson-better-errors`を使った`FromJSON`の定義

`aeson-better-errors`では、標準Aesonの`parseJSON`の代わりに、`Decoder`モナドを使ってデコードロジックを記述します。
主な手順は以下の通りです。

1. `Data.Aeson.BetterErrors`のインポート: まず、必要なモジュールをインポートします。
2. `FromJSON`インスタンスの定義: 目的のデータ型に`Data.Aeson.BetterErrors.FromJSON`インスタンスを定義します。この際、`fromJSON`メソッド内で`Decoder`モナドのコンビネータを使ってデコードロジックを記述します。
3. `object`デコーダ: JSONオブジェクトをデコードする場合、`object`コンビネータを使います。第一引数には、エラーメッセージに表示されるオブジェクトの名前を渡します。
4. フィールドへのアクセス: `field`コンビネータを使って、オブジェクト内の特定のフィールドにアクセスします。`field`の第一引数はフィールド名、第二引数はそのフィールドの値をデコードするデコーダです。
5. プリミティブデコーダ: `text`, `int`, `double`, `bool`などの関数を使って、JSONのプリミティブ型をHaskellの対応する型にデコードします。
6. ネストされた型のデコード: ネストされたJSONオブジェクトや配列も、再帰的に`fromJSON`デコーダ（または対応する`array`, `vector`デコーダ）を呼び出すことでデコードできます。

最終的に、`Decoder`モナドの計算結果は`decodeM`関数（または`decode`関数）を使って実行し、`Either ParseError a`（または`Maybe a`）として結果を受け取ります。

4. サンプルプログラム: 詳細なエラーメッセージの確認

以下のHaskellコードでは、ユーザー情報と注文品目を内包する`Order`データ型を定義し、それを`aeson-better-errors`を使ってJSONからデコードする方法を示します。意図的にJSONに誤った型を混入させ、標準Aesonと`aeson-better-errors`でのエラーメッセージの違いを比較します。

{-# LANGUAGE OverloadedStrings #-}
{-# LANGUAGE DeriveGeneric #-} — GHC.Genericsを使ってFromJSONを自動導出するために必要

module AesonBetterErrorsExample where

import Control.Applicative ((<|>)) — Alternativeインスタンスの演算子
import Data.Aeson (Value)
import Data.Text (Text)
import Data.Vector (Vector)
import qualified Data.Vector as V
import qualified Data.Aeson as A
import qualified Data.Aeson.BetterErrors as ABE
import qualified Data.ByteString.Lazy.Char8 as BL
import qualified Data.HashMap.Strict as HM
import GHC.Generics (Generic) — Genericインスタンスを導出するために必要

— ユーザー情報を表すデータ型
data User = User
{ userName :: Text
, userId :: Int
, userEmail :: Text
} deriving (Show, Generic) — Genericを導出して、標準AesonのFromJSONを簡単に定義できるようにする

— 注文品目を表すデータ型
data Item = Item
{ itemName :: Text
, itemPrice :: Double
} deriving (Show, Generic)

— 注文全体を表すデータ型
data Order = Order
{ orderId :: Text
, orderUser :: User
, orderItems :: [Item]
} deriving (Show, Generic)

— 標準AesonのFromJSONインスタンス (比較用)
— Genericを導出しているので、以下のように簡単に定義できます
instance A.FromJSON User
instance A.FromJSON Item
instance A.FromJSON Order

— aeson-better-errorsのFromJSONインスタンス
— Decoderモナドを使って、詳細なパースロジックを記述します
instance ABE.FromJSON User where
fromJSON = ABE.object “User object” $ do — オブジェクトのデコードを開始。エラー時に”User object”というラベルが付く
name <- ABE.field "name" ABE.text -- "name"フィールドをText型としてデコード id' <- ABE.field "id" ABE.int -- "id"フィールドをInt型としてデコード email <- ABE.field "email" ABE.text -- "email"フィールドをText型としてデコード pure $ User name id' email -- デコードした値でUser型を構築 instance ABE.FromJSON Item where fromJSON = ABE.object "Item object" $ do -- オブジェクトのデコードを開始 name <- ABE.field "name" ABE.text price <- ABE.field "price" ABE.double -- "price"フィールドをDouble型としてデコード pure $ Item name price instance ABE.FromJSON Order where fromJSON = ABE.object "Order object" $ do -- オブジェクトのデコードを開始 orderId' <- ABE.field "order_id" ABE.text orderUser' <- ABE.field "user_info" ABE.fromJSON -- "user_info"フィールドをUser型として再帰的にデコード orderItems' <- ABE.field "items" (ABE.array "items list" (ABE.vector ABE.fromJSON)) >>= \v -> pure $ V.toList v — “items”フィールドをItem型の配列としてデコードし、Listに変換
pure $ Order orderId’ orderUser’ orderItems’

— 意図的にエラーを起こすJSON文字列
— 1. user_info.id が Int ではなく String (“one”) になっている
— 2. items[1].price が Double ではなく String (“fifteen”) になっている
invalidJson :: BL.ByteString
invalidJson = BL.pack $ unlines
[ “{”
, ” \”order_id\”: \”ORD-2023-001\”,”
, ” \”user_info\”: {”
, ” \”name\”: \”Alice\”,”
, ” \”id\”: \”one\”,” — ★ここがエラー：Intが期待されるがString
, ” \”email\”: \”alice@example.com\””
, ” },”
, ” \”items\”: [”
, ” {”
, ” \”name\”: \”Laptop\”,”
, ” \”price\”: 1200.00″
, ” },”
, ” {”
, ” \”name\”: \”Mouse\”,”
, ” \”price\”: \”fifteen\”” — ★ここがエラー：Doubleが期待されるがString
, ” }”
, ” ]”
, “}”
]

— 健全なJSON文字列
validJson :: BL.ByteString
validJson = BL.pack $ unlines
[ “{”
, ” \”order_id\”: \”ORD-2023-001\”,”
, ” \”user_info\”: {”
, ” \”name\”: \”Alice\”,”
, ” \”id\”: 123,”
, ” \”email\”: \”alice@example.com\””
, ” },”
, ” \”items\”: [”
, ” {”
, ” \”name\”: \”Laptop\”,”
, ” \”price\”: 1200.00″
, ” },”
, ” {”
, ” \”name\”: \”Mouse\”,”
, ” \”price\”: 15.00″
, ” }”
, ” ]”
, “}”
]

— 実行例 (GHCiで実行してください)
— ghci AesonBetterErrorsExample.hs
—
— — 標準Aesonでのデコード
— A.decode invalidJson :: Maybe Order
— — 結果: Nothing
— — エラーメッセージは出ませんが、デコードに失敗したことがわかります。
— — 実際にはdecodeEither’などを使い、エラーメッセージを確認します。
— A.eitherDecode’ invalidJson :: Either String Order
— — 結果: Left “Error in $.user_info.id: expected Int, encountered String”
— — 標準Aesonでもパスは教えてくれますが、より詳細な情報やカスタマイズ性はaeson-better-errorsが優れます。
—
— — aeson-better-errorsでのデコード
— ABE.decodeM ABE.fromJSON invalidJson :: Either ABE.ParseError Order
— — 結果:
— — Left (ParseError
— — (ErrorAtKey “user_info”
— — (ErrorAtKey “id”
— — (ErrorCustom “Expected a JSON number, got: String”))))
— —
— — ABE.decodeM ABE.fromJSON validJson :: Either ABE.ParseError Order
— — 結果: Right (Order {orderId = “ORD-2023-001”, …})
— —
— — ※上記のエラー出力は、最初のエラー（user_info.id）で停止しています。
— — もし複数のエラーを一度に収集したい場合は、Validationモナドのようなアプローチを検討する必要があります。
— — aeson-better-errorsはデフォルトでは最初のエラーを報告します。
—
— — 別のエラーパターン: items[1].price のエラーを確認
— — 上記のinvalidJsonでは、user_info.idが先にエラーになるため、itemsのエラーは報告されません。
— — user_info.idを修正した上で、items[1].priceのエラーを確認します。
— let jsonWithItemError = BL.pack $ unlines
— [ “{”
— , ” \”order_id\”: \”ORD-2023-001\”,”
— , ” \”user_info\”: {”
— , ” \”name\”: \”Alice\”,”
— , ” \”id\”: 123,”
— , ” \”email\”: \”alice@example.com\””
— , ” },”
— , ” \”items\”: [”
— , ” {”
— , ” \”name\”: \”Laptop\”,”
— , ” \”price\”: 1200.00″
— , ” },”
— , ” {”
— , ” \”name\”: \”Mouse\”,”
— , ” \”price\”: \”fifteen\”” — ★ここがエラー
— , ” }”
— , ” ]”
— , “}”
— ]
— ABE.decodeM ABE.fromJSON jsonWithItemError :: Either ABE.ParseError Order
— — 結果:
— — Left (ParseError
— — (ErrorAtKey “items”
— — (ErrorAtIndex 1
— — (ErrorAtKey “price”