github-actions-creator/docs/kotlin-ktor.md

Kotlin (Ktor) 项目：URL 缩短服务

概述

使用 Kotlin 和 Ktor 构建一个异步、高性能的 URL 缩短服务。利用 Kotlin 协程处理高并发请求，提供 API 将长 URL 转换为短 URL，并通过短 URL 重定向。

功能需求

1. 核心 API

• 创建短 URL: POST /shorten
  • 请求: { "url": "..." }
  • 逻辑: 验证 URL -> 生成唯一哈希 -> 存入数据库。若 URL 已存在，则返回现有短 URL。
  • 响应: { "short_url": "http://domain.com/hash" }
• URL 重定向: GET /{hash}
  • 逻辑: 查找哈希对应的原始 URL，找到则 301/302 重定向，未找到则 404。

2. 附加功能

• 自定义短链接: POST /shorten 时可选 custom_alias 字段。
• 点击统计: 每次重定向时，异步增加点击计数。
• 获取统计: GET /stats/{hash} - 返回原始 URL、创建时间和点击次数。

技术栈

• 语言: Kotlin
• 框架: Ktor
• 构建: Gradle (Kotlin DSL)
• 数据库: PostgreSQL 或 MongoDB (使用异步驱动)
• 数据访问: Exposed (SQL) 或 KMongo (MongoDB)
• 序列化: kotlinx.serialization
• 异步: Kotlin Coroutines

项目结构

/ktor-url-shortener
└── src/main/kotlin/com/example/
    ├── Application.kt      # Ktor 主入口和模块配置
    ├── plugins/            # 插件配置 (Serialization, Routing)
    ├── routing/            # 路由定义
    ├── services/           # 业务逻辑
    ├── dao/                # 数据访问对象
    └── models/             # 数据模型

任务步骤

1. 初始化: 使用 Ktor 官方生成器创建项目，选择 Gradle, Netty, Routing, Serialization 和数据库插件。
2. 数据库设置: 配置数据库连接，并使用 Exposed 或迁移工具设置表结构。
3. 数据模型: 创建用于 API 和数据库映射的数据类。
4. DAO层: 实现数据访问逻辑，提供 suspend 函数（如 findByHash, saveMapping）。
5. Service层: 实现生成唯一哈希的核心逻辑（如 Base62 编码自增ID）。
6. 路由配置: 定义 /shorten 和 /{hash} 的 API 路由，调用 Service 完成操作。
7. 插件组装: 在主应用中配置 ContentNegotiation 和 Routing 插件。
8. 错误处理: 使用 StatusPages 插件捕获异常并返回合适的 HTTP 状态。
9. 测试: 使用 Ktor 的 testApplication 工具编写 API 集成测试。

先行任务: 研究并确定短哈希生成算法，并设计出数据库表的具体结构。