core

README

core

应用基建件——治理配置 schema/config 配置加载/lifecycle 契约/IP 工具/version

🌐 项目主页：https://oekit.github.io/ · 名称由来：Open Easy Kit（开源 · 易用 · 工具集合） 🤖 AI Agent：本仓规范与硬规则见 AGENTS.md；机器可读索引见 llms.txt（接口签名以源码为准）。

安装

go get github.com/oekit/core@v0.4.0

这个仓库做什么

core 是应用基建件集合：治理配置 schema、配置文件加载、生命周期契约、网络 IP 工具、版本信息—— 各服务都会用到、但又不属于任何具体领域的基础件。

组成

包	做什么
governance	治理配置模板 schema（retry/timeout_ms/circuit_breaker/limiter）+ Parse/Store。JSON 形态对 Nacos 友好，hertz/kitex 两侧共用
config	配置文件加载：LoadBootstrap[T]（YAML + ${VAR} 占位符展开）、LoadDotEnv、env 系列、ConfigWatcher[T] 热更新、OverlayMerge。只依赖 yaml+logx，零 Nacos
lifecycle	transport 生命周期契约（App 接口）：hertz/kitex 的 RunServer 面向它编程
network	IP 工具：GetPodIP（K8s POD_IP 感知）、IsPublicIP——注册地址解析的公共依赖
version	版本信息（ldflags 注入 Metadata()）

快速使用

import "github.com/oekit/core/governance"

cfg, err := governance.Parse([]byte(`{
  "timeout_ms": { "*": 500 },
  "retry": { "max_attempts": 3 }
}`))
// 非法值 fail-closed 返回错误；hertz/kitex 侧经 Store 订阅热更新

import "github.com/oekit/core/config"

cfg, err := config.LoadBootstrap[MyConfig]("dev") // etc/config.yaml → etc/config-dev.yaml
config.LoadDotEnv(".env")                         // 可选：本地 .env

边界

• 治理配置的消费端在 oekit/hertz（governance/hertz 动态限流/超时） 与 oekit/kitex（GovernanceConfig 热更）
• 并发原语在 concurrency；微工具在 pkg
• 本仓零矩阵内依赖

矩阵总览（23 活跃模块，自动生成）

模块	内容	矩阵内依赖
pkg	微工具集 16 合 1（errors/validator/stringx/slicex/enumx/convert/encoding/jsonrepair/httpjson/mathx/pathx/pagination/ptrx/timex/uidgen/cache）	—
concurrency	并发与流控原语（async/group/singleflight/progress/syncx/ratelimit/retry）	—
logx	统一日志门面（多后端可替换 + Sink + caller 归属）+ 优雅关停	—
core	应用基建件（governance 治理 schema / lifecycle 契约 / network IP 工具 / version）	—
istio	Istio Proxyless——Kitex xDS 动态熔断	—
metrics	Prometheus 门面 + 弹性指标族	core
tracing	OpenTelemetry 追踪 + trace_id 真相源	logx
registry	注册发现核心 + Nacos 实现 + 配置加载 + sdbridge	core、logx
data	缓存检查器（TTL/failTTL/inflight 合并）+ LocalCache	concurrency、logx
gorm	SQL/GORM 全家——连接池增强、框架无关 CRUD Service、仓储	logx、pkg
redis	Redis 全家——客户端封装、缓存后端、分布式锁	concurrency、data、logx
httpx	HTTP 客户端 + 负载均衡——服务发现/熔断/重试/指标/OTel 透传	concurrency、core、logx、metrics、registry、tracing
network	轻量网络客户端——WebSocket/NATS/MQ 抽象、连接与流工具、Octopus 推送	concurrency、logx、tracing
timertask	分片定时任务（FNV-1a、心跳续约）	concurrency、logx
middleware	Hertz 自研标准中间件栈 + contrib 桥接 + hmw	concurrency、core、logx、metrics、pkg、registry、tracing
nns	NNS 服务治理客户端——provider 无关发现/配置/实例缓存	concurrency、core、logx、registry
nns-endpoint	NNS 端点工厂——per-service 熔断、换实例重试、gRPC 池	concurrency、core、httpx、logx、metrics、nns、registry
bootstrap	应用生命周期引导——bootstrap.Run 骨架 + healthz	concurrency、logx
handler	HTTP handler 层——通用 CRUD Handler、参数绑定、版本端点	concurrency、core、gorm、logx、metrics、middleware、pkg、registry、tracing
hertz	Hertz 运行时集成——日志桥接、生命周期、SSE/health/metrics、适配器、OTel	bootstrap、concurrency、core、logx、metrics、nns、registry、tracing
kitex	Kitex 生态——日志桥接、治理热更、生命周期、BizError 桥接、kitexotel	bootstrap、concurrency、core、logx、metrics、nns、pkg、registry
workflow	组合式流程编排——串行/并行/异步/条件分支 + Hook AOP	concurrency、logx
kitex-examples	Kitex echo 示例——client/server + IDL + 治理配置	bootstrap、concurrency、core、kitex、logx、metrics、nns、pkg、registry、tracing

矩阵总览（23 活跃模块，自动生成）

模块	内容	矩阵内依赖
pkg	微工具集 16 合 1（errors/validator/stringx/…）	—
concurrency	并发与流控原语	—
logx	日志门面 + shutdown	—
core	应用基建件	—
istio	Istio XDS	—
metrics	Prometheus 门面	core
tracing	OTel + traceid	logx
registry	注册发现 + Nacos + 配置	core、logx
data	缓存检查器	concurrency、logx
gorm	SQL/CRUD	logx、pkg
redis	Redis 全家	concurrency、data、logx
httpx	HTTP 客户端	concurrency、core、logx、metrics、registry、tracing
network	轻量网络件	concurrency、logx、tracing
timertask	定时任务	concurrency、logx
middleware	Hertz 中间件栈	concurrency、core、logx、metrics、pkg、registry、tracing
nns	服务治理门面	concurrency、core、logx、registry
nns-endpoint	端点熔断重试	concurrency、core、httpx、logx、metrics、nns、registry
bootstrap	应用引导	concurrency、logx
handler	CRUD handler	concurrency、core、gorm、logx、metrics、middleware、pkg、registry、tracing
hertz	Hertz 运行时	bootstrap、concurrency、core、logx、metrics、nns、registry、tracing
kitex	Kitex 生态	bootstrap、concurrency、core、logx、metrics、nns、pkg、registry
workflow	流程编排	concurrency、logx
kitex-examples	Kitex 示例	bootstrap、concurrency、core、kitex、logx、metrics、nns、pkg、registry、tracing

依赖严格自底向上；微库已合并为 pkg，旧微库仓已删除。

本仓在矩阵中的位置与依赖见上表「矩阵内依赖」列。历史沿革：源自 ekit 单体库 （git.enjoye.top/enjoydream/ekit v0.34.0，冻结维护），2026-10 拆分为独立 module。

License

MIT — 见 LICENSE