easy-vibe 后端分层架构原理四层架构、DTO 翻译与依赖方向控制【免费下载链接】easy-vibe vibe coding 101The first course for AI-native product builders.项目地址: https://gitcode.com/GitHub_Trending/ea/easy-vibe本篇基于 easy-vibe 课程docs/ar-sa/appendix/4-server-and-backend/backend-layered-architecture.md整理讲清代码越写越乱时如何组织这一后端工程的核心命题。读完后你将掌握 Controller / Service / Repository / Domain 四层的职责边界与铁律、DTO 在层间的翻译机制、依赖方向的正确控制方式并能在电商订单这类真实场景里落地一套可测试、可复用的分层实现。当项目从几十行代码扩展到数万行、从单人开发到多人协作、从简单 CRUD 到复杂业务逻辑时代码组织方式直接决定了项目的生死。分层架构不是为了炫技或遵循教条而是为了解决软件工程中的一个根本性矛盾业务复杂度的自然增长与人类认知能力的有限性之间的冲突。1. 为什么需要分层1.1 问题的根源初期版本100 行代码PostMapping(/register) public Result register(RequestBody User user) { // 1. 检查用户名是否重复 if (userRepository.findByUsername(user.getUsername()) ! null) { return Result.error(用户名已存在); } // 2. 加密密码 user.setPassword(encrypt(user.getPassword())); // 3. 保存用户 userRepository.save(user); // 4. 发送欢迎邮件 emailService.sendWelcome(user.getEmail()); // 5. 记录日志 log.info(User registered: {}, user.getUsername()); return Result.success(); }6 个月后500 行代码新增了手机号验证新增了实名认证新增了邀请奖励新增了风控检查……现在这个方法有 500 行每次修改都提心吊胆因为逻辑混在一起改一处可能影响其他功能难以测试每次测试都要模拟完整的 HTTP 请求新人看不懂因为所有逻辑都堆在一起。问题的本质代码没有边界所有职责都混在一起。技术债的累积效应❌高耦合业务逻辑与数据访问、HTTP 协议耦合修改牵一发而动全身❌低内聚一个方法承担了多个职责违反单一职责原则❌难测试无法独立测试业务逻辑必须启动完整 HTTP 容器❌难复用业务逻辑绑定在 HTTP 请求中定时任务、消息队列无法复用❌认知负荷开发者需要同时理解所有层次的细节无法聚焦。1.2 分层的核心思想分层架构就是给代码划清边界┌─────────────────────────────────────┐ │ 接收请求 ← Controller │ 只负责接单 ├─────────────────────────────────────┤ │ 业务编排 ← Service │ 只负责做菜 ├─────────────────────────────────────┤ │ 数据存取 ← Repository │ 只负责取食材 ├─────────────────────────────────────┤ │ 业务定义 ← Domain │ 只负责菜谱标准 └─────────────────────────────────────┘关键原则每一层只做自己的事层与层之间通过明确的接口通信业务逻辑集中在 Service 和 Domain数据访问逻辑集中在 Repository。分层架构的工程价值降低认知负荷开发者可以专注于当前层的职责无需理解全局细节提高可测试性每层可以独立单元测试Mock 依赖即可增强可维护性需求变更时定位修改范围明确降低风险促进代码复用业务逻辑不依赖 HTTP可在定时任务、消息队列中复用支持团队协作不同开发者可以并行开发不同层减少冲突延长代码寿命清晰的边界让代码更容易重构和演进。2. 四层架构详解2.1 整体结构分层架构的本质是关注点分离Separation of Concerns和依赖方向控制┌─────────────────────────────────────────────────────┐ │ 前端请求 │ └────────────────────┬────────────────────────────────┘ │ HTTP Request ▼ ┌─────────────────────────────────────────────────────┐ │ Controller (控制器层) │ │ - 接收请求、参数校验 │ │ - DTO 转换 │ │ - 调用 Service │ │ - 返回响应 │ └────────────────────┬────────────────────────────────┘ │ 业务调用 ▼ ┌─────────────────────────────────────────────────────┐ │ Service (业务逻辑层) │ │ - 业务逻辑编排 │ │ - 事务管理 │ │ - 协调多个 Repository │ │ - 跨模块协调 │ └────────────────────┬────────────────────────────────┘ │ 数据访问 ▼ ┌─────────────────────────────────────────────────────┐ │ Repository (数据访问层) │ │ - 数据库 CRUD │ │ - 查询封装 │ │ - ORM 映射 │ └────────────────────┬────────────────────────────────┘ │ 领域对象 ▼ ┌─────────────────────────────────────────────────────┐ │ Domain (领域模型层) │ │ - 实体 (Entity) │ │ - 值对象 (Value Object) │ │ - 业务规则 │ └─────────────────────────────────────────────────────┘依赖方向代码的依赖必须指向更稳定、更抽象的方向。Controller 依赖 Service 接口抽象Service 依赖 Repository 接口抽象所有层都依赖 Domain业务内核最稳定禁止反向依赖例如 Repository 不能依赖 Service。仓库佐证这套四层调用链在 easy-vibe 中被实现为可交互的 Vue 组件 LayeredArchitectureDemo.vue。从源码结构看该组件用v-for渲染layers数据、点击任一层后通过activeInfo计算属性拉出该层的职责描述、类比接单 / 做菜 / 取食材 / 菜谱标准与常见错误清单把文档里的分层职责变成了可视化交互其文案来自 backend-layered-architecture 语言包。2.2 Controller 层职责请求的前台接待。接收 HTTP 请求解析参数参数校验格式、必填字段等转换 DTORequest → Param调用 Service 执行业务转换 DTOResult → Response返回 HTTP 响应。不应做的事直接写业务逻辑直接操作数据库管理事务。设计哲学Controller 是系统的门面扮演转换器——把外部 HTTP 协议适配成内部业务调用。它不应包含任何业务决策因为业务决策是领域知识的体现必须与传输协议解耦。示例RestController RequestMapping(/api/users) public class UserController { private final UserService userService; PostMapping public UserResponse createUser( RequestBody Valid UserRequest request) { // 1. Request DTO → Param DTO UserParam param UserParam.builder() .username(request.getUsername()) .password(encrypt(request.getPassword())) .email(request.getEmail()) .build(); // 2. 调用 Service User user userService.createUser(param); // 3. Entity → Response DTO return UserResponse.from(user); } }关键点使用Valid做自动参数校验用 DTO 隔离前后端数据结构只做翻译和调度不含业务逻辑。仓库佐证ControllerLayerDemo.vue 通过duties与validationDetails计算属性把 Controller 的职责清单与校验细节做成可展开面板对应文档 2.2 节列出的职责 / 禁止项。2.3 Service 层职责业务的厨师。执行核心业务逻辑协调多个 Repository 的操作管理事务边界处理跨模块的编排。不应做的事直接写 SQL留给 Repository处理 HTTP 相关事务把数据库实体返回给 Controller。设计哲学Service 层是业务逻辑的载体必须保持纯净。它不依赖任何框架或传输协议因此可以通过单元测试独立于 Web 层测试在定时任务、消息队列消费者中复用避免技术栈变更影响业务逻辑。示例Service RequiredArgsConstructor public class UserService { private final UserRepository userRepository; private final EmailService emailService; Transactional public User createUser(UserParam param) { // 1. 业务规则校验用户名不重复 if (userRepository.existsByUsername(param.getUsername())) { throw new UserAlreadyExistsException(); } // 2. 创建用户实体 User user new User(); user.setUsername(param.getUsername()); user.setPassword(param.getPassword()); user.setEmail(param.getEmail()); // 3. 保存到数据库 userRepository.save(user); // 4. 发送欢迎邮件跨模块编排 emailService.sendWelcomeEmail(user); return user; } }关键点使用Transactional保证事务一致性抛出业务异常交由 Controller 统一处理不依赖任何 HTTP 概念可复用。仓库佐证ServiceLayerDemo.vue 用scenarios/allData/steps把 Service 层校验 → 构建实体 → 持久化 → 跨模块编排的步骤做成可逐步展开的交互toggleStep(i)控制每一步的展开直观呈现事务编排的先后顺序。2.4 Repository 层职责数据的仓库管理员。封装所有数据访问逻辑执行 CRUD 操作处理 ORM 映射封装查询条件。不应做的事写业务逻辑处理事务由 Service 层管理依赖上层模块。设计哲学Repository 是数据访问的抽象层隐藏底层数据库细节。它的价值在于换数据库时只需改 Repository 实现业务逻辑不动单元测试中易于 Mock查询逻辑集中管理避免代码重复。示例Repository public interface UserRepository extends JpaRepositoryUser, Long { // Spring Data JPA 自动实现 OptionalUser findByUsername(String username); boolean existsByUsername(String username); // 自定义复杂查询 Query(SELECT u FROM User u WHERE u.email :email AND u.deleted false) OptionalUser findActiveByEmail(Param(email) String email); }关键点Repository 是接口不含业务逻辑用方法名表达查询意图复杂自定义查询可用Query。仓库佐证RepositoryLayerDemo.vue 用badCode/goodCode做反例 / 正例对照视图配合problems与benefits列表直观呈现把 SQL 散落在 Service vs. 封装进 Repository的差异。2.5 Domain 层职责业务的菜谱标准。定义业务实体Entity定义值对象Value Object封装业务规则作为所有层共同依赖的对象。重要特性Domain 层不依赖任何其他层所有层都依赖 Domain 层它是分层架构的根基。设计哲学Domain 层是整个系统的业务内核承载领域知识与业务规则。它的纯净性至关重要不依赖框架意味着业务逻辑不被技术栈绑定所有层都依赖它保证业务规则统一便于长期演进——技术栈可以替换而业务规则相对保持稳定。示例Entity public class User { Id GeneratedValue(strategy GenerationType.IDENTITY) private Long id; Column(unique true, nullable false) private String username; Column(nullable false) private String password; // ✅ 业务方法封装业务规则 public boolean isPasswordCorrect(String rawPassword) { return BCrypt.checkpw(rawPassword, this.password); } public void changePassword(String oldPassword, String newPassword) { if (!isPasswordCorrect(oldPassword)) { throw new IncorrectPasswordException(); } this.password BCrypt.hashpw(newPassword); } }关键点Entity 有唯一标识业务规则封装在 Domain 对象中Domain 层是纯业务逻辑不依赖框架。仓库佐证DomainModelDemo.vue 用贫血模型 / 充血模型两个 TabanemicEntity/richEntity、anemicService/richService对照展示实体与 Service 的职责分配并提供addressVO/moneyVO值对象示例直接对应 2.5 节实体 值对象 业务规则的 Domain 职责。3. DTO层间的翻译官3.1 为什么需要 DTO问题如果直接把数据库实体返回给前端// ❌ 错误直接返回 Entity Entity public class User { private Long id; private String username; private String password; // 敏感信息 private Boolean isDeleted; // 内部字段 }前端会收到本不该暴露的字段构成安全风险。解决用 DTO 做翻译数据库 Entity → Service Param/Result → Controller Request/Response → 前端3.2 DTO 的种类种类用途示例Request DTOController 接收参数UserCreateRequestResponse DTOController 返回数据UserResponseParam DTOService 方法入参UserParamResult DTOService 返回结果UserResultEntity数据库映射User基本原则每一层用自己的 DTO不直接传递 Entity且 DTO 只含必要字段。这样可以避免暴露内部实现细节并保证每层的独立性。仓库佐证DtoFlowDemo.vue 用headers/rows渲染DTO 流转表格把Entity → Service → Controller → 前端的转换链路可视化正是 3.1 节翻译流程的交互化表达。4. 依赖方向分层架构的铁律4.1 依赖倒置原则错误做法Controller → UserServiceImpl → UserDaoImpl → UserEntity正确做法Controller → UserService(接口) → UserRepository(接口) → UserEntity依赖方向正确方向是所有层都依赖更抽象、更稳定的层。具体而言Controller 依赖 Service 接口Service 依赖 Repository 接口所有层依赖 Domain 层而 Domain 层不依赖任何层。这个依赖方向保证了业务逻辑的独立性与可测试性。常见反模式包括Service 直接依赖 Repository 的实现类、Controller 直接操作数据库、Domain 层依赖其他层——它们都会导致耦合上升、可维护性下降。4.2 代码示例// ✅ 正确依赖接口 Service public class OrderService { private final OrderRepository orderRepository; // 接口 private final PaymentService paymentService; // 接口 } // ✅ 实现类由 Spring 自动注入 Repository public class OrderRepositoryImpl implements OrderRepository { // 实现细节 }仓库佐证DependencyDirectionDemo.vue 用rules计算属性渲染依赖方向规则清单把依赖接口而非实现、依赖指向更稳定层这一铁律做成可查条目辅助读者自查依赖方向是否合规。5. 实战案例电商订单系统5.1 需求创建订单用户选择商品校验库存计算金额创建订单扣减库存。5.2 代码实现Domain 层Entity public class Order { Id private Long id; private Long userId; private ListOrderItem items; private Money totalAmount; private OrderStatus status; public void calculateTotal() { Money total Money.zero(); for (OrderItem item : items) { total total.add(item.getSubTotal()); } this.totalAmount total; } public void cancel() { if (this.status ! OrderStatus.PENDING_PAYMENT) { throw new IllegalStateException(只能取消待支付的订单); } this.status OrderStatus.CANCELLED; } }Repository 层Repository public interface OrderRepository extends JpaRepositoryOrder, Long { ListOrder findByUserIdOrderByCreatedAtDesc(Long userId); }Service 层Service RequiredArgsConstructor public class OrderService { private final OrderRepository orderRepository; private final InventoryService inventoryService; Transactional public OrderDTO createOrder(OrderParam param) { // 1. 校验商品并扣减库存 for (OrderItemParam item : param.getItems()) { inventoryService.reserveStock(item.getProductId(), item.getQuantity()); } // 2. 创建订单 Order order new Order(); order.setUserId(param.getUserId()); order.calculateTotal(); // 3. 保存订单 orderRepository.save(order); return OrderDTO.from(order); } }Controller 层RestController RequestMapping(/api/orders) public class OrderController { private final OrderService orderService; PostMapping public OrderResponse createOrder(RequestBody Valid OrderRequest request) { OrderParam param OrderParam.builder() .userId(request.getUserId()) .items(request.getItems()) .build(); OrderDTO order orderService.createOrder(param); return OrderResponse.from(order); } }这个案例完整串联了前文的所有铁律Domain 层的calculateTotal()/cancel()承载业务规则Repository 只声明数据访问Service 用Transactional管理扣库存 → 建单 → 持久化的事务边界Controller 只做 Request→Param→DTO 的翻译与调度。6. 常见问题6.1 Controller 可以写业务逻辑吗不应该。Controller 只负责接收请求、返回响应业务逻辑应封装在 Service 层。这样做的好处是可复用——例如定时任务、消息队列消费者可直接调用 Service无需经过 HTTP 请求同时业务逻辑集中在一个地方便于测试和维护也避免了逻辑分散导致的不一致。6.2 贫血模型与充血模型概览贫血模型Anemic Model实体类只含属性和对应的 getter/setter没有任何业务逻辑所有业务规则放在 Service 层。这种模型结构简单、易理解是大多数项目采用的方式。充血模型Rich Model实体类除了属性还包含与实体相关的业务方法把业务规则封装在实体内部。这种方式更符合面向对象设计思想把数据与行为聚在一起提升代码内聚性。建议根据团队技术背景与项目复杂度选择合适的模型。无论选哪种都应保持一致且 Domain 层至少应包含基本的业务行为方法而非纯粹的空壳。6.3 跨多个 Service 的事务处理当一次业务需要跨多个 Service 时应在上层 Service 使用Transactional并在该方法内顺序调用下层多个 Service。这样能保证所有操作在同一事务上下文执行要么全部成功、要么全部回滚从而保证数据一致性。注意事务边界应尽可能小只包含必要操作避免长时间持有数据库锁而影响并发性能。7. 更多架构模式本篇介绍的是分层架构Layered Architecture它是后端工程中最常见、也最容易入门的模式。但后端架构不止于此根据业务场景的不同还有若干值得了解的模式。7.1 常见架构模式架构模式适用场景特点单体架构小型项目、MVP所有功能在一个应用中部署简单微服务架构大型复杂系统拆分为多个独立服务每个服务可独立部署事件驱动架构高并发、异步处理用事件流处理高解耦整洁架构复杂业务系统业务逻辑在内核依赖只朝内指向框架在外层六边形架构需要多个外部适配器用端口与适配器把内核与外部系统隔离洋葱架构面向领域的设计同心圆分层领域模型在内、基础设施在外单体架构Monolithic所有功能聚在一个应用中共享同一数据库与进程。┌──────────────────────────────┐ │ 单体应用 │ │ ┌────┐ ┌────┐ ┌────┐ │ │ │用户 │ │订单 │ │支付 │ ... │ │ └──┬─┘ └──┬─┘ └──┬─┘ │ │ └──────┼──────┘ │ │ 共享数据库 │ └──────────────────────────────┘优点开发简单、部署容易、本地调试方便缺点代码耦合高、难以水平扩展、单点故障可能拖垮整个系统适用创业早期项目、单团队开发、快速验证原型。微服务架构Microservices把系统拆成多个独立服务每个服务有自己的数据与业务逻辑可独立部署与扩展。┌────────┐ ┌────────┐ ┌────────┐ │ 用户 │ │ 订单 │ │ 支付 │ │ 服务 │ │ 服务 │ │ 服务 │ │ DB-1 │ │ DB-2 │ │ DB-3 │ └───┬────┘ └───┬────┘ └───┬────┘ └───────────┼───────────┘ API Gateway优点独立部署与扩展、技术栈灵活、故障隔离缺点服务间通信复杂、分布式数据一致性难、需要成熟的 DevOps 能力适用大型复杂系统、多团队协作、需要独立扩展的场景。事件驱动架构Event-Driven通过异步事件通信生产者发事件、消费者响应组件高度隔离。生产者 ──→ [事件总线/消息队列] ──→ 消费者 A ──→ 消费者 B ──→ 消费者 C优点高解耦、天然支持水平扩展、适合实时处理缺点调试困难、事件顺序与最终一致性需要额外处理适用实时数据分析、IoT 系统、微服务间的异步通信。整洁架构Clean Architecture由 Robert C. Martin 提出把系统分成四个同心圆依赖只由外朝内指向┌─────────────────────────────────────┐ │ 框架与驱动 (Frameworks Drivers) │ │ ┌─────────────────────────────┐ │ │ │ 接口适配器 (Adapters) │ │ │ │ ┌─────────────────────┐ │ │ │ │ │ 用例 (Use Cases) │ │ │ │ │ │ ┌─────────────┐ │ │ │ │ │ │ │ 实体/领域 │ │ │ │ │ │ │ │ (Entities) │ │ │ │ │ │ │ └─────────────┘ │ │ │ │ │ └─────────────────────┘ │ │ │ └─────────────────────────────┘ │ └─────────────────────────────────────┘ 依赖方向外 → 内核心规则内层不知道外层的存在业务逻辑与框架、数据库完全解耦优点高可测试性、技术栈可替换、业务逻辑清晰缺点前期开发成本高、层间映射代码多、小项目可能过度设计适用复杂业务系统、需要长期维护的项目。仓库佐证CleanArchitectureDemo.vue 用传统分层 / 整洁架构两个 TablayeredLayers/cleanLayers加compareRows对比表把传统 N 层与整洁架构在职责、依赖方向上的差异做成可视化对照辅助读者理解第 7.2 节的演进关系。六边形架构Hexagonal / Ports Adapters用端口定义核心业务的输入/输出接口用适配器连接外部系统┌─────────────┐ HTTP ──→ Port │ CLI ──→ (输入端口) │ 核心业务逻辑 │ (输出端口) ──→ 数据库 MQ ──→ │ │ Port ──→ 外部 API └─────────────┘核心思想业务逻辑不依赖任何外部技术外部系统通过适配器接入优点外部系统可自由替换、可用 Mock 适配器做测试适用需要对接多个外部系统的场景。洋葱架构Onion Architecture与整洁架构类似强调领域模型在最内层、基础设施在最外层、依赖只朝内指向┌──────────────────────────────┐ │ 基础设施 (Infrastructure) │ │ ┌────────────────────────┐ │ │ │ 应用服务 (App Service) │ │ │ │ ┌──────────────────┐ │ │ │ │ │ 领域服务 (Domain)│ │ │ │ │ │ ┌────────────┐ │ │ │ │ │ │ │ 领域模型 │ │ │ │ │ │ │ └────────────┘ │ │ │ │ │ └──────────────────┘ │ │ │ └────────────────────────┘ │ └──────────────────────────────┘核心思想领域模型是系统内核所有依赖指向它与整洁架构的区别洋葱架构更强调领域服务层整洁架构更强调用例层适用采用领域驱动设计DDD的项目。7.2 架构演进路径这些架构并非互相替代而是渐进演进传统分层架构 (N-Layered) │ 问题层间耦合外部依赖难以替换 ▼ 六边形架构 (Ports Adapters) │ 改进用端口与适配器隔离外部系统 ▼ 洋葱架构 (Onion) │ 改进清晰的同心圆分层领域模型在内核 ▼ 整洁架构 (Clean Architecture) │ 改进统一依赖规则明确四层职责 ▼ 根据业务需求选择合适的架构7.3 架构模式选择指南用户 1k代码 5000 行 ↓ 单体架构 简单分层 ↓ 用户 1k–100k需要多团队协作 ↓ 分层架构本篇介绍 ↓ 用户 100k业务复杂度高 ↓ 微服务架构 / 事件驱动架构更细致的选择维度考量因素简单分层整洁/六边形微服务团队规模1–5 人5–20 人20 人业务复杂度低中–高高发布频率低中高独立发布技术栈多样性单一单一可多样化运维成本低中高7.4 怎么选记住这个原则架构是为业务服务的而不是为了架构而架构。小项目用简单架构快速上线验证大项目再考虑复杂架构避免过度设计团队熟悉度也很重要选大家都能理解的方案。延伸阅读本篇只讲分层架构的纵深。若想了解从脚本到单体的横向演进可读姊妹篇 backend-project-architecture.md若想理解从单体到微服务的拆分可看 monolith-to-microservices.md。8. 总结层职责关键词Controller接收请求、参数校验、调用 Service、返回响应前台接待Service业务逻辑编排、事务管理、协调 Repository厨师Repository数据访问、ORM 映射、查询封装仓库管理员Domain定义实体、业务规则、值对象菜谱标准基本原则每一层只做自己的事层与层之间通过接口通信业务逻辑集中在 Service 和 Domain数据访问逻辑集中在 Repository用 DTO 隔离层间数据结构。分层架构的精髓在于清晰的责任划分与依赖方向的控制。每层只专注自己的职责通过接口与相邻层通信业务逻辑集中在 Service 与 Domain数据访问集中在 Repository层间用 DTO 隔离数据结构避免直接暴露内部实现细节。这样的设计让系统更易理解、易测试、易维护也能从容应对业务的持续演进。仓库落点本篇的四层职责、DTO 流转、依赖方向与整洁架构对比在 easy-vibe 中分别由 backend-layered-architecture 组件目录 下的LayeredArchitectureDemo、ControllerLayerDemo、ServiceLayerDemo、RepositoryLayerDemo、DomainModelDemo、DtoFlowDemo、DependencyDirectionDemo、CleanArchitectureDemo八个 Vue 组件实现文案统一走 backend-layered-architecture 语言包让这套后端分层原理在课程站点上以可交互形式呈现。【免费下载链接】easy-vibe vibe coding 101The first course for AI-native product builders.项目地址: https://gitcode.com/GitHub_Trending/ea/easy-vibe创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考