harbor

harbor Framework

Harbor 1.2.0：面向模块化单体、可平滑演进到多服务的 Go 应用框架。
核心只做装配、生命周期与稳定契约；数据库、路由、缓存、消息等按需接入。业务登录与领域逻辑留在你的 SubApp，不进框架仓库。

为什么用 Harbor

很多 Go 项目会从「手写 main + 全局变量 + 一堆 init」长成难拆的单体：依赖缠在一起、启动失败不好回滚、Web 与定时/命令行各写一套、加 Redis/支付又把主库依赖撑爆。

Harbor 把这些横切问题收成可复用约定，让你把时间花在业务上：

适合：中后台、运营系统、模块化单体（先一个仓多个 SubApp，以后再拆服务）。
不适合：只要一个 50 行 HTTP demo、或要把整套业务 CRUD/RBAC 塞进框架里——Harbor 刻意不做「业务超市」。

使用框架的好处

1. 启动与退出可控
   明确阶段与错误包装（含 Provider / 构造函数名）；启动失败回滚已 Boot 资源；进程退出 LIFO 关闭连接池、订阅等。

2. 模块可组合、依赖可选
   SubApp 自己声明 Binds() 与 ServiceProviders()；不用的 DB / Auth / 支付不会进你的二进制依赖图。

3. 契约稳定、实现可换
   contract/* 定义日志、配置、错误、鉴权、缓存等接口；业务依赖接口，Provider 可替换而不改业务签名。

4. Web 与运维开箱
   统一响应形状、AccessLevel 守卫、/livez /readyz、超时/限流/熔断、维护模式 503；需要时再开 Prometheus / OpenTelemetry / OpenAPI。

5. 工程可复制
   CLI 脚手架生成 SubApp / Provider；文档按生命周期 → 契约 → 组件索引组织；最低 Go 1.26，公开 API 优先泛型与标准库新能力。

6. 演进路径清晰
   今天：一个仓库多个 SubApp 的模块化单体。
   明天：把某个 SubApp 迁成独立服务时，生命周期与 Provider 边界已经分开，不必从全局变量堆里挖。

核心特性

分层与目录地图

业务 SubApp（admin / order / …）     ← 不在本仓库
─────────────────────────────────
L2 扩展          provider/* 、x/*
L1 核心组件      provider/conf|log|validator|event|appconf
L0 核心框架      application.go 、core/ 、contract/

完整约定见 docs/architecture/core-vs-extension.md。

L0 核心框架（Kernel）

应用怎么创建、装配、启动、失败回滚、优雅退出。无第三方业务 SDK。

L1 核心组件（Core Components）

几乎每个应用都要用的横切能力；NewApp 默装或强烈推荐具备。只依赖 L0。

L2 扩展组件（Extension）

按 SubApp ServiceProviders() 显式注册。分两类：

主 module（仍在本仓库 provider/，与主 go.mod 同仓）

边缘扩展（x/，与主库同一 go.mod，按需 import / 注册）

迁移与 import 对照见 x/README.md。

其他目录

环境要求

• 最低 Go 版本：1.26（以根目录 go.mod 的 go 行为准）
• 框架与贡献代码应主动使用 1.26+ 能力：泛型、errors.AsType、slices / maps、迭代器等；避免无必要的 any / 反射与手写循环

工程约定详见 docs/architecture/core-vs-extension.md 末尾「语言与 API 约定」。

安装

go get gitcode.com/harbor-labs/harbor@v1.2.0

x/pay、x/storage 等与主库同 module，无需单独 go get / 打标签；业务仓直接 import 即可。

本地开发：

git clone https://gitcode.com/harbor-labs/harbor.git
cd harbor
go mod download

本仓库是框架库，没有根目录 main.go。可参考 sub-utils/（Console 示例）与 docs/。

最小启动

app, err := harbor.NewApp(&admin.SubAppAdmin{})
if err != nil {
    log.Fatal(err)
}
if err := app.WebShell(); err != nil {
    log.Fatal(err)
}

扩展组件在 SubApp 里按需挂载，例如：

func (a *SubApp) ServiceProviders() []foundation.ServiceProvider {
    return []foundation.ServiceProvider{
        &db.DBServiceProvider{},
        &router.RouterServiceProvider{},
        &auth.JwtServiceProvider{},
        // 边缘扩展：&pay.PayServiceProvider{}  // gitcode.com/harbor-labs/harbor/x/pay
    }
}

文档

脚手架

go run ./tooling/cmd/harbor make subapp --name demo
go run ./tooling/cmd/harbor make provider --name demo

许可证

本项目基于 bit-labs-cn/owl Fork，采用 MIT License。