Ktor_Server_Demo/README_en.md

Ktor Server Demo

English / 简体中文

---

A Ktor 3.x backend project rewritten in an idiomatic Ktor manner, fully aligned with the features and data schemas of Springboot4-Vue3, providing seamless support for the Vue 3 frontend.

---

Tech Stack

• Language & Build: Kotlin (jvmToolchain(21) / 25) + Gradle (Kotlin DSL)
• Web Framework: Ktor 3.6.0 (Engine: CIO)
• Database & ORM:
  • MySQL 8+ (mysql-connector-j:9.2.0)
  • HikariCP Connection Pool (5.1.0)
  • JetBrains Exposed ORM (0.55.0, including Core, JDBC, DAO, and exposed-kotlin-datetime)
• Cache & Rate Limiting: Redis 6+ + Lettuce Client (6.3.2.RELEASE)
• Message Queue: RabbitMQ 3.8+ (amqp-client:5.34.0)
• Mail Service: Jakarta Mail (org.eclipse.angus:jakarta.mail:2.0.4)
• Authentication & Encryption:
  • Auth0 Java-JWT (4.4.0) + Ktor Auth JWT (ktor-server-auth-jwt)
  • BCrypt Password Hashing (at.favre.lib:bcrypt:0.10.2, 100% compatible with Spring Security BCrypt)
• Serialization & Datetime: kotlinx-serialization-json + kotlinx-datetime
• Real-time Communication: Ktor WebSockets (ktor-server-websockets)
• CORS & Error Handling: Ktor CORS (ktor-server-cors) + StatusPages (ktor-server-status-pages)

---

Prerequisites

• JDK 21+ (JDK 21 or JDK 25 recommended)
• MySQL 8.0+
• Redis 6.0+
• RabbitMQ 3.8+

---

Quick Start

1. Initialize Database

Import the included database schema and sample data:

mysql -u backend -p kotlin_springboot < src/main/resources/ktor_rpc.sql

Default Test Account:

• Username: test
• Password: 123456
• Email: 1234567890@gmail.com

2. Configure Application Properties

Review and edit src/main/resources/application.yaml (or refer to application-example.yaml):

• datasource: JDBC database URL, username, and password
• redis: Redis connection URL (default: redis://localhost:6379)
• rabbitmq: RabbitMQ credentials and queue name (default queue: mail)
• mail: SMTP account and authorization code
• jwt: JWT secret key and expiration hours

3. Build & Run

Run Gradle tasks in the project root directory:

# Build project
./gradlew build

# Run server
./gradlew run

Upon successful startup, the server listens and logs:

INFO Application - Responding at http://0.0.0.0:8080

---

API Endpoints

Method	Path	Authentication	Description
POST	/api/v1/auth/login or /api/auth/login	Public	Login via username/email and password, returns Token and expiration
GET	/api/v1/auth/ask-code or /api/auth/ask-code	Public	Send email verification code (?email=...&type=register)
POST	/api/v1/auth/register or /api/auth/register	Public	Register a new account via email
POST	/api/v1/auth/reset or /api/auth/reset	Public	Reset password with verification code
GET	/api/v1/auth/logout or /api/auth/logout	Bearer Token	Invalidate token and add to Redis blacklist
GET	/api/v1/auth/relogin or /api/auth/relogin	Bearer Token	Refresh and renew JWT token
GET	/api/test/hello	Public	Health and connectivity test
GET	/api/test/wstoken	Public	Issue a one-time handshake token for WebSocket
WS	/ws/test	Public	Test WebSocket echo pipeline
WS	/ws/v1/example	?token=...	Establish WebSocket connection with one-time token verification