Logo der codecentric AG, einem in Deutschland führenden IT-Consulting Unternehmen

Logo der codecentric AG einem in Deutschland führenden IT-Consulting Unternehmen

Cloud-Native

Data & Machine Learning

Generative KI

IT-Security

Produktentwicklung

Weitere Leistungen...

Leistungen

Arbeitsweise

Projekte

Berlin

Bielefeld

Dortmund

Erfurt

Frankfurt am Main

Hamburg

Karlsruhe

Leipzig

München

Münster

Nürnberg

Solingen

Stuttgart

Standorte

Blog

Softwerker

Fachmedien

Webinare

Events

Wissens-Hub

Unsere Kultur

Kultur & Karriere Podcast

Deine Entwicklung

Jobs

Karriere

Über uns

Aktuelles

Kontakt

Alle Standorte

Du hast Fragen oder möchtest dich mit mir austauschen? Gern – trag einfach deine Kontaktdaten ein.

Contact Us | Sub-Navi-Kontakt oder Zero Search Hits

Kontakt aufnehmen

Marketing & Community Management

Konntest du keine Einträge zu deinem Thema finden?  

STANDORT-TEAM

codecentric Team Leipzig

Unser codecentric Team am Standort Leipzig stellt sich vor.

Willkommen im Team Leipzig

In diesem Artikel gehen wir darauf ein, wie mithilfe des Spring-Webflux-Projekts eine reaktive Anwendung erstellt werden kann und welche Herausforderungen dieser Ansatz mit sich bringt. Wir erläutern kurz, was Kotlin Coroutines sind und zeigen, wie die Herausforderungen des Reactive Programmings mit Spring Webflux mit einer Implementierung in Kotlin Coroutines umgangen oder zumindest abgefedert werden können.

## Reactive Programming mit Spring Webflux
In einem [vorangegangenen Artikel](https://www.codecentric.de/wissens-hub/blog/reactive-programming-spring-webflux) haben wir eine Einführung ins Reactive Programming und das Spring-Webflux-Projekt gegeben. Den in diesem Artikel genutzten Beispiel-Controller wollen wir hier nochmal aufgreifen. Dieser wurde vollständig reaktiv mit Java, der Reactive Streams API und Spring Webflux implementiert:

```java
@RestController
class CustomerController {

   private final CustomerRepository repository;

   CustomerController(final CustomerRepository repository) {
       this.repository = repository;
   }

   @PostMapping("/customer")
   Mono<Customer> createNewCustomer(@RequestBody Mono<CustomerCreationRequest> request) {
      return request.flatMap( dto -> 
            repository.save(new Customer(dto.firstName(), dto.lastName()))
      );
   }
}

record CustomerCreationRequest(String firstName, String lastName) {}

@Repository
interface CustomerRepository extends ReactiveCrudRepository<Customer, Long> {

   Flux<Customer> findByFirstNameAndLastName(String firstName, String lastName);
}
```

Durch ein HTTP POST gegen die URL `/customer` kann hier ein neues `Customer`-Objekt erzeugt und in der Datenbank persistiert werden. Das Ganze passiert reaktiv, da in der Methode `createNewCustomer()` das `Mono` für den Eingangsparameter `request` mithilfe der `flatMap()`-Methode mit dem reaktiven Repository und dessen `save()`-Methode verknüpft wird. Dadurch kann Spring Webflux dann einen HTTP Request ohne jegliche Blocking IO verarbeiten. 

Es wird in diesem Beispiel jedoch auch deutlich, welche Nachteile das Reactive Programming mit sich bringt. Der Code ist für viele Entwickler komplizierter zu schreiben und zu verstehen. Im Gegensatz zu einem klassischen, imperativen Ansatz, bei dem der Code von oben nach unten ausgeführt wird, muss der Entwickler hier in Verkettungen von Streams denken. Und diese Verkettungen können deutlich komplexer werden als in diesem einfachen Beispiel, wie wir am Ende dieses Artikels zeigen werden. Diese Art des Denkens ist für viele Entwickler ungewohnt und stellt damit zunächst eine Hürde für die Nutzung von Reactive Programming dar. Wir werden im Folgenden zeigen, wie man mithilfe von Kotlin Coroutines das gewohnte imperative Programmiermodell auch für die Implementierung reaktiver Anwendungen nutzen kann.

## Kotlin und Coroutines
Das zentrale Element für die Implementierung von Nebenläufigkeit in Kotlin sind die sog. *Coroutines*. Dabei handelt es sich, ähnlich wie bei Threads, um Programmabläufe, die parallel zueinander ausgeführt werden können. Im Gegensatz zu Threads sind Coroutines aber sehr leichtgewichtig und können zu Tausenden nebeneinander gestartet werden. Das ist möglich, weil Coroutines mithilfe sog. *Worker-Threads* implementiert werden. Dabei gibt es einen festen Pool von Threads, der sich um die Ausführung aller Coroutines im Hintergrund kümmert. Eine Coroutine kann an bestimmten Punkten während der Ausführung unterbrochen werden und zu einem späteren Zeitpunkt von einem anderen Thread weiter bearbeitet werden. Wann diese Thread-Wechsel passieren ist für den Entwickler transparent und wird von der Kotlin Runtime entschieden. Für einen tiefergehenden Einblick in Coroutines verweisen wir auf den Einführungsartikel [hier](https://www.codecentric.de/wissens-hub/blog/einfuehrung-in-kotlin-coroutines) im Blog.

### Controller mit Suspend Function
Fest verbunden mit Coroutines sind in Kotlin die sog. *suspend functions*. Diese Funktionen werden innerhalb einer Coroutine ausgeführt und erlauben es, unterbrochen zu werden (deshalb *suspend*). Die zugehörige Coroutine wird dabei dann auch unterbrochen, was letztendlich bedeutet, dass sie keinem Thread aus dem Thread-Pool mehr zugeordnet wird. Diesen Mechanismus können wir uns zunutze machen, um Reactive Programming mit einem imperativen Programmiermodell umzusetzen. Betrachten wir dazu die Implementierung unseres Beispiel-Controllers mit Kotlin:

```kotlin
@RestController
class CustomerController(
   private val repository: CustomerRepository
) {

   @PostMapping("/customer")
   suspend fun createNewCustomer(@RequestBody request: Flow<CustomerCreationRequest>): Customer {
      val dto = request.single()
      return repository.save(Customer(dto.firstName, dto.lastName))
   }
}

data class CustomerCreationRequest(val firstName: String, val lastName: String)

@Repository
interface CustomerRepository : CoroutineCrudRepository<Customer, Long>{

   fun findByFirstNameAndLastName(firstName: String, lastName: String): Flow<Customer>
}
```

Neben der etwas kompakteren Schreibweise, die uns Kotlin erlaubt, fällt gleich auf, dass die beiden Monos verschwunden sind. Außerdem wird auch die `flatMap()`-Methode nicht mehr verwendet. Die Methode `createNewCustomer()` gibt direkt das `Customer`-Objekt zurück. Trotz dieser Änderungen ist der Controller vollständig non-blocking. Der Trick ist hier das Schlüsselwort `suspend`. Dadurch kann diese Methode immer dann unterbrochen werden, wenn sie eine andere *suspend function* aufruft. Und das wiederum erlaubt es Spring Webflux (genauer, der *InvocableHandlerMethod*), den Aufruf dieser Methode in einem `Mono` zu verpacken. Das resultierende `Mono` emittiert also genau dann das `Customer`-Objekt, wenn obige *suspend function* von der Coroutine abgearbeitet wurde. Dadurch können wir als Entwickler uns das `Mono` als Rückgabetyp ersparen. 

Eine weitere Auffälligkeit ist der Typ des Parameters `request`. Dieser hat sich von `Mono` zu `Flow` geändert. Dabei handelt es sich um eine Abstraktion von Kotlin, die als eine Vereinigung der Reactive Streams Publisher `Mono` und `Flux` betrachtet werden kann. Anders als in der Reactive Streams API wurde `Flow` aber vor allem deshalb eingeführt, um zu erlauben, dass Coroutines asynchron einen Stream von Objekten austauschen können (siehe auch <a href="https://kotlinlang.org/docs/flow.html" target="_blank">hier</a> in der Kotlin-Dokumentation). In unserem Fall möchten wir in der Methode `createNewCustomer()` darauf warten, dass ein `CustomerCreationRequest` verfügbar wird. Der Aufruf der `single()`-Methode (ebenfalls eine *suspend function*) wird die Ausführung daher so lange unterbrechen, bis ein Request-Objekt (durch Spring Webflux) verfügbar wird. Anschließend wird die Ausführung innerhalb der Coroutine fortgesetzt, ein `Customer`-Objekt erzeugt und die suspend function `save()` des Repositorys aufgerufen. Auch dieser Aufruf wird wieder zu einer Unterbrechung führen, bis die Persistierung in der Datenbank abgeschlossen ist. Erst dann wird die Coroutine weiterlaufen und das persistierte `Customer`-Objekt als Ergebnis zurückliefern. Der Sourcecode sieht fast wie in einem klassischen imperativen Programmiermodell aus, durch die Möglichkeit der Unterbrechung der Methode ist aber eine Ausführung wie in einem Reactive-Ansatz möglich. Der Entwickler muss sich damit aber gedanklich kaum beschäftigen, was die Komplexität deutlich reduziert.

### Komplexeres Beispiel
Um die mögliche Reduktion der Komplexität nochmal deutlicher zu zeigen, möchten wir abschließend unser Beispiel durch eine komplexere Abfrage ergänzen. Dabei sollen alle `Customer`-Objekte anhand ihrer Kundengruppe abgefragt werden. Der reaktive Java-Code dieser Abfrage sieht wie folgt aus:

```java
@GetMapping("/search/customerGroup/{customerGroup}")
Flux<Customer> findByCustomerGroup(@PathVariable final String customerGroup) {
   return webClient.getCustomerGroup(customerGroup)
           .flatMapMany(group ->
                   Flux.concat(
                           group.entries()
                                   .stream()
                                   .map(entry -> repository.findByFirstNameAndLastName(entry.firstName(), entry.lastName()))
                                   .toList()
                   )
           );
}
```

Zunächst wird mithilfe eines Webclients eine REST-API eines anderen Services aufgerufen, um den Namen der Kundengruppe zu einer Liste von Kundennamen aufzulösen. Diese Liste kann dann anschließend benutzt werden, um aus dem oben bereits genutzten Repository die tatsächlichen `Customer`-Objekte auszulesen. Sowohl der Aufruf der REST-API als auch der Aufruf des Repositorys sind dabei non-blocking und nutzten `Mono` bzw. `Flux` als Rückgabewert. Diese müssen dann wieder miteinander verkettet werden (diesmal mit den `flatMapMany()`- und `Flux.concat()`-Methoden). Der ungeübte Entwickler wird hier einen Augenblick brauchen, um genau zu verstehen, wie die einzelnen Aufrufe zusammenhängen. Und selbst viele geübte Entwickler werden diesen Code nicht ohne Weiteres runterschreiben können. Die Kotlin-Implementierung dieses Beispiels ist nicht nur einfacher zu verstehen, sondern einer klassischen imperativen Implementierung auch deutlich ähnlicher:

```kotlin
@GetMapping("/search/customerGroup/{customerGroup}")
suspend fun findByCustomerGroup(@PathVariable customerGroup: String): Flow<Customer> {
   val group = webClient.getCustomerGroup(customerGroup)
   return group
       .entries
       .map { repository.findByFirstNameAndLastName(it.firstName, it.lastName) }
       .merge()
}
```

Hier gibt es noch eine Besonderheit. In Kotlin hat es sich als Best Practice etabliert, dass eine Methode mit Rückgabewert `Flow` keine *suspend function* sein sollte, sondern stattdessen unmittelbar den `Flow` zurückgibt. Eventuelle Aufrufe von blockierenden oder *suspending functions* innerhalb dieser Methode werden dabei in die Ausführung des `Flow` selbst verschoben. Dies lässt sich in obiger Methode leicht erreichen, indem man den Methodenkörper in einen `flow { ... }` Builder einbettet und die `return`-Anweisung durch ein `emitAll()` ersetzt. Durch Kotlins ausdrucksstarke Syntax fällt diese Änderung kaum auf, ist für einen Entwickler des klassischen, imperativen Ansatzes dennoch weniger vertraut. Aus unserer Sicht sind für eine Controller-Methode beide Varianten akzeptable Lösungen:

```kotlin
@GetMapping("/search/customerGroup/{customerGroup}")
fun findByCustomerGroup(@PathVariable customerGroup: String) = flow {
   val group = webClient.getCustomerGroup(customerGroup)
   emitAll(group
      .entries
      .map { repository.findByFirstNameAndLastName(it.firstName, it.lastName) }
      .merge())
}
```

## Fazit
Wir hoffen, wir konnten mit den obigen Beispielen zeigen, dass in Java ein Reactive-Ansatz wie Spring Webflux eine kognitive Belastung für die Entwickler mitbringen kann und dass es möglich ist, diese durch die Benutzung von Kotlin Coroutines bzw. *suspend functions* zu reduzieren. Gerade Entwicklern, die bisher eher im Blocking-IO-Umfeld Erfahrung gesammelt haben (z. B. mit Spring MVC), kann der Umstieg in die Non-blocking-Welt vereinfacht werden, wenn man dabei die von Kotlin angebotenen Konzepte nutzt.

Ein tolles Paar: Spring Webflux und Kotlin Coroutines

Reactive Programming mit Spring Webflux

Consultant & Developer

IT Consultant & Developer

Senior IT Consultant & Developer

<p><span>In this blog post, I will demonstrate how you can deploy an application to AWS Fargate using the AWS CDK. The WordPress software is used, which introduces some requirements. So Elastic File System and Aurora Serverless database will be deployed, too.</span></p><p><span>As an example, think of a website for an event that allows for registration at a specific time. Or there are thousands of people trying to register for a very limited course that many want to attend. Everyone knows the registration likely is available during a 10 minute time frame twice a year as it is instantly fully booked. Now they are hitting the page reload button. An approach to counter such situations is a service named AWS Fargate, which provides computing resources. You don’t have to choose instance types or any other unit in advance. Amazon provides resources as needed by the workload. This is very useful if the usage pattern of the deployed application is extremely volatile and you don’t want to spend time evaluating the best amount of computing resources to handle the load. Maybe there is a database that has to be scaled with your workload.</span></p><h2>Overview</h2><p>To get an idea about the moving parts we need to create, I will provide an image showing the amazon products involved, more details will follow.</p><p><img src="https://eu-central-1.graphassets.com/AiE4QoWSSiIQO3k152ugkz/1xJHJoqCQFWqqkcwMb1o" alt="overview AWS fargate" width="708" height="341" /></p><h2><h2>Bootstrap</h2><p>Before we start, you have to create the project files. For your convenience, the AWS CDK provides a command to generate some boilerplate code. Install the CDK and create an empty directory. After that, initialize your project.</p>

```
npm install -g aws-cdk
mkdir project && cd project
cdk init --language=python --generate-only
```

<h2><h2>Docker build and push</h2><p>First, we build the Fargate task in the private section. The task serving the WordPress site needs an image, from which the container can be created from. <a href="https://hub.docker.com/_/wordpress" target="_blank"><span>Prebuilt images</span></a> <span> are available for download from the official docker hub. That image will be used to spin up a container in an ECS cluster.</span></p><p><span>You will notice that the <strong>default</strong> images have a maximum HTTP post size of <strong>2 MB</strong> configured, which is not enough if you want to upload larger plugins or media files. To configure the parameters affecting that limit, you have to create or modify some files inside the image. If you do this in local docker or in Kubernetes, you simply mount a file or a config to the container. Fargate does not have such a mechanism. It would be quite nice to mount a file from s3. Amazon is currently <a href="https://github.com/aws/containers-roadmap/issues/56">working on it</a> , but the feature is not completed yet. Another option would be to place a file in an EFS volume. But the AWS CDK <a href="https://github.com/aws/aws-cdk/issues/9496">lacks an upload feature</a>  as known from s3. A different approach is to build your own images, based on the official ones. They can be uploaded to ECR for later usage. To build an image in AWS CDK, you need the context path and a dockerfile:</span></p>

```
# docker context directory
docker_context_path = os.path.dirname(__file__) + "../../src"

# upload images to ecr
nginx_image = ecr_assets.DockerImageAsset(
    self, "Nginx",
    directory=docker_context_path,
    file="Docker.nginx",
)

wordpress_image = ecr_assets.DockerImageAsset(
    self, "Php",
    directory=docker_context_path,
    file="Docker.wordpress",
)
```

<p>That’s it! The AWS CDK detects whether a build is needed and will upload the resulting image to <a href="https://aws.amazon.com/ecr/">ECR</a> . To configure PHP to allow more than the 2 MB limit for file upload, create a file containing</p>

```
file_uploads = On
memory_limit = 64M
upload_max_filesize = 64M
post_max_size = 64M
max_execution_time = 600
```

<p>and include the path in your dockerfile.</p><p>As you can see in the CDK code above, there are two docker images. I prefer to have a single process per container as this is a cleaner approach. The downside is greater complexity when it comes to communication between the processes.</p><p>To allow Nginx to send messages to the PHP process, it needs a network address and port. To allow some local test, you can configure the endpoint at build time:</p>

```
ARG upstream_wordpress_php=localhost

COPY ./nginx/conf.d/http.conf /etc/nginx/conf.d/default.conf

RUN echo -e "upstream wordpress_php {\n  server $upstream_wordpress_php:9000;\n}\n" \
    > /etc/nginx/conf.d/upstream.conf
```

<p>This allows the usage of a local <a href="https://github.com/dhenne/aws-cdk-fargate-aurora-wordpress-example/blob/main/src/docker-compose.yml">docker-compose.yml</a> , to enable a local spin-up of a WordPress site. In Fargate all containers of a task are reachable through the loopback device. Amazon uses a network mode called <a href="https://aws.amazon.com/blogs/compute/task-networking-in-aws-fargate/">awsvpc</a> . Now that we have an image, we are able to define our Fargate task. The image object can be passed directly to the task definition. The AWS CDK takes care of all tasks needed to have the correct image used.</p><h2><h2>Fargate task definition</h2>

```
event_task = ecs.FargateTaskDefinition(self, "WordpressTask")

app_container = event_task.add_container(
    "Php",
    image=ecs.ContainerImage.from_docker_image_asset(wordpress_image)
)
nginx_container = event_task.add_container(
    "Nginx",
    image=ecs.ContainerImage.from_docker_image_asset(nginx_image)
)
```

<p><strong>Note:</strong> The strings to name the resources are meaningless. In AWS, a common pattern is to name your resources with capitalized letters.</p><p>Now you can create an ECS cluster and place your task definition on it. At this point, it is very important to specify the Fargate version to <strong>1.4</strong>. People at AWS have decided that the “latest” platform version <a href="https://docs.aws.amazon.com/AmazonECS/latest/developerguide/platform_versions.html">in fact means the “penultimate” version</a> .</p>

```
cluster = ecs.Cluster(
    self, 'ComputeResourceProvider',
    vpc=properties.vpc
)

wordpress_service = ecs.FargateService(
    self, "InternalService",
    task_definition=event_task,
    platform_version=ecs.FargatePlatformVersion.VERSION1_4,
    cluster=cluster,
)
```

<p>Now you would be able to start a task. There’s one thing more to do. We have to specify a <a href="https://github.com/aws/aws-cdk/issues/10113">port mapping for each container</a> , even though we may not need it. This can be done using the following.</p>

```
nginx_container.add_port_mappings(
    ecs.PortMapping(container_port=80)
)
```



```
app_container.add_port_mappings(
    ecs.PortMapping(container_port=9000)
)
```

<h2><h2>Database</h2><p><span>You can now start a task, but there are still some parts missing. We do need some persistence for files and structured data (SQL). As stated before, an Aurora Serverless database provides the SQL service for our task. The definition is straight forward:</span></p>

```
database = rds.ServerlessCluster(
    self, "WordpressServerless",
    engine=rds.DatabaseClusterEngine.AURORA_MYSQL,
    default_database_name="WordpressDatabase",
    vpc=properties.vpc,
    scaling=rds.ServerlessScalingOptions(
        auto_pause=core.Duration.seconds(0)
    ),
    deletion_protection=False,
    backup_retention=core.Duration.days(7),
    removal_policy=core.RemovalPolicy.DESTROY,
)
```

<p>A secret and a database are automatically created. To pass the values to the WordPress container, you can reference them directly. The AWS CDK creates appropriate roles and permissions to apply to the task that allows the retrieval of secret values.</p>

```
app_container = event_task.add_container(
    "Php",
    environment={
        'WORDPRESS_DB_HOST': database.cluster_endpoint.hostname,
        'WORDPRESS_TABLE_PREFIX': 'wp_'
    },
    secrets={
        'WORDPRESS_DB_USER':
            ecs.Secret.from_secrets_manager(database.secret, field="username"),
        'WORDPRESS_DB_PASSWORD':
            ecs.Secret.from_secrets_manager(database.secret, field="password"),
        'WORDPRESS_DB_NAME':
            ecs.Secret.from_secrets_manager(database.secret, field="dbname"),
    },
    image=ecs.ContainerImage.from_docker_image_asset(wordpress_image)
)
```

<h2><h2>Elastic File System</h2><p><span>WordPress is an application written in PHP and extendable by plugins. All that functionality is relying on a writable filesystem, where the PHP user can place its files, so everything can be done through the web interface. Therefore you need a shared filesystem that can be mounted to the container running the PHP process. Since </span><a href="https://aws.amazon.com/de/about-aws/whats-new/2020/04/amazon-ecs-aws-fargate-support-amazon-efs-filesystems-generally-available/" target="_blank"><span>last year</span></a> <span>, attaching an EFS to Fargate task definitions has generally been available. More details about persistent storage in amazon ECS is available in the <a href="https://aws.amazon.com/blogs/compute/task-networking-in-aws-fargate/">aws documentation</a> . Create your EFS storage and define a volume.</span></p>

```
file_system = efs.FileSystem(
    self, "WebRoot",
    vpc=properties.vpc,
    performance_mode=efs.PerformanceMode.GENERAL_PURPOSE,
    throughput_mode=efs.ThroughputMode.BURSTING,
)
```



```
wordpress_volume = ecs.Volume(
    name="WebRoot",
    efs_volume_configuration=ecs.EfsVolumeConfiguration(
        file_system_id=file_system.file_system_id
    )
)
```

<p>Later that volume can be used to extend your task definition.</p>

```
event_task = ecs.FargateTaskDefinition(
    self, "WordpressTask",
    volumes=[wordpress_volume]
)
```

<p>Now, this volume is available to container mounts in your task definition. WordPress needs write access to that volume. Read permissions are sufficient for Nginx.</p>

```
nginx_container_volume_mount_point = ecs.MountPoint(
    read_only=True,
    container_path="/var/www/html",
    source_volume=wordpress_volume.name
)
nginx_container.add_mount_points(nginx_container_volume_mount_point)
```



```
container_volume_mount_point = ecs.MountPoint(
    read_only=False,
    container_path="/var/www/html",
    source_volume=wordpress_volume.name
)
app_container.add_mount_points(container_volume_mount_point)


```

<h2><h2>Networking</h2><p>The final part of the deployment is about network connectivity. You may have noticed the VPC parameter before. We can create this VPC or use a preexisting one. In my example repository you have the whole network-related resources, separated in a different stack, to be reusable by several other stacks. You can have a look at the <a href="https://github.com/dhenne/aws-cdk-fargate-aurora-wordpress-example/blob/main/cdk_stacks/network.py">file</a> . There are two different network types created and endpoints of a load balancer are placed in the public subnet. The result looks like the following picture.</p><p><img loading="lazy" width="738" height="701" src="https://eu-central-1.graphassets.com/AiE4QoWSSiIQO3k152ugkz/7aaZ1hC5SzGa9yuHewiR" alt="context path and docker file" /></p><p>The VPC and the load balancer are then passed to the WordPress stack as property objects. You can also create a parent stack around the constructs, but I think you get the point. Note that there is an upper limit of stacks per account. If you have too many, you can use nested stacks.</p><p> </p><p>To allow the Fargate tasks to connect to the elastic filesystem and the Aurora Serverless database, add them to the appropriate security groups:</p>

```
database.connections.allow_default_port_from(wordpress_service)
file_system.connections.allow_default_port_from(wordpress_service)
```

<p>In this blog post, an application load balancer is used to provide an endpoint to which the outside users can connect. The Fargate tasks are automatically added to the targets of this load balancer as they are created. You simply have to define a listener and configure your load balancer watch for the WordPress service. You also can apply some rules to the listener affecting request routing. But there is only one site delivered at the moment. If the WordPress site is not initialized yet, then it is redirecting requests to an installation page. Therefore the load balancer health checks have to accept that redirect as successful. To achieve that, the HTTP Code 302 can be added to the list of acceptable return codes.</p>

```
http_listener = properties.load_balancer.add_listener(
    "HttpListener",
    port=80,
)

http_listener.add_targets(
    "HttpServiceTarget",
    protocol=elbv2.ApplicationProtocol.HTTP,
    targets=[wordpress_service],
    health_check=elbv2.HealthCheck(healthy_http_codes="200,301,302")
)
```

<h2><h2>Deploy</h2><p>When you are done defining your stacks, all resources can be deployed using the deploy command. This takes a few minutes and outputs information about created instances. You can read about the whole process <a href="https://docs.aws.amazon.com/cdk/latest/guide/apps.html">here</a> . In short, the CDK command synthesizes the code to cloud assemblies, which contain the images and cloudformation templates. After creation, the artifacts are uploaded to AWS.</p>

```
cdk deploy --require-approval never --all
```

<p>I have stripped out the progress bar and other elements of less relevance. You can see the ExternalDNSName the deployed WordPress instance is reachable at. In production scenarios, you should use HTTPS certificates and a suitable name for your users. Both can be done using the AWS CDK.<br /> <img loading="lazy" width="1024" height="101" src="https://eu-central-1.graphassets.com/AiE4QoWSSiIQO3k152ugkz/uYZfnpvoReCMXQIx08bC" alt="configure file" /></p><h2><h2>Tests</h2><p>As you define your infrastructure as code, this code can be tested and validated. You can write simple unit tests using your favorite test suite and scan the generated AWS cloud formation templates. This can be checked against what you expect. As I am using python, there are already testing frameworks available.</p><p>To get a reusable snippet of code, which synthesizes your template, add a fixture:</p>

```
@pytest.fixture()
def template():
    app = core.App()
    NetworkStack(app, "NetworkStackTest")
    return json.dumps(app.synth().get_stack("NetworkStackTest").template)
```

<p>Later this can be used to get a template and check the content using asserts. As an example, you can check that a VPC is defined.</p>

```
def test_vpc_created(template):
    assert("AWS::EC2::VPC" in template)
```

<h2><h2>Conclusion</h2><p>AWS CDK is a very convenient tool for deploying resources to AWS. There are many native AWS mechanisms used so that constructs are easily integrated into existing environments. With a few lines of source code you can define a lot of functionality, as you don’t have to define all resources needed by yourself. The complete code of this blog post is available in the example <a href="https://github.com/dhenne/aws-cdk-fargate-aurora-wordpress-example">Github repository</a> . Give it a try!</p></h2></h2></h2></h2></h2></h2></h2></h2></h2>

Fargate with EFS and Aurora Serverless using AWS CDK

In this post you will learn what GitOps is about and see the steps to create a setup on your laptop to gain some experience with ArgoCD. Using an industry standard container orchestrator such as Kubernetes, this enables developers to continuously deploy their applications.

There is a huge number of options available to deploy artifacts. A widely adopted 
approach uses the <a href='https://github.com/opencontainers/image-spec' target='_blank'>OCI image format</a> to ship your software. A continuous integration pipeline builds the software and creates an artifact. The image can then be deployed by a container orchestrator, i.e. Kubernetes. 

Furthermore, development teams are responsible for the entirety of their applications. Defining the infrastructure and the process as code is crucial
to not reducing efficiency and velocity while keeping all actions reproducible and tackling complexity. Tools such as Terraform and Helm can read a definition and be executed as part of a pipeline to push changes to achieve the desired state.

## The GitOps principles

While traditional pipelines and the tools within such as GitHub Actions or GitLab CI/CD are executed whenever a specific event like a *git push* happens, the GitOps principle works the other way around.
The largest difference is that the desired state is continuously pulled from a source such as a VCS repository to drive the infrastructure. This pattern is called a *reconciliation loop* and matches with the Kubernetes <a href='https://kubernetes.io/docs/concepts/extend-kubernetes/operator/' target='_blank'>operator pattern</a>. 

There are many tools out there that leverage the Kubernetes CRDs as input to define the desired state and apply them by operators.

The elements of GitOps can be described by four principles. 

* Declarative infrastructure
* Desired state is stored versioned and immutable
* Pulled automatically from source code
* Continuously reconciled by software agents

The CNCF hosts the project <a href='https://opengitops.dev/' target='_blank'>OpenGitOps</a> which is an attempt to define an open standard.

## ArgoCD

As stated before, in this blog post we will take a closer look at ArgoCD. This tool focuses on Continuous Delivery of applications to Kubernetes.  

For this purpose, ArgoCD monitors a source and creates the API objects out of its definitions files. A lot of options are available starting from plain YAML files to Helm Charts and Kustomize. Even custom <a href='https://argo-cd.readthedocs.io/en/stable/user-guide/config-management-plugins/' target='_blank'>plugins</a> are possible, which is very handy in migration scenarios or if the need for any custom integrations are a usual pattern in your organization. The core concepts of ArgoCD can be found at <a href='https://argo-cd.readthedocs.io/en/stable/core_concepts' target='_blank'>https://argo-cd.readthedocs.io/en/stable/core_concepts</a>. 

ArgoCD is an excellent fit in our mission to deliver our high-value applications at best-in-class velocity to users.

### Installation

Now it is time to take our first steps into our GitOps journey and try out ArgoCD. First, we need
a Kubernetes cluster to deploy to. I will use Minikube here, but every other distribution will do the job. Simply install <a href='https://minikube.sigs.k8s.io/docs/start/' target='_blank'>Minikube</a> and start your local cluster:

```
minikube start --driver=docker
```

After your kubectl tool is configured and you can access your cluster, clone the demo repository and install ArgoCD.

```
git clone git@github.com:dhenne/minikube-argocd-traefik-example.git
```

There is a `bootstrap-argo-cd` chart in the folder `charts/`, which can be used to bootstrap your ArgoCD installation using the helm CLI tool. Later we will use this instance of ArgoCD to manage itself. 


```
cd minikube-argocd-traefik-example/charts/bootstrap-argo-cd/
helm dependency build
helm install argo-cd .
```


After all images are downloaded and the pods are started, you should see a few pods running:

*kubectl get pods*
```
NAME                                                       READY   STATUS    RESTARTS   AGE
argo-cd-argocd-application-controller-0                    1/1     Running   0          52s
argo-cd-argocd-applicationset-controller-bf44c7bc9-2k4w9   1/1     Running   0          53s
argo-cd-argocd-dex-server-8676995c89-7pb5x                 1/1     Running   0          53s
argo-cd-argocd-notifications-controller-7d9d94f45d-rk5kh   1/1     Running   0          53s
argo-cd-argocd-redis-6749667d89-7prsk                      1/1     Running   0          53s
argo-cd-argocd-repo-server-58b8864fc7-kvtln                1/1     Running   0          53s
argo-cd-argocd-server-78fd54c49d-dvv7d                     1/1     Running   0          53s
```

Nice! To interact with the installation and check out what is going on, we can use the UI. The password can be found inside a secret which is automatically created if not disabled by a configuration parameter. Get yours with `kubectl -n default get secret argocd-initial-admin-secret -o jsonpath="{.data.password}" | base64 -d` forwarding a port to your workspace using the command `kubectl port-forward service/argo-cd-argocd-server -n default 8080:443 &` and browse to http://localhost:8080.

After login with the user `admin` you can see there are no applications deployed yet.

![no-applications-yet.png](https://eu-central-1.graphassets.com/AiE4QoWSSiIQO3k152ugkz/qRtVD5jDTyXSKRcVe8gF)

Congratulations, now we can start delivering!

### Apps-of-apps pattern

ArgoCD introduces an <a href='https://argo-cd.readthedocs.io/en/stable/operator-manual/cluster-bootstrapping/#app-of-apps-pattern' target='_blank'>app-of-apps pattern</a>. As applications can be defined in CRDs, applications can be part of an application. This can be used as a starting point to define which applications have to be deployed.

To demonstrate this, there is a root application defined inside the example repository. The definition contains the path pointing to the demo repository:

*charts/root/templates/root.yaml*
```
...
  source:
    repoURL: https://github.com/dhenne/minikube-argocd-traefik-example.git
    path: charts/root
    targetRevision: HEAD
...
```

The root application of the demo project includes another definition for ArgoCD. Unlike before, the source is a Helm repository. This definition causes ArgoCD to match the previously installed instance and therefore to manage itself. Now you are enabled to get <a href='https://docs.renovatebot.com/modules/manager/argocd/' target='_blank'>automated updates using Renovate</a> to update your installation!  

*<a href='https://github.com/dhenne/minikube-argocd-traefik-example/blob/main/charts/root/templates/argo-cd.yaml' target='_blank'>charts/root/tempaltes/argo-cd.yaml</a>*
```
...
  source:
    repoURL: https://argoproj.github.io/argo-helm
    chart: argo-cd
    targetRevision: 5.4.3
...
```

Use *kubectl apply* to instruct pulling the state from GitHub and apply the defined state:

```
kubectl apply -f charts/root/templates/root.yaml
```

Now watch the state changing until there are some apps including Root and ArgoCD: 

![root-and-argocd.png](https://eu-central-1.graphassets.com/AiE4QoWSSiIQO3k152ugkz/IfjtNg9SyeUNvY4jweIw)

NOTE: To keep your namespace clean, unlink the ArgoCD instance from your local Helm CLI: `kubectl delete secret -l owner=helm,name=argo-cd` 

Now you can explore the great UI from ArgoCD. Everything is clean and focused on purpose. As mentioned in the core concepts before, there are buttons labeled *refresh* and *sync*. Refreshing causes to poll the source repositories and their state. After that, a sync applies the changes needed to ensure the defined state is in place. If auto sync is enabled, then a sync is done immediately after a refresh causing an out-of-sync state. 

Another very helpful use case is to explore your deployment and get an idea of all parts and their state. If we drill down the `argo-cd` app, there are a lot of resources deployed. It's a lot of work to get an idea of all parts. But within the ArgoCD UI, everything is well organized and it's easy to check out all parts in detail. In fact, there are 47 resources. All relations definitions states, logs, and events are a few clicks away. Even parts that are paid less attention to such as replica sets or endpoints fit nicely into the big picture.

## Application gitopsified

![gitopsify-all-the-things.jpg](https://eu-central-1.graphassets.com/AiE4QoWSSiIQO3k152ugkz/a2QZLvT8RrqBpVWl0uTx)

It's time for additional proof of the ability to deploy our apps. The <a href='https://github.com/dhenne/minikube-argocd-traefik-example/' target='_blank'>demo repository</a> mentioned before can be seen as a widely used pattern of a GitOps repository. There you can find definitions of the desired state, but the source code can be found in a separate repository. In this article, I will demonstrate a slightly different approach. We only define which applications will be deployed and the desired state is placed in your application's source code repositories. Developers then have to do all their changes inside one repository, without the need to keep an eye on the GitOps repository. Of course, you can achieve that using custom pipelines and other tools, but we want a GitOps-style approach here that polls information instead of pushing it to the GitOps repo. On top of that, ArgoCD is our tool of choice here, and it can achieve that. Why should we bother with custom self-made approaches? Be aware that configuration in source code repositories can be considered a violation of <a href='https://argo-cd.readthedocs.io/en/stable/user-guide/best_practices/#best-practices' target='_blank'>best practices</a>, so prepare yourself for a good discussion (maybe with this article). 

While there's a <a href='https://github.com/argoproj/argo-cd/blob/master/docs/proposals/multiple-sources-for-applications.md' target=_blank>proposal</a>, which aims at first-class support of multiple sources for our definitions, we have to use ArgoCD <a href='https://argocd-applicationset.readthedocs.io/en/stable/Generators/' target='_blank'>generators</a> to use multiple sources to define our state. Generators are included within the ApplicationsSet feature, which has been fully <a href='https://github.com/argoproj/applicationset/releases/tag/v0.4.0' target=''>integrated into the ArgoCD installation</a> since 2022. ApplicationSets are a great option to template your application definitions without Helm or anything else. Therefore, using the <a href='https://argocd-applicationset.readthedocs.io/en/stable/Generators-Git/' target='_blank'>Git Generator</a> can be considered as a first-class approach, too.

There are two options available for the Git Generator. While the *directories* key scans a directory and creates an application for every folder found, the *files* key does the same thing for a file-matching pattern.

![argo-multisource.png](https://eu-central-1.graphassets.com/AiE4QoWSSiIQO3k152ugkz/hx4GsjLORIqFkKBTxXAU)

The demo repository contains another application in the root app named `spring-boot-apps`, which references a Helm Chart consisting of ApplicationSet definitions to demonstrate the two options. Exploring them in the UI can be done in the root app using a link in the application representation. This shortcut is quite handy to move around while using the app-of-apps pattern.

![link-app-of-apps.png](https://eu-central-1.graphassets.com/AiE4QoWSSiIQO3k152ugkz/4pGAq7Qxq7N8Yf8uIsdw)

Following the link, you can see two ApplicationSets, which consist of two applications each for a test and production stage. Let's have a look at both sets.


![spring-boot-apps.png](https://eu-central-1.graphassets.com/AiE4QoWSSiIQO3k152ugkz/8YDMaHsMQemUTUrMieyT)


### Git Generator: Directories

In my opinion, the Directories Generator is the best approach. It generates applications from a pattern that matches folders. Inside the folders, everything that is <a href='https://argo-cd.readthedocs.io/en/stable/user-guide/application_sources/' target='_blank'>supported</a> can be placed. This provides superior flexibility for developers, which encourages people to strive towards a DevOps culture. In the demo repository, you'll find Helm Charts, but it doesn't matter for the application definition and can be swapped to other options in different stages without redefining the ApplicationSet itself. Another advantage worth mentioning is the avoidance of ArgoCD or organization-specific schema of your definitions inside the source code repository. Developers can use their knowledge of existing standards. Below you can find the definition which points to a Spring Boot application.

<a href='https://github.com/dhenne/minikube-argocd-traefik-example/blob/main/charts/spring-boot-apps/templates/springboot-appset-git-directories.yaml' target='_blank'>charts/spring-boot-apps/templates/springboot-appset-git-directories.yaml</a>

```
apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: springboot-appset-git-directories
spec:
  generators:
    - git:
        repoURL: https://github.com/dhenne/spring-boot-service
        revision: HEAD
        directories:
          - path: "deployment/helm/*"
  template:
    metadata:
      name: '{{`{{path.basename}}`}}'
    spec:
      project: default
      source:
        repoURL: https://github.com/dhenne/spring-boot-service
        path: '{{`{{path}}`}}'
        targetRevision: HEAD
      destination:
        server: https://kubernetes.default.svc
        namespace: default
      syncPolicy:
        automated:
          prune: true
          selfHeal: true
```

NOTE: Unlike the files generator, using paths inside hidden folders is not supported, as the folders are <a href='https://github.com/argoproj/argo-cd/blob/02bf903dd9b25c141d073bab3c7588d190145eb3/applicationset/services/repo_service.go#L109' target='_blank'>skipped</a>. 

### Git Generator: Files

Another generator that can be used is the Files Generator that looks for files matching the provided pattern. Each file can then define keys and values in JSON or YAML format. When ArgoCD is generating the applications, values can be used in a template spec to define applications. Think of Helm Charts, then you got the concept. In the demo repository, we use Helm Charts, so we have to exclude ArgoCD templating from the Helm templating engine using Go strings. 

<a href='https://github.com/dhenne/minikube-argocd-traefik-example/blob/main/charts/spring-boot-apps/templates/springboot-appset-git-files.yaml' target='_blank'>charts/spring-boot-apps/templates/springboot-appset-git-files.yaml</a>
```
apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: springboot-appset-git-files
spec:
  generators:
    - git:
        repoURL: https://github.com/dhenne/spring-boot-service
        revision: HEAD
        files:
          - path: "deployment/multisource-files/**.yaml"
  template:
    metadata:
      name: '{{`{{name}}`}}'
    spec:
      project: default
      source:
        repoURL: https://dhenne.github.io/helm-charts/
        chart: spring-boot-helm-demo
        targetRevision: 0.1.6
        helm:
          values: |-
            {{`{{values}}`}}
      destination:
        server: https://kubernetes.default.svc
        namespace: default
      syncPolicy:
        automated:
          prune: true
          selfHeal: true
```

## Developer Workflow

The workflow for developers to deploy new versions consists of a single commit to the application repository. To instruct ArgoCD to deploy a new version, developers only need to adjust the version number inside the configuration file of the correct environment. For example, the test environment of the directories example can be found in the <a href="https://github.com/dhenne/spring-boot-service/blob/main/deployment/helm/springboot-helm-test/values.yaml" target="_blank">values.yaml</a> in the application repository. There is a GitHub workflow to demonstrate an automated version bump, release, and deployment of the <a href="https://github.com/dhenne/spring-boot-service/" target="_blank">spring-boot-service</a> to test environments. The production environments are requiring manual confirmation to allow the workflow to proceed. All information defining the application and the corresponding environments can be found in one place, which is a big advantage of this approach.

## Conclusion

ArgoCD <a href='https://argo-cd.readthedocs.io/en/stable/#why-argo-cd' target='_blank'>promises</a> to provide an easy-to-understand GitOps tool. As we have seen, this is perfectly true. There is a lot of flexibility while keeping things aligned on purpose. The UI is very helpful to drill down into the complexity of large deployments and developers can still use their favorite standard tooling for defining applications in Kubernetes. If you consider digging deeper into the topic, the <a href='https://github.com/terrytangyuan/awesome-argo' target='_blank'>awesome-argo</a> list might be a good start.

Argonauts, to the moon!

### Links

<a href='https://github.com/argoproj/argo-cd' target='_blank'>https://github.com/argoproj/argo-cd</a>

<a href='https://github.com/dhenne/minikube-argocd-traefik-example' target='_target'>https://github.com/dhenne/minikube-argocd-traefik-example</a>





Introduction to GitOps with ArgoCD

IT Consultant

<div><div><p>Mit Kotlin Multiplatform Mobile (KMM) steht ein weiteres Cross-Platform Framework in den Startlöchern. Diesmal geht JetBrains ins Rennen und versucht natürlich alles besser zu machen als alle anderen. Die Frage ist aber: Brauchen wir das wirklich? Ist es einfach nur eine weitere Kopie in neuem Gewand?<br /> Um das herauszufinden, habe ich eine kleine App gebaut und wir schauen uns gemeinsam an, wie das Ganze funktioniert. <a href="https://github.com/darthkali/kmmbikeshare" target="_blank">Hier findet ihr</a>  die Beispiel-App, auf die ich mich im Beitrag beziehe.</p><div><h2><strong>Grundlegender Aufbau von Kotlin Multiplatform Mobile</strong></h2><div><div><p>Starten wir zunächst mit dem Aufbau einer Kotlin Multiplatform Mobile-App. Ein KMM-Projekt basiert in erster Linie auf Modularisierung. Folgt man dem Standardweg von Kotlin, erhält man folgende Struktur:</p></div><div><div><img src="https://eu-central-1.graphassets.com/AiE4QoWSSiIQO3k152ugkz/wZx4FYH6TZikCTxgemlf" alt="Bild zeigt wie die Struktur einer KMM App ist." /></div></div><div><p>Wir haben also ein Android-Modul, ein iOS-Modul und ein shared-Modul. In den Android- bzw. IOS-User-Interface-Modulen implementieren wir hauptsächlich Elemente für das User Interface, während wir die Business- und Datenlogik im shared-Modul umsetzen. Eine strikte Regel für die Abgrenzung gibt es jedoch nicht. Erscheint es für den Anwendungsfall sinnvoll, einen Teil der Businesslogik in die UI-Module zu ziehen, ist das mit Kotlin Multiplatform Mobile ohne Weiteres möglich. Die Implementierungen werden dann nicht zwischen den Systemen geteilt. Diese Flexibilität ist ein großer Vorteil von Kotlin Multiplatform Mobile.</p></div><div><p>Innerhalb des shared-Moduls erfolgt eine Aufteilung in common, iOS und Android Packages. Der größte Teil der Entwicklung findet im common Package statt. Hier liegt in der Regel die komplette Implementierung der Business- und Datenlogik. Also alles von der Implementierung der Datenbank, über die Remoteschnittstelle, bis hin zur Domänenlogik. In die beiden systemspezifischen Packages innerhalb des shared-Moduls kommen nur die Implementierungen, die wir für die jeweiligen Systeme separat entwickeln müssen. Das sind meist nur Treiberimplementierungen oder Ähnliches.</p></div><div><p>Neben den oben genannten Modulen gibt es dann auch das passende Pendant für die Tests. Auch hier erfolgt der Hauptteil im CommonTest Package während wir in den systemspezifischen Packages nur das Setup und die Treiber implementieren.</p></div><div><p>Damit wissen wir nun, wie der ganz grobe Aufbau der App ist. Wie das Ganze im Detail funktioniert, schauen wir uns in den kommenden Abschnitten an.</p></div></div></div><div><h2><strong>expect / actual – was ist das?</strong></h2><div><div><p>Bevor wir uns auf konkrete Implementierungen stürzen, müssen wir vorher noch eine wichtige Funktionalität betrachten. Ich habe im letzten Abschnitt erwähnt, dass wir für manche Anwendungsfälle separate Implementierungen benötigen. Wir brauchen also einen Mechanismus, der eine Weiche darstellt, um jeweils die spezifische Implementierung für die passende Plattform zu kompilieren.<br /> Hierzu kommt das Feature <em>expect / actual</em> zum Einsatz.</p></div><div><div>expect / actual</div><div>

```rouge highlight
// Common
expect fun sharedFunction(parameter: String): String


// iOS
actual fun sharedFunction(parameter: String): String {
    return “this is the iOS implementation”
}


// Android
actual fun sharedFunction(parameter: String): String {
    return “this is the Android implementation”
}
```

</div></div><div><p>Im common Package definieren wir, was implementiert werden soll, ohne jedoch eine direkte Implementierung an dieser Stelle zu erstellen. Das Keyword <em>expect</em> sorgt dafür, dass der Compiler eine Implementierung erwartet. Sie muss den gleichen Namen aufweisen und den gleichen Package-Pfad besitzen. Danach können wir die Methode oder Klasse in dem jeweiligen plattformspezifischen Package implementieren.</p></div></div></div><div><h2><strong>Codesharing zwischen iOS und Android</strong></h2><div><div><p>Kommen wir mal zu den harten Fakten. Was lässt sich denn jetzt wirklich alles teilen? Wie viel müssen wir ggf. doch parallel implementieren?</p></div><div><h3><strong>User Interface</strong></h3><div><p>Wie schon etwas weiter oben beschrieben sind wir absolut frei, was wir teilen wollen. Ob wir nur eine einzige Methode teilen oder die kompletten Daten und Domänenlogik ist uns komplett frei gestellt. Was wir jedoch nicht teilen sollten, ist das User Interface und seine Komponenten. Demzufolge müssen wir auch die UI-Tests jeweils plattformspezifisch entwickeln, was durchaus Sinn ergibt.</p></div></div><div><h3><strong>UI-State</strong></h3><div><p>Da der State in der Beispielanwendung lediglich eine Dataclass ist, kann man ihn durchaus teilen. Aber auch hier merkt man schon, dass wir für die jeweilige Plattform kleine Abweichungen einbauen müssen. Für iOS benötigen wir einen eigenen Konstruktor. So muss man es zwar dennoch doppelt schreiben, hat es aber zumindest in einer Datei, was sicherlich Geschmackssache ist.</p></div><div><div>UI-State</div><div>

```rouge highlight
data class BicycleSharingSystemListState(
    val isLoading: Boolean = false,
    val country: String = "",
    val bicycleSharingSystems: List<BicycleSharingSystem> = listOf(),
) {
    // Need secondary constructor to initialize with no args in SwiftUI
    constructor() : this(
        isLoading = false,
        country = "",
        bicycleSharingSystems = listOf(),
    )
}
```

</div></div></div><div><h3><strong>Remote-Zugriff</strong></h3><div><p>Für die Umsetzung der Remote-Schnittstelle haben wir Ktor als Framework verwendet, was auch JetBrains offiziell als Lösung vorgeschlägt.</p></div><div><p>Hierfür benötigen wir für iOS und Android zunächst eine separate Implementierung des Treibers. Es existieren also in der <em>commonMain</em> eine <em>KtorClientFactory</em>-Klasse, die wir als <em>expect</em> deklarieren, sowie jeweils eine <em>actual</em>-Klasse für Android und iOS. Deren Implementierungen sehen dann wie folgt aus:</p></div><div><div>KtorClientFactory</div><div>

```rouge highlight
expect class KtorClientFactory() {
    fun build(): HttpClient
}


iOS
actual class KtorClientFactory {
    actual fun build(): HttpClient {
        return HttpClient(Ios) {
            install(JsonFeature) {
                serializer = KotlinxSerializer(
                    kotlinx.serialization.json.Json {
                        ignoreUnknownKeys = true
                        useAlternativeNames = false

Android
actual class KtorClientFactory {
    actual fun build(): HttpClient {
        return HttpClient(Android) {
            install(JsonFeature) {
                serializer = KotlinxSerializer(
                    kotlinx.serialization.json.Json {
                        ignoreUnknownKeys = true
```

</div></div><div><p>Hier ist zu erkennen, dass die Implementierungen jeweils recht ähnlich sind. Der wichtigste Unterschied ist, dass bei der jeweiligen Plattform die passende Client-Engine (iOS respektive Android) an den <em>HttpClient</em> übergeben wird. Zur Serialisierung der Klassen nutzt KMM in beiden Fällen die KotlinX Serialization.</p></div><div><p>Mit der Implementierung der <em>KtorClientFactory</em> ist die Grundlage für die Remote-Anbindung bereits eingearbeitet. Das ist gleichzeitig die einzige Stelle, an der wir zwischen iOS und Android unterscheiden müssen. Die restliche Implementierung erfolgt wieder als komplett geteilte Codebasis.</p></div></div><div><h3><strong>Asynchronität</strong></h3><div><p>Neben vielen Klassen und Methoden, die problemlos zwischen iOS und Android teilbar sind, gibt es auch solche, bei denen das nicht ohne Weiteres machbar ist. Ein Beispiel ist die Verwendung von Coroutines. Um Asynchronität zu implementieren, bietet Kotlin für Android die <em>kotlinx.coroutines</em>-Bibliothek an. Das ist unter anderem für die Implementierung der Remote-Anbindung nötig. iOS kann diese Funktionalität jedoch nicht nutzen.</p></div><div><p>Zur Lösung dieses Problems gibt es verschiedene Ansätze:</p></div><div><h4><strong>KMP Beta</strong></h4><div><p>Zum einen kann man ganz entspannt einen Kaffee trinken und warten, bis KMM <a href="https://blog.jetbrains.com/kotlin/2021/08/try-the-new-kotlin-native-memory-manager-development-preview/" target="_blank">in die Beta kommt</a> . Hier wird laut JetBrains ein neuer Kotlin/Native-Memory-Manager zum Einsatz kommen. Damit sollen die Differenzen zwischen den beiden System begradigt werden und das Arbeiten mit Asynchronität deutlich vereinfacht werden.</p></div></div><div><h4><strong>FlowHelper</strong></h4><div><p>Wer nicht warten kann, hat auch jetzt schon Möglichkeiten. In unserer Beispiel-App haben wir das ganze mit einem Wrapper gelöst. Der FlowHelper kann unterscheiden, ob es eine iOS-App oder eine Android-App ist.</p></div><div><div>Flow Helper</div><div>

```rouge highlight
fun <T> Flow<T>.asCommonFlow(): CommonFlow<T> = CommonFlow(this)

class CommonFlow<T>(private val origin: Flow<T>) : Flow<T> by origin {
    fun collectCommon(
        coroutineScope: CoroutineScope? = null, // 'viewModelScope' on Android and 'nil' on iOS
        callback: (T) -> Unit, // callback on each emission
    ) {
        onEach {
            callback(it)
        }.launchIn(coroutineScope ?: CoroutineScope(Dispatchers.Main))
    }
}
```

</div></div><div><p>Für Android gibt man dem FlowHelper einfach den <em>Coroutinescope</em> mit und setzt den Callback auf <em>null</em>. Der Rest funktioniert dann wie gewohnt mit der <em>coroutinex.flow dependency</em>.</p></div><div><div>collectCommon Implementierung Android</div><div>

```rouge highlight
searchBicycleSharingSystems.execute(
    country = state.value.country,
).collectCommon(viewModelScope) { dataState ->
    state.value = state.value.copy(isLoading = dataState.isLoading)

    dataState.data?.let { bicycleSharingSystems ->
        appendBicycleSharingSystem(bicycleSharingSystems)
        saveAllBicycleSharingSystems(bicycleSharingSystems)
    }
}
```

</div></div><div><p>Bei iOS gibt man einen Callback mit. Man implementiert hier eine Funktion, die KMM dann anstelle der Couroutines ausführt.</p></div><div><div>collectCommon Implementierung iOS</div><div>

```rouge highlight
searchBicycleSharingSystems.execute(
    country: currentState.country
).collectCommon(
    coroutineScope: nil,
    callback: {
        >>> Here you can write your code
    })
```

</div></div></div></div><div><h3><strong>Datenbankzugriff</strong></h3><div><p>Für die Datenbankanbindung haben wir SQLDelight genommen. Das war zum Zeitpunkt der Erstellung das einzige Framework, das sowohl für Android wie auch für iOS eine Implementierung zur Verfügung stellte. Neben SQL Delight gibt es inzwischen auch die Möglichkeit, Realm als Datenbank zu nutzen.</p></div><div><h4><strong>Grundlegende Implementierung</strong></h4><div><p>Ähnlich der Remote-Schnittstelle mit Ktor bedarf es hier ebenfalls einer plattformspezifischen Implementierung der Treiber. Das haben wir ähnlich der Implementierung der PeopleInSpace App von John O’Reilly umgesetzt.</p></div><div><div>Platform Module für die Datenbank</div><div>

```rouge highlight
expect fun platformModule(): Module
```

</div></div><div><p>In den jeweiligen plattformspezifischen Modulen wird der passende Treiber genutzt und das Datenbankschema wie auch der Datenbankname übergeben.</p></div><div><div>Platform Module für die Datenbank – iOS</div><div>

```rouge highlight
actual fun platformModule() = module {
    single {
        val driver = NativeSqliteDriver(KmmBikeShareDatabase.Schema, "BikeShareDb.db")
        KmmBikeShareDatabaseWrapper(KmmBikeShareDatabase(driver))
    }
}
```

</div></div><div><div>Platform Module für die Datenbank – Android</div><div>

```rouge highlight
actual fun platformModule() = module {
    single {
        val driver =
            AndroidSqliteDriver(KmmBikeShareDatabase.Schema, get(), "BikeShareDb.db")
        KmmBikeShareDatabaseWrapper(KmmBikeShareDatabase(driver))
    }
}
```

</div></div><div><p>Das Datenbankschema wird zunächst in SQLDelight-Dateien definiert. Hier wird klassisch erst die Tabelle mit den Attributen und deren Eigenschaften definiert. Danach erfolgen die konkreten Datenbankabfragen (CRUD-Methoden), die später für die App zum Einsatz kommen. Innerhalb der <em>build.gradle.kts</em> wird die SQLDelight-Erweiterung definiert und sowohl der Datenbankname, als auch das Verzeichnis zu den oben beschriebenen Datenbankschemata hinterlegt. Um das anschließend nutzen zu können, müssen wir diesen Abschnitt zunächst kompilieren. Erfolgt eine Änderung an dem Schema, muss ein Rebuild erfolgen, damit die Änderungen wirksam werden.</p></div><div><p>SQLDelight erzeugt aus den Dateien einige neue Dateien, darunter die Implementierung der Datenbank, die die notwendigen Methoden und Verknüpfungen für die Entitäten und die Queries enthält. Außerdem sind hier weitere grundlegende Methoden inbegriffen, zum Beispiel <em>getLastInsertRowId</em>, die die zuletzt eingefügte ID zurückgibt. Das ist später sehr nützlich, um bei einem <em>Insert</em>-Befehl die ID zurückzugeben, um damit weiterzuarbeiten.</p></div><div><p>Die eigentliche Implementierung besteht aus dem Mapper, dem Datenbankmodell und den jeweiligen Repositories.</p></div></div></div><div><h3><strong>Test</strong></h3><div><p>Ein großer Vorteil der geteilten Codebasis ist, dass die Tests ebenfalls geteilt werden können.</p></div><div><p>In der App haben wir Tests für die lokalen Datenbankimplementierungen und für die Interactors erstellt. In diesem Abschnitt geht es also nur um die Tests, die sich innerhalb der geteilten Codebasis befinden.</p></div><div><p>Als Grundlage für die Tests haben wir den <em>BaseTest</em> eingebaut. Er ist im commonMain Package ebenfalls als <em>expect</em> deklariert, da es hier nötig ist, eine Unterscheidung zwischen Android und iOS zu treffen. Der <em>BaseTest</em> ist grundlegend so aufgebaut, dass es möglich ist, darin eine Suspend Function aufzurufen. Dazu muss er in einem <em>CoroutineScope</em> laufen. Außerdem müssen die Module für die Dependency Injection angelegt werden. Diese beiden Aufgaben sorgen dafür, dass die Basisklasse separat für Android und iOS gehandhabt werden muss. Eine weitere wichtige Aufgabe in Bezug auf Koin und den <em>CoroutineScope</em> ist es, diese zu starten und vor allem auch wieder zu stoppen.</p></div><div><div>BaseTest expect im Common Main</div><div>

```rouge highlight
expect abstract class BaseTest() : KoinTest {
    fun <T> runTest(block: suspend CoroutineScope.() -> T)
}
```

</div></div><div><h4><strong>Android</strong></h4><div><p>Unter Android gestaltet sich das unkompliziert. Hier können wir eine <em>KoinTestRule</em> erzeugen, die eine <em>ﬁnished</em>– und eine <em>starting</em>-Methode beinhaltet, die KMM dann automatisch ausführt. Der Coroutine Scope wird ebenfalls selbstständig gestartet und anschließend auch wieder beendet.</p></div><div><div>BaseTest unter Android</div><div>

```rouge highlight
@RunWith(AndroidJUnit4::class)
actual abstract class BaseTest : KoinTest {
    @get:Rule
    val koinTestRule = KoinTestRule.create {
        androidContext(ApplicationProvider.getApplicationContext())
        modules(
            network,
            ...
        )
    }
    actual fun <T> runTest(
        block: suspend CoroutineScope.() -> T
    ) { runBlocking { block(
}
```

</div></div></div><div><h4><strong>iOS</strong></h4><div><p>Für iOS müssen wir die gleiche Funktionalität erzeugen. Aktuell gib es hierfür noch keine spezielle Bibliothek, die das gewährleistet. Um die Funktionalität dennoch zu erzeugen, wurde eine Implementierung benutzt, die aus dem <em>touchlab/KaMPkit</em>-Repository stammt.</p></div><div><p>Für iOS wird der Dispatcher händisch in die <em>BaseTest</em>-Klasse eingebracht und erzeugt ebenfalls eine Methode, mit der die Tests ausführbar sind. Auch hier ist zu sehen, dass Koin zunächst gestartet wurde und später wieder beendet wird. Ebenfalls wird ein <em>CFRunLoop</em> gestartet, der eine Basisimplementierung unter iOS ist. Dieser wird zum Ende hin ebenfalls beendet.</p></div><div><div>BaseTest unter iOS</div><div>

```rouge highlight
actual abstract class BaseTest : KoinTest {

    @OptIn(DelicateCoroutinesApi::class)
    actual fun <T> runTest(block: suspend CoroutineScope.() -> T) {
        var error: Throwable? = null

        GlobalScope.launch(Dispatchers.Main) {
            try {
                initKoin()
                block()
            } catch (t: Throwable) {
                error = t
            } finally {
                stopKoin()
                CFRunLoopStop(CFRunLoopGetCurrent())
            }
        }
        CFRunLoopRun()
        error?.also { throw it }
    }
}
```

</div></div><div><p>Die Testklassen erben nun vom <em>BaseTest</em>. Innerhalb der Testklasse erzeugen wir zunächst eine Methode, die vor jedem Test läuft und einen Basissatz an Daten in der Datenbank implementiert. Sie ist mit <em>@BeforeTest</em> annotiert und nutzt die <em>runTest</em>-Methode aus dem <em>BaseTest</em>.</p></div><div><p>An den Tests wird nun noch die Annotation <em>@Test</em> notiert. Ebenso wird hier die <em>runTest</em>-Methode aus der <em>BaseTest</em>-Klasse wieder verwendet. Die Daten, die die <em>Setup</em>-Methode erzeugt, stehen anschließend vor jedem der Tests zur Verfügung. Die restliche Testimplementierung erfolgt wiederum nach dem Aufbau, wie er von der klassischen Android-Entwicklung bekannt ist.</p></div></div></div></div></div><div><h2><strong>Conclusion</strong></h2><div><div><p>Damit sind die wichtigsten Aspekte von Kotlin Multiplatform Mobile aufgezeigt. Wenn wir einmal auf die Ausgangsfrage zurückkommen, ob JetBrains nur eine weitere Kopie eines bestehenden Crossplatform Frameworks gebaut hat, kann man das ganz klar verneinen.<br /> KMM verfolgt einen deutlich anderen und vor allem freieren Weg, der auch jetzt schon viel Anklang in der Welt der Mobile-App-Entwicklung erhält.<br /> Es gibt bereits jetzt für alle wichtigen Teilbereiche, die in der App-Entwicklung nötig sind, einsatzbereite Frameworks. Wir können von der Businesslogik, über die Remoteanbindung bis zu den Tests alles teilen.</p></div><div><p>Dennoch gibt es auch Hürden, die man nehmen muss. Die Ersteinrichtung vor allem auf iOS-Seite ist mitunter schwierig. Auch sind die externen Bibliotheken mitunter noch nicht für KMM ausgelegt. Und auch die kleinen Schwierigkeiten mit dem Memory-Modell lassen noch Raum für Verbesserung.</p></div><div><p>Alles in allem sollte man dieses Framework nicht aus dem Blick verlieren. Für den entsprechenden Use Case kann und wird sich KMM durchaus relevant einsetzen lassen.</p></div></div></div></div></div>

Kotlin Multiplatform Mobile – Ein praktischer Einstieg

Vor drei Monaten konnte ich zum ersten Mal mit GitHub Copilot von Microsoft auf die Startbahn gehen. Ob der Flug erfolgreich war oder ob ich es gar nicht in die Luft geschafft habe, möchte ich euch einmal berichten.

## Was ist GitHub Copilot?
Der Copilot ist ein intelligenter Assistent, der euch beim Programmieren helfen soll. Dies erfolgt in der Form von Vorschlägen, die euch Copilot in Echtzeit während der Eingabe anzeigt.
Beim Copilot handelt es sich um eine Künstliche Intelligenz, die auf <a href="https://openai.com/blog/openai-codex/" target="_blank">OpenAI Codex </a> basiert. 


## Registrieren und Installieren  
Zunächst werfen wir einen Blick in den Registrierungs- und Installationsprozess. Als Erstes müsst ihr euch bei GitHub registrieren und dort eine Lizenz erwerben. Der Copilot ist leider nicht kostenlos. Es besteht aber die Möglichkeit das Tool zunächst 60 Tage lang zu testen. Danach kostet es 10 $ pro Monat oder 100 $ pro Jahr. 

Studierende haben die Möglichkeit, sich über die <a href="https://education.github.com/" target="_blank">GitHub-Education-Seite</a> zu registrieren und sich den GitHub-Pro-Account zu sichern. Darin sind einige Tools enthalten. Unter anderem <a href="https://docs.github.com/en/copilot/overview-of-github-copilot/about-github-copilot#about-billing-for-github-copilot" target="_blank">GitHub Copilot</a>, aber auch der Azure-Edu-Account mit 100 $ Startbonus (kann man sich durchaus mal anschauen). 

Nach der Registrierung müsst Ihr Copilot in eurer IDE als Plugin installieren.
Ich habe das ganze ausschließlich in IntelliJ und Android Studio genutzt, weshalb hier nur dieser Weg aufgezeigt wird. Neben den <a href="https://docs.github.com/en/copilot/getting-started-with-github-copilot/getting-started-with-github-copilot-in-a-jetbrains-ide" target="_blank">JetBrain IDEs </a>     steht euch Copilot auch noch in
<a href="https://docs.github.com/en/copilot/getting-started-with-github-copilot/getting-started-with-github-copilot-in-visual-studio-code" target="_blank">Visual Studio Code</a>, <a href="https://docs.github.com/en/copilot/getting-started-with-github-copilot/getting-started-with-github-copilot-in-visual-studio" target="_blank">Visual Studio</a> und <a href="https://docs.github.com/en/copilot/getting-started-with-github-copilot/getting-started-with-github-copilot-in-neovim" target="_blank">Neovim</a> zur Verfügung.


GitHub stellt Copilot als Plugin bereit und ihr könnt ihn mit wenigen Klicks innerhalb der IDE im Pluginfenster installieren. 

![](https://eu-central-1.graphassets.com/AiE4QoWSSiIQO3k152ugkz/yndDfMvaT5GtXHbwo03Q)

Ist das abgeschlossen, müsst ihr noch euren GitHub-Account mit der IDE verbinden! Hierdurch wird geprüft, ob ihr eine gültige Lizenz besitzt. Das Login-Fenster findet ihr (in IntelliJ) ganz unten rechts in der Taskbar. 

<img src="https://eu-central-1.graphassets.com/AiE4QoWSSiIQO3k152ugkz/4csRilxRauicu6YEEO55" width="200" />

Danach könnt ihr direkt mit Programmieren anfangen und Copilot wird euch ab sofort Vorschläge geben.


## Wie funktioniert es in der IDE?

Nachdem Copilot eingerichtet ist, könnt Ihr mit der Benutzung starten. Der zunächst intuitive Anwendungsfall ist die Inline-Vervollständigung. Ihr habt eine bereits implementierte Funktion und wollt diese nun im Code aufrufen. Fangt ihr an, diese Funktion einzutippen, erscheint ein ausgegrauter Vorschlag. Das Besondere dabei ist, dass auch die Übergabeparameter mit syntaktisch korrekten Parametern vorgeschlagen werden.

**Du tippst:**
``` Kotlin
sumOf
```

**Vorschlag vom Copilot:**
``` Kotlin
sumOfTwoNumbers(2, 5)
```

Gefällt euch der Vorschlag nicht, habt ihr drei Möglichkeiten, damit umzugehen. 
Zum einen könnt Ihr mit der Tastenkombination `Option + [` bzw. `Option + ]` durch weitere Vorschläge iterieren. Natürlich nur sofern diese vorhanden sind. Zum anderen könnt Ihr den Vorschlag mit `Esc` ablehnen. 

Das Schönste an Copilot ist aber die Möglichkeit, weiterzuschreiben und ihn einfach zu ignorieren. Im Gegensatz zu anderen solcher Tools stört er fast nie. Warum fast nie? Weil es hin und wieder vorkommt, dass er mehrere Zeilen an Vorschlägen macht und sich somit der eigentliche Code nach unten bewegt. Will man aktuell gar nicht mit ihm arbeiten, glitscht es dann ein wenig. Aber das ist selten und stört in Summe nicht. 
Wollt ihr dennoch mal Ruhe von Copilot haben, könnt ihr ihn mit zwei Klicks leicht deaktivieren. Entweder komplett oder für einen bestimmen Dateityp. Das findet ihr am gleichen Ort wie für die Authentifizierung mit GitHub (in IntelliJ).

<img src="https://eu-central-1.graphassets.com/AiE4QoWSSiIQO3k152ugkz/8SawieNyROinyPIZE1Mn" width="200"/>


**Hier noch einmal die Shortcuts in der Zusammenfassung:**

| Aktion                | Windows / Linux | macOS       |
| --------------------- | --------------- | ----------- |
| Inline-Vorschläge     | Alt + \         | Option + \  |
| nächster Vorschlag    | Alt + ]         | Option + ]  |
| vorheriger Vorschlag  | Alt + \[        | Option + \[ |
| Vorschlag akzeptieren | Tab             | Tab         |
| Vorschlag ablehnen    | Esc             | Esc         |
 *In anderen IDEs können die Shortcuts abweichen


### Beispiele
Besonders positiv ist mir Copilot bei der Verwendung von Methoden mit vielen Parametern aufgefallen. Gerade beim Nutzen von Datenklassen, die dann in Mocks genutzt wurden, musste ich mir keine Dummy-Daten ausdenken – zum Beispiel beim Verwenden eines Personenobjekts.

``` Kotlin
data class Person(  
	val name: String,  
	val age: Int,  
	val isMarried: Boolean,  
	val children: List<Person>  
)
```
Jetzt gibt man nur  `Person` ein und Copilot schlägt dann etwas wie das folgende vor:
``` Kotlin
Person(  
	name = "John", age = 30, isMarried = true, children = listOf(  
		Person(  
			name = "Mary", age = 15, isMarried = false, children = listOf()  
		),   
		Person(  
			name = "Bob", age = 20, isMarried = false, children = listOf()  
		)  
	)  
)
```
Ok zugegeben, dass John mit 10 Jahren schon den Bob als Kind bekam, scheint nicht ganz realistisch. Hieran erkennt man aber auch die Grenze der KI.

Eine weitere Möglichkeit zur Generierung von Code ist das Schreiben von Kommentaren. Ihr könnt einfach beschreiben, was ihr haben möchtet und Copilot liefert euch einen oft ganz guten Ansatz. 

**Beispiel:**
``` Kotlin
// write a function, that can calculate the sum of 2 float values
```

**Copilot schlägt dann folgendes vor:**
``` Kotlin
fun sum(a: Float, b: Float): Float {  
	return a + b  
}
```

Ihr könnt auch auf anderen Sprachen als Englisch schreiben. Hier zum Beispiel mal zum Vergleich auf Englisch und Deutsch.
``` Kotlin
class Test(){  
//write a function, that takes a string and returns the first character of the string  
//if the string is empty, return null    

fun firstChar(str: String): Char? {  
    if (str.isEmpty()) {  
        return null  
    }  
    return str[0]  
}  
```
  
``` Kotlin
// schreibe eine Funktion, die einen string übergeben bekommt und den ersten Buchstaben des Strings zurückgibt  
// wenn der String leer ist, gib 5 zurück    

fun firstChar2(str: String): Char? {  
	if (str.isEmpty()) {  
		return '5'  
	}  
	return str[0]  
}  
```
*Den Return habe ich geändert, damit man erkennt, dass es unterschiedliche Vorschläge sind.

Copilot kann durchaus noch mehr. Hier sind vor allem auch kreative Ideen gefragt. Eine kleine Auflistung liefert GitHub im Artikel <a href="https://github.blog/2022-09-14-8-things-you-didnt-know-you-could-do-with-github-copilot/" target="_blank">8 things you didn’t know you could do with GitHub Copilot</a>.

## Copilot!
Das ganze wirkt durchaus beeindruckend und funktioniert erstaunlich vernünftig sowie stressfrei. Dennoch ist es nur eine Hilfe. Der Name Copilot ist Programm und sollte auch so verstanden werden. Im Kontext der Programmierung steuert der Pilot (das seid ihr) das Flugzeug (das Programm). Er entscheidet, wo es hingeht und er hält das Flugzeug auf Kurs. 

Copilot gibt dabei wertvolle Unterstützung beim Start, der Landung und dem Flug, ist aber nicht entscheidend für den Erfolg dieses Fluges. Verlasst euch niemals nur auf den Vorschlag von Copilot. Überprüft, was er vorschlägt und ob das ganze wirklich passt.

## Ein Blick hinter die Kulissen
Nach dem ersten positiven Hype, den ich beim Ausprobieren entwickelt habe, stellte ich mir die Frage, woher die Vorschläge eigentlich kommen. 

Zum einen stammen viele Vorschläge vom aktuelle Repository, in dem ich gerade arbeite. Es werden zum Beispiel bereits implementierte Klassen und Methoden erkannt und die Übergabeparameter "sinnvoll" vorgeschlagen. Soweit ist das nichts Neues und das gleiche Vorgehen wie auch bei anderen solcher Tools.

Jedoch werden auch Vorschläge für ganze Codeblöcke gemacht, die keineswegs von meinem Code stammen können. Ein Blick auf die Funktionsbeschreibung von Copilot verrät, dass die Quelle andere Repositories auf GitHub sind. Laut GitHub handelt es sich dabei um öffentlichen Repositories, anhand derer die KI trainiert wird. 

Codex versucht Strukturen und Pattern von existierendem Code zu finden und erzeugt daraus unter anderem diese Vorschläge.  Darin liegt die *Macht* von Github Copilot. 


##  Die Dunkle Seite der Macht
Neben all dem positiven gibt es auch eine Schattenseite. Wie schon erwähnt, generiert der Copilot seine Vorschläge anhand von öffentlichen Repositories. 

Und das ist der große Knackpunkt. Darf Microsoft einfach den Code von anderen Repositories nutzen und damit Profit generieren? Viele der auf GitHub gehosteten Projekte wurden unter einer <a href="https://de.wikipedia.org/wiki/Copyleft" target="_blank">Copyleft-Lizenz</a> lizenziert. Damit sind diese Projekte nicht gemeinfrei, sondern stehen unter der <a href="https://de.wikipedia.org/wiki/Free/Libre_Open_Source_Software" target="_blank">"Free and Open Source Software"-Lizenz (FOSS)</a>.

Nutzt man diese Projekte, muss man den oder die Autoren nennen. Außerdem gibt es die Option, dass Software, die auf Grundlage dieser Open-Source-Software basiert, ebenfalls unter einer Copyleft-Lizenz lizenziert werden muss. Das ganze geschieht bei der Nutzung von GitHub Copilot nicht. Rein rechtlich ist Microsoft hier wohl auf der sicheren Seite, aber einen faden Beigeschmack hat das Ganze dennoch.

Das ist ein komplexes Thema, welches schon <a href="https://www.heise.de/meinung/Edit-Policy-GitHubs-KI-Copilot-ist-keine-Urheberrechtsverletzung-6128502.html" target="_blank">in anderen Artikeln</a> gut beleuchtet wurde. Dieses Thema wird in den kommenden Jahren noch für viel Gesprächsstoff sorgen. Nicht nur GitHub Copilot stößt an Grenzen der Ethik und des Rechts. Auch anderer solcher Tools werden diese Probleme bekommen. Denn eine KI, die gut funktionieren soll, muss auch gut trainiert werden. Das bedeutet, dass es viele Daten braucht. Die Grenzen werden sich wohl Stück für Stück verschieben und ggf. müssen neue Regelungen geschaffen werden, damit der Open-Source-Gedanke weiter bestehen kann.


## Fun Fact
Ich schreibe den Blogbeitrag aktuell im IntelliJ mit Markdown. Und während ich diese Zeilen schreibe, schlägt mir der Copilot meine Satzvervollständigung vor.  
Wir probieren mal, was passiert, wenn ich ab jetzt nur noch das nehme, was Copilot vorschlägt. Ich markiere alles, was ich getippt habe, dick. Und Los gehts:  
  
> **Ha**llo, ich bin ein neuer Entwickler. GitHub ist ein tolles Tool. **Da**s ist ein COPILOT-Tool.  
> **Zum Ab**schluss: **sei nochmal gesa**gt, dass ich ein COPILOT-Tool bin.  
  
Naja, wie sinnvoll das in Textanwendungen ist, sei mal dahingestellt.  :) 

GitHub Copilot – Pair Programming mit der KI

P5.JS: Zeichnen mit der Open-Source-JavaScript-Bibliothek

ArchUnit in der Praxis: Architektur sauber halten und optimieren

# Modularisierung leicht gemacht: Spring Modulith mit Kotlin und Hexagonale Architektur

Modularisierung ist ein Schlüsselkonzept in der modernen Softwareentwicklung, um Anwendungen wartbar, testbar und flexibel zu gestalten. In diesem Artikel zeigen wir, wie Spring Modulith in Verbindung mit der hexagonalen Architektur und Kotlin eine solide Grundlage für die Modularisierung schaffen kann. Wir betrachten die Herausforderungen bestehender monolithischer Anwendungen und wie durch klar definierte Module eine schrittweise Entkopplung gelingt.

## Was ist ein Modulith?

Der Name deutet es schon an. Ein Modulith bezeichnet eine Architektur, bei der ein Monolith in klar abgegrenzte Module unterteilt wird. Diese Module sind so gestaltet, dass sie möglichst stark voneinander entkoppelt sind und interne Abhängigkeiten minimiert werden. Ihr könnt es euch so vorstellen, als ob ihr mehrere Microservices in ein Repository packt und unter einer Anwendung handhabt. Zum Beispiel könnte ein Modul die Benutzerdaten und ein anderes Modul die Rechnungsstellung verwalten, wobei beide Module klar voneinander getrennt sind, aber in derselben Anwendung laufen. Der Vorteil liegt auf der Hand: Es sind keine aufwendigen HTTP-Schnittstellen oder Kafka-Broker notwendig. Keine Authentifizierungen, um zwischen den Modulen zu kommunizieren, und dennoch ist der Vorteil einer losen Kopplung gegeben.

Modularisierung kann also als ein sanfter Einstieg in die Microservice-Welt gesehen werden.

## Was macht Spring Modulith

Um eine Anwendung in Module zu unterteilen gibt es verschiedene Optionen. Zum einen kann man einfach den Code in verschiedene Packages packen. Zum anderen bieten Maven bzw Gradle die Option Module mit eigenen Dependencies und eigenem Build-Script zu erzeugen. Und auch die Aufteilung in Microservices ist eine Art Modularisierung.

Schaut man sich die drei Optionen an, fällt auf, dass deren Umsetzung geordnet in ihrem Aufwand steigt. Während Pakete noch sehr einfach anzulegen sind, braucht es für Maven/Gradle-Module schon jeweils separate Dependency-Definitionen. Der Aufwand, Microservices in die Welt zu senden und deren Kommunikation untereinander zu ermöglichen, legt den anderen beiden noch einmal eine ganze Schippe oben drauf.

Wir wollen also eigentlich erst einmal nur mit Paketen starten. Aber hier bekommen wir schnell ein Problem. Stellt euch vor, ihr habt eine Legacy-Anwendung, bei der ein Domain-Modell auf das andere zugreift und das wiederum auf das nächste. Packt ihr nun alle eure passend zusammenhängenden Klassen in die jeweiligen Pakete, sieht es zwar nach verschiedenen Modulen aus, aber in Wirklichkeit ist dem nicht so.

Wir wollen eine lose Kopplung erreichen. Vom Prinzip her wollen wir vielleicht später mal in der Lage sein, eines der Module herauszulösen und als Microservice zu deployen. Dann wollen wir natürlich so wenig wie möglich Kopplung haben. Somit wird der Refactoring-Aufwand reduziert.

Leider sieht man diese Kopplung nur sehr schwer, da sie oft erst bei einer detaillierten Analyse des Quellcodes oder bei der Beobachtung von unerwartetem Verhalten in der Anwendung deutlich wird. Im Zweifel fällt es erst auf, wenn versucht wird, das Modul herauszulösen und als eigenen Microservice zu deployen. Häufig verbirgt sich diese Kopplung in subtilen Abhängigkeiten zwischen Modulen, die durch direkte Zugriffe entstehen. Selbst wenn ihr anfangt aufzuräumen und in einer großen Hauruck-Aktion die Klassen voneinander entkoppelt, werdet ihr spätestens in der weiteren Entwicklung wieder Kopplungen erhalten.

Und genau hier hilft Spring Modulith. Es prüft, ob ihr Dependencies von einem Modul auf ein anderes habt, welche nicht erlaubt sind.

## Grundlagen

Stellen wir uns vor, wir haben folgende Struktur:

```toml
src
├── Application.kt
├── module-1
│   ├── ModuleOneInterface.kt
│   └── ModuleOneService.kt
└── module-2
    ├── ModuleTwoInterface.kt
    └── ModuleTwoService.kt

```

In unserem `src`-Package liegt also eine `Application.kt` und daneben zwei Pakete: `module-1` und `module-2`. In den beiden Modulen befindet sich zum einen ein Interface und ein Service, welcher die Implementierung des Interfaces darstellt.

Das Erste, was Spring Modulith macht, ist, alle Pakete, welche auf der gleichen Ebene liegen wie die `Application.kt`, als Modul zu definieren. Das passiert von ganz alleine, und ihr müsst dafür nichts weiter tun. Alle sich darin befindlichen Klassen und Interfaces werden von Spring Modulith standardmäßig als public angesehen. Es ist also erlaubt, von allen anderen Modulen auf diese Klassen zuzugreifen.

Nun wollen wir aber nicht, dass der `ModuleOneService` direkt auf den `ModuleTwoService` und vice versa zugreifen kann, sondern das Ganze soll nur über die Interfaces möglich sein. Um das zu erreichen, packen wir die Services einfach in ein Sub-Package:

```toml
src
├── Application.kt
├── module-1
│   ├── ModuleOneInterface.kt
│   └── services
│       └── ModuleOneService.kt
└── module-2
    ├── ModuleTwoInterface.kt
    └── services
        └── ModuleTwoService.kt

```

Greifen wir nun von einem der Services auf den anderen Service zu, wird der Spring Modulith-Test fehlschlagen.

## Spring Modulith Test

Da wir nun schon den Test erwähnt haben, möchte ich hier noch einmal kurz aufzeigen, wie diese Tests aussehen. Im Grunde stellt euch Spring Modulith drei "Test"-Funktionalitäten zur Verfügung. Zum einen haben wir den eigentlichen Test, der unsere Module analysiert und verifiziert, ob wir die lose Kopplung, die wir haben wollen, einhalten.

```kotlin
@Test
fun `verifies modular structure`() {
    val modules = ApplicationModules.of(SpringModulithApplication::class.java)
    modules.verify()
}

```

Als Nächstes haben wir die Option, uns einmal die Module mit deren Definitionen anzuschauen. Hierin werden alle wesentlichen Inhalte eines Moduls wie zum Beispiel die `NamedInterfaces`, auf die wir gleich noch zu sprechen kommen, ausgegeben.

``` kotlin
@Test
fun `print module structure`() {
    val modules = ApplicationModules.of(SpringModulithApplication::class.java)
    modules.forEach(Consumer { module: ApplicationModule? -> println(module) })
}

```

Und als Letztes bietet Spring Modulith die Möglichkeit, euch eine Doku zu generieren. Diese beinhaltet verschiedene PlantUML-Diagramme der Module und deren Beziehungen zueinander. Aber auch eine AsciiDoc-Dokumentation mit den Diagrammen und allen Klassen sowie Interfaces, welche nach außen öffentlich gemacht sind.

```kotlin
@Test
fun `create module documentation`() {
    val modules = ApplicationModules.of(SpringModulithApplication::class.java)
    Documenter(modules)
        .writeDocumentation()
        .writeIndividualModulesAsPlantUml()
}

```

## Hexagonale Architektur

Selten werden wir so einfache Strukturen in unseren Modulen haben, wie in dem Beispiel weiter oben zu sehen. Gerade wenn wir mit Strukturen wie der hexagonalen Architektur arbeiten, entstehen viele Sub-Packages. Einige von ihnen wollen wir ggf. nach außen hin zugänglich machen. Eine solche Struktur könnte dann so aussehen:

```toml
src
├── Application.kt
├── module-1
│   ├── adapter
│   │   ├── inbound
│   │   └── outbound
│   ├── domain
│   │   ├── services
│   │   │   └── ModuleOneService.kt
│   │   ├── model
│   │   └── ports
│   │       ├── inbound
│   │       │   └── ModuleOneInterface.kt
│   │       └── outbound
│   └── services
└── module-2
    ├── adapter
    │   ├── inbound
    │   └── outbound
    └── domain
        ├── services
        │   └── ModuleTwoService.kt
        ├── model
        └── ports
            ├── inbound
            │   └── ModuleTwoInterface.kt
            └── outbound

```

Nun können die Services weiterhin nicht auf andere Services zugreifen, da sie in einem Sub-Package liegen. Jedoch können die Services nun auch nicht mehr auf die Interfaces zugreifen, da diese nun ebenfalls in einem Sub-Package liegen. Wir müssen an dieser Stelle also klar definieren, dass wir zum Beispiel das Package `module-1.domain.ports.inbound` nach außen öffnen wollen. Dazu legt man in Java eine `package-info.java` in das Package und kann hier sein Package definieren.

In Kotlin funktioniert dieser Weg nicht. Hier müssen wir eine Klasse erstellen und dieser gewisse Annotationen mitgeben. Wir erzeugen uns also die `ModuleMetadata.kt` und legen sie in den zu definierenden Ordner. Der Name der Klasse ist dabei nicht von Bedeutung. Ihr könnt die Klasse auch `Drotbohm.kt` oder `Weihnachtsmann.kt` nennen. Viel wichtiger ist der Inhalt.

```toml
└── ports
    ├── inbound
    │   ├── ModuleOneInterface.kt
    │   └── ModuleMetadata.kt

```

Hier sind zwei Annotationen zu sehen: Zum einen `@PackageInfo` und `@NamedInterface`.

```kotlin
@PackageInfo
@NamedInterface(name = ["inbound-port"])
class ModuleMetadata

```

`@PackageInfo` ist in der Java-Variante nicht nötig, da dies durch den Dateityp bereits gegeben ist. In Kotlin wird dies benötigt, damit Spring Modulith weiß, dass es sich um die PackageInfo-Datei handelt und hier die Deklaration für das Package zu finden ist.

`@NamedInterface` definiert den Namen, unter dem das Package später von Spring Modulith gefunden werden kann. Auch diese Annotation ist nötig, ihr müsst jedoch keinen Namen angeben. Lasst ihr den Parameter weg, wird der Name des Packages genutzt. Wollt ihr einen expliziten Namen angeben, müsst ihr in Kotlin mit Named-Parametern arbeiten und das Ganze als Array definieren.

Der Name ist gerade in der hexagonalen Architektur nicht ganz unwichtig. Schaut ihr euch ein wenig weiter oben den Projektbaum an, werdet ihr feststellen, dass wir zwei Packages haben, welche `inbound` heißen. Einmal in der Domain und einmal in den Adaptern. Lasst ihr den Namen weg, werden beide Packages öffentlich gemacht, da sie den gleichen Namen besitzen.

## Explizite Zugriffe auf Module

Stellt euch vor, wir haben einige Module in unserer Anwendung. Wir haben in jedem dieser Module einige Packages öffentlich für andere Module gemacht.

Nun kann jedoch jedes Modul auf alle der geöffneten Packages aus allen anderen Modulen zugreifen. Das wollen wir aber nicht. Wir öffnen ein Package ja ggf. nur für ein spezifisches Modul. Auch hier kann man eine Definition vornehmen, um dies sicherzustellen.

Nehmen wir an, wir haben neben unseren `module-1` und dem `module-2` auch noch ein `module-3`. In allen drei Modulen haben wir gewisse Packages öffentlich gemacht. Nun wollen wir, dass `module-1` ausschließlich auf Packages von `module-2` zugreifen darf. Und innerhalb von `module-2` soll es auch nur auf das `inbound-port`-Package zugreifen dürfen.

Um das zu tun, erstellen wir wieder eine Module-Metadata in der obersten Ebene von `module-1`:

```toml
└── module-1
    ├── ModuleMetadata.kt
    ├── adapter
    │   ├── ...
    ├── domain
        ├── ...

```

In der `ModuleMetadata.kt` fügen wir nun die `@ApplicationModule`-Annotation hinzu. Hierin können wir dann über `allowedDependencies` die Module und Packages deklarieren, auf die das Modul Zugriff haben darf. Das Ganze erfolgt nach dem Schema: `Module :: Package`. Der Paketname ist entweder der Name des Packages, in dem eure `ModuleMetadata.kt` des anderen Moduls liegt, oder derjenige, den ihr in der `ModuleMetadata.kt` als NamedInterface deklariert habt.

```kotlin
@ApplicationModule(
    allowedDependencies = ["module-2 :: inbound-port"]
)
class ModuleMetadata

```

Wenn ihr weitere Module und/oder NamedInterfaces erlauben wollt, könnt ihr dies hier einfach kommasepariert angeben. Solltet ihr zwar ein Modul erlauben, aber keine Einschränkungen der einzelnen Packages wollen, könnt ihr dies mit dem Sternchen (`*`) ausdrücken: `allowedDependencies = ["module-2 :: *"]`.

## Legacy Anwendung

Nun wissen wir, wie wir einzelne Packages freigeben und den Zugriff auf diese für andere Module explizit angeben können. Setzen wir das Ganze in einer Legacy-Anwendung um, wird die Liste an Fehlern im Spring Modulith-Test sehr lang. Das alles mit einem Mal zu beheben, ist oft sehr aufwändig.

Aber auch hierfür bietet Spring Modulith eine Option, um euch auch beim Modularisieren von Legacy-Anwendungen zu unterstützen.

Ihr könnt in der Moduldefinition, in der ihr die `allowedDependencies` eingefügt habt, noch einen weiteren Parameter ergänzen. Und zwar den `type`. Mit diesem könnt ihr das gesamte Modul auf öffentlich setzen. Das heißt, alle Packages sind ab dann für alle anderen Module verfügbar, auch wenn ihr darin keine Module-Metadata definiert habt.

```kotlin
@ApplicationModule(
    type = ApplicationModule.Type.OPEN,
    allowedDependencies = ["module-1 :: inbound-port"]
)
class ModuleMetadata

```

Es ist also möglich, zunächst die Module mit ihrer Paketstruktur zu erstellen und die bis dato starke Kopplung noch zu behalten. Eure Tests bleiben weiterhin grün, ihr könnt andere Änderungen committen und eure Pipeline läuft sauber durch. Das ermöglicht euch, eure Module nacheinander zu entkoppeln. Die Öffnung eines Moduls sollte aber nur so lange Bestand haben, wie ihr euer Modul entkoppelt. Sobald das Modul entkoppelt ist, kann man den Typ entweder auf CLOSED setzen oder einfach aus der `@ApplicationModule`-Annotation entfernen.

## Fazit

Ein Modulith ist ein Monolith, der in klar abgegrenzte Module unterteilt wird, um lose Kopplung und bessere Wartbarkeit zu erreichen. Diese Module laufen zwar in einer gemeinsamen Anwendung, sind aber so strukturiert, dass sie weitgehend voneinander getrennt funktionieren. Gerade bei Legacy-Anwendungen, die viele unübersichtliche Abhängigkeiten aufweisen, bietet das modulare Konzept einen schrittweisen Übergang zu einer entkoppelten Architektur.

Spring Modulith unterstützt diesen Ansatz, indem es auf Packagings in einer Spring-Anwendung aufsetzt und automatisch Module erkennt. Im Default-Zustand sind alle Pakete eines Moduls öffentlich, doch über spezielle „Metadata“-Dateien können unerwünschte Abhängigkeiten blockiert oder nur bestimmte Bereiche (z.B. Interfaces) öffentlich gemacht werden. Das sorgt dafür, dass Zugriffe zwischen Modulen nur explizit erlaubt erfolgen.

Zur Überprüfung der modularen Struktur stellt Spring Modulith drei zentrale Test-Funktionen bereit:

1. **Verifikation**: Ein Test, der prüft, ob alle definierten Modulgrenzen eingehalten werden.
2. **Modul-Übersicht**: Eine Ausgabe der erkannten Module und deren Abhängigkeiten.
3. **Dokumentation**: Eine automatisierte Erzeugung von AsciiDoc-Dateien und PlantUML-Diagrammen.

Gerade bei komplexen Strukturen wie in der hexagonalen Architektur (Ports & Adapters) legen sich Services, Interfaces und Adapterschichten häufig in mehreren Sub-Packages ab. In Kotlin kennzeichnet man die öffentlichen Bereiche dann mit einer speziellen Klasse (z.B. `ModuleMetadata.kt`), die Spring Modulith mit den Annotationen `@PackageInfo` und `@NamedInterface` eindeutig identifiziert. Außerdem lässt sich der Zugriff anderer Module auf genau diese Bereiche durch `@ApplicationModule(allowedDependencies = […])` explizit steuern.

Für Legacy-Systeme, die sofortige Trennung in „saubere“ Module nicht erlauben, können einzelne Module auch offen deklariert werden (`type = ApplicationModule.Type.OPEN`). Dadurch bleiben vorhandene Abhängigkeiten vorerst bestehen. So lässt sich Schritt für Schritt vorgehen: Zuerst werden Module nur grob definiert, später werden einzelne Teile geschlossen, bis eine solide Modularisierung erreicht ist.

Mit diesen Bausteinen habt ihr alles an der Hand, um einen guten Einstieg in die Modularisierung mit Spring Modulith zu schaffen. 

Spring Modulith bietet neben den genannten Dingen auch noch weitere Funktionalitäten, wie Application Events, welche einen weiteren spannenden Aspekt darstellen. Da solltet ihr ebenfalls einen Blick hineinwerfen.

Eine kleine Anwendung, in der wir einige der Aspekte umgesetzt habe, findet ihr hier: [https://github.com/darthkali/spring-modulith-hex-test](https://github.com/darthkali/spring-modulith-hex-test)

##

Modularisierung leicht gemacht: Spring Modulith mit Kotlin und Hexagonale Architektur

Stellt euch eine Insel namens "Alistair Island" vor. Diese Insel ist ein lebendiger Ort mit Häusern, fruchtbaren Böden und einer eingespielten Gemeinschaft von Bewohnern, die nach klaren Abläufen leben. Jedes Geschehen auf der Insel ist von Bedeutung und dient einem bestimmten Zweck. Die täglichen Aufgaben und Rituale sind festgelegt, und die Insel funktioniert wie ein gut koordiniertes Ensemble.

Die Insel ist von einem Festland umgeben, auf dem verschiedene Länder mit unterschiedlichen Industrien und Bevölkerungsgruppen existieren. Diese produzieren unterschiedliche Waren, bieten diverse Dienstleistungen an und sprechen verschiedene Sprachen. Die Bewohner des Festlands sind vielfältig und umfassen Handwerker, Händler, Postboten und viele andere Berufe.

Nicht nur variieren die Sprachen und Waren der verschiedenen Gebiete des Festlands. Auch die Bewohner der Insel haben ihre eigene Sprache und eine einzigartige Kultur, die sich von allem auf dem Festland Bekannten unterscheidet.

![](https://eu-central-1.graphassets.com/AiE4QoWSSiIQO3k152ugkz/wtcM9pkyTcezHMl9uucT)


Obwohl die Insel isoliert ist, gibt es zahlreiche Verbindungen zur Außenwelt. An verschiedenen Küstenpunkten befinden sich Häfen, die Handel und Kommunikation mit dem Festland ermöglichen. Für den Transport von Nachrichten, Gütern und weiteren legen Schiffe an den Häfen des Festlands und der Insel an.

Um den Handel geordnet abzuwickeln, existiert ein Handelsabkommen. Es legt fest, dass Schiffe, die Waren von der Insel zum Festland transportieren oder umgekehrt, bestimmte Handelsrouten nutzen müssen. Schiffe, die vom Festland zur Insel fahren, nutzen die Routen, welche westlich der Insel liegen, während Schiffe, die von der Insel zum Festland fahren, die östlichen Routen befahren.

 ![](https://eu-central-1.graphassets.com/AiE4QoWSSiIQO3k152ugkz/B8LsrUXQQ6W1gNYjodYg)

Es gibt verschiedene Arten von Schiffen. Große Frachtschiffe sind beladen mit Lebensmitteln und Vorräten. Passagierschiffe bringen Besucher zur Insel. Kleinere Boote dienen dazu, spezielle Nachrichten und Aufträge zu überbringen.

Jedes Schiff hat einen Heimathafen. Schiffe, die auf den westlichen Handelsrouten fahren und vom Festland aus entsandt werden, legen an einem festgelegten Hafen am Festland an. Die Schiffe von der Insel warten an den Häfen der Insel, um ihre Reise anzutreten.

Entscheidend ist also nicht, in welche Richtung Waren oder Nachrichten übermittelt werden, sondern wer den Auftrag dazu gegeben hat. Betrachten wir das Ganze stets aus Sicht der Insel, so sind Schiffe, welche vom Festland aus kommen, eingehende Schiffe. Schiffe, die von der Insel entsandt werden, sind ausgehende Schiffe. Egal ob sie Waren liefern oder eine Anfrage senden  um Waren zu bekommen. Ein ausgehendes Schiff kann also durchaus die Intention haben, Waren vom Festland zur Insel zu transportieren. Dennoch gilt es als ausgehend, da die Intention von der Insel ausgeht.

Aufgrund der unterschiedlichen Sprachen der Inselbewohner und des Festlands müssen die Schiffe mit Übersetzern ausgestattet sein, um die Nachrichten des Festlands für die Inselbewohner verständlich zu machen. Auch die Güter müssen möglicherweise umverpackt werden, da auf dem Festland z. B. große Kräne zum Verladen genutzt werden, während auf der Insel alles händisch transportiert wird. Eine Qualitätsprüfung ist ebenfalls sinnvoll, um sicherzustellen, dass die Waren den Bedürfnissen der Insel entsprechen. Falls nicht, gibt das Schiff direkt Rückmeldung an das Festland. Das Ganze gilt selbstverständlich auch andersherum. Die ausgehenden Schiffe packen um, übersetzen und prüfen, ob die Waren für das Festland korrekt sind.

Die Schiffe sind die einzigen, die sowohl die Sprache der Insel als auch die des Festlands beherrschen und wissen, wie die Waren entsprechend umverpackt werden müssen. Sie sind jedoch nur für ihre jeweilige Handelsroute spezialisiert. Wenn neue Handelsrouten entstehen, kommt ein anderes Schiff zum Einsatz.

Ein weiterer wichtiger Aspekt dieser Welt ist die Stabilität der Insel. Die Stabilität der Insel bleibt, unabhängig von Änderungen der Güter oder des Baus neuer Häfen, erhalten. Lediglich die Art des Schiffes und dessen Besatzung müssen sich anpassen oder eine neue Handelsroute eingeführt werden. Die Bewohner der Insel erhalten ihre Waren und Nachrichten jedoch immer in der für sie gewohnten Art und Sprache.

So existiert Alistair Island, sicher und stabil, inmitten des weiten Ozeans. Ungeachtet neuer Schiffe oder Veränderungen auf dem Festland bleibt die Insel das, was sie ist: ein Ort voller Leben, Struktur und mit einer besonderen Verbindung zur Welt um sie herum.

<aside>

### 💡 Zusammenfassung

- Alistair Island ist eine isolierte Insel mit einer eigenen Kultur und klaren Abläufen.
- Die Insel steht in Verbindung mit einem Festland, das vielfältige Waren und Dienstleistungen bietet.
- Handelsabkommen regeln die Handelsrouten zwischen Insel und Festland.
- Schiffe, die vom Festland entsandt werden, gelten (aus Sicht der Insel) als eingehende Schiffe. Sie sind an den Häfen des Festlands stationiert und fahren immer auf den westlichen Handelsrouten.
- Schiffe, die von der Insel entsandt werden, gelten als ausgehende Schiffe. Sie sind an den Häfen der Insel stationiert und fahren immer auf den östlichen Handelsrouten.
- Es gibt verschiedene Schiffstypen, die jeweils spezifische Aufgaben übernehmen (Frachtschiffe, Passagierschiffe, kleine Boote).
- Übersetzer und Qualitätsprüfungen sind notwendig, um die Unterschiede zwischen Insel und Festland zu überwinden. Die spezialisierten Schiffe übernehmen diese Aufgabe.
- Die Stabilität der Insel bleibt gewahrt, unabhängig von äußeren Veränderungen oder neuen Handelsrouten.

</aside>

## Übertragung der Analogie in die Hexagonale Architektur

![](https://eu-central-1.graphassets.com/AiE4QoWSSiIQO3k152ugkz/mOt9dAJRMSHBA2o8wJdY)


Lasst uns nun die Analogie der Insel, Häfen und Schiffe in die Begriffe der hexagonalen Architektur übertragen, um ihre Zusammenhänge zu verdeutlichen.

### Insel - Domäne

![Finale Insel_komplett.jpg](https://eu-central-1.graphassets.com/AiE4QoWSSiIQO3k152ugkz/I1eM0DTnS5S9rWiTKldh)


Die Insel in unserer Analogie repräsentiert die Domäne – den Kern der Geschäftslogik. Die Insel ist das Zentrum, in dem alle wichtigen Prozesse und Abläufe stattfinden, genauso wie die Domäne der Ort ist, an dem die Geschäftslogik verwaltet und verarbeitet wird.

### **Schiffe - Adapter** 

 ![](https://eu-central-1.graphassets.com/AiE4QoWSSiIQO3k152ugkz/vUKzCLWiRDHG9DKfKjNQ)


Die Schiffe in der Analogie stehen für die Adapter in der hexagonalen Architektur. Sie sorgen dafür, dass die Kommunikation zwischen der Außenwelt und der Domäne tatsächlich stattfinden kann. Sie sind spezialisierte Übersetzer, welche die Sprache zwischen der Domäne und der Außenwelt (in beide Richtungen) übersetzen.

Adapter sind also maßgeblich dafür verantwortlich, dass die Anforderungen von außen in eine Form gebracht werden, die im Inneren der Domäne verarbeitet werden kann. Zudem bringen sie auch die Anforderungen nach außen in eine Form, die von der Außenwelt verstanden werden kann. Zum Beispiel könnte ein eingehender Adapter eine REST-API-Anfrage in ein Domänenobjekt übersetzen, während ein ausgehender Adapter die Domänenobjekte in eine für Datenbankabfragen oder externe API-Aufrufe verständliche Form bringt.

Wir unterscheiden also zwischen eingehenden und ausgehenden Adaptern:

- **Eingehende Adapter** nehmen Aufträge von externen Systemen oder Aktoren (Festland) entgegen, übersetzen sie und stellen sie der Domäne bereit. Die eingehenden Adapter entsprechen den eingehenden Schiffen, die von den Häfen des Festlands starten, um auf die Insel zu gelangen.
- **Ausgehende Adapter** hingegen nehmen die Antworten oder Daten der Domäne und bereiten sie für externe Systeme oder Aktoren (Festland) auf, damit sie verständlich und nutzbar sind. Die ausgehenden Adapter sind die ausgehenden Schiffe, die an den Häfen der Insel bereitstehen, um Informationen von der Domäne zurück an das Festland zu transportieren.

Ob ein Adapter nun ein eingehender oder ausgehender ist, entscheidet maßgeblich, wer den Auftrag initial gegeben hat. Dabei schauen wir immer aus der Sicht der Domäne (Insel).

### **Häfen - Ports**

  ![](https://eu-central-1.graphassets.com/AiE4QoWSSiIQO3k152ugkz/5B96iNZeQXmyC6FPzJv4)


Die Häfen, die wir in der Analogie verwendet haben, entsprechen in der hexagonalen Architektur den sogenannten Ports. Ports sind die klar definierten Schnittstellen, über die die Domäne, also der Kern der Geschäftslogik, sich von der Außenwelt abgrenzt. Dabei wird zwischen eingehenden und ausgehenden Ports unterschieden. Wir haben in der Analogie schon einmal erwähnt, dass die Schiffe ebenfalls in eingehende und ausgehende unterteilt werden. Dabei war wichtig, wer den Auftrag erteilt  und somit das Schiff entsendet hat. Die Ports (Häfen) bilden dies ebenfalls ab.

Zum Beispiel kann ein eingehender Port eine Bestellung aus einem Webshop entgegennehmen, während ein ausgehender Port Zahlungsinformationen an einen externen Zahlungsdienstleister übermittelt.

## Wie ist die Domäne aufgebaut?

Interessanterweise haben wir uns bisher kaum mit dem Innenleben der Insel selbst beschäftigt – also damit, wie die Bewohner agieren, welche Strukturen und Rituale sie pflegen. Beispielsweise könnte man sich fragen, wie sie Güter effizient verteilen, Entscheidungen im Konsens treffen oder Regeln für ein harmonisches Zusammenleben festlegen. Was machen sie mit den Gütern und Nachrichten? Wie sind die Wege in der Stadt, welche Regeln gibt es und wie werden diese eingehalten? Das liegt daran, dass die eigentliche Gestaltung der Domäne – also der Kern der Geschäftslogik – kein Bestandteil der hexagonalen Architektur ist.

Die hexagonale Architektur konzentriert sich ausschließlich auf die Gestaltung der Schnittstellen (Ports) und den zugehörigen Adaptern. Diese Fokussierung ist zentral, da sie sicherstellt, dass die Domäne unabhängig bleibt und flexibel auf Änderungen in der Außenwelt reagieren kann, ohne ihre interne Logik zu gefährden. Wie die Menschen auf der Insel miteinander interagieren, welche Regeln sie befolgen und wie die alltäglichen Prozesse ablaufen, wird durch andere Architekturprinzipien geregelt. Ein Konzept wie Domain-Driven Design (DDD) kann unter anderem dafür verantwortlich sein, wie die Domäne strukturiert wird. Ihr könnt euch auch eigene Prinzipien ausdenken oder einfach drauf los bauen – all das hat keinen direkten Einfluss auf die hexagonale Architektur und wird auch nicht von ihr vorgeschrieben.

Die wichtigste Regel der hexagonalen Architektur ist: Trennt die Domäne von der Außenwelt. Lasst die Bewohner der Insel autark arbeiten und leben, keine Änderung der Außenwelt darf direkten Einfluss auf die Bewohner der Insel haben.

# **Warum eigentlich ein Hexagon?**

Eine Frage, die bei Einsteigern in die hexagonale Architektur häufig aufkommt, ist: Warum ist es ein Hexagon? Braucht es immer sechs Elemente? Haben die gegenüberliegenden Seiten des Hexagons eine besondere Beziehung?

Die einfache, wenn auch etwas ernüchternde Antwort lautet: Es gibt keine tiefere Bedeutung hinter der Form des Hexagons. Alistair Cockburn, der diese Architektur konzipiert hat, fand die Form des Hexagons einfach spannend und wollte eine anschaulichere Bezeichnung für die Architektur als nur "Ports und Adapter". Tatsächlich ist "Ports und Adapter" der eigentlich korrekte Name für diese Architektur, aber er ist zu generisch und nicht besonders einprägsam.

Wie wir an dem Beispiel der Insel gesehen haben, funktioniert das Ganze auch mit komplett organischen Formen und braucht keine spezielle Geometrie. Das Hexagon ist nur ein symbolisches Mittel, um die unterschiedlichen Schnittstellen und Beziehungen anschaulicher darzustellen.

# **Vom Hafen zum Java Interface**

Ein kleiner Hinweis vorweg: Wer Sprachen wie JavaScript, Python und Co. nutzt, wird die Interfaces vergebens suchen. In solchen Sprachen gibt es diese Schnittstellen nur als implizite Signatur. Das Prinzip bleibt jedoch gleich, auch wenn dort die Schnittstellen nicht explizit als Interface erzeugt werden.

Nun wollen wir uns aber anschauen, wie wir das Ganze im Code umsetzen. Dazu schauen wir uns einmal das folgende Diagramm an.

![](https://eu-central-1.graphassets.com/AiE4QoWSSiIQO3k152ugkz/vTwf2booQtmqkTNLN2B3)

Wie wir sehen, haben wir hier zwischen eingehenden und ausgehenden Adaptern unterschieden. Das sind unsere Schiffe, die zwischen dem Festland und der Insel hin- und herfahren.

Die Insel ist auch in Form der Domäne vorhanden. Diese beinhaltet die Services und die Ports. Anhand der Pfeile könnt ihr nun gut erkennen, wer wen nur nutzt und wer wen implementiert. Wichtig ist hierbei noch, dass der Outbound-Port zwingend notwendig ist, da er dafür sorgt, dass die Dependency umgedreht wird. Dies folgt dem **Dependency Inversion Principle**. Der Inbound-Port ist technisch nicht zwingend notwendig. Der Adapter kann ohne Weiteres direkt auf den Service zugreifen. Durch die Einführung von Interfaces erhaltet ihr jedoch eine losere Kopplung. Außerdem leidet die Testbarkeit ein wenig, wenn ihr direkt von dem Adapter auf den Service zugreift. In der Regel solltet ihr also auch auf der eingehenden Seite einen Port vorsehen.

Nun schauen wir uns noch kurz an, wie das Ganze im Code aussieht.

Wir gehen einmal davon aus, dass wir ein Framework nutzen, welches die Dependency Injection für uns übernimmt. Spring wäre hier ein gutes Beispiel. Dann ist das alles ganz einfach: Wenn eine Klasse ein Interface nutzt, dann gebt ihr es als Übergabeparameter in den Klassenkonstruktor mit.

```kotlin
//uses
@Service
class SomeService(private val forUsingPort: ForUsingPort){
	// what ever your service does
}

```

Implementiert eine Klasse nun ein Interface, dann tut ihr das, was der Name schon sagt. Ihr lasst die Klasse den Port (ForImplementingPort) implementieren. Das sieht dann so aus:

```kotlin
// implements
@Service
class SomeService(): ForImplementingPort{
	 override fun functionOfPort(){
		 // what ever you should do here
	 }
}
```

Und das ist es im Grunde auch schon.

# **Fazit**

Die hexagonale Architektur wird häufig als überladenes Konzept wahrgenommen, doch sie beruht auf wenigen klaren Prinzipien, die ihre Anwendung überraschend einfach machen.

- Trenne die Domäne von der Außenwelt. Die Geschäftslogik und Datenverarbeitung sollten  unabhängig von der Datenbank oder Webframeworks gestaltet werden. Damit sie leichter ausgetauscht oder erweitert werden können.
- Alles, was Technologie betrifft, sollte nicht in der Domäne sein.
- Füge Ports rund um deine Domäne hinzu, um die beiden anderen Punkte sicherzustellen.

Wenn diese Grundsätze einmal verstanden sind, lässt sich die hexagonale Architektur fast immer anwenden. Selbst in kleinen Projekten ist es sinnvoll, die Domäne frei von technischen Details zu halten, um sie einfacher testen zu können. Zum Beispiel kann eine Geschäftslogik, die keine direkte Abhängigkeit zu einer spezifischen Datenbank hat, leicht in isolierten Unit-Tests überprüft werden. Die hexagonale Architektur hilft dabei und eignet sich hervorragend zur Unterstützung dieser Trennung.

Ein Tipp zum Einstieg: Ein Tool wie ArchUnit kann euch helfen, eure Umsetzung mit Tests zu überprüfen. Falls ihr darüber mehr wissen möchtet, schaut bei meinem Blogbeitrag zu ArchUnit vorbei: [ArchUnit in der Praxis: Architektur sauber halten und optimieren](https://www.codecentric.de/wissens-hub/blog/archunit-in-der-praxis-architektur-sauber-halten-und-optimieren)

Hexagonale Architektur ist auch nur eine Insel

ArchUnit in practice: Keep your Architecture Clean

# Modularization the easy way: Spring Modulith with Kotlin and Hexagonal Architecture

Modularization is a key concept in modern software development to make applications maintainable, testable and flexible. In this article we will see how Spring Modulith combined with hexagonal architecture and Kotlin provides a solid foundation for modularization. We will examine the challenges of existing monolithic applications and how clearly defined modules enable step-by-step decoupling.

## What is a Modulith?

The name says it all. A Modulith refers to an architecture where a monolith is divided into clearly defined modules. These modules are designed to be as decoupled from each other as possible while minimizing internal dependencies. You can think of it as bundling multiple microservices into a single repository and managing them as one application. For example one module could manage user data and another could handle invoicing. Both modules running in the same application but remaining distinctly separated. The advantage is clear: there is no need for complex HTTP interfaces or Kafka brokers, no authentication for inter-module communication and yet the benefit of loose coupling is maintained.

Modularization can therefore be seen as a gentle introduction to the microservices world.

## What Does Spring Modulith Do?

To divide an application into modules, there are various options. One approach is simply to organize the code into different packages. Another is to use Maven or Gradle to create modules with their own dependencies and build scripts. Additionally splitting an application into microservices is another form of modularization.

When comparing these three options it becomes apparent that their implementation effort increases progressively. While packages are easy to organize, Maven/Gradle modules already require separate dependency definitions. Deploying microservices and enabling their communication with each other adds even more complexity.

We actually want to start with packages initially. But here we run into a problem quickly. Imagine you have a legacy application where one domain model accesses another and vice versa. Even if you group logically related classes into packages it may look like different modules but it’s not really the case.

We aim for loose coupling. Ideally, we should ne able to extract a module  later and deploy it as a microservice. In that sense, we want minimal coupling which reduces refactoring effort.

Unfortunately, this coupling is hard to detect as it often only becomes evident through detailed code analysis or when observing unexpected application behavior. In the worst case, it only becomes apparent when trying to extract a module and deploy it as a standalone microservice. Such coupling often hides in subtle interdependencies between modules arising from direct accesses. Even if you clean up and decouple classes in one big action, coupling will creep back during further development.

This is where Spring Modulith helps. It checks whether you have dependencies between modules that are not allowed.

## Basics

Let’s assume we have the following structure:

```toml
src
├── Application.kt
├── module-1
│   ├── ModuleOneInterface.kt
│   └── ModuleOneService.kt
└── module-2
    ├── ModuleTwoInterface.kt
    └── ModuleTwoService.kt

```

In our `src` package, there is an `Application.kt` and alongside it two packages: `module-1` and `module-2`. Each module contains an interface and a service that implements the interface.

The first thing Spring Modulith does is to define all packages at the `Application.kt` level. This happens automatically without requiring any additional configuration. All classes and interfaces in these packages are by default considered public by Spring Modulith allowing other modules to access them.

Now, we don’t want `ModuleOneService` to directly access `ModuleTwoService` and vice versa; access should only be possible through the interfaces. To achieve this, we simply place the services in a subpackage:

```toml
src
├── Application.kt
├── module-1
│   ├── ModuleOneInterface.kt
│   └── services
│       └── ModuleOneService.kt
└── module-2
    ├── ModuleTwoInterface.kt
    └── services
        └── ModuleTwoService.kt

```

If one service now tries to access another one, the Spring Modulith-Test will fail.

## Spring Modulith Test

Since we’ve mentioned the test let’s briefly explore what these tests look like. Spring Modulith provides three main “test”-functionalities. First, there’s the actual test that analyzes our modules and verifies if we maintain the desired level of loose coupling.

```kotlin
@Test
fun `verifies modular structure`() {
    val modules = ApplicationModules.of(SpringModulithApplication::class.java)
    modules.verify()
}

```

Next we have the option to inspect the modules and their definitions. This outputs the key contents of each module such as `NamedInterfaces`, which we’ll discuss shortly.

```kotlin
@Test
fun `print module structure`() {
    val modules = ApplicationModules.of(SpringModulithApplication::class.java)
    modules.forEach(Consumer { module: ApplicationModule? -> println(module) })
}

```

Also Spring Modulith can generate a documentation. This includes various PlantUML diagrams of the modules and their relationships as well as AsciiDoc documentation with diagrams and all publicly exposed classes and interfaces.

```kotlin
@Test
fun `create module documentation`() {
    val modules = ApplicationModules.of(SpringModulithApplication::class.java)
    Documenter(modules)
        .writeDocumentation()
        .writeIndividualModulesAsPlantUml()
}

```

## Hexagonal Architecture

Rarely will our modules have simple structures like the example above. Especially when working with an architectural style like hexagonal architecture. There we have many sub-packages. Some of which we may want to expose externally. Such a structure might look like this:

```toml
src
├── Application.kt
├── module-1
│   ├── adapter
│   │   ├── inbound
│   │   └── outbound
│   ├── domain
│   │   ├── services
│   │   │   └── ModuleOneService.kt
│   │   ├── model
│   │   └── ports
│   │       ├── inbound
│   │       │   └── ModuleOneInterface.kt
│   │       └── outbound
│   └── services
└── module-2
    ├── adapter
    │   ├── inbound
    │   └── outbound
    └── domain
        ├── services
        │   └── ModuleTwoService.kt
        ├── model
        └── ports
            ├── inbound
            │   └── ModuleTwoInterface.kt
            └── outbound

```

Services still cannot access other services as they are in a subpackage. However, they also cannot access the interfaces as they are now in a subpackage as well. Here, we must explicitly define that for instance, the `module-1.domain.ports.inbound` package should be externally accessible. In Java, this is done by creating a `package-info.java` file in the package.

In Kotlin this approach doesn’t work. Instead, we create a class and annotate it. For example, we create a `ModuleMetadata.kt` file and place it in the respective package. The class name is irrelevant. You could name it `Drotbohm.kt` or `SantaClaus.kt`. The content is what matters.

```toml
└── ports
    ├── inbound
    │   ├── ModuleOneInterface.kt
    │   └── ModuleMetadata.kt

```

Here are two annotations: `@PackageInfo` and `@NamedInterface`.

```kotlin
@PackageInfo
@NamedInterface(name = ["inbound-port"])
class ModuleMetadata

```

`@PackageInfo` is unnecessary in the Java version since it is implicitly provided by the file type. In Kotlin it is required for Spring Modulith to recognize it as the package declaration file.

`@NamedInterface` defines the name under which the package will be recognized by Spring Modulith. This annotation is also required but you can omit the name parameter. In this case the package name will be used. If you want to specify a name explicitly you must use named parameters and define it as an array.

The name is particularly important in hexagonal architecture. Looking at the project tree above we see two packages named `inbound`, one in the domain and one in the adapters. Without a specified name both packages are exposed as they share the same name.

## Explicit Module Access

Imagine we have several modules in our application, each exposing some packages to other modules.

Now any module can access all exposed packages from all other modules. Thats not what we want. Instead, we want to expose a package only for specific modules. This can also be defined.

Suppose we have `module-1`, `module-2`, and `module-3`. Each has some exposed packages. We want `module-1` to access only the packages from `module-2` and within `module-2` only the `inbound-port` package.

To achieve this we create a `ModuleMetadata.kt` file at the top level of `module-1`:

```kotlin
└── module-1
    ├── ModuleMetadata.kt
    ├── adapter
    │   ├── ...
    ├── domain
        ├── ...

```

In `ModuleMetadata.kt` we add the `@ApplicationModule` annotation. Here we can declare the modules and packages the module is allowed to access using `allowedDependencies`. The schema is `Module :: Package`. The package name is either the name of the package containing the `ModuleMetadata.kt` of the other module or the name defined as a NamedInterface in the `ModuleMetadata.kt`.

```kotlin
@ApplicationModule(
    allowedDependencies = ["module-2 :: inbound-port"]
)
class ModuleMetadata

```

If you want to allow additional modules and/or NamedInterfaces, you can list them separated by commas. If you wish to allow a module but impose no restrictions on individual packages, you can use an asterisk (`*`): `allowedDependencies = ["module-2 :: *"]`.

## Legacy Application

Now that we know how to expose specific packages and explicitly declare module access, let’s apply this to a legacy application. In this case the list of errors in the Spring Modulith-Test might be long. Fixing everything at once is often impractical.

However, Spring Modulith offers an option to support modularizing legacy applications.

In the module definition, where you’ve added `allowedDependencies`, you can also add a `type` parameter. This allows you to make the entire module public, meaning all packages are accessible to all other modules even without Module-Metadata definitions.

```kotlin
@ApplicationModule(
    type = ApplicationModule.Type.OPEN,
    allowedDependencies = ["module-1 :: inbound-port"]
)
class ModuleMetadata

```

This makes it possible to create modules with their package structures while maintaining strong coupling temporarily. Your tests remain green, commits can proceed and your pipeline continues to run. This enables gradual decoupling of modules. However this approach should only remain until the module is being decoupled. Once the module is decoupled the type can be set to CLOSED or removed from the `@ApplicationModule` annotation.

## Conclusion

A Modulith is a monolith that is divided into clearly defined modules to achieve loose coupling and improved maintainability. While these modules run in a single application, they are structured so that they operate largely independently. Particularly for legacy applications with many tangled dependencies, this modular concept provides a gradual transition toward a more decoupled architecture.

Spring Modulith supports this approach by building on packaging within a Spring application and automatically detecting modules. By default, all packages of a module are public, but special “metadata” files can block unwanted dependencies or make only certain areas (such as interfaces) public. This ensures that access between modules only occurs if it is explicitly allowed.

To verify the modular structure, Spring Modulith provides three key test functions:

1. **Verification**: A test that checks whether all defined module boundaries are respected.
2. **Module Overview**: An output displaying the detected modules and their dependencies.
3. **Documentation**: Automated generation of AsciiDoc files and PlantUML diagrams.

Especially in more complex structures, such as those found in hexagonal architecture (Ports & Adapters), services, interfaces and adapter layers are often split into multiple sub-packages. In Kotlin you mark the public areas with a special class (e.g., `ModuleMetadata.kt`) that Spring Modulith recognizes through the `@PackageInfo` and `@NamedInterface` annotations. Additionally, you can explicitly control how other modules access these areas by using `@ApplicationModule(allowedDependencies = […])`.

For legacy systems that do not allow an immediate separation into “clean” modules, individual modules can also be declared as open (`type = ApplicationModule.Type.OPEN`). This way existing dependencies remain in place for the time being. You can proceed step by step: first defining modules only roughly and then gradually restricting certain parts until a solid modularization is achieved.

With these building blocks, you have everything you need to get started with modularization using Spring Modulith.

Beyond these features, Spring Modulith also offers other functionalities, such as Application Events—another exciting aspect worth exploring.

A small application where we have implemented some of these aspects can be found here: [https://github.com/darthkali/spring-modulith-hex-test](https://github.com/darthkali/spring-modulith-hex-test).

Modularization the easy way: Spring Modulith with Kotlin and Hexagonal Architecture

Imagine an island called "Alistair Island." This island is a vibrant place with houses, fertile soil, and a well-coordinated community of residents who live by well-defined routines. Every activity on the island has significance and serves a specific purpose. Daily tasks and rituals are established, and the island functions like a well-coordinated ensemble.

The island is surrounded by a mainland where various countries with diverse industries and populations exist. These countries produce different goods, offer a range of services and speak different languages. The inhabitants of the mainland are diverse including craftsmen, merchants, postal workers, and many other professions.

Not only do the languages and goods of the different regions of the mainland vary, but the island's residents also have their own language and a unique culture distinct from anything known on the mainland.

![](https://eu-central-1.graphassets.com/AiE4QoWSSiIQO3k152ugkz/wtcM9pkyTcezHMl9uucT)

Although the island is isolated, there are numerous connections to the outside world. At various coastal points, harbors facilitate trade and communication with the mainland. Ships dock at the harbors of both the mainland and the island to transport messages, goods and other stuff.

To ensure organized trade, a trade agreement is in place. It specifies that ships transporting goods from the island to the mainland or vice versa must use designated trade routes. Ships traveling from the mainland to the island use the routes west of the island, while ships traveling from the island to the mainland take the eastern routes.

![](https://eu-central-1.graphassets.com/AiE4QoWSSiIQO3k152ugkz/B8LsrUXQQ6W1gNYjodYg)

There are various types of ships. Large cargo ships are loaded with food and supplies. Passenger ships bring visitors to the island. Smaller boats are used to deliver specific messages and fulfill special assignments.

Each ship has a home harbor. Ships traveling on the western trade routes and dispatched from the mainland dock at designated mainland harbors. Ships from the island wait at the island’s harbors to embark on their journey.

The key distinction lies not in the direction of goods or messages but in who initiated the request. Viewing everything from the island’s perspective, ships coming from the mainland are considered inbound ships. Ships dispatched from the island are outbound ships. Whether they deliver goods or make requests to get goods. An outbound ship might even intend to transport goods from the mainland to the island, yet it is classified as outbound since the intent originates from the island.

Due to the different languages spoken by the islanders and mainlanders, ships must be equipped with translators to make the mainland's messages understandable for the islanders. Goods may also need to be repackaged. For example large cranes might be used for loading on the mainland, while everything is transported manually on the island. Quality checks are also advisable to ensure the goods meet the island’s needs. If not, the ship provides immediate feedback to the mainland. This process works the other way around as well. Outbound ships repackage, translate and verify that goods destined for the mainland are appropriate.

The ships are the only ones capable of understanding both the language of the island and that of the mainland as well as how to repackage goods accordingly. However, they are specialized for their respective trade routes. When new trade routes emerge, different ships are deployed.

Another important aspect of this world is the stability of the island. The island's stability remains intact regardless of changes in goods or the construction of new harbors. Only the type of ship and its crew need to adapt, or new trade routes need to be established. The islanders continue to receive their goods and messages in the manner and language they are used to.

Thats how the Alistair Island exists secure and stable in the middle of the vast ocean. Despite the emergence of new ships or changes on the mainland the island remains what it is: a place full of life, structure and a unique connection to the world around it.

<aside>

### 💡 Summary

- Alistair Island is an isolated island with its own culture and well-defined routines.
- The island is connected to a mainland that offers a wide range of goods and services.
- Trade agreements regulate the trade routes between the island and the mainland.
- Ships dispatched from the mainland are considered inbound ships (from the island's perspective). They are stationed at mainland harbors and always use the western trade routes.
- Ships dispatched from the island are considered outbound ships. They are stationed at the island's harbors and always use the eastern trade routes.
- There are different types of ships, each taking on specific tasks (cargo ships, passenger ships, small boats).
- Translators and quality checks are necessary to bridge the differences between the island and the mainland. Specialized ships handle these tasks.
- The stability of the island remains intact, regardless of external changes or the introduction of new trade routes.

</aside>

## Transferring the Analogy to Hexagonal Architecture

![](https://eu-central-1.graphassets.com/AiE4QoWSSiIQO3k152ugkz/mOt9dAJRMSHBA2o8wJdY)

Let’s now transfer the analogy of the island, harbors and ships into the terms of hexagonal architecture to clarify their relationships.

### Island - Domain

![Finale Insel_komplett.jpg](https://eu-central-1.graphassets.com/AiE4QoWSSiIQO3k152ugkz/I1eM0DTnS5S9rWiTKldh)

The island in our analogy represents the domain – the core of the business logic. The island is the center where all critical processes and routines take place, just as the domain is the place where business logic is managed and executed.

### **Ships - Adapters**

 ![](https://eu-central-1.graphassets.com/AiE4QoWSSiIQO3k152ugkz/vUKzCLWiRDHG9DKfKjNQ)

Ships in the analogy represent the adapters in hexagonal architecture. They ensure that communication between the external world and the domain can actually take place. These ships act as specialized translators that convert the "language" between the domain and the external world in both directions.

Adapters are therefore crucial in transforming external requests into a format the domain can process.  In addition they translate internal domain responses into a format the external world can understand. For example, an inbound adapter might translate a REST API request into a domain object, while an outbound adapter might convert domain objects into a format suitable for database queries or external API calls.

We distinguish between inbound and outbound adapters:

- **Inbound adapters** receive requests from external systems or actors (the mainland), translate them and pass them to the domain. These correspond to inbound ships which depart from the harbors of the mainland to reach the island.
- **Outbound adapters** on the other hand take the responses or data from the domain and prepare them for external systems or actors (the mainland) in a comprehensible and usable way. These correspond to outbound ships stationed at the island’s harbors ready to transport information from the domain back to the mainland.

Whether an adapter is inbound or outbound is determined primarily by who initiated the request. The perspective is always that of the domain (the island).

### Harbors **- Ports**

  ![](https://eu-central-1.graphassets.com/AiE4QoWSSiIQO3k152ugkz/5B96iNZeQXmyC6FPzJv4)

The harbors we used in the analogy correspond to what are known as ports in hexagonal architecture. Ports are the clearly defined interfaces that separate the domain, the core of the business logic, from the external world. A distinction is made between inbound and outbound ports. As mentioned in the analogy, ships are also divided into inbound and outbound, depending on who issued the order and dispatched the ship. Ports reflect this concept as well.

For example, an inbound port might receive an order from a webshop, while an outbound port might send payment information to an external payment provider.

## How is the domain structured?

Interestingly we have so far barely touched on the inner workings of the island itself. How the residents act, what structures and rituals they maintain. For instance one might ask how they efficiently distribute goods, make decisions by consensus or establish rules for harmonious coexistence. What do they do with the goods and messages? How are the paths in the city organized, what rules exist and how are they enforced? This is because the actual design of the domain, the core business logic, is not part of hexagonal architecture.

Hexagonal architecture focuses exclusively on designing the interfaces (ports) and their corresponding adapters. This focus is essential as it ensures that the domain remains independent and can adapt flexibly to changes in the external world without compromising its internal logic. How the people on the island interact, what rules they follow and how everyday processes function are governed by other architectural principles. Concepts like Domain-Driven Design (DDD) can play a role in structuring the domain. Alternatively, you could devise your own principles or simply build as you go. None of this directly affects hexagonal architecture and is not dictated by it.

The most important rule of hexagonal architecture is: **Separate the domain from the external world.** Let the island's residents work and live autonomously. No change in the external world should directly impact the island's inhabitants.

# Why a hexagon?

A common question among beginners in hexagonal architecture is: Why a hexagon? Does it always need six elements? Do the opposite sides of the hexagon have a special relationship?

The simple, although somewhat underwhelming, answer is: there is no deeper meaning behind the hexagonal shape. Alistair Cockburn, who conceptualized this architecture, simply found the hexagon visually appealing and wanted a more illustrative name for the architecture than just "Ports and Adapters." In fact "Ports and Adapters" is the correct name for this architecture but it’s too generic and not particularly memorable.

As we’ve seen in the island analogy the concept also works with completely organic shapes and doesn’t require any specific geometry. The hexagon is merely a symbolic tool to make the different interfaces and relationships more visually comprehensible.

# From the harbor to the Java interface.

A quick note upfront: If you’re using languages like JavaScript, Python and similar you won’t find interfaces as explicit constructs. In these languages interfaces exist only as implicit signatures. However the principle remains the same even though interfaces are not explicitly defined.

Now, let’s take a look at how to implement this in code. To do so, we’ll examine the following diagram.

![](https://eu-central-1.graphassets.com/AiE4QoWSSiIQO3k152ugkz/vTwf2booQtmqkTNLN2B3)

As we can see we have distinguished between inbound and outbound adapters. These are our ships traveling back and forth between the mainland and the island.

The island is also represented in the form of the domain. This includes the services and ports. Based on the arrows, you can clearly see who depends on whom and who implements what. It’s important to note that the outbound port is essential because it ensures the dependency is inverted. This follows the **Dependency Inversion Principle**. The inbound port however is not technically mandatory. The adapter can directly access the service without issues. But by introducing interfaces you achieve loser coupling. Additionally, testability suffers slightly if the adapter directly accesses the service. Therefore, you should typically also define a port on the inbound side.

Now let’s briefly look at how this appears in code.

Let’s assume we are using a framework that handles dependency injection for us such as Spring. This makes everything straightforward: If a class **uses** an interface, you simply pass it as a constructor parameter in the class.

```kotlin
//uses
@Service
class SomeService(private val forUsingPort: ForUsingPort){
	// what ever your service does
}
```

When a class **implements** an interface, it does exactly what the name suggests: the class implements the port (ForImplementingPort). It looks like this:

```kotlin
// implements
@Service
class SomeService(): ForImplementingPort{
	 override fun functionOfPort(){
		 // what ever you should do here
	 }
}
```

And that's it basically.

# Conclusion

Hexagonal architecture is often perceived as an overly complex concept but it is based on a few clear principles that make its application surprisingly simple:

- Separate the domain from the external world. Business logic and data processing should be designed independently of the database or web frameworks so they can be more easily replaced or extended.
- Anything related to technology should not reside within the domain.
- Add ports around your domain to ensure the first two points are upheld.

Once these principles are understood, hexagonal architecture can be applied in almost any situation. Even in small projects it is beneficial to keep the domain free of technical details to make it easier to test. For instance, business logic with no direct dependency on a specific database can be easily verified with isolated unit tests. Hexagonal architecture supports this separation and is an excellent tool for maintaining it.

**A tip for getting started:** A tool like ArchUnit can help you verify your implementation with tests. If you'd like to know more, check out my blog post on ArchUnit: [ArchUnit in practice: Keep your Architecture Clean](https://www.codecentric.de/wissens-hub/blog/archunit-in-practice-keep-your-architecture-clean)

Hexagonal Architecture is just an island

IT-Consultant & Entwickler

IT-Consultant & Developer

Projektleiterin Services/Sales/Delivery

Leipzig | Team

Vielen Dank für deine Anfrage. Ich melde mich bei dir.

Vielen Dank für deine Anmeldung. Eine E-Mail zur Bestätigung ist zu dir unterwegs.

Diese Seite ist eine Vorschau. \nKlicken Sie hier\n, um den Vorschaumodus zu verlassen.

Zu deiner Suche haben wir leider keine passenden Blogartikel gefunden. 

Du hast noch Fragen zu diesem Thema? Dann sprich mich einfach an.

Du hast Fragen oder möchtest dich mit mir austauschen? Gern - trag einfach deine Kontaktdaten ein.

Die \nDatenschutzerklärung\n der codecentric AG habe ich zur Kenntnis genommen und bestätige das mit der Absendung des Formulars.*

Entdecke spannende weiterführende Themen und lass dich von der codecentric Welt inspirieren.

Ich möchte eure Inhalte abonnieren. Diese Einwilligung kann ich jederzeit widerrufen bzw. den Blog Newsletter abbestellen. Die Datenschutzerklärung habe ich gelesen. Ich bin damit einverstanden, dass die codecentric AG, Hochstr. 11, 42697 Solingen, mich über eigene Dienstleistungen, branchenrelevante Events, Webinare und Publikationen der codecentric AG über die von mir angegebene E-Mail-Adresse informiert. Meine Einwilligung ist freiwillig. Ich kann meine Einwilligung jederzeit mit Wirkung für die Zukunft widerrufen (z.B. über den hierfür vorgesehenen Abmeldelink in unserem Newsletter, per E-Mail an datenschutz@codecentric.de oder per Post an die oben genannte Adresse der codecentric AG) erklären. Weitere Hinweise zur Verarbeitung meiner personenbezogenen Daten und zu meinen Rechten als betroffene Person finde ich hier: \nhttps://www.codecentric.de/datenschutzerklaerung\n

Bitte wähle deine/n gewünschte/n Standort/e aus.

Wir möchten dich als Mensch kennenlernen. Erzähle uns, wer du bist, worauf du Wert legst, wie du gerne arbeitest und was du von uns als Arbeitgeber erwartest.

Bitte füge deine Bewerbungsunterlagen ​(mind. Lebenslauf, gerne auch mehr)​​ ​als eine ​PDF-​Datei ​hinzu.

Es gilt die Datenschutzerklärung der codecentric AG, abrufbar unter \nDatenschutzbestimmungen\n. Mit dem Absenden des Formulars bestätige ich, dass ich diese zur Kenntnis genommen habe.

Job application form field placeholder 10

Keine passende Rolle gefunden? Bewirb dich bitte trotzdem initiativ! Jenseits von starren Schubladen zählen für uns vielmehr Motivation, Kompetenz und der Cultural Fit.

Job application form field placeholder 11

Dies ist ein Pflichtfeld, bitte fülle es aus.

Willkommen im Team Leipzig

Jetzt für unseren Newsletter anmelden