Merge pull request #32 from shipengqi/docs/range

docs(go build): update usage of go:build tag

Author: shipengqi

SUMMARY.md

@@ -12,6 +12,7 @@
 - [Go 语言编程之旅](https://golang2.eddycjy.com/)
 - [Go 语言高级编程](https://chai2010.gitbooks.io/advanced-go-programming-book/content/)
 - [Go 夜读](https://github.com/developer-learning/reading-go) 11.6k
+- [Go Tutorial](https://github.com/jincheng9/go-tutorial)
 
 ## 高性能编程
 
@@ -53,4 +54,5 @@
 ## 其他资料
 
 - [learning-golang-awesome](https://github.com/yangwenmai/learning-golang) 2.5k
-    - Go 的学习资料
+    - Go 的学习资料
+- [Go 学习面试指南](https://github.com/mao888/golang-guide) 1.5k

content/docs/practice/01_build.md

@@ -14,10 +14,10 @@ Go 支持两种条件编译方式：
 
 ### 编译标签
 
-编译标签的规则：
+编译标签是以 `// +build` 开头的注释，编译标签的规则：
 
-1. 空格表示：AND
-2. 逗号表示：OR`
+1. 空格表示：OR
+2. 逗号表示：AND
 3. `!` 表示：NOT
 4. 换行表示：AND
 
@@ -26,14 +26,14 @@ Go 支持两种条件编译方式：
 - 操作系统，例如：`windows`、`linux` 等，对应 `runtime.GOOS` 的值。
 - 计算机架构，例如：`amd64`、`386`，对应 `runtime.GOARCH` 的值。
 - 编译器，例如：`gccgo`、`gc`，是否开启 CGO,cgo。
-- Go 版本，例如：`go1.19`、`go1.20` 等。
+- Go 版本，例如：`go1.19` 表示从 从 Go 版本 1.19 起，`go1.20` 表示从 从 Go 版本 1.20 起。
 - 自定义的标签，例如：编译时通过指定 `-tags` 传入的值。
-- `//go:build ignore`，编译时自动忽略该文件
+- `// +build ignore`，表示编译时自动忽略该文件
 
-`go:build` 之后必须有空行，否则会被编译器当做普通注释。
+编译标签之后必须有空行，否则会被编译器当做普通注释。
 
 ```go
-//go:build linux,386 darwin,!cgo
+// +build linux,386 darwin,!cgo
 
 package testpkg
 ```
@@ -51,7 +51,7 @@ go build -tags mytag1 mytag2
 `-tags` 也有 `!` 规则，它表示的是没有这个标签。
 
 ```go
-//go:build !hello
+// +build !hello
 ```
 
 ```bash
@@ -91,13 +91,17 @@ mypkg_windows_amd64.go // only builds on windows 64bit platforms
 - 需要排除某个平台或架构
 - 有一些自定义的编译条件
 
-### +build
+### go:build
 
-`// +build` 功能和 `//go:build` 一样。只不过 `//go:build` 是在 go 1.17 才引入的。目的是为了与其他现有的 Go 指令保持一致，例如 `//go:generate`。
+`//go:build` 功能和 `// +build` 一样。只不过 `//go:build` 是在 go 1.17 才引入的。目的是为了与其他现有的 Go 指令保持一致，例如 `//go:generate`。
+
+规则： 由 `||`、`&&`、`!` 运算符（或、与、非）和括号组成的表达式，`//go:build ignore`，表示编译时自动忽略该文件。
+
+例如 `//go:build (linux && 386) || (darwin && !cgo)`，表示目标系统是 386 的 linux 或者没有启用 cgo 的 darwin 时，当前文件会被编译进来。
 
 ## 交叉编译
 
-Go 可以通过设置环境变量来实现交叉编译，用来在一个平台上生成另一个平台的可执行程序。：
+Go 可以通过设置环境变量来实现交叉编译，用来在一个平台上生成另一个平台的可执行程序：
 
 ```
 #  linux amd64

content/docs/project/01_specs.md

@@ -51,11 +51,8 @@ weight: 1
 
     <!-- 如何提交代码 -->
 
-    ## License
-    
-    <!-- 开源许可证 -->
 
-也可以使用 [readme.so](https://readme.so/)，这是一个快速生成 README 文档的在线工具。
+也可以使用快速生成 README 文档的在线工具 [readme.so](https://readme.so/)。
 
 ### 项目文档
 
@@ -67,6 +64,7 @@ weight: 1
 文档最好包含英文和中文 2 个版本。
 
 文档目录结构示例：
+
 ```
 docs
 ├── dev                              # 开发文档

content/docs/project/04_commitizen.md

@@ -5,7 +5,7 @@ weight: 4
 
 # Commit 规范
 
-多人协作开发一个项目时，每个开发的 Commit Message 五花八门，时间久了，提交的历史变得很难看，而且有的 Commit Message 可能过于简单，可读性较差。
+多人协作开发一个项目时，如果 Commit Message 五花八门，时间久了，提交的历史变得很难看，而且过于简单的 Commit Message，可读性较差。
 
 一个好的 Commit 规范可以使 Commit Message 的可读性更好，并且可以实现自动化。
 
@@ -121,50 +121,7 @@ Closes #123, #245, #992
 可以使用一些开源的工具，来自动生成规范化的 Commit Message：
 
 - [commitizen](https://github.com/commitizen/cz-cli)，Javascript 实现，需要安装 Node.js。
-- [commitizen-go](https://github.com/lintingzhen/commitizen-go)，Go 版本的 commitizen，下载二进制文件就可以直接使用。
-
-上面两个命令都可以进入交互模式，并根据提示生成 Commit Message，然后提交。
-
-### commitizen
-
-#### 安装
-
-```
-$ npm install -g commitizen
-```
-
-#### 使用
-
-
-初始化项目，使用 cz-conventional-changelog 适配器：
-
-```
-# npm
-$ commitizen init cz-conventional-changelog --save-dev --save-exact
-
-# yarn
-$ commitizen init cz-conventional-changelog --yarn --dev --exact
-
-# pnpm
-$ commitizen init cz-conventional-changelog --pnpm --save-dev --save-exact
-```
-
-提交代码：
-
-```
-$ git add .
-# 进入交互模式
-$ git cz
-```
-
-![commitizen](https://raw.githubusercontent.com/shipengqi/illustrations/a6542076c06fd7a2d74ddfcb41ac8d9acf56e405/go/commitizen.gif)
-
-> `git cz` 支持 `git commit` 的所有参数。
-
-git log:
-
-![git-commit-log](https://raw.githubusercontent.com/shipengqi/illustrations/643142bf64ec66adf5cd0bed1fbbe7f67bbcfb45/go/git-commit-log.png)
-
+- Go 版本的 [commitizen](https://github.com/shipegnqi/commitizen)，下载二进制文件就可以直接使用。
 
 ## 自动生成 CHANGELOG
 

content/docs/project/06_api_doc.md

@@ -9,7 +9,8 @@ weight: 6
 
 Swagger 是基于 OpenAPI 规范的 API 文档工具。
 
-> OpenAPI 是一个 API 规范，它的前身就是 Swagger 规范，目前最新的 OpenAPI 规范是 [OpenAPI 3.0](https://swagger.io/docs/specification/about/)（也就是 Swagger 2.0 规范）。
+> OpenAPI 是一个 API 规范，它的前身就是 Swagger 规范，目前最新的 OpenAPI
+> 规范是 [OpenAPI 3.0](https://swagger.io/docs/specification/about/)（也就是 Swagger 2.0 规范）。
 
 ## Swagger 编辑器
 
@@ -37,36 +38,36 @@ commit: ecf6f05b6ecc1b1725c8569534f133fa27e9de6b
 
 `swagger` 提供的子命令：
 
-|  子命令   | 描述  |
-|  ----  | ----  |
-| diff  | 对比两个 swagger 文档的差异 |
-| expand  | 展开 swagger 定义文档中的 $ref |
-| flatten  | 展平 swagger 文档 |
-| generate  | 生成 swagger 文档，客户端，服务端代码 |
-| ini  | 初始化一个 swagger 定义文档 |
-| mix  | 合并 swagger 文档 |
-| serv  | 启动 http 服务，用来查看 swagger 文档 |
-| validate  | 验证 swagger 第一文件是否正确 |
+| 子命令      | 描述                         |
+|----------|----------------------------|
+| diff     | 对比两个 swagger 文档的差异         |
+| expand   | 展开 swagger 定义文档中的 $ref     |
+| flatten  | 展平 swagger 文档              |
+| generate | 生成 swagger 文档，客户端，服务端代码    |
+| ini      | 初始化一个 swagger 定义文档         |
+| mix      | 合并 swagger 文档              |
+| serv     | 启动 http 服务，用来查看 swagger 文档 |
+| validate | 验证 swagger 第一文件是否正确        |
 
 ### 使用
 
 go-swagger 通过解析源码中的注释来生成 Swagger 文档。
 
 注释语法：
 
-|  注释语法   | 描述       |
-|  ----  |----------|
-| swagger:meta  | 定义全局基本信息 |
-| swagger:route  | 定义路由信息   |
-| swagger:parameters  | API 请求参数 |
-| swagger:response  | API 响应参数 |
-| swagger:model  | 可以复用的 Go 数据结构 |
-| swagger:allOf  | 嵌入其他 Go 结构体 |
-| swagger:strfmt  | 格式化的字符串  |
-| swagger:ignore  | 需要忽略的结构体 |
+| 注释语法               | 描述            |
+|--------------------|---------------|
+| swagger:meta       | 定义全局基本信息      |
+| swagger:route      | 定义路由信息        |
+| swagger:parameters | API 请求参数      |
+| swagger:response   | API 响应参数      |
+| swagger:model      | 可以复用的 Go 数据结构 |
+| swagger:allOf      | 嵌入其他 Go 结构体   |
+| swagger:strfmt     | 格式化的字符串       |
+| swagger:ignore     | 需要忽略的结构体      |
 
-
-`swagger generate` 命令会找到 `main` 函数，然后遍历所有源码文件，解析源码中与 Swagger 相关的注释，然后自动生成 `swagger.json/swagger.yaml` 文件。
+`swagger generate` 命令会找到 `main` 函数，然后遍历所有源码文件，解析源码中与 Swagger
+相关的注释，然后自动生成 `swagger.json/swagger.yaml` 文件。
 
 ```go
 package main
@@ -93,7 +94,7 @@ func main() {
 	log.Fatal(r.Run(":8081"))
 }
 
-// Create create a user.
+// Create a user.
 func Create(c *gin.Context) {
 	var user api.User
 	if err := c.ShouldBindJSON(&user); err != nil {
@@ -133,19 +134,19 @@ package api
 
 // User represents body of User request and response.
 type User struct {
-    // User's name.
-    // Required: true
-    Name string `json:"name"`
+	// User's name.
+	// Required: true
+	Name string `json:"name"`
 
-    // User's nickname.
-    // Required: true
-    Nickname string `json:"nickname"`
+	// User's nickname.
+	// Required: true
+	Nickname string `json:"nickname"`
 
-    // User's address.
-    Address string `json:"address"`
+	// User's address.
+	Address string `json:"address"`
 
-    // User's email.
-    Email string `json:"email"`
+	// User's email.
+	Email string `json:"email"`
 }
 ```
 
@@ -188,9 +189,8 @@ package docs
 package docs
 
 import (
-	v1 "github.com/shipengqi/idm/api/apiserver/v1"
-	metav1 "github.com/shipengqi/idm/api/meta/v1"
-	"github.com/shipengqi/idm/internal/apiserver/contorller/v1/user"
+  v1 "github.com/shipengqi/idm/api/apiserver/v1"
+  metav1 "github.com/shipengqi/idm/api/meta/v1"
 )
 
 // swagger:route GET /users/{name} Users getUserRequest
@@ -216,57 +216,58 @@ import (
 // List users request.
 // swagger:parameters listUserRequest
 type listUserRequestParamsWrapper struct {
-	// in:query
-	metav1.ListOptions
+  // in:query
+  metav1.ListOptions
 }
 
 // List users response.
 // swagger:response listUserResponse
 type listUserResponseWrapper struct {
-	// in:body
-	Body v1.UserList
+  // in:body
+  Body v1.UserList
 }
 
 // User response.
 // swagger:response getUserResponse
 type getUserResponseWrapper struct {
-	// in:body
-	Body v1.User
+  // in:body
+  Body v1.User
 }
 
 // swagger:parameters createUserRequest updateUserRequest
 type userRequestParamsWrapper struct {
-	// User information.
-	// in:body
-	Body v1.User
+  // User information.
+  // in:body
+  Body v1.User
 }
 
 // swagger:parameters deleteUserRequest getUserRequest updateUserRequest
 type userNameParamsWrapper struct {
-	// Username.
-	// in:path
-	Name string `json:"name"`
+  // Username.
+  // in:path
+  Name string `json:"name"`
 }
 
 // ErrResponse defines the return messages when an error occurred.
 // swagger:response errResponse
 type errResponseWrapper struct {
-	// in:body
-	Body response.Response
+  // in:body
+  Body response.Response
 }
 
 // Return nil json object.
 // swagger:response okResponse
 type okResponseWrapper struct{}
+
 ```
 
-- `swagger:route`：描述一个 API，格式为 `swagger:route [method] [url path pattern] [?tag1 tag2 tag3] [operation id]`，tag 可以是多个，相同 tag 的 API 在 Swagger 文档中会被分为一组。operation id 会和 
+- `swagger:route`：描述一个 API，格式为 `swagger:route [method] [url path pattern] [?tag1 tag2 tag3] [operation id]`，tag 可以是多个，相同 tag 的 API 在 Swagger 文档中会被分为一组。operation id 会和
   `swagger:parameters` 的定义进行匹配，就是该 API 的请求参数。
-  `swagger:route` 下面的一行是该 API 的描述，需要以 `.` 为结尾。`responses:` 定义了 API 的返回参数，例如当 HTTP 状态码是 200 时，返回 `createUserResponse`，`createUserResponse` 会和 `swagger:response` 
-  的定义进行匹配，匹配成功的 `swagger:response` 就是该 API 返回 200 状态码时的返回。
+  `swagger:route` 下面的一行是该 API 的描述，需要以 `.` 为结尾。`responses:` 定义了 API 的返回参数，例如当 HTTP 状态码是 200 时，返回 `createUserResponse`，`createUserResponse` 会和 `swagger:response` 的定义进行匹配，匹配成功的 `swagger:response` 就是该 API 返回 200 状态码时的返回。
 - `swagger:response`：定义了 API 的返回，格式为 `swagger:response [?response name]`.例如 `getUserResponseWrapper` 中有一个 `Body` 字段，其注释为 `// in:body`，说明该参数是在 HTTP Body 中返回。
   `swagger:response` 上的注释是 response 的描述。`api.User` 会被 go-swagger 解析为 Example Value 和 Model，不需要重复编写。
-- `swagger:parameters`：定义了 API 的请求参数，格式为 `swagger:parameters [operationid1 operationid2]`。例如 `userRequestParamsWrapper`。`userRequestParamsWrapper` 上的注释是请求参数的描述。
+- `swagger:parameters`：定义了 API 的请求参数，格式为 `swagger:parameters [operationid1 operationid2]`
+  。例如 `userRequestParamsWrapper`。`userRequestParamsWrapper` 上的注释是请求参数的描述。
 
 进入 `swagger` 目录，执行如下命令，生成 Swagger API 文档：