Skip to content

Express から Ktor への移行

このガイドでは、アプリケーションの生成や最初のアプリケーションの作成から、アプリケーション機能を拡張するためのミドルウェアの作成まで、基本的なシナリオにおいて Express アプリケーションを Ktor へ移行する方法を見ていきます。

アプリケーションの生成

Express

express-generator ツールを使用して、新しい Express アプリケーションを生成できます。

shell
npx express-generator
Ktor

Ktor は、アプリケーションのスケルトンを生成するために以下の方法を提供しています。

  • Ktor Project Generator — Web ベースのジェネレーターを使用します。

  • Ktor CLI ツール — ktor new コマンドを使用して、コマンドラインインターフェースから Ktor プロジェクトを生成します。

    shell
    ktor new ktor-sample
  • Yeoman ジェネレーター — 対話形式でプロジェクト設定を構成し、必要なプラグインを選択します。

    shell
    yo ktor
  • IntelliJ IDEA Ultimate — 組み込みの Ktor プロジェクトウィザードを使用します。

詳細な手順については、チュートリアル 新しい Ktor プロジェクトの作成、オープン、および実行Ktor を使用したサーバーアプリケーションの開き方、実行方法、テスト方法について学びます。 を参照してください。

Hello world

このセクションでは、GET リクエストを受け付け、事前に定義されたプレーンテキストで応答する最もシンプルなサーバーアプリケーションを作成する方法を見ていきます。

Express

以下の例は、サーバーを起動し、ポート 3000 で接続をリッスンする Express アプリケーションを示しています。

javascript
const express = require('express')
const app = express()
const port = 3000

app.get('/', (req, res) => {
    res.send('Hello World!')
})

app.listen(port, () => {
    console.log(`Responding at http://0.0.0.0:${port}/`)
})

完全な例については、1_hello プロジェクトを参照してください。

Ktor

Ktor では、embeddedServer 関数を使用してコード内でサーバーパラメータを設定し、アプリケーションを迅速に実行できます。

kotlin
import io.ktor.server.engine.*
import io.ktor.server.netty.*
import io.ktor.server.application.*
import io.ktor.server.response.*
import io.ktor.server.routing.*

fun main() {
    embeddedServer(Netty, port = 8080, host = "0.0.0.0") {
        routing {
            get("/") {
                call.respondText("Hello World!")
            }
        }
    }.start(wait = true)
}

完全な例については、1_hello プロジェクトを参照してください。

HOCON または YAML 形式を使用する外部構成ファイルでサーバー設定を指定することもできます。

上記の Express アプリケーションは、次のような Date、X-Powered-By、および ETag レスポンスヘッダーを追加することに注意してください。

Date: Fri, 05 Aug 2022 06:30:48 GMT
X-Powered-By: Express
ETag: W/"c-Lve95gjOVATpfV8EL5X4nxwjKHE"

Ktor で各レスポンスにデフォルトの Server および Date ヘッダーを追加するには、DefaultHeaders必要な依存関係: io.ktor:ktor-server-default-headers プラグインをインストールする必要があります。Etag レスポンスヘッダーの構成には、ConditionalHeaders必要な依存関係: io.ktor:ktor-server-conditional-headers プラグインを使用できます。

静的コンテンツの配信

このセクションでは、Express と Ktor で画像、CSS ファイル、JavaScript ファイルなどの静的ファイルを配信する方法を見ていきます。メインの index.html ページとリンクされた一連のアセットを含む public フォルダーがあると仮定します。

public
├── index.html
├── ktor_logo.png
├── css
│   └──styles.css
└── js
    └── script.js
Express

Express では、フォルダー名を express.static 関数に渡します。

javascript
const express = require('express')
const app = express()
const port = 3000

app.use(express.static('public'))

app.listen(port, () => {
    console.log(`Responding at http://0.0.0.0:${port}/`)
})

完全な例については、2_static プロジェクトを参照してください。

Ktor

Ktor では、staticFiles() 関数を使用して、/ パスに対して行われたリクエストを実際の public 物理フォルダーにマッピングします。この関数により、public フォルダーからすべてのファイルを再帰的に配信できます。

kotlin
import io.ktor.server.application.*
import io.ktor.server.http.content.*
import io.ktor.server.routing.*
import java.io.*

fun main(args: Array<String>): Unit =
    io.ktor.server.netty.EngineMain.main(args)

fun Application.module() {
    routing {
        staticFiles("", File("public"), "index.html")
    }
}

完全な例については、2_static プロジェクトを参照してください。

静的コンテンツを配信する際、Express は次のような複数のレスポンスヘッダーを追加します。

Accept-Ranges: bytes
Cache-Control: public, max-age=0
ETag: W/"181-1823feafeb1"
Last-Modified: Wed, 27 Jul 2022 13:49:01 GMT

Ktor でこれらのヘッダーを管理するには、次のプラグインをインストールする必要があります。

  • Accept-Ranges : PartialContent必要な依存関係: io.ktor:ktor-server-partial-content

  • Cache-Control : CachingHeaders必要な依存関係: io.ktor:ktor-server-caching-headers

  • ETag および Last-Modified : ConditionalHeaders必要な依存関係: io.ktor:ktor-server-conditional-headers

ルーティング

Routingルーティングは、サーバーアプリケーションにおいて着信リクエストを処理するためのコアとなるプラグインです。 を使用すると、特定の HTTP リクエストメソッド(GET、POST など)とパスによって定義される特定のエンドポイントに対して行われた受信リクエストを処理できます。以下の例は、/ パスに対して行われた GET および POST リクエストを処理する方法を示しています。

Express
javascript
app.get('/', (req, res) => {
    res.send('GET request to the homepage')
})

app.post('/', (req, res) => {
    res.send('POST request to the homepage')
})

完全な例については、3_router プロジェクトを参照してください。

Ktor
kotlin
routing {
    get("/") {
        call.respondText("GET request to the homepage")
    }
    post("/") {
        call.respondText("POST request to the homepage")
    }
}

POST、PUT、または PATCH リクエストのリクエスト本文を受信する方法については、リクエストの受信を参照してください。

完全な例については、3_router プロジェクトを参照してください。

次の例は、ルートハンドラーをパスごとにグループ化する方法を示しています。

Express

Express では、app.route() を使用してルートパスに対してチェーン可能なルートハンドラーを作成できます。

javascript
app.route('/book')
    .get((req, res) => {
        res.send('Get a random book')
    })
    .post((req, res) => {
        res.send('Add a book')
    })
    .put((req, res) => {
        res.send('Update the book')
    })

完全な例については、3_router プロジェクトを参照してください。

Ktor

Ktor は route 関数を提供しており、パスを定義した上で、そのパスに対する動詞(HTTP メソッド)をネストされた関数として配置します。

kotlin
routing {
    route("book") {
        get {
            call.respondText("Get a random book")
        }
        post {
            call.respondText("Add a book")
        }
        put {
            call.respondText("Update the book")
        }
    }
}

完全な例については、3_router プロジェクトを参照してください。

どちらのフレームワークでも、関連するルートを単一のファイルにグループ化できます。

Express

Express は、マウント可能なルートハンドラーを作成するために express.Router クラスを提供しています。アプリケーションのディレクトリに birds.js ルーターファイルがあるとします。このルーターモジュールは、app.js に示すようにアプリケーションに読み込むことができます。

javascript
const express = require('express')
const router = express.Router()

router.get('/', (req, res) => {
    res.send('Birds home page')
})

router.get('/about', (req, res) => {
    res.send('About birds')
})

module.exports = router
javascript
const express = require('express')
const app = express()
const birds = require('./birds')
const port = 3000

app.use('/birds', birds)

app.listen(port, () => {
    console.log(`Responding at http://0.0.0.0:${port}/`)
})

完全な例については、3_router プロジェクトを参照してください。

Ktor

Ktor では、実際のルートを定義するために Routing 型の拡張関数を使用するのが一般的なパターンです。以下のサンプル(Birds.kt)は、birdsRoutes 拡張関数を定義しています。routing ブロック内でこの関数を呼び出すことで、対応するルートをアプリケーション(Application.kt)に含めることができます。

kotlin
import io.ktor.server.response.*
import io.ktor.server.routing.*

fun Routing.birdsRoutes() {
    route("/birds") {
        get {
            call.respondText("Birds home page")
        }
        get("/about") {
            call.respondText("About birds")
        }
    }
}
kotlin
import com.example.routes.*
import io.ktor.server.application.*
import io.ktor.server.response.*
import io.ktor.server.routing.*

fun main(args: Array<String>): Unit =
    io.ktor.server.netty.EngineMain.main(args)

fun Application.module() {
    routing {
        birdsRoutes()
    }
}

完全な例については、3_router プロジェクトを参照してください。

URL パスを文字列として指定する以外にも、Ktor にはタイプセーフなルートResourcesプラグインを使用すると、型安全なルーティングを実装できます。を実装する機能が含まれています。

ルートパラメータとクエリパラメータ

このセクションでは、ルートパラメータとクエリパラメータにアクセスする方法を説明します。

ルート(またはパス)パラメータは、URL 内のその位置に指定された値をキャプチャするために使用される名前付きの URL セグメントです。

Express

Express でルートパラメータにアクセスするには、Request.params を使用できます。例えば、以下のコードスニペットの req.params['login'] は、/user/admin パスに対して admin を返します。

javascript
app.get('/user/:login', (req, res) => {
    if (req.params['login'] === 'admin') {
        res.send('You are logged in as Admin')
    } else {
        res.send('You are logged in as Guest')
    }
})

完全な例については、4_parameters プロジェクトを参照してください。

Ktor

Ktor では、ルートパラメータは {param} 構文を使用して定義されます。ルートハンドラー内でルートパラメータにアクセスするには、call.parameters を使用できます。

kotlin
routing {
    get("/user/{login}") {
        if (call.parameters["login"] == "admin") {
            call.respondText("You are logged in as Admin")
        } else {
            call.respondText("You are logged in as Guest")
        }
    }
}

完全な例については、4_parameters プロジェクトを参照してください。

以下の表は、クエリ文字列のパラメータにアクセスする方法を比較しています。

Express

Express でクエリパラメータにアクセスするには、req.query を使用できます。例えば、以下のコードスニペットの req.query['price'] は、クエリパラメータの値を取得します。

javascript
app.get('/products', (req, res) => {
    if (req.query['price'] === 'asc') {
        res.send('Products from the lowest price to the highest')
    }
})

完全な例については、4_parameters プロジェクトを参照してください。

Ktor

Ktor では、クエリパラメータにアクセスするために call.request.queryParameters を使用できます。

kotlin
routing {
    get("/products") {
        if (call.request.queryParameters["price"] == "asc") {
            call.respondText("Products from the lowest price to the highest")
        }
    }
}

完全な例については、4_parameters プロジェクトを参照してください。

レスポンスの送信

前のセクションでは、プレーンテキストのコンテンツで応答する方法を既に確認しました。ここでは、JSON、ファイル、およびリダイレクトのレスポンスを送信する方法を見ていきましょう。

JSON

Express

Express で適切なコンテンツタイプを持つ JSON レスポンスを送信するには、res.json 関数を呼び出します。

javascript
const car = {type:"Fiat", model:"500", color:"white"};
app.get('/json', (req, res) => {
    res.json(car)
})

完全な例については、5_send_response プロジェクトを参照してください。

Ktor

Ktor では、ContentNegotiationContentNegotiation プラグインには、主に2つの目的があります。クライアントとサーバー間でのメディアタイプのネゴシエーション、および特定の形式でのコンテンツのシリアライズ/デシリアライズです。 プラグインをインストールし、JSON シリアライザーを構成する必要があります。

kotlin
install(ContentNegotiation) {
    json()
}

データを JSON にシリアライズするには、@Serializable アノテーションを付加したデータクラスを作成する必要があります。

kotlin
@Serializable
data class Car(val type: String, val model: String, val color: String)

その後、call.respond を使用して、このクラスのオブジェクトをレスポンスとして送信できます。

kotlin
get("/json") {
    call.respond(Car("Fiat", "500", "white"))
}

完全な例については、5_send_response プロジェクトを参照してください。

ファイル

Express

Express でファイルをレスポンスとして返すには、res.sendFile を使用します。

javascript
const path = require("path")

app.get('/file', (req, res) => {
    res.sendFile(path.join(__dirname, 'ktor_logo.png'))
})

完全な例については、5_send_response プロジェクトを参照してください。

Ktor

Ktor は、クライアントにファイルを送信するための call.respondFile 関数を提供しています。

kotlin
get("/file") {
    val file = File("public/ktor_logo.png")
    call.respondFile(file)
}

完全な例については、5_send_response プロジェクトを参照してください。

Express アプリケーションは、ファイルで応答する際に Accept-Ranges HTTP レスポンスヘッダーを追加します。サーバーはこのヘッダーを使用して、ファイルダウンロードに関するクライアントからの部分リクエスト(レンジリクエスト)のサポートを通知します。Ktor では、部分リクエストをサポートするために PartialContent必要な依存関係: io.ktor:ktor-server-partial-content プラグインをインストールする必要があります。

添付ファイル

Express

res.download 関数は、指定されたファイルを添付ファイルとして転送します。

javascript
app.get('/file-attachment', (req, res) => {
    res.download("ktor_logo.png")
})

完全な例については、5_send_response プロジェクトを参照してください。

Ktor

Ktor では、ファイルを添付ファイルとして転送するために Content-Disposition ヘッダーを手動で構成する必要があります。

kotlin
get("/file-attachment") {
    val file = File("public/ktor_logo.png")
    call.response.header(
        HttpHeaders.ContentDisposition,
        ContentDisposition.Attachment.withParameter(ContentDisposition.Parameters.FileName, "ktor_logo.png")
            .toString()
    )
    call.respondFile(file)
}

完全な例については、5_send_response プロジェクトを参照してください。

リダイレクト

Express

Express でリダイレクトレスポンスを生成するには、redirect 関数を呼び出します。

javascript
app.get('/old', (req, res) => {
    res.redirect(301, "moved")
})

app.get('/moved', (req, res) => {
    res.send('Moved resource')
})

完全な例については、5_send_response プロジェクトを参照してください。

Ktor

Ktor では、respondRedirect を使用してリダイレクトレスポンスを送信します。

kotlin
get("/old") {
    call.respondRedirect("/moved", permanent = true)
}
get("/moved") {
    call.respondText("Moved resource")
}

完全な例については、5_send_response プロジェクトを参照してください。

テンプレート

Express と Ktor の両方で、ビューを扱うためのテンプレートエンジンを使用できます。

Express

views フォルダーに次の Pug テンプレートがあるとします。

html
  head
    title= title
  body
    h1= message

このテンプレートで応答するには、res.render を呼び出します。

javascript
app.set('views', './views')
app.set('view engine', 'pug')

app.get('/', (req, res) => {
    res.render('index', { title: 'Hey', message: 'Hello there!' })
})

完全な例については、6_templates プロジェクトを参照してください。

Ktor

Ktor は、FreeMarker、Velocity などのいくつかの JVM テンプレートエンジンHTML/CSS または JVM テンプレートエンジンを使用して構築されたビューを扱う方法を学びます。をサポートしています。例えば、アプリケーションリソースに配置された FreeMarker テンプレートで応答する必要がある場合は、FreeMarker プラグインをインストールおよび構成し、call.respond を使用してテンプレートを送信します。

kotlin
fun Application.module() {
    install(FreeMarker) {
        templateLoader = ClassTemplateLoader(this::class.java.classLoader, "views")
    }
    routing {
        get("/") {
            val article = Article("Hey", "Hello there!")
            call.respond(FreeMarkerContent("index.ftl", mapOf("article" to article)))
        }
    }
}

data class Article(val title: String, val message: String)

完全な例については、6_templates プロジェクトを参照してください。

リクエストの受信

このセクションでは、さまざまな形式のリクエスト本文を受信する方法を説明します。

プレーンテキスト

以下の POST リクエストは、テキストデータをサーバーに送信します。

http
POST http://0.0.0.0:3000/text
Content-Type: text/plain

Hello, world!

このリクエストの本文をサーバー側でプレーンテキストとして受信する方法を見てみましょう。

Express

Express で受信リクエストの本文を解析するには、body-parser を追加する必要があります。

javascript
const bodyParser = require('body-parser')

post ハンドラーで、テキストパーサー(bodyParser.text)を渡す必要があります。リクエスト本文は req.body プロパティから利用できます。

javascript
app.post('/text', bodyParser.text(), (req, res) => {
    let text = req.body
    res.send(text)
})

完全な例については、7_receive_request プロジェクトを参照してください。

Ktor

Ktor では、call.receiveText を使用して本文をテキストとして受信できます。

kotlin
post("/text") {
    val text = call.receiveText()
    call.respondText(text)
}

完全な例については、7_receive_request プロジェクトを参照してください。

JSON

このセクションでは、JSON 本文を受信する方法を見ていきます。以下のサンプルは、本文に JSON オブジェクトを含む POST リクエストを示しています。

http
POST http://0.0.0.0:3000/json
Content-Type: application/json

{
  "type": "Fiat",
  "model" : "500",
  "color": "white"
}
Express

Express で JSON を受信するには、bodyParser.json を使用します。

javascript
const bodyParser = require('body-parser')

app.post('/json', bodyParser.json(), (req, res) => {
    let car = req.body
    res.send(car)
})

完全な例については、7_receive_request プロジェクトを参照してください。

Ktor

Ktor では、ContentNegotiationContentNegotiation プラグインには、主に2つの目的があります。クライアントとサーバー間でのメディアタイプのネゴシエーション、および特定の形式でのコンテンツのシリアライズ/デシリアライズです。 プラグインをインストールし、Json シリアライザーを構成する必要があります。

kotlin
install(ContentNegotiation) {
    json(Json {
        prettyPrint = true
        isLenient = true
    })
}

受信したデータをオブジェクトにデシリアライズするには、データクラスを作成する必要があります。

kotlin
@Serializable
data class Car(val type: String, val model: String, val color: String)

次に、このデータクラスをパラメータとして受け取る receive メソッドを使用します。

kotlin
post("/json") {
    val car = call.receive<Car>()
    call.respond(car)
}

完全な例については、7_receive_request プロジェクトを参照してください。

URL エンコード

次に、application/x-www-form-urlencoded タイプを使用して送信されたフォームデータを受信する方法を見てみましょう。以下のコードスニペットは、フォームデータを含む POST リクエストの例を示しています。

http
POST http://localhost:3000/urlencoded
Content-Type: application/x-www-form-urlencoded

username=JetBrains&email=example@jetbrains.com&password=foobar&confirmation=foobar
Express

プレーンテキストや JSON と同様に、Express では body-parser が必要です。パーサーのタイプを bodyParser.urlencoded に設定する必要があります。

javascript
const bodyParser = require('body-parser')

app.post('/urlencoded', bodyParser.urlencoded({extended: true}), (req, res) => {
    let user = req.body
    res.send(`The ${user["username"]} account is created`)
})

完全な例については、7_receive_request プロジェクトを参照してください。

Ktor

Ktor では、call.receiveParameters 関数を使用します。

kotlin
post("/urlencoded") {
    val formParameters = call.receiveParameters()
    val username = formParameters["username"].toString()
    call.respondText("The '$username' account is created")
}

完全な例については、7_receive_request プロジェクトを参照してください。

バイナリデータ

次のユースケースは、バイナリデータの処理です。以下のリクエストは、application/octet-stream を持つ PNG 画像をサーバーに送信します。

http
POST http://localhost:3000/raw
Content-Type: application/octet-stream

< ./ktor_logo.png
Express

Express でバイナリデータを処理するには、パーサータイプを raw に設定します。

javascript
const bodyParser = require('body-parser')
const fs = require('fs')

app.post('/raw', bodyParser.raw({type: () => true}), (req, res) => {
    let rawBody = req.body
    fs.createWriteStream('./uploads/ktor_logo.png').write(rawBody)
    res.send('A file is uploaded')
})

完全な例については、7_receive_request プロジェクトを参照してください。

Ktor

Ktor は、バイトシーケンスの非同期読み取り/書き込み用の ByteReadChannel および ByteWriteChannel を提供しています。

kotlin
post("/raw") {
    val file = File("uploads/ktor_logo.png")
    call.receiveChannel().copyAndClose(file.writeChannel())
    call.respondText("A file is uploaded")
}

完全な例については、7_receive request プロジェクトを参照してください。

マルチパート

最後のセクションでは、multipart 本文を処理する方法を見ていきます。以下の POST リクエストは、multipart/form-data タイプを使用して説明付きの PNG 画像を送信します。

http
POST http://localhost:3000/multipart
Content-Type: multipart/form-data; boundary=WebAppBoundary

--WebAppBoundary
Content-Disposition: form-data; name="description"
Content-Type: text/plain

Ktor logo
--WebAppBoundary
Content-Disposition: form-data; name="image"; filename="ktor_logo.png"
Content-Type: image/png

< ./ktor_logo.png
--WebAppBoundary--
Express

Express でマルチパートデータを解析するには、別のモジュールが必要です。以下の例では、multer を使用してファイルをサーバーにアップロードしています。

javascript
const multer = require('multer')

const storage = multer.diskStorage({
    destination: './uploads/',
    filename: function (req, file, cb) {
        cb(null, file.originalname);
    }
})
const upload = multer({storage: storage});
app.post('/multipart', upload.single('image'), function (req, res, next) {
    let fileDescription = req.body["description"]
    let fileName = req.file.filename
    res.send(`${fileDescription} is uploaded to uploads/${fileName}`)
})

完全な例については、7_receive_request プロジェクトを参照してください。

Ktor

Ktor でマルチパートリクエストの一部として送信されたファイルを受信する必要がある場合は、receiveMultipart 関数を呼び出し、必要に応じて各パートをループ処理します。以下の例では、PartData.FileItem を使用してファイルをバイトストリームとして受信しています。

kotlin
post("/multipart") {
    var fileDescription = ""
    var fileName = ""
    val multipartData = call.receiveMultipart()
    multipartData.forEachPart { part ->
        when (part) {
            is PartData.FormItem -> {
                fileDescription = part.value
            }

            is PartData.FileItem -> {
                fileName = part.originalFileName as String
                val channel = part.provider()
                SystemFileSystem.sink(Path("uploads/$fileName")).use { sink ->
                    while (!channel.exhausted()) {
                        channel.readBuffer().transferTo(sink)
                        sink.flush()
                    }
                }
            }

            else -> {}
        }
        part.dispose()
    }
    call.respondText("$fileDescription is uploaded to 'uploads/$fileName'")
}

完全な例については、7_receive_request プロジェクトを参照してください。

ミドルウェアの作成

最後に見るのは、サーバー機能を拡張できるようにするミドルウェアを作成する方法です。以下の例は、Express と Ktor を使用してリクエストロギングを実装する方法を示しています。

Express

Express では、ミドルウェアは app.use を使用してアプリケーションにバインドされる関数です。

javascript
const express = require('express')
const app = express()
const port = 3000

const requestLogging = function (req, res, next) {
    let scheme = req.protocol
    let host = req.headers.host
    let url = req.url
    console.log(`Request URL: ${scheme}://${host}${url}`)
    next()
}

app.use(requestLogging)

完全な例については、8_middleware プロジェクトを参照してください。

Ktor

Ktor では、カスタムプラグイン独自のカスタムプラグインを作成する方法を学びます。を使用して機能を拡張できます。以下のコード例は、リクエストロギングを実装するために onCall を処理する方法を示しています。

kotlin
val RequestLoggingPlugin = createApplicationPlugin(name = "RequestLoggingPlugin") {
    onCall { call ->
        call.request.origin.apply {
            println("Request URL: $scheme://$localHost:$localPort$uri")
        }
    }
}

完全な例については、8_middleware プロジェクトを参照してください。

次のステップ

セッション管理、認証、データベース統合など、このガイドでは取り上げていないユースケースがまだたくさんあります。これらの機能のほとんどについて、Ktor は必要に応じてアプリケーションにインストールして構成できる専用のプラグインを提供しています。Ktor の学習を続けるには、ステップバイステップのガイドやそのまま使えるサンプルが用意されている Learn ページにアクセスしてください。