目录结构及架构分层

模块划分

目录结构

美观展示版

点击目录可展开/折叠

📂src/main/java/com/footprintcat/backend/

🍵BackendApplication.java# 启动类

📂common/# 公共组件、工具、常量、枚举

📂annotation/# 自定义注解

🍵NoRepeatSubmit.java# 防重复提交

🍵Permission.java# 权限校验

📂config/# 全局配置类

🍵JacksonConfig.java# JSON 配置

🍵WebMvcConfig.java# Web 配置

🍵MyBatisPlusConfig.java# MyBatis-Plus 配置

📂constant/# 常量定义

🍵RedisKey.java# Redis键常量

🍵BusinessError.java# 业务错误码

📂context/# 上下文

🍵UserContext.java# 用户上下文（ThreadLocal）

📂exception/# 异常定义

🍵BusinessException.java# 业务异常

🍵GlobalExceptionHandler.java# 全局异常处理器

📂result/# 统一响应

🍵Result.java# 统一响应体

🍵ResultCode.java# 响应码枚举

📂util/# 工具类

🍵StringUtils.java# 字符串工具

🍵DateUtils.java# 日期工具

📂controller/# 统一控制层

📂admin/# 管理端接口

📂request/# 请求对象，按模块分包

📂user/# 用户模块请求对象

🍵UserCreateRequest.java# 创建用户请求

🍵UserUpdateRequest.java# 更新用户请求

🍵UserQueryRequest.java# 查询用户请求

📂order/# 订单模块请求对象

🍵OrderCreateRequest.java# 创建订单请求

🍵OrderQueryRequest.java# 查询订单请求

📂note/# 笔记模块请求对象

🍵NoteCreateRequest.java# 创建笔记请求

🍵NoteQueryRequest.java# 查询笔记请求

📂vo/# 响应对象，按模块分包

📂user/# 用户模块响应对象

🍵UserVO.java# 用户视图对象

🍵UserSimpleVO.java# 用户简略视图对象

📂order/# 订单模块响应对象

🍵OrderVO.java# 订单视图对象

🍵OrderListItemVO.java# 订单列表项视图对象

📂note/# 笔记模块响应对象

🍵NoteVO.java# 笔记视图对象

🎯UserController.java# 用户管理 Controller

🎯OrderController.java# 订单管理 Controller

🎯NoteController.java# 笔记管理 Controller

📂app/# 移动端接口

🎯UserAppController.java# 移动端用户 Controller

🎯OrderAppController.java# 移动端订单 Controller

🎯NoteAppController.java# 移动端笔记 Controller

📂openapi/# 开放平台接口

📂modules/# 核心业务模块区

📂user/# 用户模块

📂converter/# 对象转换器

🍵UserConverter.java# MapStruct 接口

📂entity/# 用户实体

🍵User.java# UserEntity

📂do/# 用户数据对象

🍵UserXxxDo.java# UserDO（用于接收自定义mapper sql的查询结果）

📂dto/# 用户数据传输对象

📂request/# 用户请求 DTO

🍵CreateUserRequest.java# 创建用户请求 DTO

🍵UpdateUserRequest.java# 更新用户请求 DTO

🍵UserQueryRequest.java# 查询用户请求 DTO

📂response/# 用户响应 DTO

🍵UserResponse.java# 用户响应 DTO

🍵UserDetailResponse.java# 用户详情响应 DTO

📂mapper/# 用户数据访问层

🍵UserMapper.java# MyBatis-Plus 接口

📂repository/# 用户数据仓储层

🍵UserRepository.java# 业务层可复用逻辑

📂service/# 用户服务层

🍵UserService.java# 用户服务接口

📂impl/# 服务实现类

🍵UserServiceImpl.java# 用户服务实现

📂order/# 订单模块

📂entity/# 订单实体

📄# OrderEntity, OrderItemEntity

📂do/# 订单数据对象

📄# OrderDO

📂dto/# 订单数据传输对象

📄# OrderDTO, OrderCreateDTO等

📂mapper/# 订单数据访问层

📄# OrderMapper, OrderItemMapper

📂service/# 订单服务层

📄# OrderService

📂note/# 笔记模块

📂entity/# 笔记实体

📄# NoteEntity

📂do/# 笔记数据对象

📄# NoteDO

📂dto/# 笔记数据传输对象

📄# NoteDTO

📂mapper/# 笔记数据访问层

📄# NoteMapper

📂service/# 笔记服务层

📄# NoteService

方便复制版

src/main/java/com/footprintcat/backend/
    ├── BackendApplication.java                   # 启动类
    ├── common/                                   # 公共组件、工具、常量、枚举
    │   ├── annotation/                           # 自定义注解
    │   │   ├── NoRepeatSubmit.java               # 防重复提交
    │   │   └── Permission.java                   # 权限校验
    │   ├── config/                               # 全局配置类
    │   │   ├── JacksonConfig.java                # JSON 配置
    │   │   ├── WebMvcConfig.java                 # Web 配置
    │   │   └── MyBatisPlusConfig.java            # MyBatis-Plus 配置
    │   ├── constant/                             # 常量定义
    │   │   ├── RedisKey.java                     # Redis键常量
    │   │   └── BusinessError.java                # 业务错误码
    │   ├── context/                              # 上下文
    │   │   └── UserContext.java                  # 用户上下文（ThreadLocal）
    │   ├── exception/                            # 异常定义
    │   │   ├── BusinessException.java            # 业务异常
    │   │   └── GlobalExceptionHandler.java       # 全局异常处理器
    │   ├── result/                               # 统一响应
    │   │   ├── Result.java                       # 统一响应体
    │   │   └── ResultCode.java                   # 响应码枚举
    │   └── util/                                 # 工具类
    │       ├── StringUtils.java                  # 字符串工具
    │       └── DateUtils.java                    # 日期工具
    ├── controller/                               # 统一控制层
    │   ├── admin/                                # 管理端接口
    │   │   ├── request/                          # 请求对象，按模块分包
    │   │   │   ├── user/                         # 用户模块请求对象
    │   │   │   │   ├── UserCreateRequest.java    # 创建用户请求
    │   │   │   │   ├── UserUpdateRequest.java    # 更新用户请求
    │   │   │   │   └── UserQueryRequest.java     # 查询用户请求
    │   │   │   ├── order/                        # 订单模块请求对象
    │   │   │   │   ├── OrderCreateRequest.java   # 创建订单请求
    │   │   │   │   └── OrderQueryRequest.java    # 查询订单请求
    │   │   │   └── note/                         # 笔记模块请求对象
    │   │   │       ├── NoteCreateRequest.java    # 创建笔记请求
    │   │   │       └── NoteQueryRequest.java     # 查询笔记请求
    │   │   ├── vo/                               # 响应对象，按模块分包
    │   │   │   ├── user/                         # 用户模块响应对象
    │   │   │   │   ├── UserVO.java               # 用户视图对象
    │   │   │   │   └── UserSimpleVO.java         # 用户简略视图对象
    │   │   │   ├── order/                        # 订单模块响应对象
    │   │   │   │   ├── OrderVO.java              # 订单视图对象
    │   │   │   │   └── OrderListItemVO.java      # 订单列表项视图对象
    │   │   │   └── note/                         # 笔记模块响应对象
    │   │   │       └── NoteVO.java               # 笔记视图对象
    │   │   ├── UserController.java               # 用户管理 Controller
    │   │   ├── OrderController.java              # 订单管理 Controller
    │   │   └── NoteController.java               # 笔记管理 Controller
    │   ├── app/                                  # 移动端接口
    │   │   ├── UserAppController.java            # 移动端用户 Controller
    │   │   ├── OrderAppController.java           # 移动端订单 Controller
    │   │   └── NoteAppController.java            # 移动端笔记 Controller
    │   └── openapi/                              # 开放平台接口
    └── modules/                                  # 核心业务模块区
        ├── user/                                 # 用户模块
        │   ├── converter/                        # 对象转换器
        │   │   └── UserConverter.java            # MapStruct 接口
        │   ├── entity/                           # 用户实体
        │   │   └── User.java                     # UserEntity
        │   ├── do/                               # 用户数据对象
        │   │   └── UserXxxDo.java                # UserDO（用于接收自定义mapper sql的查询结果）
        │   ├── dto/                              # 用户数据传输对象
        │   │   ├── request/                      # 用户请求 DTO
        │   │   │   ├── CreateUserRequest.java    # 创建用户请求 DTO
        │   │   │   ├── UpdateUserRequest.java    # 更新用户请求 DTO
        │   │   │   └── UserQueryRequest.java     # 查询用户请求 DTO
        │   │   └── response/                     # 用户响应 DTO
        │   │       ├── UserResponse.java         # 用户响应 DTO
        │   │       └── UserDetailResponse.java   # 用户详情响应 DTO
        │   ├── mapper/                           # 用户数据访问层
        │   │   └── UserMapper.java               # MyBatis-Plus 接口
        │   ├── repository/                       # 用户数据仓储层
        │   │   └── UserRepository.java           # 业务层可复用逻辑
        │   └── service/                          # 用户服务层
        │       ├── UserService.java              # 用户服务接口
        │       └── impl/                         # 服务实现类
        │           └── UserServiceImpl.java      # 用户服务实现
        ├── order/                                # 订单模块
        │   ├── entity/                           # 订单实体
        │   │   └──                               # OrderEntity, OrderItemEntity
        │   ├── do/                               # 订单数据对象
        │   │   └──                               # OrderDO
        │   ├── dto/                              # 订单数据传输对象
        │   │   └──                               # OrderDTO, OrderCreateDTO等
        │   ├── mapper/                           # 订单数据访问层
        │   │   └──                               # OrderMapper, OrderItemMapper
        │   └── service/                          # 订单服务层
        │       └──                               # OrderService
        └── note/                                 # 笔记模块
            ├── entity/                           # 笔记实体
            │   └──                               # NoteEntity
            ├── do/                               # 笔记数据对象
            │   └──                               # NoteDO
            ├── dto/                              # 笔记数据传输对象
            │   └──                               # NoteDTO
            ├── mapper/                           # 笔记数据访问层
            │   └──                               # NoteMapper
            └── service/                          # 笔记服务层
                └──                               # NoteService

架构分层

项目采用经典四层架构：Controller → Service → Repository → Mapper

┌─────────────────────────────────────────────────────────────┐
│  Controller 层（控制层）                                     │
│  • 按客户端类型分包（admin / app / web）                      │
│  • 负责接收请求、参数校验、调用 Service                        │
│  • 负责响应组装、异常处理                                     │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│  Service 层（业务服务层）                                     │
│  • 核心业务逻辑                                             │
│  • 事务管理                                                │
│  • 按业务模块分包（user / order / note）                     │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│  Repository 层（数据仓储层）                                  │
│  • 数据库查询预处理                                         │
│  • 业务层面可复用的简单操作                                   │
│  • 避免 Service 层循环依赖                                   │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│  Mapper 层（数据持久层）                                     │
│  • MyBatis-Plus 提供                                        │
│  • 简单查询直接使用，不手写 SQL                               │
│  • 复杂查询手写 SQL，通过 XML 映射到 DO                       │
└─────────────────────────────────────────────────────────────┘

分层设计要点

层级	位置	说明
Controller	controller/ 单独包	按调用端分包（admin/app/web），未来可复用
Service	modules/xxx/service/	按业务模块划分，专注核心逻辑
Repository	modules/xxx/repository/	按业务模块划分，封装数据库预处理
Mapper	modules/xxx/mapper/	按业务模块划分，MyBatis-Plus 接口

技术选型

• JSON 序列化：Jackson（Spring Boot 默认）
• 持久化框架：MyBatis-Plus
• 数据库：PostgreSQL
• 部署策略：单应用多实例，按用户 ID 哈希分片（不使用微服务）

为什么不使用微服务？ 微服务有较多网络开销，对于业务关联紧密的应用，单体架构反而更简单高效。未来可通过水平扩展多个实例，配合负载均衡和分片策略支撑高并发。