**Ktkit**：Ktor を使ったサーバーアプリケーション構築用 Kotlin ツールキット

KtKit

Ktor を使ったサーバーアプリケーション構築を高速化する、Kotlin マルチプラットフォーム向け総合ツールキットです。

• 📖 ドキュメント
• 🏠 ホームページ（現在制作中）

使い方

implementation("io.github.smyrgeorge:ktkit:x.y.z")

概要

KtKit は、Ktor を利用したサーバー側アプリケーション開発を加速するために設計された Kotlin Multiplatform ツールキットです。
複数のライブラリを統合し、バックエンド開発で繰り返される作業を一元化するツール群を提供します。

注意 – 初期段階のプロジェクトです：KtKit は継続的に進化しています。実際の運用経験に基づいて抽象化を洗練させる過程で、バージョン間で API が変更される可能性があります。プロダクション環境でも使用できますが、一部破壊的変更が発生することがあります。ご意見・貢献は大歓迎です！

今日の機能

• DI、JSON、REST ハンドラ自動登録を備えた小規模な Ktor アプリケーション起動ロジック
• トレーシング、認可/権限フック、RFC 9457 形式の API エラー処理でリクエストハンドリングを標準化
• ツールキット上に構築されたサービス向け基本的なヘルス・メトリクスエンドポイントを公開
• 環境変数展開とファイル/リソースマージをサポートした TOML 設定ローダー
• 再試行、JSON/TOML ユーティリティ、および KMP 互換のファイル／HTTP／プロセスアクセス用便利ヘルパー
• Arrow（Raise/Either）と Kotlin のコンテキストパラメータを活用し、エラー処理とコンテキスト伝搬を軽量化

今後予定している機能

• Arrow のレジリエンスライブラリ（Retry, Resource, Circuit Breaker など）の統合
• 豊富なサンプル・テスト・ドキュメントの作成
• JWT 認証用 BearerPrincipalExtractor
• sqlx4k 統合
• PGMQ 統合
• その他アイデアでリストを拡張（🧐）

モジュールと機能

Core (

ktkit

)

• Ktor サーバー起動/停止、JSON 設定、Koin DI、ルーティングのラッパー
• 型付きリクエストヘルパー、

  ExecContext

  伝搬、エラーマッピングを備えた

  AbstractRestHandler

• /api/status/health

  と

  /api/status/metrics

  の組み込みエンドポイント
• RFC 9457 に準拠したエラーモデル（

  ErrorSpec

  /

  ApiError

  ）
• 環境変数置換と層状オーバーライドをサポートする TOML 設定ローダー

セキュリティ：X‑Real‑Name ヘッダー認証

XRealNamePrincipalExtractor

と

XRealNameRestClient

は、ベース64 エンコードされた JSON ヘッダー（

x-real-name

）を用いて認証ユーザーを特定します。この仕組みは インターネット上に直接公開することは安全ではありません。

このパターンは、信頼できるリバースプロキシまたは API ゲートウェイがアプリケーションの前段に存在することを想定しています：

1. ユーザー認証（OAuth, JWT, セッション Cookie など）
2. クライアントから送られた

   x-real-name

   ヘッダーを除去
3. 認証されたユーザー情報で

   x‑real‑name

   ヘッダーを設定して転送

直接インターネットに公開されている場合、任意のクライアントがヘッダーを偽装し、誰でもなりすまし可能です。信頼できるインフラ層（プロキシ/ゲートウェイ）後ろでのみこのエグジスタを利用してください。

Ktor HTTP Client (

ktkit-ktor-httpclient

)

Ktor の

HttpClient

• タイムアウト・接続プール・JSON 設定付きの事前構成済み

  HttpClient

  を作る

  HttpClientFactory

• 型付き HTTP メソッド（GET, POST, PUT, PATCH, DELETE 等）を備えた

  AbstractRestClient

  基底クラス
• 実装例：Bearer トークン認証用

  BearerRestClient

  と X‑Real‑Name ヘッダー認証用

  XRealNameRestClient

• シールド化された

  RestClientErrorSpec

  階層でエラー処理

sqlx4k Integration (

ktkit-sqlx4k

)

コルーチン優先の SQL ツールキットで、Kotlin Multiplatform 用にコンパイル時クエリ検証を提供。PostgreSQL, MySQL/MariaDB, SQLite をサポートします。

• エラーマッピングとトレース付きトランザクション用

  DatabaseService

  ヘルパー

• createdAt/createdBy/updatedAt/updatedBy

  用のフックを持つ

  AuditableRepository

• Auditable エンティティを扱うサービス向け

  AuditableDatabaseService

  インターフェースと

  save()

  拡張関数
• sqlx4k の

  ValueEncoder

  システムで JSON 列シリアライズを行う

  JsonSupport

  ユーティリティ

PGMQ Integration (

ktkit-sqlx4k-pgmq

)

AWS SQS や RSMQ に似た軽量メッセージキュー。PostgreSQL 上に実装されています。

• Pgmq ラッパーとトレース/ユーザー伝搬付き

  AbstractPgmqEventHandler

• 再試行・シャットダウン処理を備えたコンシューマライフサイクルヘルパー

Ergonomics (Arrow + context‑parameters)

以下の例モジュールは、Arrow の Raise と Kotlin のコンテキストパラメータがどのようにサービスコードを簡潔に保ちつつ、エラーと実行コンテキストを明示的に扱うかを示しています。

class TestService(
    override val db: Driver,
    override val repo: TestRepository,
) : AuditableDatabaseService<Test> {

    val log = Logger.of(this::class)

    context(_: ExecContext, _: QueryExecutor)
    private suspend fun findAll(): List<Test> = db { repo.findAll() }

    context(_: ExecContext, _: Transaction)
    suspend fun test(): List<Test> {
        log.info { "Fetching all tests" }
        return findAll().also {
            log.info { "Fetched ${it.size} tests" }
        }
    }
}

ExecContext

class ExecContext(
    val reqId: String,
    val reqTs: Instant,
    val principal: Principal,
) : Raise<ErrorSpec>, TracingContext by tracing, CoroutineContext.Element

これにより、ハンドラやサービスはドメインエラーを発生させつつ、トレーシング情報とリクエストメタデータへアクセスでき、スレッドパラメータを手動で渡す必要がなくなります。コンテキストは

CoroutineContext

例

こちら のサンプルアプリケーションをご覧ください。

ビルド & 開発

ビルド

# JVM と現在のプラットフォーム向けに全モジュールをビルド
./gradlew build

# サポートされるすべてのプラットフォーム用に全モジュールをビルド
./gradlew build -Ptargets=all

Docker 設定

プロジェクトには PostgreSQL 用の

docker‑compose.yml

services:
  postgres:
    image: postgres:15
    environment:
      POSTGRES_USER: ktkit
      POSTGRES_PASSWORD: password
      POSTGRES_DB: ktkitdb
    ports:
      - "5432:5432"

コントリビューション

これはオープンソースプロジェクトです。貢献は大歓迎です！

ライセンス

リポジトリ内のライセンス情報をご確認ください。

関連プロジェクト

• log4k – トレーシング付きマルチプラットフォームロギング
• sqlx4k – マルチプラットフォームデータベースアクセス

作者

Yorgos S. (@smyrgeorge)