pkg/core 速查

26 个包，全部有包级文档注释与直接测试。opt-in 指需要配置文件里存在对应段 （或代码里显式挂载），否则整个包是 no-op 或干脆不存在。

驱动与编排

包 用途 开关
verticle 服务抽象：Service（Name/Setup/BuildRouter）与 Run 驱动的完整生命周期 入口
app 生命周期容器：HTTP server、后台 Block、逆序清理栈、信号驱动优雅退出 由 verticle 使用
config YAML 加载、${VAR} 展开、struct tag 默认值与逐字段环境覆盖 始终
nacos Nacos 配置中心适配：框架段/服务段两个 data_id，namespace/group/鉴权（账号密码或 AK/SK），服务段热更 nacos: 段（或 verticle.WithConfig）
errs 错误模型：每个错误带 Kind（→ HTTP 状态）、业务 Code、消息 始终
obs 可观测性：slog 结构化日志、Prometheus 指标、OpenTelemetry 链路 日志/指标始终；tracing 需 trace.enabled
httpx Web 层：无框架的 net/http server、封套 handler 约定、两个中间件槽、默认安全头 始终（HTTP 默认形态）

存储与消息

包 用途 开关
db database/sql 之上的 SQL 访问：pgx / mysql / sqlite 三驱动、可移植 ? 占位符、泛型扫描、事务、慢查询日志、错误映射 db: 段
redis go-redis 封装：初始化、JSON 助手、Lock（阻塞 + 重入 + 续租）与 TryLock 锁、Claim 槽位占领、脚本 redis: 段
memcache gomemcache 封装 + JSON 助手 memcache: 段
kafka franz-go 封装：同步/异步生产者、at-least-once 消费循环、可选死信队列 kafka: 段
cache cache-aside 模式：single-flight 回源 + TTL 抖动，防击穿与防雪崩 调用处（需 redis 客户端）
grpcx gRPC server（绑定监听、健康服务、reflection、优雅关停）与 fail-fast 拨号器 grpc: 段 + 实现 GRPCRegistrar
rpcx rpcx server 与客户端助手，链路传播内置 rpcx: 段 + 实现 RPCXRegistrar

韧性与治理

包 用途 开关
ratelimit 按调用方限流：本地令牌桶或 redis 固定窗口；ByIP/ByHeader/ByRoute 代码内
idempotency 同一 Idempotency-Key 的重复请求只写一次，回放上次响应 Use + store
breaker 三态熔断：连续失败计数或错误率滑动窗口，可按 errs 分类计失败 代码内
retry 瞬时失败的指数退避重试，带全抖动 代码内
cron 多副本下不重复执行的定时任务（redis 选主） 代码内（选主需 redis）
auth Bearer token 验签（HMAC 密钥或 JWKS/OIDC），把调用方作为 Principal 放进 ctx auth: 段 + 挂 middleware
feature 进程内功能开关：运行时 > 环境变量 > 配置 > 注册默认 feature: 段
audit 审计事件：谁对什么做了什么、结果如何，sink 可插拔 代码内（可选 SetSink）

AI 与测试基座

包 用途 开关
llm 统一 LLM 客户端：四种线协议 + 规范请求/响应；另有 System One（Jev）决策问答 代码内
dbtest 测试用已迁移数据库：默认每测试一个 SQLite 文件，自动执行仓库迁移 仅测试（DB_TEST_DRIVER/DSN 可切真库）
redistest 测试用 Redis：默认进程内 miniredis，REDIS_TEST_ADDR 可切真实例 仅测试

为什么要一页列完

这份表本身就是一条约束：基础设施的入口数量是有限的、可枚举的。 当你想加一个"顺手 import 一下"的驱动时，问题不是"能不能"，而是"它该属于这里哪一行"。 如果没有合适的一行，说明它应该待在业务包里，或者根本不该进来。 

flowchart LR
    BIZ["internal/ 业务代码"] --> V["verticle · app"]
    BIZ --> HX["httpx · errs · obs · config"]
    BIZ --> ST["db · redis · memcache · kafka"]
    BIZ --> GO["auth · ratelimit · breaker · retry
idempotency · cache · cron · feature · audit"]
    BIZ --> AI["llm"]
    ST --> DRV["第三方驱动"]
    HX --> DRV2["prometheus · otel · slog"]
    classDef core fill:#fdf6f0,stroke:#c8641f,color:#2b2722
    class V,HX,ST,GO,AI core
业务代码只认这五组入口。驱动与观测库被关在 pkg/core 内部， 由 depguard 保证不泄漏到业务侧。

下一步