cevio/hile-core

@hile/core SKILL

本文档面向代码生成器与维护者，目标是确保生成代码严格符合容器语义。

1. 强约束（必须遵守）

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 进行中才完成启动并调用 shutdown 的服务，也会在让出一次事件循环后被关掉（避免竞态漏关）。
9. src/services/ 内：*.boot.* 与 *.service.* 同属 service 模块（均为 defineService / register）；*.boot.* 由 CLI 自启动加载，*.service.* 在需要时 loadService 依赖加载。文件名必须以 *.service.ts / *.service.js 或 *.boot.ts / *.boot.js 结尾以区分上述两种加载方式。
10. 应用分层（与 @hile/http-next / 根 SKILL.md 一致）：系统/基础设施逻辑 放 src/services/*.service.*（及 *.boot.*）；业务/领域逻辑 放 src/models/*.model.*，不要混写。（http-next 下 defineModel 仅在 models；src/app/** 与 src/controllers/** 均可 loadModel(xxxModel)；src/controllers/** 亦可 loadService，见 packages/http-next/SKILL.md。）

2. 生命周期与超时约束

容器生命周期：init -> ready -> stopping -> stopped。

• 启动超时：new Container({ startTimeoutMs })
• 销毁超时：new Container({ shutdownTimeoutMs })

生成代码时：

• 不要吞掉启动超时错误。
• 不要假设 teardown 一定成功；应允许 service:shutdown:error 事件出现。

3. 可观测事件约束

允许订阅：container.on(listener)。

关键事件（服务相关事件携带 key: ServiceKey）：

• service:init
• service:ready
• service:error
• service:shutdown:start
• service:shutdown:done
• service:shutdown:error
• container:shutdown:start
• container:shutdown:done
• container:error

规则：

• 订阅后必须在生命周期结束时取消订阅。
• 记录错误时保留原始 error 对象。
• 日志展示 key 时使用 formatServiceKey(event.key)。

4. 依赖图与循环依赖

容器会自动记录服务依赖并检测循环依赖：

• getDependencyGraph()（nodes / edges 使用 ServiceKey）
• getStartupOrder() 返回 ServiceKey[]

规则：

• 不要绕开容器手动构建“隐式全局单例依赖”。
• 出现 circular dependency detected 时应通过拆分服务职责或引入中间层服务解决。

5. 反模式（禁止）

5.1 顶层缓存实例

// ✗
const db = await loadService(dbService)

// ✓
export async function query(sql: string) {
  const db = await loadService(dbService)
  return db.query(sql)
}

5.2 手动伪造服务对象

// ✗
const fake = { key: 'x', fn: async () => 1 }

// ✓
const real = defineService('real', async () => 1)

5.3 不注册资源清理

// ✗
export const bad = defineService('bad', async () => {
  return await createPool()
})

// ✓
export const good = defineService('good', async (shutdown) => {
  const pool = await createPool()
  shutdown(() => pool.end())
  return pool
})

5.4 services 下可加载服务未使用 .service 后缀

// ✗ src/services/config.ts — 供 loadService 的 service 模块应使用 *.service.*
export const configService = defineService('config', async () => ({}))

// ✓ src/services/config.service.ts（依赖加载）
export const configService = defineService('config', async () => ({}))

*.boot.* 与 *.service.* 均为 service 模块；自启动用 .boot，依赖加载用 .service。

6. 边界条件清单

• [ ] 服务同步抛错路径是否可观测
• [ ] 异步 reject 路径是否会触发 teardown
• [ ] teardown 抛错是否不覆盖原始业务错误
• [ ] 并发 resolve 同一服务是否只初始化一次
• [ ] shutdown 重复调用是否幂等
• [ ] shutdown 期间才注册的 teardown 是否在一次 setImmediate 让出后被正确执行（避免竞态漏关）