Spring Boot 项目结构规范 | 清晨的一缕阳光

前言

良好的项目结构是代码可维护性的基础。合理的目录组织、包结构、模块划分能让项目更加清晰易维护。本文将介绍 Spring Boot 项目结构的完整规范。

基础项目结构

1. 标准目录结构

demo/
├── src/
│   ├── main/
│   │   ├── java/
│   │   │   └── com/example/demo/
│   │   │       ├── DemoApplication.java      # 启动类
│   │   │       ├── controller/                # 控制器层
│   │   │       │   ├── UserController.java
│   │   │       │   └── OrderController.java
│   │   │       ├── service/                   # 服务层
│   │   │       │   ├── UserService.java
│   │   │       │   ├── OrderService.java
│   │   │       │   └── impl/                  # 服务实现
│   │   │       │       ├── UserServiceImpl.java
│   │   │       │       └── OrderServiceImpl.java
│   │   │       ├── repository/                # 数据访问层
│   │   │       │   ├── UserRepository.java
│   │   │       │   └── OrderRepository.java
│   │   │       ├── entity/                    # 实体类
│   │   │       │   ├── User.java
│   │   │       │   └── Order.java
│   │   │       ├── dto/                       # 数据传输对象
│   │   │       │   ├── request/               # 请求 DTO
│   │   │       │   │   ├── UserCreateDTO.java
│   │   │       │   │   └── UserUpdateDTO.java
│   │   │       │   └── response/              # 响应 DTO
│   │   │       │       └── UserDTO.java
│   │   │       ├── config/                    # 配置类
│   │   │       │   ├── WebConfig.java
│   │   │       │   └── SecurityConfig.java
│   │   │       ├── common/                    # 公共类
│   │   │       │   ├── exception/             # 异常类
│   │   │       │   │   ├── BusinessException.java
│   │   │       │   │   └── GlobalExceptionHandler.java
│   │   │       │   ├── result/                # 统一响应
│   │   │       │   │   └── R.java
│   │   │       │   └── constants/             # 常量
│   │   │       │       └── Constants.java
│   │   │       └── util/                      # 工具类
│   │   │           ├── DateUtils.java
│   │   │           └── JwtUtils.java
│   │   └── resources/
│   │       ├── application.yml                # 主配置文件
│   │       ├── application-dev.yml            # 开发环境配置
│   │       ├── application-test.yml           # 测试环境配置
│   │       ├── application-prod.yml           # 生产环境配置
│   │       ├── mapper/                        # MyBatis Mapper
│   │       │   └── UserMapper.xml
│   │       ├── templates/                     # 模板文件
│   │       └── static/                        # 静态资源
│   └── test/
│       └── java/
│           └── com/example/demo/
│               ├── DemoApplicationTests.java
│               ├── controller/                # 控制器测试
│               ├── service/                   # 服务测试
│               └── repository/                # 数据访问测试
├── docs/                                      # 文档
│   ├── api/                                   # API 文档
│   └── design/                                # 设计文档
├── scripts/                                   # 脚本
│   ├── deploy.sh                              # 部署脚本
│   └── init.sql                               # 初始化 SQL
├── pom.xml                                    # Maven 配置
├── README.md                                  # 项目说明
└── .gitignore                                 # Git 忽略文件

2. 启动类

package com.example.demo;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.scheduling.annotation.EnableAsync;
import org.springframework.scheduling.annotation.EnableScheduling;

@SpringBootApplication
@EnableAsync  // 启用异步
@EnableScheduling  // 启用定时任务
public class DemoApplication {
    
    public static void main(String[] args) {
        SpringApplication.run(DemoApplication.class, args);
    }
}

3. pom.xml 结构

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 
         https://maven.apache.org/xsd/maven-4.0.0.xsd">
    
    <modelVersion>4.0.0</modelVersion>
    
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>4.0.0</version>
    </parent>
    
    <groupId>com.example</groupId>
    <artifactId>demo</artifactId>
    <version>1.0.0-SNAPSHOT</version>
    <name>demo</name>
    <description>Demo Project</description>
    
    <properties>
        <java.version>21</java.version>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    </properties>
    
    <dependencies>
        <!-- Spring Boot Starters -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        
        <!-- Database -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-data-jpa</artifactId>
        </dependency>
        
        <!-- Test -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
    </dependencies>
    
    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>
</project>

包结构规范

1. 按功能分层

com.example.demo/
├── controller/          # 控制器层
├── service/             # 服务层
├── repository/          # 数据访问层
├── entity/              # 实体类
├── dto/                 # 数据传输对象
├── config/              # 配置类
├── common/              # 公共类
└── util/                # 工具类

2. 按业务模块划分

com.example.demo/
├── user/                # 用户模块
│   ├── controller/
│   ├── service/
│   ├── repository/
│   ├── entity/
│   └── dto/
├── order/               # 订单模块
│   ├── controller/
│   ├── service/
│   ├── repository/
│   ├── entity/
│   └── dto/
└── product/             # 商品模块
    ├── controller/
    ├── service/
    ├── repository/
    ├── entity/
    └── dto/

3. 混合划分

com.example.demo/
├── controller/          # 统一控制器
├── service/             # 统一服务层
├── repository/          # 统一数据访问层
├── entity/              # 统一实体类
├── dto/                 # 统一 DTO
├── user/                # 用户业务包
│   ├── UserService.java
│   └── UserConverter.java
├── order/               # 订单业务包
│   ├── OrderService.java
│   └── OrderConverter.java
└── config/              # 配置类

模块划分

1. 多模块项目结构

demo-parent/
├── demo-common/         # 公共模块
│   ├── src/
│   │   └── main/
│   │       └── java/
│   │           └── com/example/demo/common/
│   │               ├── result/          # 统一响应
│   │               ├── exception/       # 异常类
│   │               ├── constants/       # 常量
│   │               └── util/            # 工具类
│   └── pom.xml
├── demo-system/         # 系统模块
│   ├── src/
│   │   └── main/
│   │       └── java/
│   │           └── com/example/demo/system/
│   │               ├── user/            # 用户管理
│   │               ├── role/            # 角色管理
│   │               └── menu/            # 菜单管理
│   └── pom.xml
├── demo-business/       # 业务模块
│   ├── src/
│   │   └── main/
│   │       └── java/
│   │           └── com/example/demo/business/
│   │               ├── order/           # 订单
│   │               └── product/         # 商品
│   └── pom.xml
├── demo-admin/          # 管理后台
│   ├── src/
│   │   └── main/
│   │       └── java/
│   │           └── com/example/demo/admin/
│   │               └── controller/
│   └── pom.xml
├── demo-app/            # 应用模块
│   ├── src/
│   │   └── main/
│   │       └── java/
│   │           └── com/example/demo/app/
│   │               └── controller/
│   └── pom.xml
└── pom.xml              # 父 POM

2. 父 POM 配置

<!-- demo-parent/pom.xml -->
<project>
    <modelVersion>4.0.0</modelVersion>
    
    <groupId>com.example</groupId>
    <artifactId>demo-parent</artifactId>
    <version>1.0.0-SNAPSHOT</version>
    <packaging>pom</packaging>
    
    <modules>
        <module>demo-common</module>
        <module>demo-system</module>
        <module>demo-business</module>
        <module>demo-admin</module>
        <module>demo-app</module>
    </modules>
    
    <properties>
        <java.version>21</java.version>
        <spring-boot.version>4.0.0</spring-boot.version>
    </properties>
    
    <dependencyManagement>
        <dependencies>
            <dependency>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-dependencies</artifactId>
                <version>${spring-boot.version}</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
            
            <dependency>
                <groupId>com.example</groupId>
                <artifactId>demo-common</artifactId>
                <version>${project.version}</version>
            </dependency>
        </dependencies>
    </dependencyManagement>
</project>

配置文件管理

1. 多环境配置

# application.yml - 主配置
spring:
  profiles:
    active: dev
  application:
    name: demo

server:
  port: 8080

---
# application-dev.yml - 开发环境
spring:
  datasource:
    url: jdbc:mysql://localhost:3306/demo_dev
    username: root
    password: dev_password
  jpa:
    show-sql: true
    hibernate:
      ddl-auto: update

logging:
  level:
    com.example.demo: DEBUG

---
# application-prod.yml - 生产环境
spring:
  datasource:
    url: jdbc:mysql://prod-db:3306/demo_prod
    username: ${DB_USERNAME}
    password: ${DB_PASSWORD}
  jpa:
    show-sql: false
    hibernate:
      ddl-auto: validate

logging:
  level:
    com.example.demo: INFO

2. 配置类组织

package com.example.demo.config;

@Configuration
public class WebConfig implements WebMvcConfigurer {
    // Web 相关配置
}

@Configuration
public class SecurityConfig {
    // 安全相关配置
}

@Configuration
public class RedisConfig {
    // Redis 相关配置
}

@Configuration
public class SwaggerConfig {
    // Swagger 相关配置
}

3. 配置属性类

package com.example.demo.config.properties;

import lombok.Data;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.stereotype.Component;

@Data
@Component
@ConfigurationProperties(prefix = "app.jwt")
public class JwtProperties {
    
    private String secret;
    private long expiration;
    private String issuer;
}

@Data
@Component
@ConfigurationProperties(prefix = "app.upload")
public class UploadProperties {
    
    private String path;
    private long maxSize;
    private List<String> allowedTypes;
}

最佳实践

1. 代码组织原则

✅ 推荐
- 单一职责原则
- 高内聚低耦合
- 依赖倒置原则
- 接口隔离原则

❌ 不推荐
- 大杂烩式组织
- 跨层调用
- 循环依赖

2. 命名一致性

// ✅ 推荐
UserController
UserService
UserServiceImpl
UserRepository
User
UserDTO
UserCreateDTO
UserUpdateDTO

// ❌ 不推荐
UserCtrl
UserSrv
UserDao
UserEntity
UserData

3. 文档组织

docs/
├── api/                    # API 文档
│   ├── user-api.md
│   └── order-api.md
├── design/                 # 设计文档
│   ├── architecture.md
│   └── database-design.md
├── deploy/                 # 部署文档
│   ├── deployment.md
│   └── k8s-config.md
└── changelog/              # 变更日志
    └── CHANGELOG.md

4. README 模板

# Demo Project

## 项目简介

Spring Boot 4 示例项目

## 技术栈

- Spring Boot 4.x
- JDK 21
- MySQL 8.0
- Redis 7.0

## 快速开始

### 环境要求

- JDK 21+
- Maven 3.9+
- MySQL 8.0+

### 运行

```bash
mvn clean install
mvn spring-boot:run

项目结构

src/
├── main/
│   ├── java/
│   └── resources/
└── test/

联系方式

Email: team@example.com


## 总结

项目结构要点：

- ✅ **目录组织** - 标准结构、清晰分层
- ✅ **包结构** - 按功能、按业务模块
- ✅ **模块划分** - 多模块、职责分离
- ✅ **配置管理** - 多环境、配置类
- ✅ **最佳实践** - 组织原则、命名一致性

良好的项目结构是成功的一半。