README
¶
handler
HTTP handler 层——泛型 CRUD Handler/参数绑定
🌐 项目主页：https://oekit.github.io/ · 名称由来：Open Easy Kit（开源 · 易用 · 工具集合） 🤖 AI Agent：本仓规范与硬规则见 AGENTS.md；机器可读索引见 llms.txt（接口签名以源码为准）。
安装
go get github.com/oekit/handler@v0.1.10
这个仓库做什么
handler 是 HTTP handler 层：泛型 CRUD Handler（直接消费 crud.Service）、
参数绑定、版本信息端点——让「一个模型暴露 REST API」变成三行代码。
组成
| 包 | 做什么 |
|---|---|
crudh |
泛型 NewHandler[T, CreateReq, UpdateReq](svc) + RegisterRoutes：GET 列表（分页）/GET 单个/POST/PUT/DELETE 全套 |
validatorh |
BindAndValidate：Hertz 参数绑定 + 校验（ValidationError 自动 400）、分页绑定 |
versionh |
版本信息端点 |
快速使用
import "github.com/oekit/handler/crudh"
// svc 来自 oekit/gorm 的 crud.NewBaseService
crudh.NewHandler(svc).RegisterRoutes(rg, "/projects")
// → GET /projects/projects, POST /projects/projects, ...
边界
crud.Service接口在 gorm（含 TxRepository 事务语义）- 标准中间件栈在 middleware；
mw.Fail统一错误出口
矩阵总览（23 活跃模块，自动生成）
| 模块 | 内容 | 矩阵内依赖 |
|---|---|---|
| pkg | 微工具集 20 合 1（errors/bloomx/contextx/validator/stringx/slicex/enumx/convert/encoding/jsonrepair/httpjson/mathx/pathx/pagination/ptrx/timex/uidgen/cache/bufiox/strmap） | — |
| concurrency | 并发与流控原语（async/gopool/group/singleflight/progress/syncx/ratelimit/retry）+ window 滑动窗口 / breaker 自适应熔断（规范哨兵 ErrCircuitOpen）/ shedding CPU 自适应降载 | — |
| logx | 统一日志门面（多后端可替换 + Sink + caller 归属）+ 优雅关停；桥接子包 hlog/hertzlog/kitexlog 为嵌套模块按需引入 | — |
| core | 应用基建件（governance 治理 schema / config 配置加载 + default/env/range/options tag 校验 / lifecycle 契约 / network IP 工具 / version） | logx |
| istio | Istio Proxyless——Kitex xDS 动态熔断 | — |
| metrics | Prometheus 门面 + 弹性指标族 | core |
| tracing | OpenTelemetry 追踪 + trace_id 真相源 | logx |
| registry | 注册发现核心 + Nacos 实现 + Nacos 配置源 + sdbridge | core、logx |
| data | LocalCache（TTL/容量/空值防穿透）+ SingleFlightCache + 缓存键构造（刷新检查器 Checker 在 pkg/cache） | concurrency、logx |
| gorm | SQL/GORM 全家——连接池增强、框架无关 CRUD Service、仓储 | logx、pkg |
| redisx | Redis 全家——客户端封装（根包）、分布式缓存 cache/、分布式锁 distlock、分布式限流 ratelimit（Lua 三态 + 故障本地兜底） | concurrency、data、logx |
| httpx | HTTP 客户端 + 负载均衡——服务发现/熔断（规范哨兵 ErrCircuitOpen）/重试/指标/OTel 透传 | concurrency、core、logx、metrics、registry、tracing |
| network | 轻量网络客户端——WebSocket/NATS/MQ 抽象、连接与流工具、Octopus 推送 | concurrency、logx、tracing |
| timertask | 分片定时任务（FNV-1a、心跳续约） | concurrency、logx |
| middleware | Hertz 自研标准中间件栈 + contrib 桥接 + hmw + SheddingMiddleware 自适应降载 | 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 |
依赖严格自底向上；微库已合并为 pkg，旧微库仓已删除。
本仓在矩阵中的位置与依赖见上表「矩阵内依赖」列。历史沿革：源自 ekit 单体库 （git.enjoye.top/enjoydream/ekit v0.34.0，冻结维护），2026-10 拆分为独立 module。
License
MIT — 见 LICENSE
Directories
¶
| Path | Synopsis |
|---|---|
|
Package crudh 提供基于 Hertz 的通用 CRUD HTTP Handler。
|
Package crudh 提供基于 Hertz 的通用 CRUD HTTP Handler。 |
|
Package validatorh 提供基于 Hertz 的请求参数绑定与验证。
|
Package validatorh 提供基于 Hertz 的请求参数绑定与验证。 |
|
Package versionh 提供版本信息的 HTTP Handler。
|
Package versionh 提供版本信息的 HTTP Handler。 |
Click to show internal directories.
Click to hide internal directories.