How to organize the project structure of a REST API service?

[rijekaDrina]

My current project structure looks something like this:

• advice
• config
• controller
• domain
• dto
• exception
• repo
• service

I wish to use Spring Modulith and group code based on modules of my business domain. I have found some examples in this discussion. All of them have a different structure, none of which follow the guidelines fully. So I wonder what would be a recommended approach, let's say I get name these three modules: users, polls and posts.

Would the correct / recommended structure look like this?

├ user -- package
│ ├ UserController.java
│ ├ UserService.java
│ ├ UserCreateDto.java
│ └ UserReadDto.java
└ user.internal -- package
  ├ UserRepository.java
  ├ User.java
  └ UserNotFoundException.java

And what if I for example, have multiple controllers and services inside a module? Should I do subgrouping like service and controller, or is that rudimentary?

[odrotbohm]

Before we start, please note that it does not make sense to discuss module structure with only a single module present. Spring Modulith primarily helps to organize code into multiple, functional modules. What kind of technical organization you use within those modules is actually a bit out of scope as it is, essentially, an implementation detail of the module and thus doesn't affect the maintainability of the overall arrangement.

Basically, you have two options:

Single-package approach

Simply stick to the user package. Types that need to be accessed by other modules, need to be declared public (+). Everything else stays package private (o).

└ user
  ├ + User.java
  ├ o UserController.java
  ├ o UserCreateDto.java
  ├ + UserNotFoundException.java // Assuming this is thrown from UserService
  ├ o UserRepository.java
  ├ + UserService.java
  └ o UserReadDto.java

Choose a technical organization scheme to further structure the content of the module

In your case, that would look something like this:

├ user
│ ├ + User.java
│ ├ o UserRepository.java
│ ├ + UserService.java
│ └ + UserNotFoundException.java
└ user.web
  ├ o UserController.java
  ├ o UserCreateDto.java
  └ o UserReadDto.java

This arrangement doesn't make any difference from a Spring Modulith perspective, as everything in web is still not accessible by other modules. Moving the types into a separate package might make it easier to further constrain the code in it. For example, only code in packages named web might be allowed to access Spring MVC, the Servlet API etc.

In Onion Architecture, web belongs to the infrastructure ring, the service implementation to the application one. Everything else belongs to the domain. Mapping this to Hexagonal Architecture would need you to introduce an interface for the UserService so that you could set up a port (the interface) and application (the implementation) arrangement. The code in theweb package then constitutes an adapter. That said, it's just different lingo, not fundamentally different approaches.

Miscellaneous

Note, that packages are not necessarily the best means to assign roles to certain types. Their primary purpose is to provide means of encapsulation, which the simple approach uses to its maximum, as we can solely rely on the compiler to enforce the visibility. Alternatively to packages, you might want to check out jMolecules. That gives you a vocabulary (Onion, Hexagonal Architecture) in the form of annotations and interfaces so that you can assign those architectural roles to types and also get dependency verification via the corresponding ArchUnit rules.

[odrotbohm]

To achieve what exactly?

[DreamStar92]

Maybe use classical project structure.

com.test.example (project)
├── catelog  (eq order)
├── order (module)
│   ├── package-info.java (Declare dependencies)
│   ├── application (application layer)
│   │   ├── contract
│   │   │   ├── CreateOrderCmd.java (c)
│   │   │   ├── OrderCreatedEvent.java (e)
│   │   │   └── OrderQuery.java (q, maybe split)
│   │   ├── OrderAppService.java
│   │   └── Mapper.java (contract dto to/from domain value object)
│   ├── domain (domain layer)
│   │   ├── model
│   │   │   ├── Order.java
│   │   │   └── (option order dir,if has many aggregate root)
│   │   ├── service (domain service)
│   │   │   └── OrderService.java
│   │   └── repository
│   │       └── OrderRepo.java
│   └── infrastructure (infrastructure api)
│       ├── controller (web api)
│       │   └── ControllerAdvice.java
│       ├── listener (domain listener, application listener)
│       │   └── KafkaConfig.java
│       ├── rpc (APIs exposed to other modules, maybe jvm_local,http,grpc)
│       │   └── package-info.java (Declare NamedInterface)
│       ├── service  (service impl)
│       └── repository (repository impl)
├── inventory (eq order)
├── package-info.java
├── shared (common config advice, this is module independent)
└── SpringApplication.java

This modular monolithic structure can quickly locate target modules while making it easy to understand layer isolation. It also has strong scalability support for future splits.
It's also easy to apply this project to this directory structure.

My native language is not English, so please forgive me for the wording problem. We can communicate if anything is unclear.