RRuna

能力总览

可组合的能力块一览

能力块是 Runa 的业务积木。每个能力都先提供可独立使用的 New() 核心对象，再通过 Provider() 接入框架生命周期，应用启动后可以用 Default() 从 DI 取出默认实例。

能力块怎么接入应用

安装核心和需要的能力：

go get github.com/duxweb/runa github.com/duxweb/runa/cache github.com/duxweb/runa/queue

接入应用：

app := runa.New()
app.Install(
    cache.Provider(),
    queue.Provider(),
)

if err := app.Run(context.Background()); err != nil {
    panic(err)
}

启动前用 Provider 注册驱动、实例、命令和配置绑定。启动后用 Default() 读取 DI 里的默认核心对象。

store := cache.Default().MustOf[string]("default")
queues := queue.Default()

不进框架时怎么单独使用

能力包不强绑框架。只想单独使用某个能力时，可以直接 New()：

registry := cache.New()
pool := registry.MustOf[string]("default")
_ = pool

这种模式不会进入 Runa 生命周期，也不会自动读取配置文件、注册命令或处理优雅关闭。

有哪些能力块

能力 安装路径 默认对象 默认驱动 用途
Database github.com/duxweb/runa/database *database.Registry 无默认连接 管理多个数据库运行时
Cache github.com/duxweb/runa/cache *cache.Registry memory 类型化缓存池
Queue github.com/duxweb/runa/queue *queue.Registry memory 后台任务队列与 worker
Session github.com/duxweb/runa/session *session.Registry memory HTTP 会话存储
Auth github.com/duxweb/runa/auth *auth.Registry 无默认认证器 登录态、Token、权限检查
Storage github.com/duxweb/runa/storage *storage.Registry local 本地与对象存储磁盘
Log github.com/duxweb/runa/log *log.Registry console 命名日志通道
Lock github.com/duxweb/runa/lock *lock.Registry memory 互斥锁和分布式锁抽象
Rate github.com/duxweb/runa/rate *rate.Registry memory 限流规则与 HTTP 中间件
Event github.com/duxweb/runa/event *event.Registry 内存分发 领域事件
Task github.com/duxweb/runa/task *task.Registry 直接执行 业务任务分发
Schedule github.com/duxweb/runa/schedule *schedule.Registry cron 定时调度
Message github.com/duxweb/runa/message *message.Registry memory 发布订阅消息
View github.com/duxweb/runa/view *view.Registry html/template 模板渲染
Lang github.com/duxweb/runa/lang *lang.Registry go-i18n bundle 多语言消息翻译与 locale 匹配
Asset github.com/duxweb/runa/asset *asset.Registry 文件源 静态资源 URL 与服务

外部驱动按需安装

默认驱动通常是纯 Go 内存或本地实现，适合开发和单机部署。需要 Redis、S3、NATS、AMQP、Oro、SQLite 等外部依赖时，再安装对应驱动模块。

go get github.com/duxweb/runa/cache/redis github.com/duxweb/runa/storage/s3

驱动模块只在 import 后进入应用依赖图，不使用就不会进入你的 go.sum。

配置文件怎么写

Provider 会读取 config/*.toml 中自己的作用域。常见形式是按能力名分域：

[cache.pools.default]
driver = "memory"
ttl = "10m"

[queue.queues.default]
driver = "memory"
workers = ["default"]

代码选项优先级高于文件配置，适合写死运行时必须项；文件配置适合环境差异。

在 HTTP 请求里怎么取能力

route.Context 不直接绑定具体能力。HTTP handler 里最常见的写法，是使用能力包自己的 Default()。

route.Default().Get("/cache", func(ctx *route.Context) error {
    pool := cache.Default().MustOf[string]("default")
    value, _, err := pool.Get(ctx.Context(), "hello")
    if err != nil {
        return err
    }
    return ctx.Text(value)
})

ctx.Context() 是当前请求的标准库 context。调用数据库、缓存、队列、外部 HTTP 请求时，优先把它传下去。

初学者怎么选能力

  • 只写 HTTP API：先安装 route
  • 需要缓存：安装 cache
  • 需要数据库：安装 database 和具体驱动，比如 database/oro
  • 需要后台任务：安装 queue 或 task
  • 需要登录态：安装 session 和 auth
  • 需要模板页面：安装 view，需要增强模板再使用 view/rhtml
  • 需要多语言消息：安装 lang，HTTP 语言协商再加 middleware/lang

不要一开始把所有能力都装上。Runa 的核心价值就是用什么装什么。

常见错误

把能力包和驱动包混在一起理解

cache 是能力包，cache/redis 是驱动包。能力包提供统一 API，驱动包负责连接外部系统。

只 go get 但没有 import

Go 只会编译被代码 import 的包。安装模块后，还需要在代码里 import 并使用它。

只 Install 能力，没有注册实例

很多能力需要注册命名实例，比如 cache.RegisterPool(...)、queue.RegisterQueue(...)、storage.RegisterDisk(...)。具体规则见对应能力页。

编辑此页