
Hey guys, it's Sam Zhang.

So in the previous post we finished a simple Hello World request using Golang and Gin. Today it's time for us to build something more complex - CRUD with Gin!

## Table of Contents

- [Getting started](#getting-started)
- [Installing GORM](#installing-gorm)
- [Defining database models](#defining-database-models)
- [Connecting to database](#connecting-to-database)
- [RESTful APIs](#restful-apis)
  - [Create](#api-create)
  - [Read](#api-read)
  - [Update](#api-update)
  - [Delete](#api-delete)
- [Conclusion](#conclusion)

## Getting started <a name="getting-started"></a>

**This tutorial is made for developers who have some experience in programming but relatively new to Go/Gin. You might want to learn some common programming concepts if you're a total beginner.**

So to start up, you'll need to have the hello world program finished from our last post. Or of course you could clone it from [GitHub](https://github.com/samzhangjy/go-blog/tree/1533c8d1db504b2c7f44c0919cc5f2bc91269d9b) to continue.

Then let's get started!

CRUD stands for **C**reate, **R**ead, **U**pdate and **D**elete. Those are the four basic operations in the database and we will be implementing it into our Go app today.

When dealing with databases, you could just write some plain old SQL commands and execute directly it using the database drivers. But there's a problem with it: SQL injection attack. So using ORMs is normally a better option. We will be using [GORM](https://gorm.io/docs/index.html) throughout this series just because it's popular and easy to get started with.

## Installing GORM <a name="installing-gorm"></a>

As it described in the [docs](https://gorm.io/docs/index.html), simply use `go get gorm.io/gorm` to install it.

However, GORM needs database drivers in order to connect to databases and do operations. I will be using [Postgres](https://www.postgresql.org/) for now and you can use whatever database you wanted.

**Note: Sqlite is not recommended since it doesn't support some complex operations natively. But for now, you can use it since we don't have the need of complex operations and you can migrate to others in the future.**

So let's install the database driver too:

```bash
$ go get -u gorm.io/driver/postgres  # or other database provider
```

...and GORM is ready to use!

## Defining database models <a name="defining-database-models"></a>

Like other ORMs, GORM defines a table using [*models*](https://gorm.io/docs/models.html).

To define a model, you need to declare a [`struct`](https://go.dev/tour/moretypes/2) containing the information about the table. For example:

```go
type <name> struct {
    <field>  <field_type>
}
```

is the most basic form of defining a struct in Go. I assume that you have some basic knowledge about relational database storage so we won't discuss it very much here.

In order to create a GORM model, we simply need to fill in the information required. If we wanted to store a blog post in the database, then the following fields might be helpful:

- ID (unsigned integer, primary key, auto increment, required)
- Title (string, required)
- Content (string, required)
- Created at (time, defaults to current time)

So let's create a model for blog posts based on the above fields:

```go
// models/post.go
package models

import "time"

type Post struct {
	ID        uint      `json:"id" gorm:"primaryKey"`
	Title     string    `json:"title"`
	Content   string    `json:"content"`
	CreatedAt time.Time `json:"created_at"`
}
```

Okay so let me explain all these.

We defined a GORM model using a struct and declared several fields. Here `uint` is `unsigned int` in other languages and `time.Time` is the datetime format in Golang.

But the backticks after the field type might be a little weird for new Go users. Those strings are called [**tags**](https://towardsdev.com/golang-struct-tags-explained-ccb589dcbb98). They are using [backtick annotation](https://stackoverflow.com/questions/46917331/what-is-the-difference-between-backticks-double-quotes-in-golang?rq=1) to define key-value pairs.

> Struct `tags` are small pieces of metadata attached to fields of a `struct` that provide instructions to other Go code that works with the struct.[^1]

The `json` defines with key should the JSON encoder use when serializing the current field into JSON format. And the `gorm` key will let GORM know some extra information about this field. For example, here we defined `ID` as a primary key for the model.

## Connecting to database <a name="connecting-to-database"></a>

So now we successfully created the database schema, let's connect it to a real database:

```go
// models/setup.go
package models

import (
	"gorm.io/driver/postgres"
	"gorm.io/gorm"
)

var DB *gorm.DB

func ConnectDatabase() {
	dsn := "host=localhost user=postgres dbname=go_blog port=5432 sslmode=disable timezone=Asia/Shanghai"
	database, err := gorm.Open(postgres.Open(dsn), &gorm.Config{})  // change the database provider if necessary

	if err != nil {
		panic("Failed to connect to database!")
	}

	database.AutoMigrate(&Post{})  // register Post model

	DB = database
}
```

In function `ConnectDatabase()`, we first defined our data source name and established the database connection. Here I used the Postgres driver and you might change it to fit your own need.

If there's any problems when connecting to our database, `err` will point to the error. In this case, we will call `panic()` to terminate the whole process. `panic()` is a builtin function that acts similar to `raise` in Python and `throw` in JavaScript.

Then we registered our `Post` model to the database and "exported" the database variable.

Note that `DB` is a global variable that is accessible in every file of package `models`, making operations with database easier without importing everything.

...and then let's call the connection function in our `main.go`:

```go
// main.go
package main

import (
	"samzhangjy/go-blog/models"

	"github.com/gin-gonic/gin"
)

func main() {
	router := gin.Default()

	models.ConnectDatabase()  // new!

	// ...

	router.Run("localhost:8080")
}
```

And now we've finally made a connection to the database. Time to code the request controllers!

## RESTful APIs <a name="restful-apis"></a>

Unlike the first post, we are going to put all of our request logic into a separate folder called `controllers` and import them later in `main.go` to define the routes.

### Create <a name="api-create"></a>

Let's start by adding a `create` method:

```go
// controllers/post.go
package controllers

import (
	"net/http"
	"samzhangjy/go-blog/models"

	"github.com/gin-gonic/gin"
)

type CreatePostInput struct {
	Title   string `json:"title" binding:"required"`
	Content string `json:"content" binding:"required"`
}

func CreatePost(c *gin.Context) {
	var input CreatePostInput
	if err := c.ShouldBindJSON(&input); err != nil {
		c.AbortWithStatusJSON(http.StatusBadRequest, gin.H{"error": err.Error()})
		return
	}

	post := models.Post{Title: input.Title, Content: input.Content}
	models.DB.Create(&post)

	c.JSON(http.StatusOK, gin.H{"data": post})
}
```

You might be wondering, why is there `struct` again? Well structs is an important concept in Go and you will see it a lot throughout this series. In this case, our struct `CreateBlogInput` defines body schema for request `CreateBlog`. The new tag `binding` is a Gin validation tag based on [Validator](https://github.com/go-playground/validator). If you wanted to know something about Gin bindings, here's a great read: <https://blog.logrocket.com/gin-binding-in-go-a-tutorial-with-example>.

Then let's focus on `CreateBlog()`. We first validated the request body (variable `input` here) using `context.ShouldBindJSON()`. If the body is invalid, `err` would contain some error messages. If `err` contains something, then we will simply return a 400 HTTP status code and abort the request. This `if err = statement; err != nil {}` statement is a commonly used [error handling technique](https://go.dev/blog/error-handling-and-go#simplifying-repetitive-error-handling) in Go.

If the input is valid, we will first create a `Post` model with data given from the input. Then we will call `database.Create()` to put this record into the Post table.

Finally, we will return HTTP 200 with the newly created post schema if everything goes as expected.

And let's bind our controller to a route:

```go
// main.go
package main

import (
	"samzhangjy/go-blog/controllers"
	"samzhangjy/go-blog/models"

	"github.com/gin-gonic/gin"
)

func main() {
	router := gin.Default()

	models.ConnectDatabase()

	router.POST("/posts", controllers.CreatePost)  // here!

	router.Run("localhost:8080")
}
```

Notice that we're passing the controller function **itself** to `router.POST()`, without parentheses.

Run your app with `air` and use tools like Postman to play around with this endpoint!

### Read <a name="api-read"></a>

Then let's quickly add an endpoint to view every post created:

```go
// controllers/post.go

// ...

func FindPosts(c *gin.Context) {
	var posts []models.Post
	models.DB.Find(&posts)

	c.JSON(http.StatusOK, gin.H{"data": posts})
}
```

Unlike the previous request, this one has no request body. We defined array `posts` to store the posts created with type `models.Post`. `DB.Find(&posts)` means to find every entry that exists in the database and store the fetched result to `posts`. Remember to pass in the **pointer** instead of the actual variable!

And then quickly bind it to our router:

```go
// main.go
package main

import (
	"samzhangjy/go-blog/controllers"
	"samzhangjy/go-blog/models"

	"github.com/gin-gonic/gin"
)

func main() {
	router := gin.Default()

	models.ConnectDatabase()

	router.POST("/posts", controllers.CreatePost)
	router.GET("/posts", controllers.FindPosts)

	router.Run("localhost:8080")
}
```

And now you could see the posts you created using `CreateBlog`!

Then let's create a route that fetches only one specified post by URL param:

```go
// controllers/post.go

// ...

func FindPost(c *gin.Context) {
	var post models.Post

	if err := models.DB.Where("id = ?", c.Param("id")).First(&post).Error; err != nil {
		c.AbortWithStatusJSON(http.StatusNotFound, gin.H{"error": err.Error()})
		return
	}

	c.JSON(http.StatusOK, gin.H{"data": post})
}
```

The new methods here is `DB.Where` and `DB.First`. `DB.Where()` lets you write SQL query commands, replacing the dynamic data with `?` and passing the actual data as the second argument. `DB.First(&post)`, like its name, selects the first name of the given collection of data and stores the result inside `post`.

`context.Param("<param-name>")` is a Gin method to fetch the URL parameter by param name. The param name is defined like:

```go
// main.go
package main

import (
	"samzhangjy/go-blog/controllers"
	"samzhangjy/go-blog/models"

	"github.com/gin-gonic/gin"
)

func main() {
	router := gin.Default()

	models.ConnectDatabase()

	router.POST("/posts", controllers.CreatePost)
	router.GET("/posts", controllers.FindPosts)
	router.GET("/posts/:id", controllers.FindPost)  // here!

	router.Run("localhost:8080")
}
```

The slug starting with a colon `:` is defined as `url parameters` in Gin. The string after the colon is the parameter's name, which we'll use to fetch the param value.

A route `/posts/:id` will match the following:

- `/posts/1`
- `/posts/1/`

But won't match:

- `/posts/1/abcd`
- `/posts/`

### Update <a name="api-update"></a>

Then it's time for updating posts:

```go
// controllers/post.go

// ...

type UpdatePostInput struct {
	Title   string `json:"title"`
	Content string `json:"content"`
}

func UpdatePost(c *gin.Context) {
	var post models.Post
	if err := models.DB.Where("id = ?", c.Param("id")).First(&post).Error; err != nil {
		c.AbortWithStatusJSON(http.StatusNotFound, gin.H{"error": "record not found"})
		return
	}

	var input UpdatePostInput

	if err := c.ShouldBindJSON(&input); err != nil {
		c.AbortWithStatusJSON(http.StatusBadRequest, gin.H{"error": err.Error()})
		return
	}

	updatedPost := models.Post{Title: input.Title, Content: input.Content}

	models.DB.Model(&post).Updates(&updatedPost)
	c.JSON(http.StatusOK, gin.H{"data": post})
}
```

So we defined a struct containing request body schema again, but this time without any validation, since everything is optional. We copied the code to validate if the current post exists from the previous `FindPost()` method.

And if the post exists and the request body is valid, we will define a new model containing the contents of the newly generated post data. In this case, its name is `updatedPost`. Then we will fetch the model for the original post using `DB.Model(&post)` and update is using `model.Updates(&updatedPost)`.

`model.Updates()` will update multiple fields and won't modify the fields that didn't defined in the updated schema (`updatedPost`). `model.Update()` will only update one field at a time.

And bind it to the router:

```go
// main.go
package main

import (
	"samzhangjy/go-blog/controllers"
	"samzhangjy/go-blog/models"

	"github.com/gin-gonic/gin"
)

func main() {
	router := gin.Default()

	models.ConnectDatabase()

	router.POST("/posts", controllers.CreatePost)
	router.GET("/posts", controllers.FindPosts)
	router.GET("/posts/:id", controllers.FindPost)
	router.PATCH("/posts/:id", controllers.UpdatePost)

	router.Run("localhost:8080")
}
```

### Delete <a name="api-delete"></a>

And finally here comes the `DELETE` operation at last:

```go
// controllers/post.go

// ...

func DeletePost(c *gin.Context) {
	var post models.Post
	if err := models.DB.Where("id = ?", c.Param("id")).First(&post).Error; err != nil {
		c.AbortWithStatusJSON(http.StatusNotFound, gin.H{"error": "record not found"})
		return
	}

	models.DB.Delete(&post)
	c.JSON(http.StatusOK, gin.H{"data": "success"})
}
```

And we need to ensure that the currently given post ID is valid. Then we will call `DB.Delete(&post)` to delete the `post` entry from our database.

Then finally, bind it to our router:

```go
// main.go
package main

import (
	"samzhangjy/go-blog/controllers"
	"samzhangjy/go-blog/models"

	"github.com/gin-gonic/gin"
)

func main() {
	router := gin.Default()

	models.ConnectDatabase()

	router.POST("/posts", controllers.CreatePost)
	router.GET("/posts", controllers.FindPosts)
	router.GET("/posts/:id", controllers.FindPost)
	router.PATCH("/posts/:id", controllers.UpdatePost)
	router.DELETE("/posts/:id", controllers.DeletePost)

	router.Run("localhost:8080")
}
```

Congrats! You've successfully built a collection of simple but working CRUD restful API routes! Play it around and try to modify some parts or add some new operations!

## Conclusion <a name="conclusion"></a>

This is Part 2 of my learning Go web development. I actually learned a lot from writing this series and if there's any mistakes in the post, plz point them out!

I uploaded all the source code used in this post to [GitHub](https://github.com/samzhangjy/go-blog/tree/efc3ca87db71b3c954e894534aa4893b5fec8353). Feel free to clone it and play around with it!

I'm Sam Zhang and I'll see you guys next time!

[^1]: From [[Golang] Struct Tags explained](https://towardsdev.com/golang-struct-tags-explained-ccb589dcbb98).

Restful CRUD with Golang for beginners


Hey guys, I'm Sam Zhang.

Today I wanted to explore the field of backend development - so I chose Go. The main reason I chose Go instead of other languages (such as Java), is because Go is kinda a new language (at least in my opinion) .

And sadly, I have absolutely no experience in Go development before. So I started this series of blog in order to keep track on myself. I will try to "record" what I've done and write some main concepts in my posts.

Of course, because I'm still a beginner (or newbie?) in Go, so there might be some incorrect stuff here. If so, please leave me a comment to help me improve!

Then let's get started!

## Installing Go

Unlike many other languages, installing Go is quite simple, at least for me.

Go ahead and download the official installer at the [Go download page](https://go.dev/dl). Run it, then you're all set!

Go comes with its command line tool `go` by default. It includes a set of commands such as `run`, `get`, `mod`, etc. For sure, I'm going to use those command a lot in this series. Check out the full list of commands [here](https://pkg.go.dev/cmd/go).

## Installing Gin

I Googled about which Go web framework is the best for beginners, but turned out to be not that helpful. However, a lot of them mentioned [**Gin**](https://gin-gonic.com/) and has almost 60k stars on [GitHub](https://github.com/gin-gonic/gin). So I chose Gin as my framework to get started.

Create a new folder to contain your project and follow the [instructions](https://gin-gonic.com/docs/quickstart/#installation) of installation.

### Troubleshooting

If you're a total beginner like me, you might be facing the following problem when running `go get`:

```bash
$ go get -u github.com/gin-gonic/gin
go: go.mod file not found in current directory or any parent directory.
        'go get' is no longer supported outside a module.
        To build and install a command, use 'go install' with a version,
        like 'go install example.com/cmd@latest'
        For more information, see https://golang.org/doc/go-get-install-deprecation
        or run 'go help get' or 'go help install'.
```

This means that you don't have a module created in the current folder. `go mod` is a command for managing Go modules. We'll use `go mod init` command to generate a new module.

The `go mod init` command accepts one argument, *module-path* . I'm not so sure about this argument right now and I understand it like the name of the module. The format of *module-path* should be as follows:

```
lorem/ipsum/dor
```

Then run `go mod init <module-path>` , replacing `<module-path>` with your own module path. After that, you should be able to install `gin-gonic` correctly.

## Writing the first Gin request

So now we're all set with environments. Let's write a simple "Hello World" request in Go.

Create a new file named `main.go` in the root folder and fill in the following code:

```go
package main

import (
	"net/http"

	"github.com/gin-gonic/gin"
)

func main() {
	router := gin.Default()  // router with default middleware installed
	// index route
	router.GET("/", func(c *gin.Context) {
		c.JSON(http.StatusOK, gin.H{
			"message": "Hello World",
		})
	})
	// run the server
	router.Run()
}
```

Then run `go run main.go` and open up <http://localhost:8080> . Hopefully a Hello World will come up all right:

```json
{
    "message": "Hello World"
}
```

### Understanding the Hello World code

So... what the hell is going on here? Let's take a look at our code.

We've declared package `main` and imported some useful packages to our code. I'll try my best to explain code in `main()` function line by line.

So on line 10 we've declared a variable called `router`. `gin.Default` returns a router with default middleware (stuff like Logger and Recovery middleware) attached. You might be wondering, what in the world is `:=` ? Well, it's similar to `=` in other programming languages. In Golang, a single `=` means **assignment** and `:=` means **declare and assignment**. E.g:

```go
var router = gin.Default()
```

Is equivalent to:

```go
router := gin.Default()
```

The `:=` operator is called [**Short variable declarations**](https://go.dev/ref/spec#Short_variable_declarations). More information see [this StackOverflow question](https://stackoverflow.com/questions/17891226/difference-between-and-operators-in-go).

On line 12 ~ 16, we defined a GET request mapping to `/` and returns a JSON response. `router.GET()`, of course, defines a GET request. Its second argument accepts a callable function whereas that function will receive an argument with type `gin.Context`.

The context variable is named `c` in this case. `*gin.Context` is a pointer to the `gin.Context` value. The contexts in Gin provides a lot of features such as middleware and responses. For Chinese readers, you can take a look at [this article](https://www.topgoer.com/gin%E6%A1%86%E6%9E%B6/gin%E6%BA%90%E7%A0%81%E8%A7%A3%E8%AF%BB/gin%E7%89%9B%E9%80%BC%E7%9A%84context.html) for a more in-depth view of `gin.Context`.

On line 13 we called `c.JSON()` to response this request with content whose MIME type is `application/json`. `http.StatusOK` is a constant variable for the HTTP status code `200 success`, which is from the builtin package `net/http`.

`gin.H` is a short-handed version of defining type for JSON data. If you'd like to nest JSON objects inside JSON objects, you can write something like:

```go
gin.H{
    "some-data": gin.H{
        "message": "success"
    }
}
```

And finally on line 18, we run the server on the default port 8080.

### Live reloading

Now if you wanted to change the content of your Go application, you need to restart the development server every time you change something in order to test the newly added code.

So some web frameworks (such as Python Flask) has a builtin hot reloader for the development server. Unfortunately, Gin doesn't come with that. I chose to use [air](https://github.com/cosmtrek/air) as my auto reloader and of course you can use others.

Setting up Air is quite simple. Run the following command to install it:

```bash
curl -sSfL https://raw.githubusercontent.com/cosmtrek/air/master/install.sh | sh -s -- -b $(go env GOPATH)/bin
```

This will install Air to your `$GOPATH`, which is default to `~/go` . Then append it to your `$PATH` by adding the following line to your `.bashrc` (or `.zshrc`):

```bash
export PATH=$PATH:$(go env GOPATH)/bin
```

...and you're all set! Run `air init` to generate a default Air configuration.

Using Air is even simpler. Just run `air` in your command line and Air run `main.go` in the current folder and will automatically watch for changes in your source code.

> Tip for macOS users: if you don't want to see the annoying popup every time Air reloads your code, simply replace

```go
router.Run()
```

with

```go
router.Run("localhost:8080")
```

## Conclusion

So... I finally finished the Gin hello world! I put all my source code to [GitHub](https://github.com/samzhangjy/go-blog) and hopefully I will be updating it. Clone it if you found something useful or just to play around!

I'm Sam Zhang and I'll see ya next time!

标签 golang

标签为 golang 的文章

Restful CRUD with Golang for beginners

Learning Go Web Development From Zero

Sam Zhang.