Skip to main content
Version: 2.8.x

New to the project structure? Don't worry! This chapter builds on our Project Structure Guide🔥 to explain how your application starts up and how different components work together.

The Main Entry Point​

Every GoFrame application begins with main.go. This file delegates to the internal/cmd package to orchestrate the application startup. In our project template, it specifically calls the Run command of the Main object in the internal/cmd package.

All core business logic resides in the internal directory - a Go feature that prevents external packages from importing these files, enhancing security and maintaining clean architecture.

tip

Framework core components require a context parameter. We use gctx.GetInitCtx to inherit trace information from the parent process. If no parent process exists, it creates a new context with tracing capabilities for downstream operations.

main.go

Bootstrap Process​

The Main object's Run command handles bootstrap initialization, where you can place dynamic startup logic. By default, our template:

  1. Creates an HTTP server
  2. Registers routes using group routing
  3. Starts the HTTP server
  4. Blocks for incoming requests while monitoring system signals
  5. Gracefully shuts down when receiving exit signals
tip

For detailed command-line management information, see: Command Management

main command

Configuring Routes​

The template uses group routing via the Group method - one of several routing approaches supported by GoFrame's HTTP server.

s := g.Server()
s.Group("/", func(group *ghttp.RouterGroup) {
    group.Middleware(ghttp.MiddlewareHandlerResponse)
    group.Bind(
        hello.NewV1(),
    )
})

This setup:

  • Registers a middleware using Middleware to standardize route responses
  • Binds route objects returned by hello.NewV1() using the Bind method
  • Automatically registers all public methods of the route object
  • Supports API versioning (default version is v1)
tip

For comprehensive routing documentation, see: Router Guide 🔥

Route Objects​

Creating Route Objects​

Let's look at how hello.NewV1() works:

Route Object Creation

Notice it returns an API interface rather than a concrete object:

API Interface

Why use an interface instead of returning the ControllerV1 object directly?

This design enables early error detection. If your controller doesn't implement all required API methods, you'll get compilation errors and IDE warnings, rather than runtime failures.

tip
  • This pattern is optional but recommended for robust code organization
  • Most of this code can be auto-generated using the gf gen ctrl command based on API definitions

Defining Route Handlers​

Here's a typical route handler:

Route Handler

Route parameters are defined in the HelloReq input object:

Request Object

tip

This approach of using middleware for standardized responses and route objects is called standardized routing. Learn more in our Standard Router Guide.

Running Your Application​

Server Operation​

The HTTP server starts with the Run method, which:

  • Blocks for incoming requests
  • Monitors process signals
  • Handles server restart/shutdown

You'll see this output on startup:

Server Output

Notice that API documentation and Swagger UI are automatically enabled.

Testing the API​

Visit http://127.0.0.1:8000/hello to test the API:

API Response

Access the API documentation at http://127.0.0.1:8000/swagger:

Swagger UI

Chapter Summary​

You now understand how a GoFrame application bootstraps and runs. While we've covered the basics, there's much more to explore in our detailed documentation.

Next, we'll build a complete CRUD API using this template, implementing database operations for creating, reading, updating, and deleting records.