ZincSearch 项目开发环境搭建与构建指南
前言
ZincSearch 是一个现代化的搜索引擎项目，采用 Go 语言开发后端服务，Vue.js 构建前端界面。本文将详细介绍如何搭建 ZincSearch 的开发环境，以及如何从源代码构建项目。
开发环境准备
基础环境要求
在开始开发 ZincSearch 之前，需要确保系统已安装以下工具：
- Git 版本控制系统
- Go 语言 1.16 或更高版本（推荐使用 1.19+）
- Node.js v14+ 和 npm v6+（用于前端开发）
从源代码构建
获取源代码
首先需要获取项目源代码：
git clone 项目仓库地址
cd zincsearch
构建前端界面
ZincSearch 的前端使用 Vue.js 开发，构建步骤如下：
cd web
npm install
npm run build
cd ..
构建完成后，生成的文件会存储在 web/dist 目录中。这些文件将被嵌入到最终生成的 ZincSearch 二进制文件中。
重要提示：每次修改前端代码后，都需要重新执行构建命令，以确保更改被正确嵌入到 Go 应用程序中。
构建后端服务
下载依赖
go mod tidy
此命令会下载 ZincSearch 所需的所有 Go 语言依赖库。
简单构建
go build -o zincsearch cmd/zincsearch/main.go
高级构建选项
CGO_ENABLED=0 GOOS=darwin GOARCH=arm64 go build -ldflags="-s -w -X 项目元信息路径.Version=${VERSION} -X 项目元信息路径.CommitHash=${COMMIT_HASH} -X 项目元信息路径.BuildDate=${BUILD_DATE}" -o zincsearch cmd/zincsearch/main.go
构建参数说明：
GOOS和GOARCH：用于跨平台编译，指定目标操作系统和架构CGO_ENABLED=0：启用静态链接，生成不依赖外部库的独立二进制文件ldflags：用于在构建时传递版本信息等元数据
开发模式
ZincSearch 的开发分为两个主要部分：前端 UI 和后端服务。
后端服务开发
启动开发服务器：
go mod tidy
ZINC_FIRST_ADMIN_USER=admin ZINC_FIRST_ADMIN_PASSWORD=Complexpass#123 go run cmd/zincsearch/main.go
服务默认运行在 4080 端口。环境变量 ZINC_FIRST_ADMIN_USER 和 ZINC_FIRST_ADMIN_PASSWORD 仅在首次启动时需要设置。
前端 UI 开发
cd web
npm install
npm run dev
前端开发服务器运行在 8080 端口。为了完整测试功能，需要同时运行后端服务。
API 文档
ZincSearch 使用 Swagger 生成 API 文档，访问路径为 /swagger/index.html。项目使用以下工具：
- 通过注释标注 API 端点
- 自动从注释生成 Swagger 2.0 规范的 API 文档
更新 API 注释后，需要重新生成文档：
./swagger.sh
Docker 镜像构建
简单构建
docker build --tag zincsearch:latest . -f Dockerfile
多架构构建
需要安装 buildx 工具，并通过 --platform 参数指定目标平台：
docker buildx build --platform linux/amd64 --tag zinc:latest-linux-amd64 . -f Dockerfile.hub
代码质量检查
项目在持续集成流程中会执行以下检查：
-
Go 代码单元测试覆盖率
- 要求覆盖率不低于 81%
- 本地可通过
./coverage.sh检查 - 使用专业工具可视化覆盖率报告
-
前端代码规范检查
- 使用 eslint 进行 JavaScript 代码检查
- 本地可通过
./lint.sh检查 - 可自动修复部分规范问题：
npm run lint-autofix
结语
本文详细介绍了 ZincSearch 项目的开发环境搭建、构建流程以及开发模式下的注意事项。通过遵循这些步骤，开发者可以顺利开始 ZincSearch 的二次开发或功能扩展工作。项目采用现代化的技术栈和严格的代码质量检查机制，确保了代码的可靠性和可维护性。
