# qctl

**Repository Path**: MM-Q/qctl

## Basic Information

- **Project Name**: qctl
- **Description**: qctl 是一个专为 qflag 命令行参数解析库开发的脚手架工具，旨在帮助开发者快速创建基于 qflag 的 Go 命令行应用程序。通过提供项目模板生成、代码结构优化等功能，qctl 让命令行工具开发变得更加高效和标准化。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-17
- **Last Updated**: 2026-01-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: Go语言

## README

# 🚀 qctl - qflag 脚手架工具

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Go Version](https://img.shields.io/badge/Go-1.25+-00ADD8?style=flat&logo=go)](https://golang.org)
[![Repository](https://img.shields.io/badge/Repository-Gitee-red?style=flat&logo=gitee)](https://gitee.com/MM-Q/qctl)
[![Status](https://img.shields.io/badge/Status-Active-success.svg)](https://gitee.com/MM-Q/qctl)

## 📖 项目简介

**qctl** 是一个专为 [qflag](https://gitee.com/MM-Q/qflag) 命令行参数解析库开发的脚手架工具，旨在帮助开发者快速创建基于 qflag 的 Go 命令行应用程序。通过提供项目模板生成、代码结构优化等功能，qctl 让命令行工具开发变得更加高效和标准化。

## ✨ 核心特性

- 🎯 **专为 qflag 优化** - 深度集成 qflag 命令行解析库
- 🏗️ **项目模板生成** - 快速创建标准化的项目结构
- 📁 **智能目录管理** - 自动生成合理的项目目录布局
- 🔧 **配置文件支持** - 内置配置文件模板生成
- 🎨 **代码模板渲染** - 支持占位符替换和模板渲染
- 📊 **项目结构可视化** - 专业的树形结构展示
- ⚡ **高性能实现** - 基于 Go 的高性能脚手架工具
- 🌍 **中文友好** - 完整的中文文档和错误提示

## 🚀 快速开始

### 安装

#### 从 Gitee 仓库安装

```bash
go install gitee.com/MM-Q/qctl@latest
```

#### 从源码安装

```bash
git clone https://gitee.com/MM-Q/qctl.git
cd qctl

# 构建项目
python3 build.py -s

# 构建并安装到系统
python3 build.py -ai -s -f
```

### 基本用法

#### 生成新项目

```bash
# 创建一个新的命令行项目
qctl gen myapp

# 查看生成的项目结构
qctl gen myapp --show-structure
```

#### 项目模板示例

生成的项目包含以下结构：

```
myapp/
├── cmd/
│   ├── flags.go          # 根命令参数定义
│   ├── root.go           # 根命令定义
│   └── subcmd/           # 子命令目录
│       └── example/      # 示例子命令
│           ├── example.go # 子命令实现
│           └── flags.go   # 子命令参数定义
├── internal/
│   └── utils/            # 工具函数
│       └── log.go        # 日志工具
├── gobf/                 # 构建配置
├── go.mod                # Go 模块文件
├── main.go               # 程序入口
└── README.md             # 项目说明
```

## 📚 API 文档

### 核心数据结构

#### ProjectStructure

项目结构的核心数据结构，用于定义目录和文件结构：

```go
type ProjectStructure struct {
    Name        string                       // 目录/文件名称
    Type        NodeType                     // 类型: "dir" 或 "file"
    Children    map[string]*ProjectStructure // 子节点 (仅目录类型使用)
    Metadata    map[string]string            // 元数据，用于模板渲染
    Template    string                       // 模板内容 (仅文件类型使用)
    Permissions os.FileMode                  // 权限设置
}
```

#### NodeType

节点类型枚举：

```go
type NodeType string

const (
    DirType  NodeType = "dir"   // 目录类型
    FileType NodeType = "file"  // 文件类型
)
```

### 核心函数

#### GenerateProject

生成项目的主要函数：

```go
// GenerateProject 根据项目结构生成完整的项目
// 
// 参数:
//   - projectPath: 项目生成路径
//   - structure: 项目结构定义
// 
// 返回值:
//   - error: 生成过程中的错误信息
func GenerateProject(projectPath string, structure *ProjectStructure) error
```

#### PrintProjectStructure

可视化展示项目结构：

```go
// PrintProjectStructure 打印项目结构树
// 
// 参数:
//   - node: 项目结构根节点
//   - title: 标题（可选）
func PrintProjectStructure(node *ProjectStructure, title string)
```

## 🛠️ 配置选项

### 默认权限设置

qctl 提供默认的权限设置，确保生成的文件和目录具有合适的权限：

| 类型 | 默认权限 | 说明 |
|------|----------|------|
| 目录 | `0755` | 所有者可读写执行，其他用户可读执行 |
| 文件 | `0644` | 所有者可读写，其他用户只读 |

### 模板占位符

支持在模板文件中使用占位符，格式为 `{{key}}`：

```go
// 示例模板
const template = `
package main

import "fmt"

func main() {
    fmt.Println("欢迎使用 {{appName}} v{{version}}")
}
`

// 元数据映射
metadata := map[string]string{
    "appName": "MyApp",
    "version": "1.0.0",
}
```

## 📁 项目结构

```
qctl/
├── cmd/                    # 命令行接口
│   ├── subcmd/            # 子命令目录
│   │   ├── gen/           # 生成命令
│   │   ├── list/          # 列表命令
│   │   └── print/         # 打印命令
│   ├── flags.go           # 命令参数定义
│   └── root.go            # 根命令
├── internal/              # 内部实现
│   ├── generator/         # 项目生成器核心
│   ├── templates/         # 模板定义
│   └── utils/             # 工具函数
├── gobf/                  # 构建配置文件
│   ├── dev.toml           # 开发环境配置
│   ├── install.toml       # 安装配置
│   └── release.toml       # 发布配置
├── vendor/                # 依赖管理
├── go.mod                 # Go 模块
├── go.sum                 # Go 依赖校验
├── main.go                # 程序入口
├── build.py               # 构建脚本
├── LICENSE                # MIT 许可证
├── README.md              # 项目文档
└── qflag开发规范.md        # 开发规范文档
```

## 🧪 测试

### 运行测试

```bash
# 运行所有测试
go test ./...

# 运行指定包的测试
go test ./internal/generator

# 带覆盖率测试
go test -cover ./...
```

### 测试项目生成

```bash
# 生成测试项目
qctl gen test-project

# 验证生成的项目结构
cd test-project && tree
```

## 🤝 贡献指南

我们欢迎所有形式的贡献！请遵循以下步骤：

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

### 开发环境设置

```bash
# 克隆项目
git clone https://gitee.com/MM-Q/qctl.git

# 进入项目目录
cd qctl

# 下载依赖
go mod download

# 运行测试
go test ./...

# 构建项目
go build -o qctl main.go
```

## 📄 许可证

本项目基于 [MIT 许可证](LICENSE) 开源 - 详情请查看 [LICENSE](LICENSE) 文件。

## 📞 联系方式

- **项目仓库**: [https://gitee.com/MM-Q/qctl](https://gitee.com/MM-Q/qctl)
- **问题反馈**: [提交 Issue](https://gitee.com/MM-Q/qctl/issues)
- **相关项目**: [qflag - 命令行参数解析库](https://gitee.com/MM-Q/qflag)

---

<div align="center">

**⭐ 如果这个项目对你有帮助，请给我们一个星标！** 

[🏠 返回主页](https://gitee.com/MM-Q/qctl) | [📖 查看文档](https://gitee.com/MM-Q/qctl/blob/main/README.md) | [🐛 报告问题](https://gitee.com/MM-Q/qctl/issues)

</div>