外观
四、目录结构导读（带你读源码）
拿到一个后端项目，不知道从哪看起？这一章帮你建立全局地图。
4.1 整体项目结构
一个典型的 Spring Cloud 微服务项目的顶层结构：
text
project-root/
├── pom.xml ← Maven 父工程配置（类似 package.json）
│ 定义所有子模块共享的依赖版本
│
├── component/ ← ★ 共享底层组件（优先阅读）
│ ├── cpt-api ← 服务间调用客户端 + 共享 DTO
│ ├── cpt-common ← 通用工具类、统一响应格式
│ ├── cpt-mongodb ← MongoDB 连接与操作封装
│ ├── cpt-mysql ← MySQL + ORM 封装
│ ├── cpt-redis ← Redis 缓存封装
│ ├── cpt-rocketmq ← 消息队列封装
│ └── cpt-xxljob ← 定时任务框架
│
├── svc-gateway/ ← ★ API 网关（第一个要看的服务）
├── svc-auth/ ← 认证服务
├── svc-user/ ← ★ 用户服务（最适合入门的服务）
├── svc-ai/ ← AI 服务
├── svc-canvas/ ← 画布服务（最复杂的服务）
├── svc-oss/ ← 文件存储服务
├── svc-admin/ ← 管理后台
│
├── docs/ ← 项目文档
└── scripts/ ← 脚本工具💡 阅读建议：先看
component/cpt-api（了解服务间怎么调用），再看svc-gateway（了解请求入口），然后看svc-user（最简单的业务服务）。
4.2 单个服务的内部结构
每个微服务的内部结构都是一样的模式。以用户服务为例：
text
svc-user/
├── pom.xml ← 本服务的依赖声明（类似 package.json）
├── Dockerfile ← Docker 打包文件
│
└── src/main/
├── java/com/example/user/
│ │
│ ├── UserApplication.java ← ★ 服务入口
│ │ 相当于 main.ts / index.js
│ │ 一个 main() 方法启动整个服务
│ │
│ ├── controller/ ← ★ 接口层（最先看的）
│ │ ├── UserController.java ← 用户登录/注册接口
│ │ ├── QuotaController.java ← 配额查询接口
│ │ └── OrderController.java ← 订单相关接口
│ │
│ ├── service/ ← ★ 业务逻辑层
│ │ ├── LoginRegisterService.java ← 接口定义（定义"做什么"）
│ │ └── impl/
│ │ └── LoginRegisterServiceImpl.java ← 具体实现（定义"怎么做"）
│ │
│ ├── repository/ ← ★ 数据访问层
│ │ ├── UserMstRepository.java ← 标准 CRUD
│ │ └── impl/
│ │ └── UserProfileCustomRepositoryImpl.java ← 复杂自定义查询
│ │
│ ├── entity/ ← 数据模型（对应数据库文档/表）
│ │ ├── UserMst.java ← 用户主表
│ │ └── UserProfile.java ← 用户资料
│ │
│ ├── dto/ ← 请求参数对象
│ │ └── LoginDto.java ← 登录请求参数
│ │
│ ├── vo/ ← 响应数据对象
│ │ └── LoginResponse.java ← 登录响应数据
│ │
│ ├── config/ ← 框架配置类
│ └── utils/ ← 工具方法
│
└── resources/
└── application.yml ← 配置文件（类似 .env）前端类比：三层架构
text
┌──────────────────────────────────────────────────────┐
│ 前端 后端 │
│ │
│ pages/Login.vue ──────────────▶ controller/ │
│ （页面，接收用户操作） （接口，接收HTTP请求）│
│ │
│ composables/useAuth.ts ────────▶ service/ │
│ （业务逻辑 hook） （业务逻辑实现） │
│ │
│ api/auth.ts ──────────────────▶ repository/ │
│ （调接口 / 操作存储） （操作数据库） │
│ │
│ types/auth.ts ─────────────────▶ entity/ dto/ vo/ │
│ （TypeScript 类型定义） （Java 数据模型） │
└──────────────────────────────────────────────────────┘4.3 核心目录 vs 可以暂时忽略的
核心代码（必看 ⭐）
| 目录 | 作用 | 怎么读 | 优先级 |
|---|---|---|---|
controller/ | 接口入口 | 看有哪些 URL、入参出参 | ⭐⭐⭐ |
service/impl/ | 核心业务逻辑 | 看完 controller 后跟进来 | ⭐⭐⭐ |
repository/ | 数据库操作 | 看方法名理解查询逻辑 | ⭐⭐ |
entity/ | 数据模型 | 了解数据有哪些字段 | ⭐⭐ |
dto/ / vo/ | 入参和出参结构 | 接口文档的代码版 | ⭐⭐ |
mq/ | 消息队列消费者 | 理解异步流程 | ⭐⭐ |
filter/ | 过滤器（网关特有） | 理解鉴权和拦截逻辑 | ⭐⭐ |
可以暂时跳过
| 目录 | 为什么可以跳过 |
|---|---|
config/ | 框架级配置，看不懂不影响理解业务 |
utils/ | 工具方法，用到时再看 |
aspect/ | AOP 切面编程，高级功能 |
handler/ | 全局异常处理器等 |
| Dockerfile / entrypoint.sh | 部署层面，与业务代码无关 |
4.4 组件模块导读（component/）
这些模块类似你 Monorepo 里的 packages/，被所有业务服务共同依赖：
| 模块 | 作用 | 前端类比 | 什么时候看 |
|---|---|---|---|
cpt-api | 服务间调用客户端 + 共享 DTO | @org/api-client | ⭐ 最先看，理解服务怎么互相调用 |
cpt-common | 工具类、统一响应 RtData、异常码 | @org/utils | 看到 RtData 时来查 |
cpt-mongodb | MongoDB 连接配置、基础 Repository | @org/db-client | 看 Repository 时来查 |
cpt-mysql | MySQL + MyBatis-Plus 配置 | @org/sql-client | 看统计模块时再看 |
cpt-redis | Redis 连接和工具方法 | @org/cache | 看限流/缓存时再看 |
cpt-rocketmq | 消息队列封装和注解 | @org/event-bus | 看异步任务时来查 |
cpt-xxljob | 定时任务框架 | @org/cron | 暂时不用看 |
4.5 阅读源码的推荐路径
text
第一步：看 Controller
→ 了解这个服务有哪些接口、URL 是什么
第二步：看 Controller 方法的参数
→ 了解接口需要什么入参（DTO）
第三步：跟进 Service
→ 看这个接口的核心业务逻辑
第四步：看 Service 调了哪些 Repository
→ 了解数据怎么存、怎么查
第五步：看 Entity
→ 了解数据库里的数据长什么样
这个过程就像你读前端代码：
页面组件 → 调了什么 hook → hook 里调了什么 API → API 返回什么类型