Ktorはビルトインで静的コンテンツ配信をサポートしています。 スタイルシートやスクリプトや画像等を配信したいときに便利な機能です:
io.ktor.routing.Routing
and no additional artifacts are required.
static
関数を使い、Ktorに特定URIを静的コンテンツのように扱うよう指定し、そのファイルがどこにあるのかも定義することができます。
すべてのコンテンツは現在のworkingディレクトリからの相対パスで扱われます。
異なるルートフォルダを設定するにはカスタムルートフォルダの定義をご覧ください。
routing {
static("static") {
files("css")
}
}
上の例は/static
のURIに来た任意のリクエストを静的コンテンツのように扱うようktor
に伝えます。
files("css")
はそれらのファイルが配置されているフォルダを定義します。
つまりcss
フォルダ配下の任意のファイルが配信されます。
つまり、/static/styles.css
といったリクエストはcss/styles.css
ファイルを配信します。
フォルダに加え、file
を使うことで指定したファイルを含めることもできます。
実際の物理的なファイル名とURIのパス名が違った場合には、オプショナルの第二引数に実際の物理的なファイル名を指定することもできます。
routing {
static("static") {
files("css")
files("js")
file("image.png")
file("random.txt", "image.png")
default("index.html")
}
}
default
を使うことで、配信するデフォルトのファイルを指定することもできます。
例えば
/static
をファイル名無しで呼び出した場合, index.html
が配信されるようにすることができます。
workingディレクトリ以外の異なるルートフォルダを指定するためには、
staticRootFolder
にFile
型で値を指定します。
static("custom") {
staticRootFolder = File("/system/folder/docs")
files("public")
}
サブルートの定義もできます。
例えば/static/themes
などです。
static("static") {
files("css")
static("themes") {
files("data")
}
}
静的コンテンツをリソースとしてアプリケーションに組み込む場合は、
resource
、resources
関数を使ってリソースから配信することができます:
static("static") {
resources("css")
resource("favicon.ico")
}
default
に似たdefaultResource
というものもあり、フォルダに対し配信するデフォルトページの指定することができます。
staticRootFolder
に似たstaticBasePackage
というものもあり、静的コンテンツのベースリソースパッケージを指定することができます。
リクエストされたコンテンツが見つからない場合、404 Not Found
が返されます。
ファイルが配信されるとき、コンテントタイプはContentType.defaultForFile(file)
を使ってファイル拡張子から決定されます。
各ファイルタイプに対応するデータはktor-server-core
に配置されたmimelist.csv
リソースファイルから取得されます。
static
関数は以下のように定義されています。
fun Route.static(remotePath: String, configure: Route.() -> Unit) = route(remotePath, configure)
これは本質的にはただすこし違った形でルート定義しているだけです。
KtorはHEAD
リクエストをデフォルトでは扱うことができません。
それゆえに静的コンテンツ機能もHEAD
リクエストを扱うことができません。
自動的にHEAD
リクエストを各GET
ルートごとに扱えるようにするには、
AutoHeadResponse
Featureをインストールしてください。
fun Application.main() {
// ...
install(AutoHeadResponse)
// ...
}
デフォルトではHEADリクエストをハンドリングできないということは、
もしAutoHeadResponse Featureをインストールせずcurl -I
かcurl --head
をGETルートに対して使った場合、
404 Not Foundが返ることになります。