2. 유스케이스를 격리하고 의존성을 나누어 Lint로 규칙 세우기

시스템으로 강제하기

// eslint-rules.js — 본문 외 부분은 생략했습니다.
const MOCK_APIS = new Set(['fn', 'mock', 'doMock', 'hoisted', 'spyOn', 'mocked']);
// Mock을 정의해도 되는 자리.
const DEFAULT_MOCK_ALLOWED_DIRS = ['/test/support/doubles/', '/test/unit/support/', '/test/unit/http/'];
const noInternalCollaboratorMock = {
  meta: {
    // …
    messages: {
      forbidden:
        "spec 에서 'vi.{{api}}' 로 리포지토리·도메인 서비스를 Mock으로 세우지 않는다. 저장된 값을 봐야 하면 통합 테스트로 내리고, " +
        "계산 결과만 보면 in-memory fake 를 쓴다. 외부 경계(HTTP·Redis·S3·Temporal)의 대역이라면 " +
        "{{dirs}} 의 공용 함수로 만들어 쓴다.",
    },
  },
  create(context) {
    if (!context.filename.endsWith('.spec.ts')) return {};              // spec 만 본다
    if (allowedDirs.some((dir) => normalized.includes(dir))) return {}; // 화이트리스트는 통과
    return {
      'CallExpression > MemberExpression[object.name="vi"]'(node) {     // vi.* 를 잡아
        if (!MOCK_APIS.has(api)) return;                                // Mock API 만 걸러낸다
        context.report({ node, messageId: 'forbidden', data: { api, dirs } });
      },
    };
  },
};

as never 없이 진짜 객체로 갈아 끼우기

// src/database/base.repository.ts
export abstract class BaseRepository<Entity extends ObjectLiteral> {
  protected constructor(protected readonly repository: Repository<Entity>) {}
  protected withManager(manager?: EntityManager): Repository<Entity> { … }
  private withUpdateDate(partialEntity: QueryDeepPartialEntity<Entity>) { … }
  // …
}

① 컨트롤러에서 UseCase 분리하기

// Before — 한 클래스가 세 기능을 다 갖는다.
export class InternalBrandsService {
  constructor(
    brandRepository, brandProductRepository, userLinkRepository, settlementRepository,
    categoryRepository, feeResolverService, platformFeeService,
  ) {}
  public async listBrands(…)    // 목록
  public async getDetail(…)     // 상세
  public async updateDetail(…)  // 수정
}
// After — 기능마다 클래스 하나. 자기가 쓰는 것만 받는다.
export class ListInternalBrandsUseCase {      // 브랜드 목록 UseCase
  constructor(brandRepository, brandProductRepository, userLinkRepository,
              orderItemRepository, settlementRepository, categoryRepository, feeResolverService) {}
  public async execute(query: InternalBrandListQueryDto) { … }
}
export class GetInternalBrandDetailUseCase {  // 브랜드 상세 UseCase
  constructor(brandRepository, brandProductRepository, userLinkRepository,
              orderItemRepository, settlementRepository, feeResolverService) {}
  public async execute(brandCode: string) { … }
}
export class UpdateInternalBrandUseCase {     // 브랜드 수정 UseCase
  constructor(brandRepository, platformFeeService) {}
  public async execute(brandCode: string, payload: InternalBrandUpdateRequestDto) { … }
}

② 쿼리 조건을 리포지토리 안으로 넣기

// Before — 조건이 호출부에 있다.
const deals = await this.userLinkRepository.findBy({ userLinkCode: In(userDealCodes) });
const brand = await this.brandRepository.findOne({
  where: { brandCode: context.brandCode, deleteDate: IsNull() },
  select: { brandName: true, siteUrl: true },
});

// After — 조건이 리포지토리 안으로 들어가고, 밖에는 이름만 남는다.
const deals = await this.userLinkRepository.findByLinkCodes(userDealCodes);
const brand = await this.brandRepository.findActiveNameAndSite(context.brandCode);

// 스펙이 이미 갖고 있던 옛 Mock은 findBy·existsBy 를 가진 객체다.
// 유스케이스는 이제 findByLinkCodes·existsByExternalOrderCode·persist 를 요구한다.
// 그 사이를 잇는 객체를 스펙 안에서 만들어 넘긴다. 기존 시나리오(호출 순서·mockResolvedValueOnce 체인)는 그대로 둔 채.
const createUseCase = (
  manager: ManagerMock,
  userLinkRepository: { findBy: Mock },
  orderRepository: { existsBy: Mock; create: Mock },
  /* … 지면상 쓰이는 것만 남겼습니다 */
) =>
  new CreateOmsOrderUseCase(
    // …
    { findByLinkCodes: (codes) => userLinkRepository.findBy({ userLinkCode: codes }) } as never,
    // …
    {
      existsByExternalOrderCode: (code) => orderRepository.existsBy({ externalOrderCode: code }),
      create: orderRepository.create,
      persist: (order) => manager.getRepository().save(order),   // ← 리포지토리가 가져간 저장 책임을 manager 로 되돌린다
    } as never,
    // …
  );

③ 트랜잭션을 인자로 넘기지 않기

await this.orderRepository.persist(order, entityManager);
await this.orderGroupRepository.persistMany(orderGroups, entityManager);

// src/database/transaction-runner.ts — 트랜잭션을 열면서 그 manager 를 컨텍스트에 담는다.
public run<T>(work: (manager: EntityManager) => Promise<T>): Promise<T> {
  return this.dataSource.transaction((manager) => runInTransactionContext(manager, () => work(manager)));
}
// src/database/base.repository.ts — 컨텍스트에 트랜잭션이 있으면 그쪽 repository 를 쓴다.
protected get repository(): Repository<Entity> {
  const ambient = currentTransactionManager();
  return ambient ? ambient.getRepository<Entity>(this.rawRepository.target) : this.rawRepository;
}

// 회원 생성·예약 소비·SNS 저장을 한 트랜잭션으로 묶는다. 세 리포지토리 어디에도 manager 를 넘기는 자리가 없다.
await this.transactionRunner.run(async () => {
  await this.userRepository.persist(entity);
  await this.pendingCreatorRepository.persist(reservedCreator);
  await this.userSnsRepository.saveInstagram(userCode, instagramUrl);
});

④ 리포지토리를 인터페이스로 분리하기

// libs/domain/brand/brand.repository.ts — 포트. TypeORM에 대한 의존성이 전혀 없다.
export abstract class BrandRepository {
  abstract findOneByCode(brandCode: string): Promise<BrandEntity | null>;
  abstract findActiveNameAndSite(brandCode: string): Promise<BrandEntity | null>;
  abstract persist(brand: BrandEntity): Promise<BrandEntity>;
  // …
}

// database/repositories/brand.repository.ts — TypeORM 어댑터 (운영 환경)
@Injectable()
export class BrandTypeOrmRepository extends BaseRepository<BrandEntity> implements BrandRepository {
  public findActiveNameAndSite(brandCode: string): Promise<BrandEntity | null> {
    return this.repository.findOne({
      where: { brandCode, deleteDate: IsNull() },
      select: { brandName: true, siteUrl: true },
    });
  }
  // …
}

// test/unit/support/brand-in-memory.repository.ts — 인메모리 어댑터 (유닛 테스트 환경)
export class BrandInMemoryRepository extends BrandRepository {
  private readonly brands: BrandEntity[] = [];
  seed(...brands: BrandEntity[]): this {
    this.brands.push(...brands);
    return this;
  }
  /** 저장된 상태를 그대로 확인한다. "무엇이 저장되었는가"를 단언할 때 쓴다. */
  get saved(): readonly BrandEntity[] {
    return this.brands;
  }
  async save(brand: BrandEntity): Promise<BrandEntity> { … }
  /** 이 스펙에서는 브랜드 이름과 사이트를 다루지 않으므로 호출 시 예외를 던진다. */
  findActiveNameAndSite(): Promise<BrandEntity | null> {
    return notUsed('findActiveNameAndSite');
  }
}

/** 테스트에 필요한 최소 필드만 전달받아 실물 엔티티를 생성한다. 전달받지 않은 항목은 기본값으로 채워진다. */
export function aBrandEntity(overrides: Partial<BrandEntity> & Pick<BrandEntity, 'brandCode' | 'brandName'>): BrandEntity {
  return Object.assign(new BrandEntity(), overrides);
}

function notUsed(method: string): never {
  throw new Error(`BrandInMemoryRepository.${method}: 이 테스트에서 쓰지 않는 메서드입니다.`);
}

1. 인메모리로 충분한 경우: DB 없이도 로직 검증이 끝나는 규칙이라면 인메모리 어댑터에 해당 구현을 추가해 단위 테스트로 유지합니다.

2. DB 동작이 핵심인 경우: 저장이나 조회 결과가 실제 DB 특성에 의존한다면 단위 테스트의 범위를 벗어난 것이므로 통합 테스트로 넘깁니다.

타입 시스템이 허용한 침묵

abstract class OrderItemFeeRepository {
  abstract findByIds(ids: number[], includeDeleted?: boolean): Promise<Fee[]>;
}
// 인메모리 구현은 그대로 둡니다. 두 번째 인자를 아예 안 받습니다.
class OrderItemFeeInMemoryRepository extends OrderItemFeeRepository {
  override async findByIds(ids: number[]): Promise<Fee[]> {
    return this.fees.filter((fee) => ids.includes(fee.id));
  }
}

타입 시스템으로 컴파일 타임에 감지하기

/** 양방향 대입 가능성. 한쪽으로만 대입되는 관계는 false. */
type Exact<A, B> = [A] extends [B] ? ([B] extends [A] ? true : false) : false;
/** 포트의 멤버를 훑어 파라미터·반환 타입이 어긋난 멤버의 이름만 모은다. 다 맞으면 never. */
type DriftedMembers<Impl extends Port, Port> = { /* … */ }[keyof Port];
/** 어긋난 게 없으면 true, 있으면 그 이름이 박힐 튜플이 된다. */
type NoSignatureDrift<Impl extends Port, Port> = [DriftedMembers<Impl, Port>] extends [never]
  ? true
  : ['포트와 시그니처가 어긋난 멤버', DriftedMembers<Impl, Port>];

const _noSignatureDrift: NoSignatureDrift<OrderItemFeeInMemoryRepository, OrderItemFeeRepository> = true;
// error TS2322: Type 'boolean' is not assignable to type
//               '["포트와 시그니처가 어긋난 멤버", "findByIds"]'.

Mock 빈자리 채우기

@Expose 누락 시 excludeExtraneousValues 설정으로 인해 필드가 유실되는 현상이 발생합니다. 이는 TypeScript 타입 체커를 통과하며 API 응답 역시 200 OK로 반환되므로 쉽게 감지되지 않습니다. 최근 3개월간 동일 패턴의 이슈가 5회 발생했고, 매번 회귀 테스트가 추가되는 상황이었습니다.

2,199개에서 4개로 줄어든 Mock

남은 것은 어기면 에러가 나는 규칙뿐

마치며