beauty

Beauty Framework

Beauty is a Go-based microservices framework designed to simplify the development and deployment of microservices. It provides a unified way to create and manage different types of services including HTTP servers, gRPC servers, and cron jobs.

Prerequisites

Before using the Beauty framework, ensure you have the following installed:

• Go 1.18 or later
• buf for Protocol Buffers (for gRPC services)

# Install buf on macOS
brew install bufbuild/buf/buf

# Install buf on Linux
# See https://buf.build/docs/installation for more options

Installation

# Clone the repository
git clone https://github.com/rushteam/beauty.git

# Install the Beauty CLI tool
cd beauty/tools
go install ./cmd/beauty

Creating a New Project

You can create a new project using the Beauty CLI tool:

# Create a new project
beauty new my-service

The CLI will prompt you to enter:

• Project module name (Go module path)
• Web framework choice (chi or gin)

快速开始

# 创建新项目
beauty new my-service

# 进入项目目录
cd my-service

# 安装依赖
go mod tidy

# 生成 gRPC 代码（如果有 .proto 文件）
make generate

# 运行项目
go run main.go

Project Structure

Beauty 框架采用统一的项目结构，支持 HTTP、gRPC 和 Cron 三种服务类型：

my-service/
├── api/                    # Protocol Buffers 定义
│   ├── user.proto
│   └── v1/
│       ├── user.pb.go
│       ├── user_grpc.pb.go
│       └── user.pb.gw.go
├── buf.gen.yaml           # buf 代码生成配置
├── buf.yaml               # buf 项目配置
├── config/                # 配置文件
│   └── dev/
│       └── app.yaml
├── go.mod
├── main.go                # 应用入口
├── Makefile               # 构建脚本
├── scripts/               # 工具脚本
│   └── generate.sh
└── internal/              # 内部代码
    ├── config/            # 配置管理
    │   └── config.go
    ├── endpoint/          # 服务端点
    │   ├── grpc/          # gRPC 服务
    │   │   └── server.go
    │   ├── handlers/      # HTTP 处理器
    │   │   ├── user.go
    │   │   └── health.go
    │   ├── job/           # 定时任务
    │   │   └── cron.go
    │   └── router/        # HTTP 路由
    │       ├── http.go
    │       ├── middleware.go
    │       └── router.go
    └── infra/             # 基础设施
        ├── conf/          # 配置加载
        │   └── conf.go
        ├── logger/        # 日志
        │   └── logger.go
        ├── middleware/    # 中间件
        │   └── middleware.go
        └── registry/      # 服务注册
            └── registry.go

核心特性：

• 多协议支持: HTTP、gRPC、Cron 三种服务类型
• 代码生成: 基于 Protocol Buffers 自动生成 gRPC 代码
• 服务发现: 支持多种注册中心（etcd / nacos / consul / polaris / k8s），gRPC 与 HTTP 客户端均内置服务发现 + 负载均衡（轮询 / 加权轮询 / 随机）+ 重试换节点
• 配置中心: 统一 conf.New(url) 接入本地文件与远程配置，支持热加载
• 中间件: recovery、cors、compress、health、auth、限流、熔断、超时
• 实时推送: 内置 SSE（pkg/sse）与 WebSocket（pkg/ws）封装，开箱即用
• 实时服务原语: 53 个可独立组合的实时组件（会话/在场/路由/匹配/排名/调度/钱包/审计/通知/事务/Saga/负载均衡/幂等/延迟队列/状态机/ID 生成/直播 PK/计数聚合/寻路/细粒度锁/连击热度/空间索引/退避重试/事件总线/地理编码/抽卡/冷却/环形缓冲/位图/任务成就/等级/小红点等），纯标准库实现；其中 counter/cooldown/idempotency 可通过 WithStore 接 pkg/kvstore(Redis 等)实现跨实例状态共享，从单机原语升级为多实例生产可用。详见下文 Realtime Components
• 流程编排: 轻量 DAG 执行器（pkg/dag），拓扑分层 + 层内并行
• 可观测性: 内置 OpenTelemetry 链路追踪与指标收集（HTTP/gRPC 请求指标由 otelhttp/otelgrpc 自动采集）
• 动态日志: 运行时通过 HTTP 接口调整日志级别，无需重启

Configuration

The framework uses YAML configuration files. The default configuration file is located at config/config.yaml:

app: my-service
http:
  addr: :8080
log:
  level: info
  format: text

Creating Services

Beauty supports multiple types of services:

HTTP Server

import (
    "net/http"
    "github.com/rushteam/beauty"
    "github.com/go-chi/chi/v5"
)

func main() {
    r := chi.NewRouter()
    r.Get("/", func(w http.ResponseWriter, r *http.Request) {
        w.Write([]byte("Hello, World!"))
    })

    app := beauty.New(
        beauty.WithWebServer(
            ":8080",
            r,
            beauty.WithServiceName("my-http-service"),
        ),
    )

    if err := app.Start(context.Background()); err != nil {
        log.Fatalln(err)
    }
}

gRPC Server

import (
    "context"
    "github.com/rushteam/beauty"
    "google.golang.org/grpc"
    pb "your-project/api/v1"
)

type GreeterServer struct {
    pb.UnimplementedGreeterServer
}

func (s *GreeterServer) SayHello(ctx context.Context, req *pb.HelloRequest) (*pb.HelloReply, error) {
    return &pb.HelloReply{Message: "Hello " + req.Name}, nil
}

func main() {
    app := beauty.New(
        beauty.WithGrpcServer(
            ":50051",
            func(s *grpc.Server) {
                pb.RegisterGreeterServer(s, &GreeterServer{})
            },
            beauty.WithServiceName("my-grpc-service"),
        ),
    )

    if err := app.Start(context.Background()); err != nil {
        log.Fatalln(err)
    }
}

Cron Jobs

import (
    "context"
    "github.com/rushteam/beauty"
    "github.com/rushteam/beauty/pkg/service/cron"
)

func main() {
    app := beauty.New(
        beauty.WithCrontab(
            cron.WithJob("@every 1m", func(ctx context.Context) error {
                // Your job logic here
                return nil
            }),
        ),
    )

    if err := app.Start(context.Background()); err != nil {
        log.Fatalln(err)
    }
}

多实例部署:只在 leader 上跑(避免重复执行)

多实例部署下,默认每个实例都会各跑一遍定时任务(重复发奖/重复扣款/重复生成报表)。 用 cron.WithLeaderElector 接入分布式选主,只有当选 leader 的实例会运行任务:

import (
    clientv3 "go.etcd.io/etcd/client/v3"
    "github.com/rushteam/beauty/pkg/infra/etcd"
    "github.com/rushteam/beauty/pkg/service/cron"
)

client, _ := clientv3.New(clientv3.Config{Endpoints: []string{"127.0.0.1:2379"}})
elector := etcd.NewDLock(client) // 基于 etcd 官方 concurrency 包(Session+Election)

app := beauty.New(
    beauty.WithCrontab(
        cron.WithCronHandler("@every 1m", myJob),
        cron.WithLeaderElector(elector, "myservice-cron"), // 同一组实例用同一个 key
    ),
)

失去 leader 身份(进程崩溃/网络分区)时任务立即停止,其余实例自动接管——由 etcd session 租约保证最终只有一个实例在跑。不配置此项时行为不变。单实例部署/本地开发 可用 pkg/dlock.NewMemory() 模拟选举,见 examples/cron-leader。

部署在 k8s 里,不想额外运维 etcd? 用集群自带的选主能力(同一套 coordination.k8s.io/v1 Lease 机制,kube-scheduler 等控制面组件也在用):

import (
    "k8s.io/client-go/rest"
    "k8s.io/client-go/kubernetes"
    beautyk8s "github.com/rushteam/beauty/pkg/infra/k8s"
)

config, _ := rest.InClusterConfig()
client, _ := kubernetes.NewForConfig(config)
elector := beautyk8s.NewElector(client.CoordinationV1(), beautyk8s.WithNamespace("default"))

app := beauty.New(
    beauty.WithCrontab(
        cron.WithCronHandler("@every 1m", myJob),
        cron.WithLeaderElector(elector, "myservice-cron"),
    ),
)

pkg/infra/k8s.Elector 只实现选主(不实现 Locker——k8s 的 leaderelection 语义 本就是"持续参选",没有通用一次性互斥锁原语)。

Service Registration and Discovery

Beauty supports service registration and discovery using etcd or nacos:

import (
    "github.com/rushteam/beauty"
    "github.com/rushteam/beauty/pkg/service/discover/etcdv3"
)

func main() {
    app := beauty.New(
        // Your services here...
        beauty.WithRegistry(etcdv3.NewRegistry(&etcdv3.Config{
            Endpoints: []string{"127.0.0.1:2379"},
            Prefix: "/beauty",
        })),
    )

    if err := app.Start(context.Background()); err != nil {
        log.Fatalln(err)
    }
}

Using DSN

// etcd DSN
a, _ := grpcclient.New(
    context.Background(),
    grpcclient.WithAddr("etcd://user:pass@127.0.0.1:2379/beauty?ttl=10&dial_ms=3000#helloworld.rpc"),
)

// nacos DSN (supports cluster/group/namespace/app_name/weight)
a, _ := grpcclient.New(
    context.Background(),
    grpcclient.WithAddr("nacos://127.0.0.1:8848/helloworld.rpc?app_name=test&cluster=DEFAULT&group=DEFAULT_GROUP"),
)

Tracing and Metrics

Beauty provides built-in support for OpenTelemetry tracing and metrics:

import (
    "github.com/rushteam/beauty"
    "github.com/rushteam/beauty/pkg/service/telemetry"
    "go.opentelemetry.io/otel/exporters/prometheus"
)

func main() {
    metricExporter, err := prometheus.New()
    if err != nil {
        panic(err)
    }

    app := beauty.New(
        // Your services here...
        beauty.WithTrace(), // Enable tracing
        beauty.WithMetric(telemetry.WithMetricReader(metricExporter)), // Enable metrics
    )

    if err := app.Start(context.Background()); err != nil {
        log.Fatalln(err)
    }
}

HTTP/gRPC 请求指标由内置的 otelhttp/otelgrpc instrumentation 自动产出，Go runtime 指标（goroutine、GC、heap）默认开启（telemetry.WithoutMetricRuntime() 可关闭）。生产环境通常用 OTLP 出口：

beauty.WithTrace(telemetry.WithTraceOTLPGRPCExporter()),   // OTLP/gRPC，默认读 OTEL_EXPORTER_OTLP_* 环境变量
beauty.WithMetric(telemetry.WithMetricOTLPGRPCReader()),   // 指标周期上报到 Collector

Exemplars（指标↔链路关联）默认按 trace_based 启用——在已采样的 trace 上下文中产生的指标会带上 trace_id，可在 Grafana 从延迟直方图直接跳到对应 trace。OTLP exporter 默认导出 exemplar；Prometheus 需以 OpenMetrics 格式抓取。可用 telemetry.WithMetricExemplarFilter(exemplar.AlwaysOffFilter) 关闭，或通过环境变量 OTEL_METRICS_EXEMPLAR_FILTER 配置。

Running Multiple Services

Beauty allows you to run multiple services in a single application:

func main() {
    app := beauty.New(
        beauty.WithWebServer(":8080", httpHandler, beauty.WithServiceName("web-service")),
        beauty.WithGrpcServer(":50051", grpcRegistrar, beauty.WithServiceName("grpc-service")),
        beauty.WithCrontab(cronOptions...),
    )

    if err := app.Start(context.Background()); err != nil {
        log.Fatalln(err)
    }
}

Lifecycle Hooks

You can add hooks to be executed at different stages of the application lifecycle:

app := beauty.New(
    // Your services here...
)

// Add a hook to be executed before the application starts
app.Hook(beauty.EventBeforeRun, func(app *beauty.App) {
    // Your code here
})

// Add a hook to be executed after the application stops
app.Hook(beauty.EventAfterRun, func(app *beauty.App) {
    // Your cleanup code here
})

Complete Example

Here's a complete example that combines multiple services:

package main

import (
    "context"
    "log"
    "net/http"

    "github.com/go-chi/chi/v5"
    "github.com/rushteam/beauty"
    "github.com/rushteam/beauty/pkg/service/discover/etcdv3"
    "github.com/rushteam/beauty/pkg/service/telemetry"
    "google.golang.org/grpc"
    pb "your-project/api/v1"
)

type GreeterServer struct {
    pb.UnimplementedGreeterServer
}

func (s *GreeterServer) SayHello(ctx context.Context, req *pb.HelloRequest) (*pb.HelloReply, error) {
    return &pb.HelloReply{Message: "Hello " + req.Name}, nil
}

func main() {
    // HTTP Router
    r := chi.NewRouter()
    r.Get("/", func(w http.ResponseWriter, r *http.Request) {
        w.Write([]byte("Hello, World!"))
    })

    app := beauty.New(
        // HTTP Service
        beauty.WithWebServer(
            ":8080",
            r,
            beauty.WithServiceName("my-http-service"),
        ),
        
        // gRPC Service
        beauty.WithGrpcServer(
            ":50051",
            func(s *grpc.Server) {
                pb.RegisterGreeterServer(s, &GreeterServer{})
            },
            beauty.WithServiceName("my-grpc-service"),
        ),
        
        // Service Registry
        beauty.WithRegistry(etcdv3.NewRegistry(&etcdv3.Config{
            Endpoints: []string{"127.0.0.1:2379"},
            Prefix: "/beauty",
        })),
        
        // Tracing
        beauty.WithTrace(),
    )

    if err := app.Start(context.Background()); err != nil {
        log.Fatalln(err)
    }
}

Configuration Center

Beauty 支持统一的配置加载接口，通过 URL scheme 切换本地文件与远程配置中心：

import (
    "github.com/rushteam/beauty/pkg/conf"
    _ "github.com/rushteam/beauty/pkg/infra/etcd"   // 注册 etcd scheme
    _ "github.com/rushteam/beauty/pkg/infra/nacos"  // 注册 nacos scheme
)

// 本地文件
loader, _ := conf.New("config/app.yaml")

// etcd 远程配置
loader, _ := conf.New("etcd://127.0.0.1:2379/myapp/config.yaml")

// nacos 远程配置
loader, _ := conf.New("nacos://127.0.0.1:8848/myapp.yaml?namespace=dev")

var cfg AppConfig
loader.Unmarshal(&cfg)

// 热加载
loader.Watch(ctx, func() {
    loader.Unmarshal(&cfg)
})

支持 etcd / nacos / consul / polaris，详见 docs/configuration.md。

Dynamic Log Level

运行时通过 HTTP 接口动态调整日志级别，无需重启：

import "github.com/rushteam/beauty/pkg/service/logger"

// 挂载管理接口
mux.Handle("/debug/loglevel", logger.LevelHandler())

// 代码方式
logger.SetLevelByName("debug")

# 查询当前级别
curl http://localhost:8080/debug/loglevel

# 临时开启 debug
curl -X PUT http://localhost:8080/debug/loglevel -d '{"level":"debug"}'

详见 docs/logger.md。

Built-in Middleware

详见 docs/middleware-builtin.md 和 docs/middleware-summary.md。

HTTP Server Options

beauty.WithWebServer(":8080", handler,
    webserver.WithServiceName("api"),
    webserver.WithReadTimeout(30 * time.Second),
    webserver.WithWriteTimeout(30 * time.Second),
    webserver.WithIdleTimeout(90 * time.Second),
    webserver.WithShutdownTimeout(30 * time.Second),
    webserver.WithTLS("cert.pem", "key.pem"),   // 启用 HTTPS
    webserver.WithMiddleware(myMiddleware),
)

gRPC Server Options

beauty.WithGrpcServer(":9090", register,
    grpcserver.WithServiceName("rpc"),
    grpcserver.WithGrpcServerUnaryInterceptor(myInterceptor),
    grpcserver.WithGracefulStopTimeout(10 * time.Second),
    grpcserver.WithTLS("cert.pem", "key.pem"),
    // Keepalive 参数已内置合理默认值
)

Realtime Components

beauty 在 pkg/ws / pkg/sse 之上提供一组可独立组合的实时服务原语，覆盖长连接会话、在线状态、消息路由、匹配组队、排行榜、任务调度、虚拟账户、操作审计、离线通知、周期榜单、临时小队、版本化存储、社交图谱、频道历史、会话令牌、DB 错误翻译、可靠 Webhook、断线重连、状态广播、短期 TTL KV、跨域事务等典型场景。均为纯标准库实现，遵循 beauty 风格（泛型 + 函数式 Option + 中文 doc）。

包按"通用 vs 业务"分两个命名空间：

• pkg/ — 通用实时原语（不预设业务语义）
• pkg/domain/ — 业务实体（预设了业务模型：货币 / 通知 / 小队 / 赛季榜 / 存档 / 社交 / 频道）

通用原语（pkg/）

业务实体（pkg/domain/）

各包各司其职，无强耦合：可以只用 ws/session 做一个 echo 房间，也可以把 presence + router + ws/session 串起来做一个 IM 频道，用 match + matchmaker 做权威对战大厅，再用 domain/wallet + domain/notification + audit 补齐账户、通知与合规，用 txn 把跨域写操作原子化。每个包在 examples/<name>/ 下都有可运行的 demo。

组合示例：examples/live-pk 用 versus + idempotency + counter + tally + keyedmutex + eventbus + idgen 搭了一个多房间直播 PK 后端(多局并行 + 送礼幂等去重 + 配额防刷 + 实时比分 SSE + 点赞高频聚合 + 全局 PK 生命周期事件),展示原语如何协作。

详见 docs/realtime-components.md。

Documentation

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.