项目设计 skill 入门指南：从零到一构建可维护的工程架构

2次阅读

没有评论

共计 2207 个字符，预计需要花费 6 分钟才能阅读完成。

刚入行的开发者常常会遇到这样的场景：项目初期功能简单，所有代码都堆在一个文件里也能跑起来。但随着需求增加，代码逐渐变成了难以维护的『大泥球』。以下是几个典型问题：

全局状态滥用 ：在 Vue/React 项目中随处可见的this.$store.state.xxx 直接穿透多层组件
业务逻辑与 UI 强耦合：一个 500 行的组件里混杂着 API 调用、数据处理和 DOM 操作
模块边界模糊：utils 文件夹里有 200 个文件，每个文件都像黑洞不知道依赖了哪些其他模块

这些问题会导致：修改一个按钮样式可能引发支付逻辑报错，新人不敢动老代码只能不断打补丁。

表现层：处理用户交互（组件 /Controller）
业务层：核心业务逻辑（Service/Domain）
数据层：持久化和外部服务（DAO/Repository）

适用场景：CRUD 为主的业务系统，技术栈统一的中小型项目

核心域 在六边形中心
通过「端口」定义交互契约
「适配器」处理具体技术实现（如 Web 框架、数据库驱动）

优势：当需要替换数据库或 UI 框架时，只需重写适配器而不影响业务逻辑。电商、支付等复杂领域推荐采用。

内聚性：模块内元素关联程度（1-10 分）
9 分示例：所有订单相关 API、DTO、Service 都在 order 模块
2 分示例：common模块里既有日期工具又有权限校验
耦合度：模块间依赖数量（理想值 <5）
抽象泄漏：内部实现细节暴露程度（可通过接口方法数 / 公有字段数评估）

// 定义抽象接口（端口）interface PaymentService {charge(amount: number): Promise<Receipt>;
}

// 具体实现（适配器）class StripePayment implements PaymentService {async charge(amount: number) {
    // 调用 Stripe SDK
    return {id: 'stripe_123', amount};
  }
}

// 业务类通过构造函数注入依赖
class OrderProcessor {constructor(private payment: PaymentService) {}

  async checkout(order: Order) {
    // 不关心具体支付实现
    return this.payment.charge(order.total);
  }
}

// 组合根配置（DI 容器）const container = new Container();
container.bind<PaymentService>('PaymentService').to(StripePayment);

// 使用时自动解析依赖
const processor = container.get(OrderProcessor);

设计决策说明：
– 接口隔离了第三方 SDK 的强依赖，测试时可替换为 Mock 实现
– 构造函数注入比属性注入更显式地声明依赖关系
– 容器管理生命周期避免手动 new 导致的硬耦合

graph LR
  A[单体架构] --> B[功能分包]
  B --> C[层级划分]
  C --> D[领域模块]
  D --> E[微服务]

使用 madge 工具生成模块依赖图：

npx madge --circular src/

常见解决方案：
1. 提取公共代码到新模块
2. 引入中间层（如事件总线）
3. 依赖倒置（高层模块定义接口，低层实现）

坏味道：
– 对象只有 getter/setter 没有行为方法
– 业务逻辑都在 Service 中处理

重构示例：

// 重构前
class Order {items: Item[];
  status: string;
}

class OrderService {cancel(order: Order) {if(order.status !== 'paid') {throw new Error('不可取消');
    }
    order.status = 'cancelled';
  }
}

// 重构后
class Order {
  private status: OrderStatus;

  cancel() {if(this.status !== 'paid') {throw new Error('不可取消');
    }
    this.status = 'cancelled';
  }
}

实测数据（基于 Webpack）：