goframe-development

name	GoFrame Development
description	This skill should be used when the user asks to "create GoFrame application", "setup GoFrame project", "GoFrame routing", "GoFrame middleware", "GoFrame API development", or works with GoFrame web framework components.
version	0.1.0

GoFrame Development

GoFrame is a modular, high-performance, enterprise-level Go application development framework.

Core Concepts

Project Structure

Standard GoFrame project layout:

project/
├── api/              # API definitions (OpenAPI/Swagger)
├── hack/             # Build scripts and tools
├── internal/         # Internal packages
│   ├── cmd/          # Command entry points
│   ├── controller/   # HTTP controllers
│   ├── service/      # Business logic layer
│   ├── model/        # Data models
│   └── dao/          # Data access objects
├── manifest/         # Deployment manifests
├── resource/         # Static resources
├── utility/          # Utility functions
├── go.mod
└── main.go

Basic Server Setup

Create a minimal web server:

package main

import (
    "github.com/gogf/gf/v2/frame/g"
    "github.com/gogf/gf/v2/net/ghttp"
)

func main() {
    s := g.Server()
    s.BindHandler("/", func(r *ghttp.Request) {
        r.Response.Write("Hello World!")
    })
    s.SetPort(8000)
    s.Run()
}

Routing

GoFrame supports multiple routing patterns:

Handler Registration:

s.BindHandler("/user/:id", func(r *ghttp.Request) {
    id := r.Get("id")
    r.Response.WriteJson(g.Map{
        "id": id,
    })
})

Group Routing (Recommended):

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

Nested Groups with Middleware:

s.Group("/api", func(group *ghttp.RouterGroup) {
    group.Middleware(MiddlewareCORS)

    group.Group("/v1", func(group *ghttp.RouterGroup) {
        group.Bind(users.NewV1())

        group.Group("/admin", func(group *ghttp.RouterGroup) {
            group.Middleware(MiddlewareAuth)
            group.Bind(admin.NewV1())
        })
    })
})

Middleware

Create and register middleware:

func MiddlewareAuth(r *ghttp.Request) {
    token := r.GetHeader("Authorization")
    if token == "" {
        r.Response.WriteStatus(http.StatusUnauthorized)
        return
    }
    r.Middleware.Next()
}

func MiddlewareCORS(r *ghttp.Request) {
    r.Response.CORSDefault()
    r.Middleware.Next()
}

func MiddlewareLog(r *ghttp.Request) {
    r.Middleware.Next()
    g.Log().Infof("%s %s %d", r.Method, r.URL.Path, r.Response.Status)
}

Controller Pattern

Object-based controller with method mapping:

package controller

import (
    "context"
    "github.com/gogf/gf/v2/frame/g"
)

type UserV1 struct{}

func NewV1() *UserV1 {
    return &UserV1{}
}

// Get maps to GET /user/{id}
func (c *UserV1) Get(ctx context.Context, req *v1.UserGetReq) (res *v1.UserGetRes, err error) {
    return &v1.UserGetRes{
        Id:   req.Id,
        Name: "John Doe",
    }, nil
}

// Create maps to POST /user
func (c *UserV1) Create(ctx context.Context, req *v1.UserCreateReq) (res *v1.UserCreateRes, err error) {
    // Implementation
    return &v1.UserCreateRes{Id: 1}, nil
}

Request/Response Structs

Define API contracts:

package v1

// Request
type UserGetReq struct {
    g.Meta `path:"/user/{id}" method:"get" tags:"User" summary:"Get user by ID"`
    Id     int `v:"required" dc:"User ID"`
}

type UserCreateReq struct {
    g.Meta `path:"/user" method:"post" tags:"User" summary:"Create user"`
    Name  string `v:"required" dc:"User name"`
    Email string `v:"required|email" dc:"User email"`
}

// Response
type UserGetRes struct {
    Id    int    `json:"id"`
    Name  string `json:"name"`
    Email string `json:"email"`
}

type UserCreateRes struct {
    Id int `json:"id"`
}

Configuration

GoFrame uses YAML configuration files in manifest/config/:

# manifest/config/config.yaml
server:
  address: ":8000"
  serverRoot: "resource/public"
  serverAgent: "GoFrameServer"
  logPath: "/tmp/log/gf"

database:
  default:
    type: "mysql"
    host: "127.0.0.1"
    port: "3306"
    user: "root"
    pass: "password"
    name: "mydb"
    charset: "utf8mb4"

redis:
  default:
    address: "127.0.0.1:6379"
    db: 0

Access configuration:

// Get config value
port := g.Cfg().MustGet(ctx, "server.port", "8000").String()

// Get database config
host := g.Cfg().MustGet(ctx, "database.default.host").String()

Error Handling

Standardized error responses:

import "github.com/gogf/gf/v2/errors/gerror"

// Create error
err := gerror.New("user not found")

// Wrap error with code
err := gerror.NewCode(404, "user not found")

// Use in controller
if err != nil {
    return nil, gerror.NewCode(404, "user not found")
}

Best Practices

1. Use group routing for organized API structure
2. Define request/response structs with validation tags
3. Implement service layer between controller and DAO
4. Use built-in middleware for common operations (CORS, logging)
5. Leverage g.Dump() for debugging during development
6. Use gconv for type conversions

Additional Resources

• references/routing-patterns.md - Advanced routing patterns
• references/controller-patterns.md - Controller best practices
• examples/basic-server/ - Minimal server example
• examples/api-server/ - Complete API server with all layers