Go Backend Service

یک سرویس REST API ساده و production-ready با استفاده از Go و Gin framework.

📋 فهرست مطالب

شروع سریع
پیش‌نیازها
ساختار پروژه
راه‌اندازی محیط Development
راه‌اندازی محیط Production
API Endpoints
استفاده از Makefile
Observability
مستندات بیشتر

🚀 شروع سریع

برای تازه‌کارها (اولین بار)

# 1. کلون کردن پروژه (اگر از Git استفاده می‌کنید)
git clone <repository-url>
cd sdgo

# 2. ایجاد فایل .env از نمونه
cp env.example .env

# 3. راه‌اندازی با Docker (ساده‌ترین روش)
make docker-up

# 4. تست API
curl http://localhost:8080/health

خروجی مورد انتظار:

{"status":"ok","state":"ready"}

📦 پیش‌نیازها

حداقل نیازمندی‌ها

Docker 20.10+ و Docker Compose 2.0+ (برای اجرای با Docker)
Go 1.21+ (فقط برای development محلی)
Make (اختیاری اما توصیه می‌شود)

نصب Docker

Linux:

curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo usermod -aG docker $USER

macOS:

brew install docker docker-compose
# یا دانلود Docker Desktop از docker.com

Windows: دانلود و نصب Docker Desktop

بررسی نصب

docker --version
docker-compose --version

📁 ساختار پروژه

sdgo/
├── cmd/
│   └── server/              # Entry point اصلی برنامه
│       └── main.go          # نقطه شروع برنامه
│
├── internal/                # کدهای داخلی (غیر قابل استفاده خارجی)
│   ├── api/                 # API handlers و routes
│   │   ├── handlers.go     # Handler functions
│   │   └── routes.go        # Route definitions
│   ├── config/              # مدیریت configuration
│   │   └── config.go        # بارگذاری و validation
│   ├── lifecycle/           # مدیریت lifecycle (ready/shutdown)
│   │   └── lifecycle.go
│   ├── logger/              # Logging utilities
│   │   └── logger.go        # Zerolog setup
│   ├── metrics/             # Prometheus metrics
│   │   └── metrics.go
│   ├── middleware/          # HTTP middleware
│   │   ├── correlation.go   # Correlation ID
│   │   ├── error_handler.go # Error handling
│   │   ├── logging.go       # Request/Response logging
│   │   ├── prometheus.go    # Metrics collection
│   │   └── tracing.go       # OpenTelemetry tracing
│   ├── server/              # HTTP server wrapper
│   │   └── server.go        # Server lifecycle
│   └── tracer/              # OpenTelemetry tracer
│       └── tracer.go
│
├── pkg/                      # Packages قابل استفاده خارجی
│   └── errors/              # Error definitions
│       └── errors.go
│
├── configs/                  # فایل‌های configuration
│   ├── prometheus.yml        # Prometheus config
│   ├── tempo.yaml            # Tempo config
│   ├── loki/                 # Loki configs
│   └── promtail/             # Promtail configs
│
├── docs/                     # مستندات پروژه
│   ├── QUICK_START.md        # راهنمای سریع
│   ├── LOCAL_DEVELOPMENT.md  # راهنمای development
│   ├── OBSERVABILITY.md      # راهنمای Observability
│   ├── LOKI_GUIDE.md         # راهنمای Loki
│   ├── PROMETHEUS_GUIDE.md   # راهنمای Prometheus
│   └── ...                   # سایر مستندات
│
├── docker-compose.yml        # Docker Compose برای production
├── docker-compose.dev.yml    # Docker Compose برای development DB
├── docker-compose.observability.yml  # Observability stack
├── Dockerfile                # Multi-stage Docker build
├── Makefile                  # Build automation
├── env.example               # نمونه فایل environment variables
└── README.md                 # این فایل

توضیح ساختار

cmd/server/: نقطه ورود برنامه. اینجا main() قرار دارد.
internal/: کدهای داخلی که نباید از خارج پروژه استفاده شوند.
pkg/: کدهای قابل استفاده خارجی (مثل libraries).
configs/: فایل‌های configuration برای ابزارهای خارجی.

🛠️ راه‌اندازی محیط Development

روش 1: با Docker (توصیه می‌شود برای شروع)

این روش ساده‌ترین است و نیازی به نصب Go ندارد.

مرحله 1: آماده‌سازی

# ایجاد فایل .env از نمونه
cp env.example .env

# بررسی فایل .env (مقادیر پیش‌فرض معمولاً کافی است)
cat .env

مرحله 2: راه‌اندازی

# راه‌اندازی تمام سرویس‌ها (PostgreSQL + API)
make docker-up

این دستور:

✅ PostgreSQL container را راه‌اندازی می‌کند
✅ Docker image را می‌سازد (در اولین اجرا)
✅ API container را راه‌اندازی می‌کند
✅ Health check را اجرا می‌کند

مرحله 3: بررسی وضعیت

# مشاهده لاگ‌ها
make docker-logs

# یا فقط لاگ API
docker-compose logs -f api

# بررسی وضعیت containers
docker ps

مرحله 4: تست API

# Health check
curl http://localhost:8080/health

# Readiness probe
curl http://localhost:8080/ready

# Liveness probe
curl http://localhost:8080/live

# Hello endpoint
curl http://localhost:8080/hello

مرحله 5: توقف

# توقف تمام containers
make docker-down

🔄 Rebuild بعد از تغییر کد

مهم: Docker به صورت خودکار کد را rebuild نمی‌کند. بعد از تغییر کد:

# روش 1: Rebuild و restart
make docker-up-rebuild

# روش 2: فقط rebuild API
docker-compose build api
docker-compose up -d api

# روش 3: Rebuild با --build flag
docker-compose up -d --build api

روش 2: اجرای محلی با Hot Reload (برای Development)

این روش برای development بهتر است چون با هر تغییر کد، خودکار rebuild می‌شود.

مرحله 1: راه‌اندازی دیتابیس

# راه‌اندازی PostgreSQL
make dev-db-up

مرحله 2: تنظیم .env

# ایجاد .env (اگر وجود ندارد)
make dev-setup

# تغییر DB_HOST به localhost
# در فایل .env:
# DB_HOST=localhost

مرحله 3: اجرای برنامه

# اجرا با hot reload (توصیه می‌شود)
make dev-run

# یا اجرای ساده (بدون hot reload)
make run

نکته: make dev-run از air استفاده می‌کند که به صورت خودکار نصب می‌شود.

مرحله 4: توقف

# توقف دیتابیس
make dev-db-down

# توقف برنامه: Ctrl+C

مقایسه روش‌ها

ویژگی	Docker (`make docker-up`)	Local (`make dev-run`)
نیاز به Go	❌	✅
Hot Reload	❌ (نیاز به rebuild)	✅ (خودکار)
سرعت تغییرات	کند (نیاز به rebuild)	سریع (instant)
مناسب برای	Testing, Production	Development
پیچیدگی	ساده	متوسط

توصیه:

شروع کار: از make docker-up استفاده کنید
Development فعال: از make dev-run استفاده کنید

🏭 راه‌اندازی محیط Production

پیش‌نیازها

فایل .env با مقادیر production
JWT_SECRET_KEY و JWT_REFRESH_SECRET باید تغییر کنند
GIN_MODE=release

مرحله 1: تنظیم Environment Variables

# کپی از نمونه
cp env.example .env

# ویرایش .env و تغییر مقادیر مهم:
# - JWT_SECRET_KEY (حداقل 32 کاراکتر)
# - JWT_REFRESH_SECRET (حداقل 32 کاراکتر)
# - GIN_MODE=release
# - LOG_LEVEL=info

مرحله 2: Build Docker Image

# Build image
make docker-build

# یا force rebuild
make docker-build-rebuild

مرحله 3: اجرا

# با Docker Compose
make docker-up

# یا با Docker مستقیم
docker run -d \
  --name go-backend-api \
  -p 8080:8080 \
  --env-file .env \
  go-backend-service:latest

مرحله 4: بررسی Health

# Health check
curl http://localhost:8080/health

# Readiness (برای Kubernetes)
curl http://localhost:8080/ready

# Liveness (برای Kubernetes)
curl http://localhost:8080/live

مرحله 5: Monitoring

# مشاهده logs
docker logs -f go-backend-api

# یا با Docker Compose
docker-compose logs -f api

نکات Production

Secrets Management: از Docker Secrets یا Kubernetes Secrets استفاده کنید
Logging: Logs به stdout می‌روند. از log aggregation استفاده کنید
Health Checks: از /ready و /live برای Kubernetes probes استفاده کنید
Graceful Shutdown: برنامه از graceful shutdown پشتیبانی می‌کند
Metrics: از /metrics برای Prometheus scraping استفاده کنید

🔌 API Endpoints

Health & Lifecycle

Endpoint	Method	توضیحات	استفاده
`/health`	GET	Health check عمومی	Docker healthcheck
`/ready`	GET	Readiness probe	Kubernetes readiness
`/live`	GET	Liveness probe	Kubernetes liveness

مثال:

curl http://localhost:8080/health
# {"status":"ok","state":"ready"}

curl http://localhost:8080/ready
# {"status":"ready","state":"ready"}

curl http://localhost:8080/live
# {"status":"alive","state":"ready"}

Application Endpoints

Endpoint	Method	توضیحات
`/hello`	GET	پیام Hello World
`/delayed-hello`	GET	Hello با delay تصادفی (1-3 ثانیه)
`/test-error`	GET	تست error handling
`/metrics`	GET	Prometheus metrics

مثال:

curl http://localhost:8080/hello
# {"message":"Hello, World!"}

curl http://localhost:8080/metrics
# # HELP http_request_duration_seconds Duration of HTTP requests...

🎯 استفاده از Makefile

دستورات اصلی

# نمایش تمام دستورات
make help

# Development
make dev              # راه‌اندازی کامل محیط dev
make dev-setup        # ایجاد .env
make dev-db-up        # راه‌اندازی دیتابیس
make dev-run          # اجرا با hot reload
make run              # اجرای ساده

# Docker
make docker-up        # راه‌اندازی containers
make docker-down      # توقف containers
make docker-logs      # مشاهده logs
make docker-build     # Build image
make docker-up-rebuild # Rebuild و restart

# Build & Test
make build            # Build binary
make test             # اجرای تست‌ها
make deps             # دانلود dependencies

دستورات کامل

برای لیست کامل دستورات:

make help

📊 Observability

این پروژه شامل پشتیبانی کامل از Observability است:

OpenTelemetry Tracing: Distributed tracing
Tempo: Trace storage backend
Jaeger UI: Visualization traces (اختیاری)
Prometheus: Metrics collection
Loki: Log aggregation و central logging
Promtail: Log collector از Docker containers
Grafana: Dashboards و visualization (traces, logs, metrics)

راه‌اندازی سریع

# راه‌اندازی تمام stack (Tempo, Jaeger, Prometheus, Loki, Grafana)
make observability-up

# بعد از تغییر config files (tempo.yaml, prometheus.yml, loki-config.yaml):
make observability-up-rebuild

# دسترسی به UI:
# - Grafana: http://localhost:3000 (admin/admin) - برای traces, logs, metrics
# - Jaeger: http://localhost:16686 (memory storage only)
# - Prometheus: http://localhost:9090
# - Loki API: http://localhost:3100
# - Tempo API: http://localhost:3200

مشاهده Logs در Grafana

باز کردن: http://localhost:3000
رفتن به Explore (منوی سمت چپ)
انتخاب Loki datasource
جستجوی logs:
```
{container="go-backend-api"}
```

برای راهنمای کامل، به OBSERVABILITY.md و LOKI_GUIDE.md مراجعه کنید.

📚 مستندات بیشتر

تمام مستندات در پوشه docs/ قرار دارند:

راهنماهای اصلی

QUICK_START.md: راهنمای سریع شروع کار
LOCAL_DEVELOPMENT.md: راهنمای کامل development محلی
TROUBLESHOOTING.md: راهنمای عیب‌یابی مشکلات رایج

Observability

OBSERVABILITY.md: راهنمای کامل Observability (Tempo, Prometheus, Grafana)
LOKI_GUIDE.md: راهنمای کامل Loki و Central Logging
LOGGING_GUIDE.md: راهنمای مشاهده و مدیریت لاگ‌ها
PROMETHEUS_GUIDE.md: راهنمای مشاهده Metrics در Grafana
TEMPO_GUIDE.md: راهنمای کامل Tempo و مشاهده Traces
TEMPO_QUICK_START.md: راهنمای سریع Tempo

Development & Debugging

VSCODE_DEBUG_GUIDE.md: راهنمای کامل debug با VS Code
VSCODE_DEBUG.md: راهنمای debug با VS Code (نسخه قدیمی)
DEBUG_TIMEOUT_FIX.md: راهنمای رفع مشکل Timeout در Debug
DEBUG_TIPS.md: نکات و ترفندهای Debug

Docker & Infrastructure

DOCKER_VERSIONING.md: راهنمای Versioning در Docker Images
DOCKER_BUILD_FIX.md: راهنمای رفع مشکلات Docker Build

سایر

RUN_GUIDE.md: راهنمای اجرا (قدیمی - برای مرجع)

🐛 عیب‌یابی (Troubleshooting)

مشکل: Container از کد قدیمی استفاده می‌کند

راه‌حل:

# Rebuild container
make docker-up-rebuild

# یا
docker-compose build api
docker-compose up -d api

مشکل: Port 8080 در حال استفاده است

راه‌حل:

# تغییر port در .env
SERVER_PORT=8081

# یا توقف برنامه استفاده‌کننده از port
sudo lsof -i :8080
kill -9 <PID>

مشکل: Database connection failed

راه‌حل:

# بررسی وضعیت PostgreSQL
docker ps | grep postgres

# بررسی logs
docker-compose logs postgres

# Restart database
docker-compose restart postgres

مشکل: `/ready` یا `/live` 404 می‌دهد

راه‌حل:

# Container از کد قدیمی استفاده می‌کند
make docker-up-rebuild

📝 Environment Variables

تمام متغیرهای محیطی در env.example تعریف شده‌اند:

# Server
SERVER_HOST=0.0.0.0
SERVER_PORT=8080
SERVER_READ_TIMEOUT=15s
SERVER_WRITE_TIMEOUT=15s
SERVER_IDLE_TIMEOUT=120s
SERVER_GRACEFUL_SHUTDOWN_TIMEOUT=10s

# Database
DB_HOST=postgres
DB_PORT=5432
DB_USER=postgres
DB_PASSWORD=postgres
DB_NAME=go_backend_db
DB_SSLMODE=disable

# JWT
JWT_SECRET_KEY=your-secret-key-change-in-production-min-32-chars
JWT_REFRESH_SECRET=your-refresh-secret-key-change-in-production-min-32-chars
JWT_EXPIRATION=24h

# Application
GIN_MODE=release  # یا debug برای development
LOG_LEVEL=info    # debug, info, warn, error

# OpenTelemetry
OTEL_TRACING_ENABLED=true
OTEL_SERVICE_NAME=go-backend-service
OTEL_SERVICE_VERSION=1.0.0
OTEL_JAEGER_ENABLED=true
OTEL_JAEGER_ENDPOINT=jaeger:4318

🔒 امنیت

✅ Non-root user در Docker
✅ Graceful shutdown
✅ Health checks
✅ Structured logging
✅ Error handling
⚠️ مهم: در production، JWT_SECRET_KEY را تغییر دهید

📄 مجوز

MIT

🤝 مشارکت

برای مشارکت در پروژه، لطفاً:

Issue ایجاد کنید
Fork کنید
Branch جدید بسازید
تغییرات را commit کنید
Pull Request ارسال کنید

📞 پشتیبانی

برای سوالات و مشکلات:

Issue در GitHub ایجاد کنید
مستندات را بررسی کنید
Logs را بررسی کنید: make docker-logs

Name		Name	Last commit message	Last commit date
Latest commit History 25 Commits
bin		bin
cmd/server		cmd/server
configs		configs
docs		docs
internal		internal
pkg/errors		pkg/errors
tasks		tasks
.air.toml		.air.toml
.dockerignore		.dockerignore
.gitignore		.gitignore
Dockerfile		Dockerfile
Makefile		Makefile
README.md		README.md
docker-compose.dev.yml		docker-compose.dev.yml
docker-compose.observability.yml		docker-compose.observability.yml
docker-compose.yml		docker-compose.yml
env.example		env.example
go.mod		go.mod
go.sum		go.sum

system-design1/cloud-native

Folders and files

Latest commit

History

Repository files navigation

Go Backend Service

📋 فهرست مطالب

🚀 شروع سریع

برای تازه‌کارها (اولین بار)

📦 پیش‌نیازها

حداقل نیازمندی‌ها

نصب Docker

بررسی نصب

📁 ساختار پروژه

توضیح ساختار

🛠️ راه‌اندازی محیط Development

روش 1: با Docker (توصیه می‌شود برای شروع)

مرحله 1: آماده‌سازی

مرحله 2: راه‌اندازی

مرحله 3: بررسی وضعیت

مرحله 4: تست API

مرحله 5: توقف

🔄 Rebuild بعد از تغییر کد

روش 2: اجرای محلی با Hot Reload (برای Development)

مرحله 1: راه‌اندازی دیتابیس

مرحله 2: تنظیم .env

مرحله 3: اجرای برنامه

مرحله 4: توقف

مقایسه روش‌ها

🏭 راه‌اندازی محیط Production

پیش‌نیازها

مرحله 1: تنظیم Environment Variables

مرحله 2: Build Docker Image

مرحله 3: اجرا

مرحله 4: بررسی Health

مرحله 5: Monitoring

نکات Production

🔌 API Endpoints

Health & Lifecycle

Application Endpoints

🎯 استفاده از Makefile

دستورات اصلی

دستورات کامل

📊 Observability

راه‌اندازی سریع

مشاهده Logs در Grafana

📚 مستندات بیشتر

راهنماهای اصلی

Observability

Development & Debugging

Docker & Infrastructure

سایر

🐛 عیب‌یابی (Troubleshooting)

مشکل: Container از کد قدیمی استفاده می‌کند

مشکل: Port 8080 در حال استفاده است

مشکل: Database connection failed

مشکل: /ready یا /live 404 می‌دهد

📝 Environment Variables

🔒 امنیت

📄 مجوز

🤝 مشارکت

📞 پشتیبانی

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

مشکل: `/ready` یا `/live` 404 می‌دهد

Packages