Đóng góp

Trang này tóm tắt cấu trúc, script và các quy ước của repository fountain. Remote chính thức là GitLab.

Cấu trúc repository

• fountain.go, fountain_init.go, options.go, auxiliary.go — entry point và vòng đời của framework (singleton Fountain, New(), Serving()).
• runnable/ — interface AppInstance, Invoker, JobInstance và các lifecycle primitive.
• core/ — interface CoreController, đăng ký controller và observer pattern cho sự kiện cross-controller.
• clients/ — protocol client: fhttp_client/, fgrpc_client/, ftcp_client/, fudp_client/, fquic_client/.
• libs/ — các thư viện tiện ích (quy ước có tiền tố f*):
  • fnet/ — cài đặt server: fhttp (Fiber), fgrpc, ftcp, fudp, fquic.
  • flog/ — structured logging.
  • stored/ — storage backend: fedis (Redis), fongo, fcql, felastic, fbolt, và các backend khác.
  • cache/ — redis_cache/, memcache/, lfu_cache/, lru_cache/, arc_cache/, v.v.
  • brokers/ — message broker (NATS, Kafka, RabbitMQ, MQTT) và pubsub pipeline.
  • auth_token/, social_auth/, firebase_auth/ — xác thực.
  • sd/ — service discovery (fconsul, fetcd, fregistry, k8s).
  • ftracer/, metrics/, fsentinel/, resilient/ — observability và resilience.
  • base/ — utility package (arr_util, string_util, time_util, dump, fgo worker pool, v.v.).
  • ferr/, fflag/, env/, fcontext/, fsync/, validator/, noti/.
• internal/ — cmd/, encoding/ (dành riêng cho framework).
• constants/ — hằng số toàn cục (tiền tố K, UPPER_SNAKE_CASE).
• dal/ — trừu tượng Data Access Layer.
• proto/ — định nghĩa Protocol Buffer.
• examples/ — ví dụ runnable cho từng component; đây là nơi tốt nhất để tìm usage pattern.
• docs/ — tài liệu kỹ thuật và hướng dẫn migration.
• scripts/ — script build và tooling.

Lệnh & script thông dụng

Thư mục scripts/ chứa các helper build và tooling:

• build.sh — production build với CGO_ENABLED=0 và -ldflags "-s -w" (nén output bằng upx khi có).
• tidy.sh — chạy dos2unix trên scripts/* và go mod tidy.
• download_deps.sh — go mod download và cài đặt dev tool (ví dụ: dlv).
• gosec.sh — chạy security scan gosec (gosec -fmt=json -out=gosec.json, loại trừ testdata và test).
• swag.sh — sinh OpenAPI docs qua swag init và xử lý output thành OpenAPI 3.0.0.
• protoc_install.sh — cài đặt protoc plugin (protoc-gen-go, protoc-gen-go-grpc, protoc-gen-grpc-gateway, protoc-gen-validate).
• pre-commit.sh — cài đặt và cập nhật pre-commit hook.

Không commit local replace directive

build.sh và tidy.sh xóa replace directive khỏi go.mod trước khi chạy. Không commit local replace directive vào go.mod.

Pre-commit hook (gitleaks, gitlint, kiểm tra file lớn/secret) chạy khi commit; không được bỏ qua chúng.

Quy ước

Xem Khái niệm cốt lõi để hiểu nền tảng kiến trúc phía sau các quy ước này.

• Đặt tên package: thư viện có tiền tố f<name>/ (ví dụ: flog, fedis, fhttp, fgrpc); thư mục client là f<protocol>_client/.
• Hằng số: tiền tố K và dạng UPPER_SNAKE_CASE.
• Controller: đặt tên controller.go trong domain package tương ứng.
• Thứ tự import: stdlib → third-party → gitlab.soludian.com/soludian/fountain/... → local.
• Logging: dùng flog (logger := flog.NewFountainLoggerOnce()); không dùng package log của stdlib.
• Xử lý lỗi: dùng các helper wrapping và handling trong libs/ferr/.

Migration storage

libs/stored/fedis_old/ đang được thay thế bởi libs/stored/fedis/. Code mới nên dùng fedis. Xem TODO.md trong repository fountain để biết checklist migration.