appbox

go-blackbox

企业级 Go Web 应用脚手架(依赖库),开箱即用、模块热插拔——像 Spring Boot 一样: gbx new 一键生成项目 → 按需 Enable* 开启模块 → 部署即得安全基线/认证/监控/开放平台。

资源获取(门面模式,推荐)

业务统一通过 ppbox 门面获取已装配的资源,无需记忆各模块获取方式:

go db := appbox.DB() // *gorm.DB redis := appbox.Cache() // *cache.RedisCache mongo := appbox.MongoDB() // *mongodb.Client mq := appbox.MQ() // *rabbitmq.Connection kafka := appbox.KafkaProducer() // *kafka.Producer cron := appbox.Cron() // *cron.Cron esC := appbox.ES() // *es.Client oss := appbox.Storage() // *storage.Client inf := appbox.Influx() // *influx.Client smsC := appbox.SMS() // *sms.Client mailC := appbox.Mail() // *email.Client

• 未启用对应模块时返回 nil(不 panic)
• 业务自定义对象(service 等)用 gbxioc.GetBeanT(单例/多例/具名)
• 底层模块便捷函数(cache.Get() 等)保留,门面是推荐入口

快速开始(3 分钟)

# 1. 用 CLI 生成项目(或直接引用本库)
go run github.com/Connorig/go-blackbox/cmd/gbx new -name demo-app
cd demo-app

# 2. 拉依赖并启动
go mod tidy
go run .

启动即得:

生成的骨架自带:安全基线中间件、JWT 认证、数据权限隔离、SQLite + 迁移、监控。 完整可运行示例见 examples/web-basic(全家桶)与 examples/openapi(开放平台)。

分层架构(泰山版规范)

component/   通用能力(与业务无关)
├── auth/     JWT(token 轮换/scope/组织身份)、RSA 加解密
├── error/    阿里手册 A/B/C 错误码体系 + 统一错误(自动映射 HTTP 状态)
├── security/ SQL 注入检测(17 模式)+ 日志注入防护
├── util/     工具集:CopyProperties/DeepCopy/MD5/SHA/UUID/RandomString/时间...
└── mask/     脱敏器(Phone/Email/Name/IDCard/BankCard)

framework/   框架能力(面向业务)
├── web/      webiris:中间件体系/认证/限流/SQL 防护/统一响应/Admin/健康探针
├── database/ 多实例数据源 + 迁移 + DataScope 数据权限 + 雪花/UUID + 公共 Model
├── openapi/  开放 API 网关(AppKey 签名/防重放/限流/审计,业务零加密负担)
├── thirdparty/ 出站签名客户端(HMAC/RSA/Bearer + 重试 + 错误映射)
├── circuit/  熔断器(closed/open/half-open 状态机)
├── aop/      方法级切面(@Before/@After/@Around,Service 层日志/校验/耗时)
├── monitor/  服务器资源监控(跨平台采集 + 内置页面)
├── alert/    监控告警(规则引擎 + 企微/钉钉/飞书 webhook)
├── cache/    分布式锁/防击穿/防雪崩/Redis 封装
├── mq/       RabbitMQ 状态机(自动重连/Consumer/Producer)
├── push/      SSE 实时推送 / WebSocket Hub
├── event/    事件总线(同步/异步)
├── cron/     定时任务(含单例防重入)
├── mail/     邮件(gomail 封装)
├── mongo/    MongoDB(凭据 URI/泛型 FindTyped)
├── config/   配置加载(热更新/脱敏快照)
├── log/      Zap 结构化日志(运行时级别切换)
└── lifecycle/ 生命周期与优雅关闭

cmd/gbx      代码生成 CLI:gbx new 一键生成业务项目骨架

模块文档总表(配置 / 调用 / 示例)

AOP(面向切面,接口驱动)

Web 层:中间件即环绕切面——AccessLog(日志)、Auth(权限前置)、Limit(限流前置)、ErrorHandler(异常后置)。

Service 层:定义接口 + 实现 Aspect 接口,通过 aop.Proxy 自动拦截(对标 Spring @Aspect):

// ① 业务 Service 定义成接口(调用方只依赖接口)
type UserService interface {
    GetUser(ctx context.Context, id int64) (*User, error)
}

// ② 实现 Aspect 接口:JoinPoint 里方法名/目标对象/参数/返回值/错误/耗时全可获取
type LogAspect struct{}
func (LogAspect) Name() string { return "log" }
func (LogAspect) Before(ctx context.Context, jp *aop.JoinPoint) error {
    log.Printf("call %s params=%v", jp.Method, jp.Params)
    return nil // 返回 error 即终止调用(权限/参数校验)
}
func (LogAspect) After(ctx context.Context, jp *aop.JoinPoint) {
    log.Printf("call %s cost=%s err=%v", jp.Method, jp.Cost, jp.Err)
}

// ③ 代理实现:方法转发 + aop.Proxy 拦截(样板固定)
type userServiceProxy struct {
    inner *userServiceImpl
    aop   *aop.Proxy
}
func (p *userServiceProxy) GetUser(ctx context.Context, id int64) (*User, error) {
    var result *User
    _, err := p.aop.Invoke(ctx, "GetUser", []interface{}{ctx, id}, func() ([]interface{}, error) {
        var callErr error
        result, callErr = p.inner.GetUser(ctx, id)
        return []interface{}{result}, callErr
    })
    return result, err
}

// ④ 装配:注册切面链(洋葱模型:Before 顺序、After 逆序)
service := &userServiceProxy{
    inner: &userServiceImpl{},
    aop:   aop.NewProxy(impl, paramGuardAspect{}, LogAspect{}, authAspect{}),
}
var api UserService = service // 业务只持有接口,切面透明

JoinPoint 上下文:Method / Target(目标对象)/ Proxy / Params(可修改)/ Results / Err / Start / Cost。 切面可热插拔(proxy.AddAspects(...));函数级装饰器 aop.Before/After/Around 同步保留。

Web 层:中间件即环绕切面——AccessLog(日志)、Auth(权限前置)、Limit(限流前置)、ErrorHandler(异常后置)。

Service 层:framework/aop 函数级切面(对标 Spring @Before/@After/@Around):

// 原始方法(任意签名)
getUser := func(ctx context.Context, id int64) (*User, error) { ... }

// 前置校验:参数非法直接终止(不执行目标方法)
getUser = aop.Before(getUser, func(ctx context.Context, params []interface{}) error {
    if params[1].(int64) <= 0 { return errors.New("invalid id") }
    return nil
}).(func(context.Context, int64) (*User, error))

// 环绕切面:耗时 + 日志
getUser = aop.Around(getUser, func(ctx context.Context, params []interface{},
    next func() ([]interface{}, error)) ([]interface{}, error) {
    start := time.Now()
    results, err := next()
    log.Printf("GetUser cost=%s", time.Since(start))
    return results, err
}).(func(context.Context, int64) (*User, error))

切面可组合(Before + Around + After),签名不变,业务调用方无感知;配合 gbxioc 将装饰后的 Service 注册进容器。

热插拔模块(按需启用)

未启用的模块不初始化、不占资源——这就是「热插拔」:业务项目按需组合。

完整文档索引

全部模块的使用手册(定位/启用/API/示例/链接)见 模块使用手册。

版本历史(近期)

许可证

MIT