模块边界设计：让改动停在该停的地方

// ❌ 坏做法：一个 Service 承担所有职责
class OrderService {
  // 价格计算
  async calculatePrice(items: CartItem[]): Promise<PriceResult> {
    const subtotal = items.reduce((sum, i) => sum + i.price * i.qty, 0)
    const discount = await this.getDiscount(subtotal)
    // 同时做了库存检查（副作用）
    await this.checkStock(items)
    return { subtotal, discount, total: subtotal - discount }
  }
 
  // 创建订单——依赖上面所有逻辑
  async createOrder(cartId: string) {
    const items = await this.cartRepo.getItems(cartId)
    const price = await this.calculatePrice(items)
    // 库存预占直接耦合了价格计算结果
    await this.reserveInventory(items, price.subtotal)
    return this.orderRepo.create({ items, price })
  }
 
  // 库存、退款、物流全在这里
  async reserveInventory(items, amount) { /* ... */ }
  async processRefund(orderId, reason) { /* ... */ }
  async syncLogistics(orderId) { /* ... */ }
}

// ✅ 好做法：每个模块只负责一件事，通过契约通信
 
// pricing/pricing.service.ts — 只管价格计算
export class PricingService {
  async calculate(items: CartItem[]): Promise<PriceResult> {
    const subtotal = items.reduce((sum, i) => sum + i.price * i.qty, 0)
    const discount = await this.discountRepo.apply(subtotal, items)
    return { subtotal, discount, total: subtotal - discount }
  }
}
 
// inventory/inventory.service.ts — 只管库存
export class InventoryService {
  async reserve(items: CartItem[]): Promise<ReservationResult> {
    // 库存预占不需要知道价格，只关心数量
    return this.stockRepo.batchReserve(
      items.map(i => ({ skuId: i.skuId, qty: i.qty }))
    )
  }
}
 
// order/order.service.ts — 只编排流程，不实现细节
export class OrderService {
  constructor(
    private pricing: PricingService,
    private inventory: InventoryService,
    private orderRepo: OrderRepository
  ) {}
 
  async createOrder(cartId: string) {
    const items = await this.cartRepo.getItems(cartId)
 
    // 先算价，再占库存——各自独立，互不影响
    const price = await this.pricing.calculate(items)
    const reservation = await this.inventory.reserve(items)
 
    if (!reservation.success) {
      throw new InsufficientStockError(reservation.shortages)
    }
 
    return this.orderRepo.create({ items, price })
  }
}

// ❌ 坏做法：通用组件 import 了业务页面的工具函数
// src/components/common/UserAvatar.tsx
import { formatRole } from '@/pages/user-management/utils/formatRole'
 
export function UserAvatar({ user }: { user: User }) {
  return (
    <div className="avatar">
      <img src={user.avatar} alt={user.name} />
      {/* 这里用了业务页面的格式化逻辑 */}
      <span>{formatRole(user.role)}</span>
    </div>
  )
}

// ✅ 好做法：通用组件只接受展示所需的数据，不关心来源
// src/components/common/UserAvatar.tsx
// 不再 import formatRole，而是接收已格式化好的数据
interface UserAvatarProps {
  name: string
  avatar: string
  roleLabel: string  // 调用方负责格式化
}
 
export function UserAvatar({ name, avatar, roleLabel }: UserAvatarProps) {
  return (
    <div className="avatar">
      <img src={avatar} alt={name} />
      <span>{roleLabel}</span>
    </div>
  )
}
 
// 调用方在 feature 层完成格式化
// src/features/user-management/components/UserList.tsx
import { formatRole } from '../utils/formatRole'
import { UserAvatar } from '@/components/common/UserAvatar'
 
function UserList({ users }: { users: User[] }) {
  return users.map(user => (
    <UserAvatar
      key={user.id}
      name={user.name}
      avatar={user.avatar}
      roleLabel={formatRole(user.role)}
    />
  ))
}

// ❌ 坏做法：user-service 直接调用 order-service
// user-service/profile.service.ts
class ProfileService {
  constructor(private orderClient: OrderServiceClient) {}
 
  async getUserProfile(userId: string) {
    const user = await this.userRepo.findById(userId)
    // 同步调用 order-service，形成循环依赖
    const recentOrders = await this.orderClient.getRecentOrders(userId, 5)
    return { ...user, recentOrders }
  }
}

// ✅ 好做法：order-service 发布事件，user-service 订阅
// order-service/order.events.ts — 发布方
export class OrderEventPublisher {
  async publishOrderCreated(order: Order) {
    await this.messageBus.publish('order.created', {
      orderId: order.id,
      userId: order.userId,
      amount: order.totalAmount,
      status: order.status,
      createdAt: order.createdAt
    })
  }
}
 
// user-service/order-summary.handler.ts — 订阅方
export class OrderSummaryHandler {
  // 收到事件后写入本地缓存，不再同步调用 order-service
  async handle(event: OrderCreatedEvent) {
    await this.orderSummaryRepo.upsert({
      userId: event.userId,
      orderId: event.orderId,
      amount: event.amount,
      status: event.status,
      updatedAt: new Date()
    })
  }
}
 
// user-service/profile.service.ts — 读本地数据
class ProfileService {
  constructor(private orderSummaryRepo: OrderSummaryRepository) {}
 
  async getUserProfile(userId: string) {
    const user = await this.userRepo.findById(userId)
    // 从本地缓存读，不再有跨服务调用
    const recentOrders = await this.orderSummaryRepo.findRecent(userId, 5)
    return { ...user, recentOrders }
  }
}

// .dependency-cruiser.mjs
export default {
  forbidden: [
    {
      name: 'no-common-to-feature',
      comment: '通用组件不得依赖业务功能模块',
      from: { path: 'src/components/' },
      to: { path: 'src/features/' }
    },
    {
      name: 'no-feature-to-page',
      comment: '功能模块不得依赖页面层',
      from: { path: 'src/features/' },
      to: { path: 'src/pages/' }
    },
    {
      name: 'no-circular',
      comment: '禁止循环依赖',
      from: {},
      to: { circular: true }
    }
  ]
}