urldb/docs/guide/local-development.md

💻 本地开发

环境准备

1. 安装必需软件

Go 环境

# 下载并安装 Go 1.23+
# 访问 https://golang.org/dl/
# 或使用包管理器安装

# 验证安装
go version

Node.js 环境

# 下载并安装 Node.js 18+
# 访问 https://nodejs.org/
# 或使用 nvm 安装

# 验证安装
node --version
npm --version

PostgreSQL 数据库

# Ubuntu/Debian
sudo apt update
sudo apt install postgresql postgresql-contrib

# macOS (使用 Homebrew)
brew install postgresql

# 启动服务
sudo systemctl start postgresql  # Linux
brew services start postgresql   # macOS

pnpm (推荐)

# 安装 pnpm
npm install -g pnpm

# 验证安装
pnpm --version

2. 克隆项目

git clone https://github.com/ctwj/urldb.git
cd urldb

后端开发

1. 环境配置

# 复制环境变量文件
cp env.example .env

# 编辑环境变量
vim .env

2. 数据库设置

-- 登录 PostgreSQL
sudo -u postgres psql

-- 创建数据库
CREATE DATABASE url_db;

-- 创建用户（可选）
CREATE USER url_user WITH PASSWORD 'your_password';
GRANT ALL PRIVILEGES ON DATABASE url_db TO url_user;

-- 退出
\q

3. 安装依赖

# 安装 Go 依赖
go mod tidy

# 验证依赖
go mod verify

4. 启动后端服务

# 开发模式启动
go run main.go

# 或使用 air 热重载（推荐）
go install github.com/cosmtrek/air@latest
air

前端开发

1. 进入前端目录

cd web

2. 安装依赖

# 使用 pnpm (推荐)
pnpm install

# 或使用 npm
npm install

3. 启动开发服务器

# 开发模式
pnpm dev

# 或使用 npm
npm run dev

4. 访问前端

前端服务启动后，访问 http://localhost:3000

开发工具

推荐的 IDE 和插件

VS Code

• Go - Go 语言支持
• Vetur 或 Volar - Vue.js 支持
• PostgreSQL - 数据库支持
• Docker - Docker 支持
• GitLens - Git 增强

GoLand / IntelliJ IDEA

• 内置 Go 和 Vue.js 支持
• 数据库工具
• Docker 集成

代码格式化

# Go 代码格式化
go fmt ./...

# 前端代码格式化
cd web
pnpm format

代码检查

# Go 代码检查
go vet ./...

# 前端代码检查
cd web
pnpm lint

调试技巧

后端调试

# 使用 delve 调试器
go install github.com/go-delve/delve/cmd/dlv@latest
dlv debug main.go

# 或使用 VS Code 调试配置

前端调试

# 启动开发服务器时开启调试
cd web
pnpm dev --inspect

数据库调试

# 连接数据库
psql -h localhost -U postgres -d url_db

# 查看表结构
\dt

# 查看数据
SELECT * FROM users LIMIT 5;

测试

后端测试

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

# 运行特定测试
go test ./handlers

# 生成测试覆盖率报告
go test -cover ./...

前端测试

cd web

# 运行单元测试
pnpm test

# 运行 E2E 测试
pnpm test:e2e

构建

后端构建

# 构建二进制文件
go build -o urlDB main.go

# 交叉编译
GOOS=linux GOARCH=amd64 go build -o urlDB-linux main.go

前端构建

cd web

# 构建生产版本
pnpm build

# 预览构建结果
pnpm preview

常见问题

1. 端口冲突

如果遇到端口被占用的问题：

# 查看端口占用
lsof -i :8080
lsof -i :3000

# 杀死进程
kill -9 <PID>

2. 数据库连接失败

检查 .env 文件中的数据库配置：

DB_HOST=localhost
DB_PORT=5432
DB_USER=postgres
DB_PASSWORD=your_password
DB_NAME=url_db

3. 前端依赖安装失败

# 清除缓存
pnpm store prune
rm -rf node_modules
pnpm install

下一步

• 了解项目架构
• 查看 API 文档
• 学习代码规范