# figmgr

**Repository Path**: ufffnwfn/figmgr

## Basic Information

- **Project Name**: figmgr
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-16
- **Last Updated**: 2026-04-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# FibMgr

FibMgr 是一个基于 Go + Fiber 框架构建的后台管理系统，采用整洁架构设计，支持代码生成、RBAC 权限控制、Swagger 文档自动生成等特性。

## 项目架构

```
.
├── cmd/                    # 可执行程序入口
│   ├── server/            # 主应用程序
│   └── routegen/          # 路由代码生成工具
├── internal/              # 内部代码（不对外暴露）
│   ├── controller/        # 控制器层（HTTP 处理器）
│   ├── service/           # 业务逻辑层
│   ├── repository/        # 数据访问层
│   ├── dao/               # 数据访问对象（GORM Query）
│   ├── model/             # 数据模型
│   ├── router/            # 路由注册
│   ├── middleware/        # HTTP 中间件
│   ├── acl/               # 访问控制层（Casbin 适配器）
│   └── types/             # 请求/响应类型定义
├── pkg/                   # 可复用的公共包
│   ├── config/            # 配置管理
│   ├── database/          # 数据库连接
│   ├── logger/            # 日志工具
│   ├── response/          # 统一响应封装
│   ├── errcode/           # 错误码定义
│   ├── validate/          # 参数校验
│   ├── casbin/            # Casbin RBAC 初始化
│   └── snowflake/         # Snowflake ID 生成器
├── config/                # 配置文件
├── docs/                  # Swagger 文档（自动生成）
└── go.mod                 # Go 模块定义
```

---

## cmd 目录详解

`cmd` 目录包含项目的所有可执行程序入口。每个子目录代表一个独立的应用程序或工具。

### 1. cmd/server/main.go - 主应用程序入口

**作用**：FibMgr 后台管理系统的 HTTP 服务器入口，负责初始化所有组件并启动 Fiber Web 服务。

**功能职责**：

| 步骤 | 功能 | 说明 |
|------|------|------|
| 1 | 加载配置 | 从 `config/config.yaml` 读取应用配置 |
| 2 | 初始化日志 | 使用 Zap 日志库，支持结构化日志输出 |
| 3 | 初始化 Snowflake | 分布式 ID 生成器（用于生成唯一主键） |
| 4 | 初始化数据库 | 连接 PostgreSQL/MySQL 数据库（可选） |
| 5 | 初始化 Casbin | RBAC 权限控制（依赖数据库） |
| 6 | 创建 Fiber 应用 | 配置超时、错误处理等 |
| 7 | 依赖注入 | 组装 Service → Controller |
| 8 | 注册路由 | 设置 HTTP 路由和中间件 |
| 9 | Swagger 文档 | 开发模式下启用 API 文档 |
| 10 | 优雅关闭 | 监听系统信号，平滑关闭服务 |

**运行方式**：

```bash
# 开发模式运行
go run cmd/server/main.go

# 或先编译再运行
go build -o bin/server cmd/server/main.go
./bin/server
```

**配置要求**：
- 需要在项目根目录下存在 `config/config.yaml` 配置文件
- 数据库连接是可选的，但 RBAC 功能需要数据库支持

---

### 2. cmd/routegen/ - 路由代码生成工具

**作用**：一个代码生成工具，通过解析 Controller 方法上的注解自动生成路由注册代码，避免手写重复的路由注册逻辑。

**设计思想**：
- **注解驱动**：在 Controller 方法上添加注解声明路由
- **代码生成**：编译时生成类型安全的路由注册代码
- **减少样板**：无需手动维护路由注册表

#### 2.1 文件结构

```
cmd/routegen/
├── main.go      # 程序入口，命令行参数处理
├── parser.go    # Go 源码解析器，提取注解信息
├── generator.go # 代码生成器，生成路由注册代码
└── types.go     # 类型定义（RouteInfo, ControllerMeta）
```

#### 2.2 各文件功能详解

##### main.go - 程序入口

负责命令行参数解析、调用解析器和生成器、输出结果文件。

**命令行参数**：

| 参数 | 默认值 | 说明 |
|------|--------|------|
| `-dir` | `internal/controller` | Controller 源码目录 |
| `-out` | `internal/router/routes_gen.go` | 生成文件输出路径 |
| `-hint` | `false` | 输出 Casbin 策略参考 |

**使用示例**：

```bash
# 基本用法（使用默认值）
go run ./cmd/routegen

# 指定自定义目录和输出文件
go run ./cmd/routegen -dir internal/controller -out internal/router/routes_gen.go

# 同时输出 Casbin 策略提示
go run ./cmd/routegen -hint
```

##### parser.go - 注解解析器

使用 Go 标准库的 `go/ast` 包解析 Controller 源文件，提取方法上的路由注解。

**支持的注解格式**：

```go
// @route METHOD PATH     — 必须：定义 HTTP 方法和路径
// @auth                   — 可选：需要 JWT 认证
// @casbin                 — 可选：需要 Casbin RBAC 鉴权（隐含 @auth）
// @summary 接口描述       — 可选：接口摘要（用于文档）
```

**完整示例**：

```go
// UserController 用户管理控制器
type UserController struct {
    userSvc *service.UserService
}

// @route GET /api/v1/users
// @auth
// @summary 获取用户列表
func (u *UserController) List(c fiber.Ctx) error {
    // 业务逻辑...
}

// @route POST /api/v1/users
// @casbin
// @summary 创建用户（需要管理员权限）
func (u *UserController) Create(c fiber.Ctx) error {
    // 业务逻辑...
}

// @route GET /api/v1/users/:id
// @summary 获取用户详情（公开接口）
func (u *UserController) Get(c fiber.Ctx) error {
    // 业务逻辑...
}
```

**注解规则**：
- `@route` 是唯一的必需注解，格式为 `@route METHOD PATH`
- 支持的方法：GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS
- `@casbin` 会自动隐含 `@auth`，无需重复添加
- 注解写在方法的文档注释中（以 `//` 开头）

##### generator.go - 代码生成器

根据解析出的路由信息，使用 Go 模板生成类型安全的路由注册代码。

**生成的代码结构**：

```go
// Code generated by routegen. DO NOT EDIT.

package router

// Controllers 所有控制器集合
type Controllers struct {
    UserController *controller.UserController
    // ... 其他控制器
}

// RegisterGeneratedRoutes 注册由注解生成的路由
func RegisterGeneratedRoutes(app *fiber.App, cfg *config.Config, ctrls *Controllers) {
    // ── 公开路由（无需认证） ──
    app.Add([]string{"GET"}, "/api/v1/users/:id", ctrls.UserController.Get)
    
    // ── 认证路由（需要 JWT） ──
    authGroup := app.Group("", middleware.NewAuth(&cfg.JWT))
    authGroup.Add([]string{"GET"}, "/api/v1/users", ctrls.UserController.List)
    
    // ── RBAC 路由（需要 JWT + Casbin） ──
    rbacGroup := app.Group("", middleware.NewAuth(&cfg.JWT), middleware.NewCasbin())
    rbacGroup.Add([]string{"POST"}, "/api/v1/users", ctrls.UserController.Create)
}
```

**路由分组策略**：
- **公开路由**：无任何中间件
- **认证路由**：添加 JWT 认证中间件
- **RBAC 路由**：添加 JWT + Casbin 鉴权中间件

##### types.go - 类型定义

定义了解析和生成过程中使用的核心数据结构：

```go
// RouteInfo 单条路由信息
type RouteInfo struct {
    Method         string // HTTP 方法
    Path           string // 路由路径
    ControllerType string // 控制器类型名
    HandlerName    string // 方法名
    ReceiverName   string // 接收者变量名
    Auth           bool   // 是否需要 JWT
    Casbin         bool   // 是否需要 RBAC
    Summary        string // 接口摘要
}

// ControllerMeta 控制器元数据
type ControllerMeta struct {
    TypeName    string      // 类型名
    Routes      []RouteInfo // 路由列表
    PackagePath string      // 包导入路径
}
```

#### 2.3 使用流程

```
1. 在 Controller 方法上添加注解
        ↓
2. 运行 routegen 工具
   go run ./cmd/routegen
        ↓
3. 生成 routes_gen.go 文件
        ↓
4. 在 router.Setup() 中调用 RegisterGeneratedRoutes()
        ↓
5. 编译运行服务器
```

#### 2.4 在项目中集成

生成的代码需要在 [`internal/router/router.go`](internal/router/router.go) 中调用：

```go
func Setup(app *fiber.App, cfg *config.Config, healthCtrl *controller.HealthController) {
    // 中间件...
    
    // 注册生成的路由
    ctrls := &Controllers{
        HealthController: healthCtrl,
        // 其他控制器...
    }
    RegisterGeneratedRoutes(app, cfg, ctrls)
}
```

---

### 3. 其他可能的 cmd 子目录

随着项目发展，可以在 `cmd` 目录下添加更多工具或应用程序：

#### 3.1 建议添加的工具

| 目录 | 用途 | 示例场景 |
|------|------|----------|
| `cmd/migrate` | 数据库迁移工具 | 执行 schema 变更、数据迁移 |
| `cmd/seeder` | 数据填充工具 | 初始化测试数据、默认角色 |
| `cmd/cli` | 管理命令行工具 | 创建管理员账号、重置密码 |
| `cmd/worker` | 后台任务处理器 | 异步任务队列消费 |

#### 3.2 添加新工具的规范

每个 `cmd` 子目录应该：
1. 包含独立的 `main.go` 作为入口
2. 使用 `flag` 包处理命令行参数
3. 返回非零退出码表示错误
4. 在 README 中说明用途和使用方法

---

## 快速开始

### 环境要求

- Go 1.25+
- PostgreSQL 12+ 或 MySQL 8+
- Make（可选，用于使用 Makefile 命令）

### 安装依赖

```bash
go mod download
```

### 配置

复制配置文件并修改：

```bash
cp config/config.example.yaml config/config.yaml
# 编辑 config/config.yaml 修改数据库连接等配置
```

### 运行

```bash
# 启动服务器
go run cmd/server/main.go

# 生成路由代码（开发时）
go run ./cmd/routegen

# 生成 Swagger 文档（开发时）
swag init -g cmd/server/main.go
```

### 访问

- API 服务：`http://localhost:8080`
- Swagger 文档：`http://localhost:8080/swagger/index.html`（仅开发模式）

---

## 开发规范

### 添加新接口

1. 在 `internal/controller/` 创建或修改控制器
2. 添加路由注解：
   ```go
   // @route GET /api/v1/example
   // @auth
   // @summary 示例接口
   ```
3. 运行代码生成：
   ```bash
   go run ./cmd/routegen
   ```
4. 重启服务器测试

### 代码生成命令

```bash
# 生成路由
go run ./cmd/routegen

# 生成 Swagger 文档
swag init -g cmd/server/main.go

# 生成 GORM Query 代码（如果使用）
go run ./cmd/daogen
```

---

## 技术栈

- **Web 框架**: [Fiber v3](https://github.com/gofiber/fiber)
- **ORM**: [GORM](https://gorm.io/)
- **权限控制**: [Casbin](https://casbin.org/)
- **配置管理**: [Viper](https://github.com/spf13/viper)
- **日志**: [Zap](https://github.com/uber-go/zap)
- **文档**: [Swaggo](https://github.com/swaggo/swag)
- **ID 生成**: [Snowflake](https://github.com/bwmarrin/snowflake)

---

## License

Apache 2.0