API RESTful Golang dengan Gin, Gorm, PostgreSQL

Contoh komprehensif perkhidmatan Golang RESTful API yang menggunakan gin untuk penghalaan, gorm untuk ORM dan PostgreSQL sebagai pangkalan data. Contoh ini termasuk ciri PostgreSQL berikut: pangkalan data dan penciptaan jadual, pemasukan dan pertanyaan data, pengindeksan, fungsi dan prosedur tersimpan, pencetus, paparan, CTE, urus niaga, kekangan dan pengendalian JSON.

1. Persediaan Projek

Dengan mengandaikan anda mempunyai PostgreSQL, Golang, dan pergi mod persediaan, mulakan projek:

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

Struktur projek

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

2. Pasang Ketergantungan

Pasang pakej yang diperlukan:

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

3. Skema PostgreSQL

Berikut ialah skrip SQL untuk mencipta skema pangkalan data:

-- 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 $$
    --  is a placeholder for the first input. When the function is executed, PostgreSQL replaces  with the actual user_id value that is passed in by the caller.
    SELECT COUNT(*) FROM borrow_logs WHERE user_id = ;
$$ 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. Kod Golang

Berikut ialah contoh lengkap API RESTful menggunakan Gin dan 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)
}

Penjelasan Kod Golang:

• Permulaan Pangkalan Data: Menyambung ke pangkalan data PostgreSQL dan memulakan GORM.
• Laluan: Mentakrifkan laluan untuk mencipta pengarang, buku, pengguna, meminjam buku dan mengambil kiraan pinjaman.
• Pengendalian Transaksi: Menggunakan transaksi semasa meminjam buku untuk memastikan konsistensi.
• Pramuat: Menggunakan Pramuat GORM untuk menyertai jadual yang berkaitan (pengarang dengan buku).
• Panggilan Prosedur Tersimpan: Menggunakan db.Raw untuk memanggil fungsi PostgreSQL tersuai untuk mengira kiraan pinjaman.

5. Menjalankan API

• Jalankan skrip SQL PostgreSQL untuk membuat jadual, indeks, paparan, fungsi dan pencetus.

• Mulakan pelayan Golang menggunakan
  

   go run main.go
  

Kini, anda mempunyai Golang RESTful API yang komprehensif yang merangkumi pelbagai ciri PostgreSQL, menjadikannya contoh teguh untuk pembelajaran atau temu duga.

6. Menambah beberapa lagi ciri.

Mari tingkatkan contoh Golang RESTful API dengan ciri PostgreSQL tambahan dengan memasukkan Paparan, CTE (Ungkapan Jadual Biasa), pengindeksan teks penuh dan Pengendalian JSON. Setiap ciri ini akan ditunjukkan dengan takrif jadual PostgreSQL yang berkaitan dan kod Golang untuk berinteraksi dengannya.

Skema Data untuk bahagian ini sudah disediakan dari bahagian terakhir, jadi kami hanya perlu menambah lebih banyak kod golang.

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

Ringkasan Ciri:

• Paparan: Permudahkan akses kepada data dengan paparan user_borrow_history, menjadikan gabungan kompleks lebih mudah untuk ditanya.
• CTE: Gunakan WITH klausa untuk pertanyaan teratur seperti mengambil log pinjaman aktif.
• Indeks Teks Penuh: Tingkatkan keupayaan carian pada buku dengan indeks GIN pada to_tsvector.

• Pengendalian JSON:

  • Simpan dan kemas kini metadata kaya menggunakan jenis JSONB.
  • getBookTags mendapatkan semula medan JSON tertentu (teg) daripada lajur JSONB metadata.
  • updateBookPageCount mengemas kini atau menambah medan page_count dalam lajur JSONB metadata.

  Dengan menggunakan db.Raw dan db.Exec untuk SQL mentah dengan GORM, anda boleh memanfaatkan ciri berkuasa PostgreSQL sambil mengekalkan keupayaan ORM GORM untuk bahagian lain aplikasi anda. Ini menjadikan penyelesaian itu fleksibel dan kaya dengan ciri.

7. Ciri lanjutan lain

Dalam contoh lanjutan ini, saya akan menunjukkan cara untuk menyepadukan ciri berikut menggunakan Golang dan PostgreSQL:

1. VACUUM: Digunakan untuk menuntut semula storan yang diduduki oleh tupel mati dan mengelakkan kembung meja.
2. MVCC: Konsep yang membenarkan transaksi serentak dengan mengekalkan versi baris yang berbeza.
3. Fungsi Tetingkap: Digunakan untuk melakukan pengiraan merentas set baris jadual yang berkaitan dengan baris semasa.

1. Menggunakan VACUUM di Golang

VACUUM biasanya digunakan sebagai tugas penyelenggaraan, bukan terus daripada kod aplikasi. Walau bagaimanapun, anda boleh menjalankannya menggunakan Exec GORM untuk tujuan pengemasan:

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

• VACUUM ANALYZE buku: Menuntut semula storan dan mengemas kini statistik yang digunakan oleh perancang pertanyaan untuk jadual buku.
• Menjalankan VACUUM biasanya dilakukan pada waktu luar puncak atau sebagai sebahagian daripada skrip penyelenggaraan dan bukannya pada setiap permintaan.

2. Memahami MVCC (Multi-Version Concurrency Control)

MVCC PostgreSQL membenarkan urus niaga serentak dengan mengekalkan versi baris yang berbeza. Berikut ialah contoh cara menunjukkan gelagat MVCC di Golang menggunakan transaksi:

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

• UNTUK KEMASKINI: Mengunci baris yang dipilih untuk kemas kini semasa urus niaga, menghalang transaksi lain daripada mengubah suainya sehingga yang semasa selesai.
• Ini memastikan ketekalan semasa akses serentak, mempamerkan cara MVCC membenarkan bacaan serentak tetapi mengunci baris untuk kemas kini.

3. Menggunakan Fungsi Tetingkap dengan GORM

Fungsi tetingkap digunakan untuk melakukan pengiraan ke atas set baris jadual yang berkaitan dengan baris semasa. Berikut ialah contoh menggunakan fungsi tetingkap untuk mengira jumlah buku yang dipinjam untuk setiap pengarang:

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

• SUM(COUNT(bl.id)) OVER (PARTITION BY a.id ORDER BY bl.borrowed_at): Fungsi tetingkap yang mengira jumlah berjalan buku yang dipinjam untuk setiap pengarang, dipesan mengikut tarikh borrowed_at.
• Ini boleh memberikan cerapan seperti cara aliran peminjaman berubah dari semasa ke semasa untuk setiap pengarang.

Atas ialah kandungan terperinci API RESTful Golang dengan Gin, Gorm, PostgreSQL. Untuk maklumat lanjut, sila ikut artikel berkaitan lain di laman web China PHP!