# GoCodeGen **Repository Path**: ncepu-bj/GoCodeGen ## Basic Information - **Project Name**: GoCodeGen - **Description**: go语言接口代码自动化项目 - **Primary Language**: Go - **License**: Apache-2.0 - **Default Branch**: develop - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 3 - **Forks**: 2 - **Created**: 2022-03-22 - **Last Updated**: 2026-05-20 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # Go Gin框架接口项目代码生成器 ###### By：华北电力大学iDeal工作室 ## 一 项目介绍 本项目开发初衷是基于数据库的表，生成Restful风格接口的脚手架项目，以便来简化开发，去除编写CRUD基础代码的时间，提高软件开发效率。使用本项目可以快速生成你的项目，缩短交付时间，你可以有更多的时间花在业务逻辑上，更多的时间测试！我们致力于开发出开箱即用的代码生成工具，欢迎使用与反馈！ - 本项目基于已有的数据库表结构，自动生成Go语言完整的基础接口项目 - 生成的目标项目基于Gin框架，接口符合Restful风格规范 - 项目架构满足分层设计规范，分为实体层，控制器层和资源层(接口层)，用户可以添加服务层，作为商业逻辑层 - 提供完整的文件结构，利于项目管理，节约时间 - 工具类完整，包含了日志管理、错误处理等 - 提供RPC接口示例与文件组织，可以将项目转变为微服务项目 - 目标项目包含基于Docker容器的部署脚本 ### 1.1 运行环境与主要依赖（补充） 为便于快速评估项目技术栈，核心环境与依赖如下： 1. Go 语言版本 - 本项目 `go.mod` 声明版本为 `go 1.18` - 建议使用 `Go 1.18+`（推荐与项目声明版本保持一致） 2. 主要依赖包 - `github.com/spf13/cobra`：命令行框架（根命令、子命令） - `github.com/spf13/viper`：配置读取与监听 - `github.com/go-sql-driver/mysql`：MySQL 驱动 - `github.com/sirupsen/logrus`：日志框架 - `github.com/lestrrat-go/file-rotatelogs`、`gopkg.in/sohlich/elogrus.v7`：日志落盘与轮转 - `github.com/fsnotify/fsnotify`：配置文件变更监听 - `github.com/olivere/elastic/v7`：Elasticsearch 日志 Hook 支持 3. 依赖安装方式 - 在项目根目录执行：`go mod tidy` - 如需完整校验，可执行：`go build ./...` ## 二 项目详细说明 ### 2.1 项目代码结构说明 本小节用于说明两个层面的代码结构： 1. 生成器本身（当前仓库）的代码结构 2. 生成结果（dist 下目标项目）的代码结构 #### 2.1.1 生成器本身目录说明 ~~~~ GoCodeGen ├─main.go 程序入口，初始化日志并执行命令行 ├─cmd/ Cobra 命令定义（根命令、gen 子命令、version 等） ├─core/ │ ├─execute.go 生成总流程入口（项目骨架 + 数据库代码） │ ├─database/ 数据库连接、表结构读取、生成前校验 │ └─gen/ │ ├─gen_program/ 项目骨架复制与占位符替换 │ └─gen_db/ 基于表结构的模板渲染生成 ├─assets/ │ ├─project_layout/ 目标项目基础骨架模板 │ ├─template/ model/dao/service/api/router 等模板 │ └─dict/ 关键字替换、类型映射、生成映射等字典 ├─configs/ 生成器配置（数据库连接等） ├─init/ viper 初始化与全局路径常量 ├─tools/ 通用工具（日志、字符串、关键字检查等） └─dist/ 生成输出目录（运行后自动创建） ~~~~ #### 2.1.2 生成器核心模块职责 - main.go - 负责程序启动、日志初始化、命令分发 - cmd - 对外暴露命令行能力：默认生成、按模块生成、版本查看 - core/gen/gen_program - 把 assets/project_layout 复制到 dist/数据库名 - 结合字典对模板占位符执行字符串替换 - core/gen/gen_db - 读取数据库表/字段信息 - 按模板批量生成 model、dao、service、api、router、urls - core/database - 提供数据库元数据读取能力 - 执行关键字检查、主键检查等生成前约束校验 #### 2.1.3 生成后项目目录说明（快速理解） 生成后的业务项目位于 `dist/数据库名`，一般采用分层结构： - apis - 对外接口层，处理参数、调用 service/dao、返回响应 - internal/models - ORM 模型定义，映射数据库表结构 - internal/dao - 数据访问层，封装基础 CRUD 与查询 - internal/services - 业务逻辑层，承载复杂业务编排 - apis/routers - 路由注册、路由分组与中间件挂载 - configs - 运行配置文件 - deploy - Docker 与部署相关文件 - utils - 通用工具模块 #### 2.1.4 推荐阅读顺序 如果你想快速看懂本项目，建议按以下顺序阅读： 1. main.go（入口） 2. cmd/（命令定义） 3. core/execute.go（总流程） 4. core/gen/gen_program（骨架复制） 5. core/gen/gen_db（模板渲染） 6. assets/template 与 assets/dict（模板与映射规则） 通过上述顺序，可以较快建立“输入配置 -> 读取库表 -> 渲染模板 -> 输出项目”的完整认知链路。 ### 2.2 目标项目说明 1. 生成的项目文件结构 以一个简单的项目study_flask_api为例，生成时项目名与数据库名一致。项目结构如下 ~~~~ study_flask_api ├─apis 接口层 │ ├─api_1_0 1.0版本接口层 │ │ ├─student 接口-student表相关接口定义 │ │ │ ├─StudentResource.go Resource层-完成参数解析、dao层或服务层调用、数据响应 │ │ │ └─urls.go student相关路由定义 │ │ └─vStudentCourseScore 接口-vStudentCourseScore视图相关接口定义 │ │ ├─StudentResource.go Resource层-完成参数解析、dao层或服务层调用、数据响应 │ │ └─urls.go vStudentCourseScore路由定义 │ ├─middlewares 中间件 │ └─routers 路由层-初始化路由、使用中间件 ├─assets │ └─proto ├─cmd 命令行定义-通过命令行运行项目 ├─configs 配置文件夹-系统配置与数据库配置 ├─deploy 部署相关 ├─init 项目配置初始化 ├─internal 内部层（业务相关） │ ├─dao CRUD封装层 │ ├─globals 全局工具配置 │ │ ├─codes │ │ ├─database │ │ ├─extensions │ │ │ └─currentUser │ │ ├─jwt │ │ ├─parser │ │ ├─rsa │ │ ├─snowflake │ │ └─vipers │ ├─models 数据库model层-基于gorm的ORM模型 │ ├─remote RPC Clinet示例 │ │ ├─httpReq │ │ └─rpcReq │ ├─rpcServer RPC Server示例 │ │ ├─middlewares │ │ ├─pb │ │ └─service │ ├─services 业务逻辑层-复杂业务 │ └─settings 工具- 数据库连接、gin启动 ├─pkg 第三方包 ├─scripts └─utils 工具层 ├─errHelper 错误处理 ├─loggers 日志管理 ├─message 消息管理 ├─rsa 密钥管理 ├─snowflake ├─str └─structs ~~~~ 2. 开发说明 - 开发时在internal/services文件夹下完善业务逻辑，调用dao层对数据库进行操作 - 在api_1_0文件夹下进行参数接收，定义路由 - 在configs文件夹下定义了两个配置文件，可以根据实际需要修改配置文件 - 系统配置文件：`config.yaml` - 数据库配置文件：`database.yaml` 3. 启动 1. 在文件主目录下运行`go mod tidy` 按照依赖包 2. 在文件主目录运行`go run main.go` 或者在文件主目录运行`go build` 然后使用命令行方式运行 4. 测试 - 启动项目之后，打开接口测试工具（postman等），测试请求 http://127.0.0.1:8000/api/version 测试返回版本号 - 查看代码中的路由定义，测试其他业务接口 5. 推荐开发流程（补充） 1. 先完成一次全量生成，确认项目可正常启动 2. 在 `internal/services` 中实现业务逻辑，尽量保持接口层轻量 3. 在 `apis/api_1_0` 中补充参数校验、错误码映射与响应结构 4. 在 `apis/routers` 中按业务域组织路由与中间件 5. 联调完成后，再回头优化模板，沉淀通用能力 6. 二次扩展建议（补充） - 接口层（apis） - 适合放参数解析、权限校验、统一响应，不建议承载复杂业务 - 服务层（internal/services） - 适合放业务编排、事务控制、跨表逻辑 - DAO层（internal/dao） - 适合放通用查询封装，避免把业务分支写在 DAO - 全局能力（internal/globals、utils） - 可统一日志、错误码、JWT、雪花ID、配置读取等 7. 关于“重新生成”的建议（补充） - 建议将“生成产物”和“业务改造”分开提交，便于回溯差异 - 对于可复用改动，优先修改模板文件，而不是每次手工改生成结果 - 当数据库结构变化较大时，优先执行 `go run main.go gen d` 更新数据库相关代码 - 若项目骨架模板有升级，再执行 `go run main.go gen p` 做结构同步 8. 发布前检查清单（补充） 1. 配置检查：`configs/config.yaml` 中数据库、端口、日志等配置符合目标环境 2. 路由检查：确认新增接口已注册到路由入口并通过中间件链 3. 数据检查：主键、索引、逻辑删除字段与业务预期一致 4. 错误处理：统一错误码、错误信息与日志输出格式 5. 部署检查：`deploy` 目录中的 docker-compose 与镜像配置可用 6. 冒烟测试：至少验证版本接口、核心读接口、核心写接口 ## 三 生成器项目的使用建议 ### 3.1 数据库满足以下的设计规范（建议） 1. 数据库表名称推荐全小写，如student；如果涉及多个描述词，可使用"_"连接。如：user_info 2. 数据库表的字段中，必须包含一个主键；且不能为复合主键 3. 数据库表的名称和表字段名称，不能是Golang的关键字，如：`var`、`range`、`int`都是不正确的 4. 建议表的字段名称使用"大驼峰"命名法。如：UserName 5. 建议设计一个timestamp类型的"CreateTime"字段，默认为当前时间戳(用来记录数据创建的时间) 6. 建议设计一个tinyint类型的"IsDelete"字段(用来实现记录的逻辑删除，0--有效，1--已删除)，默认为0 ### 3.2 使用帮助文档 查看我们的文档 [GoCodeGen](https://idealstudio-ncepu.yuque.com/kgagg7/pkp1rg/ng5sg765x4nqfl28) 2.1. 下载我们的最新发行版，进行解压。项目结构如下 ![项目目录结构.png](https://s1.ax1x.com/2023/02/27/pp9ILf1.png) 2.2. 进入configs文件夹，修改config.yaml文件，配置你的数据库 ~~~~config.yaml: database: driver : "mysql" host : "XXXX" port : "XXXX" username : "XXX" password : "XXX" database : "XXX" ~~~~ 2.3. 回到上一级目录，运行main.go文件 `go run main.go` 2.4. 代码生成在dist文件夹下(第一次运行会在主目录生成dist文件夹)。dist文件夹存放生成的项目 ![生成的项目.png](https://s1.ax1x.com/2023/02/27/pp9oqHg.png) ## 四 模板使用说明 本项目基于模板文件，生成了对应的代码结构。使用者可以根据自己的要求，修改模板文件来满足特定的需求。在本项目assets/template文件夹下定义了相关模板 - 接口层模板 `api.go.tpl` - dao层模板 `dao.go.tpl` - 模型层模板 `model.go.tpl` - 路由层模板 `router.go.tpl` - 服务层模板 `service.go.tpl` 根据实际需求修改模板文件即可，模板语法见文档 [模板语法]() ## 五 执行流程说明 默认执行流程分为两步： 1. 先复制项目骨架 - 将项目模板目录完整复制到 `dist/数据库名` - 按字典规则替换占位符（如数据库名、MySQL连接信息等） 2. 再生成数据库相关代码 - 读取数据库中的表与字段信息 - 按模板生成 `model/dao/service/api/router/urls` 等代码 你也可以通过子命令只执行其中一部分（见下文命令说明）。 ## 六 命令行用法 本项目基于 Cobra 命令行，常用方式如下： 1. 默认执行（推荐初次使用） ~~~~bash go run main.go ~~~~ 说明：会按“项目骨架 + 数据库代码”的完整流程生成。 2. 指定配置文件（不带后缀） ~~~~bash go run main.go -C config ~~~~ 说明：`-C` 是大写，表示读取 `configs/config.yaml`。 3. 仅生成项目骨架代码 ~~~~bash go run main.go gen p ~~~~ 4. 仅生成数据库相关代码 ~~~~bash go run main.go gen d ~~~~ 5. 生成项目骨架 + 数据库代码（手动组合） ~~~~bash go run main.go gen p d ~~~~ 6. 查看版本 ~~~~bash go run main.go version ~~~~ ## 七 配置项说明 当前最核心的是 `configs/config.yaml` 中的数据库连接配置。 示例： ~~~~yaml database: driver: "mysql" host: "127.0.0.1" port: "3306" username: "root" password: "你的密码" database: "你的数据库名" redis: host: "127.0.0.1:6379" password: "" ~~~~ 字段说明： - `database.database`： - 用作数据库连接目标 - 也会作为生成项目目录名（`dist/数据库名`） - `database.host/port/username/password`：用于读取表结构并生成数据库代码 - `redis.host/password`：在项目骨架复制时用于占位符替换（若模板中使用） ## 八 模板与输出映射 生成数据库代码时，模板与输出目录默认映射如下： 1. `model.go.tpl` -> `internal/models` 2. `dao.go.tpl` -> `internal/dao` 3. `service.go.tpl` -> `internal/services` 4. `api.go.tpl` -> `apis/api_1_0/<表名目录>/<表名>Resource.go` 5. `router.go.tpl` -> `apis/api_1_0/<表名目录>/urls.go` 6. `urls.go.tpl` -> `apis/api_1_0/urls.go` 其中： - `<表名目录>` 为表名的小驼峰形式 - `<表名>` 的类型名通常会被转换为大驼峰形式 ## 九 生成前检查与约束 为保证生成稳定，建议在生成前确认： 1. 数据库名、表名、字段名不要使用 Go 关键字 2. 表必须包含主键（视图除外） 3. 表结构中每个字段的数据类型都能在类型字典中匹配到 若不满足上述条件，生成过程中可能会跳过对应表，或直接报错终止。 ## 十 常见问题 1. 运行后没有生成任何代码 - 检查是否正确连接到目标数据库 - 检查 `database.database` 是否填写正确 - 检查目标库内是否有可用表 2. 提示某表或字段名是关键字 - 按提示重命名数据库对象后重新生成 3. 提示表没有主键 - 为该表补充主键后重新执行 4. 提示类型无法匹配 - 在类型字典中补充该数据库类型到 Go 类型的映射 5. 重新生成后覆盖了手改代码 - 建议将生成后的业务改造放在独立提交中管理 - 重要改造优先沉淀到模板中，减少重复改动 ## 十一 二次开发建议 1. 先改模板，再重新生成，避免在生成结果中进行大量重复手工修改 2. 把团队统一约定（字段命名、鉴权中间件、日志格式）固化到模板 3. 对生成后的项目，建议将复杂逻辑集中在 `internal/services`，保持接口层轻量 4. 在生成前后执行一次代码审查，重点确认： - 路由是否符合预期 - 主键与查询条件是否正确 - 时间字段和逻辑删除字段是否符合业务约定