DEV Community: iexu

HTTP Status Code or Custom Status Code? An Elegant Error Handling Solution in Go

iexu — Fri, 18 Apr 2025 22:13:51 +0000

HTTP Status Code or Custom Status Code? An Elegant Error Handling Solution in Go

When developing REST APIs, have you ever encountered these problems:

Error messages are disorganized and hard to locate
Error prompts shown to users are obscure and difficult to understand
Sensitive information is exposed in production environment
Error handling code is repetitive and hard to maintain

This article introduces an elegant error handling solution that makes your code clearer, more maintainable, and provides a better user experience.

Pain Points in Error Handling

In traditional error handling approaches, we often face the following issues:

Inconsistent error messages
- Some use numeric status codes
- Some use string descriptions
- Some directly return underlying errors
Repetitive error handling code
- Each interface requires error handling logic
- Logging is scattered everywhere
- HTTP status code mapping is confusing
Poor user experience
- Error prompts are not user-friendly
- Lack of contextual information
- Difficult to locate problems

Traditional Error Handling Solutions

Let's first look at traditional error handling approaches:

// Approach 1: Direct error return
func findUser(ctx *gin.Context) {
    user, err := db.FindUser()
    if err != nil {
        ctx.JSON(500, gin.H{"error": err.Error()})
        return
    }
    ctx.JSON(200, user)
}

// Approach 2: Using status codes
func findUser(ctx *gin.Context) {
    user, err := db.FindUser()
    if err != nil {
        ctx.JSON(500, gin.H{
            "code": 1001,
            "msg": "Database query failed"
        })
        return
    }
    ctx.JSON(200, user)
}

These approaches, while simple and direct, have some obvious drawbacks:

Security issues
- Approach 1 directly exposes underlying errors to users, potentially leaking sensitive information
- Database errors may contain internal information like table structure, SQL statements
Communication complexity
- Is status code 400 an HTTP status code or a custom status code?
- Must deserialize response body to know the status
- Duplicate definitions, both HTTP status code 200 and custom status code 0 indicate success
Poor maintainability
- Numeric error codes (like 1001) lack semantics and are hard to understand
- Developers need to consult documentation to understand error meanings
- Even error code definers may forget their specific meanings

An Elegant Error Handling Solution

Let's first see how the elegant error handling solution is used:

var ErrBadRequest = reason.NewError("ErrBadRequest", "Invalid request parameters")

func (u *UserAPI) getUser(ctx *gin.Context, _ *struct{}) (*user.UserOutput, error) {
    return u.core.GetUser(in.ID)
}

// package user
func (u *Core) GetUser(id int64) (*UserOutput, error) {
    // Parameter validation
    if err != nil {
        return nil, ErrBadRequest.With(err.Error(), "xx parameter should be between 10~100")
    }
    // Correct processing logic...
}

Remember the web.WarpH function mentioned in the previous article? Its error response actually calls web.Fail(err), which checks if the error is of type reason.Error. If it is, it returns the defined HTTP status code, reason, and msg to the client.

Similar to:

HTTP Status Code: 400 (default for all errors)

{
    "reason": "Error for program recognition",
    "msg": "Error message description for users",
    "details": [
        "Field transmission error",
        "You can fix it this way",
        "Check documentation for more information"
    ]
}

Error Code Design Considerations

Traditional solutions using numeric error codes (like 1001 for database errors) have obvious disadvantages: lack of semantics, requiring documentation consultation, and definers easily forgetting meanings.

Therefore, we use strings as error codes, with clear advantages:

Strong self-explanatory nature
- ErrBadRequest is more intuitive than 1001
- Error codes serve as documentation
- Facilitates code review and debugging
Good extensibility
- Can use module prefixes for distinction
- Avoids error code conflicts
- Quickly locates problem sources

During frontend integration, when certain interfaces encounter errors, frontend developers might be confused and need to consult backend developers. Some issues might just be parameter problems. What if the error response included solutions? Could this simplify integration complexity?

To prevent users from seeing technical errors or developers lacking contextual information, we divide error information into four attributes:

type Error struct {
    Reason     string
    Msg        string
    Details    []string
    HTTPStatus int
}

The role of each field:

reason field
- Uses PascalCase English to describe error reasons
- Used for internal program error type determination
- Supports error code mapping to HTTP status codes
msg field
- Uses developer's native language to describe errors
- User-oriented, provides friendly prompts
details field
- Provides extended error information
- Developer-oriented, aids debugging
- Can be hidden in production environment by calling web.SetRelease() to avoid leaking sensitive information
HTTPStatus
- HTTP response status code
- Defaults to 400
- Common status codes 200, 400, 401 are usually sufficient, keeping it simple

Usage Documentation

Using predefined error types
- reason.ErrBadRequest: Request parameter error
- reason.ErrStore: Database error
- reason.ErrServer: Server error
Error message handling
- Use SetMsg() method to modify user-friendly prompts
- Use Withf() method to add developer assistance, increasing error context

Adopt a single reason principle, meaning errors with the same reason are considered the same error.

// Are e1 and e2 the same error?
e1 = NewError("e1", "e1")
e2 = NewError("e2", "e1")

// e3 and e2 are the same error
e2 := NewError("e2", "e2").SetHTTPStatus(200).With("e2-1")
e3 := fmt.Errorf("e3:%w", e2)
if !errors.Is(e3, e2) {
    t.Fatal("expect e3 is e2, but not")
}

// Convert error to *reason.Error struct
var e5 *reason.Error
if !errors.As(e4, &e5) {
    t.Fatal("expect e4 as e5, but not")
}

Summary

Through reasonable layering and encapsulation, we have achieved:

Unified error handling process
Friendly user prompts
Detailed developer information
Secure error exposure

This design ensures both development efficiency and user experience. If you're looking for an elegant error handling solution, why not try this approach?

About goddd

The error handling introduced in this article is a core component of the goddd project. goddd is a Go project based on DDD (Domain-Driven Design) principles, providing a series of tools and best practices to help developers build maintainable and extensible applications.

If you're interested in the content introduced in this article, welcome to visit the goddd project to learn more. The project provides complete example code and detailed documentation to help you get started quickly.

Unveiling: How to Build Elegant API Interfaces with Gin Framework

iexu — Fri, 18 Apr 2025 19:12:39 +0000

From Repetitive Code to Elegant Encapsulation

In Gin framework development, have you ever encountered this scenario: each API endpoint requires repetitive code for parameter binding, error handling, and response formatting? This not only increases code volume but also reduces development efficiency and code maintainability.

Let's look at a typical example:

func getUser(ctx *gin.Context) {
    var in UserInput
    if err := ctx.ShouldBindQuery(&in); err != nil {
        ctx.JSON(400, gin.H{"error": err.Error()})
        return
    }
    user, err := userService.GetUser(in.ID)
    if err != nil {
        ctx.JSON(500, gin.H{"error": "Server error"})
        return
    }
    ctx.JSON(200, user)
}

This code pattern repeatedly appears in projects, leading to:

Large amounts of boilerplate code
Scattered error handling logic
Inconsistent response formats
Business logic buried in technical details

This article will introduce how to solve these problems through the elegant encapsulation solution of web.WarpH.

Elegant Solution

web.WarpH is a generic-based encapsulation function that solves the above problems through:

Automatic parameter binding
Unified error handling
Standardized response formatting
Allowing developers to focus on business logic

Core Implementation

web.WarpH's implementation is based on the generic feature introduced in Go 1.18, using type parameters I and O to represent input and output types respectively:

func WarpH[I any, O any](fn func(*gin.Context, *I) (O, error)) gin.HandlerFunc {
    return func(c *gin.Context) {
        var in I
        if unsafe.Sizeof(in) != 0 {
            switch c.Request.Method {
            case http.MethodGet:
                if err := c.ShouldBindQuery(&in); err != nil {
                    Fail(c, ErrBadRequest.With(HanddleJSONErr(err).Error()))
                    return
                }
            case http.MethodPost, http.MethodPut, http.MethodDelete, http.MethodPatch:
                if c.Request.ContentLength > 0 {
                    if err := c.ShouldBindJSON(&in); err != nil {
                        Fail(c, ErrBadRequest.With(HanddleJSONErr(err).Error()))
                        return
                    }
                }
            }
        }
        out, err := fn(c, &in)
        if err != nil {
            Fail(c, err)
            return
        }
        Success(c, out)
    }
}

Key points of this implementation:

Using generics to support arbitrary input and output types
Automatically selecting parameter binding methods based on request method
Unified error handling and response formatting
Skipping binding for zero-value parameters

Usage Example

With web.WarpH, the code becomes exceptionally concise:

func getUser(ctx *gin.Context, in *UserInput) (*UserOutput, error) {
    return userService.GetUser(in.ID)
}

Advantage Analysis

web.WarpH allows developers to focus on business logic implementation rather than repetitive boilerplate code. Through generics and unified error handling mechanisms, it achieves code conciseness and maintainability. At compile time, generics ensure type safety, prevent runtime type errors, and provide better IDE support.

Practical Application Scenarios

Scenario 1: Query Single User

// Route definition
router.GET("/users/:id", web.WarpH(getUser))

// Handler function, using `*struct{}` empty value to avoid parameter binding
func getUser(ctx *gin.Context, in *struct{}) (*UserOutput, error) {
    id := ctx.Param("id")
    return userService.GetUser(id)
}

This scenario demonstrates how to handle GET requests without request parameters, using ctx.Param to get path parameters.

Scenario 2: Query User List

// Route definition
router.GET("/users", web.WarpH(listUsers))

// Request parameters (defined in user package)
type FindUsersInput struct {
    Page int    `form:"page"`
    Size int    `form:"size"`
    Name string `form:"name"`
}

// Handler function
func findUsers(ctx *gin.Context, in *FindUsersInput) (*FindUsersOutput, error) {
    return userService.ListUsers(in)
}

This scenario demonstrates how to use form tags to handle query parameters.

Scenario 3: Update User Information

// Route definition
router.PUT("/users/:id", web.WarpH(updateUser))

// Request parameters
type UpdateUserInput struct {
    Name  string `json:"name"`
    Email string `json:"email"`
    Age   int    `json:"age"`
}

// Handler function
func updateUser(ctx *gin.Context, in *UpdateUserInput) (*UserOutput, error) {
    id := ctx.Param("id")
    return userService.UpdateUser(in, id)
}

This scenario demonstrates how to handle PUT requests with both path parameters and request body parameters.

Scenario 4: Delete User

// Route definition
router.DELETE("/users/:id", web.WarpH(deleteUser))

// Handler function
func deleteUser(ctx *gin.Context, in *struct{}) (any, error) {
    id := ctx.Param("id")
    return userService.DeleteUser(id)
}

This scenario demonstrates how to handle DELETE requests and handle cases with no return value.

For complex scenarios like file downloads or non-CRUD operations, you can use gin.HandlerFunc instead of web.WarpH.

Best Practices

Use structs to define clear input and output parameters, improving code readability
Use tags appropriately, such as json, form, etc.
Add necessary parameter validation
Use pointer types to avoid unnecessary memory allocation
Design APIs following RESTful style

Summary

By using web.WarpH, we can:

Significantly reduce repetitive code
Improve code maintainability
Unify error handling
Enhance development efficiency

This encapsulation approach is particularly suitable for team collaboration, helping teams quickly build high-quality API services.

About goddd

The web.WarpH introduced in this article is a core component of the goddd project. goddd is a Go project based on DDD (Domain-Driven Design) principles, providing a series of tools and best practices to help developers build maintainable and extensible applications.

If you're interested in the content introduced in this article, welcome to visit the goddd project for more details. The project provides complete example code and detailed documentation to help you get started quickly.

Related Resources

GoDDD: Enterprise REST API Development Template

iexu — Fri, 18 Apr 2025 18:25:48 +0000

Introduction

GoDDD is an enterprise-level template focused on REST API development, designed to provide Go developers with a complete CRUD solution. It adopts Domain-Driven Design (DDD) principles and a modular monolithic architecture, enabling developers to quickly start projects and focus on business development.

Why Choose GoDDD?

As a Go developer, have you ever encountered these challenges:

Project structure becomes increasingly difficult to maintain as the business grows
New team members take a long time to understand the project
Frequent code conflicts during team collaboration
Need to write large amounts of similar CRUD code repeatedly
Inconsistent error handling and messy logging
Require extensive infrastructure configuration when starting a project

GoDDD is designed to solve these problems. It provides a clear project structure and a complete development toolchain, including:

Modular project structure for better code organization
Unified error handling and logging
Automated code generation tool godddx

Technical Architecture

Architecture Design Philosophy

In traditional MVC monolithic architecture, as business scale grows, projects become increasingly bloated, leading to reduced team development efficiency and difficulty for new members to quickly understand the system.

GoDDD adopts a modular monolithic architecture that preserves the simplicity of monolithic architecture while incorporating the modular advantages of microservices. By breaking down the business into independent domain modules (such as user domain, banking domain, product domain, etc.), each domain contains a complete set of:

API (Interface Layer)
Core (Business Core)
Store (Data Storage)

This design allows different teams to independently develop and maintain their domain modules, effectively reducing code conflicts and development chaos. Compared to microservices, this modular approach makes the code more concise, easier to test, and maintain.

More importantly, when a domain module's scale exceeds expectations, teams can easily extract it as an independent microservice, achieving smooth architecture evolution.

Technology Stack

Web Framework: Gin
ORM: GORM
Architecture Design: Domain-Driven Design (DDD)
Code Generation: Support for automated code generation
Message Processing: Event bus/transaction messages using NSQite

Project Structure

.
├── cmd               # Executable programs
├── configs           # Configuration files
├── makefile          # Provides build/image/toolchain commands
├── internal          # Private business logic
│   ├── conf          # Configuration models
│   ├── core          # Business domains
|   ├── domain        # Public domains, providing modular components for rapid development
|   ├── data        # Database initialization logic
│   └── web           # Public Web layer
└── pkg               # Dependency libraries

Application Cases

GB/T28181 Video Platform (github.com/gowvp/gb28181)

Conclusion

For junior Go developers, GoDDD provides a clear project structure and complete development toolchain, enabling you to quickly get started with enterprise-level project development. It solves common problems such as messy project structure, difficult team collaboration, and code duplication, allowing developers to focus on business logic implementation.

If you're looking for a framework to help you quickly build enterprise-level REST APIs, GoDDD is definitely worth trying. Its modular design and complete toolchain can significantly improve your development efficiency and code quality.

About GORM AutoMigrate Control for Faster Startup

iexu — Fri, 18 Apr 2025 18:02:21 +0000

What is AutoMigrate?

In Go development, we often need to modify database table structures. The traditional approach involves manually writing SQL statements, which is both tedious and error-prone. GORM's AutoMigrate feature was created to solve this problem, automatically synchronizing code and database structures to make development more efficient.

Why Control AutoMigrate?

Let's look at a real scenario: In the early stages of a project with just 7 tables, AutoMigrate execution takes only 1 second. As features are added and the number of tables grows to 30, startup time extends to 10 seconds. Even worse, every startup requires checking all tables, even when no structural changes have been made - this is clearly inefficient.

Solution: Version Control

goddd introduces a version control mechanism, similar to software updates, where updates are only needed when a new version is released. Implementation details:

Database records the current version number
Program checks code version number at startup
AutoMigrate is only executed when code version number is greater than database version number

How to Modify Version? Code Example

// Set database version (both 0.0.2 and v0.0.2 are acceptable)
versionapi.DBVersion = "0.0.2"
// Add version description to record what was updated
versionapi.DBRemark = "Added user avatar field"

The orm.EnabledAutoMigrate variable can be used to globally control AutoMigrate's enabled state.

What are the Benefits?

Faster program startup by avoiding unnecessary table checks
Reduced database pressure by eliminating redundant operations
Clear tracking of database structure change history

About goddd

github.com/ixugo/goddd is a Go language project template based on Domain-Driven Design (DDD), providing a complete project structure and best practices. It integrates commonly used components like GORM and Gin, making it particularly suitable for quickly starting small to medium-sized projects.

Want to learn more? Check out the goddd source code.

GoTransactional Message Queue: A Lightweight Solution Based on SQLite

iexu — Wed, 16 Apr 2025 20:02:57 +0000

Transactional Message Queue: A Lightweight Solution Based on SQLite

What is a Message Queue?

A message queue is an asynchronous communication mechanism used to pass messages in distributed systems. It works like a "post office" where senders put messages into the queue and receivers take them out for processing. This pattern offers several benefits:

Decoupling: Producers and consumers don't need to communicate directly
Peak Shaving: Can buffer sudden traffic spikes
Asynchrony: Improves system response time
Reliability: Message persistence ensures no data loss

What is a Transactional Message Queue?

The core of a transactional message queue is to ensure atomicity of message publishing. In traditional message queues, if a transaction rolls back, or if the program crashes after transaction completion but before message sending, messages may be lost. Transactional message queues solve these problems through:

Atomicity: Message sending and business operations are in the same transaction - they either both succeed or both fail
Rollback Mechanism: If the transaction fails, messages are automatically rolled back and won't be sent
Durability: Once committed, messages are permanently saved, even if the program crashes

Practical Example: Implementing User Behavior Analysis with NSQite

Let's consider a content platform that needs to record user behavior data (views, likes, favorites, etc.) for later analysis. This behavior data has the following characteristics:

Large volume but not time-critical
Can be retried if processing fails
Doesn't affect core business processes

Using a message queue, we can:

Return success immediately when user behavior occurs
Put behavior data into the message queue
Process data asynchronously (data cleaning, statistical analysis, etc.)

Here's a code example using nsqite:

// Define message handler
type UserActionHandler struct{}

func (h *UserActionHandler) HandleMessage(message *nsqite.Message) error {
    var action struct {
        UserID    string `json:"user_id"`
        Action    string `json:"action"`
        ContentID string `json:"content_id"`
        Timestamp string `json:"timestamp"`
    }
    if err := json.Unmarshal(message.Body, &action); err != nil {
        return err
    }
    // Data cleaning and statistical analysis
    return analyzeUserAction(action)
}

func main() {
    db, err := gorm.Open(sqlite.Open("user_actions.db"), &gorm.Config{})
    if err != nil {
        log.Fatal(err)
    }
    // Set GORM database connection
    nsqite.SetGorm(db)

    const topic = "user_actions"
    // Create producer
    p := nsqite.NewProducer()
    // Create consumer with max retry attempts of 5
    c := nsqite.NewConsumer(topic, "consumer1", nsqite.WithConsumerMaxAttempts(5))
    // Add 5 concurrent handlers
    c.AddConcurrentHandlers(&UserActionHandler{}, 5)

    // Publish message within transaction
    db.Transaction(func(tx *gorm.DB) error {
        // Business operation
        if err := doSomeBusiness(tx); err != nil {
            return err
        }
        // Publish message
        action := map[string]interface{}{
            "user_id":    "123",
            "action":     "view",
            "content_id": "456",
            "timestamp":  time.Now().Format(time.RFC3339),
        }
        body, _ := json.Marshal(action)
        return p.PublishTx(tx, topic, body)
    })


    time.Sleep(5*time.Second)
}

Why Choose NSQite?

NSQite is a message queue implementation based on SQLite with the following features:

Lightweight: Based on SQLite, no additional dependencies
High Performance: Can process millions of messages per second in single-machine environment
Easy Integration: Supports GORM, seamless integration with existing projects
Reliability: Supports transactional messages, ensuring data consistency

Use Cases:

Project Initialization: No need for complex message queue systems
Existing SQLite Projects: No additional dependencies required
Single-Machine Applications: Maintain simplicity, avoid distributed complexity
Resource-Constrained Environments: SQLite's lightweight nature

Project Address

NSQite is an open-source project available on GitHub:
https://github.com/ixugo/nsqite

If you find this project helpful, you can:

Star the project
Submit issues for feedback
Contribute code through PRs

Go Event Bus Best Practices: Implementing Loose Coupling with NSQite

iexu — Wed, 16 Apr 2025 06:54:14 +0000

Event Bus Best Practices: Implementing Loose Coupling with NSQite

What is Event Bus?

Event Bus is a messaging pattern that allows different components of an application to communicate through a publish/subscribe mechanism without direct dependencies. This pattern is particularly suitable for implementing loosely coupled architectural designs.

Why Do We Need Event Bus?

Decoupling: Components communicate through events without direct dependencies
Extensibility: New features can be easily added by subscribing to existing events
Maintainability: Code becomes easier to understand and maintain
Asynchronous Processing: Supports asynchronous message handling, improving system responsiveness

Best Practice Case: User Registration Notification System

Background

Let's assume we're developing an e-commerce system where new user registration requires:

Sending a welcome email
Creating a user points account
Pushing system notifications
Recording user behavior logs

Traditional implementation would result in tight coupling between the registration service and these features, making the code difficult to maintain.

NSQite Solution

// Define event structure
type UserRegisteredEvent struct {
    UserID   string
    Username string
    Email    string
    Time     time.Time
}

// Email service handler
type EmailHandler struct{}

func (h *EmailHandler) HandleMessage(message *EventMessage[UserRegisteredEvent]) error {
    event := message.Body
    // Send welcome email
    return sendWelcomeEmail(event.Email)
}

// Points service handler
type PointsHandler struct{}

func (h *PointsHandler) HandleMessage(message *EventMessage[UserRegisteredEvent]) error {
    event := message.Body
    // Create user points account
    return createUserPoints(event.UserID)
}

// Registration service
const topic = "user.registered"
var publisher = NewPublisher[UserRegisteredEvent]()
func RegisterUser(username, email string) error {
    // Create user
    userID := createUser(username, email)

    // Publish user registration event
    event := UserRegisteredEvent{
        UserID:   userID,
        Username: username,
        Email:    email,
        Time:     time.Now(),
    }

    return publisher.Publish(topic, event)
}

// Main program
func main() {
    // Initialize email subscriber
    const emailChannel = "email"
    emailSub := NewSubscriber(topic, emailChannel)
    emailSub.AddConcurrentHandlers(&EmailHandler{}, 2)

    // Initialize points subscriber
    const pointsChannel = "points"
    pointsSub := NewSubscriber(topic, pointsChannel)
    pointsSub.AddConcurrentHandlers(&PointsHandler{}, 2)

    // Register new user
    RegisterUser("testuser", "test@example.com")
}

Code Explanation

We define a user.registered Topic
Create two Channels: email and points
Each Channel has independent subscribers with different concurrency levels
When publishing a message, it's replicated to all Channels
Subscribers in each Channel process messages independently

Advantages

Decoupling: Registration service doesn't need to know specific notification logic
Extensibility: Adding new notification methods only requires new consumers
Reliability: NSQite guarantees at-least-once message delivery
Performance: Supports concurrent processing, improving system throughput

Summary

NSQite Event Bus Design Principles

NSQite consists of two parts: Event Bus and Transactional Message Queue. The design is inspired by NSQ's philosophy. The Event Bus is suitable for monolithic architectures, while the Transactional Message Queue is ideal for early-stage projects where you might not need large message queue systems like NSQ or Pulsar.

It implements a two-level message distribution mechanism with Topic and Channel:

Topic: Message classification, where one Topic can contain multiple Channels
Channel: Messages are replicated to all Channels
Subscriber: Subscribers can start concurrent goroutines to process channel messages quickly

Core advantages of this design:

Messages can be processed in parallel by multiple types of consumers
Each Channel can independently set its concurrency level
Supports both broadcast and point-to-point communication
Implements simple load balancing

Using github.com/ixugo/nsqite to implement the Event Bus pattern helps us build more flexible and maintainable system architectures. If you find this project helpful, please give it a Star!

Project URL: https://github.com/ixugo/nsqite