go-platform-kit

README

go-platform-kit

可复用的平台基础设施套件。framework 是唯一入口，自动编排 logger、中间件链、第三方组件的生命周期。

架构总览

main.go
  ├── config.Load[T]()          // YAML + env 加载
  ├── framework.New(cfg)        // logger 初始化 + 中间件链
  ├── fw.Init(connector...)     // 第三方组件初始化
  ├── registerRoutes(engine)    // 路由注册
  └── fw.RunWithSignal(addr)    // 启动 + 优雅关闭

Layer 架构

handler/  → 接收请求、调用 service、返回响应
service/  → 业务逻辑、调用 repo
repo/     → 数据访问（connector 提供客户端）

快速开始

package main

import (
    "github.com/AI-Hub-QM/go-platform-kit/config"
    "github.com/AI-Hub-QM/go-platform-kit/connector"
    "github.com/AI-Hub-QM/go-platform-kit/framework"
    "github.com/AI-Hub-QM/go-platform-kit/httpx"
    "github.com/AI-Hub-QM/go-platform-kit/logger"
)

type MyConfig struct {
    Server struct {
        Port int    `mapstructure:"port"`
        Env  string `mapstructure:"env"`
        Name string `mapstructure:"name"`
    } `mapstructure:"server"`
    DynamoDB struct {
        Region      string `mapstructure:"region"`
        Endpoint    string `mapstructure:"endpoint"`
    } `mapstructure:"dynamodb"`
}

func main() {
    // 1. 加载配置
    cfg, err := config.Load[MyConfig]("")
    if err != nil {
        logger.Fatal("load config failed", "err", err)
    }

    // 2. 创建 Framework
    fw := framework.New(framework.Config{
        Name: cfg.Server.Name,
        Env:  cfg.Server.Env,
    })

    // 3. 初始化组件
    fw.Init(
        connector.DynamoDB.Initializer(ctx, connector.DynamoDBConfig{
            Region:   cfg.DynamoDB.Region,
            Endpoint: cfg.DynamoDB.Endpoint,
        }),
    )

    // 4. 注册路由
    svc := service.New(connector.DynamoDB.Client())
    h := handler.New(svc)
    fw.Engine().GET("/user/:id", httpx.H(h.GetUser))

    // 5. 启动
    fw.RunWithSignal(":8080")
}

子包

包	能力
framework	唯一入口：Config → New → Init → Engine → Run/Shutdown
httpx	gin 响应封装：Success / Error / H() + Context wrapper
apperror	统一业务错误（Code/BizCode/Reason/Message/Metadata）
config	泛型配置加载（viper YAML + godotenv + env overlay）
logger	结构化 slog logger，context 自动注入 requestId + traceId
connector	第三方组件单例：DynamoDB / SLS / RevenueCat / OneSignal
jwt	JWT 签发验证 + TokenManager（Access+Refresh）+ 吊销管理
oauth	Google / Apple OAuth 验证
xtrace	AWS X-Ray 追踪（HTTP client wrapper / SDK v2 middleware）
circuitbreaker	三态熔断器
analytics	打点事件（EventEmitter + Log/SLS/Noop 实现）
r2	Cloudflare R2（S3 协议）客户端

错误体系

预定义错误（9xxx 段）

apperror.ErrBadRequest         // 400, BizCode=9001
apperror.ErrUnauthorized       // 401, BizCode=9002
apperror.ErrNotFound           // 404, BizCode=9004
apperror.ErrInternal           // 500, BizCode=9006
apperror.ErrPaymentRequired    // 402, BizCode=9007
apperror.ErrServiceUnavailable // 503, BizCode=9008

业务自定义错误（1000-8999 段）

var (
    ErrUserNotFound    = apperror.New(404, 1001, "USER_NOT_FOUND", "user not found")
    ErrInvalidPassword = apperror.New(400, 1002, "INVALID_PASSWORD", "password too weak")
)

错误码范围

范围	模块
9001-9009	通用 HTTP 错误
9101-9199	DynamoDB
9201-9299	R2 / Storage
9301-9399	RevenueCat
9401-9499	Auth / JWT
9501-9599	Subscription
9601-9699	Event / Session
1000-8999	业务自定义

使用方式

// 从预定义派生
return apperror.ErrNotFound.WithFormat("user %s not found", id)

// 类型化构造器
return apperror.BadRequest(0, "INVALID_PARAMS", "name is required")

// 判断
if apperror.IsNotFound(err) { ... }
if errors.Is(err, apperror.ErrNotFound) { ... }
code := apperror.Code(err)

HTTP 响应

JSON 格式

成功:

{"success": true, "data": {...}, "request_id": "req-1", "path": "/api/user"}

错误:

{"success": false, "error": "NOT_FOUND", "error_code": 9004, "message": "user not found", "request_id": "req-1", "path": "/api/user"}

Hades 模式（推荐）

func (h *Handler) GetUser(c *httpx.Context) error {
    user, err := h.svc.Find(c.RequestContext(), id)
    if err != nil {
        return err  // ErrorHandler 中间件自动编码
    }
    return c.Success(user)
}

// 注册
fw.Engine().GET("/user/:id", httpx.H(h.GetUser))

传统模式

func (h *Handler) GetUser(c *gin.Context) {
    user, err := h.svc.Find(c.Request.Context(), id)
    if err != nil {
        httpx.Error(c, err)
        return
    }
    httpx.Success(c, user)
}

Framework 中间件链

自动注册（外 → 内）：

Recover → RequestLog → RequestID → [XRay] → [CORS] → [Auth] → ErrorHandler

fw := framework.New(framework.Config{
    Name: "myapp",
    Env:  "prod",
    XRay: &xtrace.Config{Enabled: true},          // 可选
    CORS: &httpx.CORSConfig{AllowedOrigins: ...}, // 可选
    AuthMiddleware: myAuthMiddleware,              // 可选
    Middleware: []gin.HandlerFunc{...},            // 自定义
})

追踪接线

// 启用 X-Ray 时，在初始化阶段调用一次
xtrace.BindLogger() // 让 logger 自动附带 traceId

Connector 单例

// 初始化
fw.Init(
    connector.DynamoDB.Initializer(ctx, connector.DynamoDBConfig{Region: "us-east-1"}),
    connector.SLS.Initializer(connector.SLSConfig{Endpoint: "..."}),
    connector.RevenueCat.Initializer(connector.RevenueCatConfig{APIKey: "..."}),
    connector.OneSignal.Initializer(connector.OneSignalConfig{AppID: "..."}),
)

// 使用
db := connector.DynamoDB.Client()
rc := connector.RevenueCat.Client()

JWT

svc, _ := jwt.NewService(jwt.Config{Secret: "...32+ bytes...", Issuer: "myapp"})

// TokenManager
tm := jwt.NewTokenManager(jwt.TokenConfig{
    Service:         svc,
    AccessTokenTTL:  15 * time.Minute,
    RefreshTokenTTL: 30 * 24 * time.Hour,
}, myRefreshStore)

// 签发
pair, _ := tm.IssueTokens(ctx, userID, tokenVersion)

// 验证
claims, _ := tm.ValidateAccessToken(ctx, tokenStr)

// 吊销
rm := jwt.NewRevocationManager(myRevocationStore)
rm.RevokeAllTokens(ctx, userID)           // 批量
rm.RevokeSingleToken(ctx, token, uid, ttl) // 单个

Go 版本

go 1.25+。