From 0d91ea86b8aa7f2bea76942e24085792f9359ac7 Mon Sep 17 00:00:00 2001 From: alfredo-toledano Date: Sat, 6 Jul 2024 13:21:47 +0200 Subject: [PATCH] doc(pages.using.structuringYourCode): add notes --- .../pages/using/structuring-your-code.adoc | 41 +++++++++---------- 1 file changed, 19 insertions(+), 22 deletions(-) diff --git a/spring-boot-project/spring-boot-docs/src/docs/antora/modules/reference/pages/using/structuring-your-code.adoc b/spring-boot-project/spring-boot-docs/src/docs/antora/modules/reference/pages/using/structuring-your-code.adoc index 6f00571b3005..16e63d52dfd5 100644 --- a/spring-boot-project/spring-boot-docs/src/docs/antora/modules/reference/pages/using/structuring-your-code.adoc +++ b/spring-boot-project/spring-boot-docs/src/docs/antora/modules/reference/pages/using/structuring-your-code.adoc @@ -1,35 +1,33 @@ [[using.structuring-your-code]] = Structuring Your Code -Spring Boot does not require any specific code layout to work. -However, there are some best practices that help. - -TIP: If you wish to enforce a structure based on domains, take a look at https://spring.io/projects/spring-modulith#overview[Spring Modulith]. - - +* 👁️ NOT required by Spring Boot 👁️ +* https://spring.io/projects/spring-modulith#overview[Spring Modulith] + ** enforce structure -- based on -- domains [[using.structuring-your-code.using-the-default-package]] == Using the "`default`" Package -When a class does not include a `package` declaration, it is considered to be in the "`default package`". -The use of the "`default package`" is generally discouraged and should be avoided. -It can cause particular problems for Spring Boot applications that use the `@ComponentScan`, `@ConfigurationPropertiesScan`, `@EntityScan`, or `@SpringBootApplication` annotations, since every class from every jar is read. - -TIP: We recommend that you follow Java's recommended package naming conventions and use a reversed domain name (for example, `com.example.project`). +* uses + ** class does NOT include a `package` declaration +* recommendation + ** avoided + *** == declare always + *** Reason: 🧠 for Spring Boot applications / use `@ComponentScan`, `@ConfigurationPropertiesScan`, `@EntityScan`, or `@SpringBootApplication` -> every class from every .jar is read -> it can cause particular problems 🧠 + ** follow Java's recommended package naming conventions & reversed domain name ( _Example:_ `com.example.project`) [[using.structuring-your-code.locating-the-main-class]] == Locating the Main Application Class -We generally recommend that you locate your main application class in a root package above other classes. -The xref:using/using-the-springbootapplication-annotation.adoc[`@SpringBootApplication` annotation] is often placed on your main class, and it implicitly defines a base "`search package`" for certain items. -For example, if you are writing a JPA application, the package of the `@SpringBootApplication` annotated class is used to search for `@Entity` items. -Using a root package also allows component scan to apply only on your project. - -TIP: If you do not want to use `@SpringBootApplication`, the `@EnableAutoConfiguration` and `@ComponentScan` annotations that it imports defines that behavior so you can also use those instead. - -The following listing shows a typical layout: +* recommendation + ** main application class in a root package above other classes + *** -> component scan -- is applied -- only on your project + ** xref:using/using-the-springbootapplication-annotation.adoc[`@SpringBootApplication` annotation] oftenly placed on your main class + *** -> defines a base "`search package`" / certain items + **** _Example:_ if you are writing a JPA application -> the package of the `@SpringBootApplication` annotated class -- is used to search for -- `@Entity` items +* _Example:_ typical layout [source] ---- @@ -50,7 +48,6 @@ com +- OrderService.java +- OrderRepository.java ---- + ** `MyApplication.java` would declare the `main` method + `@SpringBootApplication` -The `MyApplication.java` file would declare the `main` method, along with the basic `@SpringBootApplication`, as follows: - -include-code::MyApplication[] + include-code::MyApplication[]