# x-admin

**Repository Path**: jiankechu/x-admin

## Basic Information

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

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2025-06-05
- **Last Updated**: 2025-09-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# X-Admin - 模块化CRUD管理后台

[![Go Version](https://img.shields.io/badge/Go-1.21+-blue.svg)](https://golang.org)
[![Vue Version](https://img.shields.io/badge/Vue-3.0+-green.svg)](https://vuejs.org)
[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

一个基于 **Vue 3** + **Gin** 的现代化管理后台脚手架，采用**模块化架构设计**，支持通过命令行一键生成完整的CRUD前后端代码。

## ✨ 核心特性

- 🏗️ **模块化架构**: 按功能模块组织代码，高内聚低耦合
- 🚀 **一键生成**: 通过交互式命令行快速生成前后端CRUD代码
- 🎯 **现代技术栈**: Vue 3 + Vite + Element Plus + Gin + GORM
- 📦 **开箱即用**: 完整的项目结构和最佳实践
- 🔧 **高度可定制**: 支持自定义模板和配置
- 📱 **响应式设计**: 适配桌面和移动端
- 🔐 **完整权限系统**: 用户-角色-权限三级权限管理，支持菜单和按钮级权限控制
- 📊 **智能文件上传**: 支持多种存储驱动和文件类型
- 🔄 **数据库逆向**: 从现有数据库表生成YAML配置
- 🗑️ **全局软删除**: 自动处理软删除逻辑，数据安全可恢复
- 📝 **优雅日志系统**: 结构化日志记录，支持多级别和可配置输出
- 🔧 **模块化迁移**: 每个模块独立管理数据库迁移和初始化

## 🏗️ 技术架构

### 后端技术栈
- **框架**: Gin (Go Web框架)
- **ORM**: GORM (Go对象关系映射)
- **数据库**: MySQL/PostgreSQL/SQLite
- **认证**: JWT Token
- **文档**: Swagger API文档
- **日志**: Logrus 结构化日志
- **中间件**: 统一的CORS、JWT认证、日志记录
- **迁移**: 模块化数据库迁移系统
- **软删除**: 全局软删除作用域

### 前端技术栈
- **框架**: Vue 3 (Composition API)
- **构建工具**: Vite
- **UI组件**: Element Plus
- **状态管理**: Pinia
- **路由**: Vue Router 4
- **HTTP客户端**: Axios
- **图标**: Element Plus Icons

## 🏗️ 模块化架构

### 核心设计理念

X-Admin 采用**按功能模块组织**的架构模式，而非传统的按技术层分层。每个业务模块包含完整的 MVC 结构，实现高内聚低耦合。

### 项目结构

```
x-admin/
├── generator/                  # 智能代码生成器 (独立Go模块)
├── backend/                    # 后端Go项目
│   ├── internal/
│   │   ├── modules/           # 🎯 业务模块 (核心特性)
│   │   │   ├── auth/          # 认证模块
│   │   │   │   ├── model.go   # 数据模型
│   │   │   │   ├── repository.go # 数据访问层
│   │   │   │   ├── service.go # 业务逻辑层
│   │   │   │   ├── handler.go # HTTP处理器
│   │   │   │   ├── router.go  # 路由注册
│   │   │   │   └── migrate.go # 模块迁移
│   │   │   ├── user/          # 用户管理模块
│   │   │   ├── role/          # 角色管理模块
│   │   │   ├── permission/    # 权限管理模块
│   │   │   ├── upload/        # 文件上传模块
│   │   │   └── ...            # 其他业务模块
│   │   ├── middleware/        # 统一中间件目录
│   │   │   ├── cors.go        # CORS中间件
│   │   │   ├── jwt.go         # JWT认证中间件
│   │   │   └── logger.go      # 日志中间件
│   │   └── router/            # 主路由
│   ├── pkg/                   # 可复用包
│   │   ├── database/          # 数据库连接和迁移
│   │   ├── logger/            # 日志工具
│   │   ├── migrate/           # 迁移接口
│   │   ├── response/          # 统一响应格式
│   │   ├── storage/           # 文件存储
│   │   ├── utils/             # 工具函数
│   │   └── validator/         # 数据验证
│   └── config/                # 配置管理
├── frontend/                  # 前端Vue项目
│   └── src/
│       ├── modules/           # 🎯 模块化核心
│       │   ├── auth/          # 认证模块
│       │   ├── user/          # 用户管理模块
│       │   ├── role/          # 角色管理模块
│       │   ├── permission/    # 权限管理模块
│       │   └── upload/        # 文件上传模块
│       ├── components/        # 通用组件
│       ├── utils/             # 工具函数
│       └── router/            # 路由配置
├── templates/                 # 代码生成模板
│   ├── backend/module/        # 模块化后端模板
│   └── frontend/              # 前端模板
├── config/models/             # 模型配置文件
├── docs/                      # 项目文档
└── scripts/                   # 工具脚本
```

### 模块化优势

- ✅ **高内聚**: 相关功能集中在一个模块内
- ✅ **低耦合**: 模块间依赖关系清晰
- ✅ **易维护**: 修改某个功能只需关注对应模块
- ✅ **便扩展**: 新增功能只需添加新模块
- ✅ **团队协作**: 不同开发者可独立开发不同模块
- ✅ **独立迁移**: 每个模块管理自己的数据库迁移
- ✅ **依赖管理**: 自动处理模块间的依赖关系

## 🚀 快速开始

### 环境要求

- Go 1.21+
- Node.js 16+
- MySQL 8.0+ (或其他支持的数据库)

### 安装依赖

```bash
# 克隆项目
git clone <your-repo-url>
cd x-admin

# 安装后端依赖
cd backend
go mod tidy

# 安装前端依赖
cd ../frontend
npm install
```

### 配置数据库

1. 复制配置文件模板：
```bash
cp backend/config/app.yaml.example backend/config/app.yaml
```

2. 修改数据库配置：
```yaml
database:
  driver: mysql
  host: localhost
  port: 3306
  username: root
  password: your_password
  database: x_admin

# 日志配置
logger:
  level: info
  format: json
  output: file
  filename: logs/app.log
  max_size: 100
  max_age: 30
  compress: true

# 服务器配置
server:
  port: 8080
  mode: debug
```

### 启动服务

```bash
# 启动后端服务
cd backend
go run main.go

# 启动前端服务 (新终端)
cd frontend
npm run dev
```

访问 http://localhost:3000 查看前端界面
访问 http://localhost:8080 查看后端API
访问 http://localhost:8080/swagger/index.html 查看API文档

### 生成API文档

如果Swagger文档无法正常显示，需要先生成API文档：

```bash
# 安装swag工具
go install github.com/swaggo/swag/cmd/swag@latest

# 在backend目录下生成Swagger文档
cd backend
swag init --parseInternal --parseDependency

# 重新启动后端服务
go run main.go
```

生成完成后，可以访问 http://localhost:8080/swagger/index.html 查看完整的API文档。

**注意事项**：
- 首次运行项目需要生成Swagger文档
- 修改API接口注释后需要重新运行 `swag init` 命令
- 确保在backend目录下执行swag命令

### 默认账户

- **管理员账户**: admin / admin123
- **普通用户账户**: user / user123

## 🛠️ 智能代码生成器

### 交互式生成体验

```bash
cd generator
go run main.go
```

生成器提供友好的交互式界面：

```
🚀 欢迎使用 X-Admin 代码生成器 (交互式模式)
==================================================

请选择操作:
1. 生成指定模型的CRUD代码
2. 生成所有模型的CRUD代码
3. 查看现有模型配置
4. 创建新的模型配置
5. 从数据库表生成YAML配置
6. 查看临时目录内容
7. 清理临时目录
8. 显示帮助信息
0. 退出
```

### 1. 快速创建模型配置

选择选项 4，交互式创建模型：

```bash
🔧 创建模型配置: Product
========================================
请输入表名 (默认: products):
请输入模型注释: 商品管理
是否要添加自定义字段? (y/N): y

📝 添加自定义字段 (输入空行结束):
字段名称: name
字段类型 (默认: string):
字段注释: 商品名称
是否必填? (y/N): y
字符串长度 (默认: 255): 100
✓ 已添加字段: name (string)

字段名称: price
字段类型 (默认: string): float64
字段注释: 商品价格
是否必填? (y/N): y
✓ 已添加字段: price (float64)
```

### 2. 从数据库逆向生成

选择选项 5，从现有数据库表生成配置：

```bash
📁 找到配置文件: backend/config/app.yaml
✅ 数据库连接成功: root@localhost:3306/x_admin

📋 数据库表列表:
1. users (用户表)
2. roles (角色表)
3. permissions (权限表)
4. products (商品表)

请选择要生成配置的表 (输入序号，多个用逗号分隔): 4
✅ 已生成配置文件: config/models/product.yaml
```

### 3. 生成模块化代码

生成器会创建完整的模块结构：

**模块化后端文件** (在 `generated_temp/backend/internal/modules/product/`):
- `model.go` - 数据模型和请求结构体
- `repository.go` - 数据访问层接口和实现
- `service.go` - 业务逻辑层接口和实现
- `handler.go` - HTTP处理器和API文档
- `router.go` - 路由注册和依赖注入

**前端模块化文件** (在 `generated_temp/frontend/src/modules/product/`):
- `list.vue` - 列表页面
- `form.vue` - 表单页面
- `api.js` - API接口

**使用说明**:
- `product_module_usage.md` - 详细的集成说明
- `router_register_product.txt` - 路由注册代码

### 4. 一键复制到项目

使用提供的复制脚本：

```bash
./scripts/copy-modules.sh
```

脚本会智能复制生成的代码到项目目录，并提供详细的集成指导。

## 📚 模块化开发指南

### 启动应用

X-Admin 使用模块化路由架构：

```go
// main.go 中的路由初始化
r := router.Init(db, cfg)
```

### 内置核心模块

| 模块 | 功能 | 路由前缀 | 特性 |
|------|------|----------|------|
| **auth** | 用户认证 | `/api/v1/auth` | JWT认证、用户信息、菜单权限 |
| **user** | 用户管理 | `/api/v1/users` | CRUD、角色分配、密码重置 |
| **role** | 角色管理 | `/api/v1/roles` | CRUD、权限分配、层级管理 |
| **permission** | 权限管理 | `/api/v1/permissions` | 树形结构、菜单/按钮权限 |
| **upload** | 文件上传 | `/api/v1/upload` | 多存储驱动、文件管理 |

### 添加新业务模块

1. **使用生成器创建**：
   ```bash
   cd generator
   go run main.go
   # 选择 "4. 创建新的模型配置"
   ```

2. **复制生成的代码**：
   ```bash
   ./scripts/copy-modules.sh
   ```

3. **注册模块路由**：
   ```go
   // 在 router.go 中添加
   newmodule.RegisterRoutes(protected, db)
   ```

### 模块开发最佳实践

#### 1. 模块结构规范
```
modules/product/
├── model.go      # 数据模型 + 请求/响应结构体
├── repository.go # 数据访问层接口 + 实现
├── service.go    # 业务逻辑层接口 + 实现
├── handler.go    # HTTP处理器 + API文档
├── router.go     # 路由注册 + 依赖注入
└── migrate.go    # 模块数据库迁移和初始化
```

#### 2. 接口设计原则
- Repository: 专注数据访问，不包含业务逻辑
- Service: 处理业务规则，调用Repository
- Handler: 处理HTTP请求，调用Service
- Router: 注册路由，创建依赖关系

#### 3. 错误处理规范
```go
// Service层返回业务错误
if user == nil {
    return nil, errors.New("用户不存在")
}

// Handler层处理HTTP错误
if err.Error() == "用户不存在" {
    response.NotFound(c, err.Error())
    return
}
```

### API设计规范

所有API遵循RESTful设计：

```bash
# 标准CRUD操作
GET    /api/v1/products      # 获取列表(支持分页/搜索)
GET    /api/v1/products/:id  # 获取详情
POST   /api/v1/products      # 创建资源
PUT    /api/v1/products/:id  # 更新资源
DELETE /api/v1/products/:id  # 删除资源

# 特殊操作
POST   /api/v1/products/:id/action  # 特定动作
GET    /api/v1/products/export      # 导出数据
```

### 统一响应格式

```json
{
  "code": 200,
  "message": "success",
  "data": {},
  "timestamp": "2024-01-01T00:00:00Z"
}
```

## 🔧 模块化迁移系统

X-Admin 采用创新的模块化迁移架构，每个模块独立管理自己的数据库迁移和初始化逻辑。

### 迁移系统特性

- ✅ **模块独立**: 每个模块管理自己的迁移逻辑
- ✅ **依赖管理**: 自动处理模块间的依赖关系
- ✅ **拓扑排序**: 按依赖关系自动确定迁移顺序
- ✅ **接口统一**: 所有模块实现相同的迁移接口
- ✅ **脚手架友好**: 适合快速原型开发

### 迁移接口设计

```go
type ModuleMigrator interface {
    GetName() string                    // 模块名称
    GetModels() []interface{}           // 需要迁移的模型
    GetDependencies() []string          // 依赖的模块
    Migrate(db *gorm.DB) error         // 执行迁移逻辑
    Seed(db *gorm.DB) error            // 初始化数据
}
```

### 模块依赖关系

```
permission (基础模块)
    ↓
role (依赖权限模块)
    ↓
user (依赖角色模块)
    ↓
upload (依赖用户模块)
```

### 迁移执行流程

1. **注册模块迁移器**
2. **依赖关系拓扑排序**
3. **按顺序执行表结构迁移**
4. **按顺序执行模块特定迁移**
5. **按顺序执行数据初始化**

### 添加新模块迁移

```go
// 实现迁移接口
type ProductMigrator struct{}

func (m *ProductMigrator) GetName() string {
    return "product"
}

func (m *ProductMigrator) GetDependencies() []string {
    return []string{"user"} // 依赖用户模块
}

func (m *ProductMigrator) Migrate(db *gorm.DB) error {
    // 创建关联表、索引等
    return nil
}

func (m *ProductMigrator) Seed(db *gorm.DB) error {
    // 初始化基础数据
    return nil
}
```

### 自定义模板

模板位置：`templates/backend/module/`
- 支持Go template语法
- 可自定义字段类型映射
- 支持条件渲染和循环

## � 权限管理系统

X-Admin 提供完整的三级权限管理体系：**用户 → 角色 → 权限**

### 权限系统特性

- ✅ **三级权限**: 用户-角色-权限的经典RBAC模型
- ✅ **树形结构**: 支持权限的层级管理
- ✅ **菜单权限**: 控制用户可访问的菜单
- ✅ **按钮权限**: 精确到按钮级别的权限控制
- ✅ **动态菜单**: 根据用户权限动态生成菜单
- ✅ **权限继承**: 父级权限自动包含子级权限
- ✅ **软删除**: 所有权限数据支持软删除

### 权限类型

| 类型 | 说明 | 示例 |
|------|------|------|
| **menu** | 菜单权限 | 用户管理、角色管理 |
| **button** | 按钮权限 | 创建用户、删除角色 |

### 内置权限结构

```
仪表板 (dashboard)
系统管理 (system)
├── 用户管理 (system:user)
│   ├── 查看用户 (system:user:read)
│   ├── 创建用户 (system:user:create)
│   ├── 编辑用户 (system:user:update)
│   └── 删除用户 (system:user:delete)
├── 角色管理 (system:role)
│   ├── 查看角色 (system:role:read)
│   ├── 创建角色 (system:role:create)
│   ├── 编辑角色 (system:role:update)
│   └── 删除角色 (system:role:delete)
└── 权限管理 (system:permission)
    ├── 查看权限 (system:permission:read)
    ├── 创建权限 (system:permission:create)
    ├── 编辑权限 (system:permission:update)
    └── 删除权限 (system:permission:delete)
```

### 默认角色

| 角色 | 权限范围 | 说明 |
|------|----------|------|
| **超级管理员** (admin) | 所有权限 | 拥有系统全部功能权限 |
| **普通用户** (user) | 基础权限 | 仅有仪表板和查看用户权限 |

### 权限验证

```go
// 检查用户是否有特定权限
func (s *AuthService) HasPermission(userID uint, permission string) bool {
    // 实现权限检查逻辑
}

// 获取用户菜单
func (s *AuthService) GetUserMenus(userID uint) []Menu {
    // 根据用户权限返回可访问菜单
}
```

## �📖 文档

- 📋 [模块化架构详解](docs/modular-architecture.md)
- 🔄 [架构迁移指南](docs/migration-guide.md)
- 🔐 [权限系统详解](docs/permission-system.md)

## 🚀 部署

### Docker 部署

```bash
# 构建并启动服务
docker-compose up -d

# 查看服务状态
docker-compose ps
```

### 手动部署

```bash
# 构建后端
cd backend
go build -o x-admin main.go

# 构建前端
cd frontend
npm run build

# 启动服务
./x-admin
```

## 🤝 贡献指南

1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 打开 Pull Request

### 开发规范

- 新功能请使用**模块化架构**
- 遵循Go和Vue的最佳实践
- 添加适当的测试和文档
- 保持代码风格一致

## 📄 许可证

本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情

## 🙏 致谢

- [Gin](https://github.com/gin-gonic/gin) - 高性能Go Web框架
- [Vue.js](https://vuejs.org/) - 渐进式JavaScript框架
- [Element Plus](https://element-plus.org/) - Vue 3 UI组件库
- [GORM](https://gorm.io/) - 优秀的Go ORM库
- [Vite](https://vitejs.dev/) - 下一代前端构建工具

## ⭐ Star History

如果这个项目对您有帮助，请给个 ⭐️ 支持一下！

[![Star History Chart](https://api.star-history.com/svg?repos=your-username/x-admin&type=Date)](https://star-history.com/#your-username/x-admin&Date)

---

**X-Admin** - 让CRUD开发更简单，让架构更优雅 🎉