Xây Dựng Golang RESTful API Với Gin, Gorm, PostgreSQL

Ví dụ về Golang RESTful API sử dụng gin cho API, gorm cho ORM, và PostgreSQL cho database. Ví dụ này bao gồm các tính năng cơ bản của PostgreSQL như: database, table creation, data insertion và querying, indexing, functions và stored procedures, triggers, views, CTEs, transactions, constraints, và JSON handling.

1. Khởi tạo project

Giả sử bạn đã cài đặt PostgreSQL, Golang, và go mod :

mkdir library-api
cd library-api
go mod init library-api

Project structure

/library-api
|-- db.sql
|-- main.go
|-- go.mod

2. Cài đặt Dependencies

Cài đặt các packages cần thiết:

go get github.com/gin-gonic/gin
go get gorm.io/gorm
go get gorm.io/driver/postgres

3. PostgreSQL Schema

Dưới đây là script SQL để tạo database schema:

-- Create the library database.
CREATE DATABASE library; -- Connect to the library database.
\c library; -- Create tables.
CREATE TABLE authors ( id SERIAL PRIMARY KEY, name VARCHAR(100) NOT NULL UNIQUE, bio TEXT
); CREATE TABLE books ( id SERIAL PRIMARY KEY, title VARCHAR(200) NOT NULL, -- This creates a foreign key constraint: -- It establishes a relationship between author_id in the books table and the id column in the authors table, ensuring that each author_id corresponds to an existing id in the authors table. -- ON DELETE CASCADE: This means that if an author is deleted from the authors table, all related records in the books table (i.e., books written by that author) will automatically be deleted as well. author_id INTEGER REFERENCES authors(id) ON DELETE CASCADE, published_date DATE NOT NULL, description TEXT, details JSONB
); CREATE TABLE users ( id SERIAL PRIMARY KEY, name VARCHAR(100) NOT NULL, email VARCHAR(100) UNIQUE NOT NULL, created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
); -- CREATE TABLE borrow_logs (
-- id SERIAL PRIMARY KEY,
-- user_id INTEGER REFERENCES users(id),
-- book_id INTEGER REFERENCES books(id),
-- borrowed_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
-- returned_at TIMESTAMP
-- ); -- Create a partitioned table for borrow logs based on year.
-- The borrow_logs table is partitioned by year using PARTITION BY RANGE (borrowed_at).
CREATE TABLE borrow_logs ( id SERIAL PRIMARY KEY, user_id INTEGER REFERENCES users(id), book_id INTEGER REFERENCES books(id), borrowed_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, returned_at TIMESTAMP
) PARTITION BY RANGE (borrowed_at); -- Create partitions for each year.
-- Automatic Routing: PostgreSQL automatically directs INSERT operations to the appropriate partition (borrow_logs_2023 or borrow_logs_2024) based on the borrowed_at date.
CREATE TABLE borrow_logs_2023 PARTITION OF borrow_logs FOR VALUES FROM ('2023-01-01') TO ('2024-01-01'); CREATE TABLE borrow_logs_2024 PARTITION OF borrow_logs FOR VALUES FROM ('2024-01-01') TO ('2025-01-01');
-- Benefit: This helps in improving query performance and managing large datasets by ensuring that data for each year is stored separately. -- Indexes for faster searching.
CREATE INDEX idx_books_published_date ON books (published_date);
CREATE INDEX idx_books_details ON books USING GIN (details);
-- GIN Index (Generalized Inverted Index). It is particularly useful for indexing columns with complex data types like arrays, JSONB, or text search fields -- Add a full-text index to the title and description of books
CREATE INDEX book_text_idx ON books USING GIN (to_tsvector('english', title || ' ' || description));
-- to_tsvector('english', ...) converts the concatenated title and description fields into a Text Search Vector (tsv) suitable for full-text searching.
-- The || operator concatenates the title and description fields, so both fields are indexed together for searching.
-- 'english' specifies the language dictionary, which helps with stemming and stop-word filtering. -- Create a simple view for books with author information.
CREATE VIEW book_author_view AS
SELECT books.id AS book_id, books.title, authors.name AS author_name
FROM books
JOIN authors ON books.author_id = authors.id; -- Create a view to get user borrow history
CREATE VIEW user_borrow_history AS
SELECT u.id AS user_id, u.name AS user_name, b.title AS book_title, bl.borrowed_at, bl.returned_at
FROM users u JOIN borrow_logs bl ON u.id = bl.user_id JOIN books b ON bl.book_id = b.id; -- Use a CTE to get all active borrow logs (not yet returned)
WITH active_borrows AS ( SELECT * FROM borrow_logs WHERE returned_at IS NULL
)
SELECT * FROM active_borrows; -- Function to calculate the number of books borrowed by a user.
-- Creates a function that takes an INT parameter user_id and returns an INT value. If the function already exists, it will replace it.
CREATE OR REPLACE FUNCTION get_borrow_count(user_id INT) RETURNS INT AS $$ -- $1 is a placeholder for the first input. When the function is executed, PostgreSQL replaces $1 with the actual user_id value that is passed in by the caller. SELECT COUNT(*) FROM borrow_logs WHERE user_id = $1;
$$ LANGUAGE SQL;
-- AS $$ ... $$: This defines the body of the function between the dollar signs ($$).
-- LANGUAGE SQL: Specifies that the function is written in SQL. -- Trigger to log activities.
CREATE TABLE activity_logs ( id SERIAL PRIMARY KEY, description TEXT, created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
); CREATE OR REPLACE FUNCTION log_activity() RETURNS TRIGGER AS $$
BEGIN INSERT INTO activity_logs (description) -- NEW refers to the new row being inserted or modified by the triggering event. VALUES ('A borrow_log entry has been added with ID ' || NEW.id); -- The function returns NEW, which means that the new data will be used as it is after the trigger action. RETURN NEW;
END;
$$ LANGUAGE plpgsql;
-- It uses plpgsql, which is a procedural language in PostgreSQL CREATE TRIGGER log_borrow_activity
AFTER INSERT ON borrow_logs
FOR EACH ROW EXECUTE FUNCTION log_activity(); -- Add a JSONB column to store metadata
ALTER TABLE books ADD COLUMN metadata JSONB;
-- Example metadata: {"tags": ["fiction", "bestseller"], "page_count": 320}

4. Golang Code

Dưới đây là một ví dụ hoàn chỉnh về RESTful API sử dụng Gin và GORM:

package main import ( "net/http" "time" "github.com/gin-gonic/gin" "gorm.io/driver/postgres" "gorm.io/gorm"
) type Author struct { ID uint `gorm:"primaryKey"` Name string `gorm:"not null;unique"` Bio string
} type Book struct { ID uint `gorm:"primaryKey"` Title string `gorm:"not null"` AuthorID uint `gorm:"not null"` PublishedDate time.Time `gorm:"not null"` Details map[string]interface{} `gorm:"type:jsonb"`
} type User struct { ID uint `gorm:"primaryKey"` Name string `gorm:"not null"` Email string `gorm:"not null;unique"` CreatedAt time.Time
} type BorrowLog struct { ID uint `gorm:"primaryKey"` UserID uint `gorm:"not null"` BookID uint `gorm:"not null"` BorrowedAt time.Time `gorm:"default:CURRENT_TIMESTAMP"` ReturnedAt *time.Time
} var db *gorm.DB func initDB() { dsn := "host=localhost user=postgres password=yourpassword dbname=library port=5432 sslmode=disable" var err error db, err = gorm.Open(postgres.Open(dsn), &gorm.Config{}) if err != nil { panic("failed to connect to database") } // Auto-migrate models. db.AutoMigrate(&Author{}, &Book{}, &User{}, &BorrowLog{})
} func main() { initDB() r := gin.Default() r.POST("/authors", createAuthor) r.POST("/books", createBook) r.POST("/users", createUser) r.POST("/borrow", borrowBook) r.GET("/borrow/:id", getBorrowCount) r.GET("/books", listBooks) r.Run(":8080")
} func createAuthor(c *gin.Context) { var author Author if err := c.ShouldBindJSON(&author); err != nil { c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()}) return } if err := db.Create(&author).Error; err != nil { c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()}) return } c.JSON(http.StatusOK, author)
} func createBook(c *gin.Context) { var book Book if err := c.ShouldBindJSON(&book); err != nil { c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()}) return } if err := db.Create(&book).Error; err != nil { c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()}) return } c.JSON(http.StatusOK, book)
} func createUser(c *gin.Context) { var user User if err := c.ShouldBindJSON(&user); err != nil { c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()}) return } if err := db.Create(&user).Error; err != nil { c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()}) return } c.JSON(http.StatusOK, user)
} // The Golang code does not need changes specifically to use the partitioned tables; the partitioning is handled by PostgreSQL
// you simply insert into the borrow_logs table, and PostgreSQL will automatically route the data to the correct partition.
func borrowBook(c *gin.Context) { var log BorrowLog if err := c.ShouldBindJSON(&log); err != nil { c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()}) return } tx := db.Begin() if err := tx.Create(&log).Error; err != nil { tx.Rollback() c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()}) return } tx.Commit() c.JSON(http.StatusOK, log)
} func getBorrowCount(c *gin.Context) { userID := c.Param("id") var count int if err := db.Raw("SELECT get_borrow_count(?)", userID).Scan(&count).Error; err != nil { c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()}) return } c.JSON(http.StatusOK, gin.H{"borrow_count": count})
} // When querying a partitioned table in PostgreSQL using Golang, no changes are needed in the query logic or code.
// You interact with the parent table (borrow_logs in this case) as you would with any normal table, and PostgreSQL automatically manages retrieving the data from the appropriate partitions.
// Performance: PostgreSQL optimizes the query by scanning only the relevant partitions, which can significantly speed up queries when dealing with large datasets.
// Here’s how you might query the borrow_logs table using GORM, even though it’s partitioned:
func getBorrowLogs(c *gin.Context) { var logs []BorrowLog if err := db.Where("user_id = ?", c.Param("user_id")).Find(&logs).Error; err != nil { c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()}) return } c.JSON(http.StatusOK, logs)
} func listBooks(c *gin.Context) { var books []Book db.Preload("Author").Find(&books) c.JSON(http.StatusOK, books)
}

Giải Thích sơ lược về golang code:

• Database Initialization: Kết nối tới PostgreSQL database và khởi tạo GORM.
• Routes: Định nghĩa các API routes cho creating authors, books, users, borrowing books, và fetching the borrow count.
• Transaction Handling: Sử dụng transaction cho thao tác borrowing a book để đảm bảo tính nhất quán dữ liệu.
• Preload: Sử dụng Preload của GORM để join related tables (authors với books).
• Stored Procedure Call: Sử dụng db.Raw gọi đến custom PostgreSQL function (store prodecure) để tính số lần mượn sách.

5. Khởi chạy APIs

• Chạy script SQL của PostgreSQL để tạo các bảng, indexes, views, hàm, và triggers.
• Khởi động server Golang bằng lệnh

  go run main.go
  

Lúc này, chúng ta đã có một Golang RESTful API bao gồm các tính năng cơ bản của PostgreSQL.

6. Thêm một số tính năng khác.

Hãy cùng nâng cấp ví dụ Golang RESTful API này bằng cách thêm các tính năng PostgreSQL mới như Views, CTEs (Common Table Expressions), full-text indexing, và JSON handling.

Data Schema cho phần này đã được chuẩn bị từ phần trước, vì vậy chúng ta chỉ cần viết thêm mã Golang.

// Querying the user_borrow_history View:
func getUserBorrowHistory(c *gin.Context) { var history []struct { UserID uint `json:"user_id"` UserName string `json:"user_name"` BookTitle string `json:"book_title"` BorrowedAt time.Time `json:"borrowed_at"` ReturnedAt *time.Time `json:"returned_at,omitempty"` } if err := db.Raw("SELECT * FROM user_borrow_history WHERE user_id = ?", c.Param("user_id")).Scan(&history).Error; err != nil { c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()}) return } c.JSON(http.StatusOK, history)
} // Using a CTE in a Query:
func getActiveBorrows(c *gin.Context) { var logs []BorrowLog query := ` WITH active_borrows AS ( SELECT * FROM borrow_logs WHERE returned_at IS NULL ) SELECT * FROM active_borrows WHERE user_id = ?` if err := db.Raw(query, c.Param("user_id")).Scan(&logs).Error; err != nil { c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()}) return } c.JSON(http.StatusOK, logs)
} // Full-Text Search in books:
func searchBooks(c *gin.Context) { var books []Book searchQuery := c.Query("q") query := ` SELECT * FROM books WHERE to_tsvector('english', title || ' ' || description) @@ plainto_tsquery('english', ?) ` if err := db.Raw(query, searchQuery).Scan(&books).Error; err != nil { c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()}) return } c.JSON(http.StatusOK, books)
} // Handling JSONB Data:
func updateBookMetadata(c *gin.Context) { var metadata map[string]interface{} if err := c.ShouldBindJSON(&metadata); err != nil { c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()}) return } bookID := c.Param("book_id") if err := db.Model(&Book{}).Where("id = ?", bookID).Update("metadata", metadata).Error; err != nil { c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()}) return } c.JSON(http.StatusOK, gin.H{"status": "metadata updated"})
} // Can query a specific field from a JSONB column using the ->> operator to extract a value as text:
func getBookTags(c *gin.Context) { var tags []string bookID := c.Param("book_id") query := `SELECT metadata->>'tags' FROM books WHERE id = ?` if err := db.Raw(query, bookID).Scan(&tags).Error; err != nil { c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()}) return } c.JSON(http.StatusOK, gin.H{"tags": tags})
} // To add or update fields in a JSONB column, use the jsonb_set function:
func updateBookPageCount(c *gin.Context) { bookID := c.Param("book_id") var input struct { PageCount int `json:"page_count"` } if err := c.ShouldBindJSON(&input); err != nil { c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()}) return } query := ` UPDATE books SET metadata = jsonb_set(metadata, '{page_count}', to_jsonb(?::int), true) WHERE id = ?` if err := db.Exec(query, input.PageCount, bookID).Error; err != nil { c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()}) return } c.JSON(http.StatusOK, gin.H{"status": "page count updated"})
}

Tóm Tắt Một Số Tính Năng Vừa Thêm Vào:

• Views: Đơn giản hóa truy cập dữ liệu với user_borrow_history view, giúp việc query các join phức tạp trở nên dễ dàng hơn.

• CTEs: Sử dụng WITH cho việc tổ chức các truy vấn, ví dụ như việc lấy các active borrow logs.

• Full-Text Index: Tăng cường khả năng tìm kiếm trên bảng books vớiGIN index và to_tsvector.

• JSON Handling:

  • Lưu trữ và cập nhật rich metadata với kiểu JSONB.
  • getBookTags lấy một trường JSON cụ thể (tags) từ cột metadata JSONB.
  • updateBookPageCount updates hoặc adds trường page_count vào metadata JSONB column.

  Bằng cách sử dụng db.Raw và db.Exec để chạy raw SQL với GORM, chúng ta có thể tận dụng các tính năng mạnh mẽ của PostgreSQL trong khi vẫn giữ được khả năng của GORM cho các phần khác của ứng dụng. Điều này giúp giải pháp vừa linh hoạt vừa feature-rich.

7. Các tính năng advanced khác

Trong phần này, chúng ta sẽ tích hợp thêm các tính năng sau:

1. VACUUM: Dùng để thu hồi bộ nhớ do các dead tuples và ngăn chặn hiện tượng table bloat.
2. MVCC: Một khái niệm cho phép concurrent transactions bằng cách duy trì các phiên bản khác nhau của các rows.
3. Window Functions: Dùng để thực hiện các tính toán trên một tập hợp các table rows liên quan đến current row.

1. Sử dụng VACUUM trong Golang

VACUUM thường được dùng như một tác vụ maintenance task, chứ không trực tiếp từ application code. Tuy nhiên, bạn có thể chạy nó bằng GORM’s Exec để phục vụ việc bảo trì:

func vacuumBooks(c *gin.Context) { if err := db.Exec("VACUUM ANALYZE books").Error; err != nil { c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()}) return } c.JSON(http.StatusOK, gin.H{"status": "Vacuum performed successfully"})
}

• VACUUM ANALYZE books: Thu hồi bộ nhớ và cập nhật các statistics sử dụng bởi query planner cho books table.
• Việc khởi chạy VACUUMthường được thực hiện định kỳ vào thời gian thấp điểm như là một phần của maintenance script.

2. Tìm hiểu MVCC (Multi-Version Concurrency Control)

MVCC của PostgreSQL cho phép concurrent transactions bằng cách giữ các phiên bản khác nhau của các rows. Dưới đây là một ví dụ minh họa về MVCC behavior trong Golang khi sử dụng transactions:

func updateBookTitle(c *gin.Context) { bookID := c.Param("book_id") var input struct { NewTitle string `json:"new_title"` } if err := c.ShouldBindJSON(&input); err != nil { c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()}) return } // Start a transaction to demonstrate MVCC tx := db.Begin() defer func() { if r := recover(); r != nil { tx.Rollback() } }() var book Book if err := tx.Set("gorm:query_option", "FOR UPDATE").First(&book, bookID).Error; err != nil { tx.Rollback() c.JSON(http.StatusNotFound, gin.H{"error": "Book not found"}) return } // Simulate an update to demonstrate MVCC handling book.Title = input.NewTitle if err := tx.Save(&book).Error; err != nil { tx.Rollback() c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()}) return } // Commit the transaction tx.Commit() c.JSON(http.StatusOK, gin.H{"status": "Book title updated"})
}

• FOR UPDATE: Locks các selected row cho việc updates trong quá tình thực thi transaction, ngăn các transaction khác chỉnh sửa nó cho đến khi transaction hiện tại kết thúc.
• Điều này đảm bảo tính nhất quán (consistency) trong trường hợp concurrent access, chỉ ra MVCC cho phép concurrent reads nhưng lock rows khi thực hiện updates.

3. Sử dụng Window Functions với GORM

Window functions được dùng để thực hiện các tính toán trên một tập hợp các rows của bảng liên quan đến row hiện tại. Dưới đây là một ví dụ về việc sử dụng window function cho việc tính tổng số sách được mượn với mỗi author:

func getAuthorBorrowStats(c *gin.Context) { var stats []struct { AuthorID int `json:"author_id"` AuthorName string `json:"author_name"` TotalBorrows int `json:"total_borrows"` RunningTotal int `json:"running_total"` } query := ` SELECT a.id AS author_id, a.name AS author_name, COUNT(bl.id) AS total_borrows, SUM(COUNT(bl.id)) OVER (PARTITION BY a.id ORDER BY bl.borrowed_at) AS running_total FROM authors a LEFT JOIN books b ON b.author_id = a.id LEFT JOIN borrow_logs bl ON bl.book_id = b.id GROUP BY a.id, a.name, bl.borrowed_at ORDER BY a.id, bl.borrowed_at ` if err := db.Raw(query).Scan(&stats).Error; err != nil { c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()}) return } c.JSON(http.StatusOK, stats)
}

• SUM(COUNT(bl.id)) OVER (PARTITION BY a.id ORDER BY bl.borrowed_at): Window function tính tổng số sách đã được mượn cho mỗi author, và sắp xếp kết quả theo ngày borrowed_at .
• Tác vụ này cung cấp các thông tin như các borrowing trends thay đổi ra sao theo thời gian đối với mỗi author.