192 lines
5.3 KiB
Markdown
192 lines
5.3 KiB
Markdown
# ULFlow Golang Starter Kit
|
|
|
|
<div align="center">
|
|
|
|
|
|
|
|
[](https://go.dev/)
|
|
[](LICENSE)
|
|
|
|
</div>
|
|
|
|
## Tổng quan
|
|
|
|
ULFlow Golang Starter Kit là nền tảng khởi tạo dự án backend cho Team ULFlow, được thiết kế để giúp khởi tạo các dự án trong thời gian ngắn, nhanh chóng mà vẫn đảm bảo các yếu tố cơ bản về kiến trúc, bảo mật và khả năng mở rộng.
|
|
|
|
### Đặc điểm chính
|
|
|
|
- **Kiến trúc DDD (Domain Driven Development)** - Customize cho phù hợp với nhu cầu dự án
|
|
- **U-Hierarchy** - Mô hình tổ chức mã nguồn theo các cấp độ logic
|
|
- **Hot Reload** - Phát triển nhanh với Air Tomb
|
|
- **Docker & Docker Compose** - Containerization và orchestration
|
|
- **Gitea Full** - CI/CD, Secret Manager, Registry Image
|
|
- **Postgres** - Cơ sở dữ liệu quan hệ
|
|
|
|
## Cài đặt
|
|
|
|
### Yêu cầu hệ thống
|
|
|
|
- Go 1.23
|
|
- Docker và Docker Compose
|
|
- Git
|
|
|
|
### Khởi tạo dự án
|
|
|
|
```bash
|
|
# Clone repository
|
|
git clone [repo-url] my-project
|
|
cd my-project
|
|
|
|
# Cài đặt dependencies và công cụ
|
|
make init
|
|
|
|
# Cấu hình môi trường
|
|
cp .env.example .env
|
|
# Chỉnh sửa file .env theo nhu cầu
|
|
|
|
# Khởi động môi trường phát triển
|
|
make dev
|
|
```
|
|
|
|
### Sử dụng Docker
|
|
|
|
Dự án cung cấp hai cấu hình Docker:
|
|
|
|
#### Môi trường phát triển (Local)
|
|
|
|
```bash
|
|
# Khởi động tất cả các dịch vụ với Docker Compose
|
|
make docker-compose-up
|
|
|
|
# Dừng tất cả các dịch vụ
|
|
make docker-compose-down
|
|
|
|
# Dọn dẹp container sau khi sử dụng
|
|
make docker-clean
|
|
```
|
|
|
|
Môi trường phát triển bao gồm:
|
|
- API service với hot reload (Air Tomb)
|
|
- PostgreSQL database
|
|
- Gitea (Git Server, CI/CD, Registry)
|
|
- Gitea Runner
|
|
|
|
#### Môi trường production
|
|
|
|
```bash
|
|
# Khởi động các dịch vụ cho production
|
|
make docker-compose-prod-up
|
|
|
|
# Dừng các dịch vụ production
|
|
make docker-compose-prod-down
|
|
```
|
|
|
|
Môi trường production bao gồm:
|
|
- API service (optimized build)
|
|
- PostgreSQL database
|
|
- Nginx reverse proxy
|
|
|
|
## Kiến trúc
|
|
|
|
Dự án sử dụng mô hình DDD (Domain Driven Development) với các thành phần chính:
|
|
|
|
- **Resource**: Các Aggregate DDD
|
|
- **Transaction**: Các Saga điều phối luồng nghiệp vụ phức tạp
|
|
- **Adapter**: Xử lý giao tiếp với các hệ thống bên ngoài
|
|
- **Helper**: Các thư viện, tiện ích dùng chung
|
|
- **UIUX**: Lớp giao diện người dùng
|
|
|
|
Thành phần kiến trúc chi tiết (U-Hierarchy):
|
|
|
|
- **ubit**: Đơn vị logic nhỏ nhất (hàm, type, hằng số)
|
|
- **ubrick**: Tập hợp các `ubit` liên quan
|
|
- **ublock**: Thành phần hoạt động độc lập tương đối
|
|
- **ubundle**: Tính năng hoàn chỉnh cho người dùng
|
|
|
|
## Cấu trúc thư mục
|
|
|
|
```
|
|
├── cmd/ # Entry points
|
|
├── pkg/ # Packages
|
|
│ ├── resource/ # Domain resources (DDD Aggregates)
|
|
│ ├── transaction/ # Business workflows
|
|
│ ├── adapter/ # External system interfaces
|
|
│ ├── helper/ # Utilities
|
|
│ └── uiux/ # User interfaces
|
|
├── config/ # Configuration
|
|
├── docs/ # Documentation
|
|
├── scripts/ # Helper scripts
|
|
└── test/ # Tests
|
|
```
|
|
|
|
## Các lệnh Makefile
|
|
|
|
```bash
|
|
# Xem danh sách lệnh có sẵn
|
|
make help
|
|
|
|
# Khởi tạo dự án
|
|
make init
|
|
|
|
# Chạy môi trường phát triển với Air Tomb
|
|
make dev
|
|
|
|
# Chạy tests
|
|
make test
|
|
|
|
# Kiểm tra linting
|
|
make lint
|
|
|
|
# Build ứng dụng
|
|
make build
|
|
|
|
# Dọn dẹp tệp tạm
|
|
make clean
|
|
|
|
# Docker commands
|
|
make docker-build # Build Docker image
|
|
make docker-run # Run container từ image
|
|
make docker-clean # Dọn dẹp container
|
|
make docker-prune # Dọn dẹp tất cả tài nguyên Docker không sử dụng
|
|
make docker-compose-up # Khởi động môi trường phát triển
|
|
make docker-compose-down # Dừng môi trường phát triển
|
|
make docker-compose-prod-up # Khởi động môi trường production
|
|
make docker-compose-prod-down # Dừng môi trường production
|
|
|
|
# Cấu hình Git
|
|
make setup-git
|
|
```
|
|
|
|
## Quy trình phát triển
|
|
|
|
Dự án sử dụng Trunk-Based Development với các quy ước đặt tên nhánh:
|
|
|
|
- `feat`: Tạo tính năng mới
|
|
- `fix`: Sửa lỗi
|
|
- `docs`: Thay đổi tài liệu
|
|
- `style`: Thay đổi không ảnh hưởng đến logic
|
|
- `refactor`: Refactor code
|
|
- `test`: Thêm hoặc sửa test
|
|
- `chore`: Thay đổi cấu hình hoặc các task không liên quan đến code
|
|
|
|
Xem thêm chi tiết trong [docs/workflow.md](docs/workflow.md).
|
|
|
|
## Tài liệu
|
|
|
|
- [Kiến trúc](docs/architecture.md)
|
|
- [Thông số kỹ thuật](docs/spec.md)
|
|
- [Roadmap](docs/roadmap.md)
|
|
- [Quy trình làm việc](docs/workflow.md)
|
|
- [CI/CD Workflows](docs/workflows.md)
|
|
- [Testing](docs/testing.md)
|
|
- [Adapter](docs/adapter.md)
|
|
- [UX](docs/ux.md)
|
|
- [Changelog](docs/changelog.md)
|
|
|
|
## Đóng góp
|
|
|
|
Xem hướng dẫn đóng góp trong [docs/workflow.md](docs/workflow.md).
|
|
|
|
## Giấy phép
|
|
|
|
Dự án này được phân phối dưới Giấy phép MIT. Xem file `LICENSE` để biết thêm thông tin. |