refactor: 类型安全与接口清理 (#311)

* refactor: 分解 IEngineBridge 为单一职责接口 - 新增 ITextureService, IDynamicAtlasService, ICoordinateService, IRenderConfigService - 移除 EngineBridgeToken，改用具体服务 Token - 更新 camera, ui, particle 等模块使用新接口 - 优化装饰器类型安全，使用 Symbol-based metadata 访问模式 * refactor: 删除 plugin-types 包，统一 createServiceToken 实现 - 移动 IEditorModuleBase 接口到 engine-core - 移除 engine-core 和 editor-core 对 plugin-types 的依赖 - 删除冗余的 plugin-types 包 - 统一使用 core 中基于 Symbol.for() 的 createServiceToken * refactor: 统一 IPlugin 接口，移除 deprecated 别名 - 移除 engine-core、editor-core、runtime-core 中的 IPlugin 别名 - 模块插件统一使用 IRuntimePlugin（运行时）或 IEditorPlugin（编辑器） - 保留 core 包中的 IPlugin 作为 ECS 核心插件接口（不同概念） - 更新所有消费方使用正确的类型 * refactor: 重命名 editor-core ComponentRegistry 为 EditorComponentRegistry - 消除与 core 包 ComponentRegistry（ECS 位掩码管理）的命名歧义 - editor-core 的 EditorComponentRegistry 专用于编辑器组件元数据 - 更新所有编辑器包使用新名称
2025-12-19 17:48:18 +08:00
parent ecdb8f2021
commit e24c850568
51 changed files with 492 additions and 623 deletions
--- a/packages/editor-app/src/App.tsx
+++ b/packages/editor-app/src/App.tsx
@@ -15,7 +15,7 @@ import {
    UIRegistry,
    MessageHub,
    EntityStoreService,
-    ComponentRegistry,
+    EditorComponentRegistry,
    LocaleService,
    LogService,
    SettingsRegistry,
@@ -394,7 +394,7 @@ function App() {
                        setStatus(t('header.status.remoteConnected'));
                    } else {
                        if (projectLoaded) {
-                            const componentRegistry = Core.services.resolve(ComponentRegistry);
+                            const componentRegistry = Core.services.resolve(EditorComponentRegistry);
                            const componentCount = componentRegistry?.getAllComponents().length || 0;
                            setStatus(t('header.status.projectOpened') + (componentCount > 0 ? ` (${componentCount} components registered)` : ''));
                        } else {
--- a/packages/editor-app/src/app/managers/ServiceRegistry.ts
+++ b/packages/editor-app/src/app/managers/ServiceRegistry.ts
@@ -7,7 +7,7 @@ import {
    IMessageHub,
    SerializerRegistry,
    EntityStoreService,
-    ComponentRegistry,
+    EditorComponentRegistry,
    ProjectService,
    ComponentDiscoveryService,
    PropertyMetadataService,
@@ -90,7 +90,7 @@ export interface EditorServices {
    messageHub: MessageHub;
    serializerRegistry: SerializerRegistry;
    entityStore: EntityStoreService;
-    componentRegistry: ComponentRegistry;
+    componentRegistry: EditorComponentRegistry;
    projectService: ProjectService;
    componentDiscovery: ComponentDiscoveryService;
    propertyMetadata: PropertyMetadataService;
@@ -121,7 +121,7 @@ export class ServiceRegistry {
        const messageHub = new MessageHub();
        const serializerRegistry = new SerializerRegistry();
        const entityStore = new EntityStoreService(messageHub);
-        const componentRegistry = new ComponentRegistry();
+        const componentRegistry = new EditorComponentRegistry();

        // 注册标准组件到编辑器和核心注册表
        // Register to both editor registry (for UI) and core registry (for serialization)
@@ -168,7 +168,7 @@ export class ServiceRegistry {
        Core.services.registerInstance(IMessageHub, messageHub);  // Symbol 注册用于跨包插件访问
        Core.services.registerInstance(SerializerRegistry, serializerRegistry);
        Core.services.registerInstance(EntityStoreService, entityStore);
-        Core.services.registerInstance(ComponentRegistry, componentRegistry);
+        Core.services.registerInstance(EditorComponentRegistry, componentRegistry);
        Core.services.registerInstance(ProjectService, projectService);
        Core.services.registerInstance(ComponentDiscoveryService, componentDiscovery);
        Core.services.registerInstance(PropertyMetadataService, propertyMetadata);
--- a/packages/editor-app/src/application/commands/component/AddComponentCommand.ts
+++ b/packages/editor-app/src/application/commands/component/AddComponentCommand.ts
@@ -1,5 +1,5 @@
 import { Entity, Component, getComponentDependencies, getComponentTypeName } from '@esengine/ecs-framework';
-import { MessageHub, ComponentRegistry } from '@esengine/editor-core';
+import { MessageHub, EditorComponentRegistry } from '@esengine/editor-core';
 import { Core } from '@esengine/ecs-framework';
 import { BaseCommand } from '../BaseCommand';

@@ -55,7 +55,7 @@ export class AddComponentCommand extends BaseCommand {
            return;
        }

-        const componentRegistry = Core.services.tryResolve(ComponentRegistry) as ComponentRegistry | null;
+        const componentRegistry = Core.services.tryResolve(EditorComponentRegistry) as EditorComponentRegistry | null;
        if (!componentRegistry) {
            return;
        }
--- a/packages/editor-app/src/components/inspector/EntityInspectorPanel.tsx
+++ b/packages/editor-app/src/components/inspector/EntityInspectorPanel.tsx
@@ -32,7 +32,7 @@ import {
 import {
    MessageHub,
    CommandManager,
-    ComponentRegistry,
+    EditorComponentRegistry,
    ComponentActionRegistry,
    ComponentInspectorRegistry,
    PrefabService,
@@ -147,7 +147,7 @@ export const EntityInspectorPanel: React.FC<EntityInspectorPanelProps> = ({

    // ==================== 服务 | Services ====================

-    const componentRegistry = Core.services.resolve(ComponentRegistry);
+    const componentRegistry = Core.services.resolve(EditorComponentRegistry);
    const componentActionRegistry = Core.services.resolve(ComponentActionRegistry);
    const componentInspectorRegistry = Core.services.resolve(ComponentInspectorRegistry);
    const prefabService = Core.services.tryResolve(PrefabService) as PrefabService | null;
--- a/packages/editor-app/src/components/inspectors/views/EntityInspector.tsx
+++ b/packages/editor-app/src/components/inspectors/views/EntityInspector.tsx
@@ -1,7 +1,7 @@
 import { useState, useRef, useEffect, useMemo, useCallback } from 'react';
 import { Settings, ChevronDown, ChevronRight, X, Plus, Box, Search, Lock, Unlock } from 'lucide-react';
 import { Entity, Component, Core, getComponentDependencies, getComponentTypeName, getComponentInstanceTypeName, isComponentInstanceHiddenInInspector, PrefabInstanceComponent } from '@esengine/ecs-framework';
-import { MessageHub, CommandManager, ComponentRegistry, ComponentActionRegistry, ComponentInspectorRegistry, PrefabService } from '@esengine/editor-core';
+import { MessageHub, CommandManager, EditorComponentRegistry, ComponentActionRegistry, ComponentInspectorRegistry, PrefabService } from '@esengine/editor-core';
 import { PropertyInspector } from '../../PropertyInspector';
 import { NotificationService } from '../../../services/NotificationService';
 import { RemoveComponentCommand, UpdateComponentCommand, AddComponentCommand } from '../../../application/commands/component';
@@ -11,7 +11,7 @@ import * as LucideIcons from 'lucide-react';

 type CategoryFilter = 'all' | 'general' | 'transform' | 'rendering' | 'physics' | 'audio' | 'other';

-// 从 ComponentRegistry category 到 CategoryFilter 的映射
+// 从 EditorComponentRegistry category 到 CategoryFilter 的映射
 const categoryKeyMap: Record<string, CategoryFilter> = {
    'components.category.core': 'general',
    'components.category.rendering': 'rendering',
@@ -84,7 +84,7 @@ export function EntityInspector({
    const addButtonRef = useRef<HTMLButtonElement>(null);
    const searchInputRef = useRef<HTMLInputElement>(null);

-    const componentRegistry = Core.services.resolve(ComponentRegistry);
+    const componentRegistry = Core.services.resolve(EditorComponentRegistry);
    const componentActionRegistry = Core.services.resolve(ComponentActionRegistry);
    const componentInspectorRegistry = Core.services.resolve(ComponentInspectorRegistry);
    const prefabService = Core.services.tryResolve(PrefabService) as PrefabService | null;
--- a/packages/editor-app/src/plugins/builtin/AssetMetaPlugin.ts
+++ b/packages/editor-app/src/plugins/builtin/AssetMetaPlugin.ts
@@ -8,7 +8,7 @@

 import type { ServiceContainer } from '@esengine/ecs-framework';
 import { createLogger } from '@esengine/ecs-framework';
-import type { IPlugin, IEditorModuleLoader, ModuleManifest } from '@esengine/editor-core';
+import type { IEditorPlugin, IEditorModuleLoader, ModuleManifest } from '@esengine/editor-core';
 import { AssetRegistryService } from '@esengine/editor-core';

 const logger = createLogger('AssetMetaPlugin');
@@ -65,7 +65,7 @@ const manifest: ModuleManifest = {
    exports: {}
 };

-export const AssetMetaPlugin: IPlugin = {
+export const AssetMetaPlugin: IEditorPlugin = {
    manifest,
    editorModule: new AssetMetaEditorModule()
 };
--- a/packages/editor-app/src/plugins/builtin/EditorAppearancePlugin.tsx
+++ b/packages/editor-app/src/plugins/builtin/EditorAppearancePlugin.tsx
@@ -5,7 +5,7 @@

 import type { ServiceContainer } from '@esengine/ecs-framework';
 import { createLogger } from '@esengine/ecs-framework';
-import type { IPlugin, IEditorModuleLoader, ModuleManifest } from '@esengine/editor-core';
+import type { IEditorPlugin, IEditorModuleLoader, ModuleManifest } from '@esengine/editor-core';
 import { SettingsRegistry } from '@esengine/editor-core';
 import { SettingsService } from '../../services/SettingsService';

@@ -146,7 +146,7 @@ const manifest: ModuleManifest = {
    exports: {}
 };

-export const EditorAppearancePlugin: IPlugin = {
+export const EditorAppearancePlugin: IEditorPlugin = {
    manifest,
    editorModule: new EditorAppearanceEditorModule()
 };
--- a/packages/editor-app/src/plugins/builtin/GizmoPlugin.ts
+++ b/packages/editor-app/src/plugins/builtin/GizmoPlugin.ts
@@ -4,7 +4,7 @@
 */

 import type { ServiceContainer } from '@esengine/ecs-framework';
-import type { IPlugin, IEditorModuleLoader, ModuleManifest, GizmoProviderRegistration } from '@esengine/editor-core';
+import type { IEditorPlugin, IEditorModuleLoader, ModuleManifest, GizmoProviderRegistration } from '@esengine/editor-core';
 import { registerSpriteGizmo } from '../../gizmos';

 /**
@@ -42,7 +42,7 @@ const manifest: ModuleManifest = {
    }
 };

-export const GizmoPlugin: IPlugin = {
+export const GizmoPlugin: IEditorPlugin = {
    manifest,
    editorModule: new GizmoEditorModule()
 };
--- a/packages/editor-app/src/plugins/builtin/PluginConfigPlugin.tsx
+++ b/packages/editor-app/src/plugins/builtin/PluginConfigPlugin.tsx
@@ -5,7 +5,7 @@

 import type { ServiceContainer } from '@esengine/ecs-framework';
 import { createLogger } from '@esengine/ecs-framework';
-import type { IPlugin, IEditorModuleLoader, ModuleManifest } from '@esengine/editor-core';
+import type { IEditorPlugin, IEditorModuleLoader, ModuleManifest } from '@esengine/editor-core';
 import { SettingsRegistry } from '@esengine/editor-core';

 const logger = createLogger('PluginConfigPlugin');
@@ -69,7 +69,7 @@ const manifest: ModuleManifest = {
    exports: {}
 };

-export const PluginConfigPlugin: IPlugin = {
+export const PluginConfigPlugin: IEditorPlugin = {
    manifest,
    editorModule: new PluginConfigEditorModule()
 };
--- a/packages/editor-app/src/plugins/builtin/ProfilerPlugin.tsx
+++ b/packages/editor-app/src/plugins/builtin/ProfilerPlugin.tsx
@@ -6,7 +6,7 @@
 import type { ServiceContainer } from '@esengine/ecs-framework';
 import { Core } from '@esengine/ecs-framework';
 import type {
-    IPlugin,
+    IEditorPlugin,
    IEditorModuleLoader,
    ModuleManifest,
    MenuItemDescriptor
@@ -140,7 +140,7 @@ const manifest: ModuleManifest = {
    exports: {}
 };

-export const ProfilerPlugin: IPlugin = {
+export const ProfilerPlugin: IEditorPlugin = {
    manifest,
    editorModule: new ProfilerEditorModule()
 };
--- a/packages/editor-app/src/plugins/builtin/ProjectSettingsPlugin.tsx
+++ b/packages/editor-app/src/plugins/builtin/ProjectSettingsPlugin.tsx
@@ -8,7 +8,7 @@

 import type { ServiceContainer } from '@esengine/ecs-framework';
 import { createLogger, Core } from '@esengine/ecs-framework';
-import type { IPlugin, IEditorModuleLoader, ModuleManifest } from '@esengine/editor-core';
+import type { IEditorPlugin, IEditorModuleLoader, ModuleManifest } from '@esengine/editor-core';
 import { SettingsRegistry, ProjectService, moduleRegistry } from '@esengine/editor-core';
 import EngineService from '../../services/EngineService';

@@ -306,7 +306,7 @@ const manifest: ModuleManifest = {
    exports: {}
 };

-export const ProjectSettingsPlugin: IPlugin = {
+export const ProjectSettingsPlugin: IEditorPlugin = {
    manifest,
    editorModule: new ProjectSettingsEditorModule()
 };
--- a/packages/editor-app/src/plugins/builtin/SceneInspectorPlugin.ts
+++ b/packages/editor-app/src/plugins/builtin/SceneInspectorPlugin.ts
@@ -6,7 +6,7 @@
 import { Core, Entity } from '@esengine/ecs-framework';
 import type { ServiceContainer } from '@esengine/ecs-framework';
 import type {
-    IPlugin,
+    IEditorPlugin,
    IEditorModuleLoader,
    ModuleManifest,
    PanelDescriptor,
@@ -191,7 +191,7 @@ const manifest: ModuleManifest = {
    }
 };

-export const SceneInspectorPlugin: IPlugin = {
+export const SceneInspectorPlugin: IEditorPlugin = {
    manifest,
    editorModule: new SceneInspectorEditorModule()
 };
--- a/packages/editor-app/src/services/EngineService.ts
+++ b/packages/editor-app/src/services/EngineService.ts
@@ -8,7 +8,15 @@

 import { GizmoRegistry, EntityStoreService, MessageHub, SceneManagerService, ProjectService, PluginManager, IPluginManager, AssetRegistryService, GizmoInteractionService, GizmoInteractionServiceToken, type SystemContext } from '@esengine/editor-core';
 import { Core, Scene, Entity, SceneSerializer, ProfilerSDK, createLogger, PluginServiceRegistry } from '@esengine/ecs-framework';
-import { CameraConfig, EngineBridgeToken, RenderSystemToken, EngineIntegrationToken } from '@esengine/ecs-engine-bindgen';
+import {
+    CameraConfig,
+    RenderSystemToken,
+    EngineIntegrationToken,
+    TextureServiceToken,
+    DynamicAtlasServiceToken,
+    CoordinateServiceToken,
+    RenderConfigServiceToken
+} from '@esengine/ecs-engine-bindgen';
 import { TransformComponent, TransformTypeToken, CanvasElementToken } from '@esengine/engine-core';
 import { SpriteComponent, SpriteAnimatorComponent, SpriteAnimatorSystemToken } from '@esengine/sprite';
 import { ParticleSystemComponent } from '@esengine/particle';
@@ -252,7 +260,11 @@ export class EngineService {
        // 创建服务注册表并注册核心服务
        // Create service registry and register core services
        const services = new PluginServiceRegistry();
-        services.register(EngineBridgeToken, this._runtime.bridge);
+        // 使用单一职责接口注册 EngineBridge | Register EngineBridge with single-responsibility interfaces
+        services.register(TextureServiceToken, this._runtime.bridge);
+        services.register(DynamicAtlasServiceToken, this._runtime.bridge);
+        services.register(CoordinateServiceToken, this._runtime.bridge);
+        services.register(RenderConfigServiceToken, this._runtime.bridge);
        services.register(RenderSystemToken, this._runtime.renderSystem);
        services.register(AssetManagerToken, this._assetManager);
        services.register(EngineIntegrationToken, this._engineIntegration);
--- a/packages/editor-app/src/services/PluginLoader.ts
+++ b/packages/editor-app/src/services/PluginLoader.ts
@@ -4,7 +4,7 @@
 */

 import { PluginManager, LocaleService, MessageHub, EditorConfig, getPluginsPath } from '@esengine/editor-core';
-import type { IPlugin, ModuleManifest } from '@esengine/editor-core';
+import type { IRuntimePlugin, ModuleManifest } from '@esengine/editor-core';
 import { Core } from '@esengine/ecs-framework';
 import { TauriAPI } from '../api/tauri';
 import { PluginSDKRegistry } from './PluginSDKRegistry';
@@ -164,7 +164,7 @@ export class PluginLoader {
        code: string,
        pluginName: string,
        _pluginDirName: string
-    ): Promise<IPlugin | null> {
+    ): Promise<IRuntimePlugin | null> {
        const pluginKey = this.sanitizePluginKey(pluginName);

        const pluginsContainer = (window as any)[PLUGINS_GLOBAL_NAME] as Record<string, any>;
@@ -267,7 +267,7 @@ export class PluginLoader {
    /**
     * 查找模块中的插件
     */
-    private findPluginLoader(module: any): IPlugin | null {
+    private findPluginLoader(module: any): IRuntimePlugin | null {
        // 优先检查 default 导出
        if (module.default && this.isPluginLoader(module.default)) {
            return module.default;
@@ -287,12 +287,12 @@ export class PluginLoader {
    /**
     * 验证对象是否为有效的插件
     */
-    private isPluginLoader(obj: any): obj is IPlugin {
+    private isPluginLoader(obj: any): obj is IRuntimePlugin {
        if (!obj || typeof obj !== 'object') {
            return false;
        }

-        // 新的 IPlugin 接口检查
+        // IRuntimePlugin 接口检查
        if (obj.manifest && this.isModuleManifest(obj.manifest)) {
            return true;
        }
@@ -315,7 +315,7 @@ export class PluginLoader {
    /**
     * 同步插件语言设置
     */
-    private syncPluginLocale(plugin: IPlugin, pluginName: string): void {
+    private syncPluginLocale(plugin: IRuntimePlugin, pluginName: string): void {
        try {
            const localeService = Core.services.resolve(LocaleService);
            const currentLocale = localeService.getCurrentLocale();