基于TypeScript+Knex的Repository模式联表查询最佳实践探讨

1. Repository的组合方式与层级选择 #

核心原则 #

• 聚合内关联（SaleOrder + LineItem）：LineItem作为聚合根SaleOrder的子实体，不应该单独设计Repository，所有涉及LineItem的操作（增删改查）必须通过SaleOrderRepository封装，以此保证聚合的完整性（比如创建订单时必须同步写入订单项，不能单独修改订单项脱离订单上下文）。
• 跨聚合查询（SaleOrder + Customer）：不建议在应用层直接组合多个Repository的查询逻辑（比如先查CustomerRepo再查SaleOrderRepo），这会导致N+1查询或低效的数据拼接，且会把数据访问细节泄露到应用层。

正确的组合方式 #

应该在基础设施层封装专门的查询逻辑：

• 方案一：扩展SaleOrderRepository，新增跨聚合查询方法，内部用Knex完成JOIN逻辑，返回结构化的DTO（而非领域对象）。
• 方案二：单独创建查询服务类（比如CustomerSalesQueryService），专注处理跨聚合的复杂查询，与Repository职责分离（Repository负责聚合的持久化，查询服务负责读优化的跨表查询）。

为什么不在应用层组合 #

应用层的职责是编排业务流程（比如校验权限、触发事件），而非处理数据访问细节。如果在应用层拼接多个Repository的查询，会导致数据访问逻辑散落在业务流程中，难以维护和复用，也违背了Repository模式封装数据访问的初衷。

2. 读写分离策略与复杂SQL的存放 #

策略合理性 #

这个方案完全符合Repository模式的设计初衷：

• 写入操作：必须通过聚合根Repository处理，保证聚合的业务规则被执行（比如订单总金额必须等于所有订单项金额之和），避免直接操作数据库破坏数据一致性。
• 常规读取操作：比如根据ID查单个订单、查订单的所有订单项，用Repository封装，返回领域对象，保证业务层能直接使用聚合逻辑。
• 复杂联表查询：跨聚合的高效JOIN查询直接用Knex写原生SQL是最优解，因为这类查询往往是为了展示数据（而非修改），不需要遵守聚合的边界，且单条JOIN的性能远优于多轮查询。

代码存放位置 #

复杂SQL的代码应该放在基础设施层：

• 若选择扩展Repository，直接把SQL逻辑写在SaleOrderRepository的查询方法中（如示例中的findByCustomerWithDetails）。
• 若选择单独的查询服务，可在基础设施层创建queries目录，比如customer-sales.queries.ts，将查询逻辑封装为独立函数或类方法。

关键注意点 #

严格遵循参考观点：Repository查询方法不能返回Knex.QueryBuilder。如果返回QueryBuilder，上层业务代码可能随意拼接查询条件，破坏Repository的封装性，导致数据访问逻辑失控。所有Repository或查询服务的方法都应该直接返回最终的领域对象或DTO。

代码示例（TypeScript+Knex） #

// 基础设施层 - SaleOrderRepository.ts
import knex from '../knex-config';
import { SaleOrder, LineItem } from '../../domain/entities';
import { CustomerSaleOrderWithItemsDTO } from '../../application/dtos';

export class SaleOrderRepository {
  // 写入：创建订单（保证聚合完整性）
  async create(order: SaleOrder): Promise<void> {
    await knex.transaction(async trx => {
      const [orderId] = await trx('sale_orders').insert({
        id: order.id,
        customer_id: order.customerId,
        total_amount: order.totalAmount,
        created_at: order.createdAt
      }).returning('id');
      
      await trx('line_items').insert(
        order.lineItems.map(item => ({
          id: item.id,
          order_id: orderId,
          product_id: item.productId,
          quantity: item.quantity,
          unit_price: item.unitPrice
        }))
      );
    });
  }

  // 常规读取：根据ID查询订单（包含订单项）
  async findById(id: string): Promise<SaleOrder | null> {
    const orderRow = await knex('sale_orders').where('id', id).first();
    if (!orderRow) return null;
    
    const lineItemRows = await knex('line_items').where('order_id', id);
    return SaleOrder.fromPersistence({
      ...orderRow,
      lineItems: lineItemRows.map(row => LineItem.fromPersistence(row))
    });
  }

  // 复杂跨聚合查询：查询指定客户的订单及详情
  async findByCustomerWithDetails(customerId: string): Promise<CustomerSaleOrderWithItemsDTO[]> {
    const rows = await knex('sale_orders as so')
      .join('customers as c', 'so.customer_id', 'c.id')
      .leftJoin('line_items as li', 'so.id', 'li.order_id')
      .where('so.customer_id', customerId)
      .select([
        'so.id as order_id',
        'so.total_amount as order_total',
        'so.created_at as order_created_at',
        'c.name as customer_name',
        'c.email as customer_email',
        'li.product_id as item_product_id',
        'li.quantity as item_quantity',
        'li.unit_price as item_unit_price'
      ]);

    // 将平级查询结果转换为结构化DTO
    const orderMap = new Map<string, CustomerSaleOrderWithItemsDTO>();
    rows.forEach(row => {
      if (!orderMap.has(row.order_id)) {
        orderMap.set(row.order_id, {
          orderId: row.order_id,
          orderTotal: row.order_total,
          orderCreatedAt: row.order_created_at,
          customer: {
            name: row.customer_name,
            email: row.customer_email
          },
          lineItems: []
        });
      }
      if (row.item_product_id) {
        orderMap.get(row.order_id)?.lineItems.push({
          productId: row.item_product_id,
          quantity: row.item_quantity,
          unitPrice: row.item_unit_price
        });
      }
    });
    return Array.from(orderMap.values());
  }
}

内容的提问来源于stack exchange，提问作者friartuck