软件设计中的整洁架构：让代码像乐高一样优雅

软件设计中的整洁架构：让代码像乐高一样优雅

你是否遇到过这样的代码？

• 改一个小功能，却要动几十个文件？
• 业务逻辑和数据库、框架代码混在一起，难以测试？
• 换一个技术框架（比如从 MySQL 换成 MongoDB），整个项目几乎要重写？

整洁架构（Clean Architecture） 就是为了解决这些问题而生的！它让你的代码像乐高积木一样，模块清晰、易于替换、长期可维护。

今天，我们就用最通俗的语言，聊聊整洁架构的核心思想，以及如何用它设计出“高内聚、低耦合”的软件系统。

1. 什么是整洁架构？

整洁架构是由 Robert C. Martin（Uncle Bob） 提出的一种软件设计思想，核心目标是：

• ✅ 业务逻辑独立：不依赖数据库、框架、UI 等具体技术。
• ✅ 易于扩展和维护：改需求或换技术时，只需改少量代码。
• ✅ 高度可测试：业务逻辑能单独测试，不依赖外部服务。

它的设计灵感来源于 “洋葱模型”，代码像洋葱一样分层，外层依赖内层，但内层绝不依赖外层！

2. 整洁架构的分层

想象一个洋葱，从内到外分为四层：

（1）核心层（Entities & Use Cases）

• Entities（实体）：代表业务核心对象（比如 User、Order）。
• Use Cases（用例）：实现具体的业务逻辑（比如 CreateUser、ProcessOrder）。

关键特点：

• 这一层是纯业务逻辑，不依赖任何外部技术（比如数据库、HTTP 框架）。
• 比如“用户注册”的逻辑，不应该知道数据是存在 MySQL 还是 Redis 里。

（2）接口适配层（Interface Adapters）

• Controller：接收 HTTP 请求，调用 Use Case。
• Repository：数据库操作的接口（比如 UserRepository），具体实现在外层。

关键特点：

• 负责把外部数据（比如 HTTP 请求、数据库）转换成 Use Case 能理解的格式。
• 比如：将 HTTP 的 JSON 请求转换成 CreateUserCommand 对象。

（3）框架层（Frameworks & Drivers）

• 数据库：MySQL、MongoDB 的具体实现。
• Web 框架：Spring Boot、Express 的路由和 HTTP 处理。
• 第三方服务：调用支付宝、微信的 SDK。

关键特点：

• 这一层是具体的工具，随时可以替换（比如从 Spring Boot 换成 Ktor）。
• 比如 UserRepository 的 MySQL 实现就在这里，但 Use Case 不需要知道。

---

3. 依赖规则：单向依赖

整洁架构的核心规则是：

• 内层（业务逻辑）不能依赖外层（技术细节）！
• 外层可以依赖内层，但不能反过来。

举个例子：

• 错误设计：User 实体里直接调用 MySQL 的 API。
• 正确设计：User 只关心业务规则，数据库操作通过 UserRepository 接口实现。

4. 为什么用整洁架构？

（1）技术无关性

• 业务逻辑不依赖框架，换技术成本极低。

比如：从 MySQL 换 MongoDB？只需改 Repository 实现，Use Case 一行代码不用动！

（2）易于测试

• Use Case 可以单独测试，不需要启动数据库或 HTTP 服务。

比如：测试“用户注册”逻辑，直接 mock 一个 UserRepository 即可。

（3）长期可维护性

• 代码分层清晰，新人能快速理解，改需求不会“牵一发而动全身”。

5. 实战案例：用户注册

• 假设我们要实现一个“用户注册”功能，用整洁架构设计如下：

（1）核心层

// Entity（业务对象）
public class User {
    private String id;
    private String email;
    // 业务规则：邮箱必须合法
    public boolean isValidEmail() { ... }
}

// Use Case（业务逻辑）
public class RegisterUser {
    private final UserRepository repository;

    public RegisterUser(UserRepository repository) {
        this.repository = repository;
    }

    public void execute(User user) {
        if (!user.isValidEmail()) throw new InvalidEmailException();
        repository.save(user); // 调用接口，不关心具体实现
    }
}

（2）接口适配层

// Repository 接口（内层定义）
public interface UserRepository {
    void save(User user);
}

// HTTP Controller（外层实现）
@RestController
public class UserController {
    private final RegisterUser registerUser;

    @PostMapping("/users")
    public void createUser(@RequestBody UserRequest request) {
        User user = new User(request.email());
        registerUser.execute(user); // 调用 Use Case
    }
}

（3）框架层

// MySQL 实现（外层）
@Repository
public class MySQLUserRepository implements UserRepository {
    public void save(User user) {
        // 具体数据库操作
    }
}

---

6. 常见问题

Q1：整洁架构适合所有项目吗？

• 适合 长期维护的中大型项目，小型项目可能会觉得“过度设计”。

Q2：会不会增加代码量？

• 短期看，分层会多写一些接口和适配器；
• 长期看，维护成本大幅降低，绝对是值得的！

Q3：如何落地到团队？

• 从 核心业务逻辑 开始，逐步剥离技术细节。
• 结合 DDD（领域驱动设计） 划分业务边界。

7. 总结

整洁架构的核心思想：

• 业务逻辑与技术细节分离（像乐高一样模块化）。
• 内层不依赖外层（避免被框架绑架）。
• 通过接口解耦（轻松替换实现）。

如果你受够了“改一行代码炸整个系统”的痛苦，不妨试试整洁架构！