spring-modulith-verifier

Spring Modulith 验证器技能

采用领域驱动的模块化布局：按业务模块组织包，而非按技术层组织。

推荐的示例包结构

dev.sivalabs.projectname/
├── Application                      # Main Spring Boot entrypoint class
├── shared/                          # Cross-cutting concerns
│   ├── package-info.java
├── users/                           # Users module (bounded context)
│   ├── config/                      # Users module-specific config
│   ├── domain/                      # Domain logic
│   │   ├── models/                  # Domain models
│   │   │   ├── package-info.java
│   │   ├── exceptions/              # Domain custom Exception classes
│   │   │   ├── package-info.java
│   │   ├── {entities, repositories, mappers, services}
│   ├── api/                        # REST API layer
│   │   ├── {controllers, DTOs}      # REST controllers, Request, Response payload DTOs
│   └── UsersAPI.java                # Module's public API (facade)
│
├── catalog/                         # Catalog module
├── orders/                          # Orders module
└── config/                          # Global Configuration
    └── WebMvcConfig.java
    └── SecurityConfig.java
    └── WebSecurityConfig.java
    └── GlobalExceptionHandler.java

上述包结构说明：

• Application.java：使用 @SpringBootApplication 注解的 Spring Boot 主入口类。包含用于启动应用程序的 main() 方法。

• shared/：包含多个模块共享的横切关注点和实用工具（例如，通用工具、共享 DTO、基类、自定义注解）。

• {module}/（例如，users/、catalog/、orders/）：每个业务模块代表一个限界上下文，并包含：

  • config/：模块专属的配置类，使用 @Configuration 注解，用于定义仅与此模块相关的 Bean、属性或第三方集成。

  • domain/：包含以下内容的核心业务逻辑层：

    • models/：表示业务概念的领域模型类（命令、查询对象、枚举、值对象、结果对象等，而非 JPA 实体）。这些是封装业务规则的纯 Java 对象。
    • exceptions/：领域专属的自定义异常类。
    • entities：使用 @Entity 注解、映射到数据库表的 JPA 实体类。为避免直接实例化并确保封装性，这些类不应为 public。
    • repositories：继承 JpaRepository 或 CrudRepository、用于数据访问的 Spring Data JPA 仓库接口。这些接口不应为 public。
    • mappers：在实体、领域模型和 DTO 之间转换的映射器类/接口（例如，MapStruct 映射器）。这些类或接口不应为 public。
    • services：使用 @Service 注解的服务类，包含业务逻辑、使用映射器转换 Bean、事务管理以及对仓库调用的编排。

  • api/：REST API 层，包含：

    • controllers：使用 @RestController 注解的 REST 控制器类，负责处理 HTTP 请求、验证输入并委托给服务。
    • DTOs：数据传输对象，包括请求负载（客户端传入的数据）和响应负载（发送给客户端的数据）。

  • {Module}API.java：作为模块公共 API 的门面类，负责委托服务调用，只公开其他模块应访问的内容，同时隐藏内部实现细节。

• config/：全局应用程序配置类，包括：

  • WebMvcConfig.java：MVC 配置（CORS、拦截器、格式化器）。
  • SecurityConfig.java：用于身份验证和授权的 Spring Security 配置。
  • GlobalExceptionHandler.java：使用 @RestControllerAdvice 集中处理异常，以提供一致的错误响应。

可见性修饰符

默认采用必要的最低可见性。仅公开其他模块或层真正需要的内容。

组件	类	构造函数	方法
控制器	package-private	package-private	package-private
服务	public	package-private	public
仓库	package-private（接口）	—	—
实体	package-private	protected	public
DTO / record	public 或 package-private	—	—
模块 API 门面	public	package-private	public
请求/响应 record	package-private	—	—
配置/异常处理器	package-private	—	—

Naming Conventions

Type	Convention	Example
Entities	*Entity	UserEntity, AddressEntity
Value Objects	Domain name (record)	Email, UserCode, UserId
Commands	*Cmd	CreateUserCmd, UpdateAddressCmd
Command Response	*Result	LoginResult, RegistrationResult
DTOs	*Dto	UserDto, AddressDto
HTTP Request	*Request	CreateUserRequest, CreateAddressRequest
HTTP Response	*Response	CreateUserResponse, CreateAddressResponse
Repositories	*Repository	UserRepository, AddressBookRepository
Services	*Service	UserService, AddressBookService
Domain Exceptions	*Exception	InvalidUserCreationException, UserCancellationException
Module API	*API	UsersAPI