Fountain

English

Tiếng Việt

English

Tiếng Việt

Appearance

Import path: gitlab.soludian.com/soludian/fountain

fountain ​

go
import "gitlab.soludian.com/soludian/fountain"

Index ​

Constants ​

go
const (
    KPackageName = "fountain"
    KRoleMain    = "main"
)

func GetRole ​

go
func GetRole() string

GetRole lấy role từ tham số dòng lệnh. Trả về "main" nếu không có tham số hoặc tham số đầu tiên là flag (bắt đầu bằng '-').

Usage:

go run main.go              -> role = "main"
go run main.go main         -> role = "main"
go run main.go worker       -> role = "worker"
go run main.go migrate      -> role = "migrate"
go run main.go --config app -> role = "main" (ignore flag)

func IsRoleMain ​

go
func IsRoleMain() bool

func QuitAppInstance ​

go
func QuitAppInstance()

QuitAppInstance gửi tín hiệu SIGQUIT để dừng ứng dụng Fountain (global function).

Usage:

// Trong goroutine khác hoặc signal handler
fountain.QuitAppInstance()

// Hoặc với timeout
time.AfterFunc(5*time.Second, fountain.QuitAppInstance)

func QuitSignal ​

go
func QuitSignal() <-chan struct{}

QuitSignal trả về channel nhận tín hiệu khi fountain bị dừng. Channel này có thể được lắng nghe bởi nhiều goroutines.

Usage:

quit := fountain.QuitSignal()

go func() {
    <-quit
    fmt.Println("Fountain is shutting down!")
    // Cleanup code here
}()

// Hoặc với select
select {
case <-quit:
    log.Println("Received shutdown signal")
case <-time.After(30*time.Second):
    log.Println("Timeout waiting for shutdown")
}

type Fountain ​

go
type Fountain struct {
    // contains filtered or unexported fields
}

func New ​

go
func New() *Fountain

New tạo và trả về một Fountain instance mới (singleton pattern). Nếu đã có instance thì trả về instance hiện có.

Usage:

f := fountain.New()
f.WithRoleInstance("main", server).Serving()

// Hoặc method chaining:
fountain.New().
    WithRoleInstance("main", server).
    WithRoleJob("migrate", job).
    Serving()

func WAfterStopClean ​

go
func WAfterStopClean(funcs ...runnable.Invoker) *Fountain

WAfterStopClean - Truyền danh sách các invokers sẽ được gọi sau khi Fountain đã dừng hoàn toàn, ví dụ như ghi log hoặc cập nhật trạng thái ứng dụng.

func WAppInstances ​

go
func WAppInstances(appInstances ...runnable.AppInstance) *Fountain

appInstances là một phần của Fountain chứa danh sách các ứng dụng (hoặc service instances) mà ứng dụng Fountain sẽ khởi động và phục vụ. Mỗi instance có thể có logic phục vụ riêng và tương tác với các thành phần khác trong ứng dụng. Quá trình khởi tạo, phục vụ, và dọn dẹp cho từng instance được quản lý trong phương thức Serving, đảm bảo rằng mọi thứ hoạt động một cách mượt mà và có thể khôi phục lỗi khi cần thiết.

Usage:

fountain.New().WAppInstances(mainServer).Serving()

func WArguments ​

go
func WArguments(arguments []string) *Fountain

WArguments passes in arguments

func WAuxiliaryConfigKey ​

go
func WAuxiliaryConfigKey(confKey string) *Fountain

func WAuxiliaryDisable ​

go
func WAuxiliaryDisable(flag ...bool) *Fountain

WAuxiliaryDisable - Cờ AuxiliaryDisable dùng để bật hoặc tắt server phụ trợ trong ứng dụng. Server phụ trợ: Thường là một server nhỏ thực hiện các tác vụ bổ sung hoặc hỗ trợ không phải là chức năng chính của ứng dụng. Ví dụ: Metrics: Thống kê số liệu Governance: Quản lý tài nguyên

Nếu AuxiliaryDisable được bật (true), server phụ trợ sẽ không khởi chạy, giúp giảm tài nguyên hệ thống và giới hạn ứng dụng chỉ thực hiện các chức năng chính. Nếu tắt (false), server phụ trợ sẽ hoạt động như một phần của ứng dụng, phục vụ các chức năng bổ sung.

func WBeforeStopClean ​

go
func WBeforeStopClean(funcs ...runnable.Invoker) *Fountain

WBeforeStopClean - Truyền danh sách các invokers sẽ được gọi trước khi Fountain dừng, phục vụ cho việc dọn dẹp hoặc hoàn tất các công việc cần thiết trước khi tắt ứng dụng.

func WConcurrency ​

go
func WConcurrency(flag ...bool) *Fountain

WConcurrency chỉ tác động tới các Invoker hoặc Job Khi được bật, các invoker/job có thể chạy trong các vòng lặp mà không cần return.

Khi cờ concurrency bật, các thành phần như invokers, jobs, appInstances, và auxiliaryServer sẽ được thực thi song song bằng cách sử dụng các goroutines và sync.WaitGroup. Nếu concurrency tắt, các thành phần này sẽ được chạy tuần tự, tức là một thành phần phải hoàn tất trước khi thành phần kế tiếp được thực thi. Nếu có concurrency mà không có hang, ứng dụng sẽ gọi các invoker/job vào goroutine và không chờ chúng kết thúc -> fountain sẽ kết thức ngay khi gọi xong các invoker/job

Usage:

fountain.WHang().WConcurrency().WJobs(job1, job2).Serving()

func WCreateInstanceFunc ​

go
func WCreateInstanceFunc(fn func() runnable.AppInstance) *Fountain

appInstances là một phần của Fountain chứa danh sách các ứng dụng (hoặc service instances) mà ứng dụng Fountain sẽ khởi động và phục vụ. Mỗi instance có thể có logic phục vụ riêng và tương tác với các thành phần khác trong ứng dụng. Quá trình khởi tạo, phục vụ, và dọn dẹp cho từng instance được quản lý trong phương thức Serving, đảm bảo rằng mọi thứ hoạt động một cách mượt mà và có thể khôi phục lỗi khi cần thiết.

Usage:

fountain.WCreateInstanceFunc(func() runnable.AppInstance {
	server := fgrpc.WithConfigKey("server.fgrpc").InstallFountainInstance()
	hello_world.RegisterGreeterServer(server.Server, &Greeter{server: server})
	return server
}).Serving()

func WCrons ​

go
func WCrons(crons ...runnable.JobInstance) *Fountain

WCrons thường là các tác vụ định kỳ, chạy theo lịch biểu đã định (giống như các cron jobs trong Unix). Đây là các công việc lặp lại theo khoảng thời gian cố định như kiểm tra và làm sạch tài nguyên, đồng bộ hóa dữ liệu, hoặc các tác vụ bảo trì định kỳ.

Crons luôn chạy đồng thời (không bị ảnh hưởng bởi cờ concurrency) và bắt buộc giữ ứng dụng hoạt động (f.hang = true). Điều này giúp các crons có thể liên tục chạy trong nền cho đến khi toàn bộ ứng dụng ngừng hoạt động. Xử lý dừng: Khi nhận tín hiệu dừng, crons cũng được xử lý ngắt tương tự jobs, đảm bảo chúng kết thúc đúng cách.

Usage:

fountain.WCrons(dailyCleanupJob, hourlySyncJob).Serving()

func WDisableBanner ​

go
func WDisableBanner(flag ...bool) *Fountain

WDisableBanner disables the banner

func WGovernance ​

go
func WGovernance(flag ...bool) *Fountain

WGovernance - Cờ Governance cho phép hoặc vô hiệu hóa các cơ chế quản trị, giám sát và kiểm soát ứng dụng.

Governance (Quản trị) là một tập hợp các quy trình và cơ chế giám sát để đảm bảo tính ổn định, bảo mật và hiệu quả hoạt động của ứng dụng. Điều này có thể bao gồm các kiểm tra tuân thủ, giám sát và hạn chế quyền truy cập, thực thi quy tắc an toàn, hoặc quản lý cấu hình ứng dụng.

Nếu Governance được bật (true), các cơ chế quản trị sẽ được áp dụng, có thể bao gồm các giới hạn bảo mật, giám sát truy cập, hoặc áp dụng các chính sách tuân thủ. Nếu tắt (false), các cơ chế quản trị có thể không được thực hiện, giúp ứng dụng đơn giản hơn và ít ràng buộc nhưng có thể thiếu bảo mật hoặc kiểm soát khi cần thiết.

func WHang ​

go
func WHang(flag ...bool) *Fountain

WHang chỉ tác động tới các Invoker hoặc Job Sẽ đợt cho tới khi các Invoker/job hoàn thành xong logic.

Khi cờ hang bật, Fountain sẽ duy trì ứng dụng ở trạng thái chờ, không kết thúc quá trình (os.Exit) ngay sau khi hoàn tất các công việc. Hang thường đi kèm với concurrency để giữ cho ứng dụng chờ cho đến khi nhận được tín hiệu kết thúc từ hệ thống (shutdownSignals). Nếu hang không được bật, Serving sẽ không chờ đợi mà sẽ thoát ngay khi các phần công việc hoàn thành, thích hợp cho các ứng dụng hoặc tác vụ cần xử lý nhanh gọn.

Usage:

fountain.WHang().WConcurrency().WJobs(job1, job2).Serving()

func WInvokers ​

go
func WInvokers(invokers ...runnable.Invoker) *Fountain

Các invokers sẽ được chạy lần lượt theo thứ tự thêm vào. Các invokers sẽ được chạy trước các jobs. Invokers thường là các hàm hoặc tác vụ khởi tạo quan trọng, cần thiết lập hoặc gọi trước khi ứng dụng bắt đầu các nhiệm vụ chính. Chúng có thể thực hiện các bước chuẩn bị như kiểm tra cấu hình, tạo kết nối cơ sở dữ liệu, hoặc khởi tạo tài nguyên.

Usage:

fountain.WInvokers(initDB, setupCache).Serving()

func WJobs ​

go
func WJobs(jobs ...runnable.JobInstance) *Fountain

WJobs sẽ chạy sau các invokers và trước khi thiết lập các cron jobs. Jobs thường là các tác vụ cần thực hiện định kỳ hoặc thường xuyên khi ứng dụng đang chạy. Chúng có thể là các tác vụ nền như cập nhật dữ liệu, ghi log, hoặc gửi báo cáo. Khi ứng dụng nhận tín hiệu dừng, tất cả jobs sẽ được dừng thông qua phương thức Stop().

Khi cờ concurrency bật, các jobs sẽ chạy đồng thời, giúp tăng hiệu suất nếu có nhiều công việc nhỏ cần chạy song song. Khi cờ concurrency tắt, các jobs sẽ được thực hiện tuần tự. Cờ cờ hang (nếu được bật) cho phép jobs tiếp tục chạy nền cho đến khi nhận được tín hiệu dừng từ hệ thống.

Usage:

fountain.WJobs(job1, job2, job3).Serving()

func WMetricsConfigKey ​

go
func WMetricsConfigKey(confKey string) *Fountain

func WMetricsDisable ​

go
func WMetricsDisable(flag ...bool) *Fountain

WMetricsDisable - Cờ MetricsDisable điều chỉnh việc thu thập và báo cáo các chỉ số (metrics) của ứng dụng.

Metrics thường được sử dụng để giám sát hiệu suất ứng dụng như số lượng yêu cầu xử lý, thời gian phản hồi, và mức sử dụng tài nguyên. Các chỉ số này được xuất ra hệ thống giám sát như Prometheus, Grafana, hoặc gửi đến các dịch vụ giám sát bên thứ ba.

Khi MetricsDisable bật (true), ứng dụng sẽ bỏ qua việc thu thập và báo cáo các chỉ số, phù hợp khi không cần giám sát chi tiết hoặc khi muốn giảm tải tài nguyên hệ thống. Khi tắt (false), tính năng thu thập và báo cáo metrics được kích hoạt, giúp đội ngũ vận hành theo dõi và giám sát hiệu suất ứng dụng.

func WRegistrar ​

go
func WRegistrar(registrar fregistry.Registry) *Fountain

WRegistrar - registrar có thể đóng vai trò là dịch vụ đăng ký giúp Fountain quản lý và điều phối các dịch vụ hoặc tài nguyên liên quan.

Hàm registrar.RegisterService sẽ được fountain gọi ngay trước khi instance serving Hàm registrar.UnregisterService sẽ được fountain trước khi thực hiện destroy instance

func WRoleInstance ​

go
func WRoleInstance(role string, instance runnable.AppInstance) *Fountain

WRoleInstance đăng ký một app instance với role/cmd cụ thể, cho phép ứng dụng chạy theo nhiều chế độ khác nhau dựa trên tham số command line. Mỗi role đại diện cho một chế độ hoạt động khác nhau của ứng dụng như "main" (server chính), "worker" (daemon xử lý nền). Khi khởi động, Fountain sẽ đọc tham số đầu tiên từ command line để xác định role và chỉ chạy instance tương ứng. Nếu không truyền role hoặc truyền "main", hệ thống sẽ mặc định chạy với role "main". Quá trình khởi tạo, phục vụ, và dọn dẹp cho instance được quản lý trong phương thức Serving, đảm bảo chỉ instance của role được chọn sẽ được thực thi.

Usage:

fountain.
    WRoleInstance("main", mainServer).
    WRoleInstance("worker", workerDaemon).
    Serving()

func WRoleInvoker ​

go
func WRoleInvoker(role string, invoker runnable.Invoker) *Fountain

WRoleInvoker đăng ký một invoker với role/cmd cụ thể, thích hợp cho các script đơn giản hoặc utility commands. Invoker là function đơn giản trả về error, phù hợp cho các tác vụ nhẹ không cần lifecycle phức tạp. Thích hợp cho các role như "version", "config-check", "health-check", "generate-config".

Usage:

fountain.
    WRoleInvoker("version", func() error {
        fmt.Println("Version 1.0.0")
        return nil
    }).
    WRoleInvoker("config-check", validateConfig).
    Serving()

// Chạy: go run main.go version      -> in version và thoát
// Chạy: go run main.go config-check -> validate config và thoát

func WRoleJob ​

go
func WRoleJob(role string, job runnable.JobInstance) *Fountain

WRoleJob đăng ký một job với role/cmd cụ thể, thích hợp cho các tác vụ một lần như migration, initialization, seeding data. Job sẽ được khởi động bằng phương thức Start() và có thể dừng lại bằng Stop() khi nhận tín hiệu ngắt. Thích hợp cho các role như "migrate", "seed-data", "cleanup", "backup" - các tác vụ chạy một lần rồi kết thúc.

Usage:

fountain.
    WRoleJob("migrate", migrationJob).
    WRoleJob("seed", seedingJob).
    Serving()

// Chạy: go run main.go migrate  -> chạy migrationJob.Start()
// Chạy: go run main.go seed    -> chạy seedingJob.Start()

func WStopForce ​

go
func WStopForce(flag ...bool) *Fountain

WStopForce chỉ tác động tới các Invoker hoặc Job Sẽ kết thúc ngay khi Invoker/job hoàn thành xong logic.

Nếu stopForce không được bật, fountain sẽ tiếp tục xử lý các appInstances, auxiliaryServer, jobs, crons (nếu có) sau khi hoàn thành các invoker/job. stopForce sẽ force ứng dụng kể cả có cờ hang.

Usage:

fountain.WConcurrency().WJobs(job1, job2).WStopForce().Serving()

func WithAfterStopClean ​

go
func WithAfterStopClean(funcs ...runnable.Invoker) *Fountain

Truyền danh sách các invokers sẽ được gọi sau khi Fountain Fountain đã dừng hoàn toàn, ví dụ như ghi log hoặc cập nhật trạng thái ứng dụng.

func WithAppInstances ​

go
func WithAppInstances(appInstances ...runnable.AppInstance) *Fountain

appInstances là một phần của Fountain chứa danh sách các ứng dụng (hoặc service instances) mà ứng dụng Fountain sẽ khởi động và phục vụ. Mỗi instance có thể có logic phục vụ riêng và tương tác với các thành phần khác trong ứng dụng. Quá trình khởi tạo, phục vụ, và dọn dẹp cho từng instance được quản lý trong phương thức Serving, đảm bảo rằng mọi thứ hoạt động một cách mượt mà và có thể khôi phục lỗi khi cần thiết.

Usage:

fountain.WithAppInstances(mainServer).Serving()

func WithArguments ​

go
func WithArguments(arguments []string) *Fountain

WithArguments passes in arguments

func WithAuxiliaryConfigKey ​

go
func WithAuxiliaryConfigKey(confKey string) *Fountain

func WithAuxiliaryDisable ​

go
func WithAuxiliaryDisable(flag ...bool) *Fountain

Cờ AuxiliaryDisable dùng để bật hoặc tắt server phụ trợ trong ứng dụng. Server phụ trợ: Thường là một server nhỏ thực hiện các tác vụ bổ sung hoặc hỗ trợ không phải là chức năng chính của ứng dụng. Ví dụ: Metrics: Thống kê số liệu Governance: Quản lý tài nguyên

Nếu AuxiliaryDisable được bật (true), server phụ trợ sẽ không khởi chạy, giúp giảm tài nguyên hệ thống và giới hạn ứng dụng chỉ thực hiện các chức năng chính. Nếu tắt (false), server phụ trợ sẽ hoạt động như một phần của ứng dụng, phục vụ các chức năng bổ sung.

func WithBeforeStopClean ​

go
func WithBeforeStopClean(funcs ...runnable.Invoker) *Fountain

Truyền danh sách các invokers sẽ được gọi trước khi Fountain dừng, phục vụ cho việc dọn dẹp hoặc hoàn tất các công việc cần thiết trước khi tắt ứng dụng.

func WithConcurrency ​

go
func WithConcurrency(flag ...bool) *Fountain

Chỉ tác động tới các Invoker hoặc Job Khi được bật, các invoker/job có thể chạy trong các vòng lặp mà không cần return.

Khi cờ concurrency bật, các thành phần như invokers, jobs, appInstances, và auxiliaryServer sẽ được thực thi song song bằng cách sử dụng các goroutines và sync.WaitGroup. Nếu concurrency tắt, các thành phần này sẽ được chạy tuần tự, tức là một thành phần phải hoàn tất trước khi thành phần kế tiếp được thực thi. Nếu có concurrency mà không có hang, ứng dụng sẽ gọi các invoker/job vào goroutine và không chờ chúng kết thúc -> fountain sẽ kết thức ngay khi gọi xong các invoker/job

Usage:

fountain.WithHang().WithConcurrency().WithJobs(job1, job2).Serving()

func WithCreateInstanceFunc ​

go
func WithCreateInstanceFunc(fn func() runnable.AppInstance) *Fountain

appInstances là một phần của Fountain chứa danh sách các ứng dụng (hoặc service instances) mà ứng dụng Fountain sẽ khởi động và phục vụ. Mỗi instance có thể có logic phục vụ riêng và tương tác với các thành phần khác trong ứng dụng. Quá trình khởi tạo, phục vụ, và dọn dẹp cho từng instance được quản lý trong phương thức Serving, đảm bảo rằng mọi thứ hoạt động một cách mượt mà và có thể khôi phục lỗi khi cần thiết.

Usage:

fountain.WithCreateInstanceFunc(func() runnable.AppInstance {
	server := fgrpc.WithConfigKey("server.fgrpc").InstallFountainInstance()
	hello_world.RegisterGreeterServer(server.Server, &Greeter{server: server})
	return server
}).Serving()

func WithCrons ​

go
func WithCrons(crons ...runnable.JobInstance) *Fountain

Crons thường là các tác vụ định kỳ, chạy theo lịch biểu đã định (giống như các cron jobs trong Unix). Đây là các công việc lặp lại theo khoảng thời gian cố định như kiểm tra và làm sạch tài nguyên, đồng bộ hóa dữ liệu, hoặc các tác vụ bảo trì định kỳ.

Crons luôn chạy đồng thời (không bị ảnh hưởng bởi cờ concurrency) và bắt buộc giữ ứng dụng hoạt động (f.hang = true). Điều này giúp các crons có thể liên tục chạy trong nền cho đến khi toàn bộ ứng dụng ngừng hoạt động. Xử lý dừng: Khi nhận tín hiệu dừng, crons cũng được xử lý ngắt tương tự jobs, đảm bảo chúng kết thúc đúng cách.

Usage:

fountain.WithCrons(dailyCleanupJob, hourlySyncJob).Serving()

func WithDisableBanner ​

go
func WithDisableBanner(flag ...bool) *Fountain

WithDisableBanner disables the banner

func WithGovernance ​

go
func WithGovernance(flag ...bool) *Fountain

Cờ Governance cho phép hoặc vô hiệu hóa các cơ chế quản trị, giám sát và kiểm soát ứng dụng.

Governance (Quản trị) là một tập hợp các quy trình và cơ chế giám sát để đảm bảo tính ổn định, bảo mật và hiệu quả hoạt động của ứng dụng. Điều này có thể bao gồm các kiểm tra tuân thủ, giám sát và hạn chế quyền truy cập, thực thi quy tắc an toàn, hoặc quản lý cấu hình ứng dụng.

Nếu Governance được bật (true), các cơ chế quản trị sẽ được áp dụng, có thể bao gồm các giới hạn bảo mật, giám sát truy cập, hoặc áp dụng các chính sách tuân thủ. Nếu tắt (false), các cơ chế quản trị có thể không được thực hiện, giúp ứng dụng đơn giản hơn và ít ràng buộc nhưng có thể thiếu bảo mật hoặc kiểm soát khi cần thiết.

func WithHang ​

go
func WithHang(flag ...bool) *Fountain

Chỉ tác động tới các Invoker hoặc Job Sẽ đợt cho tới khi các Invoker/job hoàn thành xong logic.

Khi cờ hang bật, Fountain sẽ duy trì ứng dụng ở trạng thái chờ, không kết thúc quá trình (os.Exit) ngay sau khi hoàn tất các công việc. Hang thường đi kèm với concurrency để giữ cho ứng dụng chờ cho đến khi nhận được tín hiệu kết thúc từ hệ thống (shutdownSignals). Nếu hang không được bật, Serving sẽ không chờ đợi mà sẽ thoát ngay khi các phần công việc hoàn thành, thích hợp cho các ứng dụng hoặc tác vụ cần xử lý nhanh gọn.

Usage:

fountain.WithHang().WithConcurrency().WithJobs(job1, job2).Serving()

func WithInvokers ​

go
func WithInvokers(invokers ...runnable.Invoker) *Fountain

Các invokers sẽ được chạy lần lượt theo thứ tự thêm vào. Các invokers sẽ được chạy trước các jobs. Invokers thường là các hàm hoặc tác vụ khởi tạo quan trọng, cần thiết lập hoặc gọi trước khi ứng dụng bắt đầu các nhiệm vụ chính. Chúng có thể thực hiện các bước chuẩn bị như kiểm tra cấu hình, tạo kết nối cơ sở dữ liệu, hoặc khởi tạo tài nguyên.

Usage:

fountain.WithInvokers(initDB, setupCache).Serving()

func WithJobs ​

go
func WithJobs(jobs ...runnable.JobInstance) *Fountain

Jobs sẽ chạy sau các invokers và trước khi thiết lập các cron jobs. Jobs thường là các tác vụ cần thực hiện định kỳ hoặc thường xuyên khi ứng dụng đang chạy. Chúng có thể là các tác vụ nền như cập nhật dữ liệu, ghi log, hoặc gửi báo cáo. Khi ứng dụng nhận tín hiệu dừng, tất cả jobs sẽ được dừng thông qua phương thức Stop().

Khi cờ concurrency bật, các jobs sẽ chạy đồng thời, giúp tăng hiệu suất nếu có nhiều công việc nhỏ cần chạy song song. Khi cờ concurrency tắt, các jobs sẽ được thực hiện tuần tự. Cờ cờ hang (nếu được bật) cho phép jobs tiếp tục chạy nền cho đến khi nhận được tín hiệu dừng từ hệ thống.

Usage:

fountain.WithJobs(job1, job2, job3).Serving()

func WithMetricsConfigKey ​

go
func WithMetricsConfigKey(confKey string) *Fountain

func WithMetricsDisable ​

go
func WithMetricsDisable(flag ...bool) *Fountain

Cờ MetricsDisable điều chỉnh việc thu thập và báo cáo các chỉ số (metrics) của ứng dụng.

Metrics thường được sử dụng để giám sát hiệu suất ứng dụng như số lượng yêu cầu xử lý, thời gian phản hồi, và mức sử dụng tài nguyên. Các chỉ số này được xuất ra hệ thống giám sát như Prometheus, Grafana, hoặc gửi đến các dịch vụ giám sát bên thứ ba.

Khi MetricsDisable bật (true), ứng dụng sẽ bỏ qua việc thu thập và báo cáo các chỉ số, phù hợp khi không cần giám sát chi tiết hoặc khi muốn giảm tải tài nguyên hệ thống. Khi tắt (false), tính năng thu thập và báo cáo metrics được kích hoạt, giúp đội ngũ vận hành theo dõi và giám sát hiệu suất ứng dụng.

func WithRegistrar ​

go
func WithRegistrar(registrar fregistry.Registry) *Fountain

registrar có thể đóng vai trò là dịch vụ đăng ký giúp Fountain quản lý và điều phối các dịch vụ hoặc tài nguyên liên quan.

Hàm registrar.RegisterService sẽ được fountain gọi ngay trước khi instance serving Hàm registrar.UnregisterService sẽ được fountain trước khi thực hiện destroy instance

func WithRoleInstance ​

go
func WithRoleInstance(role string, instance runnable.AppInstance) *Fountain

WithRoleInstance đăng ký một app instance với role/cmd cụ thể, cho phép ứng dụng chạy theo nhiều chế độ khác nhau dựa trên tham số command line. Mỗi role đại diện cho một chế độ hoạt động khác nhau của ứng dụng như "main" (server chính), "worker" (daemon xử lý nền). Khi khởi động, Fountain sẽ đọc tham số đầu tiên từ command line để xác định role và chỉ chạy instance tương ứng. Nếu không truyền role hoặc truyền "main", hệ thống sẽ mặc định chạy với role "main". Quá trình khởi tạo, phục vụ, và dọn dẹp cho instance được quản lý trong phương thức Serving, đảm bảo chỉ instance của role được chọn sẽ được thực thi.

Usage:

fountain.
    WithRoleInstance("main", mainServer).
    WithRoleInstance("worker", workerDaemon).
    Serving()

func WithRoleInvoker ​

go
func WithRoleInvoker(role string, invoker runnable.Invoker) *Fountain

WithRoleInvoker đăng ký một invoker với role/cmd cụ thể, thích hợp cho các script đơn giản hoặc utility commands. Invoker là function đơn giản trả về error, phù hợp cho các tác vụ nhẹ không cần lifecycle phức tạp. Thích hợp cho các role như "version", "config-check", "health-check", "generate-config".

Usage:

fountain.
    WithRoleInvoker("version", func() error {
        fmt.Println("Version 1.0.0")
        return nil
    }).
    WithRoleInvoker("config-check", validateConfig).
    Serving()

// Chạy: go run main.go version      -> in version và thoát
// Chạy: go run main.go config-check -> validate config và thoát

func WithRoleJob ​

go
func WithRoleJob(role string, job runnable.JobInstance) *Fountain

WithRoleJob đăng ký một job với role/cmd cụ thể, thích hợp cho các tác vụ một lần như migration, initialization, seeding data. Job sẽ được khởi động bằng phương thức Start() và có thể dừng lại bằng Stop() khi nhận tín hiệu ngắt. Thích hợp cho các role như "migrate", "seed-data", "cleanup", "backup" - các tác vụ chạy một lần rồi kết thúc.

Usage:

fountain.
    WithRoleJob("migrate", migrationJob).
    WithRoleJob("seed", seedingJob).
    Serving()

// Chạy: go run main.go migrate  -> chạy migrationJob.Start()
// Chạy: go run main.go seed    -> chạy seedingJob.Start()

func WithStopForce ​

go
func WithStopForce(flag ...bool) *Fountain

Chỉ tác động tới các Invoker hoặc Job Sẽ kết thúc ngay khi Invoker/job hoàn thành xong logic.

Nếu stopForce không được bật, fountain sẽ tiếp tục xử lý các appInstances, auxiliaryServer, jobs, crons (nếu có) sau khi hoàn thành các invoker/job. stopForce sẽ force ứng dụng kể cả có cờ hang.

Usage:

fountain.WithConcurrency().WithJobs(job1, job2).WithStopForce().Serving()

func (*Fountain) QuitAppInstance ​

go
func (f *Fountain) QuitAppInstance()

QuitAppInstance gửi tín hiệu SIGQUIT để dừng ứng dụng Fountain (method).

Usage:

f := fountain.New()
go func() {
    time.Sleep(10 * time.Second)
    f.QuitAppInstance() // Tự động thoát sau 10s
}()
f.Serving()

func (*Fountain) Serving ​

go
func (f *Fountain) Serving()

Thứ tự khởi chạy: Invoker: Nếu có các invokers, chúng sẽ được gọi đầu tiên. Các hàm invoker được thực thi đồng thời khi concurrency bật, ngược lại chúng sẽ thực hiện tuần tự. Jobs: Các jobs sẽ được thực thi kế tiếp. Tương tự như invokers, chúng sẽ được thực thi song song nếu concurrency bật. Crons: Các crons sẽ chạy tiếp theo. Khi có crons, cả hai cờ concurrency và hang sẽ tự động bật, đảm bảo chúng chạy song song và giữ cho ứng dụng hoạt động. App Instances: Nếu có appInstances, các instance sẽ được khởi tạo và Serving. Ở đây, concurrency và hang được kích hoạt để đảm bảo chúng có thể chạy song song và giữ ứng dụng hoạt động liên tục. Auxiliary Server: Nếu hang được bật, auxiliaryServer sẽ khởi chạy và giữ ứng dụng hoạt động cho đến khi nhận tín hiệu thoát (shutdownSignals).

Khi cờ concurrency bật, các thành phần như invokers, jobs, appInstances, và auxiliaryServer sẽ được thực thi song song bằng cách sử dụng các goroutines và sync.WaitGroup. Nếu concurrency tắt, các thành phần này sẽ được chạy tuần tự, tức là một thành phần phải hoàn tất trước khi thành phần kế tiếp được thực thi.

Khi cờ hang bật, Fountain sẽ duy trì ứng dụng ở trạng thái chờ, không kết thúc quá trình (os.Exit) ngay sau khi hoàn tất các công việc. Hang thường đi kèm với concurrency để giữ cho ứng dụng chờ cho đến khi nhận được tín hiệu kết thúc từ hệ thống (shutdownSignals). Nếu hang không được bật, Serving sẽ không chờ đợi mà sẽ thoát ngay khi các phần công việc hoàn thành, thích hợp cho các ứng dụng hoặc tác vụ cần xử lý nhanh gọn.

func (*Fountain) WAfterStopClean ​

go
func (f *Fountain) WAfterStopClean(funcs ...runnable.Invoker) *Fountain

WAfterStopClean - Truyền danh sách các invokers sẽ được gọi sau khi Fountain đã dừng hoàn toàn, ví dụ như ghi log hoặc cập nhật trạng thái ứng dụng.

func (*Fountain) WAppInstances ​

go
func (f *Fountain) WAppInstances(appInstances ...runnable.AppInstance) *Fountain

appInstances là một phần của Fountain chứa danh sách các ứng dụng (hoặc service instances) mà ứng dụng Fountain sẽ khởi động và phục vụ. Mỗi instance có thể có logic phục vụ riêng và tương tác với các thành phần khác trong ứng dụng. Quá trình khởi tạo, phục vụ, và dọn dẹp cho từng instance được quản lý trong phương thức Serving, đảm bảo rằng mọi thứ hoạt động một cách mượt mà và có thể khôi phục lỗi khi cần thiết.

Usage:

fountain.New().WAppInstances(mainServer).Serving()

func (*Fountain) WArguments ​

go
func (f *Fountain) WArguments(arguments []string) *Fountain

WArguments passes in arguments

func (*Fountain) WAuxiliaryConfigKey ​

go
func (f *Fountain) WAuxiliaryConfigKey(confKey string) *Fountain

func (*Fountain) WAuxiliaryDisable ​

go
func (f *Fountain) WAuxiliaryDisable(flag ...bool) *Fountain

WAuxiliaryDisable - Cờ AuxiliaryDisable dùng để bật hoặc tắt server phụ trợ trong ứng dụng. Server phụ trợ: Thường là một server nhỏ thực hiện các tác vụ bổ sung hoặc hỗ trợ không phải là chức năng chính của ứng dụng. Ví dụ: Metrics: Thống kê số liệu Governance: Quản lý tài nguyên

Nếu AuxiliaryDisable được bật (true), server phụ trợ sẽ không khởi chạy, giúp giảm tài nguyên hệ thống và giới hạn ứng dụng chỉ thực hiện các chức năng chính. Nếu tắt (false), server phụ trợ sẽ hoạt động như một phần của ứng dụng, phục vụ các chức năng bổ sung.

func (*Fountain) WBeforeStopClean ​

go
func (f *Fountain) WBeforeStopClean(funcs ...runnable.Invoker) *Fountain

WBeforeStopClean - Truyền danh sách các invokers sẽ được gọi trước khi Fountain dừng, phục vụ cho việc dọn dẹp hoặc hoàn tất các công việc cần thiết trước khi tắt ứng dụng.

func (*Fountain) WConcurrency ​

go
func (f *Fountain) WConcurrency(flag ...bool) *Fountain

WConcurrency chỉ tác động tới các Invoker hoặc Job Khi được bật, các invoker/job có thể chạy trong các vòng lặp mà không cần return.

Khi cờ concurrency bật, các thành phần như invokers, jobs, appInstances, và auxiliaryServer sẽ được thực thi song song bằng cách sử dụng các goroutines và sync.WaitGroup. Nếu concurrency tắt, các thành phần này sẽ được chạy tuần tự, tức là một thành phần phải hoàn tất trước khi thành phần kế tiếp được thực thi. Nếu có concurrency mà không có hang, ứng dụng sẽ gọi các invoker/job vào goroutine và không chờ chúng kết thúc -> fountain sẽ kết thức ngay khi gọi xong các invoker/job

Usage:

fountain.New().WHang().WConcurrency().WJobs(job1, job2).Serving()

func (*Fountain) WCreateInstanceFunc ​

go
func (f *Fountain) WCreateInstanceFunc(fn func() runnable.AppInstance) *Fountain

appInstances là một phần của Fountain chứa danh sách các ứng dụng (hoặc service instances) mà ứng dụng Fountain sẽ khởi động và phục vụ. Mỗi instance có thể có logic phục vụ riêng và tương tác với các thành phần khác trong ứng dụng. Quá trình khởi tạo, phục vụ, và dọn dẹp cho từng instance được quản lý trong phương thức Serving, đảm bảo rằng mọi thứ hoạt động một cách mượt mà và có thể khôi phục lỗi khi cần thiết.

Usage:

fountain.New().WCreateInstanceFunc(func() runnable.AppInstance {
	server := fgrpc.WithConfigKey("server.fgrpc").InstallFountainInstance()
	hello_world.RegisterGreeterServer(server.Server, &Greeter{server: server})
	return server
}).Serving()

func (*Fountain) WCrons ​

go
func (f *Fountain) WCrons(crons ...runnable.JobInstance) *Fountain

WCrons thường là các tác vụ định kỳ, chạy theo lịch biểu đã định (giống như các cron jobs trong Unix). Đây là các công việc lặp lại theo khoảng thời gian cố định như kiểm tra và làm sạch tài nguyên, đồng bộ hóa dữ liệu, hoặc các tác vụ bảo trì định kỳ.

Crons luôn chạy đồng thời (không bị ảnh hưởng bởi cờ concurrency) và bắt buộc giữ ứng dụng hoạt động (f.hang = true). Điều này giúp các crons có thể liên tục chạy trong nền cho đến khi toàn bộ ứng dụng ngừng hoạt động. Xử lý dừng: Khi nhận tín hiệu dừng, crons cũng được xử lý ngắt tương tự jobs, đảm bảo chúng kết thúc đúng cách.

Usage:

fountain.New().WCrons(dailyCleanupJob, hourlySyncJob).Serving()

func (*Fountain) WDisableBanner ​

go
func (f *Fountain) WDisableBanner(flag ...bool) *Fountain

WDisableBanner disables the banner

func (*Fountain) WGovernance ​

go
func (f *Fountain) WGovernance(flag ...bool) *Fountain

WGovernance - Cờ Governance cho phép hoặc vô hiệu hóa các cơ chế quản trị, giám sát và kiểm soát ứng dụng.

Governance (Quản trị) là một tập hợp các quy trình và cơ chế giám sát để đảm bảo tính ổn định, bảo mật và hiệu quả hoạt động của ứng dụng. Điều này có thể bao gồm các kiểm tra tuân thủ, giám sát và hạn chế quyền truy cập, thực thi quy tắc an toàn, hoặc quản lý cấu hình ứng dụng.

Nếu Governance được bật (true), các cơ chế quản trị sẽ được áp dụng, có thể bao gồm các giới hạn bảo mật, giám sát truy cập, hoặc áp dụng các chính sách tuân thủ. Nếu tắt (false), các cơ chế quản trị có thể không được thực hiện, giúp ứng dụng đơn giản hơn và ít ràng buộc nhưng có thể thiếu bảo mật hoặc kiểm soát khi cần thiết.

func (*Fountain) WHang ​

go
func (f *Fountain) WHang(flag ...bool) *Fountain

WHang chỉ tác động tới các Invoker hoặc Job Sẽ đợt cho tới khi các Invoker/job hoàn thành xong logic.

Khi cờ hang bật, Fountain sẽ duy trì ứng dụng ở trạng thái chờ, không kết thúc quá trình (os.Exit) ngay sau khi hoàn tất các công việc. Hang thường đi kèm với concurrency để giữ cho ứng dụng chờ cho đến khi nhận được tín hiệu kết thúc từ hệ thống (shutdownSignals). Nếu hang không được bật, Serving sẽ không chờ đợi mà sẽ thoát ngay khi các phần công việc hoàn thành, thích hợp cho các ứng dụng hoặc tác vụ cần xử lý nhanh gọn.

Usage:

fountain.New().WHang().WConcurrency().WJobs(job1, job2).Serving()

func (*Fountain) WInvokers ​

go
func (f *Fountain) WInvokers(invokers ...runnable.Invoker) *Fountain

Các invokers sẽ được chạy lần lượt theo thứ tự thêm vào. Các invokers sẽ được chạy trước các jobs. Invokers thường là các hàm hoặc tác vụ khởi tạo quan trọng, cần thiết lập hoặc gọi trước khi ứng dụng bắt đầu các nhiệm vụ chính. Chúng có thể thực hiện các bước chuẩn bị như kiểm tra cấu hình, tạo kết nối cơ sở dữ liệu, hoặc khởi tạo tài nguyên.

Usage:

fountain.New().WInvokers(initDB, setupCache).Serving()

func (*Fountain) WJobs ​

go
func (f *Fountain) WJobs(jobs ...runnable.JobInstance) *Fountain

Jobs sẽ chạy sau các invokers và trước khi thiết lập các cron jobs. Jobs thường là các tác vụ cần thực hiện định kỳ hoặc thường xuyên khi ứng dụng đang chạy. Chúng có thể là các tác vụ nền như cập nhật dữ liệu, ghi log, hoặc gửi báo cáo. Khi ứng dụng nhận tín hiệu dừng, tất cả jobs sẽ được dừng thông qua phương thức Stop().

Khi cờ concurrency bật, các jobs sẽ chạy đồng thời, giúp tăng hiệu suất nếu có nhiều công việc nhỏ cần chạy song song. Khi cờ concurrency tắt, các jobs sẽ được thực hiện tuần tự. Cờ cờ hang (nếu được bật) cho phép jobs tiếp tục chạy nền cho đến khi nhận được tín hiệu dừng từ hệ thống.

Usage:

fountain.New().WJobs(job1, job2, job3).Serving()

func (*Fountain) WMetricsConfigKey ​

go
func (f *Fountain) WMetricsConfigKey(confKey string) *Fountain

func (*Fountain) WMetricsDisable ​

go
func (f *Fountain) WMetricsDisable(flag ...bool) *Fountain

WMetricsDisable - Cờ MetricsDisable điều chỉnh việc thu thập và báo cáo các chỉ số (metrics) của ứng dụng.

Metrics thường được sử dụng để giám sát hiệu suất ứng dụng như số lượng yêu cầu xử lý, thời gian phản hồi, và mức sử dụng tài nguyên. Các chỉ số này được xuất ra hệ thống giám sát như Prometheus, Grafana, hoặc gửi đến các dịch vụ giám sát bên thứ ba.

Khi MetricsDisable bật (true), ứng dụng sẽ bỏ qua việc thu thập và báo cáo các chỉ số, phù hợp khi không cần giám sát chi tiết hoặc khi muốn giảm tải tài nguyên hệ thống. Khi tắt (false), tính năng thu thập và báo cáo metrics được kích hoạt, giúp đội ngũ vận hành theo dõi và giám sát hiệu suất ứng dụng.

func (*Fountain) WRegistrar ​

go
func (f *Fountain) WRegistrar(registrar fregistry.Registry) *Fountain

WRegistrar - registrar có thể đóng vai trò là dịch vụ đăng ký giúp Fountain quản lý và điều phối các dịch vụ hoặc tài nguyên liên quan.

Hàm registrar.RegisterService sẽ được fountain gọi ngay trước khi instance serving Hàm registrar.UnregisterService sẽ được fountain trước khi thực hiện destroy instance

func (*Fountain) WRoleInstance ​

go
func (f *Fountain) WRoleInstance(role string, instance runnable.AppInstance) *Fountain

WRoleInstance đăng ký một app instance với role/cmd cụ thể, cho phép ứng dụng chạy theo nhiều chế độ khác nhau dựa trên tham số command line. Mỗi role đại diện cho một chế độ hoạt động khác nhau của ứng dụng như "main" (server chính), "worker" (daemon xử lý nền). Khi khởi động, Fountain sẽ đọc tham số đầu tiên từ command line để xác định role và chỉ chạy instance tương ứng. Nếu không truyền role hoặc truyền "main", hệ thống sẽ mặc định chạy với role "main". Quá trình khởi tạo, phục vụ, và dọn dẹp cho instance được quản lý trong phương thức Serving, đảm bảo chỉ instance của role được chọn sẽ được thực thi.

Usage:

fountain.New().
    WRoleInstance("main", mainServer).
    WRoleInstance("worker", workerDaemon).
    Serving()

// Chạy: go run main.go main    -> chạy mainServer
// Chạy: go run main.go worker  -> chạy workerDaemon

func (*Fountain) WRoleInvoker ​

go
func (f *Fountain) WRoleInvoker(role string, invoker runnable.Invoker) *Fountain

WRoleInvoker đăng ký một invoker với role/cmd cụ thể, thích hợp cho các script đơn giản hoặc utility commands. Invoker là function đơn giản trả về error, phù hợp cho các tác vụ nhẹ không cần lifecycle phức tạp. Thích hợp cho các role như "version", "config-check", "health-check", "generate-config".

Usage:

fountain.New().
    WRoleInvoker("version", func() error {
        fmt.Println("Version 1.0.0")
        return nil
    }).
    WRoleInvoker("config-check", validateConfig).
    Serving()

// Chạy: go run main.go version      -> in version và thoát
// Chạy: go run main.go config-check -> validate config và thoát

func (*Fountain) WRoleJob ​

go
func (f *Fountain) WRoleJob(role string, job runnable.JobInstance) *Fountain

WRoleJob đăng ký một job với role/cmd cụ thể, thích hợp cho các tác vụ một lần như migration, initialization, seeding data. Job sẽ được khởi động bằng phương thức Start() và có thể dừng lại bằng Stop() khi nhận tín hiệu ngắt. Thích hợp cho các role như "migrate", "seed-data", "cleanup", "backup" - các tác vụ chạy một lần rồi kết thúc.

Usage:

fountain.New().
    WRoleJob("migrate", migrationJob).
    WRoleJob("seed", seedingJob).
    Serving()

// Chạy: go run main.go migrate  -> chạy migrationJob.Start()
// Chạy: go run main.go seed    -> chạy seedingJob.Start()

func (*Fountain) WStopForce ​

go
func (f *Fountain) WStopForce(flag ...bool) *Fountain

WStopForce chỉ tác động tới các Invoker hoặc Job Sẽ kết thúc ngay khi Invoker/job hoàn thành xong logic.

Nếu stopForce không được bật, fountain sẽ tiếp tục xử lý các appInstances, auxiliaryServer, jobs, crons (nếu có) sau khi hoàn thành các invoker/job. stopForce sẽ force ứng dụng kể cả có cờ hang.

Usage:

fountain.New().WConcurrency().WJobs(job1, job2).WStopForce().Serving()

func (*Fountain) WithAfterStopClean ​

go
func (f *Fountain) WithAfterStopClean(funcs ...runnable.Invoker) *Fountain

Truyền danh sách các invokers sẽ được gọi sau khi Fountain đã dừng hoàn toàn, ví dụ như ghi log hoặc cập nhật trạng thái ứng dụng.

func (*Fountain) WithAppInstances ​

go
func (f *Fountain) WithAppInstances(appInstances ...runnable.AppInstance) *Fountain

appInstances là một phần của Fountain chứa danh sách các ứng dụng (hoặc service instances) mà ứng dụng Fountain sẽ khởi động và phục vụ. Mỗi instance có thể có logic phục vụ riêng và tương tác với các thành phần khác trong ứng dụng. Quá trình khởi tạo, phục vụ, và dọn dẹp cho từng instance được quản lý trong phương thức Serving, đảm bảo rằng mọi thứ hoạt động một cách mượt mà và có thể khôi phục lỗi khi cần thiết.

Usage:

fountain.New().WithAppInstances(mainServer).Serving()

func (*Fountain) WithArguments ​

go
func (f *Fountain) WithArguments(arguments []string) *Fountain

WithArguments passes in arguments

func (*Fountain) WithAuxiliaryConfigKey ​

go
func (f *Fountain) WithAuxiliaryConfigKey(confKey string) *Fountain

func (*Fountain) WithAuxiliaryDisable ​

go
func (f *Fountain) WithAuxiliaryDisable(flag ...bool) *Fountain

Cờ AuxiliaryDisable dùng để bật hoặc tắt server phụ trợ trong ứng dụng. Server phụ trợ: Thường là một server nhỏ thực hiện các tác vụ bổ sung hoặc hỗ trợ không phải là chức năng chính của ứng dụng. Ví dụ: Metrics: Thống kê số liệu Governance: Quản lý tài nguyên

Nếu AuxiliaryDisable được bật (true), server phụ trợ sẽ không khởi chạy, giúp giảm tài nguyên hệ thống và giới hạn ứng dụng chỉ thực hiện các chức năng chính. Nếu tắt (false), server phụ trợ sẽ hoạt động như một phần của ứng dụng, phục vụ các chức năng bổ sung.

func (*Fountain) WithBeforeStopClean ​

go
func (f *Fountain) WithBeforeStopClean(funcs ...runnable.Invoker) *Fountain

Truyền danh sách các invokers sẽ được gọi trước khi Fountain dừng, phục vụ cho việc dọn dẹp hoặc hoàn tất các công việc cần thiết trước khi tắt ứng dụng.

func (*Fountain) WithConcurrency ​

go
func (f *Fountain) WithConcurrency(flag ...bool) *Fountain

Chỉ tác động tới các Invoker hoặc Job Khi được bật, các invoker/job có thể chạy trong các vòng lặp mà không cần return.

Khi cờ concurrency bật, các thành phần như invokers, jobs, appInstances, và auxiliaryServer sẽ được thực thi song song bằng cách sử dụng các goroutines và sync.WaitGroup. Nếu concurrency tắt, các thành phần này sẽ được chạy tuần tự, tức là một thành phần phải hoàn tất trước khi thành phần kế tiếp được thực thi. Nếu có concurrency mà không có hang, ứng dụng sẽ gọi các invoker/job vào goroutine và không chờ chúng kết thúc -> fountain sẽ kết thức ngay khi gọi xong các invoker/job

Usage:

fountain.New().WithHang().WithConcurrency().WithJobs(job1, job2).Serving()

func (*Fountain) WithCreateInstanceFunc ​

go
func (f *Fountain) WithCreateInstanceFunc(fn func() runnable.AppInstance) *Fountain

appInstances là một phần của Fountain chứa danh sách các ứng dụng (hoặc service instances) mà ứng dụng Fountain sẽ khởi động và phục vụ. Mỗi instance có thể có logic phục vụ riêng và tương tác với các thành phần khác trong ứng dụng. Quá trình khởi tạo, phục vụ, và dọn dẹp cho từng instance được quản lý trong phương thức Serving, đảm bảo rằng mọi thứ hoạt động một cách mượt mà và có thể khôi phục lỗi khi cần thiết.

Usage:

fountain.New().WithCreateInstanceFunc(func() runnable.AppInstance {
	server := fgrpc.WithConfigKey("server.fgrpc").InstallFountainInstance()
	hello_world.RegisterGreeterServer(server.Server, &Greeter{server: server})
	return server
}).Serving()

func (*Fountain) WithCrons ​

go
func (f *Fountain) WithCrons(crons ...runnable.JobInstance) *Fountain

Crons thường là các tác vụ định kỳ, chạy theo lịch biểu đã định (giống như các cron jobs trong Unix). Đây là các công việc lặp lại theo khoảng thời gian cố định như kiểm tra và làm sạch tài nguyên, đồng bộ hóa dữ liệu, hoặc các tác vụ bảo trì định kỳ.

Crons luôn chạy đồng thời (không bị ảnh hưởng bởi cờ concurrency) và bắt buộc giữ ứng dụng hoạt động (f.hang = true). Điều này giúp các crons có thể liên tục chạy trong nền cho đến khi toàn bộ ứng dụng ngừng hoạt động. Xử lý dừng: Khi nhận tín hiệu dừng, crons cũng được xử lý ngắt tương tự jobs, đảm bảo chúng kết thúc đúng cách.

Usage:

fountain.New().WithCrons(dailyCleanupJob, hourlySyncJob).Serving()

func (*Fountain) WithDisableBanner ​

go
func (f *Fountain) WithDisableBanner(flag ...bool) *Fountain

WithDisableBanner disables the banner

func (*Fountain) WithGovernance ​

go
func (f *Fountain) WithGovernance(flag ...bool) *Fountain

Cờ Governance cho phép hoặc vô hiệu hóa các cơ chế quản trị, giám sát và kiểm soát ứng dụng.

Governance (Quản trị) là một tập hợp các quy trình và cơ chế giám sát để đảm bảo tính ổn định, bảo mật và hiệu quả hoạt động của ứng dụng. Điều này có thể bao gồm các kiểm tra tuân thủ, giám sát và hạn chế quyền truy cập, thực thi quy tắc an toàn, hoặc quản lý cấu hình ứng dụng.

Nếu Governance được bật (true), các cơ chế quản trị sẽ được áp dụng, có thể bao gồm các giới hạn bảo mật, giám sát truy cập, hoặc áp dụng các chính sách tuân thủ. Nếu tắt (false), các cơ chế quản trị có thể không được thực hiện, giúp ứng dụng đơn giản hơn và ít ràng buộc nhưng có thể thiếu bảo mật hoặc kiểm soát khi cần thiết.

func (*Fountain) WithHang ​

go
func (f *Fountain) WithHang(flag ...bool) *Fountain

Chỉ tác động tới các Invoker hoặc Job Sẽ đợt cho tới khi các Invoker/job hoàn thành xong logic.

Khi cờ hang bật, Fountain sẽ duy trì ứng dụng ở trạng thái chờ, không kết thúc quá trình (os.Exit) ngay sau khi hoàn tất các công việc. Hang thường đi kèm với concurrency để giữ cho ứng dụng chờ cho đến khi nhận được tín hiệu kết thúc từ hệ thống (shutdownSignals). Nếu hang không được bật, Serving sẽ không chờ đợi mà sẽ thoát ngay khi các phần công việc hoàn thành, thích hợp cho các ứng dụng hoặc tác vụ cần xử lý nhanh gọn.

Usage:

fountain.New().WithHang().WithConcurrency().WithJobs(job1, job2).Serving()

func (*Fountain) WithInvokers ​

go
func (f *Fountain) WithInvokers(invokers ...runnable.Invoker) *Fountain

Các invokers sẽ được chạy lần lượt theo thứ tự thêm vào. Các invokers sẽ được chạy trước các jobs. Invokers thường là các hàm hoặc tác vụ khởi tạo quan trọng, cần thiết lập hoặc gọi trước khi ứng dụng bắt đầu các nhiệm vụ chính. Chúng có thể thực hiện các bước chuẩn bị như kiểm tra cấu hình, tạo kết nối cơ sở dữ liệu, hoặc khởi tạo tài nguyên.

Usage:

fountain.New().WithInvokers(initDB, setupCache).Serving()

func (*Fountain) WithJobs ​

go
func (f *Fountain) WithJobs(jobs ...runnable.JobInstance) *Fountain

Jobs sẽ chạy sau các invokers và trước khi thiết lập các cron jobs. Jobs thường là các tác vụ cần thực hiện định kỳ hoặc thường xuyên khi ứng dụng đang chạy. Chúng có thể là các tác vụ nền như cập nhật dữ liệu, ghi log, hoặc gửi báo cáo. Khi ứng dụng nhận tín hiệu dừng, tất cả jobs sẽ được dừng thông qua phương thức Stop().

Khi cờ concurrency bật, các jobs sẽ chạy đồng thời, giúp tăng hiệu suất nếu có nhiều công việc nhỏ cần chạy song song. Khi cờ concurrency tắt, các jobs sẽ được thực hiện tuần tự. Cờ cờ hang (nếu được bật) cho phép jobs tiếp tục chạy nền cho đến khi nhận được tín hiệu dừng từ hệ thống.

Usage:

fountain.New().WithJobs(job1, job2, job3).Serving()

func (*Fountain) WithMetricsConfigKey ​

go
func (f *Fountain) WithMetricsConfigKey(confKey string) *Fountain

func (*Fountain) WithMetricsDisable ​

go
func (f *Fountain) WithMetricsDisable(flag ...bool) *Fountain

Cờ MetricsDisable điều chỉnh việc thu thập và báo cáo các chỉ số (metrics) của ứng dụng.

Metrics thường được sử dụng để giám sát hiệu suất ứng dụng như số lượng yêu cầu xử lý, thời gian phản hồi, và mức sử dụng tài nguyên. Các chỉ số này được xuất ra hệ thống giám sát như Prometheus, Grafana, hoặc gửi đến các dịch vụ giám sát bên thứ ba.

Khi MetricsDisable bật (true), ứng dụng sẽ bỏ qua việc thu thập và báo cáo các chỉ số, phù hợp khi không cần giám sát chi tiết hoặc khi muốn giảm tải tài nguyên hệ thống. Khi tắt (false), tính năng thu thập và báo cáo metrics được kích hoạt, giúp đội ngũ vận hành theo dõi và giám sát hiệu suất ứng dụng.

func (*Fountain) WithRegistrar ​

go
func (f *Fountain) WithRegistrar(registrar fregistry.Registry) *Fountain

registrar có thể đóng vai trò là dịch vụ đăng ký giúp Fountain quản lý và điều phối các dịch vụ hoặc tài nguyên liên quan.

Hàm registrar.RegisterService sẽ được fountain gọi ngay trước khi instance serving Hàm registrar.UnregisterService sẽ được fountain trước khi thực hiện destroy instance

func (*Fountain) WithRoleInstance ​

go
func (f *Fountain) WithRoleInstance(role string, instance runnable.AppInstance) *Fountain

WithRoleInstance đăng ký một app instance với role/cmd cụ thể, cho phép ứng dụng chạy theo nhiều chế độ khác nhau dựa trên tham số command line. Mỗi role đại diện cho một chế độ hoạt động khác nhau của ứng dụng như "main" (server chính), "worker" (daemon xử lý nền). Khi khởi động, Fountain sẽ đọc tham số đầu tiên từ command line để xác định role và chỉ chạy instance tương ứng. Nếu không truyền role hoặc truyền "main", hệ thống sẽ mặc định chạy với role "main". Quá trình khởi tạo, phục vụ, và dọn dẹp cho instance được quản lý trong phương thức Serving, đảm bảo chỉ instance của role được chọn sẽ được thực thi.

Usage:

fountain.New().
    WithRoleInstance("main", mainServer).
    WithRoleInstance("worker", workerDaemon).
    Serving()

// Chạy: go run main.go main    -> chạy mainServer
// Chạy: go run main.go worker  -> chạy workerDaemon

func (*Fountain) WithRoleInvoker ​

go
func (f *Fountain) WithRoleInvoker(role string, invoker runnable.Invoker) *Fountain

WithRoleInvoker đăng ký một invoker với role/cmd cụ thể, thích hợp cho các script đơn giản hoặc utility commands. Invoker là function đơn giản trả về error, phù hợp cho các tác vụ nhẹ không cần lifecycle phức tạp. Thích hợp cho các role như "version", "config-check", "health-check", "generate-config".

Usage:

fountain.New().
    WithRoleInvoker("version", func() error {
        fmt.Println("Version 1.0.0")
        return nil
    }).
    WithRoleInvoker("config-check", validateConfig).
    Serving()

// Chạy: go run main.go version      -> in version và thoát
// Chạy: go run main.go config-check -> validate config và thoát

func (*Fountain) WithRoleJob ​

go
func (f *Fountain) WithRoleJob(role string, job runnable.JobInstance) *Fountain

WithRoleJob đăng ký một job với role/cmd cụ thể, thích hợp cho các tác vụ một lần như migration, initialization, seeding data. Job sẽ được khởi động bằng phương thức Start() và có thể dừng lại bằng Stop() khi nhận tín hiệu ngắt. Thích hợp cho các role như "migrate", "seed-data", "cleanup", "backup" - các tác vụ chạy một lần rồi kết thúc.

Usage:

fountain.New().
    WithRoleJob("migrate", migrationJob).
    WithRoleJob("seed", seedingJob).
    Serving()

// Chạy: go run main.go migrate  -> chạy migrationJob.Start()
// Chạy: go run main.go seed    -> chạy seedingJob.Start()

func (*Fountain) WithStopForce ​

go
func (f *Fountain) WithStopForce(flag ...bool) *Fountain

Chỉ tác động tới các Invoker hoặc Job Sẽ kết thúc ngay khi Invoker/job hoàn thành xong logic.

Nếu stopForce không được bật, fountain sẽ tiếp tục xử lý các appInstances, auxiliaryServer, jobs, crons (nếu có) sau khi hoàn thành các invoker/job. stopForce sẽ force ứng dụng kể cả có cờ hang.

Usage:

fountain.New().WithConcurrency().WithJobs(job1, job2).WithStopForce().Serving()

Generated by gomarkdoc