
## 前言

Rollup 是我在重构 [TNT.js](https://github.com/Bug-Duck/tntjs/tree/dev) 这个玩具框架时忽然发现的一个构建工具。因为需要升级整个 codebase 到 ES Modules ，所以一个好的构建工具十分重要。但是，这个项目之前用的“构建工具”就是把 TypeScript 编译成 JavaScript ，可变性并不强。在尝试使用 Webpack 的时候，我无论如何也没办法让编译产物通过 HTML 的 `script` 标签导入到页面中（这个项目是一个小前端框架，要能够在浏览器中运行，就必须使用 `script` 标签倒入，没有打包 HTML）。

然后在一位大佬的指引下，我发现了 [Rollup.js](https://github.com/rollup/rollup) ，原生支持 ESM ，感觉十分不错。于是，就诞生了这篇文章！

## 安装

```bash
$ npm i -g rollup
```

## 配置 Rollup

跟 Webpack 一样，Rollup 也用一个独立的 JS 配置文件存放自己的运行设置。在 Rollup 里，配置文件的名字是 `rollup.config.js` 。

我在这个项目里使用的配置文件长这样：

```js
import alias from "@rollup/plugin-alias";
import resolve from "@rollup/plugin-node-resolve";
import typescript from "@rollup/plugin-typescript";
import serve from "rollup-plugin-serve";

export default {
  input: "src/index.ts",
  preserveModules: true,
  treeshake: false,
  output: {
    format: "esm",
    sourcemap: true,
    dir: "./dist",
    name: "TNT"
  },
  plugins: [
    alias({
      entries: [
        { find: "runtime", replacement: "src/runtime" },
        { find: "plugins", replacement: "src/plugins" },
      ],
    }),
    resolve(),
    typescript(),
    serve(),
  ],
};
```

Rollup 也支持许多的插件，比如我这里用的 `plugin-alias` ，就是把 Webpack 里面的 `alias` 配置项移植了过来。这里需要注意，Rollup 原生并不支持 TypeScript ，需要单独安装 `@rollup/plugin-typescript` 插件才能使用。

我还是用了 `plugin-node-resolve` ，这个插件是用来解析导入 `node_modules` 中的模块的。最后的 `rollup-plugin-serve` 的作用就是在你运行 Rollup 时，自动启动一个开发服务器，提供预览。

在这里，我选用了 ESM 的打包方式，仅仅为了让我这个项目变得好玩点。`output.dir` 指定了输出目录。还需要注意的是，我关闭了摇树优化，因为我需要把所有的东西整体打包，而不是打包特定的部分。但是这带来的坏处就是需要手动检查导入，防止导入未使用的模块。

`preserveModules` 代表保留当前的所有模块，这样我就可以在构建后的代码中使用 `import` 语句了。

配置完了 Rollup 之后，可以用 `rollup -c` 来打包。当然，这样并不会热更新，你还需要指定 `-w` 参数来启动热更新。

至此，Rollup 已经完成了基本配置。但是，为了更好的开发体验，我还需要一个东西来热加载我的 HTML 文件 —— 但是并不是使用 Rollup（当然 Rollup 也支持导入 HTML ，只不过不符合我的需求）。

## 在 HTML 中使用 ESM 并热加载

在 HTML 里导入 ESM 还是比较简单的。在 `<script></script>` 标签上加入 `type="module"` 就行啦。然后，就可以在 `script` 标签里面使用 `import` 语句了：

```html
<script type="module">
  import TNT from "./dist/src/runtime/TNT.js";
  import { Value } from "./dist/src/plugins/tntjsapi-simp/ValueState.js";
  import { Globals } from "./dist/src/runtime/GlobalEnvironment.js";
  import { NumberType } from "./dist/src/runtime/SymbolTable.js";
  import { PluginMain as TemplatePlugin } from "./dist/src/plugins/TemplateLanguage/PluginMain.js";
  import { PluginMain as DebugPlugin } from "./dist/src/plugins/debug/PluginMain.js";
  import { PluginMain as TNTScriptPlugin } from "./dist/src/plugins/tntscript/PluginMain.js";

  window.onload = () => {
    console.log(Globals.getAllPlugins())
    const t = new TNT();
    new Value("testValue", NumberType).setValue(23333)
    console.log(Globals.symbolTable);
  };
</script>
```

需要注意的是，你不需要提前使用 `<script src="dist/xxx" />` 来加载 ESM 文件。

但是，如果你现在打开配置好的 HTML 文件，会得到一个错误：

```
index.html:1 
        
Access to script at 'file:///Volumes/Data/Develop/Nodejs/tntjs/dist/src/runtime/TNT.js' from origin 'null' has been blocked by CORS policy: Cross origin requests are only supported for protocol schemes: http, data, chrome-extension, edge, https, chrome-untrusted.
```

看来是直接使用文件协议传输不受 ESM 的支持。

解决方法就是启动一个热加载服务器来伺服我们的 HTML 文件。我选用了 [live-server](https://github.com/tapio/live-server) 包来解决这个问题。

首先，安装 live-server ：

```
npm install -g live-server
```

然后，就可以在项目目录里直接运行 `live-server` 启动开发服务器啦！现在到 <http://localhost:8080/> 去看看吧。

## 总结

总的来说，Rollup 是一个非常好的构建工具，它可以让我们在编写代码的时候更加简单，省去繁琐的配置过程。但是，它的社区可能还不如 Webpack 成熟，所以目前来说 Webpack 可能略占上风。

最后放一下我一直提到的小项目的 GitHub 吧：<https://github.com/Bug-Duck/tntjs/tree/dev>

欢迎 star & fork ！


Rollup.js 初体验

Hey guys, I'm Sam Zhang.

**Edit: since a lot of you are commenting about it, I would like to mention one thing though that this "portfolio" is just made for fun and not recommended to use in a real world application if you're really looking for a job.**

Recently I've updated my personal website. Originally I used [LogTure](https://github.com/samzhangjy/logture) as my primary website, but I think it's not "cool" enough.

So I started building a cooler one. After Googling around, I decided to make a terminal-like site similar to [yasfu.net](https://yasfu.net/portfolio/) with Vue 3.

Vue 3 is still new to me though. I mainly work on React projects recently and didn't explore the new features introduced in Vue 3. So this time I decided to give it a try. And after struggling with errors, I finally finished this project.

**Demo: <https://samzhangjy.com/>**

**GitHub: <https://github.com/samzhangjy/VueTerm>**

And of course, feel free to report issues to me!

However there're some downsides about this project. One is that the current bash-like command system has some trouble handling complicated paths. So for example, when you type in `cd ../folder/subfolder` will cause an inner failure of `cd`.

Recursive might be a good way to solve this problem and I'll try to implement it into this project in the near future.

And here is the end of the article. Feel free to play around with my project!

I built a terminal-like portfolio with Vue 3


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!

Learning Go Web Development From Zero


此为我在 B 站上发布的视频 [TCP | 你真的懂 HTTP 吗？](https://www.bilibili.com/video/BV1RU4y1R7Kv) 的文字稿。

<iframe src="//player.bilibili.com/player.html?aid=682385745&bvid=BV1RU4y1R7Kv&cid=554442259&page=1" scrolling="no" border="0" frameborder="no" framespacing="0" allowfullscreen="true"> </iframe>

## 前言

Hello 大家好，我是 Sam Zhang。

HTTP 相信是每个 Web 开发者都耳熟能详的名词了。但是，新手开发者想要完全理解 HTTP 协议却需要时间。这期视频，我就来带大家入门 HTTP 协议。

话不多说，我们直接进入正题！

## TCP / IP 模型

在真正讲解 HTTP 协议之前，我们先来看一下更为底层的 TCP / IP 模型。

### TCP / IP 模型的四个层次

![TCP / IP 模型](https://tva1.sinaimg.cn/large/e6c9d24ely1h09fe7w3qaj208x08xt90.jpg)

正如大家所看到的，TCP / IP 模型分为四层，由下到上依次是：

1. 链路层（Link Layer）
2. 网络层（Internet Layer）
3. 传输层（Transport Layer）
4. 应用层（Application Layer）

#### 链路层

链路层处于 TCP / IP 模型的最底层。它负责管理数据如何与物理媒介进行交互，例如 Wi-Fi 定义了数据如何进行无线传输。

#### 网络层

链路层只能在局域网中工作，而网络层定义了 IP 协议，主要负责寻址操作。

#### 传输层

传输层主要负责提供应用程序接口，为应用程序提供接入网络的途径。除此以外，这一层还出现了端口，也就是客户端与服务器连接的频道。

最主要的是，这一层有可靠传输的 TCP 协议。通过 TCP 协议传输的数据都能保证按照顺序抵达，内容正确且没有重复。大多数网络请求都是通过 TCP 传输的。

#### 应用层

这一层包括了主要为应用软件使用的协议，例如负责文件传输的 FTP 协议，负责电子邮件的 SMTP 协议和负责域名系统的 DNS 等。最经常出现的 HTTP / HTTPS 协议也是在这一层下的，在浏览器中使用非常广泛。WebSocket 协议也同属于这一层。

## HTTP / HTTPS 协议

### 基础概念

![A Web document is the composition of different resources](https://mdn.mozillademos.org/files/13677/Fetching_a_page.png)

> HTTP（**HyperText Transfer Protocol**）是万维网（World Wide Web）的基础协议。自 Tim Berners-Lee 博士和他的团队在1989-1991年间创造出它以来，HTTP已经发生了太多的变化，在保持协议简单性的同时，不断扩展其灵活性。如今，HTTP已经从一个只在实验室之间交换文件的早期协议进化到了可以传输图片，高分辨率视频和3D效果的现代复杂互联网协议。

HTTP 从 HTTP / 0.9 的单行协议演变到现在 HTTP / 2 的数据帧，HTTP 协议在不断地变化并发展着。这个最初从 CERN 实验室中走出来的小东西，最终被几乎所有人每天每刻地使用着。这，就是我们今天的主角 —— HTTP 协议。

HTTP 是一个 client-server 协议。也就是说，请求由客户端发出，被服务器处理后返回一个响应。在这之间，可能存在着许多代理 - 例如网关。这些代理是建立在应用层上的。代理的作用包括缓存，过滤，负载均衡等功能。

### HTTP 设计理念

#### HTTP 是简单的

HTTP 的设计理念是简单易读 —— 这就使得 HTTP 报文能被人类读懂，而不只是机器。

#### HTTP 是可扩展的

请求头的存在使得扩展 HTTP 变得更简单了。只要服务端和客户端对某一个 header 达成一致的语义，那么这个新 header 的功能就可以很轻松被接入进来。

#### HTTP 是无状态，有会话的

HTTP 本身是无状态的。即使在同一连接中，两个请求之间也是没有关系的。但是，通过 Cookies 创建一个会话，就能够让请求共享同样的上下文信息。

也就是说，HTTP 本身是无状态的，但因为 Cookies ，你可以在 HTTP 中创建有状态的会话。

#### HTTP 和连接

HTTP 在底层使用 TCP 传输协议，而不是 UDP 协议 —— 因为 TCP 是可靠的，不丢失消息的。

#### 数据 URL

数据 URL 是一种特殊的 URL 。他使用 `data:` 协议，允许嵌入小文件。

它的定义形式如下：

```
data:[<mediatype>][;base64],<data>
```

其中 `mediatype` 是一个 MIME 类型的字符串，用于判断数据的类型。默认为 `text/plain;charset=US-ASCII` ，即 ASCII 编码的纯文本文档。

除此以外，你还可以选择使用 `base64` 编码来存储数据。这在存储二进制文件（例如视频和图片）时非常有用。加入 `;base64` 标识符即可存储 base64 数据。

例如，`data:,Hello%20World!` 就是一个纯文本类型数据，而 ``data:text/plain;base64,SGVsbG8sIFdvcmxkIQ%3D%3D`` 则是刚刚 Hello World 的 `base64` 形式。

除此以外，还有几点注意事项：

1. 虽然 Firefox 支持无限长度的 `data` URLs，但是标准中并没有规定浏览器必须支持任意长度的 `data`URIs。比如，Opera 11浏览器限制 URLs 最长为 65535 个字符，这意味着 data URLs 最长为 65529 个字符。
2. 因为数据 URL 是没有结束标记的，所以如果你尝试使用 Query String 添加查询字符串会导致浏览器认为加入的查询字符串也是数据的一部分。
3. data URL 的格式虽然很简单，但 `<data>` 前面的逗号 `,` 却很容易被人忽略，从而导致错误。

#### MIME 类型

MIME（**Multipurpose Internet Mail Extensions**）类型，又称媒体类型，用来表示特定数据的性质和格式。

一个 MIME 类型的结构很简单：

```
type/subtype
```

其中 `type` 代表类别，`subtype` 代表子类别。注意，MIME 类型中不允许空格存在。

虽然 MIME 类型不区分大小写，但传统写法都是小写。

常见的类型有 `text` , `image` , `audio` , `video` , `application` 等。每个类别下还有不同的子类别，可谓种类繁多，绝对能找到你想要的。

刚才说的那几个类型都是**独立**类型，还有另外一种 Multipart 类型。它通常在 HTML 表单中出现，类型是 `multipart/form-data` 。

更详细的 MIME 类型表可以在 [MDN](https://developer.mozilla.org/zh-CN/docs/Web/HTTP/Basics_of_HTTP/MIME_types) 中找到。

### 请求

一个典型的 HTTP 请求应该包括以下几个部分：

1. 请求行
2. 请求头
3. 请求体，如果有的话

#### 请求行

HTTP 请求的启始行叫做请求行。它由下面几个部分组成：

```
<命令> <路径> <版本>
```

例如：`GET /user/register.html HTTP/1.1`

1. `<命令>` ：是 HTTP 请求方式的其中之一，常见的有 `GET` 、`POST` 、`PUT` 等。
2. `<路径>` ：要获取的资源等路径，通常是上下文中就很明显的元素资源的 URL 。*需要注意的是，它没有 `protocol`（`https://`），`domain`（`samzhangjy.github.io`），抑或是 TCP 协议的 `port`（`80`）。*
3. `<版本>` ：HTTP 协议版本号。

#### 请求头

请求头是一行不区分大小写的字符串。它遵循如下规范：

```
<请求头名称>: <请求头值>
```

举个栗子：

```
Accept-Language: zh-CN, en-US
```

这个 header 表示客户端接受简体中文和英文。HTTP 协议支持许多不同的请求头，大致分类有：

- [General headers](https://developer.mozilla.org/zh-CN/docs/Glossary/General_header)：同时适用于请求和响应消息，但与最终消息主体中传输的数据无关的消息头。
- [Request headers](https://developer.mozilla.org/zh-CN/docs/Glossary/Request_header)：包含更多有关要获取的资源或客户端本身信息的消息头。
- [Response headers](https://developer.mozilla.org/zh-CN/docs/Glossary/Response_header)：包含有关响应的补充信息，如其位置或服务器本身（名称和版本等）的消息头。
- [Entity headers](https://developer.mozilla.org/zh-CN/docs/Glossary/Entity_header)：包含有关实体主体的更多信息，比如主体长度 (Content-Length) 或其 MIME 类型。

完整的列表可在 [MDN](https://developer.mozilla.org/zh-CN/docs/Web/HTTP/Headers) 查看。

#### 请求体

不是所有的请求都必须有请求体：获取数据的请求，例如 `GET` , `HEAD` , `DELETE` , `OPTIONS` 等，通常都不需要请求体。某些请求可能需要上传数据到服务器（最典型的例子就是 `POST` 请求），就需要有请求体来装载数据，例如 `FormData` 。

请求体可以大致分为两种：

- Single-resource bodies，由一个单文件组成。该类型的请求体由两个 header 定义：`Content-Type` 和 `Content-Length` 。
- Multiple-resouce bodies，由多部分 body 组成，每一部分包含不同的信息位，通常和 HTML 表单数据结合在一起。

### 响应

HTTP 响应，跟 HTTP 请求一样，分为三个部分：状态行，响应头和响应体。

#### 状态行

HTTP 响应的第一行就是状态行（status line）。它的模式是：

```
<版本> <状态码> <状态文本>
```

例如：`HTTP/1.1 200 OK` 。

1. `<版本>` ：协议版本，通常情况下是 `HTTP/1.1` 。
2. `<状态码>` ：表明请求的状态，成功还是失败等。常见的有 200 ，404 ，403 等。
3. `<状态文本>` ：一条描述当前状态码的简短明确的文本。

#### 响应头

跟 HTTP 请求头的格式完全一样，HTTP 响应头也不区分大小写并使用逗号和冒号分割数据。整个 header（包括其值）表现为单行形式。

有许多响应头可用，这些响应头可以分为几组：

- *General headers*，例如 [`Via`](https://developer.mozilla.org/zh-CN/docs/Web/HTTP/Headers/Via)，适用于整个报文。
- *Response headers*，例如 [`Vary`](https://developer.mozilla.org/zh-CN/docs/Web/HTTP/Headers/Vary) 和 [`Accept-Ranges`](https://developer.mozilla.org/zh-CN/docs/Web/HTTP/Headers/Accept-Ranges)，提供其它不符合状态行的关于服务器的信息。
- *Entity headers*，例如 [`Content-Length`](https://developer.mozilla.org/zh-CN/docs/Web/HTTP/Headers/Content-Length)，适用于请求的 body。显然，如果请求中没有任何 body，则不会发送这样的头文件。

更多响应头可以在 [MDN](https://developer.mozilla.org/zh-CN/docs/Web/HTTP/Headers) 找到。

#### 响应体

响应体是可选的，例如有着 HTTP 状态码 201 或 204 的请求大多数情况下不会有响应体。

常用的 Single-resource bodies 响应体可分为两类：

- 由已知长度的单个文件构成的，由 `Content-Type` 和 `Content-Length` 响应头定义。
- 由未知长度的单个文件构成的，通过将 `Transfer-Encoding` 设为 `chunked` 来使用 chunks 编码传输。

属此以外，还有 Multiple-resource bodies ，由多部分响应体组成，每部分包含不同的信息段，但十分少见。

### HTTP / 2

HTTP / 2 修复了 HTTP / 1.1 的许多性能问题：例如在 HTTP / 2 中，可以压缩 header 了。如果你想用 HTTP / 2 协议，你完全不需要更改你的任何 API - 当用户的浏览器和你的服务器都支持 HTTP / 2 时，它会自动取代 HTTP / 1.1 。

如果你想要了解 HTTP / 2 的具体优化，请参考 [MDN](https://developer.mozilla.org/zh-CN/docs/Web/HTTP/Messages#http2_帧) 。

### 认证

![img](https://tva1.sinaimg.cn/large/e6c9d24ely1h0anyizllbj20jq09b3yw.jpg)

一个初始 HTTP 请求是不包括任何认证信息的，可以被认为是一个匿名请求。当服务器接收到此请求且客户端要访问的路由是受保护的，服务器就会返回 401 状态码，并使用 `WWW-Authenticate` 响应头告知客户端需要进行相应的认证。下面是它的语法形式：

```
WWW-Authenticate: <type> realm=<realm>
```

其中，`<type>` 表示验证方案（例如 `Basic` ）。`<realm>` 是一段用于描述进行保护区域的文字，例如 Access to the staging site ，使用户能够知晓他们正在访问的空间。

这时，当客户端（浏览器）接收到此消息后，会弹出密码框，让用户输入密码。输入完成后，客户端将所获的认证信息通过 `Authorization` 请求头传回服务器。

服务器验证当前认证信息后，会根据实际情况返回数据。

一个最基础的 HTTP 认证方式是 Basic 认证方式（基本验证方案）。

#### Basic Authentication

基本验证方案使用用户的 ID 或密码作为认证信息，并使用 base64 算法对其进行编码。

但是，由于 base64 算法的可逆性，基本验证方案并不安全。如果在非 HTTPS 的请求中使用会导致信息泄漏等安全风险。由此，Basic 认证方式不应该用来传输敏感的信息。

### 缓存

HTTP 缓存允许用户复用之前的资源来显著提高性能。

当缓存发现当前请求已经被存储，就会自动拦截请求并返回存储的资源。这跳过了请求源服务器的步骤，大大提升了访问速度。However，不是所有的缓存都是永久不变的：我们需要对缓存的截止时间作出相应的调整，使其不缓存过期的资源。

缓存分为两种，一种是私有的浏览器缓存，另一种是共享的代理缓存。

浏览器缓存，顾名思义，就是将缓存直接存储在浏览器中。而代理缓存，就是在目标服务器和用户之间添加一个代理。它将会把经常访问的资源缓存，并以此减少网络拥堵。

虽然 HTTP 缓存不是必须的，但重用缓存的资源通常是必要的。常见的 HTTP 缓存只能存储 GET 请求的相应，对其他类型的请求稍显无能为力。

客户端可以通过设置 `Cache-Control` 请求头来控制缓存。

`Cache-Control` 的常见取值由 `no-store` , `no-cache` , `max-age=<seconds>` , `must-revalidate` , `private` , `public` 等。

其中，`no-store` 代表不进行任何缓存，`no-cache` 代表缓存但重新验证是否过期，`max-age` 代表缓存保持 fresh 状态的最长时间。

更详细的缓存的信息可以在 [MDN](https://developer.mozilla.org/zh-CN/docs/Web/HTTP/Caching) 找到。

### Cookie

正如我们一开始所说的，HTTP 是无状态的。但是我们可以通过 Cookies 创建有状态的会话。

服务端可以直接使用 `Set-Cookie` 响应头来给客户端发送 Cookie 信息。一个最基础的 Cookie 可以这样设置：

```
Set-Cookie: <name>=<value>
```

客户端会将服务器给定的值存储到本地。Cookies 一旦存储，每次请求客户端都会发送 `Cookies` 请求头给服务器：

```
Cookie: <name1>=<value1>; <name2>=<value2>; ...
```

#### Cookies 的生命周期

Cookie 的生命周期可以通过 `Expires` 或 `Max-Age` 设置。E.g:

```
Set-Cookie: fruit=orange; Expires=Wed, 21 Oct 2022 07:28:00 GMT;
```

更多信息请参考 [MDN](https://developer.mozilla.org/zh-CN/docs/Web/HTTP/Cookies) 。

## 参考资料

### 文档

- [TCP/IP四层模型](https://zhuanlan.zhihu.com/p/57936826), [勤劳的小手](https://www.zhihu.com/people/duan-pan-ykjym), 2021.
- [HTTP概述](https://developer.mozilla.org/zh-CN/docs/Web/HTTP/Overview), MDN contributors, 2022.
- [Data URLs](https://developer.mozilla.org/zh-CN/docs/Web/HTTP/Basics_of_HTTP/Data_URIs), MDN contributors, 2022.
- [HTTP响应](https://developer.mozilla.org/zh-CN/docs/Web/HTTP/Messages), MDN contributors, 2022.
- [HTTP基础](https://developer.mozilla.org/zh-CN/docs/Web/HTTP/Basics_of_HTTP/MIME_types), MDN contributors, 2022.
- [HTTP缓存](https://developer.mozilla.org/zh-CN/docs/Web/HTTP/Caching), MDN contributors, 2022.
- [HTTP Cookies](https://developer.mozilla.org/zh-CN/docs/Web/HTTP/Cookies), MDN contributors, 2022.

### BGM

- [Creative Minds](https://www.bensound.com/royalty-free-music/track/creative-minds), *Benjamin Tissot* .
- [Punky](https://www.bensound.com/royalty-free-music/track/punky), *Benjamin Tissot* .
- [Energy](https://www.bensound.com/royalty-free-music/track/energy), *Benjamin Tissot* .

标签 web

标签为 web 的文章

Rollup.js 初体验

I built a terminal-like portfolio with Vue 3

Restful CRUD with Golang for beginners

Learning Go Web Development From Zero

TCP｜你真的懂 HTTP 吗？

Sam Zhang.