Go Blueprint 使用指南：用一条 CLI 命令搭建标准化 Go 项目与主流框架工程

Go Blueprint 使用指南用一条 CLI 命令搭建标准化 Go 项目与主流框架工程【免费下载链接】go-blueprintGo-blueprint allows users to spin up a quick Go project using a popular framework项目地址: https://gitcode.com/GitHub_Trending/go/go-blueprintGo Blueprint 是当前仓库 go-blueprint 提供的一款命令行脚手架工具它能在几秒钟内生成一套结构标准、可直接运行的 Go 项目骨架并自动接入 Chi、Gin、Fiber、Echo 等主流框架与 MySQL、Postgres、MongoDB 等数据库驱动。读完本文你将掌握它的安装方式、create命令的完整参数体系、六类高级特性HTMX、GitHub Actions、WebSocket、Tailwind、Docker、React的启用方法并理解脚手架在底层是如何依据模板与标志位生成每一个文件的。什么是 Go BlueprintGo Blueprint 是一个专注于项目初始化的 CLI 工具目标是让开发者把精力放在应用代码本身而不是目录布局和配置文件。它做的事情可以概括为三点自动搭建标准工程结构自动创建cmd/、internal/等目录与go.mod、.env、Makefile、.air.toml、.gitignore等基础文件集成主流 HTTP 框架支持 Go 标准库net/http、Chi、Gin、Fiber、HttpRouter、Gorilla/mux、Echo并生成对应的路由、服务端与测试代码可选集成数据库与高级功能通过标志位选择数据库驱动、HTMX、CI/CD 工作流、WebSocket、Tailwind、Docker 与 React 前端。从源码看命令入口定义在 cmd/root.go核心的create子命令在 cmd/create.go 中实现而真正负责建目录、写文件、装依赖、跑 git的引擎是 cmd/program/program.go 的CreateMainFile()。整条链路完全由模板驱动项目生成逻辑高度可预测。为什么选择 Go Blueprint官方文档 docs/docs/index.md 给出了四个核心卖点结合源码可以进一步验证其具体含义价值点文档说明源码/模板佐证安装与上手简单提供 Go、NPM、Homebrew 三种安装途径见 安装 Go Blueprint预置完整工程结构无需操心目录布局和配置文件生成逻辑见 cmd/program/program.go最终结构见 生成的工程结构详解HTTP 服务器配置开箱即用覆盖标准库、Chi、Gin、Fiber、HttpRouter、Gorilla/mux、Echo支持列表见 cmd/flags/frameworks.go各框架模板见 cmd/template/framework/files专注于应用代码脚手架完成后直接开始写业务逻辑生成的main.go自带优雅停机见 main.go.tmpl其中服务器配置开箱即用在模板中有非常具体的体现标准库版本的 server/standard_library.go.tmpl 会生成一个带IdleTimeout1 分钟、ReadTimeout10 秒、WriteTimeout30 秒的http.Server而 Gin 版本的 routes/gin.go.tmpl 则直接内置了 CORS 中间件与/health健康检查路由。安装 Go Blueprint方式一Go Installgo install github.com/melkeydev/go-blueprintlatest该命令会编译出一个 Go 二进制文件并自动绑定到$GOPATH。文档特别提醒如果使用 Zsh需要手动把 GOPATH 的 bin 目录加入~/.zshrcGOPATH$HOME/go PATH$PATH:/usr/local/go/bin:$GOPATH/bin不要忘记让配置生效source ~/.zshrc方式二NPM Installnpm install -g melkeydev/go-blueprint方式三Homebrew Installbrew install go-blueprint安装完成后在新终端中运行go-blueprint create即可进入交互式向导。如果不希望与 UI 交互也可以直接用标志位一次性指定所有选项例如go-blueprint create --name my-project --framework gin --driver postgres --git commit所有选项及缩写可以通过go-blueprint create -h查看。快速上手create 命令与交互流程交互式流程不带任何参数直接运行go-blueprint create时CLI 会依次向你提问每一步都对应一个 Bubble Tea 交互组件定义于 cmd/ui项目名称textinput组件输入合法的 Go 模块名非交互模式下的名称还会经过utils.ValidateModuleName校验非法名称会直接报错见 cmd/create.go选择框架multiInput组件从 Chi、Gin、Fiber、HttpRouter、Gorilla/mux、Echo、standard-library 中选择选择数据库驱动multiInput组件从 mysql、postgres、sqlite、mongo、redis、scylla、none 中选择高级特性多选multiSelect组件仅在--advanced模式下出现HTMX、GitHub Actions、WebSocket、Tailwind、Docker、React 可多选Git 选项multiInput组件commit初始化并提交、stage仅 git init add、skip跳过。这五个步骤的顺序与 cmd/create.go 中的执行逻辑完全一致任何一步缺少标志位都会回退为交互输入且输入结果会回写到对应的 flag 上保证后续非交互命令提示Tip可以直接复现你的选择。非交互式标志位create子命令注册的全部标志位定义在 cmd/create.go汇总如下标志缩写类型允许值说明--name-nstring任意合法模块名项目名称同时作为目录名与go.mod模块名--framework-fFrameworkchi、gin、fiber、httprouter、gorilla/mux、echo、standard-library选择的 Web 框架--driver-dDatabasemysql、postgres、sqlite、mongo、redis、scylla、none数据库驱动--advanced-abooltrue/false是否启用高级特性--feature无AdvancedFeatureshtmx、githubaction、websocket、tailwind、docker、react高级特性可多次指定--git-gGitcommit、stage、skip是否初始化并提交 Git 仓库这些标志的合法取值分别由 cmd/flags/frameworks.go、cmd/flags/database.go、cmd/flags/advancedFeatures.go 与 cmd/flags/git.go 中的白名单强制校验传入非法值会得到包含允许值列表的报错信息因此不需要担心拼写错误导致生成意外结构。create 命令做了什么在交互与非交互输入都完成后CreateMainFile() 按以下顺序执行核心流程校验当前目录下不存在同名非空目录校验 Git 的user.email/user.name配置选择非 skip 时创建项目根目录并执行go mod initutils.InitGoMod通过go get安装所选框架的依赖包标准库除外安装数据库驱动依赖生成internal/database/database.go与集成测试database_test.gosqlite 不生成测试与 docker-compose安装godotenv依赖若选择 Scylla还会把github.com/gocql/gocql替换为github.com/scylladb/gocqlv1.14.4见 cmd/program/program.go依次写入cmd/api/main.go、Makefile、README.md、internal/server/下的routes.go、routes_test.go、server.go以及根目录的.env、.gitignore、.air.toml依据高级选项追加 HTMX、React、Tailwind、GitHub Actions、WebSocket、Docker 相关文件执行go mod tidy与gofmt收尾最后按--git选项执行git init、git add、git commit。每个文件的生成入口是CreateFileWithInjection见 cmd/program/program.go它会根据方法名从对应框架/驱动的模板中渲染出最终内容这解释了为什么生成的代码风格高度统一。支持的框架Go Blueprint 支持七种框架对应值定义于 cmd/flags/frameworks.goChichigithub.com/go-chi/chi/v5Gingingithub.com/gin-gonic/ginFiberfibergithub.com/gofiber/fiber/v2HttpRouterhttproutergithub.com/julienschmidt/httprouterGorilla/muxgorilla/muxgithub.com/gorilla/muxEchoechogithub.com/labstack/echo/v4及其 middlewareGo 标准库standard-library无第三方依赖在底层每个框架被注册为一个Framework结构体绑定自身的依赖包列表与模板实现映射关系集中在 createFrameworkMap()。每个框架需要实现统一的Templater接口cmd/program/program.go分别提供Main()、Server()、Routes()、TestHandler()以及 HTMX/WebSocket 所需的模板片段。对应的模板文件位于 cmd/template/framework/files 目录main 模板main/main.go.tmpl与main/fiber_main.go.tmpl其中 main.go.tmpl 包含基于signal.NotifyContext的优雅停机实现监听 SIGINT/SIGTERM给服务器 5 秒完成在途请求server 模板server/standard_library.go.tmpl与server/fiber.go.tmplroutes 模板routes/目录下按框架分别提供chi.go.tmpl、echo.go.tmpl、fiber.go.tmpl、gin.go.tmpl、gorilla.go.tmpl、http_router.go.tmpl、standard_library.go.tmpl测试模板tests/下提供default-test.go.tmpl、gin-test.go.tmpl、fiber-test.go.tmpl、echo-test.go.tmpl。以 Gin 为例生成的RegisterRoutes()会注册/路由Hello World、/health健康检查选择数据库驱动时与/websocket选择 WebSocket 特性时并内置 CORS 中间件允许http://localhost:5173前端来源完整逻辑见 routes/gin.go.tmpl。相应的单元测试模板 tests/gin-test.go.tmpl 使用httptest.NewRecorder()断言/返回 200 与{message:Hello World}生成的routes_test.go可以直接go test ./...运行。数据库驱动支持在创建项目时通过--driver或-d标志选择数据库驱动目前支持六种驱动加一个none选项定义于 cmd/flags/database.go驱动值说明依赖包mysqlMySQLgithub.com/go-sql-driver/mysqlpostgresPostgreSQLgithub.com/jackc/pgx/v5/stdlibsqliteSQLitegithub.com/mattn/go-sqlite3mongoMongoDBgo.mongodb.org/mongo-driverredisRedisgithub.com/redis/go-redis/v9scyllaScyllaDBGoCQLgithub.com/gocql/gocql并替换为github.com/scylladb/gocqlv1.14.4none不接入数据库无选择数据库后生成的内容选中某个驱动后脚手架会额外生成四类内容数据访问层internal/database/database.go模板位于 cmd/template/dbdriver/files/service。以 Postgres 模板 service/postgres.tmpl 为例它定义Service接口Health()与Close()通过单例模式复用连接并从环境变量读取BLUEPRINT_DB_DATABASE、BLUEPRINT_DB_PASSWORD、BLUEPRINT_DB_USERNAME、BLUEPRINT_DB_PORT、BLUEPRINT_DB_HOST、BLUEPRINT_DB_SCHEMA拼装连接串Health()在 1 秒超时内 Ping 数据库并输出连接池统计打开连接数、等待数、空闲关闭数等还会在连接数或等待事件超过阈值时给出调优提示集成测试internal/database/database_test.gosqlite 除外模板见 cmd/template/dbdriver/files/testsdocker-compose 配置根目录docker-compose.ymlsqlite 除外模板见 cmd/template/docker/files/docker-compose由 createDockerMap() 按驱动匹配环境变量模板.env会合并全局模板与驱动的Env()模板全局部分固定为PORT8080与APP_ENVlocal见 cmd/template/framework/files/globalenv.tmpl驱动部分追加各自的BLUEPRINT_DB_*配置。选中数据库后路由模板还会自动追加/health健康检查接口如 Gin 模板中的healthHandler并在server.go中注入database.Service字段见 server/standard_library.go.tmpl。高级特性--advanced 与 --featureGo Blueprint 刻意保持核心体验的轻量化把可选能力收敛到--advanced标志之下。启用后你会看到一个多选提示multiSelect组件见 cmd/ui/multiSelect可同时选择多个特性也可以改用--feature标志精确指定该标志可重复使用取值白名单见 cmd/flags/advancedFeatures.go。六种高级特性及其对应命令# HTMX配合 Templ 使用 go-blueprint create --advanced --feature htmx # GitHub Actions CI/CD 工作流 go-blueprint create --advanced --feature githubaction # WebSocket 端点 go-blueprint create --advanced --feature websocket # Tailwind CSS go-blueprint create --advanced --feature tailwind # Docker 配置 go-blueprint create --advanced --feature docker # ReactTypeScript Vite前端 go-blueprint create --advanced --feature react特性之间的联动规则从 cmd/create.go 与 CreateMainFile() 的源码可以确认三条联动规则选择 Tailwind 会自动选中 HTMX除非显式选择了 React文档原话Selecting Tailwind option will automatically select HTMX unless React is explicitly selected选择 React 会自动取消 HTMX 与 TailwindReact 与 HTMX 互斥前端路径走独立的 Vite 工程生成完毕后CLI 会打印后续步骤提示React 需要cd frontend npm install npm run devTailwind 需要自行安装 standalone CLIHTMX 需要go install github.com/a-h/templ/cmd/templlatest并执行templ generate。HTMX Templ选择htmx后脚手架会在cmd/web/下生成base.templ基础布局、hello.templ示例页面、hello.go表单处理逻辑与efs.go通过embed把静态资源打进二进制并将htmx.min.js放入cmd/web/assets/js/。对应模板位于 cmd/template/advanced/files/htmx其中针对不同框架的 import 与路由片段分别放在imports/与routes/子目录若选用 Fiber还会额外引入github.com/gofiber/fiber/v2/middleware/adaptor来适配 net/http 风格的处理器见 cmd/program/program.go。HTMX 依赖github.com/a-h/templ需要按提示安装 templ CLI 并运行templ generate生成*_templ.go文件。GitHub Actions CI/CD选择githubaction后会在.github/workflows/下生成两个工作流并在根目录生成.goreleaser.yml见 cmd/program/program.gogo-test.yml运行单元测试release.yml结合 GoReleaser 发布二进制.goreleaser.ymlGoReleaser 构建与发布配置。模板源文件位于 cmd/template/advanced/files/workflow/github对应模板实现见 cmd/template/advanced/gitHubAction.go。WebSocket选择websocket后路由模板中会追加/websocket端点例如 Gin 模板中的websocketHandler通过websocket.Accept建立连接后每 2 秒推送一次带纳秒时间戳的文本消息见 routes/gin.go.tmpl。依赖选择有框架差异见 CreateWebsocketImports()除 Fiber 外使用github.com/coder/websocketFiber使用github.com/gofiber/contrib/websocket。WebSocket 特性支持为每种框架独立生成 import 片段模板位于 cmd/template/advanced/files/websocket/imports。Tailwind选择tailwind后会在cmd/web/styles/input.css生成 Tailwind 输入文件在cmd/web/assets/css/output.css生成编译产物styles/只用于编译、不对外提供并在项目根目录生成tailwind.config.js模板见 cmd/template/advanced/files/htmx/tailwind/tailwind.config.js.tmpl。由于 Tailwind 会自动勾选 HTMX因此该特性实际由 HTMX 的cmd/web结构承载见 cmd/program/program.go。Docker选择docker后生成根目录Dockerfile多阶段构建模板见 cmd/template/advanced/files/docker/dockerfile.tmpl当未选择数据库或选择 sqlite 时还会额外生成通用版docker-compose.yml模板见 cmd/template/advanced/files/docker/docker_compose.yml.tmpl其他情况则复用数据库驱动的专属 compose 配置见 cmd/program/program.go。React 前端选择react后会通过npm create vitelatest frontend -- --template react-ts --prefer-offline --no-fund拉取 Vite React TypeScript 工程见 CreateViteReactProject()并注入包含向后端发起 fetch 请求示例的src/App.tsx模板见 cmd/template/advanced/files/react/app.tsx.tmpl。脚手架还会读取根目录.env中的PORT生成前端的VITE_PORT供开发代理指向后端若同时选择了 Tailwind会安装tailwindcss^4与tailwindcss/vite并覆盖vite.config.ts、index.css与App.tsx对应模板见 cmd/template/advanced/files/react/tailwind。执行该特性前请确保本机已安装 npm。实战示例一次性生成完整项目下面这条命令覆盖了几乎所有能力——Chi 框架 MySQL 驱动 全部六种高级特性 Git 提交go-blueprint create --name my-project --framework chi --driver mysql --advanced --feature htmx --feature githubaction --feature websocket --feature tailwind --feature docker --git commit --feature react注意命令中同时给出了--feature react与--feature htmx、--feature tailwind根据联动规则React 会自动取消 HTMX 与 Tailwind最终以 React Vite 前端方案落地这一行为可在 cmd/create.go 中确认。对于交互式使用场景CLI 结束后还会贴心打印一条Tip给出与本次交互选择等价的非交互命令方便你沉淀为可复用的脚本实现见 cmd/create.go。生成的工程结构详解文档 docs/docs/index.md 给出了启用全部选项时生成的完整目录树下面结合源码逐层说明各文件的作用/ (Root) ├── .github/ │ └── workflows/ │ ├── go-test.yml # GitHub Actions 测试工作流 │ └── release.yml # GitHub Actions 发布工作流 ├── cmd/ │ ├── api/ │ │ └── main.go # 服务启动入口 │ └── web/ │ ├── styles/ # 仅用于生成 CSS不对外提供 │ │ └── input.css # Tailwind 输入文件HTMX 场景 │ ├── assets/ │ │ ├── css/ │ │ │ └── output.css # 编译生成的 CSS │ │ └── js/ │ │ └── htmx.min.js # HTMX 库 │ ├── base.templ # 基础 HTML 模板 │ ├── base_templ.go # base 模板的生成代码 │ ├── efs.go # 将静态资源嵌入编译产物 │ ├── hello.go # hello 表单处理逻辑 │ ├── hello.templ # hello 端点模板 │ └── hello_templ.go # hello 模板的生成代码 ├── frontend/ # React 高级特性与 HTMX 互斥 │ ├── node_modules/ # Node 依赖 │ ├── public/ │ │ ├── index.html │ │ └── favicon.ico │ ├── src/ │ │ ├── App.tsx # 主 React 组件 │ │ ├── assets/ │ │ │ └── logo.svg │ │ ├── components/ │ │ │ ├── Header.tsx │ │ │ └── Footer.tsx │ │ ├── styles/ │ │ │ └── global.css │ │ └── index.tsx # React 入口 │ ├── eslint.config.js # ESLint 配置 │ ├── index.html # 基础 HTML 模板 │ ├── package.json # Node 包配置 │ ├── package-lock.json │ ├── README.md │ ├── tsconfig.app.json # 应用 TS 配置 │ ├── tsconfig.json │ ├── tsconfig.node.json │ └── vite.config.ts # Vite 配置 ├── internal/ │ ├── database/ │ │ ├── database_test.go # 数据库集成测试 │ │ └── database.go # 数据库操作函数 │ └── server/ │ ├── routes.go # HTTP 路由定义 │ ├── routes_test.go # HTTP 处理器测试 │ └── server.go # 服务端主逻辑 ├── .air.toml # Air 热重载配置 ├── docker-compose.yml # Docker Compose 配置 ├── Dockerfile # Go 项目 Dockerfile ├── .env # 环境变量配置 ├── .gitignore # Git 忽略规则 ├── go.mod # Go 模块依赖管理 ├── .goreleaser.yml # GoReleaser 构建发布配置 ├── go.sum # 依赖校验和 ├── Makefile # 命令定义 └── README.md # 项目说明几个值得留意的工程细节分层清晰cmd/只放入口cmd/api启动服务、cmd/web承载 HTMX 页面业务逻辑集中在internal/server管路由与 HTTPdatabase管数据访问符合 Go 社区推荐的工程布局开发体验齐全.air.toml提供 Air 热重载配置Makefile汇总常用命令.env默认写入PORT8080与APP_ENVlocal相关模板见 cmd/template/framework/files 下的air.toml.tmpl、makefile.tmpl与globalenv.tmpl测试随项目生成routes_test.go针对所选框架的处理器测试与database_test.go数据库集成测试都随脚手架自动产出测试模板见 cmd/template/framework/files/tests 与 cmd/template/dbdriver/files/tests生成后即可go test ./...验证工程可用性依赖自动就绪go mod init、go get、go mod tidy、gofmt全部由脚手架在生成过程中代为执行见 cmd/program/program.go 与 cmd/program/program.go生成完的项目立即可编译。延伸阅读安装与初始化细节docs/docs/installation.md、docs/docs/creating-project/project-init.md框架与数据库支持详解docs/docs/blueprint-core/frameworks.md、docs/docs/blueprint-core/db-drivers.md高级特性专题docs/docs/advanced-flag/advanced-flag.md含 htmx-templ.md、react-vite.md、tailwind.md、websocket.md、docker.md、goreleaser.md开发工具链docs/docs/creating-project/air.md、docs/docs/creating-project/makefile.md生成项目的端点测试指南docs/docs/endpoints-test/server.md项目遵循 MIT License。【免费下载链接】go-blueprintGo-blueprint allows users to spin up a quick Go project using a popular framework项目地址: https://gitcode.com/GitHub_Trending/go/go-blueprint创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考