Tài Liệu Triển Khai Môi Trường Cục Bộ — API Backend Traffic Tools V2

1. Yêu Cầu Hệ Thống

1.1. Yêu Cầu Bắt Buộc

Go phiên bản >= 1.22.4. Tải từ https://golang.org/dl/. Đảm bảo GOPATH và GOROOT được cấu hình đúng.

Docker Desktop (Windows/macOS) hoặc Docker Engine (Linux) để chạy MySQL, MongoDB và Redis.

Git phiên bản >= 2.30.0.

Make (GNU Make) để chạy các lệnh trong Makefile. Người dùng Windows cần cài GnuWin32 Make hoặc sử dụng WSL2.

1.2. Công Cụ Khuyến Nghị

Air (hot-reload): go install github.com/cosmtrek/air@latest

GoLand hoặc VSCode với extension Go (golang.go).

DBeaver hoặc DataGrip để xem dữ liệu MySQL.

MongoDB Compass để xem dữ liệu MongoDB.

RedisInsight để xem dữ liệu Redis.

2. Thiết Lập Lần Đầu

2.1. Clone Repository

2.2. Cài Đặt Dependencies

2.3. Khởi Động Hạ Tầng Docker

Sau khi khởi động, các dịch vụ sẽ lắng nghe trên:

MySQL: localhost:33022 (map từ container port 3306)

MongoDB: localhost:33021 (map từ container port 27017)

Redis: localhost:33023 (map từ container port 6379)

Kiểm tra dịch vụ đang chạy:

2.4. Cấu Hình Biến Môi Trường

Mở file .env và chỉnh sửa các giá trị cần thiết. Các giá trị quan trọng cần thay đổi:

APP_MODE=development — Đảm bảo đang ở chế độ development.

AUTO_MIGRATE_DATABASE=true — Bật auto-migrate để GORM tạo bảng tự động.

DB_MYSQL_HOST=localhost — Nếu chạy API ngoài Docker, dùng localhost thay vì tên service.

DB_MYSQL_PORT=33022 — Port MySQL đã map ra ngoài.

DB_MONGO_HOST=localhost — Tương tự MongoDB.

DB_MONGO_PORT=33021 — Port MongoDB đã map ra ngoài.

REDIS_HOST=localhost — Tương tự Redis.

REDIS_PORT=33023 — Port Redis đã map ra ngoài.

Lưu ý: Nếu chạy API trong Docker Compose cùng với các dịch vụ khác, dùng tên service (traffic_tool_mysql, traffic_tool_mongodb, traffic_tool_redis) và port mặc định (3306, 27017, 6379).

2.5. Tạo Dữ Liệu Test

3. Khởi Chạy Môi Trường Phát Triển

3.1. Chạy Với go run (Đơn Giản)

Server sẽ khởi động và in ra:

DEBUG: Loaded environment in development mode
[CRON] Starting RunCron - Initializing all cronjobs...
...
Server started on port 33003

3.2. Chạy Với Air (Hot-Reload)

Khi lưu bất kỳ file .go nào, Air tự động rebuild và restart server trong vòng 500ms. Đây là cách làm việc được khuyến nghị trong development.

3.3. Build Binary

Chạy binary đã build:

4. Kiểm Tra API

4.1. Kiểm Tra Server Đang Chạy

4.2. Đăng Nhập

4.3. Gọi API Bảo Vệ

5. Các Lệnh Phát Triển Thường Dùng

5.1. Format Code

5.2. Kiểm Tra Lint

5.3. Kiểm Tra Bảo Mật

5.4. Chạy Tests

5.5. Xem Tài Liệu Go

6. Cấu Trúc Docker Compose Local

File docker-compose.yaml định nghĩa toàn bộ hạ tầng local:

7. Xử Lý Sự Cố Thường Gặp

7.1. Lỗi "Port Already In Use"

7.2. Lỗi Kết Nối Database

Kiểm tra Docker containers đang chạy:

Nếu container không chạy:

Kiểm tra log container:

7.3. Lỗi "go.mod" Không Đồng Nhất

7.4. Lỗi Auto-Migrate

Nếu GORM báo lỗi khi migrate, kiểm tra:

AUTO_MIGRATE_DATABASE=true trong .env.

User MySQL có đủ quyền CREATE TABLE, ALTER TABLE.

Database tool_traffic_api đã tồn tại.

Tạo database thủ công nếu cần:

7.5. Lỗi Air Không Reload

Kiểm tra file .air.toml có đúng cấu hình không:

Thử chạy lại với flag verbose:

7.6. Lỗi Cron Job Không Chạy

Kiểm tra biểu thức cron trong .env:

Viper đọc giá trị có dấu nháy như một chuỗi bao gồm cả dấu nháy, gây lỗi parse cron expression.

8. Debug Với Delve

Delve là debugger chính thức cho Go, tích hợp với VSCode và GoLand:

8.1. Cài Đặt Delve

8.2. Chạy Với Debugger

8.3. Cấu Hình VSCode

File .vscode/launch.json:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Launch API",
      "type": "go",
      "request": "launch",
      "mode": "auto",
      "program": "${workspaceFolder}/cmd/main.go",
      "env": {},
      "args": []
    }
  ]
}

9. Quy Trình Làm Việc Hàng Ngày

9.1. Bắt Đầu Ngày Làm Việc

9.2. Trước Khi Tạo Merge Request

9.3. Quy Trình Tạo Tính Năng Mới

Tạo branch mới từ develop: git checkout -b feature/ten-tinh-nang.

Phát triển tính năng với air -c .air.toml.

Viết unit test cho business logic quan trọng.

Commit theo Conventional Commits format.

Chạy make fmt, make lint, make test trước khi push.

Tạo Merge Request vào nhánh develop trên GitLab.

Sau khi được review và approve, merge vào develop.

Pipeline GitLab CI sẽ tự động deploy lên môi trường Develop.

10. Tạo Dữ Liệu Test

10.1. Sử Dụng testdata Package

Package testdata/ cung cấp generators để tạo dữ liệu test:

10.2. Generators Có Sẵn

testdata/generators/profile/ — Tạo browser profiles.

testdata/generators/proxy/ — Tạo proxy records.

testdata/generators/report/ — Tạo report data.

testdata/generators/server/ — Tạo server records.

10.3. Tạo MongoDB Indexes

Script này tạo các indexes cần thiết cho MongoDB collections để đảm bảo hiệu suất query.

Local

Tài Liệu Triển Khai Môi Trường Cục Bộ — API Backend Traffic Tools V2#

1. Yêu Cầu Hệ Thống#

1.1. Yêu Cầu Bắt Buộc#

1.2. Công Cụ Khuyến Nghị#

2. Thiết Lập Lần Đầu#

2.1. Clone Repository#

2.2. Cài Đặt Dependencies#

2.3. Khởi Động Hạ Tầng Docker#

2.4. Cấu Hình Biến Môi Trường#

2.5. Tạo Dữ Liệu Test#

3. Khởi Chạy Môi Trường Phát Triển#

3.1. Chạy Với go run (Đơn Giản)#

3.2. Chạy Với Air (Hot-Reload)#

3.3. Build Binary#

4. Kiểm Tra API#

4.1. Kiểm Tra Server Đang Chạy#

4.2. Đăng Nhập#

4.3. Gọi API Bảo Vệ#

5. Các Lệnh Phát Triển Thường Dùng#

5.1. Format Code#

5.2. Kiểm Tra Lint#

5.3. Kiểm Tra Bảo Mật#

5.4. Chạy Tests#

5.5. Xem Tài Liệu Go#

6. Cấu Trúc Docker Compose Local#

7. Xử Lý Sự Cố Thường Gặp#

7.1. Lỗi "Port Already In Use"#

7.2. Lỗi Kết Nối Database#

7.3. Lỗi "go.mod" Không Đồng Nhất#

7.4. Lỗi Auto-Migrate#

7.5. Lỗi Air Không Reload#

7.6. Lỗi Cron Job Không Chạy#

8. Debug Với Delve#

8.1. Cài Đặt Delve#

8.2. Chạy Với Debugger#

8.3. Cấu Hình VSCode#

9. Quy Trình Làm Việc Hàng Ngày#

9.1. Bắt Đầu Ngày Làm Việc#

9.2. Trước Khi Tạo Merge Request#

9.3. Quy Trình Tạo Tính Năng Mới#

10. Tạo Dữ Liệu Test#

10.1. Sử Dụng testdata Package#

10.2. Generators Có Sẵn#

10.3. Tạo MongoDB Indexes#