Top-level await仅触发初始化，不提供连接感知能力；真正的连接感知需封装带状态的Promise工厂函数，导出可调用、可监听、可重试的createDB()及isReady()、healthCheck()等接口，并避免循环依赖。
Top-level await 本身不提供“连接感知”能力，它只是让模块能等待异步操作完成后再导出符号。真正的连接感知需要你主动设计状态检查、重试机制和就绪信号——不是靠 await 自动实现，而是用 await 搭配可观察的状态封装来达成。
核心思路：把连接逻辑封装成带状态的 Promise 工厂
避免在顶层直接写 const db = await connect()，这会让模块变成“黑盒”，调用方无法知道连接是否失败、是否重试中、是否已断开。应该导出一个函数，每次调用都返回一个新的、可监听状态的初始化 Promise：
- 用
async function createDB()封装连接逻辑，内部处理重试、超时、错误分类 - 导出该函数本身，而非连接实例；让消费模块按需调用并自行决定何时等待
- 在函数内部用
let instance = null+ 双重检查缓存，实现首次调用初始化、后续复用
添加显式就绪状态与健康检查接口
仅靠 await 完成一次连接不够，生产环境需要持续感知连接有效性。可在工厂函数返回的对象上挂载状态方法：
-
db.isReady()：返回布尔值，基于当前实例是否存在且未标记为断开 -
db.healthCheck()：发起轻量探测（如SELECT 1），返回 Promise -
db.on('disconnect', handler)：暴露事件（可用 EventEmitter 或自定义事件总线）
这样其他模块就能在运行时主动轮询或监听状态，而不是假设“导入即可用”。
模块初始化时用顶层 await 触发但不阻塞全部导出
若确实需要模块加载时就建立连接（例如配置驱动型服务），可保留顶层 await，但必须确保它只触发初始化、不阻塞符号导出：
AI舌诊面诊问诊医疗系统+诊疗商城系统源码
下载
AI 舌诊面诊问诊医疗系统 + 诊疗商城系统源码是一套结合 AI 辅助诊断与商品转化的健康类程序，基于浩创云、ThinkPHP（PHP）开发，支持微信服务号与 H5 端，适合做中医舌诊面诊问答、健康建议推送以及配套诊疗商品的运营。
- 先同步导出
createDB、isReady等工具函数 - 再用
await createDB().catch(() => {})静默触发初始化（不 throw，避免模块加载失败） - 导出一个
readyPromise：export const ready = createDB().catch(err => { console.warn('DB init failed, will retry on first use', err); })
这样既利用了顶层 await 的启动便利性，又把控制权交还给调用方——它可以选择 await db.ready 等待，也可以跳过直接调用 createDB() 并自己处理错误。
配合模块图避免循环依赖挂起
数据库模块常被 config、auth、logger 等多处引用，极易因 top-level await 引发 A→B→A 类死锁。防范方式很具体：
- 禁止在
config.mjs或auth.mjs中直接 await 数据库连接 - 所有跨模块依赖统一走函数调用（如
getDB()），不依赖模块级初始化顺序 - 用
node --trace-module-loading启动验证加载链，确认 db 模块不处于循环路径的关键节点
本质上，连接感知 ≠ 一次性 await 成功，而是把连接从“静态资源”变成“可观察服务”。顶层 await 是启动扳机，不是状态管理器。
