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
│   ├── LOAD_TESTING_K6_HELLO_CONCURRENCY.md  # راهنمای تست بار همزمانی
│   ├── LOAD_TESTING_TRACING_SAMPLING.md  # راهنمای sampling برای load testing
│   ├── OBSERVABILITY.md      # راهنمای Observability
│   ├── OBSERVABILITY_RESET.md  # راهنمای reset کردن observability stack
│   ├── 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

📋 راهنمای Rebuild: چه زمانی چه چیزی باید rebuild شود؟

نوع تغییر	دستور Rebuild	توضیحات
تغییرات در کد Go (مثل handlers, middleware, config)	`make docker-up-rebuild`	فقط container `api` باید rebuild شود
تغییرات در Dockerfile	`make docker-up-rebuild`	فقط container `api` باید rebuild شود
تغییرات در docker-compose.yml	`make docker-up-rebuild`	فقط container `api` باید rebuild شود
تغییرات در .env (environment variables)	`docker-compose restart api`	فقط restart کافی است (بدون rebuild)
تغییرات در configs/tempo.yaml	`make observability-up-rebuild`	فقط observability stack
تغییرات در configs/prometheus.yml	`make observability-up-rebuild`	فقط observability stack
تغییرات در configs/loki/ یا configs/promtail/	`make observability-up-rebuild`	فقط observability stack
تغییرات در docker-compose.observability.yml	`make observability-up-rebuild`	فقط observability stack

نکته مهم:

تغییرات در کد Go نیازی به rebuild observability stack ندارد
تغییرات در config files observability نیازی به rebuild application ندارد

روش 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: Observability (اختیاری)

برای مشاهده traces در Jaeger/Tempo:

# Terminal 1: Application (از مرحله 3)
make dev-run

# Terminal 2: Observability stack
make observability-up

# Terminal 3: Health checker (برای ایجاد traces خودکار)
make dev-health-checker

توضیحات:

Prometheus: به صورت خودکار /metrics را scrape می‌کند (هر 5 ثانیه)
Health Checker: به صورت خودکار /health, /ready و /live را call می‌کند (هر 10 ثانیه)
برای توقف health checker: Ctrl+C

مرحله 5: توقف

# توقف برنامه: Ctrl+C (در terminal که make dev-run اجرا شده)
# توقف health checker: Ctrl+C (در terminal که make dev-health-checker اجرا شده)
# توقف observability: make observability-down
# توقف دیتابیس: make dev-db-down

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

ویژگی	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...

Versioned API (v1)

OTP Service

Phase 1: Generation only (no persistence, no SMS, no verification)

Endpoint	Method	توضیحات
`/v1/otp/code`	POST	Generate a 6-digit OTP code

Response:

{
  "code": "123456"
}

مثال:

curl -X POST http://localhost:8080/v1/otp/code
# {"code":"123456"}

🎯 استفاده از Makefile

دستورات اصلی

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

# Development
make dev              # راه‌اندازی کامل محیط dev
make dev-setup        # ایجاد .env
make dev-db-up        # راه‌اندازی دیتابیس
make dev-run          # اجرا با hot reload
make dev-health-checker  # اجرای health checker (برای ایجاد traces خودکار)
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 مراجعه کنید.

Route-Based Tracing Policy (Always/Ratio/Drop)

این پروژه از Route-Based Tracing Policy پشتیبانی می‌کند که به شما امکان کنترل sampling traces بر اساس route را می‌دهد. این قابلیت برای کاهش noise در Jaeger/Tempo و تمرکز روی traces مهم مفید است.

سه نوع Policy

ALWAYS: همیشه trace می‌شود
- برای endpoints مهم که می‌خواهید همیشه trace شوند
- مثال: /delayed-hello, /test-error
RATIO: با احتمال مشخص trace می‌شود
- برای endpoints پرترافیک که می‌خواهید گاهی trace شوند
- مثال: /health=0.01 (1% از requests)
- مقدار باید بین 0.0 و 1.0 باشد
DROP: هرگز trace نمی‌شود
- برای endpoints پرترافیک که نمی‌خواهید trace شوند
- مثال: /metrics

ترتیب اولویت (Precedence)

DROP (بالاترین اولویت)
ALWAYS
RATIO
DEFAULT policy

تنظیمات پیش‌فرض (Demo-friendly)

با تنظیمات پیش‌فرض:

/delayed-hello و /test-error: همیشه trace می‌شوند
/health, /live, /ready: 1% از requests trace می‌شوند
/metrics: trace نمی‌شود (DROP)

مثال Configuration

# فعال‌سازی route-based policy
OTEL_ROUTE_POLICY_ENABLED=true

# Routes که همیشه trace می‌شوند
OTEL_ROUTE_ALWAYS=/delayed-hello,/test-error

# Routes که هرگز trace نمی‌شوند
OTEL_ROUTE_DROP=/metrics

# Routes با sampling ratio
OTEL_ROUTE_RATIO=/health=0.01,/live=0.01,/ready=0.01

# Default policy برای routes دیگر
OTEL_ROUTE_DEFAULT=always

# Default ratio (فقط برای OTEL_ROUTE_DEFAULT=ratio)
OTEL_ROUTE_DEFAULT_RATIO=1.0

غیرفعال کردن Policy

برای غیرفعال کردن policy و استفاده از رفتار پیش‌فرض (sample همه traces):

OTEL_ROUTE_POLICY_ENABLED=false

نکات مهم

Policy فقط زمانی اعمال می‌شود که OTEL_ROUTE_POLICY_ENABLED=true باشد
وقتی policy غیرفعال است، همه traces sample می‌شوند (رفتار پیش‌فرض)
برای debugging، می‌توانید policy را غیرفعال کنید تا همه traces را ببینید
Routes با query string هم درست کار می‌کنند (فقط path بررسی می‌شود)

برای جزئیات بیشتر، به OBSERVABILITY.md مراجعه کنید.

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

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

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

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

Load Testing

LOAD_TESTING_K6_HELLO_CONCURRENCY.md: راهنمای کامل تست بار همزمانی با k6 برای endpoint /hello
LOAD_TESTING_TRACING_SAMPLING.md: راهنمای جلوگیری از overload شدن Jaeger/Tempo در طول تست‌های با بار بالا با تنظیم sampling policy
OTP Service – Performance Report (Phase 1, FA): OTP_Performance_Report_Phase1_FA.md

Observability

OBSERVABILITY.md: راهنمای کامل Observability (Tempo, Prometheus, Grafana)
OBSERVABILITY_RESET.md: راهنمای reset کردن observability stack و بازیابی Jaeger بعد از تست‌های با بار بالا
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 38 Commits
bin		bin
cmd/server		cmd/server
configs		configs
docs		docs
internal		internal
k6		k6
pkg/errors		pkg/errors
scripts		scripts
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 بعد از تغییر کد

📋 راهنمای Rebuild: چه زمانی چه چیزی باید rebuild شود؟

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

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

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

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

مرحله 4: Observability (اختیاری)

مرحله 5: توقف

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

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

پیش‌نیازها

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

مرحله 2: Build Docker Image

مرحله 3: اجرا

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

مرحله 5: Monitoring

نکات Production

🔌 API Endpoints

Health & Lifecycle

Application Endpoints

Versioned API (v1)

OTP Service

🎯 استفاده از Makefile

دستورات اصلی

دستورات کامل

📊 Observability

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

مشاهده Logs در Grafana

Route-Based Tracing Policy (Always/Ratio/Drop)

سه نوع Policy

ترتیب اولویت (Precedence)

تنظیمات پیش‌فرض (Demo-friendly)

مثال Configuration

غیرفعال کردن Policy

نکات مهم

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

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

Load Testing

Observability

Development & Debugging

Docker & Infrastructure

سایر

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

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

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

مشکل: Database connection failed

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

📝 Environment Variables

🔒 امنیت

📄 مجوز

🤝 مشارکت

📞 پشتیبانی

About

Resources

Uh oh!

Stars

Watchers

Forks

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

Packages