diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index f6b54423d..5287b7018 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -4,115 +4,277 @@ GoFrame (GF) 是一个模块化、高性能、企业级的 Golang 基础开发框架。 -## 项目目录结构 +## 目录结构说明 + +### 主包 ```shell gf -├── cmd // 命令行工具 -│ ├── gf // GF CLI工具 -│ └── internal // 内部命令实现 -├── container // 容器类型 -│ ├── garray // 数组 -│ ├── glist // 列表 -│ ├── gmap // 映射 -│ ├── gpool // 对象池 -│ ├── gqueue // 队列 -│ ├── gset // 集合 -│ ├── gstack // 栈 -│ ├── gtree // 树 -│ └── gtype // 并发安全基本类型 -├── contrib // 第三方贡献组件库 -│ ├── drivers // 数据库驱动 -│ │ ├── mysql // MySQL驱动适配 -│ │ ├── pgsql // PostgreSQL驱动适配 -│ │ ├── sqlite // SQLite驱动适配 -│ │ ├── mssql // SQL Server驱动适配 -│ │ └── oracle // Oracle驱动适配 -│ ├── registry // 注册中心实现 -│ │ ├── consul // Consul服务注册 -│ │ ├── etcd // ETCD服务注册 -│ │ ├── file // 文件系统服务注册 -│ │ ├── nacos // Nacos服务注册 -│ │ ├── polaris // Polaris服务注册 -│ │ └── zookeeper // ZooKeeper服务注册 -│ ├── config // 配置中心适配 -│ │ ├── kubecm // K8s ConfigMap配置中心 -│ │ └── polaris // Polaris配置中心 -│ └── trace // 链路追踪实现 -├── crypto // 加密解密 -│ ├── gaes // AES加密 -│ ├── gdes // DES加密 -│ ├── gmd5 // MD5哈希 -│ └── gsha1 // SHA1哈希 -├── database // 数据库功能 -│ ├── gdb // 数据库ORM -│ ├── gredis // Redis客户端 -│ └── gkafka // Kafka客户端 -├── debug // 调试相关功能 -│ ├── gdebug // 调试工具包 -│ └── checksum // 校验和工具 -├── encoding // 编码解码功能 -│ ├── gbase64 // Base64编解码 +├── container // 容器相关包 +│ ├── garray // 数组容器 +│ ├── glist // 链表容器 +│ ├── gmap // Map容器 +│ ├── gpool // 对象池 +│ ├── gqueue // 队列 +│ ├── gring // 环形缓冲区 +│ ├── gset // 集合 +│ ├── gtree // 树结构 +│ ├── gtype // 并发安全类型 +│ └── gvar // 动态变量 +├── crypto // 加密相关 +│ ├── gaes // AES加密 +│ ├── gcrc32 // CRC32校验 +│ ├── gdes // DES加密 +│ ├── gmd5 // MD5哈希 +│ └── gsha1 // SHA1哈希 +├── database // 数据库相关 +│ ├── gdb // 数据库ORM +│ └── gredis // Redis客户端 +├── debug // 调试工具 +│ └── gdebug // 调试辅助 +├── encoding // 编码相关 +│ ├── gbase64 // Base64编码 │ ├── gbinary // 二进制编码 │ ├── gcharset // 字符集转换 │ ├── gcompress // 压缩解压 -│ ├── ghash // 哈希编码 -│ ├── ghtml // HTML编码 -│ ├── gjson // JSON编解码 -│ ├── gtoml // TOML编解码 -│ ├── gurl // URL编解码 -│ ├── gxml // XML编解码 -│ └── gyaml // YAML编解码 -├── errors // 错误处理 -│ ├── gerror // 错误处理包 -│ └── gcode // 错误码管理 -├── example // 示例代码 -│ ├── http // HTTP示例 -│ ├── database // 数据库示例 -│ └── other // 其他示例 -├── frame // 框架核心组件 -│ ├── g // 核心包 -│ └── gins // 实例管理 -├── i18n // 国际化支持 -│ └── gi18n // 多语言管理 -├── internal // 内部实现 -│ ├── command // 命令行工具实现 -│ ├── filepool // 文件池 -│ ├── intlog // 内部日志 -│ └── utils // 内部工具函数 -├── net // 网络功能 -│ ├── ghttp // HTTP客户端/服务端 -│ ├── gtcp // TCP组件 -│ ├── gudp // UDP组件 -│ ├── goai // OpenAPI接口 -│ ├── gsvc // 服务注册发现 -│ └── gsel // 负载均衡 -├── os // 系统功能 +│ ├── ghash // 哈希算法 +│ ├── ghtml // HTML处理 +│ ├── gini // INI解析 +│ ├── gjson // JSON处理 +│ ├── gproperties // Properties解析 +│ ├── gtoml // TOML解析 +│ ├── gurl // URL处理 +│ ├── gxml // XML处理 +│ └── gyaml // YAML处理 +├── errors // 错误处理 +│ ├── gcode // 错误码 +│ └── gerror // 错误处理 +├── frame // 框架核心 +│ ├── g // 全局对象 +│ └── gins // 依赖注入 +├── i18n // 国际化 +│ └── gi18n // 国际化支持 +├── net // 网络相关 +│ ├── gclient // HTTP客户端 +│ ├── ghttp // HTTP服务端 +│ ├── gipv4 // IPv4工具 +│ ├── gipv6 // IPv6工具 +│ ├── goai // AI工具 +│ ├── gsel // 服务发现 +│ ├── gsvc // 服务治理 +│ ├── gtcp // TCP工具 +│ ├── gtrace // 链路追踪 +│ └── gudp // UDP工具 +├── os // 系统相关 +│ ├── gbuild // 构建工具 │ ├── gcache // 缓存管理 │ ├── gcfg // 配置管理 -│ ├── gcmd // 命令行 +│ ├── gcmd // 命令行解析 +│ ├── gcron // 定时任务 +│ ├── gctx // 上下文管理 │ ├── genv // 环境变量 │ ├── gfile // 文件操作 +│ ├── gfpool // 文件池 +│ ├── gfsnotify // 文件监控 │ ├── glog // 日志管理 +│ ├── gmetric // 指标监控 │ ├── gmlock // 内存锁 +│ ├── gmutex // 互斥锁 │ ├── gproc // 进程管理 │ ├── gres // 资源管理 +│ ├── grpool // 协程池 │ ├── gsession // 会话管理 -│ ├── gtime // 时间管理 +│ ├── gspath // 路径处理 +│ ├── gstructs // 结构体工具 +│ ├── gtime // 时间处理 │ ├── gtimer // 定时器 -│ └── gview // 模板引擎 -├── test // 测试相关 -│ ├── gtest // 测试框架 -├── text // 文本处理 -│ ├── gstr // 字符串处理 -│ └── gregex // 正则表达式 -└── util // 实用工具 +│ └── gview // 视图渲染 +├── test // 测试工具 +│ └── gtest // 测试框架 +├── text // 文本处理 +│ ├── gregex // 正则表达式 +│ └── gstr // 字符串工具 +└── util // 工具类 ├── gconv // 类型转换 + ├── gmeta // 元数据处理 ├── gmode // 运行模式 - ├── gutil // 工具函数 + ├── gpage // 分页工具 + ├── grand // 随机数 + ├── gtag // 标签处理 + ├── guid // UUID生成 + ├── gutil // 通用工具 └── gvalid // 数据校验 ``` +### cmd 命令行工具 + +```shell +cmd +├── gf // GF CLI主程序 +│ ├── gfcmd // CLI命令入口 +│ │ ├── build // 项目构建 (cmd_build.go) +│ │ ├── run // 热编译运行 (cmd_run.go) +│ │ ├── init // 项目脚手架 (cmd_init.go) +│ │ ├── gen // 代码生成入口 (cmd_gen.go) +│ │ ├── docker // 容器化操作 (cmd_docker.go) +│ │ ├── install // 依赖管理 (cmd_install.go) +│ │ ├── fix // 代码修复 (cmd_fix.go) +│ │ ├── update // 框架升级 (cmd_up.go) +│ │ ├── env // 环境变量管理 (cmd_env.go) +│ │ ├── pack // 二进制打包 (cmd_pack.go) +│ │ └── doc // 文档生成 (cmd_doc.go) +│ ├── internal/cmd/ // 命令实现核心 +│ │ ├── cmd_build.go // 构建命令：交叉编译支持/构建参数配置 +│ │ ├── cmd_doc.go // 文档命令：Swagger/API文档自动化生成 +│ │ ├── cmd_docker.go // Docker命令：镜像构建/推送/多阶段编译 +│ │ ├── cmd_env.go // 环境管理：变量查看/设置/环境切换 +│ │ ├── cmd_fix.go // 代码修复：自动修复常见语法问题 +│ │ ├── cmd_gen.go // 代码生成：统一入口路由 +│ │ ├── cmd_gen_ctrl.go // MVC控制器：RESTful接口生成 +│ │ ├── cmd_gen_dao.go // DAO层：数据库表映射生成 +│ │ ├── cmd_gen_enums.go // 枚举代码：自动生成枚举类型和方法 +│ │ ├── cmd_gen_pb.go // Protobuf：协议文件编译生成 +│ │ ├── cmd_gen_pbentity.go // Protobuf实体：数据库表到proto转换 +│ │ ├── cmd_gen_service.go // 微服务接口：GRPC服务代码生成 +│ │ ├── cmd_init.go // 项目初始化：模块化脚手架生成 +│ │ ├── cmd_install.go // 依赖管理：自动分析并安装go依赖 +│ │ ├── cmd_pack.go // 打包发布：支持二进制/Docker/zip多种格式 +│ │ ├── cmd_run.go // 运行管理：热编译/配置重载/进程监控 +│ │ ├── cmd_tpl.go // 模板管理：自定义代码模板系统 +│ │ ├── cmd_up.go // 框架升级：版本检测与自动更新 +│ │ ├── cmd_version.go // 版本管理：CLI/Golang/框架版本信息 +│ │ ├── cmd_z_init_test.go // 初始化测试：脚手架生成验证 +│ │ └── cmd_z_unit_*_test.go // 单元测试：各命令功能验证 +│ ├── internal/cmd/gen/ // 代码生成模板 +│ │ ├── tpl_field.go // 字段级模板(列映射/类型转换) +│ │ ├── tpl_table.go // 表级模板(CRUD操作/关系映射) +│ │ ├── tpl_test.go // 测试用例模板 +│ │ ├── tpl_ctrl.go // 控制器模板(RESTful方法) +│ │ ├── tpl_service.go // 服务层模板(业务逻辑) +│ │ └── tpl_pbentity.go // Protobuf实体模板 +│ ├── test/ // 测试相关 +│ │ ├── cmd_z_unit_build_test.go // 构建命令单元测试 +│ │ ├── cmd_z_unit_gen_dao_test.go // DAO生成测试 +│ │ └── testdata/ // 测试用例数据 +│ ├── internal // 内部实现 +│ ├── test // 测试代码 +│ ├── go.mod // 模块文件 +│ ├── go.sum // 依赖校验 +│ ├── go.work // 工作区配置 +│ ├── LICENSE // 许可证 +│ ├── main.go // 主入口 +│ ├── Makefile // 构建配置 +│ └── README.MD // 说明文档 +``` + +### contrib 组件库 + +```shell +contrib +├── config // 配置中心支持 +│ ├── apollo // Apollo配置中心 +│ ├── consul // Consul配置中心 +│ ├── kubecm // Kubernetes ConfigMap支持 +│ ├── nacos // Nacos配置中心 +│ └── polaris // Polaris配置中心 +├── drivers // 数据库驱动 +│ ├── clickhouse // ClickHouse驱动 +│ ├── dm // 达梦数据库驱动 +│ ├── mssql // SQL Server驱动 +│ ├── mysql // MySQL驱动 +│ ├── oracle // Oracle驱动 +│ ├── pgsql // PostgreSQL驱动 +│ ├── sqlite // SQLite驱动 +│ └── sqlitecgo // SQLite CGO驱动 +├── metric // 指标监控 +│ └── otelmetric // OpenTelemetry指标支持 +├── nosql // NoSQL支持 +│ └── redis // Redis支持 +├── registry // 服务注册发现 +│ ├── consul // Consul支持 +│ ├── etcd // Etcd支持 +│ ├── file // 文件注册中心 +│ ├── nacos // Nacos支持 +│ ├── polaris // Polaris支持 +│ └── zookeeper // Zookeeper支持 +├── rpc // RPC支持 +│ └── grpcx // gRPC扩展支持 +├── sdk // SDK支持 +│ └── httpclient // HTTP客户端SDK +└── trace // 链路追踪 + ├── otlpgrpc // OpenTelemetry gRPC支持 + └── otlphttp // OpenTelemetry HTTP支持 +``` + +### examples 示例库 + +```shell +examples +├── balancer // 负载均衡示例 +│ ├── http // HTTP负载均衡 +│ └── polaris // Polaris负载均衡 +├── config // 配置中心示例 +│ ├── apollo // Apollo配置中心 +│ ├── consul // Consul配置中心 +│ ├── kubecm // Kubernetes ConfigMap +│ ├── nacos // Nacos配置中心 +│ └── polaris // Polaris配置中心 +├── converter // 类型转换示例 +│ ├── alias-type-convert // 别名类型转换 +│ ├── alias-type-scan // 别名类型扫描 +│ ├── struct-convert // 结构体转换 +│ └── struct-scan // 结构体扫描 +├── database // 数据库示例 +│ └── mysql // MySQL数据库 +├── httpserver // HTTP服务示例 +│ ├── default-value // 默认值处理 +│ ├── proxy // 代理服务 +│ ├── rate // 限流控制 +│ ├── response-with-json // JSON响应 +│ ├── serve-file // 文件服务 +│ ├── swagger // Swagger文档 +│ ├── upload-file // 文件上传 +│ └── swagger-set-template // Swagger模板 +├── metric // 指标监控示例 +│ ├── basic // 基础指标 +│ ├── callback // 回调指标 +│ ├── dynamic-attributes // 动态属性 +│ ├── global-attributes // 全局属性 +│ ├── http-client // HTTP客户端指标 +│ ├── http-server // HTTP服务端指标 +│ ├── meter-attributes // 计量器属性 +│ └── prometheus // Prometheus集成 +├── nosql // NoSQL示例 +│ └── redis // Redis操作 +├── os // 系统操作示例 +│ ├── cron // 定时任务 +│ └── log // 日志管理 +├── pack // 打包示例 +│ ├── hack // 打包工具 +│ ├── manifest // 清单文件 +│ ├── packed // 打包结果 +│ └── resource // 资源文件 +├── registry // 服务注册发现示例 +│ ├── consul // Consul注册中心 +│ ├── etcd // Etcd注册中心 +│ ├── file // 文件注册中心 +│ ├── nacos // Nacos注册中心 +│ └── polaris // Polaris注册中心 +├── rpc // RPC示例 +│ └── grpcx // gRPC扩展 +├── tcp // TCP示例 +│ └── server // TCP服务 +└── trace // 链路追踪示例 + ├── grpc-with-db // gRPC+数据库 + ├── http // HTTP链路 + ├── http-with-db // HTTP+数据库 + ├── inprocess // 进程内追踪 + ├── inprocess-grpc // 进程内gRPC + ├── otlp // OpenTelemetry + ├── processes // 进程管理 + └── provider // 追踪提供者 +``` + ## 编码规范 1. 命名规范