如何使用 Ktor 快速开发 Web 项目

photo-of-woman-wearing-pink-top-2810803.jpg

一. Ktor 介绍

Ktor 是一个高性能的、基于 Kotlin 的 Web 开发框架，支持 Kotlin Coroutines、DSL 等特性。

Ktor 是一个由 Kotlin 团队打造的 Web 框架，可用于创建异步、高性能和轻量级的 Web 服务器，并使用 Kotlin 惯用的 API 构建非阻塞的多平台 Web 客户端。

Ktor 的服务端仅限于 JVM，但是 Ktor 的客户端是一个 Multiplatform 的库。

如果使用 Kotlin Multiplatform 构建跨平台项目时，使用 Ktor 的客户端作为 Http 框架是一个不错的选择。

Ktor 由两部分组成：服务器引擎和灵活的异步 HTTP 客户端。当前版本主要集中在 HTTP 客户端上。客户端是一个支持 JVM，JS，Android 和 iOS 的多平台库，现在经常在跨平台移动应用程序中使用。

二. Ktor 服务端的使用

我们可以通过多种方式运行 Ktor 服务端程序：

Ktor Server.png

在 main() 中调用 embeddedServer 来启动 Ktor 应用
运行一个 EngineMain 的 main() 并使用 HOCON application.conf 配置文件
作为 Web 服务器中的 Servlet
在测试中使用 withTestApplication 来启动 Ktor 应用

2.1 Gradle 配置 Ktor

Kotlin 的版本需要 1.3.x，因为 Ktor 底层会依赖到 Kotlin Coroutines。

在需要使用 Ktor 的 module 中添加如下的依赖：

dependencies {
    ...
    implementation "io.ktor:ktor-server-core:${libs.ktor}"
    implementation "io.ktor:ktor-server-netty:${libs.ktor}"
}

后面的例子还会介绍 Ktor 其他的 artifact，例如：freemarker、gson 等。

2.2 embeddedServer

当使用 embeddedServer 时，Ktor 使用 DSL 来配置应用程序和服务器引擎。目前，Ktor 支持 Netty、Jetty、Tomcat、CIO(Coroutine I/O) 作为服务器引擎。(当然，也支持创建自己的引擎并为其提供自定义配置。)

以 Netty 作为服务器引擎为例，通过 embeddedServer 启动 Ktor 应用：

fun main() {
    embeddedServer(Netty, port?:8080, watchPaths = listOf("MainKt"), module = Application::module).start()
}

2.3 ApplicationCall && Routing

当一个请求进入 Ktor 应用时（可以是 HTTP，HTTP / 2 或 WebSocket 请求），该请求将被转换为 ApplicationCall 并通过该应用程序拥有的管道。Ktor 的管道是由一个或多个预先安装的拦截器组成，这些拦截器提供某些功能，例如：路由，压缩等，最终将处理请求。

ApplicationCall 提供对两个主要属性 ApplicationRequest 和 ApplicationResponse 的访问。它们对应于传入请求和传出响应。除了这些之外，ApplicationCall 还提供了一个 ApplicationEnvironment 和一些有用的功能来帮助响应客户端请求。

Routing 是一项安装在应用程序中的功能，用于简化和构建页面请求处理。Ktor 的 Routing 支持 Restful 的各种方法，以及使用 DSL 进行配置。

Routing 支持嵌套，被称为 Routing Tree，可以通过递归匹配复杂的规则和处理请求。

2.4 CORS

默认情况下，Ktor 提供拦截器以实现对跨域资源共享（CORS）的适当支持。

首先，将 CORS 功能安装到应用中。

fun Application.main() {
  ...
  install(CORS)
  ...
}

Ktor CORS 功能的默认配置仅处理 GET，POST 和 HEAD HTTP 方法以及以下标头：

  HttpHeaders.Accept
  HttpHeaders.AcceptLanguages
  HttpHeaders.ContentLanguage
  HttpHeaders.ContentType

下面的例子展示了如何配置 CORS 功能

fun Application.main() {
  ...
  install(CORS)
  {
    method(HttpMethod.Options)
    header(HttpHeaders.XForwardedProto)
    anyHost()
    host("my-host")
    // host("my-host:80")
    // host("my-host", subDomains = listOf("www"))
    // host("my-host", schemes = listOf("http", "https"))
    allowCredentials = true
    allowNonSimpleContentTypes = true
    maxAge = Duration.ofDays(1)
  }
  ...
}

2.5 Packing

部署 Ktor 应用时，可以使用 fat jar 或者 war 包。

我们以 fat jar 为例，使用 gradle 的 shadow 插件可以方便地打包 Ktor 的应用。

在项目根目录下的 build.gradle 中添加 shadow 插件的依赖：

buildscript {
    repositories {
        jcenter()
        mavenCentral()
    }
    dependencies {
        classpath 'com.github.jengelman.gradle.plugins:shadow:5.2.0'
        ......
    }
}

然后在需要打包的 module 中添加 shadow 插件和输出 jar 包名称以及 jar 包的入口 Main 函数：

plugins {
    id 'java'
    id 'kotlin'
    id 'com.github.johnrengelman.shadow'
}

......

shadowJar {
    baseName = 'xxx'  // jar 包名称
    manifest {
        attributes["Main-Class"] = "xxx.xxx.xxx.xxx"  // jar 包的主函数
    }
}

三. 例子

以 RxCache 为例，本文会介绍使用 Ktor 开发一个 Local Cache 的 browser(浏览器)，用于读取磁盘缓存中的数据。

RxCache 是一款支持 Java 和 Android 的 Local Cache 。目前支持内存、堆外内存、磁盘缓存。

开发的背景：我们存在一些桌面程序部署在 Ubuntu 上，并需要对这些程序进行埋点，而 RxCache 本身支持磁盘的缓存。因此，我使用 RxCache 存储埋点的数据，所以需要一个浏览器的程序来查看本地的埋点数据。

3.1 RxCache 的配置

RxCache 是一个单例，使用时需要先调用 config() 配置 RxCache。

RxCache 支持二级缓存：Memory、Persistence，并拥有多种序列化方式。这些可以通过配置来体现。

val rxCache: RxCache by lazy {

    val converter: Converter = when (Config.converter) {
        "gson"      -> GsonConverter()。
        "fastjson"  -> FastJSONConverter()
        "moshi"     -> MoshiConverter()
        "kryo"      -> KryoConverter()
        "hessian"   -> HessianConverter()
        "fst"       -> FSTConverter()
        "protobuf"  -> ProtobufConverter()
        else        -> GsonConverter()
    }

    RxCache.config {
        RxCache.Builder().persistence {
            when (Config.type) {
                "disk"   -> {
                    val cacheDirectory = File(Config.path) // rxCache 持久层存放地址
                    if (!cacheDirectory.exists()) {
                        cacheDirectory.mkdir()
                    }
                    DiskImpl(cacheDirectory, converter)
                }
                "okio"   -> {
                    val cacheDirectory = File(Config.path) // rxCache 持久层存放地址
                    if (!cacheDirectory.exists()) {
                        cacheDirectory.mkdir()
                    }
                    OkioImpl(cacheDirectory, converter)
                }
                "mapdb"  -> {
                    val cacheDirectory = File(Config.path) // rxCache 持久层存放地址
                    MapDBImpl(cacheDirectory, converter)
                }
                "diskmap"-> {
                    val cacheDirectory = File(Config.path) // rxCache 持久层存放地址
                    DiskMapImpl(cacheDirectory, converter)
                }
                else     -> {
                    val cacheDirectory = File(Config.path) // rxCache 持久层存放地址
                    if (!cacheDirectory.exists()) {
                        cacheDirectory.mkdir()
                    }
                    DiskImpl(cacheDirectory, converter)
                }
            }
        }
    }

    RxCache.getRxCache()
}

3.2 module

Ktor module 是一个开发者定义的函数，它用于接收 Application 类(该类负责配置服务器管道，安装功能，注册路由，处理请求等)。

在本例子中，安装了 DefaultHeaders、CallLogging、FreeMarker、ContentNegotiation、Routing。

fun Application.module() {

    install(DefaultHeaders)
    install(CallLogging)
    install(FreeMarker) {
        templateLoader = ClassTemplateLoader(this::class.java.classLoader, "templates")
        defaultEncoding = "utf-8"
    }
    install(ContentNegotiation) {
        gson {
            setDateFormat(DateFormat.LONG)
            setPrettyPrinting()
        }
    }
    install(Routing) {
         ......
    }
}

3.3 Routing

Routing 提供了对外的页面。

    install(Routing) {
        static("/") {
            defaultResource("index.html", "web")
        }

        post("/saveConfig") {

            val postParameters: Parameters = call.receiveParameters()

            Config.path = postParameters["path"] ?: ""
            Config.type = postParameters["type"] ?: ""
            Config.converter = postParameters["converter"] ?: ""

            call.respond(FreeMarkerContent("save.ftl", mapOf("config" to Config)))
        }
        get("/list") {

            val file = File(Config.path)
            val array = file.list()
            call.respond(array)
        }
        get("/detail/{key}") {

            val key = call.parameters["key"]
            val json = rxCache.getStringData(key)
            call.respondText(json)
        }
        get("/info") {

            val json = rxCache.info
            call.respondText(json)
        }
    }

其中 index.html 用于配置 RxCache。

saveConfig 用于展示保存的 RxCache 的数据，其中用到了 FreeMarker 的模板 save.ftl

<html>
<h2>Hi</h2>

RxCache's path: ${config.path} </br>
RxCache's persistence: ${config.type} </br>
RxCache's serialization: ${config.converter} </br>
</html>

list 接口、detail 接口分别用于展示磁盘存储数据的 key，以及根据 key 来查询详细的存储内容。

list 接口

detail 接口

info 接口用于显示缓存中的信息。

info 接口

3.4 启动

browser 配置了 kotlinx-cli，它可以通过命令行解析参数。目前，只支持 '-p' 用于表示启动 Ktor 应用的端口号。

browser 使用 Netty 作为服务器引擎。

fun main(args: Array<String>) {

    val parser = ArgParser("rxcache-browser")
    val port            by parser.option(ArgType.Int, shortName = "p", description = "Port number of the local web service")
    parser.parse(args)

    embeddedServer(Netty, port?:8080, watchPaths = listOf("MainKt"), module = Application::module).start()
}

四. 小结

Ktor 构建的应用，只需少量代码和配置即可完成，非常简便。

非常适用于简单的 Web 项目、对外提供接口的 OpenAPI 项目。当然使用它来构建微服务也是可以，它也有丰富的 Features。

RxCache 项目地址：https://github.com/fengzhizi715/RxCache
例子的代码：https://github.com/fengzhizi715/RxCache/tree/master/browser