dilu-go-kit

dilu-go-kit

Go 微服务基础工具包。提供统一的服务启动、日志、中间件、错误码、服务发现和事件通知。

特性

• boot — 一行启动服务（Config + DB + Redis + gRPC + etcd 注册 + 优雅关闭）
• log — 统一日志接口（slog 实现，traceId 自动注入，底层可替换）
• mid — 可配置中间件（Trace + Recovery + Logger + ErrorHandler + JWT + CORS + RateLimit）
• resp — 统一 HTTP 响应（Ok / Fail / Page / Error）+ 标准错误码
• store — 数据访问层基础类型（ListOpts 分页）
• registry — 服务注册与发现（etcd）
• notify — 通用 HTTP 事件推送（支持 traceId 透传）

安装

go get github.com/baowk/dilu-go-kit@v0.3.0

快速开始

package main

import (
    "github.com/baowk/dilu-go-kit/boot"
    "github.com/baowk/dilu-go-kit/log"
    "github.com/baowk/dilu-go-kit/mid"
    "github.com/baowk/dilu-go-kit/resp"
    "github.com/gin-gonic/gin"
)

func main() {
    app, _ := boot.New("config.yaml")
    app.Run(func(a *boot.App) error {
        // 一行注册全部中间件（Trace + Recovery + ErrorHandler + Logger + CORS + RateLimit）
        mid.Default(a.Gin, mid.DefaultConfig{
            CORS:        mid.CORSCfg{Enable: true, Mode: "allow-all"},
            AccessLimit: mid.AccessLimitCfg{Enable: true, Total: 300, Duration: 5},
        })

        a.Gin.GET("/ping", func(c *gin.Context) {
            log.InfoContext(c.Request.Context(), "ping", "ip", c.ClientIP())
            resp.Ok(c, "pong")
        })
        return nil
    })
}

详见 docs/quickstart.md 和 example/。

目录

boot/       服务启动（Config/DB/Redis/gRPC/Registry/Logger）
log/        统一日志接口（Logger 接口 + slog 实现 + traceId）
mid/        中间件（Trace/Recovery/Logger/ErrorHandler/JWT/CORS/RateLimit/Default/gRPC interceptor）
resp/       统一 HTTP 响应 + 标准错误码
store/      数据访问基础类型（ListOpts）
registry/   服务注册与发现（etcd）
notify/     通用事件推送
example/    完整示例服务
docs/       规范文档

日志

import "github.com/baowk/dilu-go-kit/log"

log.Info("server started", "port", 8080)
log.InfoContext(ctx, "created env", "env_id", 123)  // 自动带 trace_id
log.With("module", "auth").Warn("token expired")

// 输出（JSON）:
// {"time":"...","level":"INFO","msg":"created env","trace_id":"abc-123","env_id":123,"service":"mf-env"}

底层使用 slog（Go 标准库），通过 log.SetLogger() 可替换为任意实现。

中间件

// 方式一：一行全部注册（推荐）
mid.Default(r, mid.DefaultConfig{...})

// 方式二：单独使用
r.Use(mid.Trace())         // traceId 生成/传递
r.Use(mid.Recovery())      // panic 恢复
r.Use(mid.ErrorHandler())  // AppError 捕获
r.Use(mid.Logger())        // 请求日志（method/path/status/latency/traceId）
r.Use(mid.CORS())          // CORS（支持 whitelist）
r.Use(mid.RateLimit(100, time.Minute))  // 限流

// JWT 认证
auth := r.Group("/v1").Use(mid.JWT(mid.JWTConfig{Secret: "xxx", HeaderUID: "a_uid"}))
uid := mid.GetUID(c)
nickname := mid.GetNickname(c)

// gRPC traceId 透传
conn, _ := grpc.NewClient(addr, grpc.WithUnaryInterceptor(mid.GRPCUnaryClientInterceptor()))

标准错误码

resp.Fail(c, resp.CodeUnauthorized, "未登录")   // 40101
resp.Fail(c, resp.CodeForbidden, "无权操作")     // 40301
resp.Fail(c, resp.CodeInvalidParam, "参数错误")  // 40001
resp.Fail(c, resp.CodeNotFound, "不存在")        // 40401
resp.Fail(c, resp.CodeInternal, "服务错误")      // 50000

事件通知

import "github.com/baowk/dilu-go-kit/notify"

notify.Init("http://mf-ws:9020")
notify.Send("env", map[string]any{"action": "created", "env_id": 123, "workspace_id": 1})
notify.SendContext(ctx, "proxy", payload)  // 自动携带 traceId

服务注册与发现

registry:
  enable: true
  endpoints: ["127.0.0.1:2379"]

服务启动自动注册到 etcd，关闭自动注销。网关 Watch 实时发现变更。

配置示例

server:
  name: my-service
  addr: ":8080"
  mode: debug

database:
  main:
    dsn: "host=127.0.0.1 user=postgres dbname=mydb sslmode=disable"
    slowThreshold: 200

redis:
  addr: "127.0.0.1:6379"

jwt:
  secret: "your-secret"
  expires: 1440

cors:
  enable: true
  mode: allow-all

accessLimit:
  enable: true
  total: 300
  duration: 5

notify:
  wsUrl: "http://mf-ws:9020"

registry:
  enable: true
  endpoints: ["127.0.0.1:2379"]

AI 辅助开发

本仓库提供 CLAUDE.template.md 作为 AI 开发规范模板：

curl -sL https://raw.githubusercontent.com/baowk/dilu-go-kit/main/CLAUDE.template.md > CLAUDE.md

规范

• 开发规范 — 项目结构、数据层、API、错误码、中间件
• 快速开始 — 5 分钟上手

License

MIT