refactor: mock source loading out of core (#4563)

* Refactor mock source loading out of core

* Document mock source loader boundaries

Author: czy88840616

openspec/changes/refactor-functional-dev-source-loader-boundary/design.md

@@ -0,0 +1,56 @@
+## Context
+当前 functional 一体化开发链路是：Vite/Rspack dev plugin -> `@midwayjs/mock.createApp()` -> `initializeGlobalApplicationContext()` -> `findProjectEntryFile()` -> `loadModule()` 直接加载 `src/server` 源码。
+
+在 Node 20 + ESM + TypeScript + decorator 场景下，源码直跑需要处理：
+- `.js` specifier 对应 `.ts` 源文件
+- TypeScript ESM 转译
+- decorator 与 `emitDecoratorMetadata`
+- bare package import 解析
+- dev watch 对临时文件的排除
+
+这些问题仅出现在开发期源码直跑链路，不属于 core 的通用运行时职责。
+
+## Goals / Non-Goals
+- Goals:
+  - 将开发期源码加载兼容逻辑归位到 `@midwayjs/mock`
+  - 保持 Vite 与 Rspack dev 插件共享同一套 source loader
+  - 使 `@midwayjs/core.loadModule()` 回到标准加载器职责
+  - 保持 functional 一体化开发链路在 Node 20 下可用
+- Non-Goals:
+  - 不改变 functional API 用户侧 DSL
+  - 不切换到新的默认 dev runtime（如 `tsx`）
+  - 不把传统 `dist` 驱动开发链路改为源码直跑
+
+## Decisions
+- Decision: dev source loader 归属 `@midwayjs/mock`
+  - 理由：源码直跑是 mock/dev plugin 的开发期行为，不是 core 通用能力。
+
+- Decision: Vite 与 Rspack 通过 `mock.createApp()` 共享同一 source loader
+  - 理由：避免两个 dev 入口维护两套 TS/ESM 兼容逻辑。
+
+- Decision: `@midwayjs/core.loadModule()` 只保留标准 `require/import + safeLoad`
+  - 理由：恢复 core 边界，减少基础层意外回归。
+
+- Decision: 本次先保留当前兼容策略思路，不立即切换到 `tsx`/`ts-node` 作为默认运行时
+  - 理由：历史上完整 TS runtime 在 Midway/Koa 开发链路里存在启动/重建性能成本，本次优先修正边界而非切换 runtime 路线。
+
+## Risks / Trade-offs
+- 风险：从 core 挪出 fallback 逻辑后，mock 内部实现复杂度上升。
+  - Mitigation: 将 source loader 单独封装，避免散落在 `creator.ts`、`vite.ts`、`rspack.ts` 中。
+
+- 风险：Vite/Rspack watcher 与临时产物处理仍可能产生边缘行为。
+  - Mitigation: 在 mock 层补充 watcher 排除与 Node 20 fixture 回归测试。
+
+- 风险：重新归位时可能误伤已有 commonjs/esm 加载路径。
+  - Mitigation: 保留 core/mock 定向构建与测试验证，逐步回退 core 逻辑。
+
+## Migration Plan
+1. 在 `packages/mock` 引入统一 dev source loader。
+2. 让 `mock.createApp()` 在源码入口探测与初始化阶段走 source loader。
+3. 让 Vite/Rspack 插件只负责请求桥接与 reload，不再承载源码兼容细节。
+4. 将 `core.loadModule()` 回退为纯加载器。
+5. 用 Node 20 functional fixture 验证 React/Vue 一体化开发链路。
+
+## Open Questions
+- mock source loader 是否以“显式新函数”方式接入，还是通过 `initializeGlobalApplicationContext()` 的可配置 loader hook 接入更合适。
+- decorator-heavy 业务在 mock source loader 中是否需要继续保留局部 transpile 策略，还是后续单独评估运行时替换方案。

openspec/changes/refactor-functional-dev-source-loader-boundary/proposal.md

@@ -0,0 +1,22 @@
+# Change: Refactor Functional Dev Source Loader Boundary
+
+## Why
+当前 functional 前端一体化开发模式通过 `@midwayjs/mock` 在开发期直接加载 `src/server` 源码。为兼容 Node 20 下的 ESM + TypeScript + decorator 场景，临时将源码 fallback/转译逻辑加入了 `@midwayjs/core` 的 `loadModule()`。
+
+这会把明显属于开发期、且仅在 `mock` 源码直跑链路中需要的逻辑沉入 core 基础加载层，导致职责边界模糊，并增加 core 的维护负担与回归风险。
+
+## What Changes
+- 将 functional 一体化开发期的源码加载逻辑从 `@midwayjs/core` 迁移到 `@midwayjs/mock`。
+- 在 `@midwayjs/mock` 内部引入统一的 dev source loader，供 Vite 与 Rspack 开发插件共享。
+- 将 `@midwayjs/core` 的 `loadModule()` 恢复为标准模块加载能力，不继续承载开发期源码 fallback/转译细节。
+- 为 Node 20 + ESM + TypeScript + decorator + reflect metadata 的 functional 开发链路补充 mock 层回归测试。
+
+## Impact
+- Affected specs: `functional-web-routing`
+- Affected code:
+  - `packages/mock/src/creator.ts`
+  - `packages/mock/src/vite.ts`
+  - `packages/mock/src/rspack.ts`
+  - `packages/mock/src/*`（新增 dev source loader）
+  - `packages/core/src/util/index.ts`
+  - `packages/mock/test/*`

openspec/changes/refactor-functional-dev-source-loader-boundary/specs/functional-web-routing/spec.md

@@ -0,0 +1,39 @@
+## ADDED Requirements
+### Requirement: Development Source Loader Boundary
+系统 SHALL 将 functional 一体化开发期的源码加载兼容逻辑限定在 `@midwayjs/mock` 的开发链路内，而不是放入 `@midwayjs/core` 的通用模块加载器。
+
+#### Scenario: mock 持有开发期源码加载逻辑
+- **WHEN** 用户通过 Vite 或 Rspack 开发插件启动 functional 一体化项目
+- **THEN** 开发期针对 TypeScript/ESM/decorator 的源码加载兼容逻辑由 `@midwayjs/mock` 提供
+- **AND** `@midwayjs/core` 不需要感知 dev-only 的源码 fallback 或临时文件机制
+
+#### Scenario: core loadModule 保持标准加载职责
+- **WHEN** 运行时调用 `@midwayjs/core` 的通用模块加载能力
+- **THEN** 其职责限定为标准 `require/import` 与 `safeLoad` 语义
+- **AND** 不承担 functional 一体化开发期的源码转译或 specifier fallback 逻辑
+
+### Requirement: Shared Mock Dev Loader for Vite and Rspack
+系统 SHALL 让 Vite 与 Rspack 的 functional 开发插件复用同一套 mock source loader，以保证行为一致。
+
+#### Scenario: Vite 与 Rspack 共用 source loader
+- **WHEN** 用户分别通过 Vite 或 Rspack 启动 functional 开发环境
+- **THEN** 两条链路都通过 `@midwayjs/mock` 的统一 source loader 加载 `src/server` 源码
+- **AND** 不为不同 bundler 维护两套独立的 TS/ESM 兼容实现
+
+#### Scenario: 临时产物不触发重复 reload
+- **WHEN** mock source loader 在开发期生成内部临时产物或缓存文件
+- **THEN** Vite/Rspack watcher 不会把这些内部文件视为业务源码变更
+- **AND** 应用不会因内部临时文件产生重复 reload
+
+### Requirement: Functional Dev Runtime Compatibility on Node 20
+系统 SHALL 在 Node 20 下支持 functional 一体化开发链路的源码直跑，包括 ESM、TypeScript、本地相对依赖、decorator 与 metadata。
+
+#### Scenario: Node 20 下加载 configuration 与 functional api 源码
+- **WHEN** 用户在 Node 20 下启动 functional 一体化开发环境
+- **THEN** `src/server/configuration.ts`、`src/server/index.ts` 与 `src/server/api/**/*.ts` 可被成功加载
+- **AND** 本地相对依赖与 bare package import 能保持可解析
+
+#### Scenario: Node 20 下保留 decorator metadata 行为
+- **WHEN** 开发期源码模块包含 Midway 装饰器、属性注入或 `reflect-metadata` 相关语义
+- **THEN** 其运行时行为与标准 TypeScript 编译结果保持兼容
+- **AND** 不因开发期源码加载兼容逻辑导致 metadata 丢失或装饰器语义异常

openspec/changes/refactor-functional-dev-source-loader-boundary/tasks.md

@@ -0,0 +1,17 @@
+## 1. Design
+- [x] 1.1 明确 `@midwayjs/core` 与 `@midwayjs/mock` 在开发期源码加载中的职责边界
+- [x] 1.2 设计 `mock` 内部共享 dev source loader，覆盖 Vite 与 Rspack 两条开发链路
+
+## 2. Implementation
+- [x] 2.1 在 `packages/mock` 中实现 dev source loader，并封装 ESM + TypeScript + decorator 开发期兼容逻辑
+- [x] 2.2 调整 `packages/mock/src/creator.ts`，在源码入口探测与应用初始化阶段使用 mock source loader
+- [x] 2.3 调整 `packages/mock/src/vite.ts` 与 `packages/mock/src/rspack.ts` 以复用统一 source loader，并维持 watcher 行为稳定
+- [x] 2.4 将 `packages/core/src/util/index.ts` 回退为标准模块加载实现，移除 dev-only fallback/临时文件逻辑
+
+## 3. Validation
+- [x] 3.1 为 `@midwayjs/mock` 新增 Node 20 + ESM + TypeScript + decorator fixture 回归测试
+- [x] 3.2 验证 Vite functional dev 场景在 Node 20 下可启动且不会因临时文件造成重复 reload
+- [x] 3.3 运行 `pnpm -C packages/core build`
+- [x] 3.4 运行 `pnpm -C packages/mock build`
+- [x] 3.5 运行相关 mock/core 定向测试
+- [x] 3.6 运行 `openspec validate refactor-functional-dev-source-loader-boundary --strict --no-interactive`

packages/core/src/common/fileDetector.ts

@@ -6,7 +6,11 @@ import {
 import { Types } from '../util/types';
 import { run } from '@midwayjs/glob';
 import { MidwayDuplicateClassNameError } from '../error';
-import { DEFAULT_PATTERN, IGNORE_PATTERN } from '../constants';
+import {
+  DEFAULT_PATTERN,
+  IGNORE_PATTERN,
+  MODULE_LOADER_KEY,
+} from '../constants';
 import { loadModule } from '../util';
 import { DecoratorManager } from '../decorator';
 import { debuglog } from 'util';
@@ -114,6 +118,13 @@ export class CommonJSFileDetector extends AbstractFileDetector<{
 
   async loadAsync(container: IMidwayGlobalContainer, namespace: string) {
     this.options = this.options || {};
+    // When mock injects a dev-only source loader, detector scans must reuse it
+    // instead of falling back to the generic core loader.
+    const moduleLoader: typeof loadModule = container.hasObject(
+      MODULE_LOADER_KEY
+    )
+      ? container.getObject(MODULE_LOADER_KEY)
+      : loadModule;
     const loadDirs = [].concat(
       this.options.loadDir ?? container.get('baseDir')
     );
@@ -171,7 +182,7 @@ export class CommonJSFileDetector extends AbstractFileDetector<{
               ? `${Date.now()}_${Math.random()}`
               : undefined;
         }
-        const exports = await loadModule(file, {
+        const exports = await moduleLoader(file, {
           loadMode: 'esm',
           importQuery: currentImportQuery,
         });

packages/core/src/constants.ts

@@ -18,6 +18,7 @@ export const REQUEST_CTX_UNIQUE_KEY = '_midway_ctx_unique_key';
 
 export const ASYNC_CONTEXT_KEY = Symbol('ASYNC_CONTEXT_KEY');
 export const ASYNC_CONTEXT_MANAGER_KEY = 'MIDWAY_ASYNC_CONTEXT_MANAGER_KEY';
+export const MODULE_LOADER_KEY = 'MIDWAY_MODULE_LOADER_KEY';
 
 export const DEFAULT_PATTERN = [
   '**/**.ts',

packages/core/src/interface.ts

@@ -1100,6 +1100,20 @@ export type IMidwayApplication<
 
 export type ModuleLoadType = 'commonjs' | 'esm';
 
+export interface ModuleLoadOptions {
+  enableCache?: boolean;
+  loadMode?: ModuleLoadType;
+  safeLoad?: boolean;
+  warnOnLoadError?: boolean;
+  extraModuleRoot?: string[];
+  importQuery?: string;
+}
+
+export type ModuleLoader = (
+  p: string,
+  options?: ModuleLoadOptions
+) => Promise<any>;
+
 export interface IMidwayBootstrapOptions {
   baseDir?: string;
   appDir?: string;
@@ -1113,6 +1127,9 @@ export interface IMidwayBootstrapOptions {
     | Record<string, any>;
   asyncContextManager?: AsyncContextManager;
   loggerFactory?: LoggerFactory<any, any>;
+  // Internal hook for callers like @midwayjs/mock that need a custom module
+  // loader during bootstrap. Core should keep loadModule() itself generic.
+  moduleLoader?: ModuleLoader;
 }
 
 export interface IConfigurationOptions {

packages/core/src/setup.ts

@@ -25,6 +25,7 @@ import { MidwayTraceService } from './service/traceService';
 import { ComponentConfigurationLoader } from './context/componentLoader';
 import { findProjectEntryFile, findProjectEntryFileSync } from './util';
 import { AsyncLocalStorageContextManager } from './common/asyncContextManager';
+import { MODULE_LOADER_KEY } from './constants';
 import {
   MidwayInitializerPerformanceManager,
   MidwayPerformanceManager,
@@ -199,6 +200,14 @@ export async function prepareGlobalApplicationContextAsync(
   // register baseDir and appDir
   applicationContext.registerObject('baseDir', baseDir);
   applicationContext.registerObject('appDir', appDir);
+  if (globalOptions.moduleLoader) {
+    // Keep the custom loader on the container so later module discovery
+    // phases (for example file detectors) can follow the same load strategy.
+    applicationContext.registerObject(
+      MODULE_LOADER_KEY,
+      globalOptions.moduleLoader
+    );
+  }
 
   if (!globalOptions.asyncContextManager) {
     globalOptions.asyncContextManager = new AsyncLocalStorageContextManager();
@@ -224,7 +233,12 @@ export async function prepareGlobalApplicationContextAsync(
   // set entry file
   globalOptions.imports = [
     ...(globalOptions.imports ?? []),
-    await findProjectEntryFile(appDir, baseDir, globalOptions.moduleLoadType),
+    await findProjectEntryFile(
+      appDir,
+      baseDir,
+      globalOptions.moduleLoadType,
+      globalOptions.moduleLoader
+    ),
   ];
 
   MidwayInitializerPerformanceManager.markEnd(
@@ -366,6 +380,14 @@ export function prepareGlobalApplicationContext(
   // register baseDir and appDir
   applicationContext.registerObject('baseDir', baseDir);
   applicationContext.registerObject('appDir', appDir);
+  if (globalOptions.moduleLoader) {
+    // Keep the custom loader on the container so later module discovery
+    // phases (for example file detectors) can follow the same load strategy.
+    applicationContext.registerObject(
+      MODULE_LOADER_KEY,
+      globalOptions.moduleLoader
+    );
+  }
 
   if (!globalOptions.asyncContextManager) {
     globalOptions.asyncContextManager = new AsyncLocalStorageContextManager();