Common Code
Build configuration
You have to declare the dependencies on one of the kvision-server-*
modules in the common target.
Implementation
The common sources is the place where you define how your remote services should look and how they should work. You can define as many services as you wish, and they can have as many methods as you need. It's a good practice to split your services based on their context and functions.
Note: When using authentication on the server side, you can usually apply different authentication options to different services.
Note: This guide assumes you are using KVision compiler plugin to generate code for server-side interfaces. You can write this code manually if you want - for details please check the guide for KVision 1.x.
Declaring an interface
Designing the interface is probably the most important step, and during this process you have to stick to some important rules.
An interface name need to start with 'I'
and end with 'Service'
phrases and must be annotated with @KVService
annotation.
'I'
and end with 'Service'
phrases and must be annotated with @KVService
annotation.This convention allows KVision compiler plugin to generate common, backend and frontend code.
A method must be suspending
This requirement allows the framework to translate asynchronous calls into synchronous-like code.
A method must have from zero to six parameters
This is the restriction of the current version of the framework. It may change in the future.
A method can't return nullable value
Unit
return type is not supported as well.
Method parameters and return value must be of supported types
Supported types are:
all basic Kotlin types (
String
,Boolean
,Int
,Long
,Short
,Char
,Byte
,Float
,Double
)Enum
classes defined in common code annotated with@Serializable
annotationAll date and time types from
io.kvision.types
package, which are automatically mapped tokotlin.js.Date
on the frontend side and the appropriatejava.time.*
type on the backend sideA
io.kvision.types.Decimal
type, which is automatically mapped toDouble
on the frontend side andjava.math.BigDecimal
on the backend sideany class defined in the common code with a
@Serializable
annotationa
List<T>
, where T is one of the above typesa
T?
, where T is one of the above types (allowed only as method parameters - see previous rule)a
Result<T>
, where T is one of the above types, can be used as a method return value.
Note: Default parameters values are supported.
Even with the above restrictions, the set of supported types is quite rich and you should be able to model almost any use case for your applications. With the help of @Serializable
annotation you can always wrap any data structure into a serializable data class. It's also a simple way to pass around the parameters count limit.
Note: You have to add @Contextual
annotations to your LocalDate
, LocalDateTime
, LocalTime
, OffsetDateTime,
OffsetTime, ZonedDateTime
and Decimal
fields in order to explicitly allow serialization with the KVision context. You can also use @file:UseContextualSerialization(LocalDate::class)
file annotation if you want to keep your model classes cleaner. You can find more information about this annotation in the kotlinx.serialization documentation.
With an interface defined in the common code, the type safety of your whole application is forced at a compile time. Any incompatibility between the frontend and the backend code will be marked as a compile-time error.
Using annotations to change HTTP method and/or route name
By default KVision will use HTTP POST server calls and automatically generated route names. But you can use @KVBinding
, @KVBindingMethod
and @KVBindingRoute
annotations on any interface method, to change the default values.
Note: All KVision endpoint names (even those with user defined names) are prefixed with "/kv/" to avoid potential conflicts with other endpoints.
Last updated