先生と生徒の会話形式で理解しよう

生徒

「Play Frameworkで、最近よく聞くJSONを使ったデータのやり取りってどうやるんですか？」

先生

「Webアプリケーション開発では欠かせない技術ですね。コントローラでJSONを受け取って、加工してJSONで返す、という流れが基本になります。」

生徒

「Javaだとデータ型が厳しいから、難しそうなイメージがあります……。」

先生

「安心してください。Play Frameworkにはライブラリが標準で組み込まれているので、驚くほどスマートに書けますよ。具体的な方法を一緒に見ていきましょう！」

1. JSONの重要性とWeb開発での役割

現代のWebシステムやモバイルアプリの開発において、JSON（JavaScript Object Notation）はデータをやり取りするための標準的なフォーマットです。昔はXMLという形式もよく使われていましたが、現在ではその軽量さと人間が見た時の分かりやすさから、JSONが主流となっています。

Play Frameworkで開発を行う際、フロントエンド（JavaScriptやスマートフォンアプリ）から送られてくるリクエストはJSONであることが多く、バックエンドであるPlay側もその結果をJSONで返却するのが一般的です。これを「Web API」と呼びます。コントローラはこの「データの橋渡し」をする非常に重要な役割を担っています。

2. コントローラでJSONレスポンスを返却する基本

まずは、Play Frameworkのコントローラから最もシンプルにJSONを返却する方法を学びましょう。Playでは、play.libs.Jsonという便利なユーティリティクラスが用意されており、これを使うことでJavaのオブジェクトを簡単にJSON形式に変換できます。

例えば、単純なメッセージをJSONで返したい場合は、Json.newObject()を使ってデータを作成します。これは「キー」と「値」のペアを持ったデータ構造（オブジェクト）を作成するイメージです。


package controllers;

import play.mvc.*;
import play.libs.Json;
import com.fasterxml.jackson.databind.node.ObjectNode;

public class JsonController extends Controller {

    public Result getHello() {
        // JSONオブジェクトを作成
        ObjectNode result = Json.newObject();
        result.put("message", "こんにちは、Play Frameworkの世界へ！");
        result.put("status", "success");

        // ok()メソッドでHTTP 200 OKレスポンスを返し、中身をJSONとして送信
        return ok(result);
    }
}

このコードを実行すると、ブラウザやアプリには以下のようなデータが届きます。


{"message":"こんにちは、Play Frameworkの世界へ！","status":"success"}

このように、Javaのコード上でデータを組み立てるだけで、Playが自動的に「Content-Type: application/json」というヘッダーを付けて、適切な形式で送り出してくれるのです。

3. クライアントから送信されたJSONリクエストを受け取る

次に、クライアント側から送られてくるJSONデータを読み取る方法を解説します。Playのコントローラでは、request().body().asJson()というメソッドを呼び出すだけで、送信されたデータをJsonNodeという形式で取得できます。

この際に注意しなければならないのは、相手が必ずしもJSONを送ってくるとは限らないという点です。そのため、取得したデータが「null」ではないかを確認する処理がプログラミングの安全性を高めるために必須となります。


public Result postUser() {
    // リクエストのボディをJSONとして取得
    com.fasterxml.jackson.databind.JsonNode json = request().body().asJson();

    if (json == null) {
        // JSONデータではない場合、400 Bad Requestを返す
        return badRequest("JSONデータが見つかりません");
    }

    // JSONから値を取り出す
    String name = json.findPath("name").asText();
    int age = json.findPath("age").asInt();

    // 取得したデータを使ってレスポンスを作成
    ObjectNode response = Json.newObject();
    response.put("received_name", name);
    response.put("received_age", age);
    response.put("message", "ユーザー登録を受け付けました");

    return ok(response);
}

このように、受信したJSONから特定の項目（nameやageなど）を抜き出して、それを元に新しいJSONを作るのがWeb API開発の基本サイクルです。

4. JacksonライブラリとJsonNodeの操作

Play Frameworkの内部では、Jacksonという非常に有名なJava向けのJSON処理ライブラリが動いています。先ほど出てきたJsonNodeやObjectNodeはすべてJacksonが提供しているクラスです。

初心者がよく使うメソッドをいくつか整理しておきましょう。

findPath("キー名"): 指定したキーの場所を探します。キーが存在しなくてもエラーにならず、空のノードを返してくれるので安全です。
get("キー名"): 指定したキーの値を取得します。キーがない場合はnullを返します。
asText(): ノードの値を文字列として取得します。
asInt(): ノードの値を数値として取得します。

これらのメソッドを組み合わせることで、複雑な階層構造を持ったJSONデータでも、自由自在に解析することが可能になります。パソコンでのファイル操作と同じように、フォルダ（階層）を辿って目的のデータを見つける感覚に近いです。

5. Javaオブジェクトを直接JSONに変換する方法

データ量が増えてくると、ObjectNodeに一つずつputしていくのは大変です。そこで便利なのが、Javaの「POJO（Plain Old Java Object）」と呼ばれる普通のクラスをそのままJSONに変換する方法です。PlayのJson.toJson()メソッドを使えば、クラスのフィールド名をキーにしたJSONが一瞬で作成されます。


// シンプルなデータ用クラス（POJO）
public class User {
    public String name;
    public String email;
    
    public User(String name, String email) {
        this.name = name;
        this.email = email;
    }
}

// コントローラ内での使用例
public Result getUser() {
    User user = new User("田中太郎", "tanaka@example.com");
    // オブジェクトを直接JSONノードに変換
    return ok(Json.toJson(user));
}

この手法を使うと、データベースから取得したエンティティやリストなどを、ループ処理で一つずつ加工することなく、そのままレスポンスとして返却できるため、開発スピードが飛躍的に向上します。大規模なプロジェクトになればなるほど、この「自動変換」の恩恵を受けることになります。

6. エラーハンドリングと適切なHTTPステータスコード

JSONのやり取りにおいて、正常な値を返すことと同じくらい大切なのが「エラー時の伝え方」です。Play Frameworkのコントローラでは、単にエラーメッセージを返すだけでなく、HTTPステータスコードを適切に使い分けることが推奨されます。

たとえば、送られてきたJSONの形式が正しくない場合はbadRequest()（400番）、認証が必要な場所にアクセスしようとした場合はunauthorized()（401番）、指定されたデータが存在しない場合はnotFound()（404番）といった具合です。

これらのメソッドにJSONを渡すことも可能です。エラー内容をJSONで返すことで、呼び出し側のフロントエンド（JavaScriptなど）は「なぜエラーになったのか」をプログラムで解析し、ユーザーに適切なメッセージを表示することができるようになります。親切なシステム開発には、このエラーメッセージのJSON化が欠かせません。

7. ルーティングファイルでの設定確認

コントローラでJSONを扱うメソッドを作成したら、忘れずにconf/routesファイルに登録しましょう。JSONを扱うからといって特殊な設定が必要なわけではありませんが、POSTリクエスト（データの送信）を受け取る場合は、動詞をPOSTにする必要があります。


# GETリクエストでJSONを受け取る
GET     /api/hello                  controllers.JsonController.getHello()

# POSTリクエストでJSONを送信する
POST    /api/user                   controllers.JsonController.postUser()

このように設定することで、外部のアプリケーションが/api/userというURLに対してJSONデータを投げることができるようになります。ルーティングは「どの道を通ってどの処理に行くか」を決める地図のようなものです。

8. JSON操作の応用：リストや配列の返却

実際の開発では、一つのデータだけでなく、データのリスト（配列）を返したい場面が多々あります。Play Frameworkでは、JavaのListコレクションをそのままJson.toJson()に渡すだけで、JSONの配列形式（[]で囲まれた形式）に変換してくれます。


import java.util.ArrayList;
import java.util.List;

public Result getUsers() {
    List<User> userList = new ArrayList<>();
    userList.add(new User("佐藤", "sato@example.com"));
    userList.add(new User("鈴木", "suzuki@example.com"));

    // ListをそのままJSON配列として返却
    return ok(Json.toJson(userList));
}

これだけで、複数のユーザー情報を一括でクライアントに届けることができます。非常にシンプルですね。