はじめに: このガイドで作るものと開発環境
このガイドでは、Kotlin と Spring Boot で EC サイトの注文 API を作ります。第 1 部で Kotlin の言語仕様をひととおり身につけ、第 2 部から Spring Boot を使って API を組み立てます。
この章では、作るものの全体像と章の並びを示したあと、開発環境とサンプルリポジトリを用意します。章の終わりには、第 1 部のコード例をすべて手元のコマンド 1 つで動かせる状態になります。
このガイドで作るもの
題材は EC サイトの注文システムです。扱う概念は 4 つあります。
- 注文 (
Order): 1 回の購入の依頼です。1 つ以上の注文明細を持ちます - 注文明細 (
OrderLine): 注文に含まれる 1 行です。どの商品を、いくつ、いくらで買うかを持ちます - 商品 (
Product): 注文できる品物の 1 種類です - 在庫 (
Inventory): 商品ごとに持つ、注文に引き当てられる数量です
4 つの関係を図にすると、次のようになります。
API が受け持つ仕事は、商品の一覧と詳細を返すこと、注文を受け付けて在庫を引き当てること、注文の一覧と詳細を返すことです。どれも JSON を返します。画面は作りません。
仕事の数は少なくても、本番で動かすと考えることが増えます。在庫が残り 1 個のときに 2 人が同時に注文したら、どちらに引き当てるのか。数量に負の数が届いたら、どこで止めるのか。他人の注文を見ようとするリクエストを、どう断るのか。第 2 部からの各章は、この注文 API を少しずつ育てながら、こうした問いに 1 つずつ答えていきます。
章の地図
ガイドは 5 部 29 章です。第 1 部だけは Spring Boot を使わず、Kotlin の言語そのものを扱います。
| 部 | 章 |
|---|---|
| 第 1 部 Kotlin 入門 | 01 はじめに / 02 Kotlin の基本 / 03 関数とラムダ / 04 クラスとオブジェクト / 05 コレクションとジェネリクス / 06 例外と失敗の表し方 |
| 第 2 部 Spring Boot の基礎 | 07 Spring Boot の骨格 / 08 テーブル設計とマイグレーション / 09 Spring Data JDBC で読み書きする / 10 ルーティングと最初のエンドポイント / 11 入力の検証 / 12 サービス層と DI / 13 レスポンスの形 / 14 一覧 API / 15 エラーレスポンス / 16 テスト |
| 第 3 部 認証と認可 | 17 認証 / 18 認可 / 19 フィルタ・レート制限・CORS |
| 第 4 部 整合性と非同期 | 20 トランザクションと並行性 / 21 イベント / 22 非同期処理 / 23 非同期処理を本番で動かす / 24 コルーチンで並行に呼ぶ / 25 キャッシュ |
| 第 5 部 運用 | 26 ファイルの保存と配信 / 27 定期処理 / 28 ログ・監視・デプロイ / 29 おわりに |
第 1 部の 5 つの章 (02〜06) は、後の章で使う言語機能を先にまとめて扱います。Spring Boot のコードは、クラス・注釈・ラムダ・null 安全を組み合わせて書くので、言語の側を先に固めておくと、第 2 部では Spring Boot の仕組みに集中できます。
開発環境を用意する
用意するものは JDK と IntelliJ IDEA の 2 つです。Gradle は入れなくてかまいません。Docker は第 2 部から使います。
JDK 25
このガイドは Java 25 を前提にします。Java 25 は 2025 年 9 月に一般提供が始まった長期サポート版で、Spring Boot 4.1 が対応する範囲 (Java 17 から 26) に入っています1。
JDK はいくつかの配布元から入手できます。迷ったら Eclipse Temurin を選んでください。入れ方は次のどれでもかまいません。
- 配布元のサイトからインストーラを取得する
- SDKMAN! を使う。
sdk list javaで 25 の識別子を確かめ、sdk install java <識別子>で入れる - IntelliJ IDEA の画面から入れる (プロジェクトを開いたときに JDK を選ぶ画面で、ダウンロードを選ぶ)
入れたら、ターミナルで版を確かめてください。
java -version
1 行目の引用符の中に版の番号が出ます。番号が 25 で始まっていれば準備は終わりです。
IntelliJ IDEA の画面から入れた JDK は、ターミナルの PATH に入らないので、java -version ではその JDK の版を確かめられません。その場合、ターミナルから Gradle Wrapper を動かすには、環境変数 JAVA_HOME にその JDK の場所を設定してください。IntelliJ IDEA の中から Gradle のタスクを動かすだけなら、この設定は要りません。
IntelliJ IDEA
Kotlin のコードは IntelliJ IDEA で書きます。Kotlin を開発している JetBrains の IDE で、補完と型の表示が Kotlin の型推論に沿って動きます。IntelliJ IDEA は 2025.3 から 1 つの製品になり、Java と Kotlin の開発に使う機能は無料の範囲で使えます2。
Gradle は入れなくてよい
サンプルリポジトリは Gradle Wrapper を同梱しています。リポジトリの直下にある gradlew を実行すると、リポジトリが指定した版の Gradle を自動で取得してから動きます。手元に Gradle を入れる必要はなく、誰が動かしても同じ版の Gradle でビルドされます。
Docker は第 2 部から
第 2 部では、データベースに PostgreSQL を使います。テストのたびに PostgreSQL をコンテナで立てるので、Docker が要ります。第 1 部のコード例は Docker が無くても動きます。
サンプルリポジトリを取得する
ガイドのコードは kotlin-spring-boot-order にあります。次のコマンドで取得してください。
git clone --branch api-06 https://github.com/rasshii/kotlin-spring-boot-order.git
cd kotlin-spring-boot-order
api-06 は tag の名前で、「第 6 章まで読んだ時点のコード」を指します。リポジトリの main は後の章の作業で先へ進むので、記事と食い違わないよう、記事からのリンクはすべて tag を指します。第 2 部からは、アプリが変わる章ごとに tag を付けていきます。
tag を指定して取得すると、git が英語のメッセージをいくつか出します。warning: refs/tags/api-06 ... is not a commit! は、説明文の付いた tag を指定したときに出る警告で、取得には影響しません。You are in 'detached HEAD' state. から始まる案内は、ブランチではなく tag の時点のコードを取り出したことを知らせるものです。コードを読んで動かすだけなら、そのまま進めてかまいません。変更をコミットして残したいときは、案内にあるとおり git switch -c <ブランチ名> でブランチを作ってからコミットしてください。
リポジトリには 2 つのサブプロジェクトがあります。
| ディレクトリ | 中身 |
|---|---|
kotlin-basics/ | 第 1 部のコード例。Spring に依存しません |
app/ | Spring Boot のアプリケーション。第 2 部から作っていきます |
IntelliJ IDEA で開くときは、リポジトリのディレクトリをそのまま開いてください。直下の settings.gradle.kts を見て、Gradle のプロジェクトとして読み込みます。
第 1 部のコード例を動かす
第 1 部のコード例は、すべて kotlin-basics のテストとして置いてあります。テストはコード例を動かし、標準出力を記事に載せた実行結果と比べます。次のコマンドで、第 1 部のコード例をすべて動かせます。
./gradlew :kotlin-basics:test
Windows のコマンドプロンプトでは gradlew.bat :kotlin-basics:test と打ってください。初回は Gradle と依存ライブラリの取得に時間がかかります。最後に次の行が出れば、すべてのコード例が記事のとおりに動いています。
BUILD SUCCESSFUL
章ごとのコード例は、kotlin-basics/src/test/kotlin/basics/ch02/ のように章の番号のディレクトリにあります。記事に載せた実行結果は kotlin-basics/src/test/resources/snippets/ にあり、ファイル名がコード例の名前です。1 つの章だけを動かしたいときは、--tests でテストのクラスを絞り込みます。
./gradlew :kotlin-basics:test --tests 'basics.ch02.*'
Windows のコマンドプロンプトは単一引用符を引用符として扱わないので、gradlew.bat :kotlin-basics:test --tests basics.ch02.* と引用符を外して打ってください。
後で説明するコンパイルが通らない例は、章のディレクトリでなく kotlin-basics/src/test/compile-errors/ にあります。章を問わず basics.CompileErrorSnippetsTest がまとめて確かめるので、この絞り込みには入りません。
コード例の読み方
Kotlin のプログラムは main という名前の関数から動き始めます。最も小さいプログラムは次の形です。
fun main() {
println("こんにちは、Kotlin")
}
こんにちは、Kotlin
fun は関数を宣言するキーワードで、println は引数を標準出力に書いて改行する関数です。コード例の直後にある「実行結果」の枠は、そのコードを動かしたときに標準出力へ書かれた内容です。
第 1 部のコード例の多くは、main を省いて中身の文だけを載せています。
val product = "ノート"
val quantity = 3
println(product)
println(quantity * 2)
ノート
6
このような例は、main の波括弧の中に書けば動きます。IntelliJ IDEA で試すときは、.kt のファイルを作って fun main() { } の中に貼り付け、main の行の横に出る実行ボタンを押してください。
クラスや関数の宣言は、main の外 (ファイルの一番外側) に書きます。宣言を含む例の多くは、記事の側に fun main() まで載せます。宣言だけを載せて、それを使う文を次のコード例に分けることもあります。そのときは、宣言を main の外に、次のコード例の文を main の中に書いてください。
もう 1 つ、コンパイルが通らない例も載せます。Kotlin はコンパイルの段階で多くの誤りを止める言語なので、どんな書き方が止められるかを見ることにも意味があります。そうした例の直後には、実行結果の代わりに、コンパイラが出すエラーの要点を載せます。
まとめ
- このガイドは、EC サイトの注文 API (注文・注文明細・商品・在庫) を Kotlin と Spring Boot で作ります
- 第 1 部 (01〜06 章) は Kotlin の言語を扱い、Spring Boot は第 2 部から使います
- 用意するものは JDK 25 と IntelliJ IDEA です。Gradle は Gradle Wrapper が取得し、Docker は第 2 部から使います
- サンプルリポジトリは tag
api-06を取得し、./gradlew :kotlin-basics:testで第 1 部のコード例をすべて動かせます - 文だけのコード例は、
mainの中に書けば動きます
次に読む
次章 Kotlin の基本 では、変数と型から始めて、Kotlin の null 安全と、if や when を値として使う書き方を扱います。どれも以降の章のコードで毎回使うものです。
練習問題
サンプルリポジトリの第 3 章のコード例だけを動かすには、どのコマンドを打ちますか
解答例
./gradlew :kotlin-basics:test --tests 'basics.ch03.*'
:kotlin-basics:test が kotlin-basics のサブプロジェクトのテストを指し、--tests がテストのクラスを名前で絞り込みます。第 1 部のコード例は章ごとに basics.ch03 のような package に置いてあるので、package の名前で絞れば 1 つの章だけが動きます。Windows のコマンドプロンプトでは、引用符を外して gradlew.bat :kotlin-basics:test --tests basics.ch03.* と打ちます。
記事に載せた実行結果が、コード例を実際に動かした結果と一致していることは、どうやって確かめていますか
解答例
2 つの照合を組み合わせています。
1 つ目は、kotlin-basics のテストです。テストはコード例を動かして標準出力を受け取り、src/test/resources/snippets/ にある期待値のファイルと比べます。./gradlew :kotlin-basics:test が通れば、コードの出力と期待値のファイルが一致しています。
2 つ目は、記事とリポジトリの照合です。記事のコード例と実行結果を、リポジトリのテストのコードと期待値のファイルに 1 件ずつ突き合わせています。
テストだけでは、記事に別の値を書いても気づけません。照合だけでは、期待値のファイル自体が誤っていても気づけません。両方が通ってはじめて、記事の実行結果がコードの出力だと言えます。