kotlin-ktor-exposed-starter - GitLite

KO | EN

gitlite — search

#react #ai #typescript #golang #go #android #deep-learning #linux #docker #nodejs #awesome #kubernetes #vue #open-source

kotlin-ktor-exposed-starter

(★ 588)

Starter RESTful service with websocket notifications using Kotlin, Ktor and Exposed with H2, HikariCP and FlyWay

파일 탐색기

최종 버전 다운로드 (.zip)

- - build.yml
- - gradle-wrapper.jar
  - gradle-wrapper.properties
- libs.versions.toml
.gitignore
build.gradle.kts
Dockerfile
gradle.properties
gradlew
gradlew.bat
README.md
settings.gradle

# 설치 가이드

1. 코드 내려받기

git clone https://github.com/raharrison/kotlin-ktor-exposed-starter

깃허브에서 프로젝트 코드 전체를 내 컴퓨터로 내려받습니다.

cd kotlin-ktor-exposed-starter

방금 내려받은 프로젝트 폴더 안으로 이동합니다.

2. Docker

쉬움 추천

사전 준비물

Git GitHub에서 프로젝트 코드를 내려받으려면 필요합니다.
Docker Desktop 컨테이너를 빌드하고 실행하려면 필요합니다. 설치 후 실행해서 백그라운드에 켜두세요.

docker build -t kotlin-ktor-exposed-starter .

Dockerfile을 기반으로 실행 가능한 이미지를 빌드합니다.

docker run -p 8080:80 kotlin-ktor-exposed-starter

빌드된 이미지를 실제 컨테이너로 실행합니다.

✅ 터미널에 docker compose ps 를 입력해 컨테이너들이 Up 상태인지 확인하세요. README에 포트 번호가 적혀있다면 브라우저에서 http://localhost:포트번호 로 접속해보세요.

3. Gradle (Java/Kotlin)

보통

사전 준비물

Git GitHub에서 프로젝트 코드를 내려받으려면 필요합니다.
JDK (Java) Java/Kotlin 프로젝트를 빌드/실행하려면 필요합니다.
Gradle 레포에 포함된 gradlew(Gradle Wrapper)를 쓰면 Gradle을 따로 설치할 필요가 없습니다.

./gradlew build

Gradle로 빌드를 진행합니다.

✅ BUILD SUCCESSFUL 메시지가 뜨면 성공입니다. build/ 폴더에 결과물이 생성됩니다.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

[![Kotlin](https://img.shields.io/badge/kotlin-2.4.10-blue.svg?logo=kotlin)](http://kotlinlang.org)
[![Ktor](https://img.shields.io/badge/ktor-3.5.1-blue.svg)](https://github.com/ktorio/ktor)
[![Build](https://github.com/raharrison/kotlin-ktor-exposed-starter/workflows/Build/badge.svg)](https://github.com/raharrison/kotlin-ktor-exposed-starter/actions/workflows/build.yml)
[![codecov](https://codecov.io/gh/raharrison/kotlin-ktor-exposed-starter/branch/master/graph/badge.svg?token=v2k9oObm0C)](https://codecov.io/gh/raharrison/kotlin-ktor-exposed-starter)

## Starter project to create a simple RESTful web service in Kotlin

**Updated for Kotlin 2.4.10, Ktor 3.5.1 and Exposed 1.3.1**

Companion article: <https://ryanharrison.co.uk/2018/04/14/kotlin-ktor-exposed-starter.html>

## Getting Started

1. Clone the repo.
2. In the root directory execute `./gradlew run`
3. By default, the server will start on port `8080`. See below [Routes](#routes) section for more information.

### Libraries used:

- [Ktor](https://github.com/ktorio/ktor) - Kotlin async web framework
 - [Netty](https://github.com/netty/netty) - Async web server
 - [Kotlin Serialization](https://github.com/Kotlin/kotlinx.serialization) - JSON serialization/deserialization
 - [Exposed](https://github.com/JetBrains/Exposed) - Kotlin SQL framework
 - [H2](https://github.com/h2database/h2database) - Embeddable database
 - [HikariCP](https://github.com/brettwooldridge/HikariCP) - High performance JDBC connection pooling
 - [Flyway](https://flywaydb.org/) - Database migrations
 - [JUnit 5](https://junit.org/junit5/), [AssertJ](http://joel-costigliola.github.io/assertj/)
   and [Rest Assured](http://rest-assured.io/) for testing
 - [Kover](https://github.com/Kotlin/kotlinx-kover) for code coverage, publishing
   to [Codecov](https://about.codecov.io/) through GitHub Actions
 
The starter project creates a new in-memory H2 database with one table for `Widget` instances.

As ktor is async and based on coroutines, standard blocking JDBC may cause performance issues when used
directly on the main thread pool (as threads must be reused for other requests). Therefore, another dedicated thread
pool is created for all database queries, alongside connection pooling with HikariCP.

### Routes:

`GET /widgets` --> get all widgets in the database

`GET /widgets/{id}` --> get one widget instance by id (integer)

`POST /widgets` --> add a new widget to the database by providing a JSON object (converted to a NewWidget instance). e.g -

```json
{
    "name": "new widget",
    "quantity": 64
}
```

returns

```json
{
    "id": 3,
    "name": "new widget",
    "quantity": 64,
    "dateUpdated": 1519926898
}
```  
    
`PUT /widgets` --> update an existing widgets name or quantity. Pass in the id in the JSON request to determine which record to update

`DELETE /widgets/{id}` --> delete the widget with the specified id

### Notifications (WebSocket)

All updates (creates, updates and deletes) to `Widget` instances are served as notifications through a WebSocket endpoint:

`WS /updates` --> returns `Notification` instances containing the change type, id and entity (if applicable) e.g:

```json
{ 
    "type": "CREATE", 
    "id": 12, 
    "entity": { 
      "id": 12, 
      "name": "widget1", 
      "quantity": 5, 
      "dateUpdated": 1533583858169 
    }
}
```

The websocket listener will also log out any text messages send by the client. Refer to [this blog post](https://ryanharrison.co.uk/2018/08/19/testing-websockets.html) for some useful tools to test the websocket behaviour.

### Testing

The sample Widget service and corresponding endpoints are also tested with 100% coverage. Upon startup of the main JUnit suite (via the `test` source folder), the server is started ready for testing and is torn down after all tests are run.

- Unit testing of services with AssertJ - DAO and business logic is tested by initialising an in-memory H2 database with
  Exposed, using the same schema as the main app. With this approach database queries are fully tested without any
  mocking.
- Integration testing of endpoints using a fully running server with Rest Assured - routing tests/status codes/response
  structure. This utilises the fact that Ktor is a small microframework that can be easily spun up and down as part of
  the test suite. You could also use the special test engine that [Ktor provides](https://ktor.io/docs/testing.html),
  however my preference is to always start a full version of the server so that HTTP behaviour can be tested without
  relying on special internal mechanisms.
- Code coverage and reporting performed automatically by Kover as part of the Gradle build