企业级 Go Web 应用脚手架(依赖库),开箱即用、模块热插拔——像 Spring Boot 一样:
gbx new 一键生成项目 → 按需 Enable* 开启模块 → 部署即得安全基线/认证/监控/开放平台。
| 项 | 值 |
|---|---|
| Go | 1.21+(最低 1.21,支持升级) |
| Module | github.com/Connorig/go-blackbox |
| 根包 | appbox |
| Web | Iris v12 |
| ORM | GORM(PostgreSQL 内置,MySQL/Oracle/SQLite 可注册) |
| 日志 | Zap + rotatelogs |
| IOC | gbxioc v2(Spring 式:单例/多例/具名/生命周期) |
| 配置 | Viper + 文件热更新 |
| 发布 | 每功能点 tag 发布,GitHub Action 自动验证 + Release |
业务统一通过 �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() 等)保留,门面是推荐入口
# 1. 用 CLI 生成项目(或直接引用本库)
go run github.com/Connorig/go-blackbox/cmd/gbx new -name demo-app
cd demo-app
# 2. 拉依赖并启动
go mod tidy
go run .启动即得:
| 入口 | 说明 |
|---|---|
http://localhost:8080/health/live /health/ready |
健康探针 |
http://localhost:8080/monitor |
服务器资源监控页(内存/CPU/磁盘/负载) |
POST /api/v1/login |
登录签发 JWT(scope + 组织身份) |
http://localhost:6060 |
Admin:pprof / metrics / 运行时日志级别切换 |
生成的骨架自带:安全基线中间件、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 一键生成业务项目骨架
| 模块 | 启用/接入 | 关键 API | 文档 |
|---|---|---|---|
| Web 服务 | builder.EnableWeb(timeFormat, port, level, func(app){...}) |
webiris.OK/Fail/RespondError |
API_GUIDELINES |
| 中间件体系 | app.Use(...) |
RequestID/AccessLog/CORS/SecurityHeaders/ErrorHandler |
SECURITY_GUIDELINES |
| 限流/DoS | app.Use(webiris.Limit(...), webiris.BodyLimit(...), webiris.Timeout(...)) |
429 B0210 / 413 / 504 | SECURITY_GUIDELINES |
| SQL 注入拦截 | app.Use(webiris.SQLGuard()) |
security.IsSQLInjection() |
SECURITY_GUIDELINES |
| JWT 认证 | apptoken.SetSecretKey(...) + app.Use(webiris.Auth(cfg)) |
GenTokenFull/VerifyToken, webiris.UserID/DataScope |
API_GUIDELINES |
| 数据权限 | db.Scopes(webiris.DataScope(ctx).Condition()) |
model.SnowflakeModel/StringIDModel/OrgFields |
DATABASE_STANDARDS |
| 数据库 | builder.EnableDatabase(&datasource.Config{...}) |
datasource.Get()/WithTx/NewMigrator |
DATABASE_STANDARDS |
| 开放平台(入站) | openapi.New(app, cfg) 注册式接口 |
api.GET/POST(handler),AppKey 签名 |
OPENAPI_GUIDELINES |
| 第三方调用(出站) | thirdparty.NewClient(cfg) |
client.Get/Post 自动签名 |
OPENAPI_GUIDELINES |
| 熔断器 | Config.Breaker: circuit.New(...) |
失败率阈值/冷却/半开 | OPENAPI_GUIDELINES |
| 方法级 AOP | aop.Around(fn, hook) |
Before/After/Around 装饰器 |
本文档下方 |
| 资源监控 | monitor.Register(app, "/monitor", cfg) |
页面 + /monitor/api/stats |
MONITOR_GUIDELINES |
| 监控告警 | alert.NewWatcher(cfg) + go watcher.Start(ctx) |
CPU/内存/磁盘规则 + webhook | ALERT_GUIDELINES |
| 工具集 | util.CopyProperties/DeepCopy/MD5/UUID... |
对标 Java commons/hutool | SECURITY_GUIDELINES |
| 代码生成 | gbx new -name demo |
一键生成项目骨架 | 本文档「快速开始」 |
| 事件总线 | eventbus.New(...) |
Subscribe/SubscribeAll/Publish,失败重试 |
EVENTBUS_GUIDELINES |
| SSE/WebSocket | framework/push/sse、framework/push/ws |
实时推送 | — |
| Cron | builder.InitCronJob() + Register(name, spec, fn) |
单例防重入 | — |
| Redis | builder.EnableCache(redisOptions) |
分布式锁/防击穿 | — |
| 短信 | sms.NewClient(cfg) + client.Send(...) |
阿里云 SendSms,签名/模板/变量 | SMS_GUIDELINES |
| 邮件 | mail.GetClient(cfg) + SendMail(...) |
SMTP SSL/TLS/附件 | MAIL_GUIDELINES |
| RBAC 权限 | rbac.NewEnforcer(provider) + enforcer.RequirePermission(...) | HasPermission/HasRole 带缓存,403 A0312 | RBAC_GUIDELINES |
| 可靠任务队列 | redqueue.NewQueue(client, prefix) | Submit(delay)/Consume 多实例,重试+死信 | REDQUEUE_GUIDELINES |
| 事件桥接(跨实例) | eventbus.NewRedisBridge(client, ch, bus) | Start/Publish | EVENTBUS_GUIDELINES |
| 通知中心 | notify.NewManager() + Register(adapter) | Send/SendAll,sms/mail 适配器内置 | — |
| 通知频控 |
otify.NewRateLimiter(window, max) | Allow/AllowSend 防轰炸 | NOTIFY_GUIDELINES |
| 审计查询 | audit.NewRedisListSink(client, key, limit) | Query/Count + 管理页 oplog.Register | MODULES_GUIDE |
| 灰度路由 | grayscale.New(ratio, userKey) + gray.Route(new, old) | 比例/用户稳定分流,A/B 测试 | GRAYSCALE_GUIDELINES |
| 配置中心 | configcenter.NewClient(url, dataId, group) | Fetch/Watch 热更新 | CONFIGCENTER_GUIDELINES |
| 国际化 | i18n.NewBundle() + LoadDir("langs") | T/Tf/DetectLanguage | I18N_GUIDELINES |
| 通知中心 | notify.NewManager() + Register(adapter) | Send/SendAll 模板渲染 | NOTIFY_GUIDELINES |
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 注册进容器。
| 开关 | 能力 | 说明 |
|---|---|---|
builder.EnableWeb(...) |
Web 服务 | 核心 |
builder.EnableDatabase(...) / EnableDb(...) |
关系数据库 | PostgreSQL 内置;MySQL/Oracle 注册 Dialector |
builder.EnableNamedDatabase(name, ...) |
多实例数据库 | 并行实例,独立生命周期 |
builder.EnableCache(redisOptions) |
Redis 缓存/分布式锁 | 未启用时相关 API 返回明确错误 |
builder.EnableMongoDB(cfg) |
MongoDB | 凭据 URI、超时 Ping |
builder.EnableAdmin(:6060) |
Admin 服务 | pprof + metrics + 日志级别 + 业务路由 |
builder.InitCronJob() |
定时任务 | 与 SetSeeds 配合 |
builder.SetupToken(...) |
JWT 参数 | 过期时间/签发者 |
builder.EnableStaticSource(embed.FS) |
静态资源 | Vue 打包产物嵌入 |
builder.BeforeSetup / AfterSetup |
生命周期钩子 | 数据就绪后/Web 启动前等时机 |
builder.OnShutdown(name, fn) |
关闭钩子 | 逆序执行 |
monitor.Register(app, ...) |
监控(路由级) | 按路由挂载,不启用则无 |
openapi.New(app, ...) |
开放平台(路由级) | 同上 |
未启用的模块不初始化、不占资源——这就是「热插拔」:业务项目按需组合。
全部模块的使用手册(定位/启用/API/示例/链接)见 模块使用手册。
| 文档 | 内容 |
|---|---|
| API_GUIDELINES.md | URL/响应/错误码/分页/幂等规范 |
| DATABASE_STANDARDS.md | 建表规范/索引/公共 Model/数据权限 |
| OPENAPI_GUIDELINES.md | 开放平台签名规范/出站客户端/熔断 |
| SECURITY_GUIDELINES.md | 安全基线组合/注入防护/工具集 |
| MONITOR_GUIDELINES.md | 资源监控接入/数据结构/平台矩阵 |
| ALERT_GUIDELINES.md | 告警规则/机器人渠道/自定义 |
| DEVELOPMENT_STANDARDS.md | 泰山版开发规范(代码/命名/注释) |
| PROJECT_ANALYSIS.md | 项目分析与升级基线 |
| OPTIMIZATION_ROADMAP.md | 功能优化路线图 |
| 版本 | 内容 |
|---|---|
| v1.18.0 | 方法级 AOP + 文档体系完善 |
| v1.17.0 | 全家桶示例(一次跑通全部能力) |
| v1.16.0 | 监控告警(企微/钉钉/飞书) |
| v1.15.0 | 熔断器 |
| v1.14.0 | gbx 代码生成 CLI |
| v1.13.0 | 服务器资源监控 |
| v1.12.0 | SQL 注入防护 + DoS 中间件 + 工具集 |
| v1.11.0 | 数据权限(组织/部门隔离) |
| v1.10.0 | 开放平台(网关 + 出站客户端 + 雪花/UUID) |
| v1.9.0 | 泰山版规范落地(A/B/C 错误码 + StandardModel) |
| v1.8.0 | 分层目录重构 |
MIT