controller

package
v0.0.0-...-e769803 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 2, 2026 License: Apache-2.0 Imports: 33 Imported by: 0

Documentation

Overview

Package controller contains framework-owned HTTP handlers for registered routes.

Application code should register routes through package router or generated code. Keeping controller internal prevents external projects from depending on handler factories or mutating controller-owned audit state directly.

Index

Constants

View Source 
const (
	MAX_AVATAR_SIZE = 1024 * 1024 * 2   //nolint:staticcheck // 2M
	MAX_IMPORT_SIZE = 5 * 1024 * 1024   //nolint:staticcheck // 5M
	MAX_UPLOAD_SIZE = 1024 * 1024 * 100 //nolint:staticcheck // 100M
)
View Source 
const (
	TOKEN         = "token"
	ACCESS_TOKEN  = "access_token"  //nolint:staticcheck
	REFRESH_TOKEN = "refresh_token" //nolint:staticcheck
	NAME          = "name"          //nolint:staticcheck
	ID            = "id"
	SESSION_ID    = "session_id" //nolint:staticcheck
)
View Source 
const ErrRequestBodyEmpty = "request body is empty"

ErrRequestBodyEmpty is returned when an action requires a request body but the client sends an empty body.

Variables

View Source 
var Probe = new(probe)

Functions

func Clean 

func Clean()

Clean flushes buffered operation logs during shutdown.

func Create 

func Create[M types.Model, REQ types.Request, RSP types.Response](c *gin.Context)

Create is a generic function to product gin handler to create one resource. The resource type depends on the type of interface types.Model.

func CreateFactory 

func CreateFactory[M types.Model, REQ types.Request, RSP types.Response](cfg ...*types.ControllerConfig[M]) gin.HandlerFunc

CreateFactory returns a Gin handler that creates one resource.

When M, REQ, and RSP are the same type, the handler binds the JSON body into M, fills the creator/updater fields, runs the create hooks, writes the model through the configured database handler, records an operation log, and returns the created model with a created response status.

When REQ or RSP differs from M, the handler binds the JSON body into REQ and delegates the operation to the phase service's Create method. Multipart form requests are left unbound so the service can read the request directly.

func CreateMany 

func CreateMany[M types.Model, REQ types.Request, RSP types.Response](c *gin.Context)

CreateMany handles a batch create request with the default factory settings.

func CreateManyFactory 

func CreateManyFactory[M types.Model, REQ types.Request, RSP types.Response](cfg ...*types.ControllerConfig[M]) gin.HandlerFunc

CreateManyFactory returns a Gin handler that creates multiple resources.

When M, REQ, and RSP are the same type, the handler binds the JSON body into requestData[M], fills creator/updater fields on each item, runs batch create hooks, writes the items through the configured database handler, records an operation log, and returns the request data with a summary when a body was provided.

When REQ or RSP differs from M, the handler binds the JSON body into REQ and delegates the operation to the phase service's CreateMany method.

func Delete 

func Delete[M types.Model, REQ types.Request, RSP types.Response](c *gin.Context)

Delete is a generic function to product gin handler to delete one or multiple resources. The resource type depends on the type of interface types.Model.

Resource id must be specify and all resources that id matched will be deleted in database.

Delete one resource: - specify resource `id` in "router parameter", eg: localhost:9000/api/myresource/myid - specify resource `id` in "query parameter", eg: localhost:9000/api/myresource?id=myid

Delete multiple resources: - specify resource `id` slice in "http body data".

func DeleteFactory 

func DeleteFactory[M types.Model, REQ types.Request, RSP types.Response](cfg ...*types.ControllerConfig[M]) gin.HandlerFunc

DeleteFactory returns a Gin handler that deletes one or more resources.

When M, REQ, and RSP are the same type, the handler collects ids from the query string, the configured route parameter, and an optional JSON string array body. It deduplicates ids, runs delete hooks for each model, deletes the models through the configured database handler, records operation logs, and returns a no-content response status.

When REQ or RSP differs from M, the handler binds the JSON body into REQ and delegates the operation to the phase service's Delete method.

func DeleteMany 

func DeleteMany[M types.Model, REQ types.Request, RSP types.Response](c *gin.Context)

DeleteMany handles a batch delete request with the default factory settings.

func DeleteManyFactory 

func DeleteManyFactory[M types.Model, REQ types.Request, RSP types.Response](cfg ...*types.ControllerConfig[M]) gin.HandlerFunc

DeleteManyFactory returns a Gin handler that deletes multiple resources.

When M, REQ, and RSP are the same type, the handler binds the JSON body into requestData[M], converts ids into model instances, runs batch delete hooks, deletes the models through the configured database handler, records an operation log, and returns a no-content response status.

When REQ or RSP differs from M, the handler binds the JSON body into REQ and delegates the operation to the phase service's DeleteMany method.

func Export 

func Export[M types.Model, REQ types.Request, RSP types.Response](c *gin.Context)

Export handles an export request with the default factory settings.

func ExportFactory 

func ExportFactory[M types.Model, REQ types.Request, RSP types.Response](cfg ...*types.ControllerConfig[M]) gin.HandlerFunc

ExportFactory returns a Gin handler that exports resources.

The handler decodes query parameters into M, applies service filters, runs list hooks, queries the configured database handler with export-oriented limit and query options, delegates byte generation to the phase service's Export method, and writes the result as an attachment

func Get 

func Get[M types.Model, REQ types.Request, RSP types.Response](c *gin.Context)

Get is a generic function to product gin handler to list resource in backend. The resource type deponds on the type of interface types.Model.

Query parameters:

  • `_expand`: strings (multiple items separated by ","). The responsed data to frontend will expanded(retrieve data from external table accoding to foreign key) For examples: /department/myid?_expand=children /department/myid?_expand=children,parent
  • `_depth`: strings or interger. How depth to retrieve records from datab recursively, default to 1, value scope is [1,99]. For examples: /department/myid?_expand=children&_depth=3 /department/myid?_expand=children,parent&_depth=10

Route parameters: - id: string or integer.

func GetFactory 

func GetFactory[M types.Model, REQ types.Request, RSP types.Response](cfg ...*types.ControllerConfig[M]) gin.HandlerFunc

GetFactory returns a Gin handler that retrieves one resource.

When M, REQ, and RSP are the same type, the handler reads the configured route parameter as the resource id, applies expansion, depth, selection, cache, and database index query options, runs get hooks, loads the model through the configured database handler, records an operation log, and returns the model.

When REQ or RSP differs from M, the handler binds the JSON body into REQ and delegates the operation to the phase service's Get method.

func Import 

func Import[M types.Model, REQ types.Request, RSP types.Response](c *gin.Context)

Import handles an import request with the default factory settings.

func ImportFactory 

func ImportFactory[M types.Model, REQ types.Request, RSP types.Response](cfg ...*types.ControllerConfig[M]) gin.HandlerFunc

ImportFactory returns a Gin handler that imports resources from an uploaded file.

The handler reads the multipart form file named "file", rejects files larger than MAX_IMPORT_SIZE, passes the file content to the phase service's Import method, fills creator/updater fields on the returned models, updates those models through the configured database handler, and returns a success

func Init 

func Init() (err error)

Init initializes controller-owned audit logging state.

Init is idempotent after a successful initialization. Failed initialization is not cached, so a later call can retry after configuration has been fixed.

func List 

func List[M types.Model, REQ types.Request, RSP types.Response](c *gin.Context)

List is a generic function to product gin handler to list resources in backend. The resource type deponds on the type of interface types.Model.

If you want make a structure field as query parameter, you should add a "schema" tag for it. for example: schema:"name"

TODO:combine query parameter 'page' and 'size' into decoded types.Model FIX: retrieve records recursive (current not support in gorm.) https://stackoverflow.com/questions/69395891/get-recursive-field-values-in-gorm DB.Preload("Category.Category.Category").Find(&Category) its works for me.

Query parameters:

  • All feilds of types.Model's underlying structure but excluding some special fields, such as "password", field value too large, json tag is "-", etc.
  • `_expand`: strings (multiple items separated by ","). The responsed data to frontend will expanded(retrieve data from external table accoding to foreign key) For examples: /department/myid?_expand=children /department/myid?_expand=children,parent
  • `_depth`: strings or interger. How depth to retrieve records from datab recursively, default to 1, value scope is [1,99]. For examples: /department/myid?_expand=children&_depth=3 /department/myid?_expand=children,parent&_depth=10
  • `_fuzzy`: bool fuzzy match records in database, default to fase. For examples: /department/myid?_fuzzy=true

func ListFactory 

func ListFactory[M types.Model, REQ types.Request, RSP types.Response](cfg ...*types.ControllerConfig[M]) gin.HandlerFunc

ListFactory returns a Gin handler that lists resources.

When M, REQ, and RSP are the same type, the handler decodes query parameters into M, applies service filters, runs list hooks, queries the configured database handler, records an operation log, and returns the items with a total count unless total counting is disabled or cursor pagination is used.

The automatic listing branch supports model schema fields plus framework query parameters for pagination, cursor pagination, expansion, depth, fuzzy matching, OR matching, ordering, selection, cache control, database index hints, and time ranges.

When REQ or RSP differs from M, the handler binds the JSON body into REQ and delegates the operation to the phase service's List method.

func Patch 

func Patch[M types.Model, REQ types.Request, RSP types.Response](c *gin.Context)

Patch is a generic function to product gin handler to partial update one resource. The resource type depends on the type of interface types.Model.

resource id must be specified. - specified in "query parameter `id`". - specified in "router parameter `id`".

which one or multiple resources desired modify. - specified in "query parameter". - specified in "http body data".

func PatchFactory 

func PatchFactory[M types.Model, REQ types.Request, RSP types.Response](cfg ...*types.ControllerConfig[M]) gin.HandlerFunc

PatchFactory returns a Gin handler that partially updates one resource.

When M, REQ, and RSP are the same type, the handler uses the configured route id before the body id, loads the existing record, copies fields present in the request model into that record, sets the updater field, runs patch hooks, writes the patched model through the configured database handler, and records an operation log.

When REQ or RSP differs from M, the handler binds the JSON body into REQ and delegates the operation to the phase service's Patch method.

func PatchMany 

func PatchMany[M types.Model, REQ types.Request, RSP types.Response](c *gin.Context)

PatchMany handles a batch patch request with the default factory settings.

func PatchManyFactory 

func PatchManyFactory[M types.Model, REQ types.Request, RSP types.Response](cfg ...*types.ControllerConfig[M]) gin.HandlerFunc

PatchManyFactory returns a Gin handler that partially updates multiple resources.

When M, REQ, and RSP are the same type, the handler binds the JSON body into requestData[M], loads matching existing records for the requested items, copies fields present in each item into those records, runs batch patch hooks, updates the patched models through the configured database handler, records an operation log, and returns the request data with a summary when a body was provided.

When REQ or RSP differs from M, the handler binds the JSON body into REQ and delegates the operation to the phase service's PatchMany method.

func Redoc 

func Redoc(c *gin.Context)

func Scalar 

func Scalar(c *gin.Context)

func Stoplight 

func Stoplight(c *gin.Context)

func Update 

func Update[M types.Model, REQ types.Request, RSP types.Response](c *gin.Context)

Update is a generic function to product gin handler to update one resource. The resource type depends on the type of interface types.Model.

Update will update one resource and resource "ID" must be specified, which can be specify in "router parameter `id`" or "http body data".

"router parameter `id`" has more priority than "http body data". It will skip decode id from "http body data" if "router parameter `id`" not empty.

func UpdateFactory 

func UpdateFactory[M types.Model, REQ types.Request, RSP types.Response](cfg ...*types.ControllerConfig[M]) gin.HandlerFunc

UpdateFactory returns a Gin handler that replaces one resource.

When M, REQ, and RSP are the same type, the handler binds the JSON body into M, uses the configured route id before the body id, verifies that exactly one existing record matches, preserves the original creator fields, sets the updater field, runs update hooks, writes the replacement through the configured database handler, and records an operation log.

When REQ or RSP differs from M, the handler binds the JSON body into REQ and delegates the operation to the phase service's Update method.

func UpdateMany 

func UpdateMany[M types.Model, REQ types.Request, RSP types.Response](c *gin.Context)

UpdateMany handles a batch update request with the default factory settings.

func UpdateManyFactory 

func UpdateManyFactory[M types.Model, REQ types.Request, RSP types.Response](cfg ...*types.ControllerConfig[M]) gin.HandlerFunc

UpdateManyFactory returns a Gin handler that replaces multiple resources.

When M, REQ, and RSP are the same type, the handler binds the JSON body into requestData[M], runs batch update hooks, updates the items through the configured database handler, records an operation log, and returns the request data with a summary when a body was provided.

When REQ or RSP differs from M, the handler binds the JSON body into REQ and delegates the operation to the phase service's UpdateMany method.

Types

This section is empty.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.