245 lines
7.8 KiB
Markdown
245 lines
7.8 KiB
Markdown
# label_backend 标准目录扁平化设计
|
||
|
||
**日期**: 2026-04-14
|
||
**范围**: `label_backend` 主工程 Java 包结构调整
|
||
**目标**: 将当前按业务域分层的 `com.label.module.*` 结构重组为符合《微服务开发规范文档》的扁平标准目录结构，同时保持现有业务行为不变。
|
||
|
||
---
|
||
|
||
## 1. 背景与现状
|
||
|
||
当前项目主代码位于 `src/main/java/com/label`，整体结构分为两部分：
|
||
|
||
- `com.label.common.*`：放置公共能力，如配置、异常、AOP、鉴权、Redis、状态机、存储与 AI 客户端
|
||
- `com.label.module.*`：按业务域划分的模块目录，如 `user`、`task`、`source`、`annotation`、`export`、`config`、`video`
|
||
|
||
现有结构具备一定领域边界，但与《微服务开发规范文档》中规定的标准扁平目录结构不一致。后续如果继续沿用两套组织方式，会增加新代码接入成本，也会让公共能力与业务层级的归属变得不稳定。
|
||
|
||
---
|
||
|
||
## 2. 设计目标
|
||
|
||
本次调整目标如下：
|
||
|
||
- 将主代码目录统一调整为规范文档中的扁平结构
|
||
- 保持包职责清晰，按“层级职责”而不是“业务模块”组织类
|
||
- 在不改变业务逻辑和接口行为的前提下完成迁移
|
||
- 规范包归属与少量命名，不引入新的技术分层
|
||
- 为后续新增功能提供统一、可预测的目录组织方式
|
||
|
||
---
|
||
|
||
## 3. 明确不做的事情
|
||
|
||
为控制改造范围，本次不包含以下内容：
|
||
|
||
- 不新增 `service.impl`
|
||
- 不将 `dto` 拆分为 `request`、`response`、`common`
|
||
- 不主动修改接口 URL、接口契约或返回结构
|
||
- 不进行与目录调整无关的业务重构
|
||
- 不改造数据库结构、SQL 文件或资源文件布局
|
||
|
||
---
|
||
|
||
## 4. 目标目录结构
|
||
|
||
目标结构定义如下：
|
||
|
||
```text
|
||
src/main/java/com/label/
|
||
├── annotation/
|
||
├── aspect/
|
||
├── common/
|
||
│ ├── ai/
|
||
│ ├── context/
|
||
│ ├── exception/
|
||
│ ├── redis/
|
||
│ ├── result/
|
||
│ ├── shiro/
|
||
│ ├── statemachine/
|
||
│ └── storage/
|
||
├── config/
|
||
├── constant/
|
||
├── controller/
|
||
├── dto/
|
||
├── entity/
|
||
├── event/
|
||
├── feign/
|
||
├── listener/
|
||
├── mapper/
|
||
├── scheduled/
|
||
├── service/
|
||
├── typehandler/
|
||
├── util/
|
||
└── LabelBackendApplication.java
|
||
```
|
||
|
||
说明：
|
||
|
||
- `common` 只保留真正跨业务复用的基础能力
|
||
- `config` 从原 `common.config` 提升到顶层
|
||
- `annotation` 与 `aspect` 从原 `common.aop` 中拆分
|
||
- `event` 与 `listener` 分离，避免事件定义与监听逻辑混放
|
||
- `controller`、`service`、`mapper`、`entity`、`dto` 全部收敛为顶层扁平结构
|
||
|
||
---
|
||
|
||
## 5. 包迁移规则
|
||
|
||
### 5.1 顶层迁移规则
|
||
|
||
- `com.label.module.*.controller` -> `com.label.controller`
|
||
- `com.label.module.*.service` -> `com.label.service`
|
||
- `com.label.module.*.mapper` -> `com.label.mapper`
|
||
- `com.label.module.*.entity` -> `com.label.entity`
|
||
- `com.label.module.*.dto` -> `com.label.dto`
|
||
- `com.label.module.annotation.event` -> `com.label.event`
|
||
- 事件监听类 -> `com.label.listener`
|
||
- `com.label.common.config` -> `com.label.config`
|
||
- `com.label.common.aop` 中注解类 -> `com.label.annotation`
|
||
- `com.label.common.aop` 中切面类 -> `com.label.aspect`
|
||
|
||
### 5.2 典型映射示例
|
||
|
||
- `com.label.module.user.controller.AuthController` -> `com.label.controller.AuthController`
|
||
- `com.label.module.user.service.UserService` -> `com.label.service.UserService`
|
||
- `com.label.module.task.mapper.AnnotationTaskMapper` -> `com.label.mapper.AnnotationTaskMapper`
|
||
- `com.label.module.source.entity.SourceData` -> `com.label.entity.SourceData`
|
||
- `com.label.module.user.dto.LoginRequest` -> `com.label.dto.LoginRequest`
|
||
- `com.label.common.aop.OperationLog` -> `com.label.annotation.OperationLog`
|
||
- `com.label.common.aop.AuditAspect` -> `com.label.aspect.AuditAspect`
|
||
- `com.label.module.annotation.event.ExtractionApprovedEvent` -> `com.label.event.ExtractionApprovedEvent`
|
||
- `com.label.module.annotation.service.ExtractionApprovedEventListener` -> `com.label.listener.ExtractionApprovedEventListener`
|
||
- `com.label.common.config.RedisConfig` -> `com.label.config.RedisConfig`
|
||
|
||
### 5.3 命名策略
|
||
|
||
- 以“最小必要变更”为原则，优先迁移包路径，不主动重命名类
|
||
- 仅在类职责与包语义明显不匹配时做必要归位
|
||
- 现阶段主代码类名不存在重名冲突，因此不需要为扁平化提前引入前缀或后缀
|
||
|
||
---
|
||
|
||
## 6. 实施顺序
|
||
|
||
为降低迁移风险，实际执行采用“目标一次性扁平化，操作分阶段迁移”的方式。
|
||
|
||
### 阶段 1：基础公共层归位
|
||
|
||
先迁移以下内容，建立新骨架：
|
||
|
||
- `annotation`
|
||
- `aspect`
|
||
- `config`
|
||
- `event`
|
||
- `listener`
|
||
|
||
目标是先完成最基础的结构纠偏，并尽早暴露切面、配置和事件扫描问题。
|
||
|
||
### 阶段 2：数据承载层迁移
|
||
|
||
再迁移下列包：
|
||
|
||
- `entity`
|
||
- `dto`
|
||
- `mapper`
|
||
|
||
这些类依赖通常较窄，适合优先扁平化，也能及早验证 MyBatis 相关扫描与引用是否正常。
|
||
|
||
### 阶段 3：业务服务层迁移
|
||
|
||
迁移所有业务服务类到 `service`，原则如下：
|
||
|
||
- 不新增实现层
|
||
- 不调整现有业务编排
|
||
- 只修正导包、注解引用和必要的包路径依赖
|
||
|
||
### 阶段 4：控制层迁移
|
||
|
||
最后迁移全部控制器到 `controller`。控制层依赖最广，放在后面可以减少中间态反复修改。
|
||
|
||
### 阶段 5：启动与扫描校正
|
||
|
||
统一检查并修正以下内容：
|
||
|
||
- `@MapperScan`
|
||
- 组件扫描隐式路径
|
||
- OpenAPI 相关配置
|
||
- 事件监听与切面装配
|
||
- 测试代码中的旧包引用
|
||
|
||
### 阶段 6：编译与回归验证
|
||
|
||
迁移完成后进行全量编译与测试回归，确认结构调整没有引入行为回归。
|
||
|
||
---
|
||
|
||
## 7. 风险与控制策略
|
||
|
||
### 风险 1：导包失效
|
||
|
||
大量类迁移后，主代码和测试代码中的 import 会同时失效。
|
||
|
||
控制策略：
|
||
|
||
- 按阶段迁移并同步修复引用
|
||
- 每个阶段结束后至少执行一次编译检查
|
||
|
||
### 风险 2：Spring 扫描路径异常
|
||
|
||
若配置类、切面、监听器或 Mapper 的扫描路径与旧包结构耦合，迁移后可能导致 Bean 缺失。
|
||
|
||
控制策略：
|
||
|
||
- 显式检查启动类与配置类中的扫描配置
|
||
- 将路径校正作为独立阶段处理
|
||
|
||
### 风险 3：事件监听失效
|
||
|
||
监听器从 `service` 拆到 `listener` 后，若注解或组件扫描不正确，会导致事件未被消费。
|
||
|
||
控制策略：
|
||
|
||
- 迁移时同步校验事件类与监听器依赖关系
|
||
- 通过现有集成测试覆盖事件链路
|
||
|
||
### 风险 4：测试回归失败
|
||
|
||
测试代码同样引用旧包名，若只改主代码，会造成测试集整体失效。
|
||
|
||
控制策略：
|
||
|
||
- 测试代码与主代码同步迁移
|
||
- 将 `mvn test` 作为最终验收门槛
|
||
|
||
---
|
||
|
||
## 8. 验收标准
|
||
|
||
本次结构调整完成后，应满足以下标准：
|
||
|
||
1. `src/main/java/com/label/module` 目录被完全移除
|
||
2. 主代码包结构符合标准扁平目录规范
|
||
3. 项目能够成功编译
|
||
4. 现有测试能够通过，至少覆盖当前可运行的启动测试、单元测试和集成测试
|
||
5. 调整范围内不存在残留旧包引用
|
||
|
||
---
|
||
|
||
## 9. 实现原则
|
||
|
||
执行本设计时应遵循以下原则：
|
||
|
||
- 先保证结构归位，再追求风格统一
|
||
- 先保证行为不变，再做命名优化
|
||
- 所有改动以“目录标准化”为中心，不引入额外架构决策
|
||
- 每次修改都要让工程更接近规范，而不是制造新的混合结构
|
||
|
||
---
|
||
|
||
## 10. 结论
|
||
|
||
本次改造将 `label_backend` 从“按业务域分层 + 公共包混合”的现状，统一整理为规范文档定义的扁平标准目录结构。该调整不会改变系统能力边界，但会显著提升代码组织一致性、后续开发可预测性以及新成员理解成本。
|
||
|
||
实施时采用“目标结构一次确定、操作按阶段推进”的方式，以降低大规模包迁移带来的编译与装配风险。
|