@hile/core 1.0.21 → 1.1.0

package/README.md

@@ -1,6 +1,6 @@
 # @hile/core
 
-轻量级异步服务容器，提供单例管理、并发请求合并与生命周期销毁能力。纯 TypeScript 实现，零运行时依赖。
+轻量级异步服务容器，提供单例管理、并发请求合并与生命周期销毁能力。纯 TypeScript 实现，零运行时依赖。默认容器使用进程级单例 `globalThis.HILE_GLOBAL_CONTAINER`。
 
 ## 安装
 
@@ -13,7 +13,7 @@ pnpm add @hile/core
 ```typescript
 import { defineService, loadService } from '@hile/core'
 
-const greeterService = defineService(async (shutdown) => {
+const greeterService = defineService('greeter', async (shutdown) => {
   return {
     hello(name: string) {
       return `Hello, ${name}!`
@@ -27,23 +27,27 @@ greeter.hello('World') // Hello, World!
 
 ## 核心概念
 
-### 1) 定义服务
+### 1) 服务 key
 
-通过 `defineService` 注册服务。服务函数接收 `shutdown` 注册器，用于登记资源清理回调。
+每个服务必须指定 **`ServiceKey`（`string` 或 `symbol`）**，用于在容器内唯一标识该服务槽位。同一 key 多次 `defineService`/`register` 指向同一单例；不同 key 彼此独立。集成包常用 `Symbol.for('@scope/package')`，应用内可用 `'http'`、`'database'` 等字符串。
+
+### 2) 定义服务
+
+通过 `defineService(key, fn)` 注册服务。服务函数接收 `shutdown` 注册器，用于登记资源清理回调。
 
 ```typescript
 import { defineService } from '@hile/core'
 
-export const databaseService = defineService(async (shutdown) => {
+export const databaseService = defineService('database', async (shutdown) => {
   const pool = await createPool('postgres://localhost:5432/app')
   shutdown(() => pool.end())
   return pool
 })
 ```
 
-### 2) 加载服务
+### 3) 加载服务
 
-通过 `loadService` 获取服务实例。容器保证同一服务函数只执行一次。
+通过 `loadService` 获取服务实例。容器保证同一服务 key 只执行一次工厂函数。
 
 ```typescript
 import { loadService } from '@hile/core'
@@ -53,7 +57,7 @@ const db = await loadService(databaseService)
 const users = await db.query('SELECT * FROM users')
 ```
 
-### 3) 并发请求合并
+### 4) 并发请求合并
 
 并发加载同一服务时，初始化只执行一次，调用方共享结果。
 
@@ -67,7 +71,7 @@ const [r1, r2, r3] = await Promise.all([
 // r1 === r2 === r3
 ```
 
-### 4) 服务间依赖
+### 5) 服务间依赖
 
 服务内部可通过 `loadService` 继续加载依赖服务。
 
@@ -76,7 +80,7 @@ import { defineService, loadService } from '@hile/core'
 import { databaseService } from './database'
 import { cacheService } from './cache'
 
-export const userService = defineService(async (shutdown) => {
+export const userService = defineService('user', async (shutdown) => {
   const db = await loadService(databaseService)
   const cache = await loadService(cacheService)
 
@@ -92,12 +96,12 @@ export const userService = defineService(async (shutdown) => {
 })
 ```
 
-### 5) 资源销毁（Shutdown）
+### 6) 资源销毁（Shutdown）
 
 当服务初始化失败或手动执行全局关闭时，容器会按规则执行已注册的清理回调。`container.shutdown()` 会循环处理队列直到清空，并让出一次事件循环（`setImmediate`），确保在 shutdown 进行中才完成启动并注册的 teardown 也会被执行。
 
 ```typescript
-export const connectionService = defineService(async (shutdown) => {
+export const connectionService = defineService('connection', async (shutdown) => {
   const primary = await connectPrimary()
   shutdown(() => primary.disconnect())
 
@@ -120,7 +124,7 @@ export const connectionService = defineService(async (shutdown) => {
 
 > 建议始终使用 `async` 服务函数，确保异常路径可正确触发销毁机制。
 
-### 6) 生命周期、超时与可观测事件
+### 7) 生命周期、超时与可观测事件
 
 容器支持显式生命周期阶段：`init -> ready -> stopping -> stopped`。
 
@@ -135,12 +139,14 @@ const container = new Container({
 })
 ```
 
-订阅事件：
+订阅事件（服务相关事件携带 `key`）：
 
 ```typescript
+import { formatServiceKey } from '@hile/core'
+
 const off = container.on((event) => {
   if (event.type === 'service:ready') {
-    console.log(`service#${event.id} ready in ${event.durationMs}ms`)
+    console.log(`service(${formatServiceKey(event.key)}) ready in ${event.durationMs}ms`)
   }
 })
 
@@ -148,21 +154,21 @@ const off = container.on((event) => {
 off()
 ```
 
-### 7) 依赖图与启动顺序
+### 8) 依赖图与启动顺序
 
 容器会在 `resolve` 过程中自动记录依赖关系，并检测循环依赖。
 
 ```typescript
 const graph = container.getDependencyGraph()
-// graph.nodes: number[]
-// graph.edges: Array<{ from: number; to: number }>
+// graph.nodes: ServiceKey[]
+// graph.edges: Array<{ from: ServiceKey; to: ServiceKey }>
 
 const startupOrder = container.getStartupOrder()
 ```
 
 若出现循环依赖，会抛出 `circular dependency detected` 错误。
 
-### 8) 手动销毁（Graceful Shutdown）
+### 9) 手动销毁（Graceful Shutdown）
 
 ```typescript
 import container from '@hile/core'
@@ -175,15 +181,15 @@ process.on('SIGTERM', async () => {
 
 保证：每个在 defineService 中通过 `shutdown(fn)` 注册的回调都会在 `shutdown()` 时被执行；若某服务在 shutdown 期间才完成启动并调用 `shutdown(fn)`，也会在下一轮事件循环中被关掉。
 
-### 9) 服务校验（isService）
+### 10) 服务校验（isService）
 
 ```typescript
 import { defineService, isService } from '@hile/core'
 
-const myService = defineService(async (shutdown) => 'hello')
+const myService = defineService('my', async (shutdown) => 'hello')
 
 isService(myService) // true
-isService({ id: 1, fn: () => {} } as any) // false
+isService({ key: 'x', fn: () => {} } as any) // false
 ```
 
 ## 隔离容器
@@ -195,7 +201,7 @@ import { Container } from '@hile/core'
 
 const container = new Container()
 
-const service = container.register(async (shutdown) => {
+const service = container.register('test', async (shutdown) => {
   return { value: 42 }
 })
 
@@ -208,27 +214,27 @@ const result = await container.resolve(service)
 
 | 函数 | 说明 |
 |------|------|
-| `defineService(fn)` | 注册服务到默认容器 |
+| `defineService(key, fn)` | 注册服务到默认容器 |
 | `loadService(props)` | 从默认容器加载服务 |
 | `isService(props)` | 判断对象是否为合法服务注册信息 |
+| `formatServiceKey(key)` | 将 key 格式化为可读字符串（日志） |
 
 ### `Container`
 
 | 方法 | 说明 |
 |------|------|
 | `new Container(options?)` | 创建容器，可配置启动/销毁超时 |
-| `register(fn)` | 注册服务（同函数引用去重） |
+| `register(key, fn)` | 注册服务（同一 key 共享槽位） |
 | `resolve(props)` | 加载服务（执行、等待或返回缓存） |
 | `shutdown()` | 销毁所有服务并执行清理回调 |
 | `on(listener)` | 订阅容器事件，返回取消订阅函数 |
 | `off(listener)` | 取消订阅 |
-| `getLifecycle(id)` | 获取服务生命周期阶段 |
-| `getDependencyGraph()` | 获取依赖图 `{ nodes, edges }` |
+| `getLifecycle(key)` | 获取服务生命周期阶段 |
+| `getDependencyGraph()` | 获取依赖图 `{ nodes, edges }`（key 为 `ServiceKey`） |
 | `getStartupOrder()` | 获取服务启动顺序（首次启动顺序） |
-| `hasService(fn)` | 检查函数是否已注册 |
-| `hasMeta(id)` | 检查服务是否已有运行时元数据 |
-| `getIdByService(fn)` | 通过函数获取服务 ID |
-| `getMetaById(id)` | 通过 ID 获取运行时元数据 |
+| `hasService(key)` | 是否已对该 key 注册 |
+| `hasMeta(key)` | 该 key 是否已有运行时元数据 |
+| `getMetaByKey(key)` | 按 key 获取运行时元数据 |
 
 ### 服务状态
 

package/SKILL.md

@@ -9,14 +9,14 @@ description: "@hile/core 的代码生成与使用规范。适用于定义/加载
 
 ## 1. 强约束（必须遵守）
 
-1. 服务必须使用 `async (shutdown)` 形态定义。
+1. 服务必须使用 `defineService(key, async (shutdown) => ...)` 形态：`key` 为 `ServiceKey`（`string | symbol`），在容器内唯一标识该服务槽位；同一 key 共享单例。
 2. 只能通过 `defineService` / `container.register` 产出服务对象。
 3. 只能通过 `loadService` / `container.resolve` 获取服务实例。
 4. 外部资源创建后必须立即注册 `shutdown`。
 5. 禁止在模块顶层缓存 `await loadService(...)` 结果。
 6. 依赖服务必须在服务函数内部加载。
 7. 多个 teardown 默认按 LIFO 顺序执行。
-8. `container.shutdown()` 必须执行所有已通过 `shutdown(fn)` 注册的回调；在 shutdown 进行中才完成启动并调用 `curDown` 的服务，也会在让出一次事件循环后被关掉（避免竞态漏关）。
+8. `container.shutdown()` 必须执行所有已通过 `shutdown(fn)` 注册的回调；在 shutdown 进行中才完成启动并调用 `shutdown` 的服务，也会在让出一次事件循环后被关掉（避免竞态漏关）。
 
 ## 2. 生命周期与超时约束
 
@@ -34,7 +34,7 @@ description: "@hile/core 的代码生成与使用规范。适用于定义/加载
 
 允许订阅：`container.on(listener)`。
 
-关键事件：
+关键事件（服务相关事件携带 `key: ServiceKey`）：
 
 - `service:init`
 - `service:ready`
@@ -50,13 +50,14 @@ description: "@hile/core 的代码生成与使用规范。适用于定义/加载
 
 - 订阅后必须在生命周期结束时取消订阅。
 - 记录错误时保留原始 error 对象。
+- 日志展示 key 时使用 `formatServiceKey(event.key)`。
 
 ## 4. 依赖图与循环依赖
 
 容器会自动记录服务依赖并检测循环依赖：
 
-- `getDependencyGraph()`
-- `getStartupOrder()`
+- `getDependencyGraph()`（`nodes` / `edges` 使用 `ServiceKey`）
+- `getStartupOrder()` 返回 `ServiceKey[]`
 
 规则：
 
@@ -82,22 +83,22 @@ export async function query(sql: string) {
 
 ```typescript
 // ✗
-const fake = { id: 1, fn: async () => 1 }
+const fake = { key: 'x', fn: async () => 1 }
 
 // ✓
-const real = defineService(async () => 1)
+const real = defineService('real', async () => 1)
 ```
 
 ### 5.3 不注册资源清理
 
 ```typescript
 // ✗
-export const bad = defineService(async () => {
+export const bad = defineService('bad', async () => {
   return await createPool()
 })
 
 // ✓
-export const good = defineService(async (shutdown) => {
+export const good = defineService('good', async (shutdown) => {
   const pool = await createPool()
   shutdown(() => pool.end())
   return pool
@@ -111,4 +112,4 @@ export const good = defineService(async (shutdown) => {
 - [ ] teardown 抛错是否不覆盖原始业务错误
 - [ ] 并发 resolve 同一服务是否只初始化一次
 - [ ] shutdown 重复调用是否幂等
-- [ ] shutdown 期间才注册的 teardown 是否在一次 setImmediate 让出后被正确执行
+- [ ] shutdown 期间才注册的 teardown 是否在一次 setImmediate 让出后被正确执行（避免竞态漏关）

package/dist/index.d.ts

@@ -1,12 +1,16 @@
 export type ServiceCutDownFunction = () => unknown | Promise<unknown>;
 export type ServiceCutDownHandler = (fn: ServiceCutDownFunction) => void;
 export type ServiceFunction<R> = (fn: ServiceCutDownHandler) => R | Promise<R>;
+export type ServiceKey = string | symbol;
 declare const sericeFlag: unique symbol;
+declare global {
+    var HILE_GLOBAL_CONTAINER: Container;
+}
 export type ServiceLifecycleStage = 'init' | 'ready' | 'stopping' | 'stopped';
 export interface ServiceRegisterProps<R> {
-    id: number;
     fn: ServiceFunction<R>;
     flag: typeof sericeFlag;
+    key: ServiceKey;
 }
 export interface ContainerOptions {
     startTimeoutMs?: number;
@@ -14,26 +18,26 @@ export interface ContainerOptions {
 }
 export type ContainerEvent = {
     type: 'service:init';
-    id: number;
+    key: ServiceKey;
 } | {
     type: 'service:ready';
-    id: number;
+    key: ServiceKey;
     durationMs: number;
 } | {
     type: 'service:error';
-    id: number;
+    key: ServiceKey;
     error: any;
     durationMs: number;
 } | {
     type: 'service:shutdown:start';
-    id: number;
+    key: ServiceKey;
 } | {
     type: 'service:shutdown:done';
-    id: number;
+    key: ServiceKey;
     durationMs: number;
 } | {
     type: 'service:shutdown:error';
-    id: number;
+    key: ServiceKey;
     error: any;
 } | {
     type: 'container:shutdown:start';
@@ -56,10 +60,13 @@ interface Paddings<R = any> {
     startedAt: number;
     endedAt?: number;
 }
+/** 日志或调试时展示服务 key */
+export declare function formatServiceKey(k: ServiceKey): string;
 export declare class Container {
     private readonly options;
-    private id;
-    private readonly packages;
+    private keyOrder;
+    private readonly keyOrdinal;
+    private readonly registeredKeys;
     private readonly paddings;
     private readonly dependencies;
     private readonly dependents;
@@ -70,32 +77,31 @@ export declare class Container {
     private readonly context;
     constructor(options?: ContainerOptions);
     private emit;
-    private getId;
+    private nextOrdinal;
     private hasPath;
     private trackDependency;
     on(listener: (event: ContainerEvent) => void): () => boolean;
     off(listener: (event: ContainerEvent) => void): void;
-    getLifecycle(id: number): ServiceLifecycleStage | undefined;
+    getLifecycle(key: ServiceKey): ServiceLifecycleStage | undefined;
     getDependencyGraph(): {
-        nodes: number[];
+        nodes: ServiceKey[];
         edges: {
-            from: number;
-            to: number;
+            from: ServiceKey;
+            to: ServiceKey;
         }[];
     };
-    getStartupOrder(): number[];
-    register<R>(fn: ServiceFunction<R>): ServiceRegisterProps<R>;
+    getStartupOrder(): ServiceKey[];
+    register<R>(key: ServiceKey, fn: ServiceFunction<R>): ServiceRegisterProps<R>;
     resolve<R>(props: ServiceRegisterProps<R>): Promise<R>;
     private run;
     private shutdownService;
     shutdown(): Promise<void>;
-    hasService<R>(fn: ServiceFunction<R>): boolean;
-    hasMeta(id: number): boolean;
-    getIdByService<R>(fn: ServiceFunction<R>): number | undefined;
-    getMetaById(id: number): Paddings<any> | undefined;
+    hasService(key: ServiceKey): boolean;
+    hasMeta(key: ServiceKey): boolean;
+    getMetaByKey(key: ServiceKey): Paddings<any> | undefined;
 }
 export declare const container: Container;
-export declare function defineService<R>(fn: ServiceFunction<R>): ServiceRegisterProps<R>;
+export declare function defineService<R>(key: ServiceKey, fn: ServiceFunction<R>): ServiceRegisterProps<R>;
 export declare function loadService<R>(props: ServiceRegisterProps<R>): Promise<R>;
 export declare function isService<R>(props: ServiceRegisterProps<R>): boolean;
 export default container;

package/dist/index.js

@@ -1,5 +1,5 @@
 import { AsyncLocalStorage } from 'node:async_hooks';
-const sericeFlag = Symbol('service');
+const sericeFlag = Symbol.for('service');
 async function withTimeout(promise, timeoutMs, message) {
     if (!timeoutMs || timeoutMs <= 0)
         return promise;
@@ -15,10 +15,15 @@ async function withTimeout(promise, timeoutMs, message) {
             clearTimeout(timer);
     }
 }
+/** 日志或调试时展示服务 key */
+export function formatServiceKey(k) {
+    return typeof k === 'string' ? k : String(k);
+}
 export class Container {
     options;
-    id = 1;
-    packages = new Map();
+    keyOrder = 0;
+    keyOrdinal = new Map();
+    registeredKeys = new Set();
     paddings = new Map();
     dependencies = new Map();
     dependents = new Map();
@@ -40,12 +45,12 @@ export class Container {
             }
         }
     }
-    getId() {
-        let i = this.id++;
-        if (i >= Number.MAX_SAFE_INTEGER) {
-            i = this.id = 1;
+    nextOrdinal() {
+        let o = ++this.keyOrder;
+        if (o >= Number.MAX_SAFE_INTEGER) {
+            o = this.keyOrder = 1;
         }
-        return i;
+        return o;
     }
     hasPath(from, to, visited = new Set()) {
         if (from === to)
@@ -62,25 +67,25 @@ export class Container {
         }
         return false;
     }
-    trackDependency(parentId, childId) {
-        if (parentId === childId) {
-            throw new Error(`circular dependency detected: ${parentId} -> ${childId}`);
+    trackDependency(parentKey, childKey) {
+        if (parentKey === childKey) {
+            throw new Error(`circular dependency detected: ${formatServiceKey(parentKey)} -> ${formatServiceKey(childKey)}`);
         }
-        if (!this.dependencies.has(parentId)) {
-            this.dependencies.set(parentId, new Set());
+        if (!this.dependencies.has(parentKey)) {
+            this.dependencies.set(parentKey, new Set());
         }
-        if (!this.dependents.has(childId)) {
-            this.dependents.set(childId, new Set());
+        if (!this.dependents.has(childKey)) {
+            this.dependents.set(childKey, new Set());
         }
-        const parentDeps = this.dependencies.get(parentId);
-        if (!parentDeps.has(childId)) {
-            if (this.hasPath(childId, parentId)) {
-                const error = new Error(`circular dependency detected: ${parentId} -> ${childId}`);
+        const parentDeps = this.dependencies.get(parentKey);
+        if (!parentDeps.has(childKey)) {
+            if (this.hasPath(childKey, parentKey)) {
+                const error = new Error(`circular dependency detected: ${formatServiceKey(parentKey)} -> ${formatServiceKey(childKey)}`);
                 this.emit({ type: 'container:error', error });
                 throw error;
             }
-            parentDeps.add(childId);
-            this.dependents.get(childId).add(parentId);
+            parentDeps.add(childKey);
+            this.dependents.get(childKey).add(parentKey);
         }
     }
     on(listener) {
@@ -90,15 +95,15 @@ export class Container {
     off(listener) {
         this.listeners.delete(listener);
     }
-    getLifecycle(id) {
-        return this.paddings.get(id)?.lifecycle;
+    getLifecycle(key) {
+        return this.paddings.get(key)?.lifecycle;
     }
     getDependencyGraph() {
-        const nodes = Array.from(this.packages.values()).sort((a, b) => a - b);
+        const nodes = Array.from(this.registeredKeys).sort((a, b) => (this.keyOrdinal.get(a) - this.keyOrdinal.get(b)));
         const edges = [];
-        for (const [id, deps] of this.dependencies.entries()) {
-            for (const dep of deps) {
-                edges.push({ from: id, to: dep });
+        for (const [fromKey, deps] of this.dependencies.entries()) {
+            for (const toKey of deps) {
+                edges.push({ from: fromKey, to: toKey });
             }
         }
         return { nodes, edges };
@@ -106,24 +111,23 @@ export class Container {
     getStartupOrder() {
         return [...this.startupOrder];
     }
-    register(fn) {
-        if (this.packages.has(fn)) {
-            return { id: this.packages.get(fn), fn, flag: sericeFlag };
+    register(key, fn) {
+        if (!this.keyOrdinal.has(key)) {
+            this.keyOrdinal.set(key, this.nextOrdinal());
         }
-        const id = this.getId();
-        this.packages.set(fn, id);
-        return { id, fn, flag: sericeFlag };
+        this.registeredKeys.add(key);
+        return { key, fn, flag: sericeFlag };
     }
     resolve(props) {
-        const { id, fn } = props;
+        const { key, fn } = props;
         const stack = this.context.getStore() || [];
-        const parentId = stack.length ? stack[stack.length - 1] : undefined;
-        if (parentId !== undefined) {
-            this.trackDependency(parentId, id);
+        const parentKey = stack.length ? stack[stack.length - 1] : undefined;
+        if (parentKey !== undefined) {
+            this.trackDependency(parentKey, key);
         }
         return new Promise((resolve, reject) => {
-            if (!this.paddings.has(id)) {
-                return this.run(id, fn, (e, v) => {
+            if (!this.paddings.has(key)) {
+                return this.run(key, fn, (e, v) => {
                     if (e) {
                         reject(e);
                     }
@@ -132,7 +136,7 @@ export class Container {
                     }
                 });
             }
-            const state = this.paddings.get(id);
+            const state = this.paddings.get(key);
             switch (state.status) {
                 case 0:
                     state.queue.add({ resolve, reject });
@@ -146,7 +150,7 @@ export class Container {
             }
         });
     }
-    run(id, fn, callback) {
+    run(key, fn, callback) {
         const state = {
             status: 0,
             lifecycle: 'init',
@@ -154,32 +158,32 @@ export class Container {
             queue: new Set(),
             startedAt: Date.now(),
         };
-        this.paddings.set(id, state);
-        if (!this.startupOrder.includes(id)) {
-            this.startupOrder.push(id);
+        this.paddings.set(key, state);
+        if (!this.startupOrder.includes(key)) {
+            this.startupOrder.push(key);
         }
-        this.emit({ type: 'service:init', id });
+        this.emit({ type: 'service:init', key });
         const curDown = (cutDownFn) => {
-            if (!this.shutdownQueues.includes(id)) {
-                this.shutdownQueues.push(id);
+            if (!this.shutdownQueues.includes(key)) {
+                this.shutdownQueues.push(key);
             }
-            if (!this.shutdownFunctions.has(id)) {
-                this.shutdownFunctions.set(id, []);
+            if (!this.shutdownFunctions.has(key)) {
+                this.shutdownFunctions.set(key, []);
             }
-            const pools = this.shutdownFunctions.get(id);
+            const pools = this.shutdownFunctions.get(key);
             if (!pools.includes(cutDownFn)) {
                 pools.push(cutDownFn);
             }
         };
         const parentStack = this.context.getStore() || [];
-        const startupPromise = this.context.run([...parentStack, id], () => Promise.resolve(fn(curDown)));
-        withTimeout(startupPromise, this.options.startTimeoutMs, `service startup timeout: ${id} exceeded ${this.options.startTimeoutMs}ms`).then((value) => {
+        const startupPromise = this.context.run([...parentStack, key], () => Promise.resolve(fn(curDown)));
+        withTimeout(startupPromise, this.options.startTimeoutMs, `service startup timeout: ${formatServiceKey(key)} exceeded ${this.options.startTimeoutMs}ms`).then((value) => {
             state.status = 1;
             state.lifecycle = 'ready';
             state.value = value;
             state.endedAt = Date.now();
             const durationMs = state.endedAt - state.startedAt;
-            this.emit({ type: 'service:ready', id, durationMs });
+            this.emit({ type: 'service:ready', key, durationMs });
             for (const queue of state.queue) {
                 queue.resolve(value);
             }
@@ -191,7 +195,7 @@ export class Container {
             state.error = e;
             state.endedAt = Date.now();
             const durationMs = state.endedAt - state.startedAt;
-            this.emit({ type: 'service:error', id, error: e, durationMs });
+            this.emit({ type: 'service:error', key, error: e, durationMs });
             const clear = () => {
                 state.lifecycle = 'stopped';
                 for (const queue of state.queue) {
@@ -200,39 +204,39 @@ export class Container {
                 state.queue.clear();
                 callback(e);
             };
-            this.shutdownService(id)
+            this.shutdownService(key)
                 .then(clear)
                 .catch((shutdownError) => {
-                this.emit({ type: 'service:shutdown:error', id, error: shutdownError });
+                this.emit({ type: 'service:shutdown:error', key, error: shutdownError });
                 clear();
             });
         });
     }
-    async shutdownService(id) {
-        if (this.shutdownQueues.includes(id)) {
-            const meta = this.paddings.get(id);
+    async shutdownService(key) {
+        if (this.shutdownQueues.includes(key)) {
+            const meta = this.paddings.get(key);
             if (meta) {
                 meta.lifecycle = 'stopping';
             }
-            this.emit({ type: 'service:shutdown:start', id });
+            this.emit({ type: 'service:shutdown:start', key });
             const startedAt = Date.now();
-            const pools = this.shutdownFunctions.get(id);
+            const pools = this.shutdownFunctions.get(key);
             let i = pools.length;
             while (i--) {
                 const teardown = pools[i];
                 try {
-                    await withTimeout(Promise.resolve(teardown()), this.options.shutdownTimeoutMs, `service shutdown timeout: ${id} exceeded ${this.options.shutdownTimeoutMs}ms`);
+                    await withTimeout(Promise.resolve(teardown()), this.options.shutdownTimeoutMs, `service shutdown timeout: ${formatServiceKey(key)} exceeded ${this.options.shutdownTimeoutMs}ms`);
                 }
                 catch (error) {
-                    this.emit({ type: 'service:shutdown:error', id, error });
+                    this.emit({ type: 'service:shutdown:error', key, error });
                 }
             }
-            this.shutdownFunctions.delete(id);
-            this.shutdownQueues.splice(this.shutdownQueues.indexOf(id), 1);
+            this.shutdownFunctions.delete(key);
+            this.shutdownQueues.splice(this.shutdownQueues.indexOf(key), 1);
             if (meta) {
                 meta.lifecycle = 'stopped';
             }
-            this.emit({ type: 'service:shutdown:done', id, durationMs: Date.now() - startedAt });
+            this.emit({ type: 'service:shutdown:done', key, durationMs: Date.now() - startedAt });
         }
     }
     async shutdown() {
@@ -241,8 +245,8 @@ export class Container {
         // 循环直到队列清空；再让出一次事件循环，处理「shutdown 期间才调用 curDown」的晚注册 teardown
         while (true) {
             while (this.shutdownQueues.length > 0) {
-                const id = this.shutdownQueues[this.shutdownQueues.length - 1];
-                await this.shutdownService(id);
+                const key = this.shutdownQueues[this.shutdownQueues.length - 1];
+                await this.shutdownService(key);
             }
             await new Promise(r => setImmediate(r));
             if (this.shutdownQueues.length === 0)
@@ -252,27 +256,32 @@ export class Container {
         this.shutdownQueues.length = 0;
         this.emit({ type: 'container:shutdown:done', durationMs: Date.now() - startedAt });
     }
-    hasService(fn) {
-        return this.packages.has(fn);
+    hasService(key) {
+        return this.registeredKeys.has(key);
     }
-    hasMeta(id) {
-        return this.paddings.has(id);
+    hasMeta(key) {
+        return this.paddings.has(key);
     }
-    getIdByService(fn) {
-        return this.packages.get(fn);
+    getMetaByKey(key) {
+        return this.paddings.get(key);
     }
-    getMetaById(id) {
-        return this.paddings.get(id);
+}
+function getGlobalContainer() {
+    if (!globalThis.HILE_GLOBAL_CONTAINER) {
+        globalThis.HILE_GLOBAL_CONTAINER = new Container();
     }
+    return globalThis.HILE_GLOBAL_CONTAINER;
 }
-export const container = new Container();
-export function defineService(fn) {
-    return container.register(fn);
+export const container = getGlobalContainer();
+export function defineService(key, fn) {
+    return container.register(key, fn);
 }
 export function loadService(props) {
     return container.resolve(props);
 }
 export function isService(props) {
-    return props.flag === sericeFlag && typeof props.id === 'number' && typeof props.fn === 'function';
+    return (props.flag === sericeFlag
+        && typeof props.fn === 'function'
+        && (typeof props.key === 'string' || typeof props.key === 'symbol'));
 }
 export default container;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hile/core",
-  "version": "1.0.21",
+  "version": "1.1.0",
   "description": "Hile core - lightweight async service container",
   "type": "module",
   "main": "./dist/index.js",
@@ -24,5 +24,5 @@
     "fix-esm-import-path": "^1.10.3",
     "vitest": "^4.0.18"
   },
-  "gitHead": "f5d59f9f131456cf14e5ca62eeea6becde84ebef"
+  "gitHead": "ec49eb8979b6c9c3ce99cb5311f1684bcde1bf2a"
 }