generated from MEITREX/template_microservice
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
0 parents
commit 5850e2e
Showing
47 changed files
with
1,404 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,2 @@ | ||
*.sh text eol=lf | ||
gradlew text eol=lf |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,23 @@ | ||
# To get started with Dependabot version updates, you'll need to specify which | ||
# package ecosystems to update and where the package manifests are located. | ||
# Please see the documentation for all configuration options: | ||
# https://docs.github.com/github/administering-a-repository/configuration-options-for-dependency-updates | ||
version: 2 | ||
updates: | ||
# Maintain dependencies for GitHub Actions | ||
- package-ecosystem: "github-actions" | ||
directory: "/" | ||
schedule: | ||
interval: "daily" | ||
open-pull-requests-limit: 5 | ||
labels: | ||
- "Github Actions" | ||
|
||
# Maintain App gradle dependencies | ||
- package-ecosystem: "gradle" | ||
directory: "/" | ||
schedule: | ||
interval: "daily" | ||
open-pull-requests-limit: 5 | ||
labels: | ||
- "Dependencies" |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,31 @@ | ||
name: Building Docker Image | ||
|
||
on: | ||
workflow_run: | ||
workflows: | ||
- Testing CI pipeline | ||
types: | ||
- completed | ||
|
||
jobs: | ||
docker-build: | ||
runs-on: ubuntu-latest | ||
if: github.ref == 'refs/heads/main' | ||
steps: | ||
- name: Setup docker buildx | ||
uses: docker/setup-buildx-action@v3 | ||
|
||
- name: Login to GitHub Container Registry | ||
uses: docker/login-action@v3 | ||
with: | ||
registry: ghcr.io | ||
username: ${{ github.actor }} | ||
password: ${{ secrets.GITHUB_TOKEN }} | ||
|
||
- name: Build docker container | ||
uses: docker/build-push-action@v5 | ||
with: | ||
cache-from: type=gha | ||
cache-to: type=gha,mode=max | ||
tags: ghcr.io/it-rex-platform/template_microservice:latest | ||
push: true |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,37 @@ | ||
name: Testing CI pipeline | ||
|
||
on: push | ||
|
||
jobs: | ||
test: | ||
runs-on: ubuntu-latest | ||
steps: | ||
- uses: actions/checkout@v4 | ||
with: | ||
fetch-depth: 0 | ||
- name: Set up JDK 21 | ||
uses: actions/setup-java@v4 | ||
with: | ||
java-version: '21' | ||
distribution: 'temurin' | ||
- name: Validate Gradle wrapper | ||
uses: gradle/wrapper-validation-action@v2 | ||
- name: Run chmod to make gradlew executable | ||
run: chmod +x gradlew | ||
|
||
- name: Run tests | ||
uses: gradle/gradle-build-action@v3 | ||
with: | ||
arguments: cleanTest test | ||
# Configuration for SonarCloud, enable this when SonarCloud is configured | ||
# - name: Execute tests | ||
# env: | ||
# SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }} | ||
# uses: gradle/gradle-build-action@v3 | ||
# with: | ||
# arguments: cleanTest test jacocoTestReport sonar | ||
|
||
|
||
|
||
|
||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,37 @@ | ||
HELP.md | ||
.gradle | ||
build/ | ||
!gradle/wrapper/gradle-wrapper.jar | ||
!**/src/main/**/build/ | ||
!**/src/test/**/build/ | ||
|
||
### STS ### | ||
.apt_generated | ||
.classpath | ||
.factorypath | ||
.project | ||
.settings | ||
.springBeans | ||
.sts4-cache | ||
bin/ | ||
!**/src/main/**/bin/ | ||
!**/src/test/**/bin/ | ||
|
||
### IntelliJ IDEA ### | ||
.idea | ||
*.iws | ||
*.iml | ||
*.ipr | ||
out/ | ||
!**/src/main/**/out/ | ||
!**/src/test/**/out/ | ||
|
||
### NetBeans ### | ||
/nbproject/private/ | ||
/nbbuild/ | ||
/dist/ | ||
/nbdist/ | ||
/.nb-gradle/ | ||
|
||
### VS Code ### | ||
.vscode/ |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,24 @@ | ||
# syntax=docker/dockerfile:experimental | ||
FROM gradle:7.6.2-jdk17 AS build | ||
WORKDIR /workspace/app | ||
|
||
# Copy only gradle files to container so we can install them | ||
COPY ./build.gradle ./settings.gradle /workspace/app/ | ||
|
||
# install dependencies. This will be cached by the docker layered cache. This command will fail because the | ||
# app code is still missing, so we return 0 so docker thinks the command executed successfully (but the | ||
# dependencies are still downloaded even if the command fails so now we have them cached) | ||
RUN gradle clean build -x test || return 0 | ||
|
||
# Now copy the actual app code and build it | ||
COPY . /workspace/app | ||
RUN gradle clean build -x test | ||
RUN mkdir -p build/dependency && (cd build/dependency; jar -xf ../libs/*-SNAPSHOT.jar) | ||
|
||
FROM eclipse-temurin:17-jdk | ||
VOLUME /tmp | ||
ARG DEPENDENCY=/workspace/app/build/dependency | ||
COPY --from=build ${DEPENDENCY}/BOOT-INF/lib /app/lib | ||
COPY --from=build ${DEPENDENCY}/META-INF /app/META-INF | ||
COPY --from=build ${DEPENDENCY}/BOOT-INF/classes /app | ||
ENTRYPOINT ["java","-cp","app:app/lib/*","de.unistuttgart.iste.meitrex.template.TemplateForMicroservicesApplication"] |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,21 @@ | ||
MIT License | ||
|
||
Copyright (c) 2023 MEITREX | ||
|
||
Permission is hereby granted, free of charge, to any person obtaining a copy | ||
of this software and associated documentation files (the "Software"), to deal | ||
in the Software without restriction, including without limitation the rights | ||
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell | ||
copies of the Software, and to permit persons to whom the Software is | ||
furnished to do so, subject to the following conditions: | ||
|
||
The above copyright notice and this permission notice shall be included in all | ||
copies or substantial portions of the Software. | ||
|
||
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR | ||
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, | ||
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE | ||
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER | ||
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, | ||
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE | ||
SOFTWARE. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,165 @@ | ||
# template-microservice | ||
This serves as a template for the microservices | ||
|
||
## Package structure | ||
|
||
This package structure is based on multiple sources of best practices in Spring Boot, using roughly the "Package by layer" approach. | ||
- *root* | ||
- *config* | ||
- *controller* | ||
- *dapr* | ||
- *dto* | ||
- *exception* | ||
- *persistence* | ||
- *entity* | ||
- *repository* | ||
- *mapper* | ||
- *service* | ||
- *util* (optional, if needed) | ||
- *validation* | ||
|
||
Detailed description of the packages: | ||
|
||
### Root package | ||
|
||
This should be named after the microservice itself. This is the root package for the microservice. It contains the `Application.java` file (or of similar name), which is the entry point for the microservice. Usually, this is the only class in this package. | ||
|
||
### Config package | ||
This package should contain any classes that are used to configure the application. This includes [Sprint Boot configuration classes](https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/context/annotation/Configuration.html) but might also contain anything else related to configuration the microservice. | ||
The classes that are in this package should not be deleted in the actual microservice as they provide useful functionality. | ||
|
||
### Controller package | ||
|
||
**Location:src/main/java/de/unistuttgart/iste/meitrex/{service_name}/controller** | ||
|
||
This package contains the GraphQL controllers (and other types of controllers if needed). The GraphQL controllers are annotated with the `@Controller` annotation. Controllers contain no business logic, but only delegate the requests to the service layer. They handle the "technical stuff" of the request. | ||
|
||
In some services, there is also a class called SubscriptionController which handles all dapr event subscriptions. | ||
|
||
More information can be found in | ||
the [Controller package](src/main/java/de/unistuttgart/iste/meitrex/template/controller/package-info.java). | ||
|
||
### Dapr package | ||
|
||
**Location**:src/main/java/de/unistuttgart/iste/meitrex/{service_name}/dapr | ||
|
||
This package should contain all classes that are used to communicate with Dapr, e.g. using pub sub. | ||
|
||
### DTO package | ||
|
||
**This package will not be located in the src/main/java folder, but in the build/generated folder.** | ||
|
||
This package contains the generated DTOs (data transfer objects) from the GraphQL schema. The DTOs are generated when building the project with gradle. | ||
|
||
If not necessary, no other files should be added manually to this package. | ||
|
||
#### Why both DTOs and Entities? | ||
|
||
The DTOs are used to transfer data between the GraphQL controller and the service layer. The entities are used to persist data in the database. This is done to separate the data transfer from the data persistence. This is a common approach in Spring Boot applications as it can happen that we want to store more data in the database than we want to transfer to the client or vice versa. | ||
|
||
### Exception package | ||
|
||
**Location**:src/main/java/de/unistuttgart/iste/meitrex/{service_name}/exception | ||
|
||
This package is used for exception handling. Note that with GraphQL, the exceptions are not thrown directly, but are wrapped in a `GraphQLException`, which is different that from the usual Spring Boot approach. | ||
|
||
More information can be found in | ||
the [Exception package](src/main/java/de/unistuttgart/iste/meitrex/template/exception/package-info.java). | ||
|
||
### Persistence package | ||
|
||
**Location**:src/main/java/de/unistuttgart/iste/meitrex/{service_name}/persistence | ||
|
||
This package contains all classes that are used to persist data in the database. This includes the entities, the mapping | ||
logic between entities and DTOs, as well as the repositories. | ||
|
||
This package handles the calls to the database and defines the database entities. It is structured into three sub-packages: | ||
|
||
#### 1. entity | ||
This package contains the database entities. | ||
|
||
#### 2. repository | ||
This package contains the interfaces to the database, also known as Data Access Objects (DAOs), used to perform various database operations. Note that these interfaces may sometimes be empty, especially when the default methods provided by the Spring Framework are sufficient for the required operations. | ||
|
||
#### 3. mapper | ||
The 'mapper' package is responsible for the mapping logic between the database entities and the data types defined in the GraphQL schema. Specifically, it maps the database entity classes to the corresponding classes generated from the GraphQL schema. | ||
|
||
This structure helps organize the database-related components of the project, making it easier to manage and maintain. | ||
|
||
More information can be found in | ||
the [Entity package](src/main/java/de/unistuttgart/iste/meitrex/template/persistence/entity/package-info.java) and | ||
the [Repository package](src/main/java/de/unistuttgart/iste/meitrex/template/persistence/repository/package-info.java). | ||
|
||
### Service package | ||
|
||
**Location**:src/main/java/de/unistuttgart/iste/meitrex/{service_name}/service | ||
|
||
This package contains all classes that are used to handle the business logic of the microservice. Services are annotated with the `@Service` annotation. Services contain only business logic and delegate the data access to the persistence layer (repositories). | ||
|
||
More information can be found in | ||
the [Service package](src/main/java/de/unistuttgart/iste/meitrex/template/service/package-info.java). | ||
|
||
### Validation package | ||
|
||
**Location**:src/main/java/de/unistuttgart/iste/meitrex/{service_name}/validation | ||
|
||
This package should contain the *class-level* validation logic, i.e. the validation logic that is not directly related to a specific field, e.g. validation if an end date is after a start date. | ||
|
||
Field-level validation logic should not be placed in this package, but in the graphql schema, via directives. | ||
If these directives are not sufficient, the validation logic can also be placed in this package. | ||
|
||
## Getting Started | ||
|
||
### Todos | ||
|
||
Follow the guide in the wiki: https://github.com/MEITREX/wiki/blob/main/dev-manuals/backend/new-service.md | ||
|
||
Addtionally, after cloning the repository, you need to do the following steps: | ||
- [ ] Setup the gradle files correctly. This means | ||
- [ ] Change the project name in the `settings.gradle` file | ||
- [ ] Change the package name in the `build.gradle` file (there is a TODO comment) | ||
- [ ] Change the sonar project key in the `build.gradle` file (should be MEITREX_repository_name) | ||
- [ ] Add/Remove dependencies in the `build.gradle` file | ||
- [ ] Rename the package in the `src/main/java` folder to a more suitable name (should be the same as the package name in the `build.gradle` file) | ||
- [ ] Remove the package-info.java files in the `src/main/java` folder (or update with the microservice specific information) | ||
- [ ] Update the application.properties file in the `src/main/resources` folder (check the TODOS in the file) | ||
- [ ] Change the ports and name of the database in the docker-compose.yml (see wiki on how to) | ||
- [ ] Define the GraphQL schema in the `src/main/resources/schema.graphqls` file | ||
<!-- TODO there probably more TODOs --> | ||
|
||
|
||
After creating a new service you need to do the following: | ||
- [ ] Add the repository to sonarcloud, follow the instructions for extra configuration, unselect automatic analysis and choose github actions, only the first step needs to be completed | ||
- [ ] Add SONAR_TOKEN to the service repository secrets on Github (this requires you to have admin permissions on sonarcloud) | ||
|
||
### Pull new changes from this template | ||
|
||
If this template changes and you want to pull the changes to the actual microservice, you can run the following commands: | ||
```bash | ||
git remote add template https://github.com/MEITREX/template_microservice # only necessary once | ||
git fetch --all | ||
git checkout [branch] # replace [branch] with the branch name you want the changes to be merged into (preferably not main) | ||
git merge template/main --allow-unrelated-histories | ||
# you will probably need to commit afterwars | ||
``` | ||
|
||
### Guides | ||
The following guides illustrate how to use some features concretely: | ||
|
||
* [Building a GraphQL service](https://spring.io/guides/gs/graphql-server/) | ||
* [Accessing Data with JPA](https://spring.io/guides/gs/accessing-data-jpa/) | ||
* [Validation with GraphQL directives](https://github.com/graphql-java/graphql-java-extended-validation/blob/master/README.md) | ||
* [Error handling](https://www.baeldung.com/spring-graphql-error-handling) | ||
|
||
### Reference Documentation | ||
For further reference, please consider the following sections: | ||
|
||
* [Official Gradle documentation](https://docs.gradle.org) | ||
* [Spring Boot Gradle Plugin Reference Guide](https://docs.spring.io/spring-boot/docs/3.0.6/gradle-plugin/reference/html/) | ||
* [Spring Configuration Processor](https://docs.spring.io/spring-boot/docs/3.0.6/reference/htmlsingle/#appendix.configuration-metadata.annotation-processor) | ||
* [Spring Boot DevTools](https://docs.spring.io/spring-boot/docs/3.0.6/reference/htmlsingle/#using.devtools) | ||
* [Spring for GraphQL](https://docs.spring.io/spring-boot/docs/3.0.6/reference/html/web.html#web.graphql) | ||
* [Spring Data JPA](https://docs.spring.io/spring-boot/docs/3.0.6/reference/htmlsingle/#data.sql.jpa-and-spring-data) | ||
* [Validation](https://docs.spring.io/spring-boot/docs/3.0.6/reference/htmlsingle/#io.validation) | ||
* [Generating Sonarqube Token](https://docs.sonarqube.org/latest/user-guide/user-account/generating-and-using-tokens/) | ||
* [Adding secrets on Github](https://docs.github.com/en/actions/security-guides/encrypted-secrets) |
Oops, something went wrong.