daqing/airway
daqing/airway has 62 GitHub stars and 7 forks. GitHot measured 0 stars in 24 hours. Last checked 2026-11-15 20:21 UTC. Last push 2026-10-24.
可以做什么
- Generics-based repository (lib/repo): typed FindBy[User], CreateFrom[User], preload/eager-loading, joins, transaction-bound helpers.
- Dialect-aware SQL builder (lib/sql + pg / mysql / sqlite dialects); conditions like sql.Eq, sql.AllOf, sql.Gt; native FOR UPDATE SKIP LOCKED support (sql.ForUpdateSkipLocked).
- Schema-driven migrations: generate and apply migrations with the CLI; SQLite schema changes are handled by table rebuild.
- Unified file storage (lib/storage): local directory, Amazon S3, Cloudflare R2 or Tencent COS — selected purely by configuration, exposed via an HTTP upload/download API.
实测星标增长
- 24小时
- 0
- 7天
- 更新延迟
- 15天
- 更新延迟
- 1个月
- 更新延迟
各周期内的星标净变化,周期相互重叠,并非每日新增。缺失的测量保持空白。星标代表关注度,不代表软件质量。
关于
Full-stack Web framework written in Go, inspired by Ruby on Rails.
网站与应用docs/zh-CN/README.md
原文Airway
Airway 是一个受 Rails 启发的 Go 全栈框架。它用同一套应用代码构建服务端渲染的 Web 应用、JSON API、静态展示站点和原生桌面应用,支持 PostgreSQL、 MySQL 8 和 SQLite——数据库驱动在运行时根据 DSN 自动推断。
- English README
- Admin 后台指南 / Admin panel guide
- 静态展示站点(SSG) / Static showcase sites
- 静态导出指南 / Static export guide
- CLI 脚手架指南 / CLI scaffolding guide
- 前端指南 / Frontend guide
- OpenAPI 指南 / OpenAPI guide
- 桌面应用指南 / Desktop guide
- Plugin 扩展机制 / Plugin guide
- 文件存储指南 / Storage guide
- 视图模板指南(templ) / templ views guide
- SQL Builder DSL 指南
特性
- 基于泛型的 Repository(
lib/repo):类型安全的FindBy[User]、CreateFrom[User]、预加载(eager loading)、联表查询、事务绑定助手。 - 方言感知的 SQL Builder(
lib/sql+pg/mysql/sqlite方言包);条件写法如sql.Eq、sql.AllOf、sql.Gt;原生支持FOR UPDATE SKIP LOCKED(sql.ForUpdateSkipLocked)。 - 基于 schema 的迁移:通过 CLI 生成与应用迁移;SQLite 的表结构变更通过重建表处理。
- 统一的文件存储(
lib/storage):本地目录、Amazon S3、Cloudflare R2 或腾讯云 COS——完全由配置决定,并提供 HTTP 上传/下载 API。 - Gin Web 服务 + WebSocket 发布/订阅。
- 基于 templ 的 HTML 视图:页面是
app/views/下的.templ模板,由 action 经lib/render.HTML渲染。 - 无需 Node 的前端:npm 依赖由 CLI 管理(
js:add/js:install,js.pkg.json锁定),内嵌 esbuild 打包(js:build),开发期内存重建 + livereload,以及构建在内置 airway-ui 组件库之上的交互式 Preact islands——产物全部提交并内嵌进单个 Go 二进制。 - OpenAPI 3.2 文档:从运行中的路由自动生成——operationId 由 handler 名推导,可在各模块中用代码富化,并实时服务于
/openapi.json。 - Admin 后台生成器:一份 TOML 表规格即可生成完整的后台——认证、角色、审计日志、CSV 导出、服务端分页列表。
- 桌面应用:
airway desktop:init把项目导出为 Wails v3 桌面目标;同一套 Web 技术栈跑在 macOS、Windows、Linux 的原生 WebView 窗口里。 - 静态展示站点:
airway ssg:new脚手架一个页面即 Go 代码的静态站点,外观来自可替换的主题 module(theme:new/theme:install);airway ssg:build导出纯 HTML,可部署到任何静态托管。 - 静态导出上 CDN:
airway static:build把应用页面(在export.go中注册)导出为纯 HTML 加前端产物——templ 渲染的内容 + 完整保留的 Preact islands,可直接部署到任何 CDN(见 docs/static-export.md)。 - 插件:WordPress 风格的功能模块,以独立 Go module 分发——
go get安装,plugins.go里一行 blank import 启用(见 docs/plugin.md)。 - 脚手架 CLI(
airway generate ...、db:migrate等)。 - Repo REPL:支持类型化扫描与 Go 表达式求值。
- 可选子路径前缀(
URL_PREFIX):便于在反向代理后部署,例如http://host:1900/airway/...。
快速开始
需要 Go 1.27.1 或更高版本。无需 Node.js,无需 CGO。
1. 安装 CLI 并生成新项目
go install github.com/daqing/airway@latest
airway new myapp # 或:airway new github.com/me/myapp(目录取路径最后一段)
# 或:airway new /path/to/myapp(传路径,module 取路径最后一段;相对路径同理,如 sites/myapp)
cd myapp
airway new 会以框架的 app/ 骨架为模板生成一个新项目,自动从 .env.example
生成 .env,执行 go mod tidy,安装前端依赖(airway js:install),并打印
后续步骤。如果你是想开发框架本身,可以改为克隆仓库:
git clone https://github.com/daqing/airway.git
cd airway
cp .env.example .env
打开 .env,至少设置数据库 DSN 与监听地址:
DSN="sqlite://./tmp/airway.db" # 或 postgres://...、mysql://...
LISTEN=":1900" # 要绑定的 host:port;":1900" 表示所有网卡
环境变量既可以使用短名(DSN、LISTEN、REDIS、URL_PREFIX),也可以使用带 AIRWAY_ 前缀的形式(AIRWAY_DSN、AIRWAY_LISTEN 等)。当两者都设置时,以 AIRWAY_ 形式为准。参见「配置」。
2. 启动服务
go run . server # 或:airway server(需要 AIRWAY_ENV,如 AIRWAY_ENV=local,以及配置好的 DSN)
或者启动带热重载的本地开发服务:
just dev
应用监听 http://127.0.0.1:1900(GET / 返回 templ 渲染的 HTML 页面,GET /health 返回 UP)。
配置
所有配置通过环境变量完成(见 .env.example)。.env 中的值是回退值:进程环境始终优先(例如 LISTEN=0.0.0.0:1988 airway server 会覆盖 .env 里的 LISTEN)。每个值都可以用短名或其 AIRWAY_ 别名,两者都设置时以 AIRWAY_ 形式为准。
| 变量 | 说明 |
|---|---|
DSN / AIRWAY_DSN |
数据库 URL,驱动由 scheme 推断(见下)。 |
LISTEN / AIRWAY_LISTEN |
服务器绑定的地址,host:port(如 0.0.0.0:1905、:1905),默认 :1900。 |
REDIS / AIRWAY_REDIS |
可选的 Redis URL,用于缓存/队列。 |
URL_PREFIX / AIRWAY_URL_PREFIX |
可选的公开子路径前缀,如 /airway;留空则在根路径服务。 |
AIRWAY_JS_REGISTRY |
js:add / js:install 使用的 npm registry(默认 https://registry.npmjs.org;需要时可设为 https://registry.npmmirror.com 等镜像)。 |
AIRWAY_ENV |
local 会加载 .env 并使用 Gin debug 模式;其他值为 release 模式。 |
STORAGE_DRIVER |
local(默认)、s3、r2 或 cos。 |
STORAGE_ROOT |
本地存储根目录(默认 ./data/storage)。 |
STORAGE_* |
云存储配置:STORAGE_REGION、STORAGE_ENDPOINT、STORAGE_BUCKET、STORAGE_ACCESS_KEY、STORAGE_SECRET_KEY、STORAGE_PUBLIC_URL(可选 CDN 基址)。 |
TZ |
服务器时区,如 Asia/Shanghai。 |
数据库 DSN
同一套代码只需修改 DSN 即可切换数据库:
# PostgreSQL
DSN="postgres://daqing:[email protected]:5432/airway"
# SQLite(文件或内存)——纯 Go 驱动,无需 CGO
DSN="sqlite://./tmp/airway.db"
DSN="sqlite://:memory:"
# MySQL 8(URL 或原生驱动格式)
DSN="mysql://root:[email protected]:3306/airway?charset=utf8mb4"
DSN="root:passwd@tcp(127.0.0.1:3306)/airway?charset=utf8mb4&parseTime=true"
说明:
- 基础 CRUD 在 PostgreSQL、MySQL 8 与 SQLite 之间可移植。
- 部分高级 SQL Builder 助手(ARRAY、JSONB、少量 lateral/window 表达式)仍面向 PostgreSQL。
- SQLite 使用纯 Go 的
modernc.org/sqlite驱动。
HTTP 端点
注册于 config/routes.go:
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | / |
首页(HTML,由 templ 视图渲染)。 |
| GET | /ui |
airway-ui 组件展示页(交互式 island)。 |
| GET | /openapi.json |
实时 OpenAPI 3.2 文档(见 API 文档)。 |
| GET | /health |
健康检查。 |
| GET | /ws |
WebSocket 连接。 |
| POST | /ws/publish |
向已连接客户端发布消息(表单字段 message)。 |
| POST | /api/v1/storage |
上传文件(multipart file,可选 dir)。 |
| GET | /api/v1/storage/*key |
下载文件。 |
| DELETE | /api/v1/storage/*key |
删除文件。 |
| GET | /api/v1/ui-demo/items |
/ui 页面 TanStack island 的演示数据。 |
设置了 URL_PREFIX 后,公开路由——首页、WebSocket 与 API——只会在该前缀下服务,不再出现在根路径。健康检查仍保持在无前缀的根路径可达,便于负载均衡探针直接访问 /health。以 URL_PREFIX="/airway" 为例:
curl http://127.0.0.1:1900/airway/health
curl http://127.0.0.1:1900/health # 仍然可达(探针)
curl -F "[email protected]" http://127.0.0.1:1900/airway/api/v1/storage
客户端——包括 WebSocket 连接——必须带上前缀(ws://host:1900/airway/ws)。API 返回的本地存储 URL 会带上前缀;云/CDN URL 不受影响。
HTML 视图(templ)
页面是 app/views/ 下的 templ 模板,每个 API 模块一个目录——目录名去掉 _api 后缀,因此 home_api 渲染 app/views/home/index.templ。每个目录是独立的包;共享的文档外壳位于 app/views/layouts/base.templ。action 通过 lib/render 的 HTML 助手返回组件:
// app/api/home_api/index_action.go
render.HTML(c, home.Index())
修改任何 .templ 文件后,重新生成 Go 代码并保持提交:
go generate ./... # 或:just generate,或:airway templates:compile
生成的 *_templ.go 文件已提交,因此构建与测试不需要 templ CLI。
交互式 islands
页面保持服务端渲染;交互区域是 islands——Preact TSX 组件挂载到带服务端 props 的 data-island 节点上:
// 在 .templ 视图中(见 app/views/home 的实际示例)
@assets.Island("counter", map[string]any{"start": 3})
组件位于 app/assets/js/islands/counter.tsx(默认导出即可;文件路径就是 island 名称),会被自动打包——无需手工注册。本地开发时 bundle 在内存中重建、浏览器自动刷新;生产环境中它内嵌在二进制里,通过防缓存 URL 提供。页面完全不依赖 JavaScript 也能完整渲染:挂载点初始为空。
airway-ui 是 islands 所基于的内置组件库:按钮、输入框、表单(react-hook-form)、表格(TanStack Table)、模态框、toast、标签页,以及与 lib/render JSON 信封对齐的请求层——视觉层自研,逻辑层来自 preact/compat 生态。启动服务后可在 /ui 实时查看全部组件。
前端策略
状态:已端到端落地——见前端指南。整条管线随 CLI 交付
(js:add/js:install/js:build、generate island/scaffold),随项目模板交付,也随本仓库自身交付(首页计数器与 /ui 组件展示页都是 islands)。
前端代码与 Go 代码同仓库,获得媲美现代 UI 框架的组件化工作流,并且不引入 Node.js 工具链:
- templ 渲染骨架——页面结构、SEO、首屏。
- 交互区域是 islands——
app/assets/js/下的 Preact TSX 组件,挂载到标记data-island的元素上;初始数据序列化在挂载点旁。 - esbuild 作为 Go 库内嵌——CLI 直接链接
github.com/evanw/esbuild/pkg/api:airway js:build编译 TS/TSX,开发服务器从内存提供重建后的 bundle,生产 bundle 经go:embed内嵌进单个 Go 二进制。 - 自研
airway-ui组件库,构建在preact/compat之上——重逻辑的 React 生态库(TanStack Table/Query/Form、React Hook Form)保持可用,视觉层保持自研。
已否决的备选方案:
- htmx + Alpine.js(HTML over the wire)——做渐进增强没问题,但没有基于组件的响应式编程模型;交互能力上限远不及真正的组件库。
- Node 前端子项目(Vue、React/Next.js、Svelte 等)经
go:embed内嵌——把完整的 Node 工具链拖进仓库;真到那一步,前后端分离才是更诚实的选择。 - LiveView 式服务端驱动 UI——对 Go 框架实际价值有限;当应用确实需要重度前端工程时,把前端拆出去独立开发才是正解。
逃生舱:当应用超出 islands 的能力范围(复杂 SPA、富文本编辑器),应把前端拆成独立项目(Vue、React、Svelte 等),Airway 退化为纯 JSON API。
API 文档(OpenAPI)
二进制提供的每个 API 路由都会被记录为 OpenAPI 3.2 文档——无需任何注解。airway openapi:generate 扫描路由、从 handler 名推导 operationId,写出 ./openapi.json(构建产物,已 git-ignore——路由变化后重新生成即可)。同一份文档实时服务于 /openapi.json。
各模块通过 openapi.go 文件用 lib/openapi(openapi.Get(...) 等)在代码里富化文档,声明操作及其从 Go 类型推导的请求/响应 schema;文档级元数据位于 app/api/openapi_api/doc.go。详见 OpenAPI 指南。
Admin 后台
airway admin:generate 读取 TOML 表规格(config/admin.toml),生成一个完整、可上生产的管理后台——它是真实的、归用户所有的 Go 代码:cookie 会话认证、角色、审计日志、CSV 导出、服务端分页列表,并为每个声明字段(含 datetime、enum、references、attachment)生成类型感知的表单与筛选。
airway admin:generate # 或:admin:generate --force=table1,table2
airway admin:root admin 's3cret' # 创建管理员账号
airway admin:member editor 's3cret' # 创建非管理员后台账号(--role=editor|viewer)
airway server # 在 /admin/login 登录
详见 Admin 后台指南(English)。
桌面应用
airway desktop:init 把项目导出为 Wails v3 桌面目标(./desktop):同一套 Web 技术栈(templ 视图、islands、JSON API、WebSocket)在桌面进程内的本地回环端口上运行,原生 WebView 窗口加载该地址——服务端渲染页面、cookie 会话、重定向和 WebSocket 的行为与 Web 上完全一致,应用代码零改动。SQL 迁移内嵌并在启动时自动应用;打包覆盖 macOS(.app)、Windows(NSIS)与 Linux(deb/rpm/AppImage)。
airway desktop:init # 生成 ./desktop;重跑可重新同步迁移/插件
详见桌面应用指南(English)与调研记录 WAILS.md。
静态展示站点(SSG)
Airway 同时也是面向展示型网站的静态站点生成器——公司官网、产品落地页、作品集。airway ssg:new 脚手架一个站点项目,页面在 ssg.go 中以 Go 代码声明,外观来自可替换的主题 module;airway ssg:build 导出纯 HTML 目录,可部署到任何静态托管;airway ssg:serve 本地预览。主题就是普通的 Go module(templ 组件 + 内嵌资源):airway theme:new 生成新主题,airway theme:install 把主题装进站点。框架自带 corporate 参考主题。
airway ssg:new mysite # 然后:airway ssg:build / airway ssg:serve
设计记录见 SSG.zh-CN.md(English),使用指南见 docs/zh-CN/ssg.md(English)。
CLI
Airway CLI 是单个 airway 二进制(go install github.com/daqing/airway@latest 安装)。在项目内它会检测宿主应用,并把所有项目级命令透明地经 go run . 重新执行(stderr 显示 proxying to project binary 提示),因此插件、REPL 模型与 Go 代码迁移总是来自项目自己的二进制。命令会自动加载项目根目录的 .env。
项目与服务
airway new <module-path | /path> # 生成新项目骨架
airway server # 启动 HTTP 服务
airway generate api admin # 在 app/api/ 下新建 API 命名空间
airway generate action admin show # 在已有 API 模块中新建 action
airway generate model post # 在 app/models/ 中新建模型
airway generate service post title:string # 在 app/services/ 中生成 CRUD service
airway generate island chart # 交互式 island 组件
airway generate scaffold post title:string # 全套 CRUD:模型+迁移+API+页面+island
airway generate migration create_posts # 在 db/migrate/ 中生成 .up.sql/.down.sql 对
airway repl # 交互式 repo REPL(项目内自动代理到 go run .)
airway version # 打印版本(亦支持 -v、--version)
数据库
airway db:create # 创建数据库
airway db:drop # 删除数据库
airway db:migrate [version] # 应用迁移
airway db:rollback [step] # 回滚迁移
airway db:status # 迁移状态
airway schema:dump # 写出 db/schema.json
airway schema:show # 打印 db/schema.json
前端
airway js:add <pkg>[@version] # 添加前端 npm 依赖(无需 Node)
airway js:install # 将 js.pkg.json 依赖安装到 app/assets/js/vendor/
airway js:build # 将 app/assets/js 打包到 app/assets/dist(esbuild)
airway templates:compile # 重新生成 templ 视图(`go generate ./...` 的简写)
API 文档
airway openapi:generate [--out path] # 写出 OpenAPI 3.2 文档(默认 ./openapi.json)
Admin 后台
airway admin:generate [config/admin.toml] # 从 TOML 表规格生成后台
airway admin:root <username> <password> # 创建管理员账号(role admin)
airway admin:member <username> <password> [--role=editor|viewer]
# 创建非管理员后台账号
桌面应用
airway desktop:init [--force] # 在 ./desktop 生成 Wails v3 桌面目标
静态站点与主题
airway ssg:new [--local[=path]] <name> # 脚手架静态展示站点项目
airway ssg:build [--out dist] # 将 ssg.go 定义的站点导出为静态 HTML
airway ssg:serve [--addr 127.0.0.1:3000] # 本地服务预览站点
airway theme:new [--local[=path]] <name> # 脚手架新的站点主题 module
airway theme:install <module | /path> # 把站点主题接入宿主项目
静态导出(应用页面)
airway static:build [--out dist] # 将 export.go 注册的页面 + 前端产物导出为静态 HTML
airway static:serve [--addr 127.0.0.1:3000] # 本地服务预览静态页面
插件
airway plugin:new <module-path | /path> # 脚手架新插件 module
airway plugin:list # 已注册插件及其挂载路径
airway plugin:install <module> # 启用插件 + 安装其 SQL 迁移与 deps/
airway plugin:lint # 检查当前插件项目的旧版布局问题
文件
airway upload [key] /path/to/file # 经配置的存储上传
数据库命令读取 DSN/AIRWAY_DSN。完整内容见
CLI 指南。
Repository API(lib/repo)
模型
模型是带 db tag 和 TableName() 方法的结构体。关联通过 Relations() 声明。
import "github.com/daqing/airway/lib/repo"
type User struct {
ID int64 `db:"id"`
Name string `db:"name"`
Email string `db:"email"`
Profile *Profile // belongs_to
Posts []*Post // has_many
}
func (User) TableName() string { return "users" }
func (User) Relations() map[string]repo.Relation {
return map[string]repo.Relation{
"Profile": repo.HasOne(Profile{}, "UserID"),
"Posts": repo.HasMany(Post{}, "UserID"),
}
}
type Post struct {
ID int64 `db:"id"`
UserID int64 `db:"user_id"`
Title string `db:"title"`
Author *User // belongs_to
}
func (Post) TableName() string { return "posts" }
func (Post) Relations() map[string]repo.Relation {
return map[string]repo.Relation{
"Author": repo.NewBelongsTo(User{}, "UserID"),
}
}
CRUD
所有助手使用启动时配置的数据库(repo.SetupDB),并以模型类型作为类型参数:
// 创建
user, err := repo.CreateFrom[User](sql.H{"name": "John", "email": "[email protected]"})
// 读取
user, err := repo.FindByID[User](1)
user, err := repo.FindOneBy[User](sql.H{"email": "[email protected]"})
users, err := repo.FindBy[User](sql.H{"active": true})
users, err := repo.FindAll[User]()
// 更新
err := repo.UpdateByID[User](1, sql.H{"name": "Jane"})
err := repo.UpdateWhere[User](sql.H{"status": "inactive"}, sql.Eq("last_login_at", nil))
// 删除
err := repo.DeleteByID[User](1)
err := repo.DeleteWhere[User](sql.H{"status": "banned"})
// 存在性 / 计数
ok, err := repo.ExistsWhere[User](sql.H{"email": "[email protected]"})
n, err := repo.CountWhere[User](sql.H{"active": true})
n, err := repo.CountEvery[User]()
事务
repo.WithTx 在单条事务绑定连接上运行回调。回调收到一个 *repo.Tx,其助手方法都在该事务上执行;泛型助手通过 *With 变体传入 tx.Executor():
users := sql.TableOf("users")
err := repo.WithTx(db, func(tx *repo.Tx) error {
if _, err := repo.InsertWith[User](tx.Executor(), sql.Insert(sql.H{"name": "John"}).IntoTable(users)); err != nil {
return err
}
n, err := tx.Count(sql.SelectColumns("count(*)").FromTable(users))
if err != nil {
return err
}
return nil // 提交;返回非 nil 即回滚
})
用 tx.Raw() 可以拿到 *sql.Tx 执行手写 SQL。没有公开的
Commit/Rollback——结果跟随回调的返回值,repo.WithTxContext 支持传入
context。JoinQuery/Preloader 仅限连接池,不能在事务内运行。
乐观锁配方:用 UpdateAffected 加版本检查,保证并发写只有最新者胜出:
affected, err := tx.UpdateAffected(
sql.UpdateTable(users).
Set(sql.H{"name": "Jane", "version": sql.Expr("version + 1")}).
Where(sql.AllOf(sql.Eq("id", 1), sql.Eq("version", currentVersion))),
)
if err != nil {
return err
}
if affected == 0 {
return errors.New("stale record")
}
事务以 PostgreSQL 为主要目标。MySQL 的插入路径会在同一连接上补发一次查询,在事务内属于尽力而为。
预加载(eager loading)
Preload 用几条查询替代 N+1 循环:
users, _ := repo.FindBy[User](sql.H{})
err := repo.Preload("Profile", "Posts").Exec(&users)
// 嵌套与条件预加载
err := repo.Preload("Posts").ThenPreload("Comments").Exec(&users)
err := repo.PreloadCond("Posts", sql.AllOf(
sql.Eq("published", true),
sql.Gte("created_at", "2024-01-01"),
)).Exec(&users)
联表
results, err := repo.Join(User{}).LeftJoins("Profile").Find()
results, err := repo.Join(User{}).
Joins("Posts", sql.Gt("posts.views", 100)).
Where(sql.Eq("users.active", true)).
OrderBy("users.name ASC").
Page(1, 20).
Find()
count, err := repo.Join(User{}).Joins("Posts").Count()
var users []*User
err := repo.Join(User{}).LeftJoins("Profile").FindInto(&users)
Rails 对照
| Rails ActiveRecord | Airway |
|---|---|
User.find(id) |
repo.FindByID[User](id) |
User.find_by(email: e) |
repo.FindOneBy[User](sql.H{"email": e}) |
User.where(active: true) |
repo.FindBy[User](sql.H{"active": true}) |
User.all |
repo.FindAll[User]() |
User.create(attrs) |
repo.CreateFrom[User](attrs) |
User.update(id, attrs) |
repo.UpdateByID[User](id, attrs) |
User.delete(id) |
repo.DeleteByID[User](id) |
User.joins(:profile) |
repo.Join(User{}).Joins("Profile") |
User.includes(:posts) |
repo.Preload("Posts").Exec(&users) |
User.count |
repo.CountEvery[User]() |
User.where(active: true).count |
repo.CountWhere[User](sql.H{"active": true}) |
Repo REPL
直接对已配置的数据库操作 lib/repo:
go run . repl # 使用已配置的 DSN
go run . repl --driver sqlite --dsn ./tmp/airway.db
REPL 只能看到它所在二进制编译进的模型(经 lib/replreg 注册)。在项目内,airway repl 会自动代理到 go run . repl,因此你项目的模型会出现;项目外只能看到框架内置模型。
命令:help、driver、tables、exit。输入 Go 表达式即可求值——builder 会打印编译后的 SQL,repo.* 调用直接作用于数据库:
repo.FindOne("posts", sql.Eq("id", 1))
repo.Find[models.Post](pg.Select("id").Where(sql.Eq("id", 1)))
repo.Insert[models.Post](pg.H{"id": 1234, "title": "hello"})
repo.Update("posts", pg.H{"published": false}, sql.Eq("id", 1))
repo.Delete("posts", sql.Eq("id", 1))
pg.Select("*").From("posts").Where(sql.Eq("id", 1))
可用命名空间:repo、sql、pg、mysql、sqlite、models。
repo.Find/FindOne/Count/Exists 接受构建好的语句或 表 + 条件;类型化调用支持匿名结构体与应用模型。全表更新/删除需要显式传入 true 作为最后一个参数。
文件存储
lib/storage 是本地目录或云后端(S3 / R2 / COS)之上的统一层。通过 STORAGE_DRIVER 配置后端:
# 本地
STORAGE_DRIVER="local"
STORAGE_ROOT="./data/storage"
# 云(S3 兼容):可选 s3 / r2 / cos
STORAGE_DRIVER="s3"
STORAGE_REGION="us-east-1"
STORAGE_BUCKET="my-bucket"
STORAGE_ACCESS_KEY="..."
STORAGE_SECRET_KEY="..."
# STORAGE_PUBLIC_URL="https://cdn.example.com" # 可选 CDN 基址
在代码中经当前后端使用:
store := storage.Current() // 启动时由 storage.Setup 安装
err := store.Put(ctx, "docs/report.pdf", storage.Object{
Reader: file,
Size: size,
ContentType: "application/pdf",
})
rc, err := store.Get(ctx, "docs/report.pdf") // 用完关闭
ok, err := store.Exists(ctx, "docs/report.pdf")
url, err := store.URL(ctx, "docs/report.pdf", 24*time.Hour)
err := store.Delete(ctx, "docs/report.pdf")
URL() 对本地后端返回应用自身的下载路径,对云后端返回 CDN 或预签名 URL。应用在同一层之上暴露 REST API:
# 上传(multipart 字段 "file",可选 "dir")
curl -F "[email protected]" -F "dir=docs" http://127.0.0.1:1900/api/v1/storage
# => {"key":"docs/202609/ab12cd....pdf","url":"/api/v1/storage/docs/202609/ab12cd....pdf","size":12345}
# 下载 / 删除
curl -O http://127.0.0.1:1900/api/v1/storage/docs/202609/ab12cd....pdf
curl -X DELETE http://127.0.0.1:1900/api/v1/storage/docs/202609/ab12cd....pdf
完整内容见文件存储指南。
部署
二进制是自包含的。构建纯 Go 镜像(无需 CGO 工具链):
just docker # 或:docker build -t airway .
docker run -p 1900:1900 -e AIRWAY_ENV=production -e DSN="sqlite:///app/tmp/airway.db" airway
Dockerfile 从 daocloud.io 镜像拉取基础镜像,并把 Go module 代理指向 goproxy.cn,因此在默认源缓慢或不可达的网络环境下也能开箱构建;不需要镜像 的话移除即可。
部署前后运行迁移:
./airway db:migrate
compose 示例见 docs/docker-compose.yml.example。如需在反向代理后以路径前缀服务,设置 URL_PREFIX(如 /airway)——见 HTTP 端点。