ocdp-go/backend/QUICK-REFERENCE.md

快速参考卡片

🚀 五个核心命令

make run-0     # Mock 模式（秒启动，无需 Docker）
make run-1     # 开发模式（Docker 依赖 + 本地热加载）
make run-2     # 生产模式（全部容器化）
make clean-1   # 清理开发环境
make clean-2   # 清理生产环境

---

📋 模式对比

特性	run-0	run-1	run-2
后端位置	本地	本地	容器
数据库	Mock	容器	容器
热加载	✅	✅	❌
启动速度	⚡ 秒启	🔥 5秒	🐳 30秒
适用场景	快速开发	日常开发	部署测试
依赖 Docker	❌	✅	✅

---

🎯 使用场景

场景 1: 快速功能开发

make run-0
# 修改代码，自动重新编译
# Ctrl+C 停止

场景 2: 日常开发（推荐）

make run-1
# 修改代码，自动重新编译
# Ctrl+C 停止后端（数据库继续运行）

# 第二天继续
make run-1  # 数据库还在，直接启动

# 重置数据库
make clean-1
make run-1

场景 3: 部署前测试

make run-2
# 查看日志
docker compose --profile backend logs -f

# 测试完成
make clean-2

---

🔧 Docker Compose 直接使用

启动依赖（run-1 等价）

docker compose up -d postgres
go run cmd/api/main.go

启动完整环境（run-2 等价）

docker compose --profile backend up -d

查看状态

docker compose ps                      # run-1
docker compose --profile backend ps    # run-2

停止

docker compose down                    # run-1
docker compose --profile backend down  # run-2

---

📂 关键文件

文件	说明
Makefile	5个核心命令
docker-compose.yml	使用 profile 的统一配置
.air.toml	热加载配置
env.example	环境变量模板

---

🐳 Docker Compose Profile 原理

# docker-compose.yml
services:
  postgres:
    # 默认启动（无需 profile）
    
  backend:
    profiles: [backend]  # 需要 --profile backend

使用方式:

docker compose up -d               # 只启动 postgres
docker compose --profile backend up -d  # 启动 postgres + backend

---

💡 快速提示

• 首次使用运行: go install github.com/cosmtrek/air@latest
• 查看帮助: make 或 make help
• 完整文档: 查看 DEVELOPMENT.md
• 审查报告: 查看 REVIEW.md

---

🎯 一句话总结

三种模式，五个命令，一个 Docker Compose 文件。