技术债治理路线图：把架构问题拆成可交付切片

// ❌ 所有模块直接操作同一个仓储，没有边界
class OrderService {
  constructor(private db: SharedDatabase) {}
 
  async createOrder(dto: CreateOrderDto) {
    const order = this.db.orders.create(dto)
    // 直接调用库存逻辑，紧耦合
    this.db.inventory.deduct(dto.items)
    // 直接调用支付逻辑，紧耦合
    this.db.payments.initiate(order)
    return order
  }
}

// ✅ 通过事件解耦，每个模块有自己的仓储
class OrderService {
  constructor(
    private orderRepo: OrderRepository,
    private eventBus: EventBus,
  ) {}
 
  async createOrder(dto: CreateOrderDto) {
    const order = await this.orderRepo.create(dto)
    // 发布事件，由下游模块各自处理
    await this.eventBus.publish('order.created', {
      orderId: order.id,
      items: dto.items,
    })
    return order
  }
}

// ✅ 用百分比切流，支持回滚
function shouldRouteToNewService(
  userId: string,
  featureFlags: FeatureFlags,
): boolean {
  // 未开启灰度，全走旧服务
  if (!featureFlags.isEnabled('order-read-v2')) {
    return false
  }
  // 按用户 ID 哈希取模，保证同一用户路由稳定
  const hash = parseInt(userId.slice(-2), 10)
  const rolloutPercent = featureFlags.getNumber('order-read-v2-percent', 0)
  return hash < rolloutPercent
}

# API 网关层配置，按权重分配流量
upstream order_read {
  server old-order-service:8080 weight=70;
  server new-order-service:8080 weight=30;
}

// ❌ 订单服务直接依赖风控服务的内部实现
class OrderService {
  constructor(
    private riskRepo: RiskRepository,
    private userService: UserService, // 循环：User → Message → User
  ) {}
 
  async createOrder(dto: CreateOrderDto) {
    const user = await this.userService.getUser(dto.userId)
    const riskLevel = await this.riskRepo.checkRisk(user)
    if (riskLevel === 'high') throw new Error('Risk too high')
    return this.create(dto)
  }
}

// ✅ 事件中介，各模块订阅自己关心的事件
// 订单模块只负责发布事件，不关心谁消费
class OrderService {
  constructor(
    private orderRepo: OrderRepository,
    private eventBus: EventBus,
  ) {}
 
  async createOrder(dto: CreateOrderDto) {
    const order = await this.orderRepo.create(dto)
    // 发布事件，由风控模块自己订阅处理
    await this.eventBus.publish('order.created', {
      orderId: order.id,
      userId: dto.userId,
      amount: dto.amount,
    })
    return order
  }
}
 
// 风控模块独立消费事件，不反向依赖订单模块
class RiskListener {
  constructor(
    private orderQuery: OrderQueryClient, // 通过 API 调用，非直接依赖
    private riskRepo: RiskRepository,
  ) {}
 
  @On('order.created')
  async handleOrderCreated(event: OrderCreatedEvent) {
    const history = await this.orderQuery.getUserOrders(event.userId)
    const riskLevel = this.riskRepo.evaluate(event, history)
    if (riskLevel === 'high') {
      await this.eventBus.publish('risk.alert', { orderId: event.orderId })
    }
  }
}

{
  "forbidden": [
    {
      "name": "no-circular-deps",
      "comment": "禁止模块间循环依赖，发现即阻断 CI",
      "from": { "path": "src/modules/order/" },
      "to": {
        "path": "src/modules/order/",
        "via": { "path": "src/modules/risk/" }
      }
    }
  ]
}

// ❌ 三个服务直接操作同一张 users 表
// 服务 A 改了 schema，服务 B 和 C 可能查询报错
class ProfileService {
  async updateProfile(userId: string, data: ProfileData) {
    await this.db.query(
      'UPDATE users SET name = $1, avatar = $2 WHERE id = $3',
      [data.name, data.avatar, userId]
    )
  }
}
 
class SettingsService {
  async updateSettings(userId: string, data: SettingsData) {
    // 同一个表，不同的服务在写
    await this.db.query(
      'UPDATE users SET theme = $1, lang = $2 WHERE id = $3',
      [data.theme, data.lang, userId]
    )
  }
}

// ✅ 用户服务是唯一的数据所有者
class UserService {
  async updateProfile(userId: string, data: ProfileData) {
    const user = await this.userRepo.update(userId, {
      name: data.name,
      avatar: data.avatar,
    })
    // 数据变更后发布事件，下游订阅
    await this.eventBus.publish('user.updated', {
      userId,
      changedFields: ['name', 'avatar'],
    })
    return user
  }
}
 
// ✅ 双写期间的过渡方案——保证数据一致性
async function migrateUserData(userId: string) {
  // 先写新表
  const newRecord = await newUserRepo.upsert(userId, data)
  try {
    // 再写老表，标记迁移状态
    await oldUserRepo.update(userId, { migrated: true })
    await syncLog.record({ userId, status: 'migrated' })
  } catch (err) {
    // 老表写入失败不影响新表，记录错误后续修复
    await syncLog.record({ userId, status: 'old_write_failed', error: err })
  }
}

// 明确每个阶段的进入条件，不靠「感觉差不多了」
const migrationPhases = [
  {
    phase: '全量同步',
    duration: '1-2 周',
    entryCriteria: 'CDC 管道搭建完成，延迟 < 1s',
    exitCriteria: '数据一致性 > 99.99%，错误率 < 0.01%',
  },
  {
    phase: '灰度切读',
    duration: '1-2 周',
    entryCriteria: '全量同步通过验收',
    exitCriteria: '新服务 P99 < 50ms，无数据不一致反馈',
  },
  {
    phase: '全量切读',
    duration: '1 周',
    entryCriteria: '灰度期无 P1/P2 故障',
    exitCriteria: '老表读流量降为 0，持续 72 小时',
  },
  {
    phase: '下线老表',
    duration: '-',
    entryCriteria: '老表零流量，团队 review 确认',
    exitCriteria: '老表删除，CDC 管道关闭',
  },
]