Documentation
¶
Overview ¶
Package module provides a unified module registration system that automatically registers models, services, and HTTP routes for CRUD operations.
The module system enables developers to create self-contained, reusable modules that encapsulate complete API resources with minimal boilerplate code. Each module defines its model, service, routing configuration, and authentication requirements.
Core Components:
- Model: Database entity that implements types.Model interface
- Service: Business logic layer that implements types.Service interface
- Module: Configuration provider that implements types.Module interface
Usage Pattern:
- Define your model struct (embedding model.Base)
- Define your request and response types
- Implement a service that embeds service.Base
- Implement a module that implements types.Module interface
- Call module.Use() to register the module with desired CRUD phases
Example - Full CRUD Module:
type User struct {
Username string `json:"username"`
Email string `json:"email"`
model.Base
}
type UserService struct {
service.Base[*User, *User, *User]
}
type UserModule struct{}
func (UserModule) Service() types.Service[*User, *User, *User] {
return &UserService{}
}
func (UserModule) Pub() bool { return false }
func (UserModule) Route() string { return "users" }
func (UserModule) Param() string { return "id" }
func Register() {
module.Use[*User, *User, *User, *UserService](
&UserModule{},
consts.PHASE_CREATE,
consts.PHASE_DELETE,
consts.PHASE_UPDATE,
consts.PHASE_PATCH,
consts.PHASE_LIST,
consts.PHASE_GET,
consts.PHASE_CREATE_MANY,
consts.PHASE_DELETE_MANY,
consts.PHASE_UPDATE_MANY,
consts.PHASE_PATCH_MANY,
)
}
This will automatically create the following routes:
- POST /users (create)
- DELETE /users/:id (delete)
- PUT /users/:id (update)
- PATCH /users/:id (patch)
- GET /users (list)
- GET /users/:id (get)
- POST /users/batch (create many)
- DELETE /users/batch (delete many)
- PUT /users/batch (update many)
- PATCH /users/batch (patch many)
Example - Read-Only Module:
module.Use[*LoginLog, *LoginLog, *LoginLog, *LoginLogService](
&LoginLogModule{},
consts.PHASE_LIST,
consts.PHASE_GET,
)
This will create only:
- GET /loginlog (list)
- GET /loginlog/:id (get)
Authentication:
- If Module.Pub() returns true: endpoints are publicly accessible
- If Module.Pub() returns false: endpoints require authentication/authorization
Route Path Normalization:
- Leading slashes are automatically removed
- "api" prefix is automatically removed
- Route paths are normalized for consistency
See module/helloworld and module/logger for complete working examples.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Init ¶ added in v0.10.1
func Init() error
Init notify the module system that the framework is initialized Now the module system can start to register model, service, router, middleware.
func Use ¶
func Use[M types.Model, REQ types.Request, RSP types.Response, S types.Service[M, REQ, RSP]](mod types.Module[M, REQ, RSP], phases ...consts.Phase)
Use registers a module with the framework, automatically setting up model registration, service registration, and HTTP route registration for the specified CRUD phases.
This function is the primary entry point for module registration. It performs three main operations:
- Registers the model type with the ORM layer for database operations
- Registers the service type for each specified phase to handle business logic
- Registers HTTP routes for each specified CRUD operation
Generic Type Parameters:
- M: Model type that implements types.Model interface (typically a pointer to struct)
- REQ: Request type for API operations (can be any serializable type)
- RSP: Response type for API operations (can be any serializable type)
- S: Service type that implements types.Service[M, REQ, RSP] interface
Parameters:
- mod: Module instance that implements types.Module[M, REQ, RSP] interface. This provides configuration for routing, authentication, and service access.
- phases: Variable number of CRUD phases to register. Each phase corresponds to a specific HTTP endpoint. Available phases:
- PHASE_CREATE: POST /route (create single resource)
- PHASE_DELETE: DELETE /route/:param (delete single resource)
- PHASE_UPDATE: PUT /route/:param (update single resource)
- PHASE_PATCH: PATCH /route/:param (patch single resource)
- PHASE_LIST: GET /route (list resources with pagination)
- PHASE_GET: GET /route/:param (get single resource by ID)
- PHASE_CREATE_MANY: POST /route/batch (create multiple resources)
- PHASE_DELETE_MANY: DELETE /route/batch (delete multiple resources)
- PHASE_UPDATE_MANY: PUT /route/batch (update multiple resources)
- PHASE_PATCH_MANY: PATCH /route/batch (patch multiple resources)
Route Registration:
- Routes are automatically registered based on the module's Route() and Param() methods
- Route paths are normalized (leading slashes and "api" prefix are removed)
- URL parameter name defaults to "id" if Param() returns empty string
- Authentication is determined by the module's Pub() method
Service Registration:
- Service is registered for each specified phase
- The same service instance is used for all phases, but lifecycle hooks are called at appropriate times based on the phase
Example Usage:
// Register a full CRUD module
module.Use[*User, *UserRequest, *UserResponse, *UserService](
&UserModule{},
consts.PHASE_CREATE,
consts.PHASE_DELETE,
consts.PHASE_UPDATE,
consts.PHASE_PATCH,
consts.PHASE_LIST,
consts.PHASE_GET,
)
// Register a read-only module
module.Use[*LoginLog, *LoginLog, *LoginLog, *LoginLogService](
&LoginLogModule{},
consts.PHASE_LIST,
consts.PHASE_GET,
)
Note: This function must be called during application initialization, typically in a Register() function within your module package.
Types ¶
This section is empty.
Source Files
Directories