ocdp-go/backend/DEVELOPMENT.md

开发环境快速指南

📋 前置要求

• Go 1.21+
• Docker & Docker Compose
• Air（热加载工具）: go install github.com/cosmtrek/air@latest

🎯 设计理念

本项目使用 Docker Compose Profile 机制，通过单一的 docker-compose.yml 文件支持三种运行模式，避免配置文件重复。

🚀 三种运行模式

模式 0: Mock 模式（最快）

纯本地运行，无需任何外部依赖，所有服务都是 Mock。

make run-0

特点:

• ✅ 启动最快（秒启动）
• ✅ 无需 Docker
• ✅ 支持热加载
• ✅ 适合快速功能开发

停止: Ctrl+C

---

模式 1: 开发模式（推荐）

Docker 提供真实的 PostgreSQL，后端在本地运行并支持热加载。

make run-1

特点:

• ✅ 真实的数据库
• ✅ 支持热加载
• ✅ 代码修改实时生效
• ✅ 适合日常开发

停止: Ctrl+C 停止后端（数据库容器继续运行）

清理: make clean-1 清理数据库和临时文件

---

模式 2: 生产模式

所有服务完全容器化，模拟生产环境。

make run-2

特点:

• ✅ 完全容器化
• ✅ 接近生产环境
• ✅ 后台运行
• ❌ 无热加载

查看日志:

docker compose --profile backend logs -f

停止:

docker compose --profile backend down

清理: make clean-2 清理所有容器和构建产物

---

🧹 清理命令

# 清理模式 1 的产物（依赖容器 + 临时文件）
make clean-1

# 清理模式 2 的产物（所有容器 + 构建产物）
make clean-2

---

📊 常用工作流

日常开发

# 启动开发环境
make run-1

# ... 编码、测试 ...
# 代码修改会自动重新编译

# 下班停止（Ctrl+C）
# 第二天继续（依赖容器还在运行，直接启动）
make run-1

重置数据库

# 清理并重新开始
make clean-1
make run-1

测试生产部署

# 启动生产模式
make run-2

# 查看日志
docker compose -f docker-compose.prod.yml logs -f

# 测试完成后清理
make clean-2

---

🔧 环境变量配置

复制并修改环境变量配置：

cp env.example .env

主要配置项：

• ADAPTER_MODE: 设置为 mock 启用 Mock 模式（模式 0）
• POSTGRES_*: 数据库配置（模式 1、2）
• JWT_SECRET: JWT 密钥（生产环境必须修改）
• ENCRYPTION_KEY: 加密密钥（必须 32 字节）

---

📂 文件说明

文件	用途
Makefile	开发命令入口（5个核心命令）
.air.toml	热加载配置
docker-compose.yml	统一配置文件（使用 profile 区分模式）
Dockerfile	生产镜像构建配置
DEVELOPMENT.md	本文档

Docker Compose Profile 说明

• 无 profile: 只启动 postgres（用于模式 1）
• --profile backend: 启动 postgres + backend（用于模式 2）
• --profile mock: 启动 backend-mock（独立的 mock 模式容器）

---

❓ 常见问题

Q: 模式 1 启动失败，提示端口被占用？

A: 检查是否有其他 PostgreSQL 实例在运行：

docker ps | grep postgres
# 或者修改 .env 中的 POSTGRES_PORT

Q: 如何查看依赖服务状态？

A:

docker compose ps                      # 模式 1（只有 postgres）
docker compose --profile backend ps    # 模式 2（postgres + backend）

Q: 模式 1 和模式 2 的数据库数据会互相影响吗？

A: 会共享同一个数据库容器和数据卷 ocdp-postgres-data。

• 模式 1: 使用本地 air 连接到 postgres 容器
• 模式 2: 使用 backend 容器连接到 postgres 容器
• 数据是持久化的，切换模式不会丢失数据

Q: 如何完全清理所有 Docker 资源？

A:

make clean-1
make clean-2
docker system prune -a --volumes

---

💡 提示

• 首次使用: 推荐从 make run-0 开始，快速验证环境
• 日常开发: 使用 make run-1，享受热加载和真实数据库
• 部署前测试: 使用 make run-2，确保容器化部署没问题
• 数据持久化: 模式 1 和 2 的数据库数据都会持久化，Ctrl+C 不会丢失数据
• 完全重置: 使用 clean-* 命令会删除数据卷，数据会丢失

---

🎯 快速参考

make          # 显示帮助
make run-0    # Mock 模式
make run-1    # 开发模式
make run-2    # 生产模式
make clean-1  # 清理开发环境
make clean-2  # 清理生产环境