Cool-Admin Go 版是基于 GoFrame v2 的后台权限管理系统，提供模块化、插件化、声明式 CRUD、权限认证和代码生成能力，帮助开发者快速构建后台管理服务。前往 GoFrame 官网 了解更多。
## 快速开始
### 环境要求
- Go `1.26.6`
- MySQL `8.x`，并提前创建数据库 `cool-go`
- Redis（本地配置默认使用 Redis 保存会话和风控状态）
### 配置
项目提供两份完整配置：
- `manifest/config/config.yaml`：默认配置，关闭 EPS、数据库种子和菜单种子导入。
- `manifest/config/config.local.yaml`：本地开发配置，开启 EPS、数据库种子和菜单种子导入。
两份配置都使用 Redis 保存 Session 和登录风控状态，并包含 MySQL、Redis 和 JWT 配置。首次启动前按实际环境修改 MySQL、Redis 连接：
```yaml
database:
default:
- link: "mysql:root:123456@tcp(127.0.0.1:3306)/cool-go?loc=Local&parseTime=true&charset=utf8mb4"
createdAt: createTime
updatedAt: updateTime
redis:
default:
address: "127.0.0.1:6379"
db: 0
```
还需要把 `cool.auth.jwt.keys.primary` 改为至少 32 字节的固定随机密钥。仓库中的默认值仅用于标识配置项，长度不满足框架校验，不能直接用于启动或生产环境。
### 下载依赖并运行
```bash
go mod download
COOL_CONFIG_FILE=manifest/config/config.local.yaml go run ./cmd/cool run
```
服务默认监听 [http://localhost:8001](http://localhost:8001)。`config.local.yaml` 开启了 `initDB` 和 `initMenu`，首次启动会自动创建业务表并导入模块初始化数据。
不设置 `COOL_CONFIG_FILE` 时，框架默认读取 `manifest/config/config.yaml`：
```bash
go run ./cmd/cool run
```
`cool run` 会先检查生成代码是否与源码一致。如果提示 `modules/modules.go` 过期，执行：
```bash
go run ./cmd/cool generate
COOL_CONFIG_FILE=manifest/config/config.local.yaml go run ./cmd/cool run
```
## CRUD：快速增删改查
下面以 `demo` 模块的商品管理为例。框架会根据目录和函数名推导路由，无需手工注册模块、依赖或 HTTP Handler。
### 1. 声明模块
新建 `modules/demo/config.go`：
```go
package demo
import "github.com/toothdy/cool-admin-go-next/cool-next/core/module"
// 示例模块运行配置
type Config struct{}
// 示例模块及其默认配置
func ModuleConfig() module.Declaration[Config] {
return module.Declaration[Config]{
Name: "示例模块",
Description: "演示快速 CRUD",
}
}
```
### 2. 声明实体
新建 `modules/demo/entity/goods.go`：
```go
package entity
import (
"github.com/gogf/gf/v2/frame/g"
"github.com/toothdy/cool-admin-go-next/cool-next/core/gnentity"
)
// 商品
type Goods struct {
g.Meta `orm:"table:demo_goods" description:"商品"`
gnentity.Base
Title string `json:"title" orm:"title" description:"标题" cool:"size=255"`
Pic string `json:"pic" orm:"pic" description:"图片" cool:"size=255"`
Price float64 `json:"price" orm:"price" description:"价格" cool:"precision=10,scale=2"`
}
// 商品表约束
func GoodsSchema() gnentity.Schema {
return gnentity.Schema{}
}
```
`gnentity.Base` 已包含 `id`、`createTime` 和 `updateTime`。应用启动时会根据实体声明创建表；对已有表只自动执行受支持的安全变更，存在破坏性差异时会停止启动并报告原因。
### 3. 声明服务
新建 `modules/demo/service/goods.go`：
```go
package service
import (
"github.com/toothdy/cool-admin-go-next/cool-next/core/gnservice"
"github.com/toothdy/cool-admin-go-next/modules/demo/entity"
)
// 商品业务服务
type GoodsService struct {
*gnservice.Base[entity.Goods, uint64]
}
// 创建商品业务服务
func NewGoods(base *gnservice.Base[entity.Goods, uint64]) *GoodsService {
return &GoodsService{Base: base}
}
```
嵌入的 `gnservice.Base` 已实现六个标准 CRUD 操作。需要自定义业务规则时，可在 `GoodsService` 上覆盖对应方法。
### 4. 声明控制器
新建 `modules/demo/controller/admin/goods.go`：
```go
package admin
import (
"github.com/toothdy/cool-admin-go-next/cool-next/core/gnctrl"
"github.com/toothdy/cool-admin-go-next/modules/demo/entity"
"github.com/toothdy/cool-admin-go-next/modules/demo/service"
)
// 商品接口
func AdminDemoGoodsController(goods *service.GoodsService) gnctrl.Definition {
return gnctrl.Admin().
Options(gnctrl.RouterOptions{Description: "商品", TagName: "商品"}).
Curd(gnctrl.CurdOption{
API: gnctrl.AllAPI(),
Entity: entity.Goods{},
Service: goods,
}).
Build()
}
```
生成代码并启动：
```bash
go run ./cmd/cool generate
COOL_CONFIG_FILE=manifest/config/config.local.yaml go run ./cmd/cool run
```
此时会生成以下接口：
- `POST /admin/demo/goods/add`：新增
- `POST /admin/demo/goods/delete`：删除
- `POST /admin/demo/goods/update`：修改
- `GET /admin/demo/goods/info`：详情
- `POST /admin/demo/goods/list`：列表
- `POST /admin/demo/goods/page`：分页
> `modules/modules.go` 由 `cool generate` 生成，不要手工修改。
## 构建与检查
```bash
# 生成静态装配代码
go run ./cmd/cool generate
# 检查生成代码是否最新
go run ./cmd/cool check
# 检查源码并构建到 bin/cool-admin-go-next
go run ./cmd/cool build
# 执行格式、依赖、静态分析、架构和构建检查
make check
```
生产环境直接使用默认的 `manifest/config/config.yaml`。部署前必须替换其中的数据库连接、Redis 连接和 JWT 签名密钥，并按需调整日志配置；该配置默认关闭 EPS、数据库种子和菜单种子导入。