サーバーサイドKotlinでJSONレスポンスを返してみます

こんにちは、さるまりんです。

久しぶりのサーバーサイドKotlinです。今回はクライアントへのレスポンス返却。
Spring Bootでは@RestControllerを使うだけで、関数の返り値が自動でJSONになります。Kotlinならdata classでレスポンス定義もスッキリ。まずは最小構成を動かしてみます。

KotlinでJSONを返す基本

HelloController.kt

import org.springframework.web.bind.annotation.GetMapping
import org.springframework.web.bind.annotation.RequestMapping
import org.springframework.web.bind.annotation.RestController

@RestController
@RequestMapping("/api")
class HelloController {

    @GetMapping("/hello")
    fun hello(): Greeting {
        return Greeting(name = "さるまりん", message = "こんにちは！サーバーサイドKotlinへようこそ！")
    }
}

data class Greeting(
val name: String,
val message: String
)

ポイント

@RestControllerを付けるとメソッドの戻り値がそのままHTTPレスポンス（= JSON）に。
Kotlinのdata classはシリアライズと相性がよく、フィールドの宣言がそのままJSONのキーになります。

実行して確認（curl）

curlでAPIを呼び出して確認してみます。

ターミナル

$ curl http://localhost:8080/api/hello
{"name":"さるまりん","message":"こんにちは！サーバーサイドKotlinへようこそ！"}

null安全なレスポンス設計（Nullable）

APIでは「値が無い」ケースの扱いが重要です。
値がある前提で処理してしまうと、実はnullだったときにエラーになり、思わぬ不具合につながることがあります。
Kotlinは型でnull可否を表現できます。

Nullableフィールド例

data class Greeting(
    val name: String?,   // null を許す
    val message: String  // 必須
)

メモ

String?は「nullを許す」型。クライアントが未設定でも安全に表現可能です。
必須/任意の設計が型で伝わるので、レビューと保守が楽になります。

ステータスコードやヘッダーを返す（ResponseEntity）

もう一歩踏み込んで、HTTPステータスやヘッダーをコントロールしたい場合はResponseEntityを使います。

HelloController.kt（エラーレスポンス）


import org.springframework.http.HttpStatus
import org.springframework.http.ResponseEntity
import org.springframework.web.bind.annotation.GetMapping
import org.springframework.web.bind.annotation.RestController

@RestController
class ErrorController {

    @GetMapping("/api/error")
    fun error(): ResponseEntity {
        val body = Greeting(name = null, message = "エラーが発生しました")
        return ResponseEntity.status(HttpStatus.BAD_REQUEST).body(body)
    }

}

ターミナル

$ curl -i http://localhost:8080/api/error
HTTP/1.1 400 
Content-Type: application/json
Content-Length: 58

{"name":null,"message":"エラーが発生しました"}

Bad Request 400が返っていますね。

ちょい足し：JSONの見やすい返し方（整形）

APIを呼び出してレスポンスを取得した時、JSONが一行で見にくいとなることがあります。
そんな時はcurl側でjqを使って見やすくします。

ターミナル（jqで整形）

$ curl -s http://localhost:8080/api/hello | jq .
{
  "name": "さるまりん",
  "message": "こんにちは！サーバーサイドKotlinへようこそ！"
}

さっきに比べてこちらの方が見やすいですよね。
jqは整形以外にもフィルターや検索もできるので、慣れておくとデバッグがぐっと楽になります。

まとめ

@RestController + data classで最小のJSONレスポンスがすぐ作れます。
Kotlinのnull安全で、必須/任意のフィールド設計が分かりやすい
ResponseEntityでHTTPステータスやヘッダーも柔軟に制御可能

次はルーティングとパラメータの受け渡しを整理していきます。
今後もDBアクセスやクライアント連携など、**サーバーサイドKotlinでできること**を少しずつ広げていく予定です。

読んでくださってありがとうございました。
それではまた！