How onexstack/miniblog works
Main Components
• Client Interfaces – Represent both REST/HTTP and gRPC clients (as reflected by the “examples/client” folder, which demonstrates how to interact with endpoints for health, user, and post operations).
• API Gateway / Reverse Proxy – Although not a separate microservice, note that configuration files (e.g., the nginx reverse and load balancing configs under “configs/nginx.reverse.conf” and “configs/nginx.loadbalance.conf”) indicate that a reverse proxy or API gateway might be involved.
• The Backend Server (mb-apiserver) – This is the core executable (located under “cmd/mb-apiserver”) that handles incoming API requests. It is built with high quality; supporting both gRPC and HTTP endpoints.
• Application Layers inside the Server:
• Handlers & Controllers: Separate packages in “internal/apiserver/handler” for HTTP and gRPC that map API requests to business logic.
• Business Logic (Biz): In “internal/apiserver/biz”; includes distinct versions (v1 and v2) and contains the core application rules.
• Data Models: In “internal/apiserver/model”, which define the schema (e.g., for posts, users, casbin rules, etc.).
• Persistence / Store: The “internal/apiserver/store” package manages database interactions. The project supports both an in-memory database and MySQL (as detailed in the README and configuration files).
• Middleware & Utilities: Several internal packages (e.g., “internal/pkg/log”, “internal/pkg/errno”, “internal/pkg/middleware”, “internal/pkg/rid”) offer cross-cutting concerns such as logging, error handling, request IDs, authentication (JWT), and authorization (Casbin).
Relationships and Data Flows
• Clients issue API requests via either HTTP or gRPC.
• Requests are received at the mb-apiserver. Within the server, the entry point (main.go) sets up servers for both HTTP and gRPC.
• For each incoming request, the corresponding handler (HTTP or gRPC) routes the call and applies necessary middleware (for authentication, authorization, logging, etc.).
• The handler calls the appropriate business logic (biz layer) which processes the request.
• When data persistence is needed, the biz layer interacts with the store (data access layer) which uses either an in-memory data store or a configured MySQL database (with configuration specified in “configs/mb-apiserver.yaml”).
• The response is then passed back through the handler to the client.
Architectural Patterns & Design Principles
• Separation of Concerns: The project clearly separates concerns between API specification (OpenAPI and Swagger definitions in “api/openapi”), business logic (internal/apiserver/biz), request handling (internal/apiserver/handler), and data persistence (internal/apiserver/store).
• Layered Architecture: The distinct layers (Controller/Handler, Business Logic, Persistence) allow independent development and testing.
• Extensibility & Code Quality: Utilization of common Go packages (gorm, casbin, jwt-go, viper, zap, etc.) and code generation (evidenced by the “gen-gorm-model” command) indicate adherence to enterprise coding standards.
• Multiple Server Types: The project sets up both a gRPC server and an HTTP server (plus a possible reverse proxy) to handle different data exchange formats (Protobuf and JSON).
Relevant Technologies and Frameworks
• Go standard packages and project layout (conforming to the project-layout specification).
• Frameworks/Libraries: gin (for HTTP middleware and routing), grpc, gorm, casbin, jwt-go, viper, cobra, pflag, and zap.
• API Documentation: OpenAPI/Swagger definitions for API endpoint specifications.
Elements
• Clear Labels: Give each component a specific label (e.g., “HTTP Handler”, “gRPC Handler”, “Business Logic (Biz)”, “Data Store”).
• External components (clients, API gateway)
• Core server components (handlers, business logic, persistence)
• Utility/internal support (middleware, logging, error handling)
• Technology stacks where relevant (for instance, grouping the gRPC-related components together since they handle Protobuf transport, and likewise grouping HTTP/JSON related components).