Ratel 是一套生产级 Go 微服务治理框架,整合 Web/RPC 服务端、数据存储客户端与限流、熔断、链路追踪、指标、日志等治理能力,开箱即用。
- 服务端:复用 Gin、gRPC、Hertz、Asynq 等成熟框架,统一封装为
server.Server生命周期接口。 - 客户端与存储:统一封装 etcd、RabbitMQ、FTP/SFTP、Redis、SQL(MySQL/PostgreSQL/ClickHouse)、MongoDB、Elasticsearch 等中间件。
- 治理能力:令牌桶限流、Google SRE 自适应熔断、SingleFlight 防击穿、OpenTelemetry 链路追踪、Prometheus 指标、多后端异步日志。
- 配套工具:分布式任务调度、雪花 ID、敏感词过滤、文本排版、i18n、图像处理、代码生成脚手架、热编译。
项目组织参考 Kratos 的分层方式,使用 Go 1.27 泛型与标准库,注释遵循 Go 官方文档规范(每个库包均有 doc.go 包注释,导出 API 带 Godoc)。
| 服务端 | 底层框架 | 场景 |
|---|---|---|
server/xgin |
Gin | RESTful API、Web 应用、WebSocket |
server/xgrpc |
gRPC | 微服务间 RPC 通信 |
server/xhertz |
CloudWeGo Hertz | 高并发 HTTP 服务 |
server/xasynq |
Asynq | 定时任务调度与后台任务消费 |
server/xmonitor |
net/http | pprof、路由清单、构建信息等治理接口 |
所有服务端统一实现 server.Server 接口(Serve/Stop/GracefulStop/Info/Health),由 core/app 统一管理生命周期,支持信号驱动的优雅启停。
- etcd:KV 读写、前缀/多键批量查询、分布式互斥锁、租约会话、前缀监听、BasicAuth/TLS、链路追踪。
- gRPC 客户端:etcd 服务发现、SWR 平滑加权轮询与 P2C 最少负载均衡、调试/超时/追踪/日志/指标拦截器链。
- RabbitMQ:断线自动重连、通道复用、队列声明绑定 Builder、可配置重试策略、断线后消费自动恢复。
- Redis:单节点、集群、哨兵、分片四种模式;命令按数据类型分组;统一经熔断器执行;可挂载追踪与指标钩子。
- SQL:MySQL、PostgreSQL、ClickHouse;基于 GORM;DSN 级连接缓存复用;分页/排序/范围参数辅助;指标与追踪拦截器。
- MongoDB:链式条件构造、熔断/指标/追踪增强集合、写入前结构体到 BSON 自动转换。
- Elasticsearch:节点缓存复用、HTTP 传输层追踪与指标。
- 可空类型:替代
sql.NullXxx的完整可空类型集,统一实现 Scanner/Valuer/JSON/Text 接口。 - 代理池:按分组统一管理 Redis/Mongo/ES/SQL 实例,SQL 支持读写库分离与随机选库。
- 会话存储:基于 Redis 的 JSON 会话,点分路径读写嵌套字段。
- 限流:令牌桶,支持固定间隔、固定速率、每次补充量子三种填充方式;阻塞/限时/非阻塞三种取令牌模式;限流 Reader/Writer。
- 熔断:基于 Google SRE 过载保护模型的自适应熔断器,支持自定义错误判定与降级回调。
- 防击穿:SingleFlight 并发单飞。
- 批量错误:BatchError 批量错误聚合。
- goroutine 编排:串行/并行/限流并发/延迟启动/panic 恢复/错误收集。
- 生命周期:并发生命周期控制器(cycle)、分阶段钩子(hooks,defer 语义逆序执行)。
- 指标:Prometheus 命名空间
ratel,预置服务端/客户端/任务/缓存等场景的 Counter、Gauge、Histogram、Summary 向量。 - 追踪:OpenTelemetry,支持 HTTP/gRPC 两种 OTLP 导出协议,兼容 Jaeger 与 W3C TraceContext 传播。
- 日志:基于 logrus 的结构化日志;控制台彩色输出;Elasticsearch、MongoDB、SQL 三套异步钩子,后台队列写入。
- cron 调度:五/六字段表达式与
@yearly等预定义描述符,超时控制、动态增删、优雅关闭。 - 分布式任务:cron 调度 + 一致性哈希节点池,集群内分配任务,节点变更自动进入升级状态避免重复执行;支持任务恢复与近期任务回放。
- 分布式执行器:xxl-job 风格的任务执行器接口与全局管理。
- Asynq:定时任务管理器与后台任务工作者。
- 雪花 ID 生成器(原子操作、并发安全、可自定义位宽)。
- AC 自动机敏感词过滤(
nlpword与filter两套实现)。 - 中英文混排文本自动排版(
correct)。 - i18n 多语言消息管理(
lang/i18n)。 - 图像读取/变换/合成/水印/文字绘制(
img,基于 libvips)。 - Go 项目热编译监视(
watch)。 - 代码生成脚手架(
toolkit):项目创建、DAO/接口/模型/Vue 代码生成、更新日志、脚手架升级。
flowchart TB
%% ============ 层级:自上而下 ============
subgraph APP["应用层 core/app —— 组件组装与生命周期"]
App["Application<br/>New / Run / Serve / Schedule / Job / Executor<br/>RegisterHooks / SetRegistry / Stop / GracefulStop"]
end
subgraph SRV["服务端层 server/ —— 统一 server.Server 生命周期接口"]
Xgin["xgin<br/>Gin HTTP 服务"]
Xgrpc["xgrpc<br/>gRPC 服务"]
Xhertz["xhertz<br/>Hertz HTTP 服务"]
Xasynq["xasynq<br/>Asynq 异步任务服务"]
Xmonitor["xmonitor<br/>监控 / pprof 服务"]
end
subgraph CLI["客户端层 client/ —— 中间件客户端"]
CEtcd["etcdv3<br/>配置中心 / 注册中心客户端"]
CGrpc["grpc<br/>服务发现 + 拦截器链"]
CRabbit["rabbitmq<br/>发布订阅客户端"]
CFtp["ftp / sftp<br/>文件传输客户端"]
end
subgraph STO["存储层 stores/ —— 数据访问"]
SRedis["redis<br/>单机 / 集群 / 哨兵 / Ring 四模式"]
SSql["sql<br/>GORM 封装 · MySQL / PostgreSQL / ClickHouse"]
SMongo["mongodb<br/>mongo-driver 封装"]
SEs["elasticsearch"]
SNull["null<br/>数据库可空类型"]
SProxy["proxy<br/>多客户端代理池"]
SSession["session<br/>Redis 会话存储"]
end
subgraph REG["注册中心 registry/"]
RInterface["registry.Registry 接口<br/>Register / Deregister / GetService"]
REtcd["etcdv3 实现<br/>租约续期 · 服务发现"]
end
subgraph CORE["治理核心 core/ —— 横切能力"]
CRatelimit["ratelimit 令牌桶限流"]
CResource["resource 熔断 / SingleFlight / 资源管理器"]
CTrace["trace OpenTelemetry 链路追踪"]
CMetric["metric Prometheus 指标"]
CLogger["logger 多后端异步日志"]
CGoroutine["goroutine 并发编排"]
CTask["task 分布式定时任务"]
CCycle["cycle 生命周期控制"]
CHooks["hooks 阶段钩子"]
CExecutor["executor 分布式执行器"]
end
subgraph TOOL["工具层 util/ 等 —— 通用能力"]
TUtil["util 通用工具"]
TCorrect["correct 文本排版"]
TNlp["nlpword 敏感词检测"]
TFilter["filter 文本过滤"]
TLang["lang / i18n 国际化"]
TImg["img 图像处理"]
TSnow["snowflake 雪花 ID"]
TCron["crontab 调度器"]
TWatch["watch 文件监控"]
TConfig["config 配置加载"]
end
subgraph INFRA["外部基础设施"]
IEtcd["etcd 集群"]
IRabbit["RabbitMQ"]
IRedis["Redis"]
ISql["MySQL / PostgreSQL / ClickHouse"]
IMongo["MongoDB"]
IEs["Elasticsearch"]
IFtp["FTP / SFTP"]
IOtel["OpenTelemetry Collector"]
IProm["Prometheus"]
end
%% ============ 生命周期托管 ============
APP -->|"Run 统一启动"| SRV
APP -->|"Schedule 托管"| Xasynq
APP -->|"Job 托管"| CTask
APP -->|"Executor 托管"| CExecutor
APP -->|"阶段钩子"| CHooks
APP -->|"SetRegistry 注入"| REG
%% ============ 服务端调用链 ============
Xgin -->|"业务调用"| CGrpc
Xgin -->|"业务调用"| CRabbit
Xgrpc -->|"业务调用"| CGrpc
Xhertz -->|"业务调用"| CGrpc
Xasynq -->|"消费任务"| SRedis
%% ============ 数据访问 ============
SRV -->|"数据访问"| STO
SSession -->|"基于"| SRedis
SProxy -->|"统一访问"| SRedis
SProxy -->|"统一访问"| SMongo
SProxy -->|"统一访问"| SEs
SProxy -->|"统一访问"| SSql
%% ============ 服务发现 / 配置 ============
CGrpc -->|"服务发现"| REG
SRV -->|"启动登记"| REG
REtcd -->|"读写节点"| IEtcd
CEtcd -->|"读写"| IEtcd
%% ============ 中间件连接 ============
CRabbit -->|"连接"| IRabbit
SRedis -->|"连接"| IRedis
SSql -->|"连接"| ISql
SMongo -->|"连接"| IMongo
SEs -->|"连接"| IEs
CFtp -->|"连接"| IFtp
%% ============ 治理横切(虚线) ============
STO -.->|"命令经熔断器 / 指标 / 追踪"| CORE
CLI -.->|"拦截器链(追踪 / 指标 / 访问日志 / 超时)"| CORE
CORE -->|"trace 上报"| IOtel
CORE -->|"metric 暴露"| IProm
%% ============ 任务调度内部依赖 ============
CTask -->|"生成 ID"| TSnow
CTask -->|"节点注册"| CEtcd
TCron -->|"底层调度"| CTask
TConfig -->|"配置来源"| CEtcd
%% ============ 样式 ============
classDef app fill:#1f77b4,stroke:#0d4f8b,color:#fff,stroke-width:2px;
classDef server fill:#2ca02c,stroke:#1a7a1a,color:#fff;
classDef client fill:#ff7f0e,stroke:#b35a00,color:#fff;
classDef store fill:#9467bd,stroke:#6b3fa0,color:#fff;
classDef registry fill:#17becf,stroke:#0e7f8f,color:#fff;
classDef core fill:#d62728,stroke:#9c1c1e,color:#fff;
classDef tool fill:#7f7f7f,stroke:#5a5a5a,color:#fff;
classDef infra fill:#8c564b,stroke:#5f3a33,color:#fff;
class App app;
class Xgin,Xgrpc,Xhertz,Xasynq,Xmonitor server;
class CEtcd,CGrpc,CRabbit,CFtp client;
class SRedis,SSql,SMongo,SEs,SNull,SProxy,SSession store;
class RInterface,REtcd registry;
class CRatelimit,CResource,CTrace,CMetric,CLogger,CGoroutine,CTask,CCycle,CHooks,CExecutor core;
class TUtil,TCorrect,TNlp,TFilter,TLang,TImg,TSnow,TCron,TWatch,TConfig tool;
class IEtcd,IRabbit,IRedis,ISql,IMongo,IEs,IFtp,IOtel,IProm infra;
分层说明:
| 层 | 目录 | 职责 |
|---|---|---|
| 应用层 | core/app |
组装 Server/Worker/Job/Executor,信号驱动启停,阶段钩子,注册中心注入 |
| 服务端层 | server/ |
统一封装 Gin / gRPC / Hertz / Asynq / 监控,实现 server.Server 接口 |
| 客户端层 | client/ |
etcd、gRPC、RabbitMQ、FTP/SFTP 客户端,含拦截器链与连接管理 |
| 存储层 | stores/ |
Redis(四模式)、SQL(GORM)、MongoDB、Elasticsearch、可空类型、代理池、会话 |
| 注册中心 | registry/ |
Registry 接口与 etcdv3 实现(租约、服务发现) |
| 治理核心 | core/ |
限流、熔断、追踪、指标、日志、并发编排、分布式任务、生命周期、钩子、执行器 |
| 工具层 | util/ 等 |
通用工具、文本处理、图像、ID 生成、配置加载、文件监控、i18n |
| 外部基础设施 | — | etcd / RabbitMQ / Redis / SQL / MongoDB / ES / FTP·SFTP / OTel / Prometheus |
关键链路:
- 业务请求:应用层
Run启动服务端 → 服务端经客户端层调用下游、经存储层读写数据 → 全部命令穿过治理核心(熔断 → 指标 → 追踪)。 - 服务发现:服务端启动向注册中心登记;gRPC 客户端从注册中心解析目标节点;etcdv3 实现负责租约续期与节点读写。
- 可观测性:trace 上报 OpenTelemetry Collector,metric 暴露给 Prometheus,日志经 logger 多后端异步写出。
- 任务调度:
task依赖snowflake生成任务 ID、依赖 etcd 客户端做节点注册,crontab提供底层 cron 调度。
core/app 负责组装全部组件:
- 应用启动时依次启动注册的 Server、Worker、Job、Executor。
- Server 启动后自动向注册中心登记(
registry.DefaultRegisterer)。 - 监听系统信号(SIGINT/SIGTERM 等),收到信号后执行清理:停止 Server 与 Worker、关闭后台任务、触发阶段钩子。
- 支持
Stop(立即停止)与GracefulStop(优雅停止)两种方式。
- 配置即代码:各组件均以
New()+ 链式WithXxx选项构造,配置项集中、可读、可静态检查。 - 统一生命周期:Server/Worker/Job 均实现框架约定接口,由应用统一管理,业务代码无需关心启停细节。
- 治理内建:存储与客户端命令默认经过熔断器,可开关式挂载指标与追踪,无需业务侧侵入。
- 包注释即文档:每个库包都有
doc.go包注释,导出 API 带 Godoc,可直接用go doc/ pkg.go.dev 查阅。
| 依赖 | 版本要求 | 说明 |
|---|---|---|
| Go | 1.27+ | 见 go.mod 的 go 指令 |
| libvips | 可选 | 仅 img 图像处理包需要;macOS 可用 brew install vips |
| pkg-config | 可选 | 编译 img 包时 libvips 需要 |
go get github.com/abulo/ratel/v3@latestpackage main
import (
"github.com/abulo/ratel/v3/core/app"
"github.com/abulo/ratel/v3/server/xgin"
"github.com/gin-gonic/gin"
)
func main() {
// 1. 构建 Gin 服务端:监听 8080,启用指标与慢查询中间件
httpServer := xgin.New().
WithPort(8080).
WithEnableMetric(true).
WithEnableSlowQuery(true).
Build()
// 2. 注册路由:Server 内嵌 gin.Engine,Gin 原生 API 全部可用
httpServer.GET("/hello", func(c *gin.Context) {
c.JSON(200, gin.H{"message": "Hello, Ratel!"})
})
// 3. 组装应用并启动:阻塞等待退出信号,支持优雅停机
application, err := app.New()
if err != nil {
panic(err)
}
if err := application.Run(httpServer); err != nil {
panic(err)
}
}package main
import (
"github.com/abulo/ratel/v3/core/app"
"github.com/abulo/ratel/v3/server/xgrpc"
)
func main() {
// 构建 gRPC 服务端(Server 内嵌 grpc.Server,原生 gRPC API 可用)
cfg := xgrpc.New()
cfg.Host = "0.0.0.0"
cfg.Port = 50051
cfg.EnableTrace = true
cfg.EnableMetric = true
grpcServer, err := cfg.Build()
if err != nil {
panic(err)
}
// 注册你的服务实现,例如:
// pb.RegisterYourServiceServer(grpcServer, &yourServiceImpl{})
application, err := app.New()
if err != nil {
panic(err)
}
if err := application.Run(grpcServer); err != nil {
panic(err)
}
}package main
import (
"context"
ratelapp "github.com/abulo/ratel/v3/core/app"
"github.com/abulo/ratel/v3/server/xhertz"
"github.com/cloudwego/hertz/pkg/app"
"github.com/cloudwego/hertz/pkg/protocol/consts"
)
func main() {
hertzServer := xhertz.New().
WithPort(8081).
WithEnableMetric(true).
WithEnableTrace(true).
Build()
// Server 内嵌 hertz 引擎,Hertz 原生 API 可用
hertzServer.GET("/hello", func(c context.Context, ctx *app.RequestContext) {
ctx.JSON(consts.StatusOK, map[string]string{"message": "Hello from Hertz!"})
})
application, err := ratelapp.New()
if err != nil {
panic(err)
}
if err := application.Run(hertzServer); err != nil {
panic(err)
}
}注意:
core/app与hertz/pkg/app包名相同,同时导入时需给其中一个加别名(上例使用ratelapp)。
一个应用可以同时托管多个服务端:
func main() {
httpServer := xgin.New().WithPort(8080).Build()
grpcServer := mustBuildGRPC()
monitorServer := xmonitor.New().WithPort(9090).Build() // 独立监控端,暴露 pprof 等
application, err := app.New()
if err != nil {
panic(err)
}
// Run 可接收任意多个 server.Server
if err := application.Run(httpServer, grpcServer, monitorServer); err != nil {
panic(err)
}
}core/app 提供 Application 应用生命周期管理器。
| 方法 | 说明 |
|---|---|
New(fns ...func() error) (*Application, error) |
创建应用,fns 为启动前执行的初始化函数 |
DefaultApp() *Application |
创建默认应用(跳过参数解析与配置加载) |
Serve(s ...server.Server) error |
注册服务端 |
Schedule(w worker.Worker) error |
注册后台工作单元 |
Job(runner job.Runner) error |
注册启动后并发执行的任务 |
Executor(e executor.Executor) |
注册分布式任务执行器 |
SetRegistry(reg registry.Registry) |
设置注册中心 |
Run(servers ...server.Server) error |
启动全部组件并阻塞等待退出信号 |
Stop() error |
立即停止应用 |
GracefulStop(ctx context.Context) error |
优雅停止应用 |
RegisterHooks(stage hooks.Stage, fns ...func()) |
注册生命周期钩子 |
WithOptions(options ...Option) |
应用选项 |
import "github.com/abulo/ratel/v3/core/hooks"
func main() {
// 注册启动钩子(在配置加载前执行)
hooks.Register(hooks.Stage_BeforeLoadConfig, func() {
// 自定义初始化逻辑
})
application, err := app.New()
// ...
}钩子按阶段分组,同一阶段按注册顺序逆序执行(模拟 defer 语义)。
Run 会监听系统信号:
- SIGINT / SIGTERM:触发优雅停止流程。
- 停止流程:执行
BeforeStop钩子 → 停止全部 Server/Worker → 等待后台任务结束 → 执行AfterStop钩子 → 关闭生命周期。
所有服务端统一实现 server.Server 接口,并支持:
| 方法 | 说明 |
|---|---|
Serve() error |
启动服务并阻塞监听 |
Stop() error |
立即停止 |
GracefulStop(ctx context.Context) error |
优雅停止(等待在途请求完成) |
Info() *server.ServiceInfo |
返回注册信息(名称、地址、协议、标签) |
Health() bool |
健康检查 |
基于 Gin 的 HTTP 服务端。
server := xgin.New().
WithHost("0.0.0.0"). // 监听主机
WithPort(8080). // 监听端口
WithMode(gin.ReleaseMode). // 运行模式(默认 ReleaseMode)
WithDeployment("prod"). // 部署组(服务注册流量隔离)
WithServiceAddress(""). // 注册中心登记地址,空则用 Host:Port
WithEnableMetric(true). // 启用指标采集中间件
WithEnableTrace(true). // 启用链路追踪中间件
WithEnableSlowQuery(true). // 启用慢查询与 panic 恢复中间件
WithSlowQueryThresholdInMilli(500). // 慢查询阈值(毫秒)
Build()配置项:
| 字段 | 默认值 | 说明 |
|---|---|---|
Host |
空 | 监听主机地址 |
Port |
0 | 监听端口,构建时由实际绑定端口回填 |
Mode |
ReleaseMode |
Gin 运行模式(ReleaseMode/DebugMode/TestMode) |
EnableMetric |
false | 指标采集中间件 |
EnableTrace |
false | 服务端链路追踪中间件 |
EnableSlowQuery |
false | 慢请求记录与 panic 恢复中间件 |
SlowQueryThresholdInMill |
500 | 慢查询阈值(毫秒) |
Deployment |
空 | 部署组 |
ServiceAddress |
空 | 注册中心登记地址 |
WebSocket:
type MyWebSocket struct {
// 实现自己的协议升级与处理逻辑
}
// 注册 WebSocket 处理器为 GET 路由
server.Upgrade(&MyWebSocket{Pattern: "/ws"})基于 gRPC 的服务端。
cfg := xgrpc.New()
cfg.Host = "0.0.0.0"
cfg.Port = 50051
cfg.Network = "tcp4"
cfg.EnableTrace = true
cfg.EnableMetric = true
cfg.EnableTLS = false // 开启后需配置 CaFile/CertFile/PrivateFile
// 追加拦截器
cfg.WithUnaryInterceptor(myUnaryInterceptor)
cfg.WithStreamInterceptor(myStreamInterceptor)
grpcServer, err := cfg.Build() // 返回 (*Server, error)
// 或 grpcServer := cfg.MustBuild() // 构建失败直接 panic配置项(与 xgrpc 风格一致,字段赋值 + Build):
| 字段 | 默认值 | 说明 |
|---|---|---|
Host / Port |
空 / 0 | 监听地址,端口构建时回填 |
Network |
tcp4 |
监听网络类型 |
Deployment |
constant.DefaultDeployment |
部署组 |
EnableTrace |
false | 服务端链路追踪拦截器 |
EnableMetric |
false | 指标采集拦截器 |
EnableTLS |
false | 双向 TLS 认证 |
CaFile / CertFile / PrivateFile |
空 | TLS 证书文件路径 |
SlowQueryThresholdInMill |
500 | 预留配置项 |
panic 恢复: 子包 server/xgrpc/recovery 提供一元与流式恢复拦截器,未配置回调时把 panic 包装为 PanicError 返回,避免单请求 panic 导致进程退出。
基于 CloudWeGo Hertz 的高性能 HTTP 服务端,配置项与 xgin 对齐(WithHost/WithPort/WithMode/WithEnableMetric/WithEnableTrace/WithEnableSlowQuery/WithDeployment/WithServiceAddress/WithSlowQueryThresholdInMilli),Build() 返回内嵌 hertz 引擎的 *Server。
server := xhertz.New().WithPort(8081).Build()
server.GET("/hello", func(c context.Context, ctx *app.RequestContext) {
ctx.JSON(consts.StatusOK, map[string]string{"message": "hello"})
})基于 Asynq 的定时任务与后台任务组件,分 manager 与 worker 两个子包。
manager(定时任务管理器): 按已注册的定时计划周期性将任务写入 Redis 队列。配置项与 xgin/xhertz 对齐(WithHost/WithPort/WithDeployment/WithEnableMetric/WithEnableTrace/WithMode 等),Asynq 运行选项通过 Config.Option 字段传入。
import (
"github.com/abulo/ratel/v3/server/xasynq/manager"
"github.com/hibiken/asynq"
)
mgrCfg := manager.New().
WithHost("0.0.0.0").
WithPort(0)
// Build 前配置 Asynq 运行选项(含 Redis 连接与定时任务注册表)
mgrCfg.Option = asynq.PeriodicTaskManagerOpts{
RedisConnOpt: asynq.RedisClientOpt{Addr: "127.0.0.1:6379"},
// 在此注册定时任务:cronspec -> 任务处理器
}
mgr := mgrCfg.Build() // 实现 server.Server 接口
// application.Run(mgr)worker(任务工作者): 从 Redis 队列拉取任务并按处理器路由表消费。Config.Redis(redis.UniversalClient)、Config.Mux(*asynq.ServeMux)与 Config.Option(asynq.Config)在 Build 前赋值。
import (
"github.com/abulo/ratel/v3/server/xasynq/worker"
"github.com/hibiken/asynq"
"github.com/redis/go-redis/v9"
)
wkCfg := worker.New().
WithHost("0.0.0.0").
WithPort(0)
// Build 前配置 Redis、处理器路由表与运行选项
wkCfg.Redis = redis.NewClient(&redis.Options{Addr: "127.0.0.1:6379"})
wkCfg.Mux = asynq.NewServeMux()
wkCfg.Mux.HandleFunc("task:email", func(ctx context.Context, t *asynq.Task) error {
// 处理邮件任务
return nil
})
wkCfg.Option = asynq.Config{Concurrency: 10}
wk := wkCfg.Build() // 实现 server.Server 接口
// application.Run(wk)独立的监控与治理 HTTP 服务端,在独立路由表上挂载 pprof 性能分析、已注册路由清单与模块构建信息等内置治理接口。
monitorServer := xmonitor.New().
WithPort(9090).
Build()
// application.Run(httpServer, monitorServer)基于 go.etcd.io/etcd/client/v3 的 etcd 客户端封装。
import (
"github.com/abulo/ratel/v3/client/etcdv3"
)
// Config 使用字段赋值或 Set 前缀方法填充(非 With 链式)
cfg := etcdv3.New() // 默认 BasicAuth=false、ConnectTimeout=5s、Secure=false
cfg.SetEndpoints([]string{"127.0.0.1:2379"})
cfg.SetBasicAuth(true)
cfg.SetUserName("root")
cfg.SetPassword("secret")
cfg.SetConnectTimeout(5 * time.Second)
client, err := etcdv3.NewClient(cfg)
if err != nil {
panic(err)
}Client 能力(内嵌原生 clientv3.Client,原生 API 直接可用):
| 方法 | 说明 |
|---|---|
GetKeyValue(ctx, key) |
读取单个键 |
GetValues(ctx, keys...) |
批量读取多个键 |
GetPrefix(ctx, prefix) |
前缀读取,返回 map[string]string |
DelPrefix(ctx, prefix) |
前缀删除 |
GetLeaseSession(ctx, opts...) |
创建租约会话(keepalive) |
NewMutex(key, opts...) |
创建分布式互斥锁 |
WatchPrefix(ctx, prefix) |
前缀变更监听 |
分布式锁:
mutex, err := client.NewMutex("/lock/order")
if err != nil {
panic(err)
}
if err := mutex.Lock(ctx); err != nil {
panic(err)
}
defer mutex.Unlock(ctx)
// 临界区基于 etcd 服务发现的 gRPC 客户端。
import (
grpcc "github.com/abulo/ratel/v3/client/grpc"
regEtcd "github.com/abulo/ratel/v3/registry/etcdv3"
)
// 1. etcd 服务发现配置(注意:使用 registry/etcdv3 的 Config;
// Set 方法链式调用会返回内嵌的 client 配置类型,应分开调用保持类型)
etcdCfg := regEtcd.New()
etcdCfg.SetEndpoints([]string{"127.0.0.1:2379"})
// 2. gRPC 客户端配置
conn := grpcc.New().
SetName("order-service"). // 客户端实例名(单例键与标签)
SetAddress("order.svc"). // 目标服务名(由 etcd 解析器解析)
SetBalancerName("p2c"). // 负载均衡:roundrobin / swr / p2c
SetEtcd(etcdCfg). // 必填:etcd 服务发现
SetReadTimeout(1 * time.Second). // 单次调用超时
SetSlowThreshold(600 * time.Millisecond).
SetEnableTraceInterceptor(true).
SetEnableMetricInterceptor(true).
SetEnableAccessInterceptor(true).
SetEnableTimeoutInterceptor(true).
MustBuild() // 或 Build() 返回 (conn, error)配置项:
| 字段 | 默认值 | 说明 |
|---|---|---|
BalancerName |
roundrobin |
负载均衡策略(roundrobin/swr/p2c) |
DialTimeout |
3s | 拨号超时 |
ReadTimeout |
1s | 单次调用超时(超时拦截器用) |
SlowThreshold |
600ms | 慢调用判定阈值 |
EnableDebug |
false | 调试拦截器(打印地址/方法/响应/错误) |
EnableTraceInterceptor |
false | 链路追踪拦截器 |
EnableAidInterceptor |
false | 应用 ID 元数据透传 |
EnableTimeoutInterceptor |
false | 调用超时与慢调用统计 |
EnableMetricInterceptor |
false | 指标采集 |
EnableAccessInterceptor |
false | 访问日志拦截器 |
Etcd |
必填 | etcd 服务发现配置,缺失会空指针 |
负载均衡: client/grpc/balancer 提供 SWR(平滑加权轮询)与 P2C(随机二抽样最少负载)均衡器,p2c 子包按在途请求数选择负载更低的节点。
基于 streadway/amqp 的 RabbitMQ 客户端封装,支持断线自动重连。
import (
"github.com/abulo/ratel/v3/client/rabbitmq"
"github.com/streadway/amqp"
)
// 1. 建立连接(可断线重连)
conn, err := rabbitmq.Dial("amqp://guest:guest@127.0.0.1:5672/", rabbitmq.DefaultTimesRetry())
if err != nil {
panic(err)
}
// 2. 声明并绑定队列(队列名、路由键、交换器)
queue := rabbitmq.NewQueueBuilder(conn).
SetQueueDeclareOpts(func(builder *rabbitmq.QueueDeclareOptsBuilder) *rabbitmq.QueueDeclareOpts {
return builder.SetDurable(true).SetAutoDelete(false).Build()
}).
Build()
if err := queue.DeclareAndBind("task.queue", "task.key", "exchange"); err != nil {
panic(err)
}
// 3. 获取通道并发送消息(通道由连接管理,复用常驻通道)
ch, err := conn.Channel()
if err != nil {
panic(err)
}
if err := ch.SendOpts("exchange", "task.key", []byte("hello"), rabbitmq.DefaultSendOpts()); err != nil {
// 发送失败处理
}
// 4. 消费消息(ConsumerFunc 返回 true 终止消费)
// ch.ReceiveOpts("task.queue", func(delivery *amqp.Delivery) bool {
// 处理消息,返回 true 表示确认并退出
// return true
// }, rabbitmq.DefaultReceiveOpts())关键类型:
| 类型 | 说明 |
|---|---|
Connection |
可断线重连的连接,Dial/NewConnection 构造 |
Channel |
复用连接的通道,Connection.Channel() 获取;提供 Send/SendOpts/Receive/ReceiveOpts |
QueueBuilder |
队列声明与绑定 Builder(SetQueueDeclareOpts/SetQueueBindOpts/SetRetryable/Build) |
Queue |
队列载体,DeclareAndBind/RetryDeclareAndBind 声明绑定 |
Producer / Consumer |
便捷生产者(Send)与消费者(Receive/Get)封装 |
SendOptsBuilder / ReceiveOptsBuilder / QueueDeclareOptsBuilder / QueueBindOptsBuilder |
选项 Builder |
TimesRetry / CtxRetry |
重试策略 |
MessagePlainTransient 等 |
常用消息工厂 |
文件传输客户端:
// FTP:配置字段 + Config.New 拨号 + Login 认证
ftpConfig := &ftp.Config{
Host: "127.0.0.1",
Port: "21",
User: "user",
Password: "pass",
Timeout: 10 * time.Second,
}
ftpClient, err := ftpConfig.New()
if err != nil {
panic(err)
}
defer ftpClient.Quit()
if err := ftpClient.Login(); err != nil {
panic(err)
}
// SFTP:配置字段 + Config.New(底层为 SSH 连接 + SFTP 通道)
sftpConfig := &sftp.Config{
Host: "127.0.0.1",
Port: "22",
User: "user",
Password: "pass",
Timeout: 10 * time.Second,
}
sftpClient, err := sftpConfig.New()
if err != nil {
panic(err)
}
defer sftpClient.SFTPClient.Close()两个客户端均提供目录切换、文件/目录增删查、上传下载(SFTP 支持递归目录与传输进度统计)等操作。
基于 go-redis 的 Redis 客户端封装,支持四种连接模式。
import "github.com/abulo/ratel/v3/stores/redis"
// 单节点
client, err := redis.NewRedisClient(
redis.WithClientType("normal"),
redis.WithAddr("127.0.0.1:6379"),
redis.WithPassword(""),
redis.WithDatabase(0),
redis.WithPoolSize(20),
)
// 集群
client, err = redis.NewRedisClient(
redis.WithClientType("cluster"),
redis.WithHosts([]string{"127.0.0.1:7000", "127.0.0.1:7001", "127.0.0.1:7002"}),
)
// 哨兵
client, err = redis.NewRedisClient(
redis.WithClientType("failover"),
redis.WithMasterName("mymaster"),
redis.WithHosts([]string{"127.0.0.1:26379", "127.0.0.1:26380"}),
)
// 分片
client, err = redis.NewRedisClient(
redis.WithClientType("ring"),
redis.WithAddrs(map[string]string{
"shard1": "127.0.0.1:6379",
"shard2": "127.0.0.1:6380",
}),
)配置项(Option):
| 选项 | 说明 |
|---|---|
WithClientType |
normal(单节点)/cluster/failover/ring |
WithAddr |
单节点地址 host:port |
WithHosts |
集群/哨兵节点列表 |
WithAddrs |
分片名称到地址映射 |
WithMasterName |
哨兵主节点名称 |
WithDatabase |
数据库编号 |
WithPassword |
连接密码 |
WithDialTimeout / WithReadTimeout / WithWriteTimeout |
超时配置 |
WithPoolSize / WithPoolTimeout / WithIdleTimeout / WithIdleCheckFrequency / WithConnMaxLifetime |
连接池配置 |
WithEnableMetric / WithEnableTrace |
指标与追踪钩子 |
WithName |
实例名称(单例键) |
命令调用: 命令按数据类型组织为分组方法(字符串、哈希、列表、集合、有序集合、位图、流、地理、JSON、搜索、脚本、Pub/Sub 等),统一经熔断器执行;键不存在等可接受错误不会作为失败上报。底层 go-redis 客户端可通过 redis.OriginalClient(client) 获取。
基于 GORM 的关系型数据库客户端封装,支持 MySQL、PostgreSQL、ClickHouse。
import "github.com/abulo/ratel/v3/stores/sql"
// 1. 配置并打开连接:NewClient 只装配配置,Open 才建立连接(返回内嵌 *gorm.DB 的 ClientManager)
client, err := sql.NewClient(
sql.WithDriverName(sql.MySQLDriverName), // 或 sql.PostgreSQLDriverName / sql.ClickHouseDriverName
sql.WithHost("127.0.0.1"),
sql.WithPort("3306"),
sql.WithUsername("root"),
sql.WithPassword("secret"),
sql.WithDatabase("mydb"),
sql.WithCharset("utf8mb4"),
sql.WithParseTime(true),
sql.WithMaxOpenConns(100),
sql.WithMaxIdleConns(20),
sql.WithMaxLifetime(1*time.Hour),
sql.WithEnableMetric(true),
sql.WithEnableTrace(true),
)
if err != nil {
panic(err)
}
manager, err := client.Open() // (*ClientManager, error)
if err != nil {
panic(err)
}
// 2. 执行 GORM 查询(manager 内嵌 *gorm.DB,GORM 原生 API 可用)
// manager.Model(&User{}).Find(&users)配置项(Option):
| 选项 | 说明 |
|---|---|
WithDriverName |
mysql / postgres / clickhouse |
WithHost / WithPort / WithUsername / WithPassword / WithDatabase |
连接信息 |
WithCharset / WithParseTime / WithTimeZone / WithSslMode |
驱动特定 DSN 参数 |
WithDialTimeOut / WithReadTimeOut |
ClickHouse 超时 |
WithMaxOpenConns / WithMaxIdleConns / WithMaxIdleTime / WithMaxLifetime |
连接池 |
WithEnableDebug / WithEnableMetric / WithEnableTrace |
开关 |
查询辅助:
// 分页参数载体(字段为指针,未设置时取值返回错误)
offset := int64(0)
limit := int64(20)
page := &sql.Pagination{Offset: &offset, Limit: &limit}
// 范围与排序参数载体
scope := &sql.Scope{Start: ptr("2024-01-01"), End: ptr("2024-12-31")}
sort := &sql.Sort{Name: ptr("created_at"), Desc: ptr(true)}
// 取值后拼入 GORM 链式查询(manager 内嵌 *gorm.DB)
offsetVal, _ := page.GetOffset()
limitVal, _ := page.GetLimit()
sortName, _ := sort.GetName()
manager.WithContext(ctx).Model(&User{}).
Offset(int(offsetVal)).
Limit(int(limitVal)).
Order(sortName).
Find(&users)
ptr为取地址辅助(func ptr[T any](v T) *T { return &v }),可按需自行定义。
拦截器: sql.MetricInterceptor() 与 sql.TraceInterceptor() 可通过 sql.RegisterInterceptor(manager, client, interceptors...) 注册,自动采集 SQL 指标与链路追踪(Client.Open 已在 EnableMetric/EnableTrace 开启时自动装配)。
基于 mongo-driver 的 MongoDB 客户端封装。
import "github.com/abulo/ratel/v3/stores/mongodb"
mongoClient, err := mongodb.NewMongoDBClient("mongodb://127.0.0.1:27017",
mongodb.WithTimeout(5*time.Second),
mongodb.WithMaxPoolSize(100),
mongodb.WithMinPoolSize(10),
mongodb.WithMaxConnIdleTime(1*time.Minute),
)
if err != nil {
panic(err)
}
// 获取集合增强句柄(collection 为集合名,库名取自客户端 Name)
model, err := mongoClient.NewModel("users")
if err != nil {
panic(err)
}
// model.Collection 为 *mongodb.DecoratedCollection,包装了熔断、指标与追踪DecoratedCollection 能力:
- 链式条件构造(封装原生 Filter 构建)。
- 故障保护:操作经熔断器执行。
- 指标采集与链路追踪自动挂载。
BeforeCreate/BeforeUpdate在写入前完成结构体到 BSON 文档的转换与_id生成。
基于 olivere/elastic v7 的 Elasticsearch 客户端封装。
import "github.com/abulo/ratel/v3/stores/elasticsearch"
esClient := elasticsearch.NewClient(&elasticsearch.Config{
URL: []string{"http://127.0.0.1:9200"},
Username: "elastic",
Password: "secret",
EnableMetric: true,
EnableTrace: true,
})
// esClient 内嵌原生 elastic.Client,全部原生 API 可用
// esClient.Search("index").Query(...).Do(ctx)客户端按节点地址缓存复用;ESTracedTransport 在 HTTP 传输层挂载链路追踪与指标采集,MaxContentLength(64KB)限制参与追踪记录的请求体大小。
提供完整可空基础类型集,用于替代 sql.NullXxx 处理数据库与 JSON 中的空值。
已实现类型: Bool、Byte、Bytes、String、Int、Int8/16/32/64、Uint、Uint8/16/32/64、Float32/64、Time、Date、DateTime、Timestamp、CTime、JSON。
每个类型由三个状态位组成:
- 取值:实际值。
Valid:是否持有非空有效值。Set:是否被显式赋值(包含赋值为 null)。
统一实现 sql.Scanner、driver.Valuer、json.Marshaler、json.Unmarshaler、encoding.TextMarshaler、encoding.TextUnmarshaler 接口;空值在 JSON 中序列化为 null,读写数据库映射为 SQL NULL。
import "github.com/abulo/ratel/v3/stores/null"
type User struct {
ID int64 `json:"id"`
Name null.String `json:"name"`
Email null.String `json:"email"`
}
// JSON 空值处理
b, _ := json.Marshal(User{ID: 1, Name: null.StringFrom("ratel"), Email: null.String{}})
// {"id":1,"name":"ratel","email":null}按分组注册与获取各类数据存储后端的代理池。
import "github.com/abulo/ratel/v3/stores/proxy"
p := proxy.NewProxy()
// 初始化阶段:构造代理载体并注入底层客户端,再注册到代理池
redisProxy := proxy.NewRedis()
redisProxy.Store(redisClient)
p.StoreRedis("default", redisProxy)
mongoProxy := proxy.NewMongoDB()
mongoProxy.Store(mongoClient)
p.StoreMongoDB("default", mongoProxy)
esProxy := proxy.NewElasticSearch()
esProxy.Store(esClient)
p.StoreElasticSearch("default", esProxy)
// SQL 代理支持读写分离:SetWrite/SetRead 装配 *gorm.DB,Write/Read 随机选库
sqlProxy := proxy.NewSQL()
sqlProxy.SetWrite(sqlClient) // 写库(必填)
sqlProxy.SetRead(sqlReadReplica) // 读库(可选,缺省回退写库)
p.StoreSQL("write", sqlProxy)
// 运行期按分组取出使用
r := p.LoadRedis("default") // *redis.Client
m := p.LoadMongoDB("default") // *mongodb.MongoDB
e := p.LoadElasticSearch("default") // *elasticsearch.Client
s := p.LoadSQL("write") // *proxy.SQL
db := s.Write() // 随机写库;读多库场景用 s.Read()SQL 代理额外支持写库与读库列表及随机选库(读写分离)。
基于 Redis 的会话存储,整份会话以 JSON 形式保存在单个 Redis 键下。
import "github.com/abulo/ratel/v3/stores/session"
sess := &session.Session{
Driver: redisClient, // 底层 Redis 客户端,不可为 nil
Name: "session:user:1001",
TTL: 3600, // 秒,0 表示不过期
}
// 点分路径读写嵌套字段
_ = sess.Put(ctx, "profile.name", "ratel")
_ = sess.Put(ctx, "profile.level", 3)
name := sess.Get(ctx, "profile.name") // "ratel"
// 删除字段 / 销毁整份会话
sess.Remove(ctx, "profile.level")
sess.Destroy(ctx)令牌桶限流实现。
import "github.com/abulo/ratel/v3/core/ratelimit"
// 固定间隔填充:每 100ms 补充 1 个令牌,容量 100
bucket := ratelimit.NewBucket(100*time.Millisecond, 100)
// 固定速率填充:每秒补充 rate 个令牌
bucket = ratelimit.NewBucketWithRate(1000, 100)
// 每次补充量子:每 100ms 补充 5 个令牌
bucket = ratelimit.NewBucketWithQuantum(100*time.Millisecond, 100, 5)Bucket 方法:
| 方法 | 行为 |
|---|---|
Take(count) |
取令牌,返回等待时长;桶空时按需等待 |
TakeMaxDuration(count, maxWait) |
限时等待取令牌,超时返回 (0, false) |
TakeAvailable(count) |
非阻塞取令牌,返回实际取到的数量 |
Wait(count) |
阻塞直到取到令牌(无返回值) |
WaitMaxDuration(count, maxWait) |
限时等待,返回是否在时限内取到(bool) |
Available() / Capacity() / Rate() |
查询当前可用令牌、容量、速率 |
限流 Reader/Writer:
limitedReader := ratelimit.Reader(r, bucket) // 限制读取速率
limitedWriter := ratelimit.Writer(w, bucket) // 限制写入速率桶内部加锁,可被多个 goroutine 并发使用。
基于 Google SRE 过载保护模型的自适应熔断器。
import "github.com/abulo/ratel/v3/core/resource"
// 1. 获取或创建命名熔断器
breaker := resource.GetBreaker("my-service")
// 2. 包装业务调用
err := breaker.Do(func() error {
return callDownstream()
})
// 3. 自定义错误判定:只有指定错误才算失败
err = breaker.DoWithAcceptable(func() error {
return callDownstream()
}, func(err error) bool {
return errors.Is(err, context.DeadlineExceeded)
})
// 4. 降级回调:熔断时执行 fallback
err = breaker.DoWithFallback(func() error {
return callDownstream()
}, func(err error) error {
return fallbackResult()
})
// 5. 手动管理请求生命周期
promise, err := breaker.Allow()
if err != nil {
return resource.ErrServiceUnavailable
}
defer promise.Reject("failed") // 或成功后 promise.Accept();Accept/Reject 须且仅调用其一
// 业务逻辑Breaker 接口:
| 方法 | 说明 |
|---|---|
Allow() (Promise, error) |
放行时返回 Promise,成功调用 Accept,失败调用 Reject |
Do(req) |
放行时执行 req,拒绝时返回错误;panic 记为失败后重抛 |
DoWithAcceptable(req, acceptable) |
自定义错误是否视为成功 |
DoWithFallback(req, fallback) |
拒绝时执行降级回调 |
DoWithFallbackAcceptable(...) |
组合降级与自定义判定 |
其它资源组件:
// SingleFlight 防击穿
sf := resource.NewSingleFlight()
v, err := sf.Do("key", func() (any, error) { return loadFromDB() })
// 批量错误聚合
batch := &resource.BatchError{}
batch.Add(err1)
batch.Add(err2)
if err := batch.Err(); err != nil { ... }
// 资源管理器(按名称管理可关闭资源)
manager := resource.NewResourceManager()core/goroutine 提供 goroutine 编排与安全执行工具。
| 函数 | 行为 |
|---|---|
Go(fn) |
安全启动 goroutine(自动捕获 panic) |
DelayGo(delay, fn) |
延迟启动 |
SafeGo(fn, rec) |
启动并回调恢复函数处理 panic |
GoDirect(fn, args...) |
反射调用任意函数 |
Serial(fns...) / SerialWithError(fns...) |
串行执行 |
Parallel(fns...) |
并行执行,返回等待函数 |
ParallelWithError(fns...) / ParallelWithErrorChan(fns...) |
并行并收集错误 |
RestrictParallel(restrict, fns...) |
限流并发 |
RestrictParallelWithErrorChan(concurrency, fns...) |
限流并发收集错误 |
import "github.com/abulo/ratel/v3/core/goroutine"
goroutine.Go(func() {
// 安全执行,panic 不会导致进程退出
})
// 并行执行并等待
wait := goroutine.Parallel(
func() { processA() },
func() { processB() },
func() { processC() },
)
wait()// cycle:并发生命周期控制器
import "github.com/abulo/ratel/v3/core/cycle"
cyc := cycle.NewCycle()
cyc.Run(func() error { /* 后台任务 */ })
cyc.Run(func() error { /* 另一个后台任务 */ })
// 等待全部任务结束并获取错误
if err := <-cyc.Wait(); err != nil { ... }// hooks:分阶段钩子(逆序执行,defer 语义)
import "github.com/abulo/ratel/v3/core/hooks"
hooks.Register(hooks.Stage_BeforeRun, func() { /* ... */ })
hooks.Register(hooks.Stage_AfterStop, func() { /* ... */ })
hooks.Do(hooks.Stage_BeforeRun)基于 logrus 的进程内全局日志器。
import "github.com/abulo/ratel/v3/core/logger"
logger.Logger.Info("application started")
logger.Logger.WithFields(logrus.Fields{
"user_id": 123,
"action": "login",
}).Error("operation failed")多后端异步输出(钩子):
import (
"github.com/abulo/ratel/v3/core/logger"
eslogger "github.com/abulo/ratel/v3/core/logger/es"
mongologger "github.com/abulo/ratel/v3/core/logger/mongo"
sqllogger "github.com/abulo/ratel/v3/core/logger/sql"
)
// Elasticsearch 钩子(构造失败会 panic)
esHook := eslogger.New(eslogger.WithClient(esClient))
logger.Logger.AddHook(esHook)
// MongoDB 钩子
mongoHook := mongologger.New(mongologger.WithClient(mongoClient))
logger.Logger.AddHook(mongoHook)
// SQL 钩子
sqlHook := sqllogger.New(sqllogger.WithDB(gormDB))
logger.Logger.AddHook(sqlHook)日志条目由 core/logger/queue 的异步队列在后台写入,不阻塞业务调用;core/logger/entry 定义标准化的日志条目结构(主机名、时间戳、调用位置、级别、附加字段)。
基于 Prometheus 的指标采集封装,命名空间缺省为 ratel,构造时自动注册到默认注册器。
import "github.com/abulo/ratel/v3/core/metric"
// 预置向量(标签按定义顺序:type、method、client、code)
metric.ServerHandleCounter.Inc("http", "GET", "my-service", "200")
// 自定义向量
counter := metric.NewCounterVec("my_metric_total", []string{"label"})
counter.Inc("value")预置指标:
| 指标 | 说明 |
|---|---|
ServerHandleCounter / ServerHandleSeconds |
服务端请求总数 / 耗时 |
ClientHandleCounter / ClientHandleSeconds |
客户端调用总数 / 耗时 |
JobHandleCounter / JobHandleSeconds |
任务执行总数 / 耗时 |
OpenTelemetry 链路追踪封装。
import (
"github.com/abulo/ratel/v3/core/trace"
"go.opentelemetry.io/otel/propagation"
oteltrace "go.opentelemetry.io/otel/trace"
)
// 初始化全局 TracerProvider
cfg := trace.NewConfig(
trace.WithName("my-service"),
trace.WithEndpoint("127.0.0.1:4317"), // OTLP 端点
trace.WithProtocol("grpc"), // grpc / http
trace.WithSampler(1.0), // 采样率 0-1
)
trace.SetGlobalTracer(cfg.Build())
// 在业务代码中创建 span(carrier 用于注入/提取传播上下文)
tracer := trace.NewTracer(oteltrace.SpanKindServer)
ctx, span := tracer.Start(ctx, "operation", propagation.MapCarrier{})
defer span.End()支持 HTTP/gRPC 两种 OTLP 导出协议,兼容 Jaeger 与 W3C TraceContext 传播格式;提供面向服务端、客户端、生产者、消费者角色的 Tracer 包装。中间件自动注入:xgin/xhertz 服务端中间件、xgrpc 拦截器、各存储与客户端钩子会自动携带追踪上下文。
基于 cron 表达式的定时任务调度器。
import "github.com/abulo/ratel/v3/crontab"
// 1. 创建任务管理器
manager := crontab.NewTaskManager()
// 2. 注册任务(五/六字段 cron 或 @yearly/@monthly 等描述符)
manager.AddTask("hourly-job", crontab.NewTask("hourly-job", "0 * * * *", func(ctx context.Context) error {
// 任务逻辑
return nil
}, crontab.TimeoutOption(30*time.Second))) // 可选超时控制
// 3. 启动调度
manager.StartTask()
// 4. 优雅关闭
<-manager.GracefulShutdown()TaskManager 方法:
| 方法 | 说明 |
|---|---|
AddTask(name, task) |
注册任务 |
DeleteTask(name) / ClearTask() |
删除任务 |
StartTask() / StopTask() |
启动/停止调度 |
GracefulShutdown() |
等待全部任务结束 |
WorkerStart() / WorkerStop() |
实现 worker.Worker 接口,可被应用托管 |
基于 cron 调度器与一致性哈希节点池的分布式定时任务,在集群内分配任务,避免重复执行。
import (
"github.com/abulo/ratel/v3/client/etcdv3"
"github.com/abulo/ratel/v3/core/task"
"github.com/abulo/ratel/v3/core/task/driver"
)
// 1. 创建驱动(Redis 普通键 / Redis 有序集合 / etcd 租约)
etcdClient, _ := etcdv3.NewClient(etcdv3.New().SetEndpoints([]string{"127.0.0.1:2379"}))
drv := driver.NewEtcdDriver(etcdClient)
// 或 drv := driver.NewRedisDriver(redisClient)
// 或 drv := driver.NewRedisZSetDriver(redisClient)
// 2. 构造分布式任务管理器(CronOptionSeconds 等选项经 NewTaskWithOption 传入)
t := task.NewTaskWithOption("order-service", drv, task.CronOptionSeconds())
// 3. 注册任务(AddFunc/AddJob;cron 表达式按 6 段含秒解析)
t.AddFunc("sync-order", "0 */5 * * * *", func() {
// 任务逻辑,集群内仅一个节点执行
})
// 4. 启动
t.Start()核心概念:
- 节点池(NodePool):基于一致性哈希(可配副本数
WithHashReplicas)在集群成员间分配任务;成员变更时自动进入升级状态(NodePoolStateUpgrading)避免任务重复执行。 - 任务恢复:启动时支持恢复(
WithRecoverFunc)与近期任务回放(NewRecentJobPacker)。 - 驱动(driver):
NewRedisDriver/NewRedisZSetDriver/NewEtcdDriver三种节点注册与发现实现。
xxl-job 风格的任务执行器接口与全局管理。
import "github.com/abulo/ratel/v3/core/executor"
// 1. 实现执行器接口(GetAddress/RegXJob/Run/Stop/GracefulStop)
type MyExecutor struct {
address string
}
func (e *MyExecutor) GetAddress() string { return e.address }
func (e *MyExecutor) RegXJob(jobs ...executor.XJob) {}
func (e *MyExecutor) Run() error { return nil }
func (e *MyExecutor) Stop() {}
func (e *MyExecutor) GracefulStop() {}
// 2. 注册执行器并启动
executor.Register(":9999", &MyExecutor{address: ":9999"})
if err := executor.Run(); err != nil { ... }
// 3. 停止
// executor.Stop() 或 executor.GracefulStop()// worker.Worker:后台工作单元(应用托管)
type MyWorker struct{}
func (w *MyWorker) WorkerStart() error { /* 启动 */ }
func (w *MyWorker) WorkerStop() error { /* 停止 */ }
application, _ := app.New()
_ = application.Schedule(&MyWorker{}) // 注册后台工作单元
// job.Runner:启动后并发执行的任务(Run 无返回值,通常为常驻循环)
type MyJob struct{}
func (j *MyJob) Run() { /* 任务逻辑 */ }
_ = application.Job(&MyJob{}) // 注册任务通用工具函数集合(纯函数,可并发调用)。
import "github.com/abulo/ratel/v3/util"
// 字符串与切片
util.InArray("x", []string{"a", "b", "x"}) // true
util.ArrayRemoveRepeatedElement([]string{"a", "a", "b"}) // ["a","b"]
util.Implode(",", []string{"a", "b"}) // "a,b"
util.Explode(",", "a,b") // ["a","b"]
// JSON
util.JSONString(obj) // 序列化(去装箱优化)
util.JSONDecode([]byte(s), &dst) // 反序列化
// 时间
util.Timestamp() // 当前时间戳
util.FormatDateTime(time.Now()) // 格式化时间
util.DateTimeParse(s) // 解析时间
// 数学
util.Max(1, 2) / util.Min(1, 2) // 最大值 / 最小值(float64 可变参数)
util.RandomInt(0, 100) // 随机整数((int, error))
bytes, _ := util.RandomBytes(32) // 随机字节(([]byte, error))
// 文件与网络
util.FileExists(path) // 文件是否存在
util.GetHostByName("example.com") // 域名解析
// 其它
util.ZhCharToPinyin("中国") // 拼音转换
util.Uniqid("prefix_") // 唯一 ID
util.Md5(s) / util.Sha1(s) // 摘要
util.MapToStruct(map[string]any) // 结构转换(返回 *pb.Struct)
util.StructToMap(pbStruct) // 结构转换(返回 map[string]any)涵盖字符串、切片与映射、时间日期、数学计算、文件系统、网络、URL、正则信息提取、随机数、拼音以及 protobuf 结构转换等能力。
雪花算法 int64 唯一 ID 生成器。
import "github.com/abulo/ratel/v3/snowflake"
// 一般应用配置:时间戳 40 位 + 序列 7 位 + 机器 16 位
config := snowflake.CommonConfig
// 或自定义位宽与机器编号
config = snowflake.ConstructConfigWithMachineID(40, 7, 16, 1)
// 生成 ID(原子操作,并发安全)
id := config.GenInt64ID()中英文混排文本的自动排版与清理。
import "github.com/abulo/ratel/v3/correct"
// 排版:CJK 与英文/数字/符号之间自动补空格,规范化全角字符
out := correct.Format("这是一段English文本,包含123数字。")
// 这是一段 English 文本,包含 123 数字。
// 排版 HTML(只处理标签之间的文本节点,保留标签与代码块)
out, err := correct.FormatHTML(htmlBody)
// 反排版(去除自动补充的空格)
orig := correct.Unformat(out)基于 AC 自动机的敏感词处理工具(两套实现)。
// nlpword:检测、过滤、替换
import "github.com/abulo/ratel/v3/nlpword"
filter := nlpword.New()
_ = filter.LoadWordDict("words.txt") // 从文件加载
// filter.LoadNetWordDict(url) // 从网络加载
// filter.AddWord("敏感词") // 程序内添加
replaced := filter.Replace("这句话包含敏感词", '*') // 替换命中词
ok, hit := filter.Validate("测试文本") // 是否含敏感词(返回命中词)
// 或 filter.FindIn(text) (bool, string) / filter.FindAll(text) []string
// filter:扫描器(词表/文件构建,自定义跳过分隔符)
import "github.com/abulo/ratel/v3/filter"
search := filter.Strings([]string{"敏感词1", "敏感词2"}, "@#$%^&*!?,。;:、")
has := search.HasSens([]byte("文本内容")) // 是否含敏感词
hits := search.Find([]byte("文本内容")) // 全部命中收集
replaced = string(search.ReplaceRune([]byte("文本内容"), '*'))多语言消息管理。
import "github.com/abulo/ratel/v3/lang/i18n"
// 初始化默认实例:语言目录 + 默认语言 + 语言映射(键=语言名,值=显示名)
i18n.Init("./locales", "zh-CN", map[string]string{
"zh-CN": "简体中文",
"en-US": "English",
})
// 默认 FileMode 下按 langDir/<语言名>.ini 加载语言文件(DirMode 按语言目录加载)
// 按指定语言翻译(缺失键自动回退到备用语言,支持参数渲染)
msg := i18n.Tr("zh-CN", "hello", "Ratel") // "你好, Ratel"
// 或使用默认语言:i18n.Dt("hello", "Ratel")
// 也可自行构建实例:instance := i18n.NewWithInit(langDir, defLang, languages)图像读取、变换、合成与保存(基于 libvips,需安装依赖)。
import (
"github.com/abulo/ratel/v3/img"
"github.com/disintegration/imaging"
)
image, err := img.OpenLocalFile("input.jpg")
if err != nil {
panic(err)
}
// 链式变换(就地修改源图,方法返回自身):等比缩放 → 居中裁剪 → 高斯模糊
image.Resize(800, 0, imaging.Lanczos)
image.Crop(800, 600, imaging.Center)
image.Blur(5)
// 叠加水印
wm, _ := img.OpenLocalFile("logo.png")
image.AddWaterMark(wm, imaging.Center, 20, 20, 0.5)
// 保存(按文件扩展名推断编码格式;JPEG 质量可用 imaging.JPEGQuality 控制)
if err := img.SaveToFile(image, "output.jpg", imaging.JPEGQuality(80)); err != nil {
panic(err)
}支持缩放、裁剪、模糊、灰度、对比度/亮度/饱和度调整、旋转、粘贴、叠加、水印、JPEG 压缩,以及基于 img/fontx 的文字绘制;方法返回自身支持链式调用。
Go 项目热编译监视(文件变更自动构建并重启)。
import "github.com/abulo/ratel/v3/watch"
err := watch.Watch(ctx, &watch.Options{
// 配置监听目录、入口文件、输出名称、文件后缀与编译参数
})基于 Viper 的配置读取封装。
import "github.com/abulo/ratel/v3/config"
conf := config.New()
_ = conf.LoadDir("./configs") // 目录批量加载
// _ = conf.LoadFile("config.yaml") // 或加载单个文件
// 类型化读取(缺失时返回默认值)
port := conf.Int("server.port", 8080)
name := conf.String("server.name", "ratel")
timeout := conf.Duration("server.timeout", 5*time.Second)支持从单个文件或目录批量加载 JSON、TOML、YAML 配置。
toolkit 是 ratel 的命令行脚手架程序(基于 Cobra),用于项目创建与代码生成。
# 安装
go install github.com/abulo/ratel/v3/toolkit@latest
# 查看版本与帮助
toolkit version
toolkit --help子命令:
| 命令 | 功能 |
|---|---|
toolkit project |
项目脚手架:从远程 layout 仓库克隆模板,生成后端/前端项目,或在现有项目中追加服务目录 |
toolkit module |
数据模型层代码生成:交互式采集模型路径、表名、软删除策略,生成 module/proto/service/convert 四类代码 |
toolkit dao |
DAO 代码生成:读取表元数据,生成 GORM 模型结构体(支持单表/多表) |
toolkit api |
HTTP 接口层代码生成:按 Web 框架(gin/hertz)生成接口处理函数与路由注册片段 |
toolkit vue |
Vue3 + TypeScript 前端代码生成:接口定义、API 请求方法模块、列表页面 |
toolkit build |
热编译:监听目录文件变更,自动重新编译并重启 |
toolkit changelog |
更新日志生成:按约定式提交类型分类整理,写入 CHANGELOG.md |
toolkit upgrade / toolkit init |
脚手架升级与初始化:安装最新 toolkit 本体及 protoc 工具 |
# 示例:交互式创建项目
toolkit project
# 示例:生成 DAO(指定表)
toolkit dao --table users,ordersratel/
├── client/ # 客户端封装
│ ├── etcdv3/ # etcd 客户端(KV/锁/租约/监听)
│ ├── grpc/ # gRPC 客户端(服务发现/负载均衡/拦截器)
│ ├── grpc/balancer/ # SWR、P2C 负载均衡器
│ ├── rabbitmq/ # RabbitMQ 客户端(断线重连)
│ ├── ftp/ # FTP 客户端
│ └── sftp/ # SFTP 客户端
├── config/ # Viper 配置读取
├── core/ # 核心治理能力
│ ├── app/ # 应用生命周期管理
│ ├── logger/ # 日志(es/mongo/sql 后端 + queue 异步队列)
│ ├── metric/ # Prometheus 指标
│ ├── ratelimit/ # 令牌桶限流
│ ├── resource/ # 熔断器、SingleFlight、批量错误、资源管理
│ ├── task/ # 分布式任务与 cron 调度
│ ├── executor/ # xxl-job 风格分布式执行器
│ ├── trace/ # OpenTelemetry 链路追踪
│ ├── goroutine/ # goroutine 编排
│ ├── cycle/ # 并发生命周期控制
│ ├── hooks/ # 生命周期阶段钩子
│ ├── ecode/ # 统一错误码模型
│ ├── singleton/ # 单例存储
│ ├── constant/ # 全局常量
│ ├── env/ # 运行环境元信息
│ ├── hostname/ # 主机名获取
│ ├── call/ # 调用栈信息
│ ├── component/ # 组件抽象
│ └── stack/ # 调用栈工具
├── server/ # 服务端实现
│ ├── xgin/ # Gin HTTP 服务端
│ ├── xgrpc/ # gRPC 服务端
│ ├── xhertz/ # Hertz HTTP 服务端
│ ├── xasynq/ # Asynq 定时任务(manager/worker)
│ └── xmonitor/ # 监控服务端(pprof 等)
├── stores/ # 数据存储
│ ├── redis/ # Redis(单机/集群/哨兵/分片)
│ ├── sql/ # SQL(MySQL/PostgreSQL/ClickHouse)
│ ├── mongodb/ # MongoDB
│ ├── elasticsearch/ # Elasticsearch
│ ├── null/ # 可空类型集
│ ├── proxy/ # 存储代理池
│ └── session/ # Redis 会话存储
├── registry/ # 服务注册与发现(etcdv3 实现)
├── toolkit/ # 命令行脚手架
├── util/ # 通用工具
├── correct/ # 中英文混排校正
├── nlpword/ # 敏感词处理(AC 自动机)
├── filter/ # 敏感词扫描
├── img/ # 图像处理(libvips)
├── lang/ # i18n 与占位类型
├── snowflake/ # 雪花 ID
├── crontab/ # cron 调度器
├── watch/ # 热编译监视
└── worker/ # 后台工作单元与任务
# 克隆项目
git clone https://github.com/abulo/ratel.git
cd ratel
# 安装依赖
go mod download
# 运行单元测试
make test
# 静态检查
make vet # go vet
make errcheck # 错误检查
make lint # revive lint
# 格式化与格式检查
make fmt # gofmt -w
make fmtcheck # gofmt 检查
# 完整构建(fmt + errcheck + lint + build)
make all| 目标 | 说明 |
|---|---|
make all |
完整构建(fmt → errcheck → lint → build) |
make test |
运行单元测试(go test -short) |
make vet |
静态检查(go vet ./...) |
make lint |
revive 检查(自动安装 revive) |
make fmt / make fmtcheck |
格式化 / 格式检查 |
make errcheck |
错误处理检查(自动安装 errcheck) |
make cmt |
导出函数自动注释(gocmt) |
- 使用
gofmt格式化代码,revive做 Lint 检查。 - 导出标识符编写 Godoc 文档注释(包注释统一收敛到
doc.go,以Package xxx开头)。 - 检查所有错误返回,错误处理不吞异常。
- 编写单元测试,覆盖关键路径。
- 提交信息遵循约定式提交:
feat/fix/docs/perf/chore/refactor/test等。
仓库配置了 GitHub Actions(.github/workflows/go.yml),在 push 与 PR 时自动构建并上报 Codecov;release.yml 负责发布流程。
Ratel 在原生框架之上提供统一封装:Server 生命周期管理、自动中间件(指标/追踪/慢查询)、注册中心集成、治理能力(限流/熔断)与配套工具,业务代码无需关心这些基础设施。
Ratel 服务端内嵌原生引擎,Gin/gRPC/Hertz 原生 API 全部可用:
// 替换导入即可,其余代码无需修改
// import "github.com/gin-gonic/gin"
import "github.com/abulo/ratel/v3/server/xgin"// xgin(内嵌 gin.Engine)
server.Use(func(c *gin.Context) {
// 自定义逻辑
c.Next()
})
// xgrpc
cfg.WithUnaryInterceptor(func(ctx context.Context, req any, info *grpc.UnaryServerInfo, handler grpc.UnaryHandler) (any, error) {
// 自定义逻辑
return handler(ctx, req)
})// 在业务代码中直接使用令牌桶
bucket := ratelimit.NewBucketWithRate(1000, 100)
if bucket.TakeAvailable(1) == 0 {
return errors.New("rate limit exceeded")
}import (
"github.com/abulo/ratel/v3/core/app"
"github.com/abulo/ratel/v3/registry"
regEtcd "github.com/abulo/ratel/v3/registry/etcdv3"
)
// 方式一:使用包级默认注册器(初始为本地实现)
application, _ := app.New()
application.SetRegistry(registry.DefaultRegisterer)
// 方式二:生产环境接入 etcd 注册中心
// (Set 方法会返回内嵌的 client 配置类型,应分开调用保持类型)
regConfig := regEtcd.New()
regConfig.SetEndpoints([]string{"127.0.0.1:2379"})
reg, err := regConfig.Build() // 或 regConfig.MustBuild()
if err != nil {
panic(err)
}
application.SetRegistry(reg)
// Server 启动后自动向注册中心登记application.Run() 已内置信号监听与优雅停机:收到 SIGINT/SIGTERM 后自动执行 GracefulStop 流程(停止 Server/Worker、等待后台任务结束、触发钩子)。
仅 img 图像处理包需要 libvips 与 pkg-config;其余包均为纯 Go 依赖。
欢迎以 Issue、Pull Request 或 Discussion 的形式参与贡献。提交 PR 前请确保:
- 通过
make all全部检查。 - 新增或修改的代码带有相应单元测试。
- 导出 API 补充 Godoc 注释,包注释写入
doc.go。 - 保持向后兼容;破坏性变更需在 PR 描述中说明。
Ratel 采用 Apache License 2.0。