Owl 框架使用手册

Owl 框架使用手册

Owl 是一个用 Go 编写的应用框架。它把「一个可执行程序」拆成若干子应用（SubApp），由框架统一负责依赖注入、配置生成、路由与菜单收集、数据库迁移和启动顺序。owl-admin、owl-cms、owl-cicd 都是挂在这个框架上的子应用。

这套手册面向第一次接触 Owl 的开发者，按「先跑起来，再理解机制，最后独立开发」的顺序组织。每一章都给出可直接运行的代码，读完一章就能完成该章的目标。

适合谁读

• 需要新建一个基于 Owl 的后端服务；
• 要在现有 owl-admin 里新增业务模块，但想先弄懂框架本身；
• 接手了 Owl 项目，需要快速定位「启动失败、接口 404、配置没生效」这类问题。

阅读路线

顺序	章节	读完你能做到
1	第一个 Owl 应用	用最小代码启动 HTTP 服务并访问一个接口
2	应用生命周期	说清 NewApp 到 WebShell 每一步做了什么
3	SubApp 契约	不看模板也能写出合法的子应用骨架
4	Service Provider 与依赖注入	注册自己的 Provider 和服务
5	路由、菜单与权限标识	注册接口、生成菜单和权限标识
6	配置、路径与运行目录	知道配置从哪来、文件落在哪
7	数据模型与迁移	建表、加字段并理解迁移门控
8	从零创建子系统实战	独立完成一个带 CRUD 的子系统
9	常见坑与上线自检	按清单排查启动与运行问题

建议按顺序读。第 8 章会用到前 7 章的全部概念，如果时间紧，可以先读第 1、3、8 章跑通，再回头补机制。

三个先记住的概念

1. SubApp：一个业务子系统。必须实现 owl.SubApp 接口，并包含 app foundation.Application 字段。
2. Service Provider：基础设施或横切能力的提供者，例如数据库、Redis、路由、JWT、权限引擎。
3. Binds：子应用把 Repository、Service、Handle 的构造函数交给 DI 容器，框架按参数类型自动装配。

最小可运行示例

// main.go
package main

import (
	"bit-labs.cn/owl"
	"my-order/app"
)

func main() {
	owl.NewApp(&app.SubAppOrder{}).WebShell()
}

// app/app.go
package app

import (
	"bit-labs.cn/owl"
	"bit-labs.cn/owl/contract/foundation"
	"bit-labs.cn/owl/provider/db"
	"bit-labs.cn/owl/provider/router"
	"github.com/spf13/cobra"
	"gorm.io/gorm"
)

type SubAppOrder struct {
	app foundation.Application
}

func (i *SubAppOrder) Name() string { return "order" }

func (i *SubAppOrder) ServiceProviders() []foundation.ServiceProvider {
	return []foundation.ServiceProvider{
		&router.RouterServiceProvider{},
		&db.DBServiceProvider{},
	}
}

func (i *SubAppOrder) RegisterRouters()          { /* route.InitApi(i.app, i.Name()) */ }
func (i *SubAppOrder) Binds() []any              { return nil }
func (i *SubAppOrder) Bootstrap()                {}
func (i *SubAppOrder) RegisterMenus() []*router.Menu { return nil }
func (i *SubAppOrder) RegisterCommands() []*cobra.Command { return nil }
func (i *SubAppOrder) RegisterMigrate() []any    { return nil }
func (i *SubAppOrder) BeforeMigrate(*gorm.DB) error { return nil }
func (i *SubAppOrder) AfterMigrate(*gorm.DB) error  { return nil }

完整代码见第 1 章。

仓库与文档

• 框架仓库：owl/，开发文档在 owl/docs/
• 后台子系统：owl-admin/，前端在 owl-admin/frontend/admin/
• 前端框架：owl-ui/，后台前端组件：owl-admin-ui/
• 本手册的权限部分见配套手册《owl-admin 权限子系统使用手册》