FormulaGo

English | 中文

简介

FormulaGo 是一个高性能的企业后台管理框架，基于 Hertz 和 Ent 构建。遵循 Clean Architecture / DDD 设计理念，开箱即用的 RBAC 权限管理系统。

前端项目地址：formulago-front

• AI 原生 MCP Server — 内置 MCP(Model Context Protocol)服务，Claude 等 AI 助手可直接对话操作后台数据，进入"AI 管理后台"时代。
• 高性能 — 使用字节跳动核心框架 Hertz，已在数万个服务上验证。
• 模块化架构 — 4 层清晰分层：Handler → Logic → Domain → Data。
• 类型安全 ORM — Ent 生成类型安全的 Go 数据库操作代码。
• RBAC 权限控制 — Casbin 实现 API 级细粒度权限管理。
• 多数据库 — 支持 MySQL 和 PostgreSQL，自动迁移。
• OAuth 2.0 登录 — 内置 Google、GitHub、企业微信登录。
• 开箱即用 — 用户、角色、菜单、字典、Token、日志管理完整实现。

架构

biz/handler/  →  biz/logic/  →  biz/domain/  →  data/
(HTTP 层)        (业务逻辑)       (接口定义)     (数据访问)

技术栈

快速开始

前置条件

• Go 1.26+
• MySQL（或 PostgreSQL）
• Docker（可选，用于本地 MySQL）

1. 配置

编辑 configs/config.yaml 配置文件。敏感信息建议通过环境变量设置，避免提交到 git：

# 复制环境变量模板
cp secret.sh.example secret.sh

# 编辑 secret.sh 填入真实密钥
# 然后加载到当前 shell
source secret.sh

secret.sh 已加入 .gitignore，不会误提交。

2. 启动 MySQL

docker-compose up -d

3. 运行

go build -o formulago && ./formulago

4. 初始化数据库

curl http://localhost:8191/api/initDatabase

默认管理员账号：admin / formulago

内置功能

MCP Server（AI 助手接入）

FormulaGo 内置 MCP（Model Context Protocol）服务端 —— 把整个后台"变成"AI 可以调用的工具集，向 Claude 等 AI 原生应用打开一个受控的数据入口：

• AI 直接对话管理数据 — 例如"帮我列出前 10 个用户"即可查询后台数据，无需教它 HTTP 接口。
• 浏览器 OAuth 授权 — 用户在 Claude 里粘贴一个地址，自动打开浏览器登录授权（PKCE 保护），无二次密码管理。
• 与 HTTP 同等的安全边界 — 复用同一套 JWT 会话与 Casbin 权限：网页上没权限的，AI 同样调不了；token 必须经 PKCE 授权流下发，杜绝"裸 token 直连"旁路。
• 部署零成本 — 挂在主 Hertz 服务下（/api/mcp），不另起端口。

# Claude Code 一行接入
claude mcp add --transport http formulago https://your-domain/api/mcp

项目结构

├── api/                  # Protobuf 定义和生成模型
│   ├── model/            # 生成的 Go 结构体
│   └── admin/            # 管理员 API Protobuf IDL
├── biz/                  # 业务逻辑
│   ├── domain/           # 纯 Go 接口定义（无外部依赖）
│   ├── handler/          # HTTP 处理层（参数绑定、响应）
│   │   └── middleware/   # JWT 认证、Casbin 权限、日志
│   ├── logic/            # 业务逻辑实现
│   ├── mcp/              # MCP Server（工具、OAuth/PKCE、鉴权）
│   └── router/           # 路由注册（含 mcp/ 的 Hertz 挂载）
├── configs/              # YAML 配置文件（嵌入二进制）
├── data/                 # 数据访问层
│   ├── ent/              # Ent ORM 生成代码
│   │   └── schema/       # Ent 数据模型定义
│   ├── s3/               # 阿里云 OSS 适配器
│   └── ...               # MySQL、PostgreSQL、Redis、Casbin
└── pkg/                  # 通用工具包
    ├── captcha/          # 验证码缓存
    ├── encrypt/          # bcrypt 密码加密
    ├── img/              # 图片压缩
    ├── types/            # 常用类型工具
    └── wecom/            # 企业微信集成

开发指南

代码生成

Ent（数据模型 → CRUD）：

go generate ./data/ent

Hertz（Protobuf → 处理器和路由）：

hz update -I api -idl api/admin/admin.proto -model_dir api/model --unset_omitempty

hz update -I api -idl api/admin/admin.proto -model_dir api/model --unset_omitempty

新增/编辑实体步骤

下面是admin管理模块相关的步骤，其他模块的步骤类似

1. 在 data/ent/schema/ 创建/修改 schema
2. 运行 ent 代码生成
3. 在 biz/domain/admin/ 定义领域接口
4. 在 biz/logic/admin/ 实现业务逻辑
5. 在 api/admin/admin.proto Protobuf定义API接口
6. 运行 hz 生成处理器和路由
7. 在 biz/handler/admin/ 实现处理器逻辑，注意把req\resp放一起初始化，让所有返回都使用上resp

License

Apache License 2.0