--- title: 'Quick Demo' slug: '/docs/practices/quick-demo' description: 'Quick-start HTTP RESTful API with GoFrame v2.10.0, featuring user CRUD operations, MySQL integration, OpenAPI/Swagger documentation, and standard project structure for rapid development.' keywords: [GoFrame, Quick Start, HTTP Server, RESTful API, MySQL, CRUD Operations, OpenAPI, Swagger, DAO Pattern, ORM, Web Development, Go Framework, API Development, Database Integration, Auto Code Generation, Project Template, Standard Structure, Configuration Management, Middleware, Response Handling] hide_title: true --- # Quick Demo ## Introduction `quick-demo` is a quick-start HTTP service example that demonstrates rapid development with GoFrame framework. It provides a complete RESTful API implementation with user CRUD operations, MySQL database integration, and automatic OpenAPI documentation generation. This example follows GoFrame's standard project structure and best practices, making it an ideal starting point for learning GoFrame or building new projects. ## Project Structure ```text quick-demo/ ├── api/ # API interface definitions │ └── user/ # User module API │ ├── user.go # API definition for completeness check(auto-generated by "gf gen ctrl") │ └── v1/ # API definition version v1 ├── internal/ # Internal implementation │ ├── cmd/ # Command layer │ │ └── cmd.go # Server initialization │ ├── consts/ # Constants │ ├── controller/ # Controller layer │ │ ├── hello/ # Hello controller │ │ └── user/ # User CRUD controllers │ ├── dao/ # Data Access Objects (auto-generated) │ ├── model/ # Data models │ │ ├── do/ # Data objects (auto-generated) │ │ └── entity/ # Database entities (auto-generated) │ └── service/ # Business logic layer ├── manifest/ # Application manifest │ ├── config/ # Configuration files │ │ └── config.yaml # Main configuration │ ├── deploy/ # Deployment configs │ └── docker/ # Docker configurations ├── main.go # Application entry point └── go.mod # Go module definition ``` ## Features - **RESTful API Design**: Complete user CRUD operations with RESTful conventions - **MySQL Integration**: Database operations using GoFrame's DAO pattern and ORM - **OpenAPI/Swagger**: Automatic API documentation generation and Swagger UI - **Standard Structure**: Follows GoFrame's recommended project structure for scalability - **Auto Code Generation**: DAO, entity, and model code auto-generated from database schema - **Validation**: Built-in request parameter validation with rules - **Configuration Management**: YAML-based configuration with environment support - **Middleware**: Unified response handling middleware for consistent API responses - **Hello World Example**: Simple example demonstrating basic HTTP handling ## Requirements - Go 1.23.0 or higher - MySQL 8.0 or higher ## Prerequisites **Start MySQL using Docker:** ```bash docker run -d \ --name mysql \ -p 3306:3306 \ -e MYSQL_ROOT_PASSWORD=12345678 \ -e MYSQL_DATABASE=test \ mysql:8.0 ``` **Create user table:** ```sql CREATE TABLE `user` ( `id` int unsigned NOT NULL AUTO_INCREMENT COMMENT 'user id', `name` varchar(50) NOT NULL COMMENT 'user name', `status` int NOT NULL DEFAULT '0' COMMENT 'user status', `age` int unsigned NOT NULL COMMENT 'user age', PRIMARY KEY (`id`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4; ``` ## Installation ```bash cd /path/to/examples/practices/quick-demo go mod tidy ``` ## Usage **Start the server:** ```bash go run main.go ``` The server will start on `http://localhost:8000`. **Access API documentation:** - `Swagger UI`: http://localhost:8000/swagger - `OpenAPI Spec`: http://localhost:8000/api.json ## API Reference ### Hello API **GET /hello** Returns "Hello World!" message. ```bash curl http://localhost:8000/hello ``` ### User APIs **Create User** `POST /user` ```bash curl -X POST http://localhost:8000/user \ -H "Content-Type: application/json" \ -d '{ "name": "john", "age": 25 }' ``` Response: ```json { "code": 0, "message": "", "data": { "id": 1 } } ``` **Update User** `PUT /user/{id}` ```bash curl -X PUT http://localhost:8000/user/1 \ -H "Content-Type: application/json" \ -d '{ "name": "john_updated", "age": 26, "status": 0 }' ``` **Delete User** `DELETE /user/{id}` ```bash curl -X DELETE http://localhost:8000/user/1 ``` **Get One User** `GET /user/{id}` ```bash curl http://localhost:8000/user/1 ``` Response: ```json { "code": 0, "message": "", "data": { "id": 1, "name": "john", "status": 0, "age": 25 } } ``` **Get User List** `GET /user` ```bash # Get all users curl http://localhost:8000/user # Filter by age curl "http://localhost:8000/user?age=25" # Filter by status curl "http://localhost:8000/user?status=0" ``` Response: ```json { "code": 0, "message": "", "data": { "list": [ { "id": 1, "name": "john", "status": 0, "age": 25 } ] } } ``` ## Implementation Details ### API Definition API interfaces are defined using GoFrame's `g.Meta` tags for automatic routing and documentation: ```go type CreateReq struct { g.Meta `path:"/user" method:"post" tags:"User" summary:"Create user"` Name string `v:"required|length:3,10" dc:"user name"` Age uint `v:"required|between:18,200" dc:"user age"` } ``` ### Controller Implementation Controllers implement the business logic for each API endpoint: ```go func (c *ControllerV1) Create(ctx context.Context, req *v1.CreateReq) (res *v1.CreateRes, err error) { insertId, err := dao.User.Ctx(ctx).Data(do.User{ Name: req.Name, Status: v1.StatusOK, Age: req.Age, }).InsertAndGetId() if err != nil { return nil, err } res = &v1.CreateRes{Id: insertId} return } ``` ### DAO Pattern The project uses GoFrame's DAO pattern for database operations with auto-generated code: - `dao/`: Database access layer (auto-generated) - `model/do/`: Data objects for database operations (auto-generated) - `model/entity/`: Database table structures (auto-generated) ### Response Middleware Unified response handling middleware ensures consistent API responses with code, message, and data fields. ## Configuration Configuration is managed through `manifest/config/config.yaml`: ```yaml server: address: ":8000" openapiPath: "/api.json" swaggerPath: "/swagger" database: default: link: "mysql:root:12345678@tcp(127.0.0.1:3306)/test" ```