easy-vibe 后端分层架构原理从混乱代码到清晰边界的工程实践指南【免费下载链接】easy-vibe vibe coding 101The first course for AI-native product builders.项目地址: https://gitcode.com/GitHub_Trending/ea/easy-vibe核心问题代码越写越乱怎么组织才能清晰易懂当项目从几十行代码扩展到数万行、从单人开发走向团队协作、从简单 CRUD 演进到复杂业务逻辑时代码的组织方式直接决定了项目的生死。分层架构Layered Architecture不是炫技或教条而是为了解决软件工程中的根本性矛盾——业务复杂度的自然增长与人类认知能力的有限性之间的冲突。本文以 easy-vibe 课程体系中《后端分层架构原理》一文为主线对应仓库 docs/es-es/appendix/4-server-and-backend/backend-layered-architecture.md英文版见 docs/en/appendix/4-server-and-backend/backend-layered-architecture.md中文版见 docs/zh-cn/appendix/4-server-and-backend/backend-layered-architecture.md完整讲解 Controller / Service / Repository / Domain 四层模型、DTO 隔离机制与依赖方向控制并延伸到单体、微服务、事件驱动、整洁、六边形、洋葱等常见架构模式的选型路径帮助你建立可测试、可维护、可演进的工程化后端认知。1. 为什么需要分层问题的根源1.1 从 100 行到 500 行的失控曲线初期版本约 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 协议绑定一处改动牵一发动全身❌低内聚一个方法承担多种职责违反单一职责原则SRP❌难测试无法隔离测试业务逻辑必须启动完整的 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。2.2 Controller 层请求的接待员职责接收 HTTP 请求解析参数校验参数格式、必填等DTO 转换Request → Param调用 Service 执行业务逻辑DTO 转换Result → Response返回 HTTP 响应。不该做的事直接编写业务逻辑直接操作数据库管理事务。设计哲学Controller 是系统的门面Facade扮演适配器角色——把外部 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 隔离前后端数据结构只做翻译和分发不含业务逻辑。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 概念可以复用。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自定义。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 层是纯业务逻辑不依赖框架。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 只包含必要字段避免暴露内部实现细节保证各层独立性。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 { // 实现细节 }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); } }注意这个案例中依赖方向的完整闭环Controller 只负责接收OrderRequest并转换为OrderParamService 通过OrderRepository接口与InventoryService编排流程领域对象Order自己封装了金额计算与取消规则。库存扣减逻辑以服务形式被编排这体现了层与层之间面向接口协作而非面向实现调用的核心思想。6. 常见问题解答6.1 Controller 可以包含业务逻辑吗Controller 不应包含业务逻辑只负责接收请求和返回响应。业务逻辑应封装在 Service 层这样代码才可复用例如定时任务、消息队列消费者可以不经过 HTTP 直接调用 Service。此外业务逻辑集中在一处便于测试和维护避免逻辑分散导致的不一致。6.2 贫血模型与充血模型贫血模型Anemic Domain Model实体类只包含属性及对应的 getter/setter没有任何业务逻辑所有业务规则在 Service 层实现。结构简单、易于理解是大多数项目采用的方式。充血模型Rich Domain Model实体类不仅包含属性还包含与该实体相关的业务方法把业务规则封装在实体内部。更符合面向对象设计数据与行为在一起内聚性更高。建议根据团队技术水平和项目复杂度选择合适的模型但无论选择哪种都应保持一致性。Domain 层至少应包含基本的业务行为方法而不是一个完全空壳。6.3 跨多个 Service 的事务如何处理当一个业务操作需要跨越多个 Service 时应在最上层的 Service 方法上加事务注解在该方法内部依次调用下层 Service。这保证所有操作在同一事务上下文中执行要么全部成功要么全部失败确保数据一致性。同时要注意事务边界尽量小只包含必要操作避免长时间持有数据库锁而影响并发性能。7. 分层架构小结层职责关键词Controller接收请求、校验参数、调用 Service、返回响应接待员Service业务逻辑编排、事务管理、协调 Repository厨师Repository数据访问、ORM 映射、查询封装仓管员Domain实体定义、业务规则、值对象菜谱标准基本原则每层只做自己该做的事层间通过接口通信业务逻辑集中在 Service 与 Domain数据访问逻辑集中在 Repository用 DTO 隔离层间数据结构。分层架构的核心在于清晰的职责划分与依赖方向控制。每层只关注自身职责通过接口与相邻层通信业务逻辑集中在 Service 与 Domain数据访问集中在 Repository层间数据结构通过 DTO 隔离避免直接暴露内部实现细节。这种设计让系统更容易理解、测试与维护能够应对业务的持续演进。8. 更多架构模式从分层走向演进上文介绍的分层架构Layered Architecture是最常见、最容易落地的后端架构模式。但后端架构不止于此根据业务场景还存在其他值得了解的模式。8.1 常见架构模式一览架构模式适用场景特点单体架构小项目、MVP所有功能在一个应用中部署简单微服务架构大型复杂系统拆分为多个独立服务各自独立部署事件驱动架构高并发、异步处理处理流程由事件触发高度解耦整洁架构复杂业务系统业务逻辑在中心依赖只向内框架在最外层六边形架构需要多个外部适配器通过端口与适配器隔离核心与外部系统洋葱架构领域驱动设计同心圆分层领域模型在中心基础设施在外围8.2 各模式详解单体架构Monolithic所有功能打包在一个应用中共享同一数据库与进程。┌──────────────────────────────┐ │ 单体应用 │ │ ┌────┐ ┌────┐ ┌────┐ │ │ │用户 │ │订单 │ │支付 │ ... │ │ └──┬─┘ └──┬─┘ └──┬─┘ │ │ └──────┼──────┘ │ │ 共享数据库 │ └──────────────────────────────┘优点开发简单、部署方便、本地调试容易缺点代码耦合度高、难以扩展、一个模块故障可能拖垮整个系统适用早期创业项目、单团队开发、快速验证原型。微服务架构Microservices把系统拆分为多个独立服务每个服务有自己的数据与业务逻辑可独立部署与扩展。┌────────┐ ┌────────┐ ┌────────┐ │用户服务 │ │订单服务 │ │支付服务 │ │ DB-1 │ │ DB-2 │ │ DB-3 │ └───┬────┘ └───┬────┘ └───┬────┘ └───────────┼───────────┘ API Gateway优点独立部署与扩展、技术栈灵活、故障隔离缺点服务间通信复杂、分布式数据一致性困难、需要成熟的 DevOps 能力适用大型复杂系统、多团队协作、需要独立扩展的场景。事件驱动架构Event-Driven通过异步事件通信生产者发布事件消费者响应事件组件之间高度解耦。生产者 ──→ [事件总线/消息队列] ──→ 消费者 A ──→ 消费者 B ──→ 消费者 C优点高度解耦、天然可扩展、适合实时处理缺点调试困难、事件顺序与幂等性需要额外处理适用实时数据分析、物联网系统、微服务间异步通信。整洁架构Clean Architecture由 Robert C. Martin 提出把系统划分为四个同心圆层依赖只能从外向内┌─────────────────────────────────────┐ │ 框架与驱动Frameworks Drivers │ │ ┌─────────────────────────────┐ │ │ │ 接口适配器Interface │ │ │ │ ┌─────────────────────┐ │ │ │ │ │ 用例Use Cases │ │ │ │ │ │ ┌─────────────┐ │ │ │ │ │ │ │ 实体Entity│ │ │ │ │ │ │ │ (领域) │ │ │ │ │ │ │ └─────────────┘ │ │ │ │ │ └─────────────────────┘ │ │ │ └─────────────────────────────┘ │ └─────────────────────────────────────┘ 依赖方向外 → 内基本规则内层不知道外层存在业务逻辑完全独立于框架与数据库优点可测试性高、技术栈可替换、业务逻辑清晰缺点初期开发成本高、层间映射代码多、小项目有过度设计风险适用复杂业务系统、需要长期维护的项目。六边形架构Hexagonal / Ports Adapters用端口定义业务核心的输入/输出接口用适配器连接外部系统┌─────────────┐ HTTP ──→ 端口(输入) │ CLI ──→ │ 中央业务逻辑 │ (输出) ──→ 数据库 MQ ──→ │ │ 端口 ──→ 外部 API └─────────────┘核心思想业务逻辑不依赖任何外部技术外部系统通过适配器接入优点外部系统可自由替换测试只需 Mock 适配器适用需要集成多个外部系统的场景。洋葱架构Onion Architecture与整洁架构类似强调领域模型在最内层、基础设施在最外层依赖只向内┌──────────────────────────────┐ │ 基础设施 │ │ ┌────────────────────────┐ │ │ │ 应用服务 │ │ │ │ ┌──────────────────┐ │ │ │ │ │ 领域服务 │ │ │ │ │ │ ┌────────────┐ │ │ │ │ │ │ │领域模型 │ │ │ │ │ │ │ └────────────┘ │ │ │ │ │ └──────────────────┘ │ │ │ └────────────────────────┘ │ └──────────────────────────────┘核心思想领域模型是系统核心所有依赖指向它与整洁架构的区别洋葱架构更强调领域服务层整洁架构更强调用例层适用采用领域驱动设计DDD的项目。8.3 架构演进路径这些模式不是互相替代的关系而是渐进演化传统分层架构N-Layered │ 问题层间耦合外部依赖难以替换 ▼ 六边形架构Ports Adapters │ 改进用端口与适配器隔离外部系统 ▼ 洋葱架构Onion │ 改进显式同心圆分层领域模型在中心 ▼ 整洁架构Clean Architecture │ 改进统一依赖规则四层职责清晰 ▼ 根据业务需求选择合适的架构8.4 架构模式选型指南用户 1k代码行数 5000 ↓ 单体架构 简单分层 ↓ 用户 1k-100k需要团队协作 ↓ 分层架构本文主题 ↓ 用户 100k业务复杂度高 ↓ 微服务架构 / 事件驱动架构更详细的选型维度考量因素简单分层整洁/六边形架构微服务团队规模1-5 人5-20 人20 人业务复杂度低中高高部署频率低中高独立部署技术栈多样性单一单一可多样运维成本低中高8.5 推荐阅读单体架构参见配套文章 backend-project-architecture.md理解从脚本到单体的演进中文版见 docs/zh-cn/appendix/4-server-and-backend/backend-project-architecture.md微服务架构参见 从单体到微服务整洁架构Robert C. Martin 的《Clean Architecture》——提出依赖规则与四层同心圆模型的经典著作企业应用架构模式Martin Fowler 的《Patterns of Enterprise Application Architecture》——关于分层架构与领域逻辑组织的权威参考。8.6 如何选择记住这个原则架构服务于业务而不是为了架构而架构小项目用简单架构快速上线验证大项目考虑更复杂的架构但要避免过度设计团队熟悉度同样重要选择大家都能理解的方案。9. 总结层职责关键词Controller接收请求、校验参数、调用 Service、返回响应接待员Service业务逻辑编排、事务管理、协调 Repository厨师Repository数据访问、ORM 映射、查询封装仓管员Domain实体定义、业务规则、值对象菜谱标准基本原则分层架构的核心在于清晰的职责划分与依赖方向控制。每层只关注自身职责通过接口与相邻层通信业务逻辑集中在 Service 与 Domain数据访问集中在 Repository层间数据结构通过 DTO 隔离避免直接暴露内部实现细节。这种设计让系统更容易理解、测试与维护能够应对业务的持续演进。参考资料Catalog of Patterns of Enterprise Application Architecture - Martin Fowler —— Martin Fowler 的企业应用架构模式目录分层架构的经典参考Backend Side Architecture Evolution (N-layered, DDD, Hexagon, Onion, Clean Architecture) —— 从 N 层到整洁架构理解每个模式的由来Complete Guide to Clean Architecture - GeeksforGeeks —— 整洁架构完整指南讲解分层、依赖规则与关注点分离Understanding Hexagonal, Clean, Onion, and Traditional Layered Architectures: A Deep Dive —— 六边形、整洁、洋葱与传统分层架构的深入对比Building Clean Architectures in Modern Backend Frameworks —— 在现代后端框架中落地整洁架构的实践指南Backend Architecture Patterns: From Monoliths to Microservices —— 从单体到微服务的后端架构模式全景MVC 三层架构案例分析详解 —— MVC 与三层架构的关系及实际案例适合中文读者。【免费下载链接】easy-vibe vibe coding 101The first course for AI-native product builders.项目地址: https://gitcode.com/GitHub_Trending/ea/easy-vibe创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/16 6:24:38 · 阅读 1.2k easy-vibe 后端分层架构原理：从混乱代码到清晰边界的工程实践指南
easy-vibe 后端分层架构原理从混乱代码到清晰边界的工程实践指南【免费下载链接】easy-vibe vibe coding 101The first course for AI-native product builders.项目地址: https://gitcode.com/GitHub_Trending/ea/easy-vibe核心问题代码越写越乱怎么组织才能清晰易懂当项目从几十行代码扩展到数万行、从单人开发走向团队协作、从简单 CRUD 演进到复杂业务逻辑时代码的组织方式直接决定了项目的生死。分层架构Layered Architecture不是炫技或教条而是为了解决软件工程中的根本性矛盾——业务复杂度的自然增长与人类认知能力的有限性之间的冲突。本文以 easy-vibe 课程体系中《后端分层架构原理》一文为主线对应仓库 docs/es-es/appendix/4-server-and-backend/backend-layered-architecture.md英文版见 docs/en/appendix/4-server-and-backend/backend-layered-architecture.md中文版见 docs/zh-cn/appendix/4-server-and-backend/backend-layered-architecture.md完整讲解 Controller / Service / Repository / Domain 四层模型、DTO 隔离机制与依赖方向控制并延伸到单体、微服务、事件驱动、整洁、六边形、洋葱等常见架构模式的选型路径帮助你建立可测试、可维护、可演进的工程化后端认知。1. 为什么需要分层问题的根源1.1 从 100 行到 500 行的失控曲线初期版本约 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 协议绑定一处改动牵一发动全身❌低内聚一个方法承担多种职责违反单一职责原则SRP❌难测试无法隔离测试业务逻辑必须启动完整的 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。2.2 Controller 层请求的接待员职责接收 HTTP 请求解析参数校验参数格式、必填等DTO 转换Request → Param调用 Service 执行业务逻辑DTO 转换Result → Response返回 HTTP 响应。不该做的事直接编写业务逻辑直接操作数据库管理事务。设计哲学Controller 是系统的门面Facade扮演适配器角色——把外部 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 隔离前后端数据结构只做翻译和分发不含业务逻辑。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 概念可以复用。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自定义。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 层是纯业务逻辑不依赖框架。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 只包含必要字段避免暴露内部实现细节保证各层独立性。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 { // 实现细节 }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); } }注意这个案例中依赖方向的完整闭环Controller 只负责接收OrderRequest并转换为OrderParamService 通过OrderRepository接口与InventoryService编排流程领域对象Order自己封装了金额计算与取消规则。库存扣减逻辑以服务形式被编排这体现了层与层之间面向接口协作而非面向实现调用的核心思想。6. 常见问题解答6.1 Controller 可以包含业务逻辑吗Controller 不应包含业务逻辑只负责接收请求和返回响应。业务逻辑应封装在 Service 层这样代码才可复用例如定时任务、消息队列消费者可以不经过 HTTP 直接调用 Service。此外业务逻辑集中在一处便于测试和维护避免逻辑分散导致的不一致。6.2 贫血模型与充血模型贫血模型Anemic Domain Model实体类只包含属性及对应的 getter/setter没有任何业务逻辑所有业务规则在 Service 层实现。结构简单、易于理解是大多数项目采用的方式。充血模型Rich Domain Model实体类不仅包含属性还包含与该实体相关的业务方法把业务规则封装在实体内部。更符合面向对象设计数据与行为在一起内聚性更高。建议根据团队技术水平和项目复杂度选择合适的模型但无论选择哪种都应保持一致性。Domain 层至少应包含基本的业务行为方法而不是一个完全空壳。6.3 跨多个 Service 的事务如何处理当一个业务操作需要跨越多个 Service 时应在最上层的 Service 方法上加事务注解在该方法内部依次调用下层 Service。这保证所有操作在同一事务上下文中执行要么全部成功要么全部失败确保数据一致性。同时要注意事务边界尽量小只包含必要操作避免长时间持有数据库锁而影响并发性能。7. 分层架构小结层职责关键词Controller接收请求、校验参数、调用 Service、返回响应接待员Service业务逻辑编排、事务管理、协调 Repository厨师Repository数据访问、ORM 映射、查询封装仓管员Domain实体定义、业务规则、值对象菜谱标准基本原则每层只做自己该做的事层间通过接口通信业务逻辑集中在 Service 与 Domain数据访问逻辑集中在 Repository用 DTO 隔离层间数据结构。分层架构的核心在于清晰的职责划分与依赖方向控制。每层只关注自身职责通过接口与相邻层通信业务逻辑集中在 Service 与 Domain数据访问集中在 Repository层间数据结构通过 DTO 隔离避免直接暴露内部实现细节。这种设计让系统更容易理解、测试与维护能够应对业务的持续演进。8. 更多架构模式从分层走向演进上文介绍的分层架构Layered Architecture是最常见、最容易落地的后端架构模式。但后端架构不止于此根据业务场景还存在其他值得了解的模式。8.1 常见架构模式一览架构模式适用场景特点单体架构小项目、MVP所有功能在一个应用中部署简单微服务架构大型复杂系统拆分为多个独立服务各自独立部署事件驱动架构高并发、异步处理处理流程由事件触发高度解耦整洁架构复杂业务系统业务逻辑在中心依赖只向内框架在最外层六边形架构需要多个外部适配器通过端口与适配器隔离核心与外部系统洋葱架构领域驱动设计同心圆分层领域模型在中心基础设施在外围8.2 各模式详解单体架构Monolithic所有功能打包在一个应用中共享同一数据库与进程。┌──────────────────────────────┐ │ 单体应用 │ │ ┌────┐ ┌────┐ ┌────┐ │ │ │用户 │ │订单 │ │支付 │ ... │ │ └──┬─┘ └──┬─┘ └──┬─┘ │ │ └──────┼──────┘ │ │ 共享数据库 │ └──────────────────────────────┘优点开发简单、部署方便、本地调试容易缺点代码耦合度高、难以扩展、一个模块故障可能拖垮整个系统适用早期创业项目、单团队开发、快速验证原型。微服务架构Microservices把系统拆分为多个独立服务每个服务有自己的数据与业务逻辑可独立部署与扩展。┌────────┐ ┌────────┐ ┌────────┐ │用户服务 │ │订单服务 │ │支付服务 │ │ DB-1 │ │ DB-2 │ │ DB-3 │ └───┬────┘ └───┬────┘ └───┬────┘ └───────────┼───────────┘ API Gateway优点独立部署与扩展、技术栈灵活、故障隔离缺点服务间通信复杂、分布式数据一致性困难、需要成熟的 DevOps 能力适用大型复杂系统、多团队协作、需要独立扩展的场景。事件驱动架构Event-Driven通过异步事件通信生产者发布事件消费者响应事件组件之间高度解耦。生产者 ──→ [事件总线/消息队列] ──→ 消费者 A ──→ 消费者 B ──→ 消费者 C优点高度解耦、天然可扩展、适合实时处理缺点调试困难、事件顺序与幂等性需要额外处理适用实时数据分析、物联网系统、微服务间异步通信。整洁架构Clean Architecture由 Robert C. Martin 提出把系统划分为四个同心圆层依赖只能从外向内┌─────────────────────────────────────┐ │ 框架与驱动Frameworks Drivers │ │ ┌─────────────────────────────┐ │ │ │ 接口适配器Interface │ │ │ │ ┌─────────────────────┐ │ │ │ │ │ 用例Use Cases │ │ │ │ │ │ ┌─────────────┐ │ │ │ │ │ │ │ 实体Entity│ │ │ │ │ │ │ │ (领域) │ │ │ │ │ │ │ └─────────────┘ │ │ │ │ │ └─────────────────────┘ │ │ │ └─────────────────────────────┘ │ └─────────────────────────────────────┘ 依赖方向外 → 内基本规则内层不知道外层存在业务逻辑完全独立于框架与数据库优点可测试性高、技术栈可替换、业务逻辑清晰缺点初期开发成本高、层间映射代码多、小项目有过度设计风险适用复杂业务系统、需要长期维护的项目。六边形架构Hexagonal / Ports Adapters用端口定义业务核心的输入/输出接口用适配器连接外部系统┌─────────────┐ HTTP ──→ 端口(输入) │ CLI ──→ │ 中央业务逻辑 │ (输出) ──→ 数据库 MQ ──→ │ │ 端口 ──→ 外部 API └─────────────┘核心思想业务逻辑不依赖任何外部技术外部系统通过适配器接入优点外部系统可自由替换测试只需 Mock 适配器适用需要集成多个外部系统的场景。洋葱架构Onion Architecture与整洁架构类似强调领域模型在最内层、基础设施在最外层依赖只向内┌──────────────────────────────┐ │ 基础设施 │ │ ┌────────────────────────┐ │ │ │ 应用服务 │ │ │ │ ┌──────────────────┐ │ │ │ │ │ 领域服务 │ │ │ │ │ │ ┌────────────┐ │ │ │ │ │ │ │领域模型 │ │ │ │ │ │ │ └────────────┘ │ │ │ │ │ └──────────────────┘ │ │ │ └────────────────────────┘ │ └──────────────────────────────┘核心思想领域模型是系统核心所有依赖指向它与整洁架构的区别洋葱架构更强调领域服务层整洁架构更强调用例层适用采用领域驱动设计DDD的项目。8.3 架构演进路径这些模式不是互相替代的关系而是渐进演化传统分层架构N-Layered │ 问题层间耦合外部依赖难以替换 ▼ 六边形架构Ports Adapters │ 改进用端口与适配器隔离外部系统 ▼ 洋葱架构Onion │ 改进显式同心圆分层领域模型在中心 ▼ 整洁架构Clean Architecture │ 改进统一依赖规则四层职责清晰 ▼ 根据业务需求选择合适的架构8.4 架构模式选型指南用户 1k代码行数 5000 ↓ 单体架构 简单分层 ↓ 用户 1k-100k需要团队协作 ↓ 分层架构本文主题 ↓ 用户 100k业务复杂度高 ↓ 微服务架构 / 事件驱动架构更详细的选型维度考量因素简单分层整洁/六边形架构微服务团队规模1-5 人5-20 人20 人业务复杂度低中高高部署频率低中高独立部署技术栈多样性单一单一可多样运维成本低中高8.5 推荐阅读单体架构参见配套文章 backend-project-architecture.md理解从脚本到单体的演进中文版见 docs/zh-cn/appendix/4-server-and-backend/backend-project-architecture.md微服务架构参见 从单体到微服务整洁架构Robert C. Martin 的《Clean Architecture》——提出依赖规则与四层同心圆模型的经典著作企业应用架构模式Martin Fowler 的《Patterns of Enterprise Application Architecture》——关于分层架构与领域逻辑组织的权威参考。8.6 如何选择记住这个原则架构服务于业务而不是为了架构而架构小项目用简单架构快速上线验证大项目考虑更复杂的架构但要避免过度设计团队熟悉度同样重要选择大家都能理解的方案。9. 总结层职责关键词Controller接收请求、校验参数、调用 Service、返回响应接待员Service业务逻辑编排、事务管理、协调 Repository厨师Repository数据访问、ORM 映射、查询封装仓管员Domain实体定义、业务规则、值对象菜谱标准基本原则分层架构的核心在于清晰的职责划分与依赖方向控制。每层只关注自身职责通过接口与相邻层通信业务逻辑集中在 Service 与 Domain数据访问集中在 Repository层间数据结构通过 DTO 隔离避免直接暴露内部实现细节。这种设计让系统更容易理解、测试与维护能够应对业务的持续演进。参考资料Catalog of Patterns of Enterprise Application Architecture - Martin Fowler —— Martin Fowler 的企业应用架构模式目录分层架构的经典参考Backend Side Architecture Evolution (N-layered, DDD, Hexagon, Onion, Clean Architecture) —— 从 N 层到整洁架构理解每个模式的由来Complete Guide to Clean Architecture - GeeksforGeeks —— 整洁架构完整指南讲解分层、依赖规则与关注点分离Understanding Hexagonal, Clean, Onion, and Traditional Layered Architectures: A Deep Dive —— 六边形、整洁、洋葱与传统分层架构的深入对比Building Clean Architectures in Modern Backend Frameworks —— 在现代后端框架中落地整洁架构的实践指南Backend Architecture Patterns: From Monoliths to Microservices —— 从单体到微服务的后端架构模式全景MVC 三层架构案例分析详解 —— MVC 与三层架构的关系及实际案例适合中文读者。【免费下载链接】easy-vibe vibe coding 101The first course for AI-native product builders.项目地址: https://gitcode.com/GitHub_Trending/ea/easy-vibe创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考