Xây dựng Service Fountain

Một service Fountain là một microservice chạy được, được tạo khung và kiểm tra dựa trên một tập quy ước cố định. Những quy ước này không chỉ là code style — chúng được kiểm tra tự động bởi ftkit verify, công cụ duyệt toàn bộ repository và báo mọi sai lệch dưới dạng cảnh báo hoặc lỗi. Xây dựng "đúng chuẩn Fountain" nghĩa là tổ chức code sao cho quá trình kiểm tra này vượt qua.

"Chuẩn Fountain" nghĩa là gì

Một service đạt chuẩn tuân theo kiến trúc phân tầng với cấu trúc thư mục cố định. ftkit verify thực thi điều này: nó kiểm tra các thư mục bắt buộc có tồn tại không, main.go và server/server.go có theo đúng pattern bootstrap và lifecycle không, các controller có tự đăng ký đúng cách không, các handler và DAO có tuân thủ quy tắc về vị trí và đặt tên không, và toàn bộ codebase có dùng flog để ghi log không. Một repo không vượt qua kiểm tra, theo định nghĩa, không phải là một service chuẩn Fountain.

Các thư mục bắt buộc là server, biz, biz/core và biz/dal. Tất cả những thứ còn lại (biz/dal/dao, biz/dal/models, biz/dal/do, pkg, cmd, docs, scripts, …) là tùy chọn và chỉ được kiểm tra khi có mặt.

Các tầng

Một service Fountain được tổ chức thành các tầng, mỗi tầng có một trách nhiệm duy nhất, nối với nhau từ điểm khởi đầu xuống tới tầng lưu trữ:

main.go  →  server/  →  biz/core/  →  biz/dal/  →  pkg/  →  <service>_client/
            (servers)   (controllers)  (dao,        (package  (thư viện
                                         models, do)  dùng chung) client)

• main.go — điểm khởi đầu. Nó bootstrap framework bằng fountain.WithAppInstances(...) (hoặc fountain.New()), khởi tạo server qua server.NewServer(), và chạy nó bằng .Serving().
• server/ — tầng transport và lifecycle. Nó định nghĩa struct server, hàm khởi tạo NewServer(), các phương thức lifecycle (Initialize, Serving, Destroy, Info), việc nối route (server/route.go), và các handler HTTP/gRPC chuyển request thành lời gọi controller. Nó blank-import _ ".../biz" để tầng nghiệp vụ tự đăng ký.
• biz/core/ — các controller, mỗi domain nghiệp vụ một package. Mỗi controller triển khai core.CoreController (InstallController(), RegisterCallback(...)), tự đăng ký bằng RegisterCoreController(...), và giữ logic nghiệp vụ cho domain của mình. Đây là tầng duy nhất nên chứa quy tắc nghiệp vụ.
• biz/dal/ — tầng truy cập dữ liệu. Nó tách thành dao/ (các data access object và registry managers.go), models/ (các model lưu trữ cho database), và do/ (các data object dùng ở tầng cache/Redis). DAO là code duy nhất giao tiếp trực tiếp với database, cache hay storage backend.
• pkg/ — các package dùng chung, tái sử dụng được, nội bộ của service nhưng không thuộc về tầng cụ thể nào (helper, kiểu dùng chung, tích hợp).
• <service>_client/ — thư viện client mà các service khác import để gọi service này. Nó cung cấp một client có kiểu (client.go) để bên gọi không phải tự dựng request.

Lifecycle & thứ tự cài đặt

Struct server triển khai bốn phương thức lifecycle mà framework điều khiển:

• Initialize() — nối toàn bộ dependency mà service cần (chặn, chạy một lần).
• Serving() — chạy server; đây là lời gọi chặn giữ cho tiến trình tồn tại.
• Destroy() — giải phóng tài nguyên khi tắt.
• Info() — trả về metadata mô tả instance của server.

Bên trong Initialize(), các dependency phải được cài đặt theo một thứ tự cụ thể để tiền đề của mỗi bước đã có sẵn. ftkit verify kiểm tra thứ tự này (chỉ InstallCoreControllers — bước controller — là bắt buộc; các bước còn lại chỉ được kiểm tra khi có mặt):

1. logger — Install logger
2. caches — Install caches
3. databases — Install databases
4. dao — Install dao
5. clients — Install clients
6. servers — Install servers
7. controllers — InstallCoreControllers (bắt buộc)
8. handlers — Install handlers

Logic ở đây là từ dưới lên: logger đứng trước để mọi thứ có thể ghi log; caches và databases tiếp theo; DAO phụ thuộc vào các backend đó; clients và servers phụ thuộc vào DAO; controller được cài đặt khi DAO và client của chúng đã tồn tại; và handler được nối sau cùng vì chúng phụ thuộc vào controller mà chúng gọi.

Liên quan

• Cấu trúc dự án — cây thư mục có chú thích.
• Checklist chuẩn — những gì ftkit verify kiểm tra.
• ftkit CLI — công cụ tạo khung và xác minh service.